@vzn/vx 0.0.18 → 0.0.22

package/src/cli/watch.ts

@@ -14,18 +14,42 @@
 
 import fs from 'node:fs'
 import path from 'node:path'
+import {
+  executablePath,
+  isLiteralPattern,
+  normalizeGlob,
+  staticPrefix,
+  taskGlob,
+  xxh3,
+} from '../util/index.js'
+import { asTrees } from '../cache/index.js'
 import { parseRunArgs, resolveRunOptions } from './run.js'
-import { run as runOrchestrator, type RunOptions } from '../orchestrator/index.js'
 import {
+  fingerprintClaims,
+  forwardedSignal,
+  run as runOrchestrator,
+  type HeldPersistent,
+  type RunOptions,
+} from '../orchestrator/index.js'
+import {
+  buildPackageGraph,
   findWorkspaceRoot,
+  type LoadReads,
   listProjects,
   loadProjectConfig,
   loadWorkspace,
-  loadWorkspaceConfig,
-  resolveCacheDir,
+  LOCKFILE_NAME,
+  memberBaseDirs,
+  PROJECT_CONFIG_FILENAMES,
+  WORKSPACE_CONFIG_FILENAMES,
+  configImports,
   WORKSPACE_FINGERPRINT_FILES,
+  type ProjectEntry,
   type ProjectMeta,
 } from '../workspace/index.js'
+import type { ProjectConfig } from '../config.js'
+import { type CliLoadOptions, loadCliProjects, loadCliWorkspace } from './workspace-config.js'
+import { taskEdges, taskEdgesFrom } from './select.js'
 
 /** Wait this long after the last filesystem event before re-running. */
 const DEBOUNCE_MS = 150
@@ -65,31 +89,84 @@ export function isIgnoredWatchPath(rel: string): boolean {
 export function makeWatchIgnore(
   cacheDir: string,
   outputs: ReadonlyMap<string, readonly string[]> = new Map(),
+  inputs: ReadonlyMap<string, readonly string[]> = new Map(),
 ): (base: string, filename: string) => boolean {
   const cacheAbs = path.resolve(cacheDir)
   // A task's own outputs are not edits: without this every cycle that
   // writes `dist/` (or `out.txt`) re-runs once more, reporting
   // "up-to-date" for the trouble. Matched under the directory the globs
   // are relative to, whichever watcher delivered the event.
+  // The directory that HOLDS an output tree is the task's too: `dist/**`
+  // does not match `dist`, and since the clean before a miss prunes an
+  // emptied `dist` (2026-09-10) the task re-creates it, which the watcher
+  // reports as a change to `dist` itself — a second cycle per edit,
+  // reporting "up-to-date". The literal prefix of each glob (`dist` for
+  // `dist/**`, `build/out` for `build/out/*.js`; nothing for `*.js`) and
+  // every ancestor of it under the dir are output containers.
+  // A literal entry means the file or its whole tree — the resolver's own
+  // rule (`asTrees`), so the tree's files never count as edits.
   const declared = [...outputs].map(
-    ([dir, globs]) => [path.resolve(dir), globs.map((g) => new Bun.Glob(g))] as const,
+    ([dir, globs]) =>
+      [
+        path.resolve(dir),
+        asTrees(globs).map((g) => taskGlob(g)),
+        globs.map(outputContainer).filter((c) => c !== ''),
+      ] as const,
+  )
+  // A path some task takes as an INPUT is never an output to ignore, even
+  // when another task declares it one: an in-place formatter declaring
+  // `src/**` hid every `src` edit from a `build` watched beside it, and no
+  // cycle ran (item 946). Negations are not consulted — they only narrow,
+  // and a path they would exclude costs one cache-hit cycle.
+  const read = [...inputs].map(
+    ([dir, globs]) =>
+      [
+        path.resolve(dir),
+        asTrees(globs.filter((g) => !g.startsWith('!'))).map((g) => taskGlob(g)),
+      ] as const,
   )
+  const isInput = (abs: string): boolean =>
+    read.some(([dir, globs]) => {
+      if (!abs.startsWith(dir + path.sep)) return false
+      const rel = abs
+        .slice(dir.length + 1)
+        .split(path.sep)
+        .join('/')
+      return globs.some((g) => g.match(rel))
+    })
   return (base, filename) => {
     if (isIgnoredWatchPath(filename)) return true
     const abs = path.resolve(base, filename)
     if (abs === cacheAbs || abs.startsWith(cacheAbs + path.sep)) return true
-    for (const [dir, globs] of declared) {
+    if (isInput(abs)) return false
+    for (const [dir, globs, containers] of declared) {
       if (!abs.startsWith(dir + path.sep)) continue
       const rel = abs
         .slice(dir.length + 1)
         .split(path.sep)
         .join('/')
       if (globs.some((g) => g.match(rel))) return true
+      if (containers.some((c) => c === rel || c.startsWith(`${rel}/`))) return true
     }
     return false
   }
 }
 
+/**
+ * The literal directory a glob's matches live under (`''` when the glob
+ * starts with a pattern, or negates). A literal entry is a file or its
+ * whole tree (schema: literal → tree), so the entry itself is the
+ * container; a pattern's is `staticPrefix` — the same rule the sandbox
+ * baseline and the deferral gate read.
+ */
+function outputContainer(raw: string): string {
+  const glob = normalizeGlob(raw)
+  if (glob.startsWith('!')) return ''
+  if (isLiteralPattern(glob)) return glob.replace(/\/+$/, '')
+  const prefix = staticPrefix(glob)
+  return prefix === '.' || prefix === '/' ? '' : prefix
+}
+
 /**
  * The file `armWatcher` writes under a watched directory to prove the
  * watcher delivers. Intercepted by name before any other handling, so it
@@ -97,8 +174,51 @@ export function makeWatchIgnore(
  */
 export const WATCH_PROBE = '.vx-watch-probe'
 
+/**
+ * The subset of `paths` git ignores, asked once per judgement (one
+ * `git check-ignore` per debounce window that has candidates, never per
+ * event). A git-ignored path is invisible to every cache key — inputs
+ * are tracked + untracked-not-ignored — so a cycle it starts can change
+ * nothing, and a task that writes one on every run (a pid file, a
+ * timestamped log, `.next/trace`) made the loop re-run itself forever
+ * (2026-09-16: 29 cycles in 8 s from one edit). A TRACKED file that
+ * matches a pattern is not reported, by git's own rule, so it stays an
+ * edit. Outside a repository (exit 128) nothing is ignored, as before.
+ */
+export function gitIgnored(workspaceRoot: string, paths: readonly string[]): Set<string> {
+  const ignored = new Set<string>()
+  if (paths.length === 0) return ignored
+  let proc: ReturnType<typeof Bun.spawnSync>
+  try {
+    proc = Bun.spawnSync({
+      cmd: [executablePath('git'), 'check-ignore', '-z', '--stdin'],
+      cwd: workspaceRoot,
+      stdin: Buffer.from(paths.map((p) => `${p}\0`).join('')),
+      stdout: 'pipe',
+      stderr: 'ignore',
+    })
+  } catch {
+    // No git on PATH: nothing is ignored, and the loop keeps judging —
+    // the initial run already said what vx requires.
+    return ignored
+  }
+  // 0: some ignored; 1: none. Anything else is git refusing (not a
+  // repository, a path inside a nested one): no path is ignored.
+  if (proc.exitCode !== 0) return ignored
+  for (const p of new TextDecoder().decode(proc.stdout).split('\0'))
+    if (p.length > 0) ignored.add(p)
+  return ignored
+}
+
 /** How long a watcher gets to report its own probe before the loop goes on without proof. */
 const WATCH_PROBE_TIMEOUT_MS = 2_000
+/** The file `fsClockNow` writes and removes, under the cache dir the watchers ignore. */
+const WATCH_CLOCK_STAMP = '.vx-watch-clock'
+
+/** Anything the loop needs to shut down at exit. */
+export interface WatchHandle {
+  close(): void
+}
 
 export interface ArmedWatcher {
   watcher: fs.FSWatcher
@@ -106,6 +226,101 @@ export interface ArmedWatcher {
   ready: Promise<boolean>
 }
 
+/** How often the fallback re-walks a watched tree. */
+const POLL_INTERVAL_MS = 250
+
+/**
+ * Directory names the fallback never descends into WHEN no better filter is
+ * supplied. The justification is that `makeWatchIgnore` already drops their
+ * EVENTS, so the walk buys nothing — a poller pays for it either way, and
+ * `node_modules` is the difference between a cheap fallback and one that
+ * re-stats 40 000 files four times a second.
+ *
+ * That justification is exactly `IGNORED_SEGMENTS`, so this IS that set.
+ * It used to carry a fourth name, `dist`, which the justification does NOT
+ * cover: `dist` is dropped only when a project DECLARES it as an output, and
+ * a project that does not declare it had its `dist/` sources silently
+ * invisible to `vx watch` on every host the poller exists for — a macOS
+ * sandbox, a network mount, a container bind — while the native watcher
+ * delivered them. Two watchers disagreeing about what an edit is (item 482).
+ * The real per-project answer is the caller's `skipDir`, below.
+ */
+const POLL_SKIP = new Set(IGNORED_SEGMENTS)
+
+/**
+ * A watcher built from `stat`, for when the OS one cannot deliver.
+ *
+ * `fs.watch` on macOS is FSEvents, which needs `mach-lookup` on
+ * `com.apple.FSEvents`; inside a sandbox that does not grant it the call
+ * SUCCEEDS and then never fires (measured 2026-09-05: 0 events recursive,
+ * 0 non-recursive, against 3 and 2 for the same writes outside — while
+ * `fs.watchFile` polling delivered in both). A network filesystem or a
+ * container bind mount fails the same way. Polling is slower and coarser,
+ * and it is the difference between `vx watch` working there and silently
+ * doing nothing.
+ */
+export function pollWatcher(
+  dir: string,
+  recursive: boolean,
+  onEvent: (filename: string) => void,
+  intervalMs = POLL_INTERVAL_MS,
+  /**
+   * Directories not worth descending into, by their path relative to `dir`.
+   * The watch loop passes its own event filter, so the poller skips exactly
+   * what the filter would drop anyway — every declared output container, not
+   * a hard-coded name. The default covers the unconditional segments alone.
+   */
+  skipDir: (rel: string) => boolean = (rel) => POLL_SKIP.has(path.basename(rel)),
+): WatchHandle {
+  let previous = new Map<string, number>()
+  let first = true
+  const scan = (): void => {
+    const current = new Map<string, number>()
+    const walk = (abs: string, rel: string): void => {
+      let entries: fs.Dirent[]
+      try {
+        entries = fs.readdirSync(abs, { withFileTypes: true })
+      } catch {
+        return // vanished or unreadable: its files simply stop appearing
+      }
+      for (const e of entries) {
+        if (e.name === WATCH_PROBE) continue
+        const childRel = rel === '' ? e.name : `${rel}/${e.name}`
+        if (e.isDirectory()) {
+          if (recursive && !skipDir(childRel)) walk(path.join(abs, e.name), childRel)
+          continue
+        }
+        if (!e.isFile()) continue
+        try {
+          current.set(childRel, fs.statSync(path.join(abs, e.name)).mtimeMs)
+        } catch {
+          // raced with a delete; the next scan settles it
+        }
+      }
+    }
+    walk(dir, '')
+    if (!first) {
+      for (const [rel, mtime] of current) {
+        if (previous.get(rel) !== mtime) onEvent(rel)
+      }
+      for (const rel of previous.keys()) {
+        if (!current.has(rel)) onEvent(rel)
+      }
+    }
+    previous = current
+    first = false
+  }
+  scan()
+  // Deliberately NOT unref'd: once the native watcher is closed this timer
+  // is the only thing keeping `vx watch` alive.
+  const timer = setInterval(scan, intervalMs)
+  return {
+    close(): void {
+      clearInterval(timer)
+    },
+  }
+}
+
 /**
  * `fs.watch` plus proof of delivery. On macOS a recursive watcher is an
  * FSEvents stream that another thread schedules AFTER the call returns, and
@@ -132,10 +347,20 @@ export function armWatcher(
   })
   const watcher = fs.watch(dir, { recursive, persistent: true }, (_event, filename) => {
     if (filename == null || typeof filename !== 'string') return
+    // An event naming the watched directory itself (macOS reports the
+    // directory a write landed in as its own item) carries nothing a key
+    // can see; the write's own event names the file.
+    if (filename === '' || filename === '.') return
     if (filename === WATCH_PROBE) {
       markReady(true)
       return
     }
+    // Another arm's probe, seen by this recursive watcher under a nested
+    // directory (a nested project's, a member base inside a project): no
+    // key sees it, and passing it on ran a cycle, and restarted a dev
+    // server, with no edit made (item 1016). Only the watcher's own probe
+    // proves this stream live.
+    if (path.basename(filename) === WATCH_PROBE) return
     onEvent(filename)
   })
   const probe = path.join(dir, WATCH_PROBE)
@@ -213,23 +438,54 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
     process.stderr.write(`vx watch: ${resolved.nothingSelected}\n`)
     return 0
   }
-  // The watch loop owns SIGINT/SIGTERM for its whole lifetime (the
-  // process.once handlers below close watchers and resolve 0). A
-  // cycle's run() must not install its exit-the-process handlers —
-  // Ctrl-C mid-cycle would kill the loop with 130 instead of the
-  // loop's own clean shutdown.
-  const opts: RunOptions = { ...resolved, handleSignals: false }
+  // The watch loop owns SIGINT/SIGTERM for its whole lifetime. A cycle's
+  // run() must not install its exit-the-process handlers — Ctrl-C
+  // mid-cycle would kill the loop with 130 instead of the loop's own
+  // clean shutdown — so it gets `signal` instead: on SIGINT/SIGTERM the
+  // controller aborts with the signal's name as the reason, the in-flight
+  // cycle forwards it to its children (a SIGINT as SIGINT, the rest as
+  // SIGTERM; grace, SIGKILL) and returns, and the loop resolves 0.
+  // Installed BEFORE the initial run: until 2026-09-10 the handlers went
+  // in with the loop, so a SIGTERM during the initial run took Bun's
+  // default (exit 143) and left the cycle's children running under init.
+  const stop = new AbortController()
+  const opts: RunOptions = {
+    ...resolved,
+    handleSignals: false,
+    signal: stop.signal,
+    holdPersistent: true,
+  }
+  // Every cycle's `invocations` row names the verb, as `vx run`'s does;
+  // run()'s process.argv fallback put the bin's absolute path there, so
+  // `vx last --list` showed `$ /…/bin.ts watch build` beside `$ vx run build`.
+  opts.command = ['vx', 'watch', ...args].join(' ')
+  // A staged load from the selection pass is one run's worth of configs;
+  // every cycle after an edit must evaluate live.
+  delete opts.staged
+  process.once('SIGINT', () => {
+    process.stdout.write('\nvx watch: stopped\n')
+    stop.abort('SIGINT')
+  })
+  process.once('SIGTERM', () => stop.abort('SIGTERM'))
+  // A task runs in its own session (exec/kill-tree.ts): the terminal
+  // closing reaches the loop alone, and the loop passes it on.
+  process.once('SIGHUP', () => stop.abort('SIGHUP'))
 
   // Enumerate projects-in-scope so we know what dirs to watch.
   // `opts.projects` is the resolved scope; undefined means "every
-  // project". We watch only those (plus the workspace root, for
-  // lockfile changes).
-  const workspaceRoot = await findWorkspaceRoot(cwd)
-  const allProjects = await listProjects(await loadWorkspace(workspaceRoot))
-  const scope =
-    opts.projects === undefined
-      ? allProjects
-      : allProjects.filter((p) => opts.projects!.includes(p.name))
+  // project". The watched set is what a cycle can RUN: the scope plus
+  // its transitive dependencies (a cycle runs `lib#build` for
+  // `app#build`'s `^build`, so a `lib` edit is an edit) — the same
+  // closure `--filter 'app...'` walks, computed below once the initial
+  // run has staged the configs. Plus the workspace root, for lockfile
+  // changes.
+  const reads: LoadReads = new Map()
+  const workspaceRoot = await findWorkspaceRoot(cwd, reads)
+  const workspace = await loadWorkspace(workspaceRoot, reads)
+  const allProjects = await listProjects(workspace)
+  const inScope = (all: readonly ProjectMeta[]): ProjectMeta[] =>
+    opts.projects === undefined ? [...all] : all.filter((p) => opts.projects!.includes(p.name))
+  const scope = inScope(allProjects)
 
   if (scope.length === 0) {
     process.stderr.write(`vx watch: no projects in scope\n`)
@@ -248,107 +504,540 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   // closing it properly needs the workspaceWide decision made without loading
   // configs.
   process.stdout.write('vx watch: initial run...\n\n')
-  await runOrchestrator(opts)
+  const initial = await runOrchestrator(opts)
+  if (stop.signal.aborted) {
+    await initial.persistent?.stop(forwardedSignal(stop.signal.reason))
+    return 0
+  }
 
-  const swept = await sweepConfigs(allProjects, workspaceRoot)
+  const load: CliLoadOptions = {
+    ...(opts.cacheDir !== undefined ? { cacheDir: opts.cacheDir } : {}),
+    ...(opts.frozen === true ? { frozen: true } : {}),
+  }
+  const swept = await sweepConfigs(allProjects, workspaceRoot, load)
+  const watched = await watchedProjects(workspaceRoot, allProjects, scope, load, swept.staged)
+  const ws = await loadCliWorkspace(workspaceRoot)
   return await runWatchLoop({
     opts,
+    held: initial.persistent,
+    stop: stop.signal,
     workspaceRoot,
-    projects: scope,
+    projects: watched,
     workspaceWide: swept.workspaceWide,
+    projectDirs: watched.map((p) => p.dir),
+    workspaceInputs: swept.workspaceInputs,
     outputs: swept.outputs,
+    inputs: swept.inputs,
+    uncached: swept.uncached,
+    configImports: swept.configImports,
+    workspaceConfigImports: swept.workspaceConfigImports,
+    memberBases: memberBaseDirs(workspace),
+    packageDirs: new Set(allProjects.map((p) => p.dir)),
+    // The workspace as the cycle that just ran saw it: a package added or
+    // removed since the loop armed joins or leaves the watched set. The
+    // scope is the one resolved at start; a new package joins it only as a
+    // dependency of it.
+    rediscover: async () => {
+      const all = await listProjects(await loadWorkspace(workspaceRoot))
+      const sweep = await sweepConfigs(all, workspaceRoot, load)
+      const now = await watchedProjects(workspaceRoot, all, inScope(all), load, sweep.staged)
+      return {
+        projects: now,
+        workspaceWide: sweep.workspaceWide,
+        workspaceInputs: sweep.workspaceInputs,
+        outputs: sweep.outputs,
+        inputs: sweep.inputs,
+        uncached: sweep.uncached,
+        configImports: sweep.configImports,
+        workspaceConfigImports: sweep.workspaceConfigImports,
+        packageDirs: new Set(all.map((p) => p.dir)),
+      }
+    },
+    // Under --frozen every cycle's configs are the lock's, so a re-lock is
+    // the one edit that changes what a cycle runs; unheard, the loop ran
+    // the old lock until a restart (item 971).
+    claimedRootFiles: new Set([
+      ...fingerprintClaims(ws.plugins).keys(),
+      ...(opts.frozen === true ? [LOCKFILE_NAME] : []),
+    ]),
     // The RESOLVED cache dir, not the `.vx` literal — see `makeWatchIgnore`.
-    cacheDir:
-      opts.cacheDir ?? resolveCacheDir(workspaceRoot, await loadWorkspaceConfig(workspaceRoot)),
+    cacheDir: opts.cacheDir ?? ws.cacheDir,
   })
 }
 
+/**
+ * The projects a cycle can run, so both watcher arms cover the same dirs:
+ * the scope plus its transitive dependencies through the package graph
+ * and the cross-project `dependsOn` edges the task graph adds
+ * (`e2e` → `app` from `dependsOn: ['app#build']`). Before this, the
+ * per-project arm watched the filter's answer only, so
+ * `vx watch build --filter app` never re-ran on a `lib` edit that
+ * `vx run build --filter app` would have rebuilt. A whole-workspace
+ * scope is every project already and walks nothing. A config the loader
+ * rejects contributes no edges here; the run that just happened said so.
+ */
+export async function watchedProjects(
+  workspaceRoot: string,
+  allProjects: readonly ProjectMeta[],
+  scope: readonly ProjectMeta[],
+  load: CliLoadOptions = {},
+  staged: ReadonlyMap<string, ProjectEntry> | null = null,
+): Promise<ProjectMeta[]> {
+  if (scope.length === allProjects.length) return [...allProjects]
+  let edges: Map<string, string[]> | undefined
+  try {
+    edges =
+      staged !== null
+        ? taskEdgesFrom(staged)
+        : (await taskEdges(workspaceRoot, allProjects, load)).edges
+  } catch {
+    edges = undefined
+  }
+  const graph = buildPackageGraph([...allProjects], edges)
+  const names = new Set(scope.map((p) => p.name))
+  for (const p of scope) for (const d of graph.transitiveDeps(p.name)) names.add(d)
+  return allProjects.filter((p) => names.has(p.name))
+}
+
 /**
  * One sweep over every config for the two things the loop needs: whether
  * any task declares `inputs.workspaceFiles` — globs with no project
- * boundary, so the per-project watchers can't see all triggering paths
- * and the loop switches to one recursive root watcher — and each
- * project's declared outputs, so their writes are not taken for edits.
- * Checked across ALL projects (not just the scope) because dependsOn can
- * pull tasks from anywhere; a broken out-of-scope config is skipped,
- * matching scoped-run semantics (it surfaces when that project enters
- * scope).
+ * prefix, so the whole tree has to be watched — and every project's
+ * declared outputs, so their writes are not taken for edits. The run
+ * path's load (`loadProjects`): the plugin `project` stage applies, so an
+ * output a plugin gave a config-less package is ignored like a declared
+ * one, and a pure config is served from its cached evaluation rather than
+ * re-evaluated in a worker. A config that fails to load is out of this
+ * concern's scope — the run that just happened already said so, or will —
+ * and the sweep falls back to the files that do load, one by one.
  */
-async function sweepConfigs(
+export async function sweepConfigs(
   projects: readonly ProjectMeta[],
   workspaceRoot: string,
-): Promise<{ workspaceWide: boolean; outputs: Map<string, string[]> }> {
+  load: CliLoadOptions = {},
+): Promise<{
+  workspaceWide: boolean
+  workspaceInputs: string[]
+  outputs: Map<string, string[]>
+  /** Declared input globs per directory they are relative to, the counterweight to `outputs`. */
+  inputs: Map<string, string[]>
+  /** Projects with a task that has a command and no cache: it reads what it likes, git-ignored files included. */
+  uncached: Set<string>
+  /** Files the project configs import by relative path (item 949). */
+  configImports: string[]
+  /** Files the workspace config imports by relative path: loaded once per process (item 949). */
+  workspaceConfigImports: string[]
+  /** The staged load the sweep read, when the run path's load succeeded; `watchedProjects` reads the same one. */
+  staged: Map<string, ProjectEntry> | null
+}> {
   const outputs = new Map<string, string[]>()
-  const add = (dir: string, globs: readonly string[] | undefined): void => {
+  const inputs = new Map<string, string[]>()
+  const addTo = (
+    into: Map<string, string[]>,
+    dir: string,
+    globs: readonly string[] | undefined,
+  ): void => {
     if (globs === undefined || globs.length === 0) return
-    outputs.set(dir, [...(outputs.get(dir) ?? []), ...globs])
-  }
-  // Concurrent, not sequential: the run that just happened already
-  // loaded the in-scope configs, so these are REPEAT loads that
-  // re-evaluate in a worker. Issuing them together lets one worker
-  // serve the whole sweep instead of one per project.
-  const uses = await Promise.all(
-    projects.map(async (p): Promise<boolean> => {
-      if (p.configPath === null) return false
+    into.set(dir, [...(into.get(dir) ?? []), ...globs])
+  }
+  const add = (dir: string, globs: readonly string[] | undefined): void =>
+    addTo(outputs, dir, globs)
+  const workspaceInputs = new Set<string>()
+  const uncached = new Set<string>()
+  const fold = (dir: string, config: ProjectConfig): void => {
+    for (const task of Object.values(config.tasks ?? {})) {
+      if (task.cache === undefined && task.exec !== undefined && task.exec.persistent === undefined)
+        uncached.add(dir)
+      for (const g of task.cache?.inputs?.workspaceFiles ?? []) workspaceInputs.add(g)
+      addTo(inputs, dir, task.cache?.inputs?.files)
+      addTo(inputs, workspaceRoot, task.cache?.inputs?.workspaceFiles)
+      add(dir, task.cache?.outputs?.files)
+      add(workspaceRoot, task.cache?.outputs?.workspaceFiles)
+    }
+  }
+  const result = (
+    staged: Map<string, ProjectEntry> | null,
+  ): {
+    workspaceWide: boolean
+    workspaceInputs: string[]
+    outputs: Map<string, string[]>
+    inputs: Map<string, string[]>
+    uncached: Set<string>
+    configImports: string[]
+    workspaceConfigImports: string[]
+    staged: Map<string, ProjectEntry> | null
+  } => ({
+    workspaceWide: workspaceInputs.size > 0,
+    workspaceInputs: [...workspaceInputs],
+    outputs,
+    inputs,
+    uncached,
+    configImports: [...projectImports],
+    workspaceConfigImports: [...wsImports],
+    staged,
+  })
+  const projectImports = new Set<string>()
+  const wsImports = new Set<string>()
+  await Promise.all([
+    ...projects.map(async (p) => {
+      if (p.configPath === null) return
+      for (const f of await configImports(p.configPath)) projectImports.add(f)
+    }),
+    ...WORKSPACE_CONFIG_FILENAMES.map(async (name) => {
+      for (const f of await configImports(path.join(workspaceRoot, name))) wsImports.add(f)
+    }),
+  ])
+  let staged: Map<string, ProjectEntry> | null = null
+  try {
+    staged = await loadCliProjects(workspaceRoot, projects, 'all', load)
+  } catch {
+    staged = null
+  }
+  if (staged !== null) {
+    for (const p of staged.values()) fold(p.dir, p.config)
+    return result(staged)
+  }
+  await Promise.all(
+    projects.map(async (p) => {
+      if (p.configPath === null) return
       try {
-        const config = await loadProjectConfig(p.configPath)
-        let wide = false
-        for (const task of Object.values(config.tasks ?? {})) {
-          if ((task.cache?.inputs?.workspaceFiles?.length ?? 0) > 0) wide = true
-          add(p.dir, task.cache?.outputs?.files)
-          add(workspaceRoot, task.cache?.outputs?.workspaceFiles)
-        }
-        return wide
+        fold(p.dir, await loadProjectConfig(p.configPath))
       } catch {
         // broken config — out of this concern's scope
-        return false
       }
     }),
   )
-  return { workspaceWide: uses.includes(true), outputs }
+  return result(null)
+}
+
+/**
+ * Under the recursive root watcher, the events that can move a key. The
+ * watcher hears every write in the workspace; a key can see three kinds
+ * of path and no other: a file inside a project's directory (its own
+ * `inputs.files`, or its outputs, which the ignore filter drops next), a
+ * workspace fingerprint file at the root, and a match of a declared
+ * `inputs.workspaceFiles` glob. Everything else — a log written at the
+ * root, a `coverage/` or `.turbo/` tree, an editor's scratch file — is
+ * dropped before the trigger, so it costs no cycle. Before this rule the
+ * one Turbo idiom that puts every repo on this watcher
+ * (`globalDependencies` → `workspaceFiles`) made `vx watch … > build.log`
+ * inside the repo a loop that never settled: each cycle's output grew the
+ * log, the log was an event, the event was a cycle. Negated globs are not
+ * consulted: a `!` only narrows, and an event it would have excluded costs
+ * one cache-hit cycle, which is the wrong direction to be clever in.
+ */
+export function makeRootEventFilter(
+  workspaceRoot: string,
+  projectDirs: readonly string[],
+  workspaceInputs: readonly string[],
+  claimedRootFiles: ReadonlySet<string> = new Set(),
+): (filename: string) => boolean {
+  const dirs = projectDirs.map((d) => path.resolve(d))
+  const globs = workspaceInputs
+    .map(normalizeGlob)
+    .filter((g) => !g.startsWith('!'))
+    .map((g) => taskGlob(g))
+  return (filename: string): boolean => {
+    const rel = filename.split(path.sep).join('/')
+    // The depth test is a READING AID, not a guard: both predicates below
+    // are exact membership in a set of BARE names, so a `rel` carrying a
+    // slash can never be in one. Measured with it removed (item 502) over
+    // `nested/bun.lock`, `./bun.lock`, `a/b/c/pnpm-workspace.yaml` and
+    // eight more: every answer identical. The two table rows that look
+    // like they pin it — `nested/pnpm-lock.yaml → false` and
+    // `nested/vx.workspace.ts → false` — pass either way; what they
+    // actually pin is that the predicates stay exact rather than becoming
+    // a basename or suffix match, which is the change that WOULD make
+    // this line load-bearing.
+    if (
+      !rel.includes('/') &&
+      (isWorkspaceFingerprintFile(rel) || isWorkspaceConfigFile(rel) || claimedRootFiles.has(rel))
+    ) {
+      return true
+    }
+    const abs = path.resolve(workspaceRoot, filename)
+    for (const d of dirs) if (abs === d || abs.startsWith(d + path.sep)) return true
+    for (const g of globs) if (g.match(rel)) return true
+    return false
+  }
 }
 
 interface WatchLoopArgs {
   opts: RunOptions
+  /** The persistent tasks the initial run left running; the next cycle stops them before it starts. */
+  held: HeldPersistent | undefined
+  /** Aborted by the SIGINT/SIGTERM handlers `watchCmd` installed; the loop drains its cycle and resolves. */
+  stop: AbortSignal
   workspaceRoot: string
   projects: readonly ProjectMeta[]
   workspaceWide: boolean
+  /** Every project's directory, in scope or not — under the root watcher an edit there is an edit. */
+  projectDirs: readonly string[]
+  /** Every declared `inputs.workspaceFiles` glob, root-relative. */
+  workspaceInputs: readonly string[]
   /** Absolute, already-resolved — the loop must never re-derive it. */
   cacheDir: string
   /** Declared output globs per directory they are relative to (project dir, or the root for `workspaceFiles`). */
   outputs: ReadonlyMap<string, readonly string[]>
+  /** Declared input globs per directory: never ignored as another task's output. */
+  inputs: ReadonlyMap<string, readonly string[]>
+  /** Projects whose uncached task may read a git-ignored file: such a path there is still an edit. */
+  uncached: ReadonlySet<string>
+  /** Files the configs import: an edit to one outside the watched projects is a cycle that re-reads them. */
+  configImports: readonly string[]
+  /** Files the workspace config imports: loaded once per process, so an edit is named, not run. */
+  workspaceConfigImports: readonly string[]
+  /**
+   * Root files a plugin claims (`VxPlugin.fingerprint`): a lockfile, or a
+   * file its stages read (`turbo.json`, item 961). The workspace config is
+   * loaded once per process, so the set is fixed for the loop.
+   */
+  claimedRootFiles: ReadonlySet<string>
+  /** The directory each `<dir>/*` package glob names; a member coming or going there is a cycle. */
+  memberBases: readonly string[]
+  /** Every package's directory, in scope or not: a member base's other entries are packages still to come. */
+  packageDirs: ReadonlySet<string>
+  /** The watched set again, after a cycle that followed an event which can change it. */
+  rediscover: () => Promise<Rediscovered>
+}
+
+interface Rediscovered {
+  projects: readonly ProjectMeta[]
+  workspaceWide: boolean
+  workspaceInputs: readonly string[]
+  outputs: ReadonlyMap<string, readonly string[]>
+  inputs: ReadonlyMap<string, readonly string[]>
+  uncached: ReadonlySet<string>
+  configImports: readonly string[]
+  workspaceConfigImports: readonly string[]
+  packageDirs: ReadonlySet<string>
 }
 
+const PROJECT_CONFIGS: ReadonlySet<string> = new Set(PROJECT_CONFIG_FILENAMES)
+
+/**
+ * A file whose edit can change what the loop watches: a `package.json`
+ * (a dependency added under `--filter` widens the closure), a project
+ * config (a task that starts declaring `workspaceFiles` needs the root
+ * watcher, a new output must stop being an event) or the workspace config
+ * (a plugin's `project` stage). Until item 891 only a member directory
+ * coming or going re-read the set, so each of these waited for a restart
+ * while the loop looked alive.
+ */
+function shapesWatchedSet(filename: string): boolean {
+  const base = path.basename(filename)
+  return base === 'package.json' || PROJECT_CONFIGS.has(base) || isWorkspaceConfigFile(base)
+}
+
+const CLOSED: WatchHandle = { close() {} }
+
 async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
-  const { opts, workspaceRoot, projects, workspaceWide, cacheDir, outputs } = args
+  const { opts, stop, workspaceRoot, projects, cacheDir, memberBases } = args
+  // The watched set as of the last cycle: `rearm` replaces these after an
+  // event that can change it, and every filter below reads the current one.
+  let workspaceWide = args.workspaceWide
+  let packageDirs = args.packageDirs
+  let projectDirs = args.projectDirs
+  let workspaceInputs = args.workspaceInputs
+  let outputs = args.outputs
+  let inputs = args.inputs
+  let uncached = args.uncached
+  let configImportFiles = args.configImports
+  let wsConfigImportFiles = args.workspaceConfigImports
+  // A dev server stays up while the loop idles; the cycle that replaces it
+  // stops it first, so the new one never meets the old one's port.
+  let held = args.held
 
-  // Reentrancy guard — never two orchestrator runs in flight. While
-  // one is running, any further events set `pending = true` and the
-  // loop drains it after the current run finishes.
+  // Reentrancy guard — never two orchestrator runs in flight. Events that
+  // land while one is running wait in `pendingPaths` and are judged, on
+  // settled bytes, one debounce window after it ends.
   let running = false
-  let pending = false
+  /** The cycle in flight, so the stop path can wait for its teardown before resolving. */
+  let inFlight: Promise<void> = Promise.resolve()
   let debounceTimer: ReturnType<typeof setTimeout> | null = null
 
-  const trigger = (label: string): void => {
+  // Declared outputs are ignored by PATH above. A task with no `cache`
+  // block declares none and still writes into its project, and the
+  // watcher sees the write: run 1 writes dist/x, the event re-runs, run 2
+  // writes the same bytes, the event re-runs — forever (the init
+  // walkthrough, 2026-09-04: every fresh workspace, since `init` emits no
+  // cache block). An undeclared write is caught by STATE, judged on what
+  // has settled (see `trigger`): a path whose settled state equals what
+  // this loop last saw for it is not a change. A file's state is its
+  // bytes; a directory's is its entries' names and sizes (a nested edit
+  // arrives as that path's own event); a path that is gone is one more
+  // state. A real edit changes the state; a first sighting passes through.
+  // So `rm -rf dist && tsc` — the shape of most build scripts — settles
+  // to the same `dist` it left and is one redundant cycle, not a loop
+  // (2026-09-10: 780 executions in two minutes from one edit, when a
+  // deletion and a directory each passed the gate unconditionally).
+  const ABSENT = -1n
+  const lastState = new Map<string, bigint>()
+  const settledState = (abs: string): bigint => {
+    let st: fs.Stats
+    try {
+      st = fs.statSync(abs)
+    } catch {
+      return ABSENT
+    }
+    if (!st.isDirectory()) {
+      try {
+        return xxh3(fs.readFileSync(abs))
+      } catch {
+        return ABSENT
+      }
+    }
+    const entries: string[] = []
+    try {
+      for (const e of fs.readdirSync(abs, { withFileTypes: true })) {
+        let size = 0
+        if (e.isFile()) {
+          try {
+            size = fs.statSync(path.join(abs, e.name)).size
+          } catch {
+            size = -1
+          }
+        }
+        entries.push(`${e.name}\0${e.isDirectory() ? 'd' : size}`)
+      }
+    } catch {
+      return ABSENT
+    }
+    entries.sort()
+    return xxh3(Buffer.from(entries.join('\n')))
+  }
+  // A path this loop has never judged is a change only if it moved since
+  // the watchers went live (its mtime or ctime, `modifiedBefore`). macOS delivers the initial run's own writes
+  // AFTER the arm (CI, 2026-09-11: `app dist; re-running...` with no edit
+  // made — FSEvents hands a stream what landed just before it started),
+  // and a first sighting used to pass unconditionally; the path's mtime
+  // says which side of the arm it belongs to. A path already gone is a
+  // change: a deletion has no date to read.
+  const sameState = (abs: string): boolean => {
+    const state = settledState(abs)
+    const prev = lastState.get(abs)
+    lastState.set(abs, state)
+    if (prev !== undefined) return prev === state
+    return state !== ABSENT && modifiedBefore(abs, armedAt)
+  }
+
+  // Paths that fired since the last judgement, first label wins. The state
+  // check runs when the timer fires, on SETTLED state: per event it is
+  // wrong on Linux, where a shell redirect truncates the file (one event,
+  // empty) and then writes it (another, full), so consecutive events never
+  // agree and a self-write loops anyway (CI, 2026-09-04: 9 re-runs where
+  // macOS, which coalesces the two, saw 2). While a cycle runs, nothing is
+  // judged: the run's own writes are mid-flight (a `dist` deleted and not
+  // yet rebuilt is a state the tree will not keep), so the paths wait and
+  // are judged one window after the run ends, all together — an edit made
+  // meanwhile still differs from what the loop last saw and re-runs.
+  const pendingPaths = new Map<string, string>()
+  // A path that starts cycle after cycle from the run's own writes is a
+  // task rewriting a file with different bytes every run (a pid file, a
+  // timestamped log): the state gate cannot settle it, and nothing here
+  // can tell the third such write from a user's third save mid-run — so
+  // watch names it once, with the remedy, and keeps going. "The run's
+  // own write" is read off the path itself: its mtime falls inside the
+  // previous cycle's window. Not off which judgement started the cycle:
+  // macOS delivers a run's writes late, after the loop's own post-run
+  // judgement found nothing and broke out, so there every such cycle
+  // starts from the idle timer (CI, 2026-09-16: the storm ran, the
+  // notice never came).
+  const streak = { abs: '', n: 0 }
+  const noticed = new Set<string>()
+  let lastCycle: { start: number; end: number } | undefined
+  const writtenDuringLastCycle = (abs: string, openWhileHeld = false): boolean => {
+    // A server the last cycle left running is still that cycle's: its
+    // writes land after the cycle ended, and with a closed window a dev
+    // server that rewrites a log in its project restarted itself forever
+    // with no word of it, 12 restarts in 8 s (item 948). The initial run's
+    // server is one too, from the arm on.
+    const open = openWhileHeld && held !== undefined
+    if (lastCycle === undefined && !open) return false
+    try {
+      const m = fs.statSync(abs).mtimeMs
+      const start = lastCycle?.start ?? armedAt
+      return m >= start && (open || m <= lastCycle!.end)
+    } catch {
+      return false
+    }
+  }
+  const judge = (): string | undefined => {
+    const ignored = gitIgnored(workspaceRoot, [...pendingPaths.keys()])
+    let first: string | undefined
+    let firstAbs: string | undefined
+    // `sameState` before the `first` test, never after it: it is what
+    // RECORDS a path's settled state, and every path this judgement saw
+    // must be recorded even though only the first change names the cycle.
+    // Short-circuiting after the winner leaves the rest unjudged, and
+    // their next event is a first sighting stamped after the arm — so a
+    // batch edit (a `git checkout`) makes the same bytes written to any
+    // of the others a change.
+    // A git-ignored path keys nothing, but a task with no cache has no key:
+    // it reads what it likes, and its `.env.local` edit re-ran nothing
+    // (item 947). Under such a project an ignored path is judged when the
+    // user wrote it; one the last cycle wrote (the pid file an uncached
+    // task rewrites every run, the loop the filter exists for) stays out.
+    const editForUncached = (p: string): boolean =>
+      [...uncached].some((dir) => p.startsWith(dir + path.sep)) && !writtenDuringLastCycle(p)
+    for (const [p, l] of pendingPaths) {
+      if (ignored.has(p) && !editForUncached(p)) continue
+      if (!sameState(p) && first === undefined) {
+        first = l
+        firstAbs = p
+      }
+    }
+    pendingPaths.clear()
+    const byServer = firstAbs !== undefined && held !== undefined
+    if (firstAbs === undefined || !writtenDuringLastCycle(firstAbs, true)) {
+      streak.n = 0
+      return first
+    }
+    streak.n = streak.abs === firstAbs ? streak.n + 1 : 1
+    streak.abs = firstAbs
+    if (streak.n >= 3 && !noticed.has(firstAbs)) {
+      noticed.add(firstAbs)
+      process.stdout.write(
+        byServer
+          ? `vx watch: ${first} has started 3 cycles in a row, written while a server the cycle before started was running — a persistent task rewrites it. Add it to .gitignore (a git-ignored path never starts a cycle); until then every write restarts the server.\n`
+          : `vx watch: ${first} has started 3 cycles in a row, written by the cycle before each — a task rewrites it every run. Declare it in cache.outputs (an output never starts a cycle) or add it to .gitignore (a git-ignored path never does); until then every run re-runs.\n`,
+      )
+    }
+    return first
+  }
+  const trigger = (label: string, abs: string): void => {
+    if (!pendingPaths.has(abs)) pendingPaths.set(abs, label)
+    if (running) return
     if (debounceTimer) clearTimeout(debounceTimer)
     debounceTimer = setTimeout(() => {
       debounceTimer = null
-      void cycle(label)
+      if (running) return
+      const first = judge()
+      if (first !== undefined) void cycle(first)
     }, DEBOUNCE_MS)
   }
 
   const cycle = async (label: string): Promise<void> => {
-    if (running) {
-      pending = true
-      return
-    }
+    if (stop.aborted || running) return
     running = true
+    const done = (inFlight = runCycle(label))
+    await done
+  }
+  const runCycle = async (first: string): Promise<void> => {
     try {
-      do {
-        pending = false
+      let label: string | undefined = first
+      while (label !== undefined && !stop.aborted) {
         process.stdout.write(`\nvx watch: ${label}; re-running...\n\n`)
         try {
-          await runOrchestrator(opts)
+          await held?.stop()
+          held = undefined
+          const start = Date.now()
+          held = (await runOrchestrator(opts)).persistent
+          lastCycle = { start, end: Date.now() }
+          if (reread && !stop.aborted) {
+            reread = false
+            await rearm()
+          }
         } catch (err) {
           // A re-run can fail catastrophically when the workspace
           // itself moved out from under us — e.g. the user deleted
@@ -360,10 +1049,18 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
           const message = err instanceof Error ? err.message : String(err)
           process.stderr.write(`vx watch: cycle failed: ${message}\n`)
         }
-        // If a change arrived mid-run, loop again immediately.
-      } while (pending)
+        // What landed mid-run is judged on settled state, one window
+        // after the run, under the label of what actually arrived.
+        if (pendingPaths.size === 0 || stop.aborted) break
+        await Bun.sleep(DEBOUNCE_MS)
+        label = judge()
+      }
     } finally {
       running = false
+      // Anything that landed after the last judgement waits for a timer
+      // like any other event.
+      const next = pendingAfterCycle(pendingPaths, stop.aborted)
+      if (next !== undefined) trigger(next[1], next[0])
     }
   }
 
@@ -371,84 +1068,337 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
   // project's dir recursively, so a `node_modules` write under a
   // project would otherwise trigger every save during `bun install` —
   // and vx's own cache writes would trigger a cycle that writes again.
-  const isIgnoredPath = makeWatchIgnore(cacheDir, outputs)
+  let isIgnoredPath = makeWatchIgnore(cacheDir, outputs, inputs)
+  let matters = makeRootEventFilter(
+    workspaceRoot,
+    projectDirs,
+    workspaceInputs,
+    args.claimedRootFiles,
+  )
+  /** Since the last cycle, a member came or went, or a file that shapes the watched set changed (`shapesWatchedSet`). */
+  let reread = false
 
-  const watchers: fs.FSWatcher[] = []
+  const watchers: WatchHandle[] = []
   const proofs: Promise<void>[] = []
-  const arm = (dir: string, recursive: boolean, onEvent: (filename: string) => void): void => {
+  // `VX_WATCH_POLL=1` skips the OS watcher entirely. Where it is known not
+  // to work — a sandbox with no `machLookup` for `com.apple.FSEvents`, a
+  // network mount, a container bind — the attempt costs a denied syscall
+  // and a two-second wait before the fallback takes over anyway.
+  const forcePoll = (process.env['VX_WATCH_POLL'] ?? '') !== ''
+  if (forcePoll)
+    process.stderr.write(`vx watch: polling every ${POLL_INTERVAL_MS} ms (VX_WATCH_POLL)\n`)
+  // The poller skips exactly what the event filter would drop: the
+  // unconditional segments AND this run's declared output containers. Read
+  // through `isIgnoredPath` rather than captured, because `rearm` replaces
+  // the filter when the selection changes.
+  const skipUnder =
+    (dir: string) =>
+    (rel: string): boolean =>
+      isIgnoredPath(dir, rel)
+  // By slot, not by handle: an OS watcher that never proves delivery is
+  // swapped for a poller in place, and a drop must close what is there.
+  const arm = (
+    dir: string,
+    recursive: boolean,
+    onEvent: (filename: string) => void,
+  ): WatchHandle => {
+    const at = watchers.length
+    const handle: WatchHandle = {
+      close: () => {
+        watchers[at]?.close()
+        watchers[at] = CLOSED
+      },
+    }
+    if (forcePoll) {
+      watchers.push(pollWatcher(dir, recursive, onEvent, POLL_INTERVAL_MS, skipUnder(dir)))
+      return handle
+    }
     const armed = armWatcher(dir, recursive, onEvent)
     watchers.push(armed.watcher)
     proofs.push(
       armed.ready.then((ok) => {
-        if (!ok) {
-          process.stderr.write(
-            `vx watch: ${dir}: the watcher gave no sign of life within ${WATCH_PROBE_TIMEOUT_MS} ms; early edits there may be missed\n`,
-          )
-        }
+        if (ok) return
+        armed.watcher.close()
+        // Dropped by a rearm before its proof settled: nothing to swap in.
+        if (watchers[at] !== armed.watcher) return
+        // The watcher never proved delivery, so it is not one: an FSEvents
+        // stream the OS refused, a filesystem that reports nothing. Swap in
+        // the poller rather than run a loop that silently never fires.
+        watchers[at] = pollWatcher(dir, recursive, onEvent, POLL_INTERVAL_MS, skipUnder(dir))
+        process.stderr.write(
+          `vx watch: ${dir}: no OS watch events within ${WATCH_PROBE_TIMEOUT_MS} ms; polling every ${POLL_INTERVAL_MS} ms instead\n`,
+        )
       }),
     )
+    return handle
   }
 
-  if (workspaceWide) {
-    // workspaceFiles inputs in play: any file in the workspace can be
-    // an input, so one recursive root watcher replaces the per-project
-    // ones (it also covers lockfile / pnpm-workspace.yaml edits). The
-    // ignore filter keeps node_modules / .git / .vx churn out; edits
-    // outside any task's inputs still cost only a cache-hit cycle.
+  /** The instant the watchers go live, on the mtime clock (see `fsClockNow`): a path last modified before it is the initial run's, not an edit. */
+  const armedAt = fsClockNow(cacheDir)
+  /** Per-project arms by directory, so `rearm` can add and drop them. */
+  const perProject = new Map<string, WatchHandle>()
+  /** The root arm: recursive when workspace-wide, else the root's own files only. */
+  let rootArm: WatchHandle = CLOSED
+  const armProject = (proj: ProjectMeta): void => {
     try {
-      arm(workspaceRoot, true, (filename) => {
-        if (isIgnoredPath(workspaceRoot, filename)) return
-        trigger(`root ${filename}`)
+      const handle = arm(proj.dir, true, (filename) => {
+        if (isIgnoredPath(proj.dir, filename)) return
+        if (shapesWatchedSet(filename)) reread = true
+        trigger(`${proj.name} ${filename}`, path.join(proj.dir, filename))
       })
+      perProject.set(proj.dir, handle)
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      process.stderr.write(`vx watch: cannot watch ${proj.dir}: ${msg}\n`)
+    }
+  }
+  const armRoot = (): void => {
+    try {
+      rootArm = workspaceWide
+        ? // workspaceFiles inputs in play: a root-relative glob can name a
+          // file anywhere, so one recursive root watcher replaces the
+          // per-project ones (it also covers lockfile / pnpm-workspace.yaml
+          // edits). `matters` keeps the events a key can see — project
+          // trees, root fingerprint files, the declared globs — and drops
+          // the rest of the tree; the ignore filter then keeps node_modules
+          // / .git / .vx and declared outputs out of what remains.
+          arm(workspaceRoot, true, (filename) => {
+            if (!matters(filename) || isIgnoredPath(workspaceRoot, filename)) return
+            if (shapesWatchedSet(filename) || filename === LOCKFILE_NAME) reread = true
+            trigger(`root ${filename}`, path.join(workspaceRoot, filename))
+          })
+        : // The root itself, non-recursive, beside the per-project arms, so
+          // lockfile + pnpm-workspace.yaml edits trigger re-runs even when
+          // no project dir saw the change.
+          arm(workspaceRoot, false, (filename) => {
+            if (
+              isWorkspaceFingerprintFile(filename) ||
+              isWorkspaceConfigFile(filename) ||
+              args.claimedRootFiles.has(filename)
+            ) {
+              if (shapesWatchedSet(filename) || filename === LOCKFILE_NAME) reread = true
+              trigger(`root ${filename}`, path.join(workspaceRoot, filename))
+            }
+          })
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err)
       process.stderr.write(`vx watch: cannot watch workspace root: ${msg}\n`)
     }
-  } else {
-    // One recursive watcher per project. Each project owns its own
-    // subtree; we don't watch the workspace root recursively (would
-    // cover every project + node_modules + caches).
-    for (const proj of projects) {
+  }
+  // One recursive watcher per project, unless workspace-wide: each project
+  // owns its own subtree; the root is never watched recursively for them
+  // (it would cover every project + node_modules + caches).
+  const armMode = (watched: readonly ProjectMeta[]): void => {
+    if (!workspaceWide) for (const proj of watched) armProject(proj)
+    armRoot()
+  }
+  const dropMode = (): void => {
+    for (const handle of perProject.values()) handle.close()
+    perProject.clear()
+    rootArm.close()
+    rootArm = CLOSED
+  }
+
+  /**
+   * A directory under a member base with no package in it yet. The base's
+   * own watcher is not recursive, so the `package.json` that makes it a
+   * package is an event only here; an editor or `git checkout` that makes
+   * the directory first and the manifest after left the package unwatched
+   * for good (item 891). On a rearm a new entry is armed before its
+   * manifest is checked, so one that landed after the re-read is an event
+   * or is seen by the check. At start there is no re-read to race, and a
+   * manifest already there is a directory the globs exclude.
+   */
+  const pending = new Map<string, WatchHandle>()
+  const armPending = (afterReread: boolean): void => {
+    const want = new Set<string>()
+    for (const base of memberBases)
+      for (const name of memberEntries(base)) {
+        const dir = path.join(base, name)
+        if (!packageDirs.has(dir)) want.add(dir)
+      }
+    for (const [dir, handle] of pending) {
+      if (want.has(dir)) continue
+      handle.close()
+      pending.delete(dir)
+    }
+    for (const dir of want) {
+      if (pending.has(dir)) continue
+      const manifest = path.join(dir, 'package.json')
+      const arrived = (): void => {
+        reread = true
+        trigger(path.relative(workspaceRoot, manifest), manifest)
+      }
+      try {
+        pending.set(
+          dir,
+          arm(dir, false, (filename) => {
+            if (filename === 'package.json') arrived()
+          }),
+        )
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err)
+        process.stderr.write(`vx watch: cannot watch ${dir}: ${msg}\n`)
+        continue
+      }
+      if (afterReread && fs.existsSync(manifest)) arrived()
+    }
+  }
+
+  /**
+   * A config's imports from outside the watched projects: a shared preset
+   * (`../../shared/preset.mjs`) changed what a run evaluates and no arm
+   * saw it (item 949). One non-recursive arm per directory holding one.
+   * A project config's import re-reads and runs; a workspace config's is
+   * loaded once per process (Bun keeps the module), so its edit is named
+   * with the restart it needs instead of a cycle that would run stale.
+   */
+  const importArms = new Map<string, WatchHandle>()
+  let importNames = new Map<string, Set<string>>()
+  const staleNamed = new Map<string, number>()
+  const armImports = (): void => {
+    const inProject = (f: string): boolean => projectDirs.some((d) => f.startsWith(d + path.sep))
+    const want = new Map<string, Set<string>>()
+    for (const f of new Set([...configImportFiles, ...wsConfigImportFiles])) {
+      if (inProject(f)) continue
+      const names = want.get(path.dirname(f)) ?? new Set<string>()
+      names.add(path.basename(f))
+      want.set(path.dirname(f), names)
+    }
+    importNames = want
+    for (const [dir, handle] of importArms) {
+      if (want.has(dir)) continue
+      handle.close()
+      importArms.delete(dir)
+    }
+    for (const dir of want.keys()) {
+      if (importArms.has(dir)) continue
       try {
-        arm(proj.dir, true, (filename) => {
-          if (isIgnoredPath(proj.dir, filename)) return
-          trigger(`${proj.name} ${filename}`)
-        })
+        importArms.set(
+          dir,
+          arm(dir, false, (filename) => {
+            if (!(importNames.get(dir)?.has(filename) ?? false)) return
+            const abs = path.join(dir, filename)
+            const rel = path.relative(workspaceRoot, abs)
+            if (configImportFiles.includes(abs)) {
+              reread = true
+              trigger(`config import ${rel}`, abs)
+              return
+            }
+            // One line per save, not per event: a save is often two.
+            const now = Date.now()
+            if (now - (staleNamed.get(abs) ?? 0) < 1_000) return
+            staleNamed.set(abs, now)
+            process.stdout.write(
+              `vx watch: ${rel} changed; the workspace config imports it, and this process loaded it at start — restart vx watch to apply the edit\n`,
+            )
+          }),
+        )
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err)
-        process.stderr.write(`vx watch: cannot watch ${proj.dir}: ${msg}\n`)
+        process.stderr.write(`vx watch: cannot watch ${dir}: ${msg}\n`)
       }
     }
+  }
 
-    // Plus the workspace root itself (non-recursive) so lockfile +
-    // pnpm-workspace.yaml edits trigger re-runs even when no project
-    // dir saw the change.
+  const watchingLine = (count: number): string =>
+    workspaceWide
+      ? 'vx watch: watching the workspace root (workspaceFiles inputs in use)'
+      : `vx watch: watching ${count} project(s)`
+
+  const rearm = async (): Promise<void> => {
+    let next: Rediscovered
+    try {
+      next = await args.rediscover()
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      process.stderr.write(`vx watch: cannot re-read the workspace: ${msg}\n`)
+      return
+    }
+    projectDirs = next.projects.map((p) => p.dir)
+    workspaceInputs = next.workspaceInputs
+    outputs = next.outputs
+    inputs = next.inputs
+    uncached = next.uncached
+    configImportFiles = next.configImports
+    wsConfigImportFiles = next.workspaceConfigImports
+    packageDirs = next.packageDirs
+    isIgnoredPath = makeWatchIgnore(cacheDir, outputs, inputs)
+    matters = makeRootEventFilter(
+      workspaceRoot,
+      projectDirs,
+      workspaceInputs,
+      args.claimedRootFiles,
+    )
+    if (next.workspaceWide !== workspaceWide) {
+      // A task started or stopped declaring `workspaceFiles`: the other
+      // arm's shape. Until item 891 the choice was made once, at start, and
+      // a root file a config newly named was never an event.
+      dropMode()
+      workspaceWide = next.workspaceWide
+      armMode(next.projects)
+    } else if (!workspaceWide) {
+      const keep = new Set(projectDirs)
+      for (const [dir, handle] of perProject) {
+        if (keep.has(dir)) continue
+        handle.close()
+        perProject.delete(dir)
+      }
+      for (const proj of next.projects) if (!perProject.has(proj.dir)) armProject(proj)
+    }
+    armPending(true)
+    armImports()
+    // A new arm proves delivery like the first ones: an edit in the new
+    // package right after this cycle is seen, not lost in the gap.
+    await Promise.all(proofs)
+    process.stdout.write(`${watchingLine(next.projects.length)}\n`)
+  }
+
+  armMode(projects)
+
+  // A package added while the loop runs is a directory entry appearing
+  // under the glob's directory (`packages/` for `packages/*`); one
+  // non-recursive watcher there hears it come or go, and the cycle it
+  // triggers re-reads the workspace (`rearm`) so the new package's own
+  // edits are cycles from then on. Until 2026-09-10 the watched set was
+  // fixed when the loop armed: the next cycle ran the new package, and
+  // every edit inside it after that was silence.
+  for (const base of memberBases) {
+    let members = memberEntries(base)
     try {
-      arm(workspaceRoot, false, (filename) => {
-        if (isWorkspaceFingerprintFile(filename)) trigger(`root ${filename}`)
+      arm(base, false, (filename) => {
+        if (isIgnoredWatchPath(filename)) return
+        // Only a member coming or going. On macOS a non-recursive watcher
+        // also reports a member whose CONTENTS changed (FSEvents names the
+        // directory a write landed in), so a task writing into its own
+        // project — or the arm's own probe file — read as a member event and
+        // cost an uncached task one execution per cycle (CI, 2026-09-10).
+        const now = memberEntries(base)
+        if (sameMembers(members, now)) return
+        members = now
+        reread = true
+        trigger(`${path.relative(workspaceRoot, base)}/${filename}`, path.join(base, filename))
       })
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err)
-      process.stderr.write(`vx watch: cannot watch workspace root: ${msg}\n`)
+      process.stderr.write(`vx watch: cannot watch ${base}: ${msg}\n`)
     }
   }
+  armPending(false)
+  armImports()
 
-  // The orchestrator's writes into `.vx/cache/` don't trigger
-  // re-runs because IGNORED_SEGMENTS includes `.vx`. Users who
-  // relocate the cache dir outside `.vx/` need their own filtering.
+  // The orchestrator's own writes never kick the loop: `makeWatchIgnore`
+  // closes over the RESOLVED cache dir (relocated or not) and the tasks'
+  // declared outputs.
 
   // "watching" is a promise that an edit from now on is seen; every
   // watcher has proved (or been given 2 s to prove) delivery first.
   await Promise.all(proofs)
 
-  process.stdout.write(
-    workspaceWide
-      ? `\nvx watch: watching the workspace root (workspaceFiles inputs in use); press Ctrl+C to stop\n`
-      : `\nvx watch: watching ${projects.length} project(s); press Ctrl+C to stop\n`,
-  )
+  process.stdout.write(`\n${watchingLine(projects.length)}; press Ctrl+C to stop\n`)
 
   return await new Promise<number>((resolve) => {
-    const cleanup = (): void => {
+    const cleanup = async (): Promise<void> => {
       for (const w of watchers) {
         try {
           w.close()
@@ -457,16 +1407,112 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
         }
       }
       if (debounceTimer) clearTimeout(debounceTimer)
+      // The aborted cycle is tearing its children down; resolve only once
+      // it has returned, so the process never exits over a live child.
+      await inFlight
+      await held?.stop(forwardedSignal(stop.reason))
       resolve(0)
     }
-    process.once('SIGINT', () => {
-      process.stdout.write('\nvx watch: stopped\n')
-      cleanup()
-    })
-    process.once('SIGTERM', cleanup)
+    if (stop.aborted) {
+      void cleanup()
+      return
+    }
+    stop.addEventListener('abort', () => void cleanup(), { once: true })
   })
 }
 
+/**
+ * The event a finished cycle hands back to the timer, if any.
+ *
+ * The inner loop re-runs while anything is pending, so this covers only the
+ * narrow gap between its LAST judgement and the loop going idle: an event
+ * landing there would otherwise sit in `pendingPaths` with no timer armed
+ * and no cycle to notice it — watch quietly idle over an edit the user
+ * made. Insertion order, because the map is "first label wins" and the
+ * label is what the cycle announces.
+ *
+ * A branch, not a race: extracted so it can be pinned at all. Deleting the
+ * arming left every green test in the repo green (2026-09-20) — the e2e
+ * watch fixture spawns a real `vx watch`, so it cannot deliver an event at
+ * that instant, and the suites that could are the ones this repo's cloud
+ * container already fails for timing reasons. What this pins is the
+ * decision; the delivery window is the process's own.
+ */
+export function pendingAfterCycle(
+  pending: ReadonlyMap<string, string>,
+  aborted: boolean,
+): [abs: string, label: string] | undefined {
+  if (aborted || pending.size === 0) return undefined
+  const [abs, label] = [...pending][0]!
+  return [abs, label]
+}
+
+/** True when `abs` was last modified before `t` (epoch ms); false when it cannot be read. */
+export function modifiedBefore(abs: string, t: number): boolean {
+  try {
+    // The later of the two clocks: `mv`, `cp -p`, `rsync -a` and `tar x`
+    // carry a file's OLD mtime onto the new one, and judged by mtime alone
+    // such an edit was "before the arm" and never ran (item 945). No
+    // process can set a ctime, and a rename or a write moves it.
+    const st = fs.statSync(abs)
+    return Math.max(st.mtimeMs, st.ctimeMs) < t
+  } catch {
+    return false
+  }
+}
+
+/**
+ * "Now" as the filesystem will stamp the next write, not as `Date.now()`
+ * reads it. A file's mtime comes from the kernel's coarse clock, which
+ * runs up to a tick behind the fine clock `Date.now()` reads — measured
+ * on the Linux bench box 2026-09-11: 2 of 3,000 tight writes carried an
+ * mtime 5.8 ms EARLIER than a `Date.now()` taken before the write, and
+ * more under CPU load, where the tick is skipped. An `armedAt` from the
+ * fine clock then judged an edit made right after the ready line as
+ * "modified before the arm" and dropped it (the watch e2e flake, three
+ * shard runs that day; traced: raw event, trigger, `same=true`). A stamp
+ * read off a file written here is on the mtime clock itself, and every
+ * later write's mtime is at or after it.
+ */
+export function fsClockNow(dir: string): number {
+  const stamp = path.join(dir, WATCH_CLOCK_STAMP)
+  try {
+    fs.writeFileSync(stamp, '')
+    const at = fs.statSync(stamp).mtimeMs
+    fs.unlinkSync(stamp)
+    return at
+  } catch {
+    return Date.now()
+  }
+}
+
+/**
+ * The directory entries under a package glob's directory that can be
+ * members: directories (or links) whose name is not dotted and not
+ * `node_modules`, the same rule discovery applies. A watcher on that
+ * directory reacts only when this set changes.
+ */
+export function memberEntries(base: string): ReadonlySet<string> {
+  const out = new Set<string>()
+  let entries: fs.Dirent[]
+  try {
+    entries = fs.readdirSync(base, { withFileTypes: true })
+  } catch {
+    return out
+  }
+  for (const e of entries) {
+    if (e.name.startsWith('.') || e.name === 'node_modules') continue
+    if (e.isDirectory() || e.isSymbolicLink()) out.add(e.name)
+  }
+  return out
+}
+
+function sameMembers(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
+  if (a.size !== b.size) return false
+  for (const name of a) if (!b.has(name)) return false
+  return true
+}
+
 /**
  * True for a root file that re-keys EVERY task, so a change to one must trigger
  * a cycle even though it lives in no project dir.
@@ -483,3 +1529,16 @@ const FINGERPRINT_FILES: ReadonlySet<string> = new Set(WORKSPACE_FINGERPRINT_FIL
 function isWorkspaceFingerprintFile(name: string): boolean {
   return FINGERPRINT_FILES.has(name)
 }
+
+/**
+ * The workspace config is the one root file that shapes a run without
+ * being any task's input — its plugins, `config` stage, concurrency, cache
+ * dir — and a cycle re-evaluates it (its import is keyed on its bytes).
+ * Until 2026-09-10 neither root arm listened for it: a plugin added under
+ * `vx watch` waited for a restart while the loop looked alive.
+ */
+const WORKSPACE_CONFIGS: ReadonlySet<string> = new Set(WORKSPACE_CONFIG_FILENAMES)
+
+function isWorkspaceConfigFile(name: string): boolean {
+  return WORKSPACE_CONFIGS.has(name)
+}