faberun 0.3.0

package/src/engine/retry.mjs

@@ -0,0 +1,334 @@
+/**
+ * Retry in place (TECH-SPEC lean v0.3, rule 4 and decision 9.3).
+ *
+ * A retry is the same run and the same node: attempt plus one, in the same run
+ * directory, with the failure attached. Instructions are frozen per run, so the
+ * packet never changes; what changes is the prompt, which carries a bounded
+ * `Previous attempt` section for the worker and for the judge.
+ *
+ * Resume adopts completed work first — an orphaned running node as before, and
+ * a blocking review that never produced a verdict (`judge_unavailable`) is
+ * re-judged from the preserved worker result instead of being reset or
+ * re-dispatched to a worker — and only then re-dispatches ordinary failures.
+ * Two stop boundaries are crossed by an explicit flag alone: a node blocked
+ * with `unknown_effect_reconciled` needs `--reconcile <node>`, and an
+ * exhausted run budget needs `--max-input-tokens <n>`.
+ */
+import { Buffer } from "node:buffer";
+
+/** Heading of the section appended to a retried attempt's worker and judge prompt. */
+const PREVIOUS_ATTEMPT_HEADING = "Previous attempt";
+
+/** Hard ceiling for the whole `Previous attempt` section, in bytes. */
+const PREVIOUS_ATTEMPT_MAX_BYTES = 8 * 1024;
+
+/** Heading under which an operator's answer is rendered inside the section. */
+const OPERATOR_ANSWER_HEADING = "Operator answer";
+
+/**
+ * Node statuses an ordinary resume re-dispatches as attempt plus one.
+ * `blocked` is deliberately absent: only its two error codes have a retry
+ * meaning, and `context_missing` stays terminal.
+ */
+const RETRYABLE_STATUSES = new Set(["failed", "stalled", "exhausted", "canceled"]);
+
+/**
+ * @param {{status?: string, error?: {code?: string}|null}} state
+ * @returns {boolean}
+ */
+function isJudgeUnavailable(state) {
+  return state.status === "blocked" && state.error?.code === "judge_unavailable";
+}
+
+/**
+ * @param {{status?: string, error?: {code?: string}|null}} state
+ * @returns {boolean}
+ */
+function isDependencyFailed(state) {
+  return state.status === "blocked" && state.error?.code === "dependency_failed";
+}
+
+/**
+ * @param {{status?: string, error?: {code?: string}|null}} state
+ * @returns {boolean}
+ */
+export function isUnknownEffectStop(state) {
+  return state.status === "blocked" && state.error?.code === "unknown_effect_reconciled";
+}
+
+/**
+ * @param {{status?: string, error?: {code?: string}|null}} state
+ * @returns {boolean}
+ */
+function isRetryableFailure(state) {
+  return RETRYABLE_STATUSES.has(/** @type {string} */ (state.status)) || isDependencyFailed(state);
+}
+
+/**
+ * The node a `--node` flag names plus every node that transitively depends on
+ * it: a retried dependency re-opens its dependants, so they are part of the
+ * same retry.
+ *
+ * @param {{id: string, dependsOn?: string[]}[]} planNodes
+ * @param {string} nodeId
+ * @returns {Set<string>}
+ */
+function retryTargets(planNodes, nodeId) {
+  const targets = new Set([nodeId]);
+  let grew = true;
+  while (grew) {
+    grew = false;
+    for (const node of planNodes) {
+      if (targets.has(node.id)) continue;
+      if ((node.dependsOn ?? []).some((dependency) => targets.has(dependency))) {
+        targets.add(node.id);
+        grew = true;
+      }
+    }
+  }
+  return targets;
+}
+
+/**
+ * The earliest reset instant recorded among a node's tier-exhaustion
+ * candidates, or null when no candidate carries a parseable `exhaustedUntil`.
+ * Shared by `planResumeRetry`'s hold decision and `supervise`'s waiting state
+ * so the two can never disagree about when an exhausted node is due.
+ *
+ * @param {import("../contract/index.mjs").NodeSnapshot} state
+ * @returns {number|null} epoch milliseconds, or null when nothing is parseable
+ */
+export function earliestTierReset(state) {
+  const candidates = state.routing?.tierExhaustion?.candidates ?? [];
+  const instants = candidates.map((candidate) => Date.parse(candidate.exhaustedUntil ?? "")).filter(Number.isFinite);
+  return instants.length ? Math.min(...instants) : null;
+}
+
+/**
+ * The longest a tier-exhausted node may be held waiting for its tier to
+ * recover before the controller stops waiting. A generation with no recorded
+ * reset instant would otherwise hold forever, and an announced instant can be
+ * arbitrarily far away; both are bounded here. After the cap the named
+ * post-cap transition is a re-dispatch on the current runtime (`retry`, or
+ * `rejudge` for a judge phase), with attention raised so the operator sees that
+ * the wait was abandoned rather than honoured.
+ */
+export const TIER_EXHAUSTION_HOLD_CAP_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * The reason recorded when `TIER_EXHAUSTION_HOLD_CAP_MS` is exceeded. It names
+ * the post-cap transition explicitly so the operator-facing text and the
+ * classification cannot drift.
+ */
+export const TIER_EXHAUSTION_CAP_REASON = "tier-exhaustion hold cap exceeded; post-cap transition re-dispatches on the current runtime";
+
+/**
+ * How long a node has already been held on its tier exhaustion. The block
+ * transition wrote `updatedAt`; an unparseable or absent stamp is treated as
+ * "not yet held" so a snapshot that predates the timestamp cannot be pushed
+ * over the cap on first read.
+ *
+ * @param {import("../contract/index.mjs").NodeSnapshot} state
+ * @returns {number} elapsed milliseconds, never negative
+ */
+export function tierExhaustionHeldMs(state) {
+  const since = Date.parse(state.updatedAt ?? state.startedAt ?? "");
+  return Number.isFinite(since) ? Math.max(0, Date.now() - since) : 0;
+}
+
+/**
+ * Decide, per node, what a resume does with it. Everything classified
+ * `recover` keeps today's recovery behaviour (orphan adoption, re-judge of
+ * finished work, pending re-dispatch). `hold` leaves the persisted state
+ * exactly as it is and reports attention: resetting it would either replay an
+ * unknown effect or re-dispatch work the operator did not ask for.
+ *
+ * @param {{nodes: {id: string, dependsOn?: string[]}[]}} contract
+ * @param {Map<string, import("../contract/index.mjs").NodeSnapshot>} states
+ * @param {{node?: string, reconcile?: string, answer?: string}} [options]
+ * @returns {{actions: Map<string, "recover"|"retry"|"rejudge"|"hold">, attention: {id: string, reason: string}[], targets: Set<string>|null}}
+ */
+export function planResumeRetry(contract, states, options = {}) {
+  // `--answer <node>` narrows the retry exactly like `--node <node>`: the named
+  // node plus every node that transitively depends on it.
+  const targetNode = options.node ?? options.answer;
+  const targets = targetNode ? retryTargets(contract.nodes, targetNode) : null;
+  /** @type {Map<string, "recover"|"retry"|"rejudge"|"hold">} */
+  const actions = new Map();
+  /** @type {{id: string, reason: string}[]} */
+  const attention = [];
+  /** @type {(node: string, state: import("../contract/index.mjs").NodeSnapshot) => "recover"|"retry"|"rejudge"|"hold"} */
+  const classify = (node, state) => {
+    if (isJudgeUnavailable(state)) {
+      // Adoption before retry: the worker result and the verification records
+      // are on disk, so only the arbitration is missing.
+      if (targets && !targets.has(node)) return hold(node, "its unresolved review is outside this retry");
+      return "rejudge";
+    }
+    if (isUnknownEffectStop(state)) {
+      // Stop boundary: only an explicit acknowledgement re-dispatches it.
+      return options.reconcile === node
+        ? "retry"
+        : hold(node, "an unknown workspace effect needs an explicit `resume --reconcile`");
+    }
+    if (state.status === "blocked" && state.error?.code === "context_missing") {
+      // A node the operator answered is dispatchable again; every other
+      // `context_missing` node keeps its terminal boundary.
+      return options.answer === node
+        ? "retry"
+        : "recover";
+    }
+    if (state.status === "blocked" && state.error?.code === "runtime_tier_exhausted") {
+      // A node outside an explicit `--node` retry is held before anything else,
+      // even past the cap: an operator asking for one node must not have the
+      // cap re-dispatch a different one.
+      if (targets && !targets.has(node)) return hold(node, "it is outside the `--node` retry");
+      // The cap bounds the wait: once exceeded, the named post-cap transition
+      // re-dispatches on the current runtime instead of holding forever.
+      if (tierExhaustionHeldMs(state) >= TIER_EXHAUSTION_HOLD_CAP_MS) {
+        attention.push({ id: node, reason: TIER_EXHAUSTION_CAP_REASON });
+        return state.phase === "judge" ? "rejudge" : "retry";
+      }
+      // Hold until the earliest reset the exhausted candidates announced; a
+      // generation with no parseable instant holds until the cap rather than
+      // inventing a deadline. The final candidate is already in the evidence
+      // list, so this reads Phase 1a's record, never `state.error.exhaustedUntil`.
+      const earliest = earliestTierReset(state);
+      if (earliest === null) return hold(node, "no recorded reset time for any exhausted candidate");
+      if (Date.now() < earliest) return hold(node, `earliest recorded reset is ${new Date(earliest).toISOString()}`);
+      // A judge-tier exhaustion keeps its order: rejudge transitions to the
+      // judge phase and preserves the accepted worker result, where a retry
+      // would discard it by re-dispatching a worker.
+      return state.phase === "judge" ? "rejudge" : "retry";
+    }
+    if (!isRetryableFailure(state)) return "recover";
+    if (targets && !targets.has(node)) return hold(node, "it is outside the `--node` retry");
+    return "retry";
+  };
+  /** @type {(id: string, reason: string) => "hold"} */
+  const hold = (id, reason) => {
+    attention.push({ id, reason });
+    return "hold";
+  };
+  for (const node of contract.nodes) {
+    const state = states.get(node.id);
+    if (!state) continue;
+    actions.set(node.id, classify(node.id, state));
+  }
+  // A node blocked on a failed dependency is retried only when the dependency
+  // it waited on is retried too; otherwise it keeps its boundary.
+  for (const node of contract.nodes) {
+    const state = states.get(node.id);
+    if (!state || !isDependencyFailed(state) || actions.get(node.id) !== "retry") continue;
+    const waitedOnRetried = (state.blockedBy ?? []).every((id) => actions.get(id) === "retry" || actions.get(id) === "rejudge" || states.get(id)?.status === "done");
+    if (!waitedOnRetried) {
+      actions.set(node.id, hold(node.id, "the dependency it waited on is not part of this retry"));
+    }
+  }
+  return { actions, attention, targets };
+}
+
+/**
+ * The most recent operator-answer override's text, or null. A second
+ * `--answer` appends rather than replaces, so the newest record is what
+ * surfaces; the older answers stay in `executionOverrides` untouched.
+ *
+ * @param {import("../contract/index.mjs").NodeSnapshot} state
+ * @returns {string|null}
+ */
+function mostRecentOperatorAnswer(state) {
+  const overrides = state.executionOverrides ?? [];
+  for (let index = overrides.length - 1; index >= 0; index -= 1) {
+    const record = /** @type {Record<string, unknown>} */ (overrides[index]);
+    if (record.kind === "operator-answer") {
+      return typeof record.text === "string" ? record.text : null;
+    }
+  }
+  return null;
+}
+
+/**
+ * The bounded `Previous attempt` section for a node about to be re-dispatched:
+ * the error code and message, the most recent operator answer (when one was
+ * supplied), the judge findings, the scope findings, and the failing
+ * verification commands with a bounded output tail.
+ *
+ * @param {import("../contract/index.mjs").NodeSnapshot} state
+ * @returns {string|null} null when the node carries no failure evidence
+ */
+export function renderPreviousAttemptSection(state) {
+  /** @type {string[]} */
+  const parts = [];
+  const attempt = state.attempt ?? 0;
+  // A node that never started an attempt has no failure to carry: its blocked
+  // dependency is already visible in the graph.
+  if (attempt === 0) return null;
+  parts.push(`Attempt ${attempt} failed; this is attempt ${attempt + 1}. The packet is unchanged.`);
+  if (state.error?.code || state.error?.message) {
+    parts.push(`Error: ${state.error?.code ?? "unknown"}${state.error?.message ? ` — ${bounded(state.error.message, 1024)}` : ""}`);
+  }
+  const answer = mostRecentOperatorAnswer(state);
+  if (answer !== null) {
+    parts.push(`${OPERATOR_ANSWER_HEADING}:`);
+    parts.push(bounded(answer, 1024));
+  }
+  const findings = state.gate?.findings ?? [];
+  if (findings.length) {
+    parts.push(`Judge findings (verdict ${state.gate?.verdict ?? "unknown"}, maxSeverity ${state.gate?.maxSeverity ?? "none"}):`);
+    for (const finding of findings) {
+      parts.push(`- [${finding.severity}] ${bounded(finding.description, 1024)}`);
+      if (finding.evidence) parts.push(`  Evidence: ${bounded(finding.evidence, 1024)}`);
+    }
+  }
+  const unexpected = state.scopeFindings?.unexpectedPaths ?? [];
+  if (unexpected.length) parts.push(`Scope findings (paths outside the declared boundary): ${unexpected.map((path) => bounded(path, 256)).join(", ")}`);
+  const failing = (state.verification?.commands ?? []).filter((command) => !command.passed);
+  if (failing.length) {
+    parts.push("Failing verification:");
+    for (const command of failing) {
+      parts.push(`- ${command.argv.join(" ")}`);
+      const last = command.attempts?.at(-1);
+      if (last?.stdout) parts.push(`  stdout tail: ${indent(last.stdout)}`);
+      if (last?.stderr) parts.push(`  stderr tail: ${indent(last.stderr)}`);
+      if (typeof last?.exitCode === "number" && last.exitCode !== 0) parts.push(`  exit code: ${last.exitCode}`);
+    }
+  }
+  if (parts.length === 1) return null;
+  return boundSection([`## ${PREVIOUS_ATTEMPT_HEADING}`, "", ...parts].join("\n"));
+}
+
+/**
+ * Append the section to a regenerated prompt. A prompt that already carries it
+ * (a gate revision re-rendered after a resume) is left alone.
+ *
+ * @param {string} prompt
+ * @param {string|undefined} section
+ * @returns {string}
+ */
+export function appendPreviousAttempt(prompt, section) {
+  if (!section || prompt.includes(`## ${PREVIOUS_ATTEMPT_HEADING}`)) return prompt;
+  return `${prompt}\n\n${section}`;
+}
+
+/**
+ * @param {string} text
+ * @returns {string} the text bounded to the section ceiling, with a marker
+ */
+function boundSection(text) {
+  if (Buffer.byteLength(text, "utf8") <= PREVIOUS_ATTEMPT_MAX_BYTES) return text;
+  const marker = "\n… (previous attempt section truncated)";
+  const room = PREVIOUS_ATTEMPT_MAX_BYTES - Buffer.byteLength(marker, "utf8") - 1;
+  const cut = Buffer.from(text, "utf8").subarray(0, room).toString("utf8");
+  return `${cut}${marker}`;
+}
+
+/** @param {string} text @param {number} maxBytes @returns {string} */
+function bounded(text, maxBytes) {
+  const bytes = Buffer.from(String(text ?? ""), "utf8");
+  return bytes.length <= maxBytes ? String(text) : `${bytes.subarray(0, maxBytes - 1).toString("utf8")}…`;
+}
+
+/** Collapse a persisted output tail onto one indented line. @param {string} text @returns {string} */
+function indent(text) {
+  return bounded(String(text ?? "").replace(/\s+/gu, " ").trim(), 1024);
+}

package/src/engine/review.mjs

@@ -0,0 +1,228 @@
+/**
+ * Judge round arbitration: interpret a returned verdict, decide re-ask versus
+ * settlement, and route what `startJudge` decided.
+ *
+ * `engine/dispatch.mjs` launches the judge invocation and hands the result
+ * here; this module never starts a provider invocation itself. The rejection
+ * paths themselves live in `engine/settle.mjs`, because the control loop
+ * settles too and having them here made the two import each other.
+ */import { parseJudge } from "./prompts.mjs";
+import {
+  clearJudgeReask,
+  judgeReaskOutstanding,
+  markJudgeReask,
+  uncitedRejection,
+} from "./judge-gate.mjs";
+import {
+  JUDGE_UNAVAILABLE_CODE,
+  UNCITED_REJECTION_REASON,
+  invalidJudgeVerdict,
+  reviewMode,
+} from "../contract/review-modes.mjs";
+
+import { errorMessage, excerpt } from "../util.mjs";
+import { appendTransitionEvent, transition } from "./state.mjs";
+import { startJudge } from "./dispatch.mjs";
+import { applyRejection, raiseNodeAttention, settleDone } from "./settle.mjs";
+
+/** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
+/** @typedef {import("../contract/index.mjs").ValidatedNode} ValidatedNode */
+/** @typedef {import("../contract/index.mjs").NodeSnapshot} NodeSnapshot */
+/** @typedef {import("../run/lock.mjs").LockRecord} LockRecord */
+/** @typedef {ReturnType<typeof import("../run/lock.mjs").acquire>} LockHandle */
+/** @typedef {import("./prompts.mjs").JudgeVerdict} JudgeVerdict */
+/** @typedef {import("./lifecycle.mjs").Job} Job */
+
+/** A failed judge envelope gets one bounded re-dispatch, then judge_unavailable. */
+export const JUDGE_MAX_FAILURES = 2;
+
+/** Attention code raised when an advisory review completes without a verdict. */
+const INVALID_JUDGE_OUTPUT_CODE = "invalid_judge_output";
+
+/**
+ * Settle a judge round that produced no usable verdict. The first defect earns
+ * the one bounded re-ask on the node's own bound; once it is spent the review
+ * mode decides, and blocking review never degrades into a pass.
+ *
+ * @param {ValidatedContract} contract
+ * @param {ValidatedNode} node
+ * @param {NodeSnapshot} state
+ * @param {string} runDir
+ * @param {Map<string, Job>|null} running
+ * @param {LockHandle} lock
+ * @param {Map<string, NodeSnapshot>} states
+ * @param {string} campaignPath
+ * @param {string} reason
+ */
+export async function applyJudgeProtocolFailure(contract, node, state, runDir, running, lock, states, campaignPath, reason) {
+  if (judgeReaskOutstanding(state)) {
+    if (reviewMode(node.gate) === "advisory") {
+      // The deterministic verification passed, so the review cannot fail the
+      // node; completing with the defect recorded keeps it visible instead of
+      // silently discarding the review.
+      await settleAdvisoryReview(contract, node, state, runDir, lock, states, campaignPath, invalidJudgeVerdict(reason));
+      await raiseNodeAttention(campaignPath, runDir, state, INVALID_JUDGE_OUTPUT_CODE);
+      return;
+    }
+    // Nothing about the attempt is rewritten: the accepted worker result, the
+    // verification records and the gate state stay exactly as a node awaiting
+    // its judge leaves them, so a retry in place re-judges instead of re-running.
+    transition(runDir, state, "blocked", {
+      phase: "judge",
+      result: state.result,
+      usage: state.usage,
+      error: { code: JUDGE_UNAVAILABLE_CODE, message: excerpt(reason) ?? "judge unavailable" },
+    }, lock);
+    await raiseNodeAttention(campaignPath, runDir, state, JUDGE_UNAVAILABLE_CODE);
+    return;
+  }
+  // The bound rides on the node: the next write — the recovered pending
+  // judge below or the re-ask dispatch's own invocation — persists it with
+  // the transition it belongs to, leaving no gap either way.
+  markJudgeReask(state, reason);
+  if (!running) {
+    // A verdict recovered after controller loss keeps its durable bound:
+    // the drive loop dispatches the one remaining bounded re-ask.
+    transition(runDir, state, "pending", { phase: "judge", gate: null, result: state.result, error: null, blockedBy: [] }, lock);
+    return;
+  }
+  await applyJudgeRound(await startJudge(contract, node, state, runDir, running, state.result, lock, states, campaignPath),
+    contract, node, state, runDir, running, lock, states, campaignPath, state.result);
+}
+
+/**
+ * Settle an advisory gate: the verdict is recorded with its findings and the
+ * node completes, because the deterministic verification already passed. A
+ * verdict that is not a clean pass appends the `gate.advisory` event the run
+ * journal keeps for review outcomes.
+ *
+ * @param {ValidatedContract} contract
+ * @param {ValidatedNode} node
+ * @param {NodeSnapshot} state
+ * @param {string} runDir
+ * @param {LockHandle} lock
+ * @param {Map<string, NodeSnapshot>} states
+ * @param {string} campaignPath
+ * @param {JudgeVerdict} verdict
+ */
+async function settleAdvisoryReview(contract, node, state, runDir, lock, states, campaignPath, verdict) {
+  clearJudgeReask(state);
+  state.gate = verdict;
+  if (verdict.verdict !== "pass") {
+    appendTransitionEvent(runDir, state, state.status, state.status, {
+      type: "gate.advisory",
+      verdict: verdict.verdict,
+      summary: verdict.summary,
+    }, lock);
+  }
+  await settleDone(contract, node, state, runDir, lock, states, campaignPath, { phase: "complete", gate: verdict });
+}
+
+/** Settle a judge whose provider failed its bounded re-dispatches: blocking review blocks with the work preserved; advisory review completes with the defect recorded. @param {ValidatedContract} contract @param {ValidatedNode} node @param {NodeSnapshot} state @param {string} runDir @param {LockHandle} lock @param {Map<string, NodeSnapshot>} states @param {string} campaignPath @param {string} providerMessage */
+export async function settleUnavailableJudge(contract, node, state, runDir, lock, states, campaignPath, providerMessage) {
+  if (reviewMode(node.gate) === "advisory") {
+    await settleAdvisoryReview(contract, node, state, runDir, lock, states, campaignPath, invalidJudgeVerdict(providerMessage));
+    await raiseNodeAttention(campaignPath, runDir, state, INVALID_JUDGE_OUTPUT_CODE);
+    return;
+  }
+  transition(runDir, state, "blocked", {
+    phase: "judge",
+    result: state.result,
+    usage: state.usage,
+    error: { code: JUDGE_UNAVAILABLE_CODE, message: excerpt(providerMessage) ?? "judge unavailable" },
+  }, lock);
+  await raiseNodeAttention(campaignPath, runDir, state, JUDGE_UNAVAILABLE_CODE);
+}
+
+/** Apply a judge verdict: pass settles done; a rejection citing no judgment item id is a judge protocol failure — one durable bounded re-ask, then blocked judge_protocol attention — and never consumes a revision, at any severity. Under advisory review a fail verdict is recorded and the node still completes. @param {ValidatedContract} contract @param {ValidatedNode} node @param {NodeSnapshot} state @param {unknown} result @param {string} runDir @param {LockHandle} lock @param {Map<string, Job>|null} running @param {Map<string, NodeSnapshot>} states @param {string} campaignPath */
+export async function applyJudgeResult(contract, node, state, result, runDir, lock, running, states, campaignPath) {
+  /** @type {JudgeVerdict} */
+  let verdict;
+  try {
+    verdict = parseJudge(String(result ?? ""));
+  } catch (error) {
+    await applyJudgeProtocolFailure(contract, node, state, runDir, running, lock, states, campaignPath, errorMessage(error));
+    return;
+  }
+  state.gate = verdict;
+  state.judgeFailures = 0;
+  const advisory = reviewMode(node.gate) === "advisory";
+  const protocolFailure = verdict.verdict === "fail" && uncitedRejection(verdict, node);
+  if (protocolFailure && judgeReaskOutstanding(state)) {
+    if (advisory) {
+      await settleAdvisoryReview(contract, node, state, runDir, lock, states, campaignPath, verdict);
+      await raiseNodeAttention(campaignPath, runDir, state, "judge_protocol");
+      return;
+    }
+    transition(runDir, state, "blocked", {
+      phase: "judge",
+      gate: verdict,
+      result: state.result,
+      error: { code: "judge_protocol", message: "judge rejection cited no Definition of Done item id after the bounded re-ask" },
+    }, lock);
+    await raiseNodeAttention(campaignPath, runDir, state, "judge_protocol");
+    return;
+  }
+  if (protocolFailure) {
+    markJudgeReask(state, UNCITED_REJECTION_REASON);
+    if (!running) {
+      // A verdict recovered after controller loss keeps its durable bound:
+      // the drive loop dispatches the one remaining bounded re-ask.
+      transition(runDir, state, "pending", { phase: "judge", gate: null, result: state.result, error: null, blockedBy: [] }, lock);
+      return;
+    }
+    await applyJudgeRound(await startJudge(contract, node, state, runDir, running, state.result, lock, states, campaignPath),
+      contract, node, state, runDir, running, lock, states, campaignPath, state.result);
+    return;
+  }
+  clearJudgeReask(state);
+  if (advisory) {
+    await settleAdvisoryReview(contract, node, state, runDir, lock, states, campaignPath, verdict);
+    return;
+  }
+  const shouldFail = verdict.verdict === "fail" && verdict.maxSeverity !== "none"
+    && (node.gate.failOn ?? ["critical"]).includes(verdict.maxSeverity);
+  if (!shouldFail) {
+    await settleDone(contract, node, state, runDir, lock, states, campaignPath, { phase: "complete", gate: verdict });
+    return;
+  }
+  applyRejection(contract, node, state, runDir, running, lock, states, campaignPath, verdict, {
+    code: "revision_cap",
+    label: "gate",
+    phase: "judge",
+  });
+}
+
+/**
+ * Act on what a judge round decided. `startJudge` used to do this itself, which
+ * made dispatch depend on both review policy and settlement; the five callers
+ * all reach both already, so the decision comes back to them and lands here.
+ *
+ * @param {import("./dispatch.mjs").JudgeRound} round
+ * @param {ValidatedContract} contract
+ * @param {ValidatedNode} node
+ * @param {NodeSnapshot} state
+ * @param {string} runDir
+ * @param {Map<string, Job>} running
+ * @param {LockHandle} lock
+ * @param {Map<string, NodeSnapshot>} states
+ * @param {string} campaignPath
+ * @param {unknown} workerResult
+ * @returns {Promise<void>}
+ */
+export async function applyJudgeRound(round, contract, node, state, runDir, running, lock, states, campaignPath, workerResult) {
+  if (round.kind === "rejected") {
+    applyRejection(contract, node, state, runDir, running, lock, states, campaignPath, round.verdict, {
+      code: "mechanical_gate_failed",
+      label: "mechanical-gate",
+    });
+    return;
+  }
+  if (round.kind === "settle") {
+    await settleDone(contract, node, state, runDir, lock, states, campaignPath, {
+      phase: "complete",
+      result: workerResult,
+      gate: round.gate,
+    });
+  }
+}