@vzn/vx 0.0.651 → 0.0.653

package/src/cli/watch.ts

@@ -16,6 +16,7 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { parseRunArgs, resolveRunOptions, type RunArgs, spacedHint } from './run.js'
 import { refuse, seeHelp } from './help.js'
+import { fsClockNow, namedIgnoredReach, repoFacts } from '../cache/index.js'
 import {
   fingerprintClaims,
   forwardedSignal,
@@ -37,12 +38,13 @@ import {
   isProjectConfigFile,
   isWorkspaceConfigFile,
   gitFiles,
+  lockedExtras,
   makeFence,
   makeRootEventFilter,
   makeWatchIgnore,
   shapesWatchedSet,
 } from './watch-filter.js'
-import { CLOSED, fsClockNow, type WatchHandle, WatcherPool } from './watch-fs.js'
+import { CLOSED, type WatchHandle, WatcherPool } from './watch-fs.js'
 import { ChangeJudge } from './watch-judge.js'
 import { type WatchCycle, watchCycle } from './watch-cycle.js'
 import { hangupIgnored, maskedLine, printable, restartTimings } from '../util/index.js'
@@ -70,6 +72,14 @@ function sayAllCached(opts: RunOptions, outcomes: readonly { status: string }[])
   ui.print('out', ui.line(' ', n === 1 ? '1 task' : `${n} tasks`, ' cached, nothing ran'))
 }
 
+function isDirectory(abs: string): boolean {
+  try {
+    return fs.statSync(abs).isDirectory()
+  } catch {
+    return false
+  }
+}
+
 /** Wait this long after the last filesystem event before re-running. */
 const DEBOUNCE_MS = 150
 /**
@@ -148,6 +158,7 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
     handleSignals: false,
     signal: stop.signal,
     holdPersistent: true,
+    watch: 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
@@ -157,7 +168,10 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   // worth; every cycle after an edit must load and list live.
   delete opts.staged
   delete opts.discovered
-  process.once('SIGINT', () => stop.abort('SIGINT'))
+  // `on`, not `once`: a second signal during the teardown is absorbed (an
+  // abort is once), where `once` left it to Bun's default, exit 130 with
+  // the cycle's children mid-grace.
+  process.on('SIGINT', () => stop.abort('SIGINT'))
   // Said once the loop is down, the last line: written as the signal
   // landed, the aborted cycle's summary printed below it.
   const stopped = (): number => {
@@ -167,11 +181,11 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
     }
     return 0
   }
-  process.once('SIGTERM', () => stop.abort('SIGTERM'))
+  process.on('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 — unless vx
   // was started with it ignored (nohup).
-  if (!hangupIgnored()) process.once('SIGHUP', () => stop.abort('SIGHUP'))
+  if (!hangupIgnored()) process.on('SIGHUP', () => stop.abort('SIGHUP'))
 
   // Enumerate projects-in-scope so we know what dirs to watch: the bare
   // tasks' scope (`opts.projects`; undefined means "every project", or
@@ -223,8 +237,9 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   // ahead of the run to decide which watchers to install, and that marks every
   // config loaded — so the initial run's own loads become REPEATs and pay a
   // worker round-trip each (see config-eval.ts). Trading a hot-path regression
-  // on every `vx watch` for a window a user rarely edits into is a bad deal;
-  // configs.
+  // on every `vx watch` for a window a user rarely edits into is a bad deal.
+  // An edit to the inputs of a task the run was running is caught anyway:
+  // the run leaves that task unsaved, and the loop starts on it (`drifted`).
   // The exception: once the run waits on a server's readiness alone, every
   // config is loaded, and the loop arms with the run as its cycle in
   // flight. Unarmed, a server that never got ready held the initial run
@@ -244,8 +259,11 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   // Uncaught, it ended watch at start while the same break mid-watch did
   // not (item 1017).
   let refusedToStart = false
+  /** A task whose inputs the user edited while the initial run ran it: no watcher heard the edit. */
+  let drifted: string | undefined
   initial.held = runOrchestrator(initial.cycle.opts).then(
     async (run) => {
+      drifted = run.outcomes.find((o) => o.unkeyed === true)?.node.id
       if (run.refused !== undefined) {
         const hint = run.refused.startsWith('no projects declare')
           ? await spacedHint(parsed, cwd)
@@ -288,10 +306,14 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
     sayNotice('error', 'vx watch', 'no projects in scope')
     return 1
   }
-  await armLoop(undefined, held)
+  await armLoop(undefined, held, drifted)
   return stopped()
 
-  async function armLoop(initial?: InitialCycle, held?: HeldPersistent): Promise<void> {
+  async function armLoop(
+    initial?: InitialCycle,
+    held?: HeldPersistent,
+    drifted?: string,
+  ): Promise<void> {
     // `--affected`'s diff is the tree at start; judged again, it held every
     // later edit out of the scope it picked. A cycle is an edit, and the
     // cache keys decide what in the scope it re-runs.
@@ -309,6 +331,7 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
       held,
       initial,
       tasks: openingTasks,
+      drifted,
       stop: stop.signal,
       workspaceRoot,
       projects: watched,
@@ -330,12 +353,18 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
         const all = await discoverCliProjects(workspaceRoot, load)
         const sweep = await sweepConfigs(all, workspaceRoot, load, opts.tasks)
         const now = await watchedProjects(workspaceRoot, all, inScope(all), load, sweep.staged)
+        const wsNow = await loadCliWorkspace(workspaceRoot, quiet)
         return {
           projects: now,
           // A plugin the workspace config gained since claims its file from
           // the cycle that loaded it; read once, its edits started nothing
           // until a restart.
-          claimedRootFiles: claimsOf((await loadCliWorkspace(workspaceRoot, quiet)).plugins),
+          claimedRootFiles: claimsOf(wsNow.plugins),
+          // A re-lock that records a new `file:` directory or patch.
+          extraFiles: lockedExtras(workspaceRoot),
+          // The dir the cycle just wrote its store to: kept from the start,
+          // a `cache.dir` edit let those writes start the next cycle.
+          cacheDir: opts.cacheDir ?? wsNow.cacheDir,
           workspaceWide: sweep.workspaceWide,
           workspaceInputs: sweep.workspaceInputs,
           outputs: sweep.outputs,
@@ -351,6 +380,7 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
       // the one edit that changes what a cycle runs; unheard, the loop ran
       // the old lock until a restart (item 971).
       claimedRootFiles: claimsOf(ws.plugins),
+      extraFiles: lockedExtras(workspaceRoot),
       // The RESOLVED cache dir, not the `.vx` literal — see `makeWatchIgnore`.
       cacheDir: opts.cacheDir ?? ws.cacheDir,
       poll: resolveSetting('watch.poll', ws.workspaceConfig, parsed.poll).value === true,
@@ -375,6 +405,8 @@ interface WatchLoopArgs {
   initial: InitialCycle | undefined
   /** The initial run's task count, once it has started. */
   tasks: () => number | undefined
+  /** A task the initial run left unsaved because its inputs moved under it (`TaskOutcome.unkeyed`). */
+  drifted: string | undefined
   /** Aborted by the SIGINT/SIGTERM handlers `watchCmd` installed; the loop drains its cycle and resolves. */
   stop: AbortSignal
   workspaceRoot: string
@@ -404,6 +436,8 @@ interface WatchLoopArgs {
    * loaded once per process, so the set is fixed for the loop.
    */
   claimedRootFiles: ReadonlySet<string>
+  /** The files a claimed file's recorded digests read besides it (`lockedExtras`), absolute. */
+  extraFiles: ReadonlySet<string>
   /** Every project, in scope or not: a project's key leaves out what lies in one nested under it. */
   fenceDirs: readonly string[]
   /** The watched set again, after a cycle that followed an event which can change it. */
@@ -414,9 +448,20 @@ interface WatchLoopArgs {
 
 const fenceDirs = (all: readonly ProjectMeta[]): string[] => all.map((p) => p.dir)
 
+/** The input globs that name a `node_modules` segment, per directory: what the tree watcher enters. */
+const modulesNamed = (inputs: ReadonlyMap<string, ReadonlyArray<readonly string[]>>): string =>
+  JSON.stringify(
+    [...inputs].map(([dir, tasks]) => [
+      dir,
+      tasks.flat().filter((g) => g.split('/').includes('node_modules')),
+    ]),
+  )
+
 interface Rediscovered {
   projects: readonly ProjectMeta[]
+  cacheDir: string
   claimedRootFiles: ReadonlySet<string>
+  extraFiles: ReadonlySet<string>
   workspaceWide: boolean
   workspaceInputs: readonly string[]
   outputs: ReadonlyMap<string, readonly string[]>
@@ -429,9 +474,10 @@ interface Rediscovered {
 }
 
 async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
-  const { opts, stop, workspaceRoot, projects, cacheDir } = args
+  const { opts, stop, workspaceRoot, projects } = 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 cacheDir = args.cacheDir
   let workspaceWide = args.workspaceWide
   let projectDirs = args.projectDirs
   let workspaceInputs = args.workspaceInputs
@@ -440,6 +486,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
   let uncached = args.uncached
   let namedIgnored = args.namedIgnored
   let claimedRootFiles = args.claimedRootFiles
+  let extraFiles = args.extraFiles
   let configImportFiles = args.configImports
   let wsConfigImportFiles = args.workspaceConfigImports
   // A dev server stays up while the loop idles and across cycles; a cycle
@@ -517,11 +564,12 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
   }
   const trigger = (label: string, abs: string): void => {
     if (!changes.pending.has(abs)) changes.pending.set(abs, label)
+    changes.sawEvent(abs)
     if (running) return interruptIfWaiting()
     if (debounceTimer) {
-      if (Date.now() - windowOpened >= DEBOUNCE_MAX_MS) return
+      if (performance.now() - windowOpened >= DEBOUNCE_MAX_MS) return
       clearTimeout(debounceTimer)
-    } else windowOpened = Date.now()
+    } else windowOpened = performance.now()
     debounceTimer = setTimeout(() => {
       debounceTimer = null
       if (running) return
@@ -539,10 +587,15 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
   const runCycle = async (first: string | undefined, initial?: InitialCycle): Promise<void> => {
     try {
       let label: string | undefined = first
-      let lockAtRun = ''
+      /** The lock this cycle's run read; none for the initial run. */
+      let lockAtRun: string | undefined
       // The initial run is collected even after a stop: its server is the
       // loop's to stop.
       while (initial !== undefined || (label !== undefined && !stop.aborted)) {
+        /** This cycle's failure, as said: a re-read failing on the same cause says nothing more. */
+        let failed: string | undefined
+        /** The judged cycle this run is (`ChangeJudge.cycle`): its window closes when the run ends. */
+        const judged = changes.cycle
         if (initial !== undefined) {
           held = await initial.held
           initial = undefined
@@ -565,6 +618,8 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
                 `no .vx/workspace.ts in ${workspaceRoot}; restore it, or stop vx watch`,
               )
             }
+            // A failed re-read is said once, by the re-read after the
+            // cycle: said here too, it printed above the cycle's header.
             if (reread) await rearm(false)
             ui.print('out', ui.gap())
             ui.say('info', `changed ${label}`, 'out')
@@ -575,9 +630,11 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
             // as a file born and gone since, and ran nothing.
             if (
               atArm !== undefined &&
-              changes.changed.some((p) => path.basename(p) === '.gitignore')
-            )
+              changes.changed.some((p) => path.basename(p) === '.gitignore' || p === excludeFile)
+            ) {
               for (const p of gitFiles(workspaceRoot)?.listed ?? []) atArm.listed.add(p)
+              reachOf = undefined
+            }
             restartTimings()
             // On the mtime clock, as the arm is: from `Date.now()` a write the
             // run made within a tick of it carried an earlier mtime and read as
@@ -588,11 +645,18 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
             // takes it from there. The run stops the others before its graph.
             const before = held
             current = watchCycle(
-              { ...opts, ...(before ? { keep: before } : {}) },
+              {
+                ...opts,
+                ...(before ? { keep: before } : {}),
+                ...(judged ? { commandWindows: judged.windows } : {}),
+              },
               stop,
               interruptIfWaiting,
             )
             const cycle = await runOrchestrator(current.opts)
+            changes.unseen(
+              cycle.outcomes.flatMap((o) => (o.driftedInput === undefined ? [] : [o.driftedInput])),
+            )
             sayAllCached(opts, cycle.outcomes)
             lastTasks = current.tasks ?? lastTasks
             current = undefined
@@ -610,23 +674,30 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
             // FS event (if any) will retry. The dispose() on SIGINT
             // is the canonical exit; we don't unilaterally abort here.
             // A config's own throw or a plugin's failure may quote a secret (L-11).
-            const message = maskedLine(err instanceof Error ? err.message : String(err))
-            sayNotice('error', 'vx watch', `cycle failed: ${message}`)
-          } finally {
-            // A re-lock since this cycle began: the re-arm below can
-            // close the watcher its event was still on its way to (FSEvents'
-            // latency, a poller's tick), and the new lock ran nothing until
-            // the next edit (macOS CI, 2026-10-23). A cycle that read the
-            // lock mid-write failed on it, and is the same case.
-            if (lockStamp() !== lockAtRun) rootFileEvent(LOCKFILE_NAME)
+            failed = err instanceof Error ? err.message : String(err)
+            sayNotice('error', 'vx watch', `cycle failed: ${maskedLine(failed)}`)
           }
+        if (judged !== undefined) judged.to = Math.min(judged.to, Date.now())
         // After a failed cycle too: a package added with a config that does
         // not load yet fails its cycle, and unarmed, the fix to that config
         // was never an event.
         if (reread && !stop.aborted && hasWorkspaceFile()) {
           reread = false
-          await rearm()
+          const err = await rearm()
+          // No lock is the cycle's own failure to say; said here too, it was two lines.
+          const why = err instanceof Error ? err.message : String(err)
+          if (err !== undefined && why !== NO_LOCK && why !== failed)
+            sayCannot(`cannot re-read the workspace`, err)
         }
+        // A re-lock since this cycle began: the re-arm can close the watcher
+        // its event was still on its way to (FSEvents' latency, a poller's
+        // tick), and the new lock ran nothing until the next edit (macOS CI,
+        // 2026-10-23). A cycle that read the lock mid-write failed on it, and
+        // is the same case. Asked after the re-arm, not when the run ends: a
+        // lock written in between was the re-arm's to read, its new pollers
+        // took it as their baseline, and it was never an event (macOS CI,
+        // 2026-11-06).
+        if (lockAtRun !== undefined && lockStamp() !== lockAtRun) rootFileEvent(LOCKFILE_NAME)
         // What landed mid-run is judged on settled state, one window
         // after the run, under the label of what actually arrived.
         current = undefined
@@ -676,15 +747,30 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
   const arm = (dir: string, recursive: boolean, onEvent: (filename: string) => void): WatchHandle =>
     pool.arm(dir, recursive, onEvent)
 
+  // Only the named entries a key reads ignored files under: `src` of
+  // `src/**` over a listed `src` reaches none, and a dev server's ignored
+  // `src/dev.log` started ~3 cycles a second. Reckoned per sweep.
+  let reachOf: readonly string[] | undefined
+  let reach: readonly string[] = []
   /** 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)
   /** Which settled paths are changes (watch-judge.ts); `pending` holds what fired since. */
   const changes = new ChangeJudge({
     workspaceRoot,
     armedAt,
+    clock: () => fsClockNow(cacheDir),
     held: () => held !== undefined,
     uncached: () => uncached,
-    namedIgnored: () => namedIgnored,
+    namedIgnored: () => {
+      if (reachOf !== namedIgnored) {
+        reachOf = namedIgnored
+        reach =
+          atArm === undefined
+            ? namedIgnored
+            : namedIgnoredReach(workspaceRoot, namedIgnored, atArm.listed)
+      }
+      return reach
+    },
     fenced: (ownDir, abs) => fenced(ownDir, abs),
     awaited: (abs) => ancestorNames.get(path.dirname(abs))?.has(path.basename(abs)) === true,
     ...(atArm !== undefined ? { existedAtArm: atArm.listed, trackedAtArm: atArm.tracked } : {}),
@@ -697,6 +783,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
   // went live in 8 ms (tests/watch-one-stream.test.ts). Polling keeps its
   // per-project walks, which skip what lies between projects.
   const oneStream = process.platform === 'darwin' && !args.poll
+  const treeArms = process.platform === 'linux' && !args.poll
   /** The projects the one stream hands events to, by their real directory. */
   let streamed: { proj: ProjectMeta; real: string }[] = []
   const realRoot = ((): string => {
@@ -1034,6 +1121,64 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
     }
   }
 
+  /**
+   * The files a claimed file's recorded digests read besides it (a `file:`
+   * dependency's directory, a patch; `lockedExtras`): a run keys them, and
+   * no project's arm hears one outside its tree. A directory recursively,
+   * a file (or a path gone for now) from its directory; armed again when a
+   * re-lock changes the set.
+   */
+  const extraArms = new Map<string, { at: string; handle: WatchHandle }>()
+  const armExtras = (): void => {
+    const want = new Map<string, { at: string; dir: boolean }>()
+    for (const abs of extraFiles) {
+      const dir = isDirectory(abs)
+      want.set(abs, { at: dir ? abs : path.dirname(abs), dir })
+    }
+    for (const [abs, armed] of extraArms) {
+      if (want.get(abs)?.at === armed.at && !stale(armed.at)) continue
+      armed.handle.close()
+      extraArms.delete(abs)
+    }
+    for (const [abs, { at, dir }] of want) {
+      if (extraArms.has(abs) || inodeOf(at) === undefined) continue
+      const name = path.basename(abs)
+      try {
+        const handle = arm(at, dir, (filename) => {
+          if (!dir && filename !== name) return
+          const changed = dir ? path.join(abs, filename) : abs
+          // A directory made where a file or nothing was armed: armed again, recursively.
+          if (!dir && isDirectory(abs)) reread = true
+          trigger(`root ${path.relative(workspaceRoot, changed)}`, changed)
+        })
+        extraArms.set(abs, { at, handle })
+        armedAs.set(at, inodeOf(at) ?? '')
+      } catch (err) {
+        sayCannot(`cannot watch ${at}`, err)
+      }
+    }
+  }
+  /**
+   * `info/exclude` ignores as a `.gitignore` does, and keys are
+   * gitignore-aware (X-136), so its edit is a cycle; the ignore filter drops
+   * every path under `.git/`. Armed once, from the common dir the run's own
+   * enumeration asked git for (`repoFacts`, memoised).
+   */
+  const commonDir = repoFacts(workspaceRoot)?.commonDir
+  const excludeFile =
+    commonDir === undefined ? undefined : path.resolve(workspaceRoot, commonDir, 'info', 'exclude')
+  const armExclude = (): void => {
+    if (excludeFile === undefined || inodeOf(path.dirname(excludeFile)) === undefined) return
+    try {
+      arm(path.dirname(excludeFile), false, (filename) => {
+        if (filename === 'exclude')
+          trigger(`root ${path.relative(workspaceRoot, excludeFile)}`, excludeFile)
+      })
+    } catch (err) {
+      sayCannot(`cannot watch ${path.dirname(excludeFile)}`, err)
+    }
+  }
+
   // Said once, when the loop first arms: a re-arm repeated it after every
   // cycle that re-read the watched set, between task rows. `debug.watch`
   // says each arm on stderr, for whoever needs to see the set change.
@@ -1052,23 +1197,26 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
       )
   }
 
-  const rearm = async (say = true): Promise<void> => {
+  /** Re-read the workspace and re-arm on it; a failed re-read is returned, for the caller to say. */
+  const rearm = async (say = true): Promise<unknown> => {
     let next: Rediscovered
     try {
       next = await args.rediscover()
     } catch (err) {
-      // No lock is the cycle's own failure to say; said here too, it was two lines.
-      if (!(err instanceof Error && err.message === NO_LOCK))
-        sayCannot(`cannot re-read the workspace`, err)
-      return
+      return err
     }
+    cacheDir = next.cacheDir
     projectDirs = next.projects.map((p) => p.dir)
     workspaceInputs = next.workspaceInputs
     outputs = next.outputs
+    // Linux's tree watcher picks the `node_modules` it enters when it arms
+    // (watch-fs.ts): an input newly named there needs the trees armed again.
+    const modulesRenamed = treeArms && modulesNamed(next.inputs) !== modulesNamed(inputs)
     inputs = next.inputs
     uncached = next.uncached
     namedIgnored = next.namedIgnored
     claimedRootFiles = next.claimedRootFiles
+    extraFiles = next.extraFiles
     configImportFiles = next.configImports
     wsConfigImportFiles = next.workspaceConfigImports
     armAncestors()
@@ -1081,7 +1229,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
       claimedRootFiles,
       fenced,
     )
-    if (next.workspaceWide !== workspaceWide) {
+    if (next.workspaceWide !== workspaceWide || modulesRenamed) {
       // 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.
@@ -1105,10 +1253,12 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
     watched = next.projects
     links = gitFiles(workspaceRoot)?.links ?? links
     armLinks()
+    armExtras()
     // A new arm proves delivery like the first ones: an edit in the new
     // project right after this cycle is seen, not lost in the gap.
     await pool.proved()
     if (say) sayArmed(next.projects.length)
+    return undefined
   }
 
   armMode(projects)
@@ -1190,6 +1340,8 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
   armAncestors()
   armImports()
   armLinks()
+  armExtras()
+  armExclude()
 
   // The orchestrator's own writes never kick the loop: `makeWatchIgnore`
   // closes over the RESOLVED cache dir (relocated or not) and the tasks'
@@ -1208,6 +1360,11 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
   lastTasks = args.tasks()
   sayWatching(projects.length)
   sayArmed(projects.length)
+  // An edit made while the initial run ran landed before any watcher, and
+  // its mtime predates the arm, so no event or judgement can find it: the
+  // run's own re-check did (it left the task unsaved), and that starts the
+  // first cycle. Unheard, watch idled over output built from the old bytes.
+  if (args.drifted !== undefined) void cycle(`${args.drifted} inputs, edited during the first run`)
 
   return await new Promise<void>((resolve) => {
     const cleanup = async (): Promise<void> => {