@vzn/vx 0.0.649 → 0.0.651

package/src/exec/warm-shell.ts

@@ -0,0 +1,146 @@
+// A task's shell, started before the task is asked for. A slot that frees
+// on a cold run starts its next task at once, and sh's own exec was part of
+// that turn: 200 `sleep 0.02` took 4.4 ms each past their sleep spawned
+// fresh, 2.7 ms in a shell already waiting (2026-11-01). The spare holds
+// no task's directory or env: it waits on a pipe, and the task's script,
+// written when it is taken, moves it to the task's directory and exports
+// the task's env before the command runs, so each task still has a shell
+// of its own (its CPU and memory are the shell's) and vx keeps no process
+// beyond a run. Linux only, where a task's pipes are vx's own descriptors.
+
+import { closeSync, writeSync } from 'node:fs'
+import { taskShell } from '../util/index.js'
+import { flushGuard, listGroup } from './kill-tree.js'
+import { heldPipe, TaskPipes } from './pipes.js'
+import { type OffChild, spawnOff } from './spawn-off.js'
+
+/** A shell waiting for its task's script on descriptor 3. */
+export interface Spare {
+  readonly child: Promise<OffChild>
+  readonly pipes: TaskPipes
+  /** The write end of the script's pipe; closed once the script is in. */
+  readonly script: number
+}
+
+/**
+ * Spares kept waiting. Two: a cold run's slots free one at a time, and a
+ * burst (the run's first tasks) spawns fresh while the pool fills.
+ */
+const SPARES = 2
+
+const spares: Spare[] = []
+/** A spare that could not start (no libc pipes, a refused spawn): no more are tried. */
+let off = false
+
+// `exec 3<&-` first: dash reads the script through its own descriptor,
+// opened on /dev/fd/3 and closed on exec, so the task inherits no 3.
+const WAIT = '. /dev/fd/3'
+
+function start(): Spare | undefined {
+  const fds = heldPipe()
+  if (fds === undefined) return undefined
+  let sh: string
+  try {
+    sh = taskShell()
+  } catch {
+    // No shell on vx's PATH: the task's own spawn says so.
+    closeSync(fds[0]!)
+    closeSync(fds[1]!)
+    return undefined
+  }
+  const pipes = new TaskPipes()
+  // vx lists the spare's group itself, with the turn's other lines: the
+  // spare runs nothing before `runOnSpare` flushes them.
+  const child = spawnOff({
+    cmd: [sh, '-c', WAIT],
+    argv0: 'sh',
+    cwd: '/',
+    env: {},
+    detached: true,
+    held: false,
+    stdio: ['ignore', ...(pipes.stdio as [number, number]), fds[0]!],
+  }).then((c) => {
+    listGroup(c.pid)
+    return c
+  })
+  const settled = child.finally(() => {
+    pipes.spawned()
+    closeSync(fds[0]!)
+  })
+  settled.catch(() => {
+    off = true
+    pipes.close()
+    closeSync(fds[1]!)
+  })
+  return { child: settled, pipes, script: fds[1]! }
+}
+
+/** A spare for the next task, or undefined; starts another in its place. */
+export function takeSpare(): Spare | undefined {
+  const taken = spares.shift()
+  while (!off && spares.length < SPARES) {
+    const s = start()
+    if (s === undefined) {
+      off = true
+      break
+    }
+    spares.push(s)
+  }
+  return taken
+}
+
+const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
+const quote = (v: string): string => `'${v.replaceAll("'", "'\\''")}'`
+
+/**
+ * The script a spare runs as the task: its directory (127 when it is gone,
+ * as a spawn into it fails; the OLDPWD `cd` sets is not the task's), its
+ * env, then `command`. Undefined when an env
+ * name is one sh cannot export: that task spawns fresh.
+ */
+export function spareScript(
+  cwd: string,
+  env: Readonly<Record<string, string | undefined>>,
+  command: string,
+): string | undefined {
+  // A script past what one pipe write lands whole would hold vx's thread.
+  if (command.length > SCRIPT_BYTES) return undefined
+  let out = `exec 3<&-\ncd -- ${quote(cwd)} 2>/dev/null || exit 127\nunset OLDPWD\n`
+  for (const k in env) {
+    const v = env[k]
+    // Undefined unsets the name: a spawn drops it.
+    if (v === undefined) continue
+    if (!NAME.test(k)) return undefined
+    out += `export ${k}=${quote(v)}\n`
+  }
+  out += `${command}\n`
+  return Buffer.byteLength(out) > SCRIPT_BYTES ? undefined : out
+}
+
+/** A pipe holds 64 KiB: a script under it is written without waiting on the shell's read. */
+const SCRIPT_BYTES = 60 * 1024
+
+/**
+ * Hand `spare` its script. False when the spare is gone (killed, or its
+ * spawn refused): the task then spawns fresh.
+ */
+export async function runOnSpare(spare: Spare, script: string): Promise<OffChild | undefined> {
+  let child: OffChild
+  try {
+    child = await spare.child
+  } catch {
+    return undefined
+  }
+  try {
+    // Its group listed before it runs a line of the task.
+    flushGuard()
+    writeSync(spare.script, script)
+  } catch {
+    child.kill('SIGKILL')
+    return undefined
+  } finally {
+    closeSync(spare.script)
+  }
+  child.hold()
+  return child
+}

package/src/graph/critical-path.ts

@@ -29,14 +29,26 @@ export function criticalPath(
       ? (p50s[Math.floor(p50s.length / 2)] ?? DEFAULT_DURATION_MS)
       : DEFAULT_DURATION_MS
 
-  const dependentsOf = new Map<string, string[]>()
-  for (const n of nodes) {
-    for (const upstreamId of n.deps) {
-      const list = dependentsOf.get(upstreamId)
-      if (list) list.push(n.id)
-      else dependentsOf.set(upstreamId, [n.id])
+  // Integer ids and flat arrays: Maps keyed by id strings and an array per
+  // node were 53 ms of a 9,603-task run's schedule stage (2026-11-01).
+  const count = nodes.length
+  const index = new Map<string, number>()
+  for (let i = 0; i < count; i++) index.set(nodes[i]!.id, i)
+  // Each node's dependents, as one flat list sliced by `first`.
+  const ups: number[] = []
+  const first = new Int32Array(count + 1)
+  for (let i = 0; i < count; i++) {
+    for (const up of nodes[i]!.deps) {
+      const u = index.get(up)
+      if (u === undefined) continue
+      first[u + 1]!++
+      ups.push(u, i)
     }
   }
+  for (let i = 0; i < count; i++) first[i + 1]! += first[i]!
+  const next = first.slice(0, count)
+  const dependents = new Int32Array(ups.length / 2)
+  for (let e = 0; e < ups.length; e += 2) dependents[next[ups[e]!]!++] = ups[e + 1]!
   // A group runs nothing, so it has no history; the median would charge it
   // a whole task and let a gate outrank the longest chain (PR #3286).
   const ownDuration = (n: TaskNode): number =>
@@ -47,33 +59,33 @@ export function criticalPath(
   // Reverse-topological pass: a node's value is final once every dependent's
   // is, so start from the sinks (no dependents) and release each upstream
   // when its last dependent has been scored.
-  const memo = new Map<string, number>()
-  const nodeById = new Map<string, TaskNode>(nodes.map((n) => [n.id, n]))
-  const pending = new Map<string, number>()
-  const queue: TaskNode[] = []
-  for (const n of nodes) {
-    const count = dependentsOf.get(n.id)?.length ?? 0
-    pending.set(n.id, count)
-    if (count === 0) queue.push(n)
+  const score = new Float64Array(count)
+  const scored = new Uint8Array(count)
+  const pending = new Int32Array(count)
+  const queue = new Int32Array(count)
+  let tail = 0
+  for (let i = 0; i < count; i++) {
+    pending[i] = first[i + 1]! - first[i]!
+    if (pending[i] === 0) queue[tail++] = i
   }
-  let head = 0
-  while (head < queue.length) {
-    const n = queue[head++]!
+  for (let head = 0; head < tail; head++) {
+    const i = queue[head]!
     let downstream = 0
-    for (const dep of dependentsOf.get(n.id) ?? []) {
-      const d = memo.get(dep) ?? 0
+    for (let e = first[i]!; e < first[i + 1]!; e++) {
+      const d = score[dependents[e]!]!
       if (d > downstream) downstream = d
     }
-    memo.set(n.id, ownDuration(n) + downstream)
-    for (const up of n.deps) {
-      const left = (pending.get(up) ?? 0) - 1
-      pending.set(up, left)
-      if (left === 0) {
-        const upNode = nodeById.get(up)
-        if (upNode) queue.push(upNode)
-      }
+    score[i] = ownDuration(nodes[i]!) + downstream
+    scored[i] = 1
+    for (const up of nodes[i]!.deps) {
+      const u = index.get(up)
+      if (u !== undefined && --pending[u]! === 0) queue[tail++] = u
     }
   }
-  for (const n of nodes) if (!memo.has(n.id)) memo.set(n.id, ownDuration(n))
+  const memo = new Map<string, number>()
+  for (let head = 0; head < tail; head++) memo.set(nodes[queue[head]!]!.id, score[queue[head]!]!)
+  // A node on a cycle is never released: its own duration.
+  for (let i = 0; i < count; i++)
+    if (scored[i] === 0) memo.set(nodes[i]!.id, ownDuration(nodes[i]!))
   return memo
 }

package/src/graph/priorities.ts

@@ -156,29 +156,47 @@ export function computeReverseDepCount(
   /** Count only these dependents (the exec tier); every one when absent. */
   counted?: ReadonlyMap<string, unknown>,
 ): Map<string, number> {
+  return reverseDepCountsOver(nodes, [counted])[0]!
+}
+
+/**
+ * `computeReverseDepCount` once per entry of `counted`, from ONE closure:
+ * the closure is the cost (~100 ms at 11k nodes, 2026-10-29), each count
+ * one popcount pass over it.
+ */
+function reverseDepCountsOver(
+  nodes: ReadonlyMap<string, TaskNode>,
+  counted: ReadonlyArray<ReadonlyMap<string, unknown> | undefined>,
+): Map<string, number>[] {
   // Exact transitive-dependent COUNTS need closure SETS (diamonds
   // double-count under naive summing). Set-of-strings closures are
   // O(N²) entries and took 8.5s on a 1090-package, 100-layer repo;
-  // bitsets make the same closure O(E·N/32) time and N²/8 bits of
-  // memory (3270 tasks ≈ 1.3 MB) — single-digit ms at that scale.
+  // bitsets make the same closure O(E·N/32) time over N²/8 bits
+  // (3270 tasks ≈ 1.3 MB) — single-digit ms at that scale.
   const ids = [...nodes.keys()]
-  const index = new Map<string, number>()
-  for (let i = 0; i < ids.length; i++) index.set(ids[i]!, i)
   const n = ids.length
-  const words = (n + 31) >>> 5
+  const index = new Map<string, number>()
+  for (let i = 0; i < n; i++) index.set(ids[i]!, i)
 
-  // Direct dependents as index lists + in-degree for the topo pass.
-  const directReverse: number[][] = Array.from({ length: n }, () => [])
+  // Direct dependents as one flat list (offsets per node) + in-degree.
+  const from: number[] = []
+  const to: number[] = []
+  const offset = new Int32Array(n + 1)
   const indegree = new Uint32Array(n)
-  for (const node of nodes.values()) {
-    const ni = index.get(node.id)!
-    for (const dep of node.deps) {
+  for (let ni = 0; ni < n; ni++) {
+    for (const dep of nodes.get(ids[ni]!)!.deps) {
       const di = index.get(dep)
       if (di === undefined) continue
-      directReverse[di]!.push(ni)
+      from.push(di)
+      to.push(ni)
+      offset[di + 1]!++
       indegree[ni]!++
     }
   }
+  for (let i = 0; i < n; i++) offset[i + 1]! += offset[i]!
+  const next = offset.slice(0, n)
+  const dependents = new Int32Array(from.length)
+  for (let e = 0; e < from.length; e++) dependents[next[from[e]!]!++] = to[e]!
 
   // Kahn topo order over dependency edges (deps before dependents).
   // Insertion order is topo today, but the closure's correctness
@@ -189,48 +207,84 @@ export function computeReverseDepCount(
   for (let i = 0; i < n; i++) if (indegree[i] === 0) topo[tail++] = i
   while (head < tail) {
     const v = topo[head++]!
-    for (const r of directReverse[v]!) {
+    for (let k = offset[v]!; k < offset[v + 1]!; k++) {
+      const r = dependents[k]!
       if (--indegree[r]! === 0) topo[tail++] = r
     }
   }
 
-  // Reverse-topo sweep: every direct dependent's closure is final
-  // before its dependency folds it in. closure[t] = bitset over topo
-  // POSITIONS of the node at position t's transitive dependents. A
-  // dependent sits after its dependency, so a closure holds only bits
-  // past its own position, and each OR starts at the dependent's word:
-  // half the words of indexing by insertion order on a layered graph.
+  // The same lists by topo POSITION. A dependent sits after its
+  // dependency, so a closure holds only bits past its own position.
   const pos = new Int32Array(n)
   for (let t = 0; t < tail; t++) pos[topo[t]!] = t
-  const mask = new Uint32Array(words)
-  if (counted === undefined) mask.fill(0xffffffff)
-  else
-    for (let t = 0; t < tail; t++) if (counted.has(ids[topo[t]!]!)) mask[t >>> 5]! |= 1 << (t & 31)
-  const closure = new Uint32Array(n * words)
-  const counts = new Map<string, number>()
-  for (let t = tail - 1; t >= 0; t--) {
+  const start = new Int32Array(tail + 1)
+  for (let t = 0; t < tail; t++) {
     const i = topo[t]!
-    const base = t * words
-    for (const ri of directReverse[i]!) {
-      const r = pos[ri]!
-      closure[base + (r >>> 5)]! |= 1 << (r & 31)
-      const rbase = r * words
-      for (let w = r >>> 5; w < words; w++) closure[base + w]! |= closure[rbase + w]!
-    }
-    let count = 0
-    for (let w = t >>> 5; w < words; w++) {
-      let v = closure[base + w]! & mask[w]!
-      v = v - ((v >>> 1) & 0x55555555)
-      v = (v & 0x33333333) + ((v >>> 2) & 0x33333333)
-      count += (((v + (v >>> 4)) & 0x0f0f0f0f) * 0x01010101) >>> 24
+    start[t + 1] = start[t]! + offset[i + 1]! - offset[i]!
+  }
+  const rev = new Int32Array(start[tail]!)
+  for (let t = 0; t < tail; t++) {
+    const i = topo[t]!
+    let k = start[t]!
+    for (let j = offset[i]!; j < offset[i + 1]!; j++) rev[k++] = pos[dependents[j]!]!
+  }
+  const words = (tail + 31) >>> 5
+  const masks = counted.map((only) => {
+    const mask = new Uint32Array(words)
+    if (only === undefined) mask.fill(0xffffffff)
+    else
+      for (let t = 0; t < tail; t++) if (only.has(ids[topo[t]!]!)) mask[t >>> 5]! |= 1 << (t & 31)
+    return mask
+  })
+
+  // Reverse-topo sweeps, one per block of `span` words: every node's
+  // closure restricted to the block's positions, its count summed over
+  // the blocks. All N rows of all words (9,603 tasks: 11.5 MB) missed
+  // the cache on nearly every OR, and the first call, the only one a run
+  // makes, took 77 ms; a block of ~256 KB took 37 (2026-10-29). A
+  // dependent past the block holds no bit in it, so its edge is skipped.
+  const span = Math.max(1, Math.min(words, Math.floor(65536 / Math.max(1, tail))))
+  const totals = masks.map(() => new Int32Array(tail))
+  const closure = new Uint32Array(tail * span)
+  for (let w0 = 0; w0 < words; w0 += span) {
+    const width = Math.min(words, w0 + span) - w0
+    const end = Math.min(tail, (w0 + width) << 5)
+    if (w0 > 0) closure.fill(0, 0, end * span)
+    for (let t = end - 1; t >= 0; t--) {
+      const base = t * span
+      for (let k = start[t]!; k < start[t + 1]!; k++) {
+        const r = rev[k]!
+        if (r >= end) continue
+        const rw = r >>> 5
+        if (rw >= w0) closure[base + rw - w0]! |= 1 << (r & 31)
+        const rbase = r * span
+        for (let w = rw > w0 ? rw - w0 : 0; w < width; w++)
+          closure[base + w]! |= closure[rbase + w]!
+      }
+      for (let m = 0; m < masks.length; m++) {
+        const mask = masks[m]!
+        let count = 0
+        for (let w = t >>> 5 > w0 ? (t >>> 5) - w0 : 0; w < width; w++) {
+          let v = closure[base + w]! & mask[w0 + w]!
+          if (v === 0) continue
+          v = v - ((v >>> 1) & 0x55555555)
+          v = (v & 0x33333333) + ((v >>> 2) & 0x33333333)
+          count += (((v + (v >>> 4)) & 0x0f0f0f0f) * 0x01010101) >>> 24
+        }
+        totals[m]![t]! += count
+      }
     }
-    counts.set(ids[i]!, count)
   }
-  // Cycle-stranded nodes (never topo-visited) can't occur — the graph
-  // builder rejects cycles — but a missing Map entry would silently
-  // sort as undefined, so default them defensively to 0.
-  for (const id of ids) if (!counts.has(id)) counts.set(id, 0)
-  return counts
+  const all = totals.map((total) => {
+    const counts = new Map<string, number>()
+    for (let t = 0; t < tail; t++) counts.set(ids[topo[t]!]!, total[t]!)
+    // Cycle-stranded nodes (never topo-visited) can't occur — the graph
+    // builder rejects cycles — but a missing Map entry would silently
+    // sort as undefined, so default them defensively to 0.
+    for (const id of ids) if (!counts.has(id)) counts.set(id, 0)
+    return counts
+  })
+  return all
 }
 
 /**

package/src/graph/scheduler.ts

@@ -5,8 +5,8 @@ import {
   isUserError,
   OUT_OF_FDS_HINT,
   thrownMessage,
-  ui,
 } from '../util/index.js'
+import * as ui from '../ui/index.js'
 import {
   computeReverseDepCount,
   mergePriorities,
@@ -88,6 +88,11 @@ export interface TaskOutcome {
    * its save wrote (measured only when a telemetry sink listens).
    */
   artifactBytes?: number
+  /**
+   * The raw bytes of the task's outputs: on a hit, the entry's files as
+   * restored; on a miss, the files its save stored (the row waits for it).
+   */
+  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. */
@@ -350,6 +355,11 @@ export interface ScheduleOptions {
    * Undefined or `most-work` is the reverse-deps count above.
    */
   strategy?: ScheduleStrategy
+  /**
+   * The `most-work` baseline already counted (`computeReverseDepCount`, read
+   * back with the graph): asked only when that baseline is the one used.
+   */
+  reverseDeps?: () => ReadonlyMap<string, number>
   /**
    * Restore-tier task ids: confirmed stable-key LOCAL cache hits (the
    * local short-circuit). A restore-tier task:
@@ -593,7 +603,7 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
       ? strategyPriorities(nodes, options.strategy)
       : options.restoreTier !== undefined && options.restoreTier.size > 0
         ? tieredReverseDepCount(nodes, options.restoreTier)
-        : computeReverseDepCount(nodes)
+        : (options.reverseDeps?.() ?? computeReverseDepCount(nodes))
   const priority: ReadonlyMap<string, number> = options.priorities
     ? mergePriorities(baseline, options.priorities)
     : baseline

package/src/graph/task-graph.ts

@@ -335,6 +335,31 @@ export function undeclaredDepsError(
   )
 }
 
+/**
+ * The `pkg#task` to offer for a cross-project miss: the task nearest
+ * `task` in the project named, or in the one nearest `project` — or the
+ * one whose path ends in it, since a project is named by its path unless
+ * named, and `a#build` is how a `packages/a` is first typed.
+ */
+function nearestTarget(
+  projects: ReadonlyMap<string, ProjectEntry>,
+  project: string,
+  task: string,
+): string | undefined {
+  const holder =
+    projects.get(project) ??
+    projects.get(nearest(project, projects.keys()) ?? '') ??
+    onlyOne([...projects.values()].filter((p) => p.name.endsWith(`/${project}`)))
+  if (holder === undefined) return undefined
+  const tasks = Object.keys(holder.config.tasks ?? {})
+  const name = tasks.includes(task) ? task : nearest(task, tasks)
+  return name === undefined ? undefined : taskId(holder.name, name)
+}
+
+function onlyOne<T>(list: readonly T[]): T | undefined {
+  return list.length === 1 ? list[0] : undefined
+}
+
 /** One task mid-expansion in `buildTaskGraph`'s walk. */
 interface Frame {
   node: TaskNode
@@ -656,8 +681,9 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
             `${id}: dependsOn //#${spec.task}, the workspace root's task, but the root declares no such task: add a vx.config at the root declaring it and run \`vx lock\``,
             'VX_E_DEPENDS_ON',
           )
+        const meant = nearestTarget(projects, spec.project, spec.task)
         throw new UserError(
-          `${id}: dependsOn ${taskId(spec.project, spec.task)} but no such project or task is declared`,
+          `${id}: dependsOn ${taskId(spec.project, spec.task)} but no such project or task is declared${meant === undefined ? '' : `. Did you mean ${meant}?`}`,
           'VX_E_DEPENDS_ON',
         )
       }

package/src/handoff.ts

@@ -223,15 +223,19 @@ export async function handOff(bin: string, args: readonly string[]): Promise<nev
   // hides the env on every verb, is never reached here. Imported here:
   // a start that hands off nothing pays nothing.
   await (await import('./util/index.js')).hideEnvFromTasks()
-  const child = Bun.spawn([bin, ...args], {
-    stdio: ['inherit', 'inherit', 'inherit'],
-    env: { ...process.env, VX_HANDED_OFF: process.execPath },
-  })
+  // The handlers come first: a signal landing between the spawn and them
+  // killed this vx and left the local one running, orphaned (main
+  // dc9d49c). A handler runs on the event loop, after the spawn returned.
+  let child: Bun.Subprocess | undefined
   for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP'] as const) {
     process.on(sig, () => {
-      if (!inForeground()) child.kill(sig)
+      if (!inForeground()) child?.kill(sig)
     })
   }
+  child = Bun.spawn([bin, ...args], {
+    stdio: ['inherit', 'inherit', 'inherit'],
+    env: { ...process.env, VX_HANDED_OFF: process.execPath },
+  })
   const code = await child.exited
   const signal = child.signalCode
   if (signal === null) process.exit(code)
@@ -240,8 +244,7 @@ export async function handOff(bin: string, args: readonly string[]): Promise<nev
   // SIGINT, and an exit 130 ran the script's next line. The code below is
   // the rest, and the fallback should the signal not land.
   if (signal === 'SIGINT' || signal === 'SIGTERM' || signal === 'SIGHUP') {
-    process.removeAllListeners(signal)
-    process.kill(process.pid, signal)
+    ;(await import('./util/index.js')).dieOf(signal)
   }
   if (typeof signal === 'number') process.exit(128 + signal)
   const { constants } = await import('node:os')

package/src/history/history.ts

@@ -12,7 +12,7 @@
 // (zero-config); the interface is the seam a plugin fills for any other.
 
 import type { Database } from 'bun:sqlite'
-import { branchSource, EXECUTED_RUNS_SQL } from '../cache/index.js'
+import { branchSource, type Cache, EXECUTED_RUNS_SQL, indexDb } from '../cache/index.js'
 import { isMeasure, splitTaskId } from '../util/index.js'
 import { failureModeOf, mixedOutcomeKeysSql } from './failure-mode.js'
 import type { FailureMode } from './failure-mode.js'
@@ -117,8 +117,40 @@ export class EmptyHistoryProvider implements HistoryProvider {
   }
 }
 
+/** One local cache's run history, read and written by core (`localHistory`): plain rows out, no handle. */
+export interface LocalHistory extends HistoryProvider {
+  /** Each task's measured need (`p50DurationMs`, peak cores and memory). */
+  resourcesFor(taskIds: readonly string[]): Promise<ReadonlyMap<string, TaskResources>>
+  /** Whether timings of commit `sha` were imported. */
+  hasImported(sha: string): boolean
+  /** Keep commit `sha`'s timings (task id → ms) and needs as forecast rows. */
+  importTimings(
+    sha: string,
+    timings: ReadonlyMap<string, number>,
+    needs?: ReadonlyMap<string, TaskResources>,
+    defs?: ReadonlyMap<string, string>,
+  ): void
+}
+
+export interface LocalHistoryOptions {
+  /** The newest invocations a read sees (default 50). */
+  readonly recent?: number | undefined
+  /** The run's branch (`currentBranch`); undefined: a read sees every branch's timings. */
+  readonly branch?: string | null | undefined
+  /** Each task's definition (`taskDefinitions`): given, a task reads only rows of it as it is now. */
+  readonly defs?: ReadonlyMap<string, string> | undefined
+}
+
+/**
+ * The run history in `cache`'s index. A plugin reads history only through
+ * this: core owns every read and write of cache.db (2026-10-29).
+ */
+export function localHistory(cache: Cache, options: LocalHistoryOptions = {}): LocalHistory {
+  return new LocalHistoryProvider(indexDb(cache), options.recent, options.branch, options.defs)
+}
+
 /** Reads from the orchestrator's local SQLite cache.db. */
-export class LocalHistoryProvider implements HistoryProvider {
+export class LocalHistoryProvider implements LocalHistory {
   constructor(
     private readonly db: Database,
     readonly recent: number = DEFAULT_RECENT,
@@ -279,6 +311,11 @@ export class LocalHistoryProvider implements HistoryProvider {
    * against 4 for the executed successes' durations alone.
    */
   async p50sFor(taskIds: readonly string[]): Promise<ReadonlyMap<string, number>> {
+    return this.p50sNow(taskIds)
+  }
+
+  /** `p50sFor`, at once: a row drawn now reads it (the rows' `usual`). */
+  p50sNow(taskIds: readonly string[]): ReadonlyMap<string, number> {
     if (taskIds.length === 0) return new Map()
     return this.forecasts(new Set(taskIds))
   }

package/src/history/index.ts

@@ -6,6 +6,9 @@ export {
   EmptyHistoryProvider,
   type HistoryProvider,
   type HistoryTable,
+  type LocalHistory,
+  type LocalHistoryOptions,
+  localHistory,
   LocalHistoryProvider,
   PASS_STATUSES,
   type TaskHistory,

package/src/history/metrics.ts

@@ -50,6 +50,10 @@ export interface RunSummaryRow {
   avgRssBytes: number | null
   /** Where an executor ran it (`small#1`, v44); null = here. */
   placement: string | null
+  /** The bytes of its outputs: what its save stored, or its hit restored (v51). */
+  outputBytes: number | null
+  /** How many tasks were downstream of it (v51). */
+  blocks: number | null
   // High-precision spans relative to run start. Decimal strings on the wire
   // (bigints aren't JSON-safe); use BigInt or Number on the client.
   wallclockStartNs: string | null
@@ -65,6 +69,8 @@ export interface RunSummaryRow {
   remoteError: string | null
   /** The attempts a retried task took (>1, v23); null when it ran once. */
   attempts: number | null
+  /** Milliseconds it waited, ready, for a slot (v51); null when it never queued. */
+  queuedMs: number | null
 }
 
 export interface ListRunsArgs {
@@ -123,10 +129,12 @@ export function listRuns(db: Database, args: ListRunsArgs = {}): RunSummaryRow[]
               cache_hit AS cacheHit, restored, cached, hash,
               cpu_ms AS cpuMs, peak_rss_bytes AS peakRssBytes,
               peak_cores AS peakCores, avg_rss_bytes AS avgRssBytes, placement,
+              output_bytes AS outputBytes, blocks,
               wallclock_start_ns AS wallclockStartNs, wallclock_end_ns AS wallclockEndNs,
               blocked_by AS blockedBy, timed_out AS timedOut,
               sandbox_violations AS sandboxViolations, not_ready AS notReady,
-              forward_args IS NOT NULL AS forwarded, remote_error AS remoteError, attempts
+              forward_args IS NOT NULL AS forwarded, remote_error AS remoteError, attempts,
+              queued_ms AS queuedMs
        FROM runs ${clause} ORDER BY id DESC LIMIT ?`,
     )
     .all(...params, limit) as RawRow[]