faberun 0.14.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Faberun is a development orchestration system that turns intent into verified software: harness- and model-agnostic, it keeps the intent, coordinates the work, verifies the result and decides what happens next.",
   "type": "module",
   "bin": {

package/src/cli/plan.mjs

@@ -11,6 +11,8 @@ import { classifyRunProgress } from "../campaign/chain.mjs";
 import { runProgress } from "../engine/supervise.mjs";
 import { DISCOVERY_RUNTIME_DEFINITIONS } from "../engine/runtime-discovery.mjs";
 import { validateRuntime } from "../contract/runtime.mjs";
+import { validateFinalVerification, validateSharedVerification } from "../contract/final-verification.mjs";
+import { colorLevel, statusToken } from "./brand.mjs";
 import { delay } from "../util.mjs";
 import { runPlanningPipeline } from "../plan/pipeline.mjs";
 import { runDirectory } from "../run/paths.mjs";
@@ -79,9 +81,40 @@ export function loadRuntimesCatalogue(path) {
   return runtimes;
 }
 
+/**
+ * A `--verification <path>` catalogue: a JSON object carrying either or both
+ * of the contract's own suite keys, `sharedVerification` and
+ * `finalVerification`, each validated with the same validator
+ * `validateContract` applies. A key that is not a contract suite is refused
+ * rather than ignored: a typo'd key would freeze a contract that looks
+ * ratcheted and is not, which is the failure mode this flag exists to close.
+ *
+ * @param {string} path
+ * @returns {{sharedVerification?: import("../contract/index.mjs").VerificationCommand[], finalVerification?: import("../contract/index.mjs").VerificationCommand[]}}
+ */
+export function loadVerificationSuites(path) {
+  const resolved = resolve(path);
+  /** @type {unknown} */
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(resolved, "utf8"));
+  } catch (error) {
+    throw new Error(`--verification ${path} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`--verification ${path} must be a JSON object`);
+  const record = /** @type {Record<string, unknown>} */ (raw);
+  for (const key of Object.keys(record)) {
+    if (key !== "sharedVerification" && key !== "finalVerification") throw new Error(`--verification ${path} must carry only sharedVerification and finalVerification: ${key}`);
+  }
+  return {
+    ...(record.sharedVerification === undefined ? {} : { sharedVerification: validateSharedVerification(record.sharedVerification, "contract.sharedVerification") }),
+    ...(record.finalVerification === undefined ? {} : { finalVerification: validateFinalVerification(record.finalVerification, "contract.finalVerification") }),
+  };
+}
+
 /**
  * @param {string} target
- * @param {{campaign?: string, phase?: string, "review-rounds"?: string, "approve-below"?: string, "runtime-defaults"?: string, runtimes?: string, detach?: boolean, json?: boolean}} values
+ * @param {{campaign?: string, phase?: string, "review-rounds"?: string, "approve-below"?: string, "runtime-defaults"?: string, runtimes?: string, verification?: string, detach?: boolean, json?: boolean}} values
  * @returns {Promise<void>}
  */
 export async function planCli(target, values) {
@@ -95,12 +128,16 @@ export async function planCli(target, values) {
   const runtimes = typeof values.runtimes === "string" && values.runtimes
     ? loadRuntimesCatalogue(values.runtimes)
     : DISCOVERY_RUNTIME_DEFINITIONS;
+  const verification = typeof values.verification === "string" && values.verification
+    ? loadVerificationSuites(values.verification)
+    : {};
 
   if (values.detach === true) {
     const argv = ["plan", specPath, "--campaign", campaignId, "--phase", phase, "--review-rounds", String(reviewRounds)];
     if (approveBelow !== undefined) argv.push("--approve-below", approveBelow);
     if (values["runtime-defaults"] !== undefined) argv.push("--runtime-defaults", values["runtime-defaults"]);
     if (typeof values.runtimes === "string" && values.runtimes) argv.push("--runtimes", resolve(values.runtimes));
+    if (typeof values.verification === "string" && values.verification) argv.push("--verification", resolve(values.verification));
     const child = detachArgv(argv);
     if (child.pid === undefined) throw new Error("detached plan has no pid");
     process.stdout.write(`[plan] detached · pid ${child.pid} · ${specPath}\n`);
@@ -115,6 +152,7 @@ export async function planCli(target, values) {
     approveBelow,
     runtimeDefaults,
     runtimes,
+    verification,
     launch: async (contractPath, contract) => {
       const child = detachSelf("run", contractPath);
       if (child.pid === undefined) throw new Error("detached planning run has no pid");
@@ -139,5 +177,6 @@ export async function planCli(target, values) {
     process.exitCode = 1;
     return;
   }
+  for (const warning of result.warnings) process.stdout.write(`${statusToken("warn", colorLevel(process.env, process.stdout.isTTY))} ${warning}\n`);
   process.stdout.write(`[plan] ${campaignId} phase ${phase} frozen · approved ${result.approved} · ${result.contractPath}\n`);
 }

package/src/cli.mjs

@@ -122,6 +122,7 @@ export const COMMAND_OPTIONS = {
     "approve-below": { type: "string" },
     "runtime-defaults": { type: "string" },
     runtimes: { type: "string" },
+    verification: { type: "string" },
     detach: { type: "boolean" },
     json: { type: "boolean" },
   },

package/src/contract/runtime.mjs

@@ -1,13 +1,15 @@
 /**
  * A declared runtime: its fields, the harness names it may name, whether its
- * permission mode can execute a command, and how a role resolves to one.
+ * permission mode can execute a command, and how a role resolves to one -- the
+ * latter including the strategies a routing rule may name, which are authored
+ * protocol surface a reader can reject by name just like a harness name.
  *
  * Split out because both the contract validator and the snapshot validator need
  * it -- a persisted `runtime` on a node snapshot is the shape the contract
  * declared -- and the snapshot validator should not import the contract
  * validator to reach it.
  */
-import { assertObject, nonNegativeNumber, positiveInteger, positiveNumber, rejectUnknown, requireId, requireString, requireStringArray } from "./assert.mjs";
+import { assertObject, nonNegativeNumber, positiveInteger, positiveNumber, rejectUnknown, requireId, requireString, requireStringArray, requireTimestamp } from "./assert.mjs";
 import { composeAssignments } from "../engine/runtime-discovery.mjs";
 import { harnessCapabilities, resolvePermissionExecution, resolveVendor, validateCapabilityRequirements } from "../harnesses/index.mjs";
 import { stableJson } from "../util.mjs";
@@ -26,6 +28,19 @@ const RUNTIME_FIELDS = new Set([
 ]);
 const RUNTIME_HARNESSES = new Set(["claude", "codex", "agy", "dsh", "zcode", "exec-jsonl", "replay"]);
 
+/**
+ * The strategies a routing rule may name: how a rule consumes its `prefer`
+ * list. `priority` takes the first admissible candidate; `cost` the lowest
+ * declared `costRank`; `reset-proximity` the least observed `remaining`
+ * allowance -- the window nearest its reset is spent first; `attempt-affinity`
+ * the previous attempt's runtime for the same node. A strategy whose datum a
+ * given runtime does not expose is inert for that runtime -- never a failure.
+ * An assignment records `declared` instead of any of these when an operator's
+ * runtime instruction prevailed over the table and every strategy.
+ * @typedef {"priority" | "cost" | "reset-proximity" | "attempt-affinity"} RoutingStrategy
+ */
+export const ROUTING_STRATEGIES = Object.freeze(new Set(["priority", "cost", "reset-proximity", "attempt-affinity"]));
+
 /**
  * Harness-specific stall thresholds where the contract's single default is
  * wrong for every turn the harness runs. `zcode` has no streaming flag: its
@@ -54,6 +69,14 @@ const CAPABILITY_FIELDS = new Set([
  */
 export function routeRuntime(contract, node, role = "worker", event = {}) {
   if (role !== "worker" && role !== "judge") throw new TypeError("route role must be worker or judge");
+  // Catalogue records entering a routing decision are validated here, the one
+  // boundary every runtime-routing reader shares; the copies persisted on node
+  // snapshots are validated where they are written.
+  if (event.availability) {
+    for (const [id, availability] of Object.entries(event.availability)) {
+      validateRuntimeAvailability(availability, `routing availability ${id}`);
+    }
+  }
   const initialRuntimeId = role === "judge"
     ? node.gate.runtime ?? contract.runtimeDefaults?.judge
     : node.runtime ?? contract.runtimeDefaults?.worker;
@@ -149,6 +172,31 @@ function validatePricing(value, label) {
     if (rate < 0) throw new TypeError(`${label}.${key} must not be negative`);
   }
 }
+/** The fields of one runtime-catalogue record (`RuntimeAvailability`). */
+const AVAILABILITY_FIELDS = new Set(["available", "exhaustedUntil", "reason", "observedAt", "window", "remaining"]);
+
+/**
+ * One runtime-catalogue record: what the harness de facto reported, and when.
+ * The three classified fields are required; the observables may be absent (a
+ * record that predates the field) or null (the harness exposes nothing -- never
+ * zero and never full allowance), but a present one must be typed: a record is
+ * persisted or read into a routing decision only through validators that can
+ * say what each datum means.
+ *
+ * @param {unknown} value
+ * @param {string} label
+ */
+export function validateRuntimeAvailability(value, label) {
+  assertObject(value, label);
+  rejectUnknown(value, AVAILABILITY_FIELDS, label);
+  if (typeof value.available !== "boolean") throw new TypeError(`${label}.available must be boolean`);
+  if (value.exhaustedUntil !== undefined && value.exhaustedUntil !== null) requireTimestamp(value.exhaustedUntil, `${label}.exhaustedUntil`);
+  requireString(value.reason, `${label}.reason`);
+  if (value.observedAt !== undefined && value.observedAt !== null) requireTimestamp(value.observedAt, `${label}.observedAt`);
+  if (value.window !== undefined && value.window !== null) requireString(value.window, `${label}.window`);
+  if (value.remaining !== undefined && value.remaining !== null) nonNegativeNumber(value.remaining, `${label}.remaining`);
+}
+
 /**
  * @param {Record<string, ValidatedRuntime>} runtimes
  * @param {string} runtimeId

package/src/contract/verification.mjs

@@ -21,12 +21,28 @@ export const VERIFICATION_LIMITS = Object.freeze({
   snapshotPathBytes: 1024,
 });
 
+/**
+ * The declared risk tiers and the fraction of sampled mutants a suite must kill
+ * for a `mutation` verification entry to pass. The tier is what the entry
+ * declares; the fraction is not re-picked per entry, so two nodes at the same
+ * tier sit the same bar. The wall-clock budget that bounds how many mutants run
+ * at all is a measurement, not policy, and lives with the runner that enforces
+ * it (`MUTATION_TIME_BUDGET_MS`, `src/engine/mutation.mjs`).
+ */
+export const MUTATION_TIERS = Object.freeze({
+  high: 1,
+  medium: 0.75,
+  low: 0.5,
+});
+
+/** @typedef {keyof typeof MUTATION_TIERS} MutationTier */
+
 /** @typedef {"active"|"closed"|"failed"|"crashed"|"canceled"} VerificationAttemptStatus */
 
 /**
  * One declared deterministic check: an argv command run by the controller.
  *
- * @typedef {{argv: string[], cwd?: string, timeoutSec?: number, repeat?: number, env?: string[], mutation?: {threshold: number}}} VerificationCommand
+ * @typedef {{argv: string[], cwd?: string, timeoutSec?: number, repeat?: number, env?: string[], mutation?: {tier: MutationTier}}} VerificationCommand
  */
 
 /**
@@ -126,20 +142,20 @@ function validateVerificationCommand(command, label = "verification command") {
   const envBytes = env.reduce((sum, name) => sum + Buffer.byteLength(/** @type {string} */ (name), "utf8"), 0);
   if (envBytes > VERIFICATION_LIMITS.maxEnvBytes) throw new TypeError(`${label}.env exceeds aggregate byte limit`);
   // Mutation testing is opt-in per entry: it re-runs the same argv against
-  // deliberately broken copies of the node's written files. `threshold` is the
-  // fraction of mutants the suite must kill, so 0 accepts any suite and 1
-  // demands every sampled mutant fail it.
-  /** @type {{threshold: number}|undefined} */
+  // deliberately broken copies of the node's written files. The entry declares
+  // its risk tier; `MUTATION_TIERS` fixes the kill fraction each tier demands,
+  // so the bar is a property of the tier, not of the author's caution.
+  /** @type {{tier: MutationTier}|undefined} */
   let mutation;
   if (record.mutation !== undefined) {
     const rawMutation = record.mutation;
-    if (!rawMutation || typeof rawMutation !== "object" || Array.isArray(rawMutation)) throw new TypeError(`${label}.mutation must be an object with a threshold between 0 and 1`);
+    if (!rawMutation || typeof rawMutation !== "object" || Array.isArray(rawMutation)) throw new TypeError(`${label}.mutation must be an object with a declared risk tier`);
     const mutationRecord = /** @type {Record<string, unknown>} */ (rawMutation);
-    for (const key of Object.keys(mutationRecord)) if (key !== "threshold") throw new TypeError(`${label}.mutation has unexpected field ${key}`);
-    if (typeof mutationRecord.threshold !== "number" || !Number.isFinite(mutationRecord.threshold) || mutationRecord.threshold < 0 || mutationRecord.threshold > 1) {
-      throw new TypeError(`${label}.mutation.threshold must be a number between 0 and 1`);
+    for (const key of Object.keys(mutationRecord)) if (key !== "tier") throw new TypeError(`${label}.mutation has unexpected field ${key}`);
+    if (typeof mutationRecord.tier !== "string" || !Object.hasOwn(MUTATION_TIERS, mutationRecord.tier)) {
+      throw new TypeError(`${label}.mutation.tier must be one of ${Object.keys(MUTATION_TIERS).join(", ")}`);
     }
-    mutation = { threshold: mutationRecord.threshold };
+    mutation = { tier: /** @type {MutationTier} */ (mutationRecord.tier) };
   }
   /** @type {VerificationCommand} */
   const normalized = { argv: [.../** @type {string[]} */ (record.argv)], timeoutSec, repeat, env: [.../** @type {string[]} */ (env)] };

package/src/engine/assignment.mjs

@@ -20,9 +20,17 @@ import { transition } from "./state.mjs";
 /**
  * Resolve role assignments once at run creation. Discovery is used only for
  * omitted roles; the resulting pair is persisted so resume is deterministic.
+ * Alongside it, `decisions` records, for every assignment, the strategy that
+ * was applied and the reason for the choice: `declared` with the declaring
+ * field when the contract named the runtime -- an operator instruction
+ * prevails over every strategy -- or the discovery ranking that composed an
+ * omitted role. The record lives at this boundary, not on the persisted
+ * assignment entries, because the snapshot's routing.allowlist still carries
+ * the classified fields only (the same declared lag as the catalogue
+ * observables); it widens when a reader needs the record durably.
  *
  * @param {ValidatedContract} contract
- * @returns {Promise<{assignments: Record<string, {worker: string, judge: string, composedWorker: boolean, composedJudge: boolean}>, availability: Record<string, import("./runtime-discovery.mjs").RuntimeAvailability>}>}
+ * @returns {Promise<{assignments: Record<string, {worker: string, judge: string, composedWorker: boolean, composedJudge: boolean}>, decisions: Record<string, {worker: {strategy: string|null, reason: string}, judge: {strategy: string|null, reason: string}}>, availability: Record<string, import("./runtime-discovery.mjs").RuntimeAvailability>}>}
  */
 export async function runtimeAssignments(contract) {
   const needsComposition = contract.nodes.some((node) =>
@@ -31,15 +39,34 @@ export async function runtimeAssignments(contract) {
   const availability = needsComposition ? await discoverRuntimes(contract.runtimes, { cwd: contract.cwd }) : {};
   const config = readUserConfig(process.env);
   const assignments = composeAssignments(contract, availability, { config });
+  /** @type {Record<string, {worker: {strategy: string|null, reason: string}, judge: {strategy: string|null, reason: string}}>} */
+  const decisions = {};
   return {
     assignments: Object.fromEntries(Object.entries(assignments).map(([nodeId, assignment]) => {
       const node = contract.nodes.find((candidate) => candidate.id === nodeId);
-      return [nodeId, {
-        ...assignment,
-        composedWorker: node?.runtime === undefined && contract.runtimeDefaults?.worker === undefined,
-        composedJudge: Boolean(node?.gate.enabled && node.gate.runtime === undefined && contract.runtimeDefaults?.judge === undefined),
-      }];
+      const composedWorker = node?.runtime === undefined && contract.runtimeDefaults?.worker === undefined;
+      const composedJudge = Boolean(node?.gate.enabled && node.gate.runtime === undefined && contract.runtimeDefaults?.judge === undefined);
+      // A judge the gate never asks for is no choice at all: no strategy
+      // decided it, so none is recorded.
+      const judgeSource = node?.gate.enabled && node.gate.runtime !== undefined
+        ? "gate runtime"
+        : contract.runtimeDefaults?.judge !== undefined ? "runtimeDefaults.judge" : null;
+      const workerSource = node?.runtime !== undefined
+        ? "node runtime"
+        : contract.runtimeDefaults?.worker !== undefined ? "runtimeDefaults.worker" : null;
+      decisions[nodeId] = {
+        worker: {
+          strategy: composedWorker ? "cost" : workerSource !== null ? "declared" : null,
+          reason: composedWorker ? "discovery: cheapest available runtime" : /** @type {string} */ (workerSource),
+        },
+        judge: {
+          strategy: composedJudge ? "priority" : judgeSource !== null ? "declared" : null,
+          reason: composedJudge ? "discovery: strongest available runtime" : /** @type {string} */ (judgeSource ?? "no judge required"),
+        },
+      };
+      return [nodeId, { ...assignment, composedWorker, composedJudge }];
     })),
+    decisions,
     availability,
   };
 }

package/src/engine/backoff.mjs

@@ -476,6 +476,12 @@ const MAX_ROUTING_HISTORY = 64;
 /**
  * The override reason recorded on the node, in the operator's words.
  *
+ * The reason also names the attempt-affinity outcome, because the override is
+ * the role's working assignment and the record of why it names the runtime it
+ * names: a reset holds affinity (the previous attempt's runtime stays warm
+ * for the retry), an edge yields it (the previous runtime is the one that
+ * just failed, and the reason quotes its code).
+ *
  * @param {Transition} schedule
  * @param {"worker"|"judge"} role
  * @param {string} current
@@ -484,10 +490,10 @@ const MAX_ROUTING_HISTORY = 64;
  */
 function routeReason(schedule, role, current, error) {
   if (schedule.kind === "reset" && schedule.reason === "quota_reset") {
-    return `${role} provider ${current} quota resets at ${schedule.at}: ${error.message}`;
+    return `${role} provider ${current} quota resets at ${schedule.at}: ${error.message}; attempt-affinity held: ${current} keeps the node's context for the retry`;
   }
-  if (schedule.kind === "reset") return `${role} provider ${current} hit a transient network failure, retrying at ${schedule.at}: ${error.message}`;
-  if (schedule.reason === "network_backoff") return `${role} provider ${current} kept failing on the network: ${error.message}`;
-  if (schedule.reason === "protocol_failure") return `${role} provider ${current} could not hold the result protocol: ${error.message}`;
-  return `${role} provider ${current} exhausted: ${error.message}`;
+  if (schedule.kind === "reset") return `${role} provider ${current} hit a transient network failure, retrying at ${schedule.at}: ${error.message}; attempt-affinity held: ${current} keeps the node's context for the retry`;
+  if (schedule.reason === "network_backoff") return `${role} provider ${current} kept failing on the network: ${error.message}; attempt-affinity yielded: ${current} reported ${error.code}`;
+  if (schedule.reason === "protocol_failure") return `${role} provider ${current} could not hold the result protocol: ${error.message}; attempt-affinity yielded: ${current} reported ${error.code}`;
+  return `${role} provider ${current} exhausted: ${error.message}; attempt-affinity yielded: ${current} reported ${error.code}`;
 }

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: