@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/dispatch/assignment.ts

@@ -0,0 +1,278 @@
+import {
+	type ActiveAgentRole,
+	type ActiveRoutingPosture,
+	type ActiveRoutingRole,
+	THINKING_LEVELS,
+} from "../../core/defaults.js";
+import type { AgentCapabilityClass } from "../agents/spec.js";
+import {
+	type AssignmentAttemptStartEvent,
+	type AssignmentEventStream,
+	createAssignmentEventStream,
+} from "./assignment-events.js";
+import type { DispatchRequest } from "./contract.js";
+import { withAttemptRole } from "./execution-role.js";
+import { type RouteDecisionV1, routeCandidateKey } from "./route-decision.js";
+import type { RoutingPosture } from "./route-policy.js";
+import type { RunNodeIdentity, RunOutcome, RunReceipt } from "./types.js";
+import type { DispatchFailoverCandidate, DispatchFailoverMode } from "./validation.js";
+
+declare const assignmentIdBrand: unique symbol;
+
+/** Logical dispatch identity. The value is always the first attempt's rootRunId. */
+export type AssignmentId = string & { readonly [assignmentIdBrand]: "dispatch-assignment" };
+
+export function asAssignmentId(rootRunId: string): AssignmentId {
+	return rootRunId as AssignmentId;
+}
+
+export interface AttemptRef {
+	runId: string;
+	attempt: number;
+	outcome: RunOutcome;
+	node: RunNodeIdentity | null;
+	receiptDigest: string;
+	retryReason: string | null;
+}
+
+export type AssignmentStatus = "running" | "succeeded" | "failed" | "canceled" | "timed_out";
+
+export interface AssignmentPolicy {
+	maxRetries: number;
+	failover: DispatchFailoverMode;
+	allowedCandidates: ReadonlyArray<DispatchFailoverCandidate>;
+}
+
+export interface RoutingActivationSnapshot {
+	activeRoles: ReadonlyArray<ActiveRoutingRole>;
+	activePostures: ReadonlyArray<ActiveRoutingPosture>;
+	agentAutomation: { activeAgentRoles: ReadonlyArray<ActiveAgentRole> };
+}
+
+/** Activation is explicit in both dimensions and never widens mutation authority. */
+export function activeRoutingEnabled(input: {
+	settings: RoutingActivationSnapshot;
+	role: DispatchRequest["executionRole"];
+	posture: RoutingPosture;
+	capabilityClass: AgentCapabilityClass;
+	failover: DispatchFailoverMode;
+}): boolean {
+	if (input.posture === "manual" || input.failover !== "approved") return false;
+	if (input.capabilityClass !== "read-only" && input.capabilityClass !== "verification") return false;
+	return (
+		input.settings.activeRoles.includes(input.role as ActiveRoutingRole) &&
+		input.settings.activePostures.includes(input.posture as ActiveRoutingPosture)
+	);
+}
+
+/** Bind an admitted active decision back onto the exact dispatch tuple. */
+export function applyActiveRouteSelection(req: DispatchRequest, decision: RouteDecisionV1): DispatchRequest {
+	if (decision.mode !== "active") throw new Error("dispatch: cannot apply a non-active route decision");
+	if (routeCandidateKey(decision.selected) !== routeCandidateKey(decision.executedRoute)) {
+		throw new Error("dispatch: active decision selected and executed route identities differ");
+	}
+	const executionRole = withAttemptRole(req.executionRole, req.lineage?.attempt ?? 0);
+	const activeAutoRoot = req.lineage === undefined && req.agentSelection?.mode === "auto";
+	if (
+		decision.selected.executionRole !== executionRole &&
+		!(activeAutoRoot && decision.selected.executionRole !== "recovery")
+	) {
+		throw new Error("dispatch: active route selection cannot change execution role outside an approved auto root");
+	}
+	if (decision.selected.agentId !== req.agentId && !activeAutoRoot) {
+		throw new Error("dispatch: active route selection cannot change agent outside an approved auto root");
+	}
+	if (
+		activeAutoRoot &&
+		(decision.agentSelection.request !== "auto" ||
+			decision.agentSelection.baselineAgentId !== req.agentSelection?.baselineAgentId ||
+			(decision.selected.agentId !== decision.agentSelection.baselineAgentId &&
+				decision.agentSelection.authorityTransition?.basis !== "same-authority" &&
+				decision.agentSelection.authorityTransition?.basis !== req.agentSelection?.authorityBasis))
+	) {
+		throw new Error("dispatch: active auto selection lacks its trusted authority basis");
+	}
+	const envelope = [decision.selected, ...decision.approvedFallbacks].map((candidate) => ({
+		agentId: candidate.agentId,
+		target: candidate.targetId,
+		model: candidate.modelId,
+		node: candidate.nodeId,
+	}));
+	const selected: DispatchRequest = {
+		...req,
+		agentId: decision.selected.agentId,
+		executionRole: decision.selected.executionRole,
+		target: decision.selected.targetId,
+		model: decision.selected.modelId,
+		workerRuntime: decision.selected.runtimeId,
+		node: decision.selected.nodeId,
+		failover: "approved",
+		allowedCandidates: envelope,
+	};
+	if (decision.selected.thinkingLevel === undefined) {
+		delete selected.thinkingLevel;
+	} else if (!(THINKING_LEVELS as ReadonlyArray<string>).includes(decision.selected.thinkingLevel)) {
+		throw new Error(`dispatch: active route selected unsupported thinking level '${decision.selected.thinkingLevel}'`);
+	} else {
+		selected.thinkingLevel = decision.selected.thinkingLevel as NonNullable<DispatchRequest["thinkingLevel"]>;
+	}
+	return selected;
+}
+
+/** Fail closed if lifecycle or placement changed any sealed active identity field. */
+export function assertActiveRouteIdentity(decision: RouteDecisionV1, actual: RouteDecisionV1["selected"]): void {
+	if (routeCandidateKey(actual) !== routeCandidateKey(decision.selected)) {
+		throw new Error("dispatch: active route identity drifted after lifecycle or placement resolution");
+	}
+}
+
+export interface DispatchAssignment {
+	id: AssignmentId;
+	policy: AssignmentPolicy;
+	attempts: ReadonlyArray<AttemptRef>;
+	status: AssignmentStatus;
+	terminalReceipt: RunReceipt | null;
+	/**
+	 * Why the assignment ended here when the terminal receipt does not say so
+	 * itself: a retry denied at admission leaves the previous attempt's sealed
+	 * receipt as terminal evidence, and that receipt cannot record the denial.
+	 */
+	outcomeDetail: string | null;
+	terminal: Promise<RunReceipt>;
+	/**
+	 * Every attempt's frames in order, separated by `attempt_start`. Shared
+	 * single-consumer iterator: the snapshot hands out the same stream the
+	 * assignment owns, exactly as it hands out the same terminal promise.
+	 */
+	events: AsyncIterableIterator<unknown>;
+}
+
+interface MutableAssignment {
+	id: AssignmentId;
+	policy: AssignmentPolicy;
+	attempts: AttemptRef[];
+	status: AssignmentStatus;
+	terminalReceipt: RunReceipt | null;
+	outcomeDetail: string | null;
+	terminal: Promise<RunReceipt>;
+	stream: AssignmentEventStream;
+	resolve: (receipt: RunReceipt) => void;
+	reject: (reason: unknown) => void;
+}
+
+/** In-memory assignment manager. Attempt receipts remain owned by the run ledger. */
+export class AssignmentRegistry {
+	readonly #assignments = new Map<AssignmentId, MutableAssignment>();
+	readonly #onStreamError: ((error: unknown) => void) | undefined;
+
+	constructor(options: { onStreamError?: (error: unknown) => void } = {}) {
+		this.#onStreamError = options.onStreamError;
+	}
+
+	open(rootRunId: string, policy: AssignmentPolicy): DispatchAssignment {
+		const id = asAssignmentId(rootRunId);
+		const existing = this.#assignments.get(id);
+		if (existing) return this.#snapshot(existing);
+
+		let resolve!: (receipt: RunReceipt) => void;
+		let reject!: (reason: unknown) => void;
+		const terminal = new Promise<RunReceipt>((resolvePromise, rejectPromise) => {
+			resolve = resolvePromise;
+			reject = rejectPromise;
+		});
+		const assignment: MutableAssignment = {
+			id,
+			policy: {
+				...policy,
+				allowedCandidates: policy.allowedCandidates.map((candidate) => ({ ...candidate })),
+			},
+			attempts: [],
+			status: "running",
+			terminalReceipt: null,
+			outcomeDetail: null,
+			terminal,
+			stream: createAssignmentEventStream(this.#onStreamError !== undefined ? { onError: this.#onStreamError } : {}),
+			resolve,
+			reject,
+		};
+		this.#assignments.set(id, assignment);
+		return this.#snapshot(assignment);
+	}
+
+	/**
+	 * Fold one attempt's frames into the assignment stream. The marker precedes
+	 * the frames so a consumer resets accumulated state before the new attempt's
+	 * output arrives; attempt 1 carries no marker.
+	 */
+	attachAttempt(id: AssignmentId, source: AsyncIterable<unknown>, marker?: AssignmentAttemptStartEvent): void {
+		this.#require(id).stream.attach(source, marker);
+	}
+
+	recordAttempt(id: AssignmentId, attempt: AttemptRef): void {
+		const assignment = this.#require(id);
+		if (assignment.attempts.some((entry) => entry.runId === attempt.runId)) return;
+		assignment.attempts.push({ ...attempt, node: attempt.node ? { ...attempt.node } : null });
+	}
+
+	/** Mark cancellation immediately so retry scheduling observes it. */
+	cancel(id: AssignmentId): void {
+		const assignment = this.#require(id);
+		if (assignment.status === "running") assignment.status = "canceled";
+		// A canceled assignment produces no further attempts, so the stream ends
+		// now rather than waiting on a worker that is being torn down.
+		assignment.stream.abort();
+	}
+
+	settle(id: AssignmentId, terminalReceipt: RunReceipt, status: AssignmentStatus, outcomeDetail?: string): void {
+		const assignment = this.#require(id);
+		// A canceled assignment still needs its current attempt's immutable receipt
+		// to resolve the terminal promise.
+		if (assignment.status !== "running" && !(assignment.status === "canceled" && assignment.terminalReceipt === null))
+			return;
+		assignment.status = assignment.status === "canceled" ? "canceled" : status;
+		assignment.terminalReceipt = terminalReceipt;
+		if (outcomeDetail !== undefined) assignment.outcomeDetail = outcomeDetail;
+		assignment.stream.close();
+		assignment.resolve(terminalReceipt);
+	}
+
+	/** Reject only when attempt finalization cannot produce an immutable receipt. */
+	reject(id: AssignmentId, reason: unknown): void {
+		const assignment = this.#require(id);
+		if (assignment.status !== "running" && !(assignment.status === "canceled" && assignment.terminalReceipt === null))
+			return;
+		if (assignment.status === "running") assignment.status = "failed";
+		assignment.stream.close();
+		assignment.reject(reason);
+	}
+
+	get(id: AssignmentId | string): DispatchAssignment | null {
+		const assignment = this.#assignments.get(asAssignmentId(id));
+		return assignment ? this.#snapshot(assignment) : null;
+	}
+
+	#require(id: AssignmentId): MutableAssignment {
+		const assignment = this.#assignments.get(id);
+		if (!assignment) throw new Error(`unknown dispatch assignment '${id}'`);
+		return assignment;
+	}
+
+	#snapshot(assignment: MutableAssignment): DispatchAssignment {
+		return {
+			id: assignment.id,
+			policy: {
+				...assignment.policy,
+				allowedCandidates: assignment.policy.allowedCandidates.map((candidate) => ({ ...candidate })),
+			},
+			attempts: assignment.attempts.map((attempt) => ({
+				...attempt,
+				node: attempt.node ? { ...attempt.node } : null,
+			})),
+			status: assignment.status,
+			terminalReceipt: assignment.terminalReceipt,
+			outcomeDetail: assignment.outcomeDetail,
+			terminal: assignment.terminal,
+			events: assignment.stream.events,
+		};
+	}
+}

package/src/domains/dispatch/backoff.ts

@@ -0,0 +1,59 @@
+import type { RunOutcomeCode } from "./types.js";
+
+/**
+ * Exponential backoff state, pure. `nextDelay` returns the delay that should
+ * be used BEFORE the next attempt, along with the updated state. The returned
+ * `delayMs` is always clamped to `maxMs`.
+ */
+
+export interface BackoffState {
+	attempts: number;
+	nextDelayMs: number;
+}
+
+export interface BackoffOptions {
+	baseMs?: number;
+	maxMs?: number;
+	factor?: number;
+}
+
+const DEFAULTS = { baseMs: 500, maxMs: 60_000, factor: 2 } as const;
+
+function resolve(opts?: BackoffOptions): { baseMs: number; maxMs: number; factor: number } {
+	return {
+		baseMs: opts?.baseMs ?? DEFAULTS.baseMs,
+		maxMs: opts?.maxMs ?? DEFAULTS.maxMs,
+		factor: opts?.factor ?? DEFAULTS.factor,
+	};
+}
+
+export function createBackoff(opts?: BackoffOptions): BackoffState {
+	const { baseMs } = resolve(opts);
+	return { attempts: 0, nextDelayMs: baseMs };
+}
+
+export function nextDelay(state: BackoffState, opts?: BackoffOptions): { state: BackoffState; delayMs: number } {
+	const { maxMs, factor } = resolve(opts);
+	const delayMs = Math.min(state.nextDelayMs, maxMs);
+	const next: BackoffState = {
+		attempts: state.attempts + 1,
+		nextDelayMs: Math.min(state.nextDelayMs * factor, maxMs),
+	};
+	return { state: next, delayMs };
+}
+
+export function reset(opts?: BackoffOptions): BackoffState {
+	const { baseMs } = resolve(opts);
+	return { attempts: 0, nextDelayMs: baseMs };
+}
+
+/** True only for typed terminal conditions that retrying unchanged cannot heal. */
+export function isDeterministicOutcomeCode(code: RunOutcomeCode | null | undefined): boolean {
+	return (
+		code === "vram_capacity_fit_failure" ||
+		code === "worker_tool_call_cap_exhausted" ||
+		code === "loop_guard_tools_disabled_exhausted" ||
+		code === "result_contract_exhausted" ||
+		code === "worker_final_output_missing"
+	);
+}

package/src/domains/dispatch/batch-store.ts

@@ -0,0 +1,134 @@
+/**
+ * Durable detached-batch records (WS2 async fan-out).
+ *
+ * A detached dispatch returns to the caller before its runs finish, so the
+ * grouping must outlive the tool call, the turn, and the session. Records
+ * persist as `batches.json` under `clioStateDir()`, beside the run ledger and
+ * never inside receipts: a batch is orchestration state, not run evidence.
+ * Collection state lives here too, so completion nudges stay suppressed after
+ * an operator or model has collected a batch, including across resume.
+ *
+ * Writes go through the shared state-file lock (read/merge/write), because a
+ * sibling Clio process on the same state dir may register or collect batches
+ * concurrently. Reads are lock-free snapshots, matching the run ledger.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { withStateFileLock } from "../../core/state-file-lock.js";
+import { clioStateDir } from "../../core/xdg.js";
+import { atomicWrite } from "../../engine/session.js";
+import { closeAgentLedger } from "./agent-ledger-store.js";
+
+/** Bounded ring: newest first, oldest dropped past this count. */
+const MAX_BATCH_RECORDS = 200;
+
+export interface DetachedBatchRun {
+	/** First attempt id. */
+	runId: string;
+	/** Logical assignment id (the root run id). */
+	assignmentId: string;
+	agentId: string;
+}
+
+export interface DetachedBatchRecord {
+	id: string;
+	runs: DetachedBatchRun[];
+	sessionId: string | null;
+	createdAt: string;
+	/** ISO timestamp when the batch's results were collected; null while open. */
+	collectedAt: string | null;
+	/**
+	 * The agent ledger these concurrent runs coordinated on, when the batch had
+	 * more than one. It is recorded here because collection can happen in a
+	 * later process, which has no other way to learn which ledger to close.
+	 */
+	ledgerId?: string;
+}
+
+interface DetachedBatchStoreFile {
+	version: 1;
+	batches: DetachedBatchRecord[];
+}
+
+function storePath(): string {
+	return join(clioStateDir(), "batches.json");
+}
+
+function readStore(): DetachedBatchRecord[] {
+	const path = storePath();
+	if (!existsSync(path)) return [];
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8")) as DetachedBatchStoreFile;
+		if (parsed?.version !== 1 || !Array.isArray(parsed.batches)) return [];
+		return parsed.batches;
+	} catch {
+		return [];
+	}
+}
+
+function writeStore(batches: ReadonlyArray<DetachedBatchRecord>): void {
+	const file: DetachedBatchStoreFile = { version: 1, batches: [...batches].slice(0, MAX_BATCH_RECORDS) };
+	atomicWrite(storePath(), JSON.stringify(file, null, 2));
+}
+
+export interface RegisterDetachedBatchInput {
+	batchId: string;
+	runs: ReadonlyArray<DetachedBatchRun>;
+	sessionId: string | null;
+	ledgerId?: string;
+}
+
+export async function registerDetachedBatch(input: RegisterDetachedBatchInput): Promise<DetachedBatchRecord> {
+	const record: DetachedBatchRecord = {
+		id: input.batchId,
+		runs: input.runs.map((run) => ({
+			runId: run.runId,
+			assignmentId: run.assignmentId,
+			agentId: run.agentId,
+		})),
+		sessionId: input.sessionId,
+		createdAt: new Date().toISOString(),
+		collectedAt: null,
+		...(input.ledgerId !== undefined ? { ledgerId: input.ledgerId } : {}),
+	};
+	await withStateFileLock(storePath(), () => {
+		const existing = readStore().filter((entry) => entry.id !== record.id);
+		writeStore([record, ...existing]);
+	});
+	return record;
+}
+
+export function listDetachedBatches(opts?: { includeCollected?: boolean }): ReadonlyArray<DetachedBatchRecord> {
+	const batches = readStore();
+	if (opts?.includeCollected === true) return batches;
+	return batches.filter((batch) => batch.collectedAt === null);
+}
+
+export function getDetachedBatch(batchId: string): DetachedBatchRecord | null {
+	return readStore().find((batch) => batch.id === batchId) ?? null;
+}
+
+/** Idempotent: an already-collected batch keeps its original collection time. */
+export async function markDetachedBatchCollected(batchId: string): Promise<DetachedBatchRecord | null> {
+	let updated: DetachedBatchRecord | null = null;
+	// The agent ledger closes on the first collection, which is where a detached
+	// batch's peers stop being concurrent. Only the collection that actually
+	// moves collectedAt closes it, so a repeated collect neither restamps the
+	// close time nor closes a board some other batch owns.
+	let ledgerToClose: string | null = null;
+	await withStateFileLock(storePath(), () => {
+		const batches = readStore();
+		const index = batches.findIndex((batch) => batch.id === batchId);
+		if (index === -1) return;
+		const current = batches[index];
+		if (!current) return;
+		const firstCollection = current.collectedAt === null;
+		updated = firstCollection ? { ...current, collectedAt: new Date().toISOString() } : current;
+		if (firstCollection && current.ledgerId !== undefined) ledgerToClose = current.ledgerId;
+		batches[index] = updated;
+		writeStore(batches);
+	});
+	if (ledgerToClose !== null) await closeAgentLedger(ledgerToClose);
+	return updated;
+}

package/src/domains/dispatch/batch-tracker.ts

@@ -0,0 +1,66 @@
+/**
+ * Immutable batch tracker for a group of logical dispatch assignments. Every
+ * mutation returns a new state object; the caller holds a reference and
+ * threads it through event handlers.
+ */
+
+export interface BatchState {
+	id: string;
+	assignmentIds: ReadonlyArray<string>;
+	completed: ReadonlySet<string>;
+	failed: ReadonlySet<string>;
+	startedAt: string;
+}
+
+function makeId(): string {
+	return `batch-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+export function createBatch(assignmentIds: ReadonlyArray<string>): BatchState {
+	return {
+		id: makeId(),
+		assignmentIds: [...assignmentIds],
+		completed: new Set<string>(),
+		failed: new Set<string>(),
+		startedAt: new Date().toISOString(),
+	};
+}
+
+export interface BatchSnapshot {
+	id: string;
+	assignmentIds: ReadonlyArray<string>;
+	completed: ReadonlyArray<string>;
+	failed: ReadonlyArray<string>;
+	startedAt: string;
+	done: boolean;
+}
+
+export function onRunComplete(batch: BatchState, assignmentId: string, failed: boolean): BatchState {
+	if (!batch.assignmentIds.includes(assignmentId)) return batch;
+	const completed = new Set(batch.completed);
+	const failedSet = new Set(batch.failed);
+	if (failed) failedSet.add(assignmentId);
+	else completed.add(assignmentId);
+	return {
+		id: batch.id,
+		assignmentIds: batch.assignmentIds,
+		completed,
+		failed: failedSet,
+		startedAt: batch.startedAt,
+	};
+}
+
+function isBatchDone(batch: BatchState): boolean {
+	return batch.assignmentIds.every((id) => batch.completed.has(id) || batch.failed.has(id));
+}
+
+export function snapshotBatch(batch: BatchState): BatchSnapshot {
+	return {
+		id: batch.id,
+		assignmentIds: batch.assignmentIds,
+		completed: [...batch.completed],
+		failed: [...batch.failed],
+		startedAt: batch.startedAt,
+		done: isBatchDone(batch),
+	};
+}

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

@@ -0,0 +1,155 @@
+/**
+ * Capability/task mismatch, decided before a worker process exists.
+ *
+ * Observed live (receipt 1yd79n91i9b0): `verifier`, a read-only recipe, was
+ * pinned to "fix the off-by-one bug in src/sum.ts". It ran to completion, made
+ * six read calls, executed no shell command, and sealed `outcome: succeeded`
+ * with a fabricated passing `npm run typecheck`. Nothing about that pairing
+ * needed a run to discover: the recipe carries its capability class and the
+ * task text carries its shape, and both are in hand at admission.
+ *
+ * Two verdicts, because neither the classifier nor the capability label is good
+ * enough to be the only vote. `classifyAgentTask`'s rule list is ordered and
+ * imperfect, so "explain how the config loader works" classifies as `config` (a
+ * mutating shape) purely because `config` is tested before `code_read`;
+ * `capabilityClass` is recipe frontmatter, which a recipe can get wrong without
+ * anything catching it. Refusing on either signal alone would cost real work to
+ * buy back a defect that costs one wasted run. So refusing takes three
+ * independent agreements:
+ *
+ *   1. the caller pinned this agent id; `agent:"auto"` baselines are the
+ *      harness's own choice and its mistakes are for it to report, not for the
+ *      caller to be refused over;
+ *   2. the task classifies as a mutating shape AND no read-shaped rule also
+ *      matches the text, which is the nearest thing to a second opinion on the
+ *      classifier available without a model call;
+ *   3. the recipe's declared postcondition is a report rather than a change, so
+ *      the recipe itself says twice that it does not write.
+ *
+ * Anything short of all three that still pairs a read-only recipe with a
+ * mutating task is admitted with the mismatch flagged, which rides the receipt
+ * and the dispatch summary line.
+ */
+
+import type { ResultContract } from "../agents/result-contract.js";
+import type { AgentCapabilityClass, AgentSpec } from "../agents/spec.js";
+import { type AgentTaskType, classifyAgentTask } from "./agent-candidates.js";
+
+/** Capability classes that cannot change the workspace, whatever the task says. */
+const READ_ONLY_CAPABILITY_CLASSES: ReadonlySet<AgentCapabilityClass> = new Set(["read-only", "verification"]);
+
+/** Task shapes whose completion requires writing something. */
+const MUTATING_TASK_TYPES: ReadonlySet<AgentTaskType> = new Set([
+	"code_write",
+	"debug",
+	"refactor",
+	"config",
+	"test",
+	"docs",
+]);
+
+/**
+ * The read-shaped rules from `classifyAgentTask`, re-tested as corroboration.
+ * A text that matches one of these was plausibly a read task that lost the
+ * ordered scan to an earlier mutating rule, which is exactly the case that must
+ * not be refused. Kept byte-identical to the patterns in `agent-candidates.ts`;
+ * they are duplicated rather than exported because the classifier's list is
+ * ordered and first-match-wins, and this check needs "did any of these match at
+ * all", which the ordered scan cannot answer.
+ */
+const READ_SHAPED_PATTERNS: ReadonlyArray<RegExp> = [
+	/\b(review|audit|critique|inspect for)\b/i,
+	/\b(research|investigate|explore|survey|compare|find out)\b/i,
+	/\b(read|explain|understand|summarize|describe|walk through|map|locate|trace)\b/i,
+];
+
+/**
+ * Contracts whose postcondition is a report. A recipe that declares one has
+ * said in its own frontmatter that its terminal result is an account of the
+ * workspace rather than a change to it, which is the corroboration a refusal
+ * needs. Every other kind, including the harness fixture default
+ * `external-delegation` and the deliberately unmeasurable `artifact-report`,
+ * leaves the pairing flagged instead of refused.
+ */
+const REPORTING_CONTRACT_KINDS: ReadonlySet<ResultContract["kind"]> = new Set([
+	"scout-report",
+	"verifier-report",
+	"research-report",
+	"provenance-report",
+	"debugger-report",
+]);
+
+/** Preferred mutating specialist per task shape, best first. */
+const MUTATING_SPECIALISTS: Readonly<Partial<Record<AgentTaskType, ReadonlyArray<string>>>> = {
+	code_write: ["coder"],
+	debug: ["debugger", "coder"],
+	refactor: ["coder"],
+	config: ["coder"],
+	test: ["tester", "coder"],
+	docs: ["documenter", "coder"],
+};
+
+export interface CapabilityMismatch {
+	/** `refuse` fails admission; `flag` admits the run and rides the receipt. */
+	verdict: "refuse" | "flag";
+	agentId: string;
+	capabilityClass: AgentCapabilityClass;
+	taskType: AgentTaskType;
+	/** Installed recipe that can do this work, or null when none is installed. */
+	suggestedAgentId: string | null;
+	/** One line, model-facing, naming both halves of the mismatch. */
+	detail: string;
+}
+
+export interface CapabilityMismatchInput {
+	agentId: string;
+	capabilityClass: AgentCapabilityClass;
+	task: string;
+	/** True when the caller passed `agent:"auto"` and the harness chose the id. */
+	autoSelected: boolean;
+	/** The recipe's declared postcondition; null when it declares none. */
+	resultContractKind: ResultContract["kind"] | null;
+	/** Installed recipes, used only to name a suggestion that actually resolves. */
+	specs: ReadonlyArray<AgentSpec>;
+}
+
+function suggestedSpecialist(taskType: AgentTaskType, specs: ReadonlyArray<AgentSpec>): string | null {
+	const canMutate = new Set(
+		specs.filter((spec) => !READ_ONLY_CAPABILITY_CLASSES.has(spec.capabilityClass)).map((spec) => spec.id),
+	);
+	for (const id of MUTATING_SPECIALISTS[taskType] ?? []) {
+		if (canMutate.has(id)) return id;
+	}
+	return canMutate.has("coder") ? "coder" : null;
+}
+
+/**
+ * Whether this pairing is a mismatch, and how sure the classifier is. Null
+ * means the recipe can do the work, or the task never asked it to.
+ */
+export function assessCapabilityMismatch(input: CapabilityMismatchInput): CapabilityMismatch | null {
+	if (!READ_ONLY_CAPABILITY_CLASSES.has(input.capabilityClass)) return null;
+	const features = classifyAgentTask(input.task);
+	if (!MUTATING_TASK_TYPES.has(features.taskType)) return null;
+	const readShaped = READ_SHAPED_PATTERNS.some((pattern) => pattern.test(input.task));
+	const reportingContract = input.resultContractKind !== null && REPORTING_CONTRACT_KINDS.has(input.resultContractKind);
+	const confident = !readShaped && !input.autoSelected && reportingContract;
+	const suggestedAgentId = suggestedSpecialist(features.taskType, input.specs);
+	const remedy =
+		suggestedAgentId === null
+			? "No installed recipe can change the workspace, so this task cannot be delegated as written."
+			: `Dispatch agent:"${suggestedAgentId}" for the change itself, then dispatch '${input.agentId}' to check it.`;
+	const detail = confident
+		? `dispatch: agent '${input.agentId}' is a ${input.capabilityClass} recipe and cannot write to the workspace, but this task classifies as ${features.taskType}, which requires a change on disk. ${remedy}`
+		: `capability_mismatch=${input.agentId}/${input.capabilityClass} task_shape=${features.taskType}${
+				suggestedAgentId === null ? "" : ` suggested=${suggestedAgentId}`
+			}; a read-only recipe cannot land this change, so treat any claim that it did as unsupported.`;
+	return {
+		verdict: confident ? "refuse" : "flag",
+		agentId: input.agentId,
+		capabilityClass: input.capabilityClass,
+		taskType: features.taskType,
+		suggestedAgentId,
+		detail,
+	};
+}