@iowarp/clio-coder 0.3.6 → 0.3.7

package/src/domains/agents/result-contract.ts

@@ -7,10 +7,21 @@ export type ResultContract =
 	| { kind: "architect-plan"; path: string }
 	| { kind: "scout-report" }
 	| { kind: "verifier-report" }
+	| { kind: "council-report" }
 	| { kind: "debugger-report" }
 	| { kind: "research-report" }
 	| { kind: "mutation-report" }
 	| { kind: "provenance-report" }
+	| { kind: "delegation-plan" }
+	/**
+	 * The advisory answer `/oracle` asks for. It exists as its own kind because
+	 * the answer shape is the whole point of the command: a verdict, the
+	 * strongest challenge the advisor can mount, the evidence that would change
+	 * its mind, and the prior decisions it read. Folding it onto
+	 * `research-report` would ask for claims and evidence instead, and the
+	 * challenge and the reversal condition would have nowhere to go.
+	 */
+	| { kind: "oracle-report" }
 	| { kind: "external-delegation" }
 	/**
 	 * The run's postcondition is the artifact it left on disk, so its terminal
@@ -58,6 +69,7 @@ export interface ResultContractValidation {
 	scout?: ScoutResult;
 	/** Parsed Verifier data for the dispatch review-gate projection. */
 	verifier?: VerifierResult;
+	delegationPlan?: DelegationPlanResult;
 	reason?: string;
 }
 
@@ -211,6 +223,159 @@ export interface VerifierResult {
 	checks: ReadonlyArray<VerifierCheck>;
 }
 
+export interface DelegationPlanResultTask {
+	id: string;
+	agent: string;
+	description: string;
+	depends_on: ReadonlyArray<string>;
+	writes: ReadonlyArray<string>;
+	mode?: "sequential" | "parallel";
+}
+
+export interface DelegationPlanResult {
+	tasks: ReadonlyArray<DelegationPlanResultTask>;
+}
+
+export function parseDelegationPlanResult(output: string | null): DelegationPlanResult | null {
+	const parsed = parseJson(output);
+	if (
+		!parsed.ok ||
+		!hasOnlyKeys(parsed.value, ["tasks"]) ||
+		!Array.isArray(parsed.value.tasks) ||
+		parsed.value.tasks.length === 0
+	)
+		return null;
+	const tasks: DelegationPlanResultTask[] = [];
+	for (const raw of parsed.value.tasks) {
+		if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+		const task = raw as Record<string, unknown>;
+		if (
+			!hasOnlyKeys(task, ["id", "agent", "description", "depends_on", "writes", "mode"]) ||
+			!string(task.id) ||
+			!string(task.agent) ||
+			!string(task.description) ||
+			!Array.isArray(task.depends_on) ||
+			task.depends_on.some((entry) => !string(entry)) ||
+			!Array.isArray(task.writes) ||
+			task.writes.some((entry) => !string(entry)) ||
+			(task.mode !== undefined && task.mode !== "sequential" && task.mode !== "parallel")
+		)
+			return null;
+		tasks.push({
+			id: task.id,
+			agent: task.agent,
+			description: task.description,
+			depends_on: [...task.depends_on] as string[],
+			writes: [...task.writes] as string[],
+			...(task.mode !== undefined ? { mode: task.mode as "sequential" | "parallel" } : {}),
+		});
+	}
+	return { tasks };
+}
+
+export interface CouncilReportMember {
+	label: string;
+	runId: string;
+	round: number;
+	answer: string;
+	verdict?: string;
+	failed?: { reason: string };
+}
+
+export interface CouncilReport {
+	members: CouncilReportMember[];
+	synthesis: {
+		kind: "none" | "judge" | "vote";
+		text?: string;
+		verdict?: string;
+		tally?: Record<string, number>;
+		judgeRunId?: string;
+	};
+}
+
+export function parseCouncilReport(output: string | null): CouncilReport | null {
+	if (output === null) return null;
+	const parsed = parseJsonObjectPayload(output);
+	if (!parsed.ok) return null;
+	const value = parsed.value;
+	if (!hasOnlyKeys(value, ["members", "synthesis"]) || !Array.isArray(value.members) || value.members.length === 0) {
+		return null;
+	}
+	const members: CouncilReportMember[] = [];
+	for (const raw of value.members) {
+		if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+		const member = raw as Record<string, unknown>;
+		if (
+			!hasOnlyKeys(member, ["label", "runId", "round", "answer", "verdict", "failed"]) ||
+			!string(member.label) ||
+			!string(member.runId) ||
+			!Number.isInteger(member.round) ||
+			Number(member.round) < 1 ||
+			typeof member.answer !== "string" ||
+			(member.verdict !== undefined && !string(member.verdict))
+		)
+			return null;
+		let failed: { reason: string } | undefined;
+		if (member.failed !== undefined) {
+			if (
+				member.failed === null ||
+				typeof member.failed !== "object" ||
+				Array.isArray(member.failed) ||
+				!hasOnlyKeys(member.failed as Record<string, unknown>, ["reason"]) ||
+				!string((member.failed as Record<string, unknown>).reason)
+			)
+				return null;
+			failed = { reason: (member.failed as { reason: string }).reason };
+		}
+		members.push({
+			label: member.label,
+			runId: member.runId,
+			round: Number(member.round),
+			answer: member.answer,
+			...(member.verdict !== undefined ? { verdict: member.verdict as string } : {}),
+			...(failed !== undefined ? { failed } : {}),
+		});
+	}
+	if (value.synthesis === null || typeof value.synthesis !== "object" || Array.isArray(value.synthesis)) return null;
+	const rawSynthesis = value.synthesis as Record<string, unknown>;
+	if (!hasOnlyKeys(rawSynthesis, ["kind", "text", "verdict", "tally", "judgeRunId"])) return null;
+	if (rawSynthesis.kind !== "none" && rawSynthesis.kind !== "judge" && rawSynthesis.kind !== "vote") return null;
+	for (const key of ["text", "verdict", "judgeRunId"] as const) {
+		if (rawSynthesis[key] !== undefined && !string(rawSynthesis[key])) return null;
+	}
+	let tally: Record<string, number> | undefined;
+	if (rawSynthesis.tally !== undefined) {
+		if (rawSynthesis.tally === null || typeof rawSynthesis.tally !== "object" || Array.isArray(rawSynthesis.tally))
+			return null;
+		tally = {};
+		for (const [key, count] of Object.entries(rawSynthesis.tally as Record<string, unknown>)) {
+			if (!key || !Number.isInteger(count) || Number(count) < 0) return null;
+			tally[key] = Number(count);
+		}
+	}
+	return {
+		members,
+		synthesis: {
+			kind: rawSynthesis.kind,
+			...(rawSynthesis.text !== undefined ? { text: rawSynthesis.text as string } : {}),
+			...(rawSynthesis.verdict !== undefined ? { verdict: rawSynthesis.verdict as string } : {}),
+			...(tally !== undefined ? { tally } : {}),
+			...(rawSynthesis.judgeRunId !== undefined ? { judgeRunId: rawSynthesis.judgeRunId as string } : {}),
+		},
+	};
+}
+
+/**
+ * Parsed `oracle-report` payload. `/oracle` renders these four fields into the
+ * operator note it hands the main agent, so the shape is the answer shape.
+ */
+export interface OracleResult {
+	verdict: string;
+	challenge: string;
+	changesMyMind: string;
+	citedDecisions: ReadonlyArray<string>;
+}
+
 /**
  * Parsed `code-report` payload. `passed` restates `exitCode === 0` so a
  * downstream reader never has to know a runner's exit conventions, and
@@ -269,7 +434,7 @@ function success(
 	contract: ResultContract,
 	quality: ResultContractQuality,
 	value: unknown,
-	extra: Pick<ResultContractValidation, "scout" | "verifier" | "reason"> = {},
+	extra: Pick<ResultContractValidation, "scout" | "verifier" | "delegationPlan" | "reason"> = {},
 ): ResultContractValidation {
 	return {
 		conformance: "pass",
@@ -335,6 +500,7 @@ const RESULT_CONTRACT_KINDS: ReadonlyArray<ResultContract["kind"]> = [
 	"architect-plan",
 	"scout-report",
 	"verifier-report",
+	"council-report",
 	"debugger-report",
 	"research-report",
 	"mutation-report",
@@ -664,6 +830,47 @@ export function parseVerifierResult(output: string | null): VerifierResult | nul
 	return validation.verifier ?? null;
 }
 
+/**
+ * An advisory opinion is never a correctness signal about the route that
+ * produced it, so conformance is judged on the shape alone and quality stays
+ * `unmeasured`. `citedDecisions` may be empty: an honest advisor that found no
+ * settled decision bearing on the question must be able to say so.
+ */
+function validateOracle(contract: ResultContract, output: string | null): ResultContractValidation {
+	const parsed = parseJson(output);
+	if (!parsed.ok) return failure(contract, "unmeasured", parsed.reason);
+	const value = parsed.value;
+	if (
+		!hasOnlyKeys(value, ["verdict", "challenge", "changesMyMind", "citedDecisions"]) ||
+		!string(value.verdict) ||
+		!string(value.challenge) ||
+		!string(value.changesMyMind) ||
+		!Array.isArray(value.citedDecisions) ||
+		value.citedDecisions.some((entry) => !string(entry))
+	) {
+		return failure(
+			contract,
+			"unmeasured",
+			'Oracle result must carry verdict, challenge, changesMyMind, and a citedDecisions array of strings, for example {"verdict":"consistent with decision routing.target","challenge":"...","changesMyMind":"...","citedDecisions":["routing.target"]}',
+		);
+	}
+	return success(contract, "unmeasured", value);
+}
+
+/** Parse an oracle answer under the same schema its recipe contract enforces. */
+export function parseOracleResult(output: string | null): OracleResult | null {
+	const validation = validateOracle({ kind: "oracle-report" }, output);
+	if (validation.conformance !== "pass") return null;
+	const parsed = parseJson(output);
+	if (!parsed.ok) return null;
+	return {
+		verdict: String(parsed.value.verdict),
+		challenge: String(parsed.value.challenge),
+		changesMyMind: String(parsed.value.changesMyMind),
+		citedDecisions: (parsed.value.citedDecisions as ReadonlyArray<string>).map((entry) => String(entry)),
+	};
+}
+
 /**
  * A code step's result is always `unmeasured` for routing quality. A red suite
  * is evidence about the repository, not about the route that ran the command,
@@ -1036,6 +1243,12 @@ export function validateResultContract(input: ResultContractValidationInput): Re
 		}
 		case "verifier-report":
 			return validateVerifier(input.contract, input.output);
+		case "council-report": {
+			const report = parseCouncilReport(input.output);
+			return report === null
+				? failure(input.contract, "fail", "council-report is malformed")
+				: success(input.contract, "unmeasured", { council: report });
+		}
 		case "debugger-report":
 			return validateDebugger(input.contract, input.output);
 		case "research-report":
@@ -1044,6 +1257,18 @@ export function validateResultContract(input: ResultContractValidationInput): Re
 			return validateMutation(input.contract, input);
 		case "provenance-report":
 			return validateProvenance(input.contract, input.output);
+		case "delegation-plan": {
+			const plan = parseDelegationPlanResult(input.output);
+			return plan === null
+				? failure(
+						input.contract,
+						"fail",
+						"delegation-plan must carry tasks with id, agent, description, depends_on, writes, and optional mode",
+					)
+				: success(input.contract, "unmeasured", plan, { delegationPlan: plan });
+		}
+		case "oracle-report":
+			return validateOracle(input.contract, input.output);
 		case "external-delegation":
 			return success(input.contract, "unmeasured", { external: true });
 		case "artifact-report":
@@ -1120,6 +1345,8 @@ function resultContractShape(contract: ResultContract): string {
 			return '{"findings":[{"claim":"what you observed","path":"src/file.ts","line":1}],"needsSplit":false,"proposedSubtasks":[]} or {"findings":[],"needsSplit":true,"proposedSubtasks":[{"id":"inspect","task":"Inspect the boundary","dependencies":[],"expectedResultContract":"scout-report","requestedAuthority":"read-only"}]} or, if you cannot produce a citation you are sure of, at least {"findings":[{"claim":"what you observed"}]}, which is accepted as an ungrounded lead rather than losing the run';
 		case "verifier-report":
 			return '{"verdict":"pass","checks":[{"name":"npm run typecheck","passed":true,"evidence":"exit 0"}]}';
+		case "council-report":
+			return '{"members":[{"label":"alpha","runId":"run-1","round":1,"answer":"..."}],"synthesis":{"kind":"none"}}';
 		case "debugger-report":
 			return '{"diagnosis":"...","reproduction":"reproduced","evidence":["..."]}';
 		case "research-report":
@@ -1128,6 +1355,10 @@ function resultContractShape(contract: ResultContract): string {
 			return '{"mutatedPaths":["src/file.ts"],"validations":[{"name":"npm test","passed":true,"evidence":"exit 0"}],"commitMessage":"optional: the commit message for this change","summary":"optional: one line"}';
 		case "provenance-report":
 			return '{"confirmedFacts":["..."],"missingEvidence":["..."],"nextInspections":["..."]}';
+		case "delegation-plan":
+			return '{"tasks":[{"id":"build","agent":"coder","description":"Implement the change","depends_on":[],"writes":["src"],"mode":"parallel"}]}';
+		case "oracle-report":
+			return '{"verdict":"one line","challenge":"the strongest objection you can mount","changesMyMind":"the evidence that would reverse the verdict","citedDecisions":["decision key or task id you relied on"]}';
 		case "external-delegation":
 			return "any final text";
 		case "artifact-report":
@@ -1253,13 +1484,16 @@ export function parseResultContract(value: unknown, sourcePath: string): ResultC
 	const kinds = [
 		"scout-report",
 		"verifier-report",
+		"council-report",
 		"debugger-report",
 		"research-report",
 		"mutation-report",
 		"provenance-report",
+		"oracle-report",
 		"external-delegation",
 		"artifact-report",
 		"context-handbook",
+		"delegation-plan",
 	] as const;
 	if (!(kinds as ReadonlyArray<string>).includes(record.kind) || !only("kind")) {
 		throw new Error(`agent recipe: ${sourcePath}: resultContract.kind is unsupported or has unknown keys`);

package/src/domains/config/classify.ts

@@ -28,6 +28,10 @@ const HOT_RELOAD_FIELDS = new Set<string>([
 	"modelSelector",
 	"terminal.smoothStreaming",
 	"attribution.gitCommits",
+	// The watchdog registration reads its settings live on every trigger, so
+	// enabling it, retargeting it, or changing its cadence takes effect on the
+	// next turn boundary without a restart or a session-routing patch.
+	"watchdog",
 ]);
 
 const NEXT_TURN_FIELDS = new Set<string>([

package/src/domains/dispatch/active-route-planner.ts

@@ -37,6 +37,12 @@ export function routeValidationProjection(
 		// Presentation-only parentage stamped by the calling tool, on the same
 		// terms: a model must not be able to author it.
 		parentToolCallId,
+		resolvedVerification,
+		resultContractOverride,
+		fleetGateReceipt,
+		taskWorktree,
+		runIdHint,
+		taskWorktreeDestination,
 		...raw
 	} = request;
 	const awaitingEnvelope =
@@ -54,6 +60,14 @@ export function routeValidationProjection(
 			...(assignmentDeadlineAt !== undefined ? { assignmentDeadlineAt } : {}),
 			...(ledger !== undefined ? { ledger } : {}),
 			...(parentToolCallId !== undefined ? { parentToolCallId } : {}),
+			...(resolvedVerification !== undefined
+				? { resolvedVerification: resolvedVerification.map((check) => ({ ...check, argv: [...check.argv] })) }
+				: {}),
+			...(resultContractOverride !== undefined ? { resultContractOverride } : {}),
+			...(fleetGateReceipt !== undefined ? { fleetGateReceipt: { ...fleetGateReceipt } } : {}),
+			...(taskWorktree !== undefined ? { taskWorktree } : {}),
+			...(runIdHint !== undefined ? { runIdHint } : {}),
+			...(taskWorktreeDestination !== undefined ? { taskWorktreeDestination } : {}),
 			...(awaitingEnvelope ? { failover: "approved" as const } : {}),
 		}),
 	};

package/src/domains/dispatch/backoff.ts

@@ -54,6 +54,7 @@ export function isDeterministicOutcomeCode(code: RunOutcomeCode | null | undefin
 		code === "worker_tool_call_cap_exhausted" ||
 		code === "loop_guard_tools_disabled_exhausted" ||
 		code === "result_contract_exhausted" ||
-		code === "worker_final_output_missing"
+		code === "worker_final_output_missing" ||
+		code === "host_verification_rejected"
 	);
 }

package/src/domains/dispatch/capability-match.ts

@@ -77,6 +77,7 @@ const REPORTING_CONTRACT_KINDS: ReadonlySet<ResultContract["kind"]> = new Set([
 	"research-report",
 	"provenance-report",
 	"debugger-report",
+	"oracle-report",
 ]);
 
 /** Preferred mutating specialist per task shape, best first. */

package/src/domains/dispatch/checkout-writer-lease.ts

@@ -0,0 +1,175 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, realpathSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { BIRTH_TOKEN_SOURCE_AVAILABLE, processAlive, processBirthToken } from "../../core/process-identity.js";
+import { withStateFileLockSync } from "../../core/state-file-lock.js";
+import { clioStateDir } from "../../core/xdg.js";
+import { atomicWrite } from "../../engine/session.js";
+
+export interface CheckoutWriterLeaseRecord {
+	version: 1;
+	checkout: string;
+	pid: number;
+	processBirthToken: string;
+	acquiredAt: string;
+}
+
+export interface CheckoutWriterLease {
+	checkout: string;
+	path: string;
+	release(): void;
+}
+
+export interface CheckoutWriterLeaseProbe {
+	birthToken(pid: number): string | null;
+	tokenProvesDeath?: boolean;
+	alive?(pid: number): boolean;
+}
+
+const held = new Map<string, { count: number; path: string }>();
+let exitHooksInstalled = false;
+
+function canonicalCheckout(checkout: string): string {
+	return realpathSync(checkout);
+}
+
+function checkoutWriterLeasePath(checkout: string): string {
+	const canonical = canonicalCheckout(checkout);
+	const key = createHash("sha256").update(canonical, "utf8").digest("hex");
+	return join(clioStateDir(), "checkout-writer-leases", `${key}.json`);
+}
+
+function validRecord(value: unknown): value is CheckoutWriterLeaseRecord {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const record = value as Partial<CheckoutWriterLeaseRecord>;
+	return (
+		record.version === 1 &&
+		typeof record.checkout === "string" &&
+		Number.isSafeInteger(record.pid) &&
+		(record.pid ?? 0) > 0 &&
+		typeof record.processBirthToken === "string" &&
+		typeof record.acquiredAt === "string" &&
+		Number.isFinite(Date.parse(record.acquiredAt))
+	);
+}
+
+function readRecord(path: string): CheckoutWriterLeaseRecord | null {
+	if (!existsSync(path)) return null;
+	try {
+		const value = JSON.parse(readFileSync(path, "utf8")) as unknown;
+		if (!validRecord(value)) throw new Error("invalid schema");
+		return value;
+	} catch (error) {
+		throw new Error(
+			`checkout writer lease is unreadable at ${path}: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+}
+
+function ownerAlive(record: CheckoutWriterLeaseRecord, probe: CheckoutWriterLeaseProbe): boolean {
+	const current = probe.birthToken(record.pid);
+	if (current === null || current !== record.processBirthToken) return false;
+	if (probe.tokenProvesDeath === false) return probe.alive?.(record.pid) ?? false;
+	return true;
+}
+
+const defaultProbe: CheckoutWriterLeaseProbe = {
+	birthToken: processBirthToken,
+	tokenProvesDeath: BIRTH_TOKEN_SOURCE_AVAILABLE,
+	alive: processAlive,
+};
+
+function releaseAllOnExit(): void {
+	for (const [checkout, entry] of held) {
+		try {
+			withStateFileLockSync(entry.path, () => {
+				const record = readRecord(entry.path);
+				if (record?.checkout === checkout && record.pid === process.pid) unlinkSync(entry.path);
+			});
+		} catch {
+			// Process exit is best effort. A stale record is reclaimed by the next admission.
+		}
+	}
+	held.clear();
+}
+
+function installExitHooks(): void {
+	if (exitHooksInstalled) return;
+	exitHooksInstalled = true;
+	process.once("exit", releaseAllOnExit);
+}
+
+export function acquireCheckoutWriterLease(input: {
+	checkout: string;
+	nowMs?: number;
+	pid?: number;
+	processBirthToken?: string;
+	probe?: CheckoutWriterLeaseProbe;
+}): CheckoutWriterLease {
+	const checkout = canonicalCheckout(input.checkout);
+	const path = checkoutWriterLeasePath(checkout);
+	const local = held.get(checkout);
+	if (local !== undefined && (input.pid === undefined || input.pid === process.pid)) {
+		local.count += 1;
+		let released = false;
+		return {
+			checkout,
+			path,
+			release: () => {
+				if (released) return;
+				released = true;
+				releaseCheckoutWriterLease(checkout);
+			},
+		};
+	}
+	mkdirSync(dirname(path), { recursive: true });
+	const ownerPid = input.pid ?? process.pid;
+	const token = input.processBirthToken ?? processBirthToken(ownerPid);
+	if (token === null) throw new Error("dispatch: cannot establish checkout writer process birth token");
+	withStateFileLockSync(path, () => {
+		const existing = readRecord(path);
+		if (existing !== null && ownerAlive(existing, input.probe ?? defaultProbe)) {
+			throw new Error(`checkout_writer_lease_held: checkout writer lease is held by pid ${existing.pid}`);
+		}
+		const record: CheckoutWriterLeaseRecord = {
+			version: 1,
+			checkout,
+			pid: ownerPid,
+			processBirthToken: token,
+			acquiredAt: new Date(input.nowMs ?? Date.now()).toISOString(),
+		};
+		atomicWrite(path, JSON.stringify(record, null, 2));
+	});
+	if (ownerPid === process.pid) {
+		held.set(checkout, { count: 1, path });
+		installExitHooks();
+	}
+	let released = false;
+	return {
+		checkout,
+		path,
+		release: () => {
+			if (released) return;
+			released = true;
+			if (ownerPid === process.pid) releaseCheckoutWriterLease(checkout);
+			else releaseLeaseRecord(path, checkout, ownerPid, token);
+		},
+	};
+}
+
+function releaseLeaseRecord(path: string, checkout: string, pid: number, token: string): void {
+	withStateFileLockSync(path, () => {
+		const record = readRecord(path);
+		if (record?.checkout === checkout && record.pid === pid && record.processBirthToken === token) unlinkSync(path);
+	});
+}
+
+function releaseCheckoutWriterLease(checkout: string): void {
+	const entry = held.get(checkout);
+	if (entry === undefined) return;
+	entry.count -= 1;
+	if (entry.count > 0) return;
+	held.delete(checkout);
+	const token = processBirthToken(process.pid);
+	if (token !== null) releaseLeaseRecord(entry.path, checkout, process.pid, token);
+}

package/src/domains/dispatch/contract.ts

@@ -15,6 +15,30 @@ import type { RunEnvelope, RunLineage, RunNodeIdentity, RunPhaseDurations, RunRe
 import type { DispatchFailoverCandidate, JobSpec } from "./validation.js";
 
 export interface DispatchRequest extends JobSpec {
+	/** Coordinator-owned result contract override for a fleet plan step. */
+	resultContractOverride?: ResultContract;
+	/** Gate path whose post-run hash is sealed into this step's receipt. */
+	fleetGateReceipt?: { path: string };
+	/** Orchestrator-prepared task worktree state. Model arguments cannot author it. */
+	taskWorktree?: {
+		root: string;
+		runId: string;
+		path: string;
+		branch: string;
+		base: string;
+		ownerToken: string;
+	};
+	/** Run identity allocated before task worktree creation. Model arguments cannot author it. */
+	runIdHint?: string;
+	/** Parent checkout frozen by plan approval for task worktree application. */
+	taskWorktreeDestination?: string;
+	/** Admission-resolved commands. Model text never enters these argv vectors. */
+	resolvedVerification?: ReadonlyArray<{
+		check: string;
+		argv: ReadonlyArray<string>;
+		cwd: string;
+		timeoutMs: number;
+	}>;
 	/**
 	 * Semantic role this request's first attempt runs under. Derived once by
 	 * `execution-role.ts` at request construction, never authored by a model, and
@@ -212,6 +236,16 @@ export interface DispatchContract {
 		finalPromise: Promise<ReadonlyArray<RunReceipt>>;
 	}>;
 
+	/** Seal a coordinator-only council synthesis receipt without invoking a model. */
+	sealCouncilSynthesis?(input: {
+		group: string;
+		round: number;
+		kind: "none" | "vote";
+		text: string;
+		subjects: ReadonlyArray<{ runId: string; digest: string | null }>;
+		template: RunReceipt;
+	}): Promise<RunReceipt>;
+
 	/** List runs from the ledger. */
 	listRuns(status?: RunStatus): ReadonlyArray<RunEnvelope>;