feat(cli): vx watch — initial run then re-run on file changes

[Exelord]

Summary

New subcommand mirroring turbo watch / nx watch. Closes the last open Turbo-alignment gap.

• Initial run uses the same orchestrator path as vx run.
• Per-project recursive fs.watch (Bun supports recursive on every platform).
• Workspace root non-recursive watch for lockfile / pnpm-workspace.yaml changes — so a bun install bump triggers a cycle even when no project dir saw the change.
• Path filter ignores node_modules / .git / .vx segments and .tsbuildinfo / ~ (editor swap) suffixes.
• Debounced ~150 ms after the last event.
• Reentrancy guard: while a cycle is running, further events set pending = true; the loop drains them after the current cycle so two bursty events collapse into one re-run.
• Ctrl+C closes watchers, exits 0.
• Failed cycles don't break the loop — they print the FAILED block and wait for the next change.

Cache is the workhorse — most re-runs are cache hits (~tens of ms). We deliberately don't filter events through cache.inputs.files globs: the cache key is the source of truth, and pre-filtering would redo the glob + boundary work on every event.

Rejected flags

Parser exits 1 before the initial run for flags that don't make sense in a loop:

• --dry / --graph — skip execution.
• --summarize / --profile — would overwrite the target file per cycle.

Otherwise the flag surface is identical to vx run. Extracted resolveRunOptions(parsed, cwd, tasks) from cli/run.ts so both subcommands share the scope resolution.

Persistent tasks

Re-spawn each cycle. For dev servers that should stay up, use the tool's own watch (vite, tsc -b -w, bun --watch); vx watch is for vx watch test / vx watch lint / vx watch build.

Files

• New: src/cli/watch.ts, tests/cli.test.ts (7 new tests), docs/modules/cli-watch.md
• Modified: src/cli.ts (dispatcher), src/cli/run.ts (extracted resolveRunOptions), src/cli/help.ts, docs/cli.md, docs/comparison.md, docs/modules/README.md, docs/modules/cli-run.md, CLAUDE.md

Test plan

• 6 parser-side validations (no task, --dry / --graph / --summarize / --profile rejection, parser error prefix).
• 1 end-to-end re-run-on-change: fixture workspace with a task that cats a file; the test writes a new value mid-watch and asserts the re-run surfaces it; SIGINT exits 0.
• bun src/bin.ts run lint — clean
• bun src/bin.ts run format-check — clean (oxfmt ran)
• bun test — 338 pass, 0 fail (was 331)
• Smoke test against tmpdir fixture: vx watch with no task / --dry / --help text all behave correctly.
• CI green.

---

Generated by Claude Code