@vzn/vx 0.0.90 → 0.0.92

package/README.md

@@ -88,6 +88,8 @@ rm -rf packages/*/dist
 npx vx run build --all    # restored from the cache, not rebuilt
 ```
 
+<img src="https://vznjs.github.io/vx/demo.svg" width="760" alt="vx run ci --all on examples/basic: cold, three tasks run; again, three up-to-date.">
+
 Or copy [`examples/basic`](examples/basic), a two-package starter CI
 runs on every commit. More: [Quickstart](https://vznjs.github.io/vx/quickstart/) ·
 [Configure](https://vznjs.github.io/vx/guides/configure/) ·
@@ -112,6 +114,10 @@ When you want configs of your own, one command writes them:
 bunx @vzn/vx-migrate      # vx.config.ts per package, from turbo.json or an Nx graph
 ```
 
+The written configs derive the same cache keys, so what `turbo()` cached
+still hits: [`examples/turbo`](examples/turbo) runs both steps on every
+commit.
+
 `turboCache()` and `nxCache()` keep the remote cache you have (Turbo's
 `/v8/artifacts` API, Vercel's included, or Nx's `/v1/cache`). What each
 Turbo and Nx feature is in vx, pinned by a test:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.90",
-  "description": "An open, extensible monorepo task runner.",
+  "version": "0.0.92",
+  "description": "A fast, correct task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
     ".": {
@@ -17,10 +17,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.90",
-    "@vzn/vx-linux-arm64": "0.0.90",
-    "@vzn/vx-darwin-x64": "0.0.90",
-    "@vzn/vx-darwin-arm64": "0.0.90"
+    "@vzn/vx-linux-x64": "0.0.92",
+    "@vzn/vx-linux-arm64": "0.0.92",
+    "@vzn/vx-darwin-x64": "0.0.92",
+    "@vzn/vx-darwin-arm64": "0.0.92"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"
@@ -36,16 +36,20 @@
     "type": "git",
     "url": "git+https://github.com/vznjs/vx.git"
   },
-  "homepage": "https://github.com/vznjs/vx#readme",
+  "homepage": "https://vznjs.github.io/vx/",
   "bugs": "https://github.com/vznjs/vx/issues",
   "license": "MIT",
   "keywords": [
+    "vx",
     "monorepo",
     "task-runner",
-    "build",
+    "build-cache",
+    "build-system",
     "cache",
-    "bun",
     "turborepo",
-    "nx"
+    "nx",
+    "bun",
+    "workspaces",
+    "ci"
   ]
 }

package/src/cache/cache.ts

@@ -40,6 +40,7 @@ import {
   span,
   splitTaskId,
   taskGlob,
+  xxh3hex,
 } from '../util/index.js'
 import {
   ArchiveSecurityError,
@@ -655,7 +656,7 @@ export class Cache implements CacheLayer {
     this.files = new FileHashStore(this.db, cacheDir, this.write, repoDir)
     this.configEvals = new ConfigEvalTable(this.db, { read: this.read, write: this.write })
     this.outputs = new OutputIndex(this.db)
-    this.history = new RunHistory(this.db)
+    this.history = new RunHistory(this.db, (v) => this.digestValue(v))
 
     // A CACHE_VERSION bump keeps the index but moves every key, so the run
     // after an upgrade misses everything. Roadmap 3.3: that is announced,
@@ -753,9 +754,47 @@ export class Cache implements CacheLayer {
       input,
       (f) => this.hashFile(f),
       (f) => this.relFor(input.workspaceRoot, f),
+      (v) => this.digestValue(v),
     )
   }
 
+  private valueSalt: string | undefined
+
+  /**
+   * The digest a value-bearing row holds (an env value, a runtime output,
+   * args after `--`): xxh3 under a random salt this store keeps. `vx why`,
+   * its JSON and MCP's `whyDidThisRerun` print it, and an unkeyed xxh3 in
+   * a public CI log let anyone confirm or brute-force a short secret
+   * (L-4). Salted, a digest still says whether a value changed, and says
+   * nothing without this cache's `schema_meta`. Asked for on a miss only.
+   */
+  private digestValue(value: string): string {
+    this.valueSalt ??= this.loadValueSalt()
+    return xxh3hex(`${this.valueSalt}\0${value}`)
+  }
+
+  private loadValueSalt(): string {
+    const read = (): string | undefined =>
+      (
+        this.db.prepare("SELECT value FROM schema_meta WHERE key = 'value_salt'").get() as {
+          value: string
+        } | null
+      )?.value
+    const found = read()
+    if (found !== undefined) return found
+    const salt = Buffer.from(crypto.getRandomValues(new Uint8Array(16))).toString('hex')
+    // A store this process may not write keeps the salt for the process:
+    // nothing it digests is persisted.
+    if (this.writeBlocked !== null || this.inspecting) return salt
+    // Two processes opening one new store: the first salt stands.
+    this.db
+      .prepare(
+        "INSERT INTO schema_meta(key, value) VALUES ('value_salt', ?) ON CONFLICT(key) DO NOTHING",
+      )
+      .run(salt)
+    return read() ?? salt
+  }
+
   // ctx is accepted but ignored — the local layer reads metadata from
   // the entries row. It's part of the contract so LayeredCache can
   // route metadata to `ingest()` on remote-hit without a separate API.

package/src/cache/key-fold.ts

@@ -99,6 +99,12 @@ export async function foldKey(
   input: CacheKeyInput,
   hashFile: (file: string) => Promise<string>,
   relOf: (file: string) => string,
+  /**
+   * The digest a value-bearing capture row holds. `Cache` keys it with a
+   * salt of its own (L-4); the default is for a caller that persists and
+   * prints nothing.
+   */
+  digestValue: (value: string) => string = xxh3hex,
 ): Promise<string> {
   // Seed-chained xxHash3: each step folds one field into the
   // running digest via `xxh3(part, prevDigest)`. Equivalent to the
@@ -124,16 +130,18 @@ export async function foldKey(
   // DIGEST of each component, never the raw value. For value-bearing kinds
   // (env, runtime, ws-runtime, forward) the payload is a secret or
   // sensitive string (API keys via cache.inputs.env, runtime-command
-  // output, args after `--`), so we push `xxh3hex(v)` — the diff consumer
-  // only needs to know whether a component CHANGED, which a digest
-  // preserves losslessly. cache.db must never hold plaintext secrets at
-  // rest. The cache KEY (`h`) folds the plaintext separately below and is
+  // output, args after `--`), so we push `digestValue(v)` — the diff
+  // consumer only needs to know whether a component CHANGED, which a
+  // digest preserves losslessly. cache.db must never hold plaintext
+  // secrets at rest, and `vx why` prints the digest, so it is salted: an
+  // unkeyed 64-bit xxh3 in a public CI log gave a short secret away to a
+  // brute force (L-4). The cache KEY (`h`) folds the plaintext separately below and is
   // unaffected.
   const forwarded = input.forwardArgs ?? []
   h = xxh3(`forward-args:${forwarded.length}`, h)
   for (const a of forwarded) h = xxh3(a, h)
   if (cap && forwarded.length > 0) {
-    cap.push({ kind: 'forward', name: 'argv', hash: xxh3hex(JSON.stringify(forwarded)) })
+    cap.push({ kind: 'forward', name: 'argv', hash: digestValue(JSON.stringify(forwarded)) })
   }
 
   h = xxh3(`env-values:${input.envValues.length}`, h)
@@ -145,20 +153,20 @@ export async function foldKey(
   for (const [n, v] of input.envValues) h = xxh3(v === undefined ? n : `${n}\0${v}`, h)
   if (cap)
     for (const [n, v] of input.envValues)
-      cap.push({ kind: 'env', name: n, hash: v === undefined ? 'unset' : xxh3hex(v) })
+      cap.push({ kind: 'env', name: n, hash: v === undefined ? 'unset' : digestValue(v) })
 
   const runtimeValues = input.runtimeValues ?? []
   h = xxh3(`runtime-values:${runtimeValues.length}`, h)
   for (const [c, o] of runtimeValues) h = xxh3(`${c}\0${o}`, h)
   if (cap)
-    for (const [c, o] of runtimeValues) cap.push({ kind: 'runtime', name: c, hash: xxh3hex(o) })
+    for (const [c, o] of runtimeValues) cap.push({ kind: 'runtime', name: c, hash: digestValue(o) })
 
   const wsRuntimeValues = input.workspaceRuntimeValues ?? []
   h = xxh3(`ws-runtime-values:${wsRuntimeValues.length}`, h)
   for (const [c, o] of wsRuntimeValues) h = xxh3(`${c}\0${o}`, h)
   if (cap)
     for (const [c, o] of wsRuntimeValues)
-      cap.push({ kind: 'ws-runtime', name: c, hash: xxh3hex(o) })
+      cap.push({ kind: 'ws-runtime', name: c, hash: digestValue(o) })
 
   const upstream = [...input.upstreamHashes].sort()
   h = xxh3(`upstream:${upstream.length}`, h)
@@ -174,7 +182,7 @@ export async function foldKey(
     h = xxh3(`plugin:${pluginParts.length}`, h)
     for (const [n, v] of pluginParts) h = xxh3(`${n}\0${v}`, h)
     if (cap) {
-      for (const [n, v] of pluginParts) cap.push({ kind: 'plugin', name: n, hash: xxh3hex(v) })
+      for (const [n, v] of pluginParts) cap.push({ kind: 'plugin', name: n, hash: digestValue(v) })
     }
   }
 

package/src/cache/run-history.ts

@@ -4,14 +4,17 @@
 // its statements over the store's handle; `Cache` delegates.
 
 import type { Database, SQLQueryBindings } from 'bun:sqlite'
-import { xxh3hex } from '../util/index.js'
 import type { InvocationRecord, RunRecord } from './layer.js'
 
 export class RunHistory {
   private readonly insertRun: ReturnType<Database['prepare']>
   private readonly insertInvocation: ReturnType<Database['prepare']>
 
-  constructor(private readonly db: Database) {
+  constructor(
+    private readonly db: Database,
+    /** The store's salted value digest (L-4). */
+    private readonly digestValue: (value: string) => string,
+  ) {
     this.insertRun = this.db.prepare(`
       INSERT INTO runs(
         hash, project, task, status, exit_code, duration_ms, forward_args,
@@ -37,13 +40,13 @@ export class RunHistory {
   }
 
   recordRun(run: RunRecord): void {
-    this.insertRun.run(...bindRun(run))
+    this.insertRun.run(...bindRun(run, this.digestValue))
   }
 
   recordRuns(runs: readonly RunRecord[]): void {
     if (runs.length === 0) return
     if (runs.length === 1) {
-      this.insertRun.run(...bindRun(runs[0]!))
+      this.insertRun.run(...bindRun(runs[0]!, this.digestValue))
       return
     }
     // `bun:sqlite`'s `transaction()` returns a callable that wraps the
@@ -51,7 +54,7 @@ export class RunHistory {
     // run that's one fsync instead of 200.
     const insert = this.insertRun
     const tx = this.db.transaction((batch: readonly RunRecord[]) => {
-      for (const r of batch) insert.run(...bindRun(r))
+      for (const r of batch) insert.run(...bindRun(r, this.digestValue))
     })
     tx(runs)
   }
@@ -66,7 +69,7 @@ export class RunHistory {
     const insertRun = this.insertRun
     const insertInvocation = this.insertInvocation
     this.db.transaction(() => {
-      for (const r of bundle.runs) insertRun.run(...bindRun(r))
+      for (const r of bundle.runs) insertRun.run(...bindRun(r, this.digestValue))
       insertInvocation.run(...bindInvocation(bundle.invocation))
     })()
   }
@@ -89,7 +92,7 @@ export class RunHistory {
  * `insertRun` prepared statement (21 columns). Shared between the
  * single and batched record paths.
  */
-function bindRun(run: RunRecord): SQLQueryBindings[] {
+function bindRun(run: RunRecord, digestValue: (v: string) => string): SQLQueryBindings[] {
   return [
     // The ONE place the no-key sentinel is applied, so the column's
     // NOT NULL invariant can't be violated from a call site.
@@ -102,7 +105,7 @@ function bindRun(run: RunRecord): SQLQueryBindings[] {
     // A digest, as entry_inputs keeps: args after `--` carry tokens
     // (`--token=…`), and cache.db holds no plaintext secret at rest; nothing
     // reads the column but for whether the args changed (item 1091).
-    run.forwardArgs ? xxh3hex(JSON.stringify(run.forwardArgs)) : null,
+    run.forwardArgs ? digestValue(JSON.stringify(run.forwardArgs)) : null,
     run.startedAt,
     run.endedAt,
     run.runId ?? null,

package/src/cli/cache.ts

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs'
 import { Cache, noteSchemaReset } from '../cache/index.js'
-import { seeHelp } from './help.js'
+import { flagHint, seeHelp } from './help.js'
 import { nearest, parseDuration, parseSize } from '../util/index.js'
 import { acquireRunLock } from '../orchestrator/index.js'
 import { findWorkspaceRoot } from '../workspace/index.js'
@@ -112,7 +112,10 @@ export function parsePruneArgs(args: readonly string[]): PruneArgs {
       out.dryRun = true
     } else {
       const cd = parseCacheDirFlag(args, i)
-      if (cd === null) return { error: `unknown argument: ${a}${seeHelp('cache')}` }
+      if (cd === null)
+        return {
+          error: `unknown argument: ${a}${flagHint('cache prune', a ?? '')}${seeHelp('cache')}`,
+        }
       if ('error' in cd) return { error: cd.error }
       out.cacheDir = cd.cacheDir
       i = cd.next

package/src/cli/help.ts

@@ -1,3 +1,5 @@
+import { nearest } from '../util/index.js'
+
 export function printHelp(pluginCommands: readonly string[] = [], verb?: string): void {
   process.stdout.write(verb === undefined ? helpText(pluginCommands) : verbHelpText(verb))
 }
@@ -188,6 +190,26 @@ export function seeHelp(verb: string): string {
   return ` (see \`vx ${verb} --help\`)`
 }
 
+/**
+ * `(did you mean --concurrency?)` for a flag within two edits of one `verb`
+ * accepts; empty for anything else (a positional included). A third edit
+ * is allowed only between flags that share their first five characters,
+ * so `--retries` reaches `--retry` while `--zzz` does not reach `--all`.
+ */
+export function flagHint(verb: string, arg: string): string {
+  if (!arg.startsWith('-')) return ''
+  const name = arg.replace(/=.*$/, '')
+  const flags = acceptedFlags(verb)
+  const best =
+    nearest(name, flags) ??
+    nearest(
+      name,
+      flags.filter((f) => f.slice(0, 5) === name.slice(0, 5)),
+      3,
+    )
+  return best === undefined ? '' : ` (did you mean ${best}?)`
+}
+
 /**
  * The documented `--flags` of one verb, read from the help text's
  * sections headed `… (for <verb>):` so there is no second list to drift —

package/src/cli/info.ts

@@ -5,7 +5,7 @@
 // too; this file parses the flags and renders the rows.
 
 import { collectInfo, type FlakyTask, type InfoFacts } from '../orchestrator/index.js'
-import { seeHelp } from './help.js'
+import { flagHint, seeHelp } from './help.js'
 import { namedCacheDir, parseCacheDirFlag, warnToStderr } from './workspace-config.js'
 import { formatBytes } from './format.js'
 import { MIN_BUN } from '../util/index.js'
@@ -36,7 +36,7 @@ export function parseInfoArgs(args: readonly string[]): InfoArgs {
       i = cd.next
       continue
     }
-    return { ...out, error: `unknown argument: ${a}${seeHelp('info')}` }
+    return { ...out, error: `unknown argument: ${a}${flagHint('info', a ?? '')}${seeHelp('info')}` }
   }
   return out
 }

package/src/cli/init.ts

@@ -4,7 +4,8 @@
 // the scripts is the richer source, and `@vzn/vx-migrate` maps it.
 
 import path from 'node:path'
-import { seeHelp } from './help.js'
+import { flagHint, seeHelp } from './help.js'
+import { isUserError, UserError } from '../util/index.js'
 import {
   applyMigration,
   findWorkspaceRoot,
@@ -28,7 +29,8 @@ export function parseInitArgs(args: readonly string[]): InitArgs {
     if (a === '--dry') out.dry = true
     else if (a === '--force') out.force = true
     else if (a === '--mjs') out.mjs = true
-    else if (a.startsWith('-')) return { ...out, error: `unknown flag: ${a}${seeHelp('init')}` }
+    else if (a.startsWith('-'))
+      return { ...out, error: `unknown flag: ${a}${flagHint('init', a)}${seeHelp('init')}` }
     else return { ...out, error: `unexpected argument: ${a}` }
   }
   return out
@@ -41,7 +43,16 @@ export async function initCmd(args: readonly string[]): Promise<number> {
     return 1
   }
   const reads: LoadReads = new Map()
-  const root = await findWorkspaceRoot(process.cwd(), reads)
+  // "a workspace from nowhere" still needs a package.json to start from,
+  // and the lookup's own refusal named no next step.
+  const root = await findWorkspaceRoot(process.cwd(), reads).catch((err: unknown) => {
+    if (isUserError(err) && err.message.startsWith('Could not find a workspace root')) {
+      throw new UserError(
+        'vx init: no package.json here or in any parent directory; create one (`bun init` or `npm init -y`) and run vx init again',
+      )
+    }
+    throw err
+  })
   const metas = await listProjects(await loadWorkspace(root, reads))
   // `init` reads scripts only; a runner's own config beside them is the
   // richer source (dependsOn, inputs, outputs) and was ignored without a

package/src/cli/last.ts

@@ -6,7 +6,7 @@
 
 import { Cache, noteSchemaReset } from '../cache/index.js'
 import { formatBytes } from './format.js'
-import { seeHelp } from './help.js'
+import { flagHint, seeHelp } from './help.js'
 import {
   exitSignal,
   getInvocation,
@@ -62,7 +62,8 @@ export function parseLastArgs(args: readonly string[]): LastArgs {
       i = cd.next
       continue
     }
-    if (a.startsWith('-')) return { ...out, error: `unknown flag: ${a}${seeHelp('last')}` }
+    if (a.startsWith('-'))
+      return { ...out, error: `unknown flag: ${a}${flagHint('last', a)}${seeHelp('last')}` }
     if (out.runId !== undefined) return { ...out, error: `unexpected argument: ${a}` }
     out.runId = a
   }

package/src/cli/lock.ts

@@ -3,7 +3,7 @@
 // current environment. Design: docs/design/config-lock-2026-06.md.
 
 import type { ProjectConfig } from '../config.js'
-import { seeHelp } from './help.js'
+import { flagHint, seeHelp } from './help.js'
 import { relPosix, xxh3hex } from '../util/index.js'
 import {
   findWorkspaceRoot,
@@ -29,7 +29,11 @@ export function parseLockArgs(args: readonly string[]): LockArgs {
   const out: LockArgs = { check: false }
   for (const a of args) {
     if (a === '--check') out.check = true
-    else return { check: false, error: `unknown argument: ${a}${seeHelp('lock')}` }
+    else
+      return {
+        check: false,
+        error: `unknown argument: ${a}${flagHint('lock', a)}${seeHelp('lock')}`,
+      }
   }
   return out
 }

package/src/cli/run.ts

@@ -1,6 +1,6 @@
 import { appendFileSync, mkdirSync } from 'node:fs'
 import path from 'node:path'
-import { documentedFlags, seeHelp } from './help.js'
+import { flagHint, seeHelp } from './help.js'
 import { defaultAffectedBase, findWorkspaceRoot } from '../workspace/index.js'
 import {
   planRun,
@@ -15,13 +15,7 @@ import {
 import type { ContinueMode } from '../graph/index.js'
 import { type CachePolicy, FULL_CACHE_POLICY, parseCachePolicy } from '../cache/index.js'
 import { findCwdProject, pickTask, resolveFilters } from './select.js'
-import {
-  MAX_TIMEOUT_MS,
-  isUserError,
-  parseDecimalInt,
-  nearest,
-  machineParallelism,
-} from '../util/index.js'
+import { MAX_TIMEOUT_MS, isUserError, parseDecimalInt, machineParallelism } from '../util/index.js'
 import { formatGraphDot, formatPlanJson, formatPlanText } from './plan-format.js'
 
 export interface RunArgs {
@@ -343,7 +337,7 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
       }
       out.report = fmt
     } else if (a !== undefined && a.startsWith('-')) {
-      return { ...out, error: `unknown flag: ${a}${didYouMeanFlag(a)}${seeHelp('run')}` }
+      return { ...out, error: `unknown flag: ${a}${flagHint('run', a)}${seeHelp('run')}` }
     } else if (a !== undefined) {
       out.tasks.push(a)
     }
@@ -695,20 +689,3 @@ function printSummary(summary: RunResult): void {
 function formatRow(o: OutcomeView): { task: string; status: string; duration: string } {
   return { task: o.taskId, status: outcomeLabel(o), duration: `${o.durationMs}ms` }
 }
-
-/** `(did you mean --concurrency?)` for a flag within two edits of a documented one. */
-function didYouMeanFlag(flag: string): string {
-  const name = flag.replace(/=.*$/, '')
-  const flags = documentedFlags('run')
-  // The usual two edits; a third only between flags that share their
-  // first five characters, so `--retries` reaches `--retry` (the i/y)
-  // while `--zzz` does not reach `--all` — a plain three-edit budget did.
-  const best =
-    nearest(name, flags) ??
-    nearest(
-      name,
-      flags.filter((f) => f.slice(0, 5) === name.slice(0, 5)),
-      3,
-    )
-  return best === undefined ? '' : ` (did you mean ${best}?)`
-}

package/src/cli/select.ts

@@ -413,9 +413,20 @@ function didYouMeanProject(
   projects: Iterable<{ name: string }>,
 ): string {
   const names = [...projects].map((p) => p.name)
+  // A scoped name typed without its scope (`vx-mcp` for `@vzn/vx-mcp`) is
+  // many edits from the whole name and none from the part after the `/`.
+  const byBare = new Map<string, string[]>()
+  for (const n of names) {
+    const bare = n.slice(n.indexOf('/') + 1)
+    if (bare !== n) byBare.set(bare, [...(byBare.get(bare) ?? []), n])
+  }
   for (const pattern of unmatched) {
-    const best = nearest(pattern.replace(/^!|\.\.\.$|^\.\.\.|\^/g, ''), names)
+    const typed = pattern.replace(/^!|\.\.\.$|^\.\.\.|\^/g, '')
+    const best = nearest(typed, names)
     if (best !== undefined) return `. Did you mean ${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]}?`
   }
   return ''
 }

package/src/cli/show.ts

@@ -8,7 +8,7 @@
 
 import type { ProjectConfig, TaskConfig } from '../config.js'
 import { declaredTask } from '../graph/index.js'
-import { seeHelp } from './help.js'
+import { flagHint, seeHelp } from './help.js'
 import { nearMatches, relPosix, UserError } from '../util/index.js'
 import { loadCliProjects } from './workspace-config.js'
 import {
@@ -33,7 +33,8 @@ export function parseShowArgs(args: readonly string[]): ShowArgs {
     let format: string | undefined
     if (a === '--format') format = args[++i] ?? ''
     else if (a.startsWith('--format=')) format = a.slice('--format='.length)
-    else if (a.startsWith('-')) return { ...out, error: `unknown flag: ${a}${seeHelp('show')}` }
+    else if (a.startsWith('-'))
+      return { ...out, error: `unknown flag: ${a}${flagHint('show', a)}${seeHelp('show')}` }
     else if (out.target !== undefined) return { ...out, error: `unexpected argument: ${a}` }
     else out.target = a
 
@@ -117,22 +118,25 @@ export async function showCmd(args: readonly string[]): Promise<number> {
   const task = declaredTask(config, taskName)
   if (task === undefined) {
     throw new UserError(
-      `unknown task: "${meta.name}#${taskName}"${suggest(taskName, Object.keys(config?.tasks ?? {}))}`,
+      `unknown task: "${meta.name}#${taskName}"${suggest(taskName, Object.keys(config?.tasks ?? {}), `${meta.name}#`)}`,
     )
   }
   process.stdout.write(renderTask(meta.name, dir, taskName, task, parsed.format))
   return 0
 }
 
-/** Near misses by edit distance, plus partial names in either direction. */
-function suggest(query: string, candidates: readonly string[]): string {
+/**
+ * Near misses by edit distance, plus partial names in either direction.
+ * `prefix` makes each a spec the user can paste (`app#build`, not `build`).
+ */
+function suggest(query: string, candidates: readonly string[], prefix = ''): string {
   const q = query.toLowerCase()
   const near = new Set(nearMatches(query, candidates))
   for (const c of candidates) {
     const n = c.toLowerCase()
     if (n.includes(q) || q.includes(n)) near.add(c)
   }
-  return near.size > 0 ? ` — did you mean ${[...near].join(', ')}?` : ''
+  return near.size > 0 ? ` — did you mean ${[...near].map((n) => prefix + n).join(', ')}?` : ''
 }
 
 function projectDir(root: string, meta: ProjectMeta): string {

package/src/cli/watch-fs.ts

@@ -0,0 +1,248 @@
+// `vx watch`'s file-system side: the OS watcher and the proof it delivers,
+// the stat poller that stands in where it cannot, and the clock both are
+// judged against. Nothing here knows about tasks, cycles or the cache.
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+/** Paths whose changes never trigger a re-run. */
+export const IGNORED_SEGMENTS = ['node_modules', '.git', '.vx']
+
+/**
+ * The file `armWatcher` writes under a watched directory to prove the
+ * watcher delivers. Intercepted by name before any other handling, so it
+ * can never trigger a cycle, and removed before "watching" is printed.
+ */
+export const WATCH_PROBE = '.vx-watch-probe'
+
+/** How long a watcher gets to report its own probe before the loop goes on without proof. */
+export const WATCH_PROBE_TIMEOUT_MS = 2_000
+/** The file `fsClockNow` writes and removes, under the cache dir the watchers ignore. */
+const WATCH_CLOCK_STAMP = '.vx-watch-clock'
+
+/** Anything the loop needs to shut down at exit. */
+export interface WatchHandle {
+  close(): void
+}
+
+export interface ArmedWatcher {
+  watcher: fs.FSWatcher
+  /** Resolves `true` once the watcher reported the probe, `false` on timeout. */
+  ready: Promise<boolean>
+}
+
+/** How often the fallback re-walks a watched tree. */
+export const POLL_INTERVAL_MS = 250
+
+/**
+ * Directory names the fallback never descends into WHEN no better filter is
+ * supplied. The justification is that `makeWatchIgnore` already drops their
+ * EVENTS, so the walk buys nothing — a poller pays for it either way, and
+ * `node_modules` is the difference between a cheap fallback and one that
+ * re-stats 40 000 files four times a second.
+ *
+ * That justification is exactly `IGNORED_SEGMENTS`, so this IS that set.
+ * It used to carry a fourth name, `dist`, which the justification does NOT
+ * cover: `dist` is dropped only when a project DECLARES it as an output, and
+ * a project that does not declare it had its `dist/` sources silently
+ * invisible to `vx watch` on every host the poller exists for — a macOS
+ * sandbox, a network mount, a container bind — while the native watcher
+ * delivered them. Two watchers disagreeing about what an edit is (item 482).
+ * The real per-project answer is the caller's `skipDir`, below.
+ */
+const POLL_SKIP = new Set(IGNORED_SEGMENTS)
+
+/**
+ * A watcher built from `stat`, for when the OS one cannot deliver.
+ *
+ * `fs.watch` on macOS is FSEvents, which needs `mach-lookup` on
+ * `com.apple.FSEvents`; inside a sandbox that does not grant it the call
+ * SUCCEEDS and then never fires (measured 2026-09-05: 0 events recursive,
+ * 0 non-recursive, against 3 and 2 for the same writes outside — while
+ * `fs.watchFile` polling delivered in both). A network filesystem or a
+ * container bind mount fails the same way. Polling is slower and coarser,
+ * and it is the difference between `vx watch` working there and silently
+ * doing nothing.
+ */
+export function pollWatcher(
+  dir: string,
+  recursive: boolean,
+  onEvent: (filename: string) => void,
+  intervalMs = POLL_INTERVAL_MS,
+  /**
+   * Directories not worth descending into, by their path relative to `dir`.
+   * The watch loop passes its own event filter, so the poller skips exactly
+   * what the filter would drop anyway — every declared output container, not
+   * a hard-coded name. The default covers the unconditional segments alone.
+   */
+  skipDir: (rel: string) => boolean = (rel) => POLL_SKIP.has(path.basename(rel)),
+): WatchHandle {
+  let previous = new Map<string, number>()
+  let first = true
+  const scan = (): void => {
+    const current = new Map<string, number>()
+    const walk = (abs: string, rel: string): void => {
+      let entries: fs.Dirent[]
+      try {
+        entries = fs.readdirSync(abs, { withFileTypes: true })
+      } catch {
+        return // vanished or unreadable: its files simply stop appearing
+      }
+      for (const e of entries) {
+        if (e.name === WATCH_PROBE) continue
+        const childRel = rel === '' ? e.name : `${rel}/${e.name}`
+        if (e.isDirectory()) {
+          if (recursive && !skipDir(childRel)) walk(path.join(abs, e.name), childRel)
+          continue
+        }
+        if (!e.isFile()) continue
+        try {
+          // The later of the two clocks, as `modifiedBefore` reads them: a
+          // replacement that carries the old file's mtime (`cp -p`, `rsync
+          // -a`, `mv` of a file stamped the same) moved nothing under mtime
+          // alone, and the poller never ran it where the native watcher did.
+          // A rename or a write moves ctime, and no process can set it.
+          const st = fs.statSync(path.join(abs, e.name))
+          current.set(childRel, Math.max(st.mtimeMs, st.ctimeMs))
+        } catch {
+          // raced with a delete; the next scan settles it
+        }
+      }
+    }
+    walk(dir, '')
+    if (!first) {
+      for (const [rel, mtime] of current) {
+        if (previous.get(rel) !== mtime) onEvent(rel)
+      }
+      for (const rel of previous.keys()) {
+        if (!current.has(rel)) onEvent(rel)
+      }
+    }
+    previous = current
+    first = false
+  }
+  scan()
+  // Deliberately NOT unref'd: once the native watcher is closed this timer
+  // is the only thing keeping `vx watch` alive.
+  const timer = setInterval(scan, intervalMs)
+  return {
+    close(): void {
+      clearInterval(timer)
+    },
+  }
+}
+
+/**
+ * `fs.watch` plus proof of delivery. On macOS a recursive watcher is an
+ * FSEvents stream that another thread schedules AFTER the call returns, and
+ * a change landing in that gap is never delivered — MEASURED 2026-09-03: a
+ * write made immediately after `fs.watch` was lost 5 times in 30 under CPU
+ * load (0 in 30 idle, 0 in 30 after a 50 ms pause). The gap has no fixed
+ * width, so no pause is the answer and no timeout on the waiting side ever
+ * was (the e2e flake this closes had one of 45 s). A probe file written
+ * under the watcher and waited for is: once ITS event arrives, the stream
+ * is live for everything after it.
+ *
+ * `onEvent` never sees the probe (create or unlink), and the probe is
+ * removed before `ready` resolves.
+ */
+export function armWatcher(
+  dir: string,
+  recursive: boolean,
+  onEvent: (filename: string) => void,
+  timeoutMs = WATCH_PROBE_TIMEOUT_MS,
+): ArmedWatcher {
+  let markReady: (ok: boolean) => void = () => {}
+  const seen = new Promise<boolean>((resolve) => {
+    markReady = resolve
+  })
+  const watcher = fs.watch(dir, { recursive, persistent: true }, (_event, filename) => {
+    if (filename == null || typeof filename !== 'string') return
+    // An event naming the watched directory itself (macOS reports the
+    // directory a write landed in as its own item) carries nothing a key
+    // can see; the write's own event names the file.
+    if (filename === '' || filename === '.') return
+    if (filename === WATCH_PROBE) {
+      markReady(true)
+      return
+    }
+    // Another arm's probe, seen by this recursive watcher under a nested
+    // directory (a nested project's, a member base inside a project): no
+    // key sees it, and passing it on ran a cycle, and restarted a dev
+    // server, with no edit made (item 1016). Only the watcher's own probe
+    // proves this stream live.
+    if (path.basename(filename) === WATCH_PROBE) return
+    onEvent(filename)
+  })
+  const probe = path.join(dir, WATCH_PROBE)
+  const ready = (async (): Promise<boolean> => {
+    // The probe is subject to the very race it detects: a write that lands
+    // in the gap is lost like any other (1 in 20 under a full gate's load,
+    // measured 2026-09-03, with every delivered event under 60 ms). So it is
+    // re-written on a short backoff until its event arrives — the first write
+    // after the stream goes live is the one that proves it.
+    const deadline = Date.now() + timeoutMs
+    let ok = false
+    let step = 50
+    while (!ok) {
+      try {
+        fs.writeFileSync(probe, String(Date.now()))
+      } catch {
+        break // an unwritable dir gets no proof; the watcher is kept
+      }
+      const remaining = deadline - Date.now()
+      if (remaining <= 0) break
+      const pause = new Promise<boolean>((resolve) => {
+        setTimeout(() => resolve(false), Math.min(step, remaining)).unref()
+      })
+      ok = await Promise.race([seen, pause])
+      step = Math.min(step * 2, 400)
+    }
+    try {
+      fs.unlinkSync(probe)
+    } catch {
+      // already gone
+    }
+    return ok
+  })()
+  return { watcher, ready }
+}
+
+/** True when `abs` was last modified before `t` (epoch ms); false when it cannot be read. */
+export function modifiedBefore(abs: string, t: number): boolean {
+  try {
+    // The later of the two clocks: `mv`, `cp -p`, `rsync -a` and `tar x`
+    // carry a file's OLD mtime onto the new one, and judged by mtime alone
+    // such an edit was "before the arm" and never ran (item 945). No
+    // process can set a ctime, and a rename or a write moves it.
+    const st = fs.statSync(abs)
+    return Math.max(st.mtimeMs, st.ctimeMs) < t
+  } catch {
+    return false
+  }
+}
+
+/**
+ * "Now" as the filesystem will stamp the next write, not as `Date.now()`
+ * reads it. A file's mtime comes from the kernel's coarse clock, which
+ * runs up to a tick behind the fine clock `Date.now()` reads — measured
+ * on the Linux bench box 2026-09-11: 2 of 3,000 tight writes carried an
+ * mtime 5.8 ms EARLIER than a `Date.now()` taken before the write, and
+ * more under CPU load, where the tick is skipped. An `armedAt` from the
+ * fine clock then judged an edit made right after the ready line as
+ * "modified before the arm" and dropped it (the watch e2e flake, three
+ * shard runs that day; traced: raw event, trigger, `same=true`). A stamp
+ * read off a file written here is on the mtime clock itself, and every
+ * later write's mtime is at or after it.
+ */
+export function fsClockNow(dir: string): number {
+  const stamp = path.join(dir, WATCH_CLOCK_STAMP)
+  try {
+    fs.writeFileSync(stamp, '')
+    const at = fs.statSync(stamp).mtimeMs
+    fs.unlinkSync(stamp)
+    return at
+  } catch {
+    return Date.now()
+  }
+}

package/src/cli/watch.ts

@@ -50,12 +50,20 @@ import {
 import type { ProjectConfig } from '../config.js'
 import { type CliLoadOptions, loadCliProjects, loadCliWorkspace } from './workspace-config.js'
 import { taskEdges, taskEdgesFrom } from './select.js'
+import {
+  armWatcher,
+  fsClockNow,
+  IGNORED_SEGMENTS,
+  modifiedBefore,
+  pollWatcher,
+  POLL_INTERVAL_MS,
+  WATCH_PROBE_TIMEOUT_MS,
+  type WatchHandle,
+} from './watch-fs.js'
 
 /** Wait this long after the last filesystem event before re-running. */
 const DEBOUNCE_MS = 150
 
-/** Paths whose changes never trigger a re-run. */
-const IGNORED_SEGMENTS = ['node_modules', '.git', '.vx']
 const IGNORED_SUFFIXES = ['.tsbuildinfo', '~']
 
 /**
@@ -167,13 +175,6 @@ function outputContainer(raw: string): string {
   return prefix === '.' || prefix === '/' ? '' : prefix
 }
 
-/**
- * The file `armWatcher` writes under a watched directory to prove the
- * watcher delivers. Intercepted by name before any other handling, so it
- * can never trigger a cycle, and removed before "watching" is printed.
- */
-export const WATCH_PROBE = '.vx-watch-probe'
-
 /**
  * The subset of `paths` git ignores, asked once per judgement (one
  * `git check-ignore` per debounce window that has candidates, never per
@@ -210,199 +211,6 @@ export function gitIgnored(workspaceRoot: string, paths: readonly string[]): Set
   return ignored
 }
 
-/** How long a watcher gets to report its own probe before the loop goes on without proof. */
-const WATCH_PROBE_TIMEOUT_MS = 2_000
-/** The file `fsClockNow` writes and removes, under the cache dir the watchers ignore. */
-const WATCH_CLOCK_STAMP = '.vx-watch-clock'
-
-/** Anything the loop needs to shut down at exit. */
-export interface WatchHandle {
-  close(): void
-}
-
-export interface ArmedWatcher {
-  watcher: fs.FSWatcher
-  /** Resolves `true` once the watcher reported the probe, `false` on timeout. */
-  ready: Promise<boolean>
-}
-
-/** How often the fallback re-walks a watched tree. */
-const POLL_INTERVAL_MS = 250
-
-/**
- * Directory names the fallback never descends into WHEN no better filter is
- * supplied. The justification is that `makeWatchIgnore` already drops their
- * EVENTS, so the walk buys nothing — a poller pays for it either way, and
- * `node_modules` is the difference between a cheap fallback and one that
- * re-stats 40 000 files four times a second.
- *
- * That justification is exactly `IGNORED_SEGMENTS`, so this IS that set.
- * It used to carry a fourth name, `dist`, which the justification does NOT
- * cover: `dist` is dropped only when a project DECLARES it as an output, and
- * a project that does not declare it had its `dist/` sources silently
- * invisible to `vx watch` on every host the poller exists for — a macOS
- * sandbox, a network mount, a container bind — while the native watcher
- * delivered them. Two watchers disagreeing about what an edit is (item 482).
- * The real per-project answer is the caller's `skipDir`, below.
- */
-const POLL_SKIP = new Set(IGNORED_SEGMENTS)
-
-/**
- * A watcher built from `stat`, for when the OS one cannot deliver.
- *
- * `fs.watch` on macOS is FSEvents, which needs `mach-lookup` on
- * `com.apple.FSEvents`; inside a sandbox that does not grant it the call
- * SUCCEEDS and then never fires (measured 2026-09-05: 0 events recursive,
- * 0 non-recursive, against 3 and 2 for the same writes outside — while
- * `fs.watchFile` polling delivered in both). A network filesystem or a
- * container bind mount fails the same way. Polling is slower and coarser,
- * and it is the difference between `vx watch` working there and silently
- * doing nothing.
- */
-export function pollWatcher(
-  dir: string,
-  recursive: boolean,
-  onEvent: (filename: string) => void,
-  intervalMs = POLL_INTERVAL_MS,
-  /**
-   * Directories not worth descending into, by their path relative to `dir`.
-   * The watch loop passes its own event filter, so the poller skips exactly
-   * what the filter would drop anyway — every declared output container, not
-   * a hard-coded name. The default covers the unconditional segments alone.
-   */
-  skipDir: (rel: string) => boolean = (rel) => POLL_SKIP.has(path.basename(rel)),
-): WatchHandle {
-  let previous = new Map<string, number>()
-  let first = true
-  const scan = (): void => {
-    const current = new Map<string, number>()
-    const walk = (abs: string, rel: string): void => {
-      let entries: fs.Dirent[]
-      try {
-        entries = fs.readdirSync(abs, { withFileTypes: true })
-      } catch {
-        return // vanished or unreadable: its files simply stop appearing
-      }
-      for (const e of entries) {
-        if (e.name === WATCH_PROBE) continue
-        const childRel = rel === '' ? e.name : `${rel}/${e.name}`
-        if (e.isDirectory()) {
-          if (recursive && !skipDir(childRel)) walk(path.join(abs, e.name), childRel)
-          continue
-        }
-        if (!e.isFile()) continue
-        try {
-          // The later of the two clocks, as `modifiedBefore` reads them: a
-          // replacement that carries the old file's mtime (`cp -p`, `rsync
-          // -a`, `mv` of a file stamped the same) moved nothing under mtime
-          // alone, and the poller never ran it where the native watcher did.
-          // A rename or a write moves ctime, and no process can set it.
-          const st = fs.statSync(path.join(abs, e.name))
-          current.set(childRel, Math.max(st.mtimeMs, st.ctimeMs))
-        } catch {
-          // raced with a delete; the next scan settles it
-        }
-      }
-    }
-    walk(dir, '')
-    if (!first) {
-      for (const [rel, mtime] of current) {
-        if (previous.get(rel) !== mtime) onEvent(rel)
-      }
-      for (const rel of previous.keys()) {
-        if (!current.has(rel)) onEvent(rel)
-      }
-    }
-    previous = current
-    first = false
-  }
-  scan()
-  // Deliberately NOT unref'd: once the native watcher is closed this timer
-  // is the only thing keeping `vx watch` alive.
-  const timer = setInterval(scan, intervalMs)
-  return {
-    close(): void {
-      clearInterval(timer)
-    },
-  }
-}
-
-/**
- * `fs.watch` plus proof of delivery. On macOS a recursive watcher is an
- * FSEvents stream that another thread schedules AFTER the call returns, and
- * a change landing in that gap is never delivered — MEASURED 2026-09-03: a
- * write made immediately after `fs.watch` was lost 5 times in 30 under CPU
- * load (0 in 30 idle, 0 in 30 after a 50 ms pause). The gap has no fixed
- * width, so no pause is the answer and no timeout on the waiting side ever
- * was (the e2e flake this closes had one of 45 s). A probe file written
- * under the watcher and waited for is: once ITS event arrives, the stream
- * is live for everything after it.
- *
- * `onEvent` never sees the probe (create or unlink), and the probe is
- * removed before `ready` resolves.
- */
-export function armWatcher(
-  dir: string,
-  recursive: boolean,
-  onEvent: (filename: string) => void,
-  timeoutMs = WATCH_PROBE_TIMEOUT_MS,
-): ArmedWatcher {
-  let markReady: (ok: boolean) => void = () => {}
-  const seen = new Promise<boolean>((resolve) => {
-    markReady = resolve
-  })
-  const watcher = fs.watch(dir, { recursive, persistent: true }, (_event, filename) => {
-    if (filename == null || typeof filename !== 'string') return
-    // An event naming the watched directory itself (macOS reports the
-    // directory a write landed in as its own item) carries nothing a key
-    // can see; the write's own event names the file.
-    if (filename === '' || filename === '.') return
-    if (filename === WATCH_PROBE) {
-      markReady(true)
-      return
-    }
-    // Another arm's probe, seen by this recursive watcher under a nested
-    // directory (a nested project's, a member base inside a project): no
-    // key sees it, and passing it on ran a cycle, and restarted a dev
-    // server, with no edit made (item 1016). Only the watcher's own probe
-    // proves this stream live.
-    if (path.basename(filename) === WATCH_PROBE) return
-    onEvent(filename)
-  })
-  const probe = path.join(dir, WATCH_PROBE)
-  const ready = (async (): Promise<boolean> => {
-    // The probe is subject to the very race it detects: a write that lands
-    // in the gap is lost like any other (1 in 20 under a full gate's load,
-    // measured 2026-09-03, with every delivered event under 60 ms). So it is
-    // re-written on a short backoff until its event arrives — the first write
-    // after the stream goes live is the one that proves it.
-    const deadline = Date.now() + timeoutMs
-    let ok = false
-    let step = 50
-    while (!ok) {
-      try {
-        fs.writeFileSync(probe, String(Date.now()))
-      } catch {
-        break // an unwritable dir gets no proof; the watcher is kept
-      }
-      const remaining = deadline - Date.now()
-      if (remaining <= 0) break
-      const pause = new Promise<boolean>((resolve) => {
-        setTimeout(() => resolve(false), Math.min(step, remaining)).unref()
-      })
-      ok = await Promise.race([seen, pause])
-      step = Math.min(step * 2, 400)
-    }
-    try {
-      fs.unlinkSync(probe)
-    } catch {
-      // already gone
-    }
-    return ok
-  })()
-  return { watcher, ready }
-}
-
 /**
  * The run flags a watch loop cannot honour, as the refusal line it prints; null
  * when there is none. `WATCH_REFUSED_FLAGS` (help.ts) is the same list for
@@ -1516,45 +1324,6 @@ export function pendingAfterCycle(
   return [abs, label]
 }
 
-/** True when `abs` was last modified before `t` (epoch ms); false when it cannot be read. */
-export function modifiedBefore(abs: string, t: number): boolean {
-  try {
-    // The later of the two clocks: `mv`, `cp -p`, `rsync -a` and `tar x`
-    // carry a file's OLD mtime onto the new one, and judged by mtime alone
-    // such an edit was "before the arm" and never ran (item 945). No
-    // process can set a ctime, and a rename or a write moves it.
-    const st = fs.statSync(abs)
-    return Math.max(st.mtimeMs, st.ctimeMs) < t
-  } catch {
-    return false
-  }
-}
-
-/**
- * "Now" as the filesystem will stamp the next write, not as `Date.now()`
- * reads it. A file's mtime comes from the kernel's coarse clock, which
- * runs up to a tick behind the fine clock `Date.now()` reads — measured
- * on the Linux bench box 2026-09-11: 2 of 3,000 tight writes carried an
- * mtime 5.8 ms EARLIER than a `Date.now()` taken before the write, and
- * more under CPU load, where the tick is skipped. An `armedAt` from the
- * fine clock then judged an edit made right after the ready line as
- * "modified before the arm" and dropped it (the watch e2e flake, three
- * shard runs that day; traced: raw event, trigger, `same=true`). A stamp
- * read off a file written here is on the mtime clock itself, and every
- * later write's mtime is at or after it.
- */
-export function fsClockNow(dir: string): number {
-  const stamp = path.join(dir, WATCH_CLOCK_STAMP)
-  try {
-    fs.writeFileSync(stamp, '')
-    const at = fs.statSync(stamp).mtimeMs
-    fs.unlinkSync(stamp)
-    return at
-  } catch {
-    return Date.now()
-  }
-}
-
 /**
  * The directory entries under a package glob's directory that can be
  * members: directories (or links) whose name is not dotted and not

package/src/cli/why.ts

@@ -6,7 +6,7 @@
 // no config evaluation, no re-hash.
 
 import { Cache, noteSchemaReset } from '../cache/index.js'
-import { seeHelp } from './help.js'
+import { flagHint, seeHelp } from './help.js'
 import { splitTaskId } from '../graph/index.js'
 import {
   cacheKeyDiff,
@@ -83,7 +83,8 @@ export function parseWhyArgs(args: readonly string[]): WhyArgs {
       i = cd.next
       continue
     }
-    if (a.startsWith('-')) return { ...out, error: `unknown flag: ${a}${seeHelp('why')}` }
+    if (a.startsWith('-'))
+      return { ...out, error: `unknown flag: ${a}${flagHint('why', a)}${seeHelp('why')}` }
     if (out.target !== undefined) return { ...out, error: `unexpected argument: ${a}` }
     out.target = a
   }

package/src/orchestrator/plugin-host.ts

@@ -323,7 +323,15 @@ export function buildAdmission(
     for (const plugin of answering) {
       if (broken.has(plugin)) continue
       try {
-        if (plugin.admit!(task, ctx) !== false) continue
+        const verdict: unknown = plugin.admit!(task, ctx)
+        // An `async admit` answers a Promise: truthy, so it admitted every
+        // task and its policy never ran, and its rejection was unhandled and
+        // ended the run with a stack (H-16). Named once, admitting after.
+        if (verdict instanceof Promise) {
+          verdict.catch(() => {})
+          throw new Error('returned a Promise; admit is synchronous')
+        }
+        if (verdict !== false) continue
         if (running.size > 0) return false
         if (!overridden.has(plugin)) {
           overridden.add(plugin)

package/src/orchestrator/plugin.ts

@@ -130,8 +130,9 @@ export interface VxPlugin {
    * Admission over the worker count: asked for every task about to start
    * on this machine, with the tasks running here right now. Return `false`
    * to hold it until something finishes (it is asked again then). Asked
-   * many times per run, so it must be cheap and synchronous; a throw is
-   * reported once and the plugin admits from then on — a policy never
+   * many times per run, so it must be cheap and synchronous; a throw, or
+   * an answer that is a Promise, is reported once and the plugin admits
+   * from then on — a policy never
    * breaks a run. Restore-tier hits and tasks on an executor pool hold no
    * local resources and are never asked. When several plugins answer, all
    * must admit. Core keeps no notion of what a task needs: a plugin that
@@ -144,7 +145,8 @@ export interface VxPlugin {
 
   /**
    * Verbs this plugin adds to the `vx` CLI, keyed by name. Consulted only
-   * for a verb core does not know — core's own verbs always win — and only
+   * for a verb core does not know — a verb named like a core verb is
+   * refused at load — and only
    * when the cwd is inside a workspace that declares the plugin. `vx help`
    * lists them under "Plugin commands". A verb's exit code is the process
    * exit code; a thrown `UserError` prints cleanly, like core's own.
@@ -348,6 +350,18 @@ export type PluginHookName =
   | 'onRunStatus'
   | 'onRunEnd'
 
+// A Record so the compiler holds it to `PluginHookName` both ways: a name
+// missing here, or one the type lacks, does not compile.
+const HOOK_NAMES: Record<PluginHookName, true> = {
+  onRunStart: true,
+  onTaskStart: true,
+  onTaskStdout: true,
+  onTaskStderr: true,
+  onTaskComplete: true,
+  onRunStatus: true,
+  onRunEnd: true,
+}
+
 export interface PluginHookHandlers {
   onRunStart: (info: RunStartInfo) => void | Promise<void>
   onTaskStart: (node: TaskNode) => void | Promise<void>
@@ -508,6 +522,13 @@ export async function installPlugins(args: InstallPluginsArgs): Promise<() => vo
         },
       },
       on(hook, handler) {
+        // A misspelt name ('taskComplete') subscribed a handler that never
+        // ran, and no word of it; a config file has no type-checker (H-16).
+        if (!Object.hasOwn(HOOK_NAMES, hook)) {
+          throw new Error(
+            `ctx.on: unknown hook '${String(hook)}' (one of ${Object.keys(HOOK_NAMES).join(', ')})`,
+          )
+        }
         const fail = (err: unknown): void => {
           if (disabled.has(plugin.name)) return
           disabled.add(plugin.name)

package/src/orchestrator/stable-keys.ts

@@ -340,6 +340,19 @@ export function dependsOnSiblingOutputs(
     const outputs = sameProject.outputsOf.get(node.projectName) ?? []
     if (inputs === undefined || outputs.length === 0) return true
     if (workspaceInputsReach(inputs, outputs.map(literalPrefix))) return true
+    // Nor where it WRITES inside another task's tree: restored ahead of
+    // that producer, its restore raced the producer's clean and extract
+    // (M-5; invariant 2 of docs/design/overlapping-outputs-2026-09.md).
+    // `outputsOf` holds this task's own globs too; set them aside once.
+    const own = cache.outputs.files
+    if (own.length > 0) {
+      const others = [...outputs]
+      for (const g of own) {
+        const i = others.indexOf(g)
+        if (i !== -1) others.splice(i, 1)
+      }
+      if (others.length > 0 && workspaceInputsReach(own, others.map(literalPrefix))) return true
+    }
   }
   // A root-anchored output is boundary-IGNORING by design, so it can land
   // inside THIS task's own project dir — where an ordinary project-relative

package/src/workspace/migrate-scripts.ts

@@ -116,6 +116,15 @@ function upstreamBuildOnWorker(tasks: GeneratedTask[]): void {
     at = Array.isArray(deps) ? byName.get(String(deps[0])) : undefined
   }
   if (at === undefined || at.name === 'build' || at.task === null || at.task === undefined) return
+  // The worker IS `build`'s work, and so is every group on the way to it:
+  // a `typecheck` behind `build: npm run typecheck` waited for `build`,
+  // and the run refused the cycle (D-16).
+  for (const name of [...seen, at.name]) {
+    const t = byName.get(name)!.task!
+    if (name !== 'build' && Array.isArray(t['dependsOn'])) {
+      t['dependsOn'] = (t['dependsOn'] as string[]).filter((d) => d !== 'build')
+    }
+  }
   const deps = Array.isArray(at.task['dependsOn']) ? (at.task['dependsOn'] as string[]) : []
   if (!deps.includes('^build')) at.task['dependsOn'] = ['^build', ...deps]
   if (!at.todos.includes(CACHE_TODO)) at.todos.push(CACHE_TODO)