@vzn/vx 0.0.648 → 0.0.650

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.648",
+  "version": "0.0.650",
   "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.648",
-    "@vzn/vx-linux-arm64": "0.0.648",
-    "@vzn/vx-darwin-x64": "0.0.648",
-    "@vzn/vx-darwin-arm64": "0.0.648"
+    "@vzn/vx-linux-x64": "0.0.650",
+    "@vzn/vx-linux-arm64": "0.0.650",
+    "@vzn/vx-darwin-x64": "0.0.650",
+    "@vzn/vx-darwin-arm64": "0.0.650"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

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'
 
 /**
@@ -164,13 +164,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 +352,10 @@ 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.
+export const SCHEMA_VERSION = 'v50'
 
 /**
  * An entry's key components as its one `entry_inputs` row (v34): JSON
@@ -948,7 +946,7 @@ export class Cache implements CacheLayer {
   /** The per-file (mtime, size) → blob-OID memo behind `hashFile`. */
   private readonly files: FileHashStore
   private readonly outputs: OutputIndex
-  private readonly folds: FoldMemo
+  private readonly folds: IndexFoldMemo
   private readonly history: RunHistory
   /** What the remotes said they hold, across runs (remote-hits.ts). */
   readonly remoteHits: RemoteHits
@@ -1172,7 +1170,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
@@ -1336,9 +1334,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,
@@ -3210,17 +3208,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.
@@ -3564,7 +3551,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 +3574,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/fold-memo.ts

@@ -13,7 +13,14 @@ export interface FoldMemoRow {
   key: string
 }
 
-export class FoldMemo {
+/** What a key fold asks of the memo; the rows stay core's (`IndexFoldMemo`). */
+export interface FoldMemo {
+  /** The key remembered for `taskId` under `probe`, if that is the probe it was folded under. */
+  get(taskId: string, probe: string): string | undefined
+  set(taskId: string, probe: string, key: string): void
+}
+
+export class IndexFoldMemo implements FoldMemo {
   private rows: Map<string, FoldMemoRow> | undefined
   private readonly dirty = new Map<string, FoldMemoRow>()
 

package/src/cache/index.ts

@@ -18,6 +18,7 @@ export {
   type CachePolicy,
   cachesNothing,
   EXECUTED_RUNS_SQL,
+  indexDb,
   formatCachePolicy,
   FULL_CACHE_POLICY,
   type InvocationRecord,
@@ -102,3 +103,13 @@ export {
 } from './plugin-cache.js'
 export { packRunOutputs, putRunEntry, runEntryName, writesRunStore } from './run-store.js'
 export { branchSource } from './run-history.js'
+export {
+  type KeptFailure,
+  keepRunNotes,
+  keptFailures,
+  keptSteps,
+  keptWarnings,
+  type RunNotes,
+  type RunStep,
+} from './run-notes.js'
+export { readLockfileMemo, writeLockfileMemo, type LockfileMemo } from './lockfile-memo.js'

package/src/cache/lockfile-memo.ts

@@ -0,0 +1,119 @@
+// A lockfile claimant's parse, kept in cache.db's `lockfile_memos` (v50; a
+// `lockfile-claims/` file before): what orchestrator/lockfile-claim.ts reads
+// so a warm run never parses the lockfile. Its readers run where no `Cache`
+// is open yet — a `discover` hook, `--affected`'s selection, a verb that
+// opens none — so each call opens the index on its own and closes it. Only
+// an index that exists and holds this vx's schema is read or written: one
+// another vx wrote is reset by the next run, and a directory with none is
+// left for the run that makes it. A failure of any kind is a miss: the memo
+// is a speed-up, never a requirement.
+
+import { Database } from 'bun:sqlite'
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { closeDb, SCHEMA_VERSION, SQLITE_FCNTL_PERSIST_WAL } from './cache.js'
+
+/** One claimant's parse of one lockfile's content. */
+export interface LockfileMemo {
+  /** The claimant's own counter: bumped when it digests differently. */
+  version: number
+  /** xxh3 of the lockfile's bytes. */
+  lock: string
+  /** Each extra file the digests read → its content hash then. */
+  extras: Record<string, string>
+  importers: Record<string, string>
+  edges: Record<string, unknown>
+  /** Each importer's recorded dependency names; absent when the claimant reads none. */
+  recorded?: Record<string, readonly string[]>
+}
+
+function withIndex<T>(cacheDir: string, use: (db: Database) => T): T | undefined {
+  const file = path.join(cacheDir, 'cache.db')
+  if (!existsSync(file)) return undefined
+  let db: Database
+  try {
+    db = new Database(file, { readwrite: true })
+  } catch {
+    return undefined
+  }
+  try {
+    // As `Cache` opens it: wait for another run's write, and keep `-wal`
+    // and `-shm` when this is the last connection to close (O-10).
+    db.exec('PRAGMA busy_timeout = 5000')
+    db.fileControl(SQLITE_FCNTL_PERSIST_WAL, 1)
+    db.exec('PRAGMA journal_size_limit = 67108864')
+    return use(db)
+  } catch {
+    return undefined
+  } finally {
+    closeDb(db)
+  }
+}
+
+const CURRENT = "(SELECT value FROM schema_meta WHERE key = 'version') = ?"
+
+/** The memo `claimant` kept of `file`; undefined when none or another content's. */
+export function readLockfileMemo(
+  cacheDir: string,
+  file: string,
+  claimant: string,
+): LockfileMemo | undefined {
+  return withIndex(cacheDir, (db) => {
+    const row = db
+      .query(
+        `SELECT version, lock, extras, importers, edges, recorded FROM lockfile_memos
+         WHERE file = ? AND claimant = ? AND ${CURRENT}`,
+      )
+      .get(file, claimant, SCHEMA_VERSION) as {
+      version: number
+      lock: string
+      extras: string
+      importers: string
+      edges: string
+      recorded: string | null
+    } | null
+    if (row === null) return undefined
+    return {
+      version: row.version,
+      lock: row.lock,
+      extras: JSON.parse(row.extras) as Record<string, string>,
+      importers: JSON.parse(row.importers) as Record<string, string>,
+      edges: JSON.parse(row.edges) as Record<string, unknown>,
+      ...(row.recorded !== null
+        ? { recorded: JSON.parse(row.recorded) as Record<string, readonly string[]> }
+        : {}),
+    }
+  })
+}
+
+/** Keep `memo` as `claimant`'s of `file`, replacing the last; false when it was not kept. */
+export function writeLockfileMemo(
+  cacheDir: string,
+  file: string,
+  claimant: string,
+  memo: LockfileMemo,
+): boolean {
+  return (
+    withIndex(
+      cacheDir,
+      (db) =>
+        db
+          .query(
+            `INSERT OR REPLACE INTO lockfile_memos
+               (file, claimant, version, lock, extras, importers, edges, recorded)
+             SELECT ?, ?, ?, ?, ?, ?, ?, ? WHERE ${CURRENT}`,
+          )
+          .run(
+            file,
+            claimant,
+            memo.version,
+            memo.lock,
+            JSON.stringify(memo.extras),
+            JSON.stringify(memo.importers),
+            JSON.stringify(memo.edges),
+            memo.recorded === undefined ? null : JSON.stringify(memo.recorded),
+            SCHEMA_VERSION,
+          ).changes > 0,
+    ) ?? false
+  )
+}

package/src/cache/remote-hits.ts

@@ -12,7 +12,15 @@ export interface RemoteHit {
   readonly durationMs?: number
 }
 
-export class RemoteHits {
+/** What a layered cache asks of the remote-hit rows; the rows stay core's (`IndexRemoteHits`). */
+export interface RemoteHits {
+  /** The keys of `hashes` a remote last said it holds. */
+  get(hashes: readonly string[]): Map<string, RemoteHit>
+  record(asked: readonly string[], found: ReadonlyMap<string, RemoteHit>, now?: number): void
+  forget(hash: string): void
+}
+
+export class IndexRemoteHits implements RemoteHits {
   constructor(
     private readonly db: Database,
     /** Off for a reading verb or an index this user cannot write. */

package/src/cache/run-notes.ts

@@ -0,0 +1,123 @@
+// What a run said that its `runs` rows do not hold, for `vx last`: the steps
+// it did not wait on (`vx:prefetch`, 2026-10-16), which never show in a
+// run's output; its warnings, which scroll past on a terminal (an agent
+// reading the run afterwards saw only the footer's count, 2026-10-28); and
+// each failed task's output and the files it names. Rows of cache.db's
+// `steps`, `warnings` and `failures` (v50; files under the cache dir
+// before), so `vx last --sql` reads them too. The newest `KEPT` runs that
+// had any are kept, per table. A run with none writes nothing.
+
+import type { Database } from 'bun:sqlite'
+
+/** Runs whose steps, warnings or failures are kept; run ids are UUIDv7, so they sort by age. */
+const KEPT = 50
+
+/** One of vx's own steps that ran beside the tasks. */
+export interface RunStep {
+  id: string
+  durationMs: number
+  ok: boolean
+}
+
+/** A failed task's kept output: plain, bounded, secrets masked. */
+export interface KeptFailure {
+  taskId: string
+  inputMoved?: string
+  output: string
+  locations: readonly unknown[]
+  sandboxFix?: unknown
+}
+
+export interface RunNotes {
+  readonly steps?: readonly RunStep[]
+  readonly warnings?: readonly string[]
+  readonly failures?: readonly KeptFailure[]
+}
+
+/** Drop every row of `table` older than its newest `KEPT` runs. */
+function trim(db: Database, table: 'steps' | 'warnings' | 'failures'): void {
+  db.query(
+    `DELETE FROM ${table} WHERE run_id < (SELECT run_id FROM (SELECT DISTINCT run_id FROM ${table} ORDER BY run_id DESC LIMIT 1 OFFSET ${KEPT - 1}))`,
+  ).run()
+}
+
+/** Write `notes` for `runId` in one transaction, then keep the newest `KEPT` runs of each table written. */
+export function keepRunNotes(db: Database, runId: string, notes: RunNotes): void {
+  const steps = notes.steps ?? []
+  const warnings = notes.warnings ?? []
+  const failures = notes.failures ?? []
+  if (steps.length + warnings.length + failures.length === 0) return
+  db.transaction(() => {
+    if (steps.length > 0) {
+      const insert = db.query(
+        'INSERT OR REPLACE INTO steps(run_id, seq, step, duration_ms, ok) VALUES (?, ?, ?, ?, ?)',
+      )
+      steps.forEach((s, i) => insert.run(runId, i, s.id, Math.round(s.durationMs), s.ok ? 1 : 0))
+      trim(db, 'steps')
+    }
+    if (warnings.length > 0) {
+      const insert = db.query('INSERT OR REPLACE INTO warnings(run_id, seq, text) VALUES (?, ?, ?)')
+      warnings.forEach((w, i) => insert.run(runId, i, w))
+      trim(db, 'warnings')
+    }
+    if (failures.length > 0) {
+      const insert = db.query(
+        `INSERT OR REPLACE INTO failures(run_id, task_id, input_moved, output, locations, sandbox_fix)
+         VALUES (?, ?, ?, ?, ?, ?)`,
+      )
+      for (const f of failures) {
+        insert.run(
+          runId,
+          f.taskId,
+          f.inputMoved ?? null,
+          f.output,
+          JSON.stringify(f.locations),
+          f.sandboxFix === undefined ? null : JSON.stringify(f.sandboxFix),
+        )
+      }
+      trim(db, 'failures')
+    }
+  }).immediate()
+}
+
+/** The background steps `runId` kept, in the order they ended; none when it had none. */
+export function keptSteps(db: Database, runId: string): RunStep[] {
+  const rows = db
+    .query('SELECT step, duration_ms, ok FROM steps WHERE run_id = ? ORDER BY seq')
+    .all(runId) as { step: string; duration_ms: number; ok: number }[]
+  return rows.map((r) => ({ id: r.step, durationMs: r.duration_ms, ok: r.ok === 1 }))
+}
+
+/** The warnings `runId` said, colour stripped; none when it said none. */
+export function keptWarnings(db: Database, runId: string): string[] {
+  const rows = db.query('SELECT text FROM warnings WHERE run_id = ? ORDER BY seq').all(runId) as {
+    text: string
+  }[]
+  return rows.map((r) => r.text)
+}
+
+/** What `runId` kept of its failed tasks, by task id; empty when it kept none. */
+export function keptFailures(db: Database, runId: string): Map<string, KeptFailure> {
+  const rows = db
+    .query(
+      'SELECT task_id, input_moved, output, locations, sandbox_fix FROM failures WHERE run_id = ?',
+    )
+    .all(runId) as {
+    task_id: string
+    input_moved: string | null
+    output: string
+    locations: string
+    sandbox_fix: string | null
+  }[]
+  const kept = new Map<string, KeptFailure>()
+  for (const r of rows) {
+    kept.set(r.task_id, {
+      taskId: r.task_id,
+      ...(r.input_moved !== null ? { inputMoved: r.input_moved } : {}),
+      output: r.output,
+      locations: JSON.parse(r.locations) as unknown[],
+      ...(r.sandbox_fix !== null ? { sandboxFix: JSON.parse(r.sandbox_fix) as unknown } : {}),
+    })
+  }
+  return kept
+}

package/src/cache/schema.ts

@@ -261,6 +261,49 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
       arch              TEXT,
       vx_version        TEXT NOT NULL
     );
+    -- v50: what a run said that its runs rows do not hold (run-notes.ts),
+    -- for \`vx last\`: the steps it did not wait on (\`vx:prefetch\`), its
+    -- warnings, colour stripped, and each failed task's output, plain,
+    -- bounded and masked, with the files it names (JSON). Rows of the
+    -- newest 50 runs that had any; run ids are UUIDv7, so they sort by age.
+    CREATE TABLE IF NOT EXISTS main.steps (
+      run_id      TEXT NOT NULL,
+      seq         INTEGER NOT NULL,
+      step        TEXT NOT NULL,
+      duration_ms INTEGER NOT NULL,
+      ok          INTEGER NOT NULL,
+      PRIMARY KEY (run_id, seq)
+    );
+    CREATE TABLE IF NOT EXISTS main.warnings (
+      run_id TEXT NOT NULL,
+      seq    INTEGER NOT NULL,
+      text   TEXT NOT NULL,
+      PRIMARY KEY (run_id, seq)
+    );
+    CREATE TABLE IF NOT EXISTS main.failures (
+      run_id      TEXT NOT NULL,
+      task_id     TEXT NOT NULL,
+      input_moved TEXT,
+      output      TEXT NOT NULL,
+      locations   TEXT NOT NULL,
+      sandbox_fix TEXT,
+      PRIMARY KEY (run_id, task_id)
+    );
+    -- v50: a lockfile claimant's parse (orchestrator/lockfile-claim.ts): one
+    -- row per lockfile and claimant, read while \`version\` and \`lock\` (the
+    -- file's xxh3) match, replaced when they do not. JSON: the extra files'
+    -- hashes, the importers' digests and edges, the names each records.
+    CREATE TABLE IF NOT EXISTS main.lockfile_memos (
+      file      TEXT NOT NULL,
+      claimant  TEXT NOT NULL,
+      version   INTEGER NOT NULL,
+      lock      TEXT NOT NULL,
+      extras    TEXT NOT NULL,
+      importers TEXT NOT NULL,
+      edges     TEXT NOT NULL,
+      recorded  TEXT,
+      PRIMARY KEY (file, claimant)
+    );
     CREATE INDEX IF NOT EXISTS main.invocations_started ON invocations(started_at);
     CREATE INDEX IF NOT EXISTS main.invocations_branch  ON invocations(branch);
     CREATE INDEX IF NOT EXISTS main.invocations_ci      ON invocations(ci);

package/src/cli/last.ts

@@ -5,7 +5,7 @@
 // Read-only — no config evaluation, no re-hash, no cache probe.
 
 import type { Database } from 'bun:sqlite'
-import { Cache } from '../cache/index.js'
+import { indexDb, Cache, keptSteps, keptWarnings, type RunStep } from '../cache/index.js'
 import { formatBytes } from './format.js'
 import { flagHint, formatValue, seeHelp } from './help.js'
 import {
@@ -24,9 +24,6 @@ import {
   exitSignal,
   resolveRunId,
   runFailures,
-  type RunStep,
-  runSteps,
-  runWarnings,
   shellQuote,
   shortRunId,
   taskLog,
@@ -358,8 +355,9 @@ async function printStats(
 }
 
 /**
- * `--sql`: one SELECT over the history (`runs`, `invocations`, and the
- * store's `entries`, `entry_inputs`, `task_durations`, `task_outcomes`),
+ * `--sql`: one SELECT over the history (`runs`, `invocations`, `steps`,
+ * `warnings`, `failures`, and the store's `entries`, `entry_inputs`,
+ * `task_durations`, `task_outcomes`),
  * so an agent asks what no flag answers: a task's memory trend, the
  * flakiest project, which input moved a key. `query_only` stops a write
  * the statement hides (`WITH … DELETE`); it does not stop ATTACH, which
@@ -806,7 +804,7 @@ export async function lastCmd(args: readonly string[]): Promise<number> {
   const cacheDir = await cliCacheDir(root, parsed.cacheDir)
   const cache = Cache.inspect(cacheDir)
   try {
-    const db = cache.dbHandle()
+    const db = indexDb(cache)
     // Nothing recorded at all is its own answer: `--failed` said "no
     // recorded run failed" and a run id pointed at a `--list` that lists
     // nothing, while `--list --failed` past green runs said there were none.
@@ -825,12 +823,7 @@ export async function lastCmd(args: readonly string[]): Promise<number> {
         parsed.runId === undefined
           ? undefined
           : (resolveRunId(db, parsed.runId, 'vx last') ?? parsed.runId)
-      const log = taskLog(
-        cacheDir,
-        db,
-        await bareTaskId(db, await rootSpelled(root, parsed.log)),
-        runId,
-      )
+      const log = taskLog(db, await bareTaskId(db, await rootSpelled(root, parsed.log)), runId)
       if (log === null) {
         // The id's form is hinted only when it lacks one: a task that
         // never ran was told how to spell a task id.
@@ -921,9 +914,7 @@ export async function lastCmd(args: readonly string[]): Promise<number> {
     const detail = getRun(db, inv.runId)
 
     if (parsed.format === 'json') {
-      const failures = new Map(
-        (runFailures(cacheDir, db, inv.runId)?.tasks ?? []).map((f) => [f.taskId, f]),
-      )
+      const failures = new Map((runFailures(db, inv.runId)?.tasks ?? []).map((f) => [f.taskId, f]))
       const tasks = (detail?.tasks ?? []).map((t) => {
         const f = failures.get(`${t.project}#${t.task}`)
         return f === undefined
@@ -937,8 +928,8 @@ export async function lastCmd(args: readonly string[]): Promise<number> {
               ...(f.fixedIn !== undefined ? { fixedIn: f.fixedIn } : {}),
             }
       })
-      const steps = runSteps(cacheDir, inv.runId)
-      const warnings = runWarnings(cacheDir, inv.runId)
+      const steps = keptSteps(db, inv.runId)
+      const warnings = keptWarnings(db, inv.runId)
       process.stdout.write(
         `${JSON.stringify({
           invocation: inv,
@@ -971,12 +962,12 @@ export async function lastCmd(args: readonly string[]): Promise<number> {
     )
     const moved = new Map<string, string>()
     if (inv.failedCount > 0) {
-      for (const f of runFailures(cacheDir, db, inv.runId)?.tasks ?? [])
+      for (const f of runFailures(db, inv.runId)?.tasks ?? [])
         if (f.inputMoved !== undefined) moved.set(f.taskId, f.inputMoved)
     }
     lines.push(...formatTaskRows(detail?.tasks ?? [], c, moved))
-    lines.push(...formatStepRows(runSteps(cacheDir, inv.runId), c))
-    const warnings = runWarnings(cacheDir, inv.runId)
+    lines.push(...formatStepRows(keptSteps(db, inv.runId), c))
+    const warnings = keptWarnings(db, inv.runId)
     if (warnings.length > 0) {
       lines.push('', '  warnings', ...warnings.flatMap((w) => w.split('\n').map((l) => `    ${l}`)))
     }

package/src/cli/plugin-commands.ts

@@ -7,6 +7,7 @@
 // reports an unknown command as it always did. Core's verbs are matched
 // before this is asked, so a plugin cannot shadow `run`.
 
+import { indexDb } from '../cache/index.js'
 import type { CachePolicy, PluginCache, ResolvedRemote } from '../cache/index.js'
 import type { WorkspaceConfig } from '../config.js'
 import type {
@@ -184,7 +185,7 @@ async function verbCache(
     remotes,
   })
   await openVerbRemotes(remotes, openRemotes)
-  return pluginCache(plugin, { db: localCache.dbHandle(), policy: VERB_POLICY, remotes, scope })
+  return pluginCache(plugin, { db: indexDb(localCache), policy: VERB_POLICY, remotes, scope })
 }
 
 /**

package/src/cli/why.ts

@@ -5,7 +5,7 @@
 // moved input file, no re-hash. Configs are evaluated only when a moved
 // upstream is a group: it records no run, so the graph names what it gathers.
 
-import { Cache } from '../cache/index.js'
+import { indexDb, Cache } from '../cache/index.js'
 import { anchoredSpecError, flagHint, formatValue, seeHelp } from './help.js'
 import { buildTaskGraph, isGroupTask, splitTaskId } from '../graph/index.js'
 import {
@@ -166,7 +166,7 @@ async function resolveTarget(
   target: string,
   cwdProject: () => Promise<string | null>,
 ): Promise<string> {
-  const db = cache.dbHandle()
+  const db = indexDb(cache)
   if (target.includes('#')) {
     // An exact id needs one row, and its newest is where a scan from the
     // top of the table finds it first — the full DISTINCT walk below is for
@@ -263,7 +263,7 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
   const root = await findWorkspaceRoot(process.cwd())
   const cache = Cache.inspect(await cliCacheDir(root, parsed.cacheDir))
   try {
-    const db = cache.dbHandle()
+    const db = indexDb(cache)
     const taskId = await resolveTarget(cache, await rootSpelled(root, parsed.target), () =>
       findCwdProject(process.cwd()),
     )

package/src/graph/scheduler.ts

@@ -88,6 +88,10 @@ export interface TaskOutcome {
    * its save wrote (measured only when a telemetry sink listens).
    */
   artifactBytes?: number
+  /**
+   * The raw bytes of a hit's outputs: the entry's files as restored.
+   */
+  outputBytes?: number
   /** On a remote hit this run pulled: the download and its ingest. */
   fetchMs?: number
   /** On a miss that saved, with a sink listening: the save's own time. */
@@ -304,7 +308,8 @@ export interface ScheduleOptions {
    */
   onFailFast?: () => void
   execute: (node: TaskNode, upstream: TaskOutcome[]) => Promise<TaskOutcome>
-  onStart?: (node: TaskNode) => void
+  /** `queuedMs`: how long the task waited ready for a slot, when it did. */
+  onStart?: (node: TaskNode, queuedMs?: number) => void
   onFinish?: (outcome: TaskOutcome) => void
   /**
    * Where the line naming a rejected `execute` goes, before its failed
@@ -959,9 +964,10 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
         return undefined
       }
     }
-    const started = (node: TaskNode): void => {
+    const started = (node: TaskNode, queuedMs = 0): void => {
       try {
-        onStart?.(node)
+        if (queuedMs > 0) onStart?.(node, queuedMs)
+        else onStart?.(node)
       } catch (err) {
         const m = thrownMessage(err)
         ui.say('warn', `[vx] onStart observer threw for ${node.id}: ${m}\n`)
@@ -1100,7 +1106,7 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
         const settle = settleInPlace(node, upstream)
         let now: TaskOutcome | undefined
         if (settle !== undefined) {
-          if (!demoted.has(id)) started(node)
+          if (!demoted.has(id)) started(node, queuedMs)
           try {
             now = settle()
           } catch {
@@ -1130,7 +1136,7 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
         // the dispatch loop (it would strand the tick with the slot held).
         // A demoted task's second dispatch is the same task, already started,
         // as is one whose settle threw.
-        if (!demoted.has(id) && settle === undefined) started(node)
+        if (!demoted.has(id) && settle === undefined) started(node, queuedMs)
 
         // `.then(onFulfilled, onRejected)` — NOT `.then(f).catch(g)`. The
         // rejection arm handles ONLY `execute()` rejecting; a throw from