faberun 0.30.0 → 0.31.0

package/src/harnesses/session-metrics.mjs

@@ -11,7 +11,14 @@
 import { canonicalUsage, eventItem, extractJson } from "./protocol.mjs";
 import { finite } from "../util.mjs";
 
-/** @typedef {{turns: number, cacheReadInputTokens: number, toolCalls: number, completed: boolean, requests: number, contextFirst: number|null, contextMax: number|null, contextLast: number|null, contextSum: number}} SessionTotals */
+/** @typedef {{turns: number, cacheReadInputTokens: number, cacheWriteInputTokens: number|null, outputTokens: number|null, toolCalls: number, completed: boolean, requests: number, contextFirst: number|null, contextMax: number|null, contextLast: number|null, contextSum: number}} SessionTotals */
+/**
+ * The five measured counters one invocation proves, mapped from the
+ * harness-reported session usage. `bytes` is never stream-derived -- the
+ * ledger measures the dispatched prompt file -- so it is always null here;
+ * a counter the harness never reported stays null, never a plausible zero.
+ * @typedef {{bytes: number|null, inputTokens: number|null, cacheReadInputTokens: number|null, cacheWriteInputTokens: number|null, outputTokens: number|null}} UsageCounters
+ */
 /**
  * The per-request ledger one transcript proves: provider requests that
  * reported usage, and the context each re-sent -- uncached input (cache
@@ -155,6 +162,34 @@ function sumRequestUsage(usages) {
   return inputTokens === null ? { inputTokens: null, cacheReadInputTokens: null } : { inputTokens, cacheReadInputTokens };
 }
 
+/** Sum two counters of which either may be unmeasured; null only when neither measured. @param {number|null} left @param {number|null} right @returns {number|null} */
+export function addMeasured(left, right) {
+  return left === null && right === null ? null : (left ?? 0) + (right ?? 0);
+}
+
+/**
+ * The five usage counters one bounded transcript proves: uncached input and
+ * cache reads from the observation the live meter reads, cache writes and
+ * output from the session totals the parser folds.
+ *
+ * @param {string} harness
+ * @param {string} stdout bounded transcript tail
+ * @returns {UsageCounters}
+ */
+export function liveUsageCounters(harness, stdout) {
+  const parser = new SessionMetricsParser(harness);
+  parser.push(String(stdout));
+  parser.flush();
+  const usage = liveUsage(harness, stdout);
+  return {
+    bytes: null,
+    inputTokens: usage.inputTokens,
+    cacheReadInputTokens: usage.cacheReadInputTokens,
+    cacheWriteInputTokens: parser.totals.cacheWriteInputTokens,
+    outputTokens: parser.totals.outputTokens,
+  };
+}
+
 /**
  * Budgeted live meter: one number, with cache reads weighted by the campaign
  * policy so it is comparable with the persisted ledger. A provider that only
@@ -221,6 +256,9 @@ const TOOL_USE_NEEDLE = Buffer.from('"type":"tool_use"', "utf8");
 /** Cache-read evidence spellings across harness streams. */
 const CACHE_READ_PATTERN = /"(?:cache_read_input_tokens|cached_input_tokens|cacheReadInputTokens)":(\d+)/gu;
 
+/** Cache-write evidence spellings across harness streams. */
+const CACHE_WRITE_PATTERN = /"(?:cache_creation_input_tokens|cacheWriteInputTokens|cache_write_input_tokens|cache_creation_tokens|cache_write_tokens)":(\d+)/gu;
+
 /**
  * Bounded incremental session-metrics parser: fold fixed-size chunks into
  * running rotation totals without ever holding a buffer that scales with the
@@ -240,6 +278,8 @@ export class SessionMetricsParser {
     this.totals = {
       turns: previous.turns ?? 0,
       cacheReadInputTokens: previous.cacheReadInputTokens ?? 0,
+      cacheWriteInputTokens: null,
+      outputTokens: null,
       toolCalls: previous.toolCalls ?? 0,
       completed: previous.completed === true,
       requests: 0,
@@ -455,7 +495,11 @@ function foldRecord(harness, totals, record) {
   if (harness === "codex") {
     if (record.type === "turn.completed") {
       totals.turns += 1;
-      totals.cacheReadInputTokens = Math.max(totals.cacheReadInputTokens, canonicalUsage(record.usage).cacheReadInputTokens ?? 0);
+      const usage = canonicalUsage(record.usage);
+      totals.cacheReadInputTokens = Math.max(totals.cacheReadInputTokens, usage.cacheReadInputTokens ?? 0);
+      // Codex counts input and output cumulatively per turn; it reports no
+      // cache-write counter at all, so the write total stays unmeasured.
+      if (usage.outputTokens !== null) totals.outputTokens = Math.max(totals.outputTokens ?? 0, usage.outputTokens);
     } else if (record.type === "item.completed" && CODEX_TOOL_ITEM_TYPES.has(String(eventItem(record)?.type))) {
       totals.toolCalls += 1;
     }
@@ -465,14 +509,16 @@ function foldRecord(harness, totals, record) {
     if (record.type === "assistant") {
       const message = /** @type {Record<string, unknown>} */ (record.message ?? {});
       totals.turns += 1;
-      totals.cacheReadInputTokens += canonicalUsage(message.usage).cacheReadInputTokens ?? 0;
-      foldRequestUsage(totals, canonicalUsage(message.usage));
+      const usage = canonicalUsage(message.usage);
+      totals.cacheReadInputTokens += usage.cacheReadInputTokens ?? 0;
+      totals.cacheWriteInputTokens = addMeasured(totals.cacheWriteInputTokens, cacheWriteTokensOf(message.usage));
+      totals.outputTokens = addMeasured(totals.outputTokens, usage.outputTokens);
+      foldRequestUsage(totals, usage);
       totals.toolCalls += Array.isArray(message.content)
         ? message.content.filter((/** @type {{type?: unknown}} */ block) => block?.type === "tool_use").length
         : 0;
     } else if (record.type === "result") {
-      const sessionTotal = canonicalUsage(record.usage).cacheReadInputTokens;
-      if (sessionTotal !== null) totals.cacheReadInputTokens = sessionTotal;
+      foldSessionTotal(totals, record.usage);
     }
     return;
   }
@@ -487,13 +533,15 @@ function foldRecord(harness, totals, record) {
     // activity -- three kills on 2026-09-16 at 903s against a 900s limit.
     if (record.type === transcript.usage) {
       totals.turns += 1;
-      totals.cacheReadInputTokens += canonicalUsage(record.usage).cacheReadInputTokens ?? 0;
-      foldRequestUsage(totals, canonicalUsage(record.usage));
+      const usage = canonicalUsage(record.usage);
+      totals.cacheReadInputTokens += usage.cacheReadInputTokens ?? 0;
+      totals.cacheWriteInputTokens = addMeasured(totals.cacheWriteInputTokens, cacheWriteTokensOf(record.usage));
+      totals.outputTokens = addMeasured(totals.outputTokens, usage.outputTokens);
+      foldRequestUsage(totals, usage);
     } else if (record.type === transcript.tool) {
       totals.toolCalls += 1;
     } else if (record.type === transcript.completed || record.type === transcript.failed) {
-      const sessionTotal = canonicalUsage(record.usage).cacheReadInputTokens;
-      if (sessionTotal !== null) totals.cacheReadInputTokens = sessionTotal;
+      foldSessionTotal(totals, record.usage);
     }
     return;
   }
@@ -507,32 +555,57 @@ function foldRecord(harness, totals, record) {
     if (step) {
       if (step.step_type === "agent_response" && step.state === "DONE") {
         totals.turns += 1;
-        totals.cacheReadInputTokens += canonicalUsage(step.usage).cacheReadInputTokens ?? 0;
-        foldRequestUsage(totals, canonicalUsage(step.usage));
+        const usage = canonicalUsage(step.usage);
+        totals.cacheReadInputTokens += usage.cacheReadInputTokens ?? 0;
+        totals.cacheWriteInputTokens = addMeasured(totals.cacheWriteInputTokens, cacheWriteTokensOf(step.usage));
+        totals.outputTokens = addMeasured(totals.outputTokens, usage.outputTokens);
+        foldRequestUsage(totals, usage);
       } else if (step.step_type === "tool" && (step.state === "DONE" || step.state === "ERROR")) {
         totals.toolCalls += 1;
       }
     } else if (record.event === "result") {
-      const sessionTotal = canonicalUsage(agyResult(record)?.usage).cacheReadInputTokens;
-      if (sessionTotal !== null) totals.cacheReadInputTokens = sessionTotal;
+      foldSessionTotal(totals, agyResult(record)?.usage);
     }
     return;
   }
   if (harness === "exec-jsonl" && record.type === "run.completed") {
     // The protocol carries no tool events; only a completed run proves a turn.
     totals.turns += 1;
-    totals.cacheReadInputTokens += canonicalUsage(record.usage).cacheReadInputTokens ?? 0;
-    foldRequestUsage(totals, canonicalUsage(record.usage));
+    const usage = canonicalUsage(record.usage);
+    totals.cacheReadInputTokens += usage.cacheReadInputTokens ?? 0;
+    totals.cacheWriteInputTokens = addMeasured(totals.cacheWriteInputTokens, cacheWriteTokensOf(record.usage));
+    totals.outputTokens = addMeasured(totals.outputTokens, usage.outputTokens);
+    foldRequestUsage(totals, usage);
   }
   if (harness === "replay" && typeof record.status === "string") {
     // A replayed envelope is the whole invocation: one completed turn, no
     // tool events, usage only in the terminal record.
     totals.turns += 1;
-    totals.cacheReadInputTokens += canonicalUsage(record.usage).cacheReadInputTokens ?? 0;
-    foldRequestUsage(totals, canonicalUsage(record.usage));
+    const usage = canonicalUsage(record.usage);
+    totals.cacheReadInputTokens += usage.cacheReadInputTokens ?? 0;
+    totals.cacheWriteInputTokens = addMeasured(totals.cacheWriteInputTokens, cacheWriteTokensOf(record.usage));
+    totals.outputTokens = addMeasured(totals.outputTokens, usage.outputTokens);
+    foldRequestUsage(totals, usage);
   }
 }
 
+/** Fold a terminal record's session totals over the mid-run sums; an unreported total leaves the running sum alone. @param {SessionTotals} totals @param {unknown} raw */
+function foldSessionTotal(totals, raw) {
+  const usage = canonicalUsage(raw);
+  if (usage.cacheReadInputTokens !== null) totals.cacheReadInputTokens = usage.cacheReadInputTokens;
+  const writeTotal = cacheWriteTokensOf(raw);
+  if (writeTotal !== null) totals.cacheWriteInputTokens = writeTotal;
+  if (usage.outputTokens !== null) totals.outputTokens = usage.outputTokens;
+}
+
+/** The cache-write tokens one raw usage object reports, across the harness spellings; null when none. @param {unknown} raw @returns {number|null} */
+function cacheWriteTokensOf(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const usage = /** @type {Record<string, unknown>} */ (raw);
+  return finite(usage.cache_creation_input_tokens ?? usage.cacheWriteInputTokens
+    ?? usage.cache_write_input_tokens ?? usage.cache_creation_tokens ?? usage.cache_write_tokens);
+}
+
 /**
  * Fold one provider request's usage into the per-request ledger. A request
  * with no measured input is not one the ledger can count.
@@ -575,15 +648,21 @@ function agyResult(record) {
  */
 function foldFragmentRecord(harness, totals, fragments) {
   const text = `${fragments.head}\n${fragments.tail}`;
+  // Output tokens have no fragment scanner: a record that outgrew the
+  // retention bound leaves the output total unmeasured rather than guessed.
   if (harness === "claude") {
     if (text.includes('"type":"assistant"')) {
       totals.turns += 1;
       totals.toolCalls += fragments.toolUse;
       const cacheRead = lastCacheRead(text);
       if (cacheRead !== null) totals.cacheReadInputTokens += cacheRead;
+      const cacheWrite = lastCacheWrite(text);
+      if (cacheWrite !== null) totals.cacheWriteInputTokens = addMeasured(totals.cacheWriteInputTokens, cacheWrite);
     } else if (text.includes('"type":"result"')) {
-      const sessionTotal = lastCacheRead(text);
-      if (sessionTotal !== null) totals.cacheReadInputTokens = sessionTotal;
+      const cacheRead = lastCacheRead(text);
+      if (cacheRead !== null) totals.cacheReadInputTokens = cacheRead;
+      const cacheWrite = lastCacheWrite(text);
+      if (cacheWrite !== null) totals.cacheWriteInputTokens = cacheWrite;
       totals.completed = true;
     }
     return;
@@ -607,6 +686,8 @@ function foldFragmentRecord(harness, totals, fragments) {
     totals.turns += 1;
     const cacheRead = lastCacheRead(text);
     if (cacheRead !== null) totals.cacheReadInputTokens += cacheRead;
+    const cacheWrite = lastCacheWrite(text);
+    if (cacheWrite !== null) totals.cacheWriteInputTokens = addMeasured(totals.cacheWriteInputTokens, cacheWrite);
     totals.completed = true;
   }
 }
@@ -697,3 +778,14 @@ function lastCacheRead(text) {
   const matches = [...text.matchAll(CACHE_READ_PATTERN)];
   return matches.length > 0 ? Number(matches.at(-1)?.[1]) : null;
 }
+
+/**
+ * The last cache-write number in a fragment text, or null.
+ *
+ * @param {string} text
+ * @returns {number|null}
+ */
+function lastCacheWrite(text) {
+  const matches = [...text.matchAll(CACHE_WRITE_PATTERN)];
+  return matches.length > 0 ? Number(matches.at(-1)?.[1]) : null;
+}

package/src/notify/index.mjs

@@ -17,6 +17,18 @@
  * fallback. The macOS notifier is reachable only by setting
  * `FABERUN_NOTIFY_BIN=os-macos`, an explicit opt-in, never a default.
  *
+ * A transport may also answer with a receipt: the last line it prints, as
+ * JSON carrying the `messageId` it created or edited. The campaign watcher's
+ * automatic progress update is the consumer -- its text is rendered from the
+ * shared projection (`buildCampaignProgress`), never a model, and when a
+ * previous progress message of the same campaign is still inside the
+ * fifteen-minute window (`progressEditTarget`) the update travels as an edit
+ * of that message. The anchor naming the editable message is written only
+ * after the transport's receipt returns, so a delivery is claimed only on
+ * evidence; a transport that prints no receipt simply always gets a new
+ * message. An attention event never consults the anchor: it is always a new
+ * message.
+ *
  * 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
@@ -92,7 +104,7 @@ export const NOTIFY_LANG_ENV = "FABERUN_NOTIFY_LANG";
 export const NOTIFY_ENV_NAMES = Object.freeze([NOTIFY_BIN_ENV, NOTIFY_SESSION_ENV, NOTIFY_EVENTS_ENV, NOTIFY_LANG_ENV]);
 
 /** Every event type the dispatcher can be asked to deliver. */
-export const NOTIFY_EVENT_TYPES = Object.freeze(["node.terminal", "run.terminal", "attention", "advisory"]);
+export const NOTIFY_EVENT_TYPES = Object.freeze(["node.terminal", "run.terminal", "attention", "advisory", "progress"]);
 
 /**
  * What leaves the controller when `FABERUN_NOTIFY_EVENTS` is unset: a phase
@@ -107,6 +119,30 @@ export const NOTIFY_EVENT_TYPES = Object.freeze(["node.terminal", "run.terminal"
  */
 export const DEFAULT_NOTIFY_EVENTS = Object.freeze(["run.terminal", "attention", "advisory"]);
 
+/**
+ * How long a delivered progress message stays editable, from the phase spec's
+ * constraint: a progress message of the same campaign inside this window is
+ * edited in place, an event that demands attention is always a new message.
+ */
+export const PROGRESS_EDIT_WINDOW_MS = 15 * 60_000;
+
+/**
+ * The message id an automatic progress update may edit, from the receipt-
+ * backed anchor of the last one: an anchor inside the window names its
+ * message; an expired, foreign, malformed or absent one edits nothing and the
+ * next update is a new message. An attention event never consults this --
+ * attention is always a new message.
+ *
+ * @param {{messageId: string, at: number}|null} anchor the anchor the last receipt wrote
+ * @param {number} nowMs epoch milliseconds
+ * @returns {string|null}
+ */
+export function progressEditTarget(anchor, nowMs) {
+  if (!anchor || typeof anchor.messageId !== "string" || !anchor.messageId) return null;
+  if (typeof anchor.at !== "number" || !Number.isFinite(anchor.at)) return null;
+  return nowMs - anchor.at < PROGRESS_EDIT_WINDOW_MS ? anchor.messageId : null;
+}
+
 /** The two languages the message renders its wording in; `FABERUN_NOTIFY_LANG` may name either. */
 export const NOTIFY_LANGUAGES = Object.freeze(["en", "pt"]);
 
@@ -209,9 +245,9 @@ export const NOTIFY_NO_TRANSPORT_WARNING = "no human notification transport is c
 /** @typedef {Record<string, unknown>} JsonObject */
 /** @typedef {{schemaVersion: number, eventId: string, at: string, type: string, campaignId: string|null, runId: string|null, nodeId: string|null, status: string|null, errorCode: string|null, dedupeKey: string, summary: string}} InboxEntry */
 /** @typedef {{type: string, dedupeKey: string, summary: string, at?: string, campaignId?: string|null, runId?: string|null, nodeId?: string|null, status?: string|null, errorCode?: string|null}} InboxEvent */
-/** @typedef {{type: "node.terminal"|"run.terminal"|"attention"|"advisory", runId: string|null, campaignId?: string|null, nodeId?: string|null, status?: string|null, attempt?: number|null, errorCode?: string|null, done?: number|null, total?: number|null, dedupeKey?: string|null, runDir?: string|null, costUsd?: number|null, summary?: string|null, eventId?: string}} NotifyEvent */
-/** @typedef {{id: string, ok: boolean, error?: string}} TransportOutcome one transport's own outcome, named so the receipt says which took the message */
-/** @typedef {{ok: boolean, error?: string, noTransport?: boolean, transports?: TransportOutcome[]}} DeliveryResult */
+/** @typedef {{type: "node.terminal"|"run.terminal"|"attention"|"advisory"|"progress", runId: string|null, campaignId?: string|null, nodeId?: string|null, status?: string|null, attempt?: number|null, errorCode?: string|null, done?: number|null, total?: number|null, dedupeKey?: string|null, runDir?: string|null, costUsd?: number|null, summary?: string|null, eventId?: string, editOfMessageId?: string|null}} NotifyEvent */
+/** @typedef {{id: string, ok: boolean, error?: string, messageId?: string}} TransportOutcome one transport's own outcome, named so the receipt says which took the message; `messageId` is the id a transport receipt named for the message it created or edited */
+/** @typedef {{ok: boolean, error?: string, noTransport?: boolean, messageId?: string, transports?: TransportOutcome[]}} DeliveryResult */
 
 /**
  * Render the message for an event. For `node.terminal`, `run.terminal` and
@@ -219,7 +255,10 @@ export const NOTIFY_NO_TRANSPORT_WARNING = "no human notification transport is c
  * own persisted state (its contract, its node snapshots, its usage) from
  * `event.runDir` -- so whatever calls this function once gets exactly the
  * string every audience of that event sees: the inbox entry's `summary` and
- * the transport's stdin are never rendered separately and never drift.
+ * the transport's stdin are never rendered separately and never drift. A
+ * `progress` event is never rendered here: the campaign watcher renders it
+ * from the shared projection and passes it pre-rendered, so a progress event
+ * without a summary is a caller bug and throws.
  *
  * `runDir` is absent, or names a directory with no readable run scaffold
  * (no `contract.json`, no `run.json`, a node snapshot that fails validation),
@@ -438,13 +477,16 @@ export function appendInbox(runsDir, event) {
  * text. The result is `ok` when any one of them took the message, carries
  * every transport's own outcome for the receipt, and is
  * `{ok: false, noTransport: true}` when nothing at all is bound -- without
- * spawning or connecting anything.
+ * spawning or connecting anything. When a transport answered with a receipt
+ * naming the message it created or edited, that id is surfaced as `messageId`
+ * so the caller can claim exactly what the transport acknowledged -- never
+ * more.
  *
  * @param {{type: string, summary: string, campaignId?: string|null, [key: string]: unknown}} event
  * @param {{bin?: string, env?: NodeJS.ProcessEnv, spawn?: typeof defaultSpawn, timeoutMs?: number}} [options]
  * @returns {Promise<DeliveryResult>}
  */
-async function deliverNotification(event, options = {}) {
+export async function deliverNotification(event, options = {}) {
   const env = options.env ?? process.env;
   const bin = options.bin ?? env[NOTIFY_BIN_ENV];
   const targets = resolveSessionTargets(env);
@@ -461,20 +503,50 @@ async function deliverNotification(event, options = {}) {
   if (!attempts.length && !targets.length) return { ok: false, noTransport: true, transports: [] };
   const transports = [...(await Promise.all(attempts)), ...(await sessions)];
   const failures = transports.filter((outcome) => !outcome.ok).map((outcome) => `${outcome.id}: ${outcome.error ?? "failed"}`);
+  const messageId = transports.map((outcome) => outcome.messageId).find((id) => typeof id === "string" && id !== "");
   return {
     ok: transports.some((outcome) => outcome.ok),
+    ...(messageId ? { messageId } : {}),
     ...(failures.length ? { error: failures.join("; ") } : {}),
     transports,
   };
 }
 
+/**
+ * The transport's delivery receipt, read from the last non-empty line it
+ * printed: a JSON object whose `messageId` names the message it created or
+ * edited. A transport that prints nothing else, prints non-JSON, or exits
+ * non-zero yields no receipt, and the caller claims no editable message from
+ * it.
+ *
+ * @param {string} stdout
+ * @returns {{messageId?: string}}
+ */
+function transportReceipt(stdout) {
+  const lines = stdout.split("\n");
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const trimmed = lines[index].trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      const messageId = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed.messageId : undefined;
+      return typeof messageId === "string" && messageId ? { messageId } : {};
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+
 /**
  * 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.
+ * already-exited delivery until the timeout fired. A zero exit is the
+ * delivery; whatever the transport printed on stdout is its receipt, read
+ * by `transportReceipt`.
  *
  * @param {string} bin
  * @param {JsonObject} event
@@ -490,7 +562,7 @@ function spawnDeliver(bin, event, { spawn = defaultSpawn, timeoutMs = notificati
       // names its interpreter. Either spawns as EFTYPE unhandled, which is a
       // notification that silently never arrives.
       const invocation = spawnInvocation(bin, []);
-      child = spawn(invocation.command, invocation.args, { stdio: ["pipe", "ignore", "pipe"], env: process.env, ...invocation.options });
+      child = spawn(invocation.command, invocation.args, { stdio: ["pipe", "pipe", "pipe"], env: process.env, ...invocation.options });
     } catch (error) {
       resolveDelivery({ ok: false, error: errorMessage(error) });
       return;
@@ -504,11 +576,15 @@ function spawnDeliver(bin, event, { spawn = defaultSpawn, timeoutMs = notificati
       resolveDelivery(result);
     };
     let stderr = "";
+    let stdout = "";
     child.stderr?.on("data", (chunk) => {
       stderr = `${stderr}${chunk}`.slice(-1024);
     });
+    child.stdout?.on("data", (chunk) => {
+      stdout = `${stdout}${chunk}`.slice(-2048);
+    });
     child.once("error", (error) => finish({ ok: false, error: errorMessage(error) }));
-    child.once("exit", (code) => finish(code === 0 ? { ok: true } : { ok: false, error: stderr || `notification exited ${code}` }));
+    child.once("exit", (code) => finish(code === 0 ? { ok: true, ...transportReceipt(stdout) } : { ok: false, error: stderr || `notification exited ${code}` }));
     const timer = setTimeout(() => {
       try {
         child.kill("SIGTERM");

package/src/plan/freeze.mjs

@@ -35,7 +35,8 @@ import { NODE_VALUE_OPTIONS, assertFilteredProofsNameTheirTest } from "./proof-s
 /** @typedef {{path: string, digest: string}} PlanSpecIdentity */
 /** @typedef {{formatVersion: number, contractDigest: string, spec?: PlanSpecIdentity, phases?: PlanPhase[], humanSteps?: PlanHumanStep[], provenance: PlanProvenance}} FrozenPlan */
 /** @typedef {{ok: boolean, digest: string, expectedDigest: string}} FrozenPlanVerdict */
-/** @typedef {{scripts?: Record<string, string>, verificationCandidates: {argv: string[], measuredMs: number}[]}} MeasuredFacts */
+/** @typedef {{argv: string[], measuredMs: number|null, eligible: boolean}} MeasuredCandidate */
+/** @typedef {{scripts?: Record<string, string>, verificationCandidates: MeasuredCandidate[]}} MeasuredFacts */
 
 const PLAN_FORMAT_VERSION = 1;
 
@@ -74,13 +75,17 @@ function includedDirectories(arg, directories) {
  * the sum of the `node --test <dir>` candidates it includes, `npm test`
  * resolved through the `test` script. A lower bound when the command also
  * runs files no candidate measured; null when it includes nothing measured.
+ * Only an eligible candidate with a numeric duration counts, exact or
+ * aggregated: a candidate killed at its timeout persists measuredMs null
+ * with eligible false, so neither an exact read nor a directory sum may
+ * plan from it.
  *
  * @param {string[]} argv
  * @param {MeasuredFacts} facts
  * @returns {number|null}
  */
 function measuredMsFor(argv, facts) {
-  const candidates = facts.verificationCandidates;
+  const candidates = facts.verificationCandidates.filter((candidate) => candidate.eligible === true && typeof candidate.measuredMs === "number");
   const exact = candidates.find((candidate) => candidate.argv.join(" ") === argv.join(" "));
   if (exact) return exact.measuredMs;
   const npmTest = argv[0] === "npm" && ["test", "run test"].includes(argv.slice(1).join(" "));

package/src/plan/human-step.mjs

@@ -5,6 +5,16 @@
  * freeze.mjs can carry it on the frozen plan as an explicit stop, and the
  * Campaign Brief can list it among the human decisions. Pure text matching:
  * no file I/O, no git, no model.
+ *
+ * The same module owns the other thing only an operator can do, because it
+ * is the same boundary at a different source: a packet refusal the failure
+ * classifier named `ambiguous_requirement` (R5, campaign-efficiency phase 4)
+ * is not repairable by widening the packet — the requirement itself can be
+ * read more than one way — so it becomes a durable question
+ * (`durableQuestion`) the run carries until `resume --answer <node>` closes
+ * it, instead of another widening attempt. The source is the run's failure
+ * journal, not the spec's constraints; the discipline is unchanged: pure
+ * record shaping, no file I/O, no git, no model.
  */
 
 /** @typedef {{requirementId: string, step: string, command: string}} HumanStep */
@@ -36,3 +46,29 @@ export function collectHumanSteps(requirements) {
     .map((requirement) => detectHumanStep(requirement))
     .filter((step) => step !== null);
 }
+
+/** @typedef {{node: string, artifactVersion: string, question: string}} DurableQuestion */
+
+/**
+ * The durable question an ambiguous-requirement refusal becomes. Null for
+ * every other cause: a read or write gap is the packet's own defect and a
+ * widening round can repair it, but an ambiguity is a property of the
+ * requirement the packet was written from, and no widening of read or write
+ * scope can answer it — another attempt would re-read the same prose.
+ *
+ * The question names the node and the packet version it refuses so the
+ * operator's answer is bound to the same key the failure journal uses: a
+ * widened packet changes the version, and with it the question.
+ *
+ * @param {{cause: string, node: string, artifactVersion: string}} record a
+ *   failureCause record as the reauthor journal writes it
+ * @returns {DurableQuestion|null}
+ */
+export function durableQuestion(record) {
+  if (record.cause !== "ambiguous_requirement") return null;
+  return {
+    node: record.node,
+    artifactVersion: record.artifactVersion,
+    question: `Node ${record.node} refused its packet at ${record.artifactVersion} with cause ambiguous_requirement: the requirement can be read more than one way, and no widening of the packet can answer it. Decide what the requirement means, then resume with --answer ${record.node}; no reauthor round and no further attempt runs on this packet version until then.`,
+  };
+}

package/src/plan/pipeline.mjs

@@ -25,13 +25,12 @@ import { readCampaign } from "../campaign/record.mjs";
 import { campaignCli } from "../cli/campaign.mjs";
 import { appendJsonl } from "../run/store.mjs";
 import { allowanceDelta, allowanceEventFields, sampleAllowance } from "../seat/allowance.mjs";
-import { askPlanningRuntimes, refusePlanningSilence, refuseUnplannableRuntimes } from "./preflight.mjs";
+import { askPlanningRuntimes, checkPlanBeforeReview, refusePlanningSilence, refuseUnplannableRuntimes } from "./preflight.mjs";
 import { validateJudgeIndependence } from "../contract/judge-independence.mjs";
 import { firstEligibleReviewer, reviewerProvenanceOf } from "./reviewer.mjs";
 import { parseSpec, validateSpec } from "./spec.mjs";
-import { collectRepoFacts } from "./repo-facts.mjs";
-import { clearPlanProgress, writePlanProgress } from "./progress.mjs";
-import { checkPlanProofs } from "./proof-check.mjs";
+import { collectRepoFacts, persistRepoFacts } from "./repo-facts.mjs";
+import { abandonedPlanProgress, clearPlanProgress, startDraftPlan, writePlanDraftRecord, writePlanProgress } from "./progress.mjs";
 import { collectHumanSteps } from "./human-step.mjs";
 import { RISK_TIERS, TASK_KIND_CATALOGUE_FILE, buildPlanningContract, renderTaskKindCatalogue, validatePlanOutput } from "./template.mjs";
 import { MIN_WRITE_FILES, applySizingRules, provenParallelism } from "./sizing.mjs";
@@ -159,6 +158,12 @@ async function runPlanningStages(options) {
   // the home, and the scratch relay inside the repository is excluded by the
   // same pathspec the launch uses.
   assertLaunchBaseClean(cwd, undefined);
+  // The refusal half of the pre-flight, decided from the catalogue and the
+  // machine alone and returned before anything is dispatched, so a runtime
+  // choice no frozen contract could carry costs no model call: it runs before
+  // the liveness ask below because that ask is itself a provider invocation,
+  // and everything a plan can still get wrong is a finding for the repair
+  // loop rather than a refusal.
   refuseUnplannableRuntimes(runtimes, runtimeDefaults, packageMode, judgeIndependence);
   refusePlanningSilence(await ask(runtimes, runtimeDefaults, cwd), cwd);
 
@@ -202,6 +207,8 @@ async function runPlanningStages(options) {
   // the draft stage reads what the planner measured instead of inferring it
   // from the spec's prose.
   const parsedSpec = parseSpec(specText);
+  // Sampled before this pipeline's own first liveness write (repo facts) overwrites it.
+  const abandoned = abandonedPlanProgress(cwd, campaignId, phase);
   // This stage holds the terminal for minutes, which is why it says what it is
   // about to do before it does it and one line per command as each finishes.
   // Measured 2026-09-25/26 (AP3): five to eight minutes with nothing written
@@ -217,8 +224,12 @@ async function runPlanningStages(options) {
   // here so both the freeze below and a caller inspecting the pipeline agree
   // on the same list.
   const humanSteps = collectHumanSteps(parsedSpec.requirements);
-  const repoFactsPath = join(scratchDir, "repo-facts.json");
-  writeFileSync(repoFactsPath, `${JSON.stringify(repoFacts, null, 2)}\n`);
+  // The draft and review stages read the cut through `readFiles`, and the
+  // complete path index is staged beside it rather than inside it: the
+  // artefact stays byte-bounded, and a discovery node explicitly authorised to
+  // enumerate the tree is handed `repo-paths.txt` instead of a cut that lies
+  // about what the tree holds (R4).
+  const repoFactsPath = persistRepoFacts(scratchDir, repoFacts, cwd);
   const relativeRepoFactsPath = relative(cwd, repoFactsPath);
   // The taskKind catalogue is staged like every other planning input. It used
   // to be handed over as faberun's own `src/plan/template.mjs`, which resolves
@@ -278,7 +289,13 @@ async function runPlanningStages(options) {
     return { contract: validated, output };
   };
 
-  const draft = await runStage("draft", { specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath, cataloguePath: relativeCataloguePath, packageMode });
+  // R2 resume: the sampled record survives only a process that died, and a
+  // dead attempt that validated its draft left writePlanDraftRecord's file
+  // behind. A finished phase — frozen or contested — has a plan.json, and that drafts fresh.
+  const draft = await startDraftPlan({
+    abandoned, plansDir, specDigest, runStage, logStage,
+    draftStageInput: { specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath, cataloguePath: relativeCataloguePath, packageMode },
+  });
   /** @type {PlanOutput|null} */
   let plan = null;
   // Everything still open against the plan in hand, accumulated across rounds
@@ -288,23 +305,16 @@ async function runPlanningStages(options) {
   /** @type {PlanFindingOutput[]} */
   let findings = [];
   try {
-    plan = validatePlanOutput(draft.output.plan);
+    plan = validatePlanOutput(draft.planOutput);
   } catch (error) {
     findings = [invalidPlanFinding("draft", error)];
   }
-  logStage("draft", plan === null
-    ? { runId: draft.contract.id, invalid: findings[0].text }
-    : { runId: draft.contract.id, nodeCount: plan.nodes.length });
-
-  // R15: a deterministic check for a DoD proof no node can satisfy, run once
-  // against the drafted plan before the first review round grades it — a
-  // finding this raises is exactly as actionable to a revise as a reviewer's
-  // own, and raising it before review means review never spends a round
-  // re-discovering what a mechanical check already knows for certain.
-  if (plan !== null) {
-    const proofFindings = checkPlanProofs(plan, repoFacts, cwd);
-    if (proofFindings.length > 0) findings = [...findings, ...proofFindings];
-    logStage("proof-check", { findingsCount: proofFindings.length });
+  if (!draft.resumed) {
+    // Durable before its stage line: a death in between leaves an adoptable draft.
+    if (plan !== null) writePlanDraftRecord(plansDir, { runId: draft.runId, at: new Date().toISOString(), specDigest, plan });
+    logStage("draft", plan === null
+      ? { runId: draft.runId, invalid: findings[0].text }
+      : { runId: draft.runId, nodeCount: plan.nodes.length });
   }
 
   const workingPlanPath = join(scratchDir, "plan.working.json");
@@ -364,8 +374,29 @@ async function runPlanningStages(options) {
    */
   const frozenContractRaw = (assembly) => frozenContractRawOf(assembly, { campaignId, phase, campaignGoal: campaign.goal, cwd, plansDir, runtimes, runtimeDefaults, judgeIndependence });
 
+  // R5: the complete deterministic check set — the freeze rules `freeze.mjs`
+  // and `proof-scope.mjs` apply, plus the plan-wide proof scan (R15) — runs
+  // here, before the first semantic review is dispatched, and its diagnostics
+  // are forwarded into the round loop as findings: a mechanical objection is
+  // then answered by the same revise a reviewer's objection is, inside the
+  // rounds `--review-rounds` already pays for, never by a refusal path of its
+  // own. The plan it hands on is the repaired one, so the artefact the
+  // reviewer reads is the artefact that freezes. A failure the freeze itself
+  // would raise is logged here and raised as a finding by the round loop's own
+  // copy of this check, in the same round and under the round's own id: one
+  // objection, one finding, one repair.
+  if (plan !== null) {
+    const checks = checkPlanBeforeReview(plan, { repoFacts, cwd, plansDir, assembleFrozenNodes, frozenContractRaw });
+    plan = checks.plan;
+    if (checks.raised.length > 0) logStage("timeouts-raised", { raised: checks.raised });
+    if (checks.declared.length > 0) logStage("guards-declared", { declared: checks.declared });
+    findings = [...findings, ...checks.findings];
+    logStage("proof-check", { findingsCount: checks.findings.length });
+    logStage("preflight", { raised: checks.raised.length, declared: checks.declared.length, ...(checks.failure === null ? {} : { failed: checks.failure instanceof Error ? checks.failure.message : String(checks.failure) }) });
+  }
+
   const roundsResult = await runReviewRounds({
-    reviewRounds, plan, rejectedDraft: plan === null ? draft.output.plan : undefined, findings, cwd, plansDir, scratchDir, workingPlanPath, relativeWorkingPlanPath,
+    reviewRounds, plan, rejectedDraft: plan === null ? draft.planOutput : undefined, findings, cwd, plansDir, scratchDir, workingPlanPath, relativeWorkingPlanPath,
     relativeSpecPath, relativeRepoFactsPath, relativeCataloguePath, packageMode, repoFacts,
     runStage, assembleFrozenNodes, frozenContractRaw, contest,
     invalidPlanFinding, logStage,