@iowarp/clio-coder 0.3.4 → 0.3.7

package/src/tools/dispatch-admission.ts

@@ -1,8 +1,13 @@
-import { resolve } from "node:path";
+import { isAbsolute, relative, resolve } from "node:path";
 import type { DispatchPlanTaskResolution, DispatchRequest } from "../domains/dispatch/contract.js";
 import type { ExecutionPlan } from "../domains/dispatch/execution-plan.js";
 import { gateDeciderAgentId } from "../domains/dispatch/execution-role.js";
-import { JUDGE_GATE_PROMPT, REVIEWER_GATE_PROMPT } from "../domains/dispatch/gate-role-prompts.js";
+import {
+	COUNCIL_JUDGE_PROMPT,
+	JUDGE_GATE_PROMPT,
+	REVIEWER_GATE_PROMPT,
+} from "../domains/dispatch/gate-role-prompts.js";
+import { normalizeDispatchIntent } from "../domains/dispatch/intent.js";
 import { approvedRouteCandidates } from "../domains/dispatch/route-approval.js";
 import { defaultRoutingIntent } from "../domains/dispatch/routing-intent.js";
 import type { DispatchFailoverMode } from "../domains/dispatch/validation.js";
@@ -29,12 +34,15 @@ import {
 } from "./dispatch-scout-admission.js";
 import type {
 	DispatchCompeteSettings,
+	DispatchCouncilSettings,
 	DispatchExecutionSnapshot,
 	DispatchMode,
 	DispatchReviewSettings,
 	DispatchToolDeps,
 } from "./dispatch-types.js";
 import type { ToolSpec } from "./registry.js";
+import { gitCheckoutRoot } from "./task-worktree.js";
+import { discoverDeclaredChecks } from "./verify/scripts.js";
 
 /**
  * The six identity-sensitive stores which bind synchronous admission to the
@@ -68,6 +76,64 @@ const COMPETE_SINGLE_TASK_MESSAGE = "dispatch: compete requires exactly one task
 const COMPETE_NO_REVIEW_MESSAGE = "dispatch: compete has its own judge and cannot combine with review";
 const COMPETE_MIN_CANDIDATES = 2;
 const COMPETE_MAX_CANDIDATES = 4;
+const COUNCIL_LABEL = /^[a-z][a-z0-9_-]{0,31}$/u;
+
+function councilSettingsFromArgs(
+	args: Record<string, unknown>,
+	deps: DispatchToolDeps,
+): { ok: true; council: DispatchCouncilSettings } | { ok: false; message: string } {
+	const rosterName = stringArg(args, "roster");
+	const hasMembers = Object.hasOwn(args, "members");
+	if ((rosterName === undefined) === !hasMembers) {
+		return { ok: false, message: "dispatch: council requires exactly one of roster or members" };
+	}
+	let members: DispatchCouncilSettings["members"];
+	if (rosterName !== undefined) {
+		const roster = deps.getWorkerRosters?.()[rosterName];
+		if (roster === undefined) return { ok: false, message: `council_roster_unknown: ${rosterName}` };
+		members = roster.members.map((member) => ({ ...member }));
+	} else {
+		if (!Array.isArray(args.members)) return { ok: false, message: "council_members_out_of_range" };
+		members = [];
+		for (const raw of args.members) {
+			if (!isRecord(raw)) return { ok: false, message: "council_members_out_of_range" };
+			const label = stringArg(raw, "label");
+			const target = stringArg(raw, "target");
+			if (label === undefined || target === undefined || !COUNCIL_LABEL.test(label)) {
+				return { ok: false, message: "council_members_out_of_range" };
+			}
+			const model = stringArg(raw, "model");
+			const thinking = stringArg(raw, "thinking");
+			members.push({ label, target, ...(model ? { model } : {}), ...(thinking ? { thinking } : {}) });
+		}
+	}
+	if (members.length < 2 || members.length > 5) return { ok: false, message: "council_members_out_of_range" };
+	const labels = new Set<string>();
+	for (const member of members) {
+		if (labels.has(member.label)) return { ok: false, message: `council_member_label_duplicate: ${member.label}` };
+		labels.add(member.label);
+	}
+	const synthesis = args.synthesis === undefined ? "none" : args.synthesis;
+	if (synthesis !== "none" && synthesis !== "judge" && synthesis !== "vote") {
+		return { ok: false, message: "dispatch: synthesis must be none, judge, or vote" };
+	}
+	if (args.judge !== undefined && synthesis !== "judge") {
+		return { ok: false, message: "council_synthesis_requires_judge_settings" };
+	}
+	const rounds = args.rounds === undefined ? 1 : args.rounds;
+	if (!Number.isInteger(rounds) || Number(rounds) < 1 || Number(rounds) > 3) {
+		return { ok: false, message: "dispatch: rounds must be an integer 1..3" };
+	}
+	const judge = isRecord(args.judge)
+		? Object.fromEntries(
+				["agent", "model", "target", "node"].flatMap((key) => {
+					const value = stringArg(args.judge as Record<string, unknown>, key);
+					return value === undefined ? [] : [[key, value]];
+				}),
+			)
+		: undefined;
+	return { ok: true, council: { members, synthesis, rounds: Number(rounds), ...(judge ? { judge } : {}) } };
+}
 
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -165,6 +231,28 @@ export function createDispatchAdmissionController(deps: DispatchToolDeps): Dispa
 				approvedAuthorities: ["read-only", "verification", "artifact-write", "workspace-edit"],
 				authorityBasis: deps.getAutonomy?.() === "full-auto" ? "full-auto-policy" : "operator-plan-approval",
 			},
+			resolveIntent(rawIntent, cwd) {
+				const discovery = discoverDeclaredChecks(cwd);
+				if (!discovery.ok) return { ok: false, message: `verification_catalog_invalid: ${discovery.reason}` };
+				const declared = discovery.sources.flatMap((source) => source.checks);
+				const byId = new Map(declared.map((check) => [check.id, check]));
+				const normalized = normalizeDispatchIntent(rawIntent, byId);
+				if (!normalized.ok) return { ok: false, message: `${normalized.reason}: ${normalized.message}` };
+				return {
+					ok: true,
+					intent: normalized.intent,
+					resolvedVerification: normalized.intent.verification.map((entry) => {
+						const check = byId.get(entry.check);
+						if (check === undefined) throw new Error(`resolved verification check '${entry.check}' disappeared`);
+						return {
+							check: entry.check,
+							argv: [...check.command],
+							cwd: resolve(process.cwd(), check.cwd),
+							timeoutMs: entry.timeoutMs,
+						};
+					}),
+				};
+			},
 		});
 	const trustExecution = (args: Record<string, unknown>, snapshot: DispatchExecutionSnapshot) => {
 		state.trustedExecutionSnapshots.set(args, deepFreeze(structuredClone(snapshot)));
@@ -172,11 +260,15 @@ export function createDispatchAdmissionController(deps: DispatchToolDeps): Dispa
 	};
 	const dispatchExecutionSnapshot = (
 		args: Record<string, unknown>,
-		fields: Pick<DispatchExecutionSnapshot & { kind: "dispatch" }, "requests" | "mode" | "review" | "compete">,
+		fields: Pick<
+			DispatchExecutionSnapshot & { kind: "dispatch" },
+			"requests" | "mode" | "review" | "compete" | "council"
+		>,
 	): DispatchExecutionSnapshot => ({
 		kind: "dispatch",
 		planView: describeDispatchPlan(args),
 		...fields,
+		writers: args.writers === 1 ? 1 : undefined,
 		detach: args.detach === true,
 		timeoutMs: timeoutMsArg(args),
 		maxOutputBytes: maxOutputBytesArg(args),
@@ -217,6 +309,9 @@ export function createDispatchAdmissionController(deps: DispatchToolDeps): Dispa
 	): ResolvedPlanTask => {
 		const resolution = deps.dispatch.preview?.(request);
 		if (resolution === undefined) throw new Error("dispatch preview is unavailable");
+		if (request.resolvedVerification?.length && resolution.runtimeId === "claude-code") {
+			throw new Error("verification_unsupported_runtime: claude-code subprocess dispatch cannot run host verification");
+		}
 		const pinned = request.node !== undefined || request.target !== undefined || request.model !== undefined;
 		const approvedCandidates =
 			pinned || request.failover !== "approved"
@@ -229,6 +324,15 @@ export function createDispatchAdmissionController(deps: DispatchToolDeps): Dispa
 			agent: resolution.agentId,
 			task: request.task,
 			...(request.briefing !== undefined ? { briefing: request.briefing } : {}),
+			...(request.worktree === true
+				? {
+						worktree: true as const,
+						apply: request.apply ?? "merge",
+						...(gitCheckoutRoot(resolve(request.cwd ?? process.cwd())) === null
+							? {}
+							: { worktreeDestination: gitCheckoutRoot(resolve(request.cwd ?? process.cwd())) as string }),
+					}
+				: {}),
 			target: resolution.targetId,
 			model: resolution.wireModelId,
 			node: resolution.node.id,
@@ -248,6 +352,10 @@ export function createDispatchAdmissionController(deps: DispatchToolDeps): Dispa
 			...(failover === "approved" ? { allowedCandidates: approvedCandidates.map((candidate) => ({ ...candidate })) } : {}),
 			role,
 			position,
+			...(request.intent !== undefined ? { intent: structuredClone(request.intent) } : {}),
+			...(request.resolvedVerification !== undefined
+				? { resolvedVerification: request.resolvedVerification.map((check) => ({ ...check, argv: [...check.argv] })) }
+				: {}),
 		};
 		state.taskResolutions.set(task, resolution);
 		return task;
@@ -269,6 +377,8 @@ export function createDispatchAdmissionController(deps: DispatchToolDeps): Dispa
 		if (topology === "fleet") return task.wave ?? index;
 		if (topology === "parallel" || topology === "detached") return 0;
 		if (topology === "compete") return task.role === "judge" ? 1 : 0;
+		if (topology === "council")
+			return task.role === "synthesis" ? (task.council?.rounds ?? 1) : (task.council?.round ?? 1) - 1;
 		return index;
 	};
 	const markReservedPlan = (args: Record<string, unknown>, artifact: ResolvedDispatchPlanArtifact) => {
@@ -286,7 +396,7 @@ export function createDispatchAdmissionController(deps: DispatchToolDeps): Dispa
 			};
 		});
 		const reservation = deps.dispatch.reservations.prepare({
-			topology: artifact.topology === "fleet" ? "parallel" : artifact.topology,
+			topology: artifact.topology === "fleet" || artifact.topology === "council" ? "parallel" : artifact.topology,
 			tasks,
 		});
 		try {
@@ -333,6 +443,7 @@ export function createDispatchAdmissionController(deps: DispatchToolDeps): Dispa
 						mode: "parallel",
 						review: undefined,
 						compete: undefined,
+						council: undefined,
 					}),
 				);
 				state.trustedExecutionPlans.set(marked, deepFreeze(structuredClone(prepared.executionPlan)));
@@ -375,10 +486,13 @@ export function createDispatchAdmissionController(deps: DispatchToolDeps): Dispa
 		}
 		const parsed = parseRequests(args);
 		if (!parsed.ok) return shapeRejection(args, parsed.message);
-		if (args.mode !== undefined && !["parallel", "sequential", "pipeline", "compete"].includes(String(args.mode))) {
+		if (
+			args.mode !== undefined &&
+			!["parallel", "sequential", "pipeline", "compete", "council"].includes(String(args.mode))
+		) {
 			return shapeRejection(
 				args,
-				`dispatch: mode must be parallel, sequential, pipeline, or compete; got '${String(args.mode)}'`,
+				`dispatch: mode must be parallel, sequential, pipeline, compete, or council; got '${String(args.mode)}'`,
 			);
 		}
 		const mode: DispatchMode =
@@ -388,7 +502,30 @@ export function createDispatchAdmissionController(deps: DispatchToolDeps): Dispa
 					? "pipeline"
 					: args.mode === "compete"
 						? "compete"
-						: "parallel";
+						: args.mode === "council"
+							? "council"
+							: "parallel";
+		if (args.writers !== undefined && args.writers !== 1) {
+			return shapeRejection(args, "dispatch: writers must be 1 when present");
+		}
+		if (args.writers === 1 && mode !== "parallel") {
+			return shapeRejection(args, "dispatch: writers is supported only for parallel dispatch");
+		}
+		const parentCheckout = gitCheckoutRoot(process.cwd());
+		for (const request of parsed.requests) {
+			if (request.worktree !== true) continue;
+			if (mode === "compete") return shapeRejection(args, "worktree_compete_incompatible");
+			if (parentCheckout === null) return shapeRejection(args, "worktree_non_git_checkout");
+			const spec = deps.getAgentSpecs().find((candidate) => candidate.id === request.agentId);
+			if (spec?.capabilityClass === "read-only") return shapeRejection(args, "worktree_read_only_agent");
+			if (request.cwd !== undefined) {
+				const requested = resolve(request.cwd);
+				const rel = relative(parentCheckout, requested);
+				if (rel === ".." || rel.startsWith("../") || isAbsolute(rel)) {
+					return shapeRejection(args, "worktree_cwd_outside_checkout");
+				}
+			}
+		}
 		const reviewResult = reviewSettingsFromArgs(args);
 		if (!reviewResult.ok) return shapeRejection(args, reviewResult.message);
 		if (reviewResult.review !== undefined) {
@@ -397,17 +534,35 @@ export function createDispatchAdmissionController(deps: DispatchToolDeps): Dispa
 			if (parsed.requests.length !== 1 || parsed.requests[0] === undefined) {
 				return shapeRejection(args, REVIEW_SINGLE_TASK_MESSAGE);
 			}
+			if (parsed.requests.some((request) => (request.resolvedVerification?.length ?? 0) > 0)) {
+				return shapeRejection(args, "verification_unsupported_for_mode: review requests cannot run host verification");
+			}
 		}
 		if (mode === "compete" && (parsed.requests.length !== 1 || parsed.requests[0] === undefined)) {
 			return shapeRejection(args, COMPETE_SINGLE_TASK_MESSAGE);
 		}
+		if (mode === "compete" && parsed.requests.some((request) => (request.resolvedVerification?.length ?? 0) > 0)) {
+			return shapeRejection(args, "verification_unsupported_for_mode: compete requests cannot run host verification");
+		}
 		const competeResult = mode === "compete" ? competeSettingsFromArgs(args) : undefined;
 		if (competeResult !== undefined && !competeResult.ok) return shapeRejection(args, competeResult.message);
+		const councilResult = mode === "council" ? councilSettingsFromArgs(args, deps) : undefined;
+		if (councilResult !== undefined && !councilResult.ok) return shapeRejection(args, councilResult.message);
+		if (mode === "council") {
+			if (parsed.requests.length !== 1 || parsed.requests[0] === undefined) {
+				return shapeRejection(args, "dispatch: council requires exactly one task");
+			}
+			if (reviewResult.review !== undefined) return shapeRejection(args, "dispatch: council cannot combine with review");
+			if ((parsed.requests[0].resolvedVerification?.length ?? 0) > 0) {
+				return shapeRejection(args, "council_verification_unsupported");
+			}
+		}
 		const snapshotFields = {
 			requests: parsed.requests,
 			mode,
 			review: reviewResult.review,
 			compete: competeResult?.ok === true ? competeResult.compete : undefined,
+			council: councilResult?.ok === true ? councilResult.council : undefined,
 		};
 		if (deps.dispatch.preview === undefined) {
 			const marked = markPrepared(args);
@@ -480,6 +635,72 @@ export function createDispatchAdmissionController(deps: DispatchToolDeps): Dispa
 						1,
 					),
 				);
+			} else if (mode === "council") {
+				const council = councilResult?.ok === true ? councilResult.council : undefined;
+				const base = parsed.requests[0];
+				if (council === undefined || base === undefined)
+					throw new Error("dispatch: council admission settings are unavailable");
+				const subjects: Array<{ runId: string; digest: null }> = [];
+				for (let round = 1; round <= council.rounds; round += 1) {
+					for (const [index, member] of council.members.entries()) {
+						const memberRequest: DispatchRequest = {
+							...base,
+							executionRole: "researcher",
+							autonomy: "read-only",
+							toolProfile: "council-read-only",
+							target: member.target,
+							...(member.model ? { model: member.model } : {}),
+							...(member.thinking ? { thinkingLevel: member.thinking as NonNullable<DispatchRequest["thinkingLevel"]> } : {}),
+							gate: { role: "member", group: "plan-preview", cycle: round },
+						};
+						let task: ResolvedPlanTask;
+						try {
+							task = resolveTask(memberRequest, "member", (round - 1) * council.members.length + index + 1);
+						} catch (error) {
+							return shapeRejection(
+								args,
+								`council_member_target_unknown: ${member.label}: ${error instanceof Error ? error.message : String(error)}`,
+							);
+						}
+						if (task.node !== "local" || task.nodeKind !== "local") {
+							return shapeRejection(args, `council_member_remote_node: ${member.label}`);
+						}
+						task.council = {
+							label: member.label,
+							...(member.color ? { color: member.color } : {}),
+							round,
+							rounds: council.rounds,
+							synthesis: council.synthesis,
+						};
+						if (round === council.rounds) subjects.push({ runId: `plan-member-${member.label}`, digest: null });
+						tasks.push(task);
+					}
+				}
+				if (council.synthesis === "judge") {
+					const judgeRequest: DispatchRequest = {
+						agentId: council.judge?.agent ?? base.agentId,
+						executionRole: "judge",
+						task: "Plan-time capability check for council synthesis.",
+						systemPrompt: COUNCIL_JUDGE_PROMPT,
+						autonomy: "read-only",
+						toolProfile: "council-read-only",
+						gate: { role: "synthesis", group: "plan-preview", cycle: council.rounds, subjects },
+						...(council.judge?.node ? { node: council.judge.node } : {}),
+						...(council.judge?.model ? { model: council.judge.model } : {}),
+						...(council.judge?.target ? { target: council.judge.target } : {}),
+					};
+					const judgeTask = resolveTask(judgeRequest, "synthesis", 1);
+					if (judgeTask.node !== "local" || judgeTask.nodeKind !== "local") {
+						return shapeRejection(args, "council_member_remote_node: judge");
+					}
+					judgeTask.council = {
+						label: "synthesis",
+						round: council.rounds,
+						rounds: council.rounds,
+						synthesis: council.synthesis,
+					};
+					tasks.push(judgeTask);
+				}
 			} else {
 				for (const [index, request] of parsed.requests.entries()) tasks.push(resolveTask(request, "task", index + 1));
 			}
@@ -490,7 +711,20 @@ export function createDispatchAdmissionController(deps: DispatchToolDeps): Dispa
 				topology === "compete" ||
 				tasks.some((task) => task.node !== "local" || task.failover === "approved");
 			if (!planScale) {
-				const marked = markPrepared(args);
+				const marked = parsed.requests.some((request) => request.intent !== undefined)
+					? markPrepared(
+							withResolvedDispatchPlan(args, {
+								version: 3,
+								topology,
+								source: null,
+								maxWorkers: null,
+								onFailure: null,
+								tasks,
+								costCeilingUsd: resolvedCostCeiling(),
+								deadlineMs: null,
+							}),
+						)
+					: markPrepared(args);
 				return trustExecution(marked, dispatchExecutionSnapshot(marked, snapshotFields));
 			}
 			const marked = markReservedPlan(args, {

package/src/tools/dispatch-arguments.ts

@@ -2,13 +2,22 @@
 
 import type { AgentAutomationAuthority } from "../domains/agents/spec.js";
 import { type AgentTaskType, classifyAgentTask } from "../domains/dispatch/agent-candidates.js";
+import { cloneDispatchBudgetRequest } from "../domains/dispatch/budget-envelope.js";
 import type { DispatchRequest } from "../domains/dispatch/contract.js";
 import { type AgentRoleFactsResolver, requestExecutionRole } from "../domains/dispatch/execution-role.js";
+import type { DispatchIntent } from "../domains/dispatch/intent.js";
 import { parseRoutingIntent } from "../domains/dispatch/routing-intent.js";
 import { DISPATCH_BRIEFING_MAX_BYTES, type JobThinkingLevel } from "../domains/dispatch/validation.js";
 import { isToolProfileName, TOOL_PROFILE_NAMES } from "./profiles.js";
 
 const DEFAULT_AGENT_ID = "coder";
+/**
+ * The agent a council seats when the caller names none. Council admission pins
+ * every member to the `council-read-only` tool profile, and `coder` requires a
+ * write tool, so the ordinary default would fail admission for every member.
+ * `researcher` is the builtin read-only answerer.
+ */
+const COUNCIL_DEFAULT_AGENT_ID = "researcher";
 
 /**
  * Baseline recipe per task shape for `agent:"auto"`.
@@ -68,6 +77,12 @@ export interface DispatchArgumentParserOptions {
 		approvedAuthorities: ReadonlyArray<AgentAutomationAuthority>;
 		authorityBasis: "operator-plan-approval" | "full-auto-policy";
 	};
+	resolveIntent?: (
+		rawIntent: unknown,
+		cwd: string | undefined,
+	) =>
+		| { ok: true; intent: DispatchIntent; resolvedVerification: NonNullable<DispatchRequest["resolvedVerification"]> }
+		| { ok: false; message: string };
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -99,7 +114,8 @@ function dispatchRequestFromArgs(
 	const task = stringArg(args, "task");
 	if (!task) return { ok: false, message: "missing task (pass list:true to see available agents)" };
 	if (Object.hasOwn(args, "agent_id")) return { ok: false, message: "agent_id is unsupported; use agent" };
-	const requestedAgent = stringArg(args, "agent") ?? DEFAULT_AGENT_ID;
+	const requestedAgent =
+		stringArg(args, "agent") ?? (args.mode === "council" ? COUNCIL_DEFAULT_AGENT_ID : DEFAULT_AGENT_ID);
 	const auto = requestedAgent === "auto";
 	const agentId = auto ? autoBaselineAgentId(task, options.hasAgent) : requestedAgent;
 	const request: DispatchRequest = {
@@ -149,6 +165,47 @@ function dispatchRequestFromArgs(
 	request.requiredCapabilities = routing.intent.requiredCapabilities;
 	const cwd = stringArg(args, "cwd");
 	if (cwd) request.cwd = cwd;
+	if (args.worktree !== undefined) {
+		if (args.worktree !== true) return { ok: false, message: "worktree must be true when present" };
+		request.worktree = true;
+	}
+	if (args.apply !== undefined) {
+		if (args.apply !== "merge" && args.apply !== "preserve")
+			return { ok: false, message: "apply must be merge or preserve" };
+		if (request.worktree !== true) return { ok: false, message: "apply requires worktree: true" };
+		request.apply = args.apply;
+	}
+	if (Object.hasOwn(args, "gate") && isRecord(args.intent) && Object.hasOwn(args.intent, "verification")) {
+		return { ok: false, message: "gate_and_intent_verification_conflict: gate cannot combine with intent.verification" };
+	}
+	let rawIntent = args.intent;
+	if (Object.hasOwn(args, "gate")) {
+		if (typeof args.gate !== "string" || args.gate.trim().length === 0) {
+			return { ok: false, message: "gate must be a non-empty declared check id" };
+		}
+		rawIntent = { ...(isRecord(rawIntent) ? rawIntent : {}), verification: [{ check: args.gate.trim() }] };
+	}
+	if (rawIntent !== undefined) {
+		if (options.resolveIntent === undefined) return { ok: false, message: "intent resolver is unavailable" };
+		const resolved = options.resolveIntent(rawIntent, cwd);
+		if (!resolved.ok) return resolved;
+		request.intent = resolved.intent;
+		if (resolved.resolvedVerification.length > 0) request.resolvedVerification = resolved.resolvedVerification;
+		if (resolved.intent.writeRoots.length > 0) {
+			const legacy = Array.isArray(args.writeRoots)
+				? args.writeRoots.filter((entry): entry is string => typeof entry === "string")
+				: undefined;
+			if (legacy !== undefined) {
+				const left = [...new Set(legacy)].sort();
+				if (JSON.stringify(left) !== JSON.stringify(resolved.intent.writeRoots)) {
+					return { ok: false, message: "intent_write_roots_contradiction" };
+				}
+				request.writeRoots = legacy;
+			} else {
+				request.writeRoots = resolved.intent.writeRoots;
+			}
+		}
+	}
 	if ("persona" in args && args.persona !== undefined) {
 		if (typeof args.persona !== "string") return { ok: false, message: "persona must be a string" };
 		const persona = args.persona.trim();
@@ -171,6 +228,13 @@ function dispatchRequestFromArgs(
 		}
 		request.thinkingLevel = thinkingLevel as JobThinkingLevel;
 	}
+	if (args.budget !== undefined) {
+		try {
+			request.budget = cloneDispatchBudgetRequest(args.budget);
+		} catch (error) {
+			return { ok: false, message: error instanceof Error ? error.message : String(error) };
+		}
+	}
 	return { ok: true, request };
 }
 

package/src/tools/dispatch-event-text.ts

@@ -1,6 +1,25 @@
+import { responseModelIdObservationFromRecord } from "../core/response-model-id.js";
 import { durableAssistantTextFromEvent } from "../domains/dispatch/event-pump.js";
+import type { RunReceipt } from "../domains/dispatch/types.js";
 
 /** Return the durable final assistant text carried by a worker event. */
 export function assistantTextFromEvent(event: unknown): string {
 	return durableAssistantTextFromEvent(event).trim();
 }
+
+/** Human projection of the response model-id observations carried by a receipt. */
+export function receiptResponseModelIdObservationLabel(receipt: Pick<RunReceipt, "upstreamResponses">): string | null {
+	const responses = receipt.upstreamResponses ?? [];
+	if (responses.length === 0) return null;
+	const labels = responses.map((response) => {
+		const observation = responseModelIdObservationFromRecord(
+			response as unknown as Record<string, unknown>,
+			"legacy-difference-only",
+		);
+		if (observation.state === "reported") return `reported:${observation.reportedModelId}`;
+		if (observation.state === "not-reported") return "not-reported";
+		if (observation.state === "not-observed") return "not-observed";
+		return `legacy-difference-only:${observation.differingModelId ?? "none"}`;
+	});
+	return `response_model_id_observation=${labels.join(",")}`;
+}