faberun 0.30.0 → 0.32.0

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

package/src/engine/aux-admission.mjs

@@ -0,0 +1,124 @@
+/**
+ * Admission for the paid spawns that start outside the scheduler's dispatch
+ * pass: the node's own judge after its verification gate, the bounded judge
+ * re-ask, and the gate revision. `capacity.mjs`'s `admissionPass` judges the
+ * spawns the dispatch pass issues itself and owns the pass's reservations;
+ * these three start inside a settlement or a stall handler, take over the
+ * slot the node already holds, and need one yes/no judgment against the live
+ * running set. On a refusal the node hands back to the scheduler -- the one
+ * place that knows when the run stops being full -- and the verdict is
+ * recorded on the node's event journal.
+ *
+ * Measured 2026-09-29 (ACHADOS-PRODUTO achado 2): these spawns ran with no
+ * per-runtime check, and two invocations of one runtime were seen alive at
+ * once under a contract declaring `maxParallel: 1`. The judgment here is the
+ * dispatch pass's own rule (`runtimeHasCapacity`) over the same running set
+ * the spawn is about to join, plus the pass's global bound: the settle window
+ * keeps `running` under `maxParallel` while a settlement spawns, and the
+ * stall-handler re-ask -- the one aux spawn outside any settle window -- takes
+ * the same check instead of trusting that.
+ */
+import { quotaHeldRuntimes, runningPerRuntime, runtimeHasCapacity } from "./capacity.mjs";
+import { routeRuntimeForState } from "./failover.mjs";
+import { startJudge } from "./dispatch.mjs";
+import { appendTransitionEvent, transition } from "./state.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("./dispatch.mjs").JudgeRound} JudgeRound */
+/** @typedef {import("./process.mjs").Job} Job */
+
+/**
+ * One auxiliary-spawn admission: may this spawn start right now? The spawn
+ * joins the caller's `running` map, so that map is what is judged: the
+ * contract's global `maxParallel`, and the routed runtime's `maxConcurrent`
+ * over the attempts it already holds. A runtime some node is waiting out a
+ * quota reset on refuses too, exactly as a dispatch pass would. A closed job
+ * still inside its settle window holds no live process and is not counted:
+ * the slot it holds is this node's own, and this spawn is the reason the slot
+ * existed.
+ *
+ * @param {ValidatedContract} contract
+ * @param {ValidatedNode} node
+ * @param {NodeSnapshot} state
+ * @param {Map<string, Job>} running the live dispatch map the spawn would join
+ * @param {Map<string, NodeSnapshot>} states
+ * @param {"worker"|"judge"} role
+ * @param {number} [now] epoch milliseconds
+ * @returns {{admitted: boolean, runtimeId: string, reason: string|null}}
+ */
+export function auxSpawnAdmission(contract, node, state, running, states, role, now = Date.now()) {
+  const runtime = routeRuntimeForState(contract, node, state, role);
+  if (running.size >= contract.maxParallel) {
+    return { admitted: false, runtimeId: runtime.id, reason: `run holds ${running.size} of maxParallel ${contract.maxParallel} slots` };
+  }
+  const held = quotaHeldRuntimes(states.values(), now);
+  if (!runtimeHasCapacity(runtime.id, contract, runningPerRuntime(running.values()), held)) {
+    return {
+      admitted: false,
+      runtimeId: runtime.id,
+      reason: held.has(runtime.id)
+        ? `runtime ${runtime.id} is waiting out a quota reset`
+        : `runtime ${runtime.id} holds its maxConcurrent of ${contract.runtimes[runtime.id]?.maxConcurrent}`,
+    };
+  }
+  return { admitted: true, runtimeId: runtime.id, reason: null };
+}
+
+/**
+ * Record a refused auxiliary spawn on the node's event journal: the verdict
+ * the deferral is gated on, read back by the phase proof and by an operator
+ * asking why a node went back to pending without a new attempt. The event is
+ * written only for a refusal, so its existence is the verdict. Measured
+ * 2026-10-02: `appendTransitionEvent` builds the event from the node snapshot
+ * and its own fields win every colliding name -- the event's `runtime` and
+ * `summary` are the state's, not ours -- so the refusal rides the one field
+ * the transition leaves unset: `error`, with the node's own error null
+ * (the deferral parks nothing on the node).
+ *
+ * @param {string} runDir
+ * @param {NodeSnapshot} state
+ * @param {string} from the node status the refusal found
+ * @param {LockHandle|null} lock
+ * @param {"worker"|"judge"} role
+ * @param {{runtimeId: string, reason: string|null}} admission
+ */
+export function recordAuxRefusal(runDir, state, from, lock, role, admission) {
+  appendTransitionEvent(runDir, state, from, "pending", {
+    type: "aux.admission",
+    role,
+    error: { code: "aux_spawn_refused", message: admission.reason ?? "aux spawn refused" },
+  }, lock);
+}
+
+/**
+ * The judge a settlement starts itself: admit it against the live running
+ * set, and on a refusal hand the node back to the scheduler as a pending
+ * judge with its accepted result intact -- the drive loop dispatches it
+ * through the ordinary admission pass once the runtime frees. Returns what
+ * `startJudge` would have, so the caller's `applyJudgeRound` decides nothing
+ * new: a refused round is already parked on the node.
+ *
+ * @param {ValidatedContract} contract
+ * @param {ValidatedNode} node
+ * @param {NodeSnapshot} state
+ * @param {string} runDir
+ * @param {Map<string, Job>} running
+ * @param {Map<string, NodeSnapshot>} states
+ * @param {LockHandle} lock
+ * @param {string} campaignPath
+ * @returns {Promise<JudgeRound>}
+ */
+export async function auxJudgeRound(contract, node, state, runDir, running, states, lock, campaignPath) {
+  const admission = auxSpawnAdmission(contract, node, state, running, states, "judge");
+  if (!admission.admitted) {
+    const from = state.status;
+    transition(runDir, state, "pending", { phase: "judge", error: null, blockedBy: [] }, lock);
+    recordAuxRefusal(runDir, state, from, lock, "judge", admission);
+    return { kind: "refused" };
+  }
+  return startJudge(contract, node, state, runDir, running, state.result, lock, states, campaignPath);
+}

package/src/engine/capacity.mjs

@@ -11,6 +11,25 @@
  * measured 2026-09-20: `maxParallel` was the one concurrency knob, global to
  * the run; nothing reduced dispatch to a provider that had just refused a
  * sibling on quota, and 14 of 58 stored contracts ran with maxParallel 2.
+ *
+ * measured 2026-09-29: this gate was consulted by the scheduler's own
+ * dispatches only, and a run declaring `maxParallel: 1` and `maxConcurrent: 1`
+ * on each role's runtime was measured with a judge and a sibling's worker
+ * alive at once -- peak 2, one process per role, two on the single runtime
+ * (`test/engine/max-parallel.test.mjs`). The slot a node's closed job had
+ * freed was spendable while the node was still mid-flight.
+ *
+ * F5 admission (2026-10-02): the scheduler now counts a node from before its
+ * spawn until its settle completes (`admissionHold`, fed by the settle window
+ * in `scheduler.mjs`), which closes the freed-slot race for every spawn the
+ * scheduler issues. The dispatch pass opens its turn with `admissionPass`,
+ * which folds the live jobs, the settle window and the pass's own
+ * reservations into one judgment per node. The judge a settlement starts
+ * itself, the bounded re-ask
+ * (`review.mjs`) and the gate revision (`settle.mjs` `applyRejection`) still
+ * spawn with no call here: the node's own settle-window hold keeps the global
+ * `maxParallel` true while they run, but their per-runtime ceiling is not
+ * re-checked -- wiring those spawns through this gate is the follow-up node's.
  */
 
 /** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
@@ -33,6 +52,65 @@ export function runningPerRuntime(running) {
   return counts;
 }
 
+/**
+ * The admission a dispatch pass judges a spawn against: every attempt holding
+ * a run slot right now. A live job holds one, and so does a closed job whose
+ * settlement has not finished -- a node whose worker exited but whose
+ * controller verification, judge round or integration is still running keeps
+ * the global slot and the runtime slot its dispatch reserved, because the
+ * judge that settlement is about to start is the reason the slot existed.
+ * Releasing at close instead is the measured excess (2026-09-29, achado 2 of
+ * ACHADOS-PRODUTO.md): two workers alive on one runtime under `maxParallel:
+ * 1`, and a sibling dispatched while the first node sat blocked in its
+ * verification gate.
+ *
+ * @param {Map<string, {runtime: {id: string|null}}>} running live jobs the tick is holding
+ * @param {Map<string, {runtime: {id: string|null}}>} settling closed jobs whose settlement has not finished
+ * @returns {{count: number, perRuntime: Map<string, number>}} the global slot
+ *   count and the per-runtime counts; the dispatch pass grows both as it
+ *   reserves, exactly as it grew `runningPerRuntime`'s map before
+ */
+export function admissionHold(running, settling) {
+  const holders = [...running.values(), ...settling.values()];
+  return { count: holders.length, perRuntime: runningPerRuntime(holders) };
+}
+
+/**
+ * One dispatch pass's admission: the slots the contract's `maxParallel` still
+ * grants, judged against every attempt holding one -- the live jobs plus the
+ * closed jobs still inside their settle window -- and the per-runtime
+ * reservation the pass takes as it dispatches. `take` is consulted per node
+ * and refuses a runtime a sibling is waiting out a quota reset on, a runtime
+ * at its `maxConcurrent`, and one already holding its share of this pass's
+ * reservations; on success it reserves the slot in the same breath, because a
+ * check without its reservation would admit two nodes on one judgment. A
+ * spawn the settlement starts itself (the node's judge) runs inside the
+ * node's own held slot and never reaches here.
+ *
+ * @param {ValidatedContract} contract
+ * @param {Map<string, {runtime: {id: string|null}}>} running live jobs the tick is holding
+ * @param {Map<string, {runtime: {id: string|null}}>} settling closed jobs whose settlement has not finished
+ * @param {Map<string, NodeSnapshot>} states
+ * @returns {{slots: number, take: (runtimeId: string) => boolean}} the free
+ *   slot count, read once per pass, and the per-node gate
+ */
+export function admissionPass(contract, running, settling, states) {
+  const hold = admissionHold(running, settling);
+  const held = quotaHeldRuntimes(states.values(), Date.now());
+  return {
+    slots: contract.maxParallel - hold.count,
+    /**
+     * @param {string} runtimeId
+     * @returns {boolean}
+     */
+    take: (runtimeId) => {
+      if (!runtimeHasCapacity(runtimeId, contract, hold.perRuntime, held)) return false;
+      hold.perRuntime.set(runtimeId, (hold.perRuntime.get(runtimeId) ?? 0) + 1);
+      return true;
+    },
+  };
+}
+
 /**
  * Runtimes some node is waiting to use again after a provider exhaustion:
  * the node's current routing override still has a `backoffUntil` in the

package/src/engine/dispatch.mjs

@@ -4,15 +4,22 @@
  * record the invocation intent before a token is spent.
  *
  * It decides nothing about outcomes. `startJudge` runs the mechanical gate and
- * returns what it found -- `rejected`, `settle` or `dispatched` -- for the
- * caller to act on. It used to call `applyRejection` and `settleDone` itself,
- * which made dispatch depend on review policy and on settlement, and that is
- * the shape that kept `engine/` a web instead of a stack.
+ * returns what it found -- `rejected`, `refused`, `settle` or `dispatched` --
+ * for the caller to act on. It used to call `applyRejection` and `settleDone`
+ * itself, which made dispatch depend on review policy and on settlement, and
+ * that is the shape that kept `engine/` a web instead of a stack.
+ *
+ * Every new paid dispatch is also admitted through the campaign's optional
+ * reserve (ADR 0011) before the provider starts; the admission decision lives
+ * in `reserve-admission.mjs`, while the release and the reconciliation
+ * against the real charge stay here because the reservation lives exactly as
+ * long as the call. One-turn result
+ * materialization continues an already-running session and stays on its
+ * existing path.
  */
-import { JUDGE_SCHEMA, appendSandboxNotice, judgePrompt } from "./prompts.mjs";
+import { JUDGE_SCHEMA, appendSandboxNotice, judgePrompt, splitPreviousAttemptSection } from "./prompts.mjs";
 import { LockLostError } from "../run/lock.mjs";
 import { TOOL_OUTPUT_LIMIT_BYTES } from "../harnesses/exec-jsonl/index.mjs";
-import { appendPreviousAttempt } from "./retry.mjs";
 import {
   RESULT_MATERIALIZATION_PROMPT_HEADER,
   attemptWorkerResultPath,
@@ -30,16 +37,18 @@ import { captureWorkspaceScope, captureWorkspaceSnapshot } from "../repo/workspa
 import { deterministicGate, judgeReaskReason, judgeRequired, judgeSkippedByScope } from "./judge-gate.mjs";
 import { emptyScope, persistedScopeBoundary, workerScope } from "./scope.mjs";
 import { hasOperationIntent, hasOperationSettlement, operationNeedsRecovery, operationNextState, persistInvocationIntent, providerReceipts, settleInvocation } from "../run/operations.mjs";
-import { invocationCost, invocationUsage } from "../run/usage.mjs";
+import { invocationCost, invocationUsage, priceUsage } from "../run/usage.mjs";
 import { logPaths, startProcess } from "./process.mjs";
 import { readBoundedTail } from "./transcript.mjs";
 import { mkdirSync, statSync } from "node:fs";
+import { reconcileCampaignReservation, releaseCampaignReservation } from "../campaign/reserve.mjs";
 import { READ_BYTE_LIMIT, READ_LINE_LIMIT, harnessCapabilities, normalizeProviderResult, writesWorkspace } from "../harnesses/index.mjs";
 import { writeJsonAtomic } from "../run/store.mjs";
 import { judgeReaskInstruction, reviewMode } from "../contract/review-modes.mjs";
 import { isSameProviderReviewPair } from "../contract/judge-independence.mjs";
 import { previousAttemptRuntimeId, routeRuntimeForState, runtimeSnapshot } from "./failover.mjs";
 import { fingerprintRuntime, forceFreshSession, phaseInvocationPlan } from "./phase-session.mjs";
+import { releaseReservation, reserveAdmission } from "./reserve-admission.mjs";
 
 /** @typedef {import("./phase-session.mjs").SessionPolicy} SessionPolicy */
 import { transition, writeNode } from "./state.mjs";
@@ -50,8 +59,12 @@ import { transition, writeNode } from "./state.mjs";
  * `settle`: the gate passed and no judgment item needs arbitrating.
  * `dispatched`: a judge is running (or failed to start and the node is already
  * marked failed).
+ * `refused`: the dispatch admission declined the new judge dispatch -- the
+ * campaign reserve cannot hold it, or the campaign record cannot be read or
+ * validated; the node is
+ * already parked blocked and no judge will run this round.
  *
- * @typedef {{kind: "rejected", verdict: JudgeVerdict}|{kind: "settle", gate: JudgeVerdict|null}|{kind: "dispatched"}} JudgeRound
+ * @typedef {{kind: "rejected", verdict: JudgeVerdict}|{kind: "settle", gate: JudgeVerdict|null}|{kind: "dispatched"}|{kind: "refused"}} JudgeRound
  */
 /** @typedef {import("./prompts.mjs").JudgeVerdict} JudgeVerdict */
 
@@ -232,6 +245,41 @@ function ensureAttemptWorkspace(contract, node, state, runDir, lock) {
   writeNode(runDir, state, lock);
   return worktree.path;
 }
+/**
+ * The final assembly every dispatched prompt goes through: the stable
+ * instruction sections — the caller's stable appends, run on the stable
+ * remainder (the worker's sandbox notice and result-file protocol, the
+ * judge's re-ask instruction) — precede the variable previous-attempt
+ * state, so the cacheable prefix survives across attempts. A base that
+ * already carries the section (a candidate reused from an earlier attempt)
+ * has it lifted out and re-appended last; a base without one gets the state's
+ * own section appended, and a state that carries none appends nothing. When
+ * both are present the state's section wins: an embedded one is the stale
+ * copy the reused candidate carries, from an earlier record than
+ * `state.previousAttempt`, and it is lifted out rather than re-appended. The
+ * append is a plain join, not `appendPreviousAttempt`: that helper refuses
+ * any base carrying a `Previous attempt` markdown heading — the same false
+ * positive the splitter just learned to see through, since a packet may
+ * legitimately head its own instructions `## Previous attempt notes:` — and
+ * silently dropped the state's retry record on exactly those prompts. The
+ * splitter guarantees the stable remainder carries no lifted record, so the
+ * join cannot double-append. The 64 KiB dispatch budget is enforced by the
+ * caller right after this returns, on the assembled prompt.
+ *
+ * @param {string} basePrompt
+ * @param {{sandbox?: (prompt: string) => string, protocol?: (prompt: string) => string, stable?: (prompt: string) => string, section?: string}} assembly
+ * @returns {string}
+ */
+export function assembleDispatchPrompt(basePrompt, { sandbox, protocol, stable, section } = {}) {
+  const { stable: head, section: embedded } = splitPreviousAttemptSection(basePrompt);
+  let ordered = head;
+  if (sandbox) ordered = sandbox(ordered);
+  if (protocol) ordered = protocol(ordered);
+  if (stable) ordered = stable(ordered);
+  const variable = section ?? embedded;
+  return variable ? `${ordered}\n\n${variable}` : ordered;
+}
+
 /**
  * @param {ValidatedContract} contract
  * @param {ValidatedNode} node
@@ -261,17 +309,20 @@ export function startWorker(contract, node, state, runDir, running, prompt, lock
   }
   const runtime = routeRuntimeForState(contract, node, state, "worker");
   const phasePlan = phaseInvocationPlan(contract, node, state, runDir, "worker", prompt, sessionPolicy);
-  // The previous-attempt section still has to survive on a retried attempt,
-  // so it is appended to the resolved prompt rather than the candidate handed
-  // to phaseInvocationPlan.
-  phasePlan.prompt = appendPreviousAttempt(phasePlan.prompt, state.previousAttempt);
-  // The resolved worker's sandbox is a dispatch-time fact, not a packet one.
-  phasePlan.prompt = appendSandboxNotice(phasePlan.prompt, runtime);
   // The worker prompt directs the provider to write the canonical result file;
   // make sure the directory exists before the provider is asked to.
   const resultPath = attemptWorkerResultPath(runDir, node.id, workspace);
   mkdirSync(dirname(resultPath), { recursive: true });
-  const effectivePrompt = workerProtocolPrompt(phasePlan.prompt, resultPath, writesWorkspace(runtime));
+  // The resolved worker's sandbox is a dispatch-time fact, not a packet one,
+  // and the previous-attempt section has to survive on a retried attempt.
+  // Both go through the shared assembly: stable instructions (packet prompt,
+  // sandbox notice, result-file protocol) precede the variable section, which
+  // is lifted out of a base that already carries one and re-appended last.
+  const effectivePrompt = assembleDispatchPrompt(phasePlan.prompt, {
+    sandbox: (ordered) => appendSandboxNotice(ordered, runtime),
+    protocol: (ordered) => workerProtocolPrompt(ordered, resultPath, writesWorkspace(runtime)),
+    section: state.previousAttempt,
+  });
   const paths = logPaths(runDir, node.id, "worker", state.attempt);
   if (Buffer.byteLength(effectivePrompt, "utf8") > 64 * 1024) {
     transition(runDir, state, "failed", { phase: "worker", error: { code: "worker_prompt_too_large", message: "worker prompt exceeds 65536 bytes" } }, lock);
@@ -323,6 +374,11 @@ export function startWorker(contract, node, state, runDir, running, prompt, lock
   state.error = null;
   state.scope = emptyScope(boundary);
   writeNode(runDir, state, lock);
+  const admission = reserveAdmission(campaignPath, state, basename(runDir), node.id, "worker");
+  if (admission.refused) {
+    transition(runDir, state, "blocked", { phase: "worker", error: admission.error }, lock);
+    return;
+  }
   try {
     const job = startProcess({
       contract, node, state, runtime, workspace, prompt: effectivePrompt, paths, phase: "worker",
@@ -336,7 +392,7 @@ export function startWorker(contract, node, state, runDir, running, prompt, lock
         stampInvocation(invocation, contract, node, runtime, state, runDir, "worker", phasePlan.mode, phasePlan.continuationId);
         invocation.snapshotPath = snapshotPath;
         currentJob.scopeBaseline = baseline;
-        persistInvocation(runDir, state, invocation, currentJob, lock);
+        persistInvocation(runDir, state, invocation, currentJob, lock, campaignPath, admission.reservation);
         persistInvocationIntent(runDir, invocation, {
           nodeId: node.id,
           role: "worker",
@@ -351,6 +407,7 @@ export function startWorker(contract, node, state, runDir, running, prompt, lock
     transition(runDir, state, "running", { phase: "worker", runtime, error: null }, lock);
     running.set(node.id, job);
   } catch (error) {
+    releaseReservation(campaignPath, admission.reservation);
     const invocation = state.invocations?.at(-1);
     if (invocation && hasOperationIntent(runDir, invocation.id) && operationNeedsRecovery(runDir, invocation.id)) {
       settleInvocation(runDir, invocation, {
@@ -527,18 +584,31 @@ export async function startJudge(contract, node, state, runDir, running, workerR
   if (previousInvocation && hasOperationSettlement(runDir, previousInvocation.id)) {
     settleInvocation(runDir, previousInvocation, { nextState: operationNextState(state) });
   }
+  const admission = reserveAdmission(campaignPath, state, basename(runDir), node.id, "judge");
+  if (admission.refused) {
+    transition(runDir, state, "blocked", { phase: "judge", error: admission.error }, lock);
+    return { kind: "refused" };
+  }
   try {
-    const prompt = `${judgePrompt(node, workerResult, {
+    const prompt = judgePrompt(node, workerResult, {
       diff: state.scope?.changedPaths,
       verification: state.verification,
       deterministic: results,
       scopeFindings: state.scopeFindings,
       previousAttempt: state.previousAttempt,
-    })}${reask ? judgeReaskInstruction(reaskReason) : ""}`;
+    });
     const phasePlan = phaseInvocationPlan(contract, node, state, runDir, "judge", prompt);
-    // judgePrompt already carries the section when phaseInvocationPlan reuses
-    // that candidate; appendPreviousAttempt is a no-op then.
-    phasePlan.prompt = appendPreviousAttempt(phasePlan.prompt, state.previousAttempt);
+    // The same ordering invariant as the worker prompt: the variable section
+    // stays the trailing block, lifted out of a reused candidate and
+    // re-appended last — byte-stable when judgePrompt already trailed it. The
+    // re-ask instruction rides the stable remainder like any other stable
+    // append: appended to the raw base instead, it landed after the trailing
+    // section and the assembly's state-section replacement dropped it with
+    // the lifted block — a re-asked judge dispatched without its instruction.
+    phasePlan.prompt = assembleDispatchPrompt(phasePlan.prompt, {
+      stable: reask ? (ordered) => `${ordered}${judgeReaskInstruction(reaskReason)}` : undefined,
+      section: state.previousAttempt,
+    });
     if (Buffer.byteLength(phasePlan.prompt, "utf8") > 64 * 1024) {
       const error = /** @type {Error & {code: string}} */ (new Error("judge prompt exceeds 65536 bytes"));
       error.code = "judge_prompt_too_large";
@@ -571,7 +641,7 @@ export async function startJudge(contract, node, state, runDir, running, workerR
         // worker and a judge, and this field carries no persisted shape of
         // its own that a judge borrowing it would have to match.
         currentJob.scopeBaseline = judgeBaseline;
-        persistInvocation(runDir, state, invocation, currentJob, lock);
+        persistInvocation(runDir, state, invocation, currentJob, lock, campaignPath, admission.reservation);
         persistInvocationIntent(runDir, invocation, {
           nodeId: node.id,
           role: "judge",
@@ -585,6 +655,7 @@ export async function startJudge(contract, node, state, runDir, running, workerR
     transition(runDir, state, "running", { phase: "judge", runtime }, lock);
     running.set(node.id, job);
   } catch (error) {
+    releaseReservation(campaignPath, admission.reservation);
     const invocation = state.invocations?.at(-1);
     if (invocation && hasOperationIntent(runDir, invocation.id) && operationNeedsRecovery(runDir, invocation.id)) {
       settleInvocation(runDir, invocation, {
@@ -604,8 +675,12 @@ export async function startJudge(contract, node, state, runDir, running, workerR
  * @param {Invocation} invocation
  * @param {Job} job
  * @param {LockHandle} lock
+ * @param {string} [campaignPath] absent when the call took no admission
+ * @param {import("../campaign/reserve.mjs").Reservation|null} [reservation] the
+ *   hold this dispatch was admitted under (ADR 0011); reconciled with the
+ *   charge that actually arrived, or released when the call ended with none
  */
-function persistInvocation(runDir, state, invocation, job, lock) {
+function persistInvocation(runDir, state, invocation, job, lock, campaignPath, reservation) {
   state.invocations = [...(state.invocations ?? []), invocation];
   state.updatedAt = invocation.updatedAt;
   writeNode(runDir, state, lock);
@@ -636,6 +711,24 @@ function persistInvocation(runDir, state, invocation, job, lock) {
       state.costUsd = invocationCost(state);
       state.updatedAt = closed.updatedAt;
       writeNode(runDir, state, lock);
+      if (campaignPath && reservation) {
+        // The close envelope carries raw counters -- the priced charge only
+        // exists once settlement prices it. `priceUsage` is the same pure
+        // function the settlement ledger runs over the same transcript, so
+        // the reservation reconciles against the amount the invocation will
+        // carry rather than a second derivation of it. A charge the envelope
+        // cannot price releases the hold: the reserve gates new dispatches,
+        // and the measured truth stays in the usage ledger.
+        const charge = priceUsage(job.runtime, usage, typeof costUsd === "number" ? costUsd : null).costUsd;
+        try {
+          if (typeof charge === "number") reconcileCampaignReservation(campaignPath, reservation.id, charge);
+          else releaseCampaignReservation(campaignPath, reservation.id);
+        } catch {
+          // A hold that cannot settle stays visible in `readCampaignReserve`
+          // until an operator releases it; the node's own settlement must
+          // never fail for the campaign-level ledger.
+        }
+      }
       settleInvocation(runDir, completed, {
         status: envelopeStatus,
         usage,

package/src/engine/failure-cause.mjs

@@ -0,0 +1,59 @@
+/**
+ * The cause a failure that would fire a repair trigger failed for, drawn from
+ * a fixed vocabulary.
+ *
+ * The reauthor widens a refused packet and its round budget bounds only one
+ * invocation; what lets a later trigger refuse to repeat a repair that already
+ * ran to no effect is the durable record of which cause fired, on which node,
+ * at which artifact version -- the same cause on the same node and artifact
+ * version must never fire indefinite calls. The classes are read from the
+ * refused packet's own grants: a missing entry granted nowhere is a read gap,
+ * one readable but not writable is a write gap, and prose is requirement
+ * ambiguity, which no widening repairs and which becomes a durable question
+ * instead of another discovery round.
+ */
+
+/** The cause vocabulary `classifyFailureCause` draws from. */
+export const FAILURE_CAUSE_CLASSES = ["missing_read_scope", "missing_write_scope", "ambiguous_requirement", "unclassified"];
+
+/** One classified failure: the key a repair trigger is recorded under. */
+/** @typedef {{cause: string, node: string, artifactVersion: string|null}} FailureCause */
+
+/**
+ * A missing-context entry naming a path rather than prose: a path separator,
+ * or an extension at the end. `src/extra.mjs` and `README.md` are paths;
+ * "clearer acceptance criteria" is not.
+ */
+const PATH_LIKE = /[/\\]|\.[A-Za-z][A-Za-z0-9]{0,7}$/;
+
+/**
+ * Classify the failure of a node a reauthor would fire on -- a packet refused
+ * on `context_missing`. Ambiguity dominates, then read gaps: a discovery pass
+ * that cannot settle what is being asked cannot spend its budget usefully. A
+ * refusal naming nothing classifiable is recorded as `unclassified`, never
+ * dropped.
+ *
+ * @param {import("../contract/index.mjs").ValidatedNode} node
+ * @param {import("../contract/index.mjs").NodeSnapshot} state
+ * @returns {FailureCause}
+ */
+export function classifyFailureCause(node, state) {
+  const refused = /** @type {{missingContext?: string[]}|null|undefined} */ (state.result);
+  const missingContext = Array.isArray(refused?.missingContext) ? refused.missingContext : [];
+  const artifactVersion = state.packetHash ?? null;
+  if (missingContext.length === 0) return { cause: "unclassified", node: node.id, artifactVersion };
+  const read = new Set(node.taskPacket.readFiles ?? []);
+  const write = new Set(node.taskPacket.writeFiles ?? []);
+  let ambiguous = false;
+  let readGap = false;
+  let writeGap = false;
+  for (const entry of missingContext) {
+    if (typeof entry !== "string" || !PATH_LIKE.test(entry)) ambiguous = true;
+    else if (!read.has(entry) && !write.has(entry)) readGap = true;
+    else if (!write.has(entry)) writeGap = true;
+  }
+  let cause = "missing_read_scope";
+  if (writeGap && !readGap) cause = "missing_write_scope";
+  if (ambiguous) cause = "ambiguous_requirement";
+  return { cause, node: node.id, artifactVersion };
+}

package/src/engine/lifecycle.mjs

@@ -55,7 +55,8 @@ import {
   workerResultPath,
 } from "./result-file.mjs";
 import { canReuseResultEvidence, checkResultMaterializationScope, checkWorkerScope, recordScopeFinding, sourceWorkerRuntime } from "./scope.mjs";
-import { startJudge, startMechanicalGate, startResultMaterialization } from "./dispatch.mjs";
+import { startMechanicalGate, startResultMaterialization } from "./dispatch.mjs";
+import { auxJudgeRound } from "./aux-admission.mjs";
 import { raiseNodeAttention, settleDone } from "./settle.mjs";
 import { applyRejection, applyVerificationFailure } from "./settle.mjs";
 import { emitNodeAdvisories } from "./notify-queue.mjs";
@@ -591,7 +592,7 @@ export async function finalizeClosedJobs(contract, runDir, states, closed, lock,
       }
       if (job.scopeViolation) recordScopeFinding(runDir, state, lock);
       const round = job.node.gate.enabled
-        ? await startJudge(contract, job.node, state, runDir, running, workerResult, lock, states, campaignPath)
+        ? await auxJudgeRound(contract, job.node, state, runDir, running, states, lock, campaignPath)
         : await startMechanicalGate(contract, job.node, state);
       await applyJudgeRound(round, contract, job.node, state, runDir, running, lock, states, campaignPath, workerResult);
       continue;