@vzn/vx 0.0.636 → 0.0.638

package/src/cache/plugin-cache.ts

@@ -0,0 +1,248 @@
+// A plugin's own entries in the cache the workspace declares (`ctx.cache`,
+// owner 2026-10-14): the local store first, then each remote in declared
+// order, under the run's policy and scope. The plugin speaks names; core
+// derives the key, so no plugin reaches another's entries or a task's. An
+// entry is written once and never replaced (the cache is immutable). Every
+// failure is an absent answer, never a warning (M: no extra runtime
+// warnings): what a plugin keeps here is a hint.
+
+import type { Database } from 'bun:sqlite'
+import { xxh3hex } from '../util/index.js'
+import type { CachePolicy } from './policy.js'
+import type { RemoteCacheLayer } from './layered-cache.js'
+import { scopedKey } from './scoped-cache.js'
+import { runReadKeys } from './run-store.js'
+
+/** The largest entry kept or read, in bytes: a remote's larger body is a miss, read no further. */
+export const PLUGIN_ENTRY_MAX_BYTES = 1024 * 1024
+
+/** What a plugin's `ctx.cache` offers. Keys are the plugin's own names. */
+export interface PluginCache {
+  /** The bytes stored under `key`, from the first layer holding them; null when none does. */
+  get(key: string): Promise<Uint8Array | null>
+  /** Store `bytes` under `key` in every layer the policy writes, where it is not already; empty bytes store nothing. */
+  put(key: string, bytes: Uint8Array): Promise<void>
+  /** Whether some layer holds `key`; null when no layer could answer. */
+  has(key: string): Promise<boolean | null>
+  /**
+   * The subset of `keys` some layer holds, in one probe per layer; null
+   * when a readable remote has no batch probe: ask `get` one at a time.
+   */
+  hasMany(keys: readonly string[]): Promise<Set<string> | null>
+  /**
+   * What core kept of a run under `name` (a `log` or `outputs` name its
+   * `RunReport` hands `teardown`), from the first readable remote holding
+   * it; null when none does. Uncapped: core wrote it.
+   */
+  getRun(name: string): Promise<Uint8Array | null>
+}
+
+/** One remote as the plugin cache reaches it: its wire and what the policy lets it do. */
+export interface PluginCacheRemote {
+  readonly remote: RemoteCacheLayer
+  readonly read: boolean
+  readonly write: boolean
+}
+
+export interface PluginCacheHost {
+  /** The run's index; its store holds `plugin_blobs`. */
+  readonly db: Database
+  readonly policy: CachePolicy
+  readonly remotes: readonly PluginCacheRemote[]
+  readonly scope: string | undefined
+}
+
+/** The key `name` stores under for `plugin`: task-key shaped, so every wire stores it unchanged. */
+function entryKey(plugin: string, name: string): string {
+  return xxh3hex(`vx-plugin\0${plugin}\0${name}`)
+}
+
+/**
+ * A remote body's bytes; null past the cap (read no further than it) and for
+ * an empty or odd body, which kept would hide every later good one: an entry
+ * is written once (Security, #3580).
+ */
+async function capped(body: unknown, max = PLUGIN_ENTRY_MAX_BYTES): Promise<Uint8Array | null> {
+  if (body instanceof Blob) {
+    if (body.size === 0 || body.size > max) return null
+    return new Uint8Array(await body.arrayBuffer())
+  }
+  if (!(body instanceof Response) || body.body === null) return null
+  const reader = body.body.getReader()
+  const chunks: Uint8Array[] = []
+  let size = 0
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    size += value.byteLength
+    if (size > max) {
+      await reader.cancel().catch(() => {})
+      return null
+    }
+    chunks.push(value)
+  }
+  if (size === 0) return null
+  const out = new Uint8Array(size)
+  let at = 0
+  for (const c of chunks) {
+    out.set(c, at)
+    at += c.byteLength
+  }
+  return out
+}
+
+/**
+ * `plugin`'s view of the cache. A scoped run reads the default key, then
+ * the scope's, and writes only the scope's, as tasks do (`ScopedCache`).
+ */
+export function pluginCache(plugin: string, host: PluginCacheHost): PluginCache {
+  const { db, policy, scope } = host
+  const readers = host.remotes.filter((r) => r.read)
+  const writers = host.remotes.filter((r) => r.write)
+  const reads = (name: string): string[] => {
+    const key = entryKey(plugin, name)
+    return scope === undefined ? [key] : [key, scopedKey(scope, key)]
+  }
+  const writeKey = (name: string): string => {
+    const key = entryKey(plugin, name)
+    return scope === undefined ? key : scopedKey(scope, key)
+  }
+
+  const localGet = (key: string): Uint8Array | null => {
+    if (!policy.localRead) return null
+    try {
+      const row = db.query('SELECT bytes FROM plugin_blobs WHERE key = ?').get(key) as {
+        bytes: Uint8Array
+      } | null
+      return row === null ? null : new Uint8Array(row.bytes)
+    } catch {
+      return null
+    }
+  }
+  const localHas = (keys: readonly string[]): Set<string> => {
+    const found = new Set<string>()
+    if (!policy.localRead || keys.length === 0) return found
+    try {
+      const rows = db
+        .query(`SELECT key FROM plugin_blobs WHERE key IN (${keys.map(() => '?').join(', ')})`)
+        .all(...keys) as Array<{ key: string }>
+      for (const r of rows) found.add(r.key)
+    } catch {
+      // an unreadable index holds nothing
+    }
+    return found
+  }
+  const localPut = (key: string, bytes: Uint8Array): void => {
+    try {
+      db.query('INSERT OR IGNORE INTO plugin_blobs(key, bytes, at) VALUES (?, ?, ?)').run(
+        key,
+        bytes,
+        Date.now(),
+      )
+    } catch {
+      // a read-only or busy index keeps nothing
+    }
+  }
+
+  return {
+    async get(name) {
+      const keys = reads(name)
+      for (const key of keys) {
+        const hit = localGet(key)
+        if (hit !== null) return hit
+      }
+      for (const { remote } of readers) {
+        for (const key of keys) {
+          try {
+            const got = await remote.get(key)
+            if (got === null) continue
+            const bytes = await capped(got.body)
+            if (bytes === null) continue
+            if (policy.localWrite) localPut(key, bytes)
+            return bytes
+          } catch {
+            // a failing remote is a miss there
+          }
+        }
+      }
+      return null
+    },
+
+    async put(name, bytes) {
+      if (bytes.byteLength === 0 || bytes.byteLength > PLUGIN_ENTRY_MAX_BYTES) return
+      const key = writeKey(name)
+      if (policy.localWrite) localPut(key, bytes)
+      for (const { remote } of writers) {
+        try {
+          if (await remote.has(key)) continue
+          await remote.put(key, new Blob([bytes]), { durationMs: 0 })
+        } catch {
+          // the other layers still keep it
+        }
+      }
+    },
+
+    async has(name) {
+      const keys = reads(name)
+      if (localHas(keys).size > 0) return true
+      let answered = policy.localRead
+      for (const { remote } of readers) {
+        for (const key of keys) {
+          try {
+            if (await remote.has(key)) return true
+            answered = true
+          } catch {
+            // no answer from this remote
+          }
+        }
+      }
+      return answered ? false : null
+    },
+
+    async hasMany(names) {
+      const byKey = new Map<string, string>()
+      for (const name of names) for (const key of reads(name)) byKey.set(key, name)
+      const keys = [...byKey.keys()]
+      const found = new Set<string>()
+      for (const key of localHas(keys)) found.add(byKey.get(key)!)
+      for (const { remote } of readers) {
+        const ask = keys.filter((k) => !found.has(byKey.get(k)!))
+        if (ask.length === 0) break
+        if (remote.hasMany === undefined) return null
+        try {
+          const got: unknown = await remote.hasMany(ask)
+          if (!(got instanceof Set)) return null
+          for (const key of got) if (byKey.has(key as string)) found.add(byKey.get(key as string)!)
+        } catch {
+          return null
+        }
+      }
+      return found
+    },
+
+    async getRun(name) {
+      for (const { remote } of readers) {
+        for (const key of runReadKeys(name, scope)) {
+          try {
+            const got = await remote.get(key)
+            if (got === null) continue
+            const bytes = await capped(got.body, Infinity)
+            if (bytes !== null) return bytes
+          } catch {
+            // a failing remote is a miss there
+          }
+        }
+      }
+      return null
+    },
+  }
+}
+
+/** A cache with no layer: every answer absent. What a context built outside a run holds. */
+export const absentPluginCache: PluginCache = {
+  get: async () => null,
+  put: async () => {},
+  has: async () => null,
+  hasMany: async () => null,
+  getRun: async () => null,
+}

package/src/cache/policy.ts

@@ -1,5 +1,5 @@
 // The run-level cache policy: four axes (local/remote × read/write) and
-// the `--cache=<spec>` grammar that sets them. Pure data + parsing; no I/O.
+// the `--cache-policy=<spec>` grammar that sets them. Pure data + parsing; no I/O.
 
 import { UserError } from '../util/index.js'
 
@@ -10,8 +10,7 @@ import { UserError } from '../util/index.js'
  * cache) is distinct from `--no-cache` (disable everything).
  *
  * The task-artifact get/save path is gated, and the local axes also gate
- * the local store's config-evaluation reads and writes and its file-hash
- * writes (`cache.ts`). `recordRun`, `stats`, `prune`, key derivation, and
+ * the local store's file-hash writes (`cache.ts`). `recordRun`, `stats`, `prune`, key derivation, and
  * prefetch-ingest are never affected — they are bookkeeping/analytics
  * that a run policy has no business disabling.
  */
@@ -20,12 +19,6 @@ export interface CachePolicy {
   localWrite: boolean
   remoteRead: boolean
   remoteWrite: boolean
-  /**
-   * An untrusted scope (`cacheScope: 'pr-123'`): remote reads try this
-   * scope's keys, then the trusted ones; remote writes go to this scope's
-   * keys only. Absent = trusted. See {@link scopeCachePolicy}.
-   */
-  remoteScope?: string
 }
 
 /** All four axes on — the default when no cache flag is passed. */
@@ -36,13 +29,13 @@ export const FULL_CACHE_POLICY: CachePolicy = {
   remoteWrite: true,
 }
 
-/** No axis on (`--no-cache`, `--cache=local:`): no cache answers for any task. */
+/** No axis on (`--no-cache`, `--cache-policy=local:`): no cache answers for any task. */
 export function cachesNothing(p: CachePolicy): boolean {
   return !(p.localRead || p.localWrite || p.remoteRead || p.remoteWrite)
 }
 
 /**
- * Parse a `--cache=<spec>` value into a `CachePolicy`, starting from a
+ * Parse a `--cache-policy=<spec>` value into a `CachePolicy`, starting from a
  * base (defaults to {@link FULL_CACHE_POLICY}). The spec is a
  * comma-separated list of `layer:flags` segments where `layer` is
  * `local` or `remote` and `flags` is any subset of `r` (read) and `w`
@@ -53,7 +46,8 @@ export function cachesNothing(p: CachePolicy): boolean {
  * So `local:rw,remote:r` = remote read-only, `remote:` = remote fully
  * off, `local:r` = local read-only with remote untouched.
  *
- * Throws a {@link UserError} on an unknown layer, an unknown flag, a
+ * Throws a {@link UserError}, whose message the caller prefixes with the
+ * spec's source (`--cache-policy`, `VX_CACHE_POLICY`, `cache.policy`), on an unknown layer, an unknown flag, a
  * duplicated flag, a missing colon, or a repeated layer.
  */
 export function parseCachePolicy(spec: string, base: CachePolicy = FULL_CACHE_POLICY): CachePolicy {
@@ -64,24 +58,24 @@ export function parseCachePolicy(spec: string, base: CachePolicy = FULL_CACHE_PO
     if (seg.length === 0) continue
     const colon = seg.indexOf(':')
     if (colon < 0) {
-      throw new UserError(`invalid --cache segment '${seg}': expected '<layer>:<flags>'`)
+      throw new UserError(`invalid segment '${seg}': expected '<layer>:<flags>'`)
     }
     const layer = seg.slice(0, colon)
     const flags = seg.slice(colon + 1)
     if (layer !== 'local' && layer !== 'remote') {
-      throw new UserError(`invalid --cache layer '${layer}': expected 'local' or 'remote'`)
+      throw new UserError(`invalid layer '${layer}': expected 'local' or 'remote'`)
     }
     if (seen.has(layer)) {
-      throw new UserError(`--cache layer '${layer}' specified twice`)
+      throw new UserError(`layer '${layer}' specified twice`)
     }
     seen.add(layer)
     const flagSet = new Set<string>()
     for (const ch of flags) {
       if (ch !== 'r' && ch !== 'w') {
-        throw new UserError(`invalid --cache flag '${ch}' for '${layer}': expected 'r' and/or 'w'`)
+        throw new UserError(`invalid flag '${ch}' for '${layer}': expected 'r' and/or 'w'`)
       }
       if (flagSet.has(ch)) {
-        throw new UserError(`--cache flag '${ch}' repeated for '${layer}'`)
+        throw new UserError(`flag '${ch}' repeated for '${layer}'`)
       }
       flagSet.add(ch)
     }
@@ -97,15 +91,26 @@ export function parseCachePolicy(spec: string, base: CachePolicy = FULL_CACHE_PO
 }
 
 /**
- * Apply a workspace's `cacheScope` to the run's policy. `'trusted'` (or
- * none) changes nothing; `'read-only'` turns remote writes off; any other
- * name is an untrusted scope. A clamp, never a widening: `--cache` still
- * decides which axes are on. A client-side convention, not a boundary —
- * any run holding a write credential can write a trusted key; only the
- * cache server, by token, can refuse it (docs/security.md).
+ * The `--cache-policy` spec for `p`, both layers named, so the line
+ * `vx last` shows pastes back as the flag: `local:rw,remote:r`.
  */
-export function scopeCachePolicy(policy: CachePolicy, scope: string | undefined): CachePolicy {
-  if (scope === undefined || scope === 'trusted') return policy
-  if (scope === 'read-only') return { ...policy, remoteWrite: false }
-  return { ...policy, remoteScope: scope }
+export function formatCachePolicy(p: CachePolicy): string {
+  const flags = (r: boolean, w: boolean): string => `${r ? 'r' : ''}${w ? 'w' : ''}`
+  return `local:${flags(p.localRead, p.localWrite)},remote:${flags(p.remoteRead, p.remoteWrite)}`
+}
+
+/** `--no-cache` and `--force`, which still apply over whichever spec set the base. */
+export interface CacheFlags {
+  /** `--no-cache`: every axis off. Beats `force`. */
+  noCache?: boolean
+  /** `--force`: both reads off, writes kept. */
+  force?: boolean
+}
+
+export function applyCacheFlags(policy: CachePolicy, flags: CacheFlags | undefined): CachePolicy {
+  if (flags?.noCache === true) {
+    return { localRead: false, localWrite: false, remoteRead: false, remoteWrite: false }
+  }
+  if (flags?.force === true) return { ...policy, localRead: false, remoteRead: false }
+  return policy
 }

package/src/cache/run-history.ts

@@ -31,8 +31,38 @@ function insertRunsSql(n: number): string {
  */
 const RUNS_PER_INSERT = 40
 
+/** Rows per `task_durations` INSERT: 6 variables each, under 999. */
+const DURATIONS_PER_INSERT = 160
+
+/** Rows per `task_outcomes` INSERT: 6 variables each, under 999. */
+const OUTCOMES_PER_INSERT = 160
+
+/**
+ * Whether a run says anything of its key, so the flaky record may keep it:
+ * keyed, cached, and not run behind a failure (its bytes were not the key's).
+ */
+const keyed = (r: RunRecord): boolean =>
+  r.hash !== undefined && r.hash !== '' && r.cached !== false && r.blockedBy == null
+
+/** A hit, as the orchestrator marks one (`isCacheHit`, run-records.ts). */
+const isHit = (r: RunRecord): boolean => r.cacheHit === true
+
+/**
+ * Of a JSON array of hashes, those the record holds a pass of: one index
+ * probe each (0.6 ms for 1,000; a join reading every row of each key was
+ * 5.7 ms at 20 runs of history). A hit's row is kept only when its key has
+ * none: a hit replays a pass, and the first is what a later failure
+ * relapses from (an entry adopted from its artifact, or older than the
+ * record, has no executed row). By hash alone, as the entry it replays is.
+ */
+const PASSED_HASHES = `
+      SELECT j.value AS hash FROM json_each(?) AS j
+      WHERE EXISTS (SELECT 1 FROM task_outcomes AS o WHERE o.hash = j.value AND o.status <> 'failed')`
+
+/** A local run's `task_durations.source`: its branch, `''` when it had none. */
+export const branchSource = (branch: string | null): string => `branch:${branch ?? ''}`
+
 export class RunHistory {
-  private readonly insertRun: ReturnType<Database['prepare']>
   private readonly insertInvocation: ReturnType<Database['prepare']>
 
   constructor(
@@ -40,7 +70,6 @@ export class RunHistory {
     /** The store's salted value digest (L-4). */
     private readonly digestValue: (value: string) => string,
   ) {
-    this.insertRun = lazyStatement(this.db, insertRunsSql(1))
     this.insertInvocation = lazyStatement(
       this.db,
       `
@@ -60,18 +89,74 @@ export class RunHistory {
   }
 
   recordRun(run: RunRecord): void {
-    this.insertRun.run(...bindRun(run, this.digestValue))
+    this.recordRuns([run])
   }
 
   recordRuns(runs: readonly RunRecord[]): void {
     if (runs.length === 0) return
-    if (runs.length === 1) {
-      this.insertRun.run(...bindRun(runs[0]!, this.digestValue))
-      return
-    }
     // One transaction, one fsync: for a 200-task run, one instead of 200.
     // IMMEDIATE, as `recordRunBundle` explains.
-    this.db.transaction(() => this.insertRuns(runs)).immediate()
+    this.db
+      .transaction(() => {
+        this.insertRuns(runs)
+        this.insertDurations(runs, branchSource(null), null)
+        this.insertOutcomes(runs)
+      })
+      .immediate()
+  }
+
+  /** One `task_durations` row per executed success: what a forecast reads. */
+  private insertDurations(runs: readonly RunRecord[], source: string, sha: string | null): void {
+    const done = runs.filter((r) => r.status === 'success' && r.cacheHit !== true)
+    for (let i = 0; i < done.length; i += DURATIONS_PER_INSERT) {
+      const block = done.slice(i, i + DURATIONS_PER_INSERT)
+      const params: SQLQueryBindings[] = []
+      for (const r of block) params.push(r.project, r.task, source, sha, r.durationMs, r.endedAt)
+      this.db
+        .query(
+          `INSERT INTO task_durations(project, task, source, sha, duration_ms, recorded_at) VALUES ${Array(block.length).fill('(?, ?, ?, ?, ?, ?)').join(', ')}`,
+        )
+        .run(...params)
+    }
+  }
+
+  /**
+   * The flaky record's rows: every executed outcome, and a key's first hit,
+   * in the order given (a batch may hold one key's history).
+   */
+  private insertOutcomes(runs: readonly RunRecord[]): void {
+    const rows = runs.filter(
+      (r) => keyed(r) && (isHit(r) || r.status === 'success' || r.status === 'failed'),
+    )
+    const hits = rows.filter(isHit)
+    let passed: Set<string> | undefined
+    if (hits.length > 0) {
+      const found = this.db.query(PASSED_HASHES).all(JSON.stringify(hits.map((r) => r.hash))) as {
+        hash: string
+      }[]
+      passed = new Set(found.map((f) => f.hash))
+    }
+    const kept: RunRecord[] = []
+    for (const r of rows) {
+      if (isHit(r)) {
+        if (passed!.has(r.hash!)) continue
+        passed!.add(r.hash!)
+      } else if (r.status === 'success') {
+        passed?.add(r.hash!)
+      }
+      kept.push(r)
+    }
+    for (let i = 0; i < kept.length; i += OUTCOMES_PER_INSERT) {
+      const block = kept.slice(i, i + OUTCOMES_PER_INSERT)
+      const params: SQLQueryBindings[] = []
+      for (const r of block)
+        params.push(r.project, r.task, r.hash!, r.status, r.attempts ?? null, r.startedAt)
+      this.db
+        .query(
+          `INSERT INTO task_outcomes(project, task, hash, status, attempts, recorded_at) VALUES ${Array(block.length).fill('(?, ?, ?, ?, ?, ?)').join(', ')}`,
+        )
+        .run(...params)
+    }
   }
 
   /** `runs` as few INSERTs; each distinct forward-args list digested once. */
@@ -109,6 +194,12 @@ export class RunHistory {
       .transaction(() => {
         this.insertRuns(bundle.runs)
         this.insertInvocation.run(...bindInvocation(bundle.invocation))
+        this.insertDurations(
+          bundle.runs,
+          branchSource(bundle.invocation.branch),
+          bundle.invocation.commitSha,
+        )
+        this.insertOutcomes(bundle.runs)
       })
       .immediate()
   }
@@ -116,21 +207,20 @@ export class RunHistory {
   /**
    * Retention: the runs table grows by one row per executed task per
    * invocation — a 2000-task repo accretes ~20k rows in days. 30 days
-   * covers `vx stats` (24 h windows) and CI-side consumers. The
+   * covers `vx info` (24 h windows) and CI-side consumers. The
    * `invocations` header is pruned on the SAME window, or a header would
    * outlive its rows and `vx last` would list a run whose detail is gone.
    */
   pruneOlderThan(cutoff: number): void {
     this.db.prepare('DELETE FROM runs WHERE started_at < ?').run(cutoff)
     this.db.prepare('DELETE FROM invocations WHERE started_at < ?').run(cutoff)
+    this.db.prepare('DELETE FROM task_durations WHERE recorded_at < ?').run(cutoff)
+    this.db.prepare('DELETE FROM task_outcomes WHERE recorded_at < ?').run(cutoff)
+    this.db.prepare('DELETE FROM plugin_blobs WHERE at < ?').run(cutoff)
   }
 }
 
-/**
- * Bind a RunRecord to the positional parameters expected by the
- * `insertRun` prepared statement (22 columns). Shared between the
- * single and batched record paths.
- */
+/** Bind a RunRecord to one `RUN_TUPLE`'s 22 positional parameters. */
 function bindRun(run: RunRecord, digestValue: (v: string) => string): SQLQueryBindings[] {
   return [
     // The ONE place the no-key sentinel is applied, so the column's

package/src/cache/run-store.ts

@@ -0,0 +1,77 @@
+// What core keeps of a run that writes a remote (owner 2026-10-15): a failed
+// task's log and the files its outputs left, an uncached task's log. Names
+// come from the run id and task (`run/<id>/<task>/log`); each key is derived
+// in a namespace no task key or plugin entry shares. Remote only: locally
+// `vx last --log` and the working tree already hold them. No size cap (M:
+// the cache is free). Plugins read them by name (`ctx.cache.getRun`).
+
+import { xxh3hex } from '../util/index.js'
+import type { PluginCacheRemote } from './plugin-cache.js'
+import { scopedKey } from './scoped-cache.js'
+import { tarPackInto, tarSize } from './tar-stream.js'
+
+/** The name core stores a task's `part` of run `runId` under. */
+export function runEntryName(runId: string, taskId: string, part: 'log' | 'outputs'): string {
+  return `run/${runId}/${taskId}/${part}`
+}
+
+const runKey = (name: string): string => xxh3hex(`vx-run\0${name}`)
+
+/** The keys `name` is read under: the default, then the scope's, as tasks read. */
+export function runReadKeys(name: string, scope: string | undefined): string[] {
+  const key = runKey(name)
+  return scope === undefined ? [key] : [key, scopedKey(scope, key)]
+}
+
+/** Whether some remote takes this run's writes: only then does core keep run bytes. */
+export function writesRunStore(remotes: readonly PluginCacheRemote[]): boolean {
+  return remotes.some((r) => r.write)
+}
+
+/**
+ * Store `bytes` under `name` in every remote the policy writes. An entry is
+ * written once; a remote's failure leaves the others theirs, silently: what
+ * a run keeps here is a record, never its verdict.
+ */
+export async function putRunEntry(
+  remotes: readonly PluginCacheRemote[],
+  scope: string | undefined,
+  name: string,
+  bytes: Uint8Array,
+): Promise<boolean> {
+  const key = scope === undefined ? runKey(name) : scopedKey(scope, runKey(name))
+  let kept = false
+  for (const { remote, write } of remotes) {
+    if (!write) continue
+    try {
+      if (!(await remote.has(key))) await remote.put(key, new Blob([bytes]), { durationMs: 0 })
+      kept = true
+    } catch {
+      // the other remotes still keep it
+    }
+  }
+  return kept
+}
+
+/**
+ * The files at `paths` (workspace-relative) as a plain ustar archive, names
+ * as given, so any `tar` reads it; null when none is left to read.
+ */
+export async function packRunOutputs(
+  workspaceRoot: string,
+  paths: readonly string[],
+): Promise<Uint8Array | null> {
+  const inputs: { name: string; size: number; body: Uint8Array }[] = []
+  for (const name of paths) {
+    try {
+      const body = await Bun.file(`${workspaceRoot}/${name}`).bytes()
+      inputs.push({ name, size: body.byteLength, body })
+    } catch {
+      // gone since the glob: nothing to keep
+    }
+  }
+  if (inputs.length === 0) return null
+  const out = new Uint8Array(tarSize(inputs))
+  tarPackInto(inputs, out)
+  return out
+}