@vzn/vx 0.0.633 → 0.0.635

package/docs/patterns.md

@@ -183,11 +183,14 @@ Sharing the patterns doesn't mean sharing the overhead. On the
 476-package / 1,428-node synthetic workspace
 (`packages/vx-bench/compare.ts 20 25 1`, 2026-09-02):
 
-| Runner | Fresh (cold)          | Warm (no restore)       | Warm (restore)          |
-| ------ | --------------------- | ----------------------- | ----------------------- |
-| **vx** | 1m 40s                | **297 ms**              | **416 ms**              |
-| Turbo  | 1m 40s (vx same)      | 342 ms (vx 15% faster)  | 612 ms (vx 47% faster)  |
-| Nx     | 3m 23s (vx 2× faster) | 1.38 s (vx 4.6× faster) | 1.33 s (vx 3.2× faster) |
+| Runner | Warm (no restore)       | Warm (restore)          |
+| ------ | ----------------------- | ----------------------- |
+| **vx** | **297 ms**              | **416 ms**              |
+| Turbo  | 342 ms (vx 15% faster)  | 612 ms (vx 47% faster)  |
+| Nx     | 1.38 s (vx 4.6× faster) | 1.33 s (vx 3.2× faster) |
+
+A cached run is all runner overhead. Cold builds are compared by the
+time the runner adds, on [`benchmarks.md`](./benchmarks.md).
 
 vx N% faster: that tool takes N% longer than vx; N× faster: N times as long.
 

package/docs/schema.md

@@ -704,9 +704,38 @@ Semantics:
 interface CacheConfig {
   inputs: CacheInputs // required when `cache` is provided
   outputs: CacheOutputs // required when `cache` is provided
+  rewrittenInputs?: 'withhold' | 'compare' // optional, default 'withhold'
 }
 ```
 
+`rewrittenInputs` says what a write to an input while the command runs
+means. `'withhold'` (the default, on CI too): the result stands but the
+entry is not saved, since an edit undone mid-run, or another task
+changing the file and putting it back, cannot be told from no edit.
+`'compare'`: a file rewritten to the bytes the key folded counts as
+unchanged and the entry is saved, for a task that rewrites its own input
+identically (tsdown's `package.json`); different bytes still withhold
+it. `VX_REWRITTEN_INPUTS=compare` sets the default for every task that
+does not say (owner, 2026-10-12).
+
+```ts
+import { defineProject } from '@vzn/vx/config'
+
+export default defineProject({
+  tasks: {
+    build: {
+      // tsdown rewrites package.json with the same bytes on every build.
+      exec: { command: 'tsdown' },
+      cache: {
+        inputs: { files: ['src/**', 'package.json'] },
+        outputs: { files: ['dist/**'] },
+        rewrittenInputs: 'compare',
+      },
+    },
+  },
+})
+```
+
 **Caching is opt-in.** Omit `cache` and the task always runs (no read,
 no write). Provide it and caching is active for that task. The
 project loader requires _both_ `inputs` and `outputs` when `cache` is
@@ -1534,6 +1563,7 @@ export default defineWorkspace({
   affectedBase: 'origin/main',
   cacheScope: 'trusted',
   rules: { exclusiveOutputs: true, upfrontKeys: true },
+  schedule: 'most-work',
   plugins: [otel()],
 })
 ```
@@ -1554,8 +1584,10 @@ interface WorkspaceConfig {
   cacheScope?: string
   /** Graph rules checked before anything runs; each on unless set to false. */
   rules?: WorkspaceRules
+  /** Which ready task starts first with no timings: 'most-work' (default), 'critical-path', 'direct-dependents', 'ready-order'. */
+  schedule?: 'most-work' | 'critical-path' | 'direct-dependents' | 'ready-order'
   /** Run-level plugins (cache / executor / telemetry capabilities). */
-  plugins?: readonly Plugin[]
+  plugins?: readonly (Plugin | undefined | null | false)[]
 }
 
 interface WorkspaceRules {
@@ -1631,6 +1663,17 @@ run` takes `'read-only'` off CI (`CI` unset, `0` or `false`) and
   boundary: a run holding a write credential can write any key, so only
   a cache server that scopes writes by token can refuse one
   (`docs/security.md` § Cache poisoning). Not folded into any cache key.
+- **`schedule`** — which ready task starts first when more are ready
+  than workers, with no timings. `most-work` (the default): the one the
+  most tasks wait on, at any depth. `critical-path`: the head of the
+  longest chain of tasks below it. `direct-dependents`: the one the most
+  tasks wait on directly (Nx's rule). `ready-order`: the one that became
+  ready first (Turbo's rule). Each loses some graph shape the others win
+  (`blog/scheduling-strategies`). A `schedule` plugin's weights
+  (`@vzn/vx-schedule-history`) still sort first, and the strategy breaks
+  their ties. The default costs what it did; another strategy is
+  computed only when named. Any other value is refused. Never folded
+  into a cache key.
 - **`rules`** — checks on the task graph, each on unless set to
   `false`. Turning one off allows a shape vx runs correctly but more
   slowly; never folded into a cache key. A value that is not a boolean,
@@ -1668,7 +1711,9 @@ false } in vx.workspace.ts to let it wait for its producer.` Such a key
   Declaration order is precedence: every `executor` is consulted in
   order per task (first to accept runs it; what all decline runs
   locally); every `cache` layer is chained (lookup walks, save reaches
-  all, the local store last). Each entry is a `VxPlugin` contributing
+  all, the local store last). An `undefined`, `null` or `false` entry
+  is skipped, as Vite skips one: a factory that declines (`github()` off
+  Actions) or `cond && plugin()` needs no filter. Each entry is a `VxPlugin` contributing
   any subset of the fourteen hooks, in pipeline order: `config` (edit
   the workspace config before anything derives from it), `discover`
   (name directories to make projects beyond the members), `project`
@@ -2043,6 +2088,7 @@ a user meets most:
 | `cache.inputs.tasks must be an array of non-empty strings`                                                                            | Non-string / empty entry, or a bare string.                                                                                                                                                                                    |
 | `cache.inputs.tasks: "<name>" names no task in <task>.dependsOn`                                                                      | An exact entry no `dependsOn` entry of its form names.                                                                                                                                                                         |
 | `cache.outputs is required when cache is set`                                                                                         | Forgot `outputs`.                                                                                                                                                                                                              |
+| `cache.rewrittenInputs must be 'withhold' or 'compare'`                                                                               | Any other value (`'bytes'`, `true`).                                                                                                                                                                                           |
 | `cache.outputs must be an object`                                                                                                     | Present but not an object: a string (`outputs: 'dist'`). An array is the row above.                                                                                                                                            |
 | `cache.outputs.files must be an array`                                                                                                | Wrong shape.                                                                                                                                                                                                                   |
 | `cache.inputs.files: every entry is a negation, which selects NOTHING`                                                                | Only `!` globs — nothing to subtract from.                                                                                                                                                                                     |

package/docs/security.md

@@ -89,6 +89,12 @@ writes whatever its config says. Never give the write secret to a
 out a pull request's code: it runs with main's ref and secrets, and
 `github()` scopes it `pr-<n>` only on the client side.
 
+A boundary that holds whoever can write the store is a signing cache
+plugin: main's CI signs each upload, and a reader refuses, as it streams,
+a download no trusted key signed, so the hit is a miss. Core needs no
+change for it; the plugins guide (§ Your own cache › Signed artifacts) has a
+complete one, run by `tests/signed-cache-guide.unsafe.test.ts`.
+
 ## What vx checks on bytes it did not write
 
 Every artifact that arrives from a remote, and every one read back from

package/launcher.sh

@@ -0,0 +1,50 @@
+#!/bin/sh
+# npm launcher for a vx command: the published package's `bin`. It execs the
+# platform package's prebuilt binary straight from the shell, since Node's
+# own start was ~40 ms of every `vx` call made through node_modules/.bin
+# (45-53 ms against 12-14 ms for `vx --version`, 2026-10-12). Anything it
+# cannot settle (no sibling platform package, musl, Yarn PnP, an unknown
+# platform) goes to launcher.cjs beside it, which resolves through Node and
+# owns the fallbacks and the error messages.
+
+# The real file: npm's .bin entry is a symlink to it. Parameter expansion,
+# not dirname/basename, and no `cd`: each fork is a millisecond, and the
+# kernel resolves `<dir>/..` through a symlinked directory (pnpm's
+# node_modules/@vzn/vx) to its real parent on its own.
+self=$0
+hops=0
+while [ -L "$self" ] && [ "$hops" -lt 40 ]; do
+  hops=$((hops + 1))
+  target=$(readlink "$self")
+  case $target in
+    /*) self=$target ;;
+    *) self=${self%/*}/$target ;;
+  esac
+done
+case $self in
+  */*) here=${self%/*} ;;
+  *) here=. ;;
+esac
+base=${here##*/}
+scope=${here%/*}
+scope=${scope##*/}
+
+key=
+loader=
+case $(uname -sm) in
+  'Linux x86_64') key=linux-x64 loader=/lib64/ld-linux-x86-64.so.2 ;;
+  'Linux aarch64' | 'Linux arm64') key=linux-arm64 loader=/lib/ld-linux-aarch64.so.1 ;;
+  'Darwin x86_64') key=darwin-x64 ;;
+  'Darwin arm64') key=darwin-arm64 ;;
+esac
+
+# The platform package sits beside this one under npm, pnpm and Bun
+# (node_modules/@vzn/vx-<key>), or under this package's own node_modules
+# when npm could not hoist it. The glibc binary needs its loader (musl
+# has none); launcher.cjs names that cause.
+if [ -n "$key" ] && { [ -z "$loader" ] || [ -e "$loader" ]; }; then
+  for bin in "$here/../$base-$key/$base" "$here/node_modules/$scope/$base-$key/$base"; do
+    if [ -x "$bin" ]; then exec "$bin" "$@"; fi
+  done
+fi
+exec node "$here/launcher.cjs" "$@"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.633",
-  "description": "The fastest task runner and build cache for JavaScript monorepos.",
+  "version": "0.0.635",
+  "description": "Task orchestration you own: correct, sandboxed, extensible, with a content-addressed build cache.",
   "type": "module",
   "exports": {
     ".": {
@@ -15,16 +15,16 @@
   },
   "types": "./src/index.ts",
   "bin": {
-    "vx": "./launcher.cjs"
+    "vx": "./launcher.sh"
   },
   "engines": {
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.633",
-    "@vzn/vx-linux-arm64": "0.0.633",
-    "@vzn/vx-darwin-x64": "0.0.633",
-    "@vzn/vx-darwin-arm64": "0.0.633"
+    "@vzn/vx-linux-x64": "0.0.635",
+    "@vzn/vx-linux-arm64": "0.0.635",
+    "@vzn/vx-darwin-x64": "0.0.635",
+    "@vzn/vx-darwin-arm64": "0.0.635"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"
@@ -42,6 +42,7 @@
     "docs/patterns.md",
     "docs/security.md",
     "docs/features.md",
+    "launcher.sh",
     "launcher.cjs",
     "README.md",
     "LICENSE"
@@ -64,6 +65,14 @@
     "nx",
     "bun",
     "workspaces",
-    "ci"
+    "ci",
+    "task-orchestration",
+    "turborepo-alternative",
+    "nx-alternative",
+    "remote-cache",
+    "sandbox",
+    "incremental-build",
+    "mcp",
+    "pnpm"
   ]
 }

package/schemas/error.json

@@ -16,7 +16,11 @@
           "type": "string",
           "description": "Stable; branch on it. VX_E_USAGE, VX_E_UNKNOWN_COMMAND, VX_E_UNKNOWN_TASK, VX_E_UNKNOWN_PROJECT, VX_E_NO_HISTORY, VX_E_AMBIGUOUS, VX_E_CONFIG, VX_E_CYCLE, VX_E_NO_WORKSPACE, VX_E_CACHE_VERSION, VX_E_REFUSED, VX_E_FS, VX_E_FDS, VX_E_INTERNAL."
         },
-        "message": { "type": "string", "description": "The refusal in prose; may change." }
+        "message": { "type": "string", "description": "The refusal in prose; may change." },
+        "docs": {
+          "type": "string",
+          "description": "For a core code (VX_E_…): its section of the CLI reference, which says what to do. A plugin's code has none."
+        }
       }
     }
   }

package/schemas/last.json

@@ -170,7 +170,7 @@
         },
         "locations": {
           "type": "array",
-          "description": "on a failed row: the existing files its output names, in order of first appearance",
+          "description": "on a failed row: the existing files its output names, in order of first appearance; a file it also names with a line drops its bare mention",
           "items": {
             "type": "object",
             "additionalProperties": false,
@@ -181,6 +181,10 @@
               "col": { "type": "integer" }
             }
           }
+        },
+        "fixedIn": {
+          "type": "string",
+          "description": "on a failed row: the first later run where this task passed (ran or hit); absent while it has not"
         }
       }
     }

package/schemas/plan.json

@@ -6,6 +6,10 @@
   "additionalProperties": false,
   "required": ["tasks"],
   "properties": {
+    "affectedBase": {
+      "type": "string",
+      "description": "under --affected: the ref the diff was taken against (a bare --affected guesses it: origin/HEAD, a trunk branch, else HEAD~1)"
+    },
     "tasks": {
       "type": "array",
       "items": {

package/schemas/show.json

@@ -115,7 +115,8 @@
                 "files": { "$ref": "#/$defs/stringList" },
                 "workspaceFiles": { "$ref": "#/$defs/stringList" }
               }
-            }
+            },
+            "rewrittenInputs": { "enum": ["withhold", "compare"] }
           }
         }
       }

package/schemas/why.json

@@ -77,7 +77,10 @@
               "type": ["boolean", "null"],
               "description": "on a hit: true when outputs were restored, false when up-to-date"
             },
-            "cached": { "type": ["boolean", "null"] },
+            "cached": {
+              "type": ["boolean", "null"],
+              "description": "whether the task declares a cache; not whether this run hit it"
+            },
             "startedAt": { "type": "integer", "description": "epoch ms" }
           }
         },

package/skills/vx/SKILL.md

@@ -21,6 +21,9 @@ vx run build --all --format json    # the result as JSON on stdout; logs go to s
 The exit code is the verdict: `0` every task passed or hit the cache, `1` a
 task failed or was skipped, or the command was refused. `--format json`
 prints `schemas/summary.json` (`runId`, `ok`, `exitCode`, a row per task).
+A refusal under `--format json` is one line on stdout,
+`{"ok":false,"error":{"code","message","docs"}}`: branch on `code`;
+`docs` (or `vx docs <code>` offline) says what to do.
 Without a TTY a missing task name never prompts: vx exits 1 and lists the
 tasks it found.
 
@@ -31,7 +34,10 @@ vx show --format json                          # projects, their tasks and depen
 vx run test --affected=origin/main --dry=json  # what would run, cache hit or miss, and why
 ```
 
-Under `--affected`, each kept task in `--dry=json` carries `affected`:
+Under `--affected`, `--dry=json` states `affectedBase` (the ref it diffed
+against; name one, `--affected=origin/main`, rather than trust the guess)
+and each task you asked for carries `affected` (a dependency it pulls in
+does not):
 `{ kind, file?, project?, via? }`, where `kind` is `input` (a changed file
 is one of its inputs), `project`, `package`, `named` or `selected`, and
 `via` is the `dependsOn` chain that carried the change.

package/src/cache/cache.ts

@@ -122,6 +122,13 @@ import { CACHE_VERSION, foldKey } from './key-fold.js'
  */
 const ORPHAN_GRACE_MS = 60 * 60 * 1000
 
+/**
+ * Row-less lookups answered by a stat each before the artifact directory
+ * is listed once instead: a warm run's few misses keep their stat, a
+ * cold run's thousands share one listing.
+ */
+const ADOPT_STATS = 64
+
 /**
  * A hit renews an entry's `accessed_at` only once it is older than this:
  * renewing every hit rewrote 2,180 rows at a warm 1,090-package run's
@@ -730,6 +737,10 @@ export class Cache implements CacheLayer {
   private readonly heldInlineAt = new Map<string, number>()
   /** Keys the last lookups found an inline artifact for and no row: `adopt`'s to read. */
   private readonly rowless = new Set<string>()
+  /** Row-less lookups that stat'ed their artifact path (`artifactFileMayExist`). */
+  private adoptStats = 0
+  /** The artifact directory's names, listed once past `ADOPT_STATS`; this process's writes kept in it. */
+  private artifactNames: Set<string> | undefined
   private readonly insertEntryInput: ReturnType<Database['prepare']>
   /** The per-file (mtime, size) → blob-OID memo behind `hashFile`. */
   private readonly files: FileHashStore
@@ -1472,20 +1483,21 @@ export class Cache implements CacheLayer {
    * reader reads it, and indexed in one transaction with its bytes.
    */
   private async adopt(hash: string, ctx: CacheGetContext): Promise<boolean> {
-    const meta: IngestMeta = {
+    // Built only for an artifact found: its command is masked on read.
+    const meta = (): IngestMeta => ({
       taskId: ctx.taskId,
       command: ctx.command,
       durationMs: 0,
       ...(ctx.outputs !== undefined ? { outputs: ctx.outputs } : {}),
-    }
+    })
     // Only a key whose lookup saw a row-less inline artifact asks for it: a
     // statement per miss otherwise, on every cold save.
     const blob = this.rowless.delete(hash)
       ? (this.selectBlob.get(hash) as { bytes: Uint8Array } | null)
       : null
-    if (blob !== null) return this.adopted(this.writeArtifactAndIndex(hash, blob.bytes, meta))
+    if (blob !== null) return this.adopted(this.writeArtifactAndIndex(hash, blob.bytes, meta()))
     const finalPath = this.tarPath(hash)
-    if (!existsSync(finalPath)) return false
+    if (!this.artifactFileMayExist(hash)) return false
     const tmpPath = this.tempPath(hash)
     try {
       // A second name for the same bytes: the index step renames it over
@@ -1500,7 +1512,28 @@ export class Cache implements CacheLayer {
     } catch {
       return false
     }
-    return this.adopted(this.writeArtifactAndIndex(hash, { tmpPath }, meta))
+    return this.adopted(this.writeArtifactAndIndex(hash, { tmpPath }, meta()))
+  }
+
+  /**
+   * Whether `hash` may have a file artifact: a stat for the first
+   * `ADOPT_STATS` asks, then one listing of the directory. A cold
+   * 1,090-package run asked 3,270 times before its first task ran. A
+   * name listed and since removed fails the adopt's link, a miss; a file
+   * another process writes after the listing is missed too, and its own
+   * row serves it.
+   */
+  private artifactFileMayExist(hash: string): boolean {
+    const name = `${hash}.tar.zst`
+    if (this.artifactNames === undefined) {
+      if (++this.adoptStats <= ADOPT_STATS) return existsSync(path.join(this.artifactDir, name))
+      try {
+        this.artifactNames = new Set(readdirSync(this.artifactDir))
+      } catch {
+        this.artifactNames = new Set()
+      }
+    }
+    return this.artifactNames.has(name)
   }
 
   /** An adoption's verdict: an artifact that fails the checks is a miss. */
@@ -1562,6 +1595,27 @@ export class Cache implements CacheLayer {
     return entry
   }
 
+  /**
+   * Whether no lookup here can hit: no artifact, inline or file. Every
+   * entry has one, and a row-less one is still a hit (`adopt`). The listing
+   * is kept for `adopt`.
+   */
+  holdsNothing(): boolean {
+    if (!this.read) return true
+    if (this.guard(() => this.db.query('SELECT 1 FROM artifacts LIMIT 1').get()) != null) {
+      return false
+    }
+    let names: string[]
+    try {
+      names = readdirSync(this.artifactDir)
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') return false
+      names = []
+    }
+    this.artifactNames ??= new Set(names)
+    return !names.some((n) => n.endsWith('.tar.zst'))
+  }
+
   /**
    * `get` for many hashes at once: one `entries` query and one
    * `output_files` query per chunk instead of two per hash, with the
@@ -2391,6 +2445,7 @@ export class Cache implements CacheLayer {
       } else {
         aside = moveAside()
         renameSync(tmpPath!, finalPath)
+        this.artifactNames?.add(path.basename(finalPath))
         renamed = true
         deleteBlob.run(hash)
       }

package/src/cache/inputs.ts

@@ -219,7 +219,7 @@ export async function resolveInputs(args: ResolveInputsArgs): Promise<ResolvedIn
     // Dedupe: when the project dir IS the workspace root (or a glob
     // overlaps), the same absolute path can arrive via both lists —
     // it must contribute to the key exactly once.
-    if (wsFiles.length > 0) files = [...new Set([...projectFiles, ...wsFiles])].sort()
+    if (wsFiles.length > 0) files = mergeSorted(projectFiles, wsFiles)
   }
   // Two awaited empty resolutions per task were ~3 ms of a 1000-task warm
   // run (profiled 2026-09-09); a task declaring neither skips the fan-out.
@@ -285,7 +285,6 @@ function resolveWorkspaceFiles(args: {
   }
   if (positive.length === 0) return undefined
 
-  const isExcluded = anyTaskGlob([...ALWAYS_IGNORE, ...asTrees(negative)])
   // A path the task's own outputs take back with `!` is no output, so it
   // stays an input (A-44).
   const ownOutput = outputMatcher(args.ownWorkspaceOutputs)
@@ -310,40 +309,44 @@ function resolveWorkspaceFiles(args: {
   // The memo is valid for the snapshot it was computed over: a task that
   // wrote workspace outputs mid-run replaces the partition, and the next
   // caller sees a different array and scans again.
-  const memoKey =
-    args.memo === undefined
-      ? undefined
-      : JSON.stringify([
-          positive,
-          negative,
-          args.ownWorkspaceOutputs,
-          args.ownOutputs,
-          args.projectRel,
-        ])
+  let isExcluded: ((rel: string) => boolean) | undefined
   let isPositive: ((rel: string) => boolean) | undefined
-  const excluded = (rel: string): boolean => isExcluded(rel) || ownOutput(rel) || ownProject(rel)
+  const excludedByDeclaration = (rel: string): boolean =>
+    (isExcluded ??= anyTaskGlob([...ALWAYS_IGNORE, ...asTrees(negative)]))(rel)
+  const own = (rel: string): boolean => ownOutput(rel) || ownProject(rel)
   const listing: InputListing = {
     root: args.workspaceRoot,
     listed: gitFiles,
-    isInput: (rel) => (isPositive ??= anyTaskGlob(asTrees(positive)))(rel) && !excluded(rel),
+    isInput: (rel) =>
+      (isPositive ??= anyTaskGlob(asTrees(positive)))(rel) &&
+      !excludedByDeclaration(rel) &&
+      !own(rel),
     nested: () => false,
     ...reachOf(positive),
   }
-  if (memoKey !== undefined) {
-    const hit = args.memo!.get(memoKey)
-    if (hit !== undefined && hit.snapshot === gitFiles) return { files: hit.result, listing }
+  // Two levels: the declaration's files over the snapshot, shared by every
+  // task that declares it, then the task's own outputs taken out. A
+  // Turbo-mapped repo gives two thousand tasks one 400-entry list, and a
+  // memo keyed by the project too scanned, resolved and sorted the 4,000
+  // files it matched once per task (astro, 2026-10-09).
+  const declared = JSON.stringify([positive, negative])
+  let base: Promise<string[]> | undefined
+  const hit = args.memo?.get(declared)
+  if (hit !== undefined && hit.snapshot === gitFiles) base = hit.result
+  if (base === undefined) {
+    isPositive ??= anyTaskGlob(asTrees(positive))
+    base = resolveWorkspaceFilesOver(args, gitFiles, positive, isPositive, excludedByDeclaration)
+    args.memo?.set(declared, { snapshot: gitFiles, result: base })
   }
-  isPositive ??= anyTaskGlob(asTrees(positive))
-  const result = resolveWorkspaceFilesOver(
-    args,
-    gitFiles,
-    positive,
-    isPositive,
-    excluded,
-    undecodable,
-  )
-  if (memoKey !== undefined) args.memo!.set(memoKey, { snapshot: gitFiles, result })
-  return { files: result, listing }
+  const ownsAny =
+    splitNegations(args.ownWorkspaceOutputs).positive.length > 0 ||
+    splitNegations(args.ownOutputs).positive.length > 0
+  const files = base.then((all) => {
+    const kept = ownsAny ? all.filter((abs) => !own(relPosix(args.workspaceRoot, abs))) : all
+    refuseUndecodable(kept, undecodable, args.workspaceRoot, 'workspaceFiles')
+    return kept
+  })
+  return { files, listing }
 }
 
 async function resolveWorkspaceFilesOver(
@@ -352,7 +355,6 @@ async function resolveWorkspaceFilesOver(
   positive: readonly string[],
   isPositive: (rel: string) => boolean,
   excluded: (rel: string) => boolean,
-  undecodable: ReadonlySet<string> | undefined,
 ): Promise<string[]> {
   // Second call site of the literal-input guard. `resolveWorkspaceFiles`
   // carries its own copy of the filter-over-git-set design, so the same
@@ -371,13 +373,47 @@ async function resolveWorkspaceFilesOver(
   if (unmatchedLiterals.size > 0) {
     await assertNoInvisibleLiteralInputs(unmatchedLiterals, args.workspaceRoot, 'workspaceFiles')
   }
-  refuseUndecodable(candidates, undecodable, args.workspaceRoot, 'workspaceFiles')
   // Same OID-trust shortcut as project files: a clean-per-status
   // tracked file necessarily exists on disk.
   const oids = args.gitFilesCache?.oidsFor(args.workspaceRoot)
   return candidates.filter((abs) => oids?.has(abs) === true || isInputOnDisk(abs)).sort()
 }
 
+/**
+ * The sorted union of two path lists, each once. Both sides arrive sorted
+ * and distinct, so one merge does what a Set and a sort of the
+ * concatenation did: 3.7 s of an astro plan, where 2,000 tasks each joined
+ * a few project files to the same 4,000 workspace files (2026-10-09). A
+ * side out of order takes the general path.
+ */
+function mergeSorted(a: readonly string[], b: readonly string[]): string[] {
+  if (a.length === 0 && isStrictlySorted(b)) return b as string[]
+  if (!isStrictlySorted(a) || !isStrictlySorted(b)) return [...new Set([...a, ...b])].sort()
+  const out: string[] = []
+  let i = 0
+  let j = 0
+  while (i < a.length && j < b.length) {
+    const x = a[i]!
+    const y = b[j]!
+    if (x <= y) {
+      out.push(x)
+      i++
+      if (x === y) j++
+    } else {
+      out.push(y)
+      j++
+    }
+  }
+  while (i < a.length) out.push(a[i++]!)
+  while (j < b.length) out.push(b[j++]!)
+  return out
+}
+
+function isStrictlySorted(list: readonly string[]): boolean {
+  for (let i = 1; i < list.length; i++) if (!(list[i - 1]! < list[i]!)) return false
+  return true
+}
+
 /** A project-relative matcher asked of root-relative paths: false outside the project. */
 function underProject(
   projectRel: string,

package/src/cache/layered-cache.ts

@@ -76,7 +76,9 @@ export interface RemoteCacheLayer {
    * straight into the local cache — an HTTP wire returns its `fetch`
    * `Response`, a chunked wire `new Response(stream)`, bytes in hand
    * `new Blob([bytes])`. `durationMs` is the producing task's duration
-   * when the wire carries it.
+   * when the wire carries it. A body that errors before its end stores
+   * nothing and the read is a miss, so a layer can check bytes as they pass
+   * (a digest, a signature) and refuse at the end.
    */
   get(hash: string): Promise<{ body: Blob | Response; durationMs: number | undefined } | null>
   /**

package/src/cli/docs.ts

@@ -48,7 +48,7 @@ export interface DocsHit {
 }
 
 function words(s: string): string[] {
-  return s.toLowerCase().match(/[a-z0-9][a-z0-9._-]*/g) ?? []
+  return s.toLowerCase().match(/[a-z0-9][a-z0-9_.-]*/g) ?? []
 }
 
 /** GitHub's heading anchor, which Starlight shares: lowercase, punctuation dropped, spaces to `-`. */
@@ -99,7 +99,11 @@ function count(hay: string, term: string): number {
   return n
 }
 
-/** The sections holding every term, best first: a term in the heading outweighs any count in the text. */
+/**
+ * The sections holding every term, best first: a term in the heading
+ * outweighs any count in the text. A section titled by the one word asked
+ * (an error code) is the answer alone.
+ */
 export function searchDocs(
   pages: Readonly<Record<string, string>>,
   terms: readonly string[],
@@ -123,7 +127,9 @@ export function searchDocs(
     }
   }
   scored.sort((a, b) => b.score - a.score || a.order - b.order)
-  return scored.slice(0, limit).map(({ s }) => ({
+  const exact =
+    terms.length === 1 ? scored.filter(({ s }) => words(s.heading).join(' ') === terms[0]) : []
+  return (exact.length > 0 ? exact : scored).slice(0, limit).map(({ s }) => ({
     page: s.page,
     heading: s.heading,
     url: s.heading === '' ? pageUrl(s.page) : `${pageUrl(s.page)}#${anchor(s.heading)}`,

package/src/cli/help.ts

@@ -261,7 +261,8 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     'Docs:',
     '  vx docs <query>      Search the reference offline (cli, schema, caching, execution,',
     '                       patterns, security, features): the sections holding every',
-    '                       word of the query print whole, best first, with their URL.',
+    '                       word of the query print whole, best first, with their URL;',
+    '                       an error code (vx docs VX_E_CYCLE) prints its fix alone.',
     '      --limit N        How many sections (default 3).',
     '      --format json    {query, hits: [{page, heading, url, text}]}.',
     '',