@vzn/vx 0.0.16 → 0.0.21

package/src/cache/cache.ts

@@ -20,23 +20,48 @@
 // 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 { mkdirSync, statSync } from 'node:fs'
-import { mkdir, mkdtemp, rename, rm, stat, utimes } from 'node:fs/promises'
-import os from 'node:os'
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { mkdir, readdir, rename, rm, stat, unlink, writeFile } from 'node:fs/promises'
 import path from 'node:path'
-import { relPosix, UserError, xxh3, xxh3hex } from '../util/index.js'
-import { FsCASBackend } from './cas-backend.js'
-import { extractOutputs, parseTarHeaders, readTarText } from './tar.js'
+import { relPosix, UserError, xxh3, xxh3hex, span } from '../util/index.js'
+import {
+  ArchiveSecurityError,
+  type ExecUsage,
+  extractArtifactStream,
+  scanArtifact,
+  packArtifactBytes,
+  packArtifactStream,
+  planArtifact,
+} from './archive.js'
+import {
+  type CacheEntry,
+  type CacheGetContext,
+  type CacheKeyInput,
+  type CacheLayer,
+  type CacheStats,
+  type CacheStatsOptions,
+  CorruptArtifactError,
+  type IngestMeta,
+  type InvocationRecord,
+  type OutputDirRow,
+  type OutputFileRow,
+  type PruneOptions,
+  type PruneResult,
+  type RunRecord,
+  type SaveArgs,
+  type TaskInputRow,
+} from './layer.js'
+import { bytesOf, decodedTar, STREAM_DECODE_FROM, zstdEncoder } from './zstd.js'
+import { ConfigEvalTable } from './config-evals.js'
+import { FileHashStore } from './file-hashes.js'
+import { OutputIndex } from './output-index.js'
+import { RunHistory } from './run-history.js'
 
 // v17: artifact carries only logs + outputs (stdout + outputs/<rel>).
 // Local and remote layers transport the SAME tar.zst bytes — no
@@ -75,7 +100,51 @@ import { extractOutputs, parseTarHeaders, readTarText } from './tar.js'
 // 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.
-const CACHE_VERSION = 'vx-cache-v24'
+// v25: the ARTIFACT BYTES are wrong in every existing entry, while the
+// key that addresses them is unchanged — the one situation a version
+// bump exists for. Two defects: (a) `packArtifact` staged outputs with
+// `Bun.write`, which does not carry the source mode, so every artifact
+// records 0644 and a cache hit strips the executable bit off any binary
+// or generated script; (b) it packed `--format=ustar`, which splits a
+// name over 100 bytes into prefix+name, and the reader read only `name`
+// — so those entries lost their `outputs/` prefix and were silently
+// dropped from both the restore and the output_files index. Neither is
+// self-healing: the stored bytes/headers are already wrong, so without a
+// new namespace the fixed code would keep replaying them forever.
+// v26: same situation, different producer. A task whose child was killed by
+// a shutdown signal reported `aborted`, but `aborted` did not propagate to
+// dependents — so a dependent ran against PARTIAL outputs, succeeded, and
+// cached what it built. The fold takes the upstream's INPUT key, which a
+// signal does not change, so that entry sits under exactly the key a healthy
+// run derives and replays forever as a green hit. Fixing the propagation
+// stops new poison but cannot reach entries already written, and a
+// `LayeredCache` uploads them, so the reach is a whole team's shared cache
+// rather than one developer's disk. Pre-alpha, so one cold rebuild is the
+// cheap side of that trade.
+export const CACHE_VERSION = 'vx-cache-v27'
+
+/**
+ * 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
+
+export interface SchemaReset {
+  from: string
+  to: string
+}
+
+/** 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.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).
@@ -94,578 +163,74 @@ const CACHE_VERSION = 'vx-cache-v24'
 //        passed under identical inputs is nondeterministic by definition;
 //        no cross-run inference needed). Nullable; NULL for a once-run
 //        task. Analytics-only — the cache KEY is unchanged.
-const SCHEMA_VERSION = 'v23'
+//   v24: file_hashes.ctime_ms + .ino — the stat memo's guard against a
+//        content change that PRESERVES mtime (`tar -x`, `cp -p`,
+//        `rsync --times`, SOURCE_DATE_EPOCH). (mtime, size) alone
+//        returned the previous run's digest for different bytes, i.e. a
+//        stale cache hit. `utimes` cannot suppress ctime unprivileged
+//        and an atomic write-then-rename changes the inode, so the two
+//        together close it; git's index keys on ctime+ino+dev for the
+//        same reason. Both come free from the stat already taken. The
+//        cache KEY derivation is unchanged (CACHE_VERSION not bumped) —
+//        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.
+//   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).
+export const SCHEMA_VERSION = 'v26'
 
 /**
- * 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).
+ * SQL predicate selecting `runs` rows that record an EXECUTION.
  *
- * 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,
-}
-
-/**
- * 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.
+ * Every non-group, non-aborted outcome of a run gets a row, so the header's
+ * `task_count` matches `COUNT(*)` and the run-detail timeline is complete.
+ * But a `skipped` row is a task the run never executed — its upstream failed,
+ * so it has no exit of its own, no duration, and made no cache decision.
+ * Counting it in a RATE or a MEAN dilutes that figure with a non-event: a
+ * task skipped as often as it succeeds reads 50% success, and a zero-duration
+ * row drags every average toward zero.
  *
- * Throws a {@link UserError} on an unknown layer, an unknown flag, a
- * duplicated flag, a missing colon, or a repeated layer.
+ * Lives here, beside the schema, because the same figure is computed in more
+ * than one place (`Cache.stats` and the run-history queries both answer
+ * "runs in the last 24h") and two copies of a rule are how they drift apart.
  */
-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>
-  /**
-   * 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>
-  /**
-   * 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 {
-  hash: string
-  taskId: string
-  command: string
-  exitCode: number
-  durationMs: number
-  outputFiles: string[]
-  /** 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 {
-  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 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
-}
+export const EXECUTED_RUNS_SQL = "status <> 'skipped'"
 
 /**
- * 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.
+ * SQL predicate selecting `runs` rows that recorded a cache key. `hash` is
+ * `''` for an outcome that never derived one (see {@link RunRecord.hash}),
+ * and `''` is not a key: it can neither corroborate flakiness nor say the
+ * inputs changed. Mirrors the `hash <> ''` guards in the cloud analytics copy.
  */
-export interface OutputFileRow {
-  path: string
-  size: number
-  mode: number
-  mtimeMs: number
-}
+export const KEYED_RUNS_SQL = "hash <> ''"
 
 /**
- * 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
-}
-
-/** 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[]
-}
-
-/**
- * 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'
-  }
-}
-
-/**
- * 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.
- */
-export 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.
- *
- * 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).
- */
-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 with a hard output ceiling. `trusted` marks a
- * locally-produced artifact (always carries a declared content size); an
- * UNTRUSTED (remote-sourced) frame that declares no content size is refused,
- * since our producer and the Turbo servers we interop with always write one —
- * a sizeless frame from the network is the shape a bomb takes to dodge the
- * pre-decompress check.
+ * 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.
  */
-async function zstdDecompressBounded(
-  compressed: Uint8Array,
-  hash: string,
-  trusted: boolean,
-): Promise<Uint8Array> {
-  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)`,
-    )
-  }
-  if (declared === null && !trusted) {
-    throw new CorruptArtifactError(hash, 'remote zstd frame carries no declared content size')
-  }
-  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)`,
-    )
-  }
-  return out
-}
-
-export interface CacheLayer {
-  key(input: CacheKeyInput): Promise<string>
-  get(hash: string, ctx?: CacheGetContext): Promise<CacheEntry | null>
-  /**
-   * 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>
-  /**
-   * 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
-    entry: Omit<CacheEntry, 'hash' | 'storedAt' | 'outputFiles'>
-    projectDir: string
-    outputFiles: string[]
-    /**
-     * 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(): 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
-}
+export const WORKSPACE_OUTPUT_PREFIX = 'workspace-outputs/'
 
-/**
- * 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]
+// 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'
 
 interface EntryRow {
   hash: string
@@ -678,23 +243,51 @@ interface EntryRow {
   stdout: string
   created_at: number
   accessed_at: number
+  cpu_ms: number | null
+  peak_rss_bytes: number | null
+}
+
+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 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 } : {}),
+  }
 }
 
 export class Cache implements CacheLayer {
+  /** This IS the local layer — there is nothing slower behind it. */
+  readonly hasRemote = false
+
   private readonly db: Database
   private readonly insertEntry: ReturnType<Database['prepare']>
   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 deleteOutputFiles: 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.
@@ -706,6 +299,16 @@ export class Cache implements CacheLayer {
   private readonly read: boolean
   private readonly write: boolean
 
+  /**
+   * 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
+
   constructor(
     private readonly cacheDir: string,
     localPolicy: { read: boolean; write: boolean } = { read: true, write: true },
@@ -717,6 +320,15 @@ export class Cache implements CacheLayer {
     // 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')
@@ -737,14 +349,17 @@ export class Cache implements CacheLayer {
     // 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`.
+    // 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.
     const meta = this.db.prepare("SELECT value FROM schema_meta WHERE key = 'version'").get() as
       | { value: string }
       | undefined
     if (meta && meta.value !== SCHEMA_VERSION) {
+      this.schemaReset = { from: meta.value, to: SCHEMA_VERSION }
       this.db.exec(
-        'DROP TABLE IF EXISTS entries; DROP TABLE IF EXISTS runs; DROP TABLE IF EXISTS file_hashes; DROP TABLE IF EXISTS output_files; DROP TABLE IF EXISTS invocations; DROP TABLE IF EXISTS run_task_inputs; DROP TABLE IF EXISTS entry_inputs;',
+        'DROP TABLE IF EXISTS 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) {
@@ -753,6 +368,17 @@ export class Cache implements CacheLayer {
         .run(SCHEMA_VERSION)
     }
 
+    // Cached config evaluations (workspace/config-cache.ts): the validated
+    // config as JSON, keyed by everything the evaluation could observe. A
+    // separate exec so the artifact schema above stays byte-identical.
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS config_evals (
+        key        TEXT PRIMARY KEY,
+        json       TEXT NOT NULL,
+        created_at INTEGER NOT NULL
+      );
+    `)
+
     this.db.exec(`
       -- stdout/stderr live in the <hash>.tar.zst artifact, not here
       -- (v14+) — so they survive remote round-trips. The entries
@@ -768,10 +394,15 @@ 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,
+        -- '' when the outcome derived no cache key (skipped / persistent).
+        -- Every reader that must not mistake it for a key guards hash != ''.
         hash                TEXT NOT NULL,
         project             TEXT NOT NULL,
         task                TEXT NOT NULL,
@@ -792,13 +423,37 @@ 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
       );
-      CREATE INDEX IF NOT EXISTS runs_hash       ON runs(hash);
+      -- 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
@@ -808,6 +463,8 @@ export class Cache implements CacheLayer {
         path         TEXT PRIMARY KEY,
         mtime_ms     INTEGER NOT NULL,
         size_bytes   INTEGER NOT NULL,
+        ctime_ms     INTEGER NOT NULL,
+        ino          INTEGER NOT NULL,
         content_hash TEXT NOT NULL,
         seen_at      INTEGER NOT NULL
       );
@@ -829,6 +486,27 @@ export class Cache implements CacheLayer {
         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
+      -- config_evals (2026-09-03).
+      CREATE TABLE IF NOT EXISTS config_closures (
+        config_path TEXT PRIMARY KEY,
+        files_json  TEXT NOT NULL,
+        created_at  INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS output_dirs (
+        entry_hash  TEXT NOT NULL,
+        path        TEXT NOT NULL,
+        mtime_ms    INTEGER NOT NULL,
+        PRIMARY KEY (entry_hash, path),
+        FOREIGN KEY (entry_hash) REFERENCES entries(hash) ON DELETE CASCADE
+      );
       -- v22 (Tier 3): one header row per vx-run invocation. The runs
       -- table is per-task; this is the per-invocation record that
       -- carries git/CI/host context, the command, tags, and run-level
@@ -885,41 +563,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.
@@ -927,111 +586,37 @@ 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, content_hash FROM file_hashes WHERE path = ?',
-    )
-    this.upsertFileHash = this.db.prepare(`
-      INSERT INTO file_hashes(path, mtime_ms, size_bytes, content_hash, seen_at)
-      VALUES (?, ?, ?, ?, ?)
-      ON CONFLICT(path) DO UPDATE SET
-        mtime_ms     = excluded.mtime_ms,
-        size_bytes   = excluded.size_bytes,
-        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 = ?')
+    // The slices: each owns its statements over this handle and its table(s);
+    // the schema above is the one place every table is declared.
+    this.files = new FileHashStore(this.db, cacheDir)
+    this.configEvals = new ConfigEvalTable(this.db, localPolicy)
+    this.outputs = new OutputIndex(this.db)
+    this.history = new RunHistory(this.db)
   }
 
-  /**
-   * 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)` match the current stat, we reuse the
-   * stored content_hash (a memory + SQLite lookup, no disk read).
-   * Otherwise we read + hash + upsert.
-   *
-   * 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 never diverge —
-   * a file's key contribution can't flip across dirty↔clean
-   * transitions.
-   */
-  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
-    const row = this.selectFileHash.get(filePath) as
-      | { mtime_ms: number; size_bytes: number; content_hash: string }
-      | undefined
-    if (row && row.mtime_ms === mtimeMs && row.size_bytes === size) {
-      return row.content_hash
-    }
-    const ch = await this.hashFileFromDisk(filePath)
-    this.upsertFileHash.run(filePath, mtimeMs, size, ch, Date.now())
-    return ch
+  // --- config evaluations: `ConfigEvalStore`, delegated to `ConfigEvalTable` ---
+  getConfigEval(key: string): string | null {
+    return this.configEvals.getConfigEval(key)
   }
-
-  /**
-   * 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')
+  getConfigClosures(configPaths: readonly string[]): Map<string, string[]> {
+    return this.configEvals.getConfigClosures(configPaths)
   }
-
-  /**
-   * 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.
-   */
-  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.
-    }
-    this.objectFormat = detected
-    return detected
+  putConfigClosure(configPath: string, files: readonly string[]): void {
+    this.configEvals.putConfigClosure(configPath, files)
+  }
+  getConfigEvals(keys: readonly string[]): Map<string, string> {
+    return this.configEvals.getConfigEvals(keys)
+  }
+  putConfigEval(key: string, json: string): void {
+    this.configEvals.putConfigEval(key, json)
+  }
+  // --- input file hashes: delegated to `FileHashStore` (see file-hashes.ts) ---
+  hashFile(filePath: string): Promise<string> {
+    return this.files.hashFile(filePath)
+  }
+  hashFiles(paths: readonly string[]): Promise<Map<string, string>> {
+    return this.files.hashFiles(paths)
   }
-
   async key(input: CacheKeyInput): Promise<string> {
     // Seed-chained xxHash3: each step folds one field into the
     // running digest via `xxh3(part, prevDigest)`. Equivalent to the
@@ -1098,14 +683,27 @@ export class Cache implements CacheLayer {
       }
     }
 
+    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
-    // mtime+size memo (no read), then a full in-process blob-OID
-    // computation. All three produce identical bytes for identical
-    // content. The fold order is locked to `sortedInputs` so results
-    // are stable across runs.
+    // 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)),
     )
@@ -1128,12 +726,29 @@ 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 this.readEntry(hash)
+  }
+
+  /**
+   * Read an entry BYPASSING the local read gate. The gate means "don't
+   * serve hits out of the PRE-EXISTING local cache" — it must not throw
+   * away bytes this run just downloaded. `LayeredCache` calls this to
+   * deliver an artifact it ingested from the remote; under
+   * `--cache=local:,remote:rw` the gated `get` returned null for the row
+   * `ingest` had just written, so the task re-executed and re-uploaded on
+   * every single run.
+   */
+  getIngested(hash: string): Promise<CacheEntry | null> {
+    return this.readEntry(hash)
+  }
+
+  private async readEntry(hash: string): Promise<CacheEntry | null> {
     const row = this.selectEntry.get(hash) as EntryRow | undefined
     if (!row) return null
 
     // 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
@@ -1147,18 +762,45 @@ export class Cache implements CacheLayer {
     // for four up-to-date hits on ~70 MB binaries). restoreOutputs
     // reads the artifact itself, only when extraction actually runs.
     const fileRows = this.loadOutputFilesBatch([hash]).get(hash) ?? []
+    const entry = entryOf(row, fileRows)
+    entry.outputDirRows = this.loadOutputDirsBatch([hash]).get(hash) ?? []
+    return entry
+  }
 
-    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),
-      stdout: row.stdout,
-      storedAt: new Date(row.created_at).toISOString(),
-      source: 'local',
+  /**
+   * `get` for many hashes at once: one `entries` query and one
+   * `output_files` query per chunk instead of two per hash, with the
+   * artifact-existence stats in flight together. Same answers as N calls
+   * to `get` — a hash whose artifact is gone is simply absent from the map.
+   * The up-front short-circuit probe is the caller; per-hit `get` stays for
+   * the lazy path.
+   */
+  async getMany(hashes: readonly string[]): Promise<Map<string, CacheEntry>> {
+    const out = new Map<string, CacheEntry>()
+    if (!this.read || hashes.length === 0) return out
+    const rows: EntryRow[] = []
+    for (let i = 0; i < hashes.length; i += 900) {
+      const chunk = hashes.slice(i, i + 900)
+      const placeholders = chunk.map(() => '?').join(',')
+      rows.push(
+        ...(this.db
+          .query(`SELECT * FROM entries WHERE hash IN (${placeholders})`)
+          .all(...(chunk as readonly SQLQueryBindings[])) as EntryRow[]),
+      )
     }
+    if (rows.length === 0) return out
+    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)
+    const dirRows = this.loadOutputDirsBatch(liveHashes)
+    for (const row of live) {
+      this.touched.add(row.hash)
+      const entry = entryOf(row, fileRows.get(row.hash) ?? [])
+      entry.outputDirRows = dirRows.get(row.hash) ?? []
+      out.set(row.hash, entry)
+    }
+    return out
   }
 
   // Existence probe: SQL row + artifact-on-disk check, no byte reads
@@ -1167,7 +809,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.
@@ -1177,74 +819,36 @@ 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
-    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)
   }
 
+  async recordOutputDirs(
+    hash: string,
+    projectDir: string,
+    prefixes: readonly string[],
+  ): Promise<void> {
+    await this.outputs.recordOutputDirs(hash, projectDir, prefixes)
+  }
+  loadOutputDirsBatch(hashes: readonly string[]): Map<string, OutputDirRow[]> {
+    return this.outputs.loadOutputDirsBatch(hashes)
+  }
+  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 tar extraction — no fork+exec on the hot path
+    // In-process extraction — no fork+exec on the hot path
     // (~5-10ms reclaimed per hit vs the prior subprocess `tar -xf`).
     //
     // The "tree is already current" skip-everything check happens at
@@ -1256,52 +860,84 @@ export class Cache implements CacheLayer {
     // path — they're surfaced via `get()` for the orchestrator to
     // replay through the logger.
     const src = this.tarPath(hash)
-    if (!(await Bun.file(src).exists())) return
-    const compressed = await Bun.file(src).bytes()
-    // Local artifact (already validated at ingest): trusted, so a missing
-    // declared size is allowed; the oversize ceiling still applies.
-    const tarBytes = await zstdDecompressBounded(compressed, hash, true)
-
-    const headers = parseTarHeaders(tarBytes)
-    if (
-      !headers.some(
-        (h) => h.name.startsWith('outputs/') || h.name.startsWith(WORKSPACE_OUTPUT_PREFIX),
-      )
-    ) {
-      return
+    // The caller already committed to this hit and WIPED the declared
+    // outputs, so returning quietly here would report a green cache hit over
+    // an emptied output tree. The artifact existed when `get()` probed it, so
+    // its absence now means something removed it underneath us (a concurrent
+    // `vx cache prune` is the documented way) — fail loud; the task re-runs.
+    const endExists = span('restore: exists')
+    const exists = await Bun.file(src).exists()
+    endExists()
+    if (!exists) {
+      throw new CorruptArtifactError(hash, 'artifact file vanished before restore')
+    }
+    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
+    // same truncated expectation against the same truncated tree and agrees
+    // forever. Refuse instead of silently under-restoring — checked before
+    // anything is renamed into place.
+    const rows = this.loadOutputFilesBatch([hash]).get(hash) ?? []
+    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) {
+        throw new CorruptArtifactError(
+          hash,
+          `artifact is missing ${missing.length} recorded output(s): ${missing.slice(0, 3).join(', ')}`,
+        )
+      }
     }
 
-    await extractOutputs(tarBytes, projectDir, workspaceRoot)
-
-    // Re-sync restored files' mtimes to the manifest rows (extract set
-    // them from the tar's SECOND-precision headers). After this, disk
-    // matches the rows at millisecond precision, so isOutputsCurrent
-    // compares exactly — and any later edit moves the mtime off the
-    // recorded historical value and is detected.
-    const rows = this.loadOutputFilesBatch([hash]).get(hash)
-    if (rows !== undefined) {
-      await Promise.all(
-        rows.map(async (r) => {
-          try {
-            const abs = r.path.startsWith(WORKSPACE_OUTPUT_PREFIX)
-              ? path.join(workspaceRoot ?? projectDir, r.path.slice(WORKSPACE_OUTPUT_PREFIX.length))
-              : path.join(projectDir, r.path)
-            const t = r.mtimeMs / 1000
-            await utimes(abs, t, t)
-          } catch {
-            // File absent from this extract (or unwritable) — the next
-            // probe simply restores again; never fail a hit over mtimes.
-          }
-        }),
-      )
+    // One tar reader and one extractor either way; only the decode differs
+    // by size. A large artifact is decoded and read as it streams, so the
+    // restore costs a chunk of memory, not 4× the artifact (measured
+    // 2026-09-03 on 150 MiB: +644 MiB in memory, +49 MiB streamed, same
+    // wall time). A small one is decoded in one call: the stream setup
+    // costs ~35 µs per artifact, which is 4% of the headline restore row
+    // 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 {
+      // 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)
+      await extractArtifactStream(tar, projectDir, workspaceRoot, verify)
+    } catch (err) {
+      if (err instanceof ArchiveSecurityError || err instanceof CorruptArtifactError) 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.
+      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.`,
+        )
+      }
+      throw new CorruptArtifactError(hash, 'artifact is not a readable archive', err)
+    } finally {
+      endExtract()
     }
   }
 
   async save(args: {
     hash: string
-    entry: Omit<CacheEntry, 'hash' | 'storedAt' | 'outputFiles'>
+    /** See `CacheLayer.save` — `exitCode` is not a caller's to supply. */
+    entry: Omit<CacheEntry, 'hash' | 'storedAt' | 'outputFiles' | 'exitCode'>
     projectDir: string
     outputFiles: string[]
+    /** See `CacheLayer.save`. */
+    skipLocalWrite?: boolean
     workspaceOutputFiles?: string[]
     workspaceRoot?: string
     inputComponents?: readonly TaskInputRow[]
@@ -1324,23 +960,17 @@ export class Cache implements CacheLayer {
     // still uploads to remote — it calls `packArtifact` itself to get
     // the bytes, since there's no local artifact to read off disk.
     if (!this.write) return
-    const compressed = await this.packArtifact(args)
-    await this.writeArtifactAndIndex(
-      args.hash,
-      compressed,
-      {
-        taskId: args.entry.taskId,
-        command: args.entry.command,
-        durationMs: args.entry.durationMs,
-        ...(args.inputComponents !== undefined ? { inputComponents: args.inputComponents } : {}),
-      },
-      // Save-path rows get millisecond mtimes from a fresh stat (tar
-      // headers carry only seconds) — see the row loop for the guard.
-      {
-        projectDir: args.projectDir,
-        ...(args.workspaceRoot !== undefined ? { workspaceRoot: args.workspaceRoot } : {}),
-      },
-    )
+    if (args.skipLocalWrite === true) return
+    await mkdir(this.cacheDir, { recursive: true })
+    const endPack = span('save: pack')
+    const compressed = await this.packArtifactToTemp(this.tempPath(args.hash), args)
+    endPack()
+    await this.writeArtifactAndIndex(args.hash, compressed, {
+      taskId: args.entry.taskId,
+      command: args.entry.command,
+      durationMs: args.entry.durationMs,
+      ...(args.inputComponents !== undefined ? { inputComponents: args.inputComponents } : {}),
+    })
   }
 
   /**
@@ -1357,8 +987,8 @@ 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)
+  packArtifactBytes(args: SaveArgs): Promise<Uint8Array> {
+    return this.packArtifact(args)
   }
 
   async ingest(hash: string, compressed: Uint8Array, meta: IngestMeta): Promise<void> {
@@ -1366,179 +996,201 @@ export class Cache implements CacheLayer {
   }
 
   /**
-   * Stage stdout + outputs, tar them, zstd-compress, return the bytes.
-   * No disk write to the final cache path — that's the index step's
-   * job. Pure transform, so `ingest()` can skip this and just hand its
-   * remote-supplied bytes straight to `writeArtifactAndIndex`.
+   * 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`).
+   */
+  /** Archive name → absolute source path for every declared output. */
+  private outputsOf(args: {
+    projectDir: string
+    outputFiles: string[]
+    workspaceOutputFiles?: string[]
+    workspaceRoot?: string
+  }): Map<string, string> {
+    const outputs = new Map<string, string>()
+    for (const f of args.outputFiles) {
+      outputs.set(`outputs/${path.relative(args.projectDir, f)}`, f)
+    }
+    // Caller passes workspaceRoot whenever workspaceOutputFiles is
+    // non-empty; the rels are root-anchored by construction.
+    for (const f of args.workspaceOutputFiles ?? []) {
+      outputs.set(`${WORKSPACE_OUTPUT_PREFIX}${path.relative(args.workspaceRoot!, f)}`, f)
+    }
+    return outputs
+  }
+
+  /**
+   * 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.
    */
   private async packArtifact(args: {
-    hash: string
-    entry: Omit<CacheEntry, 'hash' | 'storedAt' | 'outputFiles'>
+    entry: Omit<CacheEntry, 'hash' | 'storedAt' | 'outputFiles' | 'exitCode'>
     projectDir: string
     outputFiles: string[]
     workspaceOutputFiles?: string[]
     workspaceRoot?: string
   }): Promise<Uint8Array> {
-    const wsOutputFiles = args.workspaceOutputFiles ?? []
-    const stage = await mkdtemp(path.join(os.tmpdir(), 'vx-save-'))
+    // 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 planArtifact({
+      stdout: args.entry.stdout ?? '',
+      outputs: this.outputsOf(args),
+      exec: usageOfEntry(args.entry),
+    })
+    if (plan.size <= STREAM_DECODE_FROM)
+      return await Bun.zstdCompress(await packArtifactBytes(plan))
+    return bytesOf(packArtifactStream(plan).pipeThrough(zstdEncoder()))
+  }
+
+  /**
+   * Pack for the local save. A large artifact is read from disk as it is
+   * written and compressed as a stream straight into the temp, so it
+   * never sits in memory (measured 2026-09-03 on a 150 MiB output: +705
+   * MiB before). The streamed compressor is ~2.4× the one-call cost per
+   * byte and a stream costs ~35 µs to set up, so a small artifact is
+   * packed in memory and compressed in one call — returned as bytes,
+   * nothing written yet.
+   */
+  private async packArtifactToTemp(
+    tmpPath: string,
+    args: Parameters<Cache['packArtifact']>[0],
+  ): Promise<Uint8Array | { tmpPath: string }> {
+    const plan = await planArtifact({
+      stdout: args.entry.stdout ?? '',
+      outputs: this.outputsOf(args),
+      exec: usageOfEntry(args.entry),
+    })
+    if (plan.size <= STREAM_DECODE_FROM)
+      return await Bun.zstdCompress(await packArtifactBytes(plan))
+    const sink = Bun.file(tmpPath).writer()
     try {
-      if (args.outputFiles.length > 0) {
-        const stageOutputs = path.join(stage, 'outputs')
-        await Promise.all(
-          args.outputFiles.map(async (f) => {
-            const rel = path.relative(args.projectDir, f)
-            const dest = path.join(stageOutputs, rel)
-            // Bun.write creates parent dirs as needed.
-            await Bun.write(dest, Bun.file(f))
-          }),
-        )
+      for await (const chunk of packArtifactStream(plan).pipeThrough(zstdEncoder())) {
+        await sink.write(chunk)
       }
-      if (wsOutputFiles.length > 0) {
-        // Caller passes workspaceRoot whenever workspaceOutputFiles is
-        // non-empty; the rels are root-anchored by construction.
-        const stageWs = path.join(stage, 'workspace-outputs')
-        await Promise.all(
-          wsOutputFiles.map(async (f) => {
-            const rel = path.relative(args.workspaceRoot!, f)
-            await Bun.write(path.join(stageWs, rel), Bun.file(f))
-          }),
-        )
-      }
-      // stdout is ALWAYS present in the artifact, even if empty, so the
-      // archive layout is predictable: a successful read finds `stdout`
-      // and zero-or-more `outputs/<rel>` / `workspace-outputs/<rel>`
-      // entries.
-      await Bun.write(path.join(stage, 'stdout'), args.entry.stdout ?? '')
-
-      const topLevel: string[] = ['stdout']
-      if (wsOutputFiles.length > 0) topLevel.unshift('workspace-outputs')
-      if (args.outputFiles.length > 0) topLevel.unshift('outputs')
-
-      // `--format=ustar` forces strict POSIX ustar — no PAX extended-
-      // header records. BSD tar (macOS default) emits PAX per entry
-      // by default for xattrs / mtime-nanos; those records would
-      // otherwise show up as junk `PaxHeaders/<name>` entries in our
-      // restored trees. GNU tar also accepts the flag (no-op on its
-      // side). Names > 100 chars still work via ustar's prefix+name
-      // (255 chars) or GNU longname fallback if the tar binary
-      // chooses to emit one.
-      const proc = Bun.spawn(['tar', '--format=ustar', '-cf', '-', '-C', stage, ...topLevel], {
-        stdout: 'pipe',
-        stderr: 'pipe',
-        // COPYFILE_DISABLE blocks Apple's copyfile() from attaching
-        // xattrs to staged files via inherited child copies; tar then
-        // has nothing to emit AppleDouble for.
-        env: { ...process.env, COPYFILE_DISABLE: '1' },
-      })
-      const [tarBytes, stderrText] = await Promise.all([
-        new Response(proc.stdout).bytes(),
-        new Response(proc.stderr).text(),
-      ])
-      await proc.exited
-      if (proc.exitCode !== 0) {
-        throw new Error(`save: tar exited ${proc.exitCode}: ${stderrText.trim()}`)
-      }
-      return await Bun.zstdCompress(tarBytes)
-    } finally {
-      await rm(stage, { recursive: true, force: true })
+    } catch (err) {
+      // An output that vanished or changed shape between the plan's stat
+      // and its read: the partial temp must not outlive the failure.
+      await sink.end()
+      await unlink(tmpPath).catch(() => undefined)
+      throw err
     }
+    await sink.end()
+    return { tmpPath }
   }
 
   /**
-   * Atomically write `compressed` to `<hash>.tar.zst` and (re)build
-   * the entries + output_files SQL rows from the tar headers. Shared
-   * by `save()` (we just packed the bytes) and `ingest()` (we got
-   * them from the remote layer).
+   * 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
+   *  race on the rename. */
+  private tempPath(hash: string): string {
+    return `${this.tarPath(hash)}.tmp-${process.pid}-${process.hrtime.bigint()}-${Math.random().toString(36).slice(2, 10)}`
+  }
+
   private async writeArtifactAndIndex(
     hash: string,
-    compressed: Uint8Array,
+    compressed: Uint8Array | { tmpPath: string },
     meta: IngestMeta,
-    statBase?: { projectDir: string; workspaceRoot?: string },
   ): Promise<void> {
     // Validate BEFORE anything touches the final path. `ingest()` feeds
     // us 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
-    // `output_files` rows: same headers extractOutputs will see on
+    // `output_files` rows: same headers the restore will see on
     // restore, so the size/mode/mtime fingerprint we store matches
     // what isOutputsCurrent will compare against post-restore.
-    let tarBytes: Uint8Array
+    const finalPath = this.tarPath(hash)
+    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`).
+      // The final path is still untouched until the archive has passed.
+      // node's writeFile, not Bun.write: the latter copies the buffer first
+      // (measured on 150 MiB: +151 MiB and 33 ms against +0 and 21 ms).
+      const endWrite = span('save: write temp')
+      await writeFile(tmpPath, compressed)
+      endWrite()
+    } else {
+      // `save` 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
       // pulled from a remote. Refuse a bomb (declared or sizeless) before it
       // can expand into memory.
-      tarBytes = await zstdDecompressBounded(compressed, hash, false)
+      const source =
+        compressed instanceof Uint8Array && compressed.byteLength <= STREAM_DECODE_FROM
+          ? compressed
+          : Bun.file(tmpPath)
+      const endScan = span('save: scan')
+      scanned = await scanArtifact(await decodedTar(source, hash))
+      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')
+      }
     } catch (err) {
-      if (err instanceof CorruptArtifactError) throw err
-      throw new CorruptArtifactError(hash, 'zstd decompression failed', err)
+      await unlink(tmpPath).catch(() => undefined)
+      if (err instanceof ArchiveSecurityError || err instanceof CorruptArtifactError) throw err
+      throw new CorruptArtifactError(hash, 'artifact is not a readable archive', err)
     }
-    const headers = parseTarHeaders(tarBytes)
-    // v17 invariant: every artifact carries a `stdout` entry. Its
-    // absence means the bytes decompressed but aren't a vx artifact.
-    if (!headers.some((h) => h.name === 'stdout' && !h.isDir)) {
-      throw new CorruptArtifactError(hash, 'missing stdout entry')
-    }
-
-    const finalPath = this.tarPath(hash)
-    // 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 race on the rename.
-    const tmpPath = `${finalPath}.tmp-${process.pid}-${process.hrtime.bigint()}-${Math.random().toString(36).slice(2, 10)}`
-    await mkdir(this.cacheDir, { recursive: true })
-    await Bun.write(tmpPath, compressed)
+    const { entries } = scanned
     // POSIX rename atomically REPLACES the destination if it exists,
     // so we don't need a pre-rm. The pre-rm was actively harmful —
     // it opened a race window where writer B could delete writer A's
     // just-renamed file BEFORE A's subsequent stat, producing a
     // spurious ENOENT. The rename itself preserves the "either-or"
     // semantics for concurrent readers.
+    const endRename = span('save: rename')
     await rename(tmpPath, finalPath)
+    endRename()
 
-    const totalBytes = compressed.byteLength
+    const totalBytes =
+      compressed instanceof Uint8Array ? compressed.byteLength : Bun.file(finalPath).size
     const outputFileRows: Array<[string, number, number, number]> = []
     // Per-output-file fingerprint rows feed the skip-restore check.
     // Row paths: project entries store the bare rel (`outputs/`
     // stripped); workspace entries keep the full
     // `workspace-outputs/<rel>` name as the namespace discriminator.
-    for (const h of headers) {
-      if (h.isDir) continue
+    //
+    // Mode and MILLISECOND mtime come from the artifact's own sidecar
+    // (`.vx-meta.json`), written from a stat taken while packing. Both
+    // paths — save and remote ingest — therefore index the same values,
+    // and `restoreOutputs` materialises exactly them, so
+    // `isOutputsCurrent` compares equal at ms precision straight after a
+    // restore. (Tar headers carry seconds, which is why the save path
+    // used to need a second stat pass the ingest path could not have.)
+    for (const e of entries) {
       let rowPath: string | null = null
-      if (h.name.startsWith('outputs/')) {
-        const rel = h.name.slice('outputs/'.length)
+      if (e.name.startsWith('outputs/')) {
+        const rel = e.name.slice('outputs/'.length)
         if (rel.length > 0) rowPath = rel
-      } else if (h.name.startsWith(WORKSPACE_OUTPUT_PREFIX)) {
-        if (h.name.length > WORKSPACE_OUTPUT_PREFIX.length) rowPath = h.name
+      } else if (e.name.startsWith(WORKSPACE_OUTPUT_PREFIX)) {
+        if (e.name.length > WORKSPACE_OUTPUT_PREFIX.length) rowPath = e.name
       }
       if (rowPath === null) continue
-      let mtimeMs = Math.floor(h.mtimeMs)
-      // Save path only (ingest has no filesystem to consult): tar
-      // headers truncate mtimes to SECONDS, which is what made the
-      // skip-restore check blind to same-second same-size edits. A
-      // fresh stat refines the row to millisecond precision — but only
-      // when the size still matches the packed header, so the row
-      // always describes the ARTIFACT's bytes; a file mutated between
-      // pack and stat keeps the coarse header time (degraded, not
-      // wrong). restoreOutputs re-syncs disk mtimes to these rows.
-      if (statBase !== undefined) {
-        try {
-          const abs = rowPath.startsWith(WORKSPACE_OUTPUT_PREFIX)
-            ? path.join(
-                statBase.workspaceRoot ?? statBase.projectDir,
-                rowPath.slice(WORKSPACE_OUTPUT_PREFIX.length),
-              )
-            : path.join(statBase.projectDir, rowPath)
-          const st = await stat(abs)
-          if (st.size === h.size) mtimeMs = Math.floor(st.mtimeMs)
-        } catch {
-          // stat failed — keep the header-seconds fallback.
-        }
-      }
-      outputFileRows.push([rowPath, h.size, h.mode & 0o777, mtimeMs])
+      outputFileRows.push([rowPath, e.size, e.mode & 0o777, Math.floor(e.mtimeMs)])
     }
-    const stdoutText = readTarText(tarBytes, headers, 'stdout')
+    const stdoutText = scanned.stdout
 
     const [project, task] = splitTaskId(meta.taskId)
     const now = Date.now()
@@ -1549,8 +1201,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(() => {
@@ -1559,19 +1210,23 @@ export class Cache implements CacheLayer {
         project,
         task,
         meta.command,
-        0, // exitCode: we never cache failures
+        // exitCode. Pinned, not supplied: vx caches only successes, and neither
+        // `save` nor `ingest` accepts one (see their arg types). The column
+        // stays because the READ side still defends against a non-zero value —
+        // a row from a foreign or hand-edited cache.db classifies the hit
+        // `failed` rather than laundering a broken build into a green run.
+        0,
         meta.durationMs,
         totalBytes,
         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) {
@@ -1580,7 +1235,9 @@ export class Cache implements CacheLayer {
         }
       }
     })
+    const endTx = span('save: index tx')
     tx()
+    endTx()
   }
 
   /** Apply the deferred accessed_at bumps in one statement. */
@@ -1611,64 +1268,36 @@ 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(): CacheStats {
+  stats(opts: CacheStatsOptions = {}): CacheStats {
     this.flushAccessed()
+    const project = opts.project
+    const scoped = project !== undefined
+    const scopeParams: string[] = project === undefined ? [] : [project]
     const aggregate = this.db
-      .prepare('SELECT COUNT(*) AS n, COALESCE(SUM(size_bytes), 0) AS bytes FROM entries')
-      .get() as { n: number; bytes: number }
+      .prepare(
+        `SELECT COUNT(*) AS n, COALESCE(SUM(size_bytes), 0) AS bytes FROM entries${
+          scoped ? ' WHERE project = ?' : ''
+        }`,
+      )
+      .get(...scopeParams) as { n: number; bytes: number }
     const since = Date.now() - 24 * 60 * 60 * 1000
     const runs = this.db
       .prepare(
-        "SELECT COUNT(*) AS total, COALESCE(SUM(CASE WHEN status IN ('cache-hit', 'cache-hit-remote') THEN 1 ELSE 0 END), 0) AS hits FROM runs WHERE started_at >= ?",
+        `SELECT COUNT(*) AS total, COALESCE(SUM(CASE WHEN status IN ('cache-hit', 'cache-hit-remote') THEN 1 ELSE 0 END), 0) AS hits FROM runs WHERE started_at >= ? AND ${EXECUTED_RUNS_SQL}${
+          scoped ? ' AND project = ?' : ''
+        }`,
       )
-      .get(since) as { total: number; hits: number }
+      .get(since, ...scopeParams) as { total: number; hits: number }
     return {
       entryCount: aggregate.n,
       totalBytes: aggregate.bytes,
@@ -1679,7 +1308,7 @@ export class Cache implements CacheLayer {
 
   async prune(options: PruneOptions): Promise<PruneResult> {
     this.flushAccessed()
-    const { olderThanMs, maxBytes } = options
+    const { olderThanMs, maxBytes, dryRun = false } = options
     if (olderThanMs === undefined && maxBytes === undefined) {
       throw new Error('prune: pass at least one of `olderThanMs` or `maxBytes`')
     }
@@ -1726,6 +1355,15 @@ 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 (dryRun) {
+      const orphans = await this.orphanStats()
+      return {
+        evicted: victims.size,
+        bytesFreed,
+        orphans: orphans.orphans,
+        orphanBytes: orphans.orphanBytes,
+      }
+    }
     if (victims.size > 0) {
       const hashes = [...victims]
       this.db.transaction(() => {
@@ -1739,7 +1377,83 @@ 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(): Promise<{ orphans: number; orphanBytes: number }> {
+    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 }
+  }
+
+  /** 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) {
+      if (name.indexOf('.tar.zst.tmp-') > 0) {
+        candidates.push(name)
+      } else if (name.endsWith('.tar.zst') && !indexed.has(name.slice(0, -'.tar.zst'.length))) {
+        candidates.push(name)
+      }
+    }
+    const 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 {
@@ -1747,15 +1461,30 @@ export class Cache implements CacheLayer {
     // executed task per invocation — a 2000-task repo accretes ~20k
     // rows in days, inflating insert and checkpoint cost forever.
     // 30 days comfortably covers `vx stats` (24 h windows) and any
-    // CI-side analytics consumers.
+    // CI-side analytics consumers. The `invocations` header table (one
+    // row per `vx run`) is pruned on the SAME window — otherwise a
+    // header would outlive its `runs` rows, so `vx info`/`vx last` would
+    // list an invocation whose task detail is already gone, and the
+    // table would grow unbounded on a long-lived checkout.
     try {
-      this.db
-        .prepare('DELETE FROM runs WHERE ended_at < ?')
-        .run(Date.now() - 30 * 24 * 60 * 60 * 1000)
+      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.
     }
-    this.flushAccessed()
+    try {
+      this.flushAccessed()
+    } catch {
+      // Same contract as the retention prune above, which was already
+      // guarded while this sibling was not: `accessed_at` is LRU
+      // bookkeeping, never correctness, and the run's results are
+      // already recorded by the time we get here. Letting it throw also
+      // SKIPPED `db.close()` below, leaking the handle. Reachable when
+      // the cache dir is removed under a live handle (a concurrent
+      // `rm -rf .vx/cache`): macOS answers SQLITE_IOERR_VNODE on a
+      // write to an unlinked file where Linux happily writes on.
+    }
     this.db.close()
   }
 
@@ -1764,67 +1493,6 @@ 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 [
-    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.
- */
-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, '']