@vzn/vx 0.0.636 → 0.0.637

package/src/cli/help.ts

@@ -102,19 +102,19 @@ export function verbHelpText(verb: string): string {
 
 export function helpText(pluginCommands: readonly string[] = []): string {
   return [
-    'vx — open, extensible monorepo task runner',
+    'vx — task orchestration you own',
     '',
     'Usage:',
     '  vx run [OPTIONS] [TASK | PKG#TASK ...] [-- forwarded-args...]',
-    '  vx watch [OPTIONS] TASK [-- forwarded-args...]',
-    '  vx cache prune [--older-than <duration>] [--max-size <size>] [--dry-run] [--format pretty|json] [--cache-dir <path>]',
+    '  vx watch [OPTIONS] [--poll] TASK [-- forwarded-args...]',
+    '  vx cache clean [--older-than <duration>] [--max-size <size>] [--global] [--dry-run] [--format pretty|json] [--cache-dir <path>]',
     '  vx lock [--check] [--format pretty|json]',
     '  vx init [--dry [--format pretty|json]] [--force] [--mjs] [--native|--keep] [--plugin <seam>]',
     '  vx upgrade [TAG]',
     '  vx show [PROJECT[#TASK] | TASK] [--filter <pattern>] [--affected[=<ref>]] [--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]] [--failed] [--log <task>] [--format pretty|json] [--cache-dir <path>]',
+    '  vx last [RUNID] [--list[=N]] [--failed] [--log <task>] [--stats [<task>] [--branch <name>]] [--format pretty|json] [--cache-dir <path>]',
     '  vx docs <query> [--limit N] [--format pretty|json]',
     '  vx completions bash|zsh|fish',
     '  vx help [VERB]',
@@ -126,56 +126,80 @@ 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 =',
-    '                             affectedBase, else origin/HEAD, else main or',
-    '                             master, else HEAD~1.',
+    '      --affected[=<base>]  Projects changed since <base>, and dependents',
+    '                             (--filter "...[<base>]"); default run.affectedBase,',
+    '                             else origin/HEAD, main, master, HEAD~1.',
     "  pkg#task                 Run a specific project's task directly.",
     '',
     'Execution (for run):',
-    '      --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>',
-    '                                  (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). Without it, VX_CACHE holds the spec.',
-    "      --cache-scope <name>        This run's cacheScope: trusted | read-only | a scope (pr-123).",
-    '                                  Beats VX_CACHE_SCOPE and the workspace cacheScope.',
-    '      --cache-dir <path>          Cache directory override (cwd-relative). Beats VX_CACHE_DIR,',
-    '                                  the workspace cacheDir field and the ~/.vx/<id>/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.',
-    '      --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',
-    '                                  (focused without --all/--filter/--affected, broad with, full in CI).',
-    '      --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.',
+    '  Each setting flag beats its VX_* variable, which beats .vx/workspace',
+    '  (docs/schema.md § Settings).',
+    '      --concurrency <n>           Max parallel tasks (default: usable cores);',
+    '                                  50% means half of them.',
+    '      --schedule <rule>           most-work (default) | critical-path |',
+    '                                  direct-dependents | ready-order.',
+    '      --branch <name>             The branch history records and forecasts read',
+    "                                  (default: git's, else the CI provider's).",
+    '      --exclude-dependencies[=names]  Skip dependsOn edges: all with no value,',
+    '                                  or a comma list of names.',
+    '      --no-cache                  No cache reads or writes; outputs are left',
+    '                                  alone.',
+    '      --force                     Skip cache reads but still write: every task',
+    '                                  runs and refreshes its entry.',
+    '      --cache-policy <spec>       Per-layer read/write: a comma list of',
+    '                                  <layer>:<flags> (layer local or remote, flags',
+    '                                  from rw). A named layer is set to exactly its',
+    '                                  flags; unnamed layers keep theirs. Examples:',
+    '                                  local:rw,remote:r (remote read-only), remote:',
+    '                                  (remote off), local:r (local read-only).',
+    "      --cache-scope <name>        This run's cache.scope (pr-123): write there,",
+    '                                  read the default keys first.',
+    '      --cache-dir <path>          Cache directory (cwd-relative); default',
+    '                                  .vx/cache, entries in ~/.vx/<id>/cache.',
+    '      --cache-download <mode>     all (default) | toplevel | none:',
+    '                                  where remote outputs land.',
+    '      --retries <n>               Up to <n> more runs of a failed task, for',
+    '                                  tasks without their own exec.retries. Not',
+    '                                  folded into cache keys.',
+    "      --timeout <duration>        A task's time limit (30s, 10m), for tasks",
+    '                                  without their own exec.timeout. A task past it',
+    '                                  is killed and fails.',
+    '      --kill-grace <duration>     How long a task that ignores SIGTERM gets',
+    '                                  before SIGKILL (default 2s).',
+    "      --teardown-timeout <duration>  The bound on each plugin's end-of-run flush",
+    '                                  (default 3s).',
+    '      --ready-notice <duration>   When vx says a persistent task still waits for',
+    '                                  readyWhen (default 10s).',
+    '      --continue[=<mode>]         What a failed task takes down: never | deps-ok',
+    '                                  (default, skips its dependents) | always (bare',
+    '                                  form; dependents run, never save).',
+    '      --output-logs <mode>        full | errors-only | hash-only | none, over',
+    '                                  the flow default (focused without',
+    '                                  --all/--filter/--affected, broad with, full in',
+    '                                  CI).',
+    '      --verbosity <n>             0 (default), or 1 and up for a per-task',
+    '                                  summary table after the run.',
     '',
     'Planning (for run — skips execution):',
-    '      --dry[=text|json]    Print the task graph + cache hit/miss prediction.',
+    "      --dry[=text|json]    Print the task graph and each task's predicted hit",
+    '                           or miss.',
     '      --graph[=<path>]     Emit Graphviz DOT (stdout if no path).',
     '',
     'Artifacts (for run):',
-    '      --format <fmt>        pretty (default) | json: print the --summarize document',
-    '                            on stdout when the run ends; every other line goes to stderr.',
+    '      --format <fmt>        pretty (default) | json: print the --summarize',
+    '                            document on stdout when the run ends; every other',
+    '                            line goes to stderr.',
     '      --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.',
+    '      --report-file <path>  Append that report to <path> ($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',
     '  cache, distributed execution, and telemetry export are provided by',
-    '  PLUGINS declared in vx.workspace.ts — first-party or your own. Core',
+    '  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/',
     '',
@@ -194,24 +218,27 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                             Uses the same flags as `vx run` except --dry /',
     '                             --graph / --summarize / --profile / --report /',
     '                             --report-file / --verbosity (they plan or report',
-    '                             one run). Press Ctrl+C to stop. Cache means most',
+    '                             one run), plus --poll (watch.poll: poll instead of',
+    '                             the OS watcher). 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).',
+    '  vx cache clean --older-than 30d     Evict entries last accessed > 30 days ago.',
+    '  vx cache clean --max-size 1G        Keep total cache under 1 GB (LRU eviction).',
+    "  vx cache clean                      Clear .vx/cache and this repo's store ~/.vx/<id>/cache.",
+    "      --global                        Clear every repo's store under ~/.vx.",
     '      --dry-run                       Say what the policy would reap; delete nothing.',
     '      --format <fmt>                  pretty (default) | json.',
     '      --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).',
+    '  Duration units: ms, 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 <project>    Print the project's resolved config as a run reads",
+    '                       it from 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.',
     "      --filter <pattern>  The list (or a task's projects) as `vx run --filter` selects.",
@@ -234,25 +261,27 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '      --failed         Only failed runs: the latest one, or with --list the list.',
     "      --log <task>     That task's output in the run (latest that ran it): a failure's",
     '                       or the cached log; none for an uncached pass.',
+    '      --stats [<task>] Per-task p50/p99, pass and hit rate, failure mode, peak',
+    '                       RSS and CPU over the last 50 runs; a task id or name narrows.',
+    "      --branch <name>  The branch --stats' p50 forecasts from (default: the run's).",
     '      --format <fmt>   pretty (default) | json.',
     '  info, why and last:',
     '      --cache-dir <path>  Read the cache a run with the same flag uses.',
     '',
     'Migration:',
-    '  vx init              Generate vx.workspace.ts + one vx.config.ts per package',
-    '                       from package.json scripts. Unmappable settings become',
-    '                       TODO(vx-migrate) comments. Beside turbo.json or nx.json:',
-    '                       runs @vzn/vx-migrate, which asks native or keep.',
+    '  vx init              With no package.json: write .vx/workspace.ts and an empty',
+    '                       root vx.config.ts. With one: runs @vzn/vx-migrate, which maps',
+    '                       turbo.json, an Nx graph or package.json scripts to one',
+    '                       vx.config.ts per package (asking native or keep in Turbo/Nx).',
     '      --dry            Print the generated files instead of writing them.',
     '      --format json    With --dry: the plan as one JSON document (schemas/init.json).',
     '      --force          Overwrite existing vx.config.* files.',
     '      --mjs            Write .mjs files (no type import) instead of .ts.',
     '      --native         Turbo or Nx: write a vx.config.ts per package (no question).',
-    '      --keep           Turbo or Nx: only vx.workspace.ts, declaring turbo() or nx().',
+    '      --keep           Turbo or Nx: only .vx/workspace.ts, declaring turbo() or nx().',
     '      --plugin <seam>  Instead: write plugins/<seam>.ts, a runnable plugin, and its',
     '                       test (executor, cache, telemetry, schedule, admit, commands,',
     '                       project, graph, key).',
-    '  From turbo.json or an Nx project graph: `vx init` runs `@vzn/vx-migrate` (its own package).',
     '',
     'Shell completions:',
     '  vx completions <shell>   Print a completion script for bash, zsh or fish: the',
@@ -269,14 +298,15 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '      --format json    {query, hits: [{page, heading, url, text}]}.',
     '',
     '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              Evaluate every vx.config in the current environment, check',
+    '                       the graph rules (run.rules) and freeze the resolved objects',
+    '                       into .vx/projects.lock.json, the only place a run reads configs',
+    '                       from. A run never evaluates one, never checks the rules',
+    '                       and never writes the lock: with none it fails.',
     '  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. With --format json it prints',
+    '                       re-evaluation compared against the frozen objects, and the',
+    '                       graph rules. Exits 1 on drift (e.g. configs that read env',
+    '                       vars). Run it before the run in CI. With --format json it prints',
     '                       {upToDate, audited, notAudited, problems}.',
     '',
     ...(pluginCommands.length > 0 ? ['Plugin commands:', ...pluginCommands, ''] : []),
@@ -315,7 +345,7 @@ export function refusedWord(arg: string): string {
  * `(did you mean --concurrency?)` for a flag within two edits of one `verb`
  * accepts; empty for anything else (a positional included). A third edit
  * is allowed only between flags that share their first five characters,
- * so `--retries` reaches `--retry` while `--zzz` does not reach `--all`.
+ * so `--timeouts` reaches `--timeout` while `--zzz` does not reach `--all`.
  */
 export function flagHint(verb: string, arg: string): string {
   if (!arg.startsWith('-')) return ''
@@ -343,8 +373,8 @@ export function flagHint(verb: string, arg: string): string {
  * 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. Only the flag an option line
- * OPENS with is one: `--frozen`'s line says "pair with vx lock --check", and
- * reading every flag on it put `--check` in the list, so `vx run --chek`
+ * OPENS with is one: an option line that named `vx lock --check` once put
+ * `--check` in the list, so `vx run --chek`
  * was told "did you mean --check?" and `--check` was then refused.
  */
 export function documentedFlags(verb: string, text = helpText()): string[] {
@@ -354,8 +384,9 @@ export function documentedFlags(verb: string, text = helpText()): string[] {
     if (/^[A-Z][A-Za-z ]*(?: \(for [a-z]+\))?:$/.test(line))
       inVerb = line.endsWith(`(for ${verb}):`)
     if (!inVerb) continue
-    const own = /^\s+(--[a-zA-Z][a-zA-Z-]*)/.exec(line)
-    if (own !== null) flags.add(own[1]!)
+    // `--x, --no-x`: a flag and its negation.
+    const own = /^\s+(--[a-zA-Z][a-zA-Z-]*)(?:, (--[a-zA-Z][a-zA-Z-]*))?/.exec(line)
+    if (own !== null) for (const f of own.slice(1)) if (f !== undefined) flags.add(f)
   }
   return [...flags]
 }

package/src/cli/index.ts

@@ -2,13 +2,16 @@
 // handler lives in a sibling `<name>.ts`; tests import its parsers there.
 
 import { VERSION } from '../version.js'
+import { checkSettingsEnv } from '../settings.js'
 import { CORE_VERBS, flagHint, printHelp, refusedWord, seeHelp } from './help.js'
 import { FOREIGN_VERBS } from './foreign-flags.js'
 import {
   errorDocument,
+  hideEnvFromTasks,
+  isFsRefusal,
+  isOutOfFds,
   isUserError,
   maskedLine,
-  MOVED_VERBS,
   nearest,
   UserError,
   wantsJson,
@@ -24,6 +27,7 @@ const plugins = () => import('./plugin-commands.js')
 
 export async function run(argv: readonly string[]): Promise<number> {
   const [command, ...rest] = argv
+  await hideEnvFromTasks()
 
   // `vx <verb> --help` is the universal reflex, and every verb answered
   // `unknown flag: --help` and exited 1 (walkthrough, 2026-09-04). Only args
@@ -34,7 +38,33 @@ export async function run(argv: readonly string[]): Promise<number> {
     await printHelp(await (await plugins()).pluginCommandHelp(), command)
     return 0
   }
+  // Each setting's variable once, before any verb: a renamed one is named,
+  // and a deep reader trusts what it reads.
+  checkSettingsEnv()
 
+  try {
+    return await dispatch(command, rest)
+  } catch (err) {
+    throw await brokenLockNamed(err)
+  }
+}
+
+/**
+ * A crash from a hand-broken lock entry is that entry's fault: runs validate
+ * no entry, so it surfaced as a raw TypeError (M, 2026-10-14). The lock is
+ * read only on the crash path, so a normal run pays nothing.
+ */
+async function brokenLockNamed(err: unknown): Promise<unknown> {
+  if (isUserError(err) || isFsRefusal(err) || isOutOfFds(err)) return err
+  try {
+    const { findWorkspaceRoot, LOCK_INVALID, lockEntryBroken } =
+      await import('../workspace/index.js')
+    if (lockEntryBroken(await findWorkspaceRoot(process.cwd()))) return new UserError(LOCK_INVALID)
+  } catch {}
+  return err
+}
+
+async function dispatch(command: string | undefined, rest: string[]): Promise<number> {
   switch (command) {
     case undefined: {
       // A bare `vx` where no workspace is printed 151 lines of help, none
@@ -65,7 +95,7 @@ export async function run(argv: readonly string[]): Promise<number> {
         // for the whole reference: it printed 145 lines and no hint.
         const resolved = await (await plugins()).resolvePluginCommand(verb)
         const unknown = resolved === null || 'declaredVerbs' in resolved
-        const pointer = MOVED_VERBS[verb] ?? FOREIGN_VERBS[verb]
+        const pointer = FOREIGN_VERBS[verb]
         if (unknown && pointer !== undefined) {
           process.stderr.write(`${pointer}\n`)
           return 1
@@ -171,12 +201,11 @@ export async function run(argv: readonly string[]): Promise<number> {
       }
       const loadNote =
         resolved !== null && 'loadError' in resolved
-          ? `\n  (plugin verbs could not be looked up: vx.workspace failed to load: ${resolved.loadError})`
+          ? `\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] ?? FOREIGN_VERBS[command]
+      // Another tool's verb: the pointer, but only after the plugins had
+      // their chance — a workspace that declares a plugin verb of that name keeps it.
+      const moved = FOREIGN_VERBS[command]
       if (moved !== undefined) {
         return unknown(`${moved}${loadNote}\n`)
       }
@@ -198,7 +227,7 @@ export async function run(argv: readonly string[]): Promise<number> {
       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.
+        // 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.
@@ -213,10 +242,10 @@ export async function run(argv: readonly string[]): Promise<number> {
       // 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).
+      // line says where a verb can come from: a typo of a plugin verb read
+      // as a plain unknown command, and a plugin verb before the plugin was
+      // declared said nothing about the file that would declare it
+      // (2026-09-20).
       // A word that opens with a dash is a flag, and vx itself takes only
       // --help and --version: "unknown command: --bogus" named the wrong
       // thing (M-60).
@@ -268,5 +297,5 @@ function verbSourceNote(resolved: unknown, declaredVerbs: readonly string[]): st
     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`
+  return `  A plugin declared in .vx/workspace.ts can add verbs; ${here}.\n`
 }

package/src/cli/info.ts

@@ -1,8 +1,7 @@
 // `vx info` — workspace doctor printout. One screen of environment +
 // workspace + cache facts for bug reports and quick sanity checks.
 // The facts come
-// from the orchestrator's `collectInfo` (doctor.ts), which `vx mcp` reads
-// too; this file parses the flags and renders the rows.
+// from the orchestrator's `collectInfo` (doctor.ts); this file parses the flags and renders the rows.
 
 import os from 'node:os'
 import { collectInfo, type FlakyTask, type InfoFacts } from '../orchestrator/index.js'
@@ -10,6 +9,7 @@ import { flagHint, formatValue, refuse, refusedWord, seeHelp } from './help.js'
 import { namedCacheDir, parseCacheDirFlag, warnToStderr } from './workspace-config.js'
 import { formatBytes } from './format.js'
 import { MIN_BUN } from '../util/index.js'
+import { envName } from '../settings.js'
 
 interface InfoArgs {
   format: 'pretty' | 'json'
@@ -46,7 +46,7 @@ export function parseInfoArgs(args: readonly string[]): InfoArgs {
 export async function infoCmd(args: readonly string[]): Promise<number> {
   const parsed = parseInfoArgs(args)
   if (parsed.error) return refuse('info', args, parsed.error, 'VX_E_USAGE')
-  // `collectInfo` takes a resolved directory from `vx mcp` too, where one
+  // `collectInfo` takes a resolved directory, 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)
@@ -55,14 +55,17 @@ export async function infoCmd(args: readonly string[]): Promise<number> {
     warn: warnToStderr,
   })
   process.stdout.write(
-    parsed.format === 'json' ? `${JSON.stringify(facts, null, 2)}\n` : `${renderInfo(facts)}\n`,
+    parsed.format === 'json' ? `${JSON.stringify(facts)}\n` : `${renderInfo(facts)}\n`,
   )
   return 0
 }
 
 export function renderInfo(f: InfoFacts): string {
   const rows: [string, string][] = [
-    ['vx', f.vx],
+    [
+      'vx',
+      `${f.vx} (${tildePath(f.vxPath)}${f.handedOffFrom === null ? '' : `, handed off from ${tildePath(f.handedOffFrom)}`})`,
+    ],
     // The prose stays in the rendered row; `f.bun` itself is the bare
     // version a script reads (doctor.ts says why).
     [
@@ -75,24 +78,25 @@ export function renderInfo(f: InfoFacts): string {
     ['git status cache', renderGitStatusCache(f.gitStatusCache)],
     ['workspace root', tildePath(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', tildePath(f.cacheDir)],
+    [
+      'cache dir',
+      `${tildePath(f.cacheDir)} (${formatBytes(f.cacheDirBytes)}, ${f.cacheStore === null ? 'the entries and ' : ''}this workspace's run history)`,
+    ],
     [
       'cache store',
-      f.cacheStore === null ? 'none: the cache dir holds the entries' : tildePath(f.cacheStore),
+      f.cacheStore === null
+        ? 'none: the cache dir holds the entries'
+        : `${tildePath(f.cacheStore)} (${formatBytes(f.cacheStoreBytes ?? 0)}, shared by this repo's checkouts)`,
     ],
     ['cache versions', `keys ${f.cacheVersion} · index schema ${f.schemaVersion}`],
     ['cache entries', describeEntries(f)],
+    // Only the settings a variable or the workspace changed.
+    ...(Object.values(f.settings).some((s) => s.source !== 'default')
+      ? ([['settings', describeSettings(f.settings)]] as [string, string][])
+      : []),
     ...(f.cacheRetention !== null
       ? ([['cache retention', describeRetention(f.cacheRetention)]] as [string, string][])
       : []),
@@ -101,7 +105,7 @@ export function renderInfo(f: InfoFacts): string {
       ? ([
           [
             'orphans',
-            `${f.orphans.artifacts} artifact${f.orphans.artifacts === 1 ? '' : 's'} (${formatBytes(f.orphans.bytes)}) the index does not know — \`vx cache prune\` reaps them`,
+            `${f.orphans.artifacts} artifact${f.orphans.artifacts === 1 ? '' : 's'} (${formatBytes(f.orphans.bytes)}) the index does not know — \`vx cache clean\` reaps them`,
           ],
         ] as [string, string][])
       : []),
@@ -116,7 +120,7 @@ export function renderInfo(f: InfoFacts): string {
     ],
     ['flaky tasks', describeFlakyTasks(f.flakyTasks)],
     ['sandbox', describeSandbox(f.sandbox)],
-    ['vx-lock.json', f.lockfile ? 'yes' : 'no'],
+    ['projects lock', f.lockfile ? 'yes' : 'no'],
   ]
   const labelW = Math.max(...rows.map(([label]) => label.length))
   return rows.map(([label, value]) => `${`${label}:`.padEnd(labelW + 1)} ${value}`).join('\n')
@@ -132,6 +136,20 @@ function describeEntries(f: InfoFacts): string {
   return `${f.cacheEntries} (${size})`
 }
 
+/**
+ * The settings not at their default, with where each came from:
+ * `run.timeout 30m (VX_RUN_TIMEOUT), cache.policy local:rw (.vx/workspace)`.
+ */
+function describeSettings(settings: InfoFacts['settings']): string {
+  return Object.entries(settings)
+    .filter(([, s]) => s.source !== 'default')
+    .map(
+      ([path, s]) =>
+        `${path} ${String(s.value)} (${s.source === 'env' ? envName(path) : '.vx/workspace'})`,
+    )
+    .join(', ')
+}
+
 /** What a run's end evicts: `entries unused for 30d, and the oldest entries past 10G`. */
 function describeRetention(r: NonNullable<InfoFacts['cacheRetention']>): string {
   const parts = [
@@ -163,10 +181,10 @@ function describeSandbox(s: InfoFacts['sandbox']): string {
   return `unavailable — ${s.reason}; ${declared}${s.declared > 0 ? ' and will fail' : ''}`
 }
 
-/** `4 — the CPU count`, `2 — cgroup CPU quota 2 of 8 cores`, `8 — vx.workspace.ts (4 cores)`. */
+/** `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 === '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}`
@@ -186,10 +204,7 @@ function trimCores(n: number): string {
 
 /** `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)`
+  return `${f.projects} (${f.tasks} task${f.tasks === 1 ? '' : 's'})`
 }
 
 function describeFlakyTasks(tasks: readonly FlakyTask[]): string {