faberun 0.13.0 → 0.15.0

package/src/engine/failover.mjs

@@ -8,9 +8,14 @@
  * runtime a role started on, and (if declared) the runtime its `fallback`
  * names. contract.mjs validates the field is never a self-loop; because a
  * hop is bounded at one, a multi-runtime cycle is structurally impossible.
+ *
+ * Per-attempt resolution (`routeRuntimeForState`) lives here too, because
+ * attempt affinity is read against the same failover facts: the runtime the
+ * previous attempt ran is preferred until the hop, the catalogue, or the
+ * judge's vendor rule disqualifies it.
  */
 import { harnessCapabilities } from "../harnesses/index.mjs";
-import { nextSameTierRuntime } from "./runtime-discovery.mjs";
+import { isRuntimeAvailable, nextSameTierRuntime } from "./runtime-discovery.mjs";
 import { routeRuntime } from "../contract/runtime.mjs";
 
 /** @typedef {import("../contract/index.mjs").ValidatedNode} ValidatedNode */
@@ -170,6 +175,50 @@ export function routingBackoffActive(state, phase) {
   return Boolean(override?.role === phase && override.backoffUntil && Date.parse(override.backoffUntil) > Date.now());
 }
 
+/**
+ * The runtime id this role's previous attempt on this node ran on, read off
+ * the durable invocation record. The invocations are the one record that
+ * survives both a routed hop and the revision boundary: `resetPhaseRouting`
+ * clears the routing override between revisions, but never the invocations.
+ *
+ * @param {NodeSnapshot} state
+ * @param {"worker"|"judge"} role
+ * @returns {string|undefined}
+ */
+function previousAttemptRuntimeId(state, role) {
+  const found = [...(state.invocations ?? [])].reverse().find((invocation) => invocation.phase === role)?.runtimeId;
+  return typeof found === "string" ? found : undefined;
+}
+
+/**
+ * May attempt affinity keep this role on `candidate` -- the runtime its
+ * previous attempt on this node ran? Affinity yields to a known exhaustion
+ * only: a catalogue record that `isRuntimeAvailable` -- the one home of the
+ * exhaustion and staleness rule -- refuses to admit. An absent record is not
+ * that: the snapshot's catalogue copy is the classified fields at best and
+ * often empty outright, and the strongest evidence of health here is the
+ * attempt that just ran on this runtime, so absence of a record must not read
+ * as exhaustion any more than R12 lets it read as rested. A judge candidate
+ * stays bound by the cross-vendor rule its assignment was composed under,
+ * compared against the worker that actually ran the node, exactly as
+ * `nextSameTierRuntime` compares its own candidates.
+ *
+ * @param {ValidatedContract} contract
+ * @param {NodeSnapshot} state
+ * @param {"worker"|"judge"} role
+ * @param {string} candidate
+ * @returns {boolean}
+ */
+function admitsAffinity(contract, state, role, candidate) {
+  const runtime = contract.runtimes[candidate];
+  if (!runtime) return false;
+  const availability = state.routing?.availability?.[candidate];
+  if (availability && !isRuntimeAvailable(availability)) return false;
+  if (role !== "judge") return true;
+  const workerId = previousAttemptRuntimeId(state, "worker") ?? state.routing?.assignments?.worker;
+  return runtime.vendor !== (workerId ? contract.runtimes[workerId]?.vendor : null);
+}
+
 /**
  * @param {ValidatedContract} contract
  * @param {ValidatedNode} node
@@ -183,6 +232,18 @@ export function routeRuntimeForState(contract, node, state, role) {
     const runtime = contract.runtimes[override.runtime];
     return { id: override.runtime, ...runtime, capabilities: harnessCapabilities(runtime) };
   }
+  // Attempt affinity: successive attempts and revisions of this node prefer
+  // the runtime the previous attempt ran, because it is the one holding the
+  // node's context. It ranks ahead of the frozen assignment -- the assignment
+  // decided the first attempt, the attempt that ran since decides the next --
+  // and below the role-matched override above, which is itself already an
+  // affinity outcome: a reset hold on the warm runtime, or the failover edge
+  // affinity yielded to.
+  const previous = previousAttemptRuntimeId(state, role);
+  if (previous !== undefined && admitsAffinity(contract, state, role, previous)) {
+    const runtime = contract.runtimes[previous];
+    return { id: previous, ...runtime, capabilities: harnessCapabilities(runtime) };
+  }
   const assigned = state.routing?.assignments?.[role];
   if (assigned && contract.runtimes[assigned]) {
     const runtime = contract.runtimes[assigned];

package/src/engine/judge-gate.mjs

@@ -14,8 +14,10 @@ import { stat } from "node:fs/promises";
 import { isAbsolute, resolve } from "node:path";
 import { reviewMode, UNCITED_REJECTION_REASON } from "../contract/review-modes.mjs";
 import { JUDGE_LIMITS } from "../contract/judge-envelope.mjs";
+import { sharedVerificationCommands } from "../contract/final-verification.mjs";
 
 /** @typedef {import("../contract/definition-of-done.mjs").DefinitionOfDoneItem} DefinitionOfDoneItem */
+/** @typedef {import("../contract/verification.mjs").VerificationCommand} VerificationCommand */
 /** @typedef {import("../contract/definition-of-done.mjs").DefinitionOfDoneProof} DefinitionOfDoneProof */
 /** @typedef {import("../contract/index.mjs").ExecutionOverride} ExecutionOverride */
 /** @typedef {import("../contract/index.mjs").NodeSnapshot} NodeSnapshot */
@@ -349,6 +351,48 @@ function declaredWriteCoverage(state) {
     directoryRoots.some((root) => path === root || path.startsWith(`${root}/`));
 }
 
+/**
+ * Whether a path named by verification output belongs to the contract's own
+ * `sharedVerification` suite -- the repository ratchets the operator appends to
+ * every node -- rather than to the node's own work. An argv entry names either
+ * the file the runner was given or a directory it walked.
+ *
+ * Deliberately not caught: a `sharedVerification` that reaches the ratchet
+ * without naming it in argv (`npm test`, or any script that picks the files
+ * itself). No token matches, the file is not recognized as a ratchet, and the
+ * contract-defect advice applies to it as it did before. Widening the match to
+ * guess what a script runs would be worse than the gap it closes.
+ *
+ * @param {{sharedVerification?: VerificationCommand[]}} contract
+ * @returns {(path: string) => boolean}
+ */
+function sharedVerificationCoverage(contract) {
+  const argv = sharedVerificationCommands(contract).flatMap((command) => command.argv);
+  return (path) => argv.some((token) => token === path || path.startsWith(`${token}/`));
+}
+
+/**
+ * The operator-facing description for a failing ratchet: a check the contract
+ * itself declared, that runs on every node, and that this node's change broke.
+ *
+ * It says nothing about the write scope on purpose. Telling the operator to
+ * hand the node the ratchet licenses the next worker to edit the rule it just
+ * violated -- observed 2026-09-21, when a node that pushed
+ * `src/report/render.mjs` to 801 lines was advised to add the 800-line ratchet
+ * to its `writeFiles`. The remedy is already inside the node's scope: its own
+ * code.
+ *
+ * @param {string[]} paths
+ * @returns {string}
+ */
+function ratchetFailureDescription(paths) {
+  const files = paths.join(", ");
+  return boundedText(
+    `deterministic verification failed in ${files}, which the contract runs on every node as sharedVerification: this node's change broke a repository-wide rule. The remedy is in the node's own code -- bring the change back within the rule the check enforces. The check itself is not the node's to change, and relaxing it is not a fix`,
+    JUDGE_LIMITS.descriptionBytes,
+  );
+}
+
 /**
  * The operator-facing description for a failure that named a test outside the
  * declared write scope. The defect is not in the worker's code: the worker is
@@ -372,24 +416,38 @@ function undeclaredTestDescription(paths) {
  * The deterministic controller-verification failure verdict, kept next to the
  * Definition of Done gate so every deterministic failure settles identically.
  *
+ * The contract is a parameter because an undeclared test file has two opposite
+ * remedies and only the contract tells them apart: a ratchet it declared in
+ * `sharedVerification` is the node's code to fix, while any other withheld test
+ * is the contract's scope to widen.
+ *
+ * @param {{sharedVerification?: VerificationCommand[]}} contract
  * @param {{verification?: {commands?: Array<{argv: string[], passed?: boolean, attempts?: Array<{stdout?: string, stderr?: string, exitCode?: number|null, timedOut?: boolean}>}>, error?: unknown}|null, scope?: {boundary?: {files?: string[], roots?: string[], fileRoots?: string[]}}|null}} state
  * @returns {import("./prompts.mjs").JudgeVerdict}
  */
-export function verificationFailureVerdict(state) {
+export function verificationFailureVerdict(contract, state) {
   const failedCommands = (state.verification?.commands ?? []).filter((command) => !command.passed);
   const evidence = failedCommands.length
     ? failedCommands.map((command) => `${command.argv.join(" ")}: ${(command.attempts ?? []).map((attempt) => `exit=${attempt.exitCode ?? "-"}${attempt.timedOut ? " timeout" : ""}`).join(", ")}`).join("; ")
     : state.verification?.error ?? "verification controller failed to execute a command";
-  const undeclared = namedTestFiles(failedCommands).filter((path) => !declaredWriteCoverage(state)(path));
+  const declared = declaredWriteCoverage(state);
+  const undeclared = namedTestFiles(failedCommands).filter((path) => !declared(path));
+  const isRatchet = sharedVerificationCoverage(contract);
+  const ratchets = undeclared.filter(isRatchet);
+  const withheld = undeclared.filter((path) => !isRatchet(path));
+  const descriptions = [
+    ...(ratchets.length ? [ratchetFailureDescription(ratchets)] : []),
+    ...(withheld.length ? [undeclaredTestDescription(withheld)] : []),
+  ];
   return {
     verdict: "fail",
     maxSeverity: "critical",
     summary: "deterministic verification failed",
-    findings: [{
+    findings: (descriptions.length ? descriptions : ["deterministic verification failed"]).map((description) => ({
       severity: "critical",
-      description: undeclared.length ? undeclaredTestDescription(undeclared) : "deterministic verification failed",
+      description,
       evidence: boundedText(evidence),
-    }],
+    })),
   };
 }
 

package/src/engine/lifecycle.mjs

@@ -280,22 +280,35 @@ export function clearTierExhaustion(state) {
 }
 
 /**
+ * Settle what a closed invocation produced, and start whatever the outcome
+ * earns next.
+ *
+ * The two maps are two different things, and conflating them is what let a run
+ * exceed its own `maxParallel` (measured 2026-09-21, run
+ * state-location-and-routing-economics-13): `closed` is the job this call owns
+ * -- the scheduler hands one node's job at a time so two settlements never
+ * interleave -- while `running` is the run's live dispatch authority, the very
+ * map the scheduler's `maxParallel - running.size` counts. Anything started
+ * here lands in `running` and is accounted from that instant; nothing started
+ * here may be settled by this call.
+ *
  * @param {ValidatedContract} contract
  * @param {string} runDir
  * @param {Map<string, NodeSnapshot>} states
- * @param {Map<string, Job>} running
+ * @param {Map<string, Job>} closed
  * @param {LockHandle} lock
  * @param {string} campaignPath
+ * @param {Map<string, Job>} running
  * @returns {Promise<void>}
  */
-export async function finalizeClosedJobs(contract, runDir, states, running, lock, campaignPath) {
+export async function finalizeClosedJobs(contract, runDir, states, closed, lock, campaignPath, running) {
   // Advisory spend lines are checked every tick, before outcome handling: a
   // crossing must be visible while the spend is happening, not only when the
   // run is already over. The check never stops or transitions a node.
   await emitNodeAdvisories(contract, runDir, states);
-  for (const [nodeId, job] of running) {
+  for (const [nodeId, job] of closed) {
     if (!job.closed || invocationAlive(job.invocation)) continue;
-    running.delete(nodeId);
+    closed.delete(nodeId);
     const state = states.get(nodeId);
     if (!state) continue;
     // Usage is extracted and persisted BEFORE any outcome-specific handling:

package/src/engine/mutation.mjs

@@ -9,6 +9,14 @@
  * break syntax and the sample is a deterministic eight, because a gate that
  * fails at random, or on a mutant that does not compile, is worse than no gate.
  *
+ * The kill fraction is declared by tier, not hand-picked per entry: the entry
+ * declares a risk tier and `MUTATION_TIERS` (`contract/verification.mjs`)
+ * fixes what each tier demands, so two nodes at the same tier sit the same
+ * bar. The whole entry — baseline plus sample — is held inside
+ * `MUTATION_TIME_BUDGET_MS`, and mutants the budget cannot afford stay in the
+ * denominator, so a suite too slow to sample inside the budget fails rather
+ * than passing on a narrowed set.
+ *
  * It is a separate module from `run-command.mjs` so that the "doing" of a
  * verification run and the "which file to break" policy do not grow together;
  * the runner receives the argv executor as a callback rather than importing it,
@@ -16,10 +24,27 @@
  */
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { MUTATION_TIERS } from "../contract/verification.mjs";
 
 /** At most this many mutants run for one verification entry. */
 export const MUTATION_BUDGET = 8;
 
+/**
+ * Wall-clock budget for one mutation entry — baseline plus every mutant run —
+ * in milliseconds. Each mutant re-runs the same argv, so each one costs what
+ * the baseline cost, and the runner refuses to start a mutant the remaining
+ * budget cannot afford.
+ *
+ * measured 2026-09-21 on this repository: the scenarios in
+ * test/engine/mutation.test.mjs cost 0.08–0.37s per run, so a node-sized entry
+ * (baseline plus eight mutants over a targeted suite) costs ~1–4s and samples
+ * in full. The budget admits any suite up to ~3.3s per run and denies slower
+ * ones every mutant — measured counter-example: `node --test test/contract`
+ * costs ~20s per run, and a mutation entry is scoped to the node's own
+ * verification command, not to a whole suite directory.
+ */
+export const MUTATION_TIME_BUDGET_MS = 30_000;
+
 /**
  * The six operators, and only these: comparison and logical swaps. Each swap
  * keeps the expression well formed, so a surviving mutant is signal about the
@@ -109,18 +134,31 @@ function evenlySpaced(candidates, budget) {
  */
 export async function runMutation(command, baseCwd, options) {
   const mutation = command.mutation;
-  if (!mutation) throw new TypeError("mutation runner requires a command.mutation threshold");
-  const threshold = mutation.threshold;
-  const selected = evenlySpaced(mutationCandidates(baseCwd, options.writeFiles ?? []), MUTATION_BUDGET);
+  if (!mutation) throw new TypeError("mutation runner requires a command.mutation risk tier");
+  const threshold = MUTATION_TIERS[mutation.tier];
+  const sample = evenlySpaced(mutationCandidates(baseCwd, options.writeFiles ?? []), MUTATION_BUDGET);
   /** @type {VerificationAttemptResult[]} */
   const attempts = [];
   const baseline = await options.run(1);
   attempts.push(baseline);
-  if (!baseline.passed) return { passed: false, killed: 0, total: selected.length, threshold, attempts };
+  if (!baseline.passed) return { passed: false, killed: 0, total: sample.length, threshold, attempts };
+  // Every mutant re-runs the same argv, so the baseline's own measured duration
+  // is what one more attempt costs, and the budget is spent in those units. An
+  // executor that reports no duration (the unit-test seam) is charged zero and
+  // is never denied a mutant.
+  const attemptMs = Number.isFinite(baseline.durationMs) ? /** @type {number} */ (baseline.durationMs) : 0;
   /** @type {Map<string, string>} */
   const originals = new Map();
   let killed = 0;
-  for (const [index, candidate] of selected.entries()) {
+  let spentMs = attemptMs;
+  let attempt = 1;
+  for (const candidate of sample) {
+    // Mutants the budget cannot afford are not silently dropped from the
+    // denominator: `total` stays the full sample, so truncation can only lower
+    // the kill fraction. A suite too slow to sample inside the budget fails a
+    // gate it is too slow to sit for — the narrowing the budget exists to
+    // prevent.
+    if (attemptMs > 0 && spentMs + attemptMs > MUTATION_TIME_BUDGET_MS) break;
     let original = originals.get(candidate.absolute);
     if (original === undefined) {
       original = readFileSync(candidate.absolute, "utf8");
@@ -129,16 +167,18 @@ export async function runMutation(command, baseCwd, options) {
     const mutated = `${original.slice(0, candidate.offset)}${candidate.to}${original.slice(candidate.offset + candidate.from.length)}`;
     /** @type {VerificationAttemptResult} */
     let result;
+    attempt += 1;
     try {
       writeFileSync(candidate.absolute, mutated);
-      result = await options.run(index + 2);
+      result = await options.run(attempt);
     } finally {
       writeFileSync(candidate.absolute, original);
     }
     attempts.push(result);
+    spentMs += Number.isFinite(result.durationMs) ? /** @type {number} */ (result.durationMs) : 0;
     if (!result.passed) killed += 1;
   }
-  const total = selected.length;
+  const total = sample.length;
   // No operators to break is a vacuous pass: there is no mutant the suite could
   // have failed to kill. The caller declared the entry, so an empty target is a
   // measurement of nothing, not a suite that proved nothing.

package/src/engine/resume.mjs

@@ -609,7 +609,7 @@ export async function recoverIntegrationTransactions(contract, runDir, states, l
       const node = contract.nodes.find((candidate) => candidate.id === transaction.node);
       const state = states.get(transaction.node);
       if (!node || !state || SETTLED.has(state.status)) return;
-      const verdict = verificationFailureWithScope(verificationFailureVerdict(state), state.scope);
+      const verdict = verificationFailureWithScope(verificationFailureVerdict(contract, state), state.scope);
       verdict.summary = "integrated candidate verification failed during recovery";
       applyRejection(contract, node, state, runDir, null, lock, states, campaignPath, verdict, {
         code: "verification_failed",

package/src/engine/runtime-discovery.mjs

@@ -9,7 +9,14 @@ export { exhaustedUntilOf, normalizeProviderAvailability } from "../harnesses/in
 /** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
 /** @typedef {{harness?: string, model?: string, vendor: string, tier?: number|string, costRank?: number, [key: string]: unknown}} RuntimeLike */
 /** @typedef {{runtimes: Record<string, RuntimeLike>, runtimeDefaults?: {worker?: string, judge?: string}, nodes?: {id: string, runtime?: string, gate: {enabled: boolean, runtime?: string}}[]}} RuntimeContract */
-/** @typedef {{available: boolean, exhaustedUntil: string|null, reason: string}} RuntimeAvailability */
+/**
+ * One runtime's catalogue record: what the harness de facto reported, and
+ * when. An unobservable datum is null -- never zero and never full allowance,
+ * so a runtime that reports nothing cannot look rested -- and an absent key on
+ * a record that predates the field reads as null at every reader. An
+ * observation older than its own window reads as unknown (`isRuntimeAvailable`).
+ * @typedef {{available: boolean, exhaustedUntil: string|null, reason: string, observedAt?: string|null, window?: string|null, remaining?: number|null}} RuntimeAvailability
+ */
 /** @typedef {{harness: string, model: string, vendor: string, tier: number, costRank: number, config?: Record<string, unknown>}} DiscoveryRuntime */
 /** @typedef {{id: string, runtime: RuntimeLike, order: number}} RuntimeCandidate */
 /** @typedef {import("../host/config.mjs").UserConfig} UserConfig */
@@ -89,7 +96,7 @@ export async function discoverRuntimes(runtimes, options = {}) {
  */
 export function availableCandidates(runtimes, availability = {}) {
   return Object.entries(runtimes)
-    .filter(([id]) => isAvailable(availability[id]))
+    .filter(([id]) => isRuntimeAvailable(availability[id]))
     .map(([id, runtime], order) => ({ id, runtime, order }));
 }
 
@@ -172,7 +179,7 @@ export function nextSameTierRuntime(contract, stateRouting, role, current, attem
   const used = new Set(attempted);
   return Object.entries(contract.runtimes)
     .filter(([id, runtime]) => id !== current && !used.has(id) && sameTier(runtime, currentRuntime))
-    .filter(([id]) => isAvailable(stateRouting.availability?.[id]))
+    .filter(([id]) => isRuntimeAvailable(stateRouting.availability?.[id]))
     .filter(([, runtime]) => role !== "judge" || runtime.vendor !== workerVendor)
     .sort((left, right) => runtimeOrder(left[1]) - runtimeOrder(right[1]))
     .map(([id]) => id)
@@ -226,10 +233,40 @@ function tierOrder(runtime) {
   return typeof runtime.tier === "number" ? runtime.tier : runtime.costRank ?? Number.MAX_SAFE_INTEGER;
 }
 
-/** @param {RuntimeAvailability|undefined} availability @returns {boolean} */
-function isAvailable(availability) {
+/**
+ * Span in seconds of every rate-limit window label a harness reports. The
+ * labels are claude's `rateLimitType` values (measured 2026-09-17, the
+ * `rate_limit_event` line recorded in `src/harnesses/protocol.mjs`); a label
+ * missing here cannot prove staleness, so its observation never self-expires.
+ *
+ * @type {Readonly<Record<string, number>>}
+ */
+const AVAILABILITY_WINDOW_SEC = Object.freeze({ five_hour: 5 * 3600, seven_day: 7 * 86400 });
+
+/**
+ * May a runtime be admitted on this catalogue record? Exhaustion is waited
+ * out on `exhaustedUntil`; an observation older than its own window reads as
+ * unknown and admits nothing, because unknown must not look rested. This is
+ * the one home of the rule: plan routing and engine composition both read it,
+ * so the null and staleness semantics cannot drift between readers. The
+ * parameter is typed on the fields the rule reads, not on the full record --
+ * the plan's table copy names no `reason`.
+ *
+ * @param {{available: boolean, exhaustedUntil: string|null, observedAt?: string|null, window?: string|null, [key: string]: unknown}|undefined} availability
+ * @param {number} [now] epoch milliseconds; defaults to the current clock
+ * @returns {boolean}
+ */
+export function isRuntimeAvailable(availability, now = Date.now()) {
   if (!availability) return false;
-  if (availability.available === true) return !availability.exhaustedUntil || Date.parse(availability.exhaustedUntil) <= Date.now();
-  return Boolean(availability.exhaustedUntil && Date.parse(availability.exhaustedUntil) <= Date.now());
+  const rested = availability.available === true
+    ? !availability.exhaustedUntil || Date.parse(availability.exhaustedUntil) <= now
+    : Boolean(availability.exhaustedUntil && Date.parse(availability.exhaustedUntil) <= now);
+  if (!rested) return false;
+  const windowSec = availability.window === undefined || availability.window === null
+    ? undefined
+    : AVAILABILITY_WINDOW_SEC[availability.window];
+  if (windowSec === undefined || availability.observedAt === undefined || availability.observedAt === null) return true;
+  const observedAt = Date.parse(availability.observedAt);
+  return !Number.isNaN(observedAt) && observedAt + windowSec * 1000 >= now;
 }
 

package/src/engine/scheduler.mjs

@@ -463,23 +463,23 @@ export async function driveRun(contract, runDir, states, campaign, lock, sourceI
   // 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; those land in `slot`, not the real `running`, so they are copied
-  // back into `running` in a `finally` -- unconditionally, win or lose, so a
-  // job a settlement started before failing (a lost lock, a programmer error)
-  // is still visible to the cleanup sweeps below rather than leaked. The
-  // node's own steps stay ordered by never starting a second settlement for a
-  // node whose first has not yet cleared `pendingSettlements`.
+  // 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 slot = new Map([[nodeId, job]]);
       const settlement = settlementQueue
-        .then(() => finalizeClosedJobs(contract, runDir, states, slot, lock, campaign.path))
-        .finally(() => {
-          for (const [settledId, settledJob] of slot) running.set(settledId, settledJob);
-          pendingSettlements.delete(nodeId);
-        });
+        .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
@@ -635,20 +635,16 @@ export async function driveRun(contract, runDir, states, campaign, lock, sourceI
           // 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
-          // its own one-entry `slot` merged back into `running` in a
-          // `finally`. The node's own order is untouched (still one entry at
-          // a time, gated by `pendingSettlements`); only the tick stops
-          // waiting behind it.
+          // `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 slot = new Map();
             const settlement = settlementQueue
-              .then(() => startJudge(contract, node, state, runDir, slot, workerResult, lock, states, campaign.path))
-              .then((round) => applyJudgeRound(round, contract, node, state, runDir, slot, lock, states, campaign.path, workerResult))
-              .finally(() => {
-                for (const [settledId, settledJob] of slot) running.set(settledId, settledJob);
-                pendingSettlements.delete(node.id);
-              });
+              .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;

package/src/engine/scope.mjs

@@ -3,15 +3,19 @@
  * touched, and what to do when those differ.
  *
  * Scope is advisory by design -- an unexpected write is recorded as a finding
- * and shown to the judge, not treated as a crime -- with one exception:
+ * and shown to the judge, not treated as a crime -- with two exceptions:
  * `resolveUnknownEffect` decides whether an invocation whose effect is unproven
- * may be replayed at all, and a dirty scope there is a refusal.
+ * may be replayed at all, and a dirty scope there is a refusal; and a write
+ * that lands on a file the node's own proof names is never deferred, because a
+ * verification that passes over an edited prover has proven nothing.
  */
+import { relative, resolve } from "node:path";
+
 import { SETTLED } from "./prompts.mjs";
 import { appendTransitionEvent, recordExecutionOverride, transition, writeNode } from "./state.mjs";
 import { attemptWorkspace } from "../repo/worktree.mjs";
 
-import { errorCode, errorMessage, excerpt } from "../util.mjs";
+import { errorCode, errorMessage, excerpt, isContained } from "../util.mjs";
 import { executeControllerVerification } from "./verify.mjs";
 import { providerReceiptsFromInvocationTail, settleInvocation } from "../run/operations.mjs";
 import { readJson } from "../run/store.mjs";
@@ -98,6 +102,94 @@ export function workerScope(taskPacket) {
     roots: taskPacket.writeRoots ?? [],
   };
 }
+/**
+ * @typedef {{tokens: string[], cwd: string, literal: boolean, citation: string}} ProofCitation
+ */
+
+/**
+ * Everything a node's own proofs name: a Definition of Done `path` proof's
+ * path, the words of a `command` proof (a command proof carries a display
+ * string, not an argv, so a quoted path holding a space is not recovered), the
+ * argv of the verification entry a `verification` proof references, and the
+ * argv of every verification command the packet declares.
+ *
+ * @param {ValidatedNode} node
+ * @returns {ProofCitation[]}
+ */
+function proofCitations(node) {
+  const commands = node.taskPacket.verification ?? [];
+  /** @type {ProofCitation[]} */
+  const citations = [];
+  // Definition of Done items come first so that a path both a checklist item
+  // and a verification command name is reported under the checklist item, the
+  // name a human reading the failure can act on.
+  for (const item of node.definitionOfDone ?? []) {
+    const proof = item.proof;
+    if (!proof) continue;
+    if (proof.kind === "path") {
+      citations.push({ tokens: [proof.ref], cwd: ".", literal: true, citation: `${item.id} path proof` });
+    } else if (proof.kind === "command") {
+      citations.push({ tokens: proof.ref.split(/\s+/u), cwd: ".", literal: false, citation: `${item.id} command proof` });
+    } else {
+      const command = commands[Number.parseInt(proof.ref, 10)];
+      if (command) citations.push({ tokens: command.argv, cwd: command.cwd ?? ".", literal: false, citation: `${item.id} verification[${proof.ref}] proof` });
+    }
+  }
+  for (const [index, command] of commands.entries()) {
+    citations.push({ tokens: command.argv, cwd: command.cwd ?? ".", literal: false, citation: `verification[${index}]` });
+  }
+  return citations;
+}
+const PATH_SEPARATOR = /[\\/]/u;
+
+/**
+ * The unexpected writes that landed on a file the node's own proof names.
+ * Matching a command's argv against files is inherently approximate, so this is
+ * lexical and deliberately narrow. A word is read as a path only when it is not
+ * an option, is shaped like one (a `path` proof's ref, or a word carrying a
+ * separator or an extension), and resolves inside the workspace; it then claims
+ * an unexpected path it equals, or -- when it carries a separator or is a `path`
+ * proof's ref, so a directory really was named -- one it is the directory
+ * prefix of.
+ *
+ * What it deliberately does not catch: a file a proof reaches through a script
+ * (`npm test`), a shell string, or a glob the tool expands itself. The bare
+ * words of a command are never paths, which is what keeps the ordinary case
+ * advisory -- measured against the real node `requirement-ids-reach-the-node`
+ * (run `state-location-and-routing-economics-10-requirement-ids-and-closure`),
+ * whose legitimate out-of-scope write to `src/plan/freeze.mjs` is claimed by
+ * none of its proofs: not by `npm run typecheck`, not by the two test files its
+ * `command` proofs name, and not by the loose words of a quoted
+ * `--test-name-pattern`.
+ *
+ * @param {ValidatedNode} node
+ * @param {string[]} unexpectedPaths
+ * @param {string} workspace
+ * @returns {{path: string, citation: string}[]}
+ */
+function proofCitedWrites(node, unexpectedPaths, workspace) {
+  /** @type {Map<string, string>} */
+  const cited = new Map();
+  for (const citation of proofCitations(node)) {
+    const base = resolve(workspace, citation.cwd);
+    for (const token of citation.tokens) {
+      if (!token || token.startsWith("-")) continue;
+      const directory = citation.literal || PATH_SEPARATOR.test(token);
+      if (!directory && !/\.[A-Za-z0-9]+$/u.test(token)) continue;
+      const target = resolve(base, token);
+      if (!isContained(workspace, target)) continue;
+      const named = relative(workspace, target).replaceAll("\\", "/");
+      // The workspace root itself names no file in particular: a proof run from
+      // the root must not make every unexpected write a proof-citing one.
+      if (!named) continue;
+      for (const path of unexpectedPaths) {
+        if (cited.has(path)) continue;
+        if (path === named || (directory && path.startsWith(`${named}/`))) cited.set(path, citation.citation);
+      }
+    }
+  }
+  return [...cited].map(([path, citation]) => ({ path, citation }));
+}
 /**
  * @param {ValidatedContract} contract
  * @param {string} runDir
@@ -122,9 +214,19 @@ export function checkWorkerScope(contract, runDir, job, lock, options = {}) {
     // A completed attempt whose controller verification passes never fails
     // on scope alone (TECH-SPEC lean, rule 1): the caller defers the verdict
     // until verification has run and records an advisory finding instead.
-    if (options.deferViolation) return true;
-    const shown = bounded.unexpectedPaths.slice(0, 8).join(", ");
-    const message = `unexpected paths changed (${scope.unexpectedPaths.length}): ${shown}`;
+    // The single exception is a write onto a file the node's own proof names:
+    // verification then passes because the attempt edited the thing doing the
+    // proving, and an advisory nobody must read before the gate is too weak a
+    // signal for that. Scanned over the bounded path list -- the same first 64
+    // paths every other surface reports.
+    const cited = proofCitedWrites(job.node, bounded.unexpectedPaths, job.cwd);
+    if (options.deferViolation && !cited.length) return true;
+    const message = cited.length
+      // Kept short on purpose: an error message is capped at 120 characters,
+      // and the proof that names the path is the part a reader cannot recover
+      // from `state.scope` afterwards.
+      ? `proof-cited unexpected write (${cited.length}): ${cited.slice(0, 8).map(({ path, citation }) => `${path} (${citation})`).join(", ")}`
+      : `unexpected paths changed (${scope.unexpectedPaths.length}): ${bounded.unexpectedPaths.slice(0, 8).join(", ")}`;
     if (!SETTLED.has(state.status)) {
       transition(runDir, state, "failed", { phase: "worker", error: { code: "unexpected_write", message: excerpt(message) } }, lock);
       appendTransitionEvent(runDir, state, "failed", "failed", {