@vzn/vx 0.0.18 → 0.0.22

package/src/util/errors.ts

@@ -3,6 +3,9 @@
 //
 // `bin.ts` and the scheduler consult `isUserError` to decide what to print.
 
+import { realpathSync } from 'node:fs'
+import os from 'node:os'
+
 export class UserError extends Error {
   constructor(message: string) {
     super(message)
@@ -23,3 +26,86 @@ export class UserError extends Error {
 export function isUserError(err: unknown): err is UserError {
   return err instanceof UserError || (err instanceof Error && err.name === 'UserError')
 }
+
+/**
+ * An `EACCES`, `EPERM` or `EROFS` from the file system: a path vx must
+ * write is not this user's to write (a root-owned `.vx`, a read-only
+ * checkout). The environment's failure, reported like a UserError — one
+ * line naming the path — never as an internal error with a stack.
+ */
+export function isPermissionError(err: unknown): err is NodeJS.ErrnoException {
+  if (!(err instanceof Error)) return false
+  const code = (err as NodeJS.ErrnoException).code
+  return code === 'EACCES' || code === 'EPERM' || code === 'EROFS'
+}
+
+/** What follows the path in a permission error's one line. */
+export const PERMISSION_HINT = 'a path vx must write is not writable by this user'
+
+/** `ENOSPC` or `EDQUOT`: the disk a path is on is full. */
+export function isDiskFull(err: unknown): err is NodeJS.ErrnoException {
+  if (!(err instanceof Error)) return false
+  const code = (err as NodeJS.ErrnoException).code
+  return code === 'ENOSPC' || code === 'EDQUOT'
+}
+
+/** A file system refusing a write for a reason no code path caused: permission or space. */
+export function isFsRefusal(err: unknown): err is NodeJS.ErrnoException {
+  return isPermissionError(err) || isDiskFull(err)
+}
+
+export const DISK_FULL_HINT = 'the disk that path is on is full'
+
+/** The one-line hint after a refusal's path. */
+export function fsRefusalHint(err: NodeJS.ErrnoException): string {
+  return isDiskFull(err) ? DISK_FULL_HINT : PERMISSION_HINT
+}
+
+/**
+ * A spawn that could not run at all — Bun throws `ENOENT` ("Executable not
+ * found in $PATH") synchronously from `Bun.spawn` and `Bun.spawnSync` alike.
+ * Every git call site tells it from a git that ran and failed, because the
+ * remedy differs: install git, not "git init".
+ */
+export function isExecutableMissing(err: unknown): boolean {
+  return (err as NodeJS.ErrnoException)?.code === 'ENOENT'
+}
+
+/**
+ * The one refusal for a git that is not on PATH, wherever vx needed it — a
+ * `--affected` base, the input enumeration, a watch judgement. A minimal
+ * image without git met a stack from `defaultAffectedBase` before
+ * (2026-09-16); the enumeration had this line and the others did not.
+ */
+export function gitSpawnRefusal(cwd: string): UserError {
+  return new UserError(
+    `vx requires git: failed to spawn 'git' (working dir: ${cwd}). Install git and re-run.`,
+  )
+}
+
+export const TMPDIR_HINT = 'point TMPDIR at a writable directory'
+
+/**
+ * A temp-directory refusal: the path is under `os.tmpdir()` and the error
+ * says it is missing, a file, or not writable. The knob is TMPDIR, and a
+ * line that names the path should name the knob — a minimal image's
+ * sandboxed task said "EACCES … mkdtemp '/tmp/…/srt-obs-…'" and nothing
+ * else (2026-09-16). Only for a site whose path IS the temp directory by
+ * construction: a workspace under /tmp would pass the path test too.
+ */
+export function isTmpdirRefusal(err: unknown): err is NodeJS.ErrnoException {
+  if (!(err instanceof Error)) return false
+  const code = (err as NodeJS.ErrnoException).code
+  if (code !== 'ENOENT' && code !== 'ENOTDIR' && !isPermissionError(err)) return false
+  const p = (err as NodeJS.ErrnoException).path
+  const named = typeof p === 'string' ? p : err.message
+  const tmp = os.tmpdir()
+  // The error may name the resolved directory (macOS: /tmp is /private/tmp);
+  // a temp directory that does not exist has no real path, so the name as
+  // given is the only one it can carry.
+  let real = tmp
+  try {
+    real = realpathSync(tmp)
+  } catch {}
+  return named.includes(tmp) || named.includes(real)
+}

package/src/util/hash.ts

@@ -13,10 +13,19 @@
 // folds `part` into the running digest. Equivalent to the old
 // `CryptoHasher.update(...).update(...).digest()` pattern, without
 // allocating an intermediate buffer.
+//
+// Bun reads only the LOW 32 bits of that seed (measured, item 682), so a
+// bare `xxHash3(part, prev)` carries 32 bits of state from step to step:
+// two input sets whose running digests share their low halves merge at
+// the next step, and a birthday search found such a pair in 0.08 s — a
+// stale hit at ~2^-32 per step, not 2^-64. The seed is XORed back in
+// (feed-forward): states that share their low half keep their exact
+// high-half difference through every later step, so they never merge,
+// and a seed of 0 changes nothing, so single-shot digests are unchanged.
 
 /** xxHash3 bigint output. Use as the seed for the next chain step. */
 export function xxh3(input: string | Uint8Array, seed: bigint = 0n): bigint {
-  return Bun.hash.xxHash3(input, seed)
+  return Bun.hash.xxHash3(input, seed) ^ seed
 }
 
 /** xxHash3 hex-encoded, fixed 16 chars (zero-padded). */

package/src/util/index.ts

@@ -1,13 +1,50 @@
 // Module contract. Cross-module imports must come through here; see
 // docs/design/module-isolation-2026-06.md and tests/module-boundaries.test.ts.
 
-export { isUserError, UserError } from './errors.js'
+export {
+  DISK_FULL_HINT,
+  fsRefusalHint,
+  isDiskFull,
+  isFsRefusal,
+  isTmpdirRefusal,
+  TMPDIR_HINT,
+  isPermissionError,
+  isUserError,
+  PERMISSION_HINT,
+  UserError,
+  gitSpawnRefusal,
+  isExecutableMissing,
+} from './errors.js'
 export { xxh3, xxh3hex } from './hash.js'
 export { mark, printTimings, span } from './timing.js'
 export { clampInt, MAX_TIMEOUT_MS, parseDecimalInt } from './num.js'
-export { relPosix, staticPrefix, wholeSubtreePrefixes } from './paths.js'
-export { settleWithin, teardownTimeoutMs } from './settle.js'
-export { parseSize } from './size.js'
+export {
+  asTrees,
+  BUN_GLOB_WILDCARDS,
+  grantPrefix,
+  isLiteralPattern,
+  GLOB_WILDCARDS,
+  normalizeBunGlob,
+  normalizeGlob,
+  relPosix,
+  staticPrefix,
+  taskGlob,
+  wholeSubtreePrefixes,
+} from './paths.js'
+export { killGraceMs, settleWithin, teardownTimeoutMs } from './settle.js'
+export { formatBytes, parseDuration, parseSize } from './size.js'
+export {
+  cgroupCpuQuota,
+  cgroupMemoryLimitBytes,
+  machineMemoryBytes,
+  machineParallelism,
+  type CgroupProbe,
+} from './cgroup.js'
 export { appendTail, createTail, resetTail, tailText, type Tail } from './tail.js'
 export { ulid } from './ulid.js'
-export { editDistance } from './edit-distance.js'
+export { splitTaskId } from './task-id.js'
+export { editDistance, nearMatches, nearest } from './edit-distance.js'
+export { CORE_VERBS, DISPATCHED_VERBS, MOVED_VERBS } from './verbs.js'
+export { isUnsupportedBun, MIN_BUN, unsupportedBunMessage } from './bun-version.js'
+export { executablePath } from './which.js'
+export { procfsIsOwn } from './procfs.js'

package/src/util/paths.ts

@@ -24,10 +24,43 @@ export function relPosix(from: string, to: string): string {
  * baseline joins it onto a dir to get a write prefix, and the deferral
  * eligibility gate compares two of them for overlap. A second copy is
  * how the two would disagree about what a prefix is.
+ *
+ * The spelling is normalized FIRST, here rather than at each call site,
+ * because sharing the function was not enough to make the two callers
+ * agree: the sandbox joins the prefix onto a directory and `path.join`
+ * folds `./`, `//` and `/./` on the way, while the deferral gate compares
+ * the raw strings and does not. So `./out/**` and `out/**` named the same
+ * tree to the resolver, the sandbox and the watcher, and two DIFFERENT
+ * prefixes to the gate — which then deferred a producer a same-project
+ * reader's key could see, moving that key with a transfer flag (item 441,
+ * measured through a real run: `./out/**` keyed the consumer two ways).
+ * Every glob reaching here is user-written, so every one takes the rule.
+ */
+export function staticPrefix(rawGlob: string): string {
+  return prefixOf(normalizeGlob(rawGlob), GLOB_WILDCARDS)
+}
+
+/**
+ * {@link staticPrefix} under `Bun.Glob`'s own alphabet, for a sandbox GRANT:
+ * the grant is expanded by a `Bun.Glob` scan that reads `[ab]` as a class, so
+ * its prefix must stop there too, or `write: ['g/[ab].txt']` would create a
+ * DIRECTORY named `g/[ab].txt`.
  */
-export function staticPrefix(glob: string): string {
-  const wildcardIdx = glob.search(/[*?[\]]/)
-  if (wildcardIdx === -1) return glob
+export function grantPrefix(rawGlob: string): string {
+  return prefixOf(normalizeBunGlob(rawGlob), BUN_GLOB_WILDCARDS)
+}
+
+function prefixOf(glob: string, wildcards: RegExp): string {
+  // A brace set is a wildcard too: `{dist,build}/**` reaches either dir,
+  // and reading it as the literal directory `{dist,build}` gave the
+  // sandbox baseline a prefix that exists nowhere (2026-09-10).
+  const wildcardIdx = glob.search(wildcards)
+  // A LITERAL keeps its trailing slash through `normalizeGlob` on purpose
+  // (`asTrees` is what turns `out/` into the tree `out` + `out/**`), but a
+  // prefix with a slash on the end compares as a different string: `out/`
+  // against `out/sub` found no overlap where `out` does. The prefix is a
+  // directory either way. `/` is the root, not a trailing slash.
+  if (wildcardIdx === -1) return glob === '/' ? '/' : glob.replace(/\/+$/, '')
   const head = glob.slice(0, wildcardIdx)
   const lastSep = head.lastIndexOf('/')
   if (lastSep === -1) return '.'
@@ -47,8 +80,8 @@ export function staticPrefix(glob: string): string {
 export function wholeSubtreePrefixes(globs: readonly string[]): string[] | null {
   if (globs.length === 0) return null
   const out: string[] = []
-  for (const g of globs) {
-    const m = /^([^*?[\]{}!]+?)\/\*\*$/.exec(g)
+  for (const g of globs.map(normalizeGlob)) {
+    const m = /^([^*?{}!]+?)\/\*\*$/.exec(g)
     if (m === null) return null
     const dir = m[1]!.replace(/\/+$/, '')
     if (dir === '' || dir === '.' || dir.startsWith('/') || dir.split('/').includes('..'))
@@ -57,3 +90,133 @@ export function wholeSubtreePrefixes(globs: readonly string[]): string[] | null
   }
   return [...new Set(out)]
 }
+
+/**
+ * The spellings a reader, Turbo and `.gitignore` all accept but a matcher
+ * fed the raw string turns into NOTHING — and a task keyed on nothing
+ * replays old outputs as a green hit (2026-09-10, probed one by one):
+ * a leading `./`, an inner `/./` segment, a doubled `//`, and a trailing
+ * `/` on a pattern (`src/*\/` means the trees under `src`, so it becomes
+ * `src/*\/**`; a trailing slash on a LITERAL is `asTrees`' job). Applied
+ * after an optional `!`; a bare `.` is the empty entry the schema refuses.
+ */
+export function normalizeGlob(glob: string): string {
+  return normalizeWith(glob, GLOB_WILDCARDS)
+}
+
+/**
+ * {@link normalizeGlob} for a glob in `Bun.Glob`'s own alphabet (a workspace
+ * member glob, a sandbox grant): the same spellings, but `\[` stays escaped,
+ * since there it is what keeps a bracket from opening a class.
+ */
+export function normalizeBunGlob(glob: string): string {
+  return normalizeWith(glob, BUN_GLOB_WILDCARDS)
+}
+
+function normalizeWith(glob: string, wildcards: RegExp): string {
+  const neg = glob.startsWith('!')
+  let g = neg ? glob.slice(1) : glob
+  g = g.replace(/\/{2,}/g, '/').replace(/(^|\/)(\.\/)+/g, '$1')
+  if (g === '.') g = ''
+  // Where a bracket is literal, Turbo's escaped spelling `\[id\]` names the
+  // same path as `[id]`; one spelling is what lets every literal fast path
+  // (string compare, `settleLiterals`, `asTrees`) see it as a literal.
+  if (wildcards === GLOB_WILDCARDS && g.includes('\\')) g = g.replace(/\\([[\]])/g, '$1')
+  if (wildcards.test(g) && g.endsWith('/')) g = `${g.replace(/\/+$/, '')}/**`
+  return neg ? `!${g}` : g
+}
+
+/**
+ * True when a pattern carries no wildcard — it names exactly one path.
+ *
+ * The character SET is the whole content: in a task glob `*`, `?` and a
+ * brace alternation are wildcards, so a pattern holding any of them must
+ * be MATCHED, never compared as a string. It lives here, exported, because
+ * four places asked the same question and one of them asked it with a
+ * smaller set: `graph/task-graph.ts` omitted `{}`, so `dist/{a,b}.txt`
+ * counted as a literal and the overlapping-output refusal compared it to
+ * `dist/a.txt` as two unequal strings — the two tasks were accepted and
+ * then deleted each other's outputs, green, every run (item 495). That is
+ * the same divergence `asTrees` was moved here to end in item 442, and the
+ * same one that removed `@vzn/vx-migrate`'s copy of `outputsOverlap` in
+ * item 445.
+ */
+export function isLiteralPattern(glob: string): boolean {
+  return !GLOB_WILDCARDS.test(glob)
+}
+
+/**
+ * The alphabet of a TASK glob (`cache.inputs.files`, `cache.outputs.files`,
+ * `workspaceFiles`), behind {@link isLiteralPattern}, for the callers that
+ * need the POSITION of the first wildcard rather than a verdict. Every site
+ * that asks "must this declaration be matched?" reads this one regex: item
+ * 495 found the fourth copy with a smaller set, and item 577 found the
+ * class written out nine times — a spelling that drifts is how two guards
+ * come to answer differently for one pattern.
+ *
+ * `[` and `]` are NOT in it: a bracket is a literal character in a task
+ * glob, and there are no character classes (item 667). Route directories
+ * are named `[id]` across Next.js, SvelteKit and Astro, and read as a class
+ * `app/[id]/**` matched `app/i/…` and `app/d/…` and never the route: the
+ * file never entered the key (a stale hit) and the output clean deleted an
+ * unrelated `app/i/page.js`. {@link taskGlob} is how such a glob reaches
+ * `Bun.Glob`, whose own alphabet still reads the class.
+ */
+export const GLOB_WILDCARDS = /[*?{}]/
+
+/**
+ * `Bun.Glob`'s own alphabet, the class included, for the globs vx does not
+ * own: package-manager workspace members and `--filter` path globs follow
+ * npm/pnpm semantics, and a sandbox grant's prefix must stop where the scan
+ * that expands the grant (`Bun.Glob`, `MOUNT_WILDCARDS`) sees a wildcard.
+ */
+export const BUN_GLOB_WILDCARDS = /[*?[\]{}]/
+
+/**
+ * Compile a task glob for `Bun.Glob`, with every bare bracket escaped so it
+ * matches itself (item 667). Every task glob is compiled here and nowhere
+ * else: one site that forgot is a route directory that keys nothing.
+ */
+export function taskGlob(pattern: string): Bun.Glob {
+  // A `]` with no `[` before it is already literal to `Bun.Glob`.
+  if (!pattern.includes('[')) return new Bun.Glob(pattern)
+  return new Bun.Glob(pattern.replace(/(?<!\\)[[\]]/g, '\\$&'))
+}
+
+function stripTrailingSlash(p: string): string {
+  return p.replace(/\/+$/, '')
+}
+
+/**
+ * A literal entry names a file OR a directory tree: `src/` and `src` both
+ * mean everything under `src`, as they do in Turbo and every `.gitignore`.
+ * A glob matcher sees only the literal path, so `['src/']` folded ZERO
+ * files — a key that never moves with its source, and the most common
+ * turbo.json shape (`"outputs": ["dist"]`) captured nothing. Every
+ * literal therefore compiles to itself plus its subtree; a literal that
+ * names a file still matches exactly that file, since `x/**` matches
+ * nothing under a file.
+ *
+ * It lives in `util` rather than beside the resolver because it is not
+ * only the resolver's rule. It decides what a clean DELETES, so the
+ * graph's overlapping-output refusal has to read the same one: while it
+ * did not, `dist` and `dist/app.js` compared as two unequal literals and
+ * the run that wiped `dist/app.js` reported success (item 442). `graph`
+ * may not import `cache`, and a second copy is how the two would
+ * disagree — which is exactly what item 441 measured about
+ * `staticPrefix`.
+ */
+export function asTrees(patterns: readonly string[]): string[] {
+  const out: string[] = []
+  for (const raw of patterns) {
+    const p = normalizeGlob(raw)
+    if (!isLiteralPattern(p)) {
+      out.push(p)
+      continue
+    }
+    const lit = stripTrailingSlash(p)
+    if (lit.length === 0) continue
+    out.push(lit, `${lit}/**`)
+  }
+  return out
+}

package/src/util/procfs.ts

@@ -0,0 +1,20 @@
+// Is `/proc` this process's view of the pid namespace? A procfs mounted
+// for another namespace is a table of strangers: under the sandbox's
+// nested pid namespace vx is pid 2 while `/proc/self` names 7, and
+// `/proc/<our child's pid>` is some other process or none (2026-09-24).
+// Asked once per process: the mount does not change under a run.
+
+import { readlinkSync } from 'node:fs'
+
+let own: boolean | undefined
+
+export function procfsIsOwn(): boolean {
+  if (own === undefined) {
+    try {
+      own = process.platform === 'linux' && readlinkSync('/proc/self') === String(process.pid)
+    } catch {
+      own = false
+    }
+  }
+  return own
+}

package/src/util/settle.ts

@@ -28,9 +28,30 @@ export function teardownTimeoutMs(): number {
 }
 
 /**
- * Await `p`, giving up after `ms`. Returns true when `p` settled first,
+ * The SIGTERM→SIGKILL grace a run grants a child that ignores SIGTERM: the
+ * one-shot timeout escalation (`exec/runner.ts`) and the end-of-run
+ * persistent shutdown (`orchestrator/persistent.ts`) share it. Two seconds
+ * is generous for a real server's cleanup and is what every run waits when
+ * a child wedges. `VX_KILL_GRACE_MS` overrides it, read per call and bounded
+ * like the teardown deadline (out of range falls back to the default): the
+ * tests that prove the escalation used to wait the full two seconds each,
+ * a third of the suite's wall time for a claim a 200 ms grace proves too.
+ */
+export function killGraceMs(defaultMs: number): number {
+  const raw = process.env['VX_KILL_GRACE_MS']
+  if (raw !== undefined && /^[0-9]+$/.test(raw)) {
+    const n = Number(raw)
+    if (n > 0 && n <= MAX_TIMEOUT_MS) return n
+  }
+  return defaultMs
+}
+
+/**
+ * Await `p`, giving up after `ms`. Returns true when `p` fulfilled first,
  * false when the deadline won — the caller decides whether a lost result
- * is worth reporting.
+ * is worth reporting. A rejection before the deadline is not a timeout: it
+ * propagates, so the caller reports the failure rather than a hang
+ * (`tests/util-settle.test.ts`).
  */
 export async function settleWithin(p: Promise<unknown>, ms: number): Promise<boolean> {
   let timer: ReturnType<typeof setTimeout> | undefined

package/src/util/size.ts

@@ -18,3 +18,36 @@ export function parseSize(input: string): number | null {
     u === '' ? 1 : u === 'K' ? 1024 : u === 'M' ? 1024 * 1024 : u === 'G' ? 1024 ** 3 : 1024 ** 4
   return n * mult
 }
+
+/**
+ * Parse `<n><unit>` where unit is s/m/h/d, case-insensitively (`parseSize`
+ * has always been case-insensitive; this matched only lowercase, so `30D`
+ * was rejected while `1GB` and `1gb` both worked).
+ */
+export function parseDuration(input: string): number | null {
+  const m = input.match(/^(\d+)([smhd])$/i)
+  if (!m) return null
+  const n = parseDecimalInt(m[1]!)
+  if (n === null) return null
+  // Lowercase before the switch: with the /i flag an uppercase `M` would
+  // otherwise fall through to the days branch.
+  const unit = m[2]!.toLowerCase()
+  const mult = unit === 's' ? 1000 : unit === 'm' ? 60_000 : unit === 'h' ? 3_600_000 : 86_400_000
+  return n * mult
+}
+
+/**
+ * Human-readable byte size with KB/MB/GB/TB/PB suffixes and one
+ * decimal of precision below 10 of any unit. Used by `vx info`, `vx cache prune` and the
+ * run's `cacheRetention` line.
+ */
+export function formatBytes(n: number): string {
+  if (n < 1024) return `${n} B`
+  const units = ['KB', 'MB', 'GB', 'TB']
+  let v = n / 1024
+  for (const u of units) {
+    if (v < 1024) return `${v.toFixed(v < 10 ? 1 : 0)} ${u}`
+    v /= 1024
+  }
+  return `${v.toFixed(0)} PB`
+}

package/src/util/task-id.ts

@@ -0,0 +1,20 @@
+/**
+ * The inverse of `taskId` (`graph/task-graph.ts`). Splits on the FIRST
+ * `#`, so a task name that itself contains one round-trips: `taskId('a', 'b#c')` → `'a#b#c'` → `['a', 'b#c']`.
+ *
+ * This exists because it kept being written by hand as `id.split('#', 2)`,
+ * which is NOT the inverse — it discards everything after the second segment,
+ * so `'a#b#c'` reads back as task `'b'`. Six call sites had that form while
+ * `parseDependencySpec` (the surface that decides what actually runs) has
+ * always split on the first `#`, so the query layer and the graph disagreed
+ * about the identity of the same task: a lookup either found nothing or, worse,
+ * answered with a different task's history.
+ *
+ * A `#`-containing task name is legal and pinned elsewhere in the suite, so
+ * this is reachable rather than theoretical. The cache's run history read
+ * the same rule from a private copy until item 646; one rule, one place.
+ */
+export function splitTaskId(id: string): [project: string, task: string] {
+  const i = id.indexOf('#')
+  return i < 0 ? [id, ''] : [id.slice(0, i), id.slice(i + 1)]
+}

package/src/util/timing.ts

@@ -3,7 +3,8 @@
 // The CPU profiler attributes a tight loop's cost unreliably and hides
 // where an `await` waited; a stage table answers "where did the warm run
 // go?" directly, and costs one boolean check per mark when off. Marks are
-// cumulative from process start; the table shows each stage's own share.
+// cumulative from this module's load — process start and the imports ahead
+// of it sit outside the table; the table shows each stage's own share.
 
 const enabled = process.env.VX_TIMING !== undefined && process.env.VX_TIMING !== ''
 const t0 = Bun.nanoseconds()
@@ -58,6 +59,15 @@ export function printTimings(): void {
         `             ${label.padEnd(24)}  ${(ns / 1e6).toFixed(1).padStart(8)}ms  ${String(count).padStart(6)}`,
       )
     }
+    // The trap this table sets, said where it is sprung: a span's total is
+    // WALL summed per call, and the run's spans are taken under the
+    // scheduler's concurrency, so a span that overlaps other work reads
+    // far larger than the work it names. `output dirs` at 124 µs a task is
+    // a handful of `lstat`s (items 254 and 407). Compare spans to each
+    // other, and measure a suspect one in isolation before chasing it.
+    lines.push(
+      '             (wall per call, summed; concurrent calls overlap — compare spans, not totals)',
+    )
   }
   process.stderr.write(lines.join('\n') + '\n')
 }

package/src/util/verbs.ts

@@ -0,0 +1,39 @@
+/**
+ * The verbs the CLI dispatcher (`cli/index.ts`) owns; `stats` is a
+ * deprecated alias of `info` and stays out of hints but is still matched
+ * first. Lives in util rather than cli because the workspace VALIDATOR
+ * refuses a plugin verb that names one of these — a verb core matches
+ * first could never run — and the workspace module cannot import cli.
+ */
+export const CORE_VERBS = [
+  'run',
+  'watch',
+  'cache',
+  'lock',
+  'init',
+  'upgrade',
+  'show',
+  'info',
+  'why',
+  'last',
+  'completions',
+  'help',
+  'version',
+] as const
+
+/** Every word the dispatcher matches before consulting plugins. */
+export const DISPATCHED_VERBS: readonly string[] = [...CORE_VERBS, 'stats']
+
+/**
+ * Verbs core owned once and a package owns now. Not core verbs: a plugin
+ * may declare them, and the dispatcher prints the
+ * pointer only when no declared plugin claimed the name.
+ */
+export const MOVED_VERBS: Readonly<Record<string, string>> = {
+  migrate:
+    'vx migrate moved to @vzn/vx-migrate: run `bunx @vzn/vx-migrate` (turbo.json or an Nx ' +
+    'project graph → vx.config.ts); `vx init` reads package.json scripts',
+  prune:
+    'vx prune was removed (2026-09-11): the Docker-subset verb is not shipped; copy the ' +
+    'workspace and `--filter` the build instead',
+}

package/src/util/which.ts

@@ -0,0 +1,48 @@
+// A spawn of a bare name walks PATH with a stat per entry — `sh` for every
+// task, `git` for every git call: 200 tasks paid ~2,000 stats on a 100-package
+// workspace for the same answer each time. The walk is done here once and
+// the spawn is handed the absolute path.
+//
+// The PATH walked is vx's OWN, never a task's. A task's PATH starts with its
+// project's and the workspace's `node_modules/.bin`, and `exec.env.define`
+// may set it outright; the shell that parses the command and the git that
+// enumerates the inputs are the machine's tools, not the task's, so a
+// dependency that ships a `sh` bin must not become the interpreter of every
+// command in its project. The task's PATH still decides what the COMMAND
+// resolves, inside that shell.
+//
+// Memoized per PATH value rather than for the process's life: nothing in vx
+// changes PATH mid-run, so a run pays one walk, and a process whose PATH does
+// change (an embedder, a test) is answered for the PATH it has. A miss is
+// not remembered: it ends the spawn that asked, and a long-lived process
+// (`vx watch`) finds the tool once the user installs it.
+
+let memoPath: string | undefined
+const found = new Map<string, string>()
+
+/**
+ * `name`'s absolute path on vx's own PATH. Throws Bun's own shape for a
+ * spawn that could not run (`code: 'ENOENT'`) when it is not there, so a
+ * call inside a spawn site's `try` reaches the same `isExecutableMissing`
+ * refusal the spawn's throw did.
+ */
+export function executablePath(name: string): string {
+  const PATH = process.env['PATH'] ?? ''
+  if (PATH !== memoPath) {
+    found.clear()
+    memoPath = PATH
+  }
+  const hit = found.get(name)
+  if (hit !== undefined) return hit
+  const at = Bun.which(name, { PATH })
+  if (at === null) {
+    throw Object.assign(new Error(`Executable not found in $PATH: "${name}"`), {
+      code: 'ENOENT',
+      path: name,
+    })
+  }
+  // Absolute even for a relative PATH entry (Bun.which resolves it against
+  // this process's cwd), so it holds in whatever cwd the spawn is given.
+  found.set(name, at)
+  return at
+}