@vzn/vx 0.0.18 → 0.0.22

package/src/cli/help.ts

@@ -1,5 +1,36 @@
-export function printHelp(pluginCommands: readonly string[] = []): void {
-  process.stdout.write(helpText(pluginCommands))
+export function printHelp(pluginCommands: readonly string[] = [], verb?: string): void {
+  process.stdout.write(verb === undefined ? helpText(pluginCommands) : verbHelpText(verb))
+}
+
+/**
+ * `vx <verb> --help`: the reference cut to one verb — the title, the Usage
+ * lines that name it, and every section that is `(for <verb>)` or lists a
+ * `vx <verb>` form — read from the same text, so nothing can drift. A verb
+ * the reference does not know gets the whole thing.
+ */
+export function verbHelpText(verb: string): string {
+  const blocks = helpText().split('\n\n')
+  const title = blocks[0]!
+  // The verb goes into a RegExp, so it is escaped: `vx 'r.n' --help` is an
+  // unknown verb, not a pattern that matches `vx run` and answers with a
+  // help cut for a verb that does not exist.
+  const quoted = verb.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const names = (line: string): boolean =>
+    new RegExp(`^\\s*vx ${quoted}( |$)`).test(line) ||
+    line.includes(`(for ${verb})`) ||
+    line.includes(`(for ${verb} `)
+  const kept: string[] = []
+  for (const block of blocks.slice(1)) {
+    const lines = block.split('\n')
+    if (lines[0] === 'Usage:') {
+      const own = lines.slice(1).filter(names)
+      if (own.length > 0) kept.push(['Usage:', ...own].join('\n'))
+      continue
+    }
+    if (lines.some(names)) kept.push(block)
+  }
+  if (kept.length === 0) return helpText()
+  return [title, ...kept, 'Full reference: vx help', ''].join('\n\n')
 }
 
 export function helpText(pluginCommands: readonly string[] = []): string {
@@ -9,16 +40,15 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '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 cache prune [--older-than <duration>] [--max-size <size>] [--dry-run] [--cache-dir <path>]',
     '  vx lock [--check]',
-    '  vx init [--dry] [--force]',
-    '  vx migrate [--from turbo|nx|scripts] [--dry] [--force]',
+    '  vx init [--dry] [--force] [--mjs]',
     '  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 show [PROJECT[#TASK] | TASK] [--format pretty|json]',
+    '  vx info [--format pretty|json] [--cache-dir <path>]',
+    '  vx why [TASK | PKG#TASK] [--run <runId>] [--format pretty|json] [--cache-dir <path>]',
+    '  vx last [RUNID] [--list[=N]] [--format pretty|json] [--cache-dir <path>]',
+    '  vx completions bash|zsh|fish',
     '  vx help',
     '  vx version',
     '',
@@ -28,13 +58,13 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '      --filter <pat>       pnpm-style filter (repeatable). Examples:',
     '                             foo, @scope/*, ./packages/foo, foo..., ...foo,',
     '                             foo^..., !foo, [<since>]',
-    '      --affected[=<base>]  Sugar for --filter "[<base>]". Default base =',
+    '      --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.',
+    '      --concurrency <n>           Max parallel tasks (default: the cores this process may use); `50%` = half of them.',
+    '      --exclude-dependencies[=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>',
@@ -50,23 +80,13 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '      --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.',
+    '      --continue[=<mode>]         What a failed task takes down: never | deps-ok (default, skips',
+    '                                  its dependents) | always (bare form; dependents run, never save).',
     '      --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).',
+    '      --download <mode>           all (default) | toplevel | none — where remote outputs land.',
+    '      --verbosity <n>             0 (default) or 1+: print a per-task summary table after the run.',
     '',
     'Planning (for run — skips execution):',
     '      --dry[=text|json]    Print the task graph + cache hit/miss prediction.',
@@ -75,6 +95,9 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     'Artifacts (for run):',
     '      --summarize[=<path>] Write per-run JSON to <cacheDir>/runs/<run_id>.json.',
     '      --profile[=<path>]   Write Chrome-trace JSON (default profile.json).',
+    '      --report[=markdown]  Print a markdown run report to stdout after the run.',
+    '      --report-file <path> Append that report to <path> (for $GITHUB_STEP_SUMMARY).',
+    '      --tag <k=v>          Label this invocation (repeatable); recorded on its history row.',
     '',
     'Extensions (plugins):',
     '  vx core runs tasks in-process and nothing else. A dashboard, remote',
@@ -97,28 +120,29 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '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).',
+    '      --dry-run                       Say what the policy would reap; delete nothing.',
+    '      --cache-dir <path>              The cache a run with the same flag uses (why, last, info too).',
     '',
     '  Duration units: s, m, h, d. Size units: K, M, G, T (powers of 1024).',
+    '  Cache statistics — directory, entry count, size — are part of `vx info`.',
     '',
     '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.",
+    '  vx show <task>       That task in every project declaring it.',
     '      --format <fmt>   pretty (default) | json.',
     '  vx info              Workspace doctor: vx/bun/git versions, project +',
     '                       task counts, cache dir/entries/size, recent runs,',
     '                       lock status.',
+    '      --format <fmt>   pretty (default) | json.',
     '  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.',
@@ -127,14 +151,17 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '',
     '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.',
+    '                       from package.json scripts. Unmappable settings become',
+    '                       TODO(vx-migrate) comments.',
     '      --dry            Print the generated files instead of writing them.',
-    '      --force          Overwrite existing vx.config.* / vx-preset.ts files.',
+    '      --force          Overwrite existing vx.config.* files.',
+    '  From turbo.json or an Nx project graph: `bunx @vzn/vx-migrate` (its own package).',
+    '',
+    'Shell completions:',
+    '  vx completions <shell>   Print a completion script for bash, zsh or fish: the',
+    '                           verbs (plugin verbs of this workspace included) and',
+    '                           every flag of each. `eval "$(vx completions bash)"`,',
+    '                           or write it where the shell loads completions from.',
     '',
     'Config lock:',
     '  vx lock              Evaluate every vx.config in the current environment and',
@@ -150,6 +177,15 @@ export function helpText(pluginCommands: readonly string[] = []): string {
   ].join('\n')
 }
 
+/**
+ * Every argument error ends with this. `vx <verb> --help` prints the
+ * reference (2026-09-04); before that there was nowhere to send a user who
+ * got a flag wrong, so the errors just said no.
+ */
+export function seeHelp(verb: string): string {
+  return ` (see \`vx ${verb} --help\`)`
+}
+
 /**
  * The documented `--flags` of one verb, read from the help text's
  * sections headed `… (for <verb>):` so there is no second list to drift —
@@ -166,3 +202,5 @@ export function documentedFlags(verb: string): string[] {
   }
   return [...flags]
 }
+
+export { CORE_VERBS } from '../util/index.js'

package/src/cli/index.ts

@@ -4,9 +4,9 @@
 
 import { VERSION } from '../version.js'
 import { runCmd } from './run.js'
-import { printHelp } from './help.js'
-import { pluginCommandHelp, resolvePluginCommand } from './plugin-commands.js'
-import { UserError } from '../util/index.js'
+import { CORE_VERBS, printHelp } from './help.js'
+import { pluginCommandHelp, resolvePluginCommand, pluginVerbs } from './plugin-commands.js'
+import { MOVED_VERBS, nearest, 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
@@ -18,6 +18,16 @@ import { UserError } from '../util/index.js'
 export async function run(argv: readonly string[]): Promise<number> {
   const [command, ...rest] = argv
 
+  // `vx <verb> --help` is the universal reflex, and every verb answered
+  // `unknown flag: --help` and exited 1 (walkthrough, 2026-09-04). Only args
+  // BEFORE a `--` count: `vx run build -- --help` forwards it to the task,
+  // which is the one place `--help` is not being asked of vx. Core verbs
+  // only — a plugin verb owns its own arguments, `--help` included.
+  if (command !== undefined && wantsHelp(command, rest)) {
+    printHelp(await pluginCommandHelp(), command)
+    return 0
+  }
+
   switch (command) {
     case undefined:
     case '--help':
@@ -37,13 +47,8 @@ export async function run(argv: readonly string[]): Promise<number> {
       return await (await import('./cache.js')).cacheCmd(rest)
     case 'lock':
       return await (await import('./lock.js')).lockCmd(rest)
-    case 'migrate':
-      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 })
+      return await (await import('./init.js')).initCmd(rest)
     case 'upgrade':
       return await (await import('./upgrade.js')).upgradeCmd(rest)
     case 'show':
@@ -55,14 +60,14 @@ export async function run(argv: readonly string[]): Promise<number> {
       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)
+    case 'completions':
+      return await (await import('./completions.js')).completionsCmd(rest, await pluginVerbs())
     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)) {
+      if (resolved !== null && !('loadError' in resolved) && !('declaredVerbs' 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
@@ -82,6 +87,14 @@ export async function run(argv: readonly string[]): Promise<number> {
         resolved !== null && 'loadError' in resolved
           ? `\n  (plugin verbs could not be looked up: vx.workspace failed to load: ${resolved.loadError})`
           : ''
+      // A verb core owned once (`migrate`, `prune`) and a package owns now:
+      // the pointer, but only after the plugins had their chance — a
+      // workspace that declares a plugin verb of that name keeps it.
+      const moved = MOVED_VERBS[command]
+      if (moved !== undefined) {
+        process.stderr.write(`${moved}${loadNote}\n`)
+        return 1
+      }
       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
@@ -97,20 +110,72 @@ export async function run(argv: readonly string[]): Promise<number> {
         )
         return 1
       }
-      process.stderr.write(`vx: unknown command: ${command}${loadNote}\n`)
-      printHelp()
+      // One line, as a verb's own unknown flag or subcommand gets; the full
+      // help after a typo was a hundred lines past the hint that mattered.
+      // The verbs this workspace's plugins declare are verbs HERE, so they
+      // join the "did you mean" set, and when nothing is close the second
+      // line says where a verb can come from: `vx mpc` in a workspace
+      // declaring `mcp` read as a plain unknown command, and `vx mcp`
+      // before the plugin was declared said nothing about the file that
+      // would declare it (2026-09-20).
+      const declaredVerbs =
+        resolved !== null && 'declaredVerbs' in resolved ? resolved.declaredVerbs : []
+      const guess = didYouMeanVerb(command, declaredVerbs)
+      process.stderr.write(
+        `vx: unknown command: ${command}${guess}${loadNote} (see \`vx help\`)\n` +
+          (guess === '' && loadNote === '' ? verbSourceNote(resolved, declaredVerbs) : ''),
+      )
       return 1
     }
   }
 }
 
 // Re-exports for tests + programmatic embedders.
-export { detectFlow, parseRunArgs, resolveRunOptions, type RunArgs } from './run.js'
+export {
+  detectFlow,
+  parseConcurrency,
+  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 { parseInitArgs, type InitArgs } from './init.js'
 export { parseShowArgs, type ShowArgs } from './show.js'
 export { parseWhyArgs } from './why.js'
 export { parseLastArgs } from './last.js'
-export { parsePruneWorkspaceArgs } from './prune.js'
 export { formatBytes } from './format.js'
+export { registerCoreAlias } from './core-alias.js'
+
+/**
+ * Is this invocation asking for help rather than work? See the call site for
+ * why the scan stops at `--`, and why plugin verbs are excluded.
+ */
+function wantsHelp(command: string, rest: readonly string[]): boolean {
+  if (!(CORE_VERBS as readonly string[]).includes(command)) return false
+  const sep = rest.indexOf('--')
+  const own = sep === -1 ? rest : rest.slice(0, sep)
+  return own.includes('--help') || own.includes('-h')
+}
+
+/** ` Did you mean run?` for a verb within two edits of a core one, or of a
+ *  verb this workspace's plugins declare — the same hint a task or flag typo
+ *  gets. The plugin verbs come from the lookup that just failed, so they
+ *  cost no second load. */
+function didYouMeanVerb(verb: string, pluginVerbsHere: readonly string[] = []): string {
+  const best = nearest(verb, [...CORE_VERBS, ...pluginVerbsHere])
+  return best === undefined ? '' : `. Did you mean ${best}?`
+}
+
+/**
+ * Where a verb that is neither core nor declared COULD come from. Only when
+ * nothing is close enough to guess: after a plain typo the guess is the
+ * answer, and a second line would bury it.
+ */
+function verbSourceNote(resolved: unknown, declaredVerbs: readonly string[]): string {
+  if (declaredVerbs.length > 0) {
+    return `  This workspace's plugins declare: ${[...declaredVerbs].sort().join(', ')}.\n`
+  }
+  const here = resolved === null ? 'there is no workspace here' : 'this workspace declares none'
+  return `  A plugin declared in vx.workspace.ts can add verbs; ${here}.\n`
+}

package/src/cli/info.ts

@@ -1,110 +1,181 @@
 // `vx info` — workspace doctor printout. One screen of environment +
 // workspace + cache facts for bug reports and quick sanity checks.
-// `vx stats` is a deprecated alias (info absorbed it).
+// `vx stats` is a deprecated alias (info absorbed it). The facts come
+// from the orchestrator's `collectInfo` (doctor.ts), which `vx mcp` reads
+// too; this file parses the flags and renders the rows.
 
-import { Cache } from '../cache/index.js'
-import { VERSION } from '../version.js'
-import {
-  findWorkspaceRoot,
-  listProjects,
-  loadProjectConfig,
-  loadWorkspace,
-  loadWorkspaceConfig,
-  lockfilePath,
-  resolveCacheDir,
-} from '../workspace/index.js'
+import { collectInfo, type FlakyTask, type InfoFacts } from '../orchestrator/index.js'
+import { seeHelp } from './help.js'
+import { namedCacheDir, parseCacheDirFlag, warnToStderr } from './workspace-config.js'
 import { formatBytes } from './format.js'
+import { MIN_BUN } from '../util/index.js'
 
-export async function infoCmd(args: readonly string[]): Promise<number> {
-  if (args.length > 0) {
-    process.stderr.write(`vx info: unknown argument: ${args[0]}\n`)
-    return 1
-  }
-  const root = await findWorkspaceRoot(process.cwd())
-  const metas = await listProjects(await loadWorkspace(root))
+export interface InfoArgs {
+  format: 'pretty' | 'json'
+  /** `--cache-dir`: report on the cache a run with the same flag uses. */
+  cacheDir?: string
+  error?: string
+}
 
-  let taskCount = 0
-  await Promise.all(
-    metas.map(async (meta) => {
-      if (meta.configPath === null) return
-      // A broken config must not take the doctor down with it — it
-      // just contributes zero tasks to the count.
-      try {
-        const config = await loadProjectConfig(meta.configPath)
-        taskCount += Object.keys(config.tasks ?? {}).length
-      } catch {
-        // counted as zero
+function parseInfoArgs(args: readonly string[]): InfoArgs {
+  const out: InfoArgs = { format: 'pretty' }
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === '--format' || a?.startsWith('--format=')) {
+      const v = a === '--format' ? args[++i] : a.slice('--format='.length)
+      if (v !== 'pretty' && v !== 'json') {
+        return { ...out, error: `--format must be pretty or json${seeHelp('info')}` }
       }
-    }),
-  )
-
-  const cacheDir = resolveCacheDir(root, await loadWorkspaceConfig(root))
-  const cache = new Cache(cacheDir)
-  let stats
-  try {
-    stats = cache.stats()
-  } finally {
-    cache.close()
+      out.format = v
+      continue
+    }
+    const cd = parseCacheDirFlag(args, i)
+    if (cd !== null) {
+      if ('error' in cd) return { ...out, error: cd.error }
+      out.cacheDir = cd.cacheDir
+      i = cd.next
+      continue
+    }
+    return { ...out, error: `unknown argument: ${a}${seeHelp('info')}` }
   }
+  return out
+}
 
-  const lockPresent = await Bun.file(lockfilePath(root)).exists()
+export async function infoCmd(args: readonly string[]): Promise<number> {
+  const parsed = parseInfoArgs(args)
+  if (parsed.error) {
+    process.stderr.write(`vx info: ${parsed.error}\n`)
+    return 1
+  }
+  // `collectInfo` takes a resolved directory from `vx mcp` too, where one
+  // not made yet is a workspace that never ran; the flag is the user's,
+  // and a directory it names that is not there is a typo (item 900).
+  if (parsed.cacheDir !== undefined) namedCacheDir(parsed.cacheDir)
+  const facts = await collectInfo(process.cwd(), {
+    ...(parsed.cacheDir !== undefined ? { cacheDir: parsed.cacheDir } : {}),
+    warn: warnToStderr,
+  })
+  process.stdout.write(
+    parsed.format === 'json' ? `${JSON.stringify(facts, null, 2)}\n` : `${renderInfo(facts)}\n`,
+  )
+  return 0
+}
 
+export function renderInfo(f: InfoFacts): string {
   const rows: [string, string][] = [
-    ['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],
-    ['cache entries', `${stats.entryCount} (${formatBytes(stats.totalBytes)})`],
-    ['runs (24h)', `${stats.runCountLast24h} (${stats.hitCountLast24h} cache hits)`],
-    ['vx-lock.json', lockPresent ? 'yes' : 'no'],
+    ['vx', f.vx],
+    // The prose stays in the rendered row; `f.bun` itself is the bare
+    // version a script reads (doctor.ts says why).
+    [
+      'bun',
+      f.bunSupported
+        ? f.bun
+        : `${f.bun} — unsupported, vx needs >= ${MIN_BUN.join('.')}; answers may be wrong`,
+    ],
+    ['git', f.git ?? '(not found)'],
+    ['git status cache', renderGitStatusCache(f.gitStatusCache)],
+    ['workspace root', f.workspaceRoot],
+    ['projects', describeProjects(f)],
+    // Only when a config did not load: the count above says "zero" for
+    // it, and this row says which and why.
+    ...(f.configErrors.length > 0
+      ? ([['config errors', f.configErrors.map((e) => `${e.path}: ${e.message}`).join('; ')]] as [
+          string,
+          string,
+        ][])
+      : []),
+    ['plugins', describePlugins(f.plugins)],
+    ['workers', describeWorkers(f.workers)],
+    ['memory', describeMemory(f.memory)],
+    ['cache dir', f.cacheDir],
+    ['cache versions', `keys ${f.cacheVersion} · index schema ${f.schemaVersion}`],
+    ['cache entries', `${f.cacheEntries} (${formatBytes(f.cacheBytes)})`],
+    // Only when there is something to say.
+    ...(f.orphans.artifacts > 0
+      ? ([
+          [
+            'orphans',
+            `${f.orphans.artifacts} artifact${f.orphans.artifacts === 1 ? '' : 's'} (${formatBytes(f.orphans.bytes)}) the index does not know — \`vx cache prune\` reaps them`,
+          ],
+        ] as [string, string][])
+      : []),
+    // Task runs, not invocations (which `vx last` calls runs): the count
+    // the hits are a share of.
+    ['task runs (24h)', `${f.runs24h} (${f.hits24h} cache hits)`],
+    ['flaky tasks', describeFlakyTasks(f.flakyTasks)],
+    ['sandbox', describeSandbox(f.sandbox)],
+    ['vx-lock.json', f.lockfile ? 'yes' : 'no'],
   ]
   const labelW = Math.max(...rows.map(([label]) => label.length))
-  const lines = rows.map(([label, value]) => `${`${label}:`.padEnd(labelW + 1)} ${value}`)
-  process.stdout.write(`${lines.join('\n')}\n`)
-  return 0
+  return rows.map(([label, value]) => `${`${label}:`.padEnd(labelW + 1)} ${value}`).join('\n')
 }
 
-/** 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)'
-  }
+/**
+ * `available (3 tasks declare exec.sandbox)`, or `unavailable — <why>; 3
+ * tasks declare exec.sandbox and will fail`: a declared sandbox whose
+ * runtime cannot start fails the task, so the doctor names it before a run
+ * does.
+ */
+function describeSandbox(s: InfoFacts['sandbox']): string {
+  const declared = `${s.declared} task${s.declared === 1 ? '' : 's'} declare${s.declared === 1 ? 's' : ''} exec.sandbox`
+  if (s.available) return `available (${declared})`
+  return `unavailable — ${s.reason}; ${declared}${s.declared > 0 ? ' and will fail' : ''}`
 }
 
-function gitVersion(): string {
-  try {
-    const p = Bun.spawnSync({ cmd: ['git', '--version'], stdout: 'pipe', stderr: 'pipe' })
-    if (p.exitCode !== 0) return '(not found)'
-    return new TextDecoder()
-      .decode(p.stdout)
-      .trim()
-      .replace(/^git version /, '')
-  } catch {
-    return '(not found)'
+/** `4 — the CPU count`, `2 — cgroup CPU quota 2 of 8 cores`, `8 — vx.workspace.ts (4 cores)`. */
+export function describeWorkers(w: InfoFacts['workers']): string {
+  const quota = w.cpuQuota === null ? '' : `, cgroup CPU quota ${trimCores(w.cpuQuota)}`
+  if (w.source === 'workspace') return `${w.count} — vx.workspace.ts (${w.cores} cores${quota})`
+  if (w.source === 'cgroup')
+    return `${w.count} — cgroup CPU quota ${trimCores(w.cpuQuota ?? w.count)} of ${w.cores} cores`
+  return `${w.count} — the CPU count${quota}`
+}
+
+/** `13 GB usable — cgroup limit; the machine has 16 GB`, or `16 GB`. */
+export function describeMemory(m: InfoFacts['memory']): string {
+  if (m.cgroupLimitBytes !== null && m.usableBytes < m.totalBytes) {
+    return `${formatBytes(m.usableBytes)} usable — cgroup limit; the machine has ${formatBytes(m.totalBytes)}`
   }
+  return formatBytes(m.totalBytes)
+}
+
+function trimCores(n: number): string {
+  return Number.isInteger(n) ? String(n) : n.toFixed(2).replace(/0+$/, '')
+}
+
+/** `2 — app#test (3 of 7 runs failed on unchanged inputs); api#e2e (1 of 4)`, or `none`. */
+function describeProjects(f: InfoFacts): string {
+  const tasks = `${f.tasks} task${f.tasks === 1 ? '' : 's'}`
+  const n = f.configErrors.length
+  if (n === 0) return `${f.projects} (${tasks})`
+  return `${f.projects} (${tasks} · ${n} config${n === 1 ? '' : 's'} did not load)`
+}
+
+function describeFlakyTasks(tasks: readonly FlakyTask[]): string {
+  if (tasks.length === 0) return 'none'
+  const parts = tasks.map(
+    (t, i) =>
+      `${t.taskId} (${t.failures} of ${t.passes + t.failures} runs failed${i === 0 ? ' on unchanged inputs' : ''})`,
+  )
+  return `${tasks.length} — ${parts.join('; ')}`
+}
+
+function describePlugins(
+  plugins: ReadonlyArray<{ name: string; seams: readonly string[] }>,
+): string {
+  if (plugins.length === 0) return 'none'
+  const parts = plugins.map(
+    (p) => `${p.name} (${p.seams.length === 0 ? 'no seams' : p.seams.join(', ')})`,
+  )
+  return `${plugins.length} — ${parts.join('; ')}`
+}
+
+function renderGitStatusCache(c: InfoFacts['gitStatusCache']): string {
+  if (c === null) return '(unknown)'
+  if (c.fsmonitor && c.untrackedCache) return 'fsmonitor + untrackedCache on'
+  const missing = [
+    ...(c.fsmonitor ? [] : ['core.fsmonitor']),
+    ...(c.untrackedCache ? [] : ['core.untrackedCache']),
+  ]
+  return `${missing.join(', ')} off`
 }