@vzn/vx 0.0.16 → 0.0.18

package/src/cli/watch.ts

@@ -21,6 +21,9 @@ import {
   listProjects,
   loadProjectConfig,
   loadWorkspace,
+  loadWorkspaceConfig,
+  resolveCacheDir,
+  WORKSPACE_FINGERPRINT_FILES,
   type ProjectMeta,
 } from '../workspace/index.js'
 
@@ -31,6 +34,144 @@ const DEBOUNCE_MS = 150
 const IGNORED_SEGMENTS = ['node_modules', '.git', '.vx']
 const IGNORED_SUFFIXES = ['.tsbuildinfo', '~']
 
+/**
+ * True for a path the ignore filter drops. Every project dir is watched
+ * RECURSIVELY, so without this a `bun install` would re-run the graph on every
+ * file it writes, and vx's own `.vx/cache` writes would trigger a cycle that
+ * writes to `.vx/cache` again.
+ *
+ * Segment-wise, not prefix-wise: `node_modules` is ignored wherever it appears
+ * in the path, not only at the root.
+ */
+export function isIgnoredWatchPath(rel: string): boolean {
+  const segments = rel.split(path.sep)
+  if (segments.some((s) => IGNORED_SEGMENTS.includes(s))) return true
+  if (IGNORED_SUFFIXES.some((suf) => rel.endsWith(suf))) return true
+  return false
+}
+
+/**
+ * The ignore predicate a watcher applies, closed over the run's ACTUAL cache
+ * directory.
+ *
+ * `IGNORED_SEGMENTS` covers the `.vx/cache` default, but `cacheDir` is a
+ * shipped `defineWorkspace` field: point it anywhere else and vx's own cache
+ * writes land in a watched subtree, so every cycle triggers the next one.
+ * Measured on a relocated cache under a recursive root watcher: ONE edit kicked
+ * it and the loop then ran **22 more times during 6 seconds of total silence**
+ * (~3.7 re-runs/second, forever) where the default `.vx` cache settles at 0.
+ * A hard-coded literal cannot see a configured path — the resolved one can.
+ */
+export function makeWatchIgnore(
+  cacheDir: string,
+  outputs: ReadonlyMap<string, readonly string[]> = new Map(),
+): (base: string, filename: string) => boolean {
+  const cacheAbs = path.resolve(cacheDir)
+  // A task's own outputs are not edits: without this every cycle that
+  // writes `dist/` (or `out.txt`) re-runs once more, reporting
+  // "up-to-date" for the trouble. Matched under the directory the globs
+  // are relative to, whichever watcher delivered the event.
+  const declared = [...outputs].map(
+    ([dir, globs]) => [path.resolve(dir), globs.map((g) => new Bun.Glob(g))] as const,
+  )
+  return (base, filename) => {
+    if (isIgnoredWatchPath(filename)) return true
+    const abs = path.resolve(base, filename)
+    if (abs === cacheAbs || abs.startsWith(cacheAbs + path.sep)) return true
+    for (const [dir, globs] of declared) {
+      if (!abs.startsWith(dir + path.sep)) continue
+      const rel = abs
+        .slice(dir.length + 1)
+        .split(path.sep)
+        .join('/')
+      if (globs.some((g) => g.match(rel))) return true
+    }
+    return false
+  }
+}
+
+/**
+ * The file `armWatcher` writes under a watched directory to prove the
+ * watcher delivers. Intercepted by name before any other handling, so it
+ * can never trigger a cycle, and removed before "watching" is printed.
+ */
+export const WATCH_PROBE = '.vx-watch-probe'
+
+/** How long a watcher gets to report its own probe before the loop goes on without proof. */
+const WATCH_PROBE_TIMEOUT_MS = 2_000
+
+export interface ArmedWatcher {
+  watcher: fs.FSWatcher
+  /** Resolves `true` once the watcher reported the probe, `false` on timeout. */
+  ready: Promise<boolean>
+}
+
+/**
+ * `fs.watch` plus proof of delivery. On macOS a recursive watcher is an
+ * FSEvents stream that another thread schedules AFTER the call returns, and
+ * a change landing in that gap is never delivered — MEASURED 2026-09-03: a
+ * write made immediately after `fs.watch` was lost 5 times in 30 under CPU
+ * load (0 in 30 idle, 0 in 30 after a 50 ms pause). The gap has no fixed
+ * width, so no pause is the answer and no timeout on the waiting side ever
+ * was (the e2e flake this closes had one of 45 s). A probe file written
+ * under the watcher and waited for is: once ITS event arrives, the stream
+ * is live for everything after it.
+ *
+ * `onEvent` never sees the probe (create or unlink), and the probe is
+ * removed before `ready` resolves.
+ */
+export function armWatcher(
+  dir: string,
+  recursive: boolean,
+  onEvent: (filename: string) => void,
+  timeoutMs = WATCH_PROBE_TIMEOUT_MS,
+): ArmedWatcher {
+  let markReady: (ok: boolean) => void = () => {}
+  const seen = new Promise<boolean>((resolve) => {
+    markReady = resolve
+  })
+  const watcher = fs.watch(dir, { recursive, persistent: true }, (_event, filename) => {
+    if (filename == null || typeof filename !== 'string') return
+    if (filename === WATCH_PROBE) {
+      markReady(true)
+      return
+    }
+    onEvent(filename)
+  })
+  const probe = path.join(dir, WATCH_PROBE)
+  const ready = (async (): Promise<boolean> => {
+    // The probe is subject to the very race it detects: a write that lands
+    // in the gap is lost like any other (1 in 20 under a full gate's load,
+    // measured 2026-09-03, with every delivered event under 60 ms). So it is
+    // re-written on a short backoff until its event arrives — the first write
+    // after the stream goes live is the one that proves it.
+    const deadline = Date.now() + timeoutMs
+    let ok = false
+    let step = 50
+    while (!ok) {
+      try {
+        fs.writeFileSync(probe, String(Date.now()))
+      } catch {
+        break // an unwritable dir gets no proof; the watcher is kept
+      }
+      const remaining = deadline - Date.now()
+      if (remaining <= 0) break
+      const pause = new Promise<boolean>((resolve) => {
+        setTimeout(() => resolve(false), Math.min(step, remaining)).unref()
+      })
+      ok = await Promise.race([seen, pause])
+      step = Math.min(step * 2, 400)
+    }
+    try {
+      fs.unlinkSync(probe)
+    } catch {
+      // already gone
+    }
+    return ok
+  })()
+  return { watcher, ready }
+}
+
 export async function watchCmd(args: readonly string[]): Promise<number> {
   const parsed = parseRunArgs(args)
   if (parsed.error) {
@@ -48,6 +189,15 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
     )
     return 1
   }
+  // All three format ONE run's result and are consumed by `runCmd` alone, so
+  // a watch loop silently ignored them. `--verbosity 0` is not rejected: it
+  // asks for the output watch already gives.
+  if (parsed.report !== undefined || parsed.reportFile !== undefined || parsed.verbosity > 0) {
+    process.stderr.write(
+      `vx watch: --report / --report-file / --verbosity are not supported in watch mode (they report a single run)\n`,
+    )
+    return 1
+  }
   if (parsed.tasks.length === 0) {
     process.stderr.write(`vx watch: missing task name\n`)
     return 1
@@ -59,6 +209,10 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
     process.stderr.write(`vx watch: ${resolved.error}\n`)
     return 1
   }
+  if ('nothingSelected' in resolved) {
+    process.stderr.write(`vx watch: ${resolved.nothingSelected}\n`)
+    return 0
+  }
   // The watch loop owns SIGINT/SIGTERM for its whole lifetime (the
   // process.once handlers below close watchers and resolve 0). A
   // cycle's run() must not install its exit-the-process handlers —
@@ -83,39 +237,75 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   }
 
   // Initial run — same code path as `vx run`.
+  //
+  // Watchers do not exist yet, so an edit made WHILE this run is executing is
+  // dropped by the OS and never triggers a re-run. Known and deliberate: the
+  // obvious fix (install watchers first) forces `anyTaskUsesWorkspaceFiles`
+  // 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;
+  // closing it properly needs the workspaceWide decision made without loading
+  // configs.
   process.stdout.write('vx watch: initial run...\n\n')
   await runOrchestrator(opts)
 
+  const swept = await sweepConfigs(allProjects, workspaceRoot)
   return await runWatchLoop({
     opts,
     workspaceRoot,
     projects: scope,
-    workspaceWide: await anyTaskUsesWorkspaceFiles(allProjects),
+    workspaceWide: swept.workspaceWide,
+    outputs: swept.outputs,
+    // The RESOLVED cache dir, not the `.vx` literal — see `makeWatchIgnore`.
+    cacheDir:
+      opts.cacheDir ?? resolveCacheDir(workspaceRoot, await loadWorkspaceConfig(workspaceRoot)),
   })
 }
 
 /**
- * `inputs.workspaceFiles` globs have no project boundary — any file in
- * the workspace can be an input. When any config declares them, the
- * per-project watchers can't see all triggering paths, so the loop
- * switches to one recursive root watcher. Checked across ALL projects
- * (not just the scope) because dependsOn can pull tasks from anywhere;
- * a broken out-of-scope config is skipped, matching scoped-run
- * semantics (it surfaces when that project enters scope).
+ * One sweep over every config for the two things the loop needs: whether
+ * any task declares `inputs.workspaceFiles` — globs with no project
+ * boundary, so the per-project watchers can't see all triggering paths
+ * and the loop switches to one recursive root watcher — and each
+ * project's declared outputs, so their writes are not taken for edits.
+ * Checked across ALL projects (not just the scope) because dependsOn can
+ * pull tasks from anywhere; a broken out-of-scope config is skipped,
+ * matching scoped-run semantics (it surfaces when that project enters
+ * scope).
  */
-async function anyTaskUsesWorkspaceFiles(projects: readonly ProjectMeta[]): Promise<boolean> {
-  for (const p of projects) {
-    if (p.configPath === null) continue
-    try {
-      const config = await loadProjectConfig(p.configPath)
-      for (const task of Object.values(config.tasks ?? {})) {
-        if ((task.cache?.inputs?.workspaceFiles?.length ?? 0) > 0) return true
-      }
-    } catch {
-      // broken config — out of this concern's scope
-    }
+async function sweepConfigs(
+  projects: readonly ProjectMeta[],
+  workspaceRoot: string,
+): Promise<{ workspaceWide: boolean; outputs: Map<string, string[]> }> {
+  const outputs = new Map<string, string[]>()
+  const add = (dir: string, globs: readonly string[] | undefined): void => {
+    if (globs === undefined || globs.length === 0) return
+    outputs.set(dir, [...(outputs.get(dir) ?? []), ...globs])
   }
-  return false
+  // Concurrent, not sequential: the run that just happened already
+  // loaded the in-scope configs, so these are REPEAT loads that
+  // re-evaluate in a worker. Issuing them together lets one worker
+  // serve the whole sweep instead of one per project.
+  const uses = await Promise.all(
+    projects.map(async (p): Promise<boolean> => {
+      if (p.configPath === null) return false
+      try {
+        const config = await loadProjectConfig(p.configPath)
+        let wide = false
+        for (const task of Object.values(config.tasks ?? {})) {
+          if ((task.cache?.inputs?.workspaceFiles?.length ?? 0) > 0) wide = true
+          add(p.dir, task.cache?.outputs?.files)
+          add(workspaceRoot, task.cache?.outputs?.workspaceFiles)
+        }
+        return wide
+      } catch {
+        // broken config — out of this concern's scope
+        return false
+      }
+    }),
+  )
+  return { workspaceWide: uses.includes(true), outputs }
 }
 
 interface WatchLoopArgs {
@@ -123,10 +313,14 @@ interface WatchLoopArgs {
   workspaceRoot: string
   projects: readonly ProjectMeta[]
   workspaceWide: boolean
+  /** Absolute, already-resolved — the loop must never re-derive it. */
+  cacheDir: string
+  /** Declared output globs per directory they are relative to (project dir, or the root for `workspaceFiles`). */
+  outputs: ReadonlyMap<string, readonly string[]>
 }
 
 async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
-  const { opts, workspaceRoot, projects, workspaceWide } = args
+  const { opts, workspaceRoot, projects, workspaceWide, cacheDir, outputs } = args
 
   // Reentrancy guard — never two orchestrator runs in flight. While
   // one is running, any further events set `pending = true` and the
@@ -175,15 +369,25 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
 
   // Filter out events for paths we don't care about. We watch each
   // project's dir recursively, so a `node_modules` write under a
-  // project would otherwise trigger every save during `bun install`.
-  const isIgnoredPath = (rel: string): boolean => {
-    const segments = rel.split(path.sep)
-    if (segments.some((s) => IGNORED_SEGMENTS.includes(s))) return true
-    if (IGNORED_SUFFIXES.some((suf) => rel.endsWith(suf))) return true
-    return false
-  }
+  // project would otherwise trigger every save during `bun install` —
+  // and vx's own cache writes would trigger a cycle that writes again.
+  const isIgnoredPath = makeWatchIgnore(cacheDir, outputs)
 
   const watchers: fs.FSWatcher[] = []
+  const proofs: Promise<void>[] = []
+  const arm = (dir: string, recursive: boolean, onEvent: (filename: string) => void): void => {
+    const armed = armWatcher(dir, recursive, onEvent)
+    watchers.push(armed.watcher)
+    proofs.push(
+      armed.ready.then((ok) => {
+        if (!ok) {
+          process.stderr.write(
+            `vx watch: ${dir}: the watcher gave no sign of life within ${WATCH_PROBE_TIMEOUT_MS} ms; early edits there may be missed\n`,
+          )
+        }
+      }),
+    )
+  }
 
   if (workspaceWide) {
     // workspaceFiles inputs in play: any file in the workspace can be
@@ -192,16 +396,10 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
     // ignore filter keeps node_modules / .git / .vx churn out; edits
     // outside any task's inputs still cost only a cache-hit cycle.
     try {
-      const w = fs.watch(
-        workspaceRoot,
-        { recursive: true, persistent: true },
-        (_event, filename) => {
-          if (filename == null || typeof filename !== 'string') return
-          if (isIgnoredPath(filename)) return
-          trigger(`root ${filename}`)
-        },
-      )
-      watchers.push(w)
+      arm(workspaceRoot, true, (filename) => {
+        if (isIgnoredPath(workspaceRoot, filename)) return
+        trigger(`root ${filename}`)
+      })
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err)
       process.stderr.write(`vx watch: cannot watch workspace root: ${msg}\n`)
@@ -212,13 +410,10 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
     // cover every project + node_modules + caches).
     for (const proj of projects) {
       try {
-        const w = fs.watch(proj.dir, { recursive: true, persistent: true }, (_event, filename) => {
-          if (filename == null) return
-          if (typeof filename !== 'string') return
-          if (isIgnoredPath(filename)) return
+        arm(proj.dir, true, (filename) => {
+          if (isIgnoredPath(proj.dir, filename)) return
           trigger(`${proj.name} ${filename}`)
         })
-        watchers.push(w)
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err)
         process.stderr.write(`vx watch: cannot watch ${proj.dir}: ${msg}\n`)
@@ -229,15 +424,9 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
     // pnpm-workspace.yaml edits trigger re-runs even when no project
     // dir saw the change.
     try {
-      const w = fs.watch(
-        workspaceRoot,
-        { recursive: false, persistent: true },
-        (_event, filename) => {
-          if (filename == null || typeof filename !== 'string') return
-          if (isWorkspaceFingerprintFile(filename)) trigger(`root ${filename}`)
-        },
-      )
-      watchers.push(w)
+      arm(workspaceRoot, false, (filename) => {
+        if (isWorkspaceFingerprintFile(filename)) trigger(`root ${filename}`)
+      })
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err)
       process.stderr.write(`vx watch: cannot watch workspace root: ${msg}\n`)
@@ -248,6 +437,10 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
   // re-runs because IGNORED_SEGMENTS includes `.vx`. Users who
   // relocate the cache dir outside `.vx/` need their own filtering.
 
+  // "watching" is a promise that an edit from now on is seen; every
+  // watcher has proved (or been given 2 s to prove) delivery first.
+  await Promise.all(proofs)
+
   process.stdout.write(
     workspaceWide
       ? `\nvx watch: watching the workspace root (workspaceFiles inputs in use); press Ctrl+C to stop\n`
@@ -274,14 +467,19 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
   })
 }
 
+/**
+ * True for a root file that re-keys EVERY task, so a change to one must trigger
+ * a cycle even though it lives in no project dir.
+ *
+ * Reads the SHARED constant the fingerprint itself walks — this used to be a
+ * third hand-rolled copy of that list, which is precisely the drift the
+ * `--affected` wave exported the constant to prevent. A name added there but
+ * not here would re-key every task while `vx watch` silently never re-ran on
+ * it: the loop looks alive, and the one edit that invalidates the whole
+ * workspace is the one it ignores.
+ */
+const FINGERPRINT_FILES: ReadonlySet<string> = new Set(WORKSPACE_FINGERPRINT_FILES)
+
 function isWorkspaceFingerprintFile(name: string): boolean {
-  return (
-    name === 'pnpm-lock.yaml' ||
-    name === 'package-lock.json' ||
-    name === 'npm-shrinkwrap.json' ||
-    name === 'yarn.lock' ||
-    name === 'bun.lock' ||
-    name === 'bun.lockb' ||
-    name === 'pnpm-workspace.yaml'
-  )
+  return FINGERPRINT_FILES.has(name)
 }

package/src/cli/why.ts

@@ -0,0 +1,193 @@
+// `vx why [pkg#task | task]` — answer "why did this task re-run?" from the
+// terminal. The same persisted data the MCP `whyDidThisRerun` tool reads:
+// the runs table names the
+// run-over-run hash change, and `entry_inputs` (the input-fingerprint moat)
+// names the exact cache-key components that differ. Read-only over cache.db —
+// no config evaluation, no re-hash.
+
+import { Cache } from '../cache/index.js'
+import { splitTaskId } from '../graph/index.js'
+import {
+  cacheKeyDiff,
+  explainCacheKeyQuery as explainCacheKey,
+  whyDidThisRerunQuery as whyDidThisRerun,
+} from '../orchestrator/index.js'
+import { UserError } from '../util/index.js'
+import { findWorkspaceRoot, loadWorkspaceConfig, resolveCacheDir } from '../workspace/index.js'
+
+interface WhyArgs {
+  target?: string
+  runId?: string
+  format: 'pretty' | 'json'
+  error?: string
+}
+
+export function parseWhyArgs(args: readonly string[]): WhyArgs {
+  const out: WhyArgs = { format: 'pretty' }
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!
+    // Match on the flag NAME first. Reading the value into the same
+    // `undefined` that means "not this flag" conflated the two: a trailing
+    // `--run` (value omitted) consumed a non-existent argv slot, fell through,
+    // and was reported as `unknown flag: --run` — false, since `--run` is very
+    // much known, and silent about the real mistake. The `=` spelling of the
+    // same mistake already said `invalid --run: empty`, so one omitted value
+    // got two different diagnoses depending on how it was typed.
+    if (a === '--run' || a.startsWith('--run=')) {
+      const rv = a === '--run' ? args[++i] : a.slice(6)
+      if (rv === undefined || rv === '') return { ...out, error: 'invalid --run: empty' }
+      out.runId = rv
+      continue
+    }
+    if (a === '--format' || a.startsWith('--format=')) {
+      const fv = a === '--format' ? args[++i] : a.slice(9)
+      if (fv !== 'pretty' && fv !== 'json') {
+        // An omitted value reads as empty, not as the literal word "undefined".
+        return {
+          ...out,
+          error: `invalid --format: ${fv ?? ''} (expected pretty | json)`,
+        }
+      }
+      out.format = fv
+      continue
+    }
+    if (a.startsWith('-')) return { ...out, error: `unknown flag: ${a}` }
+    if (out.target !== undefined) return { ...out, error: `unexpected argument: ${a}` }
+    out.target = a
+  }
+  return out
+}
+
+/** Simple includes-match in both directions, case-insensitive. */
+function suggest(query: string, candidates: readonly string[]): string {
+  const q = query.toLowerCase()
+  const hits = candidates.filter((c) => {
+    const n = c.toLowerCase()
+    return n.includes(q) || q.includes(n)
+  })
+  return hits.length > 0 ? ` — did you mean ${hits.slice(0, 3).join(', ')}?` : ''
+}
+
+/**
+ * Resolve a positional target to a full `project#task` id against the runs
+ * table. A `pkg#task` form is used as-is; a bare task name matches every
+ * project that ran it — unique → resolved, several → error listing them.
+ */
+function resolveTarget(cache: Cache, target: string): string {
+  const db = cache.dbHandle()
+  const pairs = db
+    .query('SELECT DISTINCT project, task FROM runs ORDER BY project, task')
+    .all() as Array<{ project: string; task: string }>
+  const ids = pairs.map((p) => `${p.project}#${p.task}`)
+  if (target.includes('#')) {
+    if (ids.includes(target)) return target
+    throw new UserError(`vx why: no recorded runs for "${target}"${suggest(target, ids)}`)
+  }
+  const matches = ids.filter((id) => id.endsWith(`#${target}`))
+  if (matches.length === 1) return matches[0]!
+  if (matches.length > 1) {
+    throw new UserError(
+      `vx why: "${target}" ran in ${matches.length} projects — pick one:\n` +
+        matches.map((m) => `  ${m}`).join('\n'),
+    )
+  }
+  throw new UserError(`vx why: no recorded runs for task "${target}"${suggest(target, ids)}`)
+}
+
+/** The latest recorded run of a task (run_id may be NULL on very old rows). */
+function latestRunId(cache: Cache, taskId: string): string | null {
+  const [project, task] = splitTaskId(taskId)
+  const row = cache
+    .dbHandle()
+    .query(
+      `SELECT run_id AS runId FROM runs WHERE project = ? AND task = ?
+       ORDER BY started_at DESC LIMIT 1`,
+    )
+    .get(project, task) as { runId: string | null } | undefined
+  return row?.runId ?? null
+}
+
+const fmtWhen = (ms: number): string => new Date(ms).toISOString()
+
+export async function whyCmd(args: readonly string[]): Promise<number> {
+  const parsed = parseWhyArgs(args)
+  if (parsed.error !== undefined) throw new UserError(`vx why: ${parsed.error}`)
+  if (parsed.target === undefined) {
+    throw new UserError('vx why: <task> required (e.g. vx why app#build, or vx why build)')
+  }
+
+  const root = await findWorkspaceRoot(process.cwd())
+  const cacheDir = resolveCacheDir(root, await loadWorkspaceConfig(root))
+  const cache = new Cache(cacheDir)
+  try {
+    const db = cache.dbHandle()
+    const taskId = resolveTarget(cache, parsed.target)
+    const runId = parsed.runId ?? latestRunId(cache, taskId)
+
+    if (runId === null) {
+      // Runs exist (resolveTarget passed) but predate run ids — fall back to
+      // the persisted entry metadata so the verb still says something useful.
+      const explanation = explainCacheKey(db, taskId)
+      if (parsed.format === 'json') {
+        process.stdout.write(`${JSON.stringify({ taskId, why: null, diff: null, explanation })}\n`)
+      } else {
+        process.stdout.write(
+          `${taskId}: recorded runs carry no run id — showing the latest cache entry instead\n` +
+            (explanation.latestEntry !== null
+              ? `  hash ${explanation.latestEntry.hash} · $ ${explanation.latestEntry.command}\n`
+              : '  (no cache entry either)\n'),
+        )
+      }
+      return 0
+    }
+
+    const why = whyDidThisRerun(db, runId, taskId)
+    if (!why.found) {
+      throw new UserError(`vx why: run ${runId} has no row for ${taskId}`)
+    }
+    const diff = cacheKeyDiff(db, runId, taskId)
+
+    if (parsed.format === 'json') {
+      process.stdout.write(`${JSON.stringify({ taskId, runId, why, diff })}\n`)
+      return 0
+    }
+
+    const lines: string[] = []
+    const t = why.thisRun!
+    lines.push(`${taskId} — run ${runId}`)
+    lines.push(
+      `  this run   ${fmtWhen(t.startedAt)} · ${t.status}` +
+        `${t.cacheHit === true ? ' · cache hit' : t.cacheHit === false ? ' · executed' : ''} · key ${t.hash}`,
+    )
+    if (why.previousRun == null) {
+      lines.push('  previous   (none — first recorded run of this task)')
+    } else {
+      const p = why.previousRun
+      lines.push(`  previous   ${fmtWhen(p.startedAt)} · ${p.status} · key ${p.hash}`)
+      lines.push(`  verdict    ${why.note}`)
+    }
+
+    if (diff.entries.length > 0) {
+      lines.push('')
+      lines.push(
+        `  what changed (${diff.entries.length} component${diff.entries.length === 1 ? '' : 's'}, ${diff.unchangedCount} unchanged):`,
+      )
+      const kindW = Math.max(...diff.entries.map((e) => e.kind.length), 4)
+      for (const e of diff.entries) {
+        const beforeAfter =
+          e.change === 'added'
+            ? `+ ${e.after}`
+            : e.change === 'removed'
+              ? `- ${e.before}`
+              : `${e.before} → ${e.after}`
+        lines.push(`    ${e.change.padEnd(7)} ${e.kind.padEnd(kindW)}  ${e.name}  ${beforeAfter}`)
+      }
+    } else if (why.hashChanged === true) {
+      lines.push(`  detail     ${diff.note}`)
+    }
+    process.stdout.write(`${lines.join('\n')}\n`)
+    return 0
+  } finally {
+    cache.close()
+  }
+}