@iowarp/clio-coder 0.3.9 → 0.4.1

package/src/tools/dispatch-run-events.ts

@@ -1,7 +1,9 @@
 import { BusChannels } from "../core/bus-events.js";
 import type { SafeEventBus } from "../core/event-bus.js";
+import { normalizeClioCoderEventRecord, normalizeClioCoderEventType } from "../core/naming-events.js";
 import type { DispatchContract } from "../domains/dispatch/contract.js";
 import { durableAssistantTextFromEvent } from "../domains/dispatch/event-pump.js";
+import { defaultRunEventJournal, type RunEventJournalSink } from "../domains/dispatch/run-event-journal.js";
 import type { RunReceipt } from "../domains/dispatch/types.js";
 import { assistantTextFromEvent } from "./dispatch-event-text.js";
 import { truncateUtf8 } from "./truncate-utf8.js";
@@ -60,27 +62,113 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 }
 
 function eventDetail(event: unknown): string | undefined {
-	const text = assistantTextFromEvent(event);
+	const normalized = isRecord(event) ? normalizeClioCoderEventRecord(event) : event;
+	const text = assistantTextFromEvent(normalized);
 	if (text.length > 0) return truncateUtf8(text, RUN_TAIL_TEXT_LIMIT, "...");
-	if (!isRecord(event)) return undefined;
-	if (event.type === "clio_tool_finish" && isRecord(event.payload)) {
-		const tool = typeof event.payload.tool === "string" ? event.payload.tool : "tool";
-		const outcome = typeof event.payload.outcome === "string" ? event.payload.outcome : "";
+	if (!isRecord(normalized)) return undefined;
+	if (normalized.type === "clio_coder_tool_finish" && isRecord(normalized.payload)) {
+		const tool = typeof normalized.payload.tool === "string" ? normalized.payload.tool : "tool";
+		const outcome = typeof normalized.payload.outcome === "string" ? normalized.payload.outcome : "";
 		return `${tool} ${outcome}`.trim();
 	}
-	if (event.type === "attempt_start") {
-		const attempt = typeof event.attempt === "number" ? event.attempt : "?";
-		const runId = typeof event.runId === "string" ? event.runId : "?";
-		const reason = typeof event.reason === "string" ? event.reason : "retry";
+	if (normalized.type === "attempt_start") {
+		const attempt = typeof normalized.attempt === "number" ? normalized.attempt : "?";
+		const runId = typeof normalized.runId === "string" ? normalized.runId : "?";
+		const reason = typeof normalized.reason === "string" ? normalized.reason : "retry";
 		return truncateUtf8(`attempt ${attempt} -> ${runId}: ${reason}`, RUN_TAIL_TEXT_LIMIT, "...");
 	}
 	return undefined;
 }
 
-export function createDispatchRunEventRegistry(): DispatchRunEventRegistry {
+/**
+ * Project one worker/ACP event into the display tail, or null when the event is
+ * not tail-visible. Heartbeats and streaming `message_update` increments are
+ * noise on a transcript: the tail keeps message boundaries, not deltas.
+ *
+ * The durable journal writes exactly this projection, so a transcript read back
+ * by `clio-coder fleet view` and the monitor's live peek cannot disagree about
+ * what a run did. Both the registry below and the domain-owned journal bridge
+ * (src/domains/dispatch/run-event-journal-bridge.ts) call it.
+ */
+export function runTailEntryFromEvent(event: unknown, at: string = new Date().toISOString()): RunTailEntry | null {
+	const type = isRecord(event) && typeof event.type === "string" ? normalizeClioCoderEventType(event.type) : "unknown";
+	if (type === "heartbeat" || type === "message_update") return null;
+	const entry: RunTailEntry = { at, type };
+	const detail = eventDetail(event);
+	if (detail !== undefined) entry.detail = detail;
+	return entry;
+}
+
+export interface DispatchRunEventRegistryOptions {
+	/**
+	 * Durable tee for the display tail. Omitted takes the process-wide default
+	 * journal (settings-gated by `panes.journal`); `null` turns it off for this
+	 * registry. This is the one wiring choke point: every registry in the
+	 * process is built by this factory, so the sink attaches here rather than at
+	 * each of the three construction sites that call it.
+	 */
+	journal?: RunEventJournalSink | null;
+}
+
+/** Outcome recorded for a run whose completion rejected before a receipt existed. */
+const REGISTRY_FAILURE_OUTCOME = "failed";
+/** Outcome recorded when a receipt settled without a readable outcome field. */
+const REGISTRY_UNKNOWN_OUTCOME = "unknown";
+
+function errorText(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+export function createDispatchRunEventRegistry(
+	options: DispatchRunEventRegistryOptions = {},
+): DispatchRunEventRegistry {
 	const runTails = new Map<string, RunTailState>();
 	const activeRuns = new Set<string>();
 	const activeBatches = new Set<string>();
+	const journal: RunEventJournalSink | null = options.journal === undefined ? defaultRunEventJournal() : options.journal;
+
+	/**
+	 * Seal one logical run in the journal. `logicalRunId` is the id an operator
+	 * asked about; a retried run's receipt carries the terminal attempt's id
+	 * instead, and that only ever appears as a field on the line.
+	 */
+	const journalSeal = (logicalRunId: string, receipt: RunReceipt): void => {
+		if (journal === null || !isRecord(receipt)) return;
+		// Every field is read defensively. The journal sits on the completion path
+		// of every dispatch, and a receipt that is missing a block it is typed to
+		// have (a stubbed contract, a truncated read) must degrade the transcript,
+		// never reject the completion the caller is awaiting.
+		const digest = receipt.integrity?.digest;
+		const outcome = typeof receipt.outcome === "string" ? receipt.outcome : REGISTRY_UNKNOWN_OUTCOME;
+		journal.receipt(logicalRunId, {
+			outcome,
+			exitCode: typeof receipt.exitCode === "number" ? receipt.exitCode : null,
+			...(typeof digest === "string" ? { digest } : {}),
+			...(receipt.runId !== logicalRunId ? { attemptRunId: receipt.runId } : {}),
+		});
+		journal.terminal(logicalRunId, outcome, receipt.outcomeDetail ?? undefined);
+	};
+
+	/**
+	 * Seal a batch's journals. `assignmentIds` are the logical work ids in
+	 * admission order and `dispatchBatch` resolves one receipt per request, so
+	 * equal lengths pair by index. Anything else pairs by the receipt's own run
+	 * id and leaves unmatched assignments without a terminal line rather than
+	 * inventing an outcome for them.
+	 */
+	const sealBatchJournals = (assignmentIds: ReadonlyArray<string>, receipts: ReadonlyArray<RunReceipt>): void => {
+		if (journal === null || !Array.isArray(receipts)) return;
+		if (assignmentIds.length === receipts.length) {
+			for (const [index, runId] of assignmentIds.entries()) {
+				const receipt = receipts[index];
+				if (receipt !== undefined) journalSeal(runId, receipt);
+			}
+			return;
+		}
+		for (const receipt of receipts) {
+			if (receipt != null && typeof receipt.runId === "string") journalSeal(receipt.runId, receipt);
+		}
+	};
 
 	const pruneRunTails = (): void => {
 		while (runTails.size > RUN_TAIL_RUN_LIMIT) {
@@ -97,19 +185,20 @@ export function createDispatchRunEventRegistry(): DispatchRunEventRegistry {
 	};
 
 	const recordRunEvent = (runId: string, agentId: string, event: unknown): void => {
-		const type = isRecord(event) && typeof event.type === "string" ? event.type : "unknown";
-		if (type === "heartbeat" || type === "message_update") return;
+		const entry = runTailEntryFromEvent(event);
+		if (entry === null) return;
 		const state = runTails.get(runId) ?? { agentId, entries: [], lastSeenAt: Date.now() };
 		state.lastSeenAt = Date.now();
-		const entry: RunTailEntry = { at: new Date().toISOString(), type };
-		const detail = eventDetail(event);
-		if (detail !== undefined) entry.detail = detail;
 		state.entries.push(entry);
 		if (state.entries.length > RUN_TAIL_ENTRY_LIMIT) {
 			state.entries.splice(0, state.entries.length - RUN_TAIL_ENTRY_LIMIT);
 		}
 		runTails.set(runId, state);
 		pruneRunTails();
+		// The journal is a tee of exactly this projection, appended after the
+		// in-memory tail is already updated so a sink that degrades cannot change
+		// what `eventTail` returns.
+		journal?.append(runId, entry);
 	};
 
 	const drainSingle = async (
@@ -172,6 +261,7 @@ export function createDispatchRunEventRegistry(): DispatchRunEventRegistry {
 				throw new Error(`dispatch event registry: run '${handle.runId}' is already registered`);
 			}
 			activeRuns.add(handle.runId);
+			journal?.open(handle.runId, agentId);
 			const summaryPromise = drainSingle(handle.runId, agentId, handle.events, bus);
 			const completion = Promise.allSettled([summaryPromise, handle.finalPromise]).then(
 				([summaryResult, receiptResult]) => {
@@ -180,12 +270,24 @@ export function createDispatchRunEventRegistry(): DispatchRunEventRegistry {
 					return { receipt: receiptResult.value, summary: summaryResult.value };
 				},
 			);
-			void completion
-				.finally(() => {
-					activeRuns.delete(handle.runId);
-					pruneRunTails();
-				})
-				.catch(() => {});
+			// One subscription, not a `.then().finally()` chain. Chaining pushes the
+			// tail release a microtask later than it used to land, and a caller that
+			// awaits `completion` and then reads `eventTail` observes the run as
+			// still active. Journal and release settle together in this handler.
+			const releaseSingle = (): void => {
+				activeRuns.delete(handle.runId);
+				pruneRunTails();
+			};
+			void completion.then(
+				({ receipt }) => {
+					journalSeal(handle.runId, receipt);
+					releaseSingle();
+				},
+				(error: unknown) => {
+					journal?.terminal(handle.runId, REGISTRY_FAILURE_OUTCOME, errorText(error));
+					releaseSingle();
+				},
+			);
 			return { runId: handle.runId, completion };
 		},
 		registerBatch(handle, agentIds, bus) {
@@ -204,6 +306,9 @@ export function createDispatchRunEventRegistry(): DispatchRunEventRegistry {
 			}
 			activeBatches.add(handle.batchId);
 			for (const runId of handle.assignmentIds) activeRuns.add(runId);
+			for (const [index, runId] of handle.assignmentIds.entries()) {
+				journal?.open(runId, agentIds[index] ?? "unknown");
+			}
 			const completion = Promise.allSettled([drainBatch(handle.batchId, handle.events, bus), handle.finalPromise]).then(
 				([summariesResult, receiptsResult]) => {
 					if (summariesResult.status === "rejected") throw summariesResult.reason;
@@ -211,13 +316,25 @@ export function createDispatchRunEventRegistry(): DispatchRunEventRegistry {
 					return { receipts: receiptsResult.value, summaries: summariesResult.value };
 				},
 			);
-			void completion
-				.finally(() => {
-					activeBatches.delete(handle.batchId);
-					for (const runId of handle.assignmentIds) activeRuns.delete(runId);
-					pruneRunTails();
-				})
-				.catch(() => {});
+			// Single subscription for the same reason as registerSingle above.
+			const releaseBatch = (): void => {
+				activeBatches.delete(handle.batchId);
+				for (const runId of handle.assignmentIds) activeRuns.delete(runId);
+				pruneRunTails();
+			};
+			void completion.then(
+				({ receipts }) => {
+					sealBatchJournals(handle.assignmentIds, receipts);
+					releaseBatch();
+				},
+				(error: unknown) => {
+					const detail = errorText(error);
+					for (const runId of handle.assignmentIds) {
+						journal?.terminal(runId, REGISTRY_FAILURE_OUTCOME, detail);
+					}
+					releaseBatch();
+				},
+			);
 			for (const [index, runId] of handle.assignmentIds.entries()) {
 				if (!runTails.has(runId)) {
 					runTails.set(runId, {

package/src/tools/dispatch-runner.ts

@@ -40,6 +40,7 @@ import {
 	REVIEWER_GATE_PROMPT,
 	renderCouncilVoteMemberTask,
 } from "../domains/dispatch/gate-role-prompts.js";
+import { narrowDispatchIntentToReadOnly } from "../domains/dispatch/intent.js";
 import { renderDispatchReviewerTask } from "../domains/dispatch/intent-requirements.js";
 import { UNVERIFIABLE_RECEIPT_VERIFICATION } from "../domains/dispatch/receipt-findings.js";
 import { type ReceiptIntegrityResult, verifyReceiptIntegrity } from "../domains/dispatch/receipt-integrity.js";
@@ -56,7 +57,8 @@ import {
 	claimCompeteGroup,
 	cleanupCompeteGroup,
 	commitCandidateWork,
-	createCandidateWorktree,
+	competeBranchForCandidate,
+	createCandidateWorktreeMapped,
 	isGitRepository,
 	loadCompeteGroup,
 	markCompeteGroupCleanupReady,
@@ -65,7 +67,7 @@ import {
 	protectedPathsChangedByCompeteBranch,
 	recoverCleanupReadyCompeteGroups,
 	registerCompeteGroupRun,
-	removeCandidateWorktree,
+	removeCandidateWorktreeMapped,
 	settleCompeteGroupRun,
 	settleRecoveredCompeteDecision,
 } from "./compete-worktrees.js";
@@ -963,6 +965,8 @@ function recoverPendingGateEvidence(deps: DispatchToolDeps): void {
 		const pick = judged?.ok ? judged.result.winner : null;
 		const pickedSubject = pick === null ? undefined : record.subjects[pick - 1];
 		const candidateReceipt = pickedSubject === undefined ? null : readVerifiedGateReceipt(deps, pickedSubject.runId);
+		const root = record.resourceRoot ?? process.cwd();
+		const pickedBranch = pick === null ? null : competeBranchForCandidate(root, record.group, pick);
 		if (pickedSubject !== undefined && candidateReceipt === null) {
 			throw new Error(
 				`pending compete decision ${record.id} has no verified candidate receipt for ${pickedSubject.runId}`,
@@ -970,11 +974,10 @@ function recoverPendingGateEvidence(deps: DispatchToolDeps): void {
 		}
 		let blockedProtected: string[] = [];
 		if (pick !== null && pickedSubject !== undefined && candidateReceipt !== null) {
-			const root = record.resourceRoot ?? process.cwd();
 			const protectedPaths = deps.dispatch.protectedArtifactState?.().artifacts.map((artifact) => artifact.path) ?? [];
 			blockedProtected = protectedPathsChangedByCompeteBranch(
 				root,
-				`clio/compete/${record.group}/${pick}`,
+				pickedBranch ?? `clio-coder/compete/${record.group}/${pick}`,
 				protectedPaths,
 			);
 		}
@@ -984,7 +987,7 @@ function recoverPendingGateEvidence(deps: DispatchToolDeps): void {
 			candidateReceipt !== null &&
 			!isPipelineStepFailure(candidateReceipt) &&
 			blockedProtected.length === 0;
-		if (validWinner && pick !== null && pickedSubject !== undefined) {
+		if (validWinner && pick !== null && pickedSubject !== undefined && pickedBranch !== null) {
 			draft = {
 				group: record.group,
 				topology: "compete",
@@ -996,7 +999,7 @@ function recoverPendingGateEvidence(deps: DispatchToolDeps): void {
 				winner: {
 					index: pick,
 					subject: pickedSubject,
-					branch: `clio/compete/${record.group}/${pick}`,
+					branch: pickedBranch,
 				},
 			};
 		} else {
@@ -1255,10 +1258,14 @@ async function runCompete(
 			// every branch and worktree created below is covered by finalization.
 			ownership = claimCompeteGroup(requestedRoot, group);
 			const root = ownership.root;
-			const createCandidate = deps.competeWorktrees?.createCandidate ?? createCandidateWorktree;
 			for (let index = 1; index <= compete.candidates; index += 1) {
 				throwIfStopped();
-				worktrees.push(createCandidate(ownership, index, "HEAD"));
+				const customCreate = deps.competeWorktrees?.createCandidate;
+				worktrees.push(
+					await (customCreate
+						? customCreate(ownership, index, "HEAD")
+						: createCandidateWorktreeMapped(ownership, index, "HEAD", deps.competeWorktrees?.mux)),
+				);
 			}
 
 			if (timeoutMs !== undefined) {
@@ -1287,7 +1294,12 @@ async function runCompete(
 						executionRole: "builder",
 						cwd: worktree.path,
 						protectedArtifactRemap: { sourceRoot: root, workerRoot: worktree.path },
-						gate: { role: "candidate", group, cycle: worktree.index },
+						gate: {
+							role: "candidate",
+							group,
+							cycle: worktree.index,
+							...(worktree.provenance ? { worktree: worktree.provenance } : {}),
+						},
 						ledger,
 						competeStance: COMPETE_STANCES[(worktree.index - 1) % COMPETE_STANCES.length] as CompeteStance,
 					};
@@ -1523,7 +1535,7 @@ async function runCompete(
 				for (const worktree of worktrees) {
 					if (worktree.index === winnerAtFinalization.index) continue;
 					try {
-						removeCandidateWorktree(ownership, worktree, true);
+						await removeCandidateWorktreeMapped(ownership, worktree, true, deps.competeWorktrees?.mux);
 					} catch (err) {
 						finalizationErrors.push(err);
 					}
@@ -1540,8 +1552,13 @@ async function runCompete(
 				finalizationErrors.push(err);
 			}
 			try {
+				if (deps.competeWorktrees?.mux) {
+					for (const worktree of worktrees) {
+						await removeCandidateWorktreeMapped(ownership, worktree, true, deps.competeWorktrees.mux);
+					}
+				}
 				const cleanupGroup = deps.competeWorktrees?.cleanupGroup ?? cleanupCompeteGroup;
-				cleanupGroup(ownership);
+				await cleanupGroup(ownership);
 			} catch (err) {
 				finalizationErrors.push(err);
 			}
@@ -1584,9 +1601,12 @@ function runApplyWinner(
 		};
 	}
 	const branch = input.branch;
-	const match = /^clio\/compete\/([A-Za-z0-9][A-Za-z0-9._-]{0,127})\/([1-9]\d*)$/.exec(branch);
+	const match = /^(?:clio-coder|clio)\/compete\/([A-Za-z0-9][A-Za-z0-9._-]{0,127})\/([1-9]\d*)$/.exec(branch);
 	if (!match) {
-		return { kind: "error", message: "dispatch: apply_winner.branch must be a clio/compete/<group>/<n> branch" };
+		return {
+			kind: "error",
+			message: "dispatch: apply_winner.branch must be a clio-coder/compete/<group>/<n> branch",
+		};
 	}
 	const group = match[1] ?? "";
 	const winnerIndex = Number.parseInt(match[2] ?? "", 10);
@@ -1885,6 +1905,13 @@ async function runCouncil(
 					executionRole: "researcher",
 					autonomy: "read-only",
 					toolProfile: "council-read-only",
+					// Admission already demoted the caller's declared write roots to
+					// read roots for every planned member, and the resolved-plan pin
+					// below carries that narrowed intent in. Repeat it here so the
+					// no-plan fallback path lands on the same request: a member spread
+					// from `base` would otherwise inherit a write scope its read-only
+					// autonomy cannot grant, and the two paths would disagree.
+					...(base.intent === undefined ? {} : { intent: narrowDispatchIntentToReadOnly(base.intent) }),
 					// A vote is a majority over the members' verdict fields, so a vote
 					// council asks each member for one and seals the ballot it asked
 					// for. The seated recipe is untouched: the ask is a task suffix and

package/src/tools/dispatch-types.ts

@@ -3,7 +3,13 @@ import type { AgentSpec } from "../domains/agents/spec.js";
 import type { DispatchContract, DispatchRequest } from "../domains/dispatch/contract.js";
 import type { AgentRoleFactsResolver } from "../domains/dispatch/execution-role.js";
 import type { AutonomyLevel } from "../domains/safety/autonomy.js";
-import type { cleanupCompeteGroup, createCandidateWorktree, mergeWinnerBranch } from "./compete-worktrees.js";
+import type {
+	CandidateWorktree,
+	CompeteGroupOwnership,
+	CompeteMuxWorktrees,
+	cleanupCompeteGroup,
+	mergeWinnerBranch,
+} from "./compete-worktrees.js";
 import type { DispatchBackgroundRegistry } from "./dispatch-background.js";
 import type { DispatchPlanView, ResolvedDispatchPlanArtifact } from "./dispatch-plan.js";
 import type { DispatchRunEventRegistry } from "./dispatch-run-events.js";
@@ -83,9 +89,15 @@ export interface DispatchToolDeps {
 	background?: DispatchBackgroundRegistry;
 	/** Optional compete storage overrides for alternate backends and deterministic fault tests. */
 	competeWorktrees?: {
-		createCandidate?: typeof createCandidateWorktree;
-		cleanupGroup?: typeof cleanupCompeteGroup;
+		createCandidate?: (
+			ownership: CompeteGroupOwnership,
+			index: number,
+			baseline: string,
+		) => CandidateWorktree | Promise<CandidateWorktree>;
+		cleanupGroup?: (...args: Parameters<typeof cleanupCompeteGroup>) => void | Promise<void>;
 		mergeWinner?: typeof mergeWinnerBranch;
+		/** Optional herdr route; every operation retains native Git fallback. */
+		mux?: CompeteMuxWorktrees;
 	};
 	getAgentCatalog?: () => string;
 	getAgentSpecs: () => ReadonlyArray<AgentSpec>;

package/src/tools/dispatch.ts

@@ -80,7 +80,7 @@ const DispatchIntentSchema = Type.Object(
 	{
 		additionalProperties: false,
 		description:
-			"Typed repository-relative path and output intent. Verification checks are declared ids from package scripts or .clio-coder/verifiers.yaml, not shell commands.",
+			"Typed repository-relative path and output intent. Declare it on every dispatch: declared paths select the project rules that apply to them and pin worker context, and omitting it falls back to reading path-like tokens out of your task and briefing text, which can miss an applicable rule. Verification checks are declared ids from package scripts or .clio-coder/verifiers.yaml, not shell commands. In a batch, per-task intent narrows the top-level intent and is refused if it reaches outside it.",
 	},
 );
 
@@ -252,7 +252,7 @@ export function createDispatchTool(
 			apply_winner: Type.Optional(
 				Type.Object(
 					{
-						branch: Type.String({ description: "Preserved winner branch: clio/compete/<group>/<n>." }),
+						branch: Type.String({ description: "Preserved winner branch: clio-coder/compete/<group>/<n>." }),
 						cwd: Type.Optional(Type.String({ description: "Repository root (default: current directory)." })),
 					},
 					{

package/src/tools/executables.ts

@@ -1,17 +1,4 @@
-import { statSync } from "node:fs";
-import { delimiter, join } from "node:path";
-
-function findExecutableOnPath(name: string): string | null {
-	const pathEnv = process.env.PATH;
-	if (!pathEnv) return null;
-	for (const dir of pathEnv.split(delimiter)) {
-		if (!dir) continue;
-		const candidate = join(dir, name);
-		const stat = statSync(candidate, { throwIfNoEntry: false });
-		if (stat?.isFile() && (stat.mode & 0o111) !== 0) return candidate;
-	}
-	return null;
-}
+import { findExecutableOnPath, resolveToolBinary } from "../domains/toolchain/resolve.js";
 
 export function resolveFdBinary(): string | null {
 	return findExecutableOnPath("fd") ?? findExecutableOnPath("fdfind");
@@ -20,3 +7,19 @@ export function resolveFdBinary(): string | null {
 export function resolveRgBinary(): string | null {
 	return findExecutableOnPath("rg");
 }
+
+/**
+ * Resolve any executable Clio might run, through the toolchain ladder.
+ *
+ * For a name in the pinned registry the answer is PATH when the copy there
+ * clears the pin's floor, then Clio's vendored copy, then null. For anything
+ * else it is a plain PATH lookup, which is what `resolveFdBinary` and
+ * `resolveRgBinary` above already do for the two search tools Clio never
+ * vendors.
+ *
+ * Callers that need to explain the answer (doctor, `clio-coder tools status`)
+ * want `resolveToolBinary` instead: this returns only the path to run.
+ */
+export function resolveBinary(name: string): string | null {
+	return resolveToolBinary(name).binaryPath;
+}

package/src/tools/find.ts

@@ -31,12 +31,7 @@ type FindOrder = "path" | "mtime";
 // Build fd's argv. Ignore semantics (hidden files, .gitignore honoring,
 // generated-dir excludes, include_ignored) come entirely from the shared
 // ignore policy so grep and find never disagree about tree visibility.
-export function buildFdArgs(
-	pattern: string,
-	searchPath: string,
-	maxResults: number,
-	includeIgnored: boolean,
-): string[] {
+function buildFdArgs(pattern: string, searchPath: string, maxResults: number, includeIgnored: boolean): string[] {
 	const args = ["--glob", "--color=never", ...fdIgnoreArgs(searchPath, includeIgnored)];
 	args.push("--max-results", String(maxResults));
 	let effectivePattern = pattern;

package/src/tools/monitor.ts

@@ -214,16 +214,16 @@ const TOOLS_MAX_BYTES = 8 * 1024;
 const TOOLS_ARGUMENTS_CHARS = 160;
 
 /**
- * Tail event types that describe one tool call. `clio_tool_finish` is the
+ * Tail event types that describe one tool call. `clio_coder_tool_finish` is the
  * authoritative per-call outcome (it distinguishes a permission block from a
  * command that ran and exited nonzero); the engine's own `tool_execution_end`
  * is kept only when the tail recorded a detail for it, since a bare type line
  * says nothing the finish event does not.
  */
 const TOOL_CALL_EVENT_TYPES: ReadonlySet<string> = new Set([
-	"clio_tool_finish",
-	"clio_permission_resolved",
-	"clio_permission_escalated",
+	"clio_coder_tool_finish",
+	"clio_coder_permission_resolved",
+	"clio_coder_permission_escalated",
 ]);
 
 function toolCallLines(entries: ReadonlyArray<{ at: string; type: string; detail?: string }>): string[] {

package/src/tools/observation.ts

@@ -70,9 +70,29 @@ export const OBSERVATION_TURN_BUDGET_ENV = GUARDRAIL_ENV_VARS.observationTurnBud
 const MIN_BUDGET_SLICE_BYTES = 1024;
 const BUDGET_TRACK_LIMIT = 256;
 
+/**
+ * How many exhausted-pool notices one turn gets before the next such call fails
+ * terminally instead of returning a retryable notice.
+ *
+ * Smoke pass 2 (G2) watched a 9B local model re-issue the identical read about
+ * twenty times against the same 208-byte notice, until the unrelated tool-call
+ * budget stopped it. The notice cannot become un-retryable by wording alone: a
+ * `kind:"ok"` result is an invitation to try again.
+ *
+ * Three is the smallest count that still lets a model learn the shape from the
+ * notice itself. The pool is shared by six OBSERVE tools, so a model that reads,
+ * then greps narrower, then lists, has spent three honest attempts at the advice
+ * the notice gives. A fourth consecutive exhausted call is evidence the advice
+ * is not landing, and it fails. Waste is bounded at four calls out of the 60-call
+ * turn budget instead of twenty.
+ */
+const MAX_EXHAUSTED_NOTICES_PER_TURN = 3;
+
 interface TurnBudgetState {
 	usedBytes: number;
 	lastSeenAt: number;
+	/** Consecutive exhausted-pool short-circuits; reset by any call that got a slice. */
+	exhaustedStreak: number;
 }
 
 const turnBudgets = new Map<string, TurnBudgetState>();
@@ -156,7 +176,7 @@ export function reserveObservation(selfCapBytes: number, options?: ToolInvokeOpt
 		};
 	}
 	const limitBytes = observationTurnBudgetLimit();
-	const state = turnBudgets.get(key) ?? { usedBytes: 0, lastSeenAt: Date.now() };
+	const state = turnBudgets.get(key) ?? { usedBytes: 0, lastSeenAt: Date.now(), exhaustedStreak: 0 };
 	state.lastSeenAt = Date.now();
 	turnBudgets.set(key, state);
 	pruneBudgetMap();
@@ -174,6 +194,9 @@ export function reserveObservation(selfCapBytes: number, options?: ToolInvokeOpt
 			settled: false,
 		};
 	}
+	// A call that got a slice is progress, so the exhausted streak starts over.
+	// Only an unbroken run of short-circuits reaches the terminal failure.
+	state.exhaustedStreak = 0;
 	const callCapBytes = Math.min(selfCapBytes, remaining);
 	return {
 		key,
@@ -203,6 +226,7 @@ export function commitObservationReservation(reservation: ObservationReservation
 	const state = turnBudgets.get(reservation.key) ?? {
 		usedBytes: reservation.usedBeforeBytes,
 		lastSeenAt: Date.now(),
+		exhaustedStreak: 0,
 	};
 	state.usedBytes += reservation.callCapBytes;
 	state.lastSeenAt = Date.now();
@@ -237,6 +261,7 @@ function recordSpentBytes(reservation: ObservationReservation, bytes: number): v
 	const state = turnBudgets.get(reservation.key) ?? {
 		usedBytes: reservation.usedBeforeBytes + committedBytes,
 		lastSeenAt: Date.now(),
+		exhaustedStreak: 0,
 	};
 	state.usedBytes = Math.max(0, state.usedBytes + bytes - committedBytes);
 	state.lastSeenAt = Date.now();
@@ -252,10 +277,26 @@ function budgetDetails(reservation: ObservationReservation): ObservationBudgetDe
 	};
 }
 
+/** Count this short-circuit against the turn's run of them. Untracked calls never escalate. */
+function bumpExhaustedStreak(key: string | null): number {
+	if (key === null) return 1;
+	const state = turnBudgets.get(key);
+	if (state === undefined) return 1;
+	state.exhaustedStreak += 1;
+	state.lastSeenAt = Date.now();
+	turnBudgets.set(key, state);
+	return state.exhaustedStreak;
+}
+
 /**
  * Structured result for a call that found the turn pool already spent.
  * `subject` names what the call was about (a path, a pattern); `hint` names
  * the narrowing arguments the tool supports.
+ *
+ * The first few such calls get the notice, which states the numbers and the
+ * narrowing advice. Past MAX_EXHAUSTED_NOTICES_PER_TURN the call fails instead:
+ * nothing this turn can return content, so an `ok` result is an invitation to a
+ * retry loop the pool can never satisfy.
  */
 export function observationBudgetExhausted(input: {
 	tool: string;
@@ -265,9 +306,18 @@ export function observationBudgetExhausted(input: {
 	hint: string;
 }): ToolResult {
 	const { tool, unit, reservation, subject, hint } = input;
-	const output = `[observation budget exhausted for this turn before ${tool} ${subject}: ${formatSize(
-		reservation.usedBeforeBytes,
-	)} already returned of ${formatSize(reservation.limitBytes)}. ${hint}]`;
+	const streak = bumpExhaustedStreak(reservation.key);
+	const spent = `${formatSize(reservation.usedBeforeBytes)} already returned of ${formatSize(reservation.limitBytes)}`;
+	if (streak > MAX_EXHAUSTED_NOTICES_PER_TURN) {
+		const message =
+			`observation budget exhausted for this turn before ${tool} ${subject}: ${spent}. ` +
+			`This is the ${streak}th call to hit it, so no observation tool can return content until the ` +
+			`next turn. Do not retry this call and do not substitute another one. Re-plan with what you ` +
+			`already have: say what you found, name what is still unread, and propose the next step.`;
+		recordSpentBytes(reservation, byteLength(message));
+		return { kind: "error", message };
+	}
+	const output = `[observation budget exhausted for this turn before ${tool} ${subject}: ${spent}. ${hint}]`;
 	const shownBytes = byteLength(output);
 	recordSpentBytes(reservation, shownBytes);
 	const budget = budgetDetails(reservation);

package/src/tools/observers.ts

@@ -44,39 +44,6 @@ export interface FileMutationEvent {
 	toolName: string;
 }
 
-/**
- * Defers file-mutation sinks off the after_tool hot path and coalesces rapid
- * events into one best-effort batch. Lifecycle-owned sinks that must drain at
- * shutdown should admit work synchronously instead of using this convenience.
- */
-export function coalescePathSink(sink: (paths: string[]) => void): (event: FileMutationEvent) => void {
-	const pending = new Set<string>();
-	let flushScheduled = false;
-
-	const scheduleFlush = (): void => {
-		if (flushScheduled) return;
-		flushScheduled = true;
-		setImmediate(() => {
-			flushScheduled = false;
-			if (pending.size === 0) return;
-			const paths = [...pending];
-			pending.clear();
-			try {
-				sink(paths);
-			} catch {
-				// Incremental indexing is best-effort and must not change tool execution.
-			}
-			if (pending.size > 0) scheduleFlush();
-		});
-	};
-
-	return (event) => {
-		if (event.paths.length === 0) return;
-		for (const path of event.paths) pending.add(path);
-		scheduleFlush();
-	};
-}
-
 /** Notifies the caller after a successful file-mutating tool, for incremental indexing. */
 export function createFileMutationObserver(sink: (event: FileMutationEvent) => void): MiddlewareHookRegistration {
 	return {