@iowarp/clio-coder 0.4.7 → 0.4.9

package/src/domains/dispatch/extension.ts

@@ -21,7 +21,7 @@ import { BusChannels, type DispatchCompletedPayload, type DispatchRunIdentity }
 import { DEFAULT_SETTINGS, type DelegationToolGovernance } from "../../core/defaults.js";
 import type { DomainBundle, DomainContext, DomainExtension } from "../../core/domain-loader.js";
 import { gatewayRoutingObservationFromRecord } from "../../core/gateway-routing.js";
-import { GUARDRAIL_DEFAULTS } from "../../core/guardrails.js";
+import { GUARDRAIL_DEFAULTS, resolveGuardrail } from "../../core/guardrails.js";
 import { readClioVersion, readPiMonoVersion } from "../../core/package-root.js";
 import { canonicalizeExistingPath } from "../../core/path-canonical.js";
 import { protectedResidencyModels } from "../../core/residency-protection.js";
@@ -46,6 +46,7 @@ import { WORKER_RUNTIME_MEDIATES_CLIO_DISPATCH } from "../../engine/worker-runti
 import { toolPromptHintsForNames } from "../../tools/builtin-tool-catalog.js";
 import { networkToolsDisabled } from "../../tools/network-policy.js";
 import { applyToolProfile, assertToolProfileEnforceable, type ToolProfileName } from "../../tools/profiles.js";
+import { withGatewayForCapabilities } from "../../tools/surface.js";
 import {
 	applyTaskWorktree,
 	cleanupTaskWorktree,
@@ -325,7 +326,10 @@ interface RunTokenMeter {
 	outputTokens: number;
 	cacheReadTokens: number;
 	cacheWriteTokens: number;
+	cacheWrite1hTokens?: number;
 	reasoningTokens: number;
+	/** Native calls are priced individually by the SDK, including cache TTLs and context tiers. */
+	costUsd?: number;
 }
 
 interface ActiveRun {
@@ -458,6 +462,7 @@ function sealRouteDecision(draft: RunReceiptDraft, decision: RouteDecisionV1): R
 export const UNKNOWN_PRICING_ADMISSION_ESTIMATE_USD = 1;
 
 function calculateUsageCostUsd(meter: RunTokenMeter, pricing: EffectivePricing["rates"]): number {
+	if (meter.costUsd !== undefined) return meter.costUsd;
 	if (pricing === null) return 0;
 	return (
 		(meter.inputTokens * pricing.input +
@@ -468,6 +473,39 @@ function calculateUsageCostUsd(meter: RunTokenMeter, pricing: EffectivePricing["
 	);
 }
 
+function accumulateNativeUsage(
+	meter: RunTokenMeter,
+	usage: Record<string, unknown>,
+	pricing: EffectivePricing["rates"],
+): void {
+	const count = (value: unknown): number =>
+		typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+	const call: RunTokenMeter = {
+		inputTokens: count(usage.input),
+		outputTokens: count(usage.output),
+		cacheReadTokens: count(usage.cacheRead),
+		cacheWriteTokens: count(usage.cacheWrite),
+		reasoningTokens: extractReasoningTokenCount(usage),
+	};
+	const reported = isRecord(usage.cost) ? usage.cost.total : undefined;
+	// An SDK total is already priced with per-call tiers, service tier
+	// and cache-write lifetime. Never reprice it from an aggregate token count.
+	// Retain the target-rate fallback only for workers that omit calculated
+	// cost. Zero remains zero; its provenance still comes from the target.
+	const callCost =
+		typeof reported === "number" && Number.isFinite(reported) && reported >= 0
+			? reported
+			: calculateUsageCostUsd(call, pricing);
+	meter.costUsd = (meter.costUsd ?? 0) + callCost;
+	meter.inputTokens += call.inputTokens;
+	meter.outputTokens += call.outputTokens;
+	meter.cacheReadTokens += call.cacheReadTokens;
+	meter.cacheWriteTokens += call.cacheWriteTokens;
+	if (typeof usage.cacheWrite1h === "number" && usage.cacheWrite1h >= 0 && usage.cacheWrite1h <= call.cacheWriteTokens)
+		meter.cacheWrite1hTokens = (meter.cacheWrite1hTokens ?? 0) + usage.cacheWrite1h;
+	meter.reasoningTokens += call.reasoningTokens;
+}
+
 /**
  * Output-token figure the admission estimate prices a route against. Settings
  * always carry `defaults.maxTokens`; the fallback covers the callers that
@@ -1655,12 +1693,19 @@ function effectiveToolNames(
 		(tool): tool is ToolName =>
 			(isBuiltinToolName(tool) || harnessTools.has(tool)) &&
 			tool !== ToolNames.AskUser &&
-			!(networkStripped && tool === ToolNames.WebFetch) &&
+			!(networkStripped && (tool === ToolNames.WebFetch || tool === ToolNames.WebRead)) &&
 			!denied.has(tool) &&
 			!(writeConfined && WRITE_ROOT_REFUSED_TOOLS.has(tool)) &&
 			(target.runtime.id !== "claude-sdk" || isClaudeCanonicalTool(tool)),
 	);
-	return [...new Set(names)].sort();
+	// A native worker reaches a gateway-placed capability (git, web_fetch, an
+	// extension command) through the attached `gateway` tool, so the admitted
+	// list gains `gateway` whenever it names one. The worker's own narrowing
+	// (tools/agent-tools.ts effectiveToolNames) applies the same rule, which is
+	// what keeps the approved tool signature equal to the attested one.
+	const mediated = target.runtime.kind === "http" && target.runtime.id !== "claude-sdk";
+	const surface = mediated ? withGatewayForCapabilities(names) : [...new Set(names)];
+	return surface.sort();
 }
 
 /**
@@ -1679,13 +1724,23 @@ function assertPostRuntimeToolCompatibility(
 	spec: ReturnType<typeof normalizeAgentSpec>,
 	effectiveTools: ReadonlyArray<ToolName>,
 	target: ResolvedTarget,
+	writeConfined: boolean,
 ): void {
 	const compatibility = resolveAgentToolCompatibility(spec, effectiveTools, {
 		mediatesDispatch: WORKER_RUNTIME_MEDIATES_CLIO_DISPATCH,
 	});
 	if (compatibility.compatible) return;
+	// Name the narrowing that removed the tool: blaming the runtime sends the
+	// caller to another model when its own write roots caused the refusal.
+	const confined = writeConfined
+		? compatibility.missingRequired.filter((tool) => WRITE_ROOT_REFUSED_TOOLS.has(tool))
+		: [];
+	const cause =
+		confined.length > 0
+			? `; declared write roots remove ${confined.join(", ")}, so omit write roots (use autonomy: "read-only" or worktree: true) for this agent`
+			: "";
 	throw new Error(
-		`dispatch: admission denied: agent '${agentId}' is incompatible with runtime '${target.runtime.id}' after tool narrowing; missing required tools: ${compatibility.missingRequired.join(", ")}`,
+		`dispatch: admission denied: agent '${agentId}' is incompatible with runtime '${target.runtime.id}' after tool narrowing; missing required tools: ${compatibility.missingRequired.join(", ")}${cause}`,
 	);
 }
 
@@ -2838,11 +2893,30 @@ export function createDispatchBundle(
 		rootRunId: string;
 		terminalCandidate: RunReceipt;
 		timer: ReturnType<typeof setTimeout>;
+		settleCanceled: () => void;
 	}
 	const retryQueue = new Map<string, RetryQueueEntry>();
 	const retryBackoff = new Map<string, BackoffState>();
 	const retryReasons = new Map<string, string>();
 	const assignmentRootsByAttempt = new Map<string, string>();
+	// Fleet lineage is shared ancestry, not control ownership. Keep each
+	// member's retry chain distinct without changing persisted lineage.
+	const controlRootsByAttempt = new Map<string, string>();
+	const controlAttempts = new Map<string, { lineage: RunLineage; reservation: DispatchRequest["reservation"] }>();
+	const canceledControlRoots = new Set<string>();
+	const memberWork = new Map<string, Set<Promise<unknown>>>();
+	function trackMemberWork(runId: string, operation: Promise<unknown>): void {
+		const root = controlRootsByAttempt.get(runId) ?? runId;
+		const work = memberWork.get(root) ?? new Set<Promise<unknown>>();
+		memberWork.set(root, work);
+		work.add(operation);
+		const settled = (): void => {
+			work.delete(operation);
+			if (work.size === 0) memberWork.delete(root);
+		};
+		operation.then(settled, settled);
+	}
+
 	const assignments = new AssignmentRegistry({
 		onStreamError: (error) => reportDispatchDiagnostic("assignment event stream", error),
 	});
@@ -2874,6 +2948,20 @@ export function createDispatchBundle(
 	function lineageFor(req: DispatchRequest, runId: string): RunLineage {
 		const lineage = req.lineage ? { ...req.lineage } : { parentRunId: null, rootRunId: runId, attempt: 0, depth: 0 };
 		assignmentRootsByAttempt.set(runId, lineage.rootRunId);
+		const parent = lineage.parentRunId === null ? undefined : controlAttempts.get(lineage.parentRunId);
+		// Repair ordinals and fleet ancestry do not establish a retry. Only a
+		// known consecutive attempt of the same reservation member can do so.
+		const continuesParent =
+			parent !== undefined &&
+			parent.lineage.rootRunId === lineage.rootRunId &&
+			parent.lineage.depth === lineage.depth &&
+			parent.lineage.attempt + 1 === lineage.attempt &&
+			parent.reservation?.ownerId === req.reservation?.ownerId &&
+			parent.reservation?.memberId === req.reservation?.memberId;
+		const priorControl =
+			continuesParent && lineage.parentRunId !== null ? controlRootsByAttempt.get(lineage.parentRunId) : undefined;
+		controlRootsByAttempt.set(runId, priorControl ?? runId);
+		controlAttempts.set(runId, { lineage, reservation: req.reservation });
 		return lineage;
 	}
 
@@ -2940,7 +3028,8 @@ export function createDispatchBundle(
 
 	/** A reserved plan member owns its retry chain independently of the shared fleet root assignment. */
 	function retryChainIsLive(run: ActiveRun): boolean {
-		if (run.aborted) return false;
+		if (run.aborted || canceledControlRoots.has(controlRootsByAttempt.get(run.runId) ?? run.lineage.rootRunId))
+			return false;
 		const reservation = run.req.reservation;
 		if (reservation === undefined) return assignments.get(run.lineage.rootRunId)?.status === "running";
 		try {
@@ -3024,9 +3113,18 @@ export function createDispatchBundle(
 		const attempt = run.lineage.attempt + 1;
 		const reason = detail !== null ? `${outcome}: ${detail}` : outcome;
 		const dueAt = now() + delayMs;
+		let settleCanceled!: () => void;
+		let rejectContinuation!: (error: unknown) => void;
+		const continuation = new Promise<void>((resolve, reject) => {
+			settleCanceled = resolve;
+			rejectContinuation = reject;
+		});
+		trackMemberWork(run.runId, continuation);
 		const timer = setTimeout(() => {
 			retryQueue.delete(run.runId);
-			void executeRetry(run, attempt, reason, decision);
+			// 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);
 		}, delayMs);
 		retryQueue.set(run.runId, {
 			runId: run.runId,
@@ -3039,6 +3137,7 @@ export function createDispatchBundle(
 			rootRunId,
 			terminalCandidate: receipt,
 			timer,
+			settleCanceled,
 		});
 		context.bus.emit(BusChannels.DispatchProgress, {
 			runId: run.runId,
@@ -3139,6 +3238,7 @@ export function createDispatchBundle(
 		// the worktree it created). A retry shares the assignment lineage but
 		// must receive its own ledger/run identity.
 		delete retryReq.runIdHint;
+		let terminal: Promise<RunReceipt> | undefined;
 		const reasonKey = retryReasonKey(run.lineage.rootRunId, attempt);
 		retryReasons.set(reasonKey, reason);
 		try {
@@ -3204,6 +3304,10 @@ export function createDispatchBundle(
 				if (decision.excludedRouteParts.includes("runtime")) delete retryReq.workerRuntime;
 			}
 			const handle = await dispatch(retryReq, undefined, run.hostRun === undefined ? undefined : { hostRun: run.hostRun });
+			// Cancellation can arrive while retry admission is awaiting a handle.
+			if (canceledControlRoots.has(controlRootsByAttempt.get(run.runId) ?? run.lineage.rootRunId)) {
+				contract.abort(handle.runId);
+			}
 			// The assignment folds every attempt into one stream with a reset marker.
 			const marker: AssignmentAttemptStartEvent = {
 				type: "attempt_start",
@@ -3225,6 +3329,7 @@ export function createDispatchBundle(
 				runtimeKind: run.runtimeKind,
 				event: marker,
 			});
+			terminal = handle.finalPromise;
 			handle.finalPromise.catch((error) => {
 				assignments.reject(asAssignmentId(run.lineage.rootRunId), error);
 				reportDispatchDiagnostic(`finalize retry run ${handle.runId}`, error);
@@ -3257,6 +3362,7 @@ export function createDispatchBundle(
 				outcomeDetail: denial,
 			});
 		}
+		await terminal;
 	}
 
 	function requireLedger(): Ledger {
@@ -3647,7 +3753,7 @@ export function createDispatchBundle(
 			),
 			req,
 		);
-		assertPostRuntimeToolCompatibility(req.agentId, spec, effectiveTools, target);
+		assertPostRuntimeToolCompatibility(req.agentId, spec, effectiveTools, target, pathScope.writeBoundaries.length > 0);
 		const effectiveAdmission: DispatchAdmissionStage = {
 			...admission,
 			allowedTools: effectiveTools,
@@ -3952,7 +4058,13 @@ export function createDispatchBundle(
 		}
 		timing.workerSpawnedAt = new Date(now()).toISOString();
 
-		const tokenMeter = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, reasoningTokens: 0 };
+		const tokenMeter: RunTokenMeter = {
+			inputTokens: 0,
+			outputTokens: 0,
+			cacheReadTokens: 0,
+			cacheWriteTokens: 0,
+			reasoningTokens: 0,
+		};
 		const safetyDecisionCounts = { allowed: 0, blocked: 0, permissionRequested: 0 };
 		const blockedAttempts: SafetyBlockedAttempt[] = [];
 		const toolStats = new Map<string, ToolCallStat>();
@@ -4341,6 +4453,7 @@ export function createDispatchBundle(
 				outputTokenCount: tokenMeter.outputTokens,
 				cacheReadTokenCount: tokenMeter.cacheReadTokens,
 				cacheWriteTokenCount: tokenMeter.cacheWriteTokens,
+				...(tokenMeter.cacheWrite1hTokens === undefined ? {} : { cacheWrite1hTokenCount: tokenMeter.cacheWrite1hTokens }),
 				reasoningTokenCount: tokenMeter.reasoningTokens,
 				...(upstreamResponses.length > 0 ? { upstreamResponses: [...upstreamResponses] } : {}),
 				...(capturedOutput !== undefined ? { output: capturedOutput } : {}),
@@ -4427,6 +4540,7 @@ export function createDispatchBundle(
 				outputTokenCount: receipt.outputTokenCount ?? 0,
 				cacheReadTokenCount: receipt.cacheReadTokenCount ?? 0,
 				cacheWriteTokenCount: receipt.cacheWriteTokenCount ?? 0,
+				...(receipt.cacheWrite1hTokenCount === undefined ? {} : { cacheWrite1hTokenCount: receipt.cacheWrite1hTokenCount }),
 				reasoningTokenCount: receipt.reasoningTokenCount ?? 0,
 				staticShellHash: receipt.staticShellHash ?? null,
 				sessionShellHash: receipt.sessionShellHash ?? null,
@@ -4552,6 +4666,9 @@ export function createDispatchBundle(
 					dynamicHash: receiptDraft.dynamicHash ?? null,
 					cacheReadTokenCount: receiptDraft.cacheReadTokenCount ?? 0,
 					cacheWriteTokenCount: receiptDraft.cacheWriteTokenCount ?? 0,
+					...(receiptDraft.cacheWrite1hTokenCount === undefined
+						? {}
+						: { cacheWrite1hTokenCount: receiptDraft.cacheWrite1hTokenCount }),
 					reasoningTokenCount: receiptDraft.reasoningTokenCount ?? 0,
 					heartbeatAt: heartbeatIso(acp.heartbeatAt),
 				};
@@ -4838,7 +4955,13 @@ export function createDispatchBundle(
 				throw error;
 			}
 		})();
-		const tokenMeter = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, reasoningTokens: 0 };
+		const tokenMeter: RunTokenMeter = {
+			inputTokens: 0,
+			outputTokens: 0,
+			cacheReadTokens: 0,
+			cacheWriteTokens: 0,
+			reasoningTokens: 0,
+		};
 		const safetyDecisionCounts = { allowed: 0, blocked: 0, permissionRequested: 0 };
 		const escalationCounts = { requested: 0, approved: 0, denied: 0, timedOut: 0 };
 		const blockedAttempts: SafetyBlockedAttempt[] = [];
@@ -5118,11 +5241,7 @@ export function createDispatchBundle(
 			}
 			if (event.type === "message_end" && event.message?.role === "assistant" && isRecord(event.message.usage)) {
 				const u = event.message.usage;
-				tokenMeter.inputTokens += typeof u.input === "number" ? u.input : 0;
-				tokenMeter.outputTokens += typeof u.output === "number" ? u.output : 0;
-				tokenMeter.cacheReadTokens += typeof u.cacheRead === "number" ? u.cacheRead : 0;
-				tokenMeter.cacheWriteTokens += typeof u.cacheWrite === "number" ? u.cacheWrite : 0;
-				tokenMeter.reasoningTokens += extractReasoningTokenCount(u);
+				accumulateNativeUsage(tokenMeter, u, lifecycle.target.effectivePricing.rates);
 				const requestedModelId = readStringOrNull(event.message.model);
 				const responseModelIdObservation = responseModelIdObservationFromRecord(event.message, "not-observed");
 				const differingResponseModelId = readStringOrNull(event.message.responseModel);
@@ -5552,11 +5671,15 @@ export function createDispatchBundle(
 				outputTokenCount: tokenMeter.outputTokens,
 				cacheReadTokenCount: tokenMeter.cacheReadTokens,
 				cacheWriteTokenCount: tokenMeter.cacheWriteTokens,
+				...(tokenMeter.cacheWrite1hTokens === undefined ? {} : { cacheWrite1hTokenCount: tokenMeter.cacheWrite1hTokens }),
 				reasoningTokenCount: tokenMeter.reasoningTokens,
 				...(upstreamResponses.length > 0 ? { upstreamResponses: [...upstreamResponses] } : {}),
 				...(capturedOutput !== undefined ? { output: capturedOutput } : {}),
 				costUsd,
-				costProvenance: lifecycle.target.effectivePricing.provenance,
+				costProvenance:
+					lifecycle.target.effectivePricing.provenance === "unknown" && costUsd > 0
+						? "estimated"
+						: lifecycle.target.effectivePricing.provenance,
 				compiledPromptHash: lifecycle.compiledPromptHash,
 				staticCompositionHash: lifecycle.staticCompositionHash,
 				staticShellHash: lifecycle.staticCompositionHash,
@@ -5646,6 +5769,7 @@ export function createDispatchBundle(
 				outputTokenCount: receipt.outputTokenCount ?? 0,
 				cacheReadTokenCount: receipt.cacheReadTokenCount ?? 0,
 				cacheWriteTokenCount: receipt.cacheWriteTokenCount ?? 0,
+				...(receipt.cacheWrite1hTokenCount === undefined ? {} : { cacheWrite1hTokenCount: receipt.cacheWrite1hTokenCount }),
 				reasoningTokenCount: receipt.reasoningTokenCount ?? 0,
 				staticShellHash: receipt.staticShellHash ?? null,
 				sessionShellHash: receipt.sessionShellHash ?? null,
@@ -5769,6 +5893,7 @@ export function createDispatchBundle(
 					cwd: lifecycle.cwd,
 					networkAllowed:
 						lifecycle.admission.allowedTools.includes(ToolNames.WebFetch) ||
+						lifecycle.admission.allowedTools.includes(ToolNames.WebRead) ||
 						lifecycle.target.runtime.externalAgentLoop?.network === "externally-governed-unobserved",
 					observedRunEffects,
 					filesystem: nodeResultContractFilesystem(),
@@ -5891,6 +6016,9 @@ export function createDispatchBundle(
 					...(receiptDraft.cacheReadTokenCount !== undefined
 						? { cacheReadTokenCount: receiptDraft.cacheReadTokenCount }
 						: {}),
+					...(receiptDraft.cacheWrite1hTokenCount === undefined
+						? {}
+						: { cacheWrite1hTokenCount: receiptDraft.cacheWrite1hTokenCount }),
 					...(receiptDraft.cacheWriteTokenCount !== undefined
 						? { cacheWriteTokenCount: receiptDraft.cacheWriteTokenCount }
 						: {}),
@@ -6110,7 +6238,11 @@ export function createDispatchBundle(
 		}
 		// Requests carrying lineage are internal attempts (retry or nested
 		// orchestration) and retain the per-attempt handle contract.
-		if (req.lineage) return { ...handle, finalPromise: handle.finalPromise.finally(() => writerLease?.release()) };
+		if (req.lineage) {
+			const finalPromise = handle.finalPromise.finally(() => writerLease?.release());
+			trackMemberWork(handle.runId, finalPromise);
+			return { ...handle, finalPromise };
+		}
 
 		const assignment = assignments.open(handle.runId, assignmentPolicyFor(handle.effectiveRequest));
 		persistAssignment(registerAssignment(assignment.id), `${assignment.id}:open`);
@@ -6212,7 +6344,13 @@ export function createDispatchBundle(
 			),
 			req,
 		);
-		assertPostRuntimeToolCompatibility(req.agentId, agentSpec, effectiveTools, target);
+		assertPostRuntimeToolCompatibility(
+			req.agentId,
+			agentSpec,
+			effectiveTools,
+			target,
+			pathScope.writeBoundaries.length > 0,
+		);
 		assertRuntimeCanHonorWorkerPermissionMode(target.runtime, settings?.fleet.permissions.mode ?? "deny");
 		assertResponseSchemaEnforceable(target.runtime, target.modelCapabilities, req.responseSchema, effectiveTools.length);
 		assertWriteRootsEnforceable(target.runtime, pathScope.writeBoundaries);
@@ -6672,7 +6810,11 @@ export function createDispatchBundle(
 			// No in-memory executor survives a process restart, so every active
 			// side-store lease from an earlier bundle is orphaned and must expire.
 			cleanupDispatchReservations({ startup: true, nowMs: now() });
-			ledger = openLedger();
+			ledger = openLedger({
+				get maxRuns() {
+					return getEffectiveSettings()?.fleet?.history?.maxRuns ?? resolveGuardrail("maxDispatchRuns");
+				},
+			});
 			// Symphony P10: restart recovery from durable artifacts. Adopt
 			// receipts whose ledger rows were lost to a crash between
 			// recordReceipt() and persist(); quarantine tampered ones.
@@ -6802,6 +6944,7 @@ export function createDispatchBundle(
 			const meter = run.meter;
 			const totalTokens = meter.inputTokens + meter.outputTokens + meter.cacheReadTokens + meter.cacheWriteTokens;
 			const costUsd = calculateUsageCostUsd(meter, run.pricing);
+			const costProvenance = run.costProvenance === "unknown" && costUsd > 0 ? "estimated" : run.costProvenance;
 			const startedMs = Date.parse(run.startedAt);
 			const elapsedMs = Number.isFinite(startedMs) ? Math.max(0, tickNow - startedMs) : 0;
 			const timing = deriveRunPhaseDurations(run.timing, run.startedAt, new Date(tickNow).toISOString());
@@ -6819,14 +6962,14 @@ export function createDispatchBundle(
 				timing,
 				tokens: { input: meter.inputTokens, output: meter.outputTokens, total: totalTokens },
 				costUsd,
-				costProvenance: run.costProvenance,
+				costProvenance,
 				node: run.node !== null ? { ...run.node } : null,
 			});
 			totals.inputTokens += meter.inputTokens;
 			totals.outputTokens += meter.outputTokens;
 			totals.totalTokens += totalTokens;
 			totals.costUsd += costUsd;
-			costAmounts.push({ usd: costUsd, provenance: run.costProvenance });
+			costAmounts.push({ usd: costUsd, provenance: costProvenance });
 			totals.runtimeSeconds += elapsedMs / 1000;
 		}
 		const retrying = [...retryQueue.values()].map((entry) => ({
@@ -6864,6 +7007,7 @@ export function createDispatchBundle(
 	function settleQueuedAssignmentsForShutdown(): void {
 		for (const [finishedRunId, entry] of retryQueue) {
 			clearTimeout(entry.timer);
+			entry.settleCanceled();
 			if (assignments.get(entry.rootRunId)?.status === "running") {
 				settleAssignmentDurably(asAssignmentId(entry.rootRunId), entry.terminalCandidate, "canceled");
 			}
@@ -6909,11 +7053,28 @@ export function createDispatchBundle(
 		return stored?.assignmentId ?? ledger?.get(id)?.lineage?.rootRunId ?? id;
 	}
 
+	function controlRootFor(id: string): string {
+		const exact = controlRootsByAttempt.get(id);
+		if (exact !== undefined) return exact;
+		const roots = new Set<string>();
+		for (const [attempt, root] of assignmentRootsByAttempt) {
+			if (root === id) roots.add(controlRootsByAttempt.get(attempt) ?? root);
+		}
+		if (roots.size > 1) {
+			throw new Error(`dispatch: '${id}' names multiple fleet members; use a concrete member or assignment id`);
+		}
+		return roots.values().next().value ?? assignmentRootFor(id);
+	}
+
 	function currentAssignmentRun(id: string): ActiveRun | null {
-		const rootRunId = assignmentRootFor(id);
+		// An exact live attempt is authoritative even if a sibling has a higher
+		// attempt ordinal. Completed IDs may follow only their own retry chain.
+		const exact = active.get(id);
+		if (exact !== undefined) return exact;
+		const rootRunId = controlRootFor(id);
 		let current: ActiveRun | null = null;
 		for (const run of active.values()) {
-			if (run.lineage.rootRunId !== rootRunId) continue;
+			if ((controlRootsByAttempt.get(run.runId) ?? run.lineage.rootRunId) !== rootRunId) continue;
 			if (current === null || run.lineage.attempt > current.lineage.attempt) current = run;
 		}
 		return current;
@@ -6967,8 +7128,25 @@ export function createDispatchBundle(
 				await Promise.allSettled([...assignmentWrites]);
 			},
 		},
+		async drainMember(runId) {
+			const root = controlRootFor(runId);
+			const errors: unknown[] = [];
+			while (true) {
+				const pending = [...(memberWork.get(root) ?? [])];
+				const live = currentAssignmentRun(runId);
+				if (live !== null) pending.push(live.finalPromise);
+				if (pending.length === 0) break;
+				for (const result of await Promise.allSettled(pending)) {
+					if (result.status === "rejected" && !errors.includes(result.reason)) errors.push(result.reason);
+				}
+			}
+			if (errors.length === 1) throw errors[0];
+			if (errors.length > 1) throw new AggregateError(errors, "dispatch member drain failed", { cause: errors[0] });
+		},
 		abort(runId, reason) {
-			const rootRunId = assignmentRootFor(runId);
+			const rootRunId = controlRootFor(runId);
+			const run = currentAssignmentRun(runId);
+			canceledControlRoots.add(rootRunId);
 			const queued = pendingCapacity.get(rootRunId);
 			if (queued !== undefined && capacityAdmission.cancel(rootRunId)) {
 				persistAssignment(cancelStoredAssignment(rootRunId), `${rootRunId}:cancel-queued`);
@@ -6986,10 +7164,13 @@ export function createDispatchBundle(
 				persistAssignment(cancelStoredAssignment(rootRunId), `${rootRunId}:cancel`);
 			}
 			for (const [finishedRunId, retry] of retryQueue) {
-				if (retry.rootRunId !== rootRunId) continue;
+				if ((controlRootsByAttempt.get(finishedRunId) ?? retry.rootRunId) !== rootRunId) continue;
 				clearTimeout(retry.timer);
+				retry.settleCanceled();
 				retryQueue.delete(finishedRunId);
-				settleAssignmentDurably(asAssignmentId(rootRunId), retry.terminalCandidate, "canceled");
+				if (retry.rootRunId === rootRunId) {
+					settleAssignmentDurably(asAssignmentId(rootRunId), retry.terminalCandidate, "canceled");
+				}
 				context.bus.emit(BusChannels.RunAborted, {
 					source: "dispatch_abort",
 					runId: finishedRunId,
@@ -7004,7 +7185,6 @@ export function createDispatchBundle(
 					event: { type: "retry_canceled", attempt: retry.attempt },
 				});
 			}
-			const run = currentAssignmentRun(rootRunId);
 			if (!run) return;
 			emitRunAborted(run, "dispatch_abort");
 			run.aborted = true;

package/src/domains/dispatch/fleet-preflight.ts

@@ -18,6 +18,7 @@ import { performance } from "node:perf_hooks";
 import { readClioVersion } from "../../core/package-root.js";
 import { shellQuote } from "../../core/shell-quote.js";
 import { clioStateDir } from "../../core/xdg.js";
+import { atomicWrite } from "../../engine/session.js";
 import {
 	evaluateRouteFacts,
 	type FactState,
@@ -91,6 +92,20 @@ export function readFleetPreflightRecords(): FleetPreflightRecord[] {
 	}
 }
 
+/**
+ * Upsert records keyed by (nodeId, projectRoot). Only `clio-coder doctor --fix`
+ * writes: plain doctor stays observation-only, and dispatch admission fails
+ * closed on a node that has no stored passing record.
+ */
+export function recordFleetPreflight(records: ReadonlyArray<FleetPreflightRecord>): void {
+	const merged = new Map<string, FleetPreflightRecord>();
+	for (const record of [...readFleetPreflightRecords(), ...records]) {
+		merged.set(`${record.nodeId}\0${record.projectRoot}`, record);
+	}
+	const file: FleetPreflightStoreFile = { version: 2, records: [...merged.values()] };
+	atomicWrite(storePath(), JSON.stringify(file, null, 2));
+}
+
 export interface FleetPreflightVerdict {
 	ok: boolean;
 	reason: string | null;
@@ -110,19 +125,19 @@ export function fleetPreflightVerdict(
 	if (!record) {
 		return {
 			ok: false,
-			reason: `node '${node.id}' has not passed the fleet preflight for ${projectRoot}; run 'clio-coder doctor'`,
+			reason: `node '${node.id}' has not passed the fleet preflight for ${projectRoot}; run 'clio-coder doctor --fix'`,
 		};
 	}
 	if (record.host !== node.host) {
 		return {
 			ok: false,
-			reason: `node '${node.id}' preflight was recorded for host '${record.host}' but the node now points at '${node.host}'; run 'clio-coder doctor'`,
+			reason: `node '${node.id}' preflight was recorded for host '${record.host}' but the node now points at '${node.host}'; run 'clio-coder doctor --fix'`,
 		};
 	}
 	if (record.localVersion !== readClioVersion()) {
 		return {
 			ok: false,
-			reason: `node '${node.id}' preflight predates a local clio-coder upgrade (${record.localVersion} -> ${readClioVersion()}); run 'clio-coder doctor'`,
+			reason: `node '${node.id}' preflight predates a local clio-coder upgrade (${record.localVersion} -> ${readClioVersion()}); run 'clio-coder doctor --fix'`,
 		};
 	}
 	if (!record.ok) {

package/src/domains/dispatch/fleet-run.ts

@@ -788,6 +788,7 @@ export async function executeFleetRun(input: ExecuteFleetRunInput): Promise<Flee
 			beginWriteBoundary: (window, stepIds) => boundaryEnforcer.begin(window, stepIds),
 			verifyWriteBoundary: (window, stepIds) => boundaryEnforcer.verify(window, stepIds),
 			cancel: (assignmentId) => dispatch.abort(assignmentId),
+			drainMember: (assignmentId) => dispatch.drainMember?.(assignmentId) ?? Promise.resolve(),
 			release: (ownerId) => {
 				if (ownerId === NO_WORKER_RESERVATION) return;
 				dispatch.reservations?.release(ownerId);

package/src/domains/dispatch/gate-decisions.ts

@@ -75,7 +75,7 @@ export interface GateDecisionArtifact {
  * prose line. Two schemas exist because the two topologies ask different
  * questions:
  *
- *   - Review asks "does this work pass?", which is exactly the Slice 2
+ *   - Review asks "does this work pass?", which is exactly the
  *     `verifier-report` contract. There is deliberately no `revise` verdict:
  *     whether a failure is worth another cycle is the coordinator's bounded
  *     continuation policy, not a decision the reviewed model gets to author.
@@ -96,7 +96,7 @@ export interface CompeteGateResult {
 
 export type GateResultParse<T> = { ok: true; result: T } | { ok: false; reason: string };
 
-/** Parse a reviewer answer under the Slice 2 Verifier contract. */
+/** Parse a reviewer answer under the verifier-report contract. */
 function parseReviewGateResult(output: string): GateResultParse<ReviewGateResult> {
 	const result = parseVerifierResult(output);
 	return result === null
@@ -128,7 +128,7 @@ export interface ReviewGateDecision {
 /**
  * Apply the coordinator's review policy to one reviewer answer.
  *
- * The reviewer answers pass or fail under its Slice 2 contract and nothing
+ * The reviewer answers pass or fail under its verifier-report contract and nothing
  * else. `revise` is this function's bounded continuation decision: a failure
  * with cycles left earns another builder attempt, the same failure at the bound
  * is simply the terminal fail, and an answer that does not satisfy the contract

package/src/domains/dispatch/heartbeat.ts

@@ -1,5 +1,5 @@
 /**
- * Pure heartbeat watchdog classifier (Phase 6 slice 3).
+ * Pure heartbeat watchdog classifier.
  *
  * Maps a last-seen monotonic stamp to one of three states. The dispatch domain
  * drives this on each scheduler tick; the orchestrator uses `stale` to surface