@vzn/vx 0.0.18 → 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
@@ -20,89 +20,117 @@
 // for the user to see — but on a cache hit there's nothing to replay
 // (the original run was successful and stderr typically empty).
 //
-// Replace this module to plug in remote storage. The contract is:
-//   key()           : derive a stable hash from a task's identity + inputs
-//   get(hash, ctx?) : retrieve a previous run's metadata, or null
-//   restoreOutputs  : extract the artifact's outputs/ into the project dir
-//   save            : persist outputs + stdout under a hash
-//   ingest          : adopt an artifact produced elsewhere (remote-hit path)
-//   recordRun       : append a row to the run history table (for stats)
-//   close           : release the SQLite handle
+// This is core's FLOOR, not a module to replace: remote storage is a
+// `RemoteCacheLayer` (has / get / put) that `LayeredCache` wraps around
+// this handle, declared by a plugin's `cache` hook. The contract every
+// layer speaks is `CacheLayer` in layer.ts; `plugin-host.ts` enforces it.
 
 import { Database, type SQLQueryBindings } from 'bun:sqlite'
-import { existsSync, mkdirSync, statSync, writeFileSync } from 'node:fs'
-import { lstat, 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,
   packArtifactBytes,
   packArtifactStream,
   planArtifact,
 } from './archive.js'
-import { FsCASBackend } from './cas-backend.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.
-const CACHE_VERSION = 'vx-cache-v27'
+import {
+  ArtifactVanishedError,
+  type CacheEntry,
+  type CacheGetContext,
+  type CacheKeyInput,
+  type CacheLayer,
+  type CacheStats,
+  type CacheStatsOptions,
+  CorruptArtifactError,
+  type DeclaredOutputs,
+  type IngestMeta,
+  type InvocationRecord,
+  type OutputDirRow,
+  type OutputFileRow,
+  type PruneOptions,
+  type PruneResult,
+  type RunRecord,
+  type SaveArgs,
+  type TaskInputRow,
+  WORKSPACE_OUTPUT_PREFIX,
+} from './layer.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'
+import { CACHE_VERSION, foldKey } from './key-fold.js'
+
+/**
+ * An artifact or temp file without an `entries` row is reaped by
+ * `prune()` only once it is this old. A save renames the artifact into
+ * place and commits its row in the same tick; a crashed save's temp is
+ * stale long before this. Generous on purpose — a false orphan costs a
+ * re-run, a leaked temp costs disk.
+ */
+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(
+    `[vx] cache index reset: schema ${from} → ${to} (vx upgraded); every cached task misses once and re-saves, and \`vx cache prune\` reclaims the old artifacts`,
+  )
+}
 // SCHEMA history (drop+recreate on mismatch; pre-alpha, no migrations):
 //   v20: file_hashes.content_hash (git blob OIDs).
 //   v21: dropped the unused outputs_hash column (pure-input hashing).
@@ -133,7 +161,32 @@ const CACHE_VERSION = 'vx-cache-v27'
 //        the memo simply stops answering wrongly, so an affected task's
 //        key moves from a WRONG value to the right one: it misses once,
 //        re-runs, re-caches. Self-healing, never a wrong hit.
-const SCHEMA_VERSION = 'v24'
+//   v25: runs.cached — whether the task declared a `cache` block. An
+//        uncached task's row looked like any executed miss, so `vx why`
+//        headlined "cache key changed (inputs differ)" for a task that
+//        runs every time by design, and `vx last` could not mark it the
+//        way the terminal summary does (`no-cache`). Analytics-only —
+//        the cache KEY is unchanged.
+//   v26: entries.cpu_ms / peak_rss_bytes — what the producing execution
+//        used, read out of the artifact's sidecar at save and ingest
+//        alike, so a hit (a remote one on a fresh runner above all) can
+//        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).
+//   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.
@@ -160,840 +213,139 @@ 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/'
-
-/**
- * Independent read/write control over the two cache layers (local +
- * remote). Replaces the old single `noCache` boolean: each axis can be
- * toggled on its own so `--force` (re-execute but still refresh the
- * cache) is distinct from `--no-cache` (disable everything).
- *
- * Only the task-artifact get/save path is gated. `recordRun`, `stats`,
- * `prune`, key derivation, and prefetch-ingest are never affected — they
- * are bookkeeping/analytics that a run policy has no business disabling.
- */
-export interface CachePolicy {
-  localRead: boolean
-  localWrite: boolean
-  remoteRead: boolean
-  remoteWrite: boolean
-}
-
-/** All four axes on — the default when no cache flag is passed. */
-export const FULL_CACHE_POLICY: CachePolicy = {
-  localRead: true,
-  localWrite: true,
-  remoteRead: true,
-  remoteWrite: true,
-}
+// 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.
+export * from './layer.js'
+export * from './policy.js'
+export { zstdContentSize } from './zstd.js'
 
-/**
- * Parse a `--cache=<spec>` value into a `CachePolicy`, starting from a
- * base (defaults to {@link FULL_CACHE_POLICY}). The spec is a
- * comma-separated list of `layer:flags` segments where `layer` is
- * `local` or `remote` and `flags` is any subset of `r` (read) and `w`
- * (write), order-independent and possibly empty.
- *
- * A mentioned layer is set EXACTLY to its flags (read = includes `r`,
- * write = includes `w`); an unmentioned layer keeps its base value.
- * So `local:rw,remote:r` = remote read-only, `remote:` = remote fully
- * off, `local:r` = local read-only with remote untouched.
- *
- * Throws a {@link UserError} on an unknown layer, an unknown flag, a
- * duplicated flag, a missing colon, or a repeated layer.
- */
-export function parseCachePolicy(spec: string, base: CachePolicy = FULL_CACHE_POLICY): CachePolicy {
-  const out: CachePolicy = { ...base }
-  const seen = new Set<string>()
-  for (const rawSeg of spec.split(',')) {
-    const seg = rawSeg.trim()
-    if (seg.length === 0) continue
-    const colon = seg.indexOf(':')
-    if (colon < 0) {
-      throw new UserError(`invalid --cache segment '${seg}': expected '<layer>:<flags>'`)
-    }
-    const layer = seg.slice(0, colon)
-    const flags = seg.slice(colon + 1)
-    if (layer !== 'local' && layer !== 'remote') {
-      throw new UserError(`invalid --cache layer '${layer}': expected 'local' or 'remote'`)
-    }
-    if (seen.has(layer)) {
-      throw new UserError(`--cache layer '${layer}' specified twice`)
-    }
-    seen.add(layer)
-    const flagSet = new Set<string>()
-    for (const ch of flags) {
-      if (ch !== 'r' && ch !== 'w') {
-        throw new UserError(`invalid --cache flag '${ch}' for '${layer}': expected 'r' and/or 'w'`)
-      }
-      if (flagSet.has(ch)) {
-        throw new UserError(`--cache flag '${ch}' repeated for '${layer}'`)
-      }
-      flagSet.add(ch)
-    }
-    if (layer === 'local') {
-      out.localRead = flagSet.has('r')
-      out.localWrite = flagSet.has('w')
-    } else {
-      out.remoteRead = flagSet.has('r')
-      out.remoteWrite = flagSet.has('w')
-    }
-  }
-  return out
-}
-
-export interface CacheKeyInput {
-  taskId: string
-  /**
-   * Hash of the resolved task config (post-evaluation). Folds in everything
-   * the user wrote — command, env declarations (passThrough names + define
-   * key/value pairs), dependsOn, cache.inputs declarations, outputs — including
-   * values that arrived via `import` at config-load time.
-   */
-  taskConfigHash: string
-  /**
-   * Runtime values of declared cache-input env names (from parent at hash
-   * time). Independent of `exec.env`; lives here for cache identity.
-   */
-  envValues: Array<[name: string, value: string]>
-  /**
-   * Resolved `cache.inputs.runtime` commands as [command, output] pairs
-   * (output = trimmed stdout+stderr, resolved live at hash time). Folded
-   * into the key in a namespace distinct from workspaceRuntimeValues.
-   */
-  runtimeValues?: Array<[command: string, output: string]>
-  /** Resolved `cache.inputs.workspaceRuntime` pairs (root-cwd commands). */
-  workspaceRuntimeValues?: Array<[command: string, output: string]>
-  /** Absolute paths to input files. */
-  inputFiles: string[]
-  workspaceRoot: string
-  /** Cache keys of upstream tasks this one depends on, sorted. */
-  upstreamHashes: string[]
-  /**
-   * Upstream hash → upstream task id, for `captureInto` row NAMING only.
-   * Never folded into the digest — the key already folds the sorted
-   * hashes. Lets the persisted `entry_inputs` row name which upstream
-   * task a hash came from (the diff reads better than a bare hash). When
-   * absent, the captured `upstream` row falls back to `name = hash`.
-   */
-  upstreamIds?: ReadonlyMap<string, string>
-  /**
-   * The task's DEPENDENCY closure with GROUP tasks expanded into the real
-   * tasks they stand for — what an input-shipping executor must place in the
-   * input root. A different question from what the key folds, and derived
-   * differently in both directions:
-   *
-   * - It expands groups, which contribute a synthetic roll-up hash and no
-   *   outputs of their own, so a dependent of one would otherwise describe
-   *   an empty closure.
-   * - It ignores `cache.inputs.tasks`. That filter says which upstream KEYS
-   *   this task's key folds; what the task may READ is `dependsOn`, and
-   *   locally every dependency's outputs are on disk before the command runs
-   *   however the filter is written.
-   *
-   * NEVER folded into the digest — the key cascades through a group's own
-   * roll-up hash already, and folding either difference in would move every
-   * existing dependent's key without telling it anything new.
-   */
-  upstreamGraft?: ReadonlyArray<{
-    readonly taskId: string
-    readonly hash: string
-    readonly projectDir: string
-  }>
-  /**
-   * Workspace-level fingerprint — typically a hash of `pnpm-lock.yaml` +
-   * `pnpm-workspace.yaml`. Folds resolved dep versions and workspace shape
-   * into every task's key, so a lockfile bump invalidates everything.
-   */
-  workspaceFingerprint: string
-  /**
-   * CLI args forwarded to the task (after `--`). Folded into the key so that
-   * the same command with different forwarded args is treated as a distinct
-   * run, never a spurious cache hit.
-   */
-  forwardArgs?: readonly string[]
-  /**
-   * Hash of the project's `package.json` bytes. Folded into the key
-   * implicitly (Turbo / Nx parity) so dep changes invalidate every
-   * task in that project, even when `cache.inputs.files` doesn't
-   * cover package.json. Empty string when the project has no
-   * package.json (impossible in practice — workspace discovery
-   * requires one — but we don't fail-loud here).
-   */
-  projectPackageJsonHash: string
-  /**
-   * Precomputed content hashes (git blob OIDs) keyed by absolute
-   * path — typically the trusted-index OID map harvested by the
-   * run's bulk `git ls-files -s`. Paths present here skip `hashFile`
-   * entirely (no stat, no SQLite, no read); missing paths fall back
-   * to `hashFile`, which computes the byte-identical blob OID from
-   * disk. Pure fast path: the derived key never depends on whether a
-   * hash arrived via the map or the fallback.
-   */
-  fileHashes?: ReadonlyMap<string, string>
-  /**
-   * Material a plugin's `key` stage contributed, as sorted `[name, value]`
-   * pairs. Folded only when non-empty, so a workspace without a key plugin
-   * derives exactly the key it always did.
-   */
-  pluginParts?: ReadonlyArray<readonly [name: string, value: string]>
-  /**
-   * When set, `key()` pushes each component (kind, name, hash) it folds
-   * — at the same fold sites, in fold order. Pure SIDE-CHANNEL: it does
-   * not change the returned digest in any way. On a cache MISS the
-   * orchestrator allocates an array, passes it here, and persists the
-   * rows to `entry_inputs` (inside the entry-save transaction) so a
-   * later run can diff its inputs against this one (the Tier-3 "why did
-   * this re-run?" moat). Capturing at the fold sites keeps the
-   * recorded set in lockstep with the key by construction: a future
-   * component that forgets to capture is a one-line miss, not silent
-   * drift. The per-file OIDs are already awaited here, so file rows cost
-   * zero extra I/O — just array pushes.
-   */
-  captureInto?: Array<{ kind: string; name: string; hash: string }>
-}
-
-export interface CacheEntry {
+interface EntryRow {
   hash: string
-  taskId: string
-  command: string
-  exitCode: number
-  durationMs: number
-  outputFiles: string[]
-  /**
-   * The `output_files` rows behind `outputFiles` (size / mode / mtime), when
-   * the layer that produced this entry had them in hand. `restoreHit` reads
-   * them for its tree-is-current check instead of re-querying — one SQL
-   * round trip per cache hit, saved.
-   */
-  outputRows?: OutputFileRow[]
-  /**
-   * The `output_dirs` rows behind the directory short-circuit, when the
-   * batched `getMany` loaded them — one query for the run instead of one
-   * per hit (0.12 ms each across a warm 1000-project run before this).
-   */
-  outputDirRows?: OutputDirRow[]
-  /** Captured stdout, always present (may be empty). stderr is not cached. */
-  stdout: string
-  storedAt: string
-  /**
-   * Where this hit was resolved from. `'local'` for a SQLite-backed
-   * Cache; `'remote'` when LayeredCache pulled the artifact from the
-   * remote layer this lookup (even though it's been materialized into
-   * local for next time). Lets the orchestrator surface
-   * `cache-hit-remote` so users see when remote caching actually saved
-   * them work vs. a stale-local replay.
-   */
-  source?: 'local' | 'remote'
-}
-
-export interface RunRecord {
-  /**
-   * The task's cache key. ABSENT when the outcome never derived one — a
-   * `skipped` task (its upstream failed, so it never probed) or a
-   * `persistent` one (a dev server is never cached). Such a row is still a
-   * task of the run and must be recorded, so the column keeps a `''`
-   * sentinel rather than going nullable: `''` is impossible for a real key
-   * (`Cache.key` returns 16 hex chars), the reads that must not treat it as
-   * a key already guard it, and it matches what the cloud `task_runs.hash`
-   * column has stored for the same concept since its first migration.
-   */
-  hash?: string
   project: string
   task: string
-  status: 'success' | 'failed' | 'cache-hit' | 'cache-hit-remote' | 'skipped'
-  exitCode: number
-  durationMs: number
-  forwardArgs?: readonly string[]
-  startedAt: number // ms-epoch wall clock
-  endedAt: number // ms-epoch wall clock
-  /**
-   * Optional analytics columns. Populated by the orchestrator/runner;
-   * stored as NULL on rows from older runs. Surfaced via `vx stats`
-   * and consumable from CI by reading cache.db directly.
-   */
-  runId?: string // ULID shared across every task in one `vx run` invocation
-  cpuMs?: number // sum of user + system CPU time for the child process
-  peakRssBytes?: number // peak resident set size of the child process
-  wallclockStartNs?: bigint // hrtime span relative to run t=0
-  wallclockEndNs?: bigint
-  cacheHit?: boolean // convenience for flamegraph color; derivable from status
-  attempts?: number // >1 when the task retried; the direct within-run flaky signal
-}
-
-/**
- * One header row per `vx run` invocation (the `invocations` table). All
- * fields mirror the columns; nullable VCS/host columns are `null` when
- * the probe failed (not a git repo, hostname unavailable). Recorded
- * once per run inside the same transaction as the per-task `runs` rows.
- */
-export interface InvocationRecord {
-  runId: string
-  command: string
-  /** JSON-serialized `string[]` of the requested task names. */
-  requestedTasks: string
-  /** Compact policy flags, e.g. `'lR,lW,rR,rW'` (an axis omitted = off). */
-  cachePolicy: string
-  concurrency: number
-  flow: 'focused' | 'broad' | null
-  startedAt: number
-  endedAt: number
-  totalDurationMs: number
-  taskCount: number
-  failedCount: number
-  hitCount: number
-  hitLocalCount: number
-  hitRemoteCount: number
-  exitOk: boolean
-  commitSha: string | null
-  branch: string | null
-  dirty: boolean | null
-  ci: boolean
-  ciProvider: string | null
-  host: string | null
-  os: string | null
-  arch: string | null
-  vxVersion: string
-  /** JSON object `{k:v}` of `--tag` pairs. */
-  tags: string
-}
-
-/**
- * One cache-key component row for the `entry_inputs` table — keyed by
- * the cache-entry HASH it belongs to, not a run. Written inside the
- * entry-save transaction (`writeArtifactAndIndex`) on a miss/save; a
- * cache HIT does not save, so it persists nothing (warm runs are free).
- * The diff (Phase B/B1) reads these by the run's task hash
- * (`runs.hash → entry_inputs[entry_hash]`).
- */
-export interface TaskInputRow {
-  entryHash: string
-  kind: string
-  name: string
-  hash: string
-}
-
-export interface CacheStats {
-  entryCount: number
-  totalBytes: number
-  runCountLast24h: number
-  hitCountLast24h: number
-}
-
-export interface CacheStatsOptions {
-  /** Narrow every aggregate to one project. Absent = the whole workspace. */
-  project?: string
-}
-
-export interface PruneOptions {
-  /** Drop entries last accessed before this ms-epoch threshold. */
-  olderThanMs?: number
-  /**
-   * After applying olderThanMs, if the cache still exceeds this size in
-   * bytes, evict LRU (smallest `accessed_at` first) until under it.
-   */
-  maxBytes?: number
-}
-
-export interface PruneResult {
-  evicted: number
-  bytesFreed: number
-}
-
-/**
- * Per-output-file fingerprint, scoped by the cache entry that
- * produced it. Batch-loaded once at the top of a run via
- * `loadOutputFilesBatch(hashes)` so the orchestrator's "is this
- * tree already current?" probe becomes an in-memory Map lookup
- * plus N parallel stat calls.
- *
- * `path` is project-relative (e.g. `dist/index.js`), matching how
- * outputs are addressed under `<projectDir>/` — except workspace
- * outputs, which carry the full `workspace-outputs/<rel-to-root>`
- * tar entry name (see `WORKSPACE_OUTPUT_PREFIX`); callers split on
- * the prefix and anchor those at the workspace root.
- */
-export interface OutputFileRow {
-  path: string
-  size: number
-  mode: number
-  mtimeMs: number
-}
-
-/** One directory under a whole-subtree output glob, as it stood after the last save or restore on THIS machine. */
-export interface OutputDirRow {
-  path: string
-  mtimeMs: number
-}
-
-/** More directories than this under a task's output prefixes: record nothing, keep the walk. */
-export const OUTPUT_DIRS_CAP = 256
-
-/**
- * A directory whose mtime lies within this many ms of the snapshot is RACY
- * and the whole snapshot is dropped. File timestamps are coarse on Linux
- * (a kernel tick, up to 10 ms), so a write landing in the same tick as the
- * one that made the directory's recorded mtime leaves the mtime unchanged
- * and the change invisible — git's index distrusts stats this young for
- * the same reason (a stray survived a hit on the ubuntu job, 2026-09-03).
- * The next hit walks, and once the tree is older than the window it is
- * recorded for good.
- */
-export const OUTPUT_DIRS_RACY_MS = 50
-
-/**
- * The shape every cache implementation honors. `Cache` (the local v10
- * implementation) and `LayeredCache` both `implements` this so the
- * orchestrator's `executeTask` can take either without a discriminated
- * union and we get a compile-time guarantee the surfaces stay congruent.
- */
-/**
- * Context passed to `get()`. Optional, but required when the lookup
- * may resolve through the remote layer — the local SQL row inserted on
- * remote-hit needs `taskId` + `command` to be queryable later (the
- * artifact itself doesn't carry them). `Cache` (local) ignores this
- * field; `LayeredCache` forwards it to `Cache.ingest`.
- */
-export interface CacheGetContext {
-  taskId: string
   command: string
+  exit_code: number
+  duration_ms: number
+  size_bytes: number
+  stdout: string
+  created_at: number
+  accessed_at: number
+  cpu_ms: number | null
+  peak_rss_bytes: number | null
 }
 
-/** Metadata supplied at ingest time — values the artifact does not carry. */
-export interface IngestMeta {
-  taskId: string
-  command: string
-  /** Wall-clock time of the original task execution. */
-  durationMs: number
-  /**
-   * Cache-key components (Tier-3 input fingerprint) to persist into
-   * `entry_inputs` in the same transaction as the entry row. Omitted on
-   * the remote-hit ingest path (the artifact doesn't carry them — the
-   * fingerprint is the saving machine's local moat). Only computed on a
-   * miss/save, so a cache hit never reaches here.
-   */
-  inputComponents?: readonly TaskInputRow[]
+function entryOf(row: EntryRow, fileRows: OutputFileRow[]): CacheEntry {
+  return {
+    hash: row.hash,
+    taskId: `${row.project}#${row.task}`,
+    command: row.command,
+    exitCode: row.exit_code,
+    durationMs: row.duration_ms,
+    ...(row.cpu_ms !== null ? { cpuMs: row.cpu_ms } : {}),
+    ...(row.peak_rss_bytes !== null ? { peakRssBytes: row.peak_rss_bytes } : {}),
+    outputFiles: fileRows.map((r) => r.path),
+    outputRows: fileRows,
+    stdout: row.stdout,
+    storedAt: new Date(row.created_at).toISOString(),
+    source: 'local',
+  }
 }
 
-/**
- * The supplied artifact bytes don't decompress/parse as a vx artifact.
- * Thrown by `save`/`ingest` BEFORE anything reaches the final cache
- * path — a rejected artifact leaves no `<hash>.tar.zst` and no SQL row.
- * The LayeredCache treats this as a remote fault on the remote-hit
- * path (degrades to a cache miss).
- */
-export class CorruptArtifactError extends Error {
-  constructor(
-    public readonly hash: string,
-    reason: string,
-    public override readonly cause?: unknown,
-  ) {
-    super(`cache: corrupt artifact for ${hash}: ${reason}`)
-    this.name = 'CorruptArtifactError'
+/** The sidecar's `exec` from a save's entry: only the axes the runner reported. */
+function usageOfEntry(entry: { cpuMs?: number; peakRssBytes?: number }): ExecUsage | undefined {
+  if (entry.cpuMs === undefined && entry.peakRssBytes === undefined) return undefined
+  return {
+    ...(entry.cpuMs !== undefined ? { cpuMs: entry.cpuMs } : {}),
+    ...(entry.peakRssBytes !== undefined ? { peakRssBytes: entry.peakRssBytes } : {}),
   }
 }
 
 /**
- * A decompressed artifact above this is refused as a zstd bomb rather than
- * expanded into memory. 2 GiB comfortably exceeds any real build output while
- * bounding a malicious/compromised remote's ability to OOM a victim who takes
- * a cache hit.
- */
-const MAX_DECOMPRESSED_ARTIFACT_BYTES = 2 * 1024 * 1024 * 1024
-
-/**
- * Read a zstd frame's declared Frame_Content_Size (RFC 8878 §3.1.1) WITHOUT
- * decompressing. Returns null when the frame omits it (streaming frames) or
- * the header is too short to parse. vx's own producer (single-shot
- * `Bun.zstdCompress` of a known buffer) always writes it, so an artifact that
- * declares an enormous size can be rejected before a byte is allocated.
+ * 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).
  *
- * Exported for tests: pins the per-`fcsFlag` byte layouts (incl. the 2-byte
- * `+256` adjustment and the `dictIdFlag` offset) that a bomb-refusal e2e can't
- * discriminate (their max declarable sizes sit below the ceiling).
+ * 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.
  */
-export function zstdContentSize(b: Uint8Array): bigint | null {
-  if (b.length < 5) return null
-  // Magic_Number 0xFD2FB528, little-endian.
-  if (b[0] !== 0x28 || b[1] !== 0xb5 || b[2] !== 0x2f || b[3] !== 0xfd) return null
-  const desc = b[4]!
-  const fcsFlag = desc >> 6
-  const singleSegment = (desc >> 5) & 1
-  const dictIdFlag = desc & 3
-  let off = 5
-  if (singleSegment === 0) off += 1 // Window_Descriptor byte
-  off += dictIdFlag === 3 ? 4 : dictIdFlag // Dictionary_ID: 0,1,2,4 bytes
-  let fcsSize: number
-  if (fcsFlag === 0) fcsSize = singleSegment === 1 ? 1 : 0
-  else if (fcsFlag === 1) fcsSize = 2
-  else if (fcsFlag === 2) fcsSize = 4
-  else fcsSize = 8
-  if (fcsSize === 0 || b.length < off + fcsSize) return null
-  let v = 0n
-  for (let i = 0; i < fcsSize; i++) v |= BigInt(b[off + i]!) << BigInt(8 * i)
-  if (fcsSize === 2) v += 256n // per spec, the 2-byte field stores value − 256
-  return v
-}
-
-/**
- * Decompress a zstd artifact that DECLARES its content size, with a hard
- * output ceiling: refused before a byte is allocated when the declaration
- * is over the cap, and again on the actual length. A frame with no
- * declaration (a streamed producer's — vx's own, above 4 MiB) never comes
- * here: `decodedTar` decodes it as a stream under the running count, so
- * a sizeless bomb has nowhere to expand.
- */
-async function zstdDecompressBounded(compressed: Uint8Array, hash: string): Promise<Uint8Array> {
-  assertDeclaredSize(compressed, hash)
-  const out = await Bun.zstdDecompress(compressed)
-  if (out.length > MAX_DECOMPRESSED_ARTIFACT_BYTES) {
-    throw new CorruptArtifactError(
-      hash,
-      `decompressed to ${out.length} bytes (> ${MAX_DECOMPRESSED_ARTIFACT_BYTES} cap)`,
-    )
+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
   }
-  return out
-}
-
-/** The pre-decompress half of the ceiling: the frame header's own claim, when it makes one. */
-function assertDeclaredSize(compressed: Uint8Array, hash: string): bigint | null {
-  const declared = zstdContentSize(compressed)
-  if (declared !== null && declared > BigInt(MAX_DECOMPRESSED_ARTIFACT_BYTES)) {
-    throw new CorruptArtifactError(
-      hash,
-      `declares ${declared} decompressed bytes (> ${MAX_DECOMPRESSED_ARTIFACT_BYTES} cap)`,
-    )
+  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 declared
+  return null
 }
 
-/** Compressed artifacts above this size are decoded as a stream, on restore and on ingest. */
-const STREAM_DECODE_FROM = 4 * 1024 * 1024
-
-/** Collect a byte stream; only ever used where the seam wants bytes. */
-async function bytesOf(stream: ReadableStream<Uint8Array>): Promise<Uint8Array> {
-  return new Uint8Array(await new Response(stream).arrayBuffer())
-}
+// 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'
 
 /**
- * Bun's `CompressionStream` types do not satisfy `pipeThrough`'s pair
- * (its readable side is typed `NonSharedUint8Array`); the runtime object
- * is a plain byte transform.
+ * 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.
  */
-const zstdEncoder = (): TransformStream<Uint8Array, Uint8Array> =>
-  new CompressionStream('zstd') as unknown as TransformStream<Uint8Array, Uint8Array>
-
-const oneChunk = (bytes: Uint8Array): ReadableStream<Uint8Array> =>
-  new ReadableStream({
-    start(c) {
-      c.enqueue(bytes)
-      c.close()
-    },
-  })
-
-/**
- * The decoded tar as a stream: one call for a small artifact that
- * declares its size, a streamed decode otherwise — the stream setup is
- * ~35 µs, which matters at a thousand one-file artifacts and nowhere
- * else. Bytes in memory are only ever the small case (a large source
- * must be a FILE: a Blob copies its bytes and hands the decoder
- * everything at once, measured +519 MiB on 150 MiB against +448 for the
- * plain decode). The 2 GiB ceiling applies either way: the declaration
- * and the result length in one call, a running count on the stream.
- */
-async function decodedTar(
-  source: Uint8Array | Bun.BunFile,
-  hash: string,
-): Promise<ReadableStream<Uint8Array>> {
-  if (source instanceof Uint8Array) {
-    if (assertDeclaredSize(source, hash) === null) return zstdDecodeStream(new Blob([source]), hash)
-    return oneChunk(await zstdDecompressBounded(source, hash))
-  }
-  if (source.size <= STREAM_DECODE_FROM) {
-    const bytes = await source.bytes()
-    if (assertDeclaredSize(bytes, hash) === null) return zstdDecodeStream(source, hash)
-    return oneChunk(await zstdDecompressBounded(bytes, hash))
+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.`,
+    )
   }
-  assertDeclaredSize(await source.slice(0, 32).bytes(), hash)
-  return zstdDecodeStream(source, hash)
 }
 
-/**
- * The streaming twin of `zstdDecompressBounded`: the decoded bytes as a
- * stream, refused past the same ceiling. A malicious frame cannot expand
- * past the cap here either — the count runs as bytes are produced, before
- * any of them reach the reader's next entry.
- */
-function zstdDecodeStream(source: Blob, hash: string): ReadableStream<Uint8Array> {
-  let total = 0
-  return source
-    .stream()
-    .pipeThrough(new DecompressionStream('zstd'))
-    .pipeThrough(
-      new TransformStream<Uint8Array, Uint8Array>({
-        transform(chunk, controller) {
-          total += chunk.byteLength
-          if (total > MAX_DECOMPRESSED_ARTIFACT_BYTES) {
-            controller.error(
-              new CorruptArtifactError(
-                hash,
-                `decompresses past ${MAX_DECOMPRESSED_ARTIFACT_BYTES} bytes (cap)`,
-              ),
-            )
-            return
-          }
-          controller.enqueue(chunk)
-        },
-      }),
+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>`,
     )
+  }
 }
 
-export interface CacheLayer {
-  /**
-   * The local handle this layer wraps, when it wraps one (`LayeredCache`).
-   * `resolveCache` uses it to drop a bare local layer another declared layer
-   * already contains, so `[cloud(), localCachePlugin()]` does not write the
-   * local store twice.
-   */
-  readonly local?: Cache | undefined
-  /**
-   * `true` iff a REMOTE cache sits behind this layer. THE answer to "can
-   * the remote axes of the cache policy do anything on this run?" — the
-   * orchestrator clamps `remoteRead`/`remoteWrite` off when it is absent,
-   * skips the up-front local classify when it is present (that classify's
-   * `cache.get` would be a remote read-through awaited before scheduling),
-   * and drives the prefetch pass off it.
-   *
-   * A layer must answer TRUTHFULLY: identity against the local cache
-   * ("something other than the handle I passed in") is NOT the same
-   * question — an ordinary pass-through decorator with no remote at all
-   * answers yes to it. `LayeredCache` sets it, a bare `Cache` denies it,
-   * and a third-party layer opts in when, and only when, it really has a
-   * remote. Optional so a layer written before this contract keeps
-   * type-checking; absent reads as "no remote", the safe answer.
-   */
-  readonly hasRemote?: boolean
-  /**
-   * Batch existence probe over the remote — the subset of `hashes` stored
-   * remotely, in ONE round-trip, or `null` for "no batch info; use
-   * per-hash". Only meaningful with `hasRemote`; a remote layer that can't
-   * batch omits it and the prefetch pass falls back to per-hash GETs.
-   */
-  remoteHasMany?(hashes: readonly string[]): Promise<Set<string> | null>
-  /**
-   * Record that the remote has NO artifact for each of `hashes` (from a
-   * batch probe), so a later `get`/`prefetch` short-circuits to a miss with
-   * no round-trip. Only meaningful with `hasRemote`.
-   */
-  markRemoteAbsent?(hashes: Iterable<string>): void
-  /**
-   * Resolve once every background write-through upload settles. The
-   * orchestrator awaits it before `close()` — an upload reading layer state
-   * after close would race. Only meaningful with `hasRemote`; a layer that
-   * uploads synchronously (or not at all) omits it.
-   */
-  drainUploads?(): Promise<void>
-  key(input: CacheKeyInput): Promise<string>
-  get(hash: string, ctx?: CacheGetContext): Promise<CacheEntry | null>
-  /**
-   * Optional batched `get` (same answers, fewer round trips). The
-   * short-circuit probe uses it when a layer offers one; a layer without it
-   * is probed hash by hash.
-   */
-  getMany?(hashes: readonly string[]): Promise<Map<string, CacheEntry>>
-  /**
-   * Lightweight existence probe. `'local'` / `'remote'` names the layer
-   * that holds the artifact; `null` is a miss. NEVER moves bytes: no
-   * artifact read, no remote download, no local ingest, no accessed_at
-   * bump (the LayeredCache's remote side is an HTTP HEAD). Planning
-   * (`--dry` / `--graph`) predicts hits with this instead of `get` so a
-   * dry run can't pull N artifacts over the network. Remote errors
-   * degrade to `null` — an existence probe never fails anything.
-   */
-  has(hash: string): Promise<'local' | 'remote' | null>
-  /**
-   * Best-effort warm of `hash` from a slower layer (the remote cache)
-   * into this one, so a later `get(hash)` resolves locally without a
-   * round-trip on the task's critical path. Returns `true` if the
-   * artifact is now present locally, `false` on a miss / error
-   * (degrades, never throws). The local `Cache` is a no-op (nothing
-   * slower to warm from); `LayeredCache` owns the real implementation
-   * plus the in-flight de-dup so prefetch + get share ONE remote GET.
-   */
-  prefetch(hash: string, ctx?: CacheGetContext): Promise<boolean>
-  /**
-   * Batched lookup of per-output-file fingerprints for many cache
-   * entries in one SQL round-trip. Returns a Map keyed by entry hash.
-   *
-   * Orchestrator pattern: call this once at `prepareRun` for every
-   * task whose hash is known up-front, then per-task `executeCachedTask`
-   * does a Map.get (O(1)) + parallel stat checks to decide whether the
-   * on-disk tree is already current.
-   *
-   * Hashes with no rows (cache misses) are absent from the result.
-   */
-  loadOutputFilesBatch(hashes: readonly string[]): Map<string, OutputFileRow[]>
-  /**
-   * Stat each `expected` row's target under `projectDir` and return
-   * `true` iff every (size, mode, mtime) matches. Missing files,
-   * stat errors, or any mismatch → `false`.
-   *
-   * Pure FS check — no DB access. Caller batches the expected rows
-   * via `loadOutputFilesBatch`. Lets the orchestrator skip
-   * `cleanOutputs + restoreOutputs` entirely when the cached
-   * snapshot is already in place. Integrity-preserving: detects
-   * out-of-band file edits or deletions and falls through to a real
-   * restore.
-   */
-  isOutputsCurrent(projectDir: string, expected: readonly OutputFileRow[]): Promise<boolean>
-  /**
-   * The directory-mtime short-circuit behind a warm hit (optional — a layer
-   * without it keeps the output walk). `recordOutputDirs` snapshots every
-   * directory under each of `prefixes` (project-relative, whole-subtree
-   * globs only — see `wholeSubtreePrefixes`) after a save or restore;
-   * `loadOutputDirsBatch` reads them back; `outputDirsCurrent` is true iff
-   * every recorded directory still carries its recorded mtime, which proves
-   * no file was added or removed anywhere the glob could see. Machine-local
-   * state, like the output rows: a remote ingest records none.
-   */
-  recordOutputDirs?(hash: string, projectDir: string, prefixes: readonly string[]): Promise<void>
-  loadOutputDirsBatch?(hashes: readonly string[]): Map<string, OutputDirRow[]>
-  outputDirsCurrent?(projectDir: string, rows: readonly OutputDirRow[]): Promise<boolean>
-  /**
-   * Extract the artifact's `outputs/` entries into `projectDir` and —
-   * when `workspaceRoot` is given — its `workspace-outputs/` entries
-   * into the workspace root. Callers restoring entries that may carry
-   * workspace outputs must pass `workspaceRoot`.
-   */
-  restoreOutputs(hash: string, projectDir: string, workspaceRoot?: string): Promise<void>
-  save(args: {
-    hash: string
-    /**
-     * `exitCode` is deliberately NOT accepted: vx caches only successes, so
-     * the stored value is pinned to 0 and there is nothing for a caller to
-     * decide. Accepting a number and discarding it invited the one shape that
-     * launders a failure into a success — cache a failing task's outputs, read
-     * the entry back as exit 0, and the hit classifies `cache-hit` while the
-     * broken build's files are restored over a good tree. Unrepresentable
-     * beats guarded.
-     */
-    entry: Omit<CacheEntry, 'hash' | 'storedAt' | 'outputFiles' | 'exitCode'>
-    projectDir: string
-    outputFiles: string[]
-    /**
-     * Set only by ChainedCache when an EARLIER layer in the chain already
-     * wrote this artifact to the same local handle: the local pack + write
-     * is skipped and only the layer's remote side acts. A layer with no
-     * remote side treats it as a full no-op.
-     */
-    skipLocalWrite?: boolean
-    /**
-     * Resolved `outputs.workspaceFiles` (absolute paths) + the root
-     * they're relative to. Packed under `workspace-outputs/<rel>`.
-     * Omitted → artifact bytes identical to the pre-workspaceFiles
-     * format.
-     */
-    workspaceOutputFiles?: string[]
-    workspaceRoot?: string
-    /**
-     * Cache-key components for this entry (the Tier-3 input
-     * fingerprint). Persisted to `entry_inputs` inside the same
-     * transaction as the entry row, via `INSERT OR IGNORE` (a re-save
-     * of the same hash is a no-op). Omitted/empty → nothing written.
-     * Only computed on the miss/save path — never on a hit.
-     */
-    inputComponents?: readonly TaskInputRow[]
-  }): Promise<void>
-  /**
-   * Adopt an artifact produced elsewhere — the remote-hit path. Writes
-   * the compressed bytes to `<cacheDir>/<hash>.tar.zst`, parses the
-   * tar headers to populate the `output_files` rows, and inserts the
-   * `entries` row using the caller-supplied `meta`. After this returns,
-   * the next `get(hash)` resolves locally.
-   */
-  ingest(hash: string, compressed: Uint8Array, meta: IngestMeta): Promise<void>
-  recordRun(run: RunRecord): void
-  /**
-   * Append every run in `runs` to the history in a single SQLite
-   * transaction. ~10× faster than calling `recordRun` in a loop when
-   * `runs.length > ~50` (one fsync vs. N).
-   */
-  recordRuns(runs: readonly RunRecord[]): void
-  /**
-   * Record a whole `vx run` atomically: the per-task `runs` rows and
-   * the one `invocations` header row — in a SINGLE transaction (one
-   * fsync). Replaces the bare `recordRuns` call in the orchestrator's
-   * end-of-run path. Input-fingerprint rows are NOT written here — they
-   * ride the entry-save transaction (`save`/`ingest`) so a warm
-   * all-cache-hit run writes nothing.
-   */
-  recordRunBundle(bundle: { runs: readonly RunRecord[]; invocation: InvocationRecord }): void
-  stats(opts?: CacheStatsOptions): CacheStats
-  /**
-   * Content-hash a file with an mtime+size fast path. If the
-   * `(mtime_ms, size_bytes)` of `filePath` match a previously seen
-   * row, return the stored xxh3 digest instead of re-reading the
-   * bytes. Otherwise read + hash + upsert. The hash is byte-for-byte
-   * identical to what a fresh content-hash would produce — pure
-   * optimization, no cache-key change.
-   */
-  hashFile(filePath: string): Promise<string>
-  /**
-   * Absolute path to the on-disk outputs artifact for a hash —
-   * `<cacheDir>/<hash>.tar.zst`. Returns the path whether or
-   * not the artifact exists. Exposed for telemetry / dashboards;
-   * `restoreOutputs` is the canonical way to materialize the bytes.
-   */
-  outputsPath(hash: string): string
-  prune(options: PruneOptions): Promise<PruneResult>
-  close(): void
-}
-
-/**
- * Convenience alias for the `save()` args. Used by `LayeredCache` to
- * forward call args without redeclaring the structural shape — NOT
- * part of the conceptual cache contract; consumers should call
- * `CacheLayer.save({ ... })` directly.
- *
- * @internal
- */
-export type SaveArgs = Parameters<CacheLayer['save']>[0]
-
-interface EntryRow {
-  hash: string
-  project: string
-  task: string
-  command: string
-  exit_code: number
-  duration_ms: number
-  size_bytes: number
-  stdout: string
-  created_at: number
-  accessed_at: number
-}
-
-function entryOf(row: EntryRow, fileRows: OutputFileRow[]): CacheEntry {
-  return {
-    hash: row.hash,
-    taskId: `${row.project}#${row.task}`,
-    command: row.command,
-    exitCode: row.exit_code,
-    durationMs: row.duration_ms,
-    outputFiles: fileRows.map((r) => r.path),
-    outputRows: fileRows,
-    stdout: row.stdout,
-    storedAt: new Date(row.created_at).toISOString(),
-    source: 'local',
-  }
+function errorText(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
 }
 
 export class Cache implements CacheLayer {
@@ -1005,19 +357,12 @@ export class Cache implements CacheLayer {
   private readonly selectEntry: ReturnType<Database['prepare']>
   private readonly bumpAccessed: ReturnType<Database['prepare']>
   private readonly touched = new Set<string>()
-  private readonly insertRun: ReturnType<Database['prepare']>
-  private readonly insertInvocation: ReturnType<Database['prepare']>
   private readonly insertEntryInput: ReturnType<Database['prepare']>
-  private readonly selectFileHash: ReturnType<Database['prepare']>
-  private readonly upsertFileHash: ReturnType<Database['prepare']>
-  private readonly insertOutputFile: ReturnType<Database['prepare']>
-  private readonly insertOutputDir: ReturnType<Database['prepare']>
-  private readonly deleteOutputDirs: ReturnType<Database['prepare']>
-  private readonly deleteOutputFiles: ReturnType<Database['prepare']>
-  private readonly selectConfigEval: ReturnType<Database['prepare']>
-  private readonly insertConfigEval: ReturnType<Database['prepare']>
-  /** Memoized repo object format for blob-OID hashing (lazy-detected). */
-  private objectFormat: 'sha1' | 'sha256' | null = null
+  /** 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
 
   /**
    * Local-layer read/write gates for the task ARTIFACT path only.
@@ -1028,61 +373,171 @@ 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`
+   * and dropped every table. The next open sees the current version and
+   * reports null, so whoever opened first is the one that can say so —
+   * `noteSchemaReset` is that one line, at every opener that has a
+   * channel. Without it an upgrade empties the cache and the history in
+   * silence, and the all-miss run that follows looks like a bug.
+   */
+  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
-      );
-    `)
+    // failing immediately with SQLITE_BUSY. Two parallel `vx run`
+    // invocations in CI is a normal pattern; without this the second one
+    // 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
     // takes effect on stale DBs. Pre-alpha: no migrations, just drop
-    // and recreate. Outputs on disk become orphans; they'll be ignored
-    // on next miss and reaped by `vx cache prune`.
-    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.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)
+    // and recreate. Artifacts on disk become orphans: a lookup never
+    // 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.
+    //
+    // 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
@@ -1111,7 +566,10 @@ export class Cache implements CacheLayer {
         size_bytes   INTEGER NOT NULL,
         stdout       TEXT NOT NULL DEFAULT '',
         created_at   INTEGER NOT NULL,
-        accessed_at  INTEGER NOT NULL
+        accessed_at  INTEGER NOT NULL,
+        -- v26: the producing execution's usage, from the artifact's sidecar.
+        cpu_ms         INTEGER,
+        peak_rss_bytes INTEGER
       );
       CREATE TABLE IF NOT EXISTS runs (
         id                  INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -1137,18 +595,46 @@ export class Cache implements CacheLayer {
         cache_hit           INTEGER,
         -- v23: attempts a retried task took (>1); NULL for a once-run task.
         -- The direct within-run flaky signal.
-        attempts            INTEGER
+        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,
+        -- 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
       );
-      -- runs_hash had no reader: every consumer of runs.hash looks the row
-      -- up by run_id or (project, task) first. Dropped 2026-09-03 — it cost
-      -- 1,000 warm-run inserts 11.5 → 3.9 ms; the DROP sheds it from
-      -- existing databases (a schema-meta bump is for stored shapes, and
-      -- an index is not one).
+      -- 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
+      -- 1,000 inserts touch a handful of leaf pages. The dropped ones did
+      -- not — the DROPs shed them from existing databases (a schema-meta
+      -- bump is for stored shapes, and an index is not one):
+      --   runs_hash (2026-09-03) had no reader; 11.5 → 3.9 ms per 1,000.
+      --   runs_project (project, task) (2026-09-09) scattered every run's
+      --     rows over one leaf per pair: the record stage of a 1,000-hit
+      --     warm run was 57–79 ms with it and 14–19 ms without, at 166k
+      --     rows, and it bought its readers nothing — the history reader
+      --     now scans a rowid slice (history.ts), vx why walks
+      --     started_at newest-first and stops at the first match.
+      --   runs_ended (2026-09-09) served only the retention DELETE, which
+      --     prunes on started_at now (a row ends after it starts, so the
+      --     30-day window moves by at most one task's duration).
       DROP INDEX IF EXISTS runs_hash;
+      DROP INDEX IF EXISTS runs_project;
+      DROP INDEX IF EXISTS runs_ended;
       CREATE INDEX IF NOT EXISTS runs_started_at ON runs(started_at);
-      CREATE INDEX IF NOT EXISTS runs_project    ON runs(project, task);
-      CREATE INDEX IF NOT EXISTS runs_ended      ON runs(ended_at);
       CREATE INDEX IF NOT EXISTS runs_run_id     ON runs(run_id);
+      -- The one keyed index, PARTIAL over failed rows: a green run's
+      -- inserts only evaluate its predicate, so the append-only cost above
+      -- holds, and the flakiness probe after a miss (failure-mode.ts,
+      -- "did this key ever fail?") reads a handful of leaves instead of
+      -- scanning the table (2026-09-10: 10–95 ms at 170k rows without it).
+      CREATE INDEX IF NOT EXISTS runs_failed ON runs(hash) WHERE status = 'failed';
       -- Per-file (mtime, size, content_hash) cache. Lets Cache.key()
       -- skip the content-hash on inputs whose stat hasn't changed
       -- since the last run. Pure performance optimization; the stored
@@ -1178,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
@@ -1195,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,
@@ -1258,41 +748,22 @@ export class Cache implements CacheLayer {
     `)
 
     this.insertEntry = this.db.prepare(`
-      INSERT INTO entries(hash, project, task, command, exit_code, duration_ms, size_bytes, stdout, created_at, accessed_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      INSERT INTO entries(hash, project, task, command, exit_code, duration_ms, size_bytes, stdout, created_at, accessed_at, cpu_ms, peak_rss_bytes)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(hash) DO UPDATE SET
-        stdout       = excluded.stdout,
-        project      = excluded.project,
-        task         = excluded.task,
-        command      = excluded.command,
-        exit_code    = excluded.exit_code,
-        duration_ms  = excluded.duration_ms,
-        size_bytes   = excluded.size_bytes,
-        accessed_at  = excluded.accessed_at
+        stdout         = excluded.stdout,
+        project        = excluded.project,
+        task           = excluded.task,
+        command        = excluded.command,
+        exit_code      = excluded.exit_code,
+        duration_ms    = excluded.duration_ms,
+        size_bytes     = excluded.size_bytes,
+        accessed_at    = excluded.accessed_at,
+        cpu_ms         = excluded.cpu_ms,
+        peak_rss_bytes = excluded.peak_rss_bytes
     `)
     this.selectEntry = this.db.prepare('SELECT * FROM entries WHERE hash = ?')
     this.bumpAccessed = this.db.prepare('UPDATE entries SET accessed_at = ? WHERE hash = ?')
-    this.insertRun = this.db.prepare(`
-      INSERT INTO runs(
-        hash, project, task, status, exit_code, duration_ms, forward_args,
-        started_at, ended_at,
-        run_id, cpu_ms, peak_rss_bytes, wallclock_start_ns, wallclock_end_ns,
-        cache_hit, attempts
-      )
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?,  ?, ?, ?, ?, ?,  ?, ?)
-    `)
-    this.insertInvocation = this.db.prepare(`
-      INSERT INTO invocations(
-        run_id, command, requested_tasks, cache_policy, concurrency, flow,
-        started_at, ended_at, total_duration_ms,
-        task_count, failed_count, hit_count, hit_local_count, hit_remote_count,
-        exit_ok,
-        commit_sha, branch, dirty, ci, ci_provider,
-        host, os, arch, vx_version, tags
-      )
-      VALUES (?, ?, ?, ?, ?, ?,  ?, ?, ?,  ?, ?, ?, ?, ?,  ?,  ?, ?, ?, ?, ?,  ?, ?, ?, ?, ?)
-      ON CONFLICT(run_id) DO NOTHING
-    `)
     // INSERT OR IGNORE: re-saving the same hash (idempotent ingest /
     // overlapping concurrent saves) leaves the existing rows untouched —
     // identical inputs derive the identical hash, so the rows are too.
@@ -1300,304 +771,90 @@ export class Cache implements CacheLayer {
       INSERT OR IGNORE INTO entry_inputs(entry_hash, kind, name, hash)
       VALUES (?, ?, ?, ?)
     `)
-    this.selectFileHash = this.db.prepare(
-      'SELECT mtime_ms, size_bytes, ctime_ms, ino, content_hash FROM file_hashes WHERE path = ?',
-    )
-    this.upsertFileHash = this.db.prepare(`
-      INSERT INTO file_hashes(path, mtime_ms, size_bytes, ctime_ms, ino, content_hash, seen_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?)
-      ON CONFLICT(path) DO UPDATE SET
-        mtime_ms     = excluded.mtime_ms,
-        size_bytes   = excluded.size_bytes,
-        ctime_ms     = excluded.ctime_ms,
-        ino          = excluded.ino,
-        content_hash = excluded.content_hash,
-        seen_at      = excluded.seen_at
-    `)
-    this.insertOutputFile = this.db.prepare(`
-      INSERT INTO output_files(entry_hash, path, size_bytes, mode, mtime_ms)
-      VALUES (?, ?, ?, ?, ?)
-      ON CONFLICT(entry_hash, path) DO UPDATE SET
-        size_bytes = excluded.size_bytes,
-        mode       = excluded.mode,
-        mtime_ms   = excluded.mtime_ms
-    `)
-    this.deleteOutputFiles = this.db.prepare('DELETE FROM output_files WHERE entry_hash = ?')
-    this.insertOutputDir = this.db.prepare(
-      'INSERT INTO output_dirs(entry_hash, path, mtime_ms) VALUES (?, ?, ?)',
-    )
-    this.deleteOutputDirs = this.db.prepare('DELETE FROM output_dirs WHERE entry_hash = ?')
-    this.selectConfigEval = this.db.prepare('SELECT json FROM config_evals WHERE key = ?')
-    this.insertConfigEval = this.db.prepare(
-      'INSERT OR REPLACE INTO config_evals(key, json, created_at) VALUES (?, ?, ?)',
-    )
+    // 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)
+
+    // 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)
+    }
   }
 
-  /** `ConfigEvalStore`: a cached config evaluation, honouring the local READ axis. */
+  // --- config evaluations: `ConfigEvalStore`, delegated to `ConfigEvalTable` ---
   getConfigEval(key: string): string | null {
-    if (!this.read) return null
-    const row = this.selectConfigEval.get(key) as { json: string } | null
-    return row?.json ?? null
+    return this.configEvals.getConfigEval(key)
   }
-
-  /** `ConfigEvalStore`: each config's ordered closure, one `IN` query per 900 paths. */
   getConfigClosures(configPaths: readonly string[]): Map<string, string[]> {
-    const out = new Map<string, string[]>()
-    if (!this.read || configPaths.length === 0) return out
-    for (let i = 0; i < configPaths.length; i += 900) {
-      const chunk = configPaths.slice(i, i + 900)
-      const rows = this.db
-        .query(
-          `SELECT config_path, files_json FROM config_closures WHERE config_path IN (${chunk.map(() => '?').join(',')})`,
-        )
-        .all(...(chunk as readonly SQLQueryBindings[])) as Array<{
-        config_path: string
-        files_json: string
-      }>
-      for (const r of rows) out.set(r.config_path, JSON.parse(r.files_json) as string[])
-    }
-    return out
+    return this.configEvals.getConfigClosures(configPaths)
   }
-
-  /** `ConfigEvalStore`: remember a config's ordered closure, honouring the local WRITE axis. */
   putConfigClosure(configPath: string, files: readonly string[]): void {
-    if (!this.write) return
-    this.db
-      .prepare(
-        'INSERT INTO config_closures(config_path, files_json, created_at) VALUES (?, ?, ?) ON CONFLICT(config_path) DO UPDATE SET files_json = excluded.files_json, created_at = excluded.created_at',
-      )
-      .run(configPath, JSON.stringify(files), Date.now())
+    this.configEvals.putConfigClosure(configPath, files)
   }
-
-  /** `ConfigEvalStore`: the batched read — one `IN` query per 900 keys, honouring the local READ axis. */
   getConfigEvals(keys: readonly string[]): Map<string, string> {
-    const out = new Map<string, string>()
-    if (!this.read || keys.length === 0) return out
-    for (let i = 0; i < keys.length; i += 900) {
-      const chunk = keys.slice(i, i + 900)
-      const rows = this.db
-        .query(
-          `SELECT key, json FROM config_evals WHERE key IN (${chunk.map(() => '?').join(',')})`,
-        )
-        .all(...(chunk as readonly SQLQueryBindings[])) as Array<{ key: string; json: string }>
-      for (const r of rows) out.set(r.key, r.json)
-    }
-    return out
+    return this.configEvals.getConfigEvals(keys)
   }
-
-  /** `ConfigEvalStore`: remember a validated evaluation, honouring the local WRITE axis. */
   putConfigEval(key: string, json: string): void {
-    if (!this.write) return
-    this.insertConfigEval.run(key, json, Date.now())
+    this.configEvals.putConfigEval(key, json)
   }
-
-  /**
-   * Content-hash a file (as a git blob OID, v20) with an mtime+size
-   * fast path. If the `file_hashes` table has a row for `path` whose
-   * `(mtime_ms, size_bytes, ctime_ms, ino)` all match the current
-   * stat, we reuse the stored content_hash (a memory + SQLite lookup,
-   * no disk read). Otherwise we read + hash + upsert. All four fields
-   * are load-bearing — see the comment at the comparison.
-   *
-   * The OID is byte-identical to what `git hash-object` (and the git
-   * index) computes for the same content, so this fallback and the
-   * `CacheKeyInput.fileHashes` index-OID fast path agree on any file
-   * git stores verbatim. They do NOT agree when a clean filter
-   * (`text`/`eol`/`ident`) is active: the index blob is the filtered
-   * form while this hashes the worktree bytes, so `inputs.ts` drops
-   * the index OID for those paths and routes them here.
-   */
-  async hashFile(filePath: string): Promise<string> {
-    // statSync intentional: a single stat is ~1.6µs (Bun 1.3); the
-    // async-stat equivalent adds ~75µs of Promise machinery per call.
-    // Promise.all over the batched callers (key derivation) gives no
-    // I/O parallelism benefit because the stat is faster than the
-    // threadpool dispatch overhead.
-    let st
-    try {
-      st = statSync(filePath)
-    } catch {
-      // Caller is responsible for skipping files that don't exist;
-      // fall through to the content-hash path which will throw with
-      // a more useful error.
-      return await this.hashFileFromDisk(filePath)
-    }
-    const mtimeMs = Math.floor(st.mtimeMs)
-    const size = st.size
-    // ctime + ino are what make this memo SAFE, not merely fast. mtime is
-    // caller-settable, so (mtime, size) alone hands back the previous run's
-    // digest for genuinely different bytes whenever a producer preserves
-    // mtime — `tar -x`, `unzip`, `cp -p`, `rsync --times`, any
-    // SOURCE_DATE_EPOCH generator — which is a stale cache hit. `utimes`
-    // cannot suppress ctime without root, and an atomic write-then-rename
-    // changes the inode; git's own index keys on ctime+ino+dev for exactly
-    // this reason. Both fields come from the stat we already took.
-    const ctimeMs = Math.floor(st.ctimeMs)
-    const ino = Number(st.ino)
-    const row = this.selectFileHash.get(filePath) as
-      | {
-          mtime_ms: number
-          size_bytes: number
-          ctime_ms: number
-          ino: number
-          content_hash: string
-        }
-      | undefined
-    if (
-      row &&
-      row.mtime_ms === mtimeMs &&
-      row.size_bytes === size &&
-      row.ctime_ms === ctimeMs &&
-      row.ino === ino
-    ) {
-      return row.content_hash
-    }
-    const ch = await this.hashFileFromDisk(filePath)
-    this.upsertFileHash.run(filePath, mtimeMs, size, ctimeMs, ino, ch, Date.now())
-    return ch
+  putConfigEvals(entries: ReadonlyArray<readonly [string, string]>): void {
+    this.configEvals.putConfigEvals(entries)
   }
-
-  /**
-   * Git blob OID of the file's bytes:
-   * `hex(HASH("blob " + byteLength + "\0" + content))`, where HASH is
-   * the repo's object format. Same value `git hash-object` prints and
-   * the same value the index stores. Computed in-process — no git
-   * spawn per file.
-   */
-  private async hashFileFromDisk(filePath: string): Promise<string> {
-    const bytes = await Bun.file(filePath).bytes()
-    const hasher = new Bun.CryptoHasher(this.objectFormat ?? this.detectObjectFormat(filePath))
-    hasher.update(`blob ${bytes.byteLength}\0`)
-    hasher.update(bytes)
-    return hasher.digest('hex')
+  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)
   }
-
   /**
-   * Repo object format — sha1 unless the repo was created with
-   * `--object-format=sha256`. One `git rev-parse` spawn per Cache
-   * lifetime, and only when at least one file misses the mtime+size
-   * memo. Outside a repo (unit fixtures) we default to sha1, which is
-   * still a deterministic blob-OID domain.
+   * `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 detectObjectFormat(nearPath: string): 'sha1' | 'sha256' {
-    let detected: 'sha1' | 'sha256' = 'sha1'
-    try {
-      const proc = Bun.spawnSync({
-        cmd: ['git', 'rev-parse', '--show-object-format'],
-        cwd: path.dirname(nearPath),
-        stdout: 'pipe',
-        stderr: 'pipe',
-      })
-      if (proc.exitCode === 0 && new TextDecoder().decode(proc.stdout).trim() === 'sha256') {
-        detected = 'sha256'
-      }
-    } catch {
-      // git unavailable → sha1 default keeps hashing deterministic.
+  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()
     }
-    this.objectFormat = detected
-    return detected
+    let rel = this.relMemo.get(file)
+    if (rel === undefined) this.relMemo.set(file, (rel = relPosix(root, file)))
+    return rel
   }
 
-  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) })
-      }
-    }
-
-    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
@@ -1607,7 +864,7 @@ export class Cache implements CacheLayer {
     // Local reads disabled (e.g. `--force` / `--cache=local:w`): report a
     // miss so the task re-executes. The artifact + index are untouched.
     if (!this.read) return null
-    return await this.readEntry(hash)
+    return this.readEntry(hash)
   }
 
   /**
@@ -1619,8 +876,8 @@ export class Cache implements CacheLayer {
    * `ingest` had just written, so the task re-executed and re-uploaded on
    * every single run.
    */
-  async getIngested(hash: string): Promise<CacheEntry | null> {
-    return await this.readEntry(hash)
+  getIngested(hash: string): Promise<CacheEntry | null> {
+    return this.readEntry(hash)
   }
 
   private async readEntry(hash: string): Promise<CacheEntry | null> {
@@ -1629,7 +886,7 @@ export class Cache implements CacheLayer {
 
     // Verify the tar artifact actually exists. The DB and the
     // filesystem can drift if someone manually deletes the cache dir.
-    if (!(await Bun.file(this.tarPath(hash)).exists())) return null
+    if (!existsSync(this.tarPath(hash))) return null
 
     // Deferred: per-hit UPDATEs cost ~60 ms across 2000+ probes on a
     // full-cache run. Hashes are collected and flushed as ONE batched
@@ -1670,7 +927,7 @@ export class Cache implements CacheLayer {
       )
     }
     if (rows.length === 0) return out
-    const present = await Promise.all(rows.map((r) => Bun.file(this.tarPath(r.hash)).exists()))
+    const present = rows.map((r) => existsSync(this.tarPath(r.hash)))
     const live = rows.filter((_r, i) => present[i])
     const liveHashes = live.map((r) => r.hash)
     const fileRows = this.loadOutputFilesBatch(liveHashes)
@@ -1690,7 +947,7 @@ export class Cache implements CacheLayer {
     if (!this.read) return null
     const row = this.selectEntry.get(hash) as EntryRow | undefined
     if (!row) return null
-    return (await Bun.file(this.tarPath(hash)).exists()) ? 'local' : null
+    return existsSync(this.tarPath(hash)) ? 'local' : null
   }
 
   // Local cache has no slower layer to warm from — prefetch is a no-op.
@@ -1700,169 +957,37 @@ export class Cache implements CacheLayer {
     return false
   }
 
+  // --- output fingerprints: delegated to `OutputIndex` (see output-index.ts) ---
+  // The slices' proofs and hashes are returned as the slice's own promise —
+  // no `async` wrapper, no `return await`: each of those added a promise and
+  // a microtask hop per call, and a 1,000-hit warm run pays the proofs
+  // 2,000 times (measured 2026-09-10: +3 ms on `classify + probe`).
   loadOutputFilesBatch(hashes: readonly string[]): Map<string, OutputFileRow[]> {
-    const out = new Map<string, OutputFileRow[]>()
-    if (hashes.length === 0) return out
-    // Inline placeholders for an IN-list — bun:sqlite doesn't ship
-    // rarray, but `IN (?, ?, …)` with N≤~999 is fast and avoids per-
-    // hash select.get() overhead. `db.query` (not `db.prepare`) caches the
-    // compiled statement keyed by the SQL text — so the dominant single-hash
-    // warm-hit path (called up to 3× per hit) reuses one statement instead of
-    // recompiling on every call.
-    const placeholders = hashes.map(() => '?').join(',')
-    const stmt = this.db.query(
-      `SELECT entry_hash, path, size_bytes, mode, mtime_ms FROM output_files WHERE entry_hash IN (${placeholders})`,
-    )
-    const rows = stmt.all(...(hashes as readonly SQLQueryBindings[])) as Array<{
-      entry_hash: string
-      path: string
-      size_bytes: number
-      mode: number
-      mtime_ms: number
-    }>
-    for (const r of rows) {
-      let list = out.get(r.entry_hash)
-      if (!list) {
-        list = []
-        out.set(r.entry_hash, list)
-      }
-      list.push({ path: r.path, size: r.size_bytes, mode: r.mode, mtimeMs: r.mtime_ms })
-    }
-    return out
+    return this.outputs.loadOutputFilesBatch(hashes)
   }
-
-  async isOutputsCurrent(projectDir: string, expected: readonly OutputFileRow[]): Promise<boolean> {
-    // Empty manifest case (a task produced no outputs) → trivially
-    // current; the on-disk tree under projectDir is whatever it was,
-    // and nothing was supposed to land there.
-    if (expected.length === 0) return true
-    // Promise-form stat, deliberately: statSync is ~2 µs against ~13 µs in
-    // isolation, but this runs under the scheduler's concurrency and the
-    // async form keeps the stats on the thread pool in parallel — the sync
-    // version measured slower on a 1000-hit warm run (2026-09-02).
-    const results = await Promise.all(
-      expected.map(async (e) => {
-        try {
-          const s = await stat(path.join(projectDir, e.path))
-          return (
-            s.size === e.size &&
-            (s.mode & 0o777) === (e.mode & 0o777) &&
-            // MILLISECOND comparison (sub-ms tolerance for the float
-            // round-trip through utimes). Save rows carry stat-ms and
-            // restoreOutputs re-syncs restored files to the row value,
-            // so equality holds exactly in steady state; legacy
-            // second-precision rows converge on their first restore.
-            // Residual blind spot: a same-size edit landing in the SAME
-            // millisecond as the recorded write, or a deliberately
-            // forged mtime (touch -r) — the trade every mtime-based
-            // skip check accepts.
-            Math.abs(s.mtimeMs - e.mtimeMs) < 1
-          )
-        } catch {
-          return false
-        }
-      }),
-    )
-    return results.every(Boolean)
+  isOutputsCurrent(projectDir: string, expected: readonly OutputFileRow[]): Promise<boolean> {
+    return this.outputs.isOutputsCurrent(projectDir, expected)
   }
-
   outputsPath(hash: string): string {
     return this.tarPath(hash)
   }
 
-  /**
-   * Snapshot every directory under each of `prefixes` for `hash`. Called
-   * after a save and after a restore, when the tree is known to equal the
-   * entry's set. Symlinked directories are not descended (the output walk
-   * refuses them too). Over `OUTPUT_DIRS_CAP` directories, or on any
-   * error, the rows are cleared and the next hit keeps the walk.
-   */
   async recordOutputDirs(
     hash: string,
     projectDir: string,
     prefixes: readonly string[],
   ): Promise<void> {
-    const rows: Array<[string, number]> = []
-    const walk = async (rel: string): Promise<boolean> => {
-      const abs = path.join(projectDir, rel)
-      let st
-      try {
-        st = await lstat(abs)
-      } catch {
-        return false
-      }
-      if (!st.isDirectory()) return false
-      rows.push([rel, st.mtimeMs])
-      if (rows.length > OUTPUT_DIRS_CAP) return false
-      let entries
-      try {
-        entries = await readdir(abs, { withFileTypes: true })
-      } catch {
-        return false
-      }
-      for (const e of entries) {
-        if (e.isDirectory() && !e.isSymbolicLink()) {
-          if (!(await walk(`${rel}/${e.name}`))) return false
-        }
-      }
-      return true
-    }
-    let ok = true
-    for (const prefix of prefixes) {
-      if (!(await walk(prefix))) {
-        ok = false
-        break
-      }
-    }
-    // All or nothing: a racy directory dropped alone would leave its
-    // parent trusted while an addition inside it bumps only the dropped one.
-    const youngest = Date.now() - OUTPUT_DIRS_RACY_MS
-    if (rows.some(([, mtime]) => mtime > youngest)) ok = false
-    this.db.transaction(() => {
-      this.deleteOutputDirs.run(hash)
-      if (!ok) return
-      for (const [rel, mtime] of rows) this.insertOutputDir.run(hash, rel, mtime)
-    })()
+    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[]> {
-    const out = new Map<string, OutputDirRow[]>()
-    if (hashes.length === 0) return out
-    const placeholders = hashes.map(() => '?').join(',')
-    const rows = this.db
-      .query(
-        `SELECT entry_hash, path, mtime_ms FROM output_dirs WHERE entry_hash IN (${placeholders})`,
-      )
-      .all(...(hashes as readonly SQLQueryBindings[])) as Array<{
-      entry_hash: string
-      path: string
-      mtime_ms: number
-    }>
-    for (const r of rows) {
-      const list = out.get(r.entry_hash)
-      const row = { path: r.path, mtimeMs: r.mtime_ms }
-      if (list) list.push(row)
-      else out.set(r.entry_hash, [row])
-    }
-    return out
+    return this.outputs.loadOutputDirsBatch(hashes)
   }
-
-  /** True iff every recorded directory exists with its recorded mtime (ms). Same forged-mtime trade as the file check. */
-  async outputDirsCurrent(projectDir: string, rows: readonly OutputDirRow[]): Promise<boolean> {
-    if (rows.length === 0) return false
-    const results = await Promise.all(
-      rows.map(async (r) => {
-        try {
-          const st = await stat(path.join(projectDir, r.path))
-          return st.isDirectory() && Math.abs(st.mtimeMs - r.mtimeMs) < 1
-        } catch {
-          return false
-        }
-      }),
-    )
-    return results.every(Boolean)
+  outputDirsCurrent(projectDir: string, rows: readonly OutputDirRow[]): Promise<boolean> {
+    return this.outputs.outputDirsCurrent(projectDir, rows)
   }
-
   async restoreOutputs(hash: string, projectDir: string, workspaceRoot?: string): Promise<void> {
     // In-process extraction — no fork+exec on the hot path
     // (~5-10ms reclaimed per hit vs the prior subprocess `tar -xf`).
@@ -1877,13 +1002,23 @@ 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.
-    if (!(await Bun.file(src).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
     // hole that no later run detects: the skip-restore check compares the
@@ -1894,6 +1029,7 @@ export class Cache implements CacheLayer {
     const expected = rows
       .filter((r) => workspaceRoot !== undefined || !r.path.startsWith(WORKSPACE_OUTPUT_PREFIX))
       .map((r) => (r.path.startsWith(WORKSPACE_OUTPUT_PREFIX) ? r.path : `outputs/${r.path}`))
+    endRows()
     const verify = (provided: ReadonlySet<string>): void => {
       const missing = expected.filter((name) => !provided.has(name))
       if (missing.length > 0) {
@@ -1913,15 +1049,98 @@ export class Cache implements CacheLayer {
     // when every artifact is a one-file `dist/` (measured: 390 vs 355 ms
     // per 1 000). The local artifact was validated at ingest, so a missing
     // declared size is allowed; the output ceiling applies to both.
+    const endExtract = span('restore: extract')
     try {
-      const tar = await decodedTar(Bun.file(src), hash)
+      // Every step here is an async filesystem call on purpose: a
+      // synchronous restore of a small artifact is 2× faster ALONE (1.25 →
+      // 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, 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. 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(
+          `restore of ${hash} into ${projectDir} was blocked by what is on disk (${code}: ${(err as Error).message}). ` +
+            `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. */
@@ -1953,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()
@@ -1979,24 +1201,30 @@ export class Cache implements CacheLayer {
    * index. Used by the LayeredCache when local writes are disabled but
    * a remote upload still needs the artifact bytes.
    */
-  async packArtifactBytes(args: SaveArgs): Promise<Uint8Array> {
-    return await this.packArtifact(args)
-  }
-
-  async ingest(hash: string, compressed: Uint8Array, meta: IngestMeta): Promise<void> {
-    await this.writeArtifactAndIndex(hash, compressed, meta)
+  packArtifactBytes(args: SaveArgs): Promise<Uint8Array> {
+    return this.packArtifact(args)
   }
 
   /**
-   * 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
@@ -2019,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[]
@@ -2031,13 +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 await 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
   }
 
   /**
@@ -2053,10 +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),
-    })
+    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()
@@ -2075,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
@@ -2090,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
@@ -2107,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`).
@@ -2118,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 =
@@ -2131,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
@@ -2191,8 +1452,7 @@ export class Cache implements CacheLayer {
     // (not the per-run path) so a warm all-cache-hit run — which never
     // saves — writes none of them.
     const insertEntry = this.insertEntry
-    const insertOutputFile = this.insertOutputFile
-    const deleteOutputFiles = this.deleteOutputFiles
+    const outputs = this.outputs
     const insertEntryInput = this.insertEntryInput
     const inputComponents = meta.inputComponents
     const tx = this.db.transaction(() => {
@@ -2212,13 +1472,12 @@ export class Cache implements CacheLayer {
         stdoutText,
         now,
         now,
+        // From the artifact, on both paths: a save indexes what it just
+        // packed, an ingest what the producing machine packed.
+        scanned.exec?.cpuMs ?? null,
+        scanned.exec?.peakRssBytes ?? null,
       )
-      // Replace the entry's existing output_files rows (an UPDATE on
-      // the same hash should refresh, not append).
-      deleteOutputFiles.run(hash)
-      for (const [rel, size, mode, mtime] of outputFileRows) {
-        insertOutputFile.run(hash, rel, size, mode, mtime)
-      }
+      outputs.replaceFileRows(hash, outputFileRows)
       // INSERT OR IGNORE: identical inputs derive this same hash, so a
       // re-save's rows are identical — keep the first set, skip the rest.
       if (inputComponents !== undefined) {
@@ -2260,55 +1519,19 @@ export class Cache implements CacheLayer {
     return this.db
   }
 
-  /**
-   * Content-addressed storage view over the same artifacts directory.
-   * Returns an `FsCASBackend` pointing at `cacheDir`, so external
-   * subsystems (R2 mirror, REAPI CAS bridge, analytics scanners) can
-   * read raw bytes with a `Digest`-keyed API without coupling to
-   * Cache's internal save path. Read/write semantics match what
-   * Cache.save writes (`<cacheDir>/<hash>.tar.zst`).
-   */
-  contentBackend(): FsCASBackend {
-    return new FsCASBackend(this.cacheDir)
-  }
-
+  // --- run history: delegated to `RunHistory` (see run-history.ts) ---
   recordRun(run: RunRecord): void {
-    this.insertRun.run(...bindRun(run))
+    this.history.recordRun(run)
   }
-
   recordRuns(runs: readonly RunRecord[]): void {
-    if (runs.length === 0) return
-    if (runs.length === 1) {
-      this.insertRun.run(...bindRun(runs[0]!))
-      return
-    }
-    // `bun:sqlite`'s `transaction()` returns a callable that wraps the
-    // body in BEGIN/COMMIT, fsyncing once at the end. For a 200-task
-    // run that's one fsync instead of 200.
-    const insert = this.insertRun
-    const tx = this.db.transaction((batch: readonly RunRecord[]) => {
-      for (const r of batch) insert.run(...bindRun(r))
-    })
-    tx(runs)
+    this.history.recordRuns(runs)
   }
-
   recordRunBundle(bundle: { runs: readonly RunRecord[]; invocation: InvocationRecord }): void {
-    // Whole run records atomically — one transaction, one fsync: the
-    // per-task `runs` rows and the one `invocations` header. The
-    // input-fingerprint rows do NOT live here: they're written inside
-    // the entry-save transaction (`save`/`ingest`) so a warm
-    // all-cache-hit run — which writes no `runs`-vs-`entry_inputs`
-    // mismatch — pays nothing for the moat it isn't refreshing.
-    const insertRun = this.insertRun
-    const insertInvocation = this.insertInvocation
-    this.db.transaction(() => {
-      for (const r of bundle.runs) insertRun.run(...bindRun(r))
-      insertInvocation.run(...bindInvocation(bundle.invocation))
-    })()
+    this.history.recordRunBundle(bundle)
   }
-
   stats(opts: CacheStatsOptions = {}): CacheStats {
     this.flushAccessed()
+    this.outputs.flushOutputDirs()
     const project = opts.project
     const scoped = project !== undefined
     const scopeParams: string[] = project === undefined ? [] : [project]
@@ -2335,21 +1558,76 @@ 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()
-    const { olderThanMs, maxBytes } = options
+    // 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`')
     }
 
     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
       }
@@ -2359,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
@@ -2368,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)
@@ -2384,11 +1664,21 @@ export class Cache implements CacheLayer {
     // Promise.all over the unlinks. The IN-list is chunked at 900 like
     // flushAccessed so a huge eviction stays under any build's
     // bound-parameter ceiling.
-    if (victims.size > 0) {
+    if (dryRun) {
+      const orphans = await this.orphanStats()
+      return {
+        evicted: victims.size,
+        bytesFreed,
+        orphans: orphans.orphans,
+        orphanBytes: orphans.orphanBytes,
+      }
+    }
+    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[]))
@@ -2397,7 +1687,109 @@ export class Cache implements CacheLayer {
       await Promise.all(hashes.map((h) => rm(this.tarPath(h), { force: true })))
     }
 
-    return { evicted: victims.size, bytesFreed }
+    const orphans = await this.reapOrphans()
+    return { evicted: victims.size, bytesFreed, ...orphans }
+  }
+
+  /**
+   * Unlink artifacts the index does not know: a `<hash>.tar.zst` with no
+   * `entries` row (a `SCHEMA_VERSION` drop, a `cache.db` deleted by hand)
+   * and a `<hash>.tar.zst.tmp-*` a crashed save never renamed. Nothing
+   * else reaps them — a lookup starts at the row, and a save of the same
+   * key renames over the file, so a key that never recurs leaks its bytes
+   * forever. Files younger than the grace window are left alone: a save
+   * renames the artifact into place BEFORE its row commits, and its temp
+   * 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(
+    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(
+      (await this.scanOrphans()).map(async (o) => {
+        try {
+          // unlink, not `rm({ force })`: force swallows ENOENT, and a file a
+          // concurrent prune took first must not be counted as ours.
+          await unlink(o.file)
+          orphans += 1
+          orphanBytes += o.size
+        } catch {
+          // Gone under us (a concurrent prune, a save's own cleanup): not ours.
+        }
+      }),
+    )
+    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()
+    let orphanBytes = 0
+    for (const o of found) orphanBytes += o.size
+    return { orphans: found.length, orphanBytes }
+  }
+
+  /** Row-less artifacts and temps past the in-flight grace window: one readdir, one stat per candidate. */
+  private async scanOrphans(): Promise<Array<{ file: string; size: number }>> {
+    let names: string[]
+    try {
+      names = await readdir(this.cacheDir)
+    } catch {
+      return []
+    }
+    const indexed = new Set(
+      (this.db.prepare('SELECT hash FROM entries').all() as Array<{ hash: string }>).map(
+        (r) => r.hash,
+      ),
+    )
+    const cutoff = Date.now() - ORPHAN_GRACE_MS
+    const candidates: string[] = []
+    for (const name of names) {
+      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(
+      candidates.map(async (name) => {
+        const file = path.join(this.cacheDir, name)
+        try {
+          const st = await stat(file)
+          if (st.isFile() && st.mtimeMs <= cutoff) found.push({ file, size: st.size })
+        } catch {
+          // Gone between readdir and stat: not an orphan any more.
+        }
+      }),
+    )
+    return found
   }
 
   close(): void {
@@ -2410,19 +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.db.prepare('DELETE FROM runs WHERE ended_at < ?').run(cutoff)
-      this.db.prepare('DELETE FROM invocations WHERE ended_at < ?').run(cutoff)
-      // A config that has not been loaded in 30 days was edited (its key
-      // moved) or its project left; either way the row is dead weight.
-      this.db.prepare('DELETE FROM config_evals WHERE created_at < ?').run(cutoff)
-      this.db.prepare('DELETE FROM config_closures WHERE created_at < ?').run(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
@@ -2442,70 +1836,44 @@ export class Cache implements CacheLayer {
 }
 
 /**
- * Bind a RunRecord to the positional parameters expected by the
- * `insertRun` prepared statement (17 columns). Shared between the
- * single and batched record paths.
- */
-function bindRun(run: RunRecord): SQLQueryBindings[] {
-  return [
-    // The ONE place the no-key sentinel is applied, so the column's
-    // NOT NULL invariant can't be violated from a call site.
-    run.hash ?? '',
-    run.project,
-    run.task,
-    run.status,
-    run.exitCode,
-    run.durationMs,
-    run.forwardArgs ? JSON.stringify(run.forwardArgs) : null,
-    run.startedAt,
-    run.endedAt,
-    run.runId ?? null,
-    run.cpuMs ?? null,
-    run.peakRssBytes ?? null,
-    run.wallclockStartNs !== undefined ? run.wallclockStartNs : null,
-    run.wallclockEndNs !== undefined ? run.wallclockEndNs : null,
-    run.cacheHit === undefined ? null : run.cacheHit ? 1 : 0,
-    run.attempts ?? null,
-  ]
-}
-
-/**
- * Bind an InvocationRecord to the positional parameters of the
- * `insertInvocation` prepared statement (25 columns). Booleans map to
- * 0/1; null-or-bool columns (`dirty`) keep null distinct from 0.
+ * 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 bindInvocation(inv: InvocationRecord): SQLQueryBindings[] {
-  return [
-    inv.runId,
-    inv.command,
-    inv.requestedTasks,
-    inv.cachePolicy,
-    inv.concurrency,
-    inv.flow,
-    inv.startedAt,
-    inv.endedAt,
-    inv.totalDurationMs,
-    inv.taskCount,
-    inv.failedCount,
-    inv.hitCount,
-    inv.hitLocalCount,
-    inv.hitRemoteCount,
-    inv.exitOk ? 1 : 0,
-    inv.commitSha,
-    inv.branch,
-    inv.dirty === null ? null : inv.dirty ? 1 : 0,
-    inv.ci ? 1 : 0,
-    inv.ciProvider,
-    inv.host,
-    inv.os,
-    inv.arch,
-    inv.vxVersion,
-    inv.tags,
-  ]
-}
-
-function splitTaskId(id: string): [string, string] {
-  const i = id.indexOf('#')
-  if (i < 0) return [id, '']
-  return [id.slice(0, i), id.slice(i + 1)]
+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`,
+      )
+    }
+  }
 }