@iowarp/clio-coder 0.4.9 → 0.5.0

package/src/domains/dispatch/extension.ts

@@ -1,3 +1,5 @@
+import { writeDiagnostic } from "../../core/diagnostics.js";
+import { readPiMonoVersion } from "../../engine/pi-mono-names.js";
 import { parseWorkerContextSeed } from "../../worker/context-seed.js";
 import { WORKER_STDIN_FRAME_MAX_BYTES } from "../../worker/protocol.js";
 import { WORKER_CONTEXT_PREAMBLE } from "../context/worker/select.js";
@@ -22,7 +24,7 @@ import { DEFAULT_SETTINGS, type DelegationToolGovernance } from "../../core/defa
 import type { DomainBundle, DomainContext, DomainExtension } from "../../core/domain-loader.js";
 import { gatewayRoutingObservationFromRecord } from "../../core/gateway-routing.js";
 import { GUARDRAIL_DEFAULTS, resolveGuardrail } from "../../core/guardrails.js";
-import { readClioVersion, readPiMonoVersion } from "../../core/package-root.js";
+import { readClioVersion } from "../../core/package-root.js";
 import { canonicalizeExistingPath } from "../../core/path-canonical.js";
 import { protectedResidencyModels } from "../../core/residency-protection.js";
 import { responseModelIdObservationFromRecord } from "../../core/response-model-id.js";
@@ -34,6 +36,7 @@ import {
 import { isSkillActivation, type SkillActivation } from "../../core/skill-activation.js";
 import { rawDurationMs } from "../../core/timers.js";
 import { isBuiltinToolName, isHarnessExtensionToolName, type ToolName, ToolNames } from "../../core/tool-names.js";
+import { snapshotTurnConstraints, turnAllowsTool } from "../../core/turn-constraints.js";
 import {
 	type AcpDelegationRunHandle,
 	type AcpDelegationRunInput,
@@ -52,8 +55,10 @@ import {
 	cleanupTaskWorktree,
 	createTaskWorktree,
 	gitCheckoutRoot,
+	settleTaskWorktree,
 } from "../../tools/task-worktree.js";
 import { truncateUtf8 } from "../../tools/truncate-utf8.js";
+import { diskWorktreeParent, prepareWorktreeParent, resolveWorktreeRoot } from "../../tools/worktree-root.js";
 import {
 	serializeWorkerRuntimeDescriptor,
 	WORKER_PROTECTED_ARTIFACT_STATE_VERSION,
@@ -63,7 +68,11 @@ import {
 } from "../../worker/spec-contract.js";
 import type { AgentsContract } from "../agents/contract.js";
 import type { AgentRecipe } from "../agents/recipe.js";
-import { validateRecipeResult } from "../agents/result-contract.js";
+import {
+	INTERNAL_HELPER_RESULT_KINDS,
+	validateRecipeResult,
+	validateStructuredHelperResult,
+} from "../agents/result-contract.js";
 import { nodeResultContractFilesystem } from "../agents/result-contract-filesystem.js";
 import {
 	type AgentAudience,
@@ -116,6 +125,7 @@ import { parseRigorOverride, type Rigor, resolveRigor } from "../safety/rigor.js
 import { createRunEffectsRecorder, type RunEffectsRecorder } from "../safety/run-effects.js";
 import type { ScopeSpec } from "../safety/scope.js";
 import type { SchedulingContract } from "../scheduling/contract.js";
+import { resolveGlobalConcurrency } from "../scheduling/local-capacity.js";
 import {
 	approvedRouteObservation,
 	consumeActiveRouteApproval,
@@ -178,6 +188,7 @@ import {
 	classifyFailure,
 	decideRetry,
 	type FailureClass,
+	isContextOverflowFailure,
 	isInfrastructureFailure,
 	type RetryDecision,
 } from "./failure-classification.js";
@@ -258,6 +269,7 @@ import { defaultRoutingIntent } from "./routing-intent.js";
 import { attachRunEventJournalBridge, type RunEventJournalBridge } from "./run-event-journal-bridge.js";
 import { detectRunIdentity } from "./run-identity.js";
 import { type Ledger, newRunId, openLedger } from "./state.js";
+import { createTargetBreaker, type TargetBreakerBlock } from "./target-breaker.js";
 import {
 	countToolCalls,
 	hasPotentiallyMutatingAttempt,
@@ -305,12 +317,14 @@ import {
 	validateJobSpec,
 } from "./validation.js";
 import { describeUngroundedValidations, groundClaimedValidations, invalidatesQuality } from "./validation-grounding.js";
+import { adoptWorkerModelLoad } from "./worker-model-loads.js";
 import { prepareWorkerModelMetadata } from "./worker-model-metadata.js";
 import {
 	type AgentLedgerBody,
 	computeSettingsFingerprint,
 	endpointIdentityHash,
 	receiptAttestationFields,
+	type WorkerModelLoad,
 } from "./worker-protocol.js";
 import {
 	type SpawnedWorker,
@@ -443,6 +457,12 @@ export interface DispatchBundleOptions {
 
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 1000;
 const DEFAULT_RESILIENCE_COOLDOWN_MS = 15_000;
+
+/** A half-open route this dispatch was admitted to probe, keyed by its run id. */
+interface ProbeClaim {
+	key: string;
+	owner: string;
+}
 /** ACP event-inactivity stall window (Symphony §5.3.6 semantics); <= 0 disables. */
 const DEFAULT_ACP_STALL_TIMEOUT_MS = 300_000;
 const ADMISSION_INPUT_TOKEN_ESTIMATE = 4096;
@@ -742,7 +762,7 @@ async function awaitEventDrain(drained: Promise<void>, graceMs = DISPATCH_DRAIN_
 function reportDispatchDiagnostic(scope: string, error: unknown): void {
 	const message = error instanceof Error ? error.message : String(error);
 	try {
-		process.stderr.write(`[clio-coder:dispatch] ${scope}: ${message}\n`);
+		writeDiagnostic(`[clio-coder:dispatch] ${scope}: ${message}\n`);
 	} catch {
 		// stderr itself is best-effort
 	}
@@ -1719,6 +1739,33 @@ function deniedToolNames(req: DispatchRequest): ReadonlySet<string> {
 	return new Set(req.denyTools.map((tool) => tool.trim().toLowerCase()));
 }
 
+function assertTurnConstraintCompatibility(
+	req: DispatchRequest,
+	tools: ReadonlyArray<string>,
+	mediated: boolean,
+): void {
+	const constraints = req.turnConstraints;
+	if (!constraints) return;
+	if (!turnAllowsTool(constraints, "dispatch"))
+		throw new Error("dispatch: forbidden by the parent task's explicit scope");
+	if (!mediated && (constraints.allowedTools !== undefined || constraints.skills === "disabled")) {
+		throw new Error(
+			"dispatch: this external runtime cannot enforce the parent task's tool/skill constraints; use a native worker",
+		);
+	}
+	const outside = tools.filter((name) => !turnAllowsTool(constraints, name));
+	if (outside.length > 0)
+		throw new Error(
+			`dispatch: worker tool surface exceeds the parent task's explicit scope: ${outside.join(", ")}. Select a narrower recipe or tool profile.`,
+		);
+	if ((req.resolvedVerification?.length ?? 0) > 0 && !turnAllowsTool(constraints, "verify")) {
+		throw new Error("dispatch: host verification is outside the parent task's explicit tool scope");
+	}
+	if (req.worktree === true && !turnAllowsTool(constraints, "write")) {
+		throw new Error("dispatch: worktree creation requires write in the parent task's explicit tool scope");
+	}
+}
+
 function assertPostRuntimeToolCompatibility(
 	agentId: string,
 	spec: ReturnType<typeof normalizeAgentSpec>,
@@ -2029,6 +2076,14 @@ function buildDispatchWorkerSpec(input: DispatchWorkerSpecInput, config?: Config
 	// the same resolver the seal uses, so the two never disagree.
 	const workerResultContract = dispatchResultContract(input.req, input.recipe);
 	if (workerResultContract) spec.resultContract = workerResultContract;
+	if (
+		(input.recipe?.audience === "shadow" || input.recipe?.audience === "internal") &&
+		input.target.runtime.kind === "http" &&
+		targetToolCapability(input.target) === true &&
+		workerResultContract &&
+		(INTERNAL_HELPER_RESULT_KINDS as readonly string[]).includes(workerResultContract.kind)
+	)
+		spec.helperResult = true;
 	const product = input.req.product ?? input.recipe?.product;
 	if (product) spec.product = product;
 	// The orchestrator's tool decision is the one the run was admitted under and
@@ -2052,6 +2107,7 @@ function buildDispatchWorkerSpec(input: DispatchWorkerSpecInput, config?: Config
 	}
 	if (input.apiKey) spec.apiKey = input.apiKey;
 	if (input.req.noSkills !== undefined) spec.noSkills = input.req.noSkills;
+	if (input.req.turnConstraints !== undefined) spec.turnConstraints = input.req.turnConstraints;
 	const skillPaths = [...(input.req.skillPaths ?? []), ...(input.recipe?.boundSkillPaths ?? [])];
 	if (skillPaths.length > 0) spec.skillPaths = [...new Set(skillPaths)];
 	const recipeSkills = (input.recipe?.skills ?? []).map((name) => name.trim()).filter((name) => name.length > 0);
@@ -2582,6 +2638,11 @@ export function createDispatchBundle(
 	};
 	const now = options?.now ?? (() => Date.now());
 	const monotonicNow = options?.monotonicNow ?? (() => performance.now());
+	const targetBreaker = createTargetBreaker({
+		monotonicNow,
+		cooldownMs: getResilienceCooldownMs,
+		threshold: () => getEffectiveSettings()?.fleet?.retry.breakerThreshold ?? 1,
+	});
 	// Durable evidence owner used by shadow observation and active readiness.
 	const routeObserver: RouteObserver = options?.routeObserver ?? createRouteObserver({});
 
@@ -2589,7 +2650,6 @@ export function createDispatchBundle(
 	let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
 	const active = new Map<string, ActiveRun>();
 	const pendingCapacity = new Map<string, PendingCapacityAdmission>();
-	const targetCooldowns = new Map<string, { until: number; reason: string }>();
 	const ownedReservations = new Set<string>();
 	/**
 	 * Attribution from each finalized run's successful tool calls, newest last.
@@ -2614,7 +2674,7 @@ export function createDispatchBundle(
 	const capacityAdmission = createCapacityAdmissionController({
 		limits: () => {
 			const settings = getEffectiveSettings();
-			const nodes: Record<string, number> = { local: configuredGlobalCapacity(settings) };
+			const nodes: Record<string, number> = { local: configuredLocalCapacity(settings) };
 			for (const node of settings?.fleet?.nodes ?? []) nodes[node.id] = node.maxWorkers;
 			return { global: configuredGlobalCapacity(settings), nodes, endpoints: configuredEndpointLimits() };
 		},
@@ -2697,7 +2757,7 @@ export function createDispatchBundle(
 		// Read budget after the capacity lock wait too; concurrent callbacks may spend.
 		const preflight = scheduling.preflight();
 		const nodes: Record<string, { active: number; limit: number }> = {
-			local: { active: usage.nodes.local ?? 0, limit: configuredGlobalCapacity(settings) },
+			local: { active: usage.nodes.local ?? 0, limit: configuredLocalCapacity(settings) },
 		};
 		for (const node of settings?.fleet?.nodes ?? [])
 			nodes[node.id] = { active: usage.nodes[node.id] ?? 0, limit: node.maxWorkers };
@@ -2768,8 +2828,12 @@ export function createDispatchBundle(
 	}
 
 	function configuredGlobalCapacity(settings: EffectiveSettings): number {
-		const configured = settings?.fleet.concurrency;
-		return scheduling.maxWorkers?.() ?? (configured === "auto" || configured === undefined ? 4 : Math.max(1, configured));
+		return scheduling.maxWorkers?.() ?? resolveGlobalConcurrency(settings?.fleet.concurrency);
+	}
+
+	/** The local node alone follows host facts under `auto`; global and SSH limits do not. */
+	function configuredLocalCapacity(settings: EffectiveSettings): number {
+		return scheduling.localCapacity?.().limit ?? configuredGlobalCapacity(settings);
 	}
 
 	function publishCapacityQueued(
@@ -3048,6 +3112,8 @@ export function createDispatchBundle(
 		detail: string | null,
 		receipt: RunReceipt,
 		failureClass: FailureClass,
+		contextOverflow = false,
+		currentRetryReason: string | null = null,
 	): RetryScheduleResult {
 		if (draining) return { scheduled: false };
 		const rootRunId = run.lineage.rootRunId;
@@ -3067,7 +3133,19 @@ export function createDispatchBundle(
 		const maxRetries = assignments.get(rootRunId)?.policy.maxRetries ?? assignmentPolicyFor(run.req).maxRetries;
 		const baseDecision = decideRetry(failureClass, run.lineage.attempt, maxRetries);
 		// An exact manual route may be retried, but no route component may drift.
-		const decision = recovery.retryDecisionWithinFailover(baseDecision, failoverModeFor(run.req));
+		let decision = recovery.retryDecisionWithinFailover(baseDecision, failoverModeFor(run.req));
+		let overflowRoute: DispatchFailoverCandidate | null = null;
+		let overflowReason: string | null = null;
+		if (contextOverflow && !decision.retry) {
+			const plan = planOverflowRetry(run, currentRetryReason, maxRetries);
+			if ("settlementDetail" in plan) {
+				retryBackoff.delete(rootRunId);
+				return { scheduled: false, settlementDetail: plan.settlementDetail };
+			}
+			overflowRoute = plan.route;
+			overflowReason = plan.reason;
+			decision = { retry: true, excludedRouteParts: [], qualityEscalation: null, reasonCode: "retry-context-overflow" };
+		}
 		if (!decision.retry) {
 			retryBackoff.delete(rootRunId);
 			// Deterministic outcomes are intentionally not retried. This is a normal
@@ -3111,7 +3189,7 @@ export function createDispatchBundle(
 		// target cooldown it just created protects new work, not this chain.
 		const delayMs = Math.max(backoffDelayMs, decision.retryAfterMs ?? 0);
 		const attempt = run.lineage.attempt + 1;
-		const reason = detail !== null ? `${outcome}: ${detail}` : outcome;
+		const reason = overflowReason ?? (detail !== null ? `${outcome}: ${detail}` : outcome);
 		const dueAt = now() + delayMs;
 		let settleCanceled!: () => void;
 		let rejectContinuation!: (error: unknown) => void;
@@ -3124,7 +3202,7 @@ export function createDispatchBundle(
 			retryQueue.delete(run.runId);
 			// Ownership starts at scheduling, covering admission before a handle
 			// exists and terminal receipt work after the handle arrives.
-			executeRetry(run, attempt, reason, decision).then(settleCanceled, rejectContinuation);
+			executeRetry(run, attempt, reason, decision, overflowRoute).then(settleCanceled, rejectContinuation);
 		}, delayMs);
 		retryQueue.set(run.runId, {
 			runId: run.runId,
@@ -3154,6 +3232,8 @@ export function createDispatchBundle(
 		return { scheduled: true };
 	}
 
+	const CONTEXT_OVERFLOW_RETRY = "context-overflow";
+
 	function retryReasonKey(rootRunId: string, attempt: number): string {
 		return `${rootRunId}:${attempt}`;
 	}
@@ -3164,6 +3244,7 @@ export function createDispatchBundle(
 		outcome: RunOutcome,
 		detail: string | null,
 		failureClass: FailureClass,
+		contextOverflow = false,
 	): void {
 		const assignment = assignments.open(run.lineage.rootRunId, assignmentPolicyFor(run.req));
 		persistAssignment(registerAssignment(assignment.id), `${assignment.id}:open`);
@@ -3179,7 +3260,7 @@ export function createDispatchBundle(
 			retryReason,
 		});
 		persistAssignment(recordAssignmentAttempt(assignment.id, run.runId), `${assignment.id}:attempt:${run.runId}`);
-		const retry = maybeScheduleRetry(run, outcome, detail, receipt, failureClass);
+		const retry = maybeScheduleRetry(run, outcome, detail, receipt, failureClass, contextOverflow, retryReason);
 		if (retry.scheduled) return;
 		const currentStatus = assignments.get(assignment.id)?.status;
 		const terminalStatus =
@@ -3215,6 +3296,7 @@ export function createDispatchBundle(
 		attempt: number,
 		reason = "retry",
 		decision: RetryDecision = decideRetry("internal", run.lineage.attempt, assignmentPolicyFor(run.req).maxRetries),
+		overflowRoute: DispatchFailoverCandidate | null = null,
 	): Promise<void> {
 		if (draining || !retryChainIsLive(run)) return;
 		const excludesNode = decision.excludedRouteParts.includes("node");
@@ -3226,6 +3308,9 @@ export function createDispatchBundle(
 		const retryReq: DispatchRequest = {
 			...run.req,
 			...(rerouteHops !== undefined ? { reroutes: rerouteHops } : {}),
+			// A retry that moves the target names one, which would otherwise read
+			// as an operator pin and freeze every later retry in the chain.
+			failover: failoverModeFor(run.req),
 			requestOrigin: "internal",
 			lineage: {
 				parentRunId: run.runId,
@@ -3243,7 +3328,7 @@ export function createDispatchBundle(
 		retryReasons.set(reasonKey, reason);
 		try {
 			if (failoverModeFor(run.req) === "approved") {
-				const candidates = approvedRetryCandidates(run, decision);
+				const candidates = overflowRoute !== null ? [overflowRoute] : approvedRetryCandidates(run, decision);
 				if (run.req.routeApproval === undefined) {
 					const candidate = candidates[0] as DispatchFailoverCandidate;
 					retryReq.agentId = candidate.agentId;
@@ -3290,15 +3375,26 @@ export function createDispatchBundle(
 					retryReq.model = run.wireModelId;
 					retryReq.node = run.node?.id ?? "local";
 				}
+				if (overflowRoute !== null) {
+					retryReq.target = overflowRoute.target;
+					retryReq.model = overflowRoute.model;
+				}
 				// Automatic placement re-selects only the failed route component.
 				if (excludesNode) {
 					delete retryReq.node;
 					delete retryReq.plannedNode;
 				}
 				if (decision.excludedRouteParts.includes("target")) {
-					const alternateTarget = getEffectiveSettings()?.targets.find((target) => target.id !== run.targetId);
-					if (alternateTarget) retryReq.target = alternateTarget.id;
-					else delete retryReq.target;
+					const alternate = eligibleAlternateRoute(run, retryReq);
+					if (alternate !== null) {
+						retryReq.target = alternate.target;
+						retryReq.model = alternate.model;
+					} else {
+						// No other route can serve the request, so placement picks again.
+						// That is usually the failed route itself, which the chain may
+						// retry after backoff because the breaker guards new work only.
+						delete retryReq.target;
+					}
 				}
 				if (decision.excludedRouteParts.includes("model")) delete retryReq.model;
 				if (decision.excludedRouteParts.includes("runtime")) delete retryReq.workerRuntime;
@@ -3532,27 +3628,38 @@ export function createDispatchBundle(
 		return `${targetId}\0${runtimeId}\0${wireModelId}`;
 	}
 
-	function targetCooldownReason(targetId: string, runtimeId: string, wireModelId: string): string | null {
-		const key = cooldownKey(targetId, runtimeId, wireModelId);
-		const cooldown = targetCooldowns.get(key);
-		if (!cooldown) return null;
-		const remaining = cooldown.until - now();
-		if (remaining <= 0) {
-			targetCooldowns.delete(key);
-			return null;
+	function describeTargetBlock(targetId: string, block: TargetBreakerBlock | null): string | null {
+		if (block === null) return null;
+		if (block.kind === "probing") {
+			return `target '${targetId}' is cooling down while one probe run tests it after ${block.reason}`;
 		}
-		return `target '${targetId}' is cooling down for ${Math.ceil(remaining / 1000)}s after ${cooldown.reason}`;
+		return `target '${targetId}' is cooling down for ${Math.ceil(block.remainingMs / 1000)}s after ${block.reason}`;
 	}
 
+	/** Read-only cooldown view for route planning; it never claims a half-open probe. */
+	function targetCooldownReason(targetId: string, runtimeId: string, wireModelId: string): string | null {
+		return describeTargetBlock(targetId, targetBreaker.blocked(cooldownKey(targetId, runtimeId, wireModelId)));
+	}
+
+	/**
+	 * Admission gate for a top-level run. A half-open route admits this run as
+	 * its probe; the claim goes into probeClaims so a dispatch that fails before
+	 * its run starts can hand the probe back.
+	 */
 	function assertTargetNotCoolingDown(
 		req: DispatchRequest,
 		targetId: string,
 		runtimeId: string,
 		wireModelId: string,
+		probeClaims: ProbeClaim[],
 	): void {
 		if (req.lineage !== undefined) return;
-		const reason = targetCooldownReason(targetId, runtimeId, wireModelId);
+		const key = cooldownKey(targetId, runtimeId, wireModelId);
+		const owner = req.runIdHint;
+		const block = owner === undefined ? targetBreaker.blocked(key) : targetBreaker.admit(key, owner);
+		const reason = describeTargetBlock(targetId, block);
 		if (reason !== null) throw new Error(`dispatch: ${reason}`);
+		if (owner !== undefined) probeClaims.push({ key, owner });
 	}
 
 	/** The target identity a request resolves to, without composing a worker. */
@@ -3610,7 +3717,119 @@ export function createDispatchBundle(
 		return rerouted;
 	}
 
+	/**
+	 * First configured route on another target that can serve a retry: it
+	 * resolves to that target, carries every required capability, and its
+	 * breaker is neither open nor probing. With minContextWindow the route may
+	 * also be another model on the failed target, and its effective context
+	 * window must be strictly larger than minContextWindow. allowed narrows the
+	 * routes further, as an approved envelope does.
+	 */
+	function eligibleAlternateRoute(
+		run: ActiveRun,
+		req: DispatchRequest,
+		minContextWindow?: number,
+		allowed?: (candidate: DispatchFailoverCandidate) => boolean,
+	): (DispatchFailoverCandidate & { contextWindow: number }) | null {
+		const settings = getEffectiveSettings();
+		const failed = {
+			targetId: run.targetId,
+			modelId: run.wireModelId,
+			runtimeId: run.runtimeId,
+			endpointIdentityHash: "",
+		};
+		const routes = configuredJointTargets(settings?.targets ?? [], failed, endpointIdentityHash).filter((route) =>
+			minContextWindow === undefined
+				? route.targetId !== run.targetId
+				: route.targetId !== run.targetId || route.modelId !== run.wireModelId,
+		);
+		const windows = new Map<string, number>();
+		const probes: RouteAvailability[] = routes.map((route) => {
+			const candidate = { agentId: req.agentId, target: route.targetId, model: route.modelId, node: req.node ?? "local" };
+			if (allowed !== undefined && !allowed(candidate)) {
+				return { candidate, unavailable: "route is outside the approved failover envelope" };
+			}
+			try {
+				const identity = resolveTargetIdentity({ ...req, target: route.targetId, model: route.modelId }, settings);
+				if (identity.targetId !== route.targetId) {
+					return { candidate, unavailable: `route resolved to target '${identity.targetId}'` };
+				}
+				if (identity.targetId === run.targetId && identity.wireModelId === run.wireModelId) {
+					return { candidate, unavailable: "route resolved to the failed route" };
+				}
+				const capabilities = capabilityInfoForModel(providers, identity.targetId, identity.wireModelId);
+				const contextWindow = capabilities?.contextWindow ?? 0;
+				windows.set(`${route.targetId}\0${route.modelId}`, contextWindow);
+				const tooSmall =
+					minContextWindow !== undefined && contextWindow <= minContextWindow
+						? `context window ${contextWindow} is not larger than ${minContextWindow}`
+						: null;
+				return {
+					candidate,
+					unavailable:
+						tooSmall ??
+						requiredCapabilityFailureDetail(identity.targetId, capabilities, req.requiredCapabilities) ??
+						targetCooldownReason(identity.targetId, identity.runtimeId, identity.wireModelId),
+				};
+			} catch (error) {
+				return { candidate, unavailable: error instanceof Error ? error.message : String(error) };
+			}
+		});
+		const chosen = firstAvailableRouteCandidate(probes);
+		return chosen === null ? null : { ...chosen, contextWindow: windows.get(`${chosen.target}\0${chosen.model}`) ?? 0 };
+	}
+
+	/**
+	 * A context overflow is a verdict on the prompt against one window, so it
+	 * earns one retry, and only onto a route whose window is strictly larger.
+	 * Exact failover never moves, an approved plan moves only inside its
+	 * envelope, and an overflow retry that overflows again is final.
+	 */
+	function planOverflowRetry(
+		run: ActiveRun,
+		currentRetryReason: string | null,
+		maxRetries: number,
+	): { route: DispatchFailoverCandidate; reason: string } | { settlementDetail: string } {
+		const mode = failoverModeFor(run.req);
+		if (mode === "none") {
+			return { settlementDetail: "context overflow not retried because failover is none, which pins the route" };
+		}
+		if (currentRetryReason?.startsWith(`${CONTEXT_OVERFLOW_RETRY}:`) === true) {
+			return { settlementDetail: "context overflow not retried again because this attempt was already an overflow retry" };
+		}
+		if (maxRetries <= 0 || run.lineage.attempt >= maxRetries) {
+			return { settlementDetail: "context overflow not retried because the retry budget is spent" };
+		}
+		const failedWindow = capabilityInfoForModel(providers, run.targetId, run.wireModelId)?.contextWindow ?? 0;
+		const failedRoute = `${run.targetId}/${run.wireModelId}`;
+		if (failedWindow <= 0) {
+			return {
+				settlementDetail: `context overflow not retried because the context window of ${failedRoute} is unknown`,
+			};
+		}
+		const node = run.node?.id ?? "local";
+		const envelope = run.req.allowedCandidates ?? [];
+		const route = eligibleAlternateRoute(
+			run,
+			run.req,
+			failedWindow,
+			mode === "approved"
+				? (candidate) => envelope.some((entry) => recovery.sameFailoverCandidate(entry, { ...candidate, node }))
+				: undefined,
+		);
+		if (route === null) {
+			return {
+				settlementDetail: `context overflow not retried because no eligible route has a context window larger than ${failedWindow} on ${failedRoute}`,
+			};
+		}
+		return {
+			route: { agentId: route.agentId, target: route.target, model: route.model, node },
+			reason: `${CONTEXT_OVERFLOW_RETRY}: ${failedWindow} -> ${route.contextWindow} on ${route.target}/${route.model}`,
+		};
+	}
+
 	function recordTargetOutcome(
+		runId: string,
 		targetId: string,
 		runtimeId: string,
 		wireModelId: string,
@@ -3618,15 +3837,9 @@ export function createDispatchBundle(
 		exitCode: number,
 		failureClass: FailureClass,
 	): void {
-		const key = cooldownKey(targetId, runtimeId, wireModelId);
-		if (status === "completed" && exitCode === 0) {
-			targetCooldowns.delete(key);
-			return;
-		}
-		if (!affectsTargetBreaker(failureClass)) return;
-		const cooldownMs = getResilienceCooldownMs();
-		if (cooldownMs <= 0) return;
-		targetCooldowns.set(key, { until: now() + cooldownMs, reason: failureClass });
+		const outcome =
+			status === "completed" && exitCode === 0 ? "success" : affectsTargetBreaker(failureClass) ? "failure" : "neutral";
+		targetBreaker.record(cooldownKey(targetId, runtimeId, wireModelId), runId, outcome, failureClass);
 	}
 
 	function publishDispatchPathScope(req: DispatchRequest, pathScope: DispatchPathScope): void {
@@ -3754,6 +3967,7 @@ export function createDispatchBundle(
 			req,
 		);
 		assertPostRuntimeToolCompatibility(req.agentId, spec, effectiveTools, target, pathScope.writeBoundaries.length > 0);
+		assertTurnConstraintCompatibility(req, effectiveTools, target.runtime.kind === "http");
 		const effectiveAdmission: DispatchAdmissionStage = {
 			...admission,
 			allowedTools: effectiveTools,
@@ -3763,6 +3977,7 @@ export function createDispatchBundle(
 		const hasBoundSkills =
 			hasCanonicalContext && recipe.skills !== undefined && recipe.skills.length > 0 && req.noSkills !== true;
 		const compiledWorkerPrompt = await prompts.compileWorkerPrompt({
+			...(req.turnConstraints ? { turnConstraints: req.turnConstraints } : {}),
 			autonomy: effectiveAutonomy,
 			providerSupportsTools: target.runtime.kind === "subprocess" ? null : targetToolCapability(target),
 			toolNames: effectiveTools,
@@ -3970,6 +4185,7 @@ export function createDispatchBundle(
 		settings: EffectiveSettings,
 		timing: RunPhaseMarks,
 		routeDecision: RouteDecisionV1,
+		probeClaims: ProbeClaim[],
 		observer?: DispatchAdmissionObserver,
 		callerDeadlineAt?: number,
 		hostRun?: DispatchPreparationOptions["hostRun"],
@@ -3995,7 +4211,7 @@ export function createDispatchBundle(
 		const targetId = `delegation:${lifecycle.agentConfig.id}`;
 		const runtimeId = "acp";
 		const wireModelId = lifecycle.agentConfig.id;
-		assertTargetNotCoolingDown(req, targetId, runtimeId, wireModelId);
+		assertTargetNotCoolingDown(req, targetId, runtimeId, wireModelId, probeClaims);
 
 		if (req.contextSeed) persistWorkerContextSeed(req.contextSeed);
 		assertBudgetAdmitsRoute(req, { rates: null, provenance: "unknown" }, settings);
@@ -4641,12 +4857,13 @@ export function createDispatchBundle(
 					failureMessage = finalDetail;
 				}
 				const status = runStatusForOutcome(finalOutcome);
-				const failureClass = classifyFailure(
-					evidence,
-					{ exitCode: result.exitCode, signal: null, ...(failureMessage ? { stderrTail: failureMessage } : {}) },
-					finalOutcome,
-					outcomeCode,
-				);
+				const classifiedResult: SpawnedWorkerResult = {
+					exitCode: result.exitCode,
+					signal: null,
+					...(failureMessage ? { stderrTail: failureMessage } : {}),
+				};
+				const failureClass = classifyFailure(evidence, classifiedResult, finalOutcome, outcomeCode);
+				const contextOverflow = isContextOverflowFailure(failureClass, classifiedResult, outcomeCode);
 				const receiptDraft = buildReceiptDraft(result, endedAt, status, finalOutcome, finalDetail, capturedOutput);
 				const ledgerPatch: Partial<RunEnvelope> = {
 					status,
@@ -4676,10 +4893,17 @@ export function createDispatchBundle(
 				const receipt = ledgerRef.recordReceipt(envelope.id, sealRouteDecision(receiptDraft, routeDecision));
 				await ledgerRef.persist();
 				active.delete(envelope.id);
-				recordTargetOutcome(targetId, runtimeId, wireModelId, status, receipt.exitCode, failureClass);
+				recordTargetOutcome(envelope.id, targetId, runtimeId, wireModelId, status, receipt.exitCode, failureClass);
 				accumulateFinalizedTotals(receipt);
 				emitTerminalDispatchEvent(receipt, finalOutcome);
-				completeAssignmentAttempt(activeRun, receipt, finalOutcome, receipt.outcomeDetail ?? finalDetail, failureClass);
+				completeAssignmentAttempt(
+					activeRun,
+					receipt,
+					finalOutcome,
+					receipt.outcomeDetail ?? finalDetail,
+					failureClass,
+					contextOverflow,
+				);
 				return receipt;
 			} catch (error) {
 				// Finalization itself failed (ACP promise rejection, ledger or
@@ -4704,7 +4928,7 @@ export function createDispatchBundle(
 				}
 				active.delete(envelope.id);
 				settleAssignmentDurablyWithoutReceipt(lineage.rootRunId, envelope.id);
-				recordTargetOutcome(targetId, runtimeId, wireModelId, "failed", 1, "internal");
+				recordTargetOutcome(envelope.id, targetId, runtimeId, wireModelId, "failed", 1, "internal");
 				context.bus.emit(BusChannels.DispatchFailed, {
 					runId: envelope.id,
 					agentId: req.agentId,
@@ -4740,6 +4964,25 @@ export function createDispatchBundle(
 		observer?: DispatchAdmissionObserver,
 		preparation?: DispatchPreparationOptions,
 		settlement?: BatchVerificationGate,
+	): ReturnType<typeof admitDispatchAttempt> {
+		const probeClaims: ProbeClaim[] = [];
+		try {
+			return await admitDispatchAttempt(req, probeClaims, observer, preparation, settlement);
+		} catch (error) {
+			// A half-open route admitted this dispatch as its probe, but the run never
+			// started. Without the release the route would wait on a probe outcome
+			// that cannot arrive.
+			for (const claim of probeClaims) targetBreaker.release(claim.key, claim.owner);
+			throw error;
+		}
+	}
+
+	async function admitDispatchAttempt(
+		req: DispatchRequest,
+		probeClaims: ProbeClaim[],
+		observer?: DispatchAdmissionObserver,
+		preparation?: DispatchPreparationOptions,
+		settlement?: BatchVerificationGate,
 	): Promise<{
 		runId: string;
 		events: AsyncIterableIterator<unknown>;
@@ -4817,6 +5060,7 @@ export function createDispatchBundle(
 		};
 		if (req.delegationAgentId) {
 			assertPlannedNodeIdentity(req, { id: "local", kind: "local" });
+			assertTurnConstraintCompatibility(req, [], false);
 			assertProtectedArtifactsEnforceable("acp-delegation", false, protectedArtifactState);
 			if (req.responseSchema !== undefined) {
 				throw new UnsupportedResponseSchemaError(
@@ -4838,6 +5082,7 @@ export function createDispatchBundle(
 				settings,
 				timing,
 				routeObservation.decision,
+				probeClaims,
 				observer,
 				preparation?.deadlineAt,
 				hostRun,
@@ -4866,6 +5111,7 @@ export function createDispatchBundle(
 			lifecycle.target.target.id,
 			lifecycle.target.runtime.id,
 			lifecycle.target.wireModelId,
+			probeClaims,
 		);
 
 		assertBudgetAdmitsRoute(req, lifecycle.target.effectivePricing, settings);
@@ -5022,6 +5268,19 @@ export function createDispatchBundle(
 			}
 			appendLedgerPost(attribution, body);
 		};
+		// A model this worker loaded is this process's to release at exit, and
+		// stays out of mid-session eviction until then (#379). The report is
+		// checked against the admitted route, and the endpoint comes from this
+		// process's own target, so a worker can neither redirect the release nor
+		// claim a model it was not dispatched to.
+		const onModelLoaded = (load: WorkerModelLoad): void => {
+			adoptWorkerModelLoad(load, {
+				target: lifecycle.target.target,
+				runtime: lifecycle.target.runtime,
+				wireModelId: lifecycle.target.wireModelId,
+				node: placed,
+			});
+		};
 		let worker: SpawnedWorker;
 		try {
 			preparation?.signal?.throwIfAborted();
@@ -5029,6 +5288,7 @@ export function createDispatchBundle(
 				cwd: lifecycle.cwd,
 				now,
 				monotonicNow,
+				onModelLoaded,
 				...(agentLedgerId !== null ? { onLedgerPost } : {}),
 			});
 		} catch (error) {
@@ -5112,8 +5372,31 @@ export function createDispatchBundle(
 		let workerPolicyPermissionCounter = 0;
 		// The bound the receipt can seal follows the contract this run will be
 		// validated against; a conforming result never arrives clipped.
+		const helperContract = dispatchResultContract(req, lifecycle.recipe);
 		const outputCapture = createWorkerOutputCapture({
-			maxBytes: workerOutputCaptureBytes(dispatchResultContract(req, lifecycle.recipe)),
+			maxBytes: workerOutputCaptureBytes(helperContract),
+			...(spec.helperResult === true &&
+			acceptsOutcomeCodeEvents &&
+			(lifecycle.agentAudience === "shadow" || lifecycle.agentAudience === "internal") &&
+			helperContract &&
+			(INTERNAL_HELPER_RESULT_KINDS as readonly string[]).includes(helperContract.kind)
+				? {
+						helperResult: {
+							contract: helperContract,
+							validate: (data: unknown) =>
+								validateStructuredHelperResult({
+									contract: helperContract,
+									data,
+									cwd: lifecycle.cwd,
+									networkAllowed:
+										lifecycle.admission.allowedTools.includes(ToolNames.WebFetch) ||
+										lifecycle.admission.allowedTools.includes(ToolNames.WebRead),
+									observedRunEffects: runEffects.snapshot(),
+									filesystem: nodeResultContractFilesystem(),
+								}).structured,
+						},
+					}
+				: {}),
 		});
 		const markObservedPhase = (field: "firstModelTokenAt" | "firstToolAt"): void => {
 			if (timing[field] !== undefined) return;
@@ -5984,6 +6267,7 @@ export function createDispatchBundle(
 				}
 				const status = runStatusForOutcome(finalOutcome);
 				const failureClass = classifyFailure(evidence, result, finalOutcome, outcomeCode);
+				const contextOverflow = isContextOverflowFailure(failureClass, result, outcomeCode);
 				const receiptDraft = buildReceiptDraft(
 					result,
 					endedAt,
@@ -6074,9 +6358,19 @@ export function createDispatchBundle(
 					} catch (cleanupError) {
 						reportDispatchDiagnostic(`clean applied task worktree ${req.taskWorktree.runId}`, cleanupError);
 					}
+				} else if (req.taskWorktree !== undefined) {
+					// The run is over and its worktree stays for the operator (preserve
+					// mode, a failed run, a refused merge). Saying so on the claim keeps
+					// restart recovery from reading it as a crash.
+					try {
+						settleTaskWorktree(req.taskWorktree);
+					} catch (settleError) {
+						reportDispatchDiagnostic(`settle task worktree ${req.taskWorktree.runId}`, settleError);
+					}
 				}
 				active.delete(envelope.id);
 				recordTargetOutcome(
+					envelope.id,
 					lifecycle.target.target.id,
 					lifecycle.target.runtime.id,
 					lifecycle.target.wireModelId,
@@ -6087,7 +6381,14 @@ export function createDispatchBundle(
 				recordNodeChannelOutcome(activeRun, finalOutcome, failureClass, finalDetail);
 				accumulateFinalizedTotals(receipt);
 				emitTerminalDispatchEvent(receipt, finalOutcome);
-				completeAssignmentAttempt(activeRun, receipt, finalOutcome, receipt.outcomeDetail ?? finalDetail, failureClass);
+				completeAssignmentAttempt(
+					activeRun,
+					receipt,
+					finalOutcome,
+					receipt.outcomeDetail ?? finalDetail,
+					failureClass,
+					contextOverflow,
+				);
 				return receipt;
 			} catch (error) {
 				// Finalization itself failed (worker promise rejection, ledger or
@@ -6113,6 +6414,7 @@ export function createDispatchBundle(
 				active.delete(envelope.id);
 				settleAssignmentDurablyWithoutReceipt(lineage.rootRunId, envelope.id);
 				recordTargetOutcome(
+					envelope.id,
 					lifecycle.target.target.id,
 					lifecycle.target.runtime.id,
 					lifecycle.target.wireModelId,
@@ -6164,6 +6466,12 @@ export function createDispatchBundle(
 		events: AsyncIterableIterator<unknown>;
 		finalPromise: Promise<RunReceipt>;
 	}> {
+		const constraints = snapshotTurnConstraints(preparation?.turnConstraints ?? req.turnConstraints);
+		if (constraints) {
+			req = { ...req, turnConstraints: constraints, ...(constraints.skills === "disabled" ? { noSkills: true } : {}) };
+			// Validate before creating worktrees or acquiring writer/capacity leases.
+			previewFixed(req);
+		}
 		let prepared =
 			preparation?.deadlineAt === undefined
 				? req
@@ -6189,7 +6497,27 @@ export function createDispatchBundle(
 			const runId = newRunId();
 			let taskWorktree: NonNullable<DispatchRequest["taskWorktree"]>;
 			try {
-				taskWorktree = createTaskWorktree(root, runId);
+				// fleet.worktrees.root moves the working tree for local placement
+				// only: with fleet nodes the run may land on another host, which
+				// reaches the worktree by the project-root path alone.
+				const fleetSettings = getEffectiveSettings()?.fleet;
+				let worktreeRoot = resolveWorktreeRoot({
+					setting: fleetSettings?.worktrees?.root ?? "disk",
+					projectRoot: root,
+					remoteEligible: (fleetSettings?.nodes?.length ?? 0) > 0,
+				});
+				const untrusted = prepareWorktreeParent(worktreeRoot);
+				if (untrusted !== null) {
+					worktreeRoot = {
+						parent: diskWorktreeParent(root),
+						kind: "disk",
+						notice: `${untrusted}; using the project root`,
+					};
+				}
+				if (worktreeRoot.notice !== undefined) {
+					reportDispatchDiagnostic(`task worktree root for ${runId}`, new Error(worktreeRoot.notice));
+				}
+				taskWorktree = createTaskWorktree(root, runId, undefined, req.apply ?? "merge", worktreeRoot.parent);
 			} catch (error) {
 				writerLease?.release();
 				throw error;
@@ -6276,6 +6604,7 @@ export function createDispatchBundle(
 
 		if (req.delegationAgentId) {
 			const protectedArtifactState = getProtectedArtifactState();
+			assertTurnConstraintCompatibility(req, [], false);
 			assertProtectedArtifactsEnforceable("acp-delegation", false, protectedArtifactState);
 			if (req.responseSchema !== undefined) {
 				throw new UnsupportedResponseSchemaError(
@@ -6351,6 +6680,7 @@ export function createDispatchBundle(
 			target,
 			pathScope.writeBoundaries.length > 0,
 		);
+		assertTurnConstraintCompatibility(req, effectiveTools, target.runtime.kind === "http");
 		assertRuntimeCanHonorWorkerPermissionMode(target.runtime, settings?.fleet.permissions.mode ?? "deny");
 		assertResponseSchemaEnforceable(target.runtime, target.modelCapabilities, req.responseSchema, effectiveTools.length);
 		assertWriteRootsEnforceable(target.runtime, pathScope.writeBoundaries);
@@ -7249,6 +7579,19 @@ export function createDispatchBundle(
 			markCollected: markDetachedBatchCollected,
 		},
 		snapshot,
+		routeBreakers: () =>
+			targetBreaker.snapshot().map((route) => {
+				const [targetId = "", runtimeId = "", wireModelId = ""] = route.key.split("\0");
+				return {
+					targetId,
+					runtimeId,
+					wireModelId,
+					state: route.state,
+					remainingMs: route.remainingMs,
+					reason: route.reason,
+					consecutiveFailures: route.consecutiveFailures,
+				};
+			}),
 		drain,
 	};