@vzn/vx 0.0.631 → 0.0.633

package/src/cache/chained-cache.ts

@@ -12,6 +12,7 @@
 // (item 1020). A save that fails in EVERY layer still throws, so the
 // caller's own "cache save failed" line stays the one word on it.
 
+import { statSync } from 'node:fs'
 import type {
   Cache,
   CacheEntry,
@@ -248,6 +249,14 @@ export class ChainedCache implements CacheLayer {
     return this.owner(hash).outputsPath(hash)
   }
 
+  /** A layer that cannot say keeps a file at `outputsPath`, or nothing. */
+  artifactSize(hash: string): number | undefined {
+    const owner = this.owner(hash)
+    return owner.artifactSize !== undefined
+      ? owner.artifactSize(hash)
+      : statSync(owner.outputsPath(hash), { throwIfNoEntry: false })?.size
+  }
+
   prune(options: PruneOptions): Promise<PruneResult> {
     return this.layers[0]!.prune(options)
   }

package/src/cache/inputs.ts

@@ -92,6 +92,11 @@ const ALWAYS_IGNORE = [
   // extracts the downloaded runtime into, `<cwd>/.<16 hex>-<8 hex>.tmp/`,
   // 60 MB mid-write under the same race (2026-09-29).
   '**/.????????????????-????????.tmp/**',
+  // vx's own restore temp (archive.ts), live only while an artifact lands
+  // beside its target. A key taken meanwhile listed it, the rename removed
+  // it, and every task reading that directory was withheld its save
+  // (withastro/astro: 25 of 33 builds re-ran on a restore, X-209).
+  '**/.vx-tmp-*',
 ]
 
 const DEFAULT_FILE_GLOBS: readonly string[] = ['**/*']

package/src/cache/layer.ts

@@ -215,7 +215,8 @@ export interface RunRecord {
   /**
    * Why the task failed or was skipped, as the run's own footer said it
    * (v27 columns; NULL on older rows and where the reason does not apply):
-   * a skip's root blocker, vx's own timeout, the sandbox's violation count,
+   * a skip's root blocker (or the one a task that ran behind a failure ran
+   * behind), vx's own timeout, the sandbox's violation count,
    * and why a persistent task never became ready.
    */
   blockedBy?: string
@@ -266,7 +267,7 @@ export interface InvocationRecord {
 }
 
 /**
- * One cache-key component row for the `entry_inputs` table — keyed by
+ * One cache-key component of an `entry_inputs` row (v34: one row per entry) — keyed by
  * the cache-entry HASH it belongs to, not a run. Written inside the
  * entry-save transaction (`writeArtifactAndIndex`) on a miss/save; a
  * cache HIT does not save, so it persists nothing (warm runs are free).
@@ -729,12 +730,16 @@ export interface CacheLayer {
    */
   hashFile(filePath: string): Promise<string>
   /**
-   * Absolute path to the on-disk outputs artifact for a hash —
+   * Absolute path a file-backed artifact for a hash has —
    * `<cacheDir>/<hash>.tar.zst`. Returns the path whether or
-   * not the artifact exists. Exposed for telemetry / dashboards;
-   * `restoreOutputs` is the canonical way to materialize the bytes.
+   * not the artifact exists: a small artifact lives in the index, not
+   * in a file (`artifactSize` is its size). Exposed for telemetry /
+   * dashboards; `restoreOutputs` is the canonical way to materialize
+   * the bytes.
    */
   outputsPath(hash: string): string
+  /** The stored artifact's compressed size, wherever it lives; undefined when none is stored. */
+  artifactSize?(hash: string): number | undefined
   prune(options: PruneOptions): Promise<PruneResult>
   close(): void
 }

package/src/cache/layered-cache.ts

@@ -529,6 +529,10 @@ export class LayeredCache implements CacheLayer {
     return this.local.outputsPath(hash)
   }
 
+  artifactSize(hash: string): number | undefined {
+    return this.local.artifactSize(hash)
+  }
+
   hashFile(filePath: string): Promise<string> {
     return this.local.hashFile(filePath)
   }

package/src/cache/schema.ts

@@ -1,7 +1,8 @@
 // The index's tables, one concern: what a cache.db holds. `Cache` opens the
 // file, checks `SCHEMA_VERSION` and creates these; every statement against
 // them lives in the store that owns the table (file-hashes, config-evals,
-// output-index, history) or in cache.ts for `entries` and `entry_inputs`.
+// output-index, history) or in cache.ts for `entries`, `entry_inputs` and
+// `artifacts`.
 
 import type { Database, SQLQueryBindings } from 'bun:sqlite'
 
@@ -95,7 +96,8 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
       -- time by design; NULL on rows older than the column.
       cached              INTEGER,
       -- v27: why a task failed or was skipped, as the run's own footer
-      -- said it (items 267–270): a skip's root blocker (a task id), vx's
+      -- said it (items 267–270): a skip's root blocker (a task id), or
+      -- the one a task that ran behind a failure ran behind (X-183), vx's
       -- own timeout (1), the sandbox's violation count, and why a
       -- persistent task never became ready ('timeout' | 'exited' |
       -- 'spawn'). NULL where the reason does not apply.
@@ -254,22 +256,18 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
     CREATE INDEX IF NOT EXISTS main.invocations_started ON invocations(started_at);
     CREATE INDEX IF NOT EXISTS main.invocations_branch  ON invocations(branch);
     CREATE INDEX IF NOT EXISTS main.invocations_ci      ON invocations(ci);
-    -- v22 (Tier 3): the input-fingerprint moat. One row per cache-key
-    -- component, keyed by the cache-ENTRY hash it belongs to (NOT a
-    -- run id). Written inside the entry-save transaction — only on a
-    -- miss/save, never on a hit — so a warm all-cache-hit run writes
-    -- nothing here (the warm path does zero extra work). The
-    -- why-did-this-re-run diff reads two entry hashes (this run's
-    -- runs.hash and the previous run's) and anti-joins their rows in
-    -- SQL over (kind,name,hash); a JSON blob would force an app-side
-    -- parse + compare on every probe. ON DELETE CASCADE keeps these
-    -- rows in sync with entries (a prune sweeps them automatically).
+    -- v22 (Tier 3): the input-fingerprint moat: each cache ENTRY's key
+    -- components (NOT a run's). Written inside the entry-save transaction,
+    -- only on a miss/save, so a warm all-cache-hit run writes nothing
+    -- here. v34: one row per entry, the components a JSON array of
+    -- [kind, name, hash] in (kind, name) code-unit order. A row per
+    -- component cost a b-tree insert each, and a task with 50 input
+    -- files spent ~0.5 ms a save on them; every reader loads the whole
+    -- set by entry hash and diffs it app-side anyway. ON DELETE CASCADE
+    -- keeps it in sync with entries (a prune sweeps it automatically).
     CREATE TABLE IF NOT EXISTS ${store}.entry_inputs (
-      entry_hash TEXT NOT NULL,
-      kind       TEXT NOT NULL,
-      name       TEXT NOT NULL,
-      hash       TEXT NOT NULL,
-      PRIMARY KEY (entry_hash, kind, name),
+      entry_hash TEXT PRIMARY KEY,
+      components TEXT NOT NULL,
       FOREIGN KEY (entry_hash) REFERENCES entries(hash) ON DELETE CASCADE
     );
     -- v32: what belongs to the entries rather than to one workspace: the
@@ -279,9 +277,38 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
       key   TEXT PRIMARY KEY,
       value TEXT NOT NULL
     );
+    ${artifactTables(store)}
   `)
 }
 
+/**
+ * v33: an artifact of at most `INLINE_MAX` compressed bytes lives here, its
+ * exact `<hash>.tar.zst` bytes, written in the transaction that writes its
+ * rows. No foreign key and outside every drop a `SCHEMA_VERSION` reset makes:
+ * the artifact is the record and the entries only its inventory, so a reset
+ * drops the rows and keeps these, as it keeps the files. `artifacts_meta`
+ * holds the table's own layout version (`'layout'`), the one thing that may
+ * drop it. `at` is the last use a row-less sweep judges, as a file's mtime;
+ * it sits before `bytes` so reading it never walks a blob's overflow pages.
+ */
+export function createArtifactTables(db: Database, store: 'main' | 'store'): void {
+  db.exec(artifactTables(store))
+}
+
+// In the entry tables' exec, so an open runs no statement more for them.
+function artifactTables(store: 'main' | 'store'): string {
+  return `
+    CREATE TABLE IF NOT EXISTS ${store}.artifacts (
+      hash  TEXT PRIMARY KEY,
+      at    INTEGER NOT NULL,
+      bytes BLOB NOT NULL
+    ) WITHOUT ROWID;
+    CREATE TABLE IF NOT EXISTS ${store}.artifacts_meta (
+      key   TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );`
+}
+
 /**
  * A `WHERE <column> …` test against many hashes, as one statement whatever
  * their number. A list of `?` is a new statement per length, compiled each

package/src/cache/tar-stream.ts

@@ -187,30 +187,45 @@ class Source {
   }
 }
 
+/** What one header block means, decided by `TarDecoder.header`. */
+type HeaderStep =
+  /** A zero block: the first half of the end marker. */
+  | { kind: 'zero' }
+  /** The second zero block in a row: the archive is over. */
+  | { kind: 'end' }
+  /** An extended header (`x`, `L`) or a global one (`g`); its padded body follows. */
+  | { kind: 'extended'; type: 'x' | 'L' | 'g'; size: number; padded: number }
+  /** An entry; its padded body follows. */
+  | { kind: 'entry'; name: string; size: number; type: string; mtimeMs: number; padded: number }
+
+const ZERO: HeaderStep = { kind: 'zero' }
+const END: HeaderStep = { kind: 'end' }
+
 /**
- * Iterate a tar stream entry by entry. Each entry's `body` MUST be fully
- * consumed (or the iterator drains it) before the next entry is read.
+ * The dialect, decoded off whole blocks with no I/O: the one copy of the
+ * header rules both readers run — `tarEntries` over a stream (restore,
+ * ingest) and `tarEntriesSync` over a tar in memory (a save's own) — so
+ * a name a save indexes is the name a restore reads.
  */
-export async function* tarEntries(stream: ReadableStream<Uint8Array>): AsyncGenerator<TarEntry> {
-  const src = new Source(stream[Symbol.asyncIterator]())
-  let pendingPath: string | undefined
-  let pendingSize: number | undefined
-  let zeroBlocks = 0
-  for (;;) {
-    const h = await src.exact(BLOCK, 'a header')
-    if (h === null) {
-      if (zeroBlocks === 0) throw new TarFormatError('archive has no end-of-archive marker')
-      return
-    }
+class TarDecoder {
+  private pendingPath: string | undefined
+  private pendingSize: number | undefined
+  private zeroBlocks = 0
+
+  /** The bytes ended at a header boundary: clean only after a zero block. */
+  eof(): void {
+    if (this.zeroBlocks === 0) throw new TarFormatError('archive has no end-of-archive marker')
+  }
+
+  header(h: Uint8Array): HeaderStep {
     if (isZeroBlock(h)) {
-      zeroBlocks++
-      if (zeroBlocks >= 2) return
-      continue
+      this.zeroBlocks++
+      return this.zeroBlocks >= 2 ? END : ZERO
     }
-    zeroBlocks = 0
+    this.zeroBlocks = 0
     if (!checksumOk(h)) throw new TarFormatError('header checksum mismatch')
     const type = h[156] === 0 ? '0' : String.fromCharCode(h[156]!)
-    const size = pendingSize ?? octal(h, 124, 12)
+    const size = this.pendingSize ?? octal(h, 124, 12)
     const mtimeMs = octal(h, 136, 12) * 1000
     const padded = Math.ceil(size / BLOCK) * BLOCK
     // POSIX `ustar\0` only: old GNU's `ustar  ` keeps atime and ctime at
@@ -218,44 +233,67 @@ export async function* tarEntries(stream: ReadableStream<Uint8Array>): AsyncGene
     // `<atime>…/<name>`.
     const prefix = field(h, 257, 6) === 'ustar' ? field(h, 345, 155) : ''
     const rawName = field(h, 0, 100)
-    let name = pendingPath ?? (prefix ? `${prefix}/${rawName}` : rawName)
-    pendingPath = undefined
-    pendingSize = undefined
-
-    if ((type === 'x' || type === 'L' || type === 'g') && size > MAX_EXTENDED_HEADER) {
-      throw new TarFormatError(
-        `extended header of ${size} bytes, past ${MAX_EXTENDED_HEADER} (a hostile archive?)`,
-      )
+    const name = this.pendingPath ?? (prefix ? `${prefix}/${rawName}` : rawName)
+    this.pendingPath = undefined
+    this.pendingSize = undefined
+    if (type === 'x' || type === 'L' || type === 'g') {
+      if (size > MAX_EXTENDED_HEADER) {
+        throw new TarFormatError(
+          `extended header of ${size} bytes, past ${MAX_EXTENDED_HEADER} (a hostile archive?)`,
+        )
+      }
+      return { kind: 'extended', type, size, padded }
     }
-    if (type === 'x' || type === 'L') {
-      // Extended header: applies to the NEXT entry only.
-      const body = await src.exact(padded, 'an extended header')
-      if (body === null) throw new TarFormatError('archive ends inside an extended header')
-      if (type === 'x') {
-        const pax = parsePax(body.subarray(0, size))
-        const p = pax.get('path')
-        if (p !== undefined) pendingPath = p
-        const s = pax.get('size')
-        if (s !== undefined) {
-          // Digits only: `Number` reads `0.5` and `-1`, and a fractional
-          // size moved the reader to a fractional offset.
-          if (!/^[0-9]+$/.test(s) || !Number.isSafeInteger(Number(s))) {
-            throw new TarFormatError(`bad pax size: ${JSON.stringify(s)}`)
-          }
-          pendingSize = Number(s)
-        }
-      } else {
-        pendingPath = field(body, 0, size)
+    const trimmed = name.replace(/\/+$/, type === '5' ? '/' : '')
+    return { kind: 'entry', name: trimmed, size, type, mtimeMs, padded }
+  }
+
+  /** An `x` or `L` header's padded body: it applies to the NEXT entry only. */
+  extended(type: 'x' | 'L', body: Uint8Array, size: number): void {
+    if (type === 'L') {
+      this.pendingPath = field(body, 0, size)
+      return
+    }
+    const pax = parsePax(body.subarray(0, size))
+    const p = pax.get('path')
+    if (p !== undefined) this.pendingPath = p
+    const s = pax.get('size')
+    if (s !== undefined) {
+      // Digits only: `Number` reads `0.5` and `-1`, and a fractional
+      // size moved the reader to a fractional offset.
+      if (!/^[0-9]+$/.test(s) || !Number.isSafeInteger(Number(s))) {
+        throw new TarFormatError(`bad pax size: ${JSON.stringify(s)}`)
       }
-      continue
+      this.pendingSize = Number(s)
     }
-    if (type === 'g') {
-      // pax global header: not used by Bun.Archive; skip its body.
-      await src.exact(padded, 'a global header')
+  }
+}
+
+const extendedWhat = (type: 'x' | 'L' | 'g'): string =>
+  type === 'g' ? 'a global header' : 'an extended header'
+
+/**
+ * Iterate a tar stream entry by entry. Each entry's `body` MUST be fully
+ * consumed (or the iterator drains it) before the next entry is read.
+ */
+export async function* tarEntries(stream: ReadableStream<Uint8Array>): AsyncGenerator<TarEntry> {
+  const src = new Source(stream[Symbol.asyncIterator]())
+  const tar = new TarDecoder()
+  for (;;) {
+    const h = await src.exact(BLOCK, 'a header')
+    if (h === null) return tar.eof()
+    const step = tar.header(h)
+    if (step.kind === 'end') return
+    if (step.kind === 'zero') continue
+    if (step.kind === 'extended') {
+      const body = await src.exact(step.padded, extendedWhat(step.type))
+      // pax global header: not used by Bun.Archive; its body is skipped.
+      if (step.type === 'g') continue
+      if (body === null) throw new TarFormatError('archive ends inside an extended header')
+      tar.extended(step.type, body, step.size)
       continue
     }
-    name = name.replace(/\/+$/, type === '5' ? '/' : '')
-
+    const { name, size, padded } = step
     let drained = false
     const body = (async function* (): AsyncIterable<Uint8Array> {
       if (size > 0) for await (const c of src.take(size, `entry ${name}`)) yield c
@@ -265,7 +303,7 @@ export async function* tarEntries(stream: ReadableStream<Uint8Array>): AsyncGene
       }
       drained = true
     })()
-    yield { name, size, type, mtimeMs, body }
+    yield { name, size, type: step.type, mtimeMs: step.mtimeMs, body }
     if (!drained) {
       // The caller skipped this body: drain it so the next header lines up.
       for await (const _ of body) {
@@ -275,6 +313,77 @@ export async function* tarEntries(stream: ReadableStream<Uint8Array>): AsyncGene
   }
 }
 
+/** One entry of a tar in memory. `body()` is a view, checked against the tar's end when asked for. */
+interface TarBytesEntry {
+  name: string
+  size: number
+  type: string
+  mtimeMs: number
+  body(): Uint8Array
+}
+
+/**
+ * `tarEntries` over a tar already in memory, synchronously, through the
+ * same decoder. A body is checked against the tar's end when it is read,
+ * as the stream reader checks it when it is drained, so the two refuse
+ * a damaged archive with the same class at the same point.
+ */
+export function* tarEntriesSync(tar: Uint8Array): Generator<TarBytesEntry> {
+  const dec = new TarDecoder()
+  const len = tar.byteLength
+  let off = 0
+  for (;;) {
+    if (off === len) return dec.eof()
+    if (len - off < BLOCK) {
+      throw new TarFormatError(`archive ends inside a header (${len - off} of ${BLOCK} bytes)`)
+    }
+    const step = dec.header(tar.subarray(off, off + BLOCK))
+    off += BLOCK
+    if (step.kind === 'end') return
+    if (step.kind === 'zero') continue
+    if (step.kind === 'extended') {
+      const left = len - off
+      if (left < step.padded) {
+        if (left > 0) {
+          throw new TarFormatError(
+            `archive ends inside ${extendedWhat(step.type)} (${left} of ${step.padded} bytes)`,
+          )
+        }
+        // At the very end a global header's body is skipped as absent, and
+        // the end marker it lacks is what refuses the archive.
+        if (step.type === 'g') continue
+        throw new TarFormatError('archive ends inside an extended header')
+      }
+      if (step.type !== 'g')
+        dec.extended(step.type, tar.subarray(off, off + step.padded), step.size)
+      off += step.padded
+      continue
+    }
+    const { name, size, padded } = step
+    const at = off
+    // The stream reader's messages, word for word: the parity rows compare them.
+    const body = (): Uint8Array => {
+      const left = len - at
+      if (left < size) {
+        throw new TarFormatError(`archive ends inside entry ${name} (${left} of ${size} bytes)`)
+      }
+      if (left < padded) {
+        const pad = left - size
+        throw new TarFormatError(
+          pad === 0
+            ? `archive ends inside padding after ${name}`
+            : `archive ends inside padding after ${name} (${pad} of ${padded - size} bytes)`,
+        )
+      }
+      return tar.subarray(at, at + size)
+    }
+    yield { name, size, type: step.type, mtimeMs: step.mtimeMs, body }
+    // A body the caller skipped is still checked, as the stream drains it.
+    body()
+    off += padded
+  }
+}
+
 // ─── Writer ───────────────────────────────────────────────────────────
 
 /** One regular file to pack. `body` is read as it is written. */
@@ -379,6 +488,48 @@ export function tarSize(inputs: readonly TarInput[]): number {
   return size
 }
 
+/** An entry's blocks before its body: a pax `path` record when needed, then the ustar header. */
+function entryHead(input: TarInput): Uint8Array[] {
+  const mode = input.mode ?? 0o644
+  const mtime = input.mtime ?? 0
+  if (!needsPax(input.name)) return [header(input.name, input.size, '0', mode, mtime)]
+  // Under a pax record the ustar name is a courtesy for readers that
+  // ignore pax: its first 100 BYTES, never characters — a multibyte
+  // name sliced by characters can be over 100 bytes again.
+  const pax = paxRecord('path', input.name)
+  return [
+    header('PaxHeaders/entry', pax.byteLength, 'x', 0o644, mtime),
+    pax,
+    padding(pax.byteLength),
+    header(encoder.encode(input.name).subarray(0, 100), input.size, '0', mode, mtime),
+  ]
+}
+
+/**
+ * `tarPack` of in-memory bodies, written into one buffer on this thread:
+ * the same bytes, without a generator hop per block (the small-artifact
+ * save, `packArtifactBytes`). Returns the bytes written.
+ */
+export function tarPackInto(
+  inputs: readonly (TarInput & { body: Uint8Array | string })[],
+  out: Uint8Array,
+): number {
+  let off = 0
+  for (const input of inputs) {
+    for (const block of entryHead(input)) {
+      out.set(block, off)
+      off += block.byteLength
+    }
+    const bytes = typeof input.body === 'string' ? encoder.encode(input.body) : input.body
+    if (bytes.byteLength !== input.size)
+      throw new TarFormatError(`${input.name}: ${bytes.byteLength} bytes, ${input.size} declared`)
+    out.set(bytes, off)
+    // `out` is zeroed: padding and the end marker are a skip.
+    off += padded(input.size)
+  }
+  return off + BLOCK * 2
+}
+
 /**
  * Pack regular files as a tar stream: ustar with the name/prefix split,
  * a pax `path` record when a name fits neither field — exactly the
@@ -389,20 +540,7 @@ export async function* tarPack(
   inputs: AsyncIterable<TarInput> | Iterable<TarInput>,
 ): AsyncGenerator<Uint8Array> {
   for await (const input of inputs) {
-    const mode = input.mode ?? 0o644
-    const mtime = input.mtime ?? 0
-    // Under a pax record the ustar name is a courtesy for readers that
-    // ignore pax: its first 100 BYTES, never characters — a multibyte
-    // name sliced by characters can be over 100 bytes again.
-    let headerName: string | Uint8Array = input.name
-    if (needsPax(input.name)) {
-      const pax = paxRecord('path', input.name)
-      yield header('PaxHeaders/entry', pax.byteLength, 'x', 0o644, mtime)
-      yield pax
-      yield padding(pax.byteLength)
-      headerName = encoder.encode(input.name).subarray(0, 100)
-    }
-    yield header(headerName, input.size, '0', mode, mtime)
+    yield* entryHead(input)
     if (input.body instanceof Blob || isChunks(input.body)) {
       let n = 0
       const chunks = input.body instanceof Blob ? input.body.stream() : input.body

package/src/cache/zstd.ts

@@ -157,7 +157,7 @@ export const zstdEncoder = (): TransformStream<Uint8Array, Uint8Array> =>
   new CompressionStream('zstd') as unknown as TransformStream<Uint8Array, Uint8Array>
 
 /** Bytes in memory as a one-chunk stream, for a reader that takes a stream. */
-export const oneChunk = (bytes: Uint8Array): ReadableStream<Uint8Array> =>
+const oneChunk = (bytes: Uint8Array): ReadableStream<Uint8Array> =>
   new ReadableStream({
     start(c) {
       c.enqueue(bytes)

package/src/cli/cache.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs'
 import { Cache } from '../cache/index.js'
-import { flagHint, formatValue, refusedWord, seeHelp } from './help.js'
-import { nearest, parseDuration, parseSize } from '../util/index.js'
+import { flagHint, formatValue, refuse, refusedWord, seeHelp } from './help.js'
+import { errorCode, nearest, parseDuration, parseSize } from '../util/index.js'
 import { acquireRunLock } from '../orchestrator/index.js'
 import { findWorkspaceRoot } from '../workspace/index.js'
 import {
@@ -56,15 +56,19 @@ export async function cacheCmd(args: readonly string[]): Promise<number> {
       return await pruneCmd(rest)
     case undefined:
       // A bare `vx cache prune` refuses too: the hint names a whole command.
-      process.stderr.write(
-        `vx cache: missing subcommand. Try \`vx cache prune --older-than 30d\` or \`vx cache prune --max-size 1G\`${seeHelp('cache')}\n`,
+      return refuse(
+        'cache',
+        args,
+        `missing subcommand. Try \`vx cache prune --older-than 30d\` or \`vx cache prune --max-size 1G\`${seeHelp('cache')}`,
+        'VX_E_USAGE',
       )
-      return 1
     default:
-      process.stderr.write(
-        `vx cache: unknown subcommand: ${sub}${cacheSubHint(sub)}${seeHelp('cache')}\n`,
+      return refuse(
+        'cache',
+        args,
+        `unknown subcommand: ${sub}${cacheSubHint(sub)}${seeHelp('cache')}`,
+        'VX_E_USAGE',
       )
-      return 1
   }
 }
 
@@ -153,17 +157,13 @@ export function parsePruneArgs(args: readonly string[]): PruneArgs {
 
 async function pruneCmd(args: readonly string[]): Promise<number> {
   const parsed = parsePruneArgs(args)
-  if (parsed.error) {
-    process.stderr.write(`vx cache prune: ${parsed.error}\n`)
-    return 1
-  }
+  if (parsed.error) return refuse('cache prune', args, parsed.error, 'VX_E_USAGE')
   const cwd = process.cwd()
   let root: string
   try {
     root = await findWorkspaceRoot(cwd)
   } catch (err) {
-    process.stderr.write(`vx cache prune: ${(err as Error).message}\n`)
-    return 1
+    return refuse('cache prune', args, (err as Error).message, errorCode(err))
   }
   // Honor `--cache-dir`, `defineWorkspace({ cacheDir: '...' })` and a
   // `config` plugin's edit of it — `vx run` and `vx cache prune` must

package/src/cli/docs-corpus.ts

@@ -0,0 +1,21 @@
+// The pages `vx docs` searches: core's reference, imported as text so the
+// compiled binary carries them and an npm install reads them from the
+// package (package.json `files`). Loaded only by `vx docs`.
+import caching from '../../docs/caching.md' with { type: 'text' }
+import cli from '../../docs/cli.md' with { type: 'text' }
+import execution from '../../docs/execution.md' with { type: 'text' }
+import features from '../../docs/features.md' with { type: 'text' }
+import patterns from '../../docs/patterns.md' with { type: 'text' }
+import schema from '../../docs/schema.md' with { type: 'text' }
+import security from '../../docs/security.md' with { type: 'text' }
+
+/** Page name (its file, no `.md`) → markdown. */
+export const PAGES: Readonly<Record<string, string>> = {
+  cli,
+  schema,
+  caching,
+  execution,
+  patterns,
+  security,
+  features,
+}

package/src/cli/docs-text.d.ts

@@ -0,0 +1,5 @@
+// A markdown page imported `with { type: 'text' }` is its text (docs-corpus.ts).
+declare module '*.md' {
+  const text: string
+  export default text
+}