@vzn/vx 0.0.649 → 0.0.651

package/README.md

@@ -142,9 +142,8 @@ not a way to run the repo. The benchmark below uses native vx config.
 | Plugin API         | **Yes**: every pipeline stage             | No                             | Yes (TS-tied)    |
 | Install            | **Single binary**; no Bun, Node optional  | npm + Node                     | npm + Node       |
 
-Every gap, and when another tool is the better pick:
-[comparison](packages/vx/docs/comparison.md) ·
-[vx, Turborepo, Nx, Bazel](https://vznjs.github.io/vx/compare/).
+Every gap: [comparison](packages/vx/docs/comparison.md) ·
+every tool on one suite of cases: [conformance](https://vznjs.github.io/vx/conformance/).
 
 ## Fast, without trading correctness
 
@@ -152,23 +151,9 @@ Every gap, and when another tool is the better pick:
 - **No source-file reads to hash:** on a clean tree, keys come from git's index; each project's `package.json` and the lockfile are still read.
 - **One pass:** one git walk per run; each stat and lookup happens once.
 
-<!-- bench:start — generated by private/vx-bench/update-site.ts from results.json; do not hand-edit -->
-
-| Time added over the ideal run, 1,601 projects, 9,603 tasks | vx         | Turborepo  | Nx         | Vite Task |
-| ---------------------------------------------------------- | ---------- | ---------- | ---------- | --------- |
-| Nothing changed                                            | **799 ms** | 927 ms     | 24.15 s    | 12.07 s   |
-| Nothing changed, outputs restored                          | **1.28 s** | 2.01 s     | 24.45 s    | 11.86 s   |
-| Cold build                                                 | **7.57 s** | 9.63 s     | 3 min 6 s  | 9.01 s    |
-| Cold build: CPU the runner burns                           | 36.64 s    | 1 min 12 s | 5 min 34 s | 25.32 s   |
-
-Time each tool adds over the ideal run; lower is better.
-
-Benchmark workload: a synthetic monorepo of 1,601 projects and 9,603 tasks in 30 dependency levels, five core libraries a quarter of the projects use; build 300 ms, test and typecheck 150 ms, lint 75 ms, publish 30 ms; real repos with uneven task times will differ.
-Run 2026-10-25 on linux x64, 4 cores: vx at commit 9abdfb52c, Turborepo 2.11.10, Nx 24.0.1, Vite Task (vite-plus) 1.4.0.
-
-Same graph, commands and concurrency: [how it is measured](https://vznjs.github.io/vx/benchmarks/).
-
-<!-- bench:end -->
+The head-to-head against Turborepo, Nx and Vite Task, each in its own
+native config, is re-measured on every change to vx and published on the
+site: [benchmarks](https://vznjs.github.io/vx/benchmarks/).
 
 ## Status
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.649",
+  "version": "0.0.651",
   "description": "Task orchestration you own: correct, sandboxed, extensible, with a content-addressed build cache.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.649",
-    "@vzn/vx-linux-arm64": "0.0.649",
-    "@vzn/vx-darwin-x64": "0.0.649",
-    "@vzn/vx-darwin-arm64": "0.0.649"
+    "@vzn/vx-linux-x64": "0.0.651",
+    "@vzn/vx-linux-arm64": "0.0.651",
+    "@vzn/vx-darwin-x64": "0.0.651",
+    "@vzn/vx-darwin-arm64": "0.0.651"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/schemas/last.json

@@ -242,7 +242,10 @@
         "peakRssBytes",
         "peakCores",
         "avgRssBytes",
+        "queuedMs",
         "placement",
+        "outputBytes",
+        "blocks",
         "wallclockStartNs",
         "wallclockEndNs",
         "blockedBy",
@@ -288,10 +291,22 @@
           "type": ["integer", "null"],
           "description": "mean resident memory over the samples; null when nothing sampled"
         },
+        "queuedMs": {
+          "type": ["integer", "null"],
+          "description": "milliseconds it waited, ready, for a slot; null when it never queued"
+        },
         "placement": {
           "type": ["string", "null"],
           "description": "where an executor ran it (small#1); null when here"
         },
+        "outputBytes": {
+          "type": ["integer", "null"],
+          "description": "bytes of its outputs: what its save stored, or its hit restored"
+        },
+        "blocks": {
+          "type": ["integer", "null"],
+          "description": "how many tasks were downstream of it"
+        },
         "wallclockStartNs": {
           "type": ["string", "null"],
           "description": "decimal nanoseconds from the run's start"

package/src/bin.ts

@@ -21,32 +21,14 @@ async function main(): Promise<void> {
     // `vx --version` needs one leaf module; the dispatcher and the util
     // barrel it pulled in were 20 ms of its 28 (2026-10-01).
     if (argv.length === 1 && (argv[0] === '--version' || argv[0] === 'version')) {
-      // `Bun.stdout`, not `process.stdout`: the Node stream's first touch is
-      // ~7 ms, half of this verb (2026-10-02). A reader gone (EPIPE) is no
-      // failure of the line.
       // Handed off, it says which vx ran and which one handed it the call.
       const from = process.env['VX_HANDED_OFF'] || undefined
       const where = from === undefined ? '' : ` (${vxPath()}, handed off from ${from})`
-      // Painted as every other line; piped, the same words a script reads.
-      // Decided here, not by util's `detectColors`: the util barrel was the
-      // 20 ms above, and `node:tty` 17 ms; fd 1 as a character device is the
-      // TTY answer. A CI's log is not painted for this one line.
-      const [{ VERSION }, { fstatSync }] = await Promise.all([
+      const [{ VERSION }, { printVersion }] = await Promise.all([
         import('./version.js'),
-        import('node:fs'),
+        import('./ui/version-line.js'),
       ])
-      const env = process.env
-      const on = env['NO_COLOR']
-        ? false
-        : env['FORCE_COLOR'] !== undefined
-          ? env['FORCE_COLOR'] !== '0' && env['FORCE_COLOR'] !== 'false'
-          : env['TERM'] !== 'dumb' && fstatSync(1).isCharacterDevice()
-      const sgr = (code: string, text: string): string =>
-        on ? `\x1b[${code}m${text}\x1b[0m` : text
-      await Bun.write(
-        Bun.stdout,
-        `${sgr('1', 'vx')} ${sgr('38;2;6;182;212', VERSION)}${where === '' ? '' : sgr('2', where)}\n`,
-      ).catch(() => {})
+      await printVersion(VERSION, where)
       settled = true
       return
     }
@@ -64,8 +46,9 @@ async function main(): Promise<void> {
     // is set, and `exitOnceFlushed` exits after both streams have ended.
     process.exitCode = code
   } catch (err) {
+    const ui = await import('./ui/index.js')
+    const { refusalNotice } = ui
     const {
-      detectColors,
       errorCode,
       errorDocument,
       fsRefusalHint,
@@ -74,17 +57,12 @@ async function main(): Promise<void> {
       isUserError,
       maskedLine,
       OUT_OF_FDS_HINT,
-      refusalNotice,
-      ui,
       wantsJson,
     } = await import('./util/index.js')
     // A plugin's failure quotes what it was told (a remote's reply, a
     // header), and a config's own throw is its author's text: a secret in
     // either reached stderr whole (L-11).
-    const say = (line: string): void =>
-      void process.stderr.write(
-        `${ui.tagged('error', maskedLine(line), detectColors(process.stderr))}\n`,
-      )
+    const say = (line: string): void => ui.say('error', maskedLine(line))
     // UserError (workspace not found, cycle, config invalid, ...) —
     // print the message only; the stack is noise the user can't act
     // on. Everything else gets the full stack so internal bugs are
@@ -100,7 +78,7 @@ async function main(): Promise<void> {
         named === null ? err.message : err.message.slice(named[0].length),
         err.parts,
       )
-      process.stderr.write(maskedLine(ui.render([block], detectColors(process.stderr))))
+      ui.data('err', maskedLine(ui.render([block], ui.colorsOf('err'))))
     } else if (isOutOfFds(err)) {
       say(`vx: ${err.message} — ${OUT_OF_FDS_HINT}\n`)
     } else if (isFsRefusal(err)) {
@@ -114,7 +92,7 @@ async function main(): Promise<void> {
     // stdout got nothing to parse, and only prose on stderr to branch on.
     if (wantsJson(argv)) {
       const message = err instanceof Error ? err.message : String(err)
-      process.stdout.write(errorDocument(errorCode(err), maskedLine(message)))
+      ui.data('out', errorDocument(errorCode(err), maskedLine(message)))
     }
     // Same reason as the success path above: a large stderr is truncated by
     // `process.exit` too, and an error message cut in half is the one a
@@ -174,7 +152,7 @@ function withCauses(err: unknown): string {
 process.on('beforeExit', () => {
   if (settled) return
   settled = true
-  ;(require('./util/index.js') as typeof import('./util/index.js')).ui.say(
+  ;(require('./ui/index.js') as typeof import('./ui/index.js')).say(
     'error',
     'vx: the run stopped before it finished: something it awaited can never settle (a plugin hook?)',
   )

package/src/cache/cache.ts

@@ -117,8 +117,8 @@ import { FileHashStore } from './file-hashes.js'
 import { DIR_MODE, LINK_MODE, OutputIndex } from './output-index.js'
 import { RunHistory } from './run-history.js'
 import { CACHE_VERSION, foldKey } from './key-fold.js'
-import { FoldMemo } from './fold-memo.js'
-import { RemoteHits } from './remote-hits.js'
+import { type FoldMemo, IndexFoldMemo } from './fold-memo.js'
+import { IndexRemoteHits, type RemoteHits } from './remote-hits.js'
 import { behindLink } from './linked-inputs.js'
 
 /**
@@ -130,6 +130,9 @@ import { behindLink } from './linked-inputs.js'
  * 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.
  */
+// About 1.3 ms of inserts per turn: a task's exit waits at most that.
+const HELD_SLICE = 250
+
 const ORPHAN_GRACE_MS = 60 * 60 * 1000
 
 /**
@@ -164,13 +167,8 @@ const VX_CACHE_NAMES = new Set([
   'cache.db-wal',
   'cache.db-shm',
   'cache.db-journal',
-  // run-failures.ts, run-steps.ts, orchestrator/lockfile-claim.ts. Run
-  // history lives in cache.db and the config bundle always in
-  // `.vx/cache/compiled`, so a `runs` or `compiled` here is the user's.
-  'failures',
-  'steps',
-  'warnings',
-  'lockfile-claims',
+  // Every record vx keeps lives in cache.db, and the config bundle always
+  // in `.vx/cache/compiled`, so any directory here is the user's.
 ])
 
 /**
@@ -357,7 +355,13 @@ function cantOpenIndex(dbFile: string, err: unknown): UserError | undefined {
 //   v49: runs.cpu_share — the share of a core each runnable thread got
 //        where the task ran, so a crowded run's CPU reads as need. The
 //        cache KEY is unchanged.
-export const SCHEMA_VERSION = 'v49'
+//   v50: steps, warnings, failures and lockfile_memos — what a run said
+//        and a lockfile claimant parsed, files under the cache dir until
+//        now (if it can be in the DB, it is). The cache KEY is unchanged.
+//   v51: runs.queued_ms, output_bytes, blocks, flaky_passes and
+//        flaky_failures — the rest of what a results row shows, so `vx
+//        last --sql` reads it. The cache KEY is unchanged.
+export const SCHEMA_VERSION = 'v51'
 
 /**
  * An entry's key components as its one `entry_inputs` row (v34): JSON
@@ -944,11 +948,22 @@ export class Cache implements CacheLayer {
   private adoptStats = 0
   /** The artifact directory's names, listed once past `ADOPT_STATS`; this process's writes kept in it. */
   private artifactNames: Set<string> | undefined
+  private heldBlobSizes: Array<[string, number]> | undefined
+  private heldTimer: ReturnType<typeof setTimeout> | undefined
+  /** Saves' index writes waiting for this turn's one transaction (`indexInBatch`). */
+  private indexQueue: Array<{ write: () => void; settle: (err?: unknown) => void }> = []
+  private heldRest: () => Array<[string, number]> = () => []
   private readonly insertEntryInput: ReturnType<Database['prepare']>
   /** The per-file (mtime, size) → blob-OID memo behind `hashFile`. */
   private readonly files: FileHashStore
   private readonly outputs: OutputIndex
-  private readonly folds: FoldMemo
+  /**
+   * Each entry `save()` wrote: its files' bytes, summed as the rows went in,
+   * for the miss row's `outputs` (a read back was one statement a miss;
+   * principle 9). Taken once, by `outputBytes`.
+   */
+  private readonly savedBytes = new Map<string, number>()
+  private readonly folds: IndexFoldMemo
   private readonly history: RunHistory
   /** What the remotes said they hold, across runs (remote-hits.ts). */
   readonly remoteHits: RemoteHits
@@ -1172,7 +1187,7 @@ export class Cache implements CacheLayer {
             // keeps it so).
             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.task_durations; DROP TABLE IF EXISTS main.plugin_blobs; DROP TABLE IF EXISTS main.task_outcomes; DROP TABLE IF EXISTS main.store_meta; DROP TABLE IF EXISTS main.fold_memo; DROP TABLE IF EXISTS main.remote_hits;',
+                '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.task_durations; DROP TABLE IF EXISTS main.plugin_blobs; DROP TABLE IF EXISTS main.task_outcomes; DROP TABLE IF EXISTS main.store_meta; DROP TABLE IF EXISTS main.fold_memo; DROP TABLE IF EXISTS main.remote_hits; DROP TABLE IF EXISTS main.steps; DROP TABLE IF EXISTS main.warnings; DROP TABLE IF EXISTS main.failures; DROP TABLE IF EXISTS main.lockfile_memos;',
               )
             }
             // The tables land under the same write lock as the stamp: made
@@ -1237,12 +1252,13 @@ export class Cache implements CacheLayer {
         }
       }
     }
-    if (storeDir !== undefined && mode === 'open' && this.writeBlocked === null) {
-      // An index that held its entries itself would shadow the store's:
-      // SQLite resolves an unqualified name in `main` first. Its history
-      // and memos stay; its entries' artifact files are orphans `prune`
-      // reaps, and its inline artifacts go with their table.
-      const holds = readable(
+    // An index that held its entries itself (no store yet: a repository
+    // before its first commit) hands them to the store below.
+    const holds =
+      storeDir !== undefined &&
+      mode === 'open' &&
+      this.writeBlocked === null &&
+      readable(
         () =>
           this.db
             .prepare(
@@ -1250,16 +1266,6 @@ export class Cache implements CacheLayer {
             )
             .get() != null,
       )
-      if (holds) {
-        this.db
-          .transaction(() => {
-            for (const t of [...STORE_TABLES, ...ARTIFACT_TABLES]) {
-              this.db.exec(`DROP TABLE IF EXISTS main.${t}`)
-            }
-          })
-          .immediate()
-      }
-    }
     this.storeDir = storeDir
     this.artifactDir = storeDir ?? cacheDir
     if (storeDir !== undefined) {
@@ -1273,6 +1279,7 @@ export class Cache implements CacheLayer {
     if (mode === 'open' && this.writeBlocked === null && (foreign || storeDir !== recorded)) {
       readable(() => this.matchArtifactLayout(storeDir === undefined ? 'main' : 'store'))
     }
+    if (holds) this.carryEntries(cacheDir, storeDir!)
     if (mode === 'open' && this.writeBlocked === null && storeDir !== recorded) {
       if (storeDir === undefined)
         this.db.prepare("DELETE FROM schema_meta WHERE key = 'store_dir'").run()
@@ -1336,9 +1343,9 @@ export class Cache implements CacheLayer {
     // the schema above is the one place every table is declared.
     this.files = new FileHashStore(this.db, cacheDir, this.write, repoDir)
     this.outputs = new OutputIndex(this.db, this.writeBlocked === null && !this.inspecting)
-    this.folds = new FoldMemo(this.db, this.write && !this.inspecting)
+    this.folds = new IndexFoldMemo(this.db, this.write && !this.inspecting)
     this.history = new RunHistory(this.db, (v) => this.digestValue(v))
-    this.remoteHits = new RemoteHits(this.db, this.writeBlocked === null && !this.inspecting)
+    this.remoteHits = new IndexRemoteHits(this.db, this.writeBlocked === null && !this.inspecting)
 
     // A CACHE_VERSION bump keeps the index but moves every key, so the run
     // after an upgrade misses everything. Roadmap 3.3: that is announced,
@@ -1398,6 +1405,68 @@ export class Cache implements CacheLayer {
     }
   }
 
+  /**
+   * The entries an index held itself, moved into the store it now opens:
+   * the same keys over the same bytes, so the first run after a
+   * repository's first commit replays what the run before it saved. Then
+   * dropped from the index, where an unqualified name would shadow the
+   * store's. An artifact file that cannot be renamed there (another
+   * device) is left for `prune`, and its entry is a miss.
+   */
+  private carryEntries(cacheDir: string, storeDir: string): void {
+    const has = (schema: 'main' | 'store', table: string): boolean =>
+      this.db
+        .prepare(`SELECT 1 FROM ${schema}.sqlite_master WHERE type = 'table' AND name = ?`)
+        .get(table) != null
+    const layout = (schema: 'main' | 'store'): string | undefined =>
+      has(schema, 'artifacts_meta')
+        ? (
+            this.db
+              .prepare(`SELECT value FROM ${schema}.artifacts_meta WHERE key = 'layout'`)
+              .get() as { value: string } | null
+          )?.value
+        : undefined
+    if (storeDir !== cacheDir) {
+      let names: string[] = []
+      try {
+        names = readdirSync(cacheDir)
+      } catch {
+        // No directory: nothing to carry.
+      }
+      for (const name of names) {
+        if (!name.endsWith('.tar.zst') && !name.endsWith('.tree')) continue
+        const to = path.join(storeDir, name)
+        if (existsSync(to)) continue
+        try {
+          renameSync(path.join(cacheDir, name), to)
+        } catch {
+          // Another device: the artifact stays an orphan here.
+        }
+      }
+    }
+    this.db
+      .transaction(() => {
+        // `entries` first: the other tables' rows reference it.
+        for (const t of STORE_TABLES.toReversed()) {
+          if (t !== 'store_meta' && has('main', t) && has('store', t)) {
+            this.db.exec(`INSERT OR IGNORE INTO store.${t} SELECT * FROM main.${t}`)
+          }
+        }
+        if (
+          has('main', 'artifacts') &&
+          has('store', 'artifacts') &&
+          layout('main') === ARTIFACT_LAYOUT &&
+          layout('store') === ARTIFACT_LAYOUT
+        ) {
+          this.db.exec('INSERT OR IGNORE INTO store.artifacts SELECT * FROM main.artifacts')
+        }
+        for (const t of [...STORE_TABLES, ...ARTIFACT_TABLES]) {
+          this.db.exec(`DROP TABLE IF EXISTS main.${t}`)
+        }
+      })
+      .immediate()
+  }
+
   /**
    * Attach the shared store as `store`, with the pragmas the index takes:
    * WAL for both, so a workspace's run and another's share the store as
@@ -1582,7 +1651,32 @@ export class Cache implements CacheLayer {
   }
   /** `BlobSizeMemo`: remember blob sizes, honouring the local WRITE axis. */
   rememberBlobSizes(sizes: ReadonlyMap<string, number>): void {
-    this.guard(() => this.files.rememberBlobSizes(sizes))
+    if (this.heldBlobSizes !== undefined) for (const e of sizes) this.heldBlobSizes.push(e)
+    else this.guard(() => this.files.rememberBlobSizes(sizes))
+  }
+  /**
+   * Hold the blob sizes remembered from now on until `storeHeldBlobSizes`
+   * or `close`: a run learns them before its first task, where storing
+   * 40,030 cost a cold 9,603-task run 217 ms (2026-11-01).
+   */
+  holdBlobSizes(): void {
+    this.heldBlobSizes ??= []
+  }
+  /**
+   * Store the held blob sizes `HELD_SLICE` per event-loop turn from the
+   * next turn on, while the run's tasks run; `close` stores the rest.
+   */
+  storeHeldBlobSizes(): void {
+    const held = this.heldBlobSizes
+    this.heldBlobSizes = undefined
+    if (held === undefined || held.length === 0) return
+    let at = 0
+    const step = (): void => {
+      this.guard(() => this.files.rememberBlobSizes(new Map(held.slice(at, (at += HELD_SLICE)))))
+      this.heldTimer = at < held.length ? setTimeout(step, 0) : undefined
+    }
+    this.heldRest = () => held.slice(at)
+    this.heldTimer = setTimeout(step, 0)
   }
   /** `BlobSizeMemo`: the paths an index with this digest distrusts, when known. */
   blobVerdict(digest: string): string[] | undefined {
@@ -1757,7 +1851,7 @@ export class Cache implements CacheLayer {
   }
 
   /** An adoption's verdict: an artifact that fails the checks is a miss. */
-  private async adopted(indexing: Promise<void>): Promise<boolean> {
+  private async adopted(indexing: Promise<unknown>): Promise<boolean> {
     try {
       await indexing
       return true
@@ -1955,6 +2049,11 @@ export class Cache implements CacheLayer {
   outputsPath(hash: string): string {
     return this.tarPath(hash)
   }
+  outputBytes(hash: string): number | undefined {
+    const bytes = this.savedBytes.get(hash)
+    this.savedBytes.delete(hash)
+    return bytes
+  }
   artifactSize(hash: string): number | undefined {
     return this.guard(
       () =>
@@ -2048,7 +2147,15 @@ export class Cache implements CacheLayer {
    * uploaded under a fresh sum.
    */
   private treePlan(hash: string, tree: string, rows: readonly OutputFileRow[]): ArtifactPlan {
-    const plan = planOfTree(tree, this.stdoutText(hash))
+    let plan: ArtifactPlan
+    try {
+      plan = planOfTree(tree, this.stdoutText(hash))
+    } catch (err) {
+      // A sidecar cut short at rest, as a file is: named as the damage it is.
+      if (err instanceof SyntaxError)
+        throw new CorruptArtifactError(hash, 'its sidecar does not parse')
+      throw err
+    }
     const size = new Map(rows.map((r) => [treeName(r.path), r.size]))
     for (const i of plan.inputs) {
       const want = size.get(i.name)
@@ -2490,7 +2597,16 @@ export class Cache implements CacheLayer {
     if (!this.write) return
     // A cache that reads saves only on a miss. One that does not (`--force`)
     // re-executes a key it may hold: that entry is kept as it is.
-    if (!this.read && this.guard(() => this.storedHere(args.hash))) return
+    // The kept entry's bytes are this run's too (same key): the row's
+    // `outputs` counts them as a hit would.
+    if (!this.read && this.guard(() => this.storedHere(args.hash))) {
+      const rows = this.loadOutputFilesBatch([args.hash]).get(args.hash) ?? []
+      this.savedBytes.set(
+        args.hash,
+        rows.reduce((n, r) => n + r.size, 0),
+      )
+      return
+    }
     // The cache directory is the constructor's (`mkdirSync`, with a
     // refusal recorded for `assertWritable`); re-creating it here and
     // again in `writeArtifactAndIndex` cost every save two thread-pool
@@ -2507,7 +2623,7 @@ export class Cache implements CacheLayer {
       throw err
     })
     endPack()
-    await this.guard(() =>
+    const bytes = await this.guard(() =>
       this.writeArtifactAndIndex(
         args.hash,
         'tar' in packed ? packed.compressed : 'plan' in packed ? packed.saved : packed,
@@ -2520,6 +2636,7 @@ export class Cache implements CacheLayer {
         'tar' in packed ? packed.tar : undefined,
       ),
     )
+    this.savedBytes.set(args.hash, bytes)
   }
 
   /**
@@ -2829,7 +2946,7 @@ export class Cache implements CacheLayer {
      * scanned as is rather than decoded back out of the bytes just encoded.
      */
     tar?: Uint8Array,
-  ): Promise<void> {
+  ): Promise<number> {
     // Validate BEFORE anything touches the final path. `ingest()` feeds
     // us a temp of network bytes; a truncated/garbage body that went live first
     // would leave a corrupt `<hash>.tar.zst` behind (with no SQL row,
@@ -3051,6 +3168,7 @@ export class Cache implements CacheLayer {
     const upsertStdout = this.upsertStdout
     const deleteStdout = this.deleteStdout
     const outputs = this.outputs
+    let outputBytes = 0
     const insertEntryInput = this.insertEntryInput
     const inputComponents = meta.inputComponents
     // The artifact goes live INSIDE the write transaction, taken
@@ -3142,7 +3260,7 @@ export class Cache implements CacheLayer {
           hash,
           stdoutText.startsWith('\uFEFF') ? utf8.encode(stdoutText) : stdoutText,
         )
-      outputs.replaceFileRows(hash, outputFileRows)
+      outputBytes = outputs.replaceFileRows(hash, outputFileRows)
       // INSERT OR IGNORE: identical inputs derive this same hash, so a
       // re-save's row is identical — keep the first, skip the rest.
       if (inputComponents !== undefined && inputComponents.length > 0) {
@@ -3154,7 +3272,7 @@ export class Cache implements CacheLayer {
       // Built inside the try: on a database a stopping run closed while a
       // download streamed in, building it throws, and the temp or tree
       // the body went to stayed behind.
-      this.db.transaction(index).immediate()
+      await this.indexInBatch(index)
     } catch (err) {
       endTx()
       const left = renamed ?? tree ?? tmpPath
@@ -3164,6 +3282,57 @@ export class Cache implements CacheLayer {
     }
     endTx()
     for (const a of aside) await rm(a, { recursive: true, force: true })
+    return outputBytes
+  }
+
+  /**
+   * Run `write` in a write transaction shared with every other save's that
+   * arrives in this turn: settles once it has committed, or rejects with
+   * its own error (its savepoint rolled back) or the commit's. A cold run's
+   * saves land a few per turn, and a transaction each spent half its index
+   * time on BEGIN and COMMIT on the main thread, the run's busiest
+   * (2026-11-03: 81 of 164 ms over 500 saves).
+   */
+  private indexInBatch(write: () => void): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.indexQueue.push({
+        write,
+        settle: (err) => (err === undefined ? resolve() : reject(err)),
+      })
+      if (this.indexQueue.length === 1) setImmediate(() => this.flushIndex())
+    })
+  }
+
+  private flushIndex(): void {
+    const batch = this.indexQueue
+    if (batch.length === 0) return
+    this.indexQueue = []
+    const failed = new Map<number, unknown>()
+    try {
+      this.db
+        .transaction(() => {
+          for (let i = 0; i < batch.length; i++) {
+            // An error SQLite answers by rolling the whole transaction
+            // back (a full disk, a busy lock) leaves none to go on in: the
+            // rest are not run, and fail with it.
+            if (failed.size > 0 && !this.db.inTransaction) {
+              failed.set(i, failed.values().next().value)
+              continue
+            }
+            try {
+              // Nested: a savepoint, so one write's failure undoes only its own rows.
+              this.db.transaction(batch[i]!.write)()
+            } catch (err) {
+              failed.set(i, err)
+            }
+          }
+        })
+        .immediate()
+    } catch (err) {
+      for (let i = 0; i < batch.length; i++) batch[i]!.settle(failed.get(i) ?? err)
+      return
+    }
+    for (let i = 0; i < batch.length; i++) batch[i]!.settle(failed.get(i))
   }
 
   private tempTreePath(hash: string): string {
@@ -3210,17 +3379,6 @@ export class Cache implements CacheLayer {
     this.db.prepare(`UPDATE entries SET accessed_at = ? WHERE hash ${test}`).run(now, ...params)
   }
 
-  /**
-   * Raw `bun:sqlite` Database handle. Exposed for subsystems that
-   * need to issue their own queries (LocalHistoryProvider's CTE,
-   * future analytics consumers) without us proxying every method.
-   * Callers must NOT close the handle directly — `Cache.close()` owns
-   * the lifetime.
-   */
-  dbHandle(): Database {
-    return this.db
-  }
-
   // --- run history: delegated to `RunHistory` (see run-history.ts) ---
   // A run over a directory it cannot write records no history:
   // `readOnlyNotice` said so once.
@@ -3528,6 +3686,12 @@ export class Cache implements CacheLayer {
 
   close(): void {
     try {
+      this.flushIndex()
+      clearTimeout(this.heldTimer)
+      const held = this.heldBlobSizes ?? (this.heldTimer !== undefined ? this.heldRest() : [])
+      this.heldBlobSizes = undefined
+      this.heldTimer = undefined
+      if (held.length > 0) this.files.rememberBlobSizes(new Map(held))
       this.flushAccessed()
       this.outputs.flushOutputDirs()
       this.folds.flush()
@@ -3564,7 +3728,17 @@ export class Cache implements CacheLayer {
 }
 
 /** SQLite's file-control opcode (sqlite3.h). */
-const SQLITE_FCNTL_PERSIST_WAL = 10
+export const SQLITE_FCNTL_PERSIST_WAL = 10
+
+/**
+ * The cache's `bun:sqlite` handle, for core's own readers (`vx last`, `vx
+ * why`, the history provider). A function, not a member: the façade hands
+ * `Cache` to plugins and no plugin touches cache.db (2026-10-29). Callers
+ * never close it — `Cache.close()` owns the lifetime.
+ */
+export function indexDb(cache: Cache): Database {
+  return cache['db']
+}
 
 /**
  * Close for real. A plain `close()` leaves the connection open while any
@@ -3577,7 +3751,7 @@ const SQLITE_FCNTL_PERSIST_WAL = 10
  * `vx run` exited 1 with that stack after its tasks had passed (M-44). There
  * the deferred close is the one that closes.
  */
-function closeDb(db: Database): void {
+export function closeDb(db: Database): void {
   try {
     db.close(true)
   } catch {

package/src/cache/file-hashes.ts

@@ -72,6 +72,9 @@ export class FileHashStore {
   /** Each of `oids` whose size a `rememberBlobSizes` stored: one `IN` query per 900. */
   knownBlobSizes(oids: readonly string[]): Map<string, number> {
     const out = new Map<string, number>()
+    // An empty memo (a cold cache) answers nothing: 40,030 lookups there
+    // cost a 9,603-task run 57 ms before its first task (2026-11-01).
+    if (this.db.query('SELECT 1 FROM blob_sizes LIMIT 1').get() === null) return out
     for (let i = 0; i < oids.length; i += 900) {
       const chunk = oids.slice(i, i + 900)
       const rows = this.db