@vzn/vx 0.0.21 → 0.0.22

package/src/cache/cache.ts

@@ -12,7 +12,7 @@
 // metadata — taskId, command, exitCode, durationMs, storedAt — lives
 // in the SQLite `entries` row. The same tar.zst bytes ship to a remote
 // cache server unchanged; on remote-hit, the caller supplies metadata
-// via the `ingest(hash, bytes, meta)` API so the local SQL index gets
+// via the `ingest(hash, body, meta)` API so the local SQL index gets
 // populated without sniffing the artifact.
 //
 // We never cache failed runs, so stderr is dropped from the cached
@@ -26,12 +26,23 @@
 // layer speaks is `CacheLayer` in layer.ts; `plugin-host.ts` enforces it.
 
 import { Database, type SQLQueryBindings } from 'bun:sqlite'
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
-import { mkdir, readdir, rename, rm, stat, unlink, writeFile } from 'node:fs/promises'
+import { accessSync, constants, existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { readdir, rename, rm, stat, unlink, writeFile } from 'node:fs/promises'
 import path from 'node:path'
-import { relPosix, UserError, xxh3, xxh3hex, span } from '../util/index.js'
+import {
+  UserError,
+  asTrees,
+  formatBytes,
+  isDiskFull,
+  isFsRefusal,
+  relPosix,
+  span,
+  splitTaskId,
+  taskGlob,
+} from '../util/index.js'
 import {
   ArchiveSecurityError,
+  type ArtifactPlan,
   type ExecUsage,
   extractArtifactStream,
   scanArtifact,
@@ -40,6 +51,7 @@ import {
   planArtifact,
 } from './archive.js'
 import {
+  ArtifactVanishedError,
   type CacheEntry,
   type CacheGetContext,
   type CacheKeyInput,
@@ -47,6 +59,7 @@ import {
   type CacheStats,
   type CacheStatsOptions,
   CorruptArtifactError,
+  type DeclaredOutputs,
   type IngestMeta,
   type InvocationRecord,
   type OutputDirRow,
@@ -56,72 +69,20 @@ import {
   type RunRecord,
   type SaveArgs,
   type TaskInputRow,
+  WORKSPACE_OUTPUT_PREFIX,
 } from './layer.js'
-import { bytesOf, decodedTar, STREAM_DECODE_FROM, zstdEncoder } from './zstd.js'
+import {
+  bytesOf,
+  decodedTar,
+  MAX_DECOMPRESSED_ARTIFACT_BYTES,
+  STREAM_DECODE_FROM,
+  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'
-
-// v17: artifact carries only logs + outputs (stdout + outputs/<rel>).
-// Local and remote layers transport the SAME tar.zst bytes — no
-// separate stage/meta.json/tar.gz dance for remote, no
-// `cache-archive.ts`. stderr is no longer cached: we only cache
-// successful runs and stderr is rarely meaningful on success.
-// v19: '^task' dependsOn expansion switched from transitive-deps to
-// nearest-holder frontier — upstream-hash sets shrink, so keys change.
-// v20: input-file content hashes switched from xxh3 to git blob OIDs
-// (Turbo parity). Clean tracked files take their OID straight from
-// the index (harvested by the bulk `git ls-files -s`); dirty /
-// untracked files get the identical OID computed in-process. Every
-// file's hash bytes change → bump. SCHEMA_VERSION moves with it:
-// pre-v20 `file_hashes.content_hash` rows hold xxh3 digests that
-// must not leak into the OID domain via the mtime+size memo.
-// v22: reverted the v21 output-fold "early cutoff". Downstream keys
-// fold the upstream's INPUT key (its task hash) again — pure-input
-// transitive hashing (Turbo/Nx model). No output content participates
-// in any cache key. SCHEMA v21 drops the now-unused outputs_hash
-// column. Early cutoff removed (an upstream that re-emits identical
-// output still re-runs dependents) — rare, not worth the cascade.
-// v23: fold cache.inputs.runtime / workspaceRuntime command output into
-// the key (two namespaced sections after env-values). Command strings
-// live in the resolved config (frozen by `vx lock`); the OUTPUT is
-// resolved live every run, so it stays correct under --frozen. No
-// SCHEMA bump — only Cache.key derivation changed.
-// v24: vx-lock.json added to the always-ignored input set (cache/
-// inputs.ts ALWAYS_IGNORE). A task whose globs matched the root
-// lockfile (broad `**/*` on the root project) drops it from the hashed
-// file set, so those keys change; tasks that never matched it are
-// byte-identical. No SCHEMA bump — only the input file set changed.
-//
-// CACHE_VERSION stays v24 through the Tier-3 schema roll (SCHEMA v22).
-// Tier 3 persists the very components already fed to `Cache.key()` —
-// it adds nothing to, reorders nothing in, and reweights nothing
-// inside the key fold (the new `captureInto` sink is a pure
-// side-channel). A task's hash is byte-identical before and after, so
-// existing artifacts stay valid and there is no cache-version bump.
-// v25: the ARTIFACT BYTES are wrong in every existing entry, while the
-// key that addresses them is unchanged — the one situation a version
-// bump exists for. Two defects: (a) `packArtifact` staged outputs with
-// `Bun.write`, which does not carry the source mode, so every artifact
-// records 0644 and a cache hit strips the executable bit off any binary
-// or generated script; (b) it packed `--format=ustar`, which splits a
-// name over 100 bytes into prefix+name, and the reader read only `name`
-// — so those entries lost their `outputs/` prefix and were silently
-// dropped from both the restore and the output_files index. Neither is
-// self-healing: the stored bytes/headers are already wrong, so without a
-// new namespace the fixed code would keep replaying them forever.
-// v26: same situation, different producer. A task whose child was killed by
-// a shutdown signal reported `aborted`, but `aborted` did not propagate to
-// dependents — so a dependent ran against PARTIAL outputs, succeeded, and
-// cached what it built. The fold takes the upstream's INPUT key, which a
-// signal does not change, so that entry sits under exactly the key a healthy
-// run derives and replays forever as a green hit. Fixing the propagation
-// stops new poison but cannot reach entries already written, and a
-// `LayeredCache` uploads them, so the reach is a whole team's shared cache
-// rather than one developer's disk. Pre-alpha, so one cold rebuild is the
-// cheap side of that trade.
-export const CACHE_VERSION = 'vx-cache-v27'
+import { CACHE_VERSION, foldKey } from './key-fold.js'
 
 /**
  * An artifact or temp file without an `entries` row is reaped by
@@ -132,13 +93,38 @@ export const CACHE_VERSION = 'vx-cache-v27'
  */
 const ORPHAN_GRACE_MS = 60 * 60 * 1000
 
+/**
+ * The only names the orphan sweep may unlink: an artifact under a key
+ * `foldKey` prints (16 lowercase hex) and the temp `tempPath` makes of
+ * one. `cacheDir` is the user's to point anywhere (`build/`, a shared
+ * directory), and the sweep once took any `*.tar.zst` an hour old there,
+ * the user's own release tarball included (item 968).
+ */
+const VX_ARTIFACT_NAME = /^([0-9a-f]{16})\.tar\.zst(\.tmp-\d+-\d+-[0-9a-z]*)?$/
+
+/** The `schema_meta` key holding when the orphan sweep last ran (ms epoch). */
+const SWEPT_AT = 'orphans_swept_at'
+
 export interface SchemaReset {
   from: string
   to: string
 }
 
+/** SQLite's answer for a file that is not a readable database: corrupt, or not one at all. */
+function unreadableIndex(err: unknown): boolean {
+  const code = (err as { code?: unknown }).code
+  return typeof code === 'string' && (code.startsWith('SQLITE_CORRUPT') || code === 'SQLITE_NOTADB')
+}
+
 /** Say once, on the channel the opener has, that an upgrade emptied the index. */
 export function noteSchemaReset(cache: Cache, warn: (message: string) => void): void {
+  if (cache.formatChange !== null) {
+    const { from, to } = cache.formatChange
+    warn(
+      `[vx] cache format changed: ${from} → ${to} (vx upgraded); every cached task misses once and re-saves, and the old entries, never read again, age out under \`vx cache prune --older-than\` or \`cacheRetention\``,
+    )
+    return
+  }
   if (cache.schemaReset === null) return
   const { from, to } = cache.schemaReset
   warn(
@@ -187,7 +173,20 @@ export function noteSchemaReset(cache: Cache, warn: (message: string) => void):
 //        tell the history what the task needs. The cache KEY and the
 //        artifact container are unchanged (no CACHE_VERSION bump: an
 //        artifact without the field reads as before).
-export const SCHEMA_VERSION = 'v26'
+//   v28: output_files.ino + .ctime_ms — the skip-restore check's guard
+//        against another entry's bytes. Two entries whose outputs carry
+//        one fixed mtime (`tar -x`, `cp -p`, SOURCE_DATE_EPOCH) and one
+//        size matched each other's (size, mode, mtime) rows, so a hit left
+//        the last entry's bytes on disk under a green run (item 886). A row
+//        is current only with the inode and ctime recorded after the save
+//        or restore that wrote it. The cache KEY is unchanged.
+export const SCHEMA_VERSION = 'v28'
+
+/** A schema version's number (`v28` → 28); one that is not `v<n>` is older than any. */
+function schemaOrdinal(version: string): number {
+  const m = /^v(\d+)$/.exec(version)
+  return m === null ? -1 : Number(m[1])
+}
 
 /**
  * SQL predicate selecting `runs` rows that record an EXECUTION.
@@ -214,17 +213,6 @@ export const EXECUTED_RUNS_SQL = "status <> 'skipped'"
  */
 export const KEYED_RUNS_SQL = "hash <> ''"
 
-/**
- * Artifact + `output_files` namespace prefix for workspace-root-
- * anchored outputs (`cache.outputs.workspaceFiles`). Project outputs
- * keep their bare project-relative `path` rows; workspace rows store
- * the full `workspace-outputs/<rel-to-root>` tar entry name as the
- * discriminator — least-invasive row format, no schema change. A
- * project output dir literally named `workspace-outputs/` would
- * collide with the namespace; the name is reserved.
- */
-export const WORKSPACE_OUTPUT_PREFIX = 'workspace-outputs/'
-
 // The contract, the policy grammar and the zstd framing live beside this
 // file; they are re-exported here so an importer of `./cache.js` — the
 // module index, the sibling layers, the tests — keeps one path.
@@ -273,6 +261,93 @@ function usageOfEntry(entry: { cpuMs?: number; peakRssBytes?: number }): ExecUsa
   }
 }
 
+/**
+ * Make `cacheDir` exist and say why this process cannot write into it, or
+ * `null` when it can: the directory must take new files (the WAL, the
+ * artifacts) and `cache.db`, when it exists, must take pages. The file
+ * system's answer, not a trial write — under WAL a rolled-back write never
+ * reaches the disk, so `BEGIN IMMEDIATE … ROLLBACK` passes on a handle
+ * SQLite opened read-only (proven as an unprivileged user, 2026-09-16).
+ *
+ * Every verb opens the cache, so each question here is one call whose
+ * failure is another question's answer: `access` on the directory is also
+ * "does it exist" (made only on ENOENT), `access` on the database also "is
+ * it there", and the ignore file is created exclusively instead of probed
+ * first. An existing cache costs three calls; it cost six.
+ */
+function openCacheDir(cacheDir: string): string | null {
+  const ignore = path.join(cacheDir, '.gitignore')
+  try {
+    accessSync(cacheDir, constants.W_OK)
+  } catch (err) {
+    makeCacheDir(cacheDir)
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') return errorText(err)
+    writeFileSync(ignore, IGNORE_ALL)
+    return null
+  }
+  try {
+    accessSync(path.join(cacheDir, 'cache.db'), constants.W_OK)
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code
+    // A FILE at `cacheDir` passed the `access` above; mkdir names it.
+    if (code === 'ENOTDIR') makeCacheDir(cacheDir)
+    if (code !== 'ENOENT') return errorText(err)
+    refuseManifestDir(cacheDir)
+  }
+  try {
+    writeFileSync(ignore, IGNORE_ALL, { flag: 'wx' })
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err
+  }
+  return null
+}
+
+// Make the cache dir invisible to git, every time it is created: a `*`
+// .gitignore inside it (the Cargo / Nx convention). Two reasons, both
+// measured. A cache nobody ignored gets COMMITTED by the next `git add -A`;
+// and vx's own `git status -uall` walks it — 1000 artifacts doubled the
+// enumeration on the bench workspace before its generator ignored `.vx`. An
+// ignored directory is skipped by the walk entirely. Only written when
+// absent, so a user's own file wins.
+const IGNORE_ALL = '*\n'
+
+/**
+ * A first index in a directory that holds a manifest is a cache pointed at
+ * the workspace or a project (`cacheDir: ''`, `'.'`, `'packages/a'`): the
+ * `*` ignore file above hid every file in it from git, so its inputs
+ * matched nothing and a changed source replayed the old output, and the
+ * artifacts landed among the sources (item 997). Asked only when there is
+ * no index yet, so an open cache pays nothing for it.
+ */
+function refuseManifestDir(cacheDir: string): void {
+  for (const manifest of ['package.json', 'pnpm-workspace.yaml']) {
+    if (!existsSync(path.join(cacheDir, manifest))) continue
+    throw new UserError(
+      `cache directory ${cacheDir} holds a ${manifest}: it is the workspace's or a project's own ` +
+        `directory, and vx would keep its index there under a \`*\` .gitignore that hides every file ` +
+        `in it from git and from the cache keys. Point \`cacheDir\` in vx.workspace.ts (or ` +
+        `--cache-dir) at a directory of its own, such as .vx/cache.`,
+    )
+  }
+}
+
+function makeCacheDir(cacheDir: string): void {
+  try {
+    mkdirSync(cacheDir, { recursive: true })
+  } catch (err) {
+    // A read-only checkout with no cache yet: every verb opens the cache,
+    // 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>`,
+    )
+  }
+}
+
+function errorText(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
 export class Cache implements CacheLayer {
   /** This IS the local layer — there is nothing slower behind it. */
   readonly hasRemote = false
@@ -298,6 +373,10 @@ export class Cache implements CacheLayer {
    */
   private readonly read: boolean
   private readonly write: boolean
+  /** A reading verb's handle (`Cache.inspect`): it prunes no history. */
+  private readonly inspecting: boolean
+  /** Why this process cannot write into `cacheDir`, or `null`; decided at open. */
+  private readonly writeBlocked: string | null
 
   /**
    * Set when THIS open found an index written by another `SCHEMA_VERSION`
@@ -309,42 +388,92 @@ export class Cache implements CacheLayer {
    */
   readonly schemaReset: SchemaReset | null = null
 
+  /**
+   * Set when THIS open found entries written under another
+   * `CACHE_VERSION`: the index survives, but no old key is derived again,
+   * so every cached task misses once. Reported by `noteSchemaReset`.
+   */
+  readonly formatChange: SchemaReset | null = null
+
+  /** A reading verb's open: it never resets the index (the constructor's `mode`). */
+  static inspect(cacheDir: string): Cache {
+    return new Cache(cacheDir, undefined, undefined, undefined, 'inspect')
+  }
+
   constructor(
     private readonly cacheDir: string,
     localPolicy: { read: boolean; write: boolean } = { read: true, write: true },
+    /** The workspace root, where the file hasher asks git for the object format (file-hashes.ts). */
+    repoDir?: string,
+    /**
+     * The largest artifact, decoded, this cache saves, ingests or
+     * restores (zstd.ts). Lowered only by a test, through
+     * `RunOptions.artifactCeiling`: 2 GiB of output is out of a test's reach.
+     */
+    private readonly artifactCeiling: number = MAX_DECOMPRESSED_ARTIFACT_BYTES,
+    /**
+     * `'inspect'`: a reading verb (`why`, `last`, `info`, a dry prune). It
+     * never resets the index: a schema it cannot read is refused, named,
+     * and left as it was.
+     */
+    mode: 'open' | 'inspect' = 'open',
   ) {
+    this.inspecting = mode === 'inspect'
     this.read = localPolicy.read
-    this.write = localPolicy.write
-    // Ensure the directory exists before opening the DB — bun:sqlite
-    // won't create parent dirs for us. The constructor stays sync
-    // because callers use `new Cache(...)` directly; `mkdirSync` keeps
-    // that property without a subprocess fork.
-    mkdirSync(cacheDir, { recursive: true })
-    // Make the cache dir invisible to git, every time it is created: a
-    // `*` .gitignore inside it (the Cargo / Nx convention). Two reasons,
-    // both measured. A cache nobody ignored gets COMMITTED by the next
-    // `git add -A`; and vx's own `git status -uall` walks it — 1000
-    // artifacts doubled the enumeration on the bench workspace before
-    // its generator ignored `.vx`. An ignored directory is skipped by the
-    // walk entirely. Only written when absent, so a user's own file wins.
-    const ignore = path.join(cacheDir, '.gitignore')
-    if (!existsSync(ignore)) writeFileSync(ignore, '*\n')
-    this.db = new Database(path.join(cacheDir, 'cache.db'), { create: true })
-    this.db.exec('PRAGMA journal_mode = WAL')
-    this.db.exec('PRAGMA synchronous = NORMAL')
-    this.db.exec('PRAGMA foreign_keys = ON')
+    // 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
+    // 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
+    // in memory and makes nothing on disk: `vx last --cache-dir .vx/cahce`
+    // created the typo's directory, a `.gitignore` and a database, then
+    // said "no recorded runs yet" (item 900).
+    const dbFile = path.join(cacheDir, 'cache.db')
+    const absent = mode === 'inspect' && !existsSync(dbFile)
+    this.writeBlocked = absent ? 'no index there yet' : openCacheDir(cacheDir)
+    this.write = localPolicy.write && this.writeBlocked === null
+    this.db = new Database(absent ? ':memory:' : dbFile, { create: true })
     // busy_timeout makes concurrent writers wait for the lock instead of
     // failing immediately with SQLITE_BUSY. Two parallel `vx run`
     // invocations in CI is a normal pattern; without this the second one
-    // crashes in recordRun().
-    this.db.exec('PRAGMA busy_timeout = 5000')
-
-    this.db.exec(`
-      CREATE TABLE IF NOT EXISTS schema_meta (
-        key TEXT PRIMARY KEY,
-        value TEXT NOT NULL
-      );
-    `)
+    // crashes in recordRun(). FIRST, before the journal-mode switch: that
+    // pragma takes a lock of its own, and set after it the timeout did not
+    // cover it — two CLI runs opening one cache at the same instant met
+    // `database is locked` right here, on macOS's slower disk first
+    // (2026-09-16, the run lock's own e2e; the lock is taken after the
+    // cache opens, so the open is the one moment two runs still overlap).
+    // A file SQLite cannot read as a database answers the first statement
+    // that reads it, and reached every verb as `SQLiteError: file is not a
+    // database` and a stack, `vx run` and the doctor included (item 1005).
+    const readable = <T>(read: () => T): T => {
+      try {
+        return read()
+      } catch (err) {
+        if (!unreadableIndex(err)) throw err
+        this.db.close()
+        throw 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`,
+        )
+      }
+    }
+    readable(() => {
+      this.db.exec('PRAGMA busy_timeout = 5000')
+      this.db.exec('PRAGMA journal_mode = WAL')
+      this.db.exec('PRAGMA synchronous = NORMAL')
+      this.db.exec('PRAGMA foreign_keys = ON')
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS schema_meta (
+          key TEXT PRIMARY KEY,
+          value TEXT NOT NULL
+        );
+      `)
+    })
 
     // Schema-version gate runs BEFORE the rest of the schema lands so
     // a column rename (e.g. v15's `sha256` → `content_hash`) actually
@@ -353,19 +482,62 @@ export class Cache implements CacheLayer {
     // sees them (rows first, then the file), the next save of the same
     // key renames over them, and `prune()`'s orphan sweep unlinks the
     // rest.
-    const meta = this.db.prepare("SELECT value FROM schema_meta WHERE key = 'version'").get() as
-      | { value: string }
-      | undefined
-    if (meta && meta.value !== SCHEMA_VERSION) {
-      this.schemaReset = { from: meta.value, to: SCHEMA_VERSION }
-      this.db.exec(
-        'DROP TABLE IF EXISTS entries; DROP TABLE IF EXISTS runs; DROP TABLE IF EXISTS file_hashes; DROP TABLE IF EXISTS output_files; DROP TABLE IF EXISTS invocations; DROP TABLE IF EXISTS run_task_inputs; DROP TABLE IF EXISTS entry_inputs; DROP TABLE IF EXISTS config_evals;',
-      )
-      this.db.prepare("UPDATE schema_meta SET value = ? WHERE key = 'version'").run(SCHEMA_VERSION)
-    } else if (!meta) {
-      this.db
-        .prepare("INSERT INTO schema_meta(key, value) VALUES ('version', ?)")
-        .run(SCHEMA_VERSION)
+    //
+    // The write half runs under the write lock and reads the row again: two
+    // processes opening one NEW cache both read no row, and the second
+    // insert died on the primary key (upstream survey, nx#28608). A warm
+    // open reads the current version and takes no lock.
+    const readVersion = (): string | undefined =>
+      (
+        this.db.prepare("SELECT value FROM schema_meta WHERE key = 'version'").get() as
+          | { value: string }
+          | undefined
+      )?.value
+    // Only an EARLIER schema is reset, and only by an opener that may write
+    // it. A newer one is another vx's index and history: an older binary
+    // (a global install beside a workspace's own) dropped every table of it
+    // and announced "vx upgraded", and so did a reading verb, a dry prune
+    // among them (item 896).
+    const refuseUnreadable = (found: string): void => {
+      if (schemaOrdinal(found) > schemaOrdinal(SCHEMA_VERSION)) {
+        throw new UserError(
+          `the cache at ${cacheDir} holds index schema ${found}, written by a newer vx; this vx reads ${SCHEMA_VERSION} and leaves it untouched. Run the newer vx, or give this one another --cache-dir`,
+        )
+      }
+      if (mode === 'inspect') {
+        throw new UserError(
+          `the cache at ${cacheDir} holds index schema ${found} from an earlier vx; this vx reads ${SCHEMA_VERSION}, so nothing in it is readable here. The next \`vx run\` resets it; a reading verb leaves it untouched`,
+        )
+      }
+    }
+    const current = readable(readVersion)
+    if (current !== SCHEMA_VERSION) {
+      try {
+        if (current !== undefined) refuseUnreadable(current)
+        this.schemaReset = this.db
+          .transaction((): SchemaReset | null => {
+            const found = readVersion()
+            if (found !== undefined && found !== SCHEMA_VERSION) refuseUnreadable(found)
+            if (found === undefined) {
+              this.db
+                .prepare("INSERT INTO schema_meta(key, value) VALUES ('version', ?)")
+                .run(SCHEMA_VERSION)
+              return null
+            }
+            if (found === SCHEMA_VERSION) return null
+            this.db.exec(
+              'DROP TABLE IF EXISTS entries; DROP TABLE IF EXISTS runs; DROP TABLE IF EXISTS file_hashes; DROP TABLE IF EXISTS output_files; DROP TABLE IF EXISTS invocations; DROP TABLE IF EXISTS run_task_inputs; DROP TABLE IF EXISTS entry_inputs; DROP TABLE IF EXISTS config_evals;',
+            )
+            this.db
+              .prepare("UPDATE schema_meta SET value = ? WHERE key = 'version'")
+              .run(SCHEMA_VERSION)
+            return { from: found, to: SCHEMA_VERSION }
+          })
+          .immediate()
+      } catch (err) {
+        this.db.close()
+        throw err
+      }
     }
 
     // Cached config evaluations (workspace/config-cache.ts): the validated
@@ -426,7 +598,16 @@ export class Cache implements CacheLayer {
         attempts            INTEGER,
         -- v25: 1 when the task declared a cache block, 0 when it runs every
         -- time by design; NULL on rows older than the column.
-        cached              INTEGER
+        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
+        -- 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.
+        blocked_by          TEXT,
+        timed_out           INTEGER,
+        sandbox_violations  INTEGER,
+        not_ready           TEXT
       );
       -- Two whole-table indexes only, and both APPEND: every row of a run carries the
       -- same run_id and a started_at newer than everything before it, so
@@ -483,14 +664,13 @@ export class Cache implements CacheLayer {
         size_bytes  INTEGER NOT NULL,
         mode        INTEGER NOT NULL,
         mtime_ms    INTEGER NOT NULL,
+        -- v28: the inode and ctime this machine saw after the save or
+        -- restore that left the file equal to the entry; NULL until then.
+        ino         INTEGER,
+        ctime_ms    INTEGER,
         PRIMARY KEY (entry_hash, path),
         FOREIGN KEY (entry_hash) REFERENCES entries(hash) ON DELETE CASCADE
       );
-      -- Every directory under a whole-subtree output glob, with its mtime
-      -- as of the last save/restore on THIS machine (2026-09-03). On a warm
-      -- hit, unchanged mtimes prove the output SET is unchanged, replacing
-      -- the glob walk that cost 0.36 ms per hit. Machine-local: a remote
-      -- ingest writes none, and the first hit after it walks and records.
       -- Each config's ORDERED import closure (the config first), so a warm
       -- load keys it by stat-hashing the list (the file_hashes memo) instead
       -- of reading and scanning every file. Machine-local; pruned with
@@ -500,6 +680,11 @@ export class Cache implements CacheLayer {
         files_json  TEXT NOT NULL,
         created_at  INTEGER NOT NULL
       );
+      -- Every directory under a whole-subtree output glob, with its mtime
+      -- as of the last save/restore on THIS machine (2026-09-03). On a warm
+      -- hit, unchanged mtimes prove the output SET is unchanged, replacing
+      -- the glob walk that cost 0.36 ms per hit. Machine-local: a remote
+      -- ingest writes none, and the first hit after it walks and records.
       CREATE TABLE IF NOT EXISTS output_dirs (
         entry_hash  TEXT NOT NULL,
         path        TEXT NOT NULL,
@@ -588,10 +773,29 @@ 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.configEvals = new ConfigEvalTable(this.db, localPolicy)
+    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)
+
+    // A CACHE_VERSION bump keeps the index but moves every key, so the run
+    // after an upgrade misses everything. Roadmap 3.3: that is announced,
+    // never silent. A store with no recorded version and no entries is
+    // new; one with entries predates the record (item 671).
+    const format = this.db
+      .prepare("SELECT value FROM schema_meta WHERE key = 'cache_version'")
+      .get() as { value: string } | null
+    if (format?.value !== CACHE_VERSION && this.writeBlocked === null) {
+      const hasEntries = this.db.prepare('SELECT 1 FROM entries LIMIT 1').get() != null
+      if (this.schemaReset === null && (format !== null || hasEntries)) {
+        this.formatChange = { from: format?.value ?? 'an earlier format', to: CACHE_VERSION }
+      }
+      this.db
+        .prepare(
+          "INSERT INTO schema_meta(key, value) VALUES ('cache_version', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+        )
+        .run(CACHE_VERSION)
+    }
   }
 
   // --- config evaluations: `ConfigEvalStore`, delegated to `ConfigEvalTable` ---
@@ -610,113 +814,47 @@ export class Cache implements CacheLayer {
   putConfigEval(key: string, json: string): void {
     this.configEvals.putConfigEval(key, json)
   }
+  putConfigEvals(entries: ReadonlyArray<readonly [string, string]>): void {
+    this.configEvals.putConfigEvals(entries)
+  }
+  putConfigClosures(entries: ReadonlyArray<readonly [string, readonly string[]]>): void {
+    this.configEvals.putConfigClosures(entries)
+  }
   // --- input file hashes: delegated to `FileHashStore` (see file-hashes.ts) ---
   hashFile(filePath: string): Promise<string> {
     return this.files.hashFile(filePath)
   }
+  hashBytes(bytes: Uint8Array, nearPath: string): string {
+    return this.files.hashBytes(bytes, nearPath)
+  }
   hashFiles(paths: readonly string[]): Promise<Map<string, string>> {
     return this.files.hashFiles(paths)
   }
-  async key(input: CacheKeyInput): Promise<string> {
-    // Seed-chained xxHash3: each step folds one field into the
-    // running digest via `xxh3(part, prevDigest)`. Equivalent to the
-    // old CryptoHasher.update() pattern, no intermediate buffer.
-    // Field-order matters; each line is prefixed with its label so
-    // adjacent fields can't collide via concat.
-    // Optional capture sink — see CacheKeyInput.captureInto. Pure
-    // side-channel; every push below mirrors the fold immediately
-    // above/beside it so the recorded set can't drift from the key.
-    const cap = input.captureInto
-    let h = xxh3(CACHE_VERSION)
-    h = xxh3(`task:${input.taskId}`, h)
-    h = xxh3(`workspace:${input.workspaceFingerprint}`, h)
-    h = xxh3(`pkg:${input.projectPackageJsonHash}`, h)
-    h = xxh3(`config:${input.taskConfigHash}`, h)
-    if (cap) {
-      cap.push({ kind: 'workspace', name: 'fingerprint', hash: input.workspaceFingerprint })
-      cap.push({ kind: 'package', name: 'package.json', hash: input.projectPackageJsonHash })
-      cap.push({ kind: 'config', name: 'config', hash: input.taskConfigHash })
-    }
-
-    // NOTE on `cap` (entry_inputs capture): the `hash` field stores a
-    // DIGEST of each component, never the raw value. For value-bearing kinds
-    // (env, runtime, ws-runtime, forward) the payload is a secret or
-    // sensitive string (API keys via cache.inputs.env, runtime-command
-    // output, args after `--`), so we push `xxh3hex(v)` — the diff consumer
-    // only needs to know whether a component CHANGED, which a digest
-    // preserves losslessly. cache.db must never hold plaintext secrets at
-    // rest. The cache KEY (`h`) folds the plaintext separately below and is
-    // unaffected.
-    const forwarded = input.forwardArgs ?? []
-    h = xxh3(`forward-args:${forwarded.length}`, h)
-    for (const a of forwarded) h = xxh3(a, h)
-    if (cap && forwarded.length > 0) {
-      cap.push({ kind: 'forward', name: 'argv', hash: xxh3hex(JSON.stringify(forwarded)) })
-    }
-
-    h = xxh3(`env-values:${input.envValues.length}`, h)
-    // \0 delimiter, not `=`: names and values may themselves contain
-    // `=`, and `A` + `B=C` must never fold the same bytes as `A=B` + `C`.
-    for (const [n, v] of input.envValues) h = xxh3(`${n}\0${v}`, h)
-    if (cap)
-      for (const [n, v] of input.envValues) cap.push({ kind: 'env', name: n, hash: xxh3hex(v) })
-
-    const runtimeValues = input.runtimeValues ?? []
-    h = xxh3(`runtime-values:${runtimeValues.length}`, h)
-    for (const [c, o] of runtimeValues) h = xxh3(`${c}\0${o}`, h)
-    if (cap)
-      for (const [c, o] of runtimeValues) cap.push({ kind: 'runtime', name: c, hash: xxh3hex(o) })
-
-    const wsRuntimeValues = input.workspaceRuntimeValues ?? []
-    h = xxh3(`ws-runtime-values:${wsRuntimeValues.length}`, h)
-    for (const [c, o] of wsRuntimeValues) h = xxh3(`${c}\0${o}`, h)
-    if (cap)
-      for (const [c, o] of wsRuntimeValues)
-        cap.push({ kind: 'ws-runtime', name: c, hash: xxh3hex(o) })
-
-    const upstream = [...input.upstreamHashes].sort()
-    h = xxh3(`upstream:${upstream.length}`, h)
-    for (const u of upstream) h = xxh3(u, h)
-    if (cap) {
-      for (const u of upstream) {
-        cap.push({ kind: 'upstream', name: input.upstreamIds?.get(u) ?? u, hash: u })
-      }
-    }
-
-    const pluginParts = input.pluginParts ?? []
-    if (pluginParts.length > 0) {
-      h = xxh3(`plugin:${pluginParts.length}`, h)
-      for (const [n, v] of pluginParts) h = xxh3(`${n}\0${v}`, h)
-      if (cap) {
-        for (const [n, v] of pluginParts) cap.push({ kind: 'plugin', name: n, hash: xxh3hex(v) })
-      }
+  /**
+   * `relPosix` against the run's workspace root, memoized: the same three
+   * thousand files are re-relativized for every task of the project, which
+   * is 132,000 calls for 3,000 answers on this repo's own gate. Cleared
+   * when a caller arrives with a different root, so the memo can never
+   * answer for a workspace it did not measure.
+   */
+  private relMemo = new Map<string, string>()
+  private relMemoRoot: string | undefined
+  private relFor(root: string, file: string): string {
+    if (root !== this.relMemoRoot) {
+      this.relMemoRoot = root
+      this.relMemo.clear()
     }
+    let rel = this.relMemo.get(file)
+    if (rel === undefined) this.relMemo.set(file, (rel = relPosix(root, file)))
+    return rel
+  }
 
-    const sortedInputs = [...input.inputFiles].sort()
-    h = xxh3(`inputs:${sortedInputs.length}`, h)
-    // Per-file hash source, in preference order: the caller-supplied
-    // index-OID map (clean tracked files — zero I/O), then hashFile's
-    // stat memo (no read), then a full in-process blob-OID computation.
-    // All three describe the WORKTREE bytes, which is what the task
-    // reads — the index-OID map is only populated for paths whose
-    // worktree form matches their index form, because a clean filter
-    // (`text`/`eol`/`ident`) makes the index blob a DIFFERENT sequence
-    // of bytes and folding it would let two distinct worktree contents
-    // share a key. The fold order is locked to `sortedInputs` so
-    // results are stable across runs.
-    const fileHashes = await Promise.all(
-      sortedInputs.map((f) => input.fileHashes?.get(f) ?? this.hashFile(f)),
+  key(input: CacheKeyInput): Promise<string> {
+    return foldKey(
+      input,
+      (f) => this.hashFile(f),
+      (f) => this.relFor(input.workspaceRoot, f),
     )
-    for (let i = 0; i < sortedInputs.length; i++) {
-      const file = sortedInputs[i]!
-      const rel = relPosix(input.workspaceRoot, file)
-      const oid = fileHashes[i]!
-      h = xxh3(`${rel}\0${oid}`, h)
-      // The OID is already awaited — file capture is zero extra I/O.
-      if (cap) cap.push({ kind: 'file', name: rel, hash: oid })
-    }
-
-    return h.toString(16).padStart(16, '0')
   }
 
   // ctx is accepted but ignored — the local layer reads metadata from
@@ -841,6 +979,9 @@ export class Cache implements CacheLayer {
   ): Promise<void> {
     await this.outputs.recordOutputDirs(hash, projectDir, prefixes)
   }
+  recordOutputStamps(hash: string, projectDir: string, workspaceRoot: string): void {
+    this.outputs.recordOutputStamps(hash, projectDir, workspaceRoot)
+  }
   loadOutputDirsBatch(hashes: readonly string[]): Map<string, OutputDirRow[]> {
     return this.outputs.loadOutputDirsBatch(hashes)
   }
@@ -861,16 +1002,22 @@ export class Cache implements CacheLayer {
     // replay through the logger.
     const src = this.tarPath(hash)
     // The caller already committed to this hit and WIPED the declared
-    // outputs, so returning quietly 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 concurrent
-    // `vx cache prune` is the documented way) — fail loud; the task re-runs.
-    const endExists = span('restore: exists')
-    const exists = await Bun.file(src).exists()
-    endExists()
-    if (!exists) {
-      throw new CorruptArtifactError(hash, 'artifact file vanished before restore')
-    }
+    // 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
+    // on a shared `--cache-dir`) — `ArtifactVanishedError`, which the caller
+    // turns into a miss: the task runs.
+    //
+    // The FAILING is held twice: the decode below reaches the missing file
+    // and throws `CorruptArtifactError` from the extract catch either way.
+    // What the `ENOENT` mapping in that catch carries alone is the CLASS,
+    // and the two ask for opposite answers — a prune raced this run (run
+    // the task) versus the cache holds bad bytes (fail, and say so). The
+    // roundtrip row asserts the class (item 481); a row that only asserts
+    // "the restore fails" passes with the mapping deleted. It was a
+    // separate `exists()` probe until item 627: one thread-pool round trip
+    // per restore, spent to learn what the read reports itself.
     const endRows = span('restore: rows')
     // The index says exactly which files this entry materializes. If the
     // archive cannot produce one of them, restoring "successfully" leaves a
@@ -909,14 +1056,25 @@ export class Cache implements CacheLayer {
       // 0.62 ms sequential, 2026-09-10) and 30% slower in the run, where
       // four workers overlap their round trips and a blocking one stalls
       // the other three (1,000-project restore row 1.1–1.2 s → 1.5 s).
-      const tar = await decodedTar(Bun.file(src), hash)
+      const tar = await decodedTar(Bun.file(src), hash, this.artifactCeiling)
       await extractArtifactStream(tar, projectDir, workspaceRoot, verify)
     } catch (err) {
-      if (err instanceof ArchiveSecurityError || err instanceof CorruptArtifactError) throw err
+      // A UserError here is the extractor naming the tree's fault (an
+      // output directory that links out of the project).
+      if (
+        err instanceof ArchiveSecurityError ||
+        err instanceof CorruptArtifactError ||
+        err instanceof UserError
+      ) {
+        throw err
+      }
       // What is on disk, not what is in the archive: a directory standing
       // where the entry holds a file, or a file where it needs a directory.
       // The clean removes everything the output globs cover, so this is a
-      // stray they do not — name it as such, not as a corrupt artifact.
+      // stray they do not — name it as such, not as a corrupt artifact. A
+      // link on the way never lands here: the extractor writes through one
+      // that stays in the project, dangling or not, and names one that
+      // leaves it or loops (item 748).
       const code = (err as NodeJS.ErrnoException).code
       if (code === 'EISDIR' || code === 'ENOTDIR' || code === 'EEXIST' || code === 'ENOTEMPTY') {
         throw new UserError(
@@ -924,12 +1082,65 @@ export class Cache implements CacheLayer {
             `Declared outputs are wiped before a restore, so this is a path the output globs do not cover — remove it and re-run.`,
         )
       }
+      // A legal name under a destination deep enough that the two together
+      // pass PATH_MAX: the artifact is fine, the workspace's location is
+      // not (the parity audit's last open archive row, item 670).
+      if (code === 'ENAMETOOLONG') {
+        throw new UserError(
+          `restore of ${hash} into ${projectDir} could not write its outputs (${code}: ${(err as Error).message}). ` +
+            `An output path under this directory is longer than the file system allows — move the workspace to a shorter path.`,
+        )
+      }
+      // Same distinction for a tree the process cannot write into — a
+      // `dist/` another user owns, a read-only checkout, a full disk: the
+      // artifact is intact, the tree is not the process's to change.
+      if (isFsRefusal(err)) {
+        const remedy = isDiskFull(err)
+          ? 'Free space on that disk and re-run.'
+          : 'Make the declared output paths writable by this user, or stop declaring them as outputs.'
+        throw new UserError(
+          `restore of ${hash} into ${projectDir} could not write its outputs (${code}: ${err.message}). ${remedy}`,
+        )
+      }
+      // The artifact itself is gone: the read names its path (`bytes()`
+      // opens it; a staged file's ENOENT names the temp below).
+      if (code === 'ENOENT' && (err as NodeJS.ErrnoException).path === src) {
+        throw new ArtifactVanishedError(hash)
+      }
+      // A staged file the restore itself just wrote is gone before its
+      // commit: another process cleaned the same outputs under us (two runs
+      // on one workspace, a `vx watch` beside a `vx run` — a clean landing
+      // 4–32 ms into a 2,000-file restore reproduces it, 2026-09-16). The
+      // artifact is intact; the tree was not ours alone.
+      if (code === 'ENOENT' && (err as Error).message.includes('.vx-tmp-')) {
+        throw new UserError(
+          `restore of ${hash} into ${projectDir} was interrupted: a file it had just written vanished (${(err as Error).message}). ` +
+            `Another vx run is using this workspace — re-run once it is done.`,
+        )
+      }
       throw new CorruptArtifactError(hash, 'artifact is not a readable archive', err)
     } finally {
       endExtract()
     }
   }
 
+  /**
+   * A run writes here on every path — the run record at its end, an
+   * entry's `accessed_at` on a hit, the artifact on a miss — so a cache
+   * directory this user cannot write into fails the run before the graph
+   * starts, once, with the directory named, rather than every task at
+   * 0 ms (or the run at its very end) with SQLite's "attempt to write a
+   * readonly database" as an internal error. The readers open the same
+   * directory read-only and go on; a run refuses.
+   */
+  assertWritable(): void {
+    if (this.writeBlocked === null) return
+    throw new UserError(
+      `cache directory ${this.cacheDir} is not writable (${this.writeBlocked}) — every run records its ` +
+        `history there; make it writable by this user, or pass --cache-dir <path>`,
+    )
+  }
+
   async save(args: {
     hash: string
     /** See `CacheLayer.save` — `exitCode` is not a caller's to supply. */
@@ -961,7 +1172,10 @@ export class Cache implements CacheLayer {
     // the bytes, since there's no local artifact to read off disk.
     if (!this.write) return
     if (args.skipLocalWrite === true) return
-    await mkdir(this.cacheDir, { recursive: true })
+    // The cache directory is the constructor's (`mkdirSync`, with a
+    // refusal recorded for `assertWritable`); re-creating it here and
+    // again in `writeArtifactAndIndex` cost every save two thread-pool
+    // round trips for an EEXIST and a stat (item 630).
     const endPack = span('save: pack')
     const compressed = await this.packArtifactToTemp(this.tempPath(args.hash), args)
     endPack()
@@ -991,20 +1205,26 @@ export class Cache implements CacheLayer {
     return this.packArtifact(args)
   }
 
-  async ingest(hash: string, compressed: Uint8Array, meta: IngestMeta): Promise<void> {
-    await this.writeArtifactAndIndex(hash, compressed, meta)
-  }
-
   /**
-   * Collect stdout + outputs into artifact bytes, zstd-compress, return
-   * them. No disk write to the final cache path — that's the index
-   * step's job. Pure transform, so `ingest()` can skip this and hand
-   * its remote-supplied bytes straight to `writeArtifactAndIndex`.
-   *
-   * Entries are named directly into the archive, so there is no staging
-   * copy of every output byte and no `tar` subprocess (see
-   * `archive.ts`).
+   * The remote body goes to the temp by `Bun.write`, which streams a
+   * `Response` and copies a file `Blob` without collecting either, so a
+   * pull never holds the artifact. A body that fails mid-stream (a dropped
+   * socket) leaves a partial temp behind it, removed here; validation
+   * removes its own.
    */
+  async ingest(hash: string, body: Blob | Response, meta: IngestMeta): Promise<void> {
+    const tmpPath = this.tempPath(hash)
+    try {
+      // Split only for the typings: Bun.write's Response and Blob overloads
+      // do not accept their union.
+      await (body instanceof Response ? Bun.write(tmpPath, body) : Bun.write(tmpPath, body))
+    } catch (err) {
+      await unlink(tmpPath).catch(() => undefined)
+      throw err
+    }
+    await this.writeArtifactAndIndex(hash, { tmpPath }, meta)
+  }
+
   /** Archive name → absolute source path for every declared output. */
   private outputsOf(args: {
     projectDir: string
@@ -1027,9 +1247,17 @@ export class Cache implements CacheLayer {
   /**
    * The compressed artifact, in memory: the remote upload when local
    * writes are off. A large artifact is packed and compressed as a
-   * stream and collected — the seam takes bytes.
+   * stream and collected — with no local artifact the bytes must be
+   * captured while the outputs are still on disk.
+   *
+   * Both packers name entries directly into the archive — no staging
+   * copy of the outputs, no `tar` subprocess (`archive.ts`) — and
+   * neither writes the final cache path, which is the index step's job:
+   * `ingest()` packs nothing and hands its remote-supplied temp straight
+   * to `writeArtifactAndIndex`.
    */
   private async packArtifact(args: {
+    hash: string
     entry: Omit<CacheEntry, 'hash' | 'storedAt' | 'outputFiles' | 'exitCode'>
     projectDir: string
     outputFiles: string[]
@@ -1039,14 +1267,33 @@ export class Cache implements CacheLayer {
     // stdout is ALWAYS present in the artifact, even if empty, so the
     // layout is predictable: a successful read finds `stdout` and
     // zero-or-more `outputs/<rel>` / `workspace-outputs/<rel>` entries.
+    const plan = await this.planWithin(args)
+    if (plan.size <= STREAM_DECODE_FROM)
+      return await Bun.zstdCompress(await packArtifactBytes(plan))
+    return bytesOf(packArtifactStream(plan).pipeThrough(zstdEncoder()))
+  }
+
+  /**
+   * The artifact's plan, refused when its tar — exactly the bytes a restore
+   * decodes — is past the ceiling every restore enforces. Refused here, it
+   * costs a stat per output; left to the scan, it cost the whole compress
+   * and a decode of a 2.2 GB output (6 to 14 s) to learn the same thing
+   * and call the task's own outputs a "corrupt artifact".
+   */
+  private async planWithin(args: Parameters<Cache['packArtifact']>[0]): Promise<ArtifactPlan> {
     const plan = await planArtifact({
+      key: args.hash,
       stdout: args.entry.stdout ?? '',
       outputs: this.outputsOf(args),
       exec: usageOfEntry(args.entry),
     })
-    if (plan.size <= STREAM_DECODE_FROM)
-      return await Bun.zstdCompress(await packArtifactBytes(plan))
-    return bytesOf(packArtifactStream(plan).pipeThrough(zstdEncoder()))
+    if (plan.size > this.artifactCeiling) {
+      throw new Error(
+        `${args.entry.taskId} is not cached: its outputs pack to ${formatBytes(plan.size)}, past the ` +
+          `${formatBytes(this.artifactCeiling)} artifact ceiling a restore enforces — narrow cache.outputs.files`,
+      )
+    }
+    return plan
   }
 
   /**
@@ -1062,11 +1309,7 @@ export class Cache implements CacheLayer {
     tmpPath: string,
     args: Parameters<Cache['packArtifact']>[0],
   ): Promise<Uint8Array | { tmpPath: string }> {
-    const plan = await planArtifact({
-      stdout: args.entry.stdout ?? '',
-      outputs: this.outputsOf(args),
-      exec: usageOfEntry(args.entry),
-    })
+    const plan = await this.planWithin(args)
     if (plan.size <= STREAM_DECODE_FROM)
       return await Bun.zstdCompress(await packArtifactBytes(plan))
     const sink = Bun.file(tmpPath).writer()
@@ -1085,13 +1328,6 @@ export class Cache implements CacheLayer {
     return { tmpPath }
   }
 
-  /**
-   * Atomically write `compressed` to `<hash>.tar.zst` and (re)build the
-   * entries + output_files SQL rows from the archive itself. Shared by
-   * `save()` (we just packed the bytes) and `ingest()` (we got them from
-   * the remote layer) — both index the identical values, because both
-   * read them out of the artifact.
-   */
   /** tmp suffix mixes pid + hrtime + a random hex chunk so two saves of
    *  the same hash from the same process (or from two forked workers that
    *  happen to share a wall-clock ms) don't pick the same tmp filename and
@@ -1100,13 +1336,20 @@ export class Cache implements CacheLayer {
     return `${this.tarPath(hash)}.tmp-${process.pid}-${process.hrtime.bigint()}-${Math.random().toString(36).slice(2, 10)}`
   }
 
+  /**
+   * Atomically write `compressed` to `<hash>.tar.zst` and (re)build the
+   * entries + output_files SQL rows from the archive itself. Shared by
+   * `save()` (we just packed the bytes) and `ingest()` (it streamed them
+   * from the remote layer into a temp) — both index the identical values, because both
+   * read them out of the artifact.
+   */
   private async writeArtifactAndIndex(
     hash: string,
     compressed: Uint8Array | { tmpPath: string },
     meta: IngestMeta,
   ): Promise<void> {
     // Validate BEFORE anything touches the final path. `ingest()` feeds
-    // us network bytes; a truncated/garbage body that went live first
+    // us a temp of network bytes; a truncated/garbage body that went live first
     // would leave a corrupt `<hash>.tar.zst` behind (with no SQL row,
     // since the decompress throw aborted indexing) for every later
     // reader to trip over. Decompress + parse also produce the
@@ -1117,7 +1360,6 @@ export class Cache implements CacheLayer {
     let tmpPath: string
     if (compressed instanceof Uint8Array) {
       tmpPath = this.tempPath(hash)
-      await mkdir(this.cacheDir, { recursive: true })
       // The temp is written BEFORE validation so a large artifact can be
       // scanned from the file as it decodes — a file stream reads in
       // bounded pieces; the bytes in memory would not (see `decodedTar`).
@@ -1128,12 +1370,12 @@ export class Cache implements CacheLayer {
       await writeFile(tmpPath, compressed)
       endWrite()
     } else {
-      // `save` already streamed the artifact into its temp.
+      // `save` or `ingest` already streamed the artifact into its temp.
       tmpPath = compressed.tmpPath
     }
     let scanned: Awaited<ReturnType<typeof scanArtifact>>
     try {
-      // ingest() is the UNTRUSTED boundary — `compressed` is bytes just
+      // ingest() is the UNTRUSTED boundary — its temp holds bytes just
       // pulled from a remote. Refuse a bomb (declared or sizeless) before it
       // can expand into memory.
       const source =
@@ -1141,13 +1383,22 @@ export class Cache implements CacheLayer {
           ? compressed
           : Bun.file(tmpPath)
       const endScan = span('save: scan')
-      scanned = await scanArtifact(await decodedTar(source, hash))
+      scanned = await scanArtifact(await decodedTar(source, hash, this.artifactCeiling))
       endScan()
       // v17 invariant: every artifact carries a `stdout` entry. Its
       // absence means the bytes decompressed but aren't a vx artifact.
       if (scanned.stdout === null) {
         throw new CorruptArtifactError(hash, 'missing stdout entry')
       }
+      if (scanned.key !== hash) {
+        throw new CorruptArtifactError(
+          hash,
+          scanned.key === undefined
+            ? 'artifact records no cache key'
+            : `artifact was stored under another key (${scanned.key})`,
+        )
+      }
+      assertArtifactNames(hash, scanned.entries, meta.outputs)
     } catch (err) {
       await unlink(tmpPath).catch(() => undefined)
       if (err instanceof ArchiveSecurityError || err instanceof CorruptArtifactError) throw err
@@ -1280,6 +1531,7 @@ export class Cache implements CacheLayer {
   }
   stats(opts: CacheStatsOptions = {}): CacheStats {
     this.flushAccessed()
+    this.outputs.flushOutputDirs()
     const project = opts.project
     const scoped = project !== undefined
     const scopeParams: string[] = project === undefined ? [] : [project]
@@ -1306,8 +1558,57 @@ export class Cache implements CacheLayer {
     }
   }
 
+  /**
+   * The workspace's `cacheRetention`, applied at the end of a run: `prune()`
+   * with the same policy, but only when it would evict something, else the
+   * orphan sweep alone when an hour has passed since the last one. A run
+   * with nothing due pays the accessed-at flush it owed at close anyway, one
+   * scan of the index and one read of the sweep's clock — never the
+   * sweep's readdir. Null when nothing was due or this handle does not write.
+   */
+  async evictIfDue(
+    policy: { maxAgeMs?: number; maxBytes?: number },
+    now: number = Date.now(),
+  ): Promise<PruneResult | null> {
+    if (!this.write) return null
+    // First: an entry this run restored still carries its old `accessed_at`
+    // until the deferred bump lands, and would read as due for eviction.
+    this.flushAccessed()
+    const olderThanMs = policy.maxAgeMs === undefined ? undefined : now - policy.maxAgeMs
+    const { oldest, bytes } = this.db
+      .prepare(
+        'SELECT MIN(accessed_at) AS oldest, COALESCE(SUM(size_bytes), 0) AS bytes FROM entries',
+      )
+      .get() as { oldest: number | null; bytes: number }
+    const ageDue = olderThanMs !== undefined && oldest !== null && oldest < olderThanMs
+    const sizeDue = policy.maxBytes !== undefined && bytes > policy.maxBytes
+    if (ageDue || sizeDue) {
+      return this.prune({
+        ...(olderThanMs !== undefined ? { olderThanMs } : {}),
+        ...(policy.maxBytes !== undefined ? { maxBytes: policy.maxBytes } : {}),
+      })
+    }
+    // Row-less artifacts are bytes the index cannot count, so the policy
+    // above never sees them (upstream survey, nx#35483: 9 MiB of them sat
+    // under a 1 MB limit). Listing the directory to find them costs 0.5 ms
+    // per 1,000 entries (4.9 ms at 10,000), every run; the sweep's own
+    // clock in `schema_meta` costs one indexed read. An orphan is reapable
+    // only an hour after its last write anyway, so an hourly sweep reaps
+    // it within two.
+    const swept = this.db.prepare('SELECT value FROM schema_meta WHERE key = ?').get(SWEPT_AT) as {
+      value: string
+    } | null
+    if (swept !== null && now - Number(swept.value) < ORPHAN_GRACE_MS) return null
+    return { evicted: 0, bytesFreed: 0, ...(await this.reapOrphans(now)) }
+  }
+
   async prune(options: PruneOptions): Promise<PruneResult> {
     this.flushAccessed()
+    // Before any entry is deleted, so a kept entry's pending snapshot is on
+    // disk whatever the eviction does next. A pruned hash's snapshot cannot
+    // orphan rows in either order: landed first, the cascade takes them;
+    // landed after, the flush's own entry check drops them (item 628).
+    this.outputs.flushOutputDirs()
     const { olderThanMs, maxBytes, dryRun = false } = options
     if (olderThanMs === undefined && maxBytes === undefined) {
       throw new Error('prune: pass at least one of `olderThanMs` or `maxBytes`')
@@ -1315,12 +1616,18 @@ export class Cache implements CacheLayer {
 
     const victims = new Set<string>()
     let bytesFreed = 0
+    // Rows whose artifact is gone (deleted by hand, or by a disk cleaner):
+    // never a hit, and their bytes are on no disk, but `--max-size` counted
+    // them and evicted real entries to make room for them (item 975). They
+    // are dropped, neither evicted nor freed.
+    const phantoms = await this.phantomRows()
 
     if (olderThanMs !== undefined) {
       const rows = this.db
         .prepare('SELECT hash, size_bytes FROM entries WHERE accessed_at < ?')
         .all(olderThanMs) as Array<{ hash: string; size_bytes: number }>
       for (const r of rows) {
+        if (phantoms.has(r.hash)) continue
         victims.add(r.hash)
         bytesFreed += r.size_bytes
       }
@@ -1330,7 +1637,9 @@ export class Cache implements CacheLayer {
       const totalRow = this.db
         .prepare('SELECT COALESCE(SUM(size_bytes), 0) AS bytes FROM entries')
         .get() as { bytes: number }
-      let remaining = totalRow.bytes - bytesFreed
+      let phantomBytes = 0
+      for (const b of phantoms.values()) phantomBytes += b
+      let remaining = totalRow.bytes - phantomBytes - bytesFreed
       if (remaining > maxBytes) {
         // Exclude already-picked victims in JS, not via a SQL NOT-IN —
         // an IN-list over tens of thousands of TTL victims would blow
@@ -1339,7 +1648,7 @@ export class Cache implements CacheLayer {
           this.db
             .prepare('SELECT hash, size_bytes FROM entries ORDER BY accessed_at ASC')
             .all() as Array<{ hash: string; size_bytes: number }>
-        ).filter((row) => !victims.has(row.hash))
+        ).filter((row) => !victims.has(row.hash) && !phantoms.has(row.hash))
         for (const row of candidates) {
           if (remaining <= maxBytes) break
           victims.add(row.hash)
@@ -1364,11 +1673,12 @@ export class Cache implements CacheLayer {
         orphanBytes: orphans.orphanBytes,
       }
     }
-    if (victims.size > 0) {
+    if (victims.size > 0 || phantoms.size > 0) {
       const hashes = [...victims]
+      const rows = [...hashes, ...phantoms.keys()]
       this.db.transaction(() => {
-        for (let i = 0; i < hashes.length; i += 900) {
-          const chunk = hashes.slice(i, i + 900)
+        for (let i = 0; i < rows.length; i += 900) {
+          const chunk = rows.slice(i, i + 900)
           this.db
             .prepare(`DELETE FROM entries WHERE hash IN (${chunk.map(() => '?').join(',')})`)
             .run(...(chunk as readonly SQLQueryBindings[]))
@@ -1392,7 +1702,12 @@ export class Cache implements CacheLayer {
    * exists while the bytes are still being written, so a fresh file
    * without a row is a save in flight, not an orphan.
    */
-  private async reapOrphans(): Promise<{ orphans: number; orphanBytes: number }> {
+  private async reapOrphans(
+    now: number = Date.now(),
+  ): Promise<{ orphans: number; orphanBytes: number }> {
+    this.db
+      .prepare('INSERT OR REPLACE INTO schema_meta(key, value) VALUES (?, ?)')
+      .run(SWEPT_AT, String(now))
     let orphans = 0
     let orphanBytes = 0
     await Promise.all(
@@ -1411,6 +1726,29 @@ export class Cache implements CacheLayer {
     return { orphans, orphanBytes }
   }
 
+  /**
+   * Index rows whose artifact is not in the directory, with their recorded
+   * sizes. Only rows last written or used before the grace window: a save
+   * renames its artifact in before its row commits, so a fresh row without
+   * one is a listing that raced a save, not a phantom. An unreadable
+   * directory judges nothing.
+   */
+  private async phantomRows(): Promise<Map<string, number>> {
+    let names: string[]
+    try {
+      names = await readdir(this.cacheDir)
+    } catch {
+      return new Map()
+    }
+    const present = new Set(names)
+    const rows = this.db
+      .prepare('SELECT hash, size_bytes FROM entries WHERE accessed_at < ?')
+      .all(Date.now() - ORPHAN_GRACE_MS) as Array<{ hash: string; size_bytes: number }>
+    const out = new Map<string, number>()
+    for (const r of rows) if (!present.has(`${r.hash}.tar.zst`)) out.set(r.hash, r.size_bytes)
+    return out
+  }
+
   /** What `prune()` would reap right now, for `vx info` to say before anyone prunes. */
   async orphanStats(): Promise<{ orphans: number; orphanBytes: number }> {
     const found = await this.scanOrphans()
@@ -1435,11 +1773,9 @@ export class Cache implements CacheLayer {
     const cutoff = Date.now() - ORPHAN_GRACE_MS
     const candidates: string[] = []
     for (const name of names) {
-      if (name.indexOf('.tar.zst.tmp-') > 0) {
-        candidates.push(name)
-      } else if (name.endsWith('.tar.zst') && !indexed.has(name.slice(0, -'.tar.zst'.length))) {
-        candidates.push(name)
-      }
+      const m = VX_ARTIFACT_NAME.exec(name)
+      if (m === null) continue
+      if (m[2] !== undefined || !indexed.has(m[1]!)) candidates.push(name)
     }
     const found: Array<{ file: string; size: number }> = []
     await Promise.all(
@@ -1466,15 +1802,21 @@ export class Cache implements CacheLayer {
     // 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
+    // --dry-run` pruned it (item 1004).
     try {
-      const cutoff = Date.now() - 30 * 24 * 60 * 60 * 1000
-      this.history.pruneOlderThan(cutoff)
-      this.configEvals.pruneOlderThan(cutoff)
+      if (!this.inspecting) {
+        const cutoff = Date.now() - 30 * 24 * 60 * 60 * 1000
+        this.history.pruneOlderThan(cutoff)
+        this.configEvals.pruneOlderThan(cutoff)
+      }
     } catch {
       // Retention is best-effort; never block closing the handle.
     }
     try {
       this.flushAccessed()
+      this.outputs.flushOutputDirs()
     } catch {
       // Same contract as the retention prune above, which was already
       // guarded while this sibling was not: `accessed_at` is LRU
@@ -1493,8 +1835,45 @@ export class Cache implements CacheLayer {
   }
 }
 
-function splitTaskId(id: string): [string, string] {
-  const i = id.indexOf('#')
-  if (i < 0) return [id, '']
-  return [id.slice(0, i), id.slice(i + 1)]
+/**
+ * Refuse an artifact whose file names no restore can materialise as one
+ * tree, or (given the task's declared outputs) that names a file outside
+ * them. Both reached the tree before: `outputs/out.txt` beside
+ * `outputs/out.txt/x` failed every later run from the local copy, blaming
+ * what was on disk, and an undeclared name overwrote an input or planted a
+ * git hook under a green remote hit (item 942). Thrown at ingest, so the
+ * bytes never reach the local store and the remote read is a miss.
+ */
+function assertArtifactNames(
+  hash: string,
+  entries: ReadonlyArray<{ name: string }>,
+  declared: DeclaredOutputs | undefined,
+): void {
+  const names = new Set(entries.map((e) => e.name))
+  for (const name of names) {
+    for (let sep = name.indexOf('/'); sep !== -1; sep = name.indexOf('/', sep + 1)) {
+      if (names.has(name.slice(0, sep))) {
+        throw new CorruptArtifactError(
+          hash,
+          `artifact holds ${name.slice(0, sep)} as a file and as a directory`,
+        )
+      }
+    }
+  }
+  if (declared === undefined) return
+  const files = asTrees(declared.files).map(taskGlob)
+  const wsFiles = asTrees(declared.workspaceFiles).map(taskGlob)
+  for (const name of names) {
+    const ok = name.startsWith('outputs/')
+      ? files.some((g) => g.match(name.slice('outputs/'.length)))
+      : name.startsWith(WORKSPACE_OUTPUT_PREFIX)
+        ? wsFiles.some((g) => g.match(name.slice(WORKSPACE_OUTPUT_PREFIX.length)))
+        : true
+    if (!ok) {
+      throw new CorruptArtifactError(
+        hash,
+        `artifact carries ${name}, which is not one of the task's declared outputs`,
+      )
+    }
+  }
 }