faberun 0.30.0 → 0.31.0

package/src/engine/scheduler.mjs

@@ -8,7 +8,7 @@ import {
 } from "./review.mjs";
 import { CONTRACT_VERSION, PROTOCOL_SCHEMA_VERSION } from "../harnesses/index.mjs";
 import { routeRuntimeForState, routingBackoffActive } from "./failover.mjs";
-import { quotaHeldRuntimes, runningPerRuntime, runtimeHasCapacity } from "./capacity.mjs";
+import { admissionPass } from "./capacity.mjs";
 
 import {
   bootstrapAttemptPath,
@@ -45,6 +45,7 @@ import { validateContractForLaunch } from "../campaign/chain.mjs";
 import { finalVerificationCommands, gateProofTimeoutMs, sharedVerificationCommands } from "../contract/final-verification.mjs";
 import { startJudge, startWorker } from "./dispatch.mjs";
 import { raiseNodeAttention } from "./settle.mjs";
+import { createSettlementOverlap } from "./settlement-overlap.mjs";
 import { HUMAN_STEP_ERROR_CODE, humanStepAttentionMessage } from "../contract/human-step.mjs";
 import { assertEnvironmentReady, captureRunIdentity, createRunMetadata, serializableContract, statesFingerprint } from "./run-identity.mjs";
 import { blockDependents, runtimeAssignments } from "./assignment.mjs";
@@ -429,17 +430,24 @@ export async function driveRun(contract, runDir, states, campaign, lock, sourceI
   // tick's critical path so an eligible sibling still dispatches into a free
   // slot while this node's own invocation has already exited. A node's own
   // steps stay ordered because only one settlement per node is ever in flight
-  // (see the dispatch loop below); a *different* node's settlement is queued
-  // behind whichever one is already running (`settlementQueue`), not run
-  // alongside it -- `finalizeClosedJobs` shares state a concurrent second call
-  // would corrupt: the phase-continuation selection that picks at most one
-  // live node to carry a session forward, and `repo/integrate.mjs`'s one
-  // candidate ref and worktree per run. Only *dispatching a sibling* skips
-  // ahead of a node's settlement; two nodes' settlements never interleave.
-  /** @type {Map<string, Promise<void>>} */
-  const pendingSettlements = new Map();
-  /** @type {Promise<void>} */
-  let settlementQueue = Promise.resolve();
+  // (see the dispatch loop below). Different nodes' settlements overlap in
+  // exactly one place, their verification proofs (`parkDuringProof` in
+  // `engine/settlement-overlap.mjs`), and nowhere else: the sections between
+  // proofs run one at a time, because `finalizeClosedJobs` shares state a
+  // concurrent second call would corrupt -- the dispatch decisions that count
+  // `running` against `maxParallel`, the phase-continuation selection that
+  // picks at most one live node to carry a session forward, and
+  // `repo/integrate.mjs`'s one candidate ref and worktree per run. Only
+  // *dispatching a sibling* otherwise skips ahead of a node's settlement.
+  const settlements = createSettlementOverlap();
+  const pendingSettlements = settlements.pending;
+  // F5 admission's settle window: nodes whose job closed but whose settlement
+  // has not finished still hold the global and runtime slot their dispatch
+  // reserved. Released when the settlement itself settles, not at close --
+  // released at close, a sibling took the slot during the node's verification
+  // gate and a judge ran on top of it (2026-09-29, achado 2, peak 2 under
+  // `maxParallel: 1`; judged by `admissionPass` in capacity.mjs).
+  const settling = settlements.settling;
   let canceled = false;
   const cancel = () => { canceled = true; };
   process.once("SIGINT", cancel);
@@ -459,57 +467,12 @@ export async function driveRun(contract, runDir, states, campaign, lock, sourceI
     .map((state) => ({ nodeId: state.id, budgetBasis: nodeBudgetBasisMs(contract, /** @type {ValidatedNode} */ (heartbeatNodes.get(state.id))) }));
   // A programmer error surfacing inside a background settlement must still
   // crash the whole run, exactly as an unguarded `await finalizeClosedJobs`
-  // used to: it is recorded here and thrown from the top of the loop on the
-  // very next tick, rather than immediately, so it cannot itself become the
-  // block a sibling's dispatch is waiting behind. A lost lock is not this --
+  // used to: the overlap records it (`settlements.failure()`) and it is
+  // thrown from the top of the loop on the very next tick, rather than
+  // immediately, so it cannot itself become the block a sibling's dispatch is
+  // waiting behind. A lost lock is not this --
   // the loop's own `lock.assert()` calls surface that same condition on their
   // own schedule, so it is left for them.
-  /** @type {unknown} */
-  let backgroundSettlementFailure = null;
-  // Mark every job that closed this tick as settling, and free its slot,
-  // without waiting for any of them: that alone is what lets an eligible
-  // sibling dispatch into the freed slot while this node's minutes-long
-  // controller verification or judge round is still running. The actual
-  // settlement work is chained onto `settlementQueue`, one node at a time in
-  // the order its job closed, so it still runs exactly as serialized against
-  // every *other* node's settlement as it did when this loop awaited
-  // `finalizeClosedJobs` directly -- `finalizeClosedJobs` runs against a
-  // one-entry map per node, so this is one call per node rather than the one
-  // batched call it used to be, but the chain still runs them one at a time.
-  // A settlement may itself dispatch the node's next phase (a judge, a
-  // revision) through the same `startJudge`/`startWorker` calls dispatch below
-  // uses, so it is handed the real `running` to dispatch into: a job it starts
-  // is counted against `maxParallel` from the instant the process exists, and
-  // `applyRejection` reads that same map to decide whether the run has a slot
-  // for the revision at all. It used to dispatch into the throwaway one-entry
-  // map instead, copied back only once the settlement returned, which is how
-  // run state-location-and-routing-economics-13 came to hold two workers under
-  // `maxParallel: 1` on 2026-09-21. What it may *settle* is still only its own
-  // node: the one-entry map below is the job, not the run. The node's own
-  // steps stay ordered by never starting a second settlement for a node whose
-  // first has not yet cleared `pendingSettlements`.
-  const settleClosedJobsInBackground = () => {
-    for (const [nodeId, job] of [...running]) {
-      if (pendingSettlements.has(nodeId) || !job.closed || invocationAlive(job.invocation)) continue;
-      running.delete(nodeId);
-      const settlement = settlementQueue
-        .then(() => finalizeClosedJobs(contract, runDir, states, new Map([[nodeId, job]]), lock, campaign.path, running))
-        .finally(() => pendingSettlements.delete(nodeId));
-      // The queue itself must never reject -- a rejected settlement (a lost
-      // lock, a programmer error) would otherwise wedge every node queued
-      // behind it. The rejection still reaches whoever awaits the real
-      // `settlement` promise (`pendingSettlements`, below).
-      settlementQueue = settlement.catch(() => {});
-      // Handled here so an in-flight settlement never becomes an unhandled
-      // rejection when nobody happens to await `pendingSettlements` before the
-      // process exits; the original promise, still held below, carries the
-      // rejection to whichever checkpoint (cancel, shutdown) awaits it.
-      settlement.catch((error) => {
-        if (!(error instanceof LockLostError) && backgroundSettlementFailure === null) backgroundSettlementFailure = error;
-      });
-      pendingSettlements.set(nodeId, settlement);
-    }
-  };
   // Captured once, before the loop, rather than re-derived every tick: it is
   // "parked when this controller invocation started" (autoRetryParkedNodes's
   // own contract), and a node a background settlement parks between two ticks
@@ -531,7 +494,7 @@ export async function driveRun(contract, runDir, states, campaign, lock, sourceI
     // before the loop is allowed to end.
     if (anyUnsettled()) for (;;) {
       lock.assert();
-      if (backgroundSettlementFailure !== null) throw backgroundSettlementFailure;
+      if (settlements.failure() !== null) throw settlements.failure();
       if (existsSync(join(runDir, "cancel.request.json"))) canceled = true;
       if (canceled) {
         // A settlement already in flight owns the one decision a cancellation
@@ -569,9 +532,34 @@ export async function driveRun(contract, runDir, states, campaign, lock, sourceI
       // running, not only once it closes. `finalizeClosedJobs` used to open
       // with this same check; calling it once here, rather than once per
       // node settled this tick, is what keeps it at one pass per tick now
-      // that settlement runs per node in `settleClosedJobsInBackground`.
+      // that settlement runs per node below.
       await emitNodeAdvisories(contract, runDir, states);
-      settleClosedJobsInBackground();
+      // Mark every job that closed this tick as settling -- its admission slot
+      // moves from `running` into `settling` (see the settle window above) --
+      // without waiting for any of them. The settlement work is handed to the
+      // overlap one node at a time in the order its job closed: its sections
+      // are serialized against every *other* node's exactly as they were when
+      // this loop awaited `finalizeClosedJobs` directly, and only its
+      // verification proof is parked out of the slot while it runs (see
+      // `engine/settlement-overlap.mjs`). A settlement
+      // may itself dispatch the node's next phase (a judge, a revision)
+      // through the same `startJudge`/`startWorker` calls dispatch below uses,
+      // so it is handed the real `running` to dispatch into: a job it starts
+      // is counted against `maxParallel` from the instant the process exists,
+      // and `applyRejection` reads that same map to decide whether the run has
+      // a slot for the revision at all. It used to dispatch into the throwaway
+      // one-entry map instead, copied back only once the settlement returned,
+      // which is how run state-location-and-routing-economics-13 came to hold
+      // two workers under `maxParallel: 1` on 2026-09-21. What it may *settle*
+      // is still only its own node: the one-entry map below is the job, not
+      // the run. The node's own steps stay ordered by never starting a second
+      // settlement for a node whose first has not yet cleared
+      // `pendingSettlements`.
+      for (const [nodeId, job] of [...running]) {
+        if (pendingSettlements.has(nodeId) || !job.closed || invocationAlive(job.invocation)) continue;
+        running.delete(nodeId);
+        settlements.enqueue(nodeId, job, () => finalizeClosedJobs(contract, runDir, states, new Map([[nodeId, job]]), lock, campaign.path, running));
+      }
       await detectStalls(contract, running, async (job, status, error) => {
         const envelope = recordInvocationUsage(job);
         job.state.usage = invocationUsage(job.state);
@@ -642,44 +630,39 @@ export async function driveRun(contract, runDir, states, campaign, lock, sourceI
         }, lock);
         await raiseNodeAttention(campaign.path, runDir, /** @type {NodeSnapshot} */ (states.get(node.id)), HUMAN_STEP_ERROR_CODE);
       }
-      const slots = contract.maxParallel - running.size;
-      if (slots > 0) {
+      // F5 admission is judged against every attempt holding a slot: the live
+      // jobs plus the closed jobs still inside their settle window. The
+      // contract's `maxParallel` bounds the total; a spawn the settlement
+      // starts itself (the node's judge) runs inside the node's own held slot.
+      const admission = admissionPass(contract, running, settling, states);
+      if (admission.slots > 0) {
         const dispatchable = ready.filter((node) => !node.humanStep);
-        // Per-runtime capacity is judged per dispatch, not per tick: the
-        // counts include what this tick has already started, and a runtime a
-        // sibling is waiting out a quota reset on accepts nothing new.
-        const counts = runningPerRuntime(running.values());
-        const held = quotaHeldRuntimes(states.values(), Date.now());
         let dispatched = 0;
         for (const node of dispatchable) {
-          if (dispatched >= slots) break;
+          if (dispatched >= admission.slots) break;
           const state = states.get(node.id);
           if (!state || routingBackoffActive(state, state.phase)) continue;
           const routed = routeRuntimeForState(contract, node, state, state.phase === "judge" ? "judge" : "worker");
-          if (!runtimeHasCapacity(routed.id, contract, counts, held)) continue;
-          counts.set(routed.id, (counts.get(routed.id) ?? 0) + 1);
+          if (!admission.take(routed.id)) continue;
           dispatched += 1;
           // A node recovered pending a re-ask judge (its own worker attempt
           // already accepted, `state.result` durable) reaches `settleDone` /
           // `integrateAttempt` exactly like a closed job's own settlement
-          // does, on the same per-run candidate ref and worktree
-          // `settlementQueue` exists to serialize -- so it is dispatched the
-          // same way: chained onto the queue rather than awaited here, using
+          // does, on the same per-run candidate ref and worktree the
+          // overlap's serialized sections exist to protect -- so it is
+          // dispatched the same way: handed to the overlap rather than
+          // awaited here, using
           // `running` itself as its dispatch map, so the judge it starts is
           // counted the instant it exists. The node's own order is untouched
           // (still one entry at a time, gated by `pendingSettlements`); only
           // the tick stops waiting behind it.
           if (state.phase === "judge" && state.result) {
             const workerResult = state.result;
-            const settlement = settlementQueue
-              .then(() => startJudge(contract, node, state, runDir, running, workerResult, lock, states, campaign.path))
-              .then((round) => applyJudgeRound(round, contract, node, state, runDir, running, lock, states, campaign.path, workerResult))
-              .finally(() => pendingSettlements.delete(node.id));
-            settlementQueue = settlement.catch(() => {});
-            settlement.catch((error) => {
-              if (!(error instanceof LockLostError) && backgroundSettlementFailure === null) backgroundSettlementFailure = error;
-            });
-            pendingSettlements.set(node.id, settlement);
+            // Counted twice while the judge job is live -- in `settling` and
+            // in `running` -- which can only hold a sibling back.
+            settlements.enqueue(node.id, { runtime: routed }, () =>
+              startJudge(contract, node, state, runDir, running, workerResult, lock, states, campaign.path)
+                .then((round) => applyJudgeRound(round, contract, node, state, runDir, running, lock, states, campaign.path, workerResult)));
             continue;
           }
           state.attempt += 1;
@@ -734,12 +717,12 @@ export async function driveRun(contract, runDir, states, campaign, lock, sourceI
     // instant it settles, win or lose -- so a rejection recorded here can
     // already be gone from the map above by the time this line runs, with
     // nothing left to await it. The loop's own top-of-tick check
-    // (`if (backgroundSettlementFailure !== null) throw ...`) cannot save
+    // (`if (settlements.failure() !== null) throw ...`) cannot save
     // that case either: the loop has already exited. Checked again here,
     // once, so a background settlement failure can never read as a clean
     // finish just because it settled on the same tick the run's last node
     // did.
-    if (backgroundSettlementFailure !== null) throw backgroundSettlementFailure;
+    if (settlements.failure() !== null) throw settlements.failure();
   } catch (error) {
     if (!(error instanceof LockLostError)) throw error;
     // A settlement still merges whatever it started into `running` in its own

package/src/engine/settle.mjs

@@ -16,6 +16,7 @@ import { candidateOnlyFailures, resetPhaseRouting, verificationFailureVerdict }
 import { retryPrompt } from "./prompts.mjs";
 import { renderPreviousAttemptSection } from "./retry.mjs";
 import { startWorker } from "./dispatch.mjs";
+import { auxSpawnAdmission, recordAuxRefusal } from "./aux-admission.mjs";
 import { ensureTerminalEvent, transition, writeNode } from "./state.mjs";
 import { verificationFailureWithScope } from "../contract/scope-findings.mjs";
 import { alreadyNotified, notifyQueueFor } from "./notify-queue.mjs";
@@ -70,14 +71,18 @@ export function applyRejection(contract, node, state, runDir, running, lock, sta
     // path) carry it.
     state.previousAttempt = renderPreviousAttemptSection(state) ?? state.previousAttempt;
     // A revision is a new attempt, and a new attempt is a dispatch: it starts
-    // here only against a slot the run actually has free. `running` is the
-    // scheduler's own map, with this node's own closed job already out of it,
-    // so `running.size` is exactly what the dispatch loop's own
-    // `maxParallel - running.size` will read. A settlement that dispatched
-    // regardless is how run state-location-and-routing-economics-13 ran two
-    // workers under `maxParallel: 1` on 2026-09-21, and two of that day's
-    // three OOM kills happened with more running than the contract declared.
-    if (running && running.size < contract.maxParallel) {
+    // here only against a slot the run actually has free -- the global
+    // `maxParallel` and the routed runtime's own ceiling, the same judgment a
+    // dispatch pass applies (`auxSpawnAdmission`). `running` is the
+    // scheduler's own map, with this node's own closed job already out of it.
+    // A settlement that dispatched regardless is how run
+    // state-location-and-routing-economics-13 ran two workers under
+    // `maxParallel: 1` on 2026-09-21, and two of that day's three OOM kills
+    // happened with more running than the contract declared.
+    const admission = running
+      ? auxSpawnAdmission(contract, node, state, running, states, "worker")
+      : null;
+    if (admission?.admitted && running) {
       // Dispatching here owns the increment, because `startWorker` expects the
       // attempt number it is about to run under.
       state.attempt += 1;
@@ -92,7 +97,9 @@ export function applyRejection(contract, node, state, runDir, running, lock, sta
     // killed controller — a node that ran twice reported attempt 3, with no
     // `…2.*` logs and a `worktree.previousAttempt` naming an attempt that
     // never existed.
+    const from = state.status;
     transition(runDir, state, "pending", { phase: "worker", error: null }, lock);
+    if (admission) recordAuxRefusal(runDir, state, from, lock, "worker", admission);
     return;
   }
   transition(runDir, state, node.gate.enabled ? "exhausted" : "failed", {

package/src/engine/settlement-overlap.mjs

@@ -0,0 +1,143 @@
+/**
+ * The settlement overlap: what makes two closed nodes' verification proofs run
+ * at the same time through one real run, while everything a concurrent second
+ * settlement would corrupt stays serialized.
+ *
+ * The verify layer's proof gate (`engine/verify.mjs`) already bounds concurrent
+ * passes by the contract's `maxParallel` and serializes passes that share a
+ * tree; what held the engine back was the caller. `driveRun` chained whole
+ * settlements onto one promise queue, so one node's controller verification --
+ * minutes of child processes -- held every other node's settlement behind it
+ * and two independent worktree proofs never overlapped (phase-5 d4.1). This
+ * module replaces that queue: a settlement is a sequence of serialized
+ * *sections* separated by *proofs*. A section holds the run's one settlement
+ * slot; `parkDuringProof`, called around the controller verification pass,
+ * hands the slot back while the proof's child processes run and re-acquires it
+ * before the settlement's next decision. Dispatch decisions, the
+ * phase-continuation choice in `finalizeClosedJobs`, and ref updates and the
+ * whole integration transaction therefore never interleave between two nodes,
+ * while the proofs between them do. The integration candidate's own
+ * verification is deliberately never parked: it runs inside
+ * `repo/integrate.mjs`'s candidate lock, and parking it would deadlock -- its
+ * settlement would wait to re-acquire the slot behind a sibling whose section
+ * is itself waiting on the candidate lock this settlement holds -- and
+ * integration is exactly what phase 5 keeps serialized.
+ *
+ * Per-node ordering needs no lock here: the scheduler never starts a second
+ * settlement for a node whose first is still in `pending`, and the admission
+ * settle window (`settling`) holds each node's slot from its job's close until
+ * its settlement finishes, parked proof included.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { LockLostError } from "../run/lock.mjs";
+
+/** @typedef {import("./lifecycle.mjs").Job} Job */
+
+/** @typedef {{park: (factory: () => Promise<unknown>) => Promise<unknown>}} SettlementContext */
+
+/** The overlap of the settlement currently running on this controller, if any. @type {AsyncLocalStorage<SettlementContext>} */
+const settlementContext = new AsyncLocalStorage();
+
+/**
+ * Run a verification proof outside the caller's serialized section: while the
+ * proof's child processes run, the settlement's slot is handed back and a
+ * sibling's settlement advances. Outside a settlement -- a recovery path, a
+ * test driving `executeControllerVerification` directly -- the proof runs
+ * exactly inline, unchanged.
+ *
+ * @template T
+ * @param {() => Promise<T>|T} factory
+ * @returns {Promise<T>}
+ */
+export async function parkDuringProof(factory) {
+  const overlap = settlementContext.getStore();
+  if (!overlap) return /** @type {T} */ (await factory());
+  return /** @type {Promise<T>} */ (overlap.park(/** @type {() => Promise<unknown>} */ (factory)));
+}
+
+/**
+ * @returns {{pending: Map<string, Promise<void>>, settling: Map<string, Pick<Job, "runtime">>, enqueue: (nodeId: string, job: Pick<Job, "runtime">, work: () => Promise<void>) => void, failure: () => unknown}}
+ */
+export function createSettlementOverlap() {
+  /** @type {Map<string, Promise<void>>} */
+  const pending = new Map();
+  /** @type {Map<string, Pick<Job, "runtime">>} */
+  const settling = new Map();
+  /** @type {unknown} */
+  let failure = null;
+  let sectionBusy = false;
+  /** @type {(() => void)[]} */
+  const sectionWaiters = [];
+  /** @returns {Promise<void>} */
+  const acquireSection = () => new Promise((satisfy) => {
+    if (!sectionBusy) {
+      sectionBusy = true;
+      satisfy();
+      return;
+    }
+    sectionWaiters.push(satisfy);
+  });
+  // Hand-off, not vacancy: the next waiter is granted the slot directly, so a
+  // caller that acquires between the release and the grant joins the queue
+  // behind it instead of slipping past.
+  /** @returns {void} */
+  const releaseSection = () => {
+    const next = sectionWaiters.shift();
+    if (next) next();
+    else sectionBusy = false;
+  };
+  /**
+   * Hand the slot back while a proof runs and take it again before the next
+   * decision. Releasing is safe exactly because the proof holds no shared
+   * settlement state: its writes go to its own node's snapshot, its child
+   * processes run in their own worktree, and its overlap with sibling proofs
+   * is bounded by the verify layer's proof gate.
+   *
+   * @template T
+   * @param {() => Promise<T>} factory
+   * @returns {Promise<T>}
+   */
+  const park = async (factory) => {
+    releaseSection();
+    try {
+      return await factory();
+    } finally {
+      await acquireSection();
+    }
+  };
+  return {
+    pending,
+    settling,
+    /**
+     * Chain one node's settlement onto the overlap. The reservation semantics
+     * are the scheduler's old `enqueueSettlement` verbatim: the settle-window
+     * slot is reserved before the work starts, released in the same `finally`
+     * that retires `pending`, and the first rejection that is not a lost lock
+     * is recorded for the top of the next tick to throw.
+     *
+     * @param {string} nodeId
+     * @param {Pick<Job, "runtime">} job
+     * @param {() => Promise<void>} work
+     */
+    enqueue(nodeId, job, work) {
+      settling.set(nodeId, job);
+      const settlement = settlementContext.run({ park }, async () => {
+        await acquireSection();
+        try {
+          return await work();
+        } finally {
+          releaseSection();
+        }
+      }).finally(() => {
+        pending.delete(nodeId);
+        settling.delete(nodeId);
+      });
+      settlement.catch((error) => {
+        if (!(error instanceof LockLostError) && failure === null) failure = error;
+      });
+      pending.set(nodeId, settlement);
+    },
+    /** @returns {unknown} */
+    failure: () => failure,
+  };
+}

package/src/engine/verify.mjs

@@ -13,12 +13,14 @@ import { boundedUtf8, errorMessage } from "../util.mjs";
 import { compactVerification } from "../contract/verification.mjs";
 import { MAX_SCOPE_FINDING_PATHS } from "../contract/scope-findings.mjs";
 import { finalVerificationCommands, phaseTerminalNode, sharedVerificationCommands } from "../contract/final-verification.mjs";
-import { join } from "node:path";
+import { realpathSync } from "node:fs";
+import { join, resolve } 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";
+import { parkDuringProof } from "./settlement-overlap.mjs";
 
 /** @typedef {import("../repo/integrate.mjs").CandidateEvidence} CandidateEvidence */
 /** @typedef {import("../cli.mjs").LockHandle} LockHandle */
@@ -31,6 +33,119 @@ import { runVerification } from "./run-command.mjs";
 /** @typedef {import("../contract/index.mjs").VerificationState} VerificationState */
 /** @typedef {{index: number, total: number, argv: string}} VerificationProgress */
 
+/**
+ * The proof gate: the verification layer's own admission for concurrent
+ * passes. R7 (phase 5) allows proofs in independent worktrees to advance
+ * together, bounded by the contract's `maxParallel` — the ceiling the planner
+ * already sized from this machine, and nothing higher (phase-5 restriction:
+ * the host is measured before concurrency is raised). Passes that share a
+ * tree can interfere, so they never overlap no matter what the budget allows:
+ * the base checkout (`contract.cwd`, where a node without an attempt worktree
+ * runs) and the run's one candidate worktree are each serialized under their
+ * own key. The settlement overlap (`engine/settlement-overlap.mjs`) is the
+ * caller that puts the budget to work: it parks a settlement for the length
+ * of each pass, so two nodes' independent worktree proofs overlap through a
+ * real run while this gate holds the bound, shared-tree passes, and the
+ * candidate worktree's pass serialized.
+ *
+ * @typedef {{limit: number, active: number, held: Set<string>, waiters: {key: string, satisfy: () => void}[]}} ProofGate
+ */
+
+/** @type {WeakMap<ValidatedContract, ProofGate>} */
+const proofGates = new WeakMap();
+
+/**
+ * @param {ValidatedContract} contract
+ * @returns {ProofGate}
+ */
+function proofGateFor(contract) {
+  let gate = proofGates.get(contract);
+  if (!gate) {
+    gate = { limit: Math.max(1, contract.maxParallel ?? 1), active: 0, held: new Set(), waiters: [] };
+    proofGates.set(contract, gate);
+  }
+  return gate;
+}
+
+/**
+ * The tree a pass runs in. `realpath` because a worktree path reached through
+ * a symlinked parent (/var vs /private/var on darwin) must read as the same
+ * key on every call.
+ *
+ * @param {string} workspace
+ * @returns {string}
+ */
+function proofWorkspaceKey(workspace) {
+  try {
+    return realpathSync(workspace);
+  } catch {
+    // An absent workspace has no realpath; nothing can run in it anyway, so
+    // the lexical resolution is as good a key as any.
+    return resolve(workspace);
+  }
+}
+
+/** @param {ProofGate} gate @returns {void} */
+function drainProofWaiters(gate) {
+  for (let index = 0; index < gate.waiters.length && gate.active < gate.limit;) {
+    const waiter = /** @type {{key: string, satisfy: () => void}} */ (gate.waiters[index]);
+    if (gate.held.has(waiter.key)) {
+      index += 1;
+      continue;
+    }
+    gate.waiters.splice(index, 1);
+    waiter.satisfy();
+  }
+}
+
+/**
+ * @param {ProofGate} gate
+ * @param {string} key
+ * @returns {Promise<() => void>}
+ */
+function acquireProofSlot(gate, key) {
+  return new Promise((resolveSlot) => {
+    /** @returns {void} */
+    const satisfy = () => {
+      gate.active += 1;
+      gate.held.add(key);
+      let released = false;
+      resolveSlot(() => {
+        if (released) return;
+        released = true;
+        gate.active -= 1;
+        gate.held.delete(key);
+        drainProofWaiters(gate);
+      });
+    };
+    if (gate.active < gate.limit && !gate.held.has(key)) {
+      satisfy();
+      return;
+    }
+    gate.waiters.push({ key, satisfy });
+  });
+}
+
+/**
+ * Run one verification pass holding its proof slot: the pass overlaps other
+ * passes only in worktrees independent of its own, and only while the run's
+ * budget has room.
+ *
+ * @template T
+ * @param {ValidatedContract} contract
+ * @param {string} workspace
+ * @param {() => Promise<T>} run
+ * @returns {Promise<T>}
+ */
+async function withProofSlot(contract, workspace, run) {
+  const release = await acquireProofSlot(proofGateFor(contract), proofWorkspaceKey(workspace));
+  try {
+    return await run();
+  } finally {
+    release();
+  }
+}
+
 /**
  * The sibling phase-terminal node ids already settled, read straight off
  * disk: every node snapshot is persisted from the run's first tick (see
@@ -147,7 +262,16 @@ export async function executeControllerVerification(contract, runDir, node, stat
   /** @param {VerificationAttempt} attempt @returns {VerificationProgress} */
   const progressFor = (attempt) => verificationProgress(attempt.commandIndex + 1, commands.length, /** @type {VerificationCommand|undefined} */ (commands[attempt.commandIndex])?.argv);
   try {
-    const result = await runVerification(commands, workspace, {
+    // Parked for the length of the pass: the settlement's section slot goes
+    // back to the overlap while these child processes run, so a sibling's
+    // settlement -- and its own proof -- advances. Everything after this
+    // await (judge dispatch, gate verdicts, integration) runs in the
+    // re-acquired section; the proof gate below is what bounds the overlap.
+    // The candidate pass in `verifyCandidateWorkspace` is deliberately not
+    // parked: it runs inside the integration transaction's candidate lock,
+    // and parking it would wait to re-acquire a section a sibling holds
+    // while that sibling waits on this same candidate lock.
+    const result = await parkDuringProof(() => withProofSlot(contract, workspace, () => runVerification(commands, workspace, {
       logDir: join(runDir, "logs", `${node.id}.${state.attempt}.verification`),
       writeFiles: node.taskPacket.writeFiles ?? [],
       onAttemptStart: (attempt) => persistVerificationAttempt(runDir, state, lock, attempt, progressFor(attempt)),
@@ -156,7 +280,7 @@ export async function executeControllerVerification(contract, runDir, node, stat
         ...attempt,
         result: boundedVerificationAttemptResult(attempt.result),
       }),
-    });
+    })));
     state.verification = {
       ...compactVerification(result),
       completed: true,
@@ -318,19 +442,19 @@ export async function verifyCandidateWorkspace(contract, node, state, runDir, wo
   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, {
+    const result = await withProofSlot(contract, workspace, () => runVerification(commands, workspace, {
       logDir: join(runDir, "logs", `${node.id}.${state.attempt}.candidate-verification`),
       writeFiles: node.taskPacket.writeFiles ?? [],
-    });
+    }));
     /** @type {import("../contract/verification.mjs").VerificationResult & {retried?: number[]}} */
     let settled = result;
     if (!result.passed) {
       settled = await retryDivergentCandidateCommands(result, state.verification, async (indexes) => {
         const subset = indexes.map((index) => commands[index]);
-        const rerun = await runVerification(subset, workspace, {
+        const rerun = await withProofSlot(contract, workspace, () => runVerification(subset, workspace, {
           logDir: join(runDir, "logs", `${node.id}.${state.attempt}.candidate-retry`),
           writeFiles: node.taskPacket.writeFiles ?? [],
-        });
+        }));
         return rerun.commands;
       });
     }