@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/domains/dispatch/orphan-recovery.ts

@@ -0,0 +1,266 @@
+/**
+ * Startup recovery of orphaned receipts (Symphony P10: restart resumes from
+ * durable artifacts, not in-memory state).
+ *
+ * A crash between recordReceipt() and persist() leaves a sealed receipt on
+ * disk with no runs.json row. At dispatch-extension startup this module scans
+ * the receipts directory, reconstructs the ledger row each orphan was sealed
+ * against, verifies the integrity digest, and adopts valid orphans back into
+ * the ledger. Receipts that fail verification are renamed with a `.corrupt`
+ * suffix, never deleted. Receipts that cannot be reconstructed (pre-sprint
+ * receipts without a reproducibility block) are left untouched and counted as
+ * skipped: quarantining an unverifiable-but-possibly-valid artifact would
+ * destroy evidence.
+ */
+
+import { existsSync, readdirSync, readFileSync, renameSync } from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { clioStateDir } from "../../core/xdg.js";
+import { runStatusForOutcome } from "./outcome.js";
+import { isReceiptIntegrity, verifyReceiptIntegrity } from "./receipt-integrity.js";
+import type { Ledger } from "./state.js";
+import type { RunEnvelope, RunReceipt, RunStatus } from "./types.js";
+
+export interface OrphanRecoverySummary {
+	recovered: number;
+	corrupt: number;
+	skipped: number;
+	/** Non-terminal rows whose worker process no longer exists, closed as stalled. */
+	abandoned: number;
+	/** Non-terminal rows whose worker process is gone but whose own receipt verified, sealed from it. */
+	sealed: number;
+}
+
+/**
+ * Statuses the pre-taxonomy finalizer could have written. Tried in likelihood
+ * order; the integrity digest picks the right one.
+ */
+const STATUS_CANDIDATES: ReadonlyArray<RunStatus> = ["completed", "failed", "interrupted", "dead", "stale"];
+
+function receiptsDir(): string {
+	return join(clioStateDir(), "receipts");
+}
+
+/**
+ * Rebuild the RunEnvelope the receipt was sealed against. Every field the
+ * integrity digest covers is either present on the receipt verbatim or fixed
+ * by construction at finalization time (status is the only free variable).
+ */
+function envelopeFromReceipt(receipt: RunReceipt, status: RunStatus, receiptPath: string): RunEnvelope {
+	const envelope: RunEnvelope = {
+		id: receipt.runId,
+		agentId: receipt.agentId,
+		executionRole: receipt.executionRole,
+		...(receipt.agentAudience !== undefined ? { agentAudience: receipt.agentAudience } : {}),
+		...(receipt.requestOrigin !== undefined ? { requestOrigin: receipt.requestOrigin } : {}),
+		task: receipt.task,
+		...(receipt.briefing !== undefined ? { briefing: receipt.briefing } : {}),
+		...(receipt.steering !== undefined ? { steering: receipt.steering } : {}),
+		targetId: receipt.targetId,
+		wireModelId: receipt.wireModelId,
+		runtimeId: receipt.runtimeId,
+		runtimeKind: receipt.runtimeKind,
+		startedAt: receipt.startedAt,
+		endedAt: receipt.endedAt,
+		status,
+		exitCode: receipt.exitCode,
+		pid: null,
+		heartbeatAt: null,
+		receiptPath,
+		sessionId: receipt.sessionId,
+		cwd: receipt.reproducibility?.cwd ?? "",
+		tokenCount: receipt.tokenCount,
+		costUsd: receipt.costUsd,
+	};
+	if (receipt.cacheReadTokenCount !== undefined) envelope.cacheReadTokenCount = receipt.cacheReadTokenCount;
+	if (receipt.cacheWriteTokenCount !== undefined) envelope.cacheWriteTokenCount = receipt.cacheWriteTokenCount;
+	if (receipt.reasoningTokenCount !== undefined) envelope.reasoningTokenCount = receipt.reasoningTokenCount;
+	if (receipt.inputTokenCount !== undefined) envelope.inputTokenCount = receipt.inputTokenCount;
+	if (receipt.outputTokenCount !== undefined) envelope.outputTokenCount = receipt.outputTokenCount;
+	if (receipt.staticShellHash !== undefined) envelope.staticShellHash = receipt.staticShellHash;
+	if (receipt.sessionShellHash !== undefined) envelope.sessionShellHash = receipt.sessionShellHash;
+	if (receipt.dynamicHash !== undefined) envelope.dynamicHash = receipt.dynamicHash;
+	if (receipt.promptSignature !== undefined) envelope.promptSignature = receipt.promptSignature;
+	if (receipt.toolSignature !== undefined) envelope.toolSignature = receipt.toolSignature;
+	if (receipt.outcome !== undefined) {
+		envelope.outcome = receipt.outcome;
+		envelope.outcomeDetail = receipt.outcomeDetail ?? null;
+	}
+	if (receipt.outcomeCode !== undefined) envelope.outcomeCode = receipt.outcomeCode;
+	if (receipt.lineage !== undefined) envelope.lineage = receipt.lineage;
+	if (receipt.identity !== undefined) envelope.identity = receipt.identity;
+	if (receipt.node !== undefined) envelope.node = receipt.node;
+	if (receipt.reroutes !== undefined) envelope.reroutes = receipt.reroutes;
+	if (receipt.pipeline !== undefined) envelope.pipeline = receipt.pipeline;
+	if (receipt.gate !== undefined) envelope.gate = receipt.gate;
+	if (receipt.plan !== undefined) envelope.plan = receipt.plan;
+	if (receipt.personaOverride !== undefined) envelope.personaOverride = receipt.personaOverride;
+	return envelope;
+}
+
+function verifyOrphan(receipt: RunReceipt, receiptPath: string): RunEnvelope | null {
+	const candidates: ReadonlyArray<RunStatus> =
+		receipt.outcome !== undefined ? [runStatusForOutcome(receipt.outcome)] : STATUS_CANDIDATES;
+	for (const status of candidates) {
+		const envelope = envelopeFromReceipt(receipt, status, receiptPath);
+		if (verifyReceiptIntegrity(receipt, envelope).ok) return envelope;
+	}
+	return null;
+}
+
+function quarantine(path: string): boolean {
+	try {
+		renameSync(path, `${path}.corrupt`);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function isProcessAlive(pid: number | null): boolean {
+	if (pid === null || !Number.isFinite(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return (err as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+const NON_TERMINAL_STATUSES: ReadonlySet<string> = new Set(["queued", "running", "stale", "dead"]);
+
+/**
+ * The sealed receipt for a row that never made it to a persisted terminal
+ * state, or null when there is no receipt or it does not verify against a
+ * reconstructable envelope. A run writes its receipt before it persists the
+ * ledger, so this window is exactly where a crash or a clobbered persist leaves
+ * the truth on disk in the receipt and a lie in the row.
+ */
+function sealedEnvelopeFor(runId: string): RunEnvelope | null {
+	const path = join(receiptsDir(), `${runId}.json`);
+	if (!existsSync(path)) return null;
+	let receipt: RunReceipt;
+	try {
+		receipt = JSON.parse(readFileSync(path, "utf8")) as RunReceipt;
+	} catch {
+		return null;
+	}
+	if (receipt?.runId !== runId) return null;
+	if (!isReceiptIntegrity(receipt.integrity)) return null;
+	if (receipt.reproducibility?.cwd === undefined) return null;
+	return verifyOrphan(receipt, path);
+}
+
+/**
+ * Close abandoned ledger rows: a non-terminal row whose recorded worker pid
+ * no longer exists belongs to an orchestrator that died mid-run.
+ *
+ * Such a row may still have a sealed receipt on disk. A run writes its receipt
+ * before it persists the settled row, so a crash or a clobbered persist in that
+ * window leaves a receipt saying `succeeded`/0 next to a row that still says
+ * `running`. Stamping the row dead without looking was how a finished dispatch
+ * came to be recorded as a failure, and the receipt pass below could not repair
+ * it afterwards because it only adopts receipts with no row at all. So the
+ * receipt decides when it verifies, and only a row with nothing to seal is
+ * closed as "stalled" rather than left as a permanent ghost in status output.
+ *
+ * `endedAt` is the last instant the run was observed alive, not the instant
+ * recovery noticed it was gone. Stamping recovery time made every phase
+ * duration derived from the row (`executionMs`, `totalEndToEndMs`) span the
+ * whole orchestrator downtime, which is not a measurement of anything. The
+ * last heartbeat is the honest bound; a row that never heartbeat has only its
+ * own start, which reads as a zero-length run rather than an invented one.
+ */
+function closeAbandonedRows(ledger: Ledger): { closed: number; sealed: number } {
+	let closed = 0;
+	let sealed = 0;
+	const localHost = hostname();
+	for (const row of ledger.list()) {
+		if (row.endedAt !== null || !NON_TERMINAL_STATUSES.has(row.status)) continue;
+		// Transport-scoped liveness: the recorded pid is always a process on
+		// the orchestrator host that created the row (for ssh runs it is the
+		// local ssh client, i.e. the channel itself). On a shared filesystem
+		// the ledger is visible from other hosts, where a local pid probe would
+		// adjudicate the wrong process; rows created by another host are left
+		// for that host's own recovery pass.
+		if (row.identity !== undefined && row.identity.host !== localHost) continue;
+		if (isProcessAlive(row.pid)) continue;
+		const envelope = sealedEnvelopeFor(row.id);
+		if (envelope !== null) {
+			// Patch rather than replace: the row carries phase timings and lineage
+			// the receipt does not, and pid/heartbeatAt are this row's own history.
+			const { id: _id, pid: _pid, heartbeatAt: _heartbeatAt, ...settled } = envelope;
+			ledger.update(row.id, settled);
+			sealed += 1;
+			continue;
+		}
+		ledger.update(row.id, {
+			status: "dead",
+			outcome: "stalled",
+			outcomeDetail: "abandoned: orchestrator exited before the run finalized",
+			endedAt: row.heartbeatAt ?? row.startedAt,
+			exitCode: row.exitCode ?? 1,
+		});
+		closed += 1;
+	}
+	return { closed, sealed };
+}
+
+export function recoverOrphanReceipts(ledger: Ledger): OrphanRecoverySummary {
+	const summary: OrphanRecoverySummary = { recovered: 0, corrupt: 0, skipped: 0, abandoned: 0, sealed: 0 };
+	const abandoned = closeAbandonedRows(ledger);
+	summary.abandoned = abandoned.closed;
+	summary.sealed = abandoned.sealed;
+	const dir = receiptsDir();
+	if (!existsSync(dir)) return summary;
+	// Retention horizon: the ledger is a bounded ring, so a receipt older than
+	// the oldest retained row was evicted by the cap, not orphaned by a crash
+	// (a crash orphan was running when the process died, making it newer than
+	// the oldest of the retained rows). Re-adopting evicted receipts would
+	// churn against the ring on every startup. An empty ledger disables the
+	// horizon so a wiped runs.json can be rebuilt from receipts.
+	const rows = ledger.list();
+	const oldestRetained = rows.length > 0 ? (rows[rows.length - 1]?.startedAt ?? null) : null;
+	let files: string[];
+	try {
+		files = readdirSync(dir).filter((name) => name.endsWith(".json"));
+	} catch {
+		return summary;
+	}
+	for (const name of files) {
+		const path = join(dir, name);
+		let receipt: RunReceipt;
+		try {
+			receipt = JSON.parse(readFileSync(path, "utf8")) as RunReceipt;
+		} catch {
+			summary.corrupt += quarantine(path) ? 1 : 0;
+			continue;
+		}
+		if (typeof receipt?.runId !== "string" || receipt.runId.length === 0) {
+			summary.corrupt += quarantine(path) ? 1 : 0;
+			continue;
+		}
+		if (ledger.get(receipt.runId) !== null) continue;
+		if (oldestRetained !== null && typeof receipt.startedAt === "string" && receipt.startedAt < oldestRetained) {
+			continue;
+		}
+		if (!isReceiptIntegrity(receipt.integrity)) {
+			summary.corrupt += quarantine(path) ? 1 : 0;
+			continue;
+		}
+		if (receipt.reproducibility?.cwd === undefined) {
+			// Cannot reconstruct the sealed ledger row without cwd; leave the
+			// artifact in place rather than quarantine something unverifiable.
+			summary.skipped += 1;
+			continue;
+		}
+		const envelope = verifyOrphan(receipt, path);
+		if (envelope === null) {
+			summary.corrupt += quarantine(path) ? 1 : 0;
+			continue;
+		}
+		if (ledger.adopt(envelope)) summary.recovered += 1;
+	}
+	return summary;
+}

package/src/domains/dispatch/outcome.ts

@@ -0,0 +1,109 @@
+/**
+ * Single authority for mapping run-termination evidence to a RunOutcome.
+ *
+ * Every finalization path in the dispatch extension (native worker exit, ACP
+ * delegation completion, watchdog kill, operator abort) builds a
+ * RunTerminationEvidence record and calls resolveRunOutcome. No call site
+ * assigns an outcome literal directly; retry policy, ledger status, and audit
+ * records all derive from the resolved outcome.
+ */
+
+import { WORKER_EXIT_PERMISSION_REQUIRED } from "../../worker/spec-contract.js";
+import type { RunOutcome, RunOutcomeCode, RunStatus } from "./types.js";
+
+export interface RunTerminationEvidence {
+	/** Process exit code; null when a native worker never reached a live session. */
+	exitCode: number | null;
+	/** Operator abort (SIGINT, /abort, batch cancel, drain). */
+	abortedByOperator: boolean;
+	/**
+	 * Cause detail when the abort was not an operator cancel (e.g. a dispatch
+	 * `timeout_ms` kill). Names the timeout on the receipt so it stays
+	 * distinguishable from an operator abort; the outcome remains `canceled`.
+	 */
+	abortDetail?: string | null;
+	/** The reconciler declared the worker dead (heartbeat) or stalled (ACP inactivity) and killed it. */
+	stallKilled: boolean;
+	/** Turn or run timeout was exceeded (ACP turn request timeout). */
+	timedOut: boolean;
+	/** Worker exited because workers.onPermission="fail" and a permission was required. */
+	permissionFailure: boolean;
+	/** Admission/budget/scope/cooldown rejection reason; non-null means policy denial. */
+	policyDenied: string | null;
+	/** Coordinator quality/verification gate rejected an otherwise successful completion. */
+	qualityGateFailure?: boolean;
+	/** ACP stopReason when the peer reported one. */
+	stopReason: string | null;
+}
+
+export interface ResolvedOutcome {
+	outcome: RunOutcome;
+	detail: string | null;
+}
+
+export function resolveRunOutcome(evidence: RunTerminationEvidence): ResolvedOutcome {
+	if (evidence.policyDenied !== null) {
+		return { outcome: "denied_by_policy", detail: evidence.policyDenied };
+	}
+	// A reconciler kill ranks above cancellation evidence: terminating a
+	// stalled peer goes through the cancel/close path, which must not launder
+	// a stall into an operator abort.
+	if (evidence.stallKilled) {
+		return { outcome: "stalled", detail: "no worker activity within the stall window" };
+	}
+	if (evidence.abortedByOperator || evidence.stopReason === "cancelled") {
+		const detail = evidence.abortedByOperator ? (evidence.abortDetail ?? "operator abort") : "peer cancelled";
+		return { outcome: "canceled", detail };
+	}
+	if (evidence.timedOut) {
+		return { outcome: "timed_out", detail: "turn timeout exceeded" };
+	}
+	if (evidence.exitCode === null) {
+		return { outcome: "spawn_failed", detail: "process never reached a live session" };
+	}
+	if (evidence.permissionFailure || evidence.exitCode === WORKER_EXIT_PERMISSION_REQUIRED) {
+		return { outcome: "failed", detail: "permission_required" };
+	}
+	if (evidence.exitCode === 0) {
+		return { outcome: "succeeded", detail: null };
+	}
+	const stopSuffix = evidence.stopReason !== null ? ` (stopReason=${evidence.stopReason})` : "";
+	return { outcome: "failed", detail: `exit code ${evidence.exitCode}${stopSuffix}` };
+}
+
+/**
+ * Backward-compatible ledger status for a resolved outcome. RunStatus predates
+ * the taxonomy and is what pre-sprint receipts seal over, so the mapping is
+ * fixed: it must keep producing the statuses the old finalizer produced.
+ */
+export function runStatusForOutcome(outcome: RunOutcome): RunStatus {
+	switch (outcome) {
+		case "succeeded":
+			return "completed";
+		case "canceled":
+			return "interrupted";
+		case "stalled":
+			return "dead";
+		default:
+			return "failed";
+	}
+}
+
+/**
+ * Whether a declared result contract was ever due for this attempt.
+ *
+ * A postcondition is only an applicable correctness check once the run reached
+ * the point of producing a terminal result. Two termination shapes qualify:
+ * the worker finished its own execution normally, or the worker itself
+ * validated a terminal result and exhausted its bounded repair rounds.
+ *
+ * Everything else left the contract unevaluated: an operator abort, a crash
+ * before the first token, a target that could not load the model, a stall
+ * kill, and an engine loop-guard abort. Validating a `null` output in those
+ * cases manufactures a `fail` out of infrastructure noise, which then enters
+ * route history as correctness evidence about a model that never ran. Measured
+ * against real history, that inflated the Scout failure count by 8 of 16.
+ */
+export function resultContractWasDue(outcome: RunOutcome, outcomeCode: RunOutcomeCode | null): boolean {
+	return outcome === "succeeded" || outcomeCode === "result_contract_exhausted";
+}

package/src/domains/dispatch/phase-timing.ts

@@ -0,0 +1,47 @@
+import { rawDurationMs } from "../../core/timers.js";
+import type { RunEnvelope, RunPhaseDurations, RunPhaseMarks } from "./types.js";
+
+function duration(start: string | undefined, end: string | null | undefined): number | null {
+	if (start === undefined || end == null) return null;
+	const startMs = Date.parse(start);
+	const endMs = Date.parse(end);
+	// The clamp is the presentation contract (no negative phase renders), but
+	// the subtraction goes through rawDurationMs so a backwards mark is counted
+	// instead of silently reading as an unusually fast phase.
+	return Number.isFinite(startMs) && Number.isFinite(endMs) ? Math.max(0, rawDurationMs(startMs, endMs)) : null;
+}
+
+/** Derive non-overlapping routing-system phases plus execution and total wall time. */
+export function deriveRunPhaseDurations(
+	marks: RunPhaseMarks | undefined,
+	executionStartedAt: string,
+	endedAt: string | null,
+): RunPhaseDurations {
+	const end = marks?.endedAt ?? endedAt;
+	return {
+		requestToDecisionMs: duration(marks?.requestedAt, marks?.decisionCompletedAt),
+		decisionMs: duration(marks?.decisionStartedAt, marks?.decisionCompletedAt),
+		admissionWaitMs: duration(marks?.decisionCompletedAt, marks?.queuedAt),
+		queueWaitMs: duration(marks?.queuedAt, marks?.admittedAt),
+		spawnSetupMs: duration(marks?.admittedAt, marks?.workerSpawnedAt),
+		timeToFirstModelTokenMs: duration(marks?.requestedAt, marks?.firstModelTokenAt),
+		timeToFirstToolMs: duration(marks?.requestedAt, marks?.firstToolAt),
+		executionMs: duration(executionStartedAt, end),
+		totalEndToEndMs: duration(marks?.requestedAt, end),
+	};
+}
+
+export function deriveEnvelopePhaseDurations(envelope: RunEnvelope, endedAt = envelope.endedAt): RunPhaseDurations {
+	return deriveRunPhaseDurations(envelope.timing, envelope.startedAt, endedAt);
+}
+
+/** Timing is observability metadata: a failed timing write must never fail run finalization. */
+export function recordRunTimingBestEffort(update: () => void, onError?: (error: unknown) => void): boolean {
+	try {
+		update();
+		return true;
+	} catch (error) {
+		onError?.(error);
+		return false;
+	}
+}

package/src/domains/dispatch/placement.ts

@@ -0,0 +1,202 @@
+/**
+ * Deterministic fleet placement. Resolution order:
+ *
+ *   1. explicit dispatch `node` param
+ *   2. fleet profile / agent-binding node pin
+ *   3. least-loaded eligible remote node (fewest active workers, then
+ *      declaration order)
+ *   4. the implicit local node
+ *
+ * Eligible means: registry state online, a passing durable doctor preflight
+ * for this project root, and free per-node capacity. An explicit pin on an
+ * ineligible node is an admission failure with the reason spelled out; the
+ * least-loaded path silently skips ineligible nodes and falls back to local.
+ * No scored or learned placement authority exists here by design.
+ *
+ * Capacity here is advisory spreading, not authority. Durable assignment leases
+ * decide admission under the state lock, so this pass only avoids sending a
+ * request to a node whose slots are already taken while a sibling node is idle.
+ * A pinned node that is momentarily full is still placed, because the bounded
+ * admission queue is the right place to wait for its slot.
+ */
+
+import type { ClioSettings } from "../../core/config.js";
+import type { FleetNodeSettings } from "../../core/defaults.js";
+import type { FleetRegistry } from "../scheduling/cluster.js";
+import type { DispatchRequest } from "./contract.js";
+import type { DispatchNodePlacement } from "./extension.js";
+import { fleetPreflightVerdict, readFleetPreflightRecords } from "./fleet-preflight.js";
+import { createSshWorkerTransport, LOCAL_NODE_ID, localNodeIdentity, type WorkerTransport } from "./transport.js";
+import type { RunNodeIdentity, RunNodeReroute } from "./types.js";
+
+export interface FleetPlacementDeps {
+	getSettings: () => Readonly<ClioSettings> | undefined;
+	fleet: FleetRegistry | undefined;
+	/** Transport seam; contract tests substitute a fake ssh channel. */
+	transportForNode?: (node: FleetNodeSettings) => WorkerTransport;
+	/** Preflight seam; defaults to the durable doctor store. */
+	preflightVerdict?: typeof fleetPreflightVerdict;
+}
+
+/** Side-effect-free placement used to build an immutable approval plan. */
+export interface FleetPlacementPreview {
+	node: RunNodeIdentity;
+}
+
+function admissionError(reason: string): Error {
+	return new Error(`dispatch: admission denied: ${reason}`);
+}
+
+/**
+ * Fill the placement target into reroute hops the retry path left open
+ * (fromNode recorded at requeue time, toNode known only at placement).
+ */
+function completedReroutes(
+	reroutes: ReadonlyArray<RunNodeReroute> | undefined,
+	toNode: string,
+): RunNodeReroute[] | undefined {
+	if (!reroutes || reroutes.length === 0) return undefined;
+	return reroutes.map((hop) => (hop.toNode.length === 0 ? { ...hop, toNode } : hop));
+}
+
+function requestedNodeId(req: DispatchRequest, settings: Readonly<ClioSettings> | undefined): string | null {
+	if (req.node !== undefined && req.node.trim().length > 0) return req.node.trim();
+	const workers = settings?.workers;
+	if (!workers) return null;
+	const profileName = req.workerProfile ?? workers.agentBindings?.[req.agentId];
+	if (!profileName) return null;
+	const pin = workers.profiles?.[profileName]?.node;
+	return pin !== undefined && pin.trim().length > 0 ? pin.trim() : null;
+}
+
+export function createFleetPlacementResolver(
+	deps: FleetPlacementDeps,
+): (req: DispatchRequest) => DispatchNodePlacement | null {
+	const transportForNode = deps.transportForNode ?? ((node: FleetNodeSettings) => createSshWorkerTransport(node));
+	const verdictFor = deps.preflightVerdict ?? fleetPreflightVerdict;
+
+	return (req: DispatchRequest): DispatchNodePlacement | null => {
+		const settings = deps.getSettings();
+		const nodes = settings?.fleet?.nodes ?? [];
+		// Failover retries record each failed node as a reroute `fromNode`. Those
+		// nodes are excluded from re-selection so a node-scoped failure moves to a
+		// different eligible node instead of landing back on the failed one.
+		const excludedNodeIds = new Set((req.reroutes ?? []).map((hop) => hop.fromNode).filter((id) => id.length > 0));
+		// A profile/agent-binding pin that names an excluded node is overridden by
+		// the exclusion (an explicit req.node pin is dropped by the retry path
+		// before this runs, so any surviving request is a soft pin).
+		let requested = requestedNodeId(req, settings);
+		if (requested !== null && excludedNodeIds.has(requested)) requested = null;
+		// No fleet configured and nothing requested: stay on the pre-fleet
+		// local path with no node identity recorded at all.
+		if (nodes.length === 0 && requested === null && !req.reroutes?.length) return null;
+		const fleet = deps.fleet;
+
+		const localPlacement = (): DispatchNodePlacement => {
+			const reroutes = completedReroutes(req.reroutes, LOCAL_NODE_ID);
+			return { node: localNodeIdentity(), ...(reroutes !== undefined ? { reroutes } : {}) };
+		};
+
+		const sshPlacement = (node: FleetNodeSettings): DispatchNodePlacement => {
+			if (fleet === undefined) throw admissionError(`fleet registry unavailable; cannot place on node '${node.id}'`);
+			const transport = transportForNode(node);
+			const reroutes = completedReroutes(req.reroutes, node.id);
+			return {
+				node: transport.node,
+				spawn: (spec, opts) => transport.spawn(spec, opts),
+				...(reroutes !== undefined ? { reroutes } : {}),
+			};
+		};
+
+		const projectRoot = req.cwd ?? process.cwd();
+
+		if (requested !== null) {
+			if (requested === LOCAL_NODE_ID) return localPlacement();
+			const node = nodes.find((entry) => entry.id === requested);
+			if (!node) throw admissionError(`unknown fleet node '${requested}'`);
+			if (fleet === undefined) throw admissionError(`fleet registry unavailable; cannot place on node '${requested}'`);
+			const snapshot = fleet.get(node.id);
+			if (snapshot && snapshot.state !== "online") {
+				throw admissionError(
+					`fleet node '${node.id}' is ${snapshot.state}${snapshot.stateReason ? ` (${snapshot.stateReason})` : ""}`,
+				);
+			}
+			const preflight = verdictFor(node, projectRoot);
+			if (!preflight.ok) throw admissionError(preflight.reason ?? `node '${node.id}' is not preflighted`);
+			return sshPlacement(node);
+		}
+
+		// Least-loaded eligible remote node; local is the fallback unless it too
+		// has been excluded by a prior failure.
+		if (fleet !== undefined && nodes.length > 0) {
+			const preflightRecords = readFleetPreflightRecords();
+			const eligible = nodes
+				.map((node, order) => ({ node, order, snapshot: fleet.get(node.id) }))
+				.filter((entry) => !excludedNodeIds.has(entry.node.id))
+				.filter((entry) => entry.snapshot !== null && entry.snapshot.state === "online")
+				.filter((entry) => (entry.snapshot?.activeWorkers ?? 0) < entry.node.maxWorkers)
+				.filter((entry) => verdictFor(entry.node, projectRoot, preflightRecords).ok)
+				.sort((a, b) => (a.snapshot?.activeWorkers ?? 0) - (b.snapshot?.activeWorkers ?? 0) || a.order - b.order);
+			const selected = eligible[0];
+			if (selected) return sshPlacement(selected.node);
+		}
+		// A node exclusion that also excludes local has no eligible node left:
+		// fail closed rather than silently re-running on the excluded local node.
+		if (excludedNodeIds.has(LOCAL_NODE_ID)) {
+			throw admissionError(`no eligible fleet node remains after excluding ${[...excludedNodeIds].join(", ")}`);
+		}
+		return localPlacement();
+	};
+}
+
+/**
+ * Resolve the node that the normal placement policy would choose without
+ * acquiring capacity. The approved request is subsequently pinned to this
+ * node, so a capacity/state change fails launch instead of silently drifting
+ * to a different node after approval.
+ */
+export function createFleetPlacementPreviewResolver(
+	deps: FleetPlacementDeps,
+): (req: DispatchRequest) => FleetPlacementPreview {
+	const verdictFor = deps.preflightVerdict ?? fleetPreflightVerdict;
+	return (req: DispatchRequest): FleetPlacementPreview => {
+		const settings = deps.getSettings();
+		const nodes = settings?.fleet?.nodes ?? [];
+		const requested = requestedNodeId(req, settings);
+		const fleet = deps.fleet;
+		const local = (): FleetPlacementPreview => ({ node: localNodeIdentity() });
+		const remote = (node: FleetNodeSettings): FleetPlacementPreview => ({
+			node: { id: node.id, kind: "ssh", host: node.host },
+		});
+		const projectRoot = req.cwd ?? process.cwd();
+
+		if (requested !== null) {
+			if (requested === LOCAL_NODE_ID) return local();
+			const node = nodes.find((entry) => entry.id === requested);
+			if (!node) throw admissionError(`unknown fleet node '${requested}'`);
+			if (fleet === undefined) throw admissionError(`fleet registry unavailable; cannot place on node '${requested}'`);
+			const snapshot = fleet.get(node.id);
+			if (snapshot && snapshot.state !== "online") {
+				throw admissionError(
+					`fleet node '${node.id}' is ${snapshot.state}${snapshot.stateReason ? ` (${snapshot.stateReason})` : ""}`,
+				);
+			}
+			const preflight = verdictFor(node, projectRoot);
+			if (!preflight.ok) throw admissionError(preflight.reason ?? `node '${node.id}' is not preflighted`);
+			return remote(node);
+		}
+
+		if (fleet !== undefined && nodes.length > 0) {
+			const preflightRecords = readFleetPreflightRecords();
+			const eligible = nodes
+				.map((node, order) => ({ node, order, snapshot: fleet.get(node.id) }))
+				.filter((entry) => entry.snapshot !== null && entry.snapshot.state === "online")
+				.filter((entry) => (entry.snapshot?.activeWorkers ?? 0) < entry.node.maxWorkers)
+				.filter((entry) => verdictFor(entry.node, projectRoot, preflightRecords).ok)
+				.sort((a, b) => (a.snapshot?.activeWorkers ?? 0) - (b.snapshot?.activeWorkers ?? 0) || a.order - b.order);
+			const selected = eligible[0]?.node;
+			if (selected !== undefined) return remote(selected);
+		}
+		return local();
+	};
+}