@vzn/vx 0.0.646 → 0.0.649

package/src/cli/plan-format.ts

@@ -1,7 +1,17 @@
 // Formatters for `--dry` (human / JSON).
 
 import type { AffectedReason, CacheStatus, RunPlan } from '../orchestrator/index.js'
-import { formatBytes, formatElapsed, maskedCommand } from '../util/index.js'
+import { skippedReason } from '../report/index.js'
+import {
+  formatBytes,
+  formatElapsed,
+  maskedCommand,
+  paint,
+  SUCCESS,
+  ui,
+  WARN,
+  type ColorSupport,
+} from '../util/index.js'
 
 /**
  * Human-readable preview. One line per real task (groups hidden, same
@@ -16,25 +26,36 @@ import { formatBytes, formatElapsed, maskedCommand } from '../util/index.js'
  *   3 task(s) planned, 2 cache hits (1 local, 1 remote), 1 would run.
  *   predicted: ~1.20s wall · ~1.20s total execution
  */
-export function formatPlanText(plan: RunPlan): string {
-  const real = plan.tasks.filter((t) => t.cacheStatus !== 'group')
-  if (real.length === 0) return 'No tasks planned.\n'
+export function formatPlanText(plan: RunPlan, c: ColorSupport = { enabled: false }): string {
+  // A group the platform skip reaches is still a group: it runs nothing.
+  const real = plan.tasks.filter(
+    (t) =>
+      t.cacheStatus !== 'group' &&
+      (t.cacheStatus !== 'skipped' || t.node.config.exec !== undefined),
+  )
+  const dim = (s: string): string => paint('', s, c, { dim: true })
+  if (real.length === 0) return `${dim('No tasks planned.')}\n`
 
   const idWidth = Math.max(...real.map((t) => t.node.id.length))
   const tagWidth = 24
 
-  const lines: string[] = ['would run:']
+  const lines: string[] = [paint('', 'would run:', c, { bold: true })]
   let local = 0
   let remote = 0
   let miss = 0
   let nocache = 0
   let noop = 0
   let idle = 0
+  let platform = 0
   for (const t of real) {
     // `@noop`: the run succeeds it without running, whatever its key says.
-    const skipped = t.executor === 'noop'
+    const skipped = t.executor === 'noop' && t.cacheStatus !== 'skipped'
     const sym = skipped ? '·' : symbolFor(t.cacheStatus)
-    const desc = skipped ? 'noop — would not run' : describe(t.cacheStatus)
+    const desc = skipped
+      ? 'noop — would not run'
+      : t.cacheStatus === 'skipped'
+        ? `skipped — ${skippedReason(t)}`
+        : describe(t.cacheStatus)
     const shortHash = t.hash ? t.hash.slice(0, 8) : ''
     const executes = !skipped && (t.cacheStatus === 'miss' || t.cacheStatus === 'no-cache')
     const eta = executes && t.p50Ms !== undefined ? `  ~${formatElapsed(t.p50Ms)}` : ''
@@ -43,17 +64,18 @@ export function formatPlanText(plan: RunPlan): string {
     // tier, and a task placed on a named executor is what the reader can
     // act on. Present only when the workspace declared a choice.
     const where = t.executor !== undefined ? `  @${t.executor}` : ''
+    const hue = skipped ? '' : HUE[t.cacheStatus]
     lines.push(
-      `  ${sym}  ${t.node.id.padEnd(idWidth)}  ${desc.padEnd(tagWidth)}  ${shortHash}${eta}${where}`,
+      `  ${paint(hue, sym, c, { dim: hue === '' })}  ${ui.inline(ui.id(t.node.id), c)}${' '.repeat(idWidth - t.node.id.length)}  ${paint(hue, desc.padEnd(tagWidth), c, { dim: hue === '' })}  ${dim(shortHash)}${dim(eta)}${where}`,
     )
     // Optional one-line description from the task config, indented
     // under the id so the eye picks up the task → blurb mapping.
     const taskDesc = shownDescription(t)
     if (taskDesc) {
-      lines.push(`     ${' '.repeat(idWidth)}  ${taskDesc}`)
+      lines.push(`     ${' '.repeat(idWidth)}  ${dim(taskDesc)}`)
     }
     if (t.affected !== undefined) {
-      lines.push(`     ${' '.repeat(idWidth)}  affected: ${describeReason(t.affected)}`)
+      lines.push(`     ${' '.repeat(idWidth)}  ${dim(`affected: ${describeReason(t.affected)}`)}`)
     }
     if (skipped) noop++
     else if (t.cacheStatus === 'hit-local') local++
@@ -61,6 +83,7 @@ export function formatPlanText(plan: RunPlan): string {
     else if (t.cacheStatus === 'miss') miss++
     else if (t.cacheStatus === 'no-cache') nocache++
     else if (t.cacheStatus === 'not-started') idle++
+    else if (t.cacheStatus === 'skipped') platform++
   }
 
   const hitParts: string[] = []
@@ -77,8 +100,9 @@ export function formatPlanText(plan: RunPlan): string {
   if (nocache > 0) summary.push(`${nocache} no-cache`)
   if (noop > 0) summary.push(`${noop} noop`)
   if (idle > 0) summary.push(`${idle} not started`)
+  if (platform > 0) summary.push(`${platform} skipped`)
   lines.push('')
-  lines.push(summary.join(', ') + '.')
+  lines.push(dim(summary.join(', ') + '.'))
 
   // `--cache-download` is invisible without this: the eligibility gate silently
   // keeps producers eager, so a user who asked for `none` and got no
@@ -89,11 +113,14 @@ export function formatPlanText(plan: RunPlan): string {
   if (deferred.length > 0 || downgrades.length > 0) {
     lines.push('')
     lines.push(
-      `download: ${deferred.length} task(s) would keep outputs remote` +
-        (downgrades.length > 0 ? `, ${downgrades.length} kept eager:` : '.'),
+      dim(
+        `download: ${deferred.length} task(s) would keep outputs remote` +
+          (downgrades.length > 0 ? `, ${downgrades.length} kept eager:` : '.'),
+      ),
     )
-    for (const d of downgrades.slice(0, 3)) lines.push(`    ${d.taskId} — ${d.reason}`)
-    if (downgrades.length > 3) lines.push(`    …and ${downgrades.length - 3} more`)
+    for (const d of downgrades.slice(0, 3))
+      lines.push(`    ${ui.inline(ui.id(d.taskId), c)} ${dim(`— ${d.reason}`)}`)
+    if (downgrades.length > 3) lines.push(dim(`    …and ${downgrades.length - 3} more`))
   }
 
   // Time prediction — only when history gave us something to say: at least
@@ -106,7 +133,7 @@ export function formatPlanText(plan: RunPlan): string {
     if (p.unknownCount > 0) {
       parts.push(`${p.unknownCount} task${p.unknownCount === 1 ? '' : 's'} without history (+?)`)
     }
-    lines.push(parts.join(' · '))
+    lines.push(dim(parts.join(' · ')))
   }
   return lines.join('\n') + '\n'
 }
@@ -149,6 +176,8 @@ export interface PlanTaskJson {
   download?: 'deferred'
   description?: string
   affected?: AffectedReason
+  otherPlatform?: { readonly needs: readonly string[]; readonly host: string }
+  blockedBy?: string
 }
 
 /** `affectedBase`: the ref a bare `--affected` guessed (or was given), so a reader knows what the diff was against. */
@@ -157,42 +186,51 @@ export function formatPlanJson(
   affectedBase?: string,
 ): string {
   return (
-    JSON.stringify(
-      {
-        ...(affectedBase !== undefined ? { affectedBase } : {}),
-        tasks: plan.tasks.map((t): PlanTaskJson => {
-          const description = shownDescription(t)
-          return {
-            id: t.node.id,
-            project: t.node.projectName,
-            task: t.node.taskName,
-            hash: t.hash,
-            cacheStatus: t.cacheStatus,
-            deps: t.deps,
-            ...(t.p50Ms !== undefined ? { p50Ms: t.p50Ms } : {}),
-            ...(t.executor !== undefined ? { executor: t.executor } : {}),
-            ...(t.download !== undefined ? { download: t.download } : {}),
-            ...(description !== undefined ? { description } : {}),
-            ...(t.affected !== undefined ? { affected: t.affected } : {}),
-          }
-        }),
-        ...(plan.predicted !== undefined ? { predicted: plan.predicted } : {}),
-        // The gate's refusals belong on the SCRIPTING surface too: a CI job
-        // asking "did --cache-download=none actually defer anything, and if not
-        // why" reads this, not the human table. (This object enumerates its
-        // fields deliberately — the plan's internal shape is not the wire —
-        // which is exactly why a new PlannedTask field does not appear here
-        // for free, and why `download` above had to be added by hand.)
-        ...(plan.downloadDowngrades !== undefined
-          ? { downloadDowngrades: plan.downloadDowngrades }
-          : {}),
-      },
-      null,
-      2,
-    ) + '\n'
+    JSON.stringify({
+      ...(affectedBase !== undefined ? { affectedBase } : {}),
+      tasks: plan.tasks.map((t): PlanTaskJson => {
+        const description = shownDescription(t)
+        return {
+          id: t.node.id,
+          project: t.node.projectName,
+          task: t.node.taskName,
+          hash: t.hash,
+          cacheStatus: t.cacheStatus,
+          deps: t.deps,
+          ...(t.p50Ms !== undefined ? { p50Ms: t.p50Ms } : {}),
+          ...(t.executor !== undefined ? { executor: t.executor } : {}),
+          ...(t.download !== undefined ? { download: t.download } : {}),
+          ...(description !== undefined ? { description } : {}),
+          ...(t.affected !== undefined ? { affected: t.affected } : {}),
+          ...(t.otherPlatform !== undefined ? { otherPlatform: t.otherPlatform } : {}),
+          ...(t.blockedBy !== undefined ? { blockedBy: t.blockedBy } : {}),
+        }
+      }),
+      ...(plan.predicted !== undefined ? { predicted: plan.predicted } : {}),
+      // The gate's refusals belong on the SCRIPTING surface too: a CI job
+      // asking "did --cache-download=none actually defer anything, and if not
+      // why" reads this, not the human table. (This object enumerates its
+      // fields deliberately — the plan's internal shape is not the wire —
+      // which is exactly why a new PlannedTask field does not appear here
+      // for free, and why `download` above had to be added by hand.)
+      ...(plan.downloadDowngrades !== undefined
+        ? { downloadDowngrades: plan.downloadDowngrades }
+        : {}),
+    }) + '\n'
   )
 }
 
+/** A hit is green, a task that would run is yellow, the rest dim. */
+const HUE: Record<CacheStatus, string> = {
+  'hit-local': SUCCESS,
+  'hit-remote': SUCCESS,
+  miss: WARN,
+  'no-cache': WARN,
+  group: '',
+  'not-started': '',
+  skipped: '',
+}
+
 function symbolFor(s: CacheStatus): string {
   switch (s) {
     case 'hit-local':
@@ -207,6 +245,8 @@ function symbolFor(s: CacheStatus): string {
       return '○'
     case 'not-started':
       return '−'
+    case 'skipped':
+      return '·'
   }
 }
 
@@ -224,5 +264,7 @@ function describe(s: CacheStatus): string {
       return 'group task'
     case 'not-started':
       return 'not started (unneeded)'
+    case 'skipped':
+      return 'skipped'
   }
 }

package/src/cli/plugin-commands.ts

@@ -18,7 +18,14 @@ import type {
   TaskArtifacts,
 } from '../orchestrator/index.js'
 import { configuredBaseBranch, findWorkspaceRoot } from '../workspace/index.js'
-import { machineParallelism, maskedLine, SecretBroker } from '../util/index.js'
+import {
+  machineParallelism,
+  maskedLine,
+  SecretBroker,
+  thrownMessage,
+  ui,
+  UserError,
+} from '../util/index.js'
 import { resolveSetting } from '../settings.js'
 
 export interface ResolvedPluginCommand {
@@ -52,7 +59,7 @@ async function workspacePlugins(cwd: string): Promise<
   | {
       workspaceRoot: string
       cacheDir: string
-      storeRoot: Promise<string | null>
+      storeRoot: () => Promise<string | null>
       workspaceConfig: WorkspaceConfig | null
       concurrency: number
       plugins: readonly VxPlugin[]
@@ -72,7 +79,7 @@ async function workspacePlugins(cwd: string): Promise<
     const { loadCliWorkspace } = await import('./workspace-config.js')
     ws = await loadCliWorkspace(workspaceRoot)
   } catch (err) {
-    return { loadError: err instanceof Error ? err.message : String(err) }
+    return { loadError: thrownMessage(err) }
   }
   return {
     workspaceRoot,
@@ -104,8 +111,10 @@ export async function resolvePluginCommand(
   const declaredVerbs = new Set<string>()
   for (const plugin of ws.plugins) {
     for (const declared of Object.keys(plugin.commands ?? {})) declaredVerbs.add(declared)
-    const command = plugin.commands?.[verb]
-    if (command === undefined) continue
+    // Own keys only: `vx toString` found Object.prototype's and crashed.
+    const commands = plugin.commands
+    if (commands === undefined || !Object.hasOwn(commands, verb)) continue
+    const command = commands[verb]!
     return {
       plugin,
       command,
@@ -127,7 +136,7 @@ export async function resolvePluginCommand(
 }
 
 const warn = (m: string): void => {
-  process.stderr.write(`${maskedLine(m)}\n`)
+  ui.say('warn', maskedLine(m))
 }
 
 /** Read-only: a verb reads what runs stored, and only a run's policy may write. */
@@ -161,7 +170,7 @@ async function verbCache(
     ws.workspaceRoot,
     undefined,
     'open',
-    await ws.storeRoot,
+    await ws.storeRoot(),
   )
   const remotes: ResolvedRemote[] = []
   await resolveCache(ws.plugins, {
@@ -169,7 +178,7 @@ async function verbCache(
     cacheDir: ws.cacheDir,
     warn,
     scope,
-    refs: cacheRefs(ws.workspaceRoot, configuredBaseBranch(ws.workspaceConfig)),
+    refs: cacheRefs(ws.workspaceRoot, configuredBaseBranch(ws.workspaceConfig), ws.branch.refs),
     localCache,
     policy: VERB_POLICY,
     remotes,
@@ -188,7 +197,7 @@ async function verbArtifacts(
   facts?: () => CacheFacts | undefined,
 ): Promise<TaskArtifacts> {
   const [
-    { Cache, FULL_CACHE_POLICY },
+    { Cache, FULL_CACHE_POLICY, parseCachePolicy },
     {
       cacheRefs,
       namesRemote,
@@ -204,9 +213,29 @@ async function verbArtifacts(
     import('../orchestrator/index.js'),
     import('./run.js'),
   ])
-  const asked = workspaceCachePolicy(ws.workspaceConfig) ?? FULL_CACHE_POLICY
+  // `VX_CACHE_POLICY` beats the workspace's `cache.policy`, as it does for a
+  // run, refused as `parseRunArgs` refuses it (cli/run.ts).
+  const envSpec = process.env['VX_CACHE_POLICY'] || undefined
+  let asked: CachePolicy
+  if (envSpec === undefined) {
+    asked = workspaceCachePolicy(ws.workspaceConfig) ?? FULL_CACHE_POLICY
+  } else {
+    if (!envSpec.split(',').some((seg) => seg.trim().length > 0))
+      throw new UserError(
+        'VX_CACHE_POLICY needs a spec like local:r, local:rw, remote:, or local:,remote:rw',
+        'VX_E_USAGE',
+      )
+    try {
+      asked = parseCachePolicy(envSpec)
+    } catch (err) {
+      throw new UserError(
+        `VX_CACHE_POLICY: ${err instanceof Error ? err.message : String(err)}`,
+        'VX_E_USAGE',
+      )
+    }
+  }
   const policy: CachePolicy =
-    onCI(process.env['CI']) || namesRemote(ws.workspaceConfig?.cache?.policy)
+    onCI(process.env['CI']) || namesRemote(envSpec ?? ws.workspaceConfig?.cache?.policy)
       ? asked
       : { ...asked, remoteWrite: false }
   const scope = resolveCacheScope(
@@ -221,7 +250,7 @@ async function verbArtifacts(
     ws.workspaceRoot,
     undefined,
     'open',
-    await ws.storeRoot,
+    await ws.storeRoot(),
   )
   const remotes: ResolvedRemote[] = []
   const cache = await resolveCache(ws.plugins, {
@@ -229,7 +258,9 @@ async function verbArtifacts(
     cacheDir: ws.cacheDir,
     warn,
     scope,
-    refs: facts?.()?.refs ?? cacheRefs(ws.workspaceRoot, configuredBaseBranch(ws.workspaceConfig)),
+    refs:
+      facts?.()?.refs ??
+      cacheRefs(ws.workspaceRoot, configuredBaseBranch(ws.workspaceConfig), ws.branch.refs),
     localCache,
     policy,
     remotes,
@@ -258,6 +289,9 @@ function lazyArtifacts(open: () => Promise<TaskArtifacts>): TaskArtifacts {
   return {
     save: async (key, task, run) => (await artifacts()).save(key, task, run),
     restore: async (key, task) => (await artifacts()).restore(key, task),
+    output: async (key) => (await artifacts()).output(key),
+    share: async (key) => (await artifacts()).share(key),
+    resend: async (key) => (await artifacts()).resend(key),
   }
 }
 
@@ -295,8 +329,30 @@ export async function pluginCommandHelp(cwd = process.cwd()): Promise<string[]>
     for (const [verb, command] of Object.entries(plugin.commands ?? {})) {
       if (seen.has(verb)) continue
       seen.add(verb)
-      lines.push(`  vx ${verb.padEnd(17)} ${command.description} (${plugin.name})`)
+      lines.push(
+        ...helpLines(`  vx ${verb.padEnd(17)} `, `${command.description} (${plugin.name})`),
+      )
     }
   }
   return lines
 }
+
+/**
+ * One help entry: `head` then `text` wrapped at word breaks under the
+ * column `head` ends at, at core's reference width, so a plugin's long
+ * description reads as core's own entries do.
+ */
+function helpLines(head: string, text: string, width = 88): string[] {
+  const indent = ' '.repeat(head.length)
+  const lines: string[] = []
+  let line = head
+  for (const word of text.split(/\s+/)) {
+    const fresh = line === head || line === indent
+    if (!fresh && line.length + 1 + word.length > width) {
+      lines.push(line)
+      line = indent + word
+    } else line += fresh ? word : ` ${word}`
+  }
+  lines.push(line)
+  return lines
+}

package/src/cli/plugin-templates.ts

@@ -1,4 +1,4 @@
-// Generated from packages/vx-plugin-examples/plugins by
+// Generated from private/vx-plugin-examples/plugins by
 // tests/plugin-templates.unsafe.test.ts; edit the examples, then
 // VX_UPDATE_CONTRACT=1 that test. `vx init --plugin <seam>` writes these.
 
@@ -10,33 +10,33 @@ export const PLUGIN_TEMPLATES: Readonly<Record<string, { plugin: string; test: s
   },
   cache: {
     plugin:
-      "// `cache`: where artifacts live. A directory stands in for a remote store;\n// core puts it behind the local cache, so a remote error is a miss and a\n// warning, never a failed run.\nimport { link, mkdir, unlink } from 'node:fs/promises'\nimport path from 'node:path'\nimport { definePlugin, type 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.\n    const tmp = path.join(this.endpoint, `.${hash}.${process.pid}`)\n    await Bun.write(tmp, body)\n    try {\n      await link(tmp, path.join(this.endpoint, hash))\n    } catch (err) {\n      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err\n    } finally {\n      await unlink(tmp)\n    }\n  }\n}\n\nexport function dirCache(dir: string): VxPlugin {\n  return definePlugin(import.meta, {\n    cache() {\n      return new DirRemote(dir)\n    },\n  })\n}\n",
-    test: "// A test for the example `cache` plugin beside it: a throwaway workspace\n// declares the plugin and vx's own run() drives it. `bun test` runs it.\nimport { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'\nimport os from 'node:os'\nimport path from 'node:path'\nimport { afterEach, beforeEach, expect, it } from 'bun:test'\nimport { run, type Logger } from '@vzn/vx'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-cache-'))\n  await writeFile(path.join(root, 'package.json'), JSON.stringify({ name: 'ws', private: true }))\n  await writeFile(path.join(root, 'pnpm-workspace.yaml'), 'packages:\\n  - \"packages/*\"\\n')\n  Bun.spawnSync({ cmd: ['git', 'init', '-q'], cwd: root })\n})\nafterEach(async () => {\n  await rm(root, { recursive: true, force: true })\n})\n\n/** A package `name` whose `vx.config.mjs` is `config`. */\nasync function pkg(\n  name: string,\n  config: string,\n  scripts?: Record<string, string>,\n): Promise<string> {\n  const dir = path.join(root, 'packages', name)\n  await mkdir(dir, { recursive: true })\n  await writeFile(\n    path.join(dir, 'package.json'),\n    JSON.stringify({ name, version: '1.0.0', ...(scripts ? { scripts } : {}) }),\n  )\n  // Core reads no package.json: the config names the project.\n  await writeFile(\n    path.join(dir, 'vx.config.mjs'),\n    config.replace('export default {', `export default { name: ${JSON.stringify(name)},`),\n  )\n  return dir\n}\n\n/**\n * A `.vx/workspace.mjs` declaring `call`, e.g. `dirCache()`, from the plugin file\n * beside this test, then `vx lock`: a run reads project configs only from the lock.\n */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'cache.ts'))\n  await Bun.write(\n    path.join(root, '.vx/workspace.mjs'),\n    `import { dirCache } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\n  const vx = path.join(path.dirname(new URL(import.meta.resolve('@vzn/vx')).pathname), 'bin.ts')\n  const lock = Bun.spawnSync({ cmd: [process.execPath, vx, 'lock'], cwd: root })\n  expect([lock.exitCode, lock.stderr.toString()]).toEqual([0, ''])\n}\n\nfunction log(order: string[] = []): Logger {\n  return {\n    status() {},\n    taskStart(node) {\n      order.push(`start ${node.id}`)\n    },\n    taskStdout() {},\n    taskStderr() {},\n    taskComplete(node) {\n      order.push(`end ${node.id}`)\n    },\n  }\n}\n\nit('a run on an empty local cache restores from the directory', async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: { build: {\n      exec: { command: 'mkdir -p dist && echo built > dist/out.txt' },\n      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",
+      "// `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: { save: async () => {}, restore: async () => null },\n  artifactsFor: () => ({ save: async () => {}, restore: async () => null }),\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",
+    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      // 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 stop = (): void => {\n        try {\n          process.kill(-child.pid, 'SIGTERM')\n        } catch {\n          // already gone\n        }\n      }\n      req.signal?.addEventListener('abort', stop, { once: true })\n      const drain = async (stream: ReadableStream<Uint8Array>, on: (s: string) => void) => {\n        const decoder = new TextDecoder()\n        let all = ''\n        for await (const chunk of stream) {\n          const text = decoder.decode(chunk, { stream: true })\n          all += text\n          on(text)\n        }\n        return all\n      }\n      const [stdout, stderr, exitCode] = await Promise.all([\n        drain(child.stdout, req.onStdout),\n        drain(child.stderr, req.onStderr),\n        child.exited,\n      ])\n      req.signal?.removeEventListener('abort', stop)\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'\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",
+      "// `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 in id order, so they run one after another across projects.\n// Core checks 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 ids = [...nodes.keys()].filter((id) => id.endsWith(`#${task}`)).sort()\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",
+      "// `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 is folded into every cached task's key and named in `vx why`,\n// so a change to it is a miss. An unset variable folds as ''.\nimport { definePlugin, type VxPlugin } from '@vzn/vx'\n\nexport function envKey(names: readonly string[]): VxPlugin {\n  return definePlugin(import.meta, {\n    key() {\n      return Object.fromEntries(names.map((n) => [n, process.env[n] ?? '']))\n    },\n  })\n}\n",
+      "// `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.\nimport { definePlugin, 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' || config.tasks[name] !== undefined) 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",
+      "// `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:
@@ -45,7 +45,7 @@ export const PLUGIN_TEMPLATES: Readonly<Record<string, { plugin: string; test: s
   },
   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 { definePlugin, type VxPlugin } from '@vzn/vx'\n\nexport function jsonlTelemetry(file: string): VxPlugin {\n  return definePlugin(import.meta, {\n    telemetry() {\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(file, 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 } from '@vzn/vx'\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",
+      "// `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",
   },
 }