Watch mode: keep watcher setup and the readiness signature off the first interaction #1063

What do you want to change?

With watch = true, defer creating the filesystem observer until the first frame has reached idle, and make the readiness signature check (and the bootstrap's initial signature) run through the async git runners instead of spawnSync. On Linux, keep Git-pruned chokidar but move its directory walk off the main thread's first interaction.

Why?

Right after the first frame, useWatchedInput's mount effect builds the watch plan and starts the observer. On Linux that is chokidar walking every non-ignored directory to install per-directory watchers. It is synchronous main-thread work and lands exactly when the user starts pressing keys. Measured in a PTY on this repo (1.3k files, 212 dirs), key sent at first frame:

The walk scales with repo size. The #531 benchmark report (docs/watch-benchmark-final.md) recorded 858ms observer-ready wall time on its "Linux big repo" case and noted: "Concentrated setup can still affect the first interaction even when its CPU-equivalent cost is recovered within seconds." That benchmark measured time-to-first-frame, so work that runs after the first frame did not show up in its headline numbers.

History, for context:

• Chokidar on Linux instead of native recursive fs.watch was deliberate and measured in feat(watch): replace 250 ms watch polling with evented filesystem observation #531: Bun's native recursion registers one inotify watch per directory including ignored trees (~24k per session, exhausting the default 61,504 limit after ~3 sessions). Chokidar accepts an ignored predicate so Git-derived pruning works. That constraint still holds; this issue does not propose switching backends.
• Running the setup on the main thread at mount, and its timing relative to the first frame, was never discussed in feat(watch): replace 250 ms watch polling with evented filesystem observation #531 or since.
• The "immediate signature check after watcher readiness" is intentional (closes the scan race, pinned by controller.test.ts). Its synchronous spawnSync execution was inherited from the old polling loop. perf(watch): stop watch-mode signature checks from stalling the review UI #677 later called the sync signature a bug ("it stops it freezing the terminal") and widened watchSignature to string | Promise<string>, but that PR was never merged and is now stale. refactor(ui): keep history reviews in one renderer #992 since added runGitTextAsync and friends to packages/hunk-git, but watchSignature still uses the sync runner.
• Issue Watch mode is very slow #543 covers a related but different symptom: steady-state stalls during editing from the same sync git calls.

How? (optional)

1. In useWatchedInput, start the controller after the renderer's first idle (or a short setTimeout after mount) rather than in the mount effect. Keep initialWatchSignature captured before content load in loaders.ts so the startup race stays closed; the readiness check still runs once the observer reports ready.
2. Chunk chokidar's directory walk so it yields to the event loop between directories (chokidar's own _addToNodeFs is recursive and synchronous per subtree; a wrapper can add directories incrementally, or the walk can move to a worker that reports paths back for fs.watch registration on the main thread). Measure with bun run bench:watch-style timing before choosing.
3. Land the async watchSignature from perf(watch): stop watch-mode signature checks from stalling the review UI #677 on top of refactor(ui): keep history reviews in one renderer #992's async runners: string | Promise<string> with an AbortSignal, using runGitTextAsync, listGitUntrackedFilesAsync, and preventOptionalLocks unchanged. This also addresses the steady-state freeze in Watch mode is very slow #543.
4. Keep existing invariants: 2s readiness deadline with polling fallback on ENOSPC/EMFILE, no per-directory inotify watches on ignored trees, --no-optional-locks on every watch-time git call (hunk diff —watch creates git locks #398), the Bun ≥ 1.3.14 guard (fix(watch): refuse deadlocking Bun runtimes #902).
5. Add a PTY test in test/pty/watch.test.ts that sends a key at first paint with watch enabled and asserts it is answered within ~100ms on a fixture with a few hundred directories.