faberun 0.29.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(" "));
@@ -135,6 +140,33 @@ export function assertTimeoutsCoverMeasured(contract, facts) {
   if (problems.size) throw new TypeError(`verification timeouts do not cover their measured durations: ${[...problems].join("; ")}`);
 }
 
+/**
+ * Raise whichever of a command list's timeouts sit under
+ * `MEASURED_TIMEOUT_MARGIN` times their measured duration, recording each
+ * raise under `label`. Returns the list unchanged (by identity) when nothing
+ * needed raising, so the caller can tell whether to re-list.
+ *
+ * @param {import("../contract/index.mjs").VerificationCommand[]} commands
+ * @param {MeasuredFacts} facts
+ * @param {string} label
+ * @param {string[]} raised
+ * @returns {import("../contract/index.mjs").VerificationCommand[]}
+ */
+function raiseCommandTimeouts(commands, facts, label, raised) {
+  let changed = false;
+  const next = commands.map((command) => {
+    const measuredMs = measuredMsFor(command.argv, facts);
+    if (measuredMs === null) return command;
+    const requiredSec = Math.ceil((measuredMs * MEASURED_TIMEOUT_MARGIN) / 1_000);
+    const timeoutSec = command.timeoutSec ?? 120;
+    if (timeoutSec >= requiredSec || requiredSec > VERIFICATION_LIMITS.maxTimeoutSec) return command;
+    raised.push(`${label}: ${command.argv.join(" ")} ${timeoutSec}s -> ${requiredSec}s`);
+    changed = true;
+    return { ...command, timeoutSec: requiredSec };
+  });
+  return changed ? next : commands;
+}
+
 /**
  * Raise every plan node's verification timeout that sits under
  * `MEASURED_TIMEOUT_MARGIN` times its measured duration to exactly that
@@ -145,6 +177,11 @@ export function assertTimeoutsCoverMeasured(contract, facts) {
  * plan with no critical from review, contested only because three nodes gave
  * `node --test test/harnesses` 120s against a measured 84.4s (bound 127s).
  *
+ * The plan's own contract-level suites (RM-107) are raised here too, over the
+ * same measurement: `assertTimeoutsCoverMeasured` reads them, so a repair that
+ * skipped them would leave the check naming a repair this function does not
+ * make. Its label is the suite key, since a contract suite belongs to no node.
+ *
  * @param {import("./template.mjs").PlanOutput} plan
  * @param {MeasuredFacts} facts
  * @returns {{plan: import("./template.mjs").PlanOutput, raised: string[]}}
@@ -152,19 +189,22 @@ export function assertTimeoutsCoverMeasured(contract, facts) {
 export function raiseTimeoutsToMeasured(plan, facts) {
   /** @type {string[]} */
   const raised = [];
-  const nodes = plan.nodes.map((node) => ({
-    ...node,
-    verification: (node.verification ?? []).map((command) => {
-      const measuredMs = measuredMsFor(command.argv, facts);
-      if (measuredMs === null) return command;
-      const requiredSec = Math.ceil((measuredMs * MEASURED_TIMEOUT_MARGIN) / 1_000);
-      const timeoutSec = command.timeoutSec ?? 120;
-      if (timeoutSec >= requiredSec || requiredSec > VERIFICATION_LIMITS.maxTimeoutSec) return command;
-      raised.push(`${node.id}: ${command.argv.join(" ")} ${timeoutSec}s -> ${requiredSec}s`);
-      return { ...command, timeoutSec: requiredSec };
-    }),
-  }));
-  return { plan: raised.length ? { ...plan, nodes } : plan, raised };
+  const nodes = plan.nodes.map((node) => {
+    const verification = raiseCommandTimeouts(node.verification ?? [], facts, node.id, raised);
+    return verification === node.verification ? node : { ...node, verification };
+  });
+  const sharedVerification = raiseCommandTimeouts(plan.sharedVerification ?? [], facts, "sharedVerification", raised);
+  const finalVerification = raiseCommandTimeouts(plan.finalVerification ?? [], facts, "finalVerification", raised);
+  if (raised.length === 0) return { plan, raised };
+  return {
+    plan: {
+      ...plan,
+      nodes,
+      ...(plan.sharedVerification === undefined ? {} : { sharedVerification }),
+      ...(plan.finalVerification === undefined ? {} : { finalVerification }),
+    },
+    raised,
+  };
 }
 
 /** @returns {string} the installed package's own version, read once per call so a freeze always names the toolchain that produced it */

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.`,
+  };
+}