faberun 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.12.0",
+  "version": "0.13.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/contract/assert.mjs

@@ -46,7 +46,11 @@ export function assertObject(value, label) {
  * @returns {asserts value is string}
  */
 export function requireId(value, label) {
-  if (typeof value !== "string" || !/^[A-Za-z0-9._-]+$/u.test(value)) {
+  // Absent and malformed refuse with different messages: observed 2026-09-20,
+  // a missing id answered with the character-class message and sent the reader
+  // hunting for an illegal character that was not there.
+  if (typeof value !== "string" || !value) throw new TypeError(`${label} is required`);
+  if (!/^[A-Za-z0-9._-]+$/u.test(value)) {
     throw new TypeError(`${label} must contain only letters, numbers, dot, underscore, or dash`);
   }
   if (value === "." || value === "..") throw new TypeError(`${label} must not be "." or ".."`);

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",
+  "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, 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 */
@@ -220,6 +229,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 +244,7 @@ export function validateContract(raw, contractPath, options = {}) {
       prompt,
       gate,
       timeoutSec,
+      maxTurns,
       replayPolicy,
     });
   });
@@ -362,6 +375,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 +468,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 +715,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

@@ -246,7 +246,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 +272,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 +644,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;
+}

package/src/engine/dispatch.mjs

@@ -24,21 +24,23 @@ import {
 import { attemptWorkspace, createAttemptWorktree, sealAttempt } from "../repo/worktree.mjs";
 import { attemptWorktreePath } from "../run/paths.mjs";
 import { basename, dirname, join } from "node:path";
-import { boundedUtf8, errorCode, errorMessage, stableJson } from "../util.mjs";
+import { errorCode, errorMessage } from "../util.mjs";
 import { captureWorkspaceScope, captureWorkspaceSnapshot } from "../repo/workspace.mjs";
-import { createHash } from "node:crypto";
 import { deterministicGate, judgeReaskReason, judgeRequired, judgeSkippedByScope } from "./judge-gate.mjs";
 import { emptyScope, persistedScopeBoundary, workerScope } from "./scope.mjs";
 import { hasOperationIntent, hasOperationSettlement, operationNeedsRecovery, operationNextState, persistInvocationIntent, providerReceipts, settleInvocation } from "../run/operations.mjs";
 import { invocationCost, invocationUsage } from "../run/usage.mjs";
-import { logPaths, readBoundedTail, startProcess } from "./process.mjs";
+import { logPaths, startProcess } from "./process.mjs";
+import { readBoundedTail } from "./transcript.mjs";
 import { mkdirSync, statSync } from "node:fs";
-import { READ_LINE_LIMIT, normalizeProviderResult, providerCommand } from "../harnesses/index.mjs";
-import { readJson, writeJsonAtomic } from "../run/store.mjs";
+import { READ_BYTE_LIMIT, READ_LINE_LIMIT, normalizeProviderResult } from "../harnesses/index.mjs";
+import { writeJsonAtomic } from "../run/store.mjs";
 import { judgeReaskInstruction, reviewMode } from "../contract/review-modes.mjs";
 import { routeRuntimeForState, runtimeSnapshot } from "./failover.mjs";
+import { fingerprintRuntime, forceFreshSession, phaseInvocationPlan } from "./phase-session.mjs";
+
+/** @typedef {import("./phase-session.mjs").SessionPolicy} SessionPolicy */
 import { transition, writeNode } from "./state.mjs";
-import { validateNodeSnapshot } from "../contract/snapshot.mjs";
 
 /**
  * What a judge round decided, for the caller to act on.
@@ -63,156 +65,8 @@ import { validateNodeSnapshot } from "../contract/snapshot.mjs";
 /** @typedef {import("../contract/index.mjs").VerificationState} VerificationState */
 /** @typedef {import("../contract/index.mjs").WorkspaceScopeBoundary} WorkspaceScopeBoundary */
 
-/** @typedef {{forceFresh?: boolean}} SessionPolicy */
 
-/**
- * Resolve the session policy one dispatch runs under, then consume the copy the
- * node persisted. The explicit argument comes from a caller that is dispatching
- * on the spot; `state.sessionPolicy` is the copy a rejection decision left when
- * it handed the node back to the scheduler, whose own `startWorker` call passes
- * nothing at all.
- *
- * Persisting is the whole point: `phaseInvocationPlan` rediscovers a compatible
- * continuation from the persisted ledger, so nulling a local continuation id at
- * the call site would let the scheduler's later dispatch find it again. Clearing
- * the stored policy here makes it one-shot — it governs exactly the dispatch it
- * was recorded for, and the next unrelated attempt reuses normally.
- *
- * @param {{sessionPolicy?: SessionPolicy|null}} state
- * @param {SessionPolicy} [explicit]
- * @returns {SessionPolicy}
- */
-export function forceFreshSession(state, explicit = {}) {
-  const persisted = /** @type {SessionPolicy|undefined} */ (state?.sessionPolicy ?? undefined);
-  const policy = { ...(persisted ?? {}), ...explicit };
-  if (state && state.sessionPolicy !== undefined && state.sessionPolicy !== null) state.sessionPolicy = null;
-  return policy;
-}
 
-/**
- * Select the only continuation that is allowed for this plan phase and role.
- * The search is intentionally limited to persisted node snapshots in this run.
- *
- * `policy.forceFresh` is the explicit session policy a rejection decision
- * carries: it short-circuits the search before it can rediscover a compatible
- * continuation, so a retry after a gate rejection starts a fresh provider
- * session instead of re-reading the failed transcript. Nulling a local id at
- * the call site is not enough, because this function rediscovers the prior
- * continuation from the persisted ledger.
- *
- * @param {ValidatedContract} contract
- * @param {ValidatedNode} node
- * @param {NodeSnapshot} state
- * @param {string} runDir
- * @param {"worker"|"judge"} role
- * @param {string} prompt
- * @param {SessionPolicy} [policy]
- * @returns {{prompt: string, continuationId: string|null, mode: "fresh"|"reuse"|"rotate"}}
- */
-function phaseInvocationPlan(contract, node, state, runDir, role, prompt, policy = {}) {
-  if (policy.forceFresh === true) {
-    return { prompt, continuationId: null, mode: "fresh" };
-  }
-  const runId = basename(runDir);
-  const session = phaseSessionCandidates(contract, node, state, runDir, role).at(-1);
-  const runtime = routeRuntimeForState(contract, node, state, role);
-  const identityMatches = session && session.invocation.runId === runId
-    && session.invocation.campaignId === contract.campaignId
-    && session.invocation.planPhase === node.phase
-    && session.invocation.role === role
-    && session.invocation.harness === runtime.harness
-    && session.invocation.runtimeId === runtime.id
-    && session.invocation.runtimeFingerprint === fingerprintRuntime(runtime)
-    && session.invocation.model === runtime.model
-    && session.invocation.reasoning === (runtime.reasoning ?? null)
-    && session.invocation.sandbox === (runtime.sandbox ?? null);
-  const canContinue = runtime.capabilities.continuation === true;
-  if (identityMatches && canContinue) {
-    return { prompt, continuationId: session.invocation.continuationId ?? null, mode: "reuse" };
-  }
-  // A harness that cannot continue at all, or a session picked up from a
-  // different phase-sibling node whose identity does not match this one, has
-  // no native continuity: the fresh attempt carries the prior nodes'
-  // structured summaries forward instead of starting blind.
-  if (session && (!canContinue || session.nodeId !== node.id)) {
-    return {
-      prompt: phaseHandoffPrompt(contract, node, state, runDir, role),
-      continuationId: null,
-      mode: "rotate",
-    };
-  }
-  // A capable harness continuing its own node whose identity merely drifted
-  // (the run directory moved, or a runtime edge) still gets the caller's own
-  // prompt — already carrying the node's bounded "Previous attempt" section —
-  // in a fresh session, never a synthesized handoff.
-  return { prompt, continuationId: null, mode: session ? "rotate" : "fresh" };
-}
-/**
- * Continuation ids a live invocation is already driving, anywhere in the run.
- *
- * This is what makes concurrent nodes of one phase safe, and it is read from
- * the persisted ledger rather than from an in-memory registry so a controller
- * that took over a run inherits the claims instead of racing them.
- *
- * @param {ValidatedContract} contract
- * @param {NodeSnapshot} currentState
- * @param {string} runDir
- * @returns {Set<string>}
- */
-function claimedContinuations(contract, currentState, runDir) {
-  /** @type {Set<string>} */
-  const claimed = new Set();
-  for (const candidate of contract.nodes) {
-    let state = candidate.id === currentState.id ? currentState : null;
-    if (!state) {
-      try { state = validateNodeSnapshot(readJson(join(runDir, "nodes", `${candidate.id}.json`)), candidate); } catch { continue; }
-    }
-    for (const invocation of state.invocations ?? []) {
-      if (invocation.status === "active" && invocation.continuationId) claimed.add(invocation.continuationId);
-    }
-  }
-  return claimed;
-}
-/**
- * @param {ValidatedContract} contract
- * @param {ValidatedNode} node
- * @param {NodeSnapshot} currentState
- * @param {string} runDir
- * @param {"worker"|"judge"} role
- * @returns {{nodeId: string, invocation: Invocation}[]}
- */
-function phaseSessionCandidates(contract, node, currentState, runDir, role) {
-  /** @type {{nodeId: string, invocation: Invocation}[]} */
-  const candidates = [];
-  const claimed = claimedContinuations(contract, currentState, runDir);
-  for (const candidate of contract.nodes) {
-    if (candidate.phase !== node.phase) continue;
-    let state = candidate.id === currentState.id ? currentState : null;
-    if (!state) {
-      try { state = validateNodeSnapshot(readJson(join(runDir, "nodes", `${candidate.id}.json`)), candidate); } catch { continue; }
-    }
-    for (const invocation of state.invocations ?? []) {
-      if (invocation.role !== role || invocation.planPhase !== node.phase || !invocation.continuationId) continue;
-      if (invocation.nodeId !== candidate.id || invocation.attempt !== state.attempt || invocation.workspace !== state.worktree?.path) continue;
-      // One provider session, one live turn. With `maxParallel` above one,
-      // two nodes of a phase can be dispatched in the same tick, and without
-      // this both would hand the same continuation id to their own provider
-      // process. The claim is read from the persisted ledger, which the
-      // in-tick dispatch already wrote for the node that went first.
-      if (claimed.has(invocation.continuationId)) continue;
-      candidates.push({ nodeId: candidate.id, invocation });
-    }
-  }
-  return candidates.sort((left, right) => {
-    const leftStarted = Date.parse(left.invocation.startedAt);
-    const rightStarted = Date.parse(right.invocation.startedAt);
-    if (leftStarted !== rightStarted) return leftStarted - rightStarted;
-    const leftUpdated = Date.parse(left.invocation.updatedAt);
-    const rightUpdated = Date.parse(right.invocation.updatedAt);
-    if (leftUpdated !== rightUpdated) return leftUpdated - rightUpdated;
-    return left.invocation.id.localeCompare(right.invocation.id);
-  });
-}
 /** @param {Invocation} invocation @param {ValidatedContract} contract @param {ValidatedNode} node @param {RuntimeSnapshot} runtime @param {NodeSnapshot} state @param {string} runDir @param {"worker"|"judge"} role @param {"fresh"|"reuse"|"rotate"} mode @param {string|null} continuationId */
 function stampInvocation(invocation, contract, node, runtime, state, runDir, role, mode, continuationId) {
   invocation.runId = basename(runDir);
@@ -235,38 +89,6 @@ function stampInvocation(invocation, contract, node, runtime, state, runDir, rol
   // generation across a controller crash.
   /** @type {{cycle?: number}} */ (invocation).cycle = state.routing?.tierExhaustionCycle ?? 0;
 }
-/** @param {RuntimeSnapshot} runtime @returns {string} */
-function fingerprintRuntime(runtime) {
-  const executable = providerCommand(runtime, "").executable;
-  return createHash("sha256").update(stableJson({ runtime, executable })).digest("hex");
-}
-/** @param {ValidatedContract} contract @param {ValidatedNode} node @param {NodeSnapshot} state @param {string} runDir @param {"worker"|"judge"} role @returns {string} */
-function phaseHandoffPrompt(contract, node, state, runDir, role) {
-  const summaries = phaseSessionCandidates(contract, node, state, runDir, role)
-    .map(({ nodeId }) => {
-      const candidate = contract.nodes.find((item) => item.id === nodeId);
-      let snapshot = null;
-      try { snapshot = readJson(join(runDir, "nodes", `${nodeId}.json`)); } catch {
-        // ENOENT or unreadable snapshot: this prior node contributes no summary.
-      }
-      const result = snapshot?.result;
-      const record = result && typeof result === "object" && !Array.isArray(result)
-        ? /** @type {Record<string, unknown>} */ (result)
-        : null;
-      const summary = typeof record?.summary === "string" ? record.summary : null;
-      return summary && candidate ? `${candidate.id}: ${boundedUtf8(summary, 1024)}` : null;
-    })
-    .filter(Boolean)
-    .slice(-8);
-  const handoff = [
-    `Continue phase ${node.phase} as the ${role} agent in a fresh provider session.`,
-    "Prior structured node summaries:",
-    summaries.length ? summaries.map((summary) => `- ${summary}`).join("\n") : "- (none)",
-    "Current closed task packet:",
-    boundedUtf8(node.prompt, 48 * 1024),
-  ].join("\n\n");
-  return boundedUtf8(handoff, 60 * 1024);
-}
 /**
  * The declared weight of a node's readFiles at dispatch time: the sum of the
  * byte sizes of the files that exist in the attempt workspace. This is the
@@ -311,6 +133,7 @@ function workerToolPolicy(runtime, node, workspace) {
     writeFiles: node.taskPacket.writeFiles ?? [],
     writeRoots: node.taskPacket.writeRoots ?? [],
     maxReadLines: READ_LINE_LIMIT,
+    maxReadBytes: READ_BYTE_LIMIT,
   };
 }
 /**
@@ -332,6 +155,9 @@ function invocationCommandOptions(contract, node, state, runtime, phasePlan, run
   return {
     ...extra,
     continuationId: runtime.capabilities.continuation === true ? phasePlan.continuationId : null,
+    // The attempt's request ceiling. An adapter that can enforce it natively
+    // takes it as a flag; the monitor enforces it for every streaming harness.
+    maxTurns: node.maxTurns ?? contract.maxTurns,
   };
 }
 /**

package/src/engine/lifecycle.mjs

@@ -142,8 +142,13 @@ export function terminalErrorCode(state) {
   return typeof error.code === "string" && error.code ? error.code : null;
 }
 
-/** Error codes that earn exactly one automatic retry before parking. */
-export const AUTO_RETRY_CODES = new Set(["judge_unavailable", "provider_error", "stall_timeout", "wall_clock_timeout"]);
+/**
+ * Error codes that earn exactly one automatic retry before parking.
+ * `turn_limit` is here and not among the timeout codes below: a turn the CLI
+ * stopped itself at `--max-turns` exits cleanly with no seal yet, and the
+ * next dispatch seals its worktree as it does for any previous attempt.
+ */
+export const AUTO_RETRY_CODES = new Set(["judge_unavailable", "provider_error", "stall_timeout", "wall_clock_timeout", "turn_limit"]);
 
 /**
  * Timeout codes earn their automatic retry only when phase 5b sealed work