faberun 0.8.0 → 0.10.0

package/src/engine/verify.mjs

@@ -11,8 +11,10 @@
 import { attemptWorkspace } from "../repo/worktree.mjs";
 import { boundedUtf8, errorMessage } from "../util.mjs";
 import { compactVerification } from "../contract/verification.mjs";
-import { finalVerificationCommands, sharedVerificationCommands } from "../contract/final-verification.mjs";
+import { finalVerificationCommands, phaseTerminalNode, sharedVerificationCommands } from "../contract/final-verification.mjs";
 import { join } from "node:path";
+import { listNodeSnapshots, readNodeSnapshot } from "../run/node-store.mjs";
+import { SETTLED } from "./prompts.mjs";
 import { terminateInvocation } from "./process.mjs";
 import { writeNode } from "./state.mjs";
 import { runVerification } from "./run-command.mjs";
@@ -28,6 +30,34 @@ import { runVerification } from "./run-command.mjs";
 /** @typedef {import("../contract/index.mjs").VerificationState} VerificationState */
 /** @typedef {{index: number, total: number, argv: string}} VerificationProgress */
 
+/**
+ * The sibling phase-terminal node ids already settled, read straight off
+ * disk: every node snapshot is persisted from the run's first tick (see
+ * `runContract`), so a node still `pending` reads back honestly, not as
+ * missing. `finalVerificationCommands` uses this to decide, at the moment a
+ * phase-terminal node's own verification runs, whether it is the one that
+ * closes the phase -- recomputed fresh on every call, so a retried node sees
+ * its siblings' current status each time, not a decision frozen from an
+ * earlier attempt.
+ *
+ * @param {string} runDir
+ * @param {ValidatedContract} contract
+ * @param {ValidatedNode} node
+ * @returns {Set<string>}
+ */
+function settledSiblingIds(runDir, contract, node) {
+  const ids = new Set();
+  for (const name of listNodeSnapshots(runDir)) {
+    const id = name.slice(0, -".json".length);
+    if (id === node.id) continue;
+    const sibling = contract.nodes.find((candidate) => candidate.id === id);
+    if (!sibling || !phaseTerminalNode(contract, sibling)) continue;
+    const snapshot = /** @type {{status?: string}} */ (readNodeSnapshot(runDir, id));
+    if (SETTLED.has(/** @type {string} */ (snapshot.status))) ids.add(id);
+  }
+  return ids;
+}
+
 /**
  * The bounded `k/n · argv` shape a running node's status surfaces while a
  * verification command is in flight: the command's 1-based position among
@@ -108,7 +138,7 @@ export async function executeControllerVerification(contract, runDir, node, stat
   };
   writeNode(runDir, state, lock);
   const workspace = attemptWorkspace(state) ?? contract.cwd;
-  const commands = [...node.taskPacket.verification, ...sharedVerificationCommands(contract), ...finalVerificationCommands(contract, node)];
+  const commands = [...node.taskPacket.verification, ...sharedVerificationCommands(contract), ...finalVerificationCommands(contract, node, settledSiblingIds(runDir, contract, node))];
   /** @param {VerificationAttempt} attempt @returns {VerificationProgress} */
   const progressFor = (attempt) => verificationProgress(attempt.commandIndex + 1, commands.length, /** @type {VerificationCommand|undefined} */ (commands[attempt.commandIndex])?.argv);
   try {
@@ -221,16 +251,37 @@ function argvEqual(a, b) {
   if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
   return a.every((item, index) => item === b[index]);
 }
+/**
+ * Marks whether the integration candidate's own verification pass is running
+ * right now, nested inside the attempt's own already-completed verification
+ * record rather than as a new node-snapshot field: that record's validator
+ * (`validateVerificationSnapshot`) accepts extra keys, where the node
+ * snapshot's own strict field list would reject one. Status surfaces read it
+ * to tell "still verifying the sealed candidate" apart from "waiting on the
+ * judge", which otherwise both read as whatever phase the attempt last
+ * dispatched under.
+ *
+ * @param {string} runDir
+ * @param {NodeSnapshot} state
+ * @param {LockHandle|null} lock
+ * @param {boolean} active
+ */
+function markCandidateVerification(runDir, state, lock, active) {
+  state.verification = /** @type {VerificationState} */ ({ ...(state.verification ?? { passed: false, commands: [], completed: false }), candidate: active });
+  writeNode(runDir, state, lock);
+}
 /**
  * @param {ValidatedContract} contract
  * @param {ValidatedNode} node
  * @param {NodeSnapshot} state
  * @param {string} runDir
  * @param {string} workspace
+ * @param {LockHandle|null} [lock]
  * @returns {Promise<import("../repo/integrate.mjs").CandidateEvidence>}
  */
-export async function verifyCandidateWorkspace(contract, node, state, runDir, workspace) {
-  const commands = [...node.taskPacket.verification, ...sharedVerificationCommands(contract), ...finalVerificationCommands(contract, node)];
+export async function verifyCandidateWorkspace(contract, node, state, runDir, workspace, lock = null) {
+  const commands = [...node.taskPacket.verification, ...sharedVerificationCommands(contract), ...finalVerificationCommands(contract, node, settledSiblingIds(runDir, contract, node))];
+  markCandidateVerification(runDir, state, lock, true);
   try {
     const result = await runVerification(commands, workspace, {
       logDir: join(runDir, "logs", `${node.id}.${state.attempt}.candidate-verification`),
@@ -252,5 +303,7 @@ export async function verifyCandidateWorkspace(contract, node, state, runDir, wo
     return settled.retried ? { ...compacted, retried: settled.retried } : compacted;
   } catch (error) {
     return { passed: false, error: boundedUtf8(errorMessage(error), 4 * 1024) };
+  } finally {
+    markCandidateVerification(runDir, state, lock, false);
   }
 }

package/src/harnesses/protocol.mjs

@@ -5,6 +5,8 @@ import { finite } from "../util.mjs";
  * `zcode.mjs`, `replay.mjs` and `exec-jsonl.mjs` itself all depend on it.
  */
 
+/** @typedef {{remaining: number|null, limit: number|null, resetsAt: string|null, window: string|null}} ClaudeAllowance */
+
 /**
  * Parse newline-delimited JSON without accepting provider prose.
  *
@@ -75,33 +77,110 @@ function withStartupReason(message, options = {}) {
   return reason ? `${message}: ${boundedMessage(reason, 512)}` : message;
 }
 
+/**
+ * Claude's account-wide rate-limit signal, reported on its own `rate_limit_event`
+ * stream line, never on the terminal `result` event. Measured 2026-09-17
+ * against `claude -p 'Reply with exactly OK and use no tools.' --output-format
+ * stream-json --verbose`, cost `total_cost_usd: 0.27848` for that one probe
+ * (opus-tier default model, most of it `cache_creation_input_tokens` for this
+ * project's session context -- a probe against a smaller/cheaper model would
+ * cost far less, but the seat sampled is whichever model the operator's own
+ * session already has configured, so this is the honest per-probe figure for
+ * that seat). No `rate_limits` or `rate_limit_status` field appears anywhere
+ * in the stream. The measured line, verbatim:
+ * `{"type":"rate_limit_event","rate_limit_info":{"status":"allowed_warning",
+ * "resetsAt":1789837200,"rateLimitType":"seven_day","utilization":0.77,
+ * "isUsingOverage":false,"surpassedThreshold":0.75,"unifiedWindows":
+ * {"five_hour":{"utilization":0.1,"resetsAt":1789663200},"seven_day":
+ * {"utilization":0.77,"resetsAt":1789837200}}}}`. `utilization` is a 0..1
+ * fraction of the window named by `rateLimitType`, confirmed (not merely
+ * assumed) by `surpassedThreshold: 0.75` sitting just below the measured
+ * `0.77` at `status: "allowed_warning"` -- a 0-100 percentage scale would put
+ * 0.77 nowhere near a 75-scaled threshold. This is a different field, on a
+ * different scale, from the `used_percentage` (0-100) the statusline
+ * integration already reads off `rate_limits.five_hour` (see
+ * `integrations/claude-code/statusline.sh`); the two must not be confused.
+ * `remaining` here is the fraction left (`1 - utilization`) and `limit` is
+ * the fixed ceiling `1` -- a coarse proxy, declared as such. A `utilization`
+ * outside `[0, 1]` is treated as no signal (null) rather than silently
+ * clamped, so a future scale change on the stream fails visibly instead of
+ * pinning every sample to 0.
+ *
+ * `unifiedWindows` carries every window's own utilization side by side
+ * (`five_hour: 0.1` next to `seven_day: 0.77` in the measured line above): the
+ * top-level `utilization` is only ever the figure for the window `rateLimitType`
+ * names, so a sample must read the named window out of `unifiedWindows` (falling
+ * back to the top-level field only when `unifiedWindows` carries no entry for
+ * it) and record which window that was. Two samples of different windows are
+ * not comparable -- a `five_hour` utilization minus a `seven_day` one is not a
+ * delta -- so the window travels with the sample for `allowanceDelta` to pin.
+ *
+ * @param {Record<string, unknown>[]} events
+ * @returns {ClaudeAllowance}
+ */
+function extractClaudeAllowance(events) {
+  const event = events.findLast((candidate) => candidate.type === "rate_limit_event");
+  const info = event?.rate_limit_info;
+  const record = info && typeof info === "object" && !Array.isArray(info) ? /** @type {Record<string, unknown>} */ (info) : null;
+  const window = record && typeof record.rateLimitType === "string" ? record.rateLimitType : null;
+  const unifiedWindows = record?.unifiedWindows && typeof record.unifiedWindows === "object" && !Array.isArray(record.unifiedWindows)
+    ? /** @type {Record<string, unknown>} */ (record.unifiedWindows)
+    : null;
+  const namedWindowEntry = window && unifiedWindows?.[window] && typeof unifiedWindows[window] === "object" && !Array.isArray(unifiedWindows[window])
+    ? /** @type {Record<string, unknown>} */ (unifiedWindows[window])
+    : null;
+  const rawUtilization = finite(namedWindowEntry ? namedWindowEntry.utilization : record?.utilization);
+  const utilization = rawUtilization !== null && rawUtilization >= 0 && rawUtilization <= 1 ? rawUtilization : null;
+  const resetsAtSeconds = finite(namedWindowEntry ? namedWindowEntry.resetsAt : record?.resetsAt);
+  return {
+    remaining: utilization === null ? null : 1 - utilization,
+    limit: utilization === null ? null : 1,
+    resetsAt: resetsAtSeconds === null ? null : new Date(resetsAtSeconds * 1000).toISOString(),
+    window,
+  };
+}
+
+/** The claude allowance shape with every member null: no signal was read. */
+const NULL_CLAUDE_ALLOWANCE = { remaining: null, limit: null, resetsAt: null, window: null };
+
 /**
  * @param {string} stdout
  * @param {number|null} exitCode
  * @param {string|null} signal
  * @param {import("./index.mjs").NormalizeOptions} [options]
- * @returns {import("./index.mjs").ProviderEnvelope}
+ * @returns {import("./index.mjs").ProviderEnvelope & {allowance: ClaudeAllowance}}
  */
 export function normalizeClaudeResult(stdout, exitCode, signal, options = {}) {
-  if (signal) return failed("canceled", `provider ended after ${signal}`, "canceled");
+  // The signal check must stay the first statement, byte-identical to before
+  // the allowance signal existed: `parseJsonLines` throws on any unparseable
+  // line past the first, and a killed process routinely leaves a truncated
+  // *later* line (the bounded-tail tolerance only covers the first). Parsing
+  // stdout before checking `signal` would turn a clean cancellation into a
+  // thrown error, which callers (`src/run/usage.mjs`, `src/engine/process.mjs`)
+  // catch into `invalid_output` or `null`, losing the envelope entirely.
+  if (signal) return { ...failed("canceled", `provider ended after ${signal}`, "canceled"), allowance: NULL_CLAUDE_ALLOWANCE };
   const events = parseJsonLines(stdout, "claude");
+  const allowance = extractClaudeAllowance(events);
   const resultEvent = events.findLast((event) => event.type === "result");
-  if (!resultEvent) return failed("incomplete_stream", withStartupReason("Claude emitted no result event", options));
+  if (!resultEvent) return { ...failed("incomplete_stream", withStartupReason("Claude emitted no result event", options)), allowance };
   const result = typeof resultEvent.result === "string" ? resultEvent.result : null;
   // A provider-reported quota stop is exhaustion: the declared failover edge
   // must fire instead of settling the node as an ordinary provider failure.
   const quotaText = claudeQuotaText(resultEvent, events);
   if (quotaText) {
-    return failed(
-      "quota_exhausted",
-      boundedMessage(quotaText, 512),
-      "exhausted",
-      typeof resultEvent.session_id === "string" ? resultEvent.session_id : null,
-      canonicalUsage(resultEvent.usage),
-    );
+    return {
+      ...failed(
+        "quota_exhausted",
+        boundedMessage(quotaText, 512),
+        "exhausted",
+        typeof resultEvent.session_id === "string" ? resultEvent.session_id : null,
+        canonicalUsage(resultEvent.usage),
+      ),
+      allowance,
+    };
   }
   if (resultEvent.is_error || exitCode !== 0) {
-    return failed("provider_error", result ?? `Claude exited with code ${exitCode}`);
+    return { ...failed("provider_error", result ?? `Claude exited with code ${exitCode}`), allowance };
   }
   return {
     status: result?.trim() ? "done" : "no-op",
@@ -110,6 +189,7 @@ export function normalizeClaudeResult(stdout, exitCode, signal, options = {}) {
     usage: canonicalUsage(resultEvent.usage),
     costUsd: finite(resultEvent.total_cost_usd),
     error: null,
+    allowance,
   };
 }
 

package/src/plan/freeze.mjs

@@ -9,10 +9,11 @@
  * Nothing here invokes a model or the engine; it only writes and hashes
  * bytes, so freezing a plan can never be mistaken for starting a run.
  */
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CONTRACT_VERSION, PROTOCOL_SCHEMA_VERSION, contractDigest, validateContract } from "../contract/index.mjs";
+import { writeJsonAtomic } from "../run/store.mjs";
 
 /** @typedef {import("../contract/index.mjs").JsonObject} JsonObject */
 
@@ -55,7 +56,7 @@ export function freezePlan(plan, { outDir, provenance }) {
     contractVersion: CONTRACT_VERSION,
     ...plan,
   });
-  writeFileSync(contractPath, `${JSON.stringify(raw, null, 2)}\n`);
+  writeJsonAtomic(contractPath, raw);
   try {
     validateContract(raw, contractPath);
   } catch (error) {
@@ -76,7 +77,10 @@ export function freezePlan(plan, { outDir, provenance }) {
       findings: provenance.findings,
     },
   });
-  writeFileSync(join(outDir, "plan.json"), `${JSON.stringify(frozen, null, 2)}\n`);
+  // Atomic: the pipeline rewrites this file with its status straight after, and a
+  // reader polling for the frozen plan must never see a torn or half-written one
+  // (measured 2026-09-17: eval case D25 read a statusless plan.json on a slow runner).
+  writeJsonAtomic(join(outDir, "plan.json"), frozen);
   return frozen;
 }
 

package/src/plan/pipeline.mjs

@@ -0,0 +1,371 @@
+/**
+ * The planning pipeline: `faberun plan` as successive ordinary runs (draft,
+ * review, revise up to a round budget) followed by the deterministic stages
+ * (sizing, routing, freeze), never as one long-lived process. Separate from
+ * `template.mjs` (which only builds the one-node contracts) and from
+ * `freeze.mjs` (which only turns a plan into a validated contract on disk):
+ * this module is the one place that sequences those runs, decides when a
+ * plan is contested instead of frozen, and records the operator-approval
+ * open-question. `launch` and `wait` are the only two seams that touch a
+ * process or the wall clock, so a test drives the whole pipeline through
+ * `runContract` in-process, deterministically.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { validateContract } from "../contract/index.mjs";
+import { discoveryOutput } from "../contract/worker-result.mjs";
+import { readWorkerResultFile } from "../engine/result-file.mjs";
+import { classifyRunProgress } from "../campaign/chain.mjs";
+import { campaignDir } from "../campaign/layout.mjs";
+import { appendSeatAllowanceEvent, readJournal } from "../campaign/journal.mjs";
+import { readCampaign } from "../campaign/record.mjs";
+import { campaignCli } from "../cli/campaign.mjs";
+import { appendJsonl, writeJsonAtomic } from "../run/store.mjs";
+import { allowanceDelta, allowanceEventFields, sampleAllowance } from "../seat/allowance.mjs";
+import { validateSpec } from "./spec.mjs";
+import { collectRepoFacts } from "./repo-facts.mjs";
+import { RISK_TIERS, buildPlanningContract, validateFindings, validatePlanOutput } from "./template.mjs";
+import { applySizingRules } from "./sizing.mjs";
+import { resolveRuntimes } from "./routing.mjs";
+import { freezePlan } from "./freeze.mjs";
+
+/** @typedef {import("../contract/index.mjs").JsonObject} JsonObject */
+/** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
+/** @typedef {import("./template.mjs").PlanOutput} PlanOutput */
+/** @typedef {import("./template.mjs").PlanFindingOutput} PlanFindingOutput */
+/** @typedef {import("./sizing.mjs").PlanNode & {objective: string}} SizedPlanNode */
+/** @typedef {"standard"|"high"|"none"} ApproveBelow */
+/** @typedef {(contractPath: string, contract: ValidatedContract) => Promise<void>|void} LaunchFn */
+/** @typedef {(runDir: string) => Promise<import("../engine/supervise.mjs").RunProgress>|import("../engine/supervise.mjs").RunProgress} WaitFn */
+/** @typedef {{status: "frozen", plansDir: string, planPath: string, contractPath: string, approved: boolean, findings: PlanFindingOutput[]}} FrozenPipelineResult */
+/** @typedef {{status: "contested", plansDir: string, planPath: string, findings: PlanFindingOutput[], round: number}} ContestedPipelineResult */
+
+/**
+ * The session id every automated journal entry this pipeline writes carries.
+ * There is no human session behind a `plan` invocation, so a fixed id names
+ * the writer the same way `src/web/api.mjs`'s `WEB_SESSION_ID` names the web
+ * surface's own automated writes.
+ */
+export const PLANNER_SESSION_ID = "planner";
+
+/**
+ * No taskKind/riskTier row is opinionated by default: absent an operator
+ * `--runtime-defaults` instruction, every sized node routes through plain
+ * availability discovery (`resolveRuntimes`'s cheapest worker, strongest
+ * cross-vendor judge). A default table cannot safely name a `prefer` runtime
+ * id without knowing the operator's own catalogue, so "small default" here
+ * means empty rather than guessed.
+ */
+export const DEFAULT_ROUTING_TABLE = /** @type {import("./routing.mjs").RoutingRule[]} */ ([]);
+
+/** The sizing budget a frozen node's verification is measured against, absent a project-specific one. */
+export const DEFAULT_NODE_BUDGET_MS = 600_000;
+
+const APPROVE_BELOW_VALUES = new Set(["standard", "high", "none"]);
+
+/**
+ * @param {{specPath: string, campaignId: string, phase: string, cwd?: string, reviewRounds?: number, approveBelow?: ApproveBelow, runtimeDefaults?: {worker?: string, judge?: string}, runtimes: Record<string, JsonObject>, launch: LaunchFn, wait: WaitFn}} options
+ * @returns {Promise<FrozenPipelineResult|ContestedPipelineResult>}
+ */
+export async function runPlanningPipeline(options) {
+  const {
+    specPath, campaignId, phase, runtimes, launch, wait,
+    reviewRounds = 2, runtimeDefaults = {},
+  } = options;
+  const approveBelow = /** @type {ApproveBelow} */ (options.approveBelow ?? "standard");
+  if (!APPROVE_BELOW_VALUES.has(approveBelow)) throw new TypeError(`approveBelow must be one of ${[...APPROVE_BELOW_VALUES].join(", ")}`);
+  if (typeof launch !== "function") throw new TypeError("runPlanningPipeline requires a launch seam");
+  if (typeof wait !== "function") throw new TypeError("runPlanningPipeline requires a wait seam");
+  const cwd = resolve(options.cwd ?? ".");
+
+  const campaignPath = campaignDir(join(cwd, ".runs"), campaignId);
+  const campaign = readCampaign(campaignPath);
+  if (campaign.status !== "active") throw new Error(`campaign is closed: ${campaignId}`);
+
+  const relativeSpecPath = repoRelativePath(cwd, specPath, "specPath");
+  const specText = readFileSync(resolve(cwd, relativeSpecPath), "utf8");
+  const specValidation = validateSpec(specText, { cwd, strict: true });
+  if (specValidation.class === "structured" && !specValidation.ok) {
+    const detail = specValidation.findings.map((finding) => `${finding.rule}: ${finding.message}`).join("; ");
+    throw new Error(`spec ${specPath} fails strict traceability: ${detail}`);
+  }
+
+  const plansDir = join(cwd, ".runs", "campaigns", campaignId, "plans", phase);
+  mkdirSync(plansDir, { recursive: true });
+  const pipelineLog = join(plansDir, "pipeline.jsonl");
+  /** @param {string} stage @param {Record<string, unknown>} [extra] */
+  const logStage = (stage, extra = {}) => appendJsonl(pipelineLog, {
+    type: "plan.stage", at: new Date().toISOString(), campaignId, phase, stage, ...extra,
+  });
+
+  const repoFacts = collectRepoFacts(cwd);
+  const repoFactsPath = join(plansDir, "repo-facts.json");
+  writeFileSync(repoFactsPath, `${JSON.stringify(repoFacts, null, 2)}\n`);
+  const relativeRepoFactsPath = relative(cwd, repoFactsPath);
+  logStage("repo-facts", { gitHead: repoFacts.gitHead });
+
+  let n = 0;
+  const nextN = () => { n += 1; return n; };
+
+  /**
+   * Build, validate, persist, launch and wait for one planning contract, and
+   * return the discovery `output` its worker recorded. Every stage the
+   * pipeline runs is an ordinary run: it lands in `usage.jsonl` exactly like
+   * any other node, and this is the only place that reads its result back.
+   *
+   * @param {import("./template.mjs").PlanningKind} kind
+   * @param {Record<string, unknown>} inputs
+   * @returns {Promise<{contract: ValidatedContract, output: Record<string, unknown>}>}
+   */
+  const runStage = async (kind, inputs) => {
+    const stageN = nextN();
+    const contractPath = join(plansDir, "nodes", `${kind}-${stageN}.contract.json`);
+    mkdirSync(dirname(contractPath), { recursive: true });
+    const relativeCwd = relative(dirname(contractPath), cwd) || ".";
+    const raw = buildPlanningContract(kind, {
+      campaignId, phase, n: stageN, runtimes, runtimeDefaults, cwd: relativeCwd, ...inputs,
+    });
+    const validated = validateContract(raw, contractPath);
+    writeFileSync(contractPath, `${JSON.stringify(raw, null, 2)}\n`);
+    await launch(contractPath, validated);
+    const runDir = join(validated.cwd, ".runs", validated.id);
+    const progress = await wait(runDir);
+    const classification = classifyRunProgress(progress);
+    if (classification !== "succeeded") {
+      throw new Error(`planning stage ${kind} did not succeed: run ${validated.id} ${classification}`);
+    }
+    const result = readWorkerResultFile(runDir, kind);
+    const output = result ? discoveryOutput(result) : null;
+    if (!output) throw new Error(`planning stage ${kind}: run ${validated.id} recorded no discovery output`);
+    return { contract: validated, output };
+  };
+
+  const draft = await runStage("draft", { specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath });
+  let plan = validatePlanOutput(draft.output.plan);
+  logStage("draft", { runId: draft.contract.id, nodeCount: plan.nodes.length });
+
+  const workingPlanPath = join(plansDir, "plan.working.json");
+  writeJsonAtomic(workingPlanPath, plan);
+  const relativeWorkingPlanPath = relative(cwd, workingPlanPath);
+
+  /** @type {PlanFindingOutput[]} */
+  let findings = [];
+  for (let round = 1; round <= reviewRounds; round += 1) {
+    const review = await runStage("review", { specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath, planPath: relativeWorkingPlanPath });
+    findings = validateFindings(review.output.findings);
+    const criticalFindings = findings.filter((finding) => finding.severity === "critical");
+    logStage("review", { round, runId: review.contract.id, findingsCount: findings.length, criticalCount: criticalFindings.length });
+    if (criticalFindings.length === 0) break;
+    if (round === reviewRounds) {
+      const planPath = join(plansDir, "plan.json");
+      writeJsonAtomic(planPath, { formatVersion: 1, status: "contested", rounds: round, findings });
+      logStage("contested", { round, criticalCount: criticalFindings.length });
+      await campaignCli([
+        "note", campaignId, "--cwd", cwd, "--session-id", PLANNER_SESSION_ID,
+        "--kind", "open-question", "--question-id", `plan-${phase}-contested`,
+        "--text", `Plan for phase ${phase} is contested after ${round} review round(s): ${criticalFindings.map((finding) => finding.text).join("; ")}`,
+      ]);
+      return { status: "contested", plansDir, planPath, findings, round };
+    }
+    const findingsPath = join(plansDir, `findings-round-${round}.json`);
+    writeJsonAtomic(findingsPath, findings);
+    const revise = await runStage("revise", {
+      specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath, findingsPath: relative(cwd, findingsPath),
+    });
+    plan = validatePlanOutput(revise.output.plan);
+    writeJsonAtomic(workingPlanPath, plan);
+    logStage("revise", { round, runId: revise.contract.id });
+  }
+
+  const sizing = applySizingRules(
+    { nodes: plan.nodes.map(toSizingNode), justification: plan.justification },
+    { nodeBudgetMs: DEFAULT_NODE_BUDGET_MS, facts: repoFacts },
+  );
+  logStage("sizing", { transformations: sizing.transformations.length, nodeCount: sizing.plan.nodes.length });
+
+  const routingRuntimes = /** @type {Record<string, import("./routing.mjs").RoutingRuntime>} */ (runtimes);
+  const routing = resolveRuntimes(sizing.plan.nodes, {
+    table: [...DEFAULT_ROUTING_TABLE],
+    runtimes: routingRuntimes,
+    availability: availabilityOf(runtimes),
+    runtimeDefaults,
+  });
+  logStage("routing", { assignments: Object.keys(routing.assignments).length });
+
+  const highestRiskTier = highestOf(sizing.plan.nodes.map((node) => node.riskTier ?? RISK_TIERS[0]));
+  const nodes = sizing.plan.nodes.map((node) => toContractNode(/** @type {SizedPlanNode} */ (node), phase, routing.assignments[node.id]));
+  const frozen = freezePlan({
+    id: `${campaignId}-${phase}`,
+    campaignId,
+    goal: campaign.goal,
+    // `freezePlan` writes contract.json inside `outDir` (`plansDir`), so `cwd`
+    // has to point back at the repo root from there, exactly like `runStage`
+    // computes it for the nodes it writes under `plansDir/nodes/`.
+    cwd: relative(plansDir, cwd) || ".",
+    runtimes,
+    runtimeDefaults,
+    nodes,
+  }, {
+    outDir: plansDir,
+    provenance: {
+      targetGitHead: repoFacts.gitHead,
+      planner: { runtimeId: runtimeDefaults.worker ?? "", model: modelOf(runtimes, runtimeDefaults.worker) },
+      reviewer: { runtimeId: runtimeDefaults.judge ?? "", model: modelOf(runtimes, runtimeDefaults.judge) },
+      sizing: sizing.transformations,
+      findings,
+    },
+  });
+  logStage("freeze", { contractId: `${campaignId}-${phase}`, highestRiskTier });
+
+  // A delta only means something between two samples of the same seat: freeze
+  // re-samples the exact harness `campaign init` recorded at `sample: "start"`
+  // (the operator's own seat), not the plan's worker runtime, which is very
+  // often a different harness entirely (codex, dsh, agy, zcode workers under
+  // a claude operator) and would make the delta null in the common case
+  // instead of the rare one. With no start entry at all (a pipeline run with
+  // no preceding `campaign init`, as in every replay-driven pipeline test)
+  // there is no seat to re-sample, so freeze samples nothing and spends no
+  // call.
+  const journalEntries = /** @type {any[]} */ (readJournal(campaignPath));
+  const startEntry = journalEntries.findLast((entry) => entry.type === "seat.allowance" && entry.sample === "start");
+  const freezeHarness = startEntry?.harness ?? null;
+  const freezeAllowance = await sampleAllowance({ harness: freezeHarness });
+  const startAllowance = startEntry
+    ? { remaining: startEntry.remaining ?? null, limit: startEntry.limit ?? null, resetsAt: startEntry.resetsAt ?? null, window: startEntry.window ?? null }
+    : null;
+  appendSeatAllowanceEvent(campaignPath, {
+    sample: "freeze",
+    harness: freezeHarness,
+    delta: allowanceDelta(startAllowance, freezeAllowance),
+    ...allowanceEventFields(freezeAllowance),
+  });
+
+  const approved = approveBelow === "high" ? true : approveBelow === "none" ? false : highestRiskTier !== "high";
+  const planPath = join(plansDir, "plan.json");
+  writeJsonAtomic(planPath, { ...frozen, status: "frozen", approved });
+  if (!approved) {
+    await campaignCli([
+      "note", campaignId, "--cwd", cwd, "--session-id", PLANNER_SESSION_ID,
+      "--kind", "open-question", "--question-id", `plan-${phase}-approval`,
+      "--text", `Plan for phase ${phase} carries a ${highestRiskTier}-risk node; approval is required under --approve-below ${approveBelow}.`,
+    ]);
+  }
+  logStage("approval", { approved, approveBelow, highestRiskTier });
+
+  return { status: "frozen", plansDir, planPath, contractPath: join(plansDir, "contract.json"), approved, findings };
+}
+
+/**
+ * `path` made relative to `cwd`, refused when it escapes it: every planning
+ * contract's readFiles must resolve inside the same cwd a run validates
+ * against, so a spec outside the target repository can never be named there.
+ *
+ * @param {string} cwd
+ * @param {string} path
+ * @param {string} label
+ * @returns {string}
+ */
+function repoRelativePath(cwd, path, label) {
+  const relativePath = relative(cwd, resolve(cwd, path));
+  if (relativePath.startsWith("..")) throw new Error(`${label} must be inside ${cwd}: ${path}`);
+  return relativePath;
+}
+
+/**
+ * Every declared runtime treated as available. Live discovery (probing a
+ * harness for real exhaustion) is a separate concern this pipeline does not
+ * take on; a campaign that needs it can inject a table row and prune its
+ * `runtimes` catalogue instead.
+ *
+ * @param {Record<string, JsonObject>} runtimes
+ * @returns {Record<string, {available: true, exhaustedUntil: null}>}
+ */
+function availabilityOf(runtimes) {
+  return Object.fromEntries(Object.keys(runtimes).map((id) => [id, { available: true, exhaustedUntil: null }]));
+}
+
+/**
+ * @param {Record<string, JsonObject>} runtimes
+ * @param {string|undefined} id
+ * @returns {string}
+ */
+function modelOf(runtimes, id) {
+  const model = id ? runtimes[id]?.model : undefined;
+  return typeof model === "string" ? model : "";
+}
+
+/**
+ * @param {string[]} riskTiers
+ * @returns {string}
+ */
+function highestOf(riskTiers) {
+  return riskTiers.reduce((highest, tier) => (RISK_TIERS.indexOf(tier) > RISK_TIERS.indexOf(highest) ? tier : highest), RISK_TIERS[0]);
+}
+
+/**
+ * A draft or revise output node (flat `readFiles`/`writeFiles`/`verification`)
+ * turned into the shape `applySizingRules` merges and splits: those fields move
+ * under `taskPacket`, alongside `sizing.mjs`'s own `writeFiles`/`verification`
+ * expectations, while `objective` rides along as a passthrough field a merge
+ * never touches.
+ *
+ * @param {import("./template.mjs").PlanOutputNode} node
+ * @returns {SizedPlanNode}
+ */
+function toSizingNode(node) {
+  return /** @type {SizedPlanNode} */ ({
+    id: node.id,
+    dependsOn: node.dependsOn,
+    taskKind: node.taskKind,
+    riskTier: node.riskTier,
+    objective: node.objective,
+    definitionOfDone: node.definitionOfDone,
+    taskPacket: {
+      readFiles: node.readFiles,
+      writeFiles: node.writeFiles,
+      verification: node.verification,
+    },
+  });
+}
+
+/**
+ * A sized plan node's classification and shape, turned into the contract node
+ * `freezePlan` validates. `riskTier: "low"` gets no gate; `standard` an
+ * advisory one; `high` a blocking one, which `validateGate` requires `major`
+ * in `failOn` for.
+ *
+ * @param {SizedPlanNode} node
+ * @param {string} phase
+ * @param {{worker: string|null, judge: string|null}|undefined} assignment
+ * @returns {JsonObject}
+ */
+function toContractNode(node, phase, assignment) {
+  const riskTier = /** @type {string} */ (node.riskTier);
+  const gate = riskTier === "low"
+    ? false
+    : {
+      review: riskTier === "high" ? "blocking" : "advisory",
+      failOn: riskTier === "high" ? ["major", "critical"] : ["critical"],
+      ...(assignment?.judge ? { runtime: assignment.judge } : {}),
+    };
+  return {
+    id: node.id,
+    type: node.taskKind,
+    phase,
+    dependsOn: node.dependsOn ?? [],
+    ...(assignment?.worker ? { runtime: assignment.worker } : {}),
+    taskPacket: {
+      mode: "execution",
+      objective: node.objective,
+      instructions: [node.objective],
+      readFiles: node.taskPacket.readFiles ?? [],
+      writeFiles: node.taskPacket.writeFiles ?? [],
+      symbols: [],
+      decisions: [],
+      nonGoals: [],
+      verification: node.taskPacket.verification,
+    },
+    definitionOfDone: node.definitionOfDone ?? [],
+    gate,
+  };
+}