@iowarp/clio-coder 0.3.9 → 0.4.0

package/src/domains/dispatch/extension.ts

@@ -10,7 +10,7 @@
  */
 
 import { createHash, randomBytes } from "node:crypto";
-import { type Dirent, existsSync, readdirSync, readFileSync } from "node:fs";
+import { type Dirent, readdirSync, readFileSync } from "node:fs";
 import { isAbsolute, relative, resolve as resolvePath, sep } from "node:path";
 import { performance } from "node:perf_hooks";
 import { BusChannels, type DispatchCompletedPayload, type DispatchRunIdentity } from "../../core/bus-events.js";
@@ -58,6 +58,7 @@ import {
 import type { AgentsContract } from "../agents/contract.js";
 import type { AgentRecipe } from "../agents/recipe.js";
 import { validateRecipeResult } from "../agents/result-contract.js";
+import { nodeResultContractFilesystem } from "../agents/result-contract-filesystem.js";
 import {
 	type AgentAudience,
 	type AgentCapabilityClass,
@@ -78,7 +79,7 @@ import {
 	type CapabilityFlags,
 	canonicalizeWireModelId,
 	type EndpointCapacity,
-	endpointCapacitiesForStatuses,
+	endpointCapacityFor,
 	endpointCapacityForStatus,
 	firstRuntimeResolutionError,
 	isDispatchEligibleRuntime,
@@ -86,6 +87,7 @@ import {
 	type ResolvedRuntimeTarget,
 	type RuntimeApiFamily,
 	type RuntimeDescriptor,
+	resolveEndpointCapacities,
 	resolveModelCapabilities,
 	resolveRuntimeTarget,
 	runtimeResolutionWarnings,
@@ -112,6 +114,7 @@ import {
 	routeValidationProjection,
 } from "./active-route-planner.js";
 import { admit, createCapacityAdmissionController, createLeaseSlotGuard } from "./admission.js";
+import { AdmissionCanceledError } from "./admission-error.js";
 import { agentRouteCandidates } from "./agent-candidates.js";
 import { AGENT_LEDGER_PROMPT_MAX_CHARS, renderAgentLedger } from "./agent-ledger.js";
 import { publishAgentLedgerEntry, subscribeAgentLedger } from "./agent-ledger-hub.js";
@@ -236,6 +239,7 @@ import {
 import { createRouteObserver, type RouteObservationHandle, type RouteObserver } from "./route-observer.js";
 import { reduceRouteQuality } from "./route-quality.js";
 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 {
@@ -358,6 +362,12 @@ interface ActiveRun {
 	finalPromise: Promise<RunReceipt>;
 }
 
+interface PendingCapacityAdmission {
+	identity: DispatchRunIdentity & { requestOrigin: DispatchRequestOrigin };
+	timing: RunPhaseMarks;
+	node: RunNodeIdentity | null;
+}
+
 interface DispatchFinishContractSnapshot {
 	assessment: FinishContractAssessment;
 	rigor: Rigor;
@@ -398,6 +408,15 @@ export interface DispatchBundleOptions {
 	collectReproducibility?: typeof collectReproducibilityMetadata;
 	/** Observer injection seam. Production constructs the durable observer. */
 	routeObserver?: RouteObserver;
+	/**
+	 * Write the durable run event journal for every run this bundle dispatches.
+	 * Off by default and turned on by the three composition roots
+	 * (src/entry/orchestrator.ts, src/cli/run.ts, src/cli/fleet.ts), because the
+	 * process that owns a bundle also decides who owns the journal file: a
+	 * composed process routes `registerAllTools`' event registry to
+	 * `journal: null` so a tool-path run is transcribed once, not twice.
+	 */
+	journalRunEvents?: boolean;
 }
 
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 1000;
@@ -2419,6 +2438,7 @@ export function createDispatchBundle(
 	let ledger: Ledger | null = null;
 	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>();
 	/**
@@ -2459,19 +2479,37 @@ export function createDispatchBundle(
 		}),
 	);
 
+	/**
+	 * Every endpoint the configured fleet can reach.
+	 *
+	 * Deliberately resolved from the configured targets as well as the probed
+	 * statuses. A target whose status has not been built yet contributed no key,
+	 * an absent key carries no limit, and reservation planning skips a dimension
+	 * it has no limit for, so admission against a single-slot server used to fail
+	 * open for whoever asked first after boot.
+	 */
+	function configuredEndpointCapacities(): Readonly<Record<string, EndpointCapacity>> {
+		return resolveEndpointCapacities({
+			statuses: providers.list(),
+			targets: getEffectiveSettings()?.targets ?? [],
+			runtimeFor: (runtimeId) => providers.getRuntime(runtimeId),
+		});
+	}
+
 	function configuredEndpointLimits(): Readonly<Record<string, number>> {
-		return Object.fromEntries(
-			Object.entries(endpointCapacitiesForStatuses(providers.list())).map(([key, value]) => [key, value.limit]),
-		);
+		return Object.fromEntries(Object.entries(configuredEndpointCapacities()).map(([key, value]) => [key, value.limit]));
 	}
 
 	function endpointCapacityForTarget(targetId: string): EndpointCapacity | null {
 		const status = providers.list().find((entry) => entry.target.id === targetId);
-		if (status === undefined) return null;
-		const endpoint = endpointCapacityForStatus(status);
+		const target = status?.target ?? providers.getTarget(targetId);
+		if (target === null || target === undefined) return null;
+		const endpoint =
+			status === undefined
+				? endpointCapacityFor({ target, runtime: providers.getRuntime(target.runtime) })
+				: endpointCapacityForStatus(status);
 		if (endpoint === null) return null;
-		const configured = endpointCapacitiesForStatuses(providers.list())[endpoint.key];
-		return configured ?? endpoint;
+		return configuredEndpointCapacities()[endpoint.key] ?? endpoint;
 	}
 
 	function reservationCapacitySnapshot(settings: EffectiveSettings): ReservationCapacitySnapshot {
@@ -2564,6 +2602,34 @@ export function createDispatchBundle(
 		return scheduling.maxWorkers?.() ?? (configured === "auto" || configured === undefined ? 4 : Math.max(1, configured));
 	}
 
+	function publishCapacityQueued(
+		identity: DispatchRunIdentity & { requestOrigin: DispatchRequestOrigin },
+		timing: RunPhaseMarks,
+		node: RunNodeIdentity | null,
+	): void {
+		pendingCapacity.set(identity.runId, { identity, timing, node });
+		context.bus.emit(BusChannels.DispatchEnqueued, identity);
+	}
+
+	function publishCapacityAdmissionFailure(
+		identity: DispatchRunIdentity & { requestOrigin: DispatchRequestOrigin },
+		error: unknown,
+	): void {
+		const detail = error instanceof Error ? error.message : String(error);
+		const outcome: RunOutcome =
+			error instanceof AdmissionCanceledError
+				? "canceled"
+				: /admission timed out/u.test(detail)
+					? "timed_out"
+					: "denied_by_policy";
+		context.bus.emit(BusChannels.DispatchFailed, {
+			...identity,
+			outcome,
+			outcomeDetail: detail,
+			reason: outcome,
+		});
+	}
+
 	async function admitAssignmentCapacity(
 		req: DispatchRequest,
 		nodeId: string,
@@ -2572,7 +2638,8 @@ export function createDispatchBundle(
 	) {
 		const queuedAt = now();
 		timing.queuedAt = new Date(queuedAt).toISOString();
-		const assignmentId = req.lineage?.rootRunId ?? `pending-${queuedAt.toString(36)}-${randomBytes(6).toString("hex")}`;
+		const assignmentId =
+			req.lineage?.rootRunId ?? req.runIdHint ?? `pending-${queuedAt.toString(36)}-${randomBytes(6).toString("hex")}`;
 		const requestedAt = Date.parse(timing.requestedAt ?? timing.queuedAt);
 		const deadlineAt = req.assignmentDeadlineAt ?? requestedAt + (req.routingIntent?.deadlineMs ?? 60_000);
 		if (req.lineage === undefined) await registerAssignment(assignmentId);
@@ -2919,6 +2986,10 @@ export function createDispatchBundle(
 				depth: run.lineage.depth,
 			},
 		};
+		// A run-id hint names only the first attempt (and, for task worktrees,
+		// the worktree it created). A retry shares the assignment lineage but
+		// must receive its own ledger/run identity.
+		delete retryReq.runIdHint;
 		const reasonKey = retryReasonKey(run.lineage.rootRunId, attempt);
 		retryReasons.set(reasonKey, reason);
 		try {
@@ -3566,7 +3637,29 @@ export function createDispatchBundle(
 
 		assertBudgetAdmitsRoute(req, { rates: null, provenance: "unknown" }, settings);
 
-		const capacityLease = await admitAssignmentCapacity(req, "local", timing, null);
+		const queuedIdentity =
+			req.lineage === undefined && req.runIdHint !== undefined
+				? {
+						runId: req.runIdHint,
+						agentId: req.agentId,
+						task: req.task,
+						requestOrigin: lifecycle.requestOrigin,
+						targetId,
+						wireModelId,
+						runtimeId,
+						runtimeKind: "acp-delegation" as const,
+					}
+				: null;
+		if (queuedIdentity !== null) publishCapacityQueued(queuedIdentity, timing, null);
+		let capacityLease: Awaited<ReturnType<typeof admitAssignmentCapacity>>;
+		try {
+			capacityLease = await admitAssignmentCapacity(req, "local", timing, null);
+		} catch (error) {
+			if (queuedIdentity !== null) publishCapacityAdmissionFailure(queuedIdentity, error);
+			throw error;
+		} finally {
+			if (queuedIdentity !== null) pendingCapacity.delete(queuedIdentity.runId);
+		}
 		const leaseSlot = createLeaseSlotGuard(capacityAdmission, capacityLease.leaseId, req.lineage !== undefined);
 
 		// Resolve the ledger before starting the ACP process: an external agent
@@ -3774,8 +3867,10 @@ export function createDispatchBundle(
 			runIdForPermissionAudit = envelope.id;
 			lineage = lineageFor(req, envelope.id);
 			if (req.lineage === undefined) {
-				capacityAdmission.rename(capacityLease.leaseId, lineage.rootRunId);
-				await renameStoredAssignment(capacityLease.assignmentId, lineage.rootRunId);
+				if (capacityLease.assignmentId !== lineage.rootRunId) {
+					capacityAdmission.rename(capacityLease.leaseId, lineage.rootRunId);
+					await renameStoredAssignment(capacityLease.assignmentId, lineage.rootRunId);
+				}
 				leaseSlot.transferToAssignment();
 			}
 			identity = detectRunIdentity();
@@ -3801,16 +3896,18 @@ export function createDispatchBundle(
 			// One durable write at start so sibling processes (clio-coder fleet status)
 			// can observe the running row; finalization persists the terminal state.
 			await ledgerRef.persist();
-			context.bus.emit(BusChannels.DispatchEnqueued, {
-				runId: envelope.id,
-				agentId: req.agentId,
-				task: req.task,
-				requestOrigin: lifecycle.requestOrigin,
-				targetId,
-				wireModelId,
-				runtimeId,
-				runtimeKind: "acp-delegation",
-			});
+			if (req.lineage !== undefined) {
+				context.bus.emit(BusChannels.DispatchEnqueued, {
+					runId: envelope.id,
+					agentId: req.agentId,
+					task: req.task,
+					requestOrigin: lifecycle.requestOrigin,
+					targetId,
+					wireModelId,
+					runtimeId,
+					runtimeKind: "acp-delegation",
+				});
+			}
 			context.bus.emit(BusChannels.DispatchStarted, {
 				runId: envelope.id,
 				agentId: req.agentId,
@@ -4268,6 +4365,10 @@ export function createDispatchBundle(
 			throw new Error(`dispatch: invalid spec: ${validated.errors.join("; ")}`);
 		}
 		req = validation.restore(validated.spec);
+		// A top-level run needs its stable identity before it can wait for
+		// capacity. The board can then render the assignment as queued and the
+		// same id becomes the ledger row once its slot opens.
+		if (req.lineage === undefined && req.runIdHint === undefined) req = { ...req, runIdHint: newRunId() };
 		let activeRouteObservation: RouteObservationHandle | null = null;
 		if (req.delegationAgentId === undefined) {
 			const recipe = agents.get(req.agentId);
@@ -4395,7 +4496,41 @@ export function createDispatchBundle(
 			shadow: () => observeShadowRoute(req, placed, settings),
 		});
 
-		const capacityLease = await admitAssignmentCapacity(req, placement?.node.id ?? "local", timing, endpoint);
+		const queuedIdentity =
+			req.lineage === undefined && req.runIdHint !== undefined
+				? {
+						runId: req.runIdHint,
+						agentId: req.agentId,
+						task: req.task,
+						agentAudience: lifecycle.agentAudience,
+						requestOrigin: lifecycle.requestOrigin,
+						targetId: lifecycle.target.target.id,
+						wireModelId: lifecycle.target.wireModelId,
+						runtimeId: lifecycle.target.runtime.id,
+						runtimeKind: lifecycle.runtimeKind,
+						budget: lifecycle.budgetEnvelope,
+						...(endpoint !== null ? { endpoint: { key: endpoint.key, label: endpoint.label, limit: endpoint.limit } } : {}),
+						...(placement !== null ? { node: placement.node.id } : {}),
+						...(req.gate !== undefined ? { gate: { role: req.gate.role, cycle: req.gate.cycle } } : {}),
+						...(req.council !== undefined ? { council: req.council } : {}),
+						...(req.reroutes !== undefined && req.reroutes.length > 0 ? { rerouteCount: req.reroutes.length } : {}),
+						...(lifecycle.target.modelCapabilities !== undefined &&
+						lifecycle.target.modelCapabilities !== null &&
+						lifecycle.target.modelCapabilities.contextWindow > 0
+							? { contextWindow: lifecycle.target.modelCapabilities.contextWindow }
+							: {}),
+					}
+				: null;
+		if (queuedIdentity !== null) publishCapacityQueued(queuedIdentity, timing, placement?.node ?? null);
+		let capacityLease: Awaited<ReturnType<typeof admitAssignmentCapacity>>;
+		try {
+			capacityLease = await admitAssignmentCapacity(req, placement?.node.id ?? "local", timing, endpoint);
+		} catch (error) {
+			if (queuedIdentity !== null) publishCapacityAdmissionFailure(queuedIdentity, error);
+			throw error;
+		} finally {
+			if (queuedIdentity !== null) pendingCapacity.delete(queuedIdentity.runId);
+		}
 		const leaseSlot = createLeaseSlotGuard(capacityAdmission, capacityLease.leaseId, req.lineage !== undefined);
 
 		const ledgerRef = (() => {
@@ -4664,6 +4799,7 @@ export function createDispatchBundle(
 					...(ruleId !== null ? { ruleId } : {}),
 					...(policySource !== null ? { policySource } : {}),
 					...(typeof event.payload.timeoutMs === "number" ? { timeoutMs: event.payload.timeoutMs } : {}),
+					fallback: spec.escalation?.fallback ?? "deny",
 					escalation: true,
 				});
 			}
@@ -4738,6 +4874,7 @@ export function createDispatchBundle(
 					decidedBy,
 					actionClass,
 					reason,
+					...(source === "timeout" ? { fallback: spec.escalation?.fallback ?? "deny" } : {}),
 					...(runIdForPermissionAudit !== null ? { requestedBy: runIdForPermissionAudit } : {}),
 				});
 			}
@@ -4793,8 +4930,10 @@ export function createDispatchBundle(
 			runIdForPermissionAudit = envelope.id;
 			lineage = lineageFor(req, envelope.id);
 			if (req.lineage === undefined) {
-				capacityAdmission.rename(capacityLease.leaseId, lineage.rootRunId);
-				await renameStoredAssignment(capacityLease.assignmentId, lineage.rootRunId);
+				if (capacityLease.assignmentId !== lineage.rootRunId) {
+					capacityAdmission.rename(capacityLease.leaseId, lineage.rootRunId);
+					await renameStoredAssignment(capacityLease.assignmentId, lineage.rootRunId);
+				}
 				leaseSlot.transferToAssignment();
 			}
 			if (agentLedgerId !== null) {
@@ -4855,18 +4994,20 @@ export function createDispatchBundle(
 					? { contextWindow: lifecycle.target.modelCapabilities.contextWindow }
 					: {}),
 			};
-			context.bus.emit(BusChannels.DispatchEnqueued, {
-				runId: envelope.id,
-				agentId: req.agentId,
-				task: req.task,
-				agentAudience: lifecycle.agentAudience,
-				requestOrigin: lifecycle.requestOrigin,
-				targetId: lifecycle.target.target.id,
-				wireModelId: lifecycle.target.wireModelId,
-				runtimeId: lifecycle.target.runtime.id,
-				runtimeKind: lifecycle.runtimeKind,
-				...fleetIdentity,
-			});
+			if (req.lineage !== undefined) {
+				context.bus.emit(BusChannels.DispatchEnqueued, {
+					runId: envelope.id,
+					agentId: req.agentId,
+					task: req.task,
+					agentAudience: lifecycle.agentAudience,
+					requestOrigin: lifecycle.requestOrigin,
+					targetId: lifecycle.target.target.id,
+					wireModelId: lifecycle.target.wireModelId,
+					runtimeId: lifecycle.target.runtime.id,
+					runtimeKind: lifecycle.runtimeKind,
+					...fleetIdentity,
+				});
+			}
 			context.bus.emit(BusChannels.DispatchStarted, {
 				runId: envelope.id,
 				agentId: req.agentId,
@@ -5295,18 +5436,7 @@ export function createDispatchBundle(
 					cwd: lifecycle.cwd,
 					networkAllowed: lifecycle.admission.allowedTools.includes(ToolNames.WebFetch),
 					observedRunEffects,
-					filesystem: {
-						readFile(filePath) {
-							try {
-								return readFileSync(filePath, "utf8");
-							} catch {
-								return null;
-							}
-						},
-						pathExists(filePath) {
-							return existsSync(filePath);
-						},
-					},
+					filesystem: nodeResultContractFilesystem(),
 				});
 				const resultValidation = resultContract?.applicable === true ? resultContract.validation : null;
 				if (finalOutcome === "succeeded" && resultValidation?.conformance === "fail") {
@@ -6154,8 +6284,15 @@ export function createDispatchBundle(
 		return receipt;
 	}
 
+	let journalBridge: RunEventJournalBridge | null = null;
+
 	const extension: DomainExtension = {
 		async start() {
+			// The journal subscribes before anything can dispatch. It rides the
+			// domain's own progress and terminal channels, so it covers a run
+			// whose caller iterates the handle itself (every operator path) as
+			// well as one drained by the dispatch tool's event registry.
+			if (options?.journalRunEvents === true) journalBridge = attachRunEventJournalBridge(context.bus);
 			// 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() });
@@ -6221,6 +6358,10 @@ export function createDispatchBundle(
 			for (const ownerId of ownedReservations) rollbackDispatchReservation(ownerId, now());
 			ownedReservations.clear();
 			await Promise.allSettled([...assignmentWrites]);
+			// After drain(), so the last run's terminal line is written before the
+			// bridge stops listening.
+			journalBridge?.stop();
+			journalBridge = null;
 		},
 	};
 
@@ -6248,6 +6389,26 @@ export function createDispatchBundle(
 		const running: DispatchSnapshot["running"] = [];
 		const totals = { ...finalizedTotals };
 		const costAmounts = [...finalizedCosts];
+		for (const pending of pendingCapacity.values()) {
+			const startedAt = pending.timing.queuedAt ?? pending.timing.requestedAt ?? new Date(tickNow).toISOString();
+			running.push({
+				runId: pending.identity.runId,
+				agentId: pending.identity.agentId,
+				...(pending.identity.task !== undefined ? { task: pending.identity.task } : {}),
+				...(pending.identity.budget !== undefined ? { budget: pending.identity.budget } : {}),
+				runtimeKind: pending.identity.runtimeKind,
+				outcomePhase: "queued",
+				heartbeat: "n/a",
+				lineage: { parentRunId: null, rootRunId: pending.identity.runId, attempt: 0, depth: 0 },
+				startedAt,
+				elapsedMs: 0,
+				timing: deriveRunPhaseDurations(pending.timing, startedAt, new Date(tickNow).toISOString()),
+				tokens: { input: 0, output: 0, total: 0 },
+				costUsd: 0,
+				costProvenance: "unknown",
+				node: pending.node === null ? null : { ...pending.node },
+			});
+		}
 		for (const run of active.values()) {
 			let heartbeat: "alive" | "stale" | "dead" | "n/a" = "n/a";
 			if (run.heartbeatAt && Number.isFinite(heartbeatMonotonicAt(run.heartbeatAt))) {
@@ -6426,6 +6587,17 @@ export function createDispatchBundle(
 		},
 		abort(runId, reason) {
 			const rootRunId = assignmentRootFor(runId);
+			const queued = pendingCapacity.get(rootRunId);
+			if (queued !== undefined && capacityAdmission.cancel(rootRunId)) {
+				persistAssignment(cancelStoredAssignment(rootRunId), `${rootRunId}:cancel-queued`);
+				context.bus.emit(BusChannels.RunAborted, {
+					source: "dispatch_abort",
+					runId: rootRunId,
+					startedAt: null,
+					elapsedMs: null,
+					reason: reason?.detail ?? "operator abort while waiting for an endpoint slot",
+				});
+			}
 			const assignment = assignments.get(rootRunId);
 			if (assignment?.status === "running") {
 				assignments.cancel(assignment.id);

package/src/domains/dispatch/fleet-node-prompt.ts

@@ -0,0 +1,62 @@
+/**
+ * What one fleet node is told about its own answer.
+ *
+ * A fleet contract renders a single prompt body and the plan compiler gives it
+ * to every agent node, because the body describes the whole chain and each node
+ * does one part of it. That is fine for the work description and wrong for the
+ * answer: nodes in the same chain hold different result contracts, so a body
+ * that names one contract names the wrong one for every other node. A loop's
+ * check node is where the mismatch is fatal rather than merely untidy. It is
+ * dispatched with `verifier-report` as its expected contract, and in
+ * `build-review` and `build-test` it received a body ending in "Answer with
+ * your `mutation-report`". The verifier complied with the instruction it was
+ * given, the gate held it to the schema that instruction never mentioned, and
+ * both were behaving correctly: every review cycle in those two fleets ended in
+ * `review gate produced no structured verdict` and the bounded revise loop was
+ * unresolvable by construction.
+ *
+ * So each node states its own contract, appended to the shared body, and the
+ * precedence line settles the conflict explicitly rather than leaving it to the
+ * model to guess which of two shapes the run will actually validate. This is
+ * the same remedy `COUNCIL_VOTE_MEMBER_DIRECTIVE` applies to a voting council
+ * member, for the same reason and with the same shape of failure behind it
+ * (#230): a run whose postcondition differs from the shape its prompt names
+ * fails on every input, not intermittently.
+ *
+ * The shape itself is quoted from `resultContractShape`, the one place a
+ * contract's wire example is written, so this directive cannot drift from the
+ * validator that judges the answer.
+ */
+
+import { type ResultContract, resultContractShape } from "../agents/result-contract.js";
+
+/**
+ * The answer directive for a node holding this contract, or null when the kind
+ * alone does not fix the shape.
+ *
+ * `architect-plan` names the path it must write, and a plan compiler resolving
+ * agents holds only the contract's kind. Inventing a path to render would state
+ * a location the validator does not check, so that kind gets no directive and
+ * its recipe keeps sole authority over the shape. Every other kind is fully
+ * determined by its kind and can be quoted exactly.
+ */
+export function fleetNodeAnswerDirective(kind: ResultContract["kind"]): string | null {
+	if (kind === "architect-plan") return null;
+	return [
+		`Your result contract for this step is \`${kind}\`.`,
+		"The task above describes the whole chain. Any result shape it states belongs to the step that produces it, and does not apply to you.",
+		`End with exactly this shape and nothing else: ${resultContractShape({ kind })}`,
+		// The wire example carries literal names and evidence, and a small model
+		// handed one on a first attempt copies them: the first run of this
+		// directive came back claiming `npm run typecheck` / `exit 0` in the same
+		// breath as admitting it could not run a command. The fields are the
+		// contract; the values in the example are not.
+		"Its field values are an example. Fill them with what this run actually produced or observed, and never report a name or evidence you did not.",
+	].join("\n");
+}
+
+/** The shared body plus the node's own answer directive. */
+export function renderFleetNodeTask(task: string, kind: ResultContract["kind"]): string {
+	const directive = fleetNodeAnswerDirective(kind);
+	return directive === null ? task : `${task}\n\n${directive}`;
+}

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

@@ -32,6 +32,7 @@ import {
 	type ExecutionPlanStepInput,
 } from "./execution-plan.js";
 import type { ExecutionRole } from "./execution-role.js";
+import { renderFleetNodeTask } from "./fleet-node-prompt.js";
 
 /** Where an agent node sits, so the caller can resolve its role and authority. */
 export interface FleetPlanAgentContext {
@@ -58,7 +59,11 @@ export interface FleetPlanAgentResolution {
 
 export interface CompileFleetPlanInput {
 	contract: FleetContract;
-	/** Rendered prompt body; every agent node carries it as its task. */
+	/**
+	 * Rendered prompt body. It describes the whole chain, so every agent node
+	 * carries it, followed by that node's own answer directive: the nodes hold
+	 * different result contracts and the body can only ever name one of them.
+	 */
 	task: string;
 	resolveAgent(context: FleetPlanAgentContext): FleetPlanAgentResolution;
 }
@@ -143,7 +148,7 @@ export function compileFleetExecutionPlan(input: CompileFleetPlanInput): Executi
 			agentId: context.agentId,
 			scope: context.scope,
 			dependencies: [...dependencies],
-			task,
+			task: renderFleetNodeTask(task, resolved.expectedResultContract),
 			expectedResultContract: resolved.expectedResultContract,
 			requestedAuthority: resolved.requestedAuthority,
 			approvedAuthority: resolved.approvedAuthority,