@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/dispatch/route-readiness.ts

@@ -0,0 +1,120 @@
+/**
+ * Whether a route has earned the right to be selected actively.
+ *
+ * Shadow mode may rank a cold candidate: nothing executes on its opinion. Active
+ * mode does execute on it, so every prerequisite in the plan of record must hold
+ * for the exact route and execution role before the resolver may pick it. This
+ * module reports each unmet item by name rather than returning a bare boolean,
+ * because "not ready" is an operator-facing diagnosis, not a rejection.
+ *
+ * Pure by construction: the caller owns history reads, fact freshness probes,
+ * and the clock. Equal inputs produce an equal report, so a readiness refusal is
+ * reproducible from a sealed decision.
+ */
+
+import { ROUTE_POSTURES, type RouteEstimate, type RoutingPosture } from "./route-policy.js";
+
+/**
+ * The minimum labeled count in the plan of record. Six passes are exactly what
+ * clears a 0.6 quality floor under a 95% Wilson lower bound; a higher posture
+ * floor naturally demands more evidence than this, which the floor check below
+ * enforces on its own.
+ */
+export const MINIMUM_ACTIVE_QUALITY_LABELS = 6;
+
+export type ReadinessGap =
+	| "hard-constraint-validity-below-one"
+	| "integrity-failures-in-window"
+	| "insufficient-quality-labels"
+	| "quality-lower-bound-below-posture-floor"
+	| "quality-lower-bound-below-requested-minimum"
+	| "reliability-below-posture-floor"
+	| "cost-upper-bound-unknown"
+	| "route-facts-stale"
+	| "decision-latency-above-budget";
+
+/** The p95 shadow-decision budget at the configured universe bound. */
+export const DECISION_LATENCY_BUDGET_MS = 10;
+
+export interface RouteReadinessInput {
+	estimate: RouteEstimate;
+	posture: RoutingPosture;
+	/**
+	 * Share of retained decisions in which this route's hard constraints were
+	 * evaluated consistently. Anything below 1.0 means the filter itself is not
+	 * yet trustworthy, so no amount of quality evidence compensates.
+	 */
+	hardConstraintValidity: number;
+	/** Receipt or source integrity failures for this route in the retained window. */
+	integrityFailures: number;
+	/** Conservative cost ceiling, or null when the route has never completed work. */
+	costUpperBoundUsd: number | null;
+	/** Node, endpoint, resource, capacity, and settings facts are all current. */
+	factsFresh: boolean;
+	/** Measured p95 resolver duration at the configured universe bound. */
+	decisionP95Ms: number;
+	/** The request's own `minimumQuality` bound, when it named one. */
+	requestedMinimumQuality: number | null;
+}
+
+export interface RouteReadinessReport {
+	ready: boolean;
+	/** Every unmet prerequisite, in a stable order. Empty exactly when ready. */
+	gaps: ReadinessGap[];
+	/** How many more labeled outcomes this route needs. Zero once the floor is met. */
+	labelsNeeded: number;
+}
+
+export function evaluateRouteReadiness(input: RouteReadinessInput): RouteReadinessReport {
+	const gaps: ReadinessGap[] = [];
+	const floors = ROUTE_POSTURES[input.posture].floors;
+	const estimate = input.estimate;
+
+	if (input.hardConstraintValidity < 1) gaps.push("hard-constraint-validity-below-one");
+	if (input.integrityFailures > 0) gaps.push("integrity-failures-in-window");
+	if (estimate.qualityLabeledCount < MINIMUM_ACTIVE_QUALITY_LABELS) gaps.push("insufficient-quality-labels");
+	if (estimate.qualityLowerBound < floors.qualityLowerBound) gaps.push("quality-lower-bound-below-posture-floor");
+	if (input.requestedMinimumQuality !== null && estimate.qualityLowerBound < input.requestedMinimumQuality) {
+		gaps.push("quality-lower-bound-below-requested-minimum");
+	}
+	if (estimate.reliability < floors.reliability) gaps.push("reliability-below-posture-floor");
+	if (input.costUpperBoundUsd === null || !Number.isFinite(input.costUpperBoundUsd)) {
+		gaps.push("cost-upper-bound-unknown");
+	}
+	if (!input.factsFresh) gaps.push("route-facts-stale");
+	if (input.decisionP95Ms > DECISION_LATENCY_BUDGET_MS) gaps.push("decision-latency-above-budget");
+
+	return {
+		ready: gaps.length === 0,
+		gaps,
+		labelsNeeded: Math.max(0, MINIMUM_ACTIVE_QUALITY_LABELS - estimate.qualityLabeledCount),
+	};
+}
+
+/**
+ * Human-readable one-liners for a refusal message. The wording names the
+ * missing evidence, so an operator who sees an active refusal can tell whether
+ * to wait for measurements or to fix a stale fact.
+ */
+export function describeReadinessGap(gap: ReadinessGap): string {
+	switch (gap) {
+		case "hard-constraint-validity-below-one":
+			return "hard-constraint evaluation was not consistently valid over the retained window";
+		case "integrity-failures-in-window":
+			return "the retained window contains receipt or source integrity failures";
+		case "insufficient-quality-labels":
+			return `fewer than ${MINIMUM_ACTIVE_QUALITY_LABELS} quality-labeled outcomes for this route and role`;
+		case "quality-lower-bound-below-posture-floor":
+			return "the conservative quality lower bound is below the posture floor";
+		case "quality-lower-bound-below-requested-minimum":
+			return "the conservative quality lower bound is below the request's minimumQuality";
+		case "reliability-below-posture-floor":
+			return "route-attributable reliability is below the posture floor";
+		case "cost-upper-bound-unknown":
+			return "the route has no conservative cost upper bound";
+		case "route-facts-stale":
+			return "node, endpoint, resource, capacity, or settings facts are stale";
+		case "decision-latency-above-budget":
+			return `shadow decision p95 exceeds ${DECISION_LATENCY_BUDGET_MS} ms at the configured universe bound`;
+	}
+}

package/src/domains/dispatch/routing-intent.ts

@@ -0,0 +1,287 @@
+import type { RouteCandidate, RouteDecisionV1 } from "./route-decision.js";
+import type { RoutingPosture } from "./route-policy.js";
+
+export type RoutingLocality = "local-only" | "prefer-local" | "any";
+export type RoutingFailover = "none" | "approved";
+
+/** Model-facing routing policy. Every numeric value is a hard bound, never a score. */
+export interface RoutingIntent {
+	posture: RoutingPosture;
+	maxCostUsd: number | null;
+	deadlineMs: number | null;
+	minimumQuality: number | null;
+	requiredCapabilities: ReadonlyArray<string>;
+	locality: RoutingLocality;
+	failover: RoutingFailover;
+}
+
+export interface RoutingPins {
+	target?: string;
+	model?: string;
+	node?: string;
+}
+
+export type RoutingIntentResult = { ok: true; intent: RoutingIntent } | { ok: false; errors: ReadonlyArray<string> };
+
+const KEYS = new Set([
+	"posture",
+	"maxCostUsd",
+	"deadlineMs",
+	"minimumQuality",
+	"requiredCapabilities",
+	"locality",
+	"failover",
+]);
+const POSTURES = new Set<RoutingPosture>(["manual", "quality", "balanced", "latency", "economy"]);
+const LOCALITIES = new Set<RoutingLocality>(["local-only", "prefer-local", "any"]);
+const FAILOVERS = new Set<RoutingFailover>(["none", "approved"]);
+
+function record(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function isRoutingIntent(value: unknown): value is RoutingIntent {
+	if (!record(value) || Object.keys(value).some((key) => !KEYS.has(key))) return false;
+	return (
+		typeof value.posture === "string" &&
+		POSTURES.has(value.posture as RoutingPosture) &&
+		(value.maxCostUsd === null ||
+			(typeof value.maxCostUsd === "number" && Number.isFinite(value.maxCostUsd) && value.maxCostUsd > 0)) &&
+		(value.deadlineMs === null ||
+			(typeof value.deadlineMs === "number" && Number.isInteger(value.deadlineMs) && value.deadlineMs > 0)) &&
+		(value.minimumQuality === null ||
+			(typeof value.minimumQuality === "number" && value.minimumQuality >= 0 && value.minimumQuality <= 1)) &&
+		Array.isArray(value.requiredCapabilities) &&
+		value.requiredCapabilities.every((entry) => typeof entry === "string" && entry.length > 0) &&
+		typeof value.locality === "string" &&
+		LOCALITIES.has(value.locality as RoutingLocality) &&
+		typeof value.failover === "string" &&
+		FAILOVERS.has(value.failover as RoutingFailover)
+	);
+}
+
+/** Strictly parse routing intent and apply the shadow-only default. */
+export function parseRoutingIntent(value: unknown, pins: RoutingPins = {}): RoutingIntentResult {
+	const errors: string[] = [];
+	if (value !== undefined && !record(value)) return { ok: false, errors: ["routing must be an object"] };
+	const input = value === undefined ? {} : value;
+	for (const key of Object.keys(input)) if (!KEYS.has(key)) errors.push(`routing unknown key: ${key}`);
+	const pinned = pins.target !== undefined || pins.model !== undefined || pins.node !== undefined;
+	const posture = input.posture ?? (pinned ? "manual" : "balanced");
+	if (typeof posture !== "string" || !POSTURES.has(posture as RoutingPosture)) {
+		errors.push("routing.posture must be one of: manual|quality|balanced|latency|economy");
+	}
+	if (pinned && posture !== "manual") errors.push("exact target, model, or node pins require routing.posture manual");
+	const positive = (key: "maxCostUsd" | "deadlineMs"): number | null => {
+		const candidate = input[key];
+		if (candidate === undefined) return null;
+		if (typeof candidate !== "number" || !Number.isFinite(candidate) || candidate <= 0) {
+			errors.push(`routing.${key} must be a finite number greater than zero`);
+			return null;
+		}
+		if (key === "deadlineMs" && !Number.isInteger(candidate)) errors.push("routing.deadlineMs must be an integer");
+		return candidate;
+	};
+	const maxCostUsd = positive("maxCostUsd");
+	const deadlineMs = positive("deadlineMs");
+	let minimumQuality: number | null = null;
+	if (input.minimumQuality !== undefined) {
+		if (
+			typeof input.minimumQuality !== "number" ||
+			!Number.isFinite(input.minimumQuality) ||
+			input.minimumQuality < 0 ||
+			input.minimumQuality > 1
+		)
+			errors.push("routing.minimumQuality must be between zero and one");
+		else minimumQuality = input.minimumQuality;
+	}
+	const requiredCapabilities = input.requiredCapabilities ?? [];
+	if (
+		!Array.isArray(requiredCapabilities) ||
+		requiredCapabilities.some((entry) => typeof entry !== "string" || entry.trim().length === 0) ||
+		new Set(requiredCapabilities).size !== requiredCapabilities.length
+	)
+		errors.push("routing.requiredCapabilities must be an array of unique non-empty strings");
+	const locality = input.locality ?? "any";
+	if (typeof locality !== "string" || !LOCALITIES.has(locality as RoutingLocality)) {
+		errors.push("routing.locality must be one of: local-only|prefer-local|any");
+	}
+	const failover = input.failover ?? "none";
+	if (typeof failover !== "string" || !FAILOVERS.has(failover as RoutingFailover)) {
+		errors.push("routing.failover must be one of: none|approved");
+	}
+	if (pinned && failover !== "none") errors.push("manual pins imply routing.failover none");
+	if (errors.length > 0) return { ok: false, errors };
+	return {
+		ok: true,
+		intent: {
+			posture: posture as RoutingPosture,
+			maxCostUsd,
+			deadlineMs,
+			minimumQuality,
+			requiredCapabilities: [...(requiredCapabilities as string[])],
+			locality: locality as RoutingLocality,
+			failover: failover as RoutingFailover,
+		},
+	};
+}
+
+export function defaultRoutingIntent(pins: RoutingPins): RoutingIntent {
+	const parsed = parseRoutingIntent(undefined, pins);
+	if (!parsed.ok) throw new Error(parsed.errors.join("; "));
+	return parsed.intent;
+}
+
+/** Hard intent verdict. `prefer-local` deliberately does not reject. */
+export function routingIntentRejection(input: {
+	intent: RoutingIntent;
+	candidate: RouteCandidate;
+	qualityLowerBound: number;
+	costUpperBoundUsd: number;
+	endToEndUpperBoundMs: number;
+	capabilities: ReadonlyArray<string>;
+}): string | null {
+	const { intent } = input;
+	if (intent.minimumQuality !== null && input.qualityLowerBound < intent.minimumQuality) return "minimum-quality";
+	if (intent.maxCostUsd !== null && input.costUpperBoundUsd > intent.maxCostUsd) return "max-cost";
+	if (intent.deadlineMs !== null && input.endToEndUpperBoundMs > intent.deadlineMs) return "deadline";
+	if (intent.locality === "local-only" && input.candidate.nodeId !== "local") return "local-only";
+	if (intent.requiredCapabilities.some((capability) => !input.capabilities.includes(capability))) {
+		return "required-capabilities";
+	}
+	return null;
+}
+
+/** Soft locality order applied only after both candidates clear every hard filter and otherwise tie. */
+export function preferLocalTie(
+	left: RouteCandidate,
+	right: RouteCandidate,
+	locality: RoutingLocality,
+): RouteCandidate | null {
+	if (locality !== "prefer-local") return null;
+	const leftLocal = left.nodeId === "local";
+	const rightLocal = right.nodeId === "local";
+	if (leftLocal === rightLocal) return null;
+	return leftLocal ? left : right;
+}
+
+export const ROUTE_EXPLANATION_MAX_BYTES = 4_096;
+
+export interface RouteExplanation {
+	mode: RouteDecisionV1["mode"];
+	executedRoute: RouteCandidate;
+	shadowRecommendation: RouteCandidate | null;
+	hardExclusions: ReadonlyArray<string>;
+	approvedFallbacks: ReadonlyArray<RouteCandidate>;
+	costUpperBoundUsd: number | null;
+	deadlineMs: number | null;
+	confidence: number;
+	activeEligible: boolean;
+	reasonCodes: ReadonlyArray<string>;
+	decisionHash: string;
+	agentSelection: {
+		request: RouteDecisionV1["agentSelection"]["request"];
+		activation: RouteDecisionV1["agentSelection"]["activation"];
+		baselineAgentId: string;
+		recommendedAgentId: string;
+		excluded: ReadonlyArray<{ agentId: string; reasons: ReadonlyArray<string> }>;
+		authorityTransition: RouteDecisionV1["agentSelection"]["authorityTransition"];
+	};
+}
+
+function safeIdentity(candidate: RouteCandidate): RouteCandidate {
+	const safe = (value: string): string => {
+		const redacted = /(?:https?:\/\/|api[_-]?key|token|secret|password)/i.test(value) ? "[redacted]" : value;
+		return redacted.length <= 128 ? redacted : `${redacted.slice(0, 127)}…`;
+	};
+	return {
+		...candidate,
+		agentId: safe(candidate.agentId),
+		specFingerprint: safe(candidate.specFingerprint),
+		targetId: safe(candidate.targetId),
+		modelId: safe(candidate.modelId),
+		runtimeId: safe(candidate.runtimeId),
+		nodeId: safe(candidate.nodeId),
+		...(candidate.thinkingLevel !== undefined ? { thinkingLevel: safe(candidate.thinkingLevel) } : {}),
+		toolSignature: safe(candidate.toolSignature),
+		promptCompositionHash: safe(candidate.promptCompositionHash),
+		endpointIdentityHash: safe(candidate.endpointIdentityHash),
+		settingsFingerprint: safe(candidate.settingsFingerprint),
+	};
+}
+
+/** Compact receipt-derived explanation; no task, prompt, URL, or credential field is accepted. */
+export function explainRouteDecision(decision: RouteDecisionV1, intent: RoutingIntent): RouteExplanation {
+	const exclusions = [
+		...new Set(decision.candidateEvaluations.flatMap((entry) => (entry.rejection ? [entry.rejection] : []))),
+	];
+	const explanation: RouteExplanation = {
+		mode: decision.mode,
+		executedRoute: safeIdentity(decision.executedRoute),
+		shadowRecommendation: decision.mode === "shadow" ? safeIdentity(decision.selected) : null,
+		hardExclusions: exclusions.slice(0, 16),
+		approvedFallbacks: decision.approvedFallbacks.slice(0, 3).map(safeIdentity),
+		costUpperBoundUsd: intent.maxCostUsd,
+		deadlineMs: intent.deadlineMs,
+		confidence: decision.confidence,
+		activeEligible: decision.candidateEvaluations.some(
+			(entry) => entry.rejection === null && entry.activeReadiness.ready,
+		),
+		reasonCodes: decision.reasonCodes.slice(0, 16),
+		decisionHash: decision.decisionHash,
+		agentSelection: {
+			request: decision.agentSelection.request,
+			activation: decision.agentSelection.activation,
+			baselineAgentId: safeIdentity({ ...decision.executedRoute, agentId: decision.agentSelection.baselineAgentId })
+				.agentId,
+			recommendedAgentId: safeIdentity({ ...decision.executedRoute, agentId: decision.agentSelection.recommendedAgentId })
+				.agentId,
+			excluded: decision.agentSelection.evaluations
+				.filter((entry) => entry.rejections.length > 0)
+				.slice(0, 16)
+				.map((entry) => ({
+					agentId: safeIdentity({ ...decision.executedRoute, agentId: entry.agentId }).agentId,
+					reasons: entry.rejections.slice(0, 8),
+				})),
+			authorityTransition:
+				decision.agentSelection.authorityTransition === null
+					? null
+					: {
+							...decision.agentSelection.authorityTransition,
+							from: safeIdentity({
+								...decision.executedRoute,
+								agentId: decision.agentSelection.authorityTransition.from,
+							}).agentId,
+							to: safeIdentity({
+								...decision.executedRoute,
+								agentId: decision.agentSelection.authorityTransition.to,
+							}).agentId,
+						},
+		},
+	};
+	if (Buffer.byteLength(JSON.stringify(explanation), "utf8") <= ROUTE_EXPLANATION_MAX_BYTES) return explanation;
+	const compact: RouteExplanation = {
+		...explanation,
+		approvedFallbacks: explanation.approvedFallbacks.slice(0, 1),
+		hardExclusions: explanation.hardExclusions.slice(0, 4),
+		reasonCodes: explanation.reasonCodes.slice(0, 4),
+		agentSelection: {
+			...explanation.agentSelection,
+			excluded: explanation.agentSelection.excluded
+				.slice(0, 4)
+				.map((entry) => ({ ...entry, reasons: entry.reasons.slice(0, 2) })),
+		},
+	};
+	if (Buffer.byteLength(JSON.stringify(compact), "utf8") <= ROUTE_EXPLANATION_MAX_BYTES) return compact;
+	return {
+		...compact,
+		shadowRecommendation: null,
+		approvedFallbacks: [],
+		hardExclusions: compact.hardExclusions.slice(0, 2),
+		reasonCodes: compact.reasonCodes.slice(0, 2),
+		agentSelection: {
+			...compact.agentSelection,
+			excluded: [],
+		},
+	};
+}

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

@@ -0,0 +1,56 @@
+/**
+ * Host and HPC-scheduler identity detection for run receipts.
+ *
+ * Pure environment inspection, no I/O beyond os module lookups. Scheduler
+ * detection order is Slurm, then PBS, then LSF; first match wins. Outside any
+ * scheduler allocation `hpc` is null.
+ */
+
+import { hostname, userInfo } from "node:os";
+import type { RunIdentity } from "./types.js";
+
+function nonEmpty(value: string | undefined): string | null {
+	return value !== undefined && value.trim().length > 0 ? value.trim() : null;
+}
+
+export function detectRunIdentity(env: NodeJS.ProcessEnv = process.env): RunIdentity {
+	let user = "unknown";
+	try {
+		user = userInfo().username;
+	} catch {
+		user = nonEmpty(env.USER) ?? nonEmpty(env.LOGNAME) ?? "unknown";
+	}
+	const identity: RunIdentity = { host: hostname(), user, hpc: null };
+
+	const slurmJobId = nonEmpty(env.SLURM_JOB_ID);
+	if (slurmJobId !== null) {
+		identity.hpc = {
+			scheduler: "slurm",
+			jobId: slurmJobId,
+			jobName: nonEmpty(env.SLURM_JOB_NAME),
+			cluster: nonEmpty(env.SLURM_CLUSTER_NAME),
+		};
+		return identity;
+	}
+	const pbsJobId = nonEmpty(env.PBS_JOBID);
+	if (pbsJobId !== null) {
+		identity.hpc = {
+			scheduler: "pbs",
+			jobId: pbsJobId,
+			jobName: nonEmpty(env.PBS_JOBNAME),
+			cluster: nonEmpty(env.PBS_O_HOST),
+		};
+		return identity;
+	}
+	const lsfJobId = nonEmpty(env.LSB_JOBID);
+	if (lsfJobId !== null) {
+		identity.hpc = {
+			scheduler: "lsf",
+			jobId: lsfJobId,
+			jobName: nonEmpty(env.LSB_JOBNAME),
+			cluster: nonEmpty(env.LSF_CLUSTER_NAME),
+		};
+		return identity;
+	}
+	return identity;
+}

package/src/domains/dispatch/scout-transition.ts

@@ -0,0 +1,130 @@
+/** Pure coordinator-owned compilation of strict Scout phase-transition data. */
+
+import type { ScoutResult } from "../agents/result-contract.js";
+import type { AgentAutomationAuthority, AgentSpec } from "../agents/spec.js";
+import { compileExecutionPlan, type ExecutionPlan } from "./execution-plan.js";
+import { deriveExecutionRole } from "./execution-role.js";
+
+export type TrustedTransitionAuthorityBasis = "existing-plan" | "operator-plan-approval" | "full-auto-policy";
+
+export interface TrustedTransitionAuthority {
+	basis: TrustedTransitionAuthorityBasis;
+	approvedAuthorities: ReadonlyArray<AgentAutomationAuthority>;
+}
+
+export interface ScoutAgentBinding {
+	subtaskId: string;
+	spec: AgentSpec;
+}
+
+export type ScoutTransition =
+	| {
+			kind: "settled";
+			sourceReceiptDigest: string;
+			findings: ScoutResult["findings"];
+	  }
+	| {
+			kind: "approval-required";
+			sourceReceiptDigest: string;
+			plan: ExecutionPlan;
+			requiredAuthorities: ReadonlyArray<AgentAutomationAuthority>;
+	  }
+	| {
+			kind: "ready";
+			sourceReceiptDigest: string;
+			plan: ExecutionPlan;
+			authority: TrustedTransitionAuthority;
+	  };
+
+function scopeFor(authority: AgentAutomationAuthority): "readonly" | "workspace" {
+	return authority === "read-only" || authority === "verification" ? "readonly" : "workspace";
+}
+
+function assertReceiptDigest(value: string): void {
+	if (!/^[0-9a-f]{64}$/u.test(value)) throw new Error("scout transition: source receipt digest is invalid");
+}
+
+/**
+ * Scout fields are copied individually and never spread. Agent, role, scope,
+ * and grants come only from coordinator-owned bindings and authority state.
+ */
+export function compileScoutTransition(input: {
+	scout: ScoutResult;
+	sourceReceiptDigest: string;
+	rootTask: string;
+	bindings: ReadonlyArray<ScoutAgentBinding>;
+	authority: TrustedTransitionAuthority;
+	maxWorkers: number;
+}): ScoutTransition {
+	assertReceiptDigest(input.sourceReceiptDigest);
+	if (!input.scout.needsSplit) {
+		return {
+			kind: "settled",
+			sourceReceiptDigest: input.sourceReceiptDigest,
+			findings: input.scout.findings.map((finding) => ({ ...finding })),
+		};
+	}
+	const subtasks = input.scout.proposedSubtasks;
+	const byId = new Map(input.bindings.map((binding) => [binding.subtaskId, binding]));
+	if (byId.size !== input.bindings.length || byId.size !== subtasks.length) {
+		throw new Error("scout transition: coordinator bindings must match subtasks exactly");
+	}
+	for (const binding of input.bindings) {
+		if (!subtasks.some((subtask) => subtask.id === binding.subtaskId)) {
+			throw new Error(`scout transition: undeclared binding '${binding.subtaskId}'`);
+		}
+	}
+	const approved = new Set(input.authority.approvedAuthorities);
+	const missing = new Set<AgentAutomationAuthority>();
+	const steps = subtasks.map((subtask) => {
+		const binding = byId.get(subtask.id);
+		if (binding === undefined) throw new Error(`scout transition: subtask '${subtask.id}' has no agent binding`);
+		if (binding.spec.resultContract.kind !== subtask.expectedResultContract) {
+			throw new Error(`scout transition: subtask '${subtask.id}' result contract does not match its bound agent`);
+		}
+		if (binding.spec.capabilityClass !== subtask.requestedAuthority) {
+			throw new Error(`scout transition: subtask '${subtask.id}' authority does not match its bound agent`);
+		}
+		const granted = approved.has(subtask.requestedAuthority);
+		if (!granted) missing.add(subtask.requestedAuthority);
+		return {
+			id: subtask.id,
+			agentId: binding.spec.id,
+			executionRole: deriveExecutionRole({
+				attempt: 0,
+				capabilityClass: binding.spec.capabilityClass,
+				resultContractKind: binding.spec.resultContract.kind,
+			}),
+			scope: scopeFor(subtask.requestedAuthority),
+			expectedResultContract: subtask.expectedResultContract,
+			requestedAuthority: subtask.requestedAuthority,
+			approvedAuthority: granted ? subtask.requestedAuthority : null,
+			dependencies: [...subtask.dependencies],
+			task: subtask.task,
+		};
+	});
+	const plan = compileExecutionPlan({
+		topology: "fleet",
+		rootTask: input.rootTask,
+		maxWorkers: Math.max(1, Math.min(4, input.maxWorkers, steps.length)),
+		onFailure: "stop",
+		steps,
+	});
+	if (missing.size > 0) {
+		return {
+			kind: "approval-required",
+			sourceReceiptDigest: input.sourceReceiptDigest,
+			plan,
+			requiredAuthorities: [...missing],
+		};
+	}
+	return {
+		kind: "ready",
+		sourceReceiptDigest: input.sourceReceiptDigest,
+		plan,
+		authority: {
+			basis: input.authority.basis,
+			approvedAuthorities: [...input.authority.approvedAuthorities],
+		},
+	};
+}