faberun 0.12.1 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.12.1",
+  "version": "0.14.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/skills/faberun/references/contract.md

@@ -297,19 +297,19 @@ offered to a second node, so one session runs one turn.
 
 ## Gates
 
-`gate: false` skips review (`none`). A gate object accepts `runtime`
-(judge override), `review` (`none`/`advisory`/`blocking`, default
-`advisory`), `failOn` (default `["critical"]`), `maxRevisions` (default 1).
-`advisory` records the verdict, findings and `maxSeverity` and still settles
-`done` on deterministic verification alone — it never consumes a revision or
-re-dispatches. `blocking` re-dispatches within `maxRevisions` when findings
+`gate: false` skips review; the node keeps `maxRevisions` (default 1) fresh
+attempts after a red verification, and `{ enabled: false, maxRevisions: 0 }`
+makes the first red one final. A gate object accepts `runtime` (the judge),
+`review` (`none`/`advisory`/`blocking`, default `advisory`), `failOn`
+(default `["critical"]`) and `maxRevisions`. `advisory` records the verdict
+and still settles `done` on deterministic verification alone, never
+re-dispatching; `blocking` re-dispatches within `maxRevisions` when findings
 reach `failOn`. Validation requires `critical` whenever `major` is in
 `failOn`, and `major` in `failOn` for a `blocking` gate: `["critical"]` alone
-passes every major finding, which is close to no gate.
+passes every major finding.
 
-The revision budget counts gate rejections, not worker starts; a resume or a
-crash-restart never consumes one (tracked separately as `attempt` vs.
-`revisions`). Deterministic `verification` commands run once by default
+The revision budget counts rejections, not worker starts; a resume or a
+crash-restart never consumes one. Deterministic `verification` commands run once by default
 before any judge and the judge reviews the recorded results, never
 re-running them (`repeat` opts into re-running a flaky check). A judge
 output is `pass` only with empty `findings` and `maxSeverity: none`; for

package/src/campaign/index.mjs

@@ -21,7 +21,9 @@ import { handoffFromState, materializeHandoff } from "./handoff.mjs";
 /** @typedef {{path: string, digest: string}} CampaignContract */
 /** @typedef {{runId: string, contractPath?: string, branch: string, sha: string, previousSha: string|null, at: string}} PromotionRecord */
 /** @typedef {{code: string, message: string, at: string, contractPath?: string, contractId?: string, runId?: string, node?: string|null, status?: string|null, resume?: string}} CampaignAttention */
-/** @typedef {{id: string, goal: string, status: "active"|"closed", linkedRunIds: string[], contracts: CampaignContract[], landBranch: string, promotions: PromotionRecord[], attention?: CampaignAttention, createdAt: string, updatedAt: string, closedAt?: string}} Campaign */
+/** @typedef {{runId: string, node: string, passed: boolean|null, verdict: string|null}} RequirementNodeEvidence */
+/** @typedef {{requirementId: string, status: "covered"|"open", nodes: RequirementNodeEvidence[]}} RequirementClosure */
+/** @typedef {{id: string, goal: string, status: "active"|"closed", linkedRunIds: string[], contracts: CampaignContract[], landBranch: string, promotions: PromotionRecord[], attention?: CampaignAttention, requirements?: RequirementClosure[], createdAt: string, updatedAt: string, closedAt?: string}} Campaign */
 /** @typedef {{type: string, eventId: string, at: string, sessionId?: string, text?: string, tool?: string, transcript?: string|null, transcriptUnavailable?: boolean, format?: string|null, cursor?: string|null, decisionId?: string, supersedes?: string, runId?: string, questionId?: string, campaignId?: string, nodeId?: string|null, phase?: string, checkpointsDone?: number, checkpointsTotal?: number, runtime?: string|null, state?: string, lastProgressAt?: string, attention?: string|null}} JournalEntry */
 /** @typedef {{updatedAt: string|null, decisions: Record<string, JournalEntry>, questions: Record<string, JournalEntry>, constraints: JournalEntry[], intents: JournalEntry[], outcomes: JournalEntry[], sessions: JournalEntry[], next: JournalEntry|null, evicted: Record<string, number>}} Projection */
 /** @typedef {{cursor: number, byte: number, size: number, projection: Projection}} ProjectionRecord */
@@ -135,12 +137,82 @@ export function closeCampaign(campaignPath, { at = new Date().toISOString(), eve
   }
   const repoRoot = campaignRepoRoot(campaignPath);
   const ledgerFiles = preserveCampaignLedger(campaignPath, repoRoot);
-  const closed = /** @type {Campaign} */ ({ ...campaign, status: "closed", closedAt: at, updatedAt: at });
+  // The closure travels on the record itself, computed in one deterministic
+  // pass over the linked runs' own files before the close is written.
+  const requirements = buildRequirementClosure(campaignPath, campaign);
+  /** @type {Campaign} */
+  const closed = { ...campaign, status: "closed", closedAt: at, updatedAt: at, requirements };
   writeJsonAtomic(join(campaignPath, CAMPAIGN_FILE), closed);
   appendJournal(campaignPath, { type: "campaign.closed", at, eventId });
   return { path: campaignPath, campaign: closed, ledgerFiles };
 }
 
+/**
+ * The requirement closure a close records: one entry per requirement id the
+ * linked runs' contracts declared, correlated only by the identifiers the runs
+ * carried -- the contract node's declaration and the id the done node snapshot
+ * itself carries, stamped there by the engine -- never by requirement text. A
+ * requirement no done node carries is recorded as open rather than omitted.
+ * Deterministic and free of external calls: runs are visited in sorted id
+ * order, nodes in contract order, requirement ids sorted, and the only inputs
+ * are files already on disk. A run that never launched (or was pruned)
+ * contributes nothing.
+ *
+ * @param {string} campaignPath
+ * @param {Campaign} campaign
+ * @returns {RequirementClosure[]}
+ */
+function buildRequirementClosure(campaignPath, campaign) {
+  const runsDir = resolve(campaignPath, "..", "..");
+  /** @type {Map<string, RequirementNodeEvidence[]>} */
+  const covered = new Map();
+  /** @type {Set<string>} */
+  const declared = new Set();
+  for (const runId of [...campaign.linkedRunIds].sort()) {
+    const contract = readRunJson(join(runsDir, runId, "contract.json"));
+    const nodes = contract !== null && Array.isArray(contract.nodes) ? /** @type {JsonObject[]} */ (contract.nodes) : [];
+    for (const node of nodes) {
+      const nodeId = typeof node.id === "string" ? node.id : "";
+      const requirementIds = Array.isArray(node.requirementIds) ? node.requirementIds : [];
+      if (!nodeId || requirementIds.length === 0) continue;
+      const snapshot = readRunJson(join(runsDir, runId, "nodes", `${nodeId}.json`));
+      const done = snapshot !== null && snapshot.status === "done";
+      const carried = snapshot !== null && Array.isArray(snapshot.requirementIds) ? /** @type {unknown[]} */ (snapshot.requirementIds) : [];
+      const verification = snapshot !== null ? /** @type {JsonObject|null|undefined} */ (snapshot.verification) : undefined;
+      const gate = snapshot !== null ? /** @type {JsonObject|null|undefined} */ (snapshot.gate) : undefined;
+      const passed = verification && typeof verification.passed === "boolean" ? verification.passed : null;
+      const verdict = gate && typeof gate.verdict === "string" ? gate.verdict : null;
+      for (const requirementId of requirementIds) {
+        if (typeof requirementId !== "string") continue;
+        declared.add(requirementId);
+        if (!done || !carried.includes(requirementId)) continue;
+        const evidence = covered.get(requirementId) ?? [];
+        evidence.push({ runId, node: nodeId, passed, verdict });
+        covered.set(requirementId, evidence);
+      }
+    }
+  }
+  return [...declared].sort().map((requirementId) => {
+    const nodes = covered.get(requirementId) ?? [];
+    return { requirementId, status: nodes.length > 0 ? "covered" : "open", nodes };
+  });
+}
+
+/**
+ * @param {string} path
+ * @returns {JsonObject|null} null when the file is absent or not JSON: a run
+ * that never launched contributes nothing to the closure rather than failing
+ * the close, the same discipline `preserveCampaignLedger` applies to a run
+ * without a usage ledger.
+ */
+function readRunJson(path) {
+  try {
+    return /** @type {JsonObject} */ (JSON.parse(readFileSync(path, "utf8")));
+  } catch {
+    return null;
+  }
+}
+
 /**
  * The repository a campaign's ledger is preserved into. Under the home layout
  * the campaign path carries the project id at the resolver's fixed position,

package/src/campaign/record.mjs

@@ -99,4 +99,32 @@ function validateCampaign(campaign) {
       if (promotion.contractPath !== undefined) requireString(promotion.contractPath, `campaign.promotions[${index}].contractPath`);
     }
   }
+  // The requirement closure a close records: one entry per requirement id the
+  // linked runs' contracts declared, correlated by the identifiers the runs
+  // carried, with every uncovered requirement kept as open. Optional on read
+  // so a campaign closed before the field existed stays readable.
+  if (record.requirements !== undefined) {
+    if (!Array.isArray(record.requirements)) throw new TypeError("campaign.requirements must be an array");
+    for (const [index, entry] of record.requirements.entries()) {
+      assertObject(entry, `campaign.requirements[${index}]`);
+      const closure = /** @type {JsonObject} */ (entry);
+      requireId(closure.requirementId, `campaign.requirements[${index}].requirementId`);
+      if (closure.status !== "covered" && closure.status !== "open") {
+        throw new TypeError(`campaign.requirements[${index}].status must be covered or open`);
+      }
+      if (!Array.isArray(closure.nodes)) throw new TypeError(`campaign.requirements[${index}].nodes must be an array`);
+      for (const [position, evidence] of closure.nodes.entries()) {
+        assertObject(evidence, `campaign.requirements[${index}].nodes[${position}]`);
+        const node = /** @type {JsonObject} */ (evidence);
+        requireId(node.runId, `campaign.requirements[${index}].nodes[${position}].runId`);
+        requireId(node.node, `campaign.requirements[${index}].nodes[${position}].node`);
+        if (node.passed !== null && typeof node.passed !== "boolean") {
+          throw new TypeError(`campaign.requirements[${index}].nodes[${position}].passed must be a boolean or null`);
+        }
+        if (node.verdict !== null && typeof node.verdict !== "string") {
+          throw new TypeError(`campaign.requirements[${index}].nodes[${position}].verdict must be a string or null`);
+        }
+      }
+    }
+  }
 }

package/src/contract/index.mjs

@@ -32,16 +32,25 @@ const WRITE_FILE_LINE_WARN_MARGIN = 100;
 
 const CONTRACT_FIELDS = new Set([
   "schemaVersion", "contractVersion", "id", "campaignId", "goal", "cwd", "sourceIdentity",
-  "maxParallel", "pollIntervalMs", "stallTimeoutSec", "timeoutSec",
+  "maxParallel", "pollIntervalMs", "stallTimeoutSec", "timeoutSec", "maxTurns", "phaseSessionReuse",
   "runtimeDefaults", "runtimes", "nodes", "warnings", "finalVerification", "sharedVerification", "nodeAdvisory",
 ]);
 const DEFAULTS_FIELDS = new Set(["worker", "judge"]);
 const NODE_FIELDS = new Set([
-  "id", "type", "phase", "runtime", "dependsOn", "taskPacket", "taskPacketFile", "prompt", "promptFile",
-  "definitionOfDone", "gate", "timeoutSec",
+  "id", "type", "phase", "requirementIds", "runtime", "dependsOn", "taskPacket", "taskPacketFile", "prompt", "promptFile",
+  "definitionOfDone", "gate", "timeoutSec", "maxTurns",
   "requiredCapabilities", "packetHash", "sourceIdentity", "replayPolicy",
 ]);
 const REPLAY_POLICIES = new Set(["safe", "reconcile", "never"]);
+/**
+ * Provider requests one attempt may make before the controller ends it, when
+ * neither the contract nor the node says otherwise. measured 2026-09-20 over
+ * 200 completed claude worker turns: p90 83, p95 96, p99 122, max 339; the 23
+ * turns that never produced a result held 25% of all context spend, and six
+ * of them ran past 150 (180 to 600 requests). One completed turn would have
+ * been cut and retried once.
+ */
+export const DEFAULT_MAX_TURNS = 150;
 const GATE_FIELDS = new Set(["enabled", "runtime", "review", "failOn", "maxRevisions", "requiredCapabilities", "skipWhen"]);
 const GATE_REVIEWS = new Set(["none", "advisory", "blocking"]);
 
@@ -55,13 +64,13 @@ const GATE_REVIEWS = new Set(["none", "advisory", "blocking"]);
 
 /** @typedef {{mode: "execution"|"discovery"|"autonomous", objective: string, instructions: string[], readFiles: string[], writeFiles?: string[], writeRoots?: string[], symbols: string[], scopeAcknowledged?: string[], decisions: string[], nonGoals: string[], verification: VerificationCommand[]}} TaskPacket */
 
-/** @typedef {{harness: "claude"|"codex"|"agy"|"dsh"|"zcode"|"exec-jsonl"|"replay", model: string, reasoning?: string, sandbox?: "read-only"|"workspace-write"|"danger-full-access", permissionMode?: string, config?: Record<string, unknown>, printTimeout?: string, tools?: string[], executable?: string, args?: string[], versionArgs?: string[], maxArgvPromptBytes?: number, requiredCapabilities?: CapabilityRequirements, costRank?: number, fallback?: string, vendor: string, tier?: number|string, stallTimeoutSec?: number}} ValidatedRuntime */
+/** @typedef {{harness: "claude"|"codex"|"agy"|"dsh"|"zcode"|"exec-jsonl"|"replay", model: string, reasoning?: string, sandbox?: "read-only"|"workspace-write"|"danger-full-access", permissionMode?: string, config?: Record<string, unknown>, printTimeout?: string, tools?: string[], executable?: string, args?: string[], versionArgs?: string[], maxArgvPromptBytes?: number, requiredCapabilities?: CapabilityRequirements, costRank?: number, fallback?: string, vendor: string, tier?: number|string, stallTimeoutSec?: number, maxConcurrent?: number}} ValidatedRuntime */
 
 /** @typedef {{enabled: boolean, review?: ("none"|"advisory"|"blocking"), runtime?: string, failOn?: ("minor"|"major"|"critical")[], maxRevisions?: number, requiredCapabilities?: CapabilityRequirements, skipWhen?: {verificationGreen: true, maxChangedPaths: number}}} ValidatedGate */
 
-/** @typedef {{id: string, type: string, phase: string, runtime?: string, dependsOn: string[], taskPacket: TaskPacket, taskPacketFile?: string, prompt: string, definitionOfDone: import("./definition-of-done.mjs").DefinitionOfDoneItem[], gate: ValidatedGate, timeoutSec?: number, requiredCapabilities: CapabilityRequirements, packetHash: string, sourceIdentity: SourceIdentity, replayPolicy: "safe"|"reconcile"|"never"}} ValidatedNode */
+/** @typedef {{id: string, type: string, phase: string, requirementIds?: string[], runtime?: string, dependsOn: string[], taskPacket: TaskPacket, taskPacketFile?: string, prompt: string, definitionOfDone: import("./definition-of-done.mjs").DefinitionOfDoneItem[], gate: ValidatedGate, timeoutSec?: number, maxTurns?: number, requiredCapabilities: CapabilityRequirements, packetHash: string, sourceIdentity: SourceIdentity, replayPolicy: "safe"|"reconcile"|"never"}} ValidatedNode */
 
-/** @typedef {{schemaVersion: number, contractVersion: string, id: string, campaignId: string, goal: string, cwd: string, sourceIdentity: SourceIdentity, runtimes: Record<string, ValidatedRuntime>, runtimeDefaults: {worker?: string, judge?: string}, nodes: ValidatedNode[], maxParallel: number, pollIntervalMs: number, stallTimeoutSec: number, timeoutSec: number, finalVerification?: VerificationCommand[], sharedVerification?: VerificationCommand[], nodeAdvisory?: NodeAdvisoryPolicy, warnings: string[]}} ValidatedContract */
+/** @typedef {{schemaVersion: number, contractVersion: string, id: string, campaignId: string, goal: string, cwd: string, sourceIdentity: SourceIdentity, runtimes: Record<string, ValidatedRuntime>, runtimeDefaults: {worker?: string, judge?: string}, nodes: ValidatedNode[], maxParallel: number, pollIntervalMs: number, stallTimeoutSec: number, timeoutSec: number, maxTurns: number, phaseSessionReuse: boolean, finalVerification?: VerificationCommand[], sharedVerification?: VerificationCommand[], nodeAdvisory?: NodeAdvisoryPolicy, warnings: string[]}} ValidatedContract */
 /** @typedef {{costUsd?: number, durationSec?: number}} NodeAdvisoryPolicy */
 
 /** @typedef {"pending"|"running"|"done"|"no-op"|"blocked"|"failed"|"exhausted"|"stalled"|"canceled"} NodeStatus */
@@ -89,11 +98,11 @@ const GATE_REVIEWS = new Set(["none", "advisory", "blocking"]);
 /** @typedef {{history: RoutingHistoryEntry[], currentOverride: RoutingOverride|null, assignments?: RuntimeAssignments, availability?: Record<string, RuntimeAvailability>, tierExhaustion?: TierExhaustion, tierExhaustionCycle?: number}} RoutingState */
 /** @typedef {{revision?: number, heartbeatCount: number, dryHeartbeatCount: number, progressSignature?: string|null, lastHeartbeatAt: string|null, lastProgressAt: string|null, nextCheckAt?: string|null}} ProgressState */
 /** @typedef {{status: "unassigned"|"provisioning"|"ready"|"failed"|"removed", path: string|null, branch: string|null, commit: string|null, baseSha?: string|null, sealedSha?: string|null, sealError?: string|null, previousAttempt?: number|null}} WorktreeState */
-/** @typedef {{schemaVersion: number, contractVersion: string, id: string, type: string, sourceIdentity: SourceIdentity, packetHash: string, status: NodeStatus, phase: NodePhase, attempt: number, revisions: number, judgeFailures?: number, review?: ("none"|"advisory"|"blocking"), runtime: RuntimeSnapshot|null, blockedBy: string[], startedAt: string|null, updatedAt: string, result: unknown, gate: GateResult|null, error: SnapshotError|null, usage?: Usage, costUsd?: number, routing?: RoutingState|null, progress?: ProgressState|null, worktree?: WorktreeState|null, integratedHead?: string|null, invocations?: Invocation[], executionOverrides?: ExecutionOverride[], verification?: VerificationState|null, scope?: BoundedScope|null, scopeFindings?: ScopeFindings|null, previousAttempt?: string, sessionPolicy?: {forceFresh?: boolean}|null, declaredReadBytes?: number|null}} NodeSnapshot */
+/** @typedef {{schemaVersion: number, contractVersion: string, id: string, type: string, sourceIdentity: SourceIdentity, packetHash: string, requirementIds?: string[], status: NodeStatus, phase: NodePhase, attempt: number, revisions: number, judgeFailures?: number, review?: ("none"|"advisory"|"blocking"), runtime: RuntimeSnapshot|null, blockedBy: string[], startedAt: string|null, updatedAt: string, result: unknown, gate: GateResult|null, error: SnapshotError|null, usage?: Usage, costUsd?: number, routing?: RoutingState|null, progress?: ProgressState|null, worktree?: WorktreeState|null, integratedHead?: string|null, invocations?: Invocation[], executionOverrides?: ExecutionOverride[], verification?: VerificationState|null, scope?: BoundedScope|null, scopeFindings?: ScopeFindings|null, previousAttempt?: string, sessionPolicy?: {forceFresh?: boolean}|null, declaredReadBytes?: number|null}} NodeSnapshot */
 /** @typedef {{path: string, sha: string}} ControllerIdentity */
 /** @typedef {{schemaVersion: number, contractVersion: string, pid: number, processStartToken: string|null, startedAt: string, sourceIdentity: SourceIdentity, controllerIdentity?: ControllerIdentity, integrationRef?: string, identityWarnings?: string[], relaunchCount?: number, lastRelaunchProgressAt?: string|null, attention?: {code: string, message: string, at: string}|null, contractDigest?: string, scopeDecision?: ScopeDecision, autoRetries?: Record<string, {code: string, at: string}>}} RunMetadata */
 /** @typedef {{at: string, base: string|null, dirtyTreeFingerprint: string|null}} ScopeDecision */
-/** @typedef {{schemaVersion: number, contractVersion: string, at: string, node: string, from?: string, to: string, type?: string, phase?: string, attempt?: number, role?: "worker"|"judge", status?: NodeStatus, runtime?: string, currentRuntime?: string, errorCode?: string, error?: SnapshotError, verdict?: string, summary?: string, revisions?: number, sourceIdentity: SourceIdentity, packetHash: string, override?: unknown, recovery?: unknown, invocationId?: string, unexpectedPaths?: string[], unexpectedPathCount?: number}} EventRecord */
+/** @typedef {{schemaVersion: number, contractVersion: string, at: string, node: string, from?: string, to: string, type?: string, phase?: string, attempt?: number, role?: "worker"|"judge", status?: NodeStatus, runtime?: string, currentRuntime?: string, errorCode?: string, error?: SnapshotError, verdict?: string, summary?: string, revisions?: number, requirementIds?: string[], sourceIdentity: SourceIdentity, packetHash: string, override?: unknown, recovery?: unknown, invocationId?: string, unexpectedPaths?: string[], unexpectedPathCount?: number}} EventRecord */
 
 /**
  * Validate and canonicalize the versioned contract. Runtime JSON remains
@@ -170,6 +179,17 @@ export function validateContract(raw, contractPath, options = {}) {
     ids.add(node.id);
     requireString(node.type, `nodes[${index}].type`);
     boundedString(node.phase, `nodes[${index}].phase`, 128);
+    // A node's requirementIds are inherited from its phase at freeze time
+    // (src/plan/freeze.mjs stamps them) and are optional on read: a contract
+    // without the field loads unchanged, which is what keeps CONTRACT_VERSION
+    // at 0.3.0 while requirement ids reach the node.
+    const requirementIds = node.requirementIds;
+    if (requirementIds !== undefined) {
+      if (!Array.isArray(requirementIds) || requirementIds.length > 64) {
+        throw new TypeError(`nodes[${index}].requirementIds must be an array of at most 64 requirement ids`);
+      }
+      requirementIds.forEach((id, position) => boundedString(id, `nodes[${index}].requirementIds[${position}]`, 128));
+    }
     if (node.runtime !== undefined) requireRuntime(runtimes, node.runtime, `nodes[${index}].runtime`);
     const dependsOn = node.dependsOn ?? [];
     if (!Array.isArray(dependsOn) || dependsOn.some((id) => typeof id !== "string")) {
@@ -220,6 +240,9 @@ export function validateContract(raw, contractPath, options = {}) {
     const timeoutSec = node.timeoutSec === undefined
       ? undefined
       : positiveNumber(node.timeoutSec, `nodes[${index}].timeoutSec`);
+    const maxTurns = node.maxTurns === undefined
+      ? undefined
+      : positiveInteger(node.maxTurns, `nodes[${index}].maxTurns`);
     const replayPolicy = validateReplayPolicy(node.replayPolicy, `nodes[${index}]`);
     return /** @type {ValidatedNode} */ ({
       ...node,
@@ -232,6 +255,7 @@ export function validateContract(raw, contractPath, options = {}) {
       prompt,
       gate,
       timeoutSec,
+      maxTurns,
       replayPolicy,
     });
   });
@@ -362,6 +386,14 @@ export function validateContract(raw, contractPath, options = {}) {
     pollIntervalMs: positiveInteger(raw.pollIntervalMs ?? 1_000, "contract.pollIntervalMs"),
     stallTimeoutSec: positiveNumber(raw.stallTimeoutSec ?? 300, "contract.stallTimeoutSec"),
     timeoutSec: positiveNumber(raw.timeoutSec ?? 2_400, "contract.timeoutSec"),
+    maxTurns: positiveInteger(raw.maxTurns ?? DEFAULT_MAX_TURNS, "contract.maxTurns"),
+    // Opt-in: a phase sibling's provider session is rotated (fresh session,
+    // structured summaries carried) unless the contract asks to reuse it.
+    // measured 2026-09-20 over 21 runs with both kinds of turn: a turn opened
+    // on a sibling's session cost 1.87x the fresh one at the same request
+    // count, because it began with 200k tokens of context instead of 45k and
+    // re-read them on every request.
+    phaseSessionReuse: booleanField(raw.phaseSessionReuse, false, "contract.phaseSessionReuse"),
     finalVerification: validateFinalVerification(raw.finalVerification, "contract.finalVerification"),
     sharedVerification: validateSharedVerification(raw.sharedVerification, "contract.sharedVerification"),
     nodeAdvisory: validateNodeAdvisory(raw.nodeAdvisory),
@@ -447,8 +479,16 @@ function validateGate(gate, runtimes, index, nodeId) {
   assertObject(gate, `nodes[${index}].gate`);
   rejectUnknown(gate, GATE_FIELDS, `nodes[${index}].gate`);
   if (gate.enabled === false) {
-    if (Object.keys(gate).length !== 1) throw new TypeError(`nodes[${index}].gate disabled shape only allows enabled`);
-    return { enabled: false };
+    // A disabled gate reviews nothing, but the node keeps its revision budget
+    // for a red verification (default 1, as with a gate); that budget is the
+    // one field the disabled shape may carry.
+    if (Object.keys(gate).some((key) => key !== "enabled" && key !== "maxRevisions")) {
+      throw new TypeError(`nodes[${index}].gate disabled shape only allows enabled and maxRevisions`);
+    }
+    return {
+      enabled: false,
+      ...(gate.maxRevisions === undefined ? {} : { maxRevisions: nonNegativeInteger(gate.maxRevisions, `nodes[${index}].gate.maxRevisions`) }),
+    };
   }
   if (gate.enabled !== undefined && gate.enabled !== true) {
     throw new TypeError(`nodes[${index}].gate.enabled must be true or false`);
@@ -686,3 +726,10 @@ function validateMaxParallel(value) {
   // beyond being a sane positive integer.
   return positiveInteger(value, "contract.maxParallel");
 }
+
+/** @param {unknown} value @param {boolean} fallback @param {string} label @returns {boolean} */
+function booleanField(value, fallback, label) {
+  if (value === undefined) return fallback;
+  if (typeof value !== "boolean") throw new TypeError(`${label} must be a boolean`);
+  return value;
+}

package/src/contract/runtime.mjs

@@ -22,7 +22,7 @@ import { stableJson } from "../util.mjs";
 const RUNTIME_FIELDS = new Set([
   "harness", "model", "reasoning", "sandbox", "permissionMode", "config", "printTimeout", "tools",
   "executable", "args", "versionArgs", "maxArgvPromptBytes", "requiredCapabilities", "costRank",
-  "fallback", "vendor", "tier", "pricing", "stallTimeoutSec",
+  "fallback", "vendor", "tier", "pricing", "stallTimeoutSec", "maxConcurrent",
 ]);
 const RUNTIME_HARNESSES = new Set(["claude", "codex", "agy", "dsh", "zcode", "exec-jsonl", "replay"]);
 
@@ -98,6 +98,9 @@ function validateRuntimeValues(runtime, label, executableRequired) {
     throw new TypeError(`${label}.sandbox is invalid`);
   }
   if (runtime.permissionMode !== undefined) requireString(runtime.permissionMode, `${label}.permissionMode`);
+  // How many attempts this runtime may run at once, below the run's
+  // maxParallel; absent leaves only maxParallel to bound it.
+  if (runtime.maxConcurrent !== undefined) positiveInteger(runtime.maxConcurrent, `${label}.maxConcurrent`);
   if (runtime.config !== undefined && (!runtime.config || typeof runtime.config !== "object" || Array.isArray(runtime.config))) {
     throw new TypeError(`${label}.config must be an object`);
   }

package/src/contract/snapshot.mjs

@@ -127,7 +127,7 @@ export function validateNodeSnapshot(value, expectedNode = null) {
   assertObject(value, "node snapshot");
   rejectUnknown(value, new Set([
     "schemaVersion", "contractVersion", "id", "type", "sourceIdentity", "packetHash", "status", "phase",
-    "attempt", "revisions", "judgeFailures", "runtime", "blockedBy", "startedAt", "updatedAt", "result", "gate", "error", "usage",
+    "attempt", "revisions", "judgeFailures", "requirementIds", "runtime", "blockedBy", "startedAt", "updatedAt", "result", "gate", "error", "usage",
     "costUsd", "routing", "progress", "worktree", "invocations", "executionOverrides", "verification", "scope",
     "scopeFindings", "review", "previousAttempt", "sessionPolicy", "integratedHead", "declaredReadBytes",
   ]), "node snapshot");
@@ -139,6 +139,10 @@ export function validateNodeSnapshot(value, expectedNode = null) {
   nonNegativeInteger(value.attempt, "node snapshot.attempt");
   nonNegativeInteger(value.revisions, "node snapshot.revisions");
   if (value.judgeFailures !== undefined) nonNegativeInteger(value.judgeFailures, "node snapshot.judgeFailures");
+  // The phase requirement ids the engine stamped onto the node when its result
+  // was accepted; optional on read so snapshots written before the stamp load
+  // unchanged.
+  if (value.requirementIds !== undefined) validateRequirementIdList(value.requirementIds, "node snapshot.requirementIds");
   // The review mode that governed the attempt's gate, recorded so a status
   // surface can tell an advisory finding from a below-threshold blocking one.
   if (value.review !== undefined && !REVIEW_MODES.has(/** @type {string} */ (value.review))) {
@@ -206,7 +210,7 @@ export function validateEvent(value) {
   assertObject(value, "event");
   rejectUnknown(value, new Set([
     "schemaVersion", "contractVersion", "at", "node", "from", "to", "type", "phase", "attempt", "runtime",
-    "role", "status", "currentRuntime", "errorCode", "error", "verdict", "summary", "revisions", "sourceIdentity", "packetHash", "override", "recovery", "invocationId", "unexpectedPaths", "unexpectedPathCount",
+    "role", "status", "currentRuntime", "errorCode", "error", "verdict", "summary", "revisions", "requirementIds", "sourceIdentity", "packetHash", "override", "recovery", "invocationId", "unexpectedPaths", "unexpectedPathCount",
   ]), "event");
   validateMetadata(value, "event");
   requireString(value.at, "event.at");
@@ -230,8 +234,23 @@ export function validateEvent(value) {
     }
   }
   if (value.unexpectedPathCount !== undefined) nonNegativeInteger(value.unexpectedPathCount, "event.unexpectedPathCount");
+  if (value.requirementIds !== undefined) validateRequirementIdList(value.requirementIds, "event.requirementIds");
   return /** @type {EventRecord} */ (value);
 }
+/**
+ * The requirement ids a node inherited from its phase, stamped by the engine
+ * and carried beside the result on both the snapshot and the transition event.
+ * Bounded like every persisted list: at most 64 ids of at most 128 bytes.
+ *
+ * @param {unknown} value
+ * @param {string} label
+ */
+function validateRequirementIdList(value, label) {
+  if (!Array.isArray(value) || value.length > 64) {
+    throw new TypeError(`${label} must be an array of at most 64 requirement ids`);
+  }
+  for (const [index, id] of value.entries()) boundedString(id, `${label}[${index}]`, 128);
+}
 /**
  * @param {unknown} value
  * @param {string} label
@@ -246,7 +265,7 @@ function validateInvocations(value, label) {
       "promptPath", "stdoutPath", "stderrPath", "startedAt", "updatedAt", "closedAt", "deadlineAt",
       "exitCode", "signal", "status", "executable", "usage", "usageEstimated", "costUsd", "costProvenance", "snapshotPath", "revision", "cycle",
       "runId", "campaignId", "planPhase", "role", "runtimeFingerprint", "model", "reasoning", "sandbox", "continuationId", "continuationMode",
-      "nodeId", "attempt", "workspace", "worktreeBranch", "worktreeBaseSha",
+      "nodeId", "attempt", "workspace", "worktreeBranch", "worktreeBaseSha", "session",
     ]);
     rejectUnknown(invocation, allowed, `${label}[${index}]`);
     requireString(invocation.id, `${label}[${index}].id`);
@@ -272,6 +291,7 @@ function validateInvocations(value, label) {
     if (!['fresh', 'reuse', 'rotate'].includes(/** @type {string} */ (invocation.continuationMode))) {
       throw new TypeError(`${label}[${index}].continuationMode is invalid`);
     }
+    if (invocation.session !== undefined && invocation.session !== null) validateSessionLedger(invocation.session, `${label}[${index}].session`);
     if (invocation.revision !== undefined) nonNegativeInteger(invocation.revision, `${label}[${index}].revision`);
     if (invocation.cycle !== undefined) nonNegativeInteger(invocation.cycle, `${label}[${index}].cycle`);
     for (const key of ["promptPath", "stdoutPath", "stderrPath", "executable"]) {
@@ -643,3 +663,26 @@ function validateScopeBoundarySnapshot(value, label) {
     }
   }
 }
+
+const SESSION_LEDGER_FIELDS = new Set(["turns", "toolCalls", "requests", "contextFirst", "contextMax", "contextLast", "contextSum", "completed"]);
+
+/**
+ * The per-request ledger an invocation carries (`session-metrics.mjs`'s
+ * SessionLedger): turns and tool calls are non-negative integers; requests
+ * and the context fields are non-negative integers, or null when the stream
+ * carried no usage per request (codex reports per turn, zcode emits one
+ * document), which is unknown, not zero.
+ *
+ * @param {unknown} value
+ * @param {string} label
+ */
+function validateSessionLedger(value, label) {
+  assertObject(value, label);
+  const record = /** @type {Record<string, unknown>} */ (value);
+  rejectUnknown(record, SESSION_LEDGER_FIELDS, label);
+  for (const key of ["turns", "toolCalls"]) nonNegativeInteger(record[key], `${label}.${key}`);
+  for (const key of ["requests", "contextFirst", "contextMax", "contextLast", "contextSum"]) {
+    if (record[key] !== null) nonNegativeInteger(record[key], `${label}.${key}`);
+  }
+  if (typeof record.completed !== "boolean") throw new TypeError(`${label}.completed must be a boolean`);
+}

package/src/contract/task-packet.mjs

@@ -25,7 +25,11 @@ const PROMPT_MAX_BYTES = 64 * 1024;
  * process-free command, so a sandbox that cannot signal processes never hangs
  * on the node's own verification.
  */
-const VERIFICATION_PARAGRAPH = "The controller runs every command below after you report; its recorded results are the proof of this node. Running a command yourself is optional and only for one that finishes in seconds and spawns no long-lived process. Keep output bounded (pipe through `| tail -n 200`). Never wait on a background job, never run the whole test suite, and never run tests that start and terminate other processes.";
+// measured 2026-09-20 over 228 stored claude worker turns: tool results are
+// 73% of what enters the context after the packet (Read 38%, Bash 32%), edits
+// and whole-file writes 24%, and each byte is re-read by a median of 49 later
+// requests of the same turn. Hence the last sentence.
+const VERIFICATION_PARAGRAPH = "The controller runs every command below after you report; its recorded results are the proof of this node. Running a command yourself is optional and only for one that finishes in seconds and spawns no long-lived process. Keep output bounded (pipe through `| tail -n 200`). Never wait on a background job, never run the whole test suite, and never run tests that start and terminate other processes. Prefer a targeted edit over rewriting a whole file, and read with an offset and limit rather than whole files: every byte you read or write is re-read by every later request of this turn.";
 
 /**
  * The `## Required output` schema every mode states: literally every key

package/src/engine/backoff.mjs

@@ -321,7 +321,8 @@ export function networkTransition(contract, node, state, role, envelope, exitCod
  * @returns {boolean}
  */
 export function isRepairable(node, state) {
-  return Boolean(node.gate.enabled) && (state.revisions ?? 0) < (node.gate.maxRevisions ?? 1);
+  // The budget is the node's, gate or not: see settle.mjs applyRejection.
+  return (state.revisions ?? 0) < (node.gate.maxRevisions ?? 1);
 }
 
 /**

package/src/engine/capacity.mjs

@@ -0,0 +1,74 @@
+/**
+ * Per-runtime dispatch capacity: how many attempts one runtime may run at
+ * once (`maxConcurrent`; absent means only `maxParallel` bounds it) and which
+ * runtimes are on a quota hold -- a node of theirs is waiting out a provider
+ * exhaustion backoff on that same runtime, so dispatching a sibling to it
+ * would spend the next quota window on a refusal the run already knows
+ * about. Separate from the scheduler because it is pure over the running set
+ * and the persisted snapshots, and from failover.mjs because that decides one
+ * node's route while this decides whether the tick may start another.
+ *
+ * measured 2026-09-20: `maxParallel` was the one concurrency knob, global to
+ * the run; nothing reduced dispatch to a provider that had just refused a
+ * sibling on quota, and 14 of 58 stored contracts ran with maxParallel 2.
+ */
+
+/** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
+/** @typedef {import("../contract/index.mjs").NodeSnapshot} NodeSnapshot */
+
+/**
+ * Live attempts per runtime id, from the jobs a tick is holding.
+ *
+ * @param {Iterable<{runtime: {id: string|null}}>} running
+ * @returns {Map<string, number>}
+ */
+export function runningPerRuntime(running) {
+  /** @type {Map<string, number>} */
+  const counts = new Map();
+  for (const job of running) {
+    const id = job.runtime.id;
+    if (typeof id !== "string") continue;
+    counts.set(id, (counts.get(id) ?? 0) + 1);
+  }
+  return counts;
+}
+
+/**
+ * Runtimes some node is waiting to use again after a provider exhaustion:
+ * the node's current routing override still has a `backoffUntil` in the
+ * future, it points back at the runtime that was exhausted (a reset wait, not
+ * a hop to another runtime), and the exhaustion was the last routing event.
+ * A network wait or an ordinary provider failure holds nothing.
+ *
+ * @param {Iterable<NodeSnapshot>} states
+ * @param {number} now epoch milliseconds
+ * @returns {Set<string>}
+ */
+export function quotaHeldRuntimes(states, now) {
+  /** @type {Set<string>} */
+  const held = new Set();
+  for (const state of states) {
+    const override = state.routing?.currentOverride;
+    const last = state.routing?.history?.at(-1);
+    if (!override?.backoffUntil || Date.parse(override.backoffUntil) <= now) continue;
+    if (!override.runtime || !last || last.runtime !== override.runtime) continue;
+    if (last.status !== "exhausted") continue;
+    held.add(override.runtime);
+  }
+  return held;
+}
+
+/**
+ * Whether one more attempt may start on `runtimeId` right now.
+ *
+ * @param {string} runtimeId
+ * @param {ValidatedContract} contract
+ * @param {Map<string, number>} counts live attempts per runtime, `runningPerRuntime`'s shape
+ * @param {Set<string>} held `quotaHeldRuntimes`'s result
+ * @returns {boolean}
+ */
+export function runtimeHasCapacity(runtimeId, contract, counts, held) {
+  if (held.has(runtimeId)) return false;
+  const limit = contract.runtimes[runtimeId]?.maxConcurrent;
+  return typeof limit !== "number" || (counts.get(runtimeId) ?? 0) < limit;
+}