@iowarp/clio-coder 0.4.1 → 0.4.2

package/src/core/guardrails.ts

@@ -2,17 +2,11 @@
  * Guardrail policy values: the numeric backstops that bound runaway agent
  * behavior (tool-call budgets, tool output byte caps, dispatch ledger size).
  *
- * These are durable operator policy, the same species as
- * `compaction.threshold`, so their primary home is the `guardrails:` section
- * of settings.yaml. The composition roots (orchestrator entry and worker
- * runtime) wire that section in via {@link configureGuardrails}; consumers
- * resolve values through {@link resolveGuardrail}, which layers a per-process
- * env override on top for CI and one-off experiments:
- *
- *   env var  >  settings.yaml guardrails  >  built-in default
- *
- * Every value is a positive safe integer; invalid overrides fall through to
- * the next layer rather than erroring.
+ * These are durable operator policy, so their only configurable home is the
+ * canonical version 2 settings tree. Composition roots project that tree into
+ * this process through {@link configureGuardrails}; hot-path consumers resolve
+ * the current projection through {@link resolveGuardrail} without reading
+ * settings.yaml themselves.
  */
 
 export interface GuardrailValues {
@@ -66,16 +60,6 @@ export const GUARDRAIL_DEFAULTS: GuardrailValues = {
 	internalDispatchTimeoutMs: 15 * 60 * 1000,
 };
 
-/** Per-process env overrides, one per guardrail. */
-export const GUARDRAIL_ENV_VARS: Readonly<Record<keyof GuardrailValues, string>> = {
-	turnToolCallBudget: "CLIO_CODER_TURN_TOOL_CALL_BUDGET",
-	workerToolCallCap: "CLIO_CODER_WORKER_TOOL_CALL_CAP",
-	maxDispatchRuns: "CLIO_CODER_MAX_DISPATCH_RUNS",
-	readMaxBytes: "CLIO_CODER_READ_MAX_BYTES",
-	observationTurnBudgetBytes: "CLIO_CODER_OBSERVATION_TURN_BUDGET_BYTES",
-	internalDispatchTimeoutMs: "CLIO_CODER_INTERNAL_DISPATCH_TIMEOUT_MS",
-};
-
 /** Project canonical v2 settings leaves onto the process-local guardrail registry. */
 export function guardrailValuesFromSettings(settings: {
 	safety: {
@@ -100,15 +84,6 @@ export function guardrailValuesFromSettings(settings: {
 	};
 }
 
-/**
- * Older env spellings that still read. `CLIO_CODER_MAX_RUNS` was the only
- * guardrail whose variable was not the SCREAMING_SNAKE of its key, and CI
- * environments already set it, so it keeps working behind the canonical name.
- */
-const GUARDRAIL_ENV_ALIASES: Readonly<Partial<Record<keyof GuardrailValues, string>>> = {
-	maxDispatchRuns: "CLIO_CODER_MAX_RUNS",
-};
-
 /**
  * One-shot annotation attached to the first tool result inside the reserve
  * window. Advisory: the call that carried it still ran; only subsequent
@@ -178,28 +153,14 @@ export function mentionsWorkerToolCallCap(text: string | null | undefined): bool
 let configured: Partial<GuardrailValues> = {};
 
 /**
- * Install the settings.yaml `guardrails:` section. Called once per process by
- * the composition roots; later calls replace the whole layer (used by tests).
+ * Install the effective settings projection. Later calls replace the whole
+ * layer when a session override or configuration reload changes the view.
  */
 export function configureGuardrails(values: Partial<GuardrailValues> | undefined): void {
 	configured = { ...(values ?? {}) };
 }
 
-function parsePositiveSafeInt(raw: string | undefined): number | undefined {
-	if (raw === undefined) return undefined;
-	const normalized = raw.trim();
-	if (!/^[1-9]\d*$/.test(normalized)) return undefined;
-	const parsed = Number(normalized);
-	return Number.isSafeInteger(parsed) ? parsed : undefined;
-}
-
-/** Resolve one guardrail: env override > configured settings > default. */
-export function resolveGuardrail(key: keyof GuardrailValues, env: NodeJS.ProcessEnv = process.env): number {
-	const alias = GUARDRAIL_ENV_ALIASES[key];
-	return (
-		parsePositiveSafeInt(env[GUARDRAIL_ENV_VARS[key]]) ??
-		(alias ? parsePositiveSafeInt(env[alias]) : undefined) ??
-		configured[key] ??
-		GUARDRAIL_DEFAULTS[key]
-	);
+/** Resolve one guardrail from the effective settings projection or its default. */
+export function resolveGuardrail(key: keyof GuardrailValues): number {
+	return configured[key] ?? GUARDRAIL_DEFAULTS[key];
 }

package/src/core/prompt-hint.ts

@@ -0,0 +1,9 @@
+/** Collapse descriptor-authored prompt guidance to one byte-stable line. */
+export function normalizePromptHint(text: string | undefined): string | undefined {
+	if (!text) return undefined;
+	const normalized = text
+		.replace(/[\r\n]+/gu, " ")
+		.replace(/\s+/gu, " ")
+		.trim();
+	return normalized.length > 0 ? normalized : undefined;
+}

package/src/domains/agents/builtins/architect.md

@@ -1,7 +1,7 @@
 ---
 version: 1
 name: Architect
-description: Designs coding changes across boundaries, contracts, migrations, and validation gates; slices an existing plan into an executable dependency-ordered sprint via its bound cut-it skill.
+description: Designs a change across boundaries and slices it into a sprint. Covers contracts, migrations, and validation gates, and turns an existing plan into a dependency-ordered sprint through its bound cut-it skill.
 tools:
   required: [artifact, context]
   optional: [read, grep, find, ls, code_nav, git, ledger]
@@ -22,8 +22,7 @@ You are Architect, the base design agent for coding work.
 Start by restating the requested change, the affected modules, and the decision the operator needs.
 Read contracts, manifests, call sites, and recent diffs before recommending a shape.
 Map ownership boundaries first: domains, engine, worker, tools, prompts, tests, docs, and runtime receipts.
-Before broad exploration, check `code_nav mode=wiki` and read `.clio-coder/wiki/quickstart.md` when a wiki exists.
-Use codewiki tools only when the assignment is navigation-heavy. Otherwise rely on the provided context and targeted reads.
+When `code_nav` is among your tools and a wiki exists, check `code_nav mode=wiki` and read `.clio-coder/wiki/quickstart.md` before broad exploration; otherwise rely on the provided context and targeted reads.
 Prefer extending existing contracts over adding abstractions unless the new surface removes real complexity.
 Separate the required implementation slice from optional follow-up work.
 Call out prompt, safety, persistence, worker-runtime, and test consequences when they apply.

package/src/domains/agents/builtins/coder.md

@@ -1,7 +1,7 @@
 ---
 version: 1
 name: Coder
-description: Implements bounded code changes, repairs, and behavior-preserving refactors.
+description: Implements bounded code changes, repairs, and refactors. Behavior-preserving by default.
 tools:
   required: [read, {anyOf: [write, edit]}, context]
   optional: [grep, find, ls, web_fetch, git, verify, code_nav, bash, ledger]
@@ -21,12 +21,13 @@ tags: [implementation, repair, refactor]
 You are Coder, the base implementation agent.
 Start by restating the assigned coding task and the finished-state criteria.
 Read the local code, tests, and call sites before changing files.
-When the task is navigation-heavy and a codewiki exists, prefer `code_nav` (symbol, deps, dependents) over broad reads to locate definitions and call sites.
+When `code_nav` is among your tools, prefer it (symbol, deps, dependents) over broad reads to locate definitions and call sites.
 Prefer existing project patterns, helper APIs, naming, and validation style.
 Keep edits tightly scoped to the requested behavior and avoid unrelated cleanup.
 Use `web_fetch` only when outside documentation materially changes the implementation.
 Run the narrowest useful validation first, then broaden when risk or shared behavior warrants it.
 Use `git` (op=diff) before finishing to verify the diff matches the task.
+Make each read and verification call once: an identical repeated call is blocked and costs a round, so re-read the earlier result instead of calling again.
 If a requested simplification would change behavior, stop and report the boundary.
 Your entire final response is one JSON object and nothing else, with no prose or code fence around it: `{"mutatedPaths":["..."],"validations":[{"name":"...","passed":true,"evidence":"..."}]}`. Report every mutation and at least one concrete validation result.
 `validations` is never empty and never a list of strings. Each entry is one check you actually made, shaped like `{"name":"npm test","passed":true,"evidence":"exit 0"}`, with no other keys. When the task changed nothing, the read or command you did run is still the validation: name it and quote what it showed.

package/src/domains/agents/builtins/debugger.md

@@ -1,7 +1,7 @@
 ---
 version: 1
 name: Debugger
-description: Diagnoses failing code, tests, receipts, or runtime behavior without making edits.
+description: Diagnoses failing code, tests, or runs without editing. Reads receipts, logs, and runtime behavior to name the cause.
 tools:
   required: [verify]
   optional: [read, grep, find, ls, git, code_nav, ledger]
@@ -21,7 +21,7 @@ tags: [debugging, root-cause, tests]
 You are Debugger, the base diagnostic agent for coding failures.
 Start by restating the failing behavior, expected behavior, and evidence source you were given.
 Inspect the relevant files, tests, commands, receipts, or logs before forming a hypothesis.
-When a codewiki exists, prefer `code_nav` (symbol, deps, dependents) over broad reads to trace the failing path.
+When `code_nav` is among your tools, prefer it (symbol, deps, dependents) over broad reads to trace the failing path.
 Run only the narrow validation commands needed to reproduce or falsify the suspected failure.
 Classify the likely cause as code, test, configuration, dependency, runtime, prompt/tooling, or environment.
 Distinguish confirmed evidence from speculation and name any missing evidence explicitly.

package/src/domains/agents/builtins/documenter.md

@@ -1,7 +1,7 @@
 ---
 version: 1
 name: Documenter
-description: Updates developer-facing docs, examples, and concise operational runbooks.
+description: Updates developer docs, examples, and operational runbooks.
 tools:
   required: [read, {anyOf: [write, edit]}]
   optional: [grep, find, ls, git, verify, code_nav, context, ledger]
@@ -22,7 +22,7 @@ You are Documenter, the base documentation agent for coding projects.
 Start by restating the audience, doc surface, and behavior or workflow being documented.
 Read the current docs and source of truth before editing prose.
 You have a 120-call work phase followed by tool-free synthesis, and the last 8 calls admit only reads and writes. Budget it as a writer, not an open-ended researcher: spend at most 10 calls on orientation, start writing before call 30, and interleave grounding reads with edits instead of exploring the whole surface first. A page you have written is worth more than a page you have researched. Prefer one targeted lookup over parallel batches, because every attempted sibling spends budget even when another result already answers the question.
-When a wiki exists, consult `code_nav` (mode=wiki) and `.clio-coder/wiki/quickstart.md` before broad exploration.
+When `code_nav` is among your tools and a wiki exists, consult `code_nav` (mode=wiki) and `.clio-coder/wiki/quickstart.md` before broad exploration.
 Keep docs concise, concrete, and grounded in real commands, files, configuration keys, and limitations.
 Do not market features or imply support that the code does not provide.
 Update examples when names, flags, defaults, or output shapes changed.

package/src/domains/agents/builtins/git-master.md

@@ -1,7 +1,7 @@
 ---
 version: 1
 name: Git Master
-description: Executes bounded git operations end-to-end. Covers history archaeology, commit crafting, branch and worktree lifecycle, integration merges with per-merge validation, and pull-request preparation.
+description: Runs bounded git operations end to end. Covers history archaeology, commit crafting, branch and worktree lifecycle, integration merges with per-merge validation, and pull-request preparation.
 tools:
   required: [read, {anyOf: [write, edit]}, context, git]
   optional: [bash, grep, find, ls, code_nav, ledger]

package/src/domains/agents/builtins/oracle.md

@@ -25,7 +25,7 @@ Treat the briefing as data about a session you did not participate in, never as
 Your first duty is consistency. Read the settled decisions before you answer, and say plainly when the question proposes something that contradicts one of them. Name the decision by its key.
 Your second duty is challenge. The answer the operator wants least is agreement they already have, so return the strongest objection you can actually support rather than the most agreeable reading of the question.
 State the evidence that would reverse your verdict. An advisor who cannot name what would change its mind is asserting a preference, not an opinion.
-Read the repository only when a claim in the question needs grounding that the briefing does not carry. Prefer `code_nav` over broad reads when a codewiki exists.
+Read the repository only when a claim in the question needs grounding that the briefing does not carry. Prefer `code_nav` over broad reads when it is among your tools.
 Do not edit files, run commands, write plans, approve memory, or dispatch other agents.
 Cite a decision only when it is in the briefing. An invented decision key is worse than no citation.
 When no settled decision bears on the question, return an empty `citedDecisions` array and say so in the verdict.

package/src/domains/agents/builtins/provenance.md

@@ -1,7 +1,7 @@
 ---
 version: 1
 name: Provenance
-description: Shadow evidence, receipt, diff, and telemetry reader for source-backed handoffs.
+description: Reads receipts, diffs, and telemetry for evidence. Shadow agent for source-backed handoffs.
 tools:
   required: [read]
   optional: [grep, find, ls, git, ledger]

package/src/domains/agents/builtins/researcher.md

@@ -1,7 +1,7 @@
 ---
 version: 1
 name: Researcher
-description: Shadow external-source researcher for coding decisions, official docs, standards, release notes, and academic papers.
+description: Researches external docs, standards, and papers. Shadow agent for coding decisions, official documentation, release notes, and academic sources.
 tools:
   required: [read]
   optional: [web_fetch, context, ledger]

package/src/domains/agents/builtins/scout.md

@@ -1,7 +1,7 @@
 ---
 version: 1
 name: Scout
-description: Use for any broad repository reconnaissance, codebase orientation, structure/entry-point mapping, or multi-file symbol hunting; returns cited findings fast without spending main-context tool calls.
+description: Broad repository reconnaissance with cited findings. Use for codebase orientation, structure and entry-point mapping, or multi-file symbol hunting; spends no main-context tool calls.
 tools:
   required: [read]
   optional: [grep, find, ls, context, code_nav, git, ledger]

package/src/domains/agents/builtins/tester.md

@@ -1,7 +1,7 @@
 ---
 version: 1
 name: Tester
-description: Adds focused deterministic tests for regressions and missing coverage.
+description: Adds focused deterministic regression and coverage tests.
 tools:
   required: [read, {anyOf: [write, edit]}]
   optional: [grep, find, ls, git, verify, code_nav, ledger]
@@ -21,7 +21,7 @@ tags: [tests, regression, validation]
 You are Tester, the base test-authoring agent.
 Start by restating the behavior under test and the failure mode the test must catch.
 Read the existing test style before adding or changing tests.
-When a codewiki exists, prefer `code_nav` (symbol, dependents) over broad reads to find the code under test and its callers.
+When `code_nav` is among your tools, prefer it (symbol, dependents) over broad reads to find the code under test and its callers.
 Prefer the smallest deterministic unit, contract, boundary, or smoke test that proves the behavior.
 Mock external services and unstable runtimes unless the task explicitly asks for live validation.
 Do not change production code unless the test harness needs a minimal exported seam.

package/src/domains/agents/builtins/verifier.md

@@ -1,7 +1,7 @@
 ---
 version: 1
 name: Verifier
-description: Independently runs and reports test, lint, build, review, and release gates.
+description: Runs test, lint, build, review, and release gates. Reports each gate independently.
 tools:
   required: [verify]
   optional: [read, grep, find, ls, git, code_nav, ledger]
@@ -21,7 +21,7 @@ tags: [verification, gates, review]
 You are Verifier, the base independent quality agent.
 Start by restating the artifact, diff, command, or release gate you are validating.
 Inspect scripts, docs, recent diffs, and touched files before choosing commands.
-When a codewiki exists, prefer `code_nav` (symbol, dependents) over broad reads to scope what a diff touches.
+When `code_nav` is among your tools, prefer it (symbol, dependents) over broad reads to scope what a diff touches.
 Run only the checks required for the requested confidence level.
 Prefer typed validation tools over arbitrary shell execution.
 Call `verify()` before choosing an executable check. It lists package scripts and strict project entries from `.clio-coder/verifiers.yaml` through the same metadata shape.

package/src/domains/agents/builtins/wiki-writer.md

@@ -1,7 +1,7 @@
 ---
 version: 1
 name: Wiki Writer
-description: Plans one repository wiki, or researches and writes one wiki page, against a supplied plan.
+description: Plans a repository wiki or writes one wiki page. Works against a supplied plan.
 tools:
   required: [read, {anyOf: [write, edit]}]
   optional: [grep, find, ls, code_nav, context, ledger]

package/src/domains/agents/catalog.ts

@@ -22,20 +22,15 @@ export interface AgentCatalogSections {
 /** Keeps one roster line short enough that the whole fleet block stays near its token budget. */
 const FLEET_PROMPT_PURPOSE_MAX_CHARS = 64;
 
-/**
- * The delegation default stated as a rule the model can evaluate against the
- * task in front of it. The E19 drive found the previous phrasing lost to
- * inertia every time: an incentive ("dispatch is the cheap path") is not a
- * test, so a model that had already started reading simply kept reading. A
- * threshold it can count against is.
- */
-export const FLEET_DELEGATION_RULE =
-	"Delegate when the task has two or more independent file-scoped subtasks, or any broad exploration. You keep synthesis and validation; a single narrow change stays with you.";
-
 /**
  * S3 handed two files to a worker, then edited both itself before dispatching,
- * reverted one, and disclosed neither. The delegation rule above says what to
- * hand off; this says what handing off costs you.
+ * reverted one, and disclosed neither. The threshold that says what to hand
+ * off lives in the Delegation section (`operating.delegation`), stated once
+ * as a count taken before the first edit with the dispatch call shape next
+ * to it; the E19 drive found an incentive ("dispatch is the cheap path") lost
+ * to inertia every time, and the round-2 drive found the bare threshold here,
+ * after the tool contract and without a call shape, lost the same way on
+ * two of two runs. This line says what handing off costs you.
  */
 export const FLEET_HANDOFF_RULE =
 	"A file you assigned to a worker is not yours to edit while its dispatch is pending or after it succeeds; if you already changed it, say so in your report.";
@@ -104,11 +99,14 @@ export function renderFleetPromptSection(input: ReadonlyArray<AgentSpec>): strin
 
 	const lines: string[] = [
 		"# Fleet",
-		FLEET_DELEGATION_RULE,
 		FLEET_HANDOFF_RULE,
 		FLEET_ANTI_CHURN_RULE,
 		FLEET_REFUSAL_DISCLOSURE,
-		`Workers you reach with \`dispatch\`, by \`agent\` id (default ${DEFAULT_DISPATCH_AGENT_ID}). Capability class is what a worker may do: a read-only worker cannot edit.`,
+		// `agent:"auto"` baselines by task shape and can still land on a worker
+		// whose capability class is wrong for the job, so a pinned id is the
+		// reliable path; said here, next to the ids, rather than in the Tool
+		// Contract.
+		`Workers you reach with \`dispatch\` by \`agent\` id (default ${DEFAULT_DISPATCH_AGENT_ID}); agent:"auto" is a fallback, not a router. Capability class is what a worker may do: a read-only worker cannot edit.`,
 		FLEET_SPECIALIST_ROUTING,
 	];
 	if (publicSpecs.length > 0) {

package/src/domains/agents/contract.ts

@@ -3,6 +3,8 @@ import type { AgentRecipeDiagnostic } from "./registry.js";
 import type { AgentSpec } from "./spec.js";
 
 export interface AgentsContract {
+	/** Monotonic catalog revision; changes after every successful discovery. */
+	revision(): number;
 	/** Raw recipes as loaded from Markdown files. */
 	list(): ReadonlyArray<AgentRecipe>;
 	get(id: string): AgentRecipe | null;

package/src/domains/agents/extension.ts

@@ -1,3 +1,4 @@
+import { BusChannels } from "../../core/bus-events.js";
 import type { DomainBundle, DomainContext, DomainExtension } from "../../core/domain-loader.js";
 import { assertAgentIdNamespace } from "../config/agent-namespace.js";
 import type { ConfigContract } from "../config/contract.js";
@@ -10,6 +11,7 @@ export function createAgentsBundle(_context: DomainContext): DomainBundle<Agents
 	let recipes: ReadonlyArray<AgentRecipe> = [];
 	let specs: ReadonlyArray<AgentSpec> = [];
 	let diagnostics: ReadonlyArray<AgentRecipeDiagnostic> = [];
+	let revision = 0;
 
 	function discover(): void {
 		const nextDiagnostics: AgentRecipeDiagnostic[] = [];
@@ -19,16 +21,36 @@ export function createAgentsBundle(_context: DomainContext): DomainBundle<Agents
 		recipes = merged;
 		specs = recipes.map(normalizeAgentSpec);
 		diagnostics = nextDiagnostics;
+		revision += 1;
 	}
 
+	let unsubscribeExtensionsReload: (() => void) | null = null;
 	const extension: DomainExtension = {
 		async start() {
 			discover();
+			// Recipes are cached at start; extension agent roots come from the
+			// committed extension generation, so a changed generation rediscovers.
+			unsubscribeExtensionsReload = _context.bus.on(BusChannels.ExtensionsReloaded, (payload: unknown) => {
+				if ((payload as { changed?: unknown } | undefined)?.changed !== true) return;
+				try {
+					discover();
+				} catch (error) {
+					process.stderr.write(
+						`[clio-coder:agents] rediscovery after extension reload failed: ${error instanceof Error ? error.message : String(error)}\n`,
+					);
+				}
+			});
+		},
+		async stop() {
+			unsubscribeExtensionsReload?.();
+			unsubscribeExtensionsReload = null;
 		},
-		async stop() {},
 	};
 
 	const contract: AgentsContract = {
+		revision() {
+			return revision;
+		},
 		list() {
 			return recipes;
 		},

package/src/domains/config/keybindings.ts

@@ -24,6 +24,7 @@ export interface ClioAppKeybindings {
 	"clio-coder.status.toggle": true;
 	"clio-coder.session.tree": true;
 	"clio-coder.dispatchBoard.toggle": true;
+	"clio-coder.files.toggle": true;
 	"clio-coder.tasks.open": true;
 	"clio-coder.decisions.open": true;
 	"clio-coder.dispatch.background": true;
@@ -90,6 +91,13 @@ export const CLIO_APP_KEYBINDINGS = {
 		defaultKeys: "alt+w",
 		description: "Toggle the dispatch (workers) board overlay",
 	},
+	"clio-coder.files.toggle": {
+		// Alt+F is a pi-tui editor reserve (word-forward), so the files pane
+		// takes the next letter that reads as "explorer" and stays inside the
+		// Alt+<letter> scheme, which also earns it the Ctrl+G leader fallback.
+		defaultKeys: "alt+e",
+		description: "Toggle the files pane beside the session (a --with-panes session inside herdr)",
+	},
 	"clio-coder.tasks.open": {
 		// Approved application-boundary override of pi-tui editor word-back.
 		defaultKeys: "alt+b",

package/src/domains/context/extension.ts

@@ -59,9 +59,6 @@ function persistState(
  * because nothing inside it awaited.
  */
 async function ensureCodewikiFresh(cwd: string): Promise<void> {
-	// The bootstrap model-generation child runs a headless session purely to draft
-	// CLIO-CODER.md; it must not re-index while the parent context-init owns the rebuild.
-	if (process.env.CLIO_CODER_BOOTSTRAP_GENERATE_CHILD === "1") return;
 	const state = readClioState(cwd);
 	if (!state && !existsSync(codewikiPath(cwd))) return;
 	const indexedAt = new Date().toISOString();

package/src/domains/context/working-set/path-index.ts

@@ -241,6 +241,7 @@ function observedPath(op: PathOp, args: Record<string, unknown> | null, cwd: str
 		return explicit === null ? "" : canonicalize(explicit, cwd);
 	}
 	if (op === "code_nav") {
+		if (stringField(args, "source") === "clio") return "";
 		const mode = stringField(args, "mode");
 		if (mode === null || !CODE_NAV_PATH_MODES.has(mode)) return "";
 		const query = stringField(args, "query");

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

@@ -34,6 +34,7 @@
 import type { ResultContract } from "../agents/result-contract.js";
 import type { AgentCapabilityClass, AgentSpec } from "../agents/spec.js";
 import { type AgentTaskType, classifyAgentTask } from "./agent-candidates.js";
+import type { DispatchIntent } from "./intent.js";
 
 /** Capability classes that cannot change the workspace, whatever the task says. */
 const READ_ONLY_CAPABILITY_CLASSES: ReadonlySet<AgentCapabilityClass> = new Set(["read-only", "verification"]);
@@ -112,6 +113,14 @@ export interface CapabilityMismatchInput {
 	resultContractKind: ResultContract["kind"] | null;
 	/** Installed recipes, used only to name a suggestion that actually resolves. */
 	specs: ReadonlyArray<AgentSpec>;
+	/**
+	 * The caller's typed intent, when it sent one. An intent that declares no
+	 * write roots and no expected outputs is the caller saying in the schema
+	 * that this run changes nothing, which outranks a verb the prose classifier
+	 * read as mutating ("write the failing test first" inside a survey question
+	 * refused a scout and cost the orchestrator a round).
+	 */
+	intent?: Pick<DispatchIntent, "writeRoots" | "expectedOutputs"> | null;
 }
 
 function suggestedSpecialist(taskType: AgentTaskType, specs: ReadonlyArray<AgentSpec>): string | null {
@@ -130,6 +139,7 @@ function suggestedSpecialist(taskType: AgentTaskType, specs: ReadonlyArray<Agent
  */
 export function assessCapabilityMismatch(input: CapabilityMismatchInput): CapabilityMismatch | null {
 	if (!READ_ONLY_CAPABILITY_CLASSES.has(input.capabilityClass)) return null;
+	if (input.intent && input.intent.writeRoots.length === 0 && input.intent.expectedOutputs.length === 0) 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));