@vzn/vx 0.0.595 → 0.0.597

package/README.md

@@ -98,7 +98,7 @@ More: [Quickstart](https://vznjs.github.io/vx/quickstart/) ·
 Beside `turbo.json` or `nx.json`, `vx init` writes only a
 `vx.workspace.ts` that maps the old config until then: a temporary
 start, not a way to run the repo. The numbers above are native vx
-config. `@vzn/vx-migrate`'s first npm publish is pending.
+config.
 [Migration guide](https://vznjs.github.io/vx/guides/migrate/).
 
 ## Why it is faster

package/launcher.cjs

@@ -18,12 +18,16 @@
 // CommonJS, not ESM: Node's ESM loader cost every `vx` call ~8 ms of a
 // ~65 ms launch (min of 21, interleaved, Node 22, 2026-10-01).
 const { execFileSync, spawn, spawnSync } = require('node:child_process')
-const { existsSync, readFileSync } = require('node:fs')
+const { existsSync, readFileSync, realpathSync } = require('node:fs')
 const { constants: osConstants } = require('node:os')
 const { dirname, join } = require('node:path')
 
-const here = __dirname
-const pkg = require('./package.json')
+// The real directory, not `__dirname`: npm's `node_modules/.bin/vx` is a
+// symlink to this file, and under `--preserve-symlinks-main` (NODE_OPTIONS)
+// `__dirname` is `.bin`, where `./package.json` does not resolve and
+// the launcher died MODULE_NOT_FOUND before vx started.
+const here = dirname(realpathSync(__filename))
+const pkg = require(join(here, 'package.json'))
 
 // Derive the platform-package prefix + binary basename from this package's
 // name. `base` is the unscoped name — the command AND the binary filename

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.595",
+  "version": "0.0.597",
   "description": "The fastest task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.595",
-    "@vzn/vx-linux-arm64": "0.0.595",
-    "@vzn/vx-darwin-x64": "0.0.595",
-    "@vzn/vx-darwin-arm64": "0.0.595"
+    "@vzn/vx-linux-x64": "0.0.597",
+    "@vzn/vx-linux-arm64": "0.0.597",
+    "@vzn/vx-darwin-x64": "0.0.597",
+    "@vzn/vx-darwin-arm64": "0.0.597"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/cache/archive.ts

@@ -233,7 +233,7 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
   const few = args.outputs.size <= ON_THREAD_STATS
   const lstatOf = few ? async (p: string) => lstatSync(p) : lstat
   const statOf = few ? async (p: string) => statSync(p) : stat
-  const realpathOf = few ? async (p: string) => realpathSync(p) : realpath
+  const realpathOf = (p: string) => realOf(p, few)
   let withinReal: Promise<string> | undefined
   // Where this artifact's own non-link outputs really are: a link to one of
   // them packs bytes the task wrote itself. A root-anchored output tree is
@@ -262,6 +262,16 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
         : name.startsWith(WORKSPACE_OUTPUT_PREFIX)
           ? `workspaceFiles output ${name.slice(WORKSPACE_OUTPUT_PREFIX.length)}`
           : `output ${name}`
+      // The index stores a project row as its bare rel and reads one under
+      // `workspace-outputs/` as a workspace output, so every hit of this
+      // entry was "missing a recorded output", dropped and run again. The
+      // loader refuses a glob written under the name; one that reaches it
+      // otherwise (`**/*.js`, `w*/**`) is refused here, where names are known.
+      if (name.startsWith(`outputs/${WORKSPACE_OUTPUT_PREFIX}`)) {
+        throw new UserError(
+          `${shown} is under workspace-outputs/, a name vx's artifacts reserve for outputs.workspaceFiles — write the task's files to another directory, or take them back with a '!' entry`,
+        )
+      }
       const dangling = (err: NodeJS.ErrnoException): never => {
         if (err.code === 'ENOENT') {
           throw new UserError(
@@ -293,12 +303,12 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
         )
       }
       const mode = st.mode & 0o777
-      meta.files[name] = [mode, Math.floor(st.mtimeMs)]
       return {
         name,
         abs: src,
         size: st.size,
         mode,
+        mtimeMs: Math.floor(st.mtimeMs),
         // 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.
@@ -306,6 +316,8 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
       }
     }),
   )
+  // In the outputs' order, not as each stat settled: one tree, one artifact.
+  for (const f of files) meta.files[f.name] = [f.mode, f.mtimeMs]
   const stdout = new TextEncoder().encode(args.stdout)
   const metaBytes = new TextEncoder().encode(JSON.stringify(meta))
   const inputs: TarInput[] = [
@@ -624,11 +636,11 @@ class Extractor {
       // deepest EXISTING ancestor and re-append the rest: the answer is the
       // same before and after the base is created, which is what makes the
       // memo safe.
-      r = await realpath(key).catch(async () => {
+      r = await realOf(key).catch(async () => {
         let probe = path.dirname(key)
         const tail: string[] = [path.basename(key)]
         while (probe !== path.dirname(probe)) {
-          const real = await realpath(probe).then(
+          const real = await realOf(probe).then(
             (v) => v,
             () => null,
           )
@@ -674,7 +686,7 @@ class Extractor {
     // resolve was a round trip spent on a comparison never made (item 627).
     let probe = path.dirname(targetResolved)
     while (probe.startsWith(baseResolved + path.sep)) {
-      const real = await realpath(probe).then(
+      const real = await realOf(probe).then(
         (r) => r,
         () => null,
       )
@@ -854,7 +866,7 @@ class Extractor {
       const top = path.resolve(s.created)
       // Created at a dangling link's resolved target (`mkdirThroughLink`),
       // so the chain is pruned from where the link leads.
-      if (!dir.startsWith(top)) dir = await realpath(dir).catch(() => dir)
+      if (!dir.startsWith(top)) dir = await realOf(dir).catch(() => dir)
       while (dir.startsWith(top)) {
         if (
           !(await rmdir(dir).then(
@@ -903,6 +915,23 @@ async function linkOutError(base: string, probe: string, realBase: string): Prom
   )
 }
 
+/**
+ * `realpath`, for a path holding a backslash too: Bun's answers ENOENT for
+ * any such path (1.4.2), so the containment walk took a link named
+ * `dist\x` for absent and wrote through it, and a save called a linked
+ * output under one dangling. Such a path's links are read one by one.
+ */
+async function realOf(p: string, sync = false): Promise<string> {
+  try {
+    return sync ? realpathSync(p) : await realpath(p)
+  } catch (err) {
+    if (!p.includes('\\')) throw err
+    const real = await resolveThrough(p)
+    await stat(real)
+    return real
+  }
+}
+
 /**
  * Where `p` leads, every link on the way followed, a dangling one included:
  * `realpath` for the part that exists, and past the first missing name the

package/src/cache/cache.ts

@@ -44,6 +44,7 @@ import {
   openSync,
   readdirSync,
   renameSync,
+  statSync,
   utimesSync,
   writeFileSync,
 } from 'node:fs'
@@ -111,12 +112,13 @@ import { RunHistory } from './run-history.js'
 import { CACHE_VERSION, foldKey } from './key-fold.js'
 
 /**
- * An artifact or temp file without an `entries` row is reaped by
- * `prune()` only once it is this old. A save renames the artifact into
- * place inside its `BEGIN IMMEDIATE` row transaction (A-3), so a live
- * artifact without a row is one whose commit failed and was taken back
- * out; 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.
+ * An artifact or temp file without an `entries` row is never reaped
+ * younger than this: a crashed save's temp is stale long before it. A
+ * row-less artifact may still be in use (another vx version's open dropped
+ * its row), so past this it is judged by the retention policy, its file
+ * time standing for `accessed_at`. A hit renews a file time older than
+ * this, so the file time trails the last use by at most this much, and
+ * the policy reads the file time plus this as the last use.
  */
 const ORPHAN_GRACE_MS = 60 * 60 * 1000
 
@@ -271,6 +273,62 @@ function indexOfAnotherSchema(dbFile: string): boolean {
 const SELECT_ENTRY =
   "SELECT e.*, COALESCE(s.stdout, '') AS stdout FROM entries e LEFT JOIN entry_stdout s ON s.hash = e.hash"
 
+/** A file the orphan sweep may judge: a row-less artifact, or a temp. */
+interface RowlessFile {
+  file: string
+  size: number
+  mtimeMs: number
+  temp: boolean
+}
+
+/**
+ * What a prune takes under `policy`: index rows by `accessed_at` and
+ * row-less artifacts by file time, under one rule (a temp always). The
+ * rows are the non-phantom ones; the files are past the in-flight grace.
+ */
+function pickVictims(
+  rows: ReadonlyArray<{ hash: string; size_bytes: number; accessed_at: number }>,
+  files: readonly RowlessFile[],
+  policy: { olderThanMs?: number; maxBytes?: number },
+): { hashes: Set<string>; bytesFreed: number; files: RowlessFile[] } {
+  const { olderThanMs, maxBytes } = policy
+  const hashes = new Set<string>()
+  let bytesFreed = 0
+  const taken: RowlessFile[] = []
+  const kept: Array<{ at: number; size: number; row?: string; file?: RowlessFile }> = []
+  let remaining = 0
+  for (const r of rows) {
+    if (olderThanMs !== undefined && r.accessed_at < olderThanMs) {
+      hashes.add(r.hash)
+      bytesFreed += r.size_bytes
+    } else {
+      kept.push({ at: r.accessed_at, size: r.size_bytes, row: r.hash })
+      remaining += r.size_bytes
+    }
+  }
+  for (const f of files) {
+    const at = f.mtimeMs + ORPHAN_GRACE_MS
+    if (f.temp || (olderThanMs !== undefined && at < olderThanMs)) taken.push(f)
+    else {
+      kept.push({ at, size: f.size, file: f })
+      remaining += f.size
+    }
+  }
+  if (maxBytes !== undefined && remaining > maxBytes) {
+    kept.sort((a, b) => a.at - b.at)
+    for (const k of kept) {
+      if (remaining <= maxBytes) break
+      remaining -= k.size
+      if (k.file !== undefined) taken.push(k.file)
+      else {
+        hashes.add(k.row!)
+        bytesFreed += k.size
+      }
+    }
+  }
+  return { hashes, bytesFreed, files: taken }
+}
+
 /**
  * Artifacts `indexed` does not hold, and temps, past the in-flight grace
  * window: one readdir, one stat per candidate. `indexed` is asked only
@@ -281,7 +339,7 @@ const SELECT_ENTRY =
 async function scanOrphanFiles(
   cacheDir: string,
   indexedHashes: () => ReadonlySet<string>,
-): Promise<Array<{ file: string; size: number }>> {
+): Promise<RowlessFile[]> {
   let names: string[]
   try {
     names = await readdir(cacheDir)
@@ -290,19 +348,22 @@ async function scanOrphanFiles(
   }
   const indexed = indexedHashes()
   const cutoff = Date.now() - ORPHAN_GRACE_MS
-  const candidates: string[] = []
+  const candidates: Array<{ name: string; temp: boolean }> = []
   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 temp = m[2] !== undefined
+    if (temp || !indexed.has(m[1]!)) candidates.push({ name, temp })
   }
-  const found: Array<{ file: string; size: number }> = []
+  const found: RowlessFile[] = []
   await Promise.all(
-    candidates.map(async (name) => {
+    candidates.map(async ({ name, temp }) => {
       const file = path.join(cacheDir, name)
       try {
         const st = await stat(file)
-        if (st.isFile() && st.mtimeMs <= cutoff) found.push({ file, size: st.size })
+        if (st.isFile() && st.mtimeMs <= cutoff) {
+          found.push({ file, size: st.size, mtimeMs: st.mtimeMs, temp })
+        }
       } catch {
         // Gone between readdir and stat: not an orphan any more.
       }
@@ -570,6 +631,8 @@ export class Cache implements CacheLayer {
   private readonly deleteStdout: ReturnType<Database['prepare']>
   private readonly entryExists: ReturnType<Database['prepare']>
   private readonly touched = new Set<string>()
+  /** Hit artifacts whose file time is past the grace: renewed at the flush (`ORPHAN_GRACE_MS`). */
+  private readonly staleTimes = new Set<string>()
   private readonly insertEntryInput: ReturnType<Database['prepare']>
   /** The per-file (mtime, size) → blob-OID memo behind `hashFile`. */
   private readonly files: FileHashStore
@@ -599,7 +662,7 @@ export class Cache implements CacheLayer {
 
   /**
    * The store this open was asked for and could not use, with why: the
-   * entries went to a store inside `cacheDir` instead.
+   * entries went to a store inside `cacheDir` instead. Never printed.
    */
   readonly storeFallback: string | null = null
 
@@ -786,24 +849,33 @@ export class Cache implements CacheLayer {
         this.schemaReset = this.db
           .transaction((): SchemaReset | null => {
             const found = readVersion()
-            if (found !== undefined && found !== SCHEMA_VERSION) refuseUnreadable(found)
-            if (found === undefined) {
-              this.db
-                .prepare("INSERT INTO schema_meta(key, value) VALUES ('version', ?)")
-                .run(SCHEMA_VERSION)
-              return null
-            }
             if (found === SCHEMA_VERSION) return null
+            if (found !== undefined) refuseUnreadable(found)
             // `main.` on every name: unqualified, a table the index lacks
             // resolves to an attached store's (none is attached yet; this
             // keeps it so).
-            this.db.exec(
-              'DROP TABLE IF EXISTS main.entries; DROP TABLE IF EXISTS main.runs; DROP TABLE IF EXISTS main.file_hashes; DROP TABLE IF EXISTS main.blob_sizes; DROP TABLE IF EXISTS main.blob_verdicts; DROP TABLE IF EXISTS main.output_files; DROP TABLE IF EXISTS main.output_stamps; DROP TABLE IF EXISTS main.invocations; DROP TABLE IF EXISTS main.run_task_inputs; DROP TABLE IF EXISTS main.entry_inputs; DROP TABLE IF EXISTS main.config_evals; DROP TABLE IF EXISTS main.config_closures; DROP TABLE IF EXISTS main.output_dirs; DROP TABLE IF EXISTS main.entry_stdout; DROP TABLE IF EXISTS main.store_meta;',
-            )
+            if (found !== undefined) {
+              this.db.exec(
+                'DROP TABLE IF EXISTS main.entries; DROP TABLE IF EXISTS main.runs; DROP TABLE IF EXISTS main.file_hashes; DROP TABLE IF EXISTS main.blob_sizes; DROP TABLE IF EXISTS main.blob_verdicts; DROP TABLE IF EXISTS main.output_files; DROP TABLE IF EXISTS main.output_stamps; DROP TABLE IF EXISTS main.invocations; DROP TABLE IF EXISTS main.run_task_inputs; DROP TABLE IF EXISTS main.entry_inputs; DROP TABLE IF EXISTS main.config_evals; DROP TABLE IF EXISTS main.config_closures; DROP TABLE IF EXISTS main.output_dirs; DROP TABLE IF EXISTS main.entry_stdout; DROP TABLE IF EXISTS main.store_meta;',
+              )
+            }
+            // The tables land under the same write lock as the stamp: made
+            // after it, another vx's reset could stamp its own schema in
+            // between and keep these tables under it. An index beside a
+            // store keeps no entry tables (they would shadow the store's).
+            createTables(this.db, 'main')
+            const recordedStore = this.db
+              .prepare("SELECT 1 FROM schema_meta WHERE key = 'store_dir'")
+              .get()
+            if (storeRoot === undefined ? recordedStore != null : storeRoot !== null) {
+              for (const t of STORE_TABLES) this.db.exec(`DROP TABLE main.${t}`)
+            }
             this.db
-              .prepare("UPDATE schema_meta SET value = ? WHERE key = 'version'")
+              .prepare(
+                "INSERT INTO schema_meta(key, value) VALUES ('version', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+              )
               .run(SCHEMA_VERSION)
-            return { from: found, to: SCHEMA_VERSION }
+            return found === undefined ? null : { from: found, to: SCHEMA_VERSION }
           })
           .immediate()
       } catch (err) {
@@ -841,7 +913,8 @@ export class Cache implements CacheLayer {
         // the entries stay in this workspace rather than fail the run.
         const fallback = cacheDir
         if (fallback !== storeDir) {
-          // Said by the open that falls back; the ones after it find it recorded.
+          // Set by the open that falls back, never printed; the ones after it
+          // find it recorded.
           if (recorded !== fallback) this.storeFallback = `${storeDir} (${blocked})`
           storeDir = fallback
           openCacheDir(fallback)
@@ -1268,7 +1341,9 @@ export class Cache implements CacheLayer {
 
     // Verify the tar artifact actually exists. The DB and the
     // filesystem can drift if someone manually deletes the cache dir.
-    if (!existsSync(this.tarPath(hash))) return null
+    const st = statSync(this.tarPath(hash), { throwIfNoEntry: false })
+    if (st === undefined) return null
+    if (st.mtimeMs < Date.now() - ORPHAN_GRACE_MS) this.staleTimes.add(hash)
 
     // Deferred: per-hit UPDATEs cost ~60 ms across 2000+ probes on a
     // full-cache run. Hashes are collected and flushed as ONE batched
@@ -1301,7 +1376,7 @@ export class Cache implements CacheLayer {
   ): Promise<Map<string, CacheEntry>> {
     return this.guard(async () => {
       const out = await this.getManyEntries(hashes)
-      if (ctx === undefined || !this.write || out.size === hashes.length) return out
+      if (ctx === undefined || !this.read || !this.write || out.size === hashes.length) return out
       // An artifact the index does not know is still a hit (`adopt`).
       for (const hash of hashes) {
         if (out.has(hash) || !(await this.adopt(hash, ctx(hash)))) continue
@@ -1318,8 +1393,12 @@ export class Cache implements CacheLayer {
     const { test, params } = inHashes(hashes)
     const rows = this.db.query(`${SELECT_ENTRY} WHERE e.hash ${test}`).all(...params) 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 graceStart = Date.now() - ORPHAN_GRACE_MS
+    const live = rows.filter((r) => {
+      const st = statSync(this.tarPath(r.hash), { throwIfNoEntry: false })
+      if (st !== undefined && st.mtimeMs < graceStart) this.staleTimes.add(r.hash)
+      return st !== undefined
+    })
     const liveHashes = live.map((r) => r.hash)
     const fileRows = this.loadOutputFilesBatch(liveHashes)
     const dirRows = this.loadOutputDirsBatch(liveHashes)
@@ -1700,6 +1779,9 @@ export class Cache implements CacheLayer {
         hash,
         `remote body runs past ${cap} bytes (the artifact ceiling's bound)`,
       )
+    // Every refusal releases the remote body: a held response pins its
+    // connection, and a layer that settles on the body's end never hears.
+    let counted: ReadableStream<Uint8Array> | undefined
     try {
       if (body instanceof Blob) {
         if (body.size > cap) throw past()
@@ -1708,7 +1790,7 @@ export class Cache implements CacheLayer {
         throw past()
       } else {
         let n = 0
-        const counted = body.body?.pipeThrough(
+        counted = body.body?.pipeThrough(
           new TransformStream<Uint8Array, Uint8Array>({
             transform(chunk, controller) {
               n += chunk.byteLength
@@ -1720,6 +1802,9 @@ export class Cache implements CacheLayer {
         await Bun.write(tmpPath, new Response(counted ?? null))
       }
     } catch (err) {
+      // A failed write leaves the pipe's end unlocked; cancelling it
+      // cancels the source. A body refused by its length is cancelled itself.
+      if (!(body instanceof Blob)) void (counted ?? body.body)?.cancel(err).catch(() => undefined)
       await unlink(tmpPath).catch(() => undefined)
       throw err
     }
@@ -2047,6 +2132,17 @@ export class Cache implements CacheLayer {
     const hashes = [...this.touched]
     this.touched.clear()
     const now = Date.now()
+    // The file time is the last use another vx version's sweep can see:
+    // its open dropped this index's rows (`pickVictims`).
+    const at = new Date(now)
+    for (const hash of this.staleTimes) {
+      try {
+        utimesSync(this.tarPath(hash), at, at)
+      } catch {
+        // Gone, or another user's file: a sweep judges its old time.
+      }
+    }
+    this.staleTimes.clear()
     // LRU bookkeeping: on a full disk the bumps are dropped, never the prune
     // or the stats that asked for them (A-14).
     try {
@@ -2161,21 +2257,26 @@ export class Cache implements CacheLayer {
     // above never sees them (upstream survey, nx#35483: 9 MiB of them sat
     // under a 1 MB limit). Listing the directory to find them costs 0.5 ms
     // per 1,000 entries (4.9 ms at 10,000), every run; the sweep's own
-    // clock in `schema_meta` costs one indexed read. An orphan is reapable
-    // only an hour after its last write anyway, so an hourly sweep reaps
-    // it within two.
+    // clock in `schema_meta` costs one indexed read. The sweep is the
+    // policy's own prune, with the row-less files counted.
     const swept = this.db.prepare('SELECT value FROM schema_meta WHERE key = ?').get(SWEPT_AT) as {
       value: string
     } | null
     if (swept !== null && now - Number(swept.value) < ORPHAN_GRACE_MS) return null
-    return { evicted: 0, bytesFreed: 0, ...(await this.reapOrphans(now)) }
+    return this.pruneIndex(
+      {
+        ...(olderThanMs !== undefined ? { olderThanMs } : {}),
+        ...(policy.maxBytes !== undefined ? { maxBytes: policy.maxBytes } : {}),
+      },
+      now,
+    )
   }
 
   async prune(options: PruneOptions): Promise<PruneResult> {
     return this.guard(() => this.pruneIndex(options))
   }
 
-  private async pruneIndex(options: PruneOptions): Promise<PruneResult> {
+  private async pruneIndex(options: PruneOptions, now: number = Date.now()): Promise<PruneResult> {
     this.flushAccessed()
     // Before any entry is deleted, so a kept entry's pending snapshot is on
     // disk whatever the eviction does next. A pruned hash's snapshot cannot
@@ -2187,50 +2288,24 @@ export class Cache implements CacheLayer {
       throw new Error('prune: pass at least one of `olderThanMs` or `maxBytes`')
     }
 
-    const victims = new Set<string>()
-    let bytesFreed = 0
     // Rows whose artifact is gone (deleted by hand, or by a disk cleaner):
     // never a hit, and their bytes are on no disk, but `--max-size` counted
     // them and evicted real entries to make room for them (item 975). 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
-        .prepare('SELECT hash, size_bytes FROM entries WHERE accessed_at < ?')
-        .all(olderThanMs) as Array<{ hash: string; size_bytes: number }>
-      for (const r of rows) {
-        if (phantoms.has(r.hash)) continue
-        victims.add(r.hash)
-        bytesFreed += r.size_bytes
-      }
-    }
-
-    if (maxBytes !== undefined) {
-      const totalRow = this.db
-        .prepare('SELECT COALESCE(SUM(size_bytes), 0) AS bytes FROM entries')
-        .get() as { bytes: number }
-      let phantomBytes = 0
-      for (const b of phantoms.values()) phantomBytes += b
-      let remaining = totalRow.bytes - phantomBytes - bytesFreed
-      if (remaining > maxBytes) {
-        // Exclude already-picked victims in JS, not via a SQL NOT-IN —
-        // an IN-list over tens of thousands of TTL victims would blow
-        // SQLite's bound-parameter ceiling (see flushAccessed's 900 cap).
-        const candidates = (
-          this.db
-            .prepare('SELECT hash, size_bytes FROM entries ORDER BY accessed_at ASC')
-            .all() as Array<{ hash: string; size_bytes: number }>
-        ).filter((row) => !victims.has(row.hash) && !phantoms.has(row.hash))
-        for (const row of candidates) {
-          if (remaining <= maxBytes) break
-          victims.add(row.hash)
-          bytesFreed += row.size_bytes
-          remaining -= row.size_bytes
-        }
-      }
-    }
+    const { phantoms, stale, rows } = await this.phantomRows()
+    const picked = pickVictims(
+      rows.filter((r) => !phantoms.has(r.hash)),
+      await this.scanOrphans(),
+      {
+        ...(olderThanMs !== undefined ? { olderThanMs } : {}),
+        ...(maxBytes !== undefined ? { maxBytes } : {}),
+      },
+    )
+    const victims = picked.hashes
+    const { bytesFreed } = picked
+    let orphanBytes = 0
+    for (const o of picked.files) orphanBytes += o.size
 
     // Delete DB rows in a single transaction (one fsync; ON DELETE
     // CASCADE clears `output_files`) and unlink artifacts in parallel.
@@ -2239,13 +2314,7 @@ export class Cache implements CacheLayer {
     // 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,
-      }
+      return { evicted: victims.size, bytesFreed, orphans: picked.files.length, orphanBytes }
     }
     if (victims.size > 0 || stale.length > 0) {
       const hashes = [...victims]
@@ -2275,23 +2344,21 @@ export class Cache implements CacheLayer {
     } catch (err) {
       if (!isIndexFull(err)) throw err
     }
-    const orphans = await this.reapOrphans()
+    const orphans = await this.reapOrphans(picked.files, now)
     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.
+   * Unlink the row-less files `pickVictims` took: a `<hash>.tar.zst` with
+   * no `entries` row (another vx version's open dropped it, a `cache.db`
+   * deleted by hand) past the policy, 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.
    */
   private async reapOrphans(
-    now: number = Date.now(),
+    taken: readonly RowlessFile[],
+    now: number,
   ): Promise<{ orphans: number; orphanBytes: number }> {
     try {
       this.db
@@ -2304,7 +2371,7 @@ export class Cache implements CacheLayer {
     let orphans = 0
     let orphanBytes = 0
     await Promise.all(
-      (await this.scanOrphans()).map(async (o) => {
+      taken.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.
@@ -2328,7 +2395,11 @@ export class Cache implements CacheLayer {
    * 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<{ phantoms: Map<string, number>; stale: string[] }> {
+  private async phantomRows(): Promise<{
+    phantoms: Map<string, number>
+    stale: string[]
+    rows: Array<{ hash: string; size_bytes: number; accessed_at: number }>
+  }> {
     const graceStart = Date.now() - ORPHAN_GRACE_MS
     const rows = this.db
       .prepare('SELECT hash, size_bytes, accessed_at FROM entries')
@@ -2341,7 +2412,7 @@ export class Cache implements CacheLayer {
     try {
       names = await readdir(this.artifactDir)
     } catch {
-      return { phantoms: new Map(), stale: [] }
+      return { phantoms: new Map(), stale: [], rows }
     }
     const present = new Set(names)
     const phantoms = new Map<string, number>()
@@ -2351,10 +2422,10 @@ export class Cache implements CacheLayer {
       phantoms.set(r.hash, r.size_bytes)
       if (r.accessed_at < graceStart) stale.push(r.hash)
     }
-    return { phantoms, stale }
+    return { phantoms, stale, rows }
   }
 
-  /** What `prune()` would reap right now, for `vx info` to say before anyone prunes. */
+  /** Row-less files past the in-flight grace, for `vx info`: a prune reaps them by its policy. */
   async orphanStats(): Promise<{ orphans: number; orphanBytes: number }> {
     const found = await this.scanOrphans()
     let orphanBytes = 0
@@ -2363,7 +2434,7 @@ 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 }>> {
+  private async scanOrphans(): Promise<RowlessFile[]> {
     const found = await scanOrphanFiles(
       this.artifactDir,
       () =>