@vzn/vx 0.0.638 → 0.0.640

package/src/cli/completions.ts

@@ -21,8 +21,8 @@ const SHELLS: readonly CompletionShell[] = ['bash', 'zsh', 'fish']
 /**
  * `--help` and every flag the verb accepts. Not every `--flag` its help cut
  * mentions: the cut's prose names other verbs' flags, and `vx watch`
- * completed only `--dry --graph --summarize --profile`, the four its line
- * says it refuses, while `vx show` offered `--run` and `--list`.
+ * completed only the flags its help line says it refuses, while `vx show`
+ * offered `--run` and `--list`.
  */
 export function verbFlags(verb: string): string[] {
   return [...new Set(['--help', ...acceptedFlags(verb)])]

package/src/cli/foreign-flags.ts

@@ -22,8 +22,7 @@ interface ForeignFlag {
   /**
    * The runner reads `=true` / `=false` on it (Turbo's `--force [FORCE]`,
    * Nx's yargs booleans): `=false` is the flag left out, `=true` the flag
-   * bare. `--skip-nx-cache=false` forced every task, `--summarize=true`
-   * wrote the summary to a file named `true`.
+   * bare: `--skip-nx-cache=false` forced every task.
    */
   bool?: true
   /** For an alias: the vx argv. For a refusal: none. */
@@ -47,8 +46,6 @@ const nxPattern = (p: string): string => {
   return p
 }
 
-const GRAPH_IMAGE = /\.(svg|png|jpe?g|pdf|json|html|mermaid)$/i
-
 export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
   {
     runner: 'turbo',
@@ -98,21 +95,12 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     vx: '`--dry[=text|json]`',
     to: (v) => [v === undefined ? '--dry' : `--dry=${v}`],
   },
-  {
-    runner: 'turbo',
-    names: ['--graph'],
-    value: true,
-    when: (v) => v !== undefined && GRAPH_IMAGE.test(v),
-    shown: '`--graph=<file>.svg|png|json|html|…`',
-    outcome: 'refuse',
-    vx: 'vx writes Graphviz DOT only: `--graph=<file>.dot`, then `dot -Tsvg`',
-  },
   {
     runner: 'turbo',
     names: ['--graph'],
     value: false,
-    outcome: 'same',
-    vx: '`--graph[=<file>.dot]`',
+    outcome: 'refuse',
+    vx: '`--dry=json` prints the planned task graph, each task with its deps',
   },
   {
     runner: 'turbo',
@@ -133,9 +121,8 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     runner: 'turbo',
     names: ['--summarize'],
     value: false,
-    bool: true,
-    outcome: 'same',
-    vx: '`--summarize[=<path>]`',
+    outcome: 'refuse',
+    vx: "use `vx last --format json` for the run's JSON record",
   },
   {
     runner: 'turbo',
@@ -263,7 +250,8 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     runner: 'nx',
     names: ['--parallel'],
     value: true,
-    when: (v) => v !== undefined && v !== 'true',
+    // Nx's value is a count or `false`; a word after it is a task name.
+    when: (v) => v === 'false' || (v !== undefined && /^\d+$/.test(v)),
     shown: '`--parallel <n>`',
     outcome: 'alias',
     vx: '`--concurrency <n>` (`--parallel=false` is 1)',
@@ -355,21 +343,21 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     names: ['--global-deps'],
     value: true,
     outcome: 'refuse',
-    vx: "declare them in `cache.inputs.workspaceFiles` (under `turbo()`, turbo.json's `globalDependencies`)",
+    vx: "declare them in `inputs.workspaceFiles` (under `turbo()`, turbo.json's `globalDependencies`)",
   },
   {
     runner: 'turbo',
     names: ['--json'],
     value: false,
     outcome: 'refuse',
-    vx: "use `--format json` for the run's result on stdout, `--dry=json` for the plan",
+    vx: "use `vx last --format json` for the run's result, `--dry=json` for the plan",
   },
   {
     runner: 'turbo',
     names: ['--log-file'],
     value: false,
     outcome: 'refuse',
-    vx: "use `--summarize[=<path>]` for the run's JSON record",
+    vx: "use `vx last --format json` for the run's JSON record",
   },
   {
     runner: 'turbo',
@@ -664,7 +652,7 @@ export const FOREIGN_VERBS: Readonly<Record<string, string>> = {
     '`nx run-many` is `vx run <task> --all` here; -t, -p, --exclude and --parallel work as they are',
   affected:
     '`nx affected` is `vx run <task> --affected` here; -t, --base and --exclude work as they are',
-  graph: '`nx graph` is `vx run <task> --graph[=<file>.dot]` here: the task graph as Graphviz DOT',
+  graph: '`nx graph` is `vx run <task> --dry=json` here: the planned task graph as JSON',
   ls: '`turbo ls` is `vx show` here: every project, its directory and its task count',
   query:
     '`turbo query` has no vx form: `vx run <task> --dry=json` prints the planned graph as JSON',

package/src/cli/help.ts

@@ -171,12 +171,6 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     "      --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).',
@@ -190,18 +184,9 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     'Planning (for run — skips execution):',
     "      --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.',
-    '      --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> ($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',
@@ -223,12 +208,11 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '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 / --report /',
-    '                             --report-file / --verbosity (they plan or report',
-    '                             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).',
+    '                             --profile / --verbosity (they plan or report 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 clean --older-than 30d     Evict entries last accessed > 30 days ago.',
@@ -402,16 +386,7 @@ export function documentedFlags(verb: string, text = helpText()): string[] {
  * The `vx run` flags `vx watch` refuses: each plans or reports ONE run
  * (`watchRefusal` in watch.ts, held to this list by a test).
  */
-export const WATCH_REFUSED_FLAGS: readonly string[] = [
-  '--dry',
-  '--graph',
-  '--summarize',
-  '--profile',
-  '--report',
-  '--report-file',
-  '--verbosity',
-  '--format',
-]
+export const WATCH_REFUSED_FLAGS: readonly string[] = ['--dry', '--profile', '--verbosity']
 
 /**
  * The flags one verb accepts: those on its own Usage line, and for a verb

package/src/cli/info.ts

@@ -4,7 +4,8 @@
 // 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'
+import { collectInfo, type InfoFacts } from '../orchestrator/index.js'
+import { type FlakyTask } from '../history/index.js'
 import { flagHint, formatValue, refuse, refusedWord, seeHelp } from './help.js'
 import { namedCacheDir, parseCacheDirFlag, warnToStderr } from './workspace-config.js'
 import { formatBytes } from './format.js'

package/src/cli/init.ts

@@ -13,7 +13,7 @@ import { gitTop, workspaceFileWritten } from '../handoff.js'
 import { flagHint, formatValue, refuse, seeHelp } from './help.js'
 import { lockAfterMigration } from './lock.js'
 import { PLUGIN_TEMPLATES } from './plugin-templates.js'
-import { isCompiledBinary } from './upgrade.js'
+import { isCompiledBinary, targetVersion } from './upgrade.js'
 import { VERSION } from '../version.js'
 import { DOT_VX_GITATTRIBUTES, DOT_VX_GITIGNORE, ui, UserError, sayNotice } from '../util/index.js'
 import {
@@ -217,8 +217,11 @@ async function starter(root: string, noGit: boolean, args: InitArgs): Promise<nu
 }
 
 /**
- * A repo with a package.json is `@vzn/vx-migrate`'s: the installed one,
- * else this version's through `bun x`. It finds the root itself, asks a
+ * A repo with a package.json is `@vzn/vx-migrate`'s, at the latest
+ * release: it installs @vzn/vx and every @vzn/vx-* plugin the root lists
+ * at its own version, so init always lands on latest with all of them
+ * together, as `vx upgrade` moves them (M, 2026-10-16: an installed 0.0.637
+ * pinned core back from 0.0.639). It finds the root itself, asks a
  * terminal native or keep in a Turbo or Nx repo, and installs what it writes.
  */
 async function migrate(dirs: readonly string[], args: InitArgs): Promise<number> {
@@ -229,21 +232,30 @@ async function migrate(dirs: readonly string[], args: InitArgs): Promise<number>
     args.mode !== undefined && `--${args.mode}`,
     args.json === true && '--format=json',
   ].filter((f): f is string => typeof f === 'string')
-  return Bun.spawn(migrateCommand(dirs, flags), {
+  // An exact version: `bun x` may answer `@latest` from its cache.
+  const latest = VERSION === '0.0.0' ? 'latest' : await targetVersion(undefined, 'vx init')
+  return Bun.spawn(migrateCommand(dirs, flags, latest), {
     stdio: ['inherit', 'inherit', 'inherit'],
     // A compiled vx is a Bun runtime only when told so.
     env: isCompiledBinary() ? { ...process.env, BUN_BE_BUN: '1' } : process.env,
   }).exited
 }
 
-export function migrateCommand(dirs: readonly string[], flags: readonly string[]): string[] {
-  for (const d of dirs) {
-    const installed = path.join(d, 'node_modules', '@vzn', 'vx-migrate', 'src', 'bin.ts')
-    if (existsSync(installed)) return [process.execPath, '--no-install', installed, ...flags]
+export function migrateCommand(
+  dirs: readonly string[],
+  flags: readonly string[],
+  latest: string,
+  running = VERSION,
+): string[] {
+  // A source checkout (0.0.0, which npm never had) runs the vx-migrate
+  // beside it; a release never runs an installed one.
+  if (running === '0.0.0') {
+    for (const d of dirs) {
+      const installed = path.join(d, 'node_modules', '@vzn', 'vx-migrate', 'src', 'bin.ts')
+      if (existsSync(installed)) return [process.execPath, '--no-install', installed, ...flags]
+    }
   }
-  // A source checkout is 0.0.0, which npm never had.
-  const version = VERSION === '0.0.0' ? 'latest' : VERSION
   // Bun's own install output ("Slow filesystem detected…") in a pnpm or npm
   // repo reads as a stranger speaking (Growth's first-run funnel F2).
-  return [process.execPath, 'x', '--silent', `@vzn/vx-migrate@${version}`, ...flags]
+  return [process.execPath, 'x', '--silent', `@vzn/vx-migrate@${latest}`, ...flags]
 }

package/src/cli/last.ts

@@ -9,21 +9,25 @@ import { Cache } from '../cache/index.js'
 import { formatBytes } from './format.js'
 import { flagHint, formatValue, seeHelp } from './help.js'
 import {
-  currentBranch,
-  exitSignal,
   type FailureMode,
   getInvocation,
   getRun,
   type InvocationDetail,
   listInvocations,
   LocalHistoryProvider,
-  outcomeWord,
   type RunSummaryRow,
+} from '../history/index.js'
+import {
+  currentBranch,
+  exitSignal,
   resolveRunId,
   runFailures,
+  type RunStep,
+  runSteps,
   shortRunId,
   taskLog,
 } from '../orchestrator/index.js'
+import { outcomeWord } from '../report/index.js'
 import { formatElapsed, refusal, splitTaskId, UserError, sayNotice, ui } from '../util/index.js'
 import { findWorkspaceRoot } from '../workspace/index.js'
 import { cliCacheDir, parseCacheDirFlag } from './workspace-config.js'
@@ -319,12 +323,29 @@ function reasonParts(t: RunSummaryRow): string {
   } else if (t.status === 'skipped' && t.blockedBy !== null) {
     parts.push(`after ${t.blockedBy} failed`)
   }
+  if (t.remoteError !== null) parts.push(`remote \u2717 ${t.remoteError}`)
   return parts.map((p) => `  ${p}`).join('')
 }
 
 /** Hit rows shown before the rest fold — the slowest restores. */
 const HITS_SHOWN = 16
 
+/**
+ * The steps the run did not wait on (`vx:prefetch`), which its own output
+ * never showed (M, 2026-10-16): here for debugging, marked `internal`.
+ */
+function formatStepRows(steps: readonly RunStep[]): string[] {
+  if (steps.length === 0) return []
+  const idW = Math.max(...steps.map((s) => s.id.length), 4)
+  return [
+    '',
+    ...steps.map(
+      (s) =>
+        `  ${(s.ok ? 'success' : 'failed').padEnd(17)} ${s.id.padEnd(idW)}  ${fmtMs(s.durationMs).padStart(8)}  internal`,
+    ),
+  ]
+}
+
 /**
  * The per-task rows: failures first, then what executed or was skipped,
  * then cache hits. Hits are the noise of a warm run — 996 of a thousand
@@ -333,6 +354,7 @@ const HITS_SHOWN = 16
  * count; the ones shown are the slowest restores, the one thing a hit's
  * row tells. `--format json` lists every row.
  */
+
 export function formatTaskRows(tasks: readonly RunSummaryRow[]): string[] {
   if (tasks.length === 0) return []
   const failed = tasks.filter((t) => t.status === 'failed')
@@ -542,7 +564,10 @@ export async function lastCmd(args: readonly string[]): Promise<number> {
               ...(f.fixedIn !== undefined ? { fixedIn: f.fixedIn } : {}),
             }
       })
-      process.stdout.write(`${JSON.stringify({ invocation: inv, tasks })}\n`)
+      const steps = runSteps(cacheDir, inv.runId)
+      process.stdout.write(
+        `${JSON.stringify({ invocation: inv, tasks, ...(steps.length > 0 ? { steps } : {}) })}\n`,
+      )
       return 0
     }
 
@@ -560,6 +585,7 @@ export async function lastCmd(args: readonly string[]): Promise<number> {
         `${inv.failedCount > 0 ? ` · ${inv.failedCount} failed` : ''}`,
     )
     lines.push(...formatTaskRows(detail?.tasks ?? []))
+    lines.push(...formatStepRows(runSteps(cacheDir, inv.runId)))
     // The next command after reading a failed run, with the arguments the
     // run forwarded to the tasks that got them (a failure under `-- --shard
     // 2` is that shard's); a dependency never got them, so its line has none.

package/src/cli/plan-format.ts

@@ -1,4 +1,4 @@
-// Formatters for `--dry-run` (human / JSON) and `--graph` (DOT).
+// Formatters for `--dry` (human / JSON).
 
 import type { AffectedReason, CacheStatus, RunPlan } from '../orchestrator/index.js'
 import { formatElapsed, maskedCommand } from '../util/index.js'
@@ -9,7 +9,7 @@ import { formatElapsed, maskedCommand } from '../util/index.js'
  * task with recorded history also shows its typical duration (~p50).
  *
  *   would run:
- *     ◉  @vzn/vx#lint       cache hit (local)        abc12345
+ *     ✓  @vzn/vx#lint       cache hit (local)        abc12345
  *     ↓  @vzn/vx#test       cache hit (remote)       def67890
  *     ▶  @vzn/vx#build      cache miss — would exec  fedcba98  ~1.20s
  *
@@ -33,7 +33,7 @@ export function formatPlanText(plan: RunPlan): string {
   for (const t of real) {
     // `@noop`: the run succeeds it without running, whatever its key says.
     const skipped = t.executor === 'noop'
-    const sym = skipped ? '∅' : symbolFor(t.cacheStatus)
+    const sym = skipped ? '·' : symbolFor(t.cacheStatus)
     const desc = skipped ? 'noop — would not run' : describe(t.cacheStatus)
     const shortHash = t.hash ? t.hash.slice(0, 8) : ''
     const executes = !skipped && (t.cacheStatus === 'miss' || t.cacheStatus === 'no-cache')
@@ -186,52 +186,16 @@ export function formatPlanJson(plan: RunPlan, affectedBase?: string): string {
   )
 }
 
-/**
- * Render the task graph as a Graphviz DOT document. Includes group
- * nodes — they're real nodes in the graph (just not real units of
- * work), and a `--graph` consumer wants to see the whole structure.
- *
- * Layout: `rankdir=LR`. Node fillcolor varies by predicted cache
- * status so a quick visual scan tells you which boxes get to skip
- * actual work.
- */
-export function formatGraphDot(plan: RunPlan): string {
-  const lines: string[] = ['digraph TaskGraph {', '  rankdir=LR;', '  node [shape=box];']
-  for (const t of plan.tasks) {
-    const color = dotColor(t.cacheStatus)
-    lines.push(
-      `  ${dotString(t.node.id)} [label=${dotString(`${t.node.id}\n${t.hash.slice(0, 8)}`)}, style="filled", fillcolor="${color}"];`,
-    )
-  }
-  for (const t of plan.tasks) {
-    for (const dep of t.deps) {
-      lines.push(`  ${dotString(dep)} -> ${dotString(t.node.id)};`)
-    }
-  }
-  lines.push('}')
-  return lines.join('\n') + '\n'
-}
-
-/**
- * A DOT double-quoted ID. A task name is any object key in a config, so
- * `"`, `\` and a newline are all reachable; unescaped they end the
- * string early and the document stops parsing. `\n` is DOT's own line
- * break inside a label.
- */
-function dotString(s: string): string {
-  return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\r?\n/g, '\\n')}"`
-}
-
 function symbolFor(s: CacheStatus): string {
   switch (s) {
     case 'hit-local':
-      return '◉'
+      return '✓'
     case 'hit-remote':
       return '↓'
     case 'miss':
       return '▶'
     case 'no-cache':
-      return '·'
+      return '∅'
     case 'group':
       return '○'
     case 'not-started':
@@ -255,20 +219,3 @@ function describe(s: CacheStatus): string {
       return 'not started (unneeded)'
   }
 }
-
-function dotColor(s: CacheStatus): string {
-  switch (s) {
-    case 'hit-local':
-      return '#bbf7d0' // green-200
-    case 'hit-remote':
-      return '#bae6fd' // sky-200
-    case 'miss':
-      return '#fed7aa' // orange-200
-    case 'no-cache':
-      return '#e5e7eb' // gray-200
-    case 'group':
-      return '#f5d0fe' // fuchsia-200
-    case 'not-started':
-      return '#ffffff'
-  }
-}

package/src/cli/plugin-commands.ts

@@ -7,7 +7,7 @@
 // reports an unknown command as it always did. Core's verbs are matched
 // before this is asked, so a plugin cannot shadow `run`.
 
-import type { CachePolicy, PluginCache, PluginCacheRemote } from '../cache/index.js'
+import type { CachePolicy, PluginCache, ResolvedRemote } from '../cache/index.js'
 import type { WorkspaceConfig } from '../config.js'
 import type { VxPlugin, PluginCommand, CommandContext } from '../orchestrator/index.js'
 import { cacheScopeEnvError, findWorkspaceRoot, isCacheScope } from '../workspace/index.js'
@@ -151,7 +151,7 @@ async function verbCache(
     'open',
     await ws.storeRoot,
   )
-  const remotes: PluginCacheRemote[] = []
+  const remotes: ResolvedRemote[] = []
   await resolveCache(ws.plugins, {
     workspaceRoot: ws.workspaceRoot,
     cacheDir: ws.cacheDir,

package/src/cli/plugin-templates.ts

@@ -11,7 +11,7 @@ export const PLUGIN_TEMPLATES: Readonly<Record<string, { plugin: string; test: s
   cache: {
     plugin:
       "// `cache`: where artifacts live. A directory stands in for a remote store;\n// core puts it behind the local cache, so a remote error is a miss and a\n// warning, never a failed run.\nimport { link, mkdir, unlink } from 'node:fs/promises'\nimport path from 'node:path'\nimport { definePlugin, type RemoteCacheLayer, type VxPlugin } from '@vzn/vx'\n\nclass DirRemote implements RemoteCacheLayer {\n  constructor(readonly endpoint: string) {}\n  async has(hash: string): Promise<boolean> {\n    return Bun.file(path.join(this.endpoint, hash)).exists()\n  }\n  async get(hash: string) {\n    const file = Bun.file(path.join(this.endpoint, hash))\n    return (await file.exists()) ? { body: file, durationMs: undefined } : null\n  }\n  async put(hash: string, body: Blob): Promise<void> {\n    await mkdir(this.endpoint, { recursive: true })\n    // Written aside, then linked: on a shared directory a rename can swap\n    // the file under a reader, while a link never replaces an existing one.\n    // EEXIST is success: the same hash means the same bytes.\n    const tmp = path.join(this.endpoint, `.${hash}.${process.pid}`)\n    await Bun.write(tmp, body)\n    try {\n      await link(tmp, path.join(this.endpoint, hash))\n    } catch (err) {\n      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err\n    } finally {\n      await unlink(tmp)\n    }\n  }\n}\n\nexport function dirCache(dir: string): VxPlugin {\n  return definePlugin(import.meta, {\n    cache() {\n      return new DirRemote(dir)\n    },\n  })\n}\n",
-    test: "// A test for the example `cache` plugin beside it: a throwaway workspace\n// declares the plugin and vx's own run() drives it. `bun test` runs it.\nimport { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'\nimport os from 'node:os'\nimport path from 'node:path'\nimport { afterEach, beforeEach, expect, it } from 'bun:test'\nimport { run, type Logger } from '@vzn/vx'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-cache-'))\n  await writeFile(path.join(root, 'package.json'), JSON.stringify({ name: 'ws', private: true }))\n  await writeFile(path.join(root, 'pnpm-workspace.yaml'), 'packages:\\n  - \"packages/*\"\\n')\n  Bun.spawnSync({ cmd: ['git', 'init', '-q'], cwd: root })\n})\nafterEach(async () => {\n  await rm(root, { recursive: true, force: true })\n})\n\n/** A package `name` whose `vx.config.mjs` is `config`. */\nasync function pkg(\n  name: string,\n  config: string,\n  scripts?: Record<string, string>,\n): Promise<string> {\n  const dir = path.join(root, 'packages', name)\n  await mkdir(dir, { recursive: true })\n  await writeFile(\n    path.join(dir, 'package.json'),\n    JSON.stringify({ name, version: '1.0.0', ...(scripts ? { scripts } : {}) }),\n  )\n  // Core reads no package.json: the config names the project.\n  await writeFile(\n    path.join(dir, 'vx.config.mjs'),\n    config.replace('export default {', `export default { name: ${JSON.stringify(name)},`),\n  )\n  return dir\n}\n\n/**\n * A `.vx/workspace.mjs` declaring `call`, e.g. `dirCache()`, from the plugin file\n * beside this test, then `vx lock`: a run reads project configs only from the lock.\n */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'cache.ts'))\n  await Bun.write(\n    path.join(root, '.vx/workspace.mjs'),\n    `import { dirCache } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\n  const vx = path.join(path.dirname(new URL(import.meta.resolve('@vzn/vx')).pathname), 'bin.ts')\n  const lock = Bun.spawnSync({ cmd: [process.execPath, vx, 'lock'], cwd: root })\n  expect([lock.exitCode, lock.stderr.toString()]).toEqual([0, ''])\n}\n\nfunction log(order: string[] = []): Logger {\n  return {\n    status() {},\n    taskStart(node) {\n      order.push(`start ${node.id}`)\n    },\n    taskStdout() {},\n    taskStderr() {},\n    taskComplete(node) {\n      order.push(`end ${node.id}`)\n    },\n  }\n}\n\nit('a run on an empty local cache restores from the directory', async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: { build: {\n      exec: { command: 'mkdir -p dist && echo built > dist/out.txt' },\n      cache: { inputs: { files: ['package.json'] }, outputs: { files: ['dist/**'] } },\n    } } }`,\n  )\n  await workspace(`dirCache(${JSON.stringify(path.join(root, 'remote'))})`)\n  const first = await run({ cwd: root, tasks: ['build'], log: log(), handleSignals: false })\n  expect(first.outcomes.map((o) => o.status)).toEqual(['success'])\n  await rm(path.join(root, '.vx', 'cache'), { recursive: true, force: true })\n  await rm(path.join(dir, 'dist'), { recursive: true, force: true })\n  const second = await run({ cwd: root, tasks: ['build'], log: log(), handleSignals: false })\n  expect(second.outcomes.map((o) => o.status)).toEqual(['cache-hit-remote'])\n  expect(await Bun.file(path.join(dir, 'dist', 'out.txt')).text()).toBe('built\\n')\n}, 20_000)\n",
+    test: "// A test for the example `cache` plugin beside it: a throwaway workspace\n// declares the plugin and vx's own run() drives it. `bun test` runs it.\nimport { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'\nimport os from 'node:os'\nimport path from 'node:path'\nimport { afterEach, beforeEach, expect, it } from 'bun:test'\nimport { run, type Logger } from '@vzn/vx'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-cache-'))\n  await writeFile(path.join(root, 'package.json'), JSON.stringify({ name: 'ws', private: true }))\n  await writeFile(path.join(root, 'pnpm-workspace.yaml'), 'packages:\\n  - \"packages/*\"\\n')\n  Bun.spawnSync({ cmd: ['git', 'init', '-q'], cwd: root })\n})\nafterEach(async () => {\n  await rm(root, { recursive: true, force: true })\n})\n\n/** A package `name` whose `vx.config.mjs` is `config`. */\nasync function pkg(\n  name: string,\n  config: string,\n  scripts?: Record<string, string>,\n): Promise<string> {\n  const dir = path.join(root, 'packages', name)\n  await mkdir(dir, { recursive: true })\n  await writeFile(\n    path.join(dir, 'package.json'),\n    JSON.stringify({ name, version: '1.0.0', ...(scripts ? { scripts } : {}) }),\n  )\n  // Core reads no package.json: the config names the project.\n  await writeFile(\n    path.join(dir, 'vx.config.mjs'),\n    config.replace('export default {', `export default { name: ${JSON.stringify(name)},`),\n  )\n  return dir\n}\n\n/**\n * A `.vx/workspace.mjs` declaring `call`, e.g. `dirCache()`, from the plugin file\n * beside this test, then `vx lock`: a run reads project configs only from the lock.\n */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'cache.ts'))\n  await Bun.write(\n    path.join(root, '.vx/workspace.mjs'),\n    `import { dirCache } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\n  const vx = path.join(path.dirname(new URL(import.meta.resolve('@vzn/vx')).pathname), 'bin.ts')\n  const lock = Bun.spawnSync({ cmd: [process.execPath, vx, 'lock'], cwd: root })\n  expect([lock.exitCode, lock.stderr.toString()]).toEqual([0, ''])\n}\n\nfunction log(order: string[] = []): Logger {\n  return {\n    status() {},\n    taskStart(node) {\n      order.push(`start ${node.id}`)\n    },\n    taskStdout() {},\n    taskStderr() {},\n    taskComplete(node) {\n      order.push(`end ${node.id}`)\n    },\n  }\n}\n\nit('a run on an empty local cache restores from the directory', async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: { build: {\n      exec: { command: 'mkdir -p dist && echo built > dist/out.txt' },\n      inputs: { files: ['package.json'] }, cache: { outputs: { files: ['dist/**'] } },\n    } } }`,\n  )\n  await workspace(`dirCache(${JSON.stringify(path.join(root, 'remote'))})`)\n  const first = await run({ cwd: root, tasks: ['build'], log: log(), handleSignals: false })\n  expect(first.outcomes.map((o) => o.status)).toEqual(['success'])\n  await rm(path.join(root, '.vx', 'cache'), { recursive: true, force: true })\n  await rm(path.join(dir, 'dist'), { recursive: true, force: true })\n  const second = await run({ cwd: root, tasks: ['build'], log: log(), handleSignals: false })\n  expect(second.outcomes.map((o) => o.status)).toEqual(['cache-hit-remote'])\n  expect(await Bun.file(path.join(dir, 'dist', 'out.txt')).text()).toBe('built\\n')\n}, 20_000)\n",
   },
   commands: {
     plugin:
@@ -31,7 +31,7 @@ export const PLUGIN_TEMPLATES: Readonly<Record<string, { plugin: string; test: s
   key: {
     plugin:
       "// `key`: extra cache-key material. The value of each named environment\n// variable is folded into every cached task's key and named in `vx why`,\n// so a change to it is a miss. An unset variable folds as ''.\nimport { definePlugin, type VxPlugin } from '@vzn/vx'\n\nexport function envKey(names: readonly string[]): VxPlugin {\n  return definePlugin(import.meta, {\n    key() {\n      return Object.fromEntries(names.map((n) => [n, process.env[n] ?? '']))\n    },\n  })\n}\n",
-    test: "// A test for the example `key` plugin beside it: a throwaway workspace\n// declares the plugin and vx's own run() drives it. `bun test` runs it.\nimport { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'\nimport os from 'node:os'\nimport path from 'node:path'\nimport { afterEach, beforeEach, expect, it } from 'bun:test'\nimport { planRun, type Logger } from '@vzn/vx'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-key-'))\n  await writeFile(path.join(root, 'package.json'), JSON.stringify({ name: 'ws', private: true }))\n  await writeFile(path.join(root, 'pnpm-workspace.yaml'), 'packages:\\n  - \"packages/*\"\\n')\n  Bun.spawnSync({ cmd: ['git', 'init', '-q'], cwd: root })\n})\nafterEach(async () => {\n  await rm(root, { recursive: true, force: true })\n})\n\n/** A package `name` whose `vx.config.mjs` is `config`. */\nasync function pkg(\n  name: string,\n  config: string,\n  scripts?: Record<string, string>,\n): Promise<string> {\n  const dir = path.join(root, 'packages', name)\n  await mkdir(dir, { recursive: true })\n  await writeFile(\n    path.join(dir, 'package.json'),\n    JSON.stringify({ name, version: '1.0.0', ...(scripts ? { scripts } : {}) }),\n  )\n  // Core reads no package.json: the config names the project.\n  await writeFile(\n    path.join(dir, 'vx.config.mjs'),\n    config.replace('export default {', `export default { name: ${JSON.stringify(name)},`),\n  )\n  return dir\n}\n\n/**\n * A `.vx/workspace.mjs` declaring `call`, e.g. `envKey()`, from the plugin file\n * beside this test, then `vx lock`: a run reads project configs only from the lock.\n */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'key.ts'))\n  await Bun.write(\n    path.join(root, '.vx/workspace.mjs'),\n    `import { envKey } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\n  const vx = path.join(path.dirname(new URL(import.meta.resolve('@vzn/vx')).pathname), 'bin.ts')\n  const lock = Bun.spawnSync({ cmd: [process.execPath, vx, 'lock'], cwd: root })\n  expect([lock.exitCode, lock.stderr.toString()]).toEqual([0, ''])\n}\n\nfunction log(order: string[] = []): Logger {\n  return {\n    status() {},\n    taskStart(node) {\n      order.push(`start ${node.id}`)\n    },\n    taskStdout() {},\n    taskStderr() {},\n    taskComplete(node) {\n      order.push(`end ${node.id}`)\n    },\n  }\n}\n\nit(\"the variable's value moves the key; the same value keeps it\", async () => {\n  await pkg(\n    'a',\n    `export default { tasks: { build: {\n      exec: { command: 'true' },\n      cache: { inputs: { files: ['package.json'] }, outputs: { files: [] } },\n    } } }`,\n  )\n  await workspace(`envKey(['EXAMPLE_FLAG'])`)\n  const hash = async (value: string): Promise<string | undefined> => {\n    process.env['EXAMPLE_FLAG'] = value\n    try {\n      const plan = await planRun({ cwd: root, tasks: ['build'], log: log() })\n      return plan.tasks[0]!.hash\n    } finally {\n      delete process.env['EXAMPLE_FLAG']\n    }\n  }\n  const one = await hash('1')\n  expect(one).toBeDefined()\n  expect(await hash('1')).toBe(one)\n  expect(await hash('2')).not.toBe(one)\n}, 20_000)\n",
+    test: "// A test for the example `key` plugin beside it: a throwaway workspace\n// declares the plugin and vx's own run() drives it. `bun test` runs it.\nimport { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'\nimport os from 'node:os'\nimport path from 'node:path'\nimport { afterEach, beforeEach, expect, it } from 'bun:test'\nimport { planRun, type Logger } from '@vzn/vx'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-key-'))\n  await writeFile(path.join(root, 'package.json'), JSON.stringify({ name: 'ws', private: true }))\n  await writeFile(path.join(root, 'pnpm-workspace.yaml'), 'packages:\\n  - \"packages/*\"\\n')\n  Bun.spawnSync({ cmd: ['git', 'init', '-q'], cwd: root })\n})\nafterEach(async () => {\n  await rm(root, { recursive: true, force: true })\n})\n\n/** A package `name` whose `vx.config.mjs` is `config`. */\nasync function pkg(\n  name: string,\n  config: string,\n  scripts?: Record<string, string>,\n): Promise<string> {\n  const dir = path.join(root, 'packages', name)\n  await mkdir(dir, { recursive: true })\n  await writeFile(\n    path.join(dir, 'package.json'),\n    JSON.stringify({ name, version: '1.0.0', ...(scripts ? { scripts } : {}) }),\n  )\n  // Core reads no package.json: the config names the project.\n  await writeFile(\n    path.join(dir, 'vx.config.mjs'),\n    config.replace('export default {', `export default { name: ${JSON.stringify(name)},`),\n  )\n  return dir\n}\n\n/**\n * A `.vx/workspace.mjs` declaring `call`, e.g. `envKey()`, from the plugin file\n * beside this test, then `vx lock`: a run reads project configs only from the lock.\n */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'key.ts'))\n  await Bun.write(\n    path.join(root, '.vx/workspace.mjs'),\n    `import { envKey } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\n  const vx = path.join(path.dirname(new URL(import.meta.resolve('@vzn/vx')).pathname), 'bin.ts')\n  const lock = Bun.spawnSync({ cmd: [process.execPath, vx, 'lock'], cwd: root })\n  expect([lock.exitCode, lock.stderr.toString()]).toEqual([0, ''])\n}\n\nfunction log(order: string[] = []): Logger {\n  return {\n    status() {},\n    taskStart(node) {\n      order.push(`start ${node.id}`)\n    },\n    taskStdout() {},\n    taskStderr() {},\n    taskComplete(node) {\n      order.push(`end ${node.id}`)\n    },\n  }\n}\n\nit(\"the variable's value moves the key; the same value keeps it\", async () => {\n  await pkg(\n    'a',\n    `export default { tasks: { build: {\n      exec: { command: 'true' },\n      inputs: { files: ['package.json'] }, cache: { outputs: { files: [] } },\n    } } }`,\n  )\n  await workspace(`envKey(['EXAMPLE_FLAG'])`)\n  const hash = async (value: string): Promise<string | undefined> => {\n    process.env['EXAMPLE_FLAG'] = value\n    try {\n      const plan = await planRun({ cwd: root, tasks: ['build'], log: log() })\n      return plan.tasks[0]!.hash\n    } finally {\n      delete process.env['EXAMPLE_FLAG']\n    }\n  }\n  const one = await hash('1')\n  expect(one).toBeDefined()\n  expect(await hash('1')).toBe(one)\n  expect(await hash('2')).not.toBe(one)\n}, 20_000)\n",
   },
   project: {
     plugin: