@vzn/vx 0.0.650 → 0.0.652

package/src/cli/plugin-templates.ts

@@ -3,49 +3,40 @@
 // VX_UPDATE_CONTRACT=1 that test. `vx init --plugin <seam>` writes these.
 
 export const PLUGIN_TEMPLATES: Readonly<Record<string, { plugin: string; test: string }>> = {
-  admit: {
-    plugin:
-      "// `admit`: whether a ready task starts now, beside what runs here. At most\n// one task of the named `task` runs at a time (say, one that holds a port).\n// Synchronous and cheap: it is asked at every dispatch.\nimport { definePlugin, type VxPlugin } from '@vzn/vx'\n\nexport function oneAtATime(task: string): VxPlugin {\n  const named = (id: string): boolean => id.endsWith(`#${task}`)\n  return definePlugin(import.meta, {\n    admit(node, ctx) {\n      return !named(node.id) || !ctx.running.some((r) => named(r.id))\n    },\n  })\n}\n",
-    test: "// A test for the example `admit` 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-admit-'))\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. `oneAtATime()`, 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, 'admit.ts'))\n  await Bun.write(\n    path.join(root, '.vx/workspace.mjs'),\n    `import { oneAtATime } 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('two tasks of the named task never overlap, even with two workers', async () => {\n  for (const name of ['a', 'b']) {\n    await pkg(name, `export default { tasks: { serve: { exec: { command: 'sleep 0.2' } } } }`)\n  }\n  await workspace(`oneAtATime('serve')`)\n  const order: string[] = []\n  await run({ cwd: root, tasks: ['serve'], log: log(order), handleSignals: false, concurrency: 2 })\n  // Each start is followed by its own end: no second start in between.\n  expect(order).toHaveLength(4)\n  expect(order[1]!.replace('end', 'start')).toBe(order[0]!)\n  expect(order[3]!.replace('end', 'start')).toBe(order[2]!)\n}, 20_000)\n",
-  },
-  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 ArtifactInfo, type RemoteCacheLayer, type VxPlugin } from '@vzn/vx'\n\nclass DirRemote implements RemoteCacheLayer {\n  constructor(readonly endpoint: string) {}\n  async has(hash: string): Promise<ArtifactInfo | null> {\n    const file = Bun.file(path.join(this.endpoint, hash))\n    return (await file.exists()) ? { size: file.size } : null\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. The aside\n    // name is the writer's own: a pid is not (two puts here, containers on\n    // one volume).\n    const tmp = path.join(this.endpoint, `.${hash}.${crypto.randomUUID()}`)\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(ctx) {\n      // From the root, not the cwd: a run in a project's directory reads\n      // the same store as one at the root.\n      return new DirRemote(path.resolve(ctx.workspaceRoot, 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, readdir, 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'\nimport { dirCache } from './cache.ts'\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\n// Read against the process's cwd, a relative directory was another store\n// for a run started in a project's directory than for one at the root.\nit('reads a relative directory from the workspace root', async () => {\n  const layer = await dirCache('remote').cache!({ workspaceRoot: root } as never)\n  expect(layer?.endpoint).toBe(path.join(root, 'remote'))\n})\n\n// Two writers of one key shared one temporary name (`.<hash>.<pid>`, and\n// containers on one volume share pids): one unlinked the other's file\n// mid-put, or linked it while the other rewrote it.\nit('two puts of one key at once both land, as one entry', async () => {\n  const store = path.join(root, 'remote')\n  const layer = (await dirCache(store).cache!({ workspaceRoot: root } as never))!\n  const bytes = new Blob(['x'.repeat(1 << 20)])\n  const puts = await Promise.allSettled([\n    layer.put('k', bytes, { durationMs: 1 }),\n    layer.put('k', bytes, { durationMs: 1 }),\n  ])\n  expect(puts.map((p) => p.status)).toEqual(['fulfilled', 'fulfilled'])\n  expect(await readdir(store)).toEqual(['k'])\n  expect((await (await layer.get('k'))!.body.arrayBuffer()).byteLength).toBe(1 << 20)\n})\n",
-  },
-  commands: {
-    plugin:
-      "// `commands`: a CLI verb. `vx cache-dir` prints where this workspace's cache\n// lives. The verb's return value is the exit code.\nimport { definePlugin, type VxPlugin } from '@vzn/vx'\n\nexport function cacheDirVerb(): VxPlugin {\n  return definePlugin(import.meta, {\n    commands: {\n      'cache-dir': {\n        description: \"print this workspace's cache directory\",\n        run(argv, ctx) {\n          if (argv.length > 0) {\n            console.error(`vx cache-dir: takes no arguments, got ${argv.join(' ')}`)\n            return 2\n          }\n          console.log(ctx.cacheDir)\n          return 0\n        },\n      },\n    },\n  })\n}\n",
-    test: "// A test for the example `commands` plugin beside it: the verb is called\n// the way vx calls it, with the context vx hands it. `bun test` runs it.\nimport { expect, it, spyOn } from 'bun:test'\nimport { cacheDirVerb } from './commands.ts'\n\nconst verb = cacheDirVerb().commands!['cache-dir']!\nconst ctx = {\n  workspaceRoot: '/ws',\n  cacheDir: '/ws/.vx/cache',\n  warn() {},\n  concurrency: 1,\n  vx: ['vx'],\n  cache: {\n    get: async () => null,\n    put: async () => {},\n    has: async () => null,\n    hasMany: async () => null,\n    getRun: async () => null,\n  },\n  artifacts: {\n    save: async () => {},\n    restore: async () => null,\n    output: async () => null,\n    share: async () => false,\n    resend: async () => false,\n  },\n  artifactsFor: () => ({\n    save: async () => {},\n    restore: async () => null,\n    output: async () => null,\n    share: async () => false,\n    resend: async () => false,\n  }),\n}\n\nit('prints the cache directory; an argument is exit 2', async () => {\n  const out = spyOn(console, 'log').mockImplementation(() => {})\n  const err = spyOn(console, 'error').mockImplementation(() => {})\n  try {\n    expect(await verb.run([], ctx)).toBe(0)\n    expect(out.mock.calls).toEqual([['/ws/.vx/cache']])\n    expect(await verb.run(['x'], ctx)).toBe(2)\n    expect(err.mock.calls).toEqual([['vx cache-dir: takes no arguments, got x']])\n  } finally {\n    out.mockRestore()\n    err.mockRestore()\n  }\n})\n",
-  },
-  executor: {
-    plugin:
-      "// `executor`: where a task's command runs. This one runs it here, in a\n// shell of its own, and stops the shell's whole process group when core\n// aborts the request (a stop, or `exec.timeout`): core cannot reach a\n// process an executor spawned.\nimport { definePlugin, withForwardArgs, type TaskExecutor, type VxPlugin } from '@vzn/vx'\n\nexport function shellExecutor(): VxPlugin {\n  const executor: TaskExecutor = {\n    name: 'shell',\n    async execute(req) {\n      const started = Date.now()\n      // A stop before the spawn is work not to start: an abort fires no\n      // listener added after it, so the command would run unstopped.\n      if (req.signal?.aborted === true) {\n        const exitCode = req.signal.reason === 'SIGINT' ? 130 : 143\n        return { exitCode, durationMs: 0, stdout: '', stderr: '', violations: [], where: 'shell' }\n      }\n      // vx's own `sh`: a bare name is looked up on `req.env`'s PATH, which\n      // leads with the project's node_modules/.bin, where a dependency's\n      // `sh` would run every command.\n      const sh = Bun.which('sh') ?? '/bin/sh'\n      // The args after `--`, quoted and placed as the local executor places\n      // them (before a trailing comment, never on a heredoc's terminator).\n      const command = withForwardArgs(req.command, req.forwardArgs)\n      const child = Bun.spawn([sh, '-c', command], {\n        cwd: req.cwd,\n        env: req.env,\n        stdout: 'pipe',\n        stderr: 'pipe',\n        detached: true,\n      })\n      const kill = (signal: NodeJS.Signals): void => {\n        try {\n          process.kill(-child.pid, signal)\n        } catch {\n          // already gone\n        }\n      }\n      // Core abandons an executor 2 s after the abort: a group that ignores\n      // SIGTERM is killed before then, or it would run on unreached.\n      let killTimer: ReturnType<typeof setTimeout> | undefined\n      const stop = (): void => {\n        kill('SIGTERM')\n        killTimer = setTimeout(() => kill('SIGKILL'), 1_000)\n      }\n      req.signal?.addEventListener('abort', stop, { once: true })\n      const readers: { cancel(): Promise<void> }[] = []\n      const drain = async (stream: ReadableStream<Uint8Array>, on: (s: string) => void) => {\n        const reader = stream.getReader()\n        readers.push(reader)\n        const decoder = new TextDecoder()\n        let all = ''\n        for (let r = await reader.read(); !r.done; r = await reader.read()) {\n          const text = decoder.decode(r.value, { stream: true })\n          all += text\n          on(text)\n        }\n        return all\n      }\n      const drained = Promise.all([\n        drain(child.stdout, req.onStdout),\n        drain(child.stderr, req.onStderr),\n      ])\n      const exitCode = await child.exited\n      // A pipe ends only when every writer closes it: a process the command\n      // left running (`server &`) would hold the task open. What it writes\n      // after a short grace is not the task's.\n      const cut = setTimeout(() => readers.forEach((r) => void r.cancel()), 250)\n      const [stdout, stderr] = await drained\n      clearTimeout(cut)\n      req.signal?.removeEventListener('abort', stop)\n      clearTimeout(killTimer)\n      return {\n        exitCode,\n        durationMs: Date.now() - started,\n        stdout,\n        stderr,\n        violations: [],\n        where: 'shell',\n      }\n    },\n  }\n  return definePlugin(import.meta, { executor: () => executor })\n}\n",
-    test: "// A test for the example `executor` 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'\nimport { shellExecutor } from './executor.ts'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-executor-'))\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. `shellExecutor()`, 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, 'executor.ts'))\n  await Bun.write(\n    path.join(root, '.vx/workspace.mjs'),\n    `import { shellExecutor } 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('runs the command and says where; stops it on exec.timeout', async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: {\n      hello: { exec: { command: 'echo hi > out.txt' } },\n      slow: { exec: { command: 'exec sleep 30', timeout: '300ms' } },\n    } }`,\n  )\n  await workspace('shellExecutor()')\n  const ok = await run({ cwd: root, tasks: ['hello'], log: log(), handleSignals: false })\n  expect(ok.outcomes.map((o) => [o.node.id, o.status, o.where])).toEqual([\n    ['a#hello', 'success', 'shell'],\n  ])\n  expect(await Bun.file(path.join(dir, 'out.txt')).text()).toBe('hi\\n')\n  const started = Date.now()\n  const slow = await run({ cwd: root, tasks: ['slow'], log: log(), handleSignals: false })\n  expect(slow.outcomes.map((o) => [o.node.id, o.status, o.timedOut === true])).toEqual([\n    ['a#slow', 'failed', true],\n  ])\n  expect(Date.now() - started).toBeLessThan(10_000)\n}, 20_000)\n\nit(\"runs the command through this machine's sh, not a project's node_modules/.bin sh\", async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: { hello: { exec: { command: 'echo real' } } } }`,\n  )\n  await mkdir(path.join(dir, 'node_modules', '.bin'), { recursive: true })\n  await writeFile(path.join(dir, 'node_modules', '.bin', 'sh'), '#!/bin/sh\\necho planted\\n', {\n    mode: 0o755,\n  })\n  await workspace('shellExecutor()')\n  const out: string[] = []\n  const r = await run({\n    cwd: root,\n    tasks: ['hello'],\n    log: { ...log(), taskStdout: (_n, chunk) => void out.push(chunk) },\n    handleSignals: false,\n  })\n  expect([r.outcomes.map((o) => o.status), out.join('')]).toEqual([['success'], 'real\\n'])\n}, 20_000)\n\nit('puts the args after -- on the command as the local executor does', async () => {\n  await pkg(\n    'a',\n    `export default { tasks: { say: { exec: { command: \"printf '<%s>' # each arg\" } } } }`,\n  )\n  await workspace('shellExecutor()')\n  const out: string[] = []\n  const r = await run({\n    cwd: root,\n    tasks: ['say'],\n    forwardArgs: [\"it's\", 'a b'],\n    log: { ...log(), taskStdout: (_n, chunk) => void out.push(chunk) },\n    handleSignals: false,\n  })\n  expect([r.outcomes.map((o) => o.status), out.join('')]).toEqual([['success'], \"<it's><a b>\"])\n}, 20_000)\n\n// An abort fires no listener added after it: a request stopped before\n// `execute` ran its command anyway, in a group nothing would stop.\nit('starts nothing for a request already aborted', async () => {\n  const executor = (await shellExecutor().executor!({} as never))!\n  const stop = new AbortController()\n  stop.abort('SIGTERM')\n  const r = await executor.execute({\n    command: 'sleep 0.3; echo ran > ran.txt',\n    cwd: root,\n    env: { PATH: process.env['PATH'] ?? '' },\n    forwardArgs: [],\n    onStdout() {},\n    onStderr() {},\n    signal: stop.signal,\n  } as never)\n  await Bun.sleep(600)\n  expect([r.exitCode, await Bun.file(path.join(root, 'ran.txt')).exists()]).toEqual([143, false])\n})\n\n// Core abandons an executor 2 s after its abort: a group that ignored\n// SIGTERM ran on, unreached, after the run had ended.\nit('kills a group that ignores SIGTERM after a grace', async () => {\n  const executor = (await shellExecutor().executor!({} as never))!\n  const stop = new AbortController()\n  const started = Date.now()\n  setTimeout(() => stop.abort('SIGTERM'), 200)\n  const r = await executor.execute({\n    command: \"trap '' TERM; sleep 30\",\n    cwd: root,\n    env: { PATH: process.env['PATH'] ?? '' },\n    forwardArgs: [],\n    onStdout() {},\n    onStderr() {},\n    signal: stop.signal,\n  } as never)\n  expect([r.exitCode, Date.now() - started < 10_000]).toEqual([137, true])\n}, 40_000)\n\n// A pipe ends only when every writer closes it: a process the command\n// left running (`server &`) held the task open until it exited.\nit('ends when the shell exits, though a process it left holds the pipes', async () => {\n  const executor = (await shellExecutor().executor!({} as never))!\n  const started = Date.now()\n  const r = await executor.execute({\n    command: 'sleep 5 & echo up',\n    cwd: root,\n    env: { PATH: process.env['PATH'] ?? '' },\n    forwardArgs: [],\n    onStdout() {},\n    onStderr() {},\n  } as never)\n  expect([r.exitCode, r.stdout, Date.now() - started < 3_000]).toEqual([0, 'up\\n', true])\n}, 20_000)\n",
-  },
-  graph: {
-    plugin:
-      "// `graph`: the run's edges. Every task named `task` waits for the one\n// before it, so they run one after another across projects: in dependency\n// order, then id order, so an added edge never closes a cycle. Core checks\n// the edited graph again (a missing dep, a cycle).\nimport { definePlugin, type VxPlugin } from '@vzn/vx'\n\nexport function chain(task: string): VxPlugin {\n  return definePlugin(import.meta, {\n    graph(nodes) {\n      const named = (id: string): boolean => id.endsWith(`#${task}`)\n      const ids: string[] = []\n      const seen = new Set<string>()\n      const visit = (id: string): void => {\n        if (seen.has(id)) return\n        seen.add(id)\n        for (const dep of nodes.get(id)?.deps ?? []) visit(dep)\n        if (named(id)) ids.push(id)\n      }\n      for (const id of [...nodes.keys()].filter(named).sort()) visit(id)\n      for (const [i, id] of ids.entries()) {\n        const prev = ids[i - 1]\n        const node = nodes.get(id)!\n        if (prev !== undefined && !node.deps.includes(prev)) node.deps.push(prev)\n      }\n    },\n  })\n}\n",
-    test: "// A test for the example `graph` 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-graph-'))\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. `chain()`, 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, 'graph.ts'))\n  await Bun.write(\n    path.join(root, '.vx/workspace.mjs'),\n    `import { chain } 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('each named task waits on the one before it in id order', async () => {\n  for (const name of ['a', 'b', 'c']) {\n    await pkg(name, `export default { tasks: { build: { exec: { command: 'true' } } } }`)\n  }\n  await workspace(`chain('build')`)\n  const plan = await planRun({ cwd: root, tasks: ['build'], log: log() })\n  expect(plan.tasks.map((t) => `${t.node.id} <- ${t.deps.join(',')}`).sort()).toEqual([\n    'a#build <- ',\n    'b#build <- a#build',\n    'c#build <- b#build',\n  ])\n}, 20_000)\n\n// Id order alone put a#build before b#build even when a#build already\n// waits on b#build: the added edge closed a cycle and the run was refused.\nit('chains in dependency order, never closing a cycle', async () => {\n  await pkg(\n    'a',\n    `export default { tasks: { build: { exec: { command: 'true' }, dependsOn: ['b#build'] } } }`,\n  )\n  for (const name of ['b', 'c']) {\n    await pkg(name, `export default { tasks: { build: { exec: { command: 'true' } } } }`)\n  }\n  await workspace(`chain('build')`)\n  const plan = await planRun({ cwd: root, tasks: ['build'], log: log() })\n  expect(plan.tasks.map((t) => `${t.node.id} <- ${t.deps.join(',')}`).sort()).toEqual([\n    'a#build <- b#build',\n    'b#build <- ',\n    'c#build <- a#build',\n  ])\n}, 20_000)\n",
-  },
-  key: {
-    plugin:
-      "// `key`: extra cache-key material. The value of each named environment\n// variable goes into every cached task's key and is 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      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:
-      "// `project`: a project's tasks. Every script in the project's package.json\n// becomes a task of the same name that runs it, unless the project already\n// declares one. Core reads no package.json, so the plugin does. Core\n// re-validates each edit as it would the user's own config, so a blank\n// script, or one no task can be named after (`taskNameProblem`: a `#`\n// comment key), is left out.\nimport { definePlugin, taskNameProblem, type VxPlugin } from '@vzn/vx'\n\nexport function scriptTasks(): VxPlugin {\n  return definePlugin(import.meta, {\n    async project(config, ctx) {\n      const pkg: unknown = await Bun.file(`${ctx.dir}/package.json`)\n        .json()\n        .catch(() => null)\n      const scripts = (pkg as { scripts?: unknown } | null)?.scripts\n      if (scripts === null || typeof scripts !== 'object') return\n      config.tasks ??= {}\n      for (const [name, command] of Object.entries(scripts)) {\n        if (typeof command !== 'string' || command.trim() === '') continue\n        if (config.tasks[name] !== undefined || taskNameProblem(name) !== null) continue\n        config.tasks[name] = { exec: { command } }\n      }\n    },\n  })\n}\n",
-    test: "// A test for the example `project` 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-project-'))\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. `scriptTasks()`, 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, 'project.ts'))\n  await Bun.write(\n    path.join(root, '.vx/workspace.mjs'),\n    `import { scriptTasks } 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 package.json script runs as a task; a declared task wins', async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: { build: { exec: { command: 'echo declared > build.txt' } } } }`,\n    { hello: 'echo hi > hello.txt', build: 'echo script > build.txt' },\n  )\n  await workspace('scriptTasks()')\n  const r = await run({ cwd: root, tasks: ['hello', 'build'], log: log(), handleSignals: false })\n  expect(r.outcomes.map((o) => `${o.node.id} ${o.status}`).sort()).toEqual([\n    'a#build success',\n    'a#hello success',\n  ])\n  expect(await Bun.file(path.join(dir, 'hello.txt')).text()).toBe('hi\\n')\n  expect(await Bun.file(path.join(dir, 'build.txt')).text()).toBe('declared\\n')\n}, 20_000)\n\n// A blank script, or one no task can be named after (a `#` comment key),\n// was handed to core, which refused the project: every run of it failed.\nit('leaves out a blank script and one no task can be named after', async () => {\n  const dir = await pkg('a', `export default { tasks: {} }`, {\n    '# notes': 'see README',\n    test: '',\n    hello: 'echo hi > hello.txt',\n  })\n  await workspace('scriptTasks()')\n  const r = await run({ cwd: root, tasks: ['hello'], log: log(), handleSignals: false })\n  expect(r.outcomes.map((o) => `${o.node.id} ${o.status}`)).toEqual(['a#hello success'])\n  expect(await Bun.file(path.join(dir, 'hello.txt')).text()).toBe('hi\\n')\n}, 20_000)\n",
-  },
-  schedule: {
-    plugin:
-      "// `schedule`: which ready task runs first. Tasks named here outrank the rest;\n// earlier in the list, higher.\nimport { definePlugin, type VxPlugin } from '@vzn/vx'\n\nexport function prioritize(ids: readonly string[]): VxPlugin {\n  return definePlugin(import.meta, {\n    schedule(nodes) {\n      const weights = new Map<string, number>()\n      for (const [i, id] of ids.entries()) if (nodes.has(id)) weights.set(id, 1e6 - i)\n      return weights\n    },\n  })\n}\n",
-    test: "// A test for the example `schedule` 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-schedule-'))\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. `prioritize()`, 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, 'schedule.ts'))\n  await Bun.write(\n    path.join(root, '.vx/workspace.mjs'),\n    `import { prioritize } 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 named task starts first on one worker, whichever it is', async () => {\n  for (const name of ['a', 'b']) {\n    await pkg(name, `export default { tasks: { build: { exec: { command: 'true' } } } }`)\n  }\n  const first = async (id: string): Promise<string | undefined> => {\n    await workspace(`prioritize([${JSON.stringify(id)}])`)\n    const order: string[] = []\n    await run({\n      cwd: root,\n      tasks: ['build'],\n      log: log(order),\n      handleSignals: false,\n      concurrency: 1,\n    })\n    return order[0]\n  }\n  expect(await first('b#build')).toBe('start b#build')\n  expect(await first('a#build')).toBe('start a#build')\n}, 20_000)\n",
-  },
-  telemetry: {
-    plugin:
-      "// `telemetry`: who observes. One JSON line per run, appended to a file.\n// Observability never breaks a run: a sink that throws is switched off,\n// and `flush` is where slow I/O goes (core bounds it).\nimport { appendFile } from 'node:fs/promises'\nimport path from 'node:path'\nimport { definePlugin, type VxPlugin } from '@vzn/vx'\n\nexport function jsonlTelemetry(file: string): VxPlugin {\n  return definePlugin(import.meta, {\n    telemetry(ctx) {\n      // From the root, not the cwd: a run in a project's directory appends\n      // to the same file as one at the root.\n      const to = path.resolve(ctx.workspaceRoot, file)\n      const lines: string[] = []\n      return {\n        onRunSummary(s) {\n          lines.push(\n            JSON.stringify({ tasks: s.taskCount, failed: s.failedCount, cached: s.hitCount }),\n          )\n        },\n        async flush() {\n          if (lines.length > 0) await appendFile(to, lines.splice(0).join('\\n') + '\\n')\n        },\n      }\n    },\n  })\n}\n",
-    test: "// A test for the example `telemetry` 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, type TelemetrySink } from '@vzn/vx'\nimport { jsonlTelemetry } from './telemetry.ts'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-telemetry-'))\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. `jsonlTelemetry()`, 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, 'telemetry.ts'))\n  await Bun.write(\n    path.join(root, '.vx/workspace.mjs'),\n    `import { jsonlTelemetry } 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('appends one line per run', async () => {\n  await pkg('a', `export default { tasks: { hello: { exec: { command: 'true' } } } }`)\n  const file = path.join(root, 'runs.jsonl')\n  await workspace(`jsonlTelemetry(${JSON.stringify(file)})`)\n  await run({ cwd: root, tasks: ['hello'], log: log(), handleSignals: false })\n  await run({ cwd: root, tasks: ['hello'], log: log(), handleSignals: false })\n  expect(await Bun.file(file).text()).toBe(\n    '{\"tasks\":1,\"failed\":0,\"cached\":0}\\n{\"tasks\":1,\"failed\":0,\"cached\":0}\\n',\n  )\n}, 20_000)\n\n// Read against the process's cwd, a relative file was another file for a\n// run started in a project's directory, written inside that project.\nit('writes a relative file at the workspace root', async () => {\n  const elsewhere = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-telemetry-cwd-'))\n  const cwd = process.cwd()\n  process.chdir(elsewhere)\n  try {\n    const plugin = jsonlTelemetry('runs.jsonl')\n    const sink = (await plugin.telemetry!({ workspaceRoot: root } as never)) as TelemetrySink\n    sink.onRunSummary!({ taskCount: 2, failedCount: 0, hitCount: 1 } as never)\n    await sink.flush!(new AbortController().signal)\n  } finally {\n    process.chdir(cwd)\n    await rm(elsewhere, { recursive: true, force: true })\n  }\n  expect(await Bun.file(path.join(root, 'runs.jsonl')).text()).toBe(\n    '{\"tasks\":2,\"failed\":0,\"cached\":1}\\n',\n  )\n})\n",
-  },
+  "admit": {
+    "plugin": "// `admit`: whether a ready task starts now, beside what runs here. At most\n// one task of the named `task` runs at a time (say, one that holds a port).\n// Synchronous and cheap: it is asked at every dispatch.\nimport { definePlugin, type VxPlugin } from '@vzn/vx'\n\nexport function oneAtATime(task: string): VxPlugin {\n  const named = (id: string): boolean => id.endsWith(`#${task}`)\n  return definePlugin(import.meta, {\n    admit(node, ctx) {\n      return !named(node.id) || !ctx.running.some((r) => named(r.id))\n    },\n  })\n}\n",
+    "test": "// A test for the example `admit` 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-admit-'))\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. `oneAtATime()`, 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, 'admit.ts'))\n  await Bun.write(\n    path.join(root, '.vx/workspace.mjs'),\n    `import { oneAtATime } 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('two tasks of the named task never overlap, even with two workers', async () => {\n  for (const name of ['a', 'b']) {\n    await pkg(name, `export default { tasks: { serve: { exec: { command: 'sleep 0.2' } } } }`)\n  }\n  await workspace(`oneAtATime('serve')`)\n  const order: string[] = []\n  await run({ cwd: root, tasks: ['serve'], log: log(order), handleSignals: false, concurrency: 2 })\n  // Each start is followed by its own end: no second start in between.\n  expect(order).toHaveLength(4)\n  expect(order[1]!.replace('end', 'start')).toBe(order[0]!)\n  expect(order[3]!.replace('end', 'start')).toBe(order[2]!)\n}, 20_000)\n"
+  },
+  "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 ArtifactInfo, type RemoteCacheLayer, type VxPlugin } from '@vzn/vx'\n\nclass DirRemote implements RemoteCacheLayer {\n  constructor(readonly endpoint: string) {}\n  async has(hash: string): Promise<ArtifactInfo | null> {\n    const file = Bun.file(path.join(this.endpoint, hash))\n    return (await file.exists()) ? { size: file.size } : null\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. The aside\n    // name is the writer's own: a pid is not (two puts here, containers on\n    // one volume).\n    const tmp = path.join(this.endpoint, `.${hash}.${crypto.randomUUID()}`)\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(ctx) {\n      // From the root, not the cwd: a run in a project's directory reads\n      // the same store as one at the root.\n      return new DirRemote(path.resolve(ctx.workspaceRoot, 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, readdir, 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'\nimport { dirCache } from './cache.ts'\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'] }, outputs: { files: ['dist/**'] }, cache: true,\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\n// Read against the process's cwd, a relative directory was another store\n// for a run started in a project's directory than for one at the root.\nit('reads a relative directory from the workspace root', async () => {\n  const layer = await dirCache('remote').cache!({ workspaceRoot: root } as never)\n  expect(layer?.endpoint).toBe(path.join(root, 'remote'))\n})\n\n// Two writers of one key shared one temporary name (`.<hash>.<pid>`, and\n// containers on one volume share pids): one unlinked the other's file\n// mid-put, or linked it while the other rewrote it.\nit('two puts of one key at once both land, as one entry', async () => {\n  const store = path.join(root, 'remote')\n  const layer = (await dirCache(store).cache!({ workspaceRoot: root } as never))!\n  const bytes = new Blob(['x'.repeat(1 << 20)])\n  const puts = await Promise.allSettled([\n    layer.put('k', bytes, { durationMs: 1 }),\n    layer.put('k', bytes, { durationMs: 1 }),\n  ])\n  expect(puts.map((p) => p.status)).toEqual(['fulfilled', 'fulfilled'])\n  expect(await readdir(store)).toEqual(['k'])\n  expect((await (await layer.get('k'))!.body.arrayBuffer()).byteLength).toBe(1 << 20)\n})\n"
+  },
+  "commands": {
+    "plugin": "// `commands`: a CLI verb. `vx cache-dir` prints where this workspace's cache\n// lives. The verb's return value is the exit code.\nimport { definePlugin, ui, type VxPlugin } from '@vzn/vx'\n\nexport function cacheDirVerb(): VxPlugin {\n  return definePlugin(import.meta, {\n    commands: {\n      'cache-dir': {\n        description: \"print this workspace's cache directory\",\n        run(argv, ctx) {\n          if (argv.length > 0) {\n            ui.say('error', `vx cache-dir: takes no arguments, got ${argv.join(' ')}`)\n            return 2\n          }\n          ui.data('out', `${ctx.cacheDir}\\n`)\n          return 0\n        },\n      },\n    },\n  })\n}\n",
+    "test": "// A test for the example `commands` plugin beside it: the verb is called\n// the way vx calls it, with the context vx hands it. `bun test` runs it.\nimport { expect, it, spyOn } from 'bun:test'\nimport { cacheDirVerb } from './commands.ts'\n\nconst verb = cacheDirVerb().commands!['cache-dir']!\nconst ctx = {\n  workspaceRoot: '/ws',\n  cacheDir: '/ws/.vx/cache',\n  warn() {},\n  concurrency: 1,\n  vx: ['vx'],\n  cache: {\n    get: async () => null,\n    put: async () => {},\n    has: async () => null,\n    hasMany: async () => null,\n    getRun: async () => null,\n  },\n  artifacts: {\n    save: async () => {},\n    restore: async () => null,\n    output: async () => null,\n    share: async () => false,\n    resend: async () => false,\n  },\n  artifactsFor: () => ({\n    save: async () => {},\n    restore: async () => null,\n    output: async () => null,\n    share: async () => false,\n    resend: async () => false,\n  }),\n}\n\nit('prints the cache directory; an argument is exit 2', async () => {\n  const out = spyOn(process.stdout, 'write').mockImplementation(() => true)\n  const err = spyOn(process.stderr, 'write').mockImplementation(() => true)\n  try {\n    expect(await verb.run([], ctx)).toBe(0)\n    expect(out.mock.calls).toEqual([['/ws/.vx/cache\\n']])\n    expect(await verb.run(['x'], ctx)).toBe(2)\n    // On CI the line is coloured: the words are what this asserts.\n    expect(err.mock.calls.map(([l]) => Bun.stripANSI(String(l)))).toEqual([\n      'vx cache-dir: takes no arguments, got x\\n',\n    ])\n  } finally {\n    out.mockRestore()\n    err.mockRestore()\n  }\n})\n"
+  },
+  "executor": {
+    "plugin": "// `executor`: where a task's command runs. This one runs it here, in a\n// shell of its own, and stops the shell's whole process group when core\n// aborts the request (a stop, or `exec.timeout`): core cannot reach a\n// process an executor spawned.\nimport { definePlugin, withForwardArgs, type TaskExecutor, type VxPlugin } from '@vzn/vx'\n\nexport function shellExecutor(): VxPlugin {\n  const executor: TaskExecutor = {\n    name: 'shell',\n    async execute(req) {\n      const started = Date.now()\n      // A stop before the spawn is work not to start: an abort fires no\n      // listener added after it, so the command would run unstopped.\n      if (req.signal?.aborted === true) {\n        const exitCode = req.signal.reason === 'SIGINT' ? 130 : 143\n        return { exitCode, durationMs: 0, stdout: '', stderr: '', violations: [], where: 'shell' }\n      }\n      // vx's own `sh`: a bare name is looked up on `req.env`'s PATH, which\n      // leads with the project's node_modules/.bin, where a dependency's\n      // `sh` would run every command.\n      const sh = Bun.which('sh') ?? '/bin/sh'\n      // The args after `--`, quoted and placed as the local executor places\n      // them (before a trailing comment, never on a heredoc's terminator).\n      const command = withForwardArgs(req.command, req.forwardArgs)\n      const child = Bun.spawn([sh, '-c', command], {\n        cwd: req.cwd,\n        env: req.env,\n        stdout: 'pipe',\n        stderr: 'pipe',\n        detached: true,\n      })\n      const kill = (signal: NodeJS.Signals): void => {\n        try {\n          process.kill(-child.pid, signal)\n        } catch {\n          // already gone\n        }\n      }\n      // Core abandons an executor 2 s after the abort: a group that ignores\n      // SIGTERM is killed before then, or it would run on unreached.\n      let killTimer: ReturnType<typeof setTimeout> | undefined\n      const stop = (): void => {\n        kill('SIGTERM')\n        killTimer = setTimeout(() => kill('SIGKILL'), 1_000)\n      }\n      req.signal?.addEventListener('abort', stop, { once: true })\n      const readers: { cancel(): Promise<void> }[] = []\n      const drain = async (stream: ReadableStream<Uint8Array>, on: (s: string) => void) => {\n        const reader = stream.getReader()\n        readers.push(reader)\n        const decoder = new TextDecoder()\n        let all = ''\n        for (let r = await reader.read(); !r.done; r = await reader.read()) {\n          const text = decoder.decode(r.value, { stream: true })\n          all += text\n          on(text)\n        }\n        return all\n      }\n      const drained = Promise.all([\n        drain(child.stdout, req.onStdout),\n        drain(child.stderr, req.onStderr),\n      ])\n      const exitCode = await child.exited\n      // A pipe ends only when every writer closes it: a process the command\n      // left running (`server &`) would hold the task open. What it writes\n      // after a short grace is not the task's.\n      const cut = setTimeout(() => readers.forEach((r) => void r.cancel()), 250)\n      const [stdout, stderr] = await drained\n      clearTimeout(cut)\n      req.signal?.removeEventListener('abort', stop)\n      clearTimeout(killTimer)\n      return {\n        exitCode,\n        durationMs: Date.now() - started,\n        stdout,\n        stderr,\n        violations: [],\n        where: 'shell',\n      }\n    },\n  }\n  return definePlugin(import.meta, { executor: () => executor })\n}\n",
+    "test": "// A test for the example `executor` 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'\nimport { shellExecutor } from './executor.ts'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-executor-'))\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. `shellExecutor()`, 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, 'executor.ts'))\n  await Bun.write(\n    path.join(root, '.vx/workspace.mjs'),\n    `import { shellExecutor } 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('runs the command and says where; stops it on exec.timeout', async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: {\n      hello: { exec: { command: 'echo hi > out.txt' } },\n      slow: { exec: { command: 'exec sleep 30', timeout: '300ms' } },\n    } }`,\n  )\n  await workspace('shellExecutor()')\n  const ok = await run({ cwd: root, tasks: ['hello'], log: log(), handleSignals: false })\n  expect(ok.outcomes.map((o) => [o.node.id, o.status, o.where])).toEqual([\n    ['a#hello', 'success', 'shell'],\n  ])\n  expect(await Bun.file(path.join(dir, 'out.txt')).text()).toBe('hi\\n')\n  const started = Date.now()\n  const slow = await run({ cwd: root, tasks: ['slow'], log: log(), handleSignals: false })\n  expect(slow.outcomes.map((o) => [o.node.id, o.status, o.timedOut === true])).toEqual([\n    ['a#slow', 'failed', true],\n  ])\n  expect(Date.now() - started).toBeLessThan(10_000)\n}, 20_000)\n\nit(\"runs the command through this machine's sh, not a project's node_modules/.bin sh\", async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: { hello: { exec: { command: 'echo real' } } } }`,\n  )\n  await mkdir(path.join(dir, 'node_modules', '.bin'), { recursive: true })\n  await writeFile(path.join(dir, 'node_modules', '.bin', 'sh'), '#!/bin/sh\\necho planted\\n', {\n    mode: 0o755,\n  })\n  await workspace('shellExecutor()')\n  const out: string[] = []\n  const r = await run({\n    cwd: root,\n    tasks: ['hello'],\n    log: { ...log(), taskStdout: (_n, chunk) => void out.push(chunk) },\n    handleSignals: false,\n  })\n  expect([r.outcomes.map((o) => o.status), out.join('')]).toEqual([['success'], 'real\\n'])\n}, 20_000)\n\nit('puts the args after -- on the command as the local executor does', async () => {\n  await pkg(\n    'a',\n    `export default { tasks: { say: { exec: { command: \"printf '<%s>' # each arg\" } } } }`,\n  )\n  await workspace('shellExecutor()')\n  const out: string[] = []\n  const r = await run({\n    cwd: root,\n    tasks: ['say'],\n    forwardArgs: [\"it's\", 'a b'],\n    log: { ...log(), taskStdout: (_n, chunk) => void out.push(chunk) },\n    handleSignals: false,\n  })\n  expect([r.outcomes.map((o) => o.status), out.join('')]).toEqual([['success'], \"<it's><a b>\"])\n}, 20_000)\n\n// An abort fires no listener added after it: a request stopped before\n// `execute` ran its command anyway, in a group nothing would stop.\nit('starts nothing for a request already aborted', async () => {\n  const executor = (await shellExecutor().executor!({} as never))!\n  const stop = new AbortController()\n  stop.abort('SIGTERM')\n  const r = await executor.execute({\n    command: 'sleep 0.3; echo ran > ran.txt',\n    cwd: root,\n    env: { PATH: process.env['PATH'] ?? '' },\n    forwardArgs: [],\n    onStdout() {},\n    onStderr() {},\n    signal: stop.signal,\n  } as never)\n  await Bun.sleep(600)\n  expect([r.exitCode, await Bun.file(path.join(root, 'ran.txt')).exists()]).toEqual([143, false])\n})\n\n// Core abandons an executor 2 s after its abort: a group that ignored\n// SIGTERM ran on, unreached, after the run had ended.\nit('kills a group that ignores SIGTERM after a grace', async () => {\n  const executor = (await shellExecutor().executor!({} as never))!\n  const stop = new AbortController()\n  const started = Date.now()\n  setTimeout(() => stop.abort('SIGTERM'), 200)\n  const r = await executor.execute({\n    command: \"trap '' TERM; sleep 30\",\n    cwd: root,\n    env: { PATH: process.env['PATH'] ?? '' },\n    forwardArgs: [],\n    onStdout() {},\n    onStderr() {},\n    signal: stop.signal,\n  } as never)\n  expect([r.exitCode, Date.now() - started < 10_000]).toEqual([137, true])\n}, 40_000)\n\n// A pipe ends only when every writer closes it: a process the command\n// left running (`server &`) held the task open until it exited.\nit('ends when the shell exits, though a process it left holds the pipes', async () => {\n  const executor = (await shellExecutor().executor!({} as never))!\n  const started = Date.now()\n  const r = await executor.execute({\n    command: 'sleep 5 & echo up',\n    cwd: root,\n    env: { PATH: process.env['PATH'] ?? '' },\n    forwardArgs: [],\n    onStdout() {},\n    onStderr() {},\n  } as never)\n  expect([r.exitCode, r.stdout, Date.now() - started < 3_000]).toEqual([0, 'up\\n', true])\n}, 20_000)\n"
+  },
+  "graph": {
+    "plugin": "// `graph`: the run's edges. Every task named `task` waits for the one\n// before it, so they run one after another across projects: in dependency\n// order, then id order, so an added edge never closes a cycle. Core checks\n// the edited graph again (a missing dep, a cycle).\nimport { definePlugin, type VxPlugin } from '@vzn/vx'\n\nexport function chain(task: string): VxPlugin {\n  return definePlugin(import.meta, {\n    graph(nodes) {\n      const named = (id: string): boolean => id.endsWith(`#${task}`)\n      const ids: string[] = []\n      const seen = new Set<string>()\n      const visit = (id: string): void => {\n        if (seen.has(id)) return\n        seen.add(id)\n        for (const dep of nodes.get(id)?.deps ?? []) visit(dep)\n        if (named(id)) ids.push(id)\n      }\n      for (const id of [...nodes.keys()].filter(named).sort()) visit(id)\n      for (const [i, id] of ids.entries()) {\n        const prev = ids[i - 1]\n        const node = nodes.get(id)!\n        if (prev !== undefined && !node.deps.includes(prev)) node.deps.push(prev)\n      }\n    },\n  })\n}\n",
+    "test": "// A test for the example `graph` 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-graph-'))\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. `chain()`, 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, 'graph.ts'))\n  await Bun.write(\n    path.join(root, '.vx/workspace.mjs'),\n    `import { chain } 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('each named task waits on the one before it in id order', async () => {\n  for (const name of ['a', 'b', 'c']) {\n    await pkg(name, `export default { tasks: { build: { exec: { command: 'true' } } } }`)\n  }\n  await workspace(`chain('build')`)\n  const plan = await planRun({ cwd: root, tasks: ['build'], log: log() })\n  expect(plan.tasks.map((t) => `${t.node.id} <- ${t.deps.join(',')}`).sort()).toEqual([\n    'a#build <- ',\n    'b#build <- a#build',\n    'c#build <- b#build',\n  ])\n}, 20_000)\n\n// Id order alone put a#build before b#build even when a#build already\n// waits on b#build: the added edge closed a cycle and the run was refused.\nit('chains in dependency order, never closing a cycle', async () => {\n  await pkg(\n    'a',\n    `export default { tasks: { build: { exec: { command: 'true' }, dependsOn: ['b#build'] } } }`,\n  )\n  for (const name of ['b', 'c']) {\n    await pkg(name, `export default { tasks: { build: { exec: { command: 'true' } } } }`)\n  }\n  await workspace(`chain('build')`)\n  const plan = await planRun({ cwd: root, tasks: ['build'], log: log() })\n  expect(plan.tasks.map((t) => `${t.node.id} <- ${t.deps.join(',')}`).sort()).toEqual([\n    'a#build <- b#build',\n    'b#build <- ',\n    'c#build <- a#build',\n  ])\n}, 20_000)\n"
+  },
+  "key": {
+    "plugin": "// `key`: extra cache-key material. The value of each named environment\n// variable goes into every cached task's key and is 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      inputs: { files: ['package.json'] }, outputs: { files: [] }, cache: true,\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": "// `project`: a project's tasks. Every script in the project's package.json\n// becomes a task of the same name that runs it, unless the project already\n// declares one. Core reads no package.json, so the plugin does. Core\n// re-validates each edit as it would the user's own config, so a blank\n// script, or one no task can be named after (`taskNameProblem`: a `#`\n// comment key), is left out.\nimport { definePlugin, taskNameProblem, type VxPlugin } from '@vzn/vx'\n\nexport function scriptTasks(): VxPlugin {\n  return definePlugin(import.meta, {\n    async project(config, ctx) {\n      const pkg: unknown = await Bun.file(`${ctx.dir}/package.json`)\n        .json()\n        .catch(() => null)\n      const scripts = (pkg as { scripts?: unknown } | null)?.scripts\n      if (scripts === null || typeof scripts !== 'object') return\n      config.tasks ??= {}\n      for (const [name, command] of Object.entries(scripts)) {\n        if (typeof command !== 'string' || command.trim() === '') continue\n        if (config.tasks[name] !== undefined || taskNameProblem(name) !== null) continue\n        config.tasks[name] = { exec: { command } }\n      }\n    },\n  })\n}\n",
+    "test": "// A test for the example `project` 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-project-'))\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. `scriptTasks()`, 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, 'project.ts'))\n  await Bun.write(\n    path.join(root, '.vx/workspace.mjs'),\n    `import { scriptTasks } 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 package.json script runs as a task; a declared task wins', async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: { build: { exec: { command: 'echo declared > build.txt' } } } }`,\n    { hello: 'echo hi > hello.txt', build: 'echo script > build.txt' },\n  )\n  await workspace('scriptTasks()')\n  const r = await run({ cwd: root, tasks: ['hello', 'build'], log: log(), handleSignals: false })\n  expect(r.outcomes.map((o) => `${o.node.id} ${o.status}`).sort()).toEqual([\n    'a#build success',\n    'a#hello success',\n  ])\n  expect(await Bun.file(path.join(dir, 'hello.txt')).text()).toBe('hi\\n')\n  expect(await Bun.file(path.join(dir, 'build.txt')).text()).toBe('declared\\n')\n}, 20_000)\n\n// A blank script, or one no task can be named after (a `#` comment key),\n// was handed to core, which refused the project: every run of it failed.\nit('leaves out a blank script and one no task can be named after', async () => {\n  const dir = await pkg('a', `export default { tasks: {} }`, {\n    '# notes': 'see README',\n    test: '',\n    hello: 'echo hi > hello.txt',\n  })\n  await workspace('scriptTasks()')\n  const r = await run({ cwd: root, tasks: ['hello'], log: log(), handleSignals: false })\n  expect(r.outcomes.map((o) => `${o.node.id} ${o.status}`)).toEqual(['a#hello success'])\n  expect(await Bun.file(path.join(dir, 'hello.txt')).text()).toBe('hi\\n')\n}, 20_000)\n"
+  },
+  "schedule": {
+    "plugin": "// `schedule`: which ready task runs first. Tasks named here outrank the rest;\n// earlier in the list, higher.\nimport { definePlugin, type VxPlugin } from '@vzn/vx'\n\nexport function prioritize(ids: readonly string[]): VxPlugin {\n  return definePlugin(import.meta, {\n    schedule(nodes) {\n      const weights = new Map<string, number>()\n      for (const [i, id] of ids.entries()) if (nodes.has(id)) weights.set(id, 1e6 - i)\n      return weights\n    },\n  })\n}\n",
+    "test": "// A test for the example `schedule` 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-schedule-'))\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. `prioritize()`, 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, 'schedule.ts'))\n  await Bun.write(\n    path.join(root, '.vx/workspace.mjs'),\n    `import { prioritize } 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 named task starts first on one worker, whichever it is', async () => {\n  for (const name of ['a', 'b']) {\n    await pkg(name, `export default { tasks: { build: { exec: { command: 'true' } } } }`)\n  }\n  const first = async (id: string): Promise<string | undefined> => {\n    await workspace(`prioritize([${JSON.stringify(id)}])`)\n    const order: string[] = []\n    await run({\n      cwd: root,\n      tasks: ['build'],\n      log: log(order),\n      handleSignals: false,\n      concurrency: 1,\n    })\n    return order[0]\n  }\n  expect(await first('b#build')).toBe('start b#build')\n  expect(await first('a#build')).toBe('start a#build')\n}, 20_000)\n"
+  },
+  "telemetry": {
+    "plugin": "// `telemetry`: who observes. One JSON line per run, appended to a file.\n// Observability never breaks a run: a sink that throws is switched off,\n// and `flush` is where slow I/O goes (core bounds it).\nimport { appendFile } from 'node:fs/promises'\nimport path from 'node:path'\nimport { definePlugin, type VxPlugin } from '@vzn/vx'\n\nexport function jsonlTelemetry(file: string): VxPlugin {\n  return definePlugin(import.meta, {\n    telemetry(ctx) {\n      // From the root, not the cwd: a run in a project's directory appends\n      // to the same file as one at the root.\n      const to = path.resolve(ctx.workspaceRoot, file)\n      const lines: string[] = []\n      return {\n        onRunSummary(s) {\n          lines.push(\n            JSON.stringify({ tasks: s.taskCount, failed: s.failedCount, cached: s.hitCount }),\n          )\n        },\n        async flush() {\n          if (lines.length > 0) await appendFile(to, lines.splice(0).join('\\n') + '\\n')\n        },\n      }\n    },\n  })\n}\n",
+    "test": "// A test for the example `telemetry` 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, type TelemetrySink } from '@vzn/vx'\nimport { jsonlTelemetry } from './telemetry.ts'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-telemetry-'))\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. `jsonlTelemetry()`, 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, 'telemetry.ts'))\n  await Bun.write(\n    path.join(root, '.vx/workspace.mjs'),\n    `import { jsonlTelemetry } 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('appends one line per run', async () => {\n  await pkg('a', `export default { tasks: { hello: { exec: { command: 'true' } } } }`)\n  const file = path.join(root, 'runs.jsonl')\n  await workspace(`jsonlTelemetry(${JSON.stringify(file)})`)\n  await run({ cwd: root, tasks: ['hello'], log: log(), handleSignals: false })\n  await run({ cwd: root, tasks: ['hello'], log: log(), handleSignals: false })\n  expect(await Bun.file(file).text()).toBe(\n    '{\"tasks\":1,\"failed\":0,\"cached\":0}\\n{\"tasks\":1,\"failed\":0,\"cached\":0}\\n',\n  )\n}, 20_000)\n\n// Read against the process's cwd, a relative file was another file for a\n// run started in a project's directory, written inside that project.\nit('writes a relative file at the workspace root', async () => {\n  const elsewhere = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-telemetry-cwd-'))\n  const cwd = process.cwd()\n  process.chdir(elsewhere)\n  try {\n    const plugin = jsonlTelemetry('runs.jsonl')\n    const sink = (await plugin.telemetry!({ workspaceRoot: root } as never)) as TelemetrySink\n    sink.onRunSummary!({ taskCount: 2, failedCount: 0, hitCount: 1 } as never)\n    await sink.flush!(new AbortController().signal)\n  } finally {\n    process.chdir(cwd)\n    await rm(elsewhere, { recursive: true, force: true })\n  }\n  expect(await Bun.file(path.join(root, 'runs.jsonl')).text()).toBe(\n    '{\"tasks\":2,\"failed\":0,\"cached\":1}\\n',\n  )\n})\n"
+  }
 }

package/src/cli/run.ts

@@ -19,17 +19,12 @@ import {
   parseCachePolicy,
 } from '../cache/index.js'
 import { affectedFilterFor, findCwdSelection, pickTask, resolveFilters } from './select.js'
-import { nxTargetHint, taskNamesHere } from './task-verb.js'
-import {
-  detectColors,
-  envFlagOn,
-  hasControl,
-  parseDecimalInt,
-  sayNotice,
-  sayLine,
-} from '../util/index.js'
+import { nxTargetHint, taskNamesHere, undeclaredTasks } from './task-verb.js'
+import { envFlagOn, hasControl, parseDecimalInt } from '../util/index.js'
+import * as ui from '../ui/index.js'
+import { sayNotice, sayLine } from '../ui/index.js'
 import { kindHint, parseSettingValue, type Setting, SETTINGS, settingRefusal } from '../settings.js'
-import { formatPlanJson, formatPlanText } from './plan-format.js'
+import { formatPlanJson, planReport } from './plan-format.js'
 
 export interface RunArgs {
   /** Failure propagation (`--continue[=never|deps-ok|always]`). */
@@ -80,6 +75,12 @@ export interface RunArgs {
    * `defaultAffectedBase`). Any other string is an explicit git ref.
    */
   affected: string | undefined
+  /**
+   * A bare `--affected` or `--profile` followed by a word: the word is read
+   * as a task, and when no project declares it the refusal names the `=`
+   * form the user likely meant.
+   */
+  spaced?: { flag: '--affected' | '--profile'; value: string }
   error?: string
 }
 
@@ -154,6 +155,12 @@ export function parseRunArgs(args: readonly string[], verb: 'run' | 'watch' = 'r
   let noCacheFlag = false
   let forceFlag = false
 
+  // Its value optional, the flag cannot take the next word: `--affected
+  // main build` reads `main` as a task, so only a refusal of it says why.
+  const spacedValue = (flag: '--affected' | '--profile', next: string | undefined): void => {
+    if (next !== undefined && !next.startsWith('-')) out.spaced ??= { flag, value: next }
+  }
+
   for (let i = 0; i < before.length; i++) {
     const a = before[i]
     if (a === '--filter' || a?.startsWith('--filter=')) {
@@ -294,6 +301,7 @@ export function parseRunArgs(args: readonly string[], verb: 'run' | 'watch' = 'r
       out.dry = fmt
     } else if (a === '--profile') {
       out.profile = 'profile.json'
+      spacedValue('--profile', before[i + 1])
     } else if (a?.startsWith('--profile=')) {
       // An optional-value flag: an empty `=` means "no value given", so it
       // takes the same documented default as the bare form. Resolving ''
@@ -302,6 +310,7 @@ export function parseRunArgs(args: readonly string[], verb: 'run' | 'watch' = 'r
       out.profile = a.slice('--profile='.length) || 'profile.json'
     } else if (a === '--affected') {
       out.affected = ''
+      spacedValue('--affected', before[i + 1])
     } else if (a?.startsWith('--affected=')) {
       out.affected = a.slice('--affected='.length)
     } else if (a === '--poll') {
@@ -505,6 +514,8 @@ export async function resolveRunOptions(
       // `pkg#task`, which resolves to its own project regardless of
       // scope. An empty project list keeps the bare tasks unselected
       // while the anchored ones still run.
+      const typo = await undeclaredTasks(bareTasks, cwd)
+      if (typo !== undefined) return { error: typo, code: 'VX_E_UNKNOWN_TASK' }
       if (anchoredTasks.length === 0) return { nothingSelected: resolved.empty }
       sayNotice('info', 'vx run', `${resolved.empty} — running ${anchoredTasks.join(', ')} only`)
       projects = []
@@ -587,6 +598,8 @@ export async function runCmd(args: readonly string[]): Promise<number> {
   }
 
   const cwd = process.cwd()
+  const unknownTask = async (message: string): Promise<number> =>
+    refuse('run', args, `${message}${await spacedHint(parsed, cwd)}`, 'VX_E_UNKNOWN_TASK')
   if (parsed.profile !== undefined) {
     const problem = profileProblem(cwd, parsed.profile)
     if (problem !== undefined) return refuse('run', args, problem, 'VX_E_USAGE')
@@ -647,12 +660,14 @@ export async function runCmd(args: readonly string[]): Promise<number> {
 
   const scopeOut: { affectedBase?: string } = {}
   const resolved = await resolveRunOptions(parsed, cwd, tasks, 'run', scopeOut)
-  if ('error' in resolved) return refuse('run', args, resolved.error, resolved.code ?? 'VX_E_USAGE')
+  if ('error' in resolved)
+    return resolved.code === 'VX_E_UNKNOWN_TASK'
+      ? unknownTask(resolved.error)
+      : refuse('run', args, resolved.error, resolved.code ?? 'VX_E_USAGE')
   // `--dry=json` prints a plan even when there is nothing to run: a script
   // reading stdout broke exactly then (Growth, 2026-10-16).
   const nothingToRun = (): 0 => {
-    if (parsed.dry === 'json')
-      process.stdout.write(formatPlanJson({ tasks: [] }, scopeOut.affectedBase))
+    if (parsed.dry === 'json') ui.data('out', formatPlanJson({ tasks: [] }, scopeOut.affectedBase))
     return 0
   }
   if ('nothingSelected' in resolved) {
@@ -676,11 +691,8 @@ export async function runCmd(args: readonly string[]): Promise<number> {
     const plan = await planRun(opts)
     // Refused as a run refuses: `--dry=json` gets the error document.
     if (plan.unresolvedTasks !== undefined && plan.unresolvedTasks.length > 0) {
-      return refuse(
-        'run',
-        args,
+      return unknownTask(
         `no projects declare task(s): ${plan.unresolvedTasks.join(', ')}.${plan.unresolvedHint ?? ''}`,
-        'VX_E_UNKNOWN_TASK',
       )
     }
     if (plan.tasks.length === 0) {
@@ -694,17 +706,12 @@ export async function runCmd(args: readonly string[]): Promise<number> {
         sayNotice('info', 'vx run', `no affected project declares task(s): ${tasks.join(', ')}`)
         return nothingToRun()
       }
-      return refuse(
-        'run',
-        args,
-        `no projects declare task(s): ${tasks.join(', ')}`,
-        'VX_E_UNKNOWN_TASK',
-      )
+      return unknownTask(`no projects declare task(s): ${tasks.join(', ')}`)
     }
     if (parsed.dry === 'json') {
-      process.stdout.write(formatPlanJson(plan, scopeOut.affectedBase))
+      ui.data('out', formatPlanJson(plan, scopeOut.affectedBase))
     } else {
-      process.stdout.write(formatPlanText(plan, detectColors(process.stdout)))
+      ui.print('out', planReport(plan))
     }
     return 0
   }
@@ -715,12 +722,24 @@ export async function runCmd(args: readonly string[]): Promise<number> {
   // is no whole-run delegation seam to consult.
   const summary = await runOrchestrator(opts)
   if (summary.refused !== undefined) {
-    const unknown = summary.refused.startsWith('no projects declare')
-    return refuse('run', args, summary.refused, unknown ? 'VX_E_UNKNOWN_TASK' : 'VX_E_REFUSED')
+    return summary.refused.startsWith('no projects declare')
+      ? unknownTask(summary.refused)
+      : refuse('run', args, summary.refused, 'VX_E_REFUSED')
   }
   return summary.ok ? 0 : 1
 }
 
+/**
+ * The `=` form a refused task name was likely meant as: the word after a
+ * bare `--affected` or `--profile`, when no project declares it.
+ */
+export async function spacedHint(parsed: RunArgs, cwd: string): Promise<string> {
+  const s = parsed.spaced
+  if (s === undefined || (await undeclaredTasks([s.value], cwd)) === undefined) return ''
+  const what = s.flag === '--affected' ? 'base' : 'file'
+  return ` \`${s.flag}\` takes its ${what} with '=': ${s.flag}=${s.value}`
+}
+
 /**
  * Why `--profile` cannot write `target`, or undefined. Asked before the
  * run: a directory named as the file died with EISDIR only after it. A

package/src/cli/select.ts

@@ -37,12 +37,13 @@ import {
   nearest,
   relPosix,
   UserError,
-  sayNotice,
-  ui,
 } from '../util/index.js'
+import * as ui from '../ui/index.js'
+import { sayNotice } from '../ui/index.js'
 import {
   claimedAffected,
   claimedExtraFiles,
+  claimedDigests,
   fingerprintClaims,
   gitOfDiscovery,
   hasHook,
@@ -132,6 +133,7 @@ async function workspaceFingerprintClaims(
     files: new Set(claims.keys()),
     affected: (change) => claimedAffected(claims.get(change.file)!, change, ctx),
     extraFiles: (file, bytes) => claimedExtraFiles(claims.get(file)!, file, bytes, ctx),
+    digests: (file) => claimedDigests(claims.get(file)!, file, ctx),
   }
 }
 
@@ -705,6 +707,31 @@ function didYouMean(
   return best !== undefined ? `. Did you mean tag:${best}?` : `. Tags: ${listed(known)}`
 }
 
+/**
+ * The patterns a comma list names, or one when it is none. A comma inside
+ * a glob's braces is no list (`./packages/{a,b}`), and a braced directory
+ * list (Turbo's `{cli,docs}`) is one braced directory each: split at every
+ * comma, it hinted `--filter {cli --filter docs}`.
+ */
+function commaList(pattern: string): string[] {
+  const braced = pattern.length > 2 && pattern.startsWith('{') && pattern.endsWith('}')
+  const body = braced ? pattern.slice(1, -1) : pattern
+  const parts: string[] = []
+  let depth = 0
+  let start = 0
+  for (let i = 0; i <= body.length; i++) {
+    const c = body[i]
+    if (c === '{') depth++
+    else if (c === '}') depth--
+    else if (i === body.length || (c === ',' && depth === 0)) {
+      const part = body.slice(start, i)
+      if (part !== '') parts.push(braced ? `{${part}}` : part)
+      start = i + 1
+    }
+  }
+  return parts
+}
+
 /** `. Did you mean @acme/app?` for the first unmatched pattern within two edits of a project name. */
 function didYouMeanProject(
   unmatched: readonly string[],
@@ -725,15 +752,26 @@ function didYouMeanProject(
       return '. `//` is the workspace root, which is no project here: add a vx.config there and run `vx lock`'
     }
     // Nx's `--projects=a,b`: the edit distance hinted the first name alone.
-    const parts = pattern.split(',').filter((p) => p !== '')
+    const parts = commaList(pattern)
     if (parts.length > 1) {
       return `. A filter is one pattern: ${parts.map((p) => `--filter ${p}`).join(' ')}`
     }
+    // The pattern as typed with the name put right: `apq...` hinted `app`,
+    // and the run it was copied into dropped the dependencies.
+    const meant = (name: string): string => `. Did you mean ${pattern.replace(typed, name)}?`
+    // A task id where a project goes (`--filter app#build`): the filter
+    // takes the project, and the projects listed beside it hid why.
+    const hash = typed.indexOf('#')
+    const project = typed.slice(0, Math.max(hash, 0))
+    const owner =
+      hash <= 0 ? undefined : names.includes(project) ? project : nearest(project, names)
+    if (owner !== undefined)
+      return `. A filter names projects; did you mean ${pattern.replace(typed, owner)}?`
     const best = nearest(typed, names)
-    if (best !== undefined) return `. Did you mean ${best}?`
+    if (best !== undefined) return meant(best)
     const bare = byBare.has(typed) ? typed : nearest(typed, byBare.keys())
     const scoped = bare === undefined ? undefined : byBare.get(bare)
-    if (scoped?.length === 1) return `. Did you mean ${scoped[0]}?`
+    if (scoped?.length === 1) return meant(scoped[0]!)
   }
   return names.length === 0 ? '' : `. Projects: ${listed(names)}`
 }