@vzn/vx 0.0.50 → 0.0.51

package/README.md

@@ -101,10 +101,12 @@ with the invariant that keeps it valid —
 
 ## Built for trust
 
-- **Corruption can't go live.** A remote artifact is verified against
-  its content digest and validated before it enters the store
-  (zstd-bomb and oversize downloads refused); bad bytes degrade to a
-  cache miss, never a wrong hit and never a crash.
+- **Corruption can't go live.** A remote artifact is validated before
+  it enters the store: a zstd bomb, bytes that are not a vx archive,
+  and an archive recording another key than the one it was fetched
+  under are refused, and `@vzn/vx-reapi` re-hashes every blob against
+  its content digest; bad bytes degrade to a cache miss, never a wrong
+  hit and never a crash.
 - **Clean exits.** SIGINT/SIGTERM reap every child process — no
   orphaned dev servers in CI.
 - **Readiness you can bound.** Persistent tasks gate downstream work
@@ -129,13 +131,15 @@ vx lock                      # evaluate everything once, write vx-lock.json
 vx lock --check && vx run ci --frozen     # CI: audit, then run EXACTLY that graph
 ```
 
-| Command           | Evaluates configs | Uses lock                                                       |
-| ----------------- | ----------------- | --------------------------------------------------------------- |
-| `vx run`          | always, live      | never — local truth has no asterisks                            |
-| `vx run --frozen` | never             | yes; refuses if absent or a config file changed since locking   |
-| `vx lock --check` | full graph        | compares — catches env and import drift that byte hashes cannot |
+| Command           | Evaluates configs | Uses lock                                                        |
+| ----------------- | ----------------- | ---------------------------------------------------------------- |
+| `vx run`          | always, live      | never — local truth has no asterisks                             |
+| `vx run --frozen` | never             | yes, as written; refuses only a missing lock or project entry    |
+| `vx lock --check` | full graph        | compares — a changed file, and env or import drift it cannot see |
 
-Env values read at lock time are frozen by design — cache keys become
+`--frozen` checks nothing about staleness itself: an edited config runs
+its locked form until `vx lock` re-writes it, and `vx lock --check` is
+the guard that fails first. Env values read at lock time are frozen by design — cache keys become
 reproducible across machines. Take it for that, not for speed: measured
 on the 1,000-project bench, a plain warm run and a frozen one are a tie
 (177 ms against 165, 2026-09-12), because the config-evaluation cache
@@ -162,17 +166,20 @@ task graph, derive keys, schedule, execute, cache, observe. Plugins
 declared in `vx.workspace.ts` hook each stage, Vite-style, on one
 `VxPlugin` object:
 
-| Stage     | Hook                       | A plugin can…                                               |
-| --------- | -------------------------- | ----------------------------------------------------------- |
-| workspace | `config(ws, ctx)`          | edit the workspace config before it is used                 |
-| project   | `project(config, ctx)`     | add, remove or rewrite a project's tasks (keyed like yours) |
-| graph     | `graph(nodes, ctx)`        | add or drop edges, mark tasks requested                     |
-| key       | `key(task, ctx)`           | fold extra material into the cache key (named in `vx why`)  |
-| schedule  | `schedule(nodes, ctx)`     | decide which ready task runs first                          |
-| execute   | `executor(ctx)`            | decide WHERE a task's command runs (local, a REAPI worker)  |
-| store     | `cache(ctx)`               | decide where artifacts live (local, a shared remote)        |
-| observe   | `telemetry(ctx)` / `setup` | receive every run record, or the raw event bus              |
-| cli       | `commands`                 | add verbs to `vx`                                           |
+| Stage     | Hook                       | A plugin can…                                                |
+| --------- | -------------------------- | ------------------------------------------------------------ |
+| workspace | `config(ws, ctx)`          | edit the workspace config before it is used                  |
+| project   | `project(config, ctx)`     | add, remove or rewrite a project's tasks (keyed like yours)  |
+| graph     | `graph(nodes, ctx)`        | add or drop edges, mark tasks requested                      |
+| key       | `key(task, ctx)`           | fold extra material into the cache key (named in `vx why`)   |
+| key       | `fingerprint` (a claim)    | claim a root file (a lockfile) and key each task on its part |
+| schedule  | `schedule(nodes, ctx)`     | decide which ready task runs first                           |
+| schedule  | `admit(task, ctx)`         | hold a ready task until something running here finishes      |
+| execute   | `executor(ctx)`            | decide WHERE a task's command runs (local, a REAPI worker)   |
+| store     | `cache(ctx)`               | decide where artifacts live (local, a shared remote)         |
+| observe   | `telemetry(ctx)` / `setup` | receive every run record, or the raw event bus               |
+| run       | `setup` / `teardown`       | acquire before the run, release after it                     |
+| cli       | `commands`                 | add verbs to `vx`                                            |
 
 Core applies **no plugin by default** and names none. Running here and
 caching here are its floor — the tail of every executor list and cache
@@ -194,10 +201,9 @@ Context Protocol server for AI coding agents, no SDK),
 artifacts are vx's),
 [`@vzn/vx-lockfile`](packages/vx-lockfile) (`pnpm()`, `bun()`, `npm()`,
 `yarn()`: the lockfile keyed per project, so one install re-keys only the
-projects it reaches, and `--affected` follows), and [`@vzn/vx-schedule-history`](packages/vx-schedule-history)
-(order by learned critical path) and [`@vzn/vx-migrate`](packages/vx-migrate)
-(`bunx @vzn/vx-migrate`: turbo.json or an Nx graph → vx.config.ts, through
-core's migration seam). Core ships no plugin and reads no other runner's
+projects it reaches, and `--affected` follows) and [`@vzn/vx-schedule-history`](packages/vx-schedule-history)
+(order by learned critical path, and pack admission by what past runs
+used). Core ships no plugin and reads no other runner's
 format; nothing
 distributed ships in this repo; the seams are how you build it.
 
@@ -205,7 +211,7 @@ distributed ships in this repo; the seams are how you build it.
 
 |                           | vx                                                               | Turborepo                      | Nx               |
 | ------------------------- | ---------------------------------------------------------------- | ------------------------------ | ---------------- |
-| Fully cached, 100 pkgs¹   | **144 ms**                                                       | 279 ms                         | 583+ ms          |
+| Fully cached, 1,090 pkgs¹ | **510 ms**                                                       | 760 ms                         | 3.59 s           |
 | Config                    | TypeScript, evaluated into the cache key                         | JSON (static)                  | JSON (static)    |
 | Output ownership          | **Strict** — wiped before exec AND restore                       | Additive (stale files survive) | Additive         |
 | Clean-tree hashing        | **Zero reads** (git index OIDs)                                  | git OIDs                       | re-hash / daemon |
@@ -215,9 +221,10 @@ distributed ships in this repo; the seams are how you build it.
 | OTel CI/CD spans          | **Yes** — `otel()` plugin, zero OTel-SDK deps                    | No                             | Paid             |
 | Install                   | **Single binary** — npm, or one release file; no Node/Bun needed | npm + Node                     | npm + Node       |
 
-¹ Wall-clock, direct binaries, same machine and workspace — full
-methodology and more scenarios in
-[`packages/vx/docs/benchmarks.md`](packages/vx/docs/benchmarks.md).
+¹ Warm, nothing to rebuild, on the 3,270-task graph quoted at the top:
+wall-clock, direct binaries, same machine and workspace — methodology
+and more scenarios in
+[`packages/vx/docs/benchmarks.md`](packages/vx/docs/benchmarks.md) § A real monorepo.
 
 ## Switching from another runner
 
@@ -309,7 +316,7 @@ maintainers' handoff is [`packages/vx/docs/STATUS.md`](packages/vx/docs/STATUS.m
 
 **Pre-alpha.** The schema is settling; we bump `CACHE_VERSION` rather
 than maintain back-compat. What 1.0 will promise is in
-[`versioning-1.0.md`](packages/vx/docs/design/versioning-1.0.md). **~3,000 core tests plus the package suites; CI green on every commit**;
+[`versioning-1.0.md`](packages/vx/docs/design/versioning-1.0.md). **over 4,000 core tests plus the package suites; CI green on every commit**;
 the project dogfoods itself (`vx run ci`). Published on npm:
 [`@vzn/vx`](https://www.npmjs.com/package/@vzn/vx) (a prebuilt standalone
 binary).
@@ -321,7 +328,7 @@ build.
 
 | Surface                                            | Maturity             | Notes                                                                                                                                                             |
 | -------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Core task runner + caching                         | **production-ready** | dogfooded continuously; ~3,000 core tests + the package suites, green                                                                                             |
+| Core task runner + caching                         | **production-ready** | dogfooded continuously; over 4,000 core tests + the package suites, green                                                                                         |
 | Plugin pipeline (13 hooks, `commands` included)    | **shippable**        | crash-isolated, re-validated; the local executor + cache are the floor under every plugin                                                                         |
 | `vx init` / `@vzn/vx-migrate` (scripts; Turbo, Nx) | **shippable**        | one config per package, TODOs where a source cannot say                                                                                                           |
 | REAPI remote cache + execution (`@vzn/vx-reapi`)   | **shippable**        | Bazel AC + CAS + Execute; NativeLink / BuildBuddy / Buildbarn / bazel-remote                                                                                      |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.50",
+  "version": "0.0.51",
   "description": "An open, extensible monorepo task runner.",
   "type": "module",
   "exports": {
@@ -17,10 +17,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.50",
-    "@vzn/vx-linux-arm64": "0.0.50",
-    "@vzn/vx-darwin-x64": "0.0.50",
-    "@vzn/vx-darwin-arm64": "0.0.50"
+    "@vzn/vx-linux-x64": "0.0.51",
+    "@vzn/vx-linux-arm64": "0.0.51",
+    "@vzn/vx-darwin-x64": "0.0.51",
+    "@vzn/vx-darwin-arm64": "0.0.51"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/bin.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env bun
+#!/usr/bin/env -S bun --no-env-file
 import { registerCoreAlias, run } from './cli/index.js'
 import { fsRefusalHint, isFsRefusal, isUserError } from './util/index.js'
 

package/src/cache/archive.ts

@@ -163,7 +163,10 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
         abs,
         size: st.size,
         mode: st.mode & 0o777,
-        mtime: Math.floor(st.mtimeMs / 1000),
+        // ustar's octal field holds no sign: an mtime before 1970 made the
+        // header unreadable and every save of it a "corrupt artifact". The
+        // sidecar above carries the real value.
+        mtime: Math.max(0, Math.floor(st.mtimeMs / 1000)),
       }
     }),
   )
@@ -333,9 +336,14 @@ export async function extractArtifactStream(
       )
     }
     verify?.(provided)
+    // The sidecar's stat is the truth, a mode of 000 and an mtime at or
+    // before the epoch included (`SOURCE_DATE_EPOCH=0`). Without one, a
+    // header mtime of 0 is a producer that wrote none: unknown.
     await x.commit((name) => {
       const m = meta[name]
-      return [m?.[0] ?? 0o644, m?.[1] ?? headerMtime.get(name) ?? 0]
+      if (m !== undefined) return [m[0], m[1]]
+      const header = headerMtime.get(name)
+      return [0o644, header !== undefined && header > 0 ? header : undefined]
     })
   } catch (err) {
     await x.abort()
@@ -623,16 +631,20 @@ class Extractor {
    * restores' round trips flowing. The chmod is skipped when the mode is
    * the one the temp file was created with — the common case.
    */
-  async commit(metaFor: (name: string) => [mode: number, mtimeMs: number]): Promise<void> {
+  async commit(
+    metaFor: (name: string) => [mode: number, mtimeMs: number | undefined],
+  ): Promise<void> {
     await this.drain()
     const first = this.staged[0]
     const createdMode = first === undefined ? -1 : statSync(first.tmp).mode & 0o777
     let n = 0
     for (const s of this.staged) {
       const [mode, mtimeMs] = metaFor(s.name)
-      if (mode !== 0 && (mode & 0o777) !== createdMode) chmodSync(s.tmp, mode & 0o777)
-      if (mtimeMs > 0) {
-        const t = mtimeMs / 1000
+      if ((mode & 0o777) !== createdMode) chmodSync(s.tmp, mode & 0o777)
+      if (mtimeMs !== undefined) {
+        // A Date, not seconds: Bun reads a negative number of seconds as
+        // "now", and a Date before 1970 as itself (Bun 1.4.2).
+        const t = new Date(mtimeMs)
         utimesSync(s.tmp, t, t)
       }
       renameSync(s.tmp, s.target)

package/src/cache/cache.ts

@@ -26,8 +26,8 @@
 // layer speaks is `CacheLayer` in layer.ts; `plugin-host.ts` enforces it.
 
 import { Database, type SQLQueryBindings } from 'bun:sqlite'
-import { accessSync, constants, existsSync, mkdirSync, writeFileSync } from 'node:fs'
-import { readdir, rename, rm, stat, unlink, writeFile } from 'node:fs/promises'
+import { accessSync, constants, existsSync, mkdirSync, renameSync, writeFileSync } from 'node:fs'
+import { readdir, rm, stat, unlink, writeFile } from 'node:fs/promises'
 import path from 'node:path'
 import {
   UserError,
@@ -188,6 +188,46 @@ function schemaOrdinal(version: string): number {
   return m === null ? -1 : Number(m[1])
 }
 
+/**
+ * Artifacts `indexed` does not hold, and temps, past the in-flight grace
+ * window: one readdir, one stat per candidate. `indexed` is asked only
+ * once the readdir succeeded: with the directory gone, macOS answers a
+ * read of the index SQLITE_IOERR_VNODE, and an unreadable directory
+ * reports nothing.
+ */
+async function scanOrphanFiles(
+  cacheDir: string,
+  indexedHashes: () => ReadonlySet<string>,
+): Promise<Array<{ file: string; size: number }>> {
+  let names: string[]
+  try {
+    names = await readdir(cacheDir)
+  } catch {
+    return []
+  }
+  const indexed = indexedHashes()
+  const cutoff = Date.now() - ORPHAN_GRACE_MS
+  const candidates: string[] = []
+  for (const name of names) {
+    const m = VX_ARTIFACT_NAME.exec(name)
+    if (m === null) continue
+    if (m[2] !== undefined || !indexed.has(m[1]!)) candidates.push(name)
+  }
+  const found: Array<{ file: string; size: number }> = []
+  await Promise.all(
+    candidates.map(async (name) => {
+      const file = path.join(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
+}
+
 /**
  * SQL predicate selecting `runs` rows that record an EXECUTION.
  *
@@ -400,6 +440,41 @@ export class Cache implements CacheLayer {
     return new Cache(cacheDir, undefined, undefined, undefined, 'inspect')
   }
 
+  /**
+   * What a real prune reaps from an index of an EARLIER schema, which it
+   * resets first, leaving every aged artifact row-less: a dry run that
+   * refused it could not preview the biggest prune there is, the one
+   * after an upgrade (item 1083). Reads the recorded version alone and
+   * touches nothing. Null for an absent, current, newer or unreadable
+   * index; `Cache.inspect` answers those.
+   */
+  static async orphansBeforeReset(
+    cacheDir: string,
+  ): Promise<{ found: string; orphans: number; orphanBytes: number } | null> {
+    const dbFile = path.join(cacheDir, 'cache.db')
+    if (!existsSync(dbFile)) return null
+    let found: string | undefined
+    try {
+      const db = new Database(dbFile, { readonly: true })
+      try {
+        found = (
+          db.prepare("SELECT value FROM schema_meta WHERE key = 'version'").get() as {
+            value: string
+          } | null
+        )?.value
+      } finally {
+        db.close()
+      }
+    } catch {
+      return null
+    }
+    if (found === undefined || schemaOrdinal(found) >= schemaOrdinal(SCHEMA_VERSION)) return null
+    const aged = await scanOrphanFiles(cacheDir, () => new Set())
+    let orphanBytes = 0
+    for (const o of aged) orphanBytes += o.size
+    return { found, orphans: aged.length, orphanBytes }
+  }
+
   constructor(
     private readonly cacheDir: string,
     localPolicy: { read: boolean; write: boolean } = { read: true, write: true },
@@ -785,7 +860,7 @@ export class Cache implements CacheLayer {
     const format = this.db
       .prepare("SELECT value FROM schema_meta WHERE key = 'cache_version'")
       .get() as { value: string } | null
-    if (format?.value !== CACHE_VERSION && this.writeBlocked === null) {
+    if (format?.value !== CACHE_VERSION && this.writeBlocked === null && !this.inspecting) {
       const hasEntries = this.db.prepare('SELECT 1 FROM entries LIMIT 1').get() != null
       if (this.schemaReset === null && (format !== null || hasEntries)) {
         this.formatChange = { from: format?.value ?? 'an earlier format', to: CACHE_VERSION }
@@ -976,8 +1051,9 @@ export class Cache implements CacheLayer {
     hash: string,
     projectDir: string,
     prefixes: readonly string[],
+    holds?: (files: readonly string[]) => boolean,
   ): Promise<void> {
-    await this.outputs.recordOutputDirs(hash, projectDir, prefixes)
+    await this.outputs.recordOutputDirs(hash, projectDir, prefixes, holds)
   }
   recordOutputStamps(hash: string, projectDir: string, workspaceRoot: string): void {
     this.outputs.recordOutputStamps(hash, projectDir, workspaceRoot)
@@ -1070,8 +1146,11 @@ export class Cache implements CacheLayer {
       }
       // What is on disk, not what is in the archive: a directory standing
       // where the entry holds a file, or a file where it needs a directory.
-      // The clean removes everything the output globs cover, so this is a
-      // stray they do not — name it as such, not as a corrupt artifact. A
+      // The clean removes the FILES the output globs select and the
+      // directories that removal emptied, so this is a path it left: one
+      // the globs do not cover, or an empty directory where a file goes,
+      // which `dist/**` covers and the clean does not take (item 1094).
+      // Named as such, not as a corrupt artifact. A
       // link on the way never lands here: the extractor writes through one
       // that stays in the project, dangling or not, and names one that
       // leaves it or loops (item 748).
@@ -1079,7 +1158,7 @@ export class Cache implements CacheLayer {
       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.`,
+            `The clean before a restore removes the files the output globs select, not a directory standing where the entry holds a file, nor a path the globs do not cover — remove it and re-run.`,
         )
       }
       // A legal name under a destination deep enough that the two together
@@ -1405,18 +1484,8 @@ export class Cache implements CacheLayer {
       throw new CorruptArtifactError(hash, 'artifact is not a readable archive', err)
     }
     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 instanceof Uint8Array ? compressed.byteLength : Bun.file(finalPath).size
+      compressed instanceof Uint8Array ? compressed.byteLength : Bun.file(tmpPath).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/`
@@ -1455,7 +1524,23 @@ export class Cache implements CacheLayer {
     const outputs = this.outputs
     const insertEntryInput = this.insertEntryInput
     const inputComponents = meta.inputComponents
+    // The artifact goes live INSIDE the write transaction, taken
+    // IMMEDIATE: the rename happens only once this writer holds the
+    // database's write lock, and its rows commit before any other writer
+    // can rename. Renamed first and indexed after, a commit that failed
+    // (`SQLITE_BUSY` past the busy timeout, `SQLITE_FULL`) left these bytes
+    // beside the previous save's rows, and two writers of one key (two
+    // workspaces on one `--cache-dir`) could pair one's bytes with the
+    // other's rows: every later hit failed the task on an artifact
+    // "missing" a recorded output (A-3). POSIX rename replaces the
+    // destination atomically, so a reader holding the old file reads it
+    // whole. A commit that fails after the rename takes the artifact back
+    // out: the old rows then name no artifact, which a probe reads as a
+    // miss.
+    let renamed = false
     const tx = this.db.transaction(() => {
+      renameSync(tmpPath, finalPath)
+      renamed = true
       insertEntry.run(
         hash,
         project,
@@ -1487,8 +1572,14 @@ export class Cache implements CacheLayer {
       }
     })
     const endTx = span('save: index tx')
-    tx()
-    endTx()
+    try {
+      tx.immediate()
+    } catch (err) {
+      await unlink(renamed ? finalPath : tmpPath).catch(() => undefined)
+      throw err
+    } finally {
+      endTx()
+    }
   }
 
   /** Apply the deferred accessed_at bumps in one statement. */
@@ -1618,9 +1709,10 @@ export class Cache implements CacheLayer {
     let bytesFreed = 0
     // Rows whose artifact is gone (deleted by hand, or by a disk cleaner):
     // never a hit, and their bytes are on no disk, but `--max-size` counted
-    // them and evicted real entries to make room for them (item 975). They
-    // are dropped, neither evicted nor freed.
-    const phantoms = await this.phantomRows()
+    // them and evicted real entries to make room for them (item 975). None
+    // is evicted or freed, whatever its age (item 1081); the ones past the
+    // grace window are dropped.
+    const { phantoms, stale } = await this.phantomRows()
 
     if (olderThanMs !== undefined) {
       const rows = this.db
@@ -1673,9 +1765,9 @@ export class Cache implements CacheLayer {
         orphanBytes: orphans.orphanBytes,
       }
     }
-    if (victims.size > 0 || phantoms.size > 0) {
+    if (victims.size > 0 || stale.length > 0) {
       const hashes = [...victims]
-      const rows = [...hashes, ...phantoms.keys()]
+      const rows = [...hashes, ...stale]
       this.db.transaction(() => {
         for (let i = 0; i < rows.length; i += 900) {
           const chunk = rows.slice(i, i + 900)
@@ -1728,25 +1820,37 @@ export class Cache implements CacheLayer {
 
   /**
    * Index rows whose artifact is not in the directory, with their recorded
-   * sizes. Only rows last written or used before the grace window: a save
-   * renames its artifact in before its row commits, so a fresh row without
-   * one is a listing that raced a save, not a phantom. An unreadable
-   * directory judges nothing.
+   * sizes, and the ones among them last used before the grace window. The
+   * rows are read BEFORE the directory: a save renames its artifact in
+   * before its row commits, so every row read has its artifact listed
+   * unless it is gone, and the count is exact. Only `stale` rows are
+   * dropped — a row is never deleted on one listing's word while it may be
+   * in use. An unreadable directory judges nothing.
    */
-  private async phantomRows(): Promise<Map<string, number>> {
+  private async phantomRows(): Promise<{ phantoms: Map<string, number>; stale: string[] }> {
+    const graceStart = Date.now() - ORPHAN_GRACE_MS
+    const rows = this.db
+      .prepare('SELECT hash, size_bytes, accessed_at FROM entries')
+      .all() as Array<{
+      hash: string
+      size_bytes: number
+      accessed_at: number
+    }>
     let names: string[]
     try {
       names = await readdir(this.cacheDir)
     } catch {
-      return new Map()
+      return { phantoms: new Map(), stale: [] }
     }
     const present = new Set(names)
-    const rows = this.db
-      .prepare('SELECT hash, size_bytes FROM entries WHERE accessed_at < ?')
-      .all(Date.now() - ORPHAN_GRACE_MS) as Array<{ hash: string; size_bytes: number }>
-    const out = new Map<string, number>()
-    for (const r of rows) if (!present.has(`${r.hash}.tar.zst`)) out.set(r.hash, r.size_bytes)
-    return out
+    const phantoms = new Map<string, number>()
+    const stale: string[] = []
+    for (const r of rows) {
+      if (present.has(`${r.hash}.tar.zst`)) continue
+      phantoms.set(r.hash, r.size_bytes)
+      if (r.accessed_at < graceStart) stale.push(r.hash)
+    }
+    return { phantoms, stale }
   }
 
   /** What `prune()` would reap right now, for `vx info` to say before anyone prunes. */
@@ -1759,37 +1863,15 @@ export class Cache implements CacheLayer {
 
   /** Row-less artifacts and temps past the in-flight grace window: one readdir, one stat per candidate. */
   private async scanOrphans(): Promise<Array<{ file: string; size: number }>> {
-    let names: string[]
-    try {
-      names = await readdir(this.cacheDir)
-    } catch {
-      return []
-    }
-    const indexed = new Set(
-      (this.db.prepare('SELECT hash FROM entries').all() as Array<{ hash: string }>).map(
-        (r) => r.hash,
-      ),
-    )
-    const cutoff = Date.now() - ORPHAN_GRACE_MS
-    const candidates: string[] = []
-    for (const name of names) {
-      const m = VX_ARTIFACT_NAME.exec(name)
-      if (m === null) continue
-      if (m[2] !== undefined || !indexed.has(m[1]!)) candidates.push(name)
-    }
-    const found: Array<{ file: string; size: number }> = []
-    await Promise.all(
-      candidates.map(async (name) => {
-        const file = path.join(this.cacheDir, name)
-        try {
-          const st = await stat(file)
-          if (st.isFile() && st.mtimeMs <= cutoff) found.push({ file, size: st.size })
-        } catch {
-          // Gone between readdir and stat: not an orphan any more.
-        }
-      }),
+    return scanOrphanFiles(
+      this.cacheDir,
+      () =>
+        new Set(
+          (this.db.prepare('SELECT hash FROM entries').all() as Array<{ hash: string }>).map(
+            (r) => r.hash,
+          ),
+        ),
     )
-    return found
   }
 
   close(): void {
@@ -1810,6 +1892,7 @@ export class Cache implements CacheLayer {
         const cutoff = Date.now() - 30 * 24 * 60 * 60 * 1000
         this.history.pruneOlderThan(cutoff)
         this.configEvals.pruneOlderThan(cutoff)
+        if (this.write) this.files.pruneOlderThan(cutoff)
       }
     } catch {
       // Retention is best-effort; never block closing the handle.

package/src/cache/chained-cache.ts

@@ -161,8 +161,15 @@ export class ChainedCache implements CacheLayer {
 
   // The directory short-circuit lives with the layer that owns the local
   // rows — the first, like the file check.
-  recordOutputDirs(hash: string, projectDir: string, prefixes: readonly string[]): Promise<void> {
-    return this.layers[0]!.recordOutputDirs?.(hash, projectDir, prefixes) ?? Promise.resolve()
+  recordOutputDirs(
+    hash: string,
+    projectDir: string,
+    prefixes: readonly string[],
+    holds?: (files: readonly string[]) => boolean,
+  ): Promise<void> {
+    return (
+      this.layers[0]!.recordOutputDirs?.(hash, projectDir, prefixes, holds) ?? Promise.resolve()
+    )
   }
   recordOutputStamps(hash: string, projectDir: string, workspaceRoot: string): void {
     this.layers[0]!.recordOutputStamps?.(hash, projectDir, workspaceRoot)

package/src/cache/file-hashes.ts

@@ -10,7 +10,10 @@ import type { Database } from 'bun:sqlite'
 import { lstatSync, readlinkSync } from 'node:fs'
 import path from 'node:path'
 import { fileIdentity, repoFacts } from './git-inputs.js'
-import { FILE_HASH_RACY_MS } from './layer.js'
+import { FILE_HASH_RACY_MS, racyWindowMs } from './layer.js'
+
+const FILE_HASHES_SWEPT_AT = 'file_hashes_swept_at'
+const DAY_MS = 24 * 60 * 60 * 1000
 
 export class FileHashStore {
   private readonly selectFileHash: ReturnType<Database['prepare']>
@@ -47,6 +50,29 @@ export class FileHashStore {
     `)
   }
 
+  /**
+   * Drop the memo rows last written before `cutoff`: a path that is gone
+   * (a deleted generated input, a worktree removed, a CI checkout at a new
+   * path) keeps its row forever otherwise, and `cache.db` grows with every
+   * path ever hashed. A hit does not refresh `seen_at` (a write per file
+   * per run), so a file unchanged for the window loses its row too and is
+   * read once more; a dropped row is only a memo miss. The scan costs
+   * 8 ms at 100,000 rows, so it runs once a day, on its own clock in
+   * `schema_meta` (item 1082).
+   */
+  pruneOlderThan(cutoff: number, now: number = Date.now()): void {
+    const last = this.db
+      .prepare('SELECT value FROM schema_meta WHERE key = ?')
+      .get(FILE_HASHES_SWEPT_AT) as { value: string } | null
+    if (last !== null && now - Number(last.value) < DAY_MS) return
+    this.db.transaction(() => {
+      this.db.prepare('DELETE FROM file_hashes WHERE seen_at < ?').run(cutoff)
+      this.db
+        .prepare('INSERT OR REPLACE INTO schema_meta(key, value) VALUES (?, ?)')
+        .run(FILE_HASHES_SWEPT_AT, String(now))
+    })()
+  }
+
   /**
    * 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
@@ -136,7 +162,7 @@ export class FileHashStore {
     // changed within the window is hashed again on its next call rather
     // than memoised; the warm path never meets it (keys are derived long
     // after the files were written).
-    if (this.write && Date.now() - ctimeMs >= FILE_HASH_RACY_MS) {
+    if (this.write && Date.now() - ctimeMs >= racyWindowMs(st.ctimeMs, FILE_HASH_RACY_MS)) {
       this.upsertFileHash.run(filePath, mtimeMs, size, ctimeMs, ino, ch, Date.now())
     }
     return fileIdentity(mode, ch)
@@ -161,6 +187,8 @@ export class FileHashStore {
       mtimeMs: number
       size: number
       ctimeMs: number
+      /** Unfloored, for the racy window: a whole second is a whole-second clock only here. */
+      ctimeRaw: number
       ino: number
     }
     const stats = new Map<string, Stat>()
@@ -188,6 +216,7 @@ export class FileHashStore {
           mtimeMs: Math.floor(st.mtimeMs),
           size: st.size,
           ctimeMs: Math.floor(st.ctimeMs),
+          ctimeRaw: st.ctimeMs,
           ino: Number(st.ino),
         })
       } catch {
@@ -241,7 +270,7 @@ export class FileHashStore {
         out.set(p, fileIdentity(st.mode, digest))
         // The same racy-clean rule as `hashFile`: a stat taken within the
         // window of the file's last change is not memoised.
-        if (this.write && now - st.ctimeMs >= FILE_HASH_RACY_MS) {
+        if (this.write && now - st.ctimeMs >= racyWindowMs(st.ctimeRaw, FILE_HASH_RACY_MS)) {
           this.upsertFileHash.run(p, st.mtimeMs, st.size, st.ctimeMs, st.ino, digest, now)
         }
       }