@vzn/vx 0.0.16 → 0.0.18

package/src/cli/help.ts

@@ -1,129 +1,168 @@
-export function printHelp(): void {
-  process.stdout.write(
-    [
-      'vx — open, extensible monorepo task runner',
-      '',
-      'Usage:',
-      '  vx run [OPTIONS] [TASK | PKG#TASK] [-- forwarded-args...]',
-      '  vx watch [OPTIONS] TASK [-- forwarded-args...]',
-      '  vx cache prune [--older-than <duration>] [--max-size <bytes>]',
-      '  vx lock [--check]',
-      '  vx migrate [--from turbo|nx] [--dry] [--force]',
-      '  vx upgrade [tag]',
-      '  vx show [PROJECT[#TASK]] [--format pretty|json]',
-      '  vx info',
-      '  vx mcp [--stdio]',
-      '  vx help',
-      '  vx version',
-      '',
-      'Selection (for run):',
-      '  (default)                Run task in the project containing cwd.',
-      '      --all                Run task in every project that declares it.',
-      '      --filter <pat>       pnpm-style filter (repeatable). Examples:',
-      '                             foo, @scope/*, ./packages/foo, foo..., ...foo,',
-      '                             foo^..., !foo, [<since>]',
-      '      --affected[=<base>]  Sugar for --filter "[<base>]". Default base =',
-      '                             origin/HEAD (falls back to HEAD~1).',
-      "  pkg#task                 Run a specific project's task directly.",
-      '',
-      'Execution (for run):',
-      '      --concurrency <n>           Max parallel tasks (default: CPU count).',
-      '      --excludeDependencies[=names]  Skip dependsOn edges. No value = all; comma list = specific names.',
-      '      --no-cache                  Disable caching entirely (no reads, no writes, outputs left alone).',
-      '      --force                     Re-execute everything (skip reads) but still refresh the cache (writes on).',
-      '      --cache <spec>              Per-layer read/write control. Comma list of <layer>:<flags>',
-      '                                  (layer = local|remote, flags ⊆ rw). A named layer is set EXACTLY',
-      '                                  to its flags; unnamed layers keep their value. Examples:',
-      '                                  local:rw,remote:r (remote read-only), remote: (remote off),',
-      '                                  local:r (local read-only).',
-      '      --cache-dir <path>          Cache directory override (cwd-relative). Beats the workspace',
-      '                                  cacheDir field + the .vx/cache default.',
-      '      --retry <n>                 Re-run a failed task up to <n> more times (default for tasks',
-      "                                  without their own exec.retries; explicit config wins). Doesn't",
-      '                                  affect cache keys.',
-      '      --timeout <ms>              Default per-task timeout for tasks without their own exec.timeout',
-      '                                  (above VX_TASK_TIMEOUT env + workspace timeout). Kills + fails',
-      '                                  a runaway task. Per-task exec.timeout always wins.',
-      '      --memory <size>             Memory budget (e.g. 8GB) that exec.resources.memory reservations',
-      '                                  pack against. Default: total system RAM — pass this in',
-      '                                  cgroup-limited containers (the default reads the HOST RAM).',
-      '                                  Reservations are per-task config (exec.resources), not flags.',
-      '      --verify[=<what>]           Prove cache correctness. determinism (default): re-run each',
-      '                                  executed cacheable task + content-compare outputs. inputs: sandbox',
-      '                                  with the declared-input baseline + flag reads of undeclared inputs.',
-      '                                  fingerprint: ship output-tree fingerprints for the cross-machine',
-      '                                  diff on a connected serve (~1× exec — no re-run). all: everything.',
-      '                                  An unsafe task fails the run with the exact paths.',
-      '                                  ~2× exec (determinism); CI-shaped. inputs/all need the OS sandbox.',
-      '      --verify-allow <pkg#task,…> Exempt known-nondeterministic tasks from failing --verify.',
-      '      --frozen                    Load configs from vx-lock.json (CI; pair with vx lock --check).',
-      '      --output-logs <mode>        full | errors-only | none — overrides the flow default',
-      '                                  (focused without --all/--filter/--affected, broad with, full in CI).',
-      '      --verbosity <n>             0=quiet, 1=verbose summary, 2+=debug (reserved).',
-      '',
-      'Planning (for run — skips execution):',
-      '      --dry[=text|json]    Print the task graph + cache hit/miss prediction.',
-      '      --graph[=<path>]     Emit Graphviz DOT (stdout if no path).',
-      '',
-      'Artifacts (for run):',
-      '      --summarize[=<path>] Write per-run JSON to <cacheDir>/runs/<run_id>.json.',
-      '      --profile[=<path>]   Write Chrome-trace JSON (default profile.json).',
-      '',
-      'Extensions (plugins):',
-      '  vx core runs tasks in-process and nothing else. A dashboard, remote',
-      '  cache, distributed execution, and telemetry export are provided by',
-      '  PLUGINS declared in vx.workspace.ts — first-party or your own. Core',
-      '  depends on none of them; a plain `vx run` never requires a plugin.',
-      '  See the plugin guide: https://vznjs.github.io/vx/guides/plugins/',
-      '',
-      'Argument forwarding (for run):',
-      "  Anything after `--` is forwarded (shell-quoted) to the task's exec",
-      '  command. The forwarded args are folded into the cache key.',
-      '',
-      'Watch mode:',
-      '  vx watch <task>            Initial run, then re-run on filesystem changes.',
-      '                             Uses the same flags as `vx run` except --dry /',
-      '                             --graph / --summarize / --profile. Press Ctrl+C',
-      '                             to stop. Cache means most re-runs are near-zero',
-      '                             cost (cache hits restore outputs + replay logs).',
-      '',
-      'Cache management:',
-      '  vx cache prune --older-than 30d     Evict entries last accessed > 30 days ago.',
-      '  vx cache prune --max-size 1G        Keep total cache under 1 GB (LRU eviction).',
-      '',
-      '  Duration units: s, m, h, d. Size units: K, M, G, T (powers of 1024).',
-      '',
-      'Introspection:',
-      '  vx show              List every project: name, dir, declared task count.',
-      "  vx show <project>    Print the project's LIVE resolved config (fresh",
-      '                       evaluation, not the lock), one block per task.',
-      "  vx show <pkg>#<task> Print a single task's resolved config.",
-      '      --format <fmt>   pretty (default) | json.',
-      '  vx info              Workspace doctor: vx/bun/git versions, project +',
-      '                       task counts, cache dir/entries/size, recent runs,',
-      '                       lock status.',
-      '  vx stats             Deprecated: alias of vx info.',
-      '  vx mcp               Model Context Protocol server (stdio) — exposes inspector',
-      '                       RPCs as MCP tools for AI agents (Claude Code, Cursor, …).',
-      '',
-      'Migration:',
-      '  vx migrate           Generate vx.config.ts per package from turbo.json or an',
-      '                       Nx project graph (.nx/workspace-data/project-graph.json).',
-      '                       Unmappable settings become TODO(vx-migrate) comments;',
-      '                       turbo global fields become a shared vx-preset.ts.',
-      '      --dry            Print the generated files instead of writing them.',
-      '      --force          Overwrite existing vx.config.* / vx-preset.ts files.',
-      '',
-      'Config lock:',
-      '  vx lock              Evaluate every vx.config in the current environment and',
-      '                       freeze the resolved objects into vx-lock.json. Plain runs',
-      '                       always evaluate live; only `vx run --frozen` consumes the',
-      '                       lock (CI reproducibility, frozen-env semantics).',
-      '  vx lock --check      Audit the lock: file-changed hash report PLUS a full',
-      '                       re-evaluation compared against the frozen objects. Exits 1',
-      '                       on drift (e.g. configs that read env vars). Run it before',
-      '                       `vx run --frozen` in CI.',
-      '',
-    ].join('\n'),
-  )
+export function printHelp(pluginCommands: readonly string[] = []): void {
+  process.stdout.write(helpText(pluginCommands))
+}
+
+export function helpText(pluginCommands: readonly string[] = []): string {
+  return [
+    'vx — open, extensible monorepo task runner',
+    '',
+    'Usage:',
+    '  vx run [OPTIONS] [TASK | PKG#TASK] [-- forwarded-args...]',
+    '  vx watch [OPTIONS] TASK [-- forwarded-args...]',
+    '  vx cache prune [--older-than <duration>] [--max-size <bytes>]',
+    '  vx lock [--check]',
+    '  vx init [--dry] [--force]',
+    '  vx migrate [--from turbo|nx|scripts] [--dry] [--force]',
+    '  vx upgrade [tag]',
+    '  vx show [PROJECT[#TASK]] [--format pretty|json]',
+    '  vx info',
+    '  vx why [TASK | PKG#TASK] [--run <runId>] [--format pretty|json]',
+    '  vx last [RUNID] [--list[=N]] [--format pretty|json]',
+    '  vx prune PROJECT [--out-dir <dir>] [--docker]',
+    '  vx help',
+    '  vx version',
+    '',
+    'Selection (for run):',
+    '  (default)                Run task in the project containing cwd.',
+    '      --all                Run task in every project that declares it.',
+    '      --filter <pat>       pnpm-style filter (repeatable). Examples:',
+    '                             foo, @scope/*, ./packages/foo, foo..., ...foo,',
+    '                             foo^..., !foo, [<since>]',
+    '      --affected[=<base>]  Sugar for --filter "[<base>]". Default base =',
+    '                             origin/HEAD (falls back to HEAD~1).',
+    "  pkg#task                 Run a specific project's task directly.",
+    '',
+    'Execution (for run):',
+    '      --concurrency <n>           Max parallel tasks (default: CPU count).',
+    '      --excludeDependencies[=names]  Skip dependsOn edges. No value = all; comma list = specific names.',
+    '      --no-cache                  Disable caching entirely (no reads, no writes, outputs left alone).',
+    '      --force                     Re-execute everything (skip reads) but still refresh the cache (writes on).',
+    '      --cache <spec>              Per-layer read/write control. Comma list of <layer>:<flags>',
+    '                                  (layer = local|remote, flags ⊆ rw). A named layer is set EXACTLY',
+    '                                  to its flags; unnamed layers keep their value. Examples:',
+    '                                  local:rw,remote:r (remote read-only), remote: (remote off),',
+    '                                  local:r (local read-only).',
+    '      --cache-dir <path>          Cache directory override (cwd-relative). Beats the workspace',
+    '                                  cacheDir field + the .vx/cache default.',
+    '      --retry <n>                 Re-run a failed task up to <n> more times (default for tasks',
+    "                                  without their own exec.retries; explicit config wins). Doesn't",
+    '                                  affect cache keys.',
+    '      --timeout <ms>              Default per-task timeout for tasks without their own exec.timeout',
+    '                                  (above VX_TASK_TIMEOUT env + workspace timeout). Kills + fails',
+    '                                  a runaway task. Per-task exec.timeout always wins.',
+    '      --memory <size>             Memory budget (e.g. 8GB) that exec.resources.memory reservations',
+    '                                  pack against. Default: total system RAM — pass this in',
+    '                                  cgroup-limited containers (the default reads the HOST RAM).',
+    '                                  Reservations are per-task config (exec.resources), not flags.',
+    '      --verify[=<what>]           Prove cache correctness. determinism (default): re-run each',
+    '                                  executed cacheable task + content-compare outputs. inputs: sandbox',
+    '                                  with the declared-input baseline + flag reads of undeclared inputs.',
+    '                                  fingerprint: ship output-tree fingerprints for the cross-machine',
+    '                                  diff on a connected serve (~1× exec — no re-run). all: everything.',
+    '                                  An unsafe task fails the run with the exact paths.',
+    '                                  ~2× exec (determinism); CI-shaped. inputs/all need the OS sandbox.',
+    '      --verify-allow <pkg#task,…> Exempt known-nondeterministic tasks from failing --verify.',
+    '      --frozen                    Load configs from vx-lock.json (CI; pair with vx lock --check).',
+    '      --output-logs <mode>        full | errors-only | hash-only | none — overrides the flow default',
+    '      --download <mode>           all (default) | toplevel | none — where remote outputs land',
+    '                                  (focused without --all/--filter/--affected, broad with, full in CI).',
+    '      --verbosity <n>             0=quiet, 1=verbose summary, 2+=debug (reserved).',
+    '',
+    'Planning (for run — skips execution):',
+    '      --dry[=text|json]    Print the task graph + cache hit/miss prediction.',
+    '      --graph[=<path>]     Emit Graphviz DOT (stdout if no path).',
+    '',
+    'Artifacts (for run):',
+    '      --summarize[=<path>] Write per-run JSON to <cacheDir>/runs/<run_id>.json.',
+    '      --profile[=<path>]   Write Chrome-trace JSON (default profile.json).',
+    '',
+    'Extensions (plugins):',
+    '  vx core runs tasks in-process and nothing else. A dashboard, remote',
+    '  cache, distributed execution, and telemetry export are provided by',
+    '  PLUGINS declared in vx.workspace.ts — first-party or your own. Core',
+    '  depends on none of them; a plain `vx run` never requires a plugin.',
+    '  See the plugin guide: https://vznjs.github.io/vx/guides/plugins/',
+    '',
+    'Argument forwarding (for run):',
+    "  Anything after `--` is forwarded (shell-quoted) to the task's exec",
+    '  command. The forwarded args are folded into the cache key.',
+    '',
+    'Watch mode:',
+    '  vx watch <task>            Initial run, then re-run on filesystem changes.',
+    '                             Uses the same flags as `vx run` except --dry /',
+    '                             --graph / --summarize / --profile. Press Ctrl+C',
+    '                             to stop. Cache means most re-runs are near-zero',
+    '                             cost (cache hits restore outputs + replay logs).',
+    '',
+    'Cache management:',
+    '  vx cache prune --older-than 30d     Evict entries last accessed > 30 days ago.',
+    '  vx cache prune --max-size 1G        Keep total cache under 1 GB (LRU eviction).',
+    '',
+    '  Duration units: s, m, h, d. Size units: K, M, G, T (powers of 1024).',
+    '',
+    'Introspection:',
+    '  vx show              List every project: name, dir, declared task count.',
+    "  vx show <project>    Print the project's LIVE resolved config (fresh",
+    '                       evaluation, not the lock), one block per task.',
+    "  vx show <pkg>#<task> Print a single task's resolved config.",
+    '      --format <fmt>   pretty (default) | json.',
+    '  vx info              Workspace doctor: vx/bun/git versions, project +',
+    '                       task counts, cache dir/entries/size, recent runs,',
+    '                       lock status.',
+    '  vx stats             Deprecated: alias of vx info.',
+    "  vx why <task>        Why did this task re-run? Compares the task's latest",
+    '                       run (or --run <id>) against its previous run: names the',
+    '                       exact changed cache-key components (files / env / runtime',
+    '                       / upstream) from the persisted input fingerprints.',
+    '      --format <fmt>   pretty (default) | json.',
+    '  vx prune <project>   Emit a self-contained workspace SUBSET — the project +',
+    '                       its transitive workspace deps, root manifests, and the',
+    '                       (unpruned) lockfile — for Docker builds. --docker splits',
+    '                       json/ (manifests, the cacheable install layer) from full/.',
+    "  vx last [runId]      Replay a recorded run's summary from the local history —",
+    '                       header (command, when, branch, counts) plus the per-task',
+    '                       table, failures first. No re-execution, no cache probe.',
+    '      --list[=N]       List the N most recent runs (default 10) with run ids.',
+    '      --format <fmt>   pretty (default) | json.',
+    '',
+    'Migration:',
+    '  vx init              Generate vx.workspace.ts + one vx.config.ts per package',
+    '                       from package.json scripts (= vx migrate --from scripts).',
+    '  vx migrate           Generate vx.config.ts per package from turbo.json or an',
+    '                       Nx project graph (.nx/workspace-data/project-graph.json);',
+    '                       with neither present, from package.json scripts.',
+    '                       Unmappable settings become TODO(vx-migrate) comments;',
+    '                       turbo global fields become a shared vx-preset.ts.',
+    '      --dry            Print the generated files instead of writing them.',
+    '      --force          Overwrite existing vx.config.* / vx-preset.ts files.',
+    '',
+    'Config lock:',
+    '  vx lock              Evaluate every vx.config in the current environment and',
+    '                       freeze the resolved objects into vx-lock.json. Plain runs',
+    '                       always evaluate live; only `vx run --frozen` consumes the',
+    '                       lock (CI reproducibility, frozen-env semantics).',
+    '  vx lock --check      Audit the lock: file-changed hash report PLUS a full',
+    '                       re-evaluation compared against the frozen objects. Exits 1',
+    '                       on drift (e.g. configs that read env vars). Run it before',
+    '                       `vx run --frozen` in CI.',
+    '',
+    ...(pluginCommands.length > 0 ? ['Plugin commands:', ...pluginCommands, ''] : []),
+  ].join('\n')
+}
+
+/**
+ * The documented `--flags` of one verb, read from the help text's
+ * sections headed `… (for <verb>):` so there is no second list to drift —
+ * and no hint that names another verb's flag.
+ */
+export function documentedFlags(verb: string): string[] {
+  const flags = new Set<string>()
+  let inVerb = false
+  for (const line of helpText().split('\n')) {
+    if (/^[A-Z][A-Za-z ]*(?: \(for [a-z]+\))?:$/.test(line))
+      inVerb = line.endsWith(`(for ${verb}):`)
+    if (!inVerb) continue
+    for (const f of line.match(/--[a-zA-Z][a-zA-Z-]*/g) ?? []) flags.add(f)
+  }
+  return [...flags]
 }

package/src/cli/index.ts

@@ -4,15 +4,16 @@
 
 import { VERSION } from '../version.js'
 import { runCmd } from './run.js'
-import { watchCmd } from './watch.js'
-import { cacheCmd } from './cache.js'
-import { lockCmd } from './lock.js'
-import { migrateCmd } from './migrate.js'
-import { upgradeCmd } from './upgrade.js'
-import { showCmd } from './show.js'
-import { infoCmd } from './info.js'
-import { mcpCmd } from './mcp.js'
 import { printHelp } from './help.js'
+import { pluginCommandHelp, resolvePluginCommand } from './plugin-commands.js'
+import { UserError } from '../util/index.js'
+
+// Every verb but `run` is imported when invoked. `vx run` is the hot path
+// and nearly every invocation; the other verbs' modules are code that
+// process never calls. Measured 2026-09-03: `--version` is 25 ms either
+// way (module loading is not where start-up goes), so this is hygiene, not
+// a speed-up. The specifiers are string literals, so `bun build --compile`
+// still embeds them.
 
 export async function run(argv: readonly string[]): Promise<number> {
   const [command, ...rest] = argv
@@ -22,7 +23,7 @@ export async function run(argv: readonly string[]): Promise<number> {
     case '--help':
     case '-h':
     case 'help':
-      printHelp()
+      printHelp(await pluginCommandHelp())
       return 0
     case '--version':
     case 'version':
@@ -31,55 +32,85 @@ export async function run(argv: readonly string[]): Promise<number> {
     case 'run':
       return await runCmd(rest)
     case 'watch':
-      return await watchCmd(rest)
+      return await (await import('./watch.js')).watchCmd(rest)
     case 'cache':
-      return await cacheCmd(rest)
+      return await (await import('./cache.js')).cacheCmd(rest)
     case 'lock':
-      return await lockCmd(rest)
+      return await (await import('./lock.js')).lockCmd(rest)
     case 'migrate':
-      return await migrateCmd(rest)
+      return await (await import('./migrate.js')).migrateCmd(rest)
+    case 'init':
+      // A workspace from nowhere: package.json scripts are the source.
+      return await (
+        await import('./migrate.js')
+      ).migrateCmd(['--from', 'scripts', ...rest], { init: true })
     case 'upgrade':
-      return await upgradeCmd(rest)
+      return await (await import('./upgrade.js')).upgradeCmd(rest)
     case 'show':
-      return await showCmd(rest)
+      return await (await import('./show.js')).showCmd(rest)
     case 'info':
     case 'stats': // deprecated alias — `vx info` absorbed `vx stats`
-      return await infoCmd(rest)
-    case 'mcp':
-      return await mcpCmd(rest)
-    case 'serve':
-    case 'dev':
-      // vx core is only a task runner — it has no service layer of its own.
-      // A dashboard, remote cache, distributed execution, etc. are provided
-      // by PLUGINS (declared in vx.workspace.ts), never by core. We keep this
-      // neutral hint for the common muscle-memory verbs, but core names no
-      // specific plugin package: any package can provide these.
-      process.stderr.write(
-        `vx: '${command}' is not a vx core command.\n` +
-          `  vx core runs tasks in-process. A dashboard, remote cache, and\n` +
-          `  distributed execution come from plugins — not core. See the plugin\n` +
-          `  guide: https://vznjs.github.io/vx/guides/plugins/\n`,
-      )
-      return 1
-    default:
-      process.stderr.write(`vx: unknown command: ${command}\n`)
+      return await (await import('./info.js')).infoCmd(rest)
+    case 'why':
+      return await (await import('./why.js')).whyCmd(rest)
+    case 'last':
+      return await (await import('./last.js')).lastCmd(rest)
+    case 'prune':
+      return await (await import('./prune.js')).pruneWorkspaceCmd(rest)
+    default: {
+      // Not a core verb: a plugin declared in the workspace around the cwd
+      // may own it (`VxPlugin.commands`). Core verbs were matched above, so
+      // nothing here can shadow them.
+      const resolved = await resolvePluginCommand(command)
+      if (resolved !== null && !('loadError' in resolved)) {
+        const code = await resolved.command.run(rest, resolved.ctx)
+        // A plugin is a boundary: a JS-authored verb that resolves nothing
+        // would reach `process.exit(undefined)` and read as SUCCESS. A verb
+        // that cannot say whether it succeeded fails, naming its owner.
+        if (!Number.isInteger(code)) {
+          throw new UserError(
+            `plugin '${resolved.plugin.name}': command '${command}' resolved ${JSON.stringify(code)} instead of an exit code`,
+          )
+        }
+        return code
+      }
+      // A broken workspace file cannot say whether the verb exists. Say
+      // both things: the verb is unknown HERE, and why the lookup could not
+      // finish — a typo still reads as a typo, and a real plugin verb still
+      // points at the file that broke it.
+      const loadNote =
+        resolved !== null && 'loadError' in resolved
+          ? `\n  (plugin verbs could not be looked up: vx.workspace failed to load: ${resolved.loadError})`
+          : ''
+      if (command === 'serve' || command === 'dev') {
+        // vx core is only a task runner — it has no service layer of its
+        // own. A dashboard, remote cache, distributed execution, etc. are
+        // provided by PLUGINS (declared in vx.workspace.ts), never by core.
+        // We keep this neutral hint for the common muscle-memory verbs, but
+        // core names no specific plugin package: any package can provide
+        // these.
+        process.stderr.write(
+          `vx: '${command}' is not a vx core command.\n` +
+            `  vx core runs tasks in-process. A dashboard, remote cache, and\n` +
+            `  distributed execution come from plugins — not core. See the plugin\n` +
+            `  guide: https://vznjs.github.io/vx/guides/plugins/\n`,
+        )
+        return 1
+      }
+      process.stderr.write(`vx: unknown command: ${command}${loadNote}\n`)
       printHelp()
       return 1
+    }
   }
 }
 
 // Re-exports for tests + programmatic embedders.
-export { detectFlow, parseRunArgs, type RunArgs } from './run.js'
+export { detectFlow, parseRunArgs, resolveRunOptions, type RunArgs } from './run.js'
 export { parsePruneArgs, parseDuration, parseSize } from './cache.js'
 export { parseLockArgs, type LockArgs } from './lock.js'
 export { parseMigrateArgs, type MigrateArgs } from './migrate.js'
 export { parseShowArgs, type ShowArgs } from './show.js'
-export { parseMcpArgs, type McpArgs } from './mcp.js'
-export {
-  handleMcpRequest,
-  listMcpTools,
-  setMcpContext,
-  type McpContext,
-  type McpToolDef,
-} from './mcp-rpc.js'
+export { parseWhyArgs } from './why.js'
+export { parseLastArgs } from './last.js'
+export { parsePruneWorkspaceArgs } from './prune.js'
 export { formatBytes } from './format.js'

package/src/cli/info.ts

@@ -53,6 +53,11 @@ export async function infoCmd(args: readonly string[]): Promise<number> {
     ['vx', VERSION],
     ['bun', Bun.version],
     ['git', gitVersion()],
+    // The one `git status` walk per run is the warm path's critical path on
+    // a large tree (~55 ms at 1000 projects, measured 2026-09-02). git's
+    // own caches make it near-free after the first run, and they are OFF by
+    // default — say so, since nothing else in a run would.
+    ['git status cache', gitStatusCache(root)],
     ['workspace root', root],
     ['projects', `${metas.length} (${taskCount} task${taskCount === 1 ? '' : 's'})`],
     ['cache dir', cacheDir],
@@ -66,6 +71,31 @@ export async function infoCmd(args: readonly string[]): Promise<number> {
   return 0
 }
 
+/** Whether git's fsmonitor / untracked cache are on, with the remedy when not. */
+function gitStatusCache(root: string): string {
+  try {
+    const p = Bun.spawnSync({
+      cmd: ['git', 'config', '--get-regexp', '^core\\.(fsmonitor|untrackedcache)$'],
+      cwd: root,
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    const out = p.exitCode === 0 ? new TextDecoder().decode(p.stdout) : ''
+    const on = (key: string): boolean =>
+      new RegExp(`^core\\.${key} (true|1|yes|on)$`, 'im').test(out)
+    const fsmonitor = on('fsmonitor')
+    const untracked = on('untrackedcache')
+    if (fsmonitor && untracked) return 'fsmonitor + untrackedCache on'
+    const missing = [
+      ...(fsmonitor ? [] : ['core.fsmonitor']),
+      ...(untracked ? [] : ['core.untrackedCache']),
+    ]
+    return `${missing.join(', ')} off — \`git config ${missing[0]} true\` makes every run's status walk near-free on a large tree`
+  } catch {
+    return '(unknown)'
+  }
+}
+
 function gitVersion(): string {
   try {
     const p = Bun.spawnSync({ cmd: ['git', '--version'], stdout: 'pipe', stderr: 'pipe' })