@vzn/vx 0.0.594 → 0.0.596

package/src/cli/select.ts

@@ -12,6 +12,7 @@ import {
   refIsHead,
   applyFilters,
   buildPackageGraph,
+  defaultAffectedBase,
   findWorkspaceRoot,
   type LoadReads,
   type FingerprintClaims,
@@ -26,7 +27,7 @@ import type { ProjectConfig } from '../config.js'
 import type { ProjectEntry } from '../workspace/index.js'
 import { parseDependencySpec } from '../graph/index.js'
 import { declaresInput } from '../cache/index.js'
-import { listed, maskedLine, nearest, UserError } from '../util/index.js'
+import { isUserError, listed, maskedLine, nearest, UserError } from '../util/index.js'
 import {
   claimedAffected,
   fingerprintClaims,
@@ -228,6 +229,30 @@ export function taskEdgesFrom(staged: ReadonlyMap<string, ProjectEntry>): Map<st
   return out
 }
 
+/**
+ * The filter `--affected[=<base>]` stands for: `...[<base>]`, the changed
+ * projects and their dependents. An empty base is the workspace's
+ * `affectedBase` (or a plugin's `config` stage, from nx.json's
+ * `defaultBase` or `TURBO_SCM_BASE`), then the guess.
+ */
+export async function affectedFilterFor(
+  cwd: string,
+  affected: string,
+): Promise<string | { error: string }> {
+  const root = await findWorkspaceRoot(cwd)
+  let base = affected
+  if (base === '') base = (await loadCliWorkspace(root)).workspaceConfig?.affectedBase ?? ''
+  if (base === '') {
+    try {
+      base = await defaultAffectedBase(root)
+    } catch (err) {
+      if (!isUserError(err)) throw err
+      return { error: err.message }
+    }
+  }
+  return `...[${base}]`
+}
+
 export async function resolveFilters(
   cwd: string,
   raw: string[],
@@ -471,7 +496,9 @@ export async function pickTask(
     )
     return null
   }
-  const out = io.output ?? process.stdout
+  // The menu is a conversation with the terminal, not the run's output: on
+  // stdout, `vx run > out.txt` put it in the file and asked a blank screen.
+  const out = io.output ?? process.stderr
   const numW = String(entries.length).length
   const idW = Math.max(...entries.map((e) => `${e.project}#${e.task}`.length))
   out.write('Tasks:\n')
@@ -486,7 +513,7 @@ export async function pickTask(
   const readline = await import('node:readline/promises')
   const rl = readline.createInterface({
     input: io.input ?? process.stdin,
-    output: io.output ?? process.stdout,
+    output: out,
   })
   // On a terminal readline takes Ctrl-C and Ctrl-D itself, raw, and
   // rejects the pending question with an AbortError — which reached the

package/src/cli/show.ts

@@ -12,6 +12,7 @@ import { declaredTask } from '../graph/index.js'
 import { isDefaultBuild } from '../orchestrator/index.js'
 import { flagHint, formatValue, seeHelp } from './help.js'
 import { listed, nearMatches, relPosix, secretMask, UserError } from '../util/index.js'
+import { affectedFilterFor, resolveFilters } from './select.js'
 import { discoverCliProjects, loadCliProjects } from './workspace-config.js'
 import {
   findWorkspaceRoot,
@@ -24,16 +25,27 @@ import {
 interface ShowArgs {
   target?: string
   format: 'pretty' | 'json'
+  /** `--filter`, as `vx run` reads it: which projects the list shows. */
+  filters: string[]
+  /** `--affected[=<base>]`: `''` is the default base. */
+  affected?: string
   error?: string
 }
 
 export function parseShowArgs(args: readonly string[]): ShowArgs {
-  const out: ShowArgs = { format: 'pretty' }
+  const out: ShowArgs = { format: 'pretty', filters: [] }
   for (let i = 0; i < args.length; i++) {
     const a = args[i]!
     let format: string | undefined
     if (a === '--format') format = args[++i] ?? ''
     else if (a.startsWith('--format=')) format = a.slice('--format='.length)
+    else if (a === '--filter') {
+      const v = args[++i]
+      if (v === undefined) return { ...out, error: '--filter requires a value (a pattern)' }
+      out.filters.push(v)
+    } else if (a.startsWith('--filter=')) out.filters.push(a.slice('--filter='.length))
+    else if (a === '--affected') out.affected = ''
+    else if (a.startsWith('--affected=')) out.affected = a.slice('--affected='.length)
     else if (a.startsWith('-'))
       return { ...out, error: `unknown flag: ${a}${flagHint('show', a)}${seeHelp('show')}` }
     else if (out.target === 'project')
@@ -103,10 +115,35 @@ export async function showCmd(args: readonly string[]): Promise<number> {
   const bareTask = projectName !== undefined && taskName === undefined && !byName.has(projectName)
   const scope = projectName === undefined || bareTask ? 'all' : [projectName]
 
+  // `turbo ls --filter` / `nx show projects --affected`: the list, and a
+  // task's projects, narrowed by the selection `vx run` would make.
+  let selected: Set<string> | undefined
+  if (parsed.filters.length > 0 || parsed.affected !== undefined) {
+    if (scope !== 'all') {
+      throw new UserError(
+        'vx show: --filter and --affected narrow a list: `vx show` or `vx show <task>`',
+      )
+    }
+    const raw = [...parsed.filters]
+    let affected: string | undefined
+    if (parsed.affected !== undefined) {
+      const f = await affectedFilterFor(process.cwd(), parsed.affected)
+      if (typeof f === 'object') throw new UserError(`vx show: ${f.error}`)
+      affected = f
+      raw.unshift(f)
+    }
+    const r = await resolveFilters(process.cwd(), raw, { noCreate: true }, affected)
+    if ('error' in r) throw new UserError(`vx show: ${r.error}`)
+    if ('empty' in r) process.stderr.write(`vx show: ${r.empty}\n`)
+    selected = new Set('empty' in r ? [] : r.names)
+  }
+  const inSelection = (name: string): boolean => selected === undefined || selected.has(name)
+
   const projects = await loadCliProjects(root, metas, scope, { noCreate: true, closure: true })
 
   if (parsed.target === undefined) {
-    process.stdout.write(renderList(root, metas, projects, parsed.format))
+    const shown = metas.filter((m) => inSelection(m.name))
+    process.stdout.write(renderList(root, shown, projects, parsed.format))
     return 0
   }
 
@@ -124,7 +161,8 @@ export async function showCmd(args: readonly string[]): Promise<number> {
         `vx show: unknown project or task: "${projectName}"${nx}${suggest(projectName!, [...byName.keys(), ...names], '', 'projects and tasks')}`,
       )
     }
-    process.stdout.write(renderTaskAcross(root, declaring, projectName!, parsed.format))
+    const shown = declaring.filter((p) => inSelection(p.name))
+    process.stdout.write(renderTaskAcross(root, shown, projectName!, parsed.format))
     return 0
   }
 
@@ -239,6 +277,7 @@ function renderList(
       2,
     )}\n`
   }
+  if (rows.length === 0) return ''
   const nameW = Math.max(...rows.map((r) => r.name.length))
   const dirW = Math.max(...rows.map((r) => r.dir.length))
   const lines = rows.map((r) => {

package/src/cli/watch-filter.ts

@@ -8,6 +8,7 @@ import {
   isLiteralPattern,
   normalizeGlob,
   outputMatcher,
+  realPath,
   staticPrefix,
   taskGlob,
 } from '../util/index.js'
@@ -54,7 +55,9 @@ export function makeWatchIgnore(
   outputs: ReadonlyMap<string, readonly string[]> = new Map(),
   inputs: ReadonlyMap<string, ReadonlyArray<readonly string[]>> = new Map(),
 ): (base: string, filename: string) => boolean {
-  const cacheAbs = path.resolve(cacheDir)
+  // Watchers report under the real root; a cache dir named through a link
+  // (`VX_CACHE_DIR`, macOS `/var` -> `/private/var`) is matched as its target.
+  const cacheAbs = realThrough(path.resolve(cacheDir))
   // A task's own outputs are not edits: without this every cycle that
   // writes `dist/` (or `out.txt`) re-runs once more, reporting
   // "up-to-date" for the trouble. Matched under the directory the globs
@@ -132,6 +135,16 @@ export function makeWatchIgnore(
   }
 }
 
+/** `p` with its longest existing prefix realpath'd: the cache dir may not exist yet. */
+function realThrough(p: string): string {
+  try {
+    return realPath(p)
+  } catch {
+    const up = path.dirname(p)
+    return up === p ? p : path.join(realThrough(up), path.basename(p))
+  }
+}
+
 /**
  * The literal directory a glob's matches live under (`''` when the glob
  * starts with a pattern, or negates). A literal entry is a file or its
@@ -166,9 +179,14 @@ export function gitIgnored(workspaceRoot: string, paths: readonly string[]): Set
   // ignored let a pid file in the same window start cycles again. The
   // refused path is skipped and the rest asked again; a refusal before
   // any record outside a work tree is git refusing them all.
-  let rest = paths
+  // Git refuses a path beyond a symbolic link: its ignored pid file read
+  // as an edit and an uncached task re-ran forever. Asked at its real
+  // place, answered as given.
+  const real = paths.map(gitSpeller(workspaceRoot))
+  let from = 0
   let inWorkTree: boolean | undefined
-  while (rest.length > 0) {
+  while (from < paths.length) {
+    const rest = real.slice(from)
     let proc: ReturnType<typeof Bun.spawnSync>
     try {
       proc = Bun.spawnSync({
@@ -188,8 +206,8 @@ export function gitIgnored(workspaceRoot: string, paths: readonly string[]): Set
     const fields = new TextDecoder('utf-8', { ignoreBOM: true }).decode(proc.stdout).split('\0')
     const records = Math.floor(fields.length / 4)
     for (let i = 0; i < records; i++) {
-      const [source, , pattern, p] = fields.slice(i * 4, i * 4 + 4)
-      if (source !== '' && !pattern!.startsWith('!')) ignored.add(p!)
+      const [source, , pattern] = fields.slice(i * 4, i * 4 + 4)
+      if (source !== '' && !pattern!.startsWith('!')) ignored.add(paths[from + i]!)
     }
     // 0: some ignored; 1: none. Anything else is git refusing.
     if (proc.exitCode === 0 || proc.exitCode === 1) return ignored
@@ -203,7 +221,7 @@ export function gitIgnored(workspaceRoot: string, paths: readonly string[]): Set
         }).exitCode === 0
       if (!inWorkTree) return ignored
     }
-    rest = rest.slice(records + 1)
+    from += records + 1
   }
   return ignored
 }
@@ -338,19 +356,59 @@ export function isWorkspaceConfigFile(name: string): boolean {
  */
 const FINGERPRINT_FILES: ReadonlySet<string> = new Set(WORKSPACE_FINGERPRINT_FILES)
 
+/**
+ * Paths as git spells them under `root`: a project reached through a
+ * symlink below the root (`packages/x -> ../shared/x`) is watched at the
+ * link, and git names and answers for its files only at the real place.
+ * The root keeps its own spelling (macOS's `/var` is `/private/var`), the
+ * name its own (the file may be gone); a directory outside the root is
+ * kept as given. Directories are resolved once per speller.
+ */
+export function gitSpeller(root: string): (p: string) => string {
+  const dirs = new Map<string, string>()
+  let realRoot: string | undefined
+  return (p) => {
+    const dir = path.dirname(p)
+    let at = dirs.get(dir)
+    if (at === undefined) {
+      at = dir
+      try {
+        realRoot ??= realPath(root)
+        const rel = path.relative(realRoot, realPath(dir))
+        if (rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel)) {
+          at = path.join(root, rel)
+        }
+      } catch {}
+      dirs.set(dir, at)
+    }
+    return path.join(at, path.basename(p))
+  }
+}
+
 /**
  * The files under the workspace git lists, tracked and untracked, ignored
  * ones aside, and every directory above one (git lists no directory, and
  * a project moved away whole is one event on its directory): what existed
  * when watch armed, so a path born and gone since is told from a deletion
- * (watch-judge.ts). Undefined when git cannot answer: no inventory, every
- * gone path is a deletion as before.
+ * (watch-judge.ts). `tracked` is the files git tracks: a user edits those,
+ * so a server cannot be blamed for one. Undefined when git cannot answer:
+ * no inventory, every gone path is a deletion as before.
  */
-export function gitFiles(workspaceRoot: string): Set<string> | undefined {
+export function gitFiles(
+  workspaceRoot: string,
+): { listed: Set<string>; tracked: Set<string> } | undefined {
   let proc: ReturnType<typeof Bun.spawnSync>
   try {
     proc = Bun.spawnSync({
-      cmd: [executablePath('git'), 'ls-files', '-z', '--cached', '--others', '--exclude-standard'],
+      cmd: [
+        executablePath('git'),
+        'ls-files',
+        '-z',
+        '-t',
+        '--cached',
+        '--others',
+        '--exclude-standard',
+      ],
       cwd: workspaceRoot,
       stdout: 'pipe',
       stderr: 'ignore',
@@ -360,13 +418,19 @@ export function gitFiles(workspaceRoot: string): Set<string> | undefined {
   }
   if (proc.exitCode !== 0) return undefined
   const files = new Set<string>()
-  for (const p of new TextDecoder('utf-8', { ignoreBOM: true }).decode(proc.stdout).split('\0')) {
-    if (p.length === 0) continue
+  const tracked = new Set<string>()
+  for (const entry of new TextDecoder('utf-8', { ignoreBOM: true })
+    .decode(proc.stdout)
+    .split('\0')) {
+    if (entry.length === 0) continue
+    // `-t` prefixes a tag and a space; `?` is untracked.
+    const p = entry.slice(2)
     // An untracked nested repository is listed as `dir/`.
     let abs = path.join(workspaceRoot, p.endsWith('/') ? p.slice(0, -1) : p)
     files.add(abs)
+    if (entry[0] !== '?') tracked.add(abs)
     for (abs = path.dirname(abs); abs !== workspaceRoot && !files.has(abs); abs = path.dirname(abs))
       files.add(abs)
   }
-  return files
+  return { listed: files, tracked }
 }

package/src/cli/watch-fs.ts

@@ -77,10 +77,10 @@ export function pollWatcher(
    */
   skipDir: (rel: string) => boolean = (rel) => POLL_SKIP.has(path.basename(rel)),
 ): WatchHandle {
-  let previous = new Map<string, number>()
+  let previous = new Map<string, string>()
   let first = true
   const scan = (): void => {
-    const current = new Map<string, number>()
+    const current = new Map<string, string>()
     const walk = (abs: string, rel: string): void => {
       let entries: fs.Dirent[]
       try {
@@ -95,15 +95,23 @@ export function pollWatcher(
           if (recursive && !skipDir(childRel)) walk(path.join(abs, e.name), childRel)
           continue
         }
-        if (!e.isFile()) continue
+        // A link is an input as its target string (watch-judge.ts), so that
+        // string is sampled, never the target's times: a retarget inside
+        // one clock tick carries the same times.
+        const link = e.isSymbolicLink()
+        if (!e.isFile() && !link) continue
         try {
           // The later of the two clocks, as `modifiedBefore` reads them: a
           // replacement that carries the old file's mtime (`cp -p`, `rsync
           // -a`, `mv` of a file stamped the same) moved nothing under mtime
           // alone, and the poller never ran it where the native watcher did.
           // A rename or a write moves ctime, and no process can set it.
-          const st = fs.statSync(path.join(abs, e.name))
-          current.set(childRel, Math.max(st.mtimeMs, st.ctimeMs))
+          const p = path.join(abs, e.name)
+          if (link) current.set(childRel, `link:${fs.readlinkSync(p)}`)
+          else {
+            const st = fs.statSync(p)
+            current.set(childRel, String(Math.max(st.mtimeMs, st.ctimeMs)))
+          }
         } catch {
           // raced with a delete; the next scan settles it
         }
@@ -111,8 +119,8 @@ export function pollWatcher(
     }
     walk(dir, '')
     if (!first) {
-      for (const [rel, mtime] of current) {
-        if (previous.get(rel) !== mtime) onEvent(rel)
+      for (const [rel, stamp] of current) {
+        if (previous.get(rel) !== stamp) onEvent(rel)
       }
       for (const rel of previous.keys()) {
         if (!current.has(rel)) onEvent(rel)

package/src/cli/watch-judge.ts

@@ -5,7 +5,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { xxh3 } from '../util/index.js'
-import { gitIgnored } from './watch-filter.js'
+import { gitIgnored, gitSpeller } from './watch-filter.js'
 import { modifiedBefore } from './watch-fs.js'
 
 const ABSENT = -1n
@@ -63,6 +63,8 @@ export interface JudgeContext {
   fenced?(ownDir: string, abs: string): boolean
   /** The files git listed at the arm; absent when git could not answer. */
   existedAtArm?: ReadonlySet<string>
+  /** The files git tracked at the arm; absent when git could not answer. */
+  trackedAtArm?: ReadonlySet<string>
 }
 
 export class ChangeJudge {
@@ -77,7 +79,7 @@ export class ChangeJudge {
   // 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.
   readonly pending = new Map<string, string>()
-  /** The last cycle's wall window; a write inside it is the run's own. */
+  /** The last cycle's window, its start on the mtime clock (`fsClockNow`); a write inside it is the run's own. */
   lastCycle: { start: number; end: number } | undefined
   // Declared outputs are ignored by PATH above. A task with no `cache`
   // block declares none and still writes into its project, and the
@@ -124,14 +126,14 @@ export class ChangeJudge {
   // the moment between a judgement and that cycle's keys, and gone by the
   // next judgement, was read and its deletion re-runs nothing. Git lists
   // no ignored path, so one of those is a deletion as before.
-  private sameState(abs: string, ignored = false): boolean {
+  private sameState(abs: string, ignored: boolean, spell: (p: string) => string): boolean {
     const state = settledState(abs)
     const prev = this.lastState.get(abs)
     this.lastState.set(abs, state)
     if (prev !== undefined) return prev === state
     if (state === ABSENT) {
       const listed = this.ctx.existedAtArm
-      return !ignored && listed !== undefined && !listed.has(abs) && !this.inNestedRepo(abs)
+      return !ignored && listed !== undefined && !listed.has(spell(abs)) && !this.inNestedRepo(abs)
     }
     return modifiedBefore(abs, this.ctx.armedAt)
   }
@@ -146,13 +148,17 @@ export class ChangeJudge {
     return false
   }
 
-  private writtenDuringLastCycle(abs: string, openWhileHeld = false): boolean {
+  /** `spell` (git's spelling, see `gitSpeller`) given: a held server's write counts outside a cycle too. */
+  private writtenDuringLastCycle(abs: string, spell?: (p: string) => string): 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 && this.ctx.held()
+    // server is one too, from the arm on. Not a tracked file: that is the
+    // user's edit, and three saves of one source file were told to
+    // .gitignore it as a server's write (WD-7).
+    const open =
+      spell !== undefined && this.ctx.held() && this.ctx.trackedAtArm?.has(spell(abs)) !== true
     if (this.lastCycle === undefined && !open) return false
     try {
       const m = fs.statSync(abs).mtimeMs
@@ -165,6 +171,7 @@ export class ChangeJudge {
 
   judge(): string | undefined {
     const ignored = gitIgnored(this.ctx.workspaceRoot, [...this.pending.keys()])
+    const spell = gitSpeller(this.ctx.workspaceRoot)
     let first: string | undefined
     let firstAbs: string | undefined
     // `sameState` before the `first` test, never after it: it is what
@@ -190,7 +197,7 @@ export class ChangeJudge {
     let gone: [label: string, abs: string] | undefined
     for (const [p, l] of this.pending) {
       if (ignored.has(p) && !editForUncached(p)) continue
-      if (this.sameState(p, ignored.has(p)) || first !== undefined) continue
+      if (this.sameState(p, ignored.has(p), spell) || first !== undefined) continue
       if (!fs.existsSync(p)) {
         gone ??= [l, p]
         continue
@@ -201,7 +208,7 @@ export class ChangeJudge {
     if (first === undefined && gone !== undefined) [first, firstAbs] = gone
     this.pending.clear()
     const byServer = firstAbs !== undefined && this.ctx.held()
-    if (firstAbs === undefined || !this.writtenDuringLastCycle(firstAbs, true)) {
+    if (firstAbs === undefined || !this.writtenDuringLastCycle(firstAbs, spell)) {
       this.streak.n = 0
       return first
     }

package/src/cli/watch.ts

@@ -86,7 +86,7 @@ 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}\n`)
+    process.stderr.write(`vx watch: ${parsed.error}${seeHelp('watch')}\n`)
     return 1
   }
 
@@ -103,7 +103,7 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   }
 
   const cwd = process.cwd()
-  const resolved = await resolveRunOptions(parsed, cwd, parsed.tasks)
+  const resolved = await resolveRunOptions(parsed, cwd, parsed.tasks, 'watch')
   if ('error' in resolved) {
     process.stderr.write(`vx watch: ${resolved.error}\n`)
     return 1
@@ -137,10 +137,13 @@ 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', () => {
-    process.stdout.write('\nvx watch: stopped\n')
-    stop.abort('SIGINT')
-  })
+  process.once('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 => {
+    if (stop.signal.reason === 'SIGINT') process.stdout.write('\nvx watch: stopped\n')
+    return 0
+  }
   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.
@@ -206,7 +209,7 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   }
   if (stop.signal.aborted) {
     await held?.stop(forwardedSignal(stop.signal.reason))
-    return 0
+    return stopped()
   }
   if (refusedToStart) return 1
   // After the initial run, so a `pkg#task` naming no project gets the
@@ -234,7 +237,7 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
       ...fingerprintClaims(plugins).keys(),
       ...(opts.frozen === true ? [LOCKFILE_NAME] : []),
     ])
-  return await runWatchLoop({
+  await runWatchLoop({
     opts,
     held,
     stop: stop.signal,
@@ -285,6 +288,7 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
     // The RESOLVED cache dir, not the `.vx` literal — see `makeWatchIgnore`.
     cacheDir: opts.cacheDir ?? ws.cacheDir,
   })
+  return stopped()
 }
 
 interface WatchLoopArgs {
@@ -345,7 +349,7 @@ interface Rediscovered {
   fenceDirs: readonly string[]
 }
 
-async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
+async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
   const { opts, stop, workspaceRoot, projects, cacheDir } = 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.
@@ -403,7 +407,10 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
           await held?.stop()
           held = undefined
           restartTimings()
-          const start = Date.now()
+          // 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
+          // an edit (WD-20). The end needs no stamp: an mtime never leads it.
+          const start = fsClockNow(cacheDir)
           const cycle = await runOrchestrator(opts)
           held = cycle.persistent
           if (cycle.refused !== undefined) process.stderr.write(`vx watch: ${cycle.refused}\n`)
@@ -464,8 +471,8 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
 
   /** 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 at the arm, so a file born and gone since is no deletion (watch-judge.ts). */
-  const existedAtArm = gitFiles(workspaceRoot)
+  /** 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,
@@ -473,7 +480,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
     held: () => held !== undefined,
     uncached: () => uncached,
     fenced: (ownDir, abs) => fenced(ownDir, abs),
-    ...(existedAtArm !== undefined ? { existedAtArm } : {}),
+    ...(atArm !== undefined ? { existedAtArm: atArm.listed, trackedAtArm: atArm.tracked } : {}),
   })
   /** Per-project arms by directory, so `rearm` can add and drop them. */
   const perProject = new Map<string, WatchHandle>()
@@ -838,7 +845,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
 
   process.stdout.write(`\n${watchingLine(projects.length)}; press Ctrl+C to stop\n`)
 
-  return await new Promise<number>((resolve) => {
+  return await new Promise<void>((resolve) => {
     const cleanup = async (): Promise<void> => {
       pool.closeAll()
       if (debounceTimer) clearTimeout(debounceTimer)
@@ -846,7 +853,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
       // it has returned, so the process never exits over a live child.
       await inFlight
       await held?.stop(forwardedSignal(stop.reason))
-      resolve(0)
+      resolve()
     }
     if (stop.aborted) {
       void cleanup()