@vzn/vx 0.0.636 → 0.0.638

package/src/cli/watch.ts

@@ -24,20 +24,12 @@ import {
   type RunOptions,
   shellQuote,
 } from '../orchestrator/index.js'
-import {
-  findWorkspaceRoot,
-  type LoadReads,
-  loadWorkspace,
-  LOCKFILE_NAME,
-  memberBaseDirs,
-  type ProjectMeta,
-} from '../workspace/index.js'
+import { findWorkspaceRoot, LOCKFILE_NAME, NO_LOCK, type ProjectMeta } from '../workspace/index.js'
 import { type CliLoadOptions, discoverCliProjects, loadCliWorkspace } from './workspace-config.js'
+import { resolveSetting } from '../settings.js'
 import {
-  isIgnoredWatchPath,
   isWorkspaceConfigFile,
   gitFiles,
-  isWorkspaceFingerprintFile,
   makeFence,
   makeRootEventFilter,
   makeWatchIgnore,
@@ -46,12 +38,12 @@ import {
 import { CLOSED, fsClockNow, type WatchHandle, WatcherPool } from './watch-fs.js'
 import { ChangeJudge } from './watch-judge.js'
 import { type WatchCycle, watchCycle } from './watch-cycle.js'
-import { hangupIgnored, maskedLine, restartTimings } from '../util/index.js'
-import { memberEntries, sameMembers, sweepConfigs, watchedProjects } from './watch-set.js'
+import { hangupIgnored, maskedLine, restartTimings, sayNotice, sayLine } from '../util/index.js'
+import { sweepConfigs, watchedProjects } from './watch-set.js'
 
 /** One line for a watcher or re-read the OS refused; the loop goes on without it. */
 function sayCannot(what: string, err: unknown): void {
-  process.stderr.write(`vx watch: ${what}: ${err instanceof Error ? err.message : String(err)}\n`)
+  sayNotice('warn', 'vx watch', `${what}: ${err instanceof Error ? err.message : String(err)}`)
 }
 
 /** Wait this long after the last filesystem event before re-running. */
@@ -92,18 +84,20 @@ export function watchRefusal(parsed: RunArgs): string | null {
 export async function watchCmd(args: readonly string[]): Promise<number> {
   const parsed = parseRunArgs(args, 'watch')
   if (parsed.error) {
-    process.stderr.write(`vx watch: ${parsed.error}${seeHelp('watch')}\n`)
+    sayNotice('error', 'vx watch', `${parsed.error}${seeHelp('watch')}`)
     return 1
   }
 
   const refused = watchRefusal(parsed)
   if (refused !== null) {
-    process.stderr.write(`${refused}\n`)
+    sayLine('error', refused, 'vx watch')
     return 1
   }
   if (parsed.tasks.length === 0) {
-    process.stderr.write(
-      `vx watch: missing task name (vx watch <task>, e.g. vx watch build)${seeHelp('watch')}\n`,
+    sayNotice(
+      'error',
+      'vx watch',
+      `missing task name (vx watch <task>, e.g. vx watch build)${seeHelp('watch')}`,
     )
     return 1
   }
@@ -111,11 +105,11 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   const cwd = process.cwd()
   const resolved = await resolveRunOptions(parsed, cwd, parsed.tasks, 'watch')
   if ('error' in resolved) {
-    process.stderr.write(`vx watch: ${resolved.error}\n`)
+    sayNotice('error', 'vx watch', resolved.error)
     return 1
   }
   if ('nothingSelected' in resolved) {
-    process.stderr.write(`vx watch: ${resolved.nothingSelected}\n`)
+    sayNotice('info', 'vx watch', resolved.nothingSelected)
     return 0
   }
   // The watch loop owns SIGINT/SIGTERM for its whole lifetime. A cycle's
@@ -165,13 +159,18 @@ 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 reads: LoadReads = new Map()
-  const workspaceRoot = await findWorkspaceRoot(cwd, reads)
-  const workspace = await loadWorkspace(workspaceRoot, reads)
-  const allProjects = await discoverCliProjects(workspace)
-  // `//#check` is the root project's task, named by its package.json name
-  // as the run names it (prepare.ts, D-39): taken literally, no project
-  // was in scope and the watch exited 1 after a green run.
+  const workspaceRoot = await findWorkspaceRoot(cwd)
+  // No lock yet is no project yet: the first cycle fails saying so, and
+  // the lock `vx lock` writes is the event that arms the set.
+  let unlocked = false
+  const allProjects = await discoverCliProjects(workspaceRoot).catch((err: unknown) => {
+    if (!(err instanceof Error) || err.message !== NO_LOCK) throw err
+    unlocked = true
+    return []
+  })
+  // `//#check` is the root project's task, under the name the run gives
+  // it (prepare.ts, D-39): taken literally, no project was in scope and
+  // the watch exited 1 after a green run.
   const rootDir = path.resolve(workspaceRoot)
   const rootName = allProjects.find((p) => path.resolve(p.dir) === rootDir)?.name
   const anchored = opts.tasks
@@ -202,16 +201,16 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   // 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
   // for good, and the fix to it was never heard (X-139).
-  process.stdout.write('vx watch: initial run...\n\n')
   let loop: Promise<void> | undefined
   const initial: InitialCycle = {
     cycle: watchCycle(opts, stop.signal, () => {
       if (initial.onWaiting !== undefined) initial.onWaiting()
-      else if (loop === undefined && scope.length > 0 && !stop.signal.aborted)
+      else if (loop === undefined && (scope.length > 0 || unlocked) && !stop.signal.aborted)
         loop = armLoop(initial)
     }),
     held: Promise.resolve(undefined),
   }
+  const openingTasks = (): number | undefined => initial.cycle.tasks
   // A run that throws (a config that does not parse) is a failed cycle, as
   // it is once the loop runs: watch keeps watching, so the fix re-runs.
   // Uncaught, it ended watch at start while the same break mid-watch did
@@ -219,7 +218,7 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   let refusedToStart = false
   initial.held = runOrchestrator(initial.cycle.opts).then(
     (run) => {
-      if (run.refused !== undefined) process.stderr.write(`vx watch: ${run.refused}\n`)
+      if (run.refused !== undefined) sayNotice('error', 'vx watch', run.refused)
       // A run that failed having run nothing refused to start: a requested
       // name no project declares (run() says which, with a "did you mean").
       // `vx run` exits 1 on it; `vx watch buidl` watched on, re-running the
@@ -230,8 +229,10 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
       return run.persistent
     },
     (err: unknown) => {
-      process.stderr.write(
-        `vx watch: cycle failed: ${err instanceof Error ? err.message : String(err)}\n`,
+      sayNotice(
+        'error',
+        'vx watch',
+        `cycle failed: ${err instanceof Error ? err.message : String(err)}`,
       )
       return undefined
     },
@@ -248,9 +249,9 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   if (refusedToStart) return 1
   // After the initial run, so a `pkg#task` naming no project gets the
   // run's own refusal and its "did you mean".
-  if (scope.length === 0) {
+  if (scope.length === 0 && !unlocked) {
     await held?.stop()
-    process.stderr.write(`vx watch: no projects in scope\n`)
+    sayNotice('error', 'vx watch', 'no projects in scope')
     return 1
   }
   await armLoop(undefined, held)
@@ -263,22 +264,17 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
     delete opts.affected
     delete opts.selectedOutright
 
-    const load: CliLoadOptions = {
-      ...(opts.cacheDir !== undefined ? { cacheDir: opts.cacheDir } : {}),
-      ...(opts.frozen === true ? { frozen: true } : {}),
-    }
+    const load: CliLoadOptions = opts.cacheDir !== undefined ? { cacheDir: opts.cacheDir } : {}
     const swept = await sweepConfigs(allProjects, workspaceRoot, load, opts.tasks)
     const watched = await watchedProjects(workspaceRoot, allProjects, scope, load, swept.staged)
     const ws = await loadCliWorkspace(workspaceRoot)
     const claimsOf = (plugins: Parameters<typeof fingerprintClaims>[0]): Set<string> =>
-      new Set([
-        ...fingerprintClaims(plugins).keys(),
-        ...(opts.frozen === true ? [LOCKFILE_NAME] : []),
-      ])
+      new Set([...fingerprintClaims(plugins).keys(), LOCKFILE_NAME])
     await runWatchLoop({
       opts,
       held,
       initial,
+      tasks: openingTasks,
       stop: stop.signal,
       workspaceRoot,
       projects: watched,
@@ -290,16 +286,13 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
       uncached: swept.uncached,
       configImports: swept.configImports,
       workspaceConfigImports: swept.workspaceConfigImports,
-      memberBases: memberBaseDirs(workspace),
-      packageDirs: new Set(allProjects.map((p) => p.dir)),
       fenceDirs: fenceDirs(allProjects),
-      // 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.
+      // The workspace as the cycle that just ran saw it: a project the lock
+      // gained or lost since the loop armed joins or leaves the watched
+      // set. The scope is the one resolved at start; a new project joins
+      // it only as a dependency of it.
       rediscover: async () => {
-        const workspace = await loadWorkspace(workspaceRoot)
-        const all = await discoverCliProjects(workspace)
+        const all = await discoverCliProjects(workspaceRoot)
         const sweep = await sweepConfigs(all, workspaceRoot, load, opts.tasks)
         const now = await watchedProjects(workspaceRoot, all, inScope(all), load, sweep.staged)
         return {
@@ -308,7 +301,6 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
           // the cycle that loaded it; read once, its edits started nothing
           // until a restart.
           claimedRootFiles: claimsOf((await loadCliWorkspace(workspaceRoot)).plugins),
-          memberBases: memberBaseDirs(workspace),
           workspaceWide: sweep.workspaceWide,
           workspaceInputs: sweep.workspaceInputs,
           outputs: sweep.outputs,
@@ -316,16 +308,16 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
           uncached: sweep.uncached,
           configImports: sweep.configImports,
           workspaceConfigImports: sweep.workspaceConfigImports,
-          packageDirs: new Set(all.map((p) => p.dir)),
           fenceDirs: fenceDirs(all),
         }
       },
-      // Under --frozen every cycle's configs are the lock's, so a re-lock is
+      // 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: claimsOf(ws.plugins),
       // 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,
     })
   }
 }
@@ -345,6 +337,8 @@ interface WatchLoopArgs {
   held: HeldPersistent | undefined
   /** The initial run, still in flight: the loop's first cycle. */
   initial: InitialCycle | undefined
+  /** The initial run's task count, once it has started. */
+  tasks: () => number | undefined
   /** Aborted by the SIGINT/SIGTERM handlers `watchCmd` installed; the loop drains its cycle and resolves. */
   stop: AbortSignal
   workspaceRoot: string
@@ -372,14 +366,12 @@ interface WatchLoopArgs {
    * loaded once per process, so the set is fixed for the loop.
    */
   claimedRootFiles: ReadonlySet<string>
-  /** The directory each `<dir>/*` package glob names at start; 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>
   /** 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. */
   rediscover: () => Promise<Rediscovered>
+  /** `watch.poll`: poll from the start instead of the OS watcher. */
+  poll: boolean
 }
 
 const fenceDirs = (all: readonly ProjectMeta[]): string[] => all.map((p) => p.dir)
@@ -387,7 +379,6 @@ const fenceDirs = (all: readonly ProjectMeta[]): string[] => all.map((p) => p.di
 interface Rediscovered {
   projects: readonly ProjectMeta[]
   claimedRootFiles: ReadonlySet<string>
-  memberBases: readonly string[]
   workspaceWide: boolean
   workspaceInputs: readonly string[]
   outputs: ReadonlyMap<string, readonly string[]>
@@ -395,7 +386,6 @@ interface Rediscovered {
   uncached: ReadonlySet<string>
   configImports: readonly string[]
   workspaceConfigImports: readonly string[]
-  packageDirs: ReadonlySet<string>
   fenceDirs: readonly string[]
 }
 
@@ -404,8 +394,6 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
   // 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 memberBases = args.memberBases
   let projectDirs = args.projectDirs
   let workspaceInputs = args.workspaceInputs
   let outputs = args.outputs
@@ -485,7 +473,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
             // only after, it fell in the gap and ran nothing (X-138). The re-read
             // after the run stays, for what the run itself changed.
             if (reread) await rearm(false)
-            process.stdout.write(`\nvx watch: ${label}; re-running...\n\n`)
+            process.stdout.write(`\nchanged ${label}\n`)
             if (stop.aborted) break
             restartTimings()
             // On the mtime clock, as the arm is: from `Date.now()` a write the
@@ -502,11 +490,12 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
               interruptIfWaiting,
             )
             const cycle = await runOrchestrator(current.opts)
+            lastTasks = current.tasks ?? lastTasks
             current = undefined
             held = cycle.persistent
             // What this cycle did not take (a server whose task did not run).
             await before?.stop()
-            if (cycle.refused !== undefined) process.stderr.write(`vx watch: ${cycle.refused}\n`)
+            if (cycle.refused !== undefined) sayNotice('error', 'vx watch', cycle.refused)
             changes.lastCycle = { start, end: Date.now() }
           } catch (err) {
             // A re-run can fail catastrophically when the workspace
@@ -518,7 +507,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
             // 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))
-            process.stderr.write(`vx watch: cycle failed: ${message}\n`)
+            sayNotice('error', 'vx watch', `cycle failed: ${message}`)
           }
         // 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
@@ -553,7 +542,9 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
   // 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, inputs)
+  /** What existed and was tracked at the arm, so a file born and gone since is no deletion and a tracked one is the user's edit (watch-judge.ts). */
+  const atArm = gitFiles(workspaceRoot)
+  let isIgnoredPath = makeWatchIgnore(cacheDir, outputs, inputs, atArm?.tracked)
   let fenced = makeFence(args.fenceDirs)
   let matters = makeRootEventFilter(
     workspaceRoot,
@@ -569,14 +560,12 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
   // 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 pool = new WatcherPool((dir, rel) => isIgnoredPath(dir, rel))
+  const pool = new WatcherPool((dir, rel) => isIgnoredPath(dir, rel), args.poll)
   const arm = (dir: string, recursive: boolean, onEvent: (filename: string) => void): WatchHandle =>
     pool.arm(dir, recursive, onEvent)
 
   /** 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)
-  /** What existed and was tracked at the arm, so a file born and gone since is no deletion and a tracked one is the user's edit (watch-judge.ts). */
-  const atArm = gitFiles(workspaceRoot)
   /** Which settled paths are changes (watch-judge.ts); `pending` holds what fired since. */
   const changes = new ChangeJudge({
     workspaceRoot,
@@ -588,6 +577,38 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
   })
   /** Per-project arms by directory, so `rearm` can add and drop them. */
   const perProject = new Map<string, WatchHandle>()
+  // Each FSEvents stream goes live slower than the one before it: per
+  // project, 751 of 3000 missed their 2 s proof on a macos-latest runner
+  // and fell back to polling, a full core at idle; one stream at the root
+  // 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
+  /** The projects the one stream hands events to, by their real directory. */
+  let streamed: { proj: ProjectMeta; real: string }[] = []
+  const realRoot = ((): string => {
+    try {
+      return fs.realpathSync(workspaceRoot)
+    } catch {
+      return path.resolve(workspaceRoot)
+    }
+  })()
+  // The stream names a file by its real place under the root, so a project
+  // whose real directory lies outside the root keeps its own arm.
+  const toStream = (all: readonly ProjectMeta[]): { proj: ProjectMeta; real: string }[] => {
+    const out: { proj: ProjectMeta; real: string }[] = []
+    for (const proj of all) {
+      let real: string
+      try {
+        real = fs.realpathSync(proj.dir)
+      } catch {
+        continue
+      }
+      const rel = path.relative(realRoot, real)
+      if (rel.startsWith('..') || path.isAbsolute(rel)) continue
+      out.push({ proj, real })
+    }
+    return out
+  }
   // An OS watch holds the directory's inode, not its path: one removed and
   // made again (`rm -rf packages && git checkout packages`) keeps reporting
   // for the deleted one. Each arm notes the directory it holds, and a
@@ -605,32 +626,68 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
     }
   }
   const stale = (dir: string): boolean => armedAs.get(dir) !== inodeOf(dir)
-  /** The root arm: recursive when workspace-wide, else the root's own files only. */
+  /** The root arm: recursive when workspace-wide or the one stream, else the root's own files only. */
   let rootArm: WatchHandle = CLOSED
+  let dotVxArm: WatchHandle = CLOSED
+  const projectEvent = (proj: ProjectMeta, filename: string): void => {
+    const abs = path.join(proj.dir, filename)
+    if (isIgnoredPath(proj.dir, filename) || fenced(proj.dir, abs)) return
+    // A module the config imports from inside the project is the config
+    // too: its edit can add an output or a `workspaceFiles` input.
+    if (shapesWatchedSet(filename) || configImportFiles.includes(abs)) reread = true
+    trigger(`${proj.name} ${filename}`, abs)
+  }
   const armProject = (proj: ProjectMeta): void => {
+    // Gone for now: its ancestor's arm (`armAncestors`) hears it return.
+    if (inodeOf(proj.dir) === undefined) return
     try {
-      const handle = arm(proj.dir, true, (filename) => {
-        const abs = path.join(proj.dir, filename)
-        if (isIgnoredPath(proj.dir, filename) || fenced(proj.dir, abs)) return
-        // A module the config imports from inside the project is the config
-        // too: its edit can add an output or a `workspaceFiles` input.
-        if (shapesWatchedSet(filename) || configImportFiles.includes(abs)) reread = true
-        trigger(`${proj.name} ${filename}`, abs)
-      })
+      const handle = arm(proj.dir, true, (filename) => projectEvent(proj, filename))
       perProject.set(proj.dir, handle)
       armedAs.set(proj.dir, inodeOf(proj.dir) ?? '')
     } catch (err) {
       sayCannot(`cannot watch ${proj.dir}`, err)
     }
   }
+  const rootFileEvent = (filename: string): void => {
+    if (
+      !isWorkspaceConfigFile(filename) &&
+      filename !== '.gitignore' &&
+      !claimedRootFiles.has(filename)
+    )
+      return
+    if (shapesWatchedSet(filename) || filename === LOCKFILE_NAME || claimedRootFiles.has(filename))
+      reread = true
+    trigger(`root ${filename}`, path.join(workspaceRoot, filename))
+  }
+  const dotVxEvent = (filename: string): void => {
+    const rel = `.vx/${filename}`
+    if (!isWorkspaceConfigFile(rel) && !claimedRootFiles.has(rel)) return
+    reread = true
+    trigger(`root ${rel}`, path.join(workspaceRoot, rel))
+  }
+  /**
+   * The one stream's events, handed out as the per-project arms, the
+   * root's own files and `.vx/` would have heard them: an event lies in
+   * every watched project whose tree holds it (a nested one's fence drops
+   * it from the outer), so each listener decides exactly as its own arm did.
+   */
+  const streamEvent = (filename: string): void => {
+    const rel = filename.split(path.sep).join('/')
+    if (!rel.includes('/')) rootFileEvent(rel)
+    else if (rel.startsWith('.vx/') && rel.indexOf('/', 4) < 0) dotVxEvent(rel.slice(4))
+    const abs = path.join(realRoot, filename)
+    for (const { proj, real } of streamed) {
+      if (abs.startsWith(real + path.sep)) projectEvent(proj, path.relative(real, abs))
+    }
+  }
   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
+          // per-project ones (it also covers claimed root files).
+          // `matters` keeps the events a key can see —
+          // project trees, claimed root 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) => {
@@ -639,88 +696,50 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
             if (
               shapesWatchedSet(filename) ||
               filename === LOCKFILE_NAME ||
+              claimedRootFiles.has(filename) ||
               configImportFiles.includes(abs)
             )
               reread = true
             trigger(`root ${filename}`, abs)
           })
-        : // 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) ||
-              filename === 'package.json' ||
-              filename === '.gitignore' ||
-              claimedRootFiles.has(filename)
-            ) {
-              if (shapesWatchedSet(filename) || filename === LOCKFILE_NAME) reread = true
-              trigger(`root ${filename}`, path.join(workspaceRoot, filename))
-            }
-          })
+        : oneStream
+          ? arm(workspaceRoot, true, streamEvent)
+          : // The root itself, non-recursive, beside the per-project arms, so
+            // claimed root files (a lockfile) trigger re-runs even when no
+            // project dir saw the change.
+            arm(workspaceRoot, false, rootFileEvent)
     } catch (err) {
       sayCannot(`cannot watch workspace root`, err)
     }
+    // The workspace config and the lock sit in `.vx/`, which the root's
+    // non-recursive arm does not see into.
+    if (workspaceWide || oneStream) return
+    try {
+      dotVxArm = arm(path.join(workspaceRoot, '.vx'), false, dotVxEvent)
+    } catch (err) {
+      sayCannot(`cannot watch ${path.join(workspaceRoot, '.vx')}`, err)
+    }
   }
   // 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).
+  // (it would cover every project + node_modules + caches). On macOS one
+  // recursive stream at the root stands for all of them (`oneStream`).
   const armMode = (watched: readonly ProjectMeta[]): void => {
-    if (!workspaceWide) for (const proj of watched) armProject(proj)
+    if (!workspaceWide) {
+      streamed = oneStream ? toStream(watched) : []
+      const inStream = new Set(streamed.map((s) => s.proj))
+      for (const proj of watched) if (!inStream.has(proj)) armProject(proj)
+    }
     armRoot()
   }
   const dropMode = (): void => {
+    streamed = []
     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) && !stale(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()
-          }),
-        )
-        armedAs.set(dir, inodeOf(dir) ?? '')
-      } catch (err) {
-        sayCannot(`cannot watch ${dir}`, err)
-        continue
-      }
-      if (afterReread && fs.existsSync(manifest)) arrived()
-    }
+    dotVxArm.close()
+    dotVxArm = CLOSED
   }
 
   /**
@@ -782,10 +801,19 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
     armAncestors()
   }
 
-  const watchingLine = (count: number): string =>
-    workspaceWide
-      ? 'vx watch: watching the workspace root (workspaceFiles inputs in use)'
-      : `vx watch: watching ${count} project(s)`
+  // 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.
+  let lastTasks: number | undefined
+  const plural = (n: number, noun: string): string => `${n} ${noun}${n === 1 ? '' : 's'}`
+  const sayWatching = (count: number): void => {
+    const tasks = lastTasks === undefined ? '' : ` · ${plural(lastTasks, 'task')}`
+    process.stdout.write(`watching ${plural(count, 'project')}${tasks}\n`)
+  }
+  const debugArms = resolveSetting('debug.watch', undefined).value === true
+  const sayArmed = (count: number): void => {
+    if (debugArms) process.stderr.write(`vx watch: armed ${plural(count, 'project')}\n`)
+  }
 
   const rearm = async (say = true): Promise<void> => {
     let next: Rediscovered
@@ -803,10 +831,8 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
     claimedRootFiles = next.claimedRootFiles
     configImportFiles = next.configImports
     wsConfigImportFiles = next.workspaceConfigImports
-    packageDirs = next.packageDirs
-    memberBases = next.memberBases
-    armBases()
-    isIgnoredPath = makeWatchIgnore(cacheDir, outputs, inputs)
+    armAncestors()
+    isIgnoredPath = makeWatchIgnore(cacheDir, outputs, inputs, atArm?.tracked)
     fenced = makeFence(next.fenceDirs)
     matters = makeRootEventFilter(
       workspaceRoot,
@@ -823,53 +849,68 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
       workspaceWide = next.workspaceWide
       armMode(next.projects)
     } else if (!workspaceWide) {
-      const keep = new Set(projectDirs)
+      streamed = oneStream ? toStream(next.projects) : []
+      const inStream = new Set(streamed.map((s) => s.proj))
+      const own = next.projects.filter((p) => !inStream.has(p))
+      const keep = new Set(own.map((p) => p.dir))
       for (const [dir, handle] of perProject) {
         if (keep.has(dir) && !stale(dir)) continue
         handle.close()
         perProject.delete(dir)
       }
-      for (const proj of next.projects) if (!perProject.has(proj.dir)) armProject(proj)
+      for (const proj of own) 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.
+    // project right after this cycle is seen, not lost in the gap.
     await pool.proved()
-    if (say) process.stdout.write(`${watchingLine(next.projects.length)}\n`)
+    if (say) sayArmed(next.projects.length)
   }
 
   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. The bases themselves are
-  // re-read with the set: a glob added to the list watched nothing new
-  // until a restart (item 1018).
-  const baseArms = new Map<string, WatchHandle>()
-  // A base removed and made again is no event to its own watch (it holds
-  // the deleted directory) nor to the root arm, which drops every name but
-  // its own files: `watching 0 project(s)` and silence until a restart. So
-  // each base, and each directory a config imports from, is watched from
-  // its nearest directory that exists, for the next name on the way down:
-  // its parent while it is there, an ancestor when the parent went too
-  // (`apps/` removed under `apps/web/*`).
+  // A project directory, or one a config imports from, removed and made
+  // again (`rm -rf packages && git checkout packages`) is no event to its
+  // own watch (it holds the deleted directory) nor to the root arm, which
+  // drops every name but its own files: silence until a restart. So each
+  // is watched from its nearest directory that exists, for the next name
+  // on the way down: its parent while it is there, an ancestor when the
+  // parent went too (`apps/` removed under `apps/web/site`). Every
+  // directory above it up to the root is watched for the next name too:
+  // FSEvents reports nothing for a watched directory's children when the
+  // directory itself goes with them, so on macOS the parent's arm alone
+  // never heard `packages/` removed under `packages/a` (inotify did).
   const ancestorArms = new Map<string, WatchHandle>()
   let ancestorNames = new Map<string, Set<string>>()
+  /** Each project directory below the root as these arms first saw it (`inodeOf`). */
+  let heldDirs = new Map<string, string>()
   const armAncestors = (): void => {
     ancestorNames = new Map()
-    for (const base of [...memberBases, ...importNames.keys()]) {
+    const rootDir = path.resolve(workspaceRoot)
+    const below = projectDirs.filter((d) => path.resolve(d) !== rootDir)
+    heldDirs = new Map(
+      below.flatMap((d) => {
+        const id = inodeOf(d)
+        return id === undefined ? [] : [[d, id]]
+      }),
+    )
+    for (const base of [...below, ...importNames.keys()]) {
       let dir = path.dirname(base)
       let name = path.basename(base)
       while (inodeOf(dir) === undefined && dir !== workspaceRoot && dir !== path.dirname(dir)) {
         name = path.basename(dir)
         dir = path.dirname(dir)
       }
-      ancestorNames.set(dir, (ancestorNames.get(dir) ?? new Set()).add(name))
+      for (;;) {
+        const names = ancestorNames.get(dir) ?? new Set<string>()
+        // A directory already holding this name was climbed from here before.
+        const climbed = names.has(name)
+        ancestorNames.set(dir, names.add(name))
+        // Outside the root (a preset a config imports from `../`) only the nearest arm.
+        if (climbed || !dir.startsWith(workspaceRoot + path.sep)) break
+        name = path.basename(dir)
+        dir = path.dirname(dir)
+      }
     }
     for (const [dir, handle] of ancestorArms) {
       if (ancestorNames.has(dir) && !stale(dir)) continue
@@ -882,9 +923,15 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
         ancestorArms.set(
           dir,
           arm(dir, false, (filename) => {
-            if (!ancestorNames.get(dir)?.has(filename)) return
-            reread = true
+            // A project's parent's `.gitignore` shapes what its keys read, as the root's does.
+            if (!ancestorNames.get(dir)?.has(filename) && filename !== '.gitignore') return
             const abs = path.join(dir, filename)
+            // A project directory still the one its arm holds is no change:
+            // its arm judges what is in it. macOS reports the directory's
+            // mtime here on every write at its top level, and a cycle's own
+            // write started the next (solid's `types`, M 2026-10-15).
+            if (heldDirs.get(abs) === (inodeOf(abs) ?? '')) return
+            reread = true
             trigger(path.relative(workspaceRoot, abs), abs)
           }),
         )
@@ -894,59 +941,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
       }
     }
   }
-  const armBases = (): void => {
-    armAncestors()
-    const want = new Set(memberBases)
-    for (const [base, handle] of baseArms) {
-      if (want.has(base) && !stale(base)) continue
-      handle.close()
-      baseArms.delete(base)
-    }
-    for (const base of want) {
-      if (baseArms.has(base)) continue
-      // Gone for now: its parent's arm hears it come back.
-      if (inodeOf(base) === undefined) continue
-      let members = memberEntries(base)
-      try {
-        baseArms.set(
-          base,
-          arm(base, false, (filename) => {
-            if (isIgnoredWatchPath(filename)) return
-            // Inputs are gitignore-aware: an edit here changes what the
-            // members' keys read, and `vx run` would miss on it.
-            if (filename === '.gitignore') {
-              trigger(
-                path.relative(workspaceRoot, path.join(base, filename)),
-                path.join(base, 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)
-            // The same names, but a directory still without a package made
-            // again (or replaced by a rename): its pending watch holds the
-            // deleted one, and the `package.json` that lands next is heard
-            // only by a new arm.
-            const entry = path.join(base, filename)
-            if (sameMembers(members, now) && !(pending.has(entry) && stale(entry))) return
-            members = now
-            reread = true
-            trigger(`${path.relative(workspaceRoot, base)}/${filename}`, path.join(base, filename))
-          }),
-        )
-        armedAs.set(base, inodeOf(base) ?? '')
-      } catch (err) {
-        sayCannot(`cannot watch ${base}`, err)
-      }
-    }
-  }
-  armBases()
-  armPending(false)
+  armAncestors()
   armImports()
 
   // The orchestrator's own writes never kick the loop: `makeWatchIgnore`
@@ -963,7 +958,9 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
     interruptIfWaiting()
   }
 
-  process.stdout.write(`\n${watchingLine(projects.length)}; press Ctrl+C to stop\n`)
+  lastTasks = args.tasks()
+  sayWatching(projects.length)
+  sayArmed(projects.length)
 
   return await new Promise<void>((resolve) => {
     const cleanup = async (): Promise<void> => {