@vzn/vx 0.0.636 → 0.0.638

package/skills/vx/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vx
-description: Run, inspect and debug tasks in a vx monorepo (vx.config.ts, vx.workspace.ts). Use to build or test projects, find what a change affects, read why a task failed or re-ran, and query the cache as JSON.
+description: Run, inspect and debug tasks in a vx monorepo (vx.config.ts, .vx/workspace.ts). Use to build or test projects, find what a change affects, read why a task failed or re-ran, and query the cache as JSON.
 ---
 
 # vx
@@ -27,10 +27,21 @@ A refusal under `--format json` is one line on stdout,
 Without a TTY a missing task name never prompts: vx exits 1 and lists the
 tasks it found.
 
+## After editing a config
+
+```sh
+vx lock   # after any edit to a vx.config.ts or .vx/workspace.ts
+```
+
+A run reads every config from `.vx/projects.lock.json`, never the files:
+a task you add, or an edit to one, does nothing until `vx lock`. Commit
+the lock with the config.
+
 ## Look before running
 
 ```sh
-vx show --format json                          # projects, their tasks and dependencies
+vx show --format json                          # projects and their tasks
+vx show app --format json                      # one project's tasks as a run reads them
 vx run test --affected=origin/main --dry=json  # what would run, cache hit or miss, and why
 ```
 
@@ -59,22 +70,20 @@ files, fix, and re-run the same command: cached tasks that passed replay from th
 vx why app#build --format json   # which input changed, down to the root cause
 ```
 
-## Workspace health
+## Run history
 
 ```sh
-vx info --format json   # vx and Bun versions, projects, config errors, plugins, cache
+vx last --stats --format json            # per task: p50 (the live estimate's), p99, pass and hit rate, failure mode, peak RSS
+vx last --stats --branch main --format json  # p50 from main's timings
+vx last --stats app#build --format json  # one task; a task name covers every project
+vx last --list --format json             # recent runs, newest first
 ```
 
-## MCP
+## Workspace health
 
-When `@vzn/vx-mcp` is a plugin in `vx.workspace.ts`, `vx mcp` serves the
-same facts and runs tasks. Adoption does not add it: install
-`@vzn/vx-mcp` and put `mcp()` (from `'@vzn/vx-mcp'`) in `plugins`. Its tools: `listTasks`, `getCacheStats`,
-`getRunHistory`, `explainCacheKey`, `whyDidThisRerun`, `getFailures`, `getTaskLog`, `getConfig`, `checkLock`, `pruneCache`, `planInit`, `searchDocs`,
-`getWorkspaceInfo`, `runTasks`, `planTasks`. `runTasks` answers what
-`vx run <tasks> --format json` prints, `planTasks` what
-`vx run <tasks> --dry=json` prints, `pruneCache` evicts only with
-`dryRun: false`; the others only read.
+```sh
+vx info --format json   # vx and Bun versions, projects, config errors, plugins, cache
+```
 
 ## Rules
 
@@ -93,3 +102,9 @@ same facts and runs tasks. Adoption does not add it: install
   `https://raw.githubusercontent.com/vznjs/vx/main/packages/vx-docs/src/content/docs/<page>.md`:
   `quickstart`, `guides/migrate`, `guides/configure`, `guides/agents`,
   `guides/troubleshooting`, `guides/ci`, `guides/plugins`.
+
+## Install
+
+`npx skills add vznjs/vx` installs this skill. To match the vx a workspace
+has installed, copy it from there instead:
+`cp node_modules/@vzn/vx/skills/vx/SKILL.md .claude/skills/vx/`.

package/src/bin.ts

@@ -1,18 +1,33 @@
 #!/usr/bin/env -S bun --no-env-file --no-install
 // Wrapped in an explicit async main so `bun build --compile` accepts
 // the file. The compile target doesn't allow top-level await.
+import { handOff, localVx, vxPath } from './handoff.js'
+
 let settled = false
 
 async function main(): Promise<void> {
   const argv = process.argv.slice(2)
   try {
+    // Inside the try: `process.cwd()` throws EMFILE when out of descriptors,
+    // and that is a one-line UserError below, not a stack.
+    const local = await localVx(
+      process.cwd(),
+      process.execPath,
+      Bun.main.startsWith('/$bunfs') || (process.argv[1] ?? '').startsWith('/$bunfs'),
+    )
+    if (local !== null) await handOff(local, argv)
     // `vx --version` needs one leaf module; the dispatcher and the util
     // barrel it pulled in were 20 ms of its 28 (2026-10-01).
     if (argv.length === 1 && (argv[0] === '--version' || argv[0] === 'version')) {
       // `Bun.stdout`, not `process.stdout`: the Node stream's first touch is
       // ~7 ms, half of this verb (2026-10-02). A reader gone (EPIPE) is no
       // failure of the line.
-      await Bun.write(Bun.stdout, `vx ${(await import('./version.js')).VERSION}\n`).catch(() => {})
+      // Handed off, it says which vx ran and which one handed it the call.
+      const from = process.env['VX_HANDED_OFF']
+      const where = from === undefined ? '' : ` (${vxPath()}, handed off from ${from})`
+      await Bun.write(Bun.stdout, `vx ${(await import('./version.js')).VERSION}${where}\n`).catch(
+        () => {},
+      )
       settled = true
       return
     }
@@ -31,7 +46,7 @@ async function main(): Promise<void> {
     process.exitCode = code
   } catch (err) {
     const {
-      configErrorFrame,
+      detectColors,
       errorCode,
       errorDocument,
       fsRefusalHint,
@@ -40,6 +55,8 @@ async function main(): Promise<void> {
       isUserError,
       maskedLine,
       OUT_OF_FDS_HINT,
+      refusalNotice,
+      ui,
       wantsJson,
     } = await import('./util/index.js')
     // A plugin's failure quotes what it was told (a remote's reply, a
@@ -51,12 +68,16 @@ async function main(): Promise<void> {
     // on. Everything else gets the full stack so internal bugs are
     // debuggable.
     if (isUserError(err)) {
-      // A message that already names the tool (`vx why: …`, thrown by a verb
-      // that wants its own name in the line) is printed as it is; prefixing
-      // it produced `vx: vx why: …` (walkthrough, 2026-09-04).
-      // A config refusal names its line and shows it.
-      const m = configErrorFrame(err.message, process.cwd()) ?? err.message
-      say(m.startsWith('vx ') ? `${m}\n` : `vx: ${m}\n`)
+      // A message that names its verb (`vx why: …`) is that verb's; any
+      // other is the verb typed. A config refusal shows its line.
+      const named = /^(vx [a-z][\w-]*): /.exec(err.message)
+      const typed = /^[a-z][\w-]*$/.test(argv[0] ?? '') ? `vx ${argv[0]}` : 'vx'
+      const block = refusalNotice(
+        named?.[1] ?? typed,
+        named === null ? err.message : err.message.slice(named[0].length),
+        err.parts,
+      )
+      process.stderr.write(maskedLine(ui.render([block], detectColors(process.stderr))))
     } else if (isOutOfFds(err)) {
       say(`vx: ${err.message} — ${OUT_OF_FDS_HINT}\n`)
     } else if (isFsRefusal(err)) {
@@ -87,7 +108,7 @@ async function main(): Promise<void> {
  * config can leave a timer behind (a top-level `setInterval`, an await that
  * hit its evaluation budget), and the loop it holds never drained: vx
  * printed its verdict and hung for good. Only after `main` has settled, so
- * `vx watch`, `vx mcp` and a run's kept-alive tasks end when their verb
+ * `vx watch`, a plugin's long-lived verb and a run's kept-alive tasks end when their verb
  * does. `end(cb)` delivers a large write whole on Bun 1.4.2 (4 MiB under a
  * slow reader; `write('', cb)` delivered 450 KB), the floor `engines.bun`
  * holds. A stream whose end never calls back leaves the loop to drain. A

package/src/cache/archive.ts

@@ -230,6 +230,12 @@ interface PackArgs {
    * output of the same artifact is packed wherever it is.
    */
   within?: string
+  /**
+   * For a sandboxed task: whether it could read this canonical path. A
+   * symlinked output inside `within` whose target it could not read is
+   * refused like one outside it.
+   */
+  readable?: ((real: string) => boolean) | undefined
 }
 
 /** The largest second count ustar's 12-byte mtime field holds: 11 octal digits. */
@@ -321,6 +327,11 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
             )
           }
         }
+        if (args.readable !== undefined && !args.readable(src) && !(await ownOutputs()).has(src)) {
+          throw new UserError(
+            `${shown} is a symlink to ${src}, which the task's sandbox does not let it read: vx packs a symlinked output as its target's bytes — emit a file there, grant the target in exec.sandbox.allow.read, or take it back with a '!' entry`,
+          )
+        }
         st = await statOf(src).catch(dangling)
       }
       if (!st.isFile()) {

package/src/cache/cache.ts

@@ -43,6 +43,7 @@ import {
   mkdirSync,
   openSync,
   readdirSync,
+  readFileSync,
   renameSync,
   statSync,
   utimesSync,
@@ -53,6 +54,7 @@ import path from 'node:path'
 import { createArtifactTables, createTables, inHashes, lazyStatement } from './schema.js'
 import {
   UserError,
+  DOT_VX_GITIGNORE,
   formatBytes,
   isDiskFull,
   isFsRefusal,
@@ -105,7 +107,6 @@ import {
   zstdCompress,
   zstdEncoder,
 } from './zstd.js'
-import { ConfigEvalTable } from './config-evals.js'
 import { FileHashStore } from './file-hashes.js'
 import { OutputIndex } from './output-index.js'
 import { RunHistory } from './run-history.js'
@@ -148,6 +149,40 @@ const ACCESS_REFRESH_MS = 60 * 60 * 1000
  */
 const VX_ARTIFACT_NAME = /^([0-9a-f]{16})\.tar\.zst(\.tmp-\d+-\d+-[0-9a-z]*)?$/
 
+/** What vx writes in a cache directory besides its artifacts. */
+const VX_CACHE_NAMES = new Set([
+  'cache.db',
+  'cache.db-wal',
+  'cache.db-shm',
+  'cache.db-journal',
+  'runs',
+  'failures',
+  'lockfile-claims',
+])
+
+/**
+ * The entries of `cacheDir` vx wrote: the index, its artifacts, run
+ * history, and the `*` ignore file unless the user changed it. A clear of
+ * a directory the user named deletes these and nothing else (item 968).
+ */
+export function vxCacheEntries(cacheDir: string): string[] {
+  let names: string[]
+  try {
+    names = readdirSync(cacheDir)
+  } catch {
+    return []
+  }
+  return names.filter((name) => {
+    if (VX_CACHE_NAMES.has(name) || VX_ARTIFACT_NAME.test(name)) return true
+    if (name !== '.gitignore') return false
+    try {
+      return readFileSync(path.join(cacheDir, name), 'utf8') === IGNORE_ALL
+    } catch {
+      return false
+    }
+  })
+}
+
 /** The `schema_meta` key holding when the orphan sweep last ran (ms epoch). */
 const SWEPT_AT = 'orphans_swept_at'
 
@@ -167,7 +202,7 @@ function unreadableIndexError(dbFile: string, err: unknown): UserError {
   return new UserError(
     `the cache index ${dbFile} is not a database SQLite can read (${(err as Error).message}) — ` +
       `it holds nothing a run cannot rebuild: remove it with its -wal and -shm files and ` +
-      `re-run, and \`vx cache prune\` reclaims the artifacts it indexed`,
+      `re-run, and \`vx cache clean\` reclaims the artifacts it indexed`,
   )
 }
 
@@ -263,7 +298,18 @@ function outOfFdsAtOpen(dbFile: string, err: unknown): UserError | undefined {
 //        unchanged (CACHE_VERSION not bumped).
 //   v34: entry_inputs holds one row per entry, its key components as one
 //        JSON array, not a row per component. The cache KEY is unchanged.
-export const SCHEMA_VERSION = 'v34'
+//   v35: config_evals and config_closures are gone: runs read configs from
+//        the lock, and `vx lock` evaluates every one. The cache KEY is
+//        unchanged.
+//   v36: the store's task_durations: each executed success's time, tagged
+//        by branch, read by the forecast. The cache KEY is unchanged.
+//   v37: the store's plugin_blobs (a plugin's `ctx.cache`) and one
+//        'remote' task_durations row per (sha, task). The cache KEY is
+//        unchanged.
+//   v38: blob_sizes moved to the store, and the store's task_outcomes
+//        holds the flaky record, so worktrees share both. The cache KEY is
+//        unchanged.
+export const SCHEMA_VERSION = 'v38'
 
 /**
  * An entry's key components as its one `entry_inputs` row (v34): JSON
@@ -288,7 +334,17 @@ function encodeEntryInputs(
 }
 
 /** The tables a store holds: dropped from a workspace index that held them itself. */
-const STORE_TABLES = ['entry_inputs', 'output_files', 'entry_stdout', 'store_meta', 'entries']
+const STORE_TABLES = [
+  'entry_inputs',
+  'output_files',
+  'entry_stdout',
+  'task_durations',
+  'task_outcomes',
+  'blob_sizes',
+  'plugin_blobs',
+  'store_meta',
+  'entries',
+]
 
 /**
  * The inline artifacts' tables (schema.ts): dropped from a workspace index
@@ -549,13 +605,13 @@ function usageOfEntry(entry: { cpuMs?: number; peakRssBytes?: number }): ExecUsa
  * first. An existing cache costs three calls; it cost six.
  */
 function openCacheDir(cacheDir: string, workspaceRoot?: string): string | null {
-  const ignore = path.join(cacheDir, '.gitignore')
+  const [ignore, ignoreText] = ignoreFileFor(cacheDir)
   try {
     accessSync(cacheDir, constants.W_OK)
   } catch (err) {
     makeCacheDir(cacheDir)
     if ((err as NodeJS.ErrnoException).code !== 'ENOENT') return errorText(err)
-    writeFileSync(ignore, IGNORE_ALL)
+    writeIgnore(ignore, ignoreText)
     return null
   }
   try {
@@ -567,11 +623,7 @@ function openCacheDir(cacheDir: string, workspaceRoot?: string): string | null {
     if (code !== 'ENOENT') return errorText(err)
     refuseManifestDir(cacheDir, workspaceRoot)
   }
-  try {
-    writeFileSync(ignore, IGNORE_ALL, { flag: 'wx' })
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err
-  }
+  writeIgnore(ignore, ignoreText)
   return null
 }
 
@@ -630,6 +682,29 @@ function ensurePrivateDir(dir: string): string | null {
 const utf8 = new TextEncoder()
 const IGNORE_ALL = '*\n'
 
+/**
+ * The ignore file that keeps `cacheDir` out of git, and its text. The
+ * default `.vx/cache` is named by `.vx/.gitignore` (`/cache`), committed
+ * beside the workspace config and the lock (owner, 2026-10-14); any other
+ * cache directory holds a `*` one of its own. Written only when missing:
+ * an existing file is the user's.
+ */
+function writeIgnore(file: string, text: string): void {
+  try {
+    writeFileSync(file, text, { flag: 'wx' })
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err
+  }
+}
+
+function ignoreFileFor(cacheDir: string): [string, string] {
+  const parent = path.dirname(cacheDir)
+  if (path.basename(cacheDir) === 'cache' && path.basename(parent) === '.vx') {
+    return [path.join(parent, '.gitignore'), DOT_VX_GITIGNORE]
+  }
+  return [path.join(cacheDir, '.gitignore'), IGNORE_ALL]
+}
+
 /**
  * A first index in a directory that holds a manifest is a cache pointed at
  * the workspace or a project (`cacheDir: ''`, `'.'`, `'packages/a'`): the
@@ -675,9 +750,17 @@ function refuseManifestDir(cacheDir: string, workspaceRoot: string | undefined):
   }
 }
 
-const MANIFESTS = ['package.json', 'pnpm-workspace.yaml']
+// What marks a project or workspace directory: a vx config (workspace
+// PROJECT_CONFIG_FILENAMES) or the workspace file, and a package manifest,
+// which a `discover` plugin makes a project with no config.
+const MANIFESTS = [
+  'package.json',
+  'pnpm-workspace.yaml',
+  ...['ts', 'mts', 'js', 'mjs', 'cts', 'cjs'].map((ext) => `vx.config.${ext}`),
+  ...['ts', 'mts', 'js', 'mjs', 'cts', 'cjs'].map((ext) => `.vx/workspace.${ext}`),
+]
 const OWN_DIR_HINT =
-  'Point `cacheDir` in vx.workspace.ts (or --cache-dir) at a directory of its own, such as .vx/cache.'
+  'Point `cache.dir` in .vx/workspace.ts (or --cache-dir) at a directory of its own, such as .vx/cache.'
 
 function makeCacheDir(cacheDir: string): void {
   try {
@@ -687,7 +770,7 @@ function makeCacheDir(cacheDir: string): void {
     // so this is the first thing any of them says there.
     throw new UserError(
       `cannot create cache directory ${cacheDir} (${errorText(err)}) — vx keeps its cache there; make ` +
-        `the workspace writable, set \`cacheDir\` in vx.workspace.ts, or pass --cache-dir <path>`,
+        `the workspace writable, set \`cache.dir\` in .vx/workspace.ts, or pass --cache-dir <path>`,
     )
   }
 }
@@ -744,7 +827,6 @@ export class Cache implements CacheLayer {
   private readonly insertEntryInput: ReturnType<Database['prepare']>
   /** The per-file (mtime, size) → blob-OID memo behind `hashFile`. */
   private readonly files: FileHashStore
-  private readonly configEvals: ConfigEvalTable
   private readonly outputs: OutputIndex
   private readonly history: RunHistory
 
@@ -832,9 +914,8 @@ export class Cache implements CacheLayer {
     // The directory exists before the DB opens — bun:sqlite won't create
     // parent dirs for us. A directory this user cannot write into is a
     // read-only cache for every reader (`vx show`, `why`, `last`, the
-    // doctor, the watch sweep): the write axis goes off, so the
-    // config-evaluation store and the file-hash memo skip their upserts
-    // instead of dying in SQLite on the first miss (an unprivileged user on
+    // doctor, the watch sweep): the write axis goes off, so the file-hash
+    // memo skips its upserts instead of dying in SQLite on the first miss (an unprivileged user on
     // a root-owned `.vx`, 2026-09-16). A run wants more than a quiet
     // read-only cache — `assertWritable()`.
     // A reading verb over a directory with no index yet reads an empty one
@@ -958,7 +1039,7 @@ export class Cache implements CacheLayer {
             // keeps it so).
             if (found !== undefined) {
               this.db.exec(
-                'DROP TABLE IF EXISTS main.entries; DROP TABLE IF EXISTS main.runs; DROP TABLE IF EXISTS main.file_hashes; DROP TABLE IF EXISTS main.blob_sizes; DROP TABLE IF EXISTS main.blob_verdicts; DROP TABLE IF EXISTS main.output_files; DROP TABLE IF EXISTS main.output_stamps; DROP TABLE IF EXISTS main.invocations; DROP TABLE IF EXISTS main.run_task_inputs; DROP TABLE IF EXISTS main.entry_inputs; DROP TABLE IF EXISTS main.config_evals; DROP TABLE IF EXISTS main.config_closures; DROP TABLE IF EXISTS main.output_dirs; DROP TABLE IF EXISTS main.entry_stdout; DROP TABLE IF EXISTS main.store_meta;',
+                'DROP TABLE IF EXISTS main.entries; DROP TABLE IF EXISTS main.runs; DROP TABLE IF EXISTS main.file_hashes; DROP TABLE IF EXISTS main.blob_sizes; DROP TABLE IF EXISTS main.blob_verdicts; DROP TABLE IF EXISTS main.output_files; DROP TABLE IF EXISTS main.output_stamps; DROP TABLE IF EXISTS main.invocations; DROP TABLE IF EXISTS main.run_task_inputs; DROP TABLE IF EXISTS main.entry_inputs; DROP TABLE IF EXISTS main.config_evals; DROP TABLE IF EXISTS main.config_closures; DROP TABLE IF EXISTS main.output_dirs; DROP TABLE IF EXISTS main.entry_stdout; DROP TABLE IF EXISTS main.task_durations; DROP TABLE IF EXISTS main.plugin_blobs; DROP TABLE IF EXISTS main.task_outcomes; DROP TABLE IF EXISTS main.store_meta;',
               )
             }
             // The tables land under the same write lock as the stamp: made
@@ -1119,7 +1200,6 @@ export class Cache implements CacheLayer {
     // The slices: each owns its statements over this handle and its table(s);
     // the schema above is the one place every table is declared.
     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, (v) => this.digestValue(v))
 
@@ -1148,7 +1228,7 @@ export class Cache implements CacheLayer {
    * corrupt past the ones the open reads — to the open's own refusal. The
    * open reads the header and `schema_meta` alone (item 1005), so a file
    * corrupt deeper answered the first lookup that reached the bad page: every
-   * task of a run failed as an "internal error", and `vx cache prune` printed
+   * task of a run failed as an "internal error", and `vx cache clean` printed
    * a stack (A-8). Every other error passes through as it was.
    */
   private guard<T>(op: () => T): T {
@@ -1331,28 +1411,6 @@ export class Cache implements CacheLayer {
       .immediate()
   }
 
-  // --- config evaluations: `ConfigEvalStore`, delegated to `ConfigEvalTable` ---
-  getConfigEval(key: string): string | null {
-    return this.guard(() => this.configEvals.getConfigEval(key))
-  }
-  getConfigClosures(configPaths: readonly string[]): Map<string, string[]> {
-    return this.guard(() => this.configEvals.getConfigClosures(configPaths))
-  }
-  putConfigClosure(configPath: string, files: readonly string[]): void {
-    return this.guard(() => this.configEvals.putConfigClosure(configPath, files))
-  }
-  getConfigEvals(keys: readonly string[]): Map<string, string> {
-    return this.guard(() => this.configEvals.getConfigEvals(keys))
-  }
-  putConfigEval(key: string, json: string): void {
-    return this.guard(() => this.configEvals.putConfigEval(key, json))
-  }
-  putConfigEvals(entries: ReadonlyArray<readonly [string, string]>): void {
-    return this.guard(() => this.configEvals.putConfigEvals(entries))
-  }
-  putConfigClosures(entries: ReadonlyArray<readonly [string, readonly string[]]>): void {
-    return this.guard(() => this.configEvals.putConfigClosures(entries))
-  }
   // --- input file hashes: delegated to `FileHashStore` (see file-hashes.ts) ---
   hashFile(filePath: string): Promise<string> {
     return this.guard(() => this.files.hashFile(filePath))
@@ -1425,8 +1483,8 @@ export class Cache implements CacheLayer {
 
   /**
    * 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
+   * args after `--`): xxh3 under a random salt this store keeps. `vx why`
+   * and its JSON 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.
@@ -1462,7 +1520,7 @@ export class Cache implements CacheLayer {
   // the entries row. It's part of the contract so LayeredCache can
   // route metadata to `ingest()` on remote-hit without a separate API.
   async get(hash: string, ctx?: CacheGetContext): Promise<CacheEntry | null> {
-    // Local reads disabled (e.g. `--force` / `--cache=local:w`): report a
+    // Local reads disabled (e.g. `--force` / `--cache-policy=local:w`): report a
     // miss so the task re-executes. The artifact + index are untouched.
     if (!this.read) return null
     return this.guard(async () => {
@@ -1552,7 +1610,7 @@ export class Cache implements CacheLayer {
    * serve hits out of the PRE-EXISTING local cache" — it must not throw
    * away bytes this run just downloaded. `LayeredCache` calls this to
    * deliver an artifact it ingested from the remote; under
-   * `--cache=local:,remote:rw` the gated `get` returned null for the row
+   * `--cache-policy=local:,remote:rw` the gated `get` returned null for the row
    * `ingest` had just written, so the task re-executed and re-uploaded on
    * every single run.
    */
@@ -1688,6 +1746,16 @@ export class Cache implements CacheLayer {
     return this.guard(() => this.hasEntry(hash))
   }
 
+  /**
+   * The subset of `hashes` this store holds, `has` for each: the prefetch
+   * pass asks the remote only about the rest (M, 2026-10-15).
+   */
+  async localHasMany(hashes: readonly string[]): Promise<Set<string>> {
+    const out = new Set<string>()
+    for (const hash of hashes) if ((await this.has(hash)) === 'local') out.add(hash)
+    return out
+  }
+
   private async hasEntry(hash: string): Promise<'local' | 'remote' | null> {
     if (!this.read) return null
     const row = this.entryExists.get(hash) as { inline_at: number | null } | null
@@ -1799,7 +1867,7 @@ export class Cache implements CacheLayer {
     // outputs, so a restore that did not fail here would report a green cache
     // hit over an emptied output tree. The artifact existed when `get()`
     // probed it, so its absence now means something removed it underneath us
-    // (a `vx cache prune` in another shell, or another workspace's retention
+    // (a `vx cache clean` in another shell, or another workspace's retention
     // on a shared `--cache-dir`) — `ArtifactVanishedError`, which the caller
     // turns into a miss: the task runs.
     //
@@ -1991,6 +2059,8 @@ export class Cache implements CacheLayer {
     workspaceOutputFiles?: string[]
     workspaceRoot?: string
     inputComponents?: readonly TaskInputRow[]
+    /** See `CacheLayer.save`. */
+    readable?: ((real: string) => boolean) | undefined
   }): Promise<void> {
     // Layout (v17, extended additively for workspaceFiles): one
     // `<hash>.tar.zst` per entry. Tar carries ONLY the things you'd
@@ -2005,7 +2075,7 @@ export class Cache implements CacheLayer {
     // SQLite, not the artifact. Remote-hit ingestion takes metadata
     // through `ingest()` arguments — the artifact stays clean bytes.
     //
-    // Local writes disabled (e.g. `--cache=local:,remote:rw`): produce
+    // Local writes disabled (e.g. `--cache-policy=local:,remote:rw`): produce
     // no `<hash>.tar.zst` and no index row. The LayeredCache wrapping us
     // still uploads to remote — it calls `packArtifact` itself to get
     // the bytes, since there's no local artifact to read off disk.
@@ -2188,6 +2258,7 @@ export class Cache implements CacheLayer {
     outputFiles: string[]
     workspaceOutputFiles?: string[]
     workspaceRoot?: string
+    readable?: ((real: string) => boolean) | undefined
   }): Promise<Uint8Array> {
     // stdout is ALWAYS present in the artifact, even if empty, so the
     // layout is predictable: a successful read finds `stdout` and
@@ -2211,6 +2282,7 @@ export class Cache implements CacheLayer {
       outputs: this.outputsOf(args),
       exec: usageOfEntry(args.entry),
       within: args.projectDir,
+      readable: args.readable,
     })
     if (plan.size > this.artifactCeiling) {
       throw new Error(
@@ -2601,7 +2673,7 @@ export class Cache implements CacheLayer {
    * scan of the index and one read of the sweep's clock — never the
    * sweep's readdir. Null when nothing was due or the directory is not this
    * handle's to write. The local WRITE axis does not gate it: under
-   * `--cache=local:r,remote:rw` a save writes nothing here, but every remote
+   * `--cache-policy=local:r,remote:rw` a save writes nothing here, but every remote
    * hit is still ingested (`ingest`, ungated by design), and gated on that
    * axis the retention never ran while the store grew hit by hit (A-7).
    */
@@ -2887,20 +2959,19 @@ export class Cache implements CacheLayer {
     // Run-history retention: the runs table grows by one row per
     // executed task per invocation — a 2000-task repo accretes ~20k
     // rows in days, inflating insert and checkpoint cost forever.
-    // 30 days comfortably covers `vx stats` (24 h windows) and any
+    // 30 days comfortably covers `vx info` (24 h windows) and any
     // CI-side analytics consumers. The `invocations` header table (one
     // row per `vx run`) is pruned on the SAME window — otherwise a
     // header would outlive its `runs` rows, so `vx info`/`vx last` would
     // list an invocation whose task detail is already gone, and the
     // table would grow unbounded on a long-lived checkout.
     // A reading verb and a dry run delete nothing: `vx last --list` over
-    // month-old runs emptied the history it listed, and `vx cache prune
+    // month-old runs emptied the history it listed, and `vx cache clean
     // --dry-run` pruned it (item 1004).
     try {
       if (!this.inspecting) {
         const cutoff = Date.now() - 30 * 24 * 60 * 60 * 1000
         this.history.pruneOlderThan(cutoff)
-        this.configEvals.pruneOlderThan(cutoff)
         if (this.write) this.files.pruneOlderThan(cutoff)
       }
     } catch {

package/src/cache/chained-cache.ts

@@ -108,6 +108,10 @@ export class ChainedCache implements CacheLayer {
     return false
   }
 
+  localHasMany(hashes: readonly string[]): Promise<Set<string>> {
+    return this.layers[0]!.localHasMany?.(hashes) ?? Promise.resolve(new Set())
+  }
+
   async remoteHasMany(hashes: readonly string[]): Promise<Set<string> | null> {
     // The caller (remote-prefetch) treats a non-null answer as authoritative
     // for the WHOLE chain: complement = absent, broadcast. That is sound only