@vzn/vx 0.0.21 → 0.0.22

package/src/cli/watch.ts

@@ -14,18 +14,35 @@
 
 import fs from 'node:fs'
 import path from 'node:path'
-import { normalizeGlob, staticPrefix, xxh3 } from '../util/index.js'
+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,
+  LOCKFILE_NAME,
   memberBaseDirs,
+  PROJECT_CONFIG_FILENAMES,
   WORKSPACE_CONFIG_FILENAMES,
+  configImports,
   WORKSPACE_FINGERPRINT_FILES,
   type ProjectEntry,
   type ProjectMeta,
@@ -72,6 +89,7 @@ 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
@@ -91,14 +109,36 @@ export function makeWatchIgnore(
     ([dir, globs]) =>
       [
         path.resolve(dir),
-        asTrees(globs).map((g) => new Bun.Glob(g)),
+        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
+    if (isInput(abs)) return false
     for (const [dir, globs, containers] of declared) {
       if (!abs.startsWith(dir + path.sep)) continue
       const rel = abs
@@ -119,10 +159,10 @@ export function makeWatchIgnore(
  * container; a pattern's is `staticPrefix` — the same rule the sandbox
  * baseline and the deferral gate read.
  */
-export function outputContainer(raw: string): string {
+function outputContainer(raw: string): string {
   const glob = normalizeGlob(raw)
   if (glob.startsWith('!')) return ''
-  if (!/[*?[\]{}]/.test(glob)) return glob.replace(/\/+$/, '')
+  if (isLiteralPattern(glob)) return glob.replace(/\/+$/, '')
   const prefix = staticPrefix(glob)
   return prefix === '.' || prefix === '/' ? '' : prefix
 }
@@ -134,6 +174,42 @@ export function outputContainer(raw: string): string {
  */
 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. */
@@ -154,12 +230,22 @@ export interface ArmedWatcher {
 const POLL_INTERVAL_MS = 250
 
 /**
- * Directory names the fallback never descends into. `makeWatchIgnore`
- * already drops their EVENTS, but a poller pays for the walk itself, and
+ * 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(['node_modules', '.git', '.vx', 'dist'])
+const POLL_SKIP = new Set(IGNORED_SEGMENTS)
 
 /**
  * A watcher built from `stat`, for when the OS one cannot deliver.
@@ -178,6 +264,13 @@ export function pollWatcher(
   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
@@ -194,7 +287,7 @@ export function pollWatcher(
         if (e.name === WATCH_PROBE) continue
         const childRel = rel === '' ? e.name : `${rel}/${e.name}`
         if (e.isDirectory()) {
-          if (recursive && !POLL_SKIP.has(e.name)) walk(path.join(abs, e.name), childRel)
+          if (recursive && !skipDir(childRel)) walk(path.join(abs, e.name), childRel)
           continue
         }
         if (!e.isFile()) continue
@@ -262,6 +355,12 @@ export function armWatcher(
       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)
@@ -343,21 +442,34 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   // 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, the in-flight cycle tears its children down
-  // (SIGTERM, grace, SIGKILL) and returns, and the loop resolves 0.
+  // 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 }
+  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()
+    stop.abort('SIGINT')
   })
-  process.once('SIGTERM', () => stop.abort())
+  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
@@ -367,8 +479,9 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   // closure `--filter 'app...'` walks, computed below once the initial
   // run has staged the configs. Plus the workspace root, for lockfile
   // changes.
-  const workspaceRoot = await findWorkspaceRoot(cwd)
-  const workspace = await loadWorkspace(workspaceRoot)
+  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))
@@ -391,8 +504,11 @@ 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)
-  if (stop.signal.aborted) return 0
+  const initial = await runOrchestrator(opts)
+  if (stop.signal.aborted) {
+    await initial.persistent?.stop(forwardedSignal(stop.signal.reason))
+    return 0
+  }
 
   const load: CliLoadOptions = {
     ...(opts.cacheDir !== undefined ? { cacheDir: opts.cacheDir } : {}),
@@ -400,8 +516,10 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   }
   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: watched,
@@ -409,7 +527,12 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
     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
@@ -418,10 +541,27 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
       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, workspaceInputs: sweep.workspaceInputs, outputs: sweep.outputs }
+      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 ?? (await loadCliWorkspace(workspaceRoot)).cacheDir,
+    cacheDir: opts.cacheDir ?? ws.cacheDir,
   })
 }
 
@@ -479,18 +619,38 @@ export async function sweepConfigs(
   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])
+    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)
     }
@@ -501,13 +661,32 @@ export async function sweepConfigs(
     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)
@@ -551,15 +730,29 @@ 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) => new Bun.Glob(g))
+    .map((g) => taskGlob(g))
   return (filename: string): boolean => {
     const rel = filename.split(path.sep).join('/')
-    if (!rel.includes('/') && (isWorkspaceFingerprintFile(rel) || isWorkspaceConfigFile(rel))) {
+    // 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)
@@ -571,6 +764,8 @@ export function makeRootEventFilter(
 
 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
@@ -584,25 +779,74 @@ interface WatchLoopArgs {
   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[]
-  /** The watched set again, after a cycle that followed a member event. */
+  /** 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, stop, workspaceRoot, projects, workspaceWide, cacheDir, memberBases } = args
-  // The watched set as of the last cycle: `rearm` replaces these when a
-  // member came or went, and every filter below reads the current one.
+  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. Events that
   // land while one is running wait in `pendingPaths` and are judged, on
@@ -663,7 +907,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
     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. macOS delivers the initial run's own writes
+  // 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
@@ -688,12 +932,77 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
   // 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 (!sameState(p)) first ??= l
+      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 => {
@@ -720,9 +1029,13 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
       while (label !== undefined && !stop.aborted) {
         process.stdout.write(`\nvx watch: ${label}; re-running...\n\n`)
         try {
-          await runOrchestrator(opts)
-          if (membersChanged && !stop.aborted) {
-            membersChanged = false
+          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) {
@@ -746,10 +1059,8 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
       running = false
       // Anything that landed after the last judgement waits for a timer
       // like any other event.
-      if (pendingPaths.size > 0 && !stop.aborted) {
-        const [abs, label] = [...pendingPaths][0]!
-        trigger(label, abs)
-      }
+      const next = pendingAfterCycle(pendingPaths, stop.aborted)
+      if (next !== undefined) trigger(next[1], next[0])
     }
   }
 
@@ -757,10 +1068,15 @@ 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.
-  let isIgnoredPath = makeWatchIgnore(cacheDir, outputs)
-  let matters = makeRootEventFilter(workspaceRoot, projectDirs, workspaceInputs)
-  /** A member came or went under a package glob's directory since the last cycle. */
-  let membersChanged = false
+  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: WatchHandle[] = []
   const proofs: Promise<void>[] = []
@@ -769,47 +1085,227 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
   // 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'] ?? '') !== ''
-  const arm = (dir: string, recursive: boolean, onEvent: (filename: string) => void): void => {
+  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))
-      return
+      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) 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.
-        armed.watcher.close()
-        watchers[watchers.indexOf(armed.watcher)] = pollWatcher(dir, recursive, onEvent)
+        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
   }
 
   /** 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 {
-      const at = watchers.length
-      arm(proj.dir, true, (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))
       })
-      // 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.
-      perProject.set(proj.dir, { close: () => watchers[at]?.close() })
+      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`)
+    }
+  }
+  // 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 {
+        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 ${dir}: ${msg}\n`)
+      }
+    }
+  }
+
+  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 {
@@ -822,9 +1318,26 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
     projectDirs = next.projects.map((p) => p.dir)
     workspaceInputs = next.workspaceInputs
     outputs = next.outputs
-    isIgnoredPath = makeWatchIgnore(cacheDir, outputs)
-    matters = makeRootEventFilter(workspaceRoot, projectDirs, workspaceInputs)
-    if (!workspaceWide) {
+    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
@@ -832,50 +1345,16 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
         perProject.delete(dir)
       }
       for (const proj of next.projects) if (!perProject.has(proj.dir)) armProject(proj)
-      // 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(`vx watch: watching ${next.projects.length} project(s)\n`)
+    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`)
   }
 
-  if (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.
-    try {
-      arm(workspaceRoot, true, (filename) => {
-        if (!matters(filename) || isIgnoredPath(workspaceRoot, filename)) return
-        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) armProject(proj)
-
-    // Plus the workspace root itself (non-recursive) so lockfile +
-    // pnpm-workspace.yaml edits trigger re-runs even when no project
-    // dir saw the change.
-    try {
-      arm(workspaceRoot, false, (filename) => {
-        if (isWorkspaceFingerprintFile(filename) || isWorkspaceConfigFile(filename)) {
-          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`)
-    }
-  }
+  armMode(projects)
 
   // A package added while the loop runs is a directory entry appearing
   // under the glob's directory (`packages/` for `packages/*`); one
@@ -897,7 +1376,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
         const now = memberEntries(base)
         if (sameMembers(members, now)) return
         members = now
-        membersChanged = true
+        reread = true
         trigger(`${path.relative(workspaceRoot, base)}/${filename}`, path.join(base, filename))
       })
     } catch (err) {
@@ -905,6 +1384,8 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
       process.stderr.write(`vx watch: cannot watch ${base}: ${msg}\n`)
     }
   }
+  armPending(false)
+  armImports()
 
   // The orchestrator's own writes never kick the loop: `makeWatchIgnore`
   // closes over the RESOLVED cache dir (relocated or not) and the tasks'
@@ -914,11 +1395,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
   // 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 = async (): Promise<void> => {
@@ -933,6 +1410,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
       // 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)
     }
     if (stop.aborted) {
@@ -943,10 +1421,41 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
   })
 }
 
+/**
+ * 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 {
-    return fs.statSync(abs).mtimeMs < t
+    // 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
   }