faberun 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Faberun is a development orchestration system that turns intent into verified software: harness- and model-agnostic, it keeps the intent, coordinates the work, verifies the result and decides what happens next.",
   "type": "module",
   "bin": {
@@ -27,6 +27,8 @@
     "check": "for f in bin/*.mjs .claude/hooks/*.mjs src/*.mjs src/*/*.mjs src/*/*/*.mjs evals/*.mjs test/*.mjs test/*/*.mjs; do node --check \"$f\" || exit 1; done",
     "typecheck": "tsc",
     "test": "node --test test/*.test.mjs test/*/*.test.mjs",
+    "docs": "node src/cli/manual.mjs --write",
+    "docs:check": "node src/cli/manual.mjs --check",
     "prepare": "husky"
   },
   "devDependencies": {

package/src/cli/campaign.mjs

@@ -728,3 +728,5 @@ function usage() {
   );
   process.exitCode = 2;
 }
+
+export default OPERATION_OPTIONS;

package/src/cli/contract.mjs

@@ -65,3 +65,5 @@ function usage() {
   process.stderr.write("usage: faberun contract validate <contract.json>\n");
   process.exitCode = 2;
 }
+
+export default OPERATION_OPTIONS;

package/src/cli/manual.mjs

@@ -0,0 +1,341 @@
+/**
+ * Regenerates the derivable parts of docs/COMMANDS.md — verb and operation
+ * headings, synopsis lines and flag-table rows — from the option tables the
+ * CLI itself dispatches on. Every other line (description paragraphs,
+ * reads/writes prose, examples, Related lines, and the four fixed sections)
+ * is copied through unchanged, so the manual's prose stays hand-authored
+ * while its command surface cannot drift from the code silently.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { COMMAND_OPTIONS } from "../cli.mjs";
+import CAMPAIGN_OPERATIONS from "./campaign.mjs";
+import SEAT_OPERATIONS from "./seat.mjs";
+import CONTRACT_OPERATIONS from "./contract.mjs";
+import SKILLS_OPERATIONS from "./skills.mjs";
+
+/** @typedef {{type: "string"|"boolean", multiple?: boolean}} FlagSpec */
+/** @typedef {{flags?: Record<string, FlagSpec>, operations?: Record<string, Record<string, FlagSpec>>}} VerbSurface */
+/** @typedef {{verbs: Record<string, VerbSurface>}} Surface */
+
+const MANUAL_PATH = fileURLToPath(new URL("../../docs/COMMANDS.md", import.meta.url));
+
+/**
+ * `campaign`, `seat`, `contract` and `skills` are dispatched before
+ * `COMMAND_OPTIONS` is ever consulted (`cli.mjs` routes them by `argv[0]`), so
+ * they carry no flags of their own — only the operations their own module
+ * declares. Their top-level `## faberun <verb>` section is therefore never
+ * regenerated; it is hand-authored overview prose, preserved verbatim.
+ *
+ * @type {Record<string, Record<string, Record<string, FlagSpec>>>}
+ */
+const CONTAINER_OPERATIONS = {
+  campaign: CAMPAIGN_OPERATIONS,
+  seat: SEAT_OPERATIONS,
+  contract: CONTRACT_OPERATIONS,
+  skills: SKILLS_OPERATIONS,
+};
+
+/**
+ * The real command surface, read from the same option tables `cli.mjs`
+ * parses argv against. `supervise campaign` is `campaign.mjs`'s `supervise`
+ * operation reached through a second spelling (`cli.mjs` routes
+ * `argv = ["supervise", "campaign", …]` into `campaignCli`), so it shares that
+ * operation's flags rather than declaring its own.
+ *
+ * @returns {Surface}
+ */
+export function collectSurface() {
+  /** @type {Record<string, VerbSurface>} */
+  const verbs = {};
+  for (const [verb, flags] of Object.entries(COMMAND_OPTIONS)) verbs[verb] = { flags };
+  if (verbs.supervise) verbs.supervise.operations = { campaign: CAMPAIGN_OPERATIONS.supervise };
+  for (const [verb, operations] of Object.entries(CONTAINER_OPERATIONS)) verbs[verb] = { operations };
+  return { verbs };
+}
+
+const VERB_HEADING = /^## faberun ([a-z][a-z-]*)$/u;
+const TABLE_HEADER = "| Flag | Value | Effect | Default |";
+const TABLE_SEPARATOR = "| --- | --- | --- | --- |";
+/** The start of a flag token in a synopsis line: `--flag` or `[--flag`. */
+const FLAG_TOKEN = /\[?--/u;
+
+/**
+ * Regenerate the derivable parts of a command manual. A verb absent from
+ * `surface` is dropped; one present in `surface` but absent from `current` is
+ * appended as a skeleton section.
+ *
+ * @param {string} current
+ * @param {Surface} surface
+ * @returns {string}
+ */
+export function renderManual(current, surface) {
+  const lines = current.split("\n");
+  /** @type {string[]} */
+  const output = [];
+  const seenVerbs = new Set();
+  let i = 0;
+  while (i < lines.length) {
+    const match = VERB_HEADING.exec(lines[i]);
+    if (!match) {
+      output.push(lines[i]);
+      i += 1;
+      continue;
+    }
+    const verb = match[1];
+    let end = i + 1;
+    while (end < lines.length && !/^## /u.test(lines[end])) end += 1;
+    const entry = surface.verbs[verb];
+    if (entry) {
+      output.push(...renderVerbBlock(verb, lines.slice(i, end), entry));
+      seenVerbs.add(verb);
+    }
+    i = end;
+  }
+  for (const [verb, entry] of Object.entries(surface.verbs)) {
+    if (!seenVerbs.has(verb)) output.push(...renderVerbBlock(verb, [`## faberun ${verb}`], entry));
+  }
+  return output.join("\n");
+}
+
+/**
+ * @param {string} verb
+ * @param {string[]} block
+ * @param {VerbSurface} entry
+ * @returns {string[]}
+ */
+function renderVerbBlock(verb, block, entry) {
+  const heading = block[0] ?? `## faberun ${verb}`;
+  const { body, operationBlocks } = splitOperations(verb, block.slice(1));
+  const renderedBody = entry.flags
+    ? renderFlaggedBody(`faberun ${verb}`, body, entry.flags)
+    : body.length
+      ? body
+      : renderFlaggedBody(`faberun ${verb}`, [], {});
+  const renderedOperations = renderOperations(verb, operationBlocks, entry.operations ?? {});
+  return [heading, ...renderedBody, ...renderedOperations];
+}
+
+/**
+ * Splits a verb's body into the part before its first `### faberun <verb>
+ * <op>` heading and the operation sub-blocks that follow, each running to the
+ * next `### ` heading.
+ *
+ * @param {string} verb
+ * @param {string[]} lines
+ * @returns {{body: string[], operationBlocks: {op: string, block: string[]}[]}}
+ */
+function splitOperations(verb, lines) {
+  const opHeading = new RegExp(`^### faberun ${verb} ([a-z][a-z-]*)$`, "u");
+  const firstOpIndex = lines.findIndex((line) => opHeading.test(line));
+  if (firstOpIndex === -1) return { body: lines, operationBlocks: [] };
+  const body = lines.slice(0, firstOpIndex);
+  /** @type {{op: string, block: string[]}[]} */
+  const operationBlocks = [];
+  let i = firstOpIndex;
+  while (i < lines.length) {
+    const match = opHeading.exec(lines[i]);
+    if (!match) break;
+    let end = i + 1;
+    while (end < lines.length && !/^###? /u.test(lines[end])) end += 1;
+    operationBlocks.push({ op: match[1], block: lines.slice(i, end) });
+    i = end;
+  }
+  return { body, operationBlocks };
+}
+
+/**
+ * @param {string} verb
+ * @param {{op: string, block: string[]}[]} operationBlocks
+ * @param {Record<string, Record<string, FlagSpec>>} operations
+ * @returns {string[]}
+ */
+function renderOperations(verb, operationBlocks, operations) {
+  const output = [];
+  const seen = new Set();
+  for (const { op, block } of operationBlocks) {
+    if (!Object.hasOwn(operations, op)) continue;
+    output.push(block[0] ?? `### faberun ${verb} ${op}`, ...renderFlaggedBody(`faberun ${verb} ${op}`, block.slice(1), operations[op]));
+    seen.add(op);
+  }
+  for (const [op, flags] of Object.entries(operations)) {
+    if (seen.has(op)) continue;
+    output.push(`### faberun ${verb} ${op}`, ...renderFlaggedBody(`faberun ${verb} ${op}`, [], flags));
+  }
+  return output;
+}
+
+/**
+ * Regenerates a section's synopsis fence and flag table in place; every
+ * other line is untouched.
+ *
+ * @param {string} prefix
+ * @param {string[]} body
+ * @param {Record<string, FlagSpec>} flags
+ * @returns {string[]}
+ */
+function renderFlaggedBody(prefix, body, flags) {
+  const positional = extractPositional(prefix, body);
+  const synopsis = renderSynopsis(prefix, positional, flags);
+  const fence = findFence(body, "```text");
+  const withSynopsis = fence
+    ? [...body.slice(0, fence.start), "```text", synopsis, "```", ...body.slice(fence.end + 1)]
+    : ["```text", synopsis, "```", ...body];
+  return replaceFlagTable(withSynopsis, flags);
+}
+
+/**
+ * The positional placeholder a synopsis names, kept verbatim from the
+ * current text (including its own brackets, when optional) — everything
+ * before the first flag token.
+ *
+ * @param {string} prefix
+ * @param {string[]} body
+ * @returns {string}
+ */
+function extractPositional(prefix, body) {
+  const fence = findFence(body, "```text");
+  if (!fence) return "";
+  const inner = body[fence.start + 1] ?? "";
+  if (!inner.startsWith(prefix)) return "";
+  const remainder = inner.slice(prefix.length).trim();
+  const flagToken = FLAG_TOKEN.exec(remainder);
+  return flagToken ? remainder.slice(0, flagToken.index).trim() : remainder;
+}
+
+/**
+ * @param {string} prefix
+ * @param {string} positional
+ * @param {Record<string, FlagSpec>} flags
+ * @returns {string}
+ */
+function renderSynopsis(prefix, positional, flags) {
+  const parts = [prefix];
+  if (positional) parts.push(positional);
+  for (const [name, spec] of Object.entries(flags)) {
+    if (spec.type === "boolean") parts.push(`[--${name}]`);
+    else if (spec.multiple) parts.push(`[--${name} <a>...]`);
+    else parts.push(`[--${name} <value>]`);
+  }
+  return parts.join(" ");
+}
+
+/**
+ * @param {string[]} lines
+ * @param {string} opener
+ * @returns {{start: number, end: number}|null}
+ */
+function findFence(lines, opener) {
+  const start = lines.indexOf(opener);
+  if (start === -1) return null;
+  let end = start + 1;
+  while (end < lines.length && lines[end] !== "```") end += 1;
+  return { start, end };
+}
+
+/**
+ * @param {string[]} lines
+ * @param {Record<string, FlagSpec>} flags
+ * @returns {string[]}
+ */
+function replaceFlagTable(lines, flags) {
+  const headerIndex = lines.indexOf(TABLE_HEADER);
+  const existingRows = headerIndex === -1 ? new Map() : parseRows(lines, headerIndex + 2);
+  const newRows = buildRows(flags, existingRows);
+  if (headerIndex === -1) {
+    const fenceEnd = lines.indexOf("```");
+    const insertAt = fenceEnd === -1 ? lines.length : fenceEnd + 1;
+    return [...lines.slice(0, insertAt), TABLE_HEADER, TABLE_SEPARATOR, ...newRows, ...lines.slice(insertAt)];
+  }
+  let rowsEnd = headerIndex + 2;
+  while (rowsEnd < lines.length && lines[rowsEnd].startsWith("|")) rowsEnd += 1;
+  return [...lines.slice(0, headerIndex), TABLE_HEADER, TABLE_SEPARATOR, ...newRows, ...lines.slice(rowsEnd)];
+}
+
+/**
+ * @param {string[]} lines
+ * @param {number} start
+ * @returns {Map<string, {value: string, effect: string, default: string}>}
+ */
+function parseRows(lines, start) {
+  /** @type {Map<string, {value: string, effect: string, default: string}>} */
+  const map = new Map();
+  let i = start;
+  while (i < lines.length && lines[i].startsWith("|")) {
+    const cells = lines[i].trim().replace(/^\|/u, "").replace(/\|$/u, "").split("|").map((cell) => cell.trim());
+    if (cells.length === 4) map.set(flagKeyOf(cells[0]), { value: cells[1], effect: cells[2], default: cells[3] });
+    i += 1;
+  }
+  return map;
+}
+
+/** @param {string} cell @returns {string} */
+function flagKeyOf(cell) {
+  const match = /`--([a-z-]+)`/u.exec(cell);
+  return match ? match[1] : "—";
+}
+
+/**
+ * @param {Record<string, FlagSpec>} flags
+ * @param {Map<string, {value: string, effect: string, default: string}>} existingRows
+ * @returns {string[]}
+ */
+function buildRows(flags, existingRows) {
+  const names = Object.keys(flags);
+  if (names.length === 0) {
+    const existing = existingRows.get("—");
+    return [existing ? `| — | ${existing.value} | ${existing.effect} | ${existing.default} |` : "| — | — | No flags. | — |"];
+  }
+  return names.map((name) => {
+    const existing = existingRows.get(name);
+    const value = existing ? existing.value : "<value>";
+    const effect = existing ? existing.effect : "";
+    const fallback = existing ? existing.default : "—";
+    return `| \`--${name}\` | ${value} | ${effect} | ${fallback} |`;
+  });
+}
+
+/**
+ * A minimal, dependency-free diff summary: every line index where the two
+ * texts disagree, capped so a large rewrite does not flood the console.
+ *
+ * @param {string} current
+ * @param {string} next
+ * @returns {string}
+ */
+function diffSummary(current, next) {
+  const a = current.split("\n");
+  const b = next.split("\n");
+  const max = Math.max(a.length, b.length);
+  /** @type {string[]} */
+  const lines = [];
+  for (let i = 0; i < max && lines.length < 40; i += 1) {
+    if (a[i] !== b[i]) lines.push(`line ${i + 1}:\n- ${a[i] ?? "<eof>"}\n+ ${b[i] ?? "<eof>"}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * @param {string[]} argv
+ * @returns {void}
+ */
+function main(argv) {
+  const mode = argv[0];
+  if (mode !== "--write" && mode !== "--check") {
+    process.stderr.write("usage: manual.mjs --write|--check\n");
+    process.exitCode = 2;
+    return;
+  }
+  const current = readFileSync(MANUAL_PATH, "utf8");
+  const next = renderManual(current, collectSurface());
+  if (next === current) return;
+  if (mode === "--write") {
+    writeFileSync(MANUAL_PATH, next);
+    return;
+  }
+  process.stderr.write(`docs/COMMANDS.md is out of date; run \`npm run docs\`.\n${diffSummary(current, next)}\n`);
+  process.exitCode = 1;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) main(process.argv.slice(2));

package/src/cli/seat.mjs

@@ -137,3 +137,5 @@ function usage() {
   process.stderr.write("usage: faberun seat <start|attach|status|stop|switch> [<campaign-id>] [--cwd <dir>] ...\n");
   process.exitCode = 2;
 }
+
+export default OPERATION_OPTIONS;

package/src/cli/skills.mjs

@@ -403,3 +403,5 @@ function usage() {
   process.stderr.write("usage: faberun skills <list|install|register> [<name>...] [--target <dir>] [--global] [--force] [--copy] [--harness <a,b>] [--json]\n");
   process.exitCode = 2;
 }
+
+export default OPERATION_OPTIONS;

package/src/cli.mjs

@@ -87,7 +87,7 @@ export function hasDetachedBootstrapNonce() {
 }
 
 /** @type {Record<string, import("node:util").ParseArgsOptionsConfig>} */
-const COMMAND_OPTIONS = {
+export const COMMAND_OPTIONS = {
   run: { detach: { type: "boolean" }, "base-ref": { type: "string" } },
   resume: { detach: { type: "boolean" }, node: { type: "string" }, reconcile: { type: "string" }, answer: { type: "string" } },
   supervise: { detach: { type: "boolean" }, interval: { type: "string" } },

package/src/contract/index.mjs

@@ -79,7 +79,7 @@ const GATE_REVIEWS = new Set(["none", "advisory", "blocking"]);
 /** @typedef {{history: RoutingHistoryEntry[], currentOverride: RoutingOverride|null, assignments?: RuntimeAssignments, availability?: Record<string, RuntimeAvailability>, tierExhaustion?: TierExhaustion, tierExhaustionCycle?: number}} RoutingState */
 /** @typedef {{revision?: number, heartbeatCount: number, dryHeartbeatCount: number, progressSignature?: string|null, lastHeartbeatAt: string|null, lastProgressAt: string|null, nextCheckAt?: string|null}} ProgressState */
 /** @typedef {{status: "unassigned"|"provisioning"|"ready"|"failed"|"removed", path: string|null, branch: string|null, commit: string|null, baseSha?: string|null, sealedSha?: string|null, sealError?: string|null, previousAttempt?: number|null}} WorktreeState */
-/** @typedef {{schemaVersion: number, contractVersion: string, id: string, type: string, sourceIdentity: SourceIdentity, packetHash: string, status: NodeStatus, phase: NodePhase, attempt: number, revisions: number, judgeFailures?: number, review?: ("none"|"advisory"|"blocking"), runtime: RuntimeSnapshot|null, blockedBy: string[], startedAt: string|null, updatedAt: string, result: unknown, gate: GateResult|null, error: SnapshotError|null, usage?: Usage, costUsd?: number, routing?: RoutingState|null, progress?: ProgressState|null, worktree?: WorktreeState|null, integratedHead?: string|null, invocations?: Invocation[], executionOverrides?: ExecutionOverride[], verification?: VerificationState|null, scope?: BoundedScope|null, scopeFindings?: ScopeFindings|null, previousAttempt?: string, sessionPolicy?: {forceFresh?: boolean}|null}} NodeSnapshot */
+/** @typedef {{schemaVersion: number, contractVersion: string, id: string, type: string, sourceIdentity: SourceIdentity, packetHash: string, status: NodeStatus, phase: NodePhase, attempt: number, revisions: number, judgeFailures?: number, review?: ("none"|"advisory"|"blocking"), runtime: RuntimeSnapshot|null, blockedBy: string[], startedAt: string|null, updatedAt: string, result: unknown, gate: GateResult|null, error: SnapshotError|null, usage?: Usage, costUsd?: number, routing?: RoutingState|null, progress?: ProgressState|null, worktree?: WorktreeState|null, integratedHead?: string|null, invocations?: Invocation[], executionOverrides?: ExecutionOverride[], verification?: VerificationState|null, scope?: BoundedScope|null, scopeFindings?: ScopeFindings|null, previousAttempt?: string, sessionPolicy?: {forceFresh?: boolean}|null, declaredReadBytes?: number|null}} NodeSnapshot */
 /** @typedef {{path: string, sha: string}} ControllerIdentity */
 /** @typedef {{schemaVersion: number, contractVersion: string, pid: number, processStartToken: string|null, startedAt: string, sourceIdentity: SourceIdentity, controllerIdentity?: ControllerIdentity, integrationRef?: string, identityWarnings?: string[], relaunchCount?: number, lastRelaunchProgressAt?: string|null, attention?: {code: string, message: string, at: string}|null, contractDigest?: string, scopeDecision?: ScopeDecision, autoRetries?: Record<string, {code: string, at: string}>}} RunMetadata */
 /** @typedef {{at: string, base: string|null, dirtyTreeFingerprint: string|null}} ScopeDecision */

package/src/contract/snapshot.mjs

@@ -129,7 +129,7 @@ export function validateNodeSnapshot(value, expectedNode = null) {
     "schemaVersion", "contractVersion", "id", "type", "sourceIdentity", "packetHash", "status", "phase",
     "attempt", "revisions", "judgeFailures", "runtime", "blockedBy", "startedAt", "updatedAt", "result", "gate", "error", "usage",
     "costUsd", "routing", "progress", "worktree", "invocations", "executionOverrides", "verification", "scope",
-    "scopeFindings", "review", "previousAttempt", "sessionPolicy", "integratedHead",
+    "scopeFindings", "review", "previousAttempt", "sessionPolicy", "integratedHead", "declaredReadBytes",
   ]), "node snapshot");
   validateMetadata(value, "node snapshot");
   requireId(value.id, "node snapshot.id");
@@ -166,6 +166,12 @@ export function validateNodeSnapshot(value, expectedNode = null) {
   validateSnapshotError(value.error, "node snapshot.error");
   if (value.usage !== undefined) validateUsage(value.usage, "node snapshot.usage");
   if (value.costUsd !== undefined) nonNegativeNumber(value.costUsd, "node snapshot.costUsd");
+  // The summed byte size of the node's declared readFiles in the attempt
+  // worktree at dispatch time -- the one quantity the controller can measure
+  // about a packet's reference load, since the worker reads the files itself.
+  if (value.declaredReadBytes !== undefined && value.declaredReadBytes !== null) {
+    nonNegativeInteger(value.declaredReadBytes, "node snapshot.declaredReadBytes");
+  }
   if (value.routing !== undefined && value.routing !== null) validateRoutingState(value.routing, "node snapshot.routing");
   if (value.progress !== undefined && value.progress !== null) validateProgressState(value.progress, "node snapshot.progress");
   if (value.worktree !== undefined && value.worktree !== null) validateWorktreeState(value.worktree, "node snapshot.worktree");

package/src/engine/dispatch.mjs

@@ -32,7 +32,7 @@ import { emptyScope, persistedScopeBoundary, workerScope } from "./scope.mjs";
 import { hasOperationIntent, hasOperationSettlement, operationNeedsRecovery, operationNextState, persistInvocationIntent, providerReceipts, settleInvocation } from "../run/operations.mjs";
 import { invocationCost, invocationUsage } from "../run/usage.mjs";
 import { logPaths, readBoundedTail, startProcess } from "./process.mjs";
-import { mkdirSync } from "node:fs";
+import { mkdirSync, statSync } from "node:fs";
 import { READ_LINE_LIMIT, normalizeProviderResult, providerCommand } from "../harnesses/index.mjs";
 import { readJson, writeJsonAtomic } from "../run/store.mjs";
 import { judgeReaskInstruction, reviewMode } from "../contract/review-modes.mjs";
@@ -267,6 +267,30 @@ function phaseHandoffPrompt(contract, node, state, runDir, role) {
   ].join("\n\n");
   return boundedUtf8(handoff, 60 * 1024);
 }
+/**
+ * The declared weight of a node's readFiles at dispatch time: the sum of the
+ * byte sizes of the files that exist in the attempt workspace. This is the
+ * one quantity the controller can measure about a packet's reference load --
+ * the worker prompt lists readFiles and the worker reads them itself, so what
+ * it actually reads is the harness's business. A missing file counts 0 rather
+ * than throwing: a declared path can be produced by a dependency that has not
+ * run yet or removed by the tree since the packet was authored.
+ *
+ * @param {string[]} readFiles
+ * @param {string} workspace
+ * @returns {number}
+ */
+export function declaredReadBytes(readFiles, workspace) {
+  let total = 0;
+  for (const path of readFiles) {
+    try {
+      total += statSync(join(workspace, path)).size;
+    } catch {
+      // Missing or unreadable file: contributes no weight.
+    }
+  }
+  return total;
+}
 /**
  * The mechanical worker tool policy for the provider boundary: hook settings
  * on Claude-compatible commands. Only an adapter whose surface can prove
@@ -431,6 +455,7 @@ export function startWorker(contract, node, state, runDir, running, prompt, lock
   writeJsonAtomic(snapshotPath, baseline);
   state.phase = "worker";
   state.runtime = runtime;
+  state.declaredReadBytes = declaredReadBytes(node.taskPacket.readFiles ?? [], workspace);
   // A new worker attempt has no accepted result yet. The canonical result
   // file is cleared when the previous attempt was explicitly rejected (failed
   // gate verdict), when no valid canonical file exists, or when the stale file

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`;
 }
 /**

package/src/report/render.mjs

@@ -26,7 +26,7 @@ const POINTER_ATTENTION_CHARS = 80;
 /** @typedef {{costUsd: number|null, costProvenance: CostProvenance, inputTokens: number, outputTokens: number, cacheReadInputTokens: number, pricedInvocations: number, unpricedInvocations: number}} RoleUsage */
 /** @typedef {{inputTokens: number|null, outputTokens: number|null, cacheReadInputTokens: number|null}} StatusPayloadUsage */
 /** @typedef {{index: number, total: number, argv: string}} VerificationProgress */
-/** @typedef {{id: string, status: NodeStatus, phase: string|null, executionPhase: string|null, runtime: string|null, workerRuntime: string|null, continuation: string, attempt: number, revisions: number, startedAt: string|null, updatedAt: string|null, usage: StatusPayloadUsage|null, costUsd: number|null, verdict: string|null, pendingHandoff: {runtime: string, reason: string}|null, note: string|null, scopeFindings: string[]|null, errorCode: string|null, blockedBy: string[], verificationProgress: VerificationProgress|null}} StatusPayloadNode */
+/** @typedef {{id: string, status: NodeStatus, phase: string|null, executionPhase: string|null, runtime: string|null, workerRuntime: string|null, continuation: string, attempt: number, revisions: number, startedAt: string|null, updatedAt: string|null, usage: StatusPayloadUsage|null, costUsd: number|null, verdict: string|null, pendingHandoff: {runtime: string, reason: string}|null, note: string|null, scopeFindings: string[]|null, errorCode: string|null, blockedBy: string[], verificationProgress: VerificationProgress|null, declaredReadBytes: number|null}} StatusPayloadNode */
 /** @typedef {{schemaVersion: 1, run: string, contractId: string, campaignId: string, goal: string, usage: {inputTokens: number, outputTokens: number, cacheReadInputTokens: number, costUsd: number|null}, roles: {worker: RoleUsage, judge: RoleUsage}, controller: JsonObject, identityWarnings: string[], summary: string, nodes: StatusPayloadNode[]}} StatusPayload */
 
 /** The glyph each terminal state prints in a status table. */
@@ -92,7 +92,8 @@ export function renderStatus(runDir) {
       node.note ?? "-",
     ]));
   }
-  lines.push("```", "", "## Cost", "", `in ${compactTokens(usage.inputTokens)} · out ${compactTokens(usage.outputTokens)} · cache ${compactTokens(usage.cacheReadInputTokens)} · worker ${formatRole(payload.roles.worker)} · judge ${formatRole(payload.roles.judge)} · cost ${compactCost(usage.costUsd)}`);
+  const readBytes = payload.nodes.reduce((total, node) => total + (node.declaredReadBytes ?? 0), 0);
+  lines.push("```", "", "## Cost", "", `in ${compactTokens(usage.inputTokens)} · out ${compactTokens(usage.outputTokens)} · cache ${compactTokens(usage.cacheReadInputTokens)} · worker ${formatRole(payload.roles.worker)} · judge ${formatRole(payload.roles.judge)} · cost ${compactCost(usage.costUsd)} · read ${compactTokens(readBytes)}`);
   return `${lines.join("\n")}\n`;
 }
 
@@ -232,6 +233,7 @@ function buildStatusPayload(runDir, contract, nodes, identityWarnings, usage) {
         errorCode: node.error?.code ?? null,
         blockedBy: node.blockedBy ?? [],
         verificationProgress: progress,
+        declaredReadBytes: typeof node.declaredReadBytes === "number" ? node.declaredReadBytes : null,
       };
     }),
   };
@@ -407,13 +409,14 @@ export function renderReportJson(runDir) {
   const { contract, nodes } = loadRun(runDir);
   const counts = new Map();
   for (const node of nodes) counts.set(node.status, (counts.get(node.status) ?? 0) + 1);
-  /** @type {{inputTokens: number, outputTokens: number, cacheReadInputTokens: number, costUsd: number|null, costStatus: string, workerCostUsd: number|null, judgeCostUsd: number|null}} */
-  const totals = { inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0, costUsd: null, costStatus: "ambiguous", workerCostUsd: null, judgeCostUsd: null };
+  /** @type {{inputTokens: number, outputTokens: number, cacheReadInputTokens: number, costUsd: number|null, costStatus: string, workerCostUsd: number|null, judgeCostUsd: number|null, declaredReadBytes: number}} */
+  const totals = { inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0, costUsd: null, costStatus: "ambiguous", workerCostUsd: null, judgeCostUsd: null, declaredReadBytes: 0 };
   const costs = nodes.map(costProjection);
   const listed = nodes.map((node, index) => {
     const usage = node.usage ?? { inputTokens: null, outputTokens: null, cacheReadInputTokens: null };
     for (const key of /** @type {("inputTokens"|"outputTokens"|"cacheReadInputTokens")[]} */ (["inputTokens", "outputTokens", "cacheReadInputTokens"])) totals[key] = (totals[key] ?? 0) + (usage[key] ?? 0);
     const cost = costs[index];
+    totals.declaredReadBytes += typeof node.declaredReadBytes === "number" ? node.declaredReadBytes : 0;
     return {
       id: node.id,
       status: node.status,
@@ -427,6 +430,7 @@ export function renderReportJson(runDir) {
       costStatus: cost.status,
       continuation: continuationMode(node),
       note: nodeNote(node),
+      declaredReadBytes: typeof node.declaredReadBytes === "number" ? node.declaredReadBytes : null,
     };
   });
   const aggregateCost = aggregateCostProjection(costs);