faberun 0.29.0 → 0.31.0

package/src/campaign/watch.mjs

@@ -8,13 +8,37 @@
  * supervisor with a poll interval, an idle policy, a durable dedupe through
  * the inbox, and a lock with its own staleness rule. `cli/campaign.mjs` keeps
  * the thin `watch` operation that reads the flags and calls in here.
+ *
+ * The idle episode is durable too, in `watch-idle.json` beside the lock: the
+ * idle alert's key carries the episode, and an episode kept only in memory
+ * re-anchors on every restart, which either re-sends a window the operator
+ * already saw or stays silent through the next one.
+ *
+ * The campaign alerts -- phase completed, recovery exhausted, decision
+ * needed, closure -- are derived from the same projection the page and the
+ * CLI read (`buildCampaignProgress`), never from a second scan of raw run
+ * files, so every surface answers the campaign from one set of numbers, and
+ * are deduplicated by campaign and episode through the inbox
+ * (`alert:<id>:<campaign>:<episode>`, the keys the ALERTS catalogue in
+ * `report/locale.mjs` declares). The automatic progress update is rendered
+ * from that projection alone -- never a model -- and is an explicit opt-in
+ * through `FABERUN_NOTIFY_EVENTS`; when the transport answers with a receipt
+ * naming a message id, the anchor in `watch-progress.json` records it, and
+ * the next update inside the fifteen-minute window travels as an edit of
+ * that message. The anchor is written only after the receipt returns, so an
+ * editable message is claimed only on evidence, and it carries the state
+ * signature it announced, so an unchanged campaign never re-sends. An
+ * attention event is always a new message: alerts never consult the anchor.
  */
 import { closeSync, openSync, readFileSync, unlinkSync, writeSync } from "node:fs";
 import { join } from "node:path";
 import { lockStale, pidAlive, processStartToken, readLock } from "../run/lock.mjs";
+import { writeJsonAtomic } from "../run/store.mjs";
 import { readCampaign } from "./record.mjs";
 import { notifyQueueFor } from "../engine/notify-queue.mjs";
-import { appendInbox, readInbox, wakeCapabilityNotice } from "../notify/index.mjs";
+import { appendInbox, deliverNotification, deliverableEventTypes, progressEditTarget, readInbox, wakeCapabilityNotice } from "../notify/index.mjs";
+import { buildCampaignProgress } from "../report/progress.mjs";
+import { ALERTS, chooseLanguage, labelsFor } from "../report/locale.mjs";
 import { errorCode, readJsonTolerant } from "../util.mjs";
 
 /** How often the watcher re-reads the campaign when the operator named no interval. */
@@ -23,19 +47,129 @@ export const DEFAULT_WAKE_POLL_MS = 30_000;
 /** How long without a material event before the watcher reports the campaign idle. */
 const WAKE_IDLE_AFTER_MS = 20 * 60_000;
 
+/**
+ * Where the watcher records the idle episode it is in. The idle alert's dedupe
+ * key embeds the instant the episode began, so that anchor has to outlive the
+ * process; the file lives beside `watch.lock` because the one campaign watcher
+ * owns both.
+ */
+const WATCH_IDLE_FILE = "watch-idle.json";
+
+/**
+ * Where the watcher records the progress message a transport acknowledged:
+ * the message id from the transport's receipt, the instant of that receipt,
+ * and the state signature the message announced. Beside `watch.lock`, whose
+ * single watcher owns both; the anchor outlives the process, so a restart
+ * keeps editing the message the operator can still see and never re-sends a
+ * state that was already announced.
+ */
+const WATCH_PROGRESS_FILE = "watch-progress.json";
+
+/**
+ * The dedupe key for one alert occurrence: the catalogue's two keys, campaign
+ * and episode (`report/locale.mjs`'s ALERTS declares the same pair), joined
+ * under the alert's id, so the same occurrence sends once through the inbox
+ * no matter how many polls or restarts re-derive it.
+ *
+ * @param {string} alertId
+ * @param {string} campaignId
+ * @param {string} episode
+ * @returns {string}
+ */
+function alertKey(alertId, campaignId, episode) {
+  return `alert:${alertId}:${campaignId}:${episode}`;
+}
+
+/**
+ * The fields of the shared projection (`buildCampaignProgress`) the watcher
+ * reads. The projection's own module types its return as
+ * `Record<string, unknown>`, so every consumer narrows the fields it needs
+ * its own way; this is the watcher's narrowing, and it names exactly the
+ * fields the alerts and the progress update are rendered from -- never the
+ * whole shape, which is the projection's to own.
+ *
+ * @typedef {object} CampaignProjection
+ * @property {{done: number, total: number}} counts
+ * @property {{nodeId: string}|null} activity
+ * @property {number|null} costTotalUsd
+ * @property {{contractId: string|null, counts: {done: number, total: number}, nodes: {id: string, status: string}[]}[]} phases
+ * @property {{contractId: string}|null} currentPhase
+ */
+
+/**
+ * The one line an automatic progress update says, rendered entirely from the
+ * projection's own numbers and the campaign's wording home: nodes done over
+ * declared, the node in flight, the recorded spend. The same persisted state
+ * yields the same bytes on every poll and every restart -- that is the whole
+ * guarantee, and the reason no model is asked to phrase it.
+ *
+ * @param {CampaignProjection} progress
+ * @param {(key: string) => string} labels
+ * @returns {string}
+ */
+function progressSummaryText(progress, labels) {
+  /** @type {string[]} */
+  const parts = [`${progress.counts.done}/${progress.counts.total} ${labels("done")}`];
+  if (progress.activity) parts.push(`${labels("running")} ${progress.activity.nodeId}`);
+  if (typeof progress.costTotalUsd === "number") parts.push(`$${progress.costTotalUsd.toFixed(2)}`);
+  return parts.join(" · ");
+}
+
+/**
+ * The closure alert's detail: the campaign's final counts and its recorded
+ * spend.
+ *
+ * @param {CampaignProjection} progress
+ * @param {(key: string) => string} labels
+ * @param {string} campaignId
+ * @returns {string}
+ */
+function closureDetail(progress, labels, campaignId) {
+  const cost = typeof progress.costTotalUsd === "number" ? ` · $${progress.costTotalUsd.toFixed(2)}` : "";
+  return `${campaignId} · ${progress.counts.done}/${progress.counts.total} ${labels("done")}${cost}`;
+}
+
+/**
+ * The automatic progress update's delivery: an explicit opt-in through
+ * `FABERUN_NOTIFY_EVENTS` (`progress` is not in the default set -- it is the
+ * one recurring message, and exactly the flood the default set exists to
+ * keep off the operator's phone). The summary arrives already rendered from
+ * the projection; `editOfMessageId`, when the caller anchors one, asks the
+ * transport to edit that message instead of sending a new one. Resolves
+ * `null` when nothing was attempted, so the caller's anchor stays untouched.
+ *
+ * @param {string} campaignId
+ * @param {string} summary
+ * @param {string|null} editOfMessageId
+ * @returns {Promise<import("../notify/index.mjs").DeliveryResult|null>}
+ */
+async function deliverProgressUpdate(campaignId, summary, editOfMessageId) {
+  if (!deliverableEventTypes().has("progress")) return null;
+  return deliverNotification({
+    type: "progress",
+    campaignId,
+    summary,
+    ...(editOfMessageId ? { editOfMessageId } : {}),
+  });
+}
+
 const TERMINAL_NODE_STATUSES = new Set(["done", "no-op", "blocked", "failed", "exhausted", "stalled", "canceled", "cancelled"]);
-const ATTENTION_NODE_STATUSES = new Set(["failed", "exhausted", "stalled", "canceled", "cancelled"]);
 
 /**
- * The watcher loop. Each line is announced through `notify`, which by default
- * records it in `<runs-dir>/inbox.jsonl` and delivers it to the campaign's
- * `notify.jsonl`; the inbox is both the durable record and the dedupe, so a
- * line already recorded is never re-sent. The injectable seams exist so a
- * test can drive the loop deterministically.
+ * The watcher loop. The campaign alerts are derived from the projection and
+ * announced through `notify`, which by default records them in
+ * `<runs-dir>/inbox.jsonl` and delivers them to the campaign's
+ * `notify.jsonl`; the inbox is both the durable record and the dedupe, so an
+ * occurrence already recorded is never re-sent. The idle line is keyed by
+ * campaign, by the durable idle episode and by the twenty-minute window
+ * inside it. The automatic progress update is not an alert: it is delivered
+ * through `sendProgress`, which returns the transport's receipt, and the
+ * receipt -- only the receipt -- writes the `watch-progress.json` anchor.
+ * The injectable seams exist so a test can drive the loop deterministically.
  *
  * @param {string} campaignPath
  * @param {string} runsDir
- * @param {{pollMs?: number, once?: boolean, now?: () => number, sleep?: (ms: number) => Promise<void>, emit?: (line: string) => void, notify?: (event: {type: string, campaignId: string, dedupeKey: string, summary: string, runId?: string|null, nodeId?: string|null, status?: string|null, errorCode?: string|null}) => Promise<void>|void, lock?: {release: () => void}}} [options]
+ * @param {{pollMs?: number, once?: boolean, now?: () => number, sleep?: (ms: number) => Promise<void>, emit?: (line: string) => void, notify?: (event: {type: string, campaignId: string, dedupeKey: string, summary: string, runId?: string|null, nodeId?: string|null, status?: string|null, errorCode?: string|null}) => Promise<void>|void, sendProgress?: (campaignId: string, summary: string, editOfMessageId: string|null) => Promise<{ok: boolean, messageId?: string}|null>, lock?: {release: () => void}}} [options]
  * @returns {Promise<void>}
  */
 export async function watchCampaignWake(campaignPath, runsDir, options = {}) {
@@ -53,20 +187,17 @@ export async function watchCampaignWake(campaignPath, runsDir, options = {}) {
     status: event.status ?? null,
     errorCode: event.errorCode ?? null,
   }));
+  const sendProgress = options.sendProgress ?? deliverProgressUpdate;
   const seen = new Set(readInbox(runsDir).map((entry) => entry.dedupeKey));
   const lock = options.lock ?? acquireWatchLock(campaignPath);
   emit(wakeCapabilityNotice());
-  /** @type {Map<string, string>} */
-  const runSignatures = new Map();
   let lastActiveAt = now();
+  /** @type {number|null} */
+  let idleSince = null;
   let first = true;
   try {
     for (;;) {
       const campaign = readCampaign(campaignPath);
-      if (campaign.status !== "active") {
-        emit(`campaign-watch: ${campaign.id} is ${campaign.status}; stopping`);
-        return;
-      }
       /**
        * Persist first, deliver second: the inbox entry is the durable dedupe,
        * so a restart or a second watcher skips a line already recorded even
@@ -82,14 +213,64 @@ export async function watchCampaignWake(campaignPath, runsDir, options = {}) {
         emit(summary);
         await notify({ type: "attention", campaignId: campaign.id, dedupeKey, summary, ...extra });
       };
+      const language = chooseLanguage(process.env, [campaign.goal]);
+      const labels = labelsFor(language);
+      const nowMs = now();
+      /** @type {CampaignProjection|null} */
+      let progress = null;
+      try {
+        progress = /** @type {CampaignProjection} */ (buildCampaignProgress(runsDir, campaign.id, nowMs));
+      } catch {
+        // A projection that cannot be built (a torn record, an unreadable
+        // journal) yields no alerts and no progress update this poll; the
+        // status loop and the idle clock below still run, and the next poll
+        // re-reads everything.
+        progress = null;
+      }
+      /**
+       * One alert occurrence, worded by the catalogue and deduped by campaign
+       * and episode through the inbox. Alerts are always new messages: none
+       * of them ever consults the progress anchor.
+       *
+       * @param {string} alertId @param {string} episode @param {string} detail
+       */
+      const announceAlert = async (alertId, episode, detail) => {
+        const spec = ALERTS.find((entry) => entry.id === alertId);
+        if (!spec) throw new Error(`campaign watch: no catalogue entry for alert ${alertId}`);
+        await announce(alertKey(alertId, campaign.id, episode), `campaign-watch: ${spec.text[language]}: ${detail}`);
+      };
+      if (campaign.status !== "active") {
+        if (progress) await announceAlert("closure", campaign.id, closureDetail(progress, labels, campaign.id));
+        emit(`campaign-watch: ${campaign.id} is ${campaign.status}; stopping`);
+        return;
+      }
+      if (progress) {
+        for (const phase of progress.phases) {
+          if (phase.contractId === null) continue;
+          if (phase.counts.total > 0 && phase.counts.done === phase.counts.total) {
+            await announceAlert("phase-completed", phase.contractId, `${phase.contractId} · ${phase.counts.done}/${phase.counts.total} ${labels("done")}`);
+          }
+          for (const node of phase.nodes) {
+            if (node.status === "exhausted") {
+              await announceAlert("recovery-exhausted", `${phase.contractId}:${node.id}`, `${phase.contractId} · ${node.id}`);
+            } else if (node.status === "blocked") {
+              await announceAlert("decision-needed", `${phase.contractId}:${node.id}`, `${phase.contractId} · ${node.id}`);
+            }
+          }
+        }
+      }
+      // A restart resumes the episode this campaign was already in. The key
+      // carries the episode's anchor, so resuming it is what keeps a window
+      // already announced quiet and the next window audible.
+      if (first) {
+        const storedSince = readIdleEpisode(campaignPath, campaign.id);
+        if (storedSince !== null) idleSince = storedSince;
+      }
       let anyActive = false;
       for (const runId of campaign.linkedRunIds) {
         const status = /** @type {Record<string, any>|null} */ (readJsonTolerant(join(runsDir, runId, "status.json")));
         if (!status || !Array.isArray(status.nodes)) continue;
         const terminal = status.nodes.every((/** @type {any} */ node) => TERMINAL_NODE_STATUSES.has(String(node.status)));
-        const signature = status.nodes.map((/** @type {any} */ node) => `${node.id}:${node.status}:${node.errorCode ?? ""}`).join("|");
-        const previous = runSignatures.get(runId);
-        runSignatures.set(runId, signature);
         if (!terminal) {
           anyActive = true;
           const runLock = readLock(join(runsDir, runId));
@@ -98,29 +279,41 @@ export async function watchCampaignWake(campaignPath, runsDir, options = {}) {
             await announce(`stale:${runId}`, `campaign-watch: ${runId} has non-terminal nodes but no live controller; resume it`, { runId });
           }
         }
-        if (!first && previous !== signature) {
-          for (const node of status.nodes) {
-            const attention = ATTENTION_NODE_STATUSES.has(String(node.status))
-              || (node.status === "blocked" && !(Array.isArray(node.blockedBy) && node.blockedBy.length > 0));
-            if (attention) {
-              const key = `node:${runId}:${node.id}:${node.status}:${node.errorCode ?? ""}`;
-              await announce(
-                key,
-                `campaign-watch: ${runId} node ${node.id} ${node.status}${node.errorCode ? ` [${node.errorCode}]` : ""}${node.note ? ` ${node.note}` : ""}`,
-                { runId, nodeId: String(node.id), status: String(node.status), errorCode: node.errorCode ?? null },
-              );
+      }
+      if (anyActive) {
+        lastActiveAt = nowMs;
+        if (idleSince !== null) {
+          idleSince = null;
+          clearIdleEpisode(campaignPath);
+        }
+      } else if (idleSince === null) {
+        idleSince = lastActiveAt;
+        writeIdleEpisode(campaignPath, campaign.id, idleSince);
+      }
+      if (idleSince !== null && nowMs - idleSince >= WAKE_IDLE_AFTER_MS) {
+        const key = `idle:${campaign.id}:${new Date(idleSince).toISOString()}:${Math.floor((nowMs - idleSince) / WAKE_IDLE_AFTER_MS)}`;
+        await announce(key, `campaign-watch: ${campaign.id} active but no run has been active for ${Math.round((nowMs - idleSince) / 60_000)} min; dispatch the next step`);
+      }
+      // The automatic progress update. The anchor is the record of what was
+      // already announced: the same state signature is never delivered
+      // twice, whatever restarted in between. When there is something new to
+      // say, a still-editable message is edited in place, and the anchor is
+      // claimed only from the transport's receipt -- a delivery without a
+      // receipt claims nothing, and the next poll tries again.
+      if (progress) {
+        const signature = `${progress.counts.done}/${progress.counts.total}:${progress.activity?.nodeId ?? "-"}:${progress.currentPhase?.contractId ?? "-"}`;
+        const anchor = readProgressAnchor(campaignPath, campaign.id);
+        if (!anchor || anchor.signature !== signature) {
+          const editOfMessageId = progressEditTarget(anchor, nowMs);
+          const receipt = await sendProgress(campaign.id, progressSummaryText(progress, labels), editOfMessageId);
+          if (receipt) {
+            if (receipt.ok && typeof receipt.messageId === "string" && receipt.messageId) {
+              writeProgressAnchor(campaignPath, campaign.id, { messageId: receipt.messageId, at: nowMs, signature });
+            } else {
+              clearProgressAnchor(campaignPath);
             }
           }
         }
-        if (terminal) {
-          await announce(`terminal:${runId}`, `campaign-watch: ${runId} terminal · ${status.summary ?? ""}`, { runId });
-        }
-      }
-      const nowMs = now();
-      if (anyActive) lastActiveAt = nowMs;
-      else if (!first && nowMs - lastActiveAt >= WAKE_IDLE_AFTER_MS) {
-        const key = `idle:${Math.floor((nowMs - lastActiveAt) / WAKE_IDLE_AFTER_MS)}`;
-        await announce(key, `campaign-watch: ${campaign.id} active but no run has been active for ${Math.round((nowMs - lastActiveAt) / 60_000)} min; dispatch the next step`);
       }
       first = false;
       if (options.once === true) return;
@@ -131,6 +324,90 @@ export async function watchCampaignWake(campaignPath, runsDir, options = {}) {
   }
 }
 
+/**
+ * The idle anchor a restart resumes, or null when no episode is in progress. A
+ * record naming another campaign, or whose instant does not parse, is no
+ * anchor: a campaign directory is just a path, and a stale file must never seed
+ * the key with an identity nothing can check.
+ *
+ * @param {string} campaignPath
+ * @param {string} campaignId
+ * @returns {number|null} epoch milliseconds the episode began
+ */
+function readIdleEpisode(campaignPath, campaignId) {
+  const record = /** @type {{campaignId?: unknown, idleSince?: unknown}|null} */ (readJsonTolerant(join(campaignPath, WATCH_IDLE_FILE)));
+  if (!record || record.campaignId !== campaignId || typeof record.idleSince !== "string") return null;
+  const started = Date.parse(record.idleSince);
+  return Number.isFinite(started) ? started : null;
+}
+
+/**
+ * @param {string} campaignPath
+ * @param {string} campaignId
+ * @param {number} idleSince epoch milliseconds
+ */
+function writeIdleEpisode(campaignPath, campaignId, idleSince) {
+  writeJsonAtomic(join(campaignPath, WATCH_IDLE_FILE), { campaignId, idleSince: new Date(idleSince).toISOString() });
+}
+
+/**
+ * @param {string} campaignPath
+ */
+function clearIdleEpisode(campaignPath) {
+  try {
+    unlinkSync(join(campaignPath, WATCH_IDLE_FILE));
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") throw error;
+  }
+}
+
+/**
+ * The progress anchor a restart resumes, or null when none stands. A record
+ * naming another campaign, a message id it does not carry, or an instant or
+ * state signature that does not parse is no anchor: the anchor claims a
+ * message the transport acknowledged, and a claim without all of that is
+ * exactly the claim the receipt rule forbids.
+ *
+ * @param {string} campaignPath
+ * @param {string} campaignId
+ * @returns {{messageId: string, at: number, signature: string}|null}
+ */
+function readProgressAnchor(campaignPath, campaignId) {
+  const record = /** @type {{campaignId?: unknown, messageId?: unknown, at?: unknown, signature?: unknown}|null} */ (readJsonTolerant(join(campaignPath, WATCH_PROGRESS_FILE)));
+  if (!record
+    || record.campaignId !== campaignId
+    || typeof record.messageId !== "string" || !record.messageId
+    || typeof record.at !== "string"
+    || typeof record.signature !== "string") return null;
+  const at = Date.parse(record.at);
+  return Number.isFinite(at) ? { messageId: record.messageId, at, signature: record.signature } : null;
+}
+
+/**
+ * @param {string} campaignPath
+ * @param {string} campaignId
+ * @param {{messageId: string, at: number, signature: string}} anchor
+ */
+function writeProgressAnchor(campaignPath, campaignId, anchor) {
+  writeJsonAtomic(join(campaignPath, WATCH_PROGRESS_FILE), {
+    campaignId,
+    messageId: anchor.messageId,
+    at: new Date(anchor.at).toISOString(),
+    signature: anchor.signature,
+  });
+}
+
+/**
+ * @param {string} campaignPath
+ */
+function clearProgressAnchor(campaignPath) {
+  try {
+    unlinkSync(join(campaignPath, WATCH_PROGRESS_FILE));
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") throw error;
+  }
+}
+
 const WATCH_LOCK_FILE = "watch.lock";
 
 /**

package/src/contract/judge-envelope.mjs

@@ -1,6 +1,6 @@
 /**
- * The judge verdict envelope: the limits `parseJudge` enforces and the reasons
- * it rejects by.
+ * The judge envelope: the limits `parseJudge` enforces, the reasons it rejects
+ * by, and the byte budget a judge prompt itself must fit.
  *
  * They live apart from the parser because the judge prompt must render the same
  * numbers. A judge that is never told the limit can only be discarded by it: a
@@ -23,3 +23,18 @@ export const JUDGE_ENVELOPE_REASON = "judge result exceeds limits";
 
 /** The reason `parseJudge` throws when a single finding overshoots the envelope. */
 export const JUDGE_FINDING_ENVELOPE_REASON = "judge finding exceeds limits";
+
+/**
+ * The byte budget a judge prompt must fit.
+ *
+ * The prompt carries the Definition of Done, the evidence and the re-ask
+ * instruction, so it is the one judge artefact that must never be cut to fit.
+ * `dispatch.mjs` enforces this budget on the prompt it assembles, and the
+ * rotation in `engine/phase-session.mjs` refuses with it rather than bounding
+ * the caller's prompt down, which would send a judge to arbitrate less than the
+ * node declared. One number, two call sites.
+ */
+export const JUDGE_PROMPT_BYTES = 64 * 1024;
+
+/** The reason an oversized judge prompt is refused, byte-for-byte in both call sites. */
+export const JUDGE_PROMPT_REASON = `judge prompt exceeds ${JUDGE_PROMPT_BYTES} bytes`;

package/src/contract/scope-findings.mjs

@@ -142,10 +142,11 @@ export function reauthorWriteConflicts(nodes, nodeId, addedWriteFiles) {
  *   packet: import("./task-packet.mjs").TaskPacket|null|undefined,
  *   findings: string[]|null|undefined,
  *   history: {round: number, accepted: boolean, additions?: ReauthorAdditions, findings?: string[]}[],
+ *   failureCause?: import("../engine/failure-cause.mjs").FailureCause|null,
  * }} entry
  * @returns {Record<string, unknown>}
  */
-export function reauthorProposalRecord({ nodeId, outcome, riskTier, budget, roundsUsed, additions, packet, findings, history }) {
+export function reauthorProposalRecord({ nodeId, outcome, riskTier, budget, roundsUsed, additions, packet, findings, history, failureCause }) {
   /** @param {string[]|undefined} paths @returns {string[]} */
   const bounded = (paths) => [...new Set(paths ?? [])].slice(0, MAX_REAUTHOR_PATHS);
   return {
@@ -153,6 +154,7 @@ export function reauthorProposalRecord({ nodeId, outcome, riskTier, budget, roun
     node: nodeId,
     outcome,
     riskTier,
+    failureCause: failureCause ?? null,
     reauthorProposal: {
       packet: packet ?? null,
       addedReadFiles: bounded(additions?.readFiles),

package/src/contract/task-packet.mjs

@@ -1,3 +1,17 @@
+/**
+ * The closed task packet: the schema, validation and prompt rendering for the
+ * durable scope one node runs under. Separate from the contract that carries
+ * it (`index.mjs`) because a packet is authored and validated on its own too —
+ * a discovery node's `artifacts[0]` is one — and from the planning templates
+ * (`plan/template.mjs`) because those only assemble the JSON this module
+ * refuses or renders. Three modes, one boundary: an execution packet is closed
+ * to named read and write files, a discovery packet is read-only, and an
+ * autonomous packet bounds writes to roots while leaving inspection free.
+ * Every prompt states the whole worker-result shape and the reserved owner
+ * decisions, and none may exceed the byte budget below: a packet's mandatory
+ * content — its declared read files among it — is never truncated to fit, so
+ * a packet without room for it is refused by name instead.
+ */
 import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { Buffer } from "node:buffer";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
@@ -20,6 +34,29 @@ const FIELDS = new Set([
   "verification",
 ]);
 const PROMPT_MAX_BYTES = 64 * 1024;
+
+/**
+ * The one refusal for a packet whose mandatory content does not fit the
+ * prompt budget (R4, campaign-efficiency phase 4). Naming the node, the mode
+ * and the overage is the point: a packet is never truncated to fit — a
+ * dropped read file is a fact the worker was promised — so whoever authored
+ * the packet must be told which node to shrink and by how much, not left
+ * with an anonymous throw that kills the node at dispatch.
+ *
+ * The prompt-budget sentence is kept verbatim inside the message: it is the
+ * wording earlier packets and tests were written against.
+ *
+ * @param {string} prompt
+ * @param {string} nodeId
+ * @param {TaskPacket["mode"]} mode
+ * @returns {never}
+ */
+function refusePromptOverBudget(prompt, nodeId, mode) {
+  const total = Buffer.byteLength(prompt, "utf8");
+  throw new TypeError(
+    `worker_prompt_over_budget: node ${nodeId} (${mode}) prompt is ${total - PROMPT_MAX_BYTES} bytes over the ${PROMPT_MAX_BYTES}-byte budget at ${total} total — the worker prompt exceeds ${PROMPT_MAX_BYTES} bytes, and a packet is never truncated to fit: shrink the readFiles selection or the instructions, or split the node`,
+  );
+}
 /**
  * The `## Verification` preamble every worker prompt carries. The controller's
  * recorded run is the proof; a self-run is optional and must be a quick,
@@ -166,9 +203,7 @@ export function renderWorkerPrompt(packet, nodeId) {
     REQUIRED_OUTPUT_SCHEMA,
   ];
   const prompt = `${lines.join("\n")}\n`;
-  if (Buffer.byteLength(prompt, "utf8") > PROMPT_MAX_BYTES) {
-    throw new TypeError(`worker prompt exceeds ${PROMPT_MAX_BYTES} bytes`);
-  }
+  if (Buffer.byteLength(prompt, "utf8") > PROMPT_MAX_BYTES) refusePromptOverBudget(prompt, nodeId, "execution");
   return prompt;
 }
 
@@ -513,7 +548,7 @@ function renderDiscoveryPrompt(packet, nodeId) {
     ...packet.verification.map((command) => `- ${command.argv.join(" ")}`),
   ];
   const prompt = `${lines.join("\n")}\n`;
-  if (Buffer.byteLength(prompt, "utf8") > PROMPT_MAX_BYTES) throw new TypeError(`worker prompt exceeds ${PROMPT_MAX_BYTES} bytes`);
+  if (Buffer.byteLength(prompt, "utf8") > PROMPT_MAX_BYTES) refusePromptOverBudget(prompt, nodeId, "discovery");
   return prompt;
 }
 
@@ -560,7 +595,7 @@ function renderAutonomousPrompt(packet, nodeId) {
     REQUIRED_OUTPUT_SCHEMA,
   ];
   const prompt = `${lines.join("\n")}\n`;
-  if (Buffer.byteLength(prompt, "utf8") > PROMPT_MAX_BYTES) throw new TypeError(`worker prompt exceeds ${PROMPT_MAX_BYTES} bytes`);
+  if (Buffer.byteLength(prompt, "utf8") > PROMPT_MAX_BYTES) refusePromptOverBudget(prompt, nodeId, "autonomous");
   return prompt;
 }
 

package/src/contract/verification.mjs

@@ -1,4 +1,5 @@
 import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
 import { realpathSync, statSync } from "node:fs";
 import { isAbsolute, resolve } from "node:path";
 import { fail, isContained, tailText } from "../util.mjs";
@@ -88,7 +89,10 @@ export const MUTATION_TIERS = Object.freeze({
  */
 
 /**
- * Callbacks and options for {@link runVerification}.
+ * Callbacks and options for {@link runVerification}. `logDir` is both the
+ * per-command evidence log and the checkpoint store a resumed pass serves
+ * from; the serving is `engine/run-command.mjs`'s, the record's shape is
+ * validated here.
  *
  * @typedef {{signal?: AbortSignal, logDir?: string, writeFiles?: string[], onAttemptStart?: (attempt: VerificationAttempt) => void, onAttemptSpawn?: (attempt: VerificationAttempt) => void, onAttemptComplete?: (attempt: VerificationAttempt) => void}} VerificationOptions
  */
@@ -225,6 +229,68 @@ export function compactVerification(result) {
   return { passed: Boolean(result?.passed), commands };
 }
 
+/**
+ * A per-command checkpoint: the identity hash of everything the recorded proof
+ * depends on, plus the recorded result bounded exactly like persisted state.
+ * It lives beside the pass's evidence log (`checkpoint-<ordinal>.json`) and is
+ * what a resumed verification pass serves instead of re-running a command.
+ *
+ * @typedef {{identity: string, result: VerificationCommandResult}} CommandCheckpoint
+ */
+
+/**
+ * The identity of one command's proof: a hash over the workspace tree — the
+ * dirty fingerprint *and* the HEAD tree id, because the fingerprint hashes
+ * only the difference from HEAD and two clean trees at different commits share
+ * one (review 2026-10-02: a stale passing result was served across a commit) —
+ * plus the validated command, the exact child environment and the
+ * dependency-inputs hash. The tree, the command, the environment and the
+ * dependencies all participate — never the argv alone, which is the proof
+ * cache phase 5 refuses. Key order is fixed by construction (`env` arrives in
+ * `VERIFICATION_ENV_BASE_NAMES`-then-declared order and the canonical object
+ * is one literal), so the hash is stable across the process restart a resume
+ * is.
+ *
+ * @param {{treeFingerprint: string|null, headTree: string|null, command: VerificationCommand, env: Record<string, string>, dependencyHash: string}} parts
+ * @returns {string}
+ */
+export function commandCheckpointIdentity({ treeFingerprint, headTree, command, env, dependencyHash }) {
+  const canonical = { dependencyHash, command, env, headTree, treeFingerprint };
+  return createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
+}
+
+/**
+ * Read back a written checkpoint, failing closed: anything malformed throws
+ * and the caller re-runs the command rather than serving or crashing. The
+ * recorded result is re-compacted on read, so a hand-edited or oversized
+ * record is either bounded to exactly what persisted state may carry or
+ * rejected.
+ *
+ * @param {unknown} value
+ * @param {string} [label]
+ * @returns {CommandCheckpoint}
+ */
+export function parseCommandCheckpoint(value, label = "command checkpoint") {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${label} must be an object`);
+  const record = /** @type {Record<string, unknown>} */ (value);
+  for (const key of Object.keys(record)) {
+    if (key !== "identity" && key !== "result") throw new TypeError(`${label} has unexpected field ${key}`);
+  }
+  if (typeof record.identity !== "string" || !record.identity || Buffer.byteLength(record.identity, "utf8") > 128) {
+    throw new TypeError(`${label}.identity must be a hash of at most 128 bytes`);
+  }
+  const result = /** @type {Record<string, unknown>} */ (record.result);
+  if (!result || typeof result !== "object" || Array.isArray(result) || typeof result.passed !== "boolean") {
+    throw new TypeError(`${label}.result must be a single-command verification result`);
+  }
+  if (!Array.isArray(result.commands) || result.commands.length !== 1) {
+    throw new TypeError(`${label}.result must carry exactly one command`);
+  }
+  const compacted = compactVerification({ passed: result.passed, commands: /** @type {VerificationCommandResult[]} */ (result.commands) });
+  if (compacted.commands.length !== 1) throw new TypeError(`${label}.result exceeds the persisted command bounds`);
+  return { identity: record.identity, result: compacted.commands[0] };
+}
+
 
 /**
  * One proof, one source. A command that declares `requirementId` says it is