codex exec: a switch to disable the file watcher for one-shot headless runs

What

A config/env/flag switch (e.g. CODEX_DISABLE_FILE_WATCHER=1, --no-watch, or [file_watcher] enabled = false) that keeps codex exec from starting its notify-based file watcher (the codex-file-watcher crate split out in #21290).

Why

We run a pool of 12 headless codex exec workers (plus ~14 headless claude -p workers) on one macOS box against ~9.5 GB git clones. Each headless run registers FSEvents stream clients for its lifetime; none of the things the watcher serves (skills hot-reload, config hot-reload, git-init detection) matter to a one-shot non-interactive run that exits when its task ends. Across a churning pool the per-run clients accumulate in fseventsd — we measured 82 client pids in 40 min and an fseventsd RSS blow-up severe enough to contribute to a kernel watchdog panic loop on 2026-08-19.

For the Claude CLI side we found an escape (CHOKIDAR_USEPOLLING=1 makes its chokidar watchers stat-poll; measured 6–7 → 0 FSEvents clients per run, 3/3). codex exposes nothing equivalent: as of codex-cli 0.153.4, codex --help, codex exec --help and codex features list have no watcher flag, there is no file_watcher config key, and FileWatcher::new() is constructed unconditionally (no toggle anywhere in the crate); the Rust notify watcher ignores chokidar's env.

Related

• #21290 (watcher moved to its own crate — a natural place for an on/off knob)
• #39473, #23574 (watch-limit exhaustion in desktop/extension — same cost, different surface)
• #15698 (seatbelt vs FSEvents)

Environment

codex-cli 0.153.4, macOS 26.6.2 (Mac Studio), codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check.

Start by inspecting the codex-file-watcher crate and the FileWatcher::new() construction used by codex exec. Trace how exec configuration, environment variables, and flags are parsed, then determine one supported switch that prevents watcher startup for one-shot runs. Done means the disabled mode avoids creating the watcher while normal interactive behavior remains unchanged, with coverage for both paths.