faberun 0.3.0 → 0.7.0

package/src/engine/verify.mjs

@@ -11,7 +11,7 @@
 import { attemptWorkspace } from "../repo/worktree.mjs";
 import { boundedUtf8, errorMessage } from "../util.mjs";
 import { compactVerification } from "../contract/verification.mjs";
-import { finalVerificationCommands } from "../contract/final-verification.mjs";
+import { finalVerificationCommands, sharedVerificationCommands } from "../contract/final-verification.mjs";
 import { join } from "node:path";
 import { terminateInvocation } from "./process.mjs";
 import { writeNode } from "./state.mjs";
@@ -24,8 +24,24 @@ import { runVerification } from "./run-command.mjs";
 /** @typedef {import("../contract/index.mjs").ValidatedNode} ValidatedNode */
 /** @typedef {import("../contract/verification.mjs").VerificationAttempt} VerificationAttempt */
 /** @typedef {import("../contract/verification.mjs").VerificationAttemptResult} VerificationAttemptResult */
+/** @typedef {import("../contract/verification.mjs").VerificationCommand} VerificationCommand */
 /** @typedef {import("../contract/index.mjs").VerificationState} VerificationState */
+/** @typedef {{index: number, total: number, argv: string}} VerificationProgress */
 
+/**
+ * The bounded `k/n · argv` shape a running node's status surfaces while a
+ * verification command is in flight: the command's 1-based position among
+ * every command this pass runs, and its argv joined and bounded so a long
+ * command line can never threaten the node snapshot's byte ceiling.
+ *
+ * @param {number} index 1-based position of the command now running
+ * @param {number} total command count in this verification pass
+ * @param {string[]|undefined} argv
+ * @returns {VerificationProgress}
+ */
+export function verificationProgress(index, total, argv) {
+  return { index, total, argv: boundedUtf8((argv ?? []).join(" "), 120) };
+}
 /**
  * @param {VerificationAttemptResult|null|undefined} result
  * @returns {VerificationAttemptResult}
@@ -57,14 +73,21 @@ function verificationAttemptRecords(state) {
  * @param {NodeSnapshot} state
  * @param {LockHandle} lock
  * @param {VerificationAttempt} attempt
+ * @param {VerificationProgress} [progress] the running command's `k/n · argv`
+ *   shape; omitted on completion, since a following `onAttemptStart` replaces
+ *   it or the pass's final rewrite of `state.verification` drops it
  */
-function persistVerificationAttempt(runDir, state, lock, attempt) {
+function persistVerificationAttempt(runDir, state, lock, attempt, progress) {
   const attempts = verificationAttemptRecords(state);
   const index = attempts.findIndex((item) => item.invocationId === attempt.invocationId);
   if (index >= 0) attempts[index] = { ...attempts[index], ...attempt };
   else attempts.push({ ...attempt, completedAt: attempt.completedAt ?? null, result: attempt.result ?? null });
   state.verification ??= { passed: false, commands: [], completed: false, attempts: [] };
   state.verification.attempts = attempts.slice(-16);
+  if (progress) {
+    /** @type {VerificationState & {progress?: VerificationProgress}} */
+    (state.verification).progress = progress;
+  }
   writeNode(runDir, state, lock);
 }
 /**
@@ -85,12 +108,15 @@ export async function executeControllerVerification(contract, runDir, node, stat
   };
   writeNode(runDir, state, lock);
   const workspace = attemptWorkspace(state) ?? contract.cwd;
+  const commands = [...node.taskPacket.verification, ...sharedVerificationCommands(contract), ...finalVerificationCommands(contract, node)];
+  /** @param {VerificationAttempt} attempt @returns {VerificationProgress} */
+  const progressFor = (attempt) => verificationProgress(attempt.commandIndex + 1, commands.length, /** @type {VerificationCommand|undefined} */ (commands[attempt.commandIndex])?.argv);
   try {
-    const result = await runVerification([...node.taskPacket.verification, ...finalVerificationCommands(contract, node)], workspace, {
+    const result = await runVerification(commands, workspace, {
       logDir: join(runDir, "logs", `${node.id}.${state.attempt}.verification`),
       writeFiles: node.taskPacket.writeFiles ?? [],
-      onAttemptStart: (attempt) => persistVerificationAttempt(runDir, state, lock, attempt),
-      onAttemptSpawn: (attempt) => persistVerificationAttempt(runDir, state, lock, attempt),
+      onAttemptStart: (attempt) => persistVerificationAttempt(runDir, state, lock, attempt, progressFor(attempt)),
+      onAttemptSpawn: (attempt) => persistVerificationAttempt(runDir, state, lock, attempt, progressFor(attempt)),
       onAttemptComplete: (attempt) => persistVerificationAttempt(runDir, state, lock, {
         ...attempt,
         result: boundedVerificationAttemptResult(attempt.result),
@@ -102,10 +128,13 @@ export async function executeControllerVerification(contract, runDir, node, stat
       attempts: verificationAttemptRecords(state),
     };
   } catch (error) {
+    // A rebuilt object, not a spread of the prior one: a thrown error can land
+    // between an `onAttemptStart` and the matching `onAttemptComplete`, and the
+    // stale `progress` that start wrote must not survive into the terminal record.
     state.verification = {
-      ...state.verification,
-      completed: true,
       passed: false,
+      commands: state.verification?.commands ?? [],
+      completed: true,
       error: boundedUtf8(errorMessage(error), 4 * 1024),
       attempts: verificationAttemptRecords(state),
     };
@@ -146,6 +175,52 @@ export async function recoverVerificationAttempts(runDir, state, lock) {
   delete state.verification.error;
   writeNode(runDir, state, lock);
 }
+/**
+ * Re-run, once, exactly the candidate commands that failed here but passed in
+ * the attempt's own recorded verification, same argv and same position. A
+ * candidate whose *every* failure disagrees with the attempt this way is
+ * evidence about the two worktrees' environment rather than about the work --
+ * `candidateOnlyFailures` (judge-gate.mjs) already names that disagreement in
+ * the rejection it phrases, and this is what earns the candidate one
+ * independent confirmation before the node pays for a defect that may not be
+ * its own. A candidate with even one failure that also failed in the attempt
+ * is not purely divergent, so nothing is retried and the failure stands.
+ *
+ * `run` is the one side-effecting seam, injected so this stays unit-testable
+ * without a workspace or a git repository.
+ *
+ * @param {import("../contract/verification.mjs").VerificationResult} result the candidate's verification result
+ * @param {{commands?: Array<{argv?: string[], passed?: boolean}>}|null|undefined} attemptEvidence the attempt's own recorded verification
+ * @param {(indexes: number[]) => Promise<import("../contract/verification.mjs").VerificationCommandResult[]>} run re-runs exactly the commands at `indexes`, returning their results in that order
+ * @returns {Promise<import("../contract/verification.mjs").VerificationResult & {retried?: number[]}>}
+ */
+export async function retryDivergentCandidateCommands(result, attemptEvidence, run) {
+  const commands = result?.commands ?? [];
+  const failedIndexes = commands.reduce((indexes, command, index) => {
+    if (!command.passed) indexes.push(index);
+    return indexes;
+  }, /** @type {number[]} */ ([]));
+  if (!failedIndexes.length) return result;
+  const attemptCommands = attemptEvidence?.commands ?? [];
+  const divergent = failedIndexes.every((index) => {
+    const counterpart = attemptCommands[index];
+    return counterpart?.passed === true && argvEqual(commands[index]?.argv, counterpart.argv);
+  });
+  if (!divergent) return result;
+  const retried = await run(failedIndexes);
+  const merged = [...commands];
+  failedIndexes.forEach((index, position) => { merged[index] = retried[position]; });
+  return { ...result, commands: merged, passed: merged.every((command) => command.passed), retried: failedIndexes };
+}
+/**
+ * @param {unknown} a
+ * @param {unknown} b
+ * @returns {boolean}
+ */
+function argvEqual(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+  return a.every((item, index) => item === b[index]);
+}
 /**
  * @param {ValidatedContract} contract
  * @param {ValidatedNode} node
@@ -155,12 +230,26 @@ export async function recoverVerificationAttempts(runDir, state, lock) {
  * @returns {Promise<import("../repo/integrate.mjs").CandidateEvidence>}
  */
 export async function verifyCandidateWorkspace(contract, node, state, runDir, workspace) {
+  const commands = [...node.taskPacket.verification, ...sharedVerificationCommands(contract), ...finalVerificationCommands(contract, node)];
   try {
-    const result = await runVerification([...node.taskPacket.verification, ...finalVerificationCommands(contract, node)], workspace, {
+    const result = await runVerification(commands, workspace, {
       logDir: join(runDir, "logs", `${node.id}.${state.attempt}.candidate-verification`),
       writeFiles: node.taskPacket.writeFiles ?? [],
     });
-    return compactVerification(result);
+    /** @type {import("../contract/verification.mjs").VerificationResult & {retried?: number[]}} */
+    let settled = result;
+    if (!result.passed) {
+      settled = await retryDivergentCandidateCommands(result, state.verification, async (indexes) => {
+        const subset = indexes.map((index) => commands[index]);
+        const rerun = await runVerification(subset, workspace, {
+          logDir: join(runDir, "logs", `${node.id}.${state.attempt}.candidate-retry`),
+          writeFiles: node.taskPacket.writeFiles ?? [],
+        });
+        return rerun.commands;
+      });
+    }
+    const compacted = compactVerification(settled);
+    return settled.retried ? { ...compacted, retried: settled.retried } : compacted;
   } catch (error) {
     return { passed: false, error: boundedUtf8(errorMessage(error), 4 * 1024) };
   }

package/src/harnesses/agy/index.mjs

@@ -19,6 +19,9 @@ export const agyHarness = {
     // `--output-format=stream-json` writes one JSON line per event as the
     // turn runs, not one dump at exit.
     streamsOutput: true,
+    // Unmeasured: no run has proven whether agy's sandbox can signal child
+    // processes or read the process table.
+    signalsProcesses: null,
   },
 
   // command() always passes --dangerously-skip-permissions.

package/src/harnesses/claude/index.mjs

@@ -45,6 +45,11 @@ export const claudeHarness = {
     // `--output-format stream-json --verbose` writes one JSON line per event
     // as the turn runs, not one dump at exit.
     streamsOutput: true,
+    // Measured 2026-09-16: `bypassPermissions` runs an unsandboxed Bash that
+    // signals child processes and reads the process table; headless
+    // `acceptEdits` cannot run commands at all, so the flag describes the
+    // executing mode.
+    signalsProcesses: true,
   },
 
   // Headless acceptEdits denies Bash; bypassPermissions executes commands.

package/src/harnesses/codex/index.mjs

@@ -41,6 +41,9 @@ export const codexHarness = {
     // `--json` writes one JSONL event per item/turn as it happens, not one
     // dump at exit.
     streamsOutput: true,
+    // Unmeasured: no run has proven whether codex's sandbox can signal child
+    // processes or read the process table.
+    signalsProcesses: null,
   },
 
   // Every sandbox mode executes commands; sandbox only bounds their effects.

package/src/harnesses/dsh/index.mjs

@@ -51,6 +51,11 @@ export const dshHarness = {
     // deepseek-official/deepseek-flash grew the redirected stdout file from
     // 67 to 1,380 to 1,441 to 2,084 bytes across a 14s turn.
     streamsOutput: true,
+    // Measured 2026-09-16 in the controller's workspace-write sandbox: a test
+    // that starts and terminates a child process cannot signal it or read the
+    // process table, so it hangs until the executor's cap. `danger-full-access`
+    // was not measured.
+    signalsProcesses: false,
   },
 
   // sandbox maps to DSH_PERMISSION_MODE, which is the harness's file-effect
@@ -98,6 +103,7 @@ export const dshHarness = {
       args,
       promptTransport: "stdin",
       input: withSchema(prompt, options.schema),
+      env: dshEnvironmentOverlay(process.env),
     };
   },
 
@@ -156,6 +162,26 @@ export const dshHarness = {
   },
 };
 
+/**
+ * The environment overlay every dsh turn spawns with. The Claude Code shell
+ * exports `GIT_CONFIG_COUNT` with the VALUE half of each `GIT_CONFIG_{KEY,VALUE}_<n>`
+ * pair but not the key half, so `git init` inside the worker fails with status
+ * 128; the overlay removes the whole family. `GIT_TERMINAL_PROMPT=0` takes over
+ * the prompting that family was for. A null value removes the ambient variable
+ * when the gate merges the overlay over the runner environment.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {Record<string, string|null>}
+ */
+function dshEnvironmentOverlay(env) {
+  /** @type {Record<string, string|null>} */
+  const overlay = { GIT_TERMINAL_PROMPT: "0" };
+  for (const key of Object.keys(env)) {
+    if (key === "GIT_CONFIG_COUNT" || /^GIT_CONFIG_(?:KEY|VALUE)_\d+$/u.test(key)) overlay[key] = null;
+  }
+  return overlay;
+}
+
 /**
  * Append the output schema the judge prompt refers to. Codex and Claude receive
  * it through a native flag; this harness has none, so it travels in the prompt.

package/src/harnesses/exec-jsonl/index.mjs

@@ -74,6 +74,8 @@ export const execJsonlHarness = {
     // The protocol allows zero `message` events before the terminal one, so
     // an arbitrary wrapper cannot honestly advertise incremental output either.
     streamsOutput: false,
+    // Unmeasured: an arbitrary wrapper executable names no sandbox to measure.
+    signalsProcesses: null,
   },
 
   // The wrapper protocol exposes no permission mode.

package/src/harnesses/index.mjs

@@ -35,13 +35,14 @@ const CAPABILITY_NAMES = new Set([
   "cost",
   "toolPolicy",
   "streamsOutput",
+  "signalsProcesses",
 ]);
 
-/** @typedef {"structuredOutput"|"promptTransport"|"sandbox"|"permissions"|"continuation"|"tokenBudget"|"costBudget"|"usage"|"cost"|"toolPolicy"|"streamsOutput"} CapabilityName */
+/** @typedef {"structuredOutput"|"promptTransport"|"sandbox"|"permissions"|"continuation"|"tokenBudget"|"costBudget"|"usage"|"cost"|"toolPolicy"|"streamsOutput"|"signalsProcesses"} CapabilityName */
 
-/** @typedef {{structuredOutput: boolean, promptTransport: "stdin"|"argv", sandbox: boolean, permissions: boolean, continuation: boolean, tokenBudget: boolean, costBudget: boolean, usage: boolean, cost: boolean, toolPolicy: boolean, streamsOutput: boolean, maxArgvPromptBytes?: number}} HarnessCapabilities */
+/** @typedef {{structuredOutput: boolean, promptTransport: "stdin"|"argv", sandbox: boolean, permissions: boolean, continuation: boolean, tokenBudget: boolean, costBudget: boolean, usage: boolean, cost: boolean, toolPolicy: boolean, streamsOutput: boolean, signalsProcesses: boolean|null, maxArgvPromptBytes?: number}} HarnessCapabilities */
 
-/** @typedef {{structuredOutput?: boolean, promptTransport?: "stdin"|"argv", sandbox?: boolean, permissions?: boolean, continuation?: boolean, tokenBudget?: boolean, costBudget?: boolean, usage?: boolean, cost?: boolean, toolPolicy?: boolean, streamsOutput?: boolean}} CapabilityRequirements */
+/** @typedef {{structuredOutput?: boolean, promptTransport?: "stdin"|"argv", sandbox?: boolean, permissions?: boolean, continuation?: boolean, tokenBudget?: boolean, costBudget?: boolean, usage?: boolean, cost?: boolean, toolPolicy?: boolean, streamsOutput?: boolean, signalsProcesses?: boolean|null}} CapabilityRequirements */
 
 /** @typedef {{executable: string, args: string[], promptTransport: "stdin"|"argv", input: string|null, env?: Record<string, string|null>}} HarnessCommand */
 
@@ -324,6 +325,12 @@ export function validateCapabilityRequirements(requirements, label = "requiredCa
     if (!isCapabilityName(name)) throw new TypeError(`${label}.${name} is unknown`);
     if (name === "promptTransport") {
       if (value !== "stdin" && value !== "argv") throw new TypeError(`${label}.promptTransport is invalid`);
+    } else if (name === "signalsProcesses") {
+      // Tri-state: `null` is a harness whose sandbox has not been measured, so
+      // it can never satisfy a true or false requirement.
+      if (value !== true && value !== false && value !== null) {
+        throw new TypeError(`${label}.signalsProcesses must be true, false, or null`);
+      }
     } else if (typeof value !== "boolean") {
       throw new TypeError(`${label}.${name} must be boolean`);
     }

package/src/harnesses/replay/index.mjs

@@ -37,6 +37,8 @@ export const replayHarness = {
     // replay/bin.mjs writes its one envelope line after the recorded delay,
     // never incrementally.
     streamsOutput: false,
+    // A recording executes nothing, so it never starts a process to signal.
+    signalsProcesses: false,
   },
 
   // A recording exposes no permission mode.

package/src/harnesses/zcode/index.mjs

@@ -70,6 +70,9 @@ export const zcodeHarness = {
     // log held its full 26 lines only once the process exited. Stall
     // detection must not watch this harness's stdout/stderr mtime.
     streamsOutput: false,
+    // Unmeasured: no run has proven whether zcode's sandbox can signal child
+    // processes or read the process table.
+    signalsProcesses: null,
   },
 
   // build/edit/plan do not execute commands; command() defaults to yolo.

package/src/host/preflight.mjs

@@ -20,6 +20,7 @@ import { delimiter, join, resolve } from "node:path";
 import { CONTRACT_VERSION, PROTOCOL_SCHEMA_VERSION, getHarness, probeRuntime } from "../harnesses/index.mjs";
 import { addRuntimeRequirement, failoverTargets, runtimeSnapshot } from "../engine/failover.mjs";
 import { validateContract } from "../contract/index.mjs";
+import { sharedVerificationCommands } from "../contract/final-verification.mjs";
 import { DISCOVERY_RUNTIME_DEFINITIONS, discoverRuntimes } from "../engine/runtime-discovery.mjs";
 import { errorMessage } from "../util.mjs";
 import { boundedGitSync } from "../repo/worktree.mjs";
@@ -220,7 +221,9 @@ const VERIFICATION_DURATION_WARN_RATIO = 0.8;
 
 /**
  * Every distinct verification command the contract declares, with the
- * strictest timeout any node gives it and the nodes that share it.
+ * strictest timeout any node gives it and the nodes that share it. The
+ * contract-wide `sharedVerification` set is included once, under the name
+ * `sharedVerification`, because every node runs it.
  *
  * Commands are keyed by argv and cwd, never merged across different argv, so
  * one measurement stands in for every node that declares the same command —
@@ -234,6 +237,7 @@ export function declaredVerificationCommands(contract) {
   const commands = new Map();
   const declarations = [
     ...contract.nodes.flatMap((node) => (node.taskPacket?.verification ?? []).map((command) => ({ command, node: node.id }))),
+    ...sharedVerificationCommands(contract).map((command) => ({ command, node: "sharedVerification" })),
     ...(contract.finalVerification ?? []).map((command) => ({ command, node: "finalVerification" })),
   ];
   for (const { command, node } of declarations) {

package/src/notify/index.mjs

@@ -11,6 +11,33 @@
  * a `no_transport` receipt is recorded instead — there is no implicit desktop
  * fallback. The macOS notifier is reachable only by setting
  * `FABERUN_NOTIFY_BIN=os-macos`, an explicit opt-in, never a default.
+ *
+ * Measured 2026-09-16: `test/cli/cli.test.mjs`'s two notifier fixtures were
+ * instrumented with `{at, phase}` timelines (spawned, stdin-end, exit) and run
+ * over 80 times (targeted loops, four-way parallel full-file bursts, and a
+ * 15-way parallel burst) alongside `node --test test/engine/` and
+ * `test/contract/` as background load; every completed timeline resolved in
+ * under 40ms end to end, and a direct spawn-to-first-line-of-JS measurement
+ * under the same load never exceeded 306ms across 40 concurrent spawns --
+ * ruling out class (a) (Node process launch under load), since 306ms is
+ * ~16x below the 5000ms budget that has been observed to fire. Two genuine
+ * `notification timed out after 5000ms` receipts turned up in leftover run
+ * directories from other concurrent sessions on this shared machine (their
+ * fixtures unmodified, so no timeline exists for them), confirming the flake
+ * is real but requires contention this harness could not reliably reproduce
+ * with an instrumented fixture. Class (c) (stdin never ends) is excluded by
+ * inspection: `spawnDeliver` below always calls `child.stdin.end(...)`
+ * synchronously right after spawning, unconditionally. That leaves class (b):
+ * the previous implementation resolved on the child's `close` event, which
+ * Node fires only once every stdio stream (including the piped, accumulating
+ * `stderr`) has finished closing -- a fd inherited or held open by a
+ * lingering grandchild, or slow to flush under load, delays `close` well
+ * past the point the notifier process itself has already exited. `spawnDeliver`
+ * now resolves on `exit` (fires as soon as the process itself terminates,
+ * independent of stdio stream closure) instead of `close`, and no longer
+ * gates delivery on the stderr stream ending. The timeout budget is left at
+ * its original 5000ms: no measurement here justified raising it, and the (b)
+ * fix removes the mechanism that budget was actually timing out on.
  */
 
 import { spawn as defaultSpawn } from "node:child_process";
@@ -32,6 +59,15 @@ export const NOTIFY_LOG_FILE = "notify.jsonl";
  */
 export const MAX_ATTEMPTS = 3;
 
+/**
+ * The spawn-to-delivery budget for a non-macOS transport, in milliseconds.
+ * Unchanged from its original value: the 2026-09-16 measurement (see the
+ * module header) found no evidence this needed to be larger, only that the
+ * previous implementation could time out waiting on `close` while the child
+ * had already exited. That is fixed at the source in `spawnDeliver` below.
+ */
+export const notificationDeliveryTimeoutMs = 5_000;
+
 const SUMMARY_CHARS = 200;
 
 /**
@@ -248,12 +284,19 @@ function deliverNotification(event, options = {}) {
 }
 
 /**
+ * Resolves on the child's own `exit`, not `close`: `close` waits for every
+ * stdio stream to finish closing, and a piped `stderr` fd can be held open
+ * by a lingering grandchild or be slow to flush under load well after the
+ * notifier process itself has terminated. Gating delivery on that stream
+ * closing (as the previous implementation did) could stall a healthy,
+ * already-exited delivery until the timeout fired.
+ *
  * @param {string} bin
  * @param {JsonObject} event
  * @param {{spawn?: typeof defaultSpawn, timeoutMs?: number}} options
  * @returns {Promise<DeliveryResult>}
  */
-function spawnDeliver(bin, event, { spawn = defaultSpawn, timeoutMs = 5_000 } = {}) {
+function spawnDeliver(bin, event, { spawn = defaultSpawn, timeoutMs = notificationDeliveryTimeoutMs } = {}) {
   return new Promise((resolveDelivery) => {
     let child;
     try {
@@ -275,7 +318,7 @@ function spawnDeliver(bin, event, { spawn = defaultSpawn, timeoutMs = 5_000 } =
       stderr = `${stderr}${chunk}`.slice(-1024);
     });
     child.once("error", (error) => finish({ ok: false, error: errorMessage(error) }));
-    child.once("close", (code) => finish(code === 0 ? { ok: true } : { ok: false, error: stderr || `notification exited ${code}` }));
+    child.once("exit", (code) => finish(code === 0 ? { ok: true } : { ok: false, error: stderr || `notification exited ${code}` }));
     const timer = setTimeout(() => {
       try {
         child.kill("SIGTERM");

package/src/repo/source-identity.mjs

@@ -46,7 +46,7 @@ export function validateSourceIdentity(value, label, expected = null) {
   assertObject(value, label);
   const allowed = new Set([
     "kind", "id", "campaignId", "contractId", "nodeId", "cwd", "gitHead",
-    "dirtyTreeFingerprint", "packetHashes", "harnessVersions",
+    "dirtyTreeFingerprint", "packetHashes", "harnessVersions", "baseRef",
   ]);
   rejectUnknown(value, allowed, label);
   requireString(value.kind, `${label}.kind`);
@@ -54,7 +54,7 @@ export function validateSourceIdentity(value, label, expected = null) {
     if (value[key] !== undefined) requireId(value[key], `${label}.${key}`);
   }
   if (value.cwd !== undefined) requireString(value.cwd, `${label}.cwd`);
-  for (const key of ["gitHead", "dirtyTreeFingerprint"]) {
+  for (const key of ["gitHead", "dirtyTreeFingerprint", "baseRef"]) {
     if (value[key] !== undefined && value[key] !== null) requireString(value[key], `${label}.${key}`);
   }
   if (value.packetHashes !== undefined) validateHashMap(value.packetHashes, `${label}.packetHashes`);
@@ -75,7 +75,7 @@ export function validateSourceIdentity(value, label, expected = null) {
 /**
  * @param {{id: string, campaignId: string, cwd: string, nodes: {id: string, packetHash: string}[]}} contract
  * @param {Record<string, string|null>} harnessVersions
- * @param {{ignorePaths?: string[], ignoreRoots?: string[]}} options
+ * @param {{ignorePaths?: string[], ignoreRoots?: string[], baseRef?: string}} options
  */
 export function captureSourceIdentity(contract, harnessVersions = {}, options = {}) {
   const git = gitIdentity(contract.cwd, options);
@@ -88,6 +88,7 @@ export function captureSourceIdentity(contract, harnessVersions = {}, options =
     dirtyTreeFingerprint: git.dirtyTreeFingerprint,
     packetHashes: Object.fromEntries(contract.nodes.map((node) => [node.id, node.packetHash])),
     harnessVersions,
+    baseRef: options.baseRef ?? null,
   }, "run source identity", { kind: "run", contractId: contract.id, campaignId: contract.campaignId });
 }
 /**

package/src/report/final.mjs

@@ -90,7 +90,7 @@ export function renderFinalReport(runDir, contract, states) {
   const widths = [3, 24, 9, 7, 7, 28, 10, 10, 10, 12, 64];
   /** @param {unknown[]} cells */
   const row = (cells) => cells.map((cell, index) => fit(String(cell ?? ""), widths[index])).join(" ");
-  const totals = { inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0 };
+  const totals = { inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0, declaredReadBytes: 0 };
   let totalCostUsd = null;
   const lines = [
     `# run ${basename(runDir)}`,
@@ -106,6 +106,7 @@ export function renderFinalReport(runDir, contract, states) {
     totals.inputTokens += usage.inputTokens ?? 0;
     totals.outputTokens += usage.outputTokens ?? 0;
     totals.cacheReadInputTokens += usage.cacheReadInputTokens ?? 0;
+    if (typeof node.declaredReadBytes === "number") totals.declaredReadBytes += node.declaredReadBytes;
     if (typeof node.costUsd === "number" && Number.isFinite(node.costUsd)) totalCostUsd = (totalCostUsd ?? 0) + node.costUsd;
     const runtime = node.runtime ? `${node.runtime.harness}/${node.runtime.model}` : "-";
     const planNode = contract.nodes.find((candidate) => candidate.id === node.id);
@@ -129,7 +130,7 @@ export function renderFinalReport(runDir, contract, states) {
     ]));
   }
   const roles = roleCosts(nodes);
-  lines.push("```", "", `totals · in ${compactTokens(totals.inputTokens)} · out ${compactTokens(totals.outputTokens)} · cache ${compactTokens(totals.cacheReadInputTokens)} · worker ${compactCost(roles.worker)} · judge ${compactCost(roles.judge)} · cost ${compactCost(totalCostUsd)}`);
+  lines.push("```", "", `totals · in ${compactTokens(totals.inputTokens)} · out ${compactTokens(totals.outputTokens)} · cache ${compactTokens(totals.cacheReadInputTokens)} · worker ${compactCost(roles.worker)} · judge ${compactCost(roles.judge)} · cost ${compactCost(totalCostUsd)} · read ${compactTokens(totals.declaredReadBytes)}`);
   return `${lines.join("\n")}\n`;
 }
 /**