@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/tools/compete-worktrees.ts

@@ -34,7 +34,7 @@ import {
 } from "node:fs";
 import { hostname } from "node:os";
 import { join, relative, resolve } from "node:path";
-import type { RunKind } from "../domains/dispatch/types.js";
+import type { RunGateWorktreeProvenance, RunKind } from "../domains/dispatch/types.js";
 import {
 	commitWorktreePath,
 	isCanonicalWorktreePathInside,
@@ -47,6 +47,24 @@ export interface CandidateWorktree {
 	index: number;
 	branch: string;
 	path: string;
+	provenance?: RunGateWorktreeProvenance;
+}
+
+/** Narrow mux surface used by compete; the native functions remain usable alone. */
+export interface CompeteMuxWorktrees {
+	available(): boolean;
+	worktreeCreate(request: {
+		cwd: string;
+		branch: string;
+		base: string;
+		path: string;
+		label: string;
+		focus: boolean;
+	}): Promise<{
+		workspaceId: string;
+		worktree: { path: string; branch: string | null };
+	} | null>;
+	worktreeRemove(workspaceId: string, options?: { force?: boolean }): Promise<boolean>;
 }
 
 export type CompeteGroupState = "active" | "cleanup-ready" | "winner-preserved";
@@ -546,6 +564,52 @@ export function createCandidateWorktree(
 	return { index, branch, path };
 }
 
+/**
+ * Prefer herdr's worktree lifecycle while preserving Git as the recovery
+ * authority. A failed or vanished mux is deliberately indistinguishable from
+ * no mux to the caller except for the receipt provenance returned here.
+ */
+export async function createCandidateWorktreeMapped(
+	ownership: CompeteGroupOwnership,
+	index: number,
+	baseline: string,
+	mux?: CompeteMuxWorktrees,
+): Promise<CandidateWorktree> {
+	assertOwnership(ownership);
+	const branch = competeBranch(ownership.group, index);
+	const path = join(ownership.directory, `candidate-${index}`);
+	if (!isCanonicalPathInside(ownership.directory, path)) {
+		throw new Error(`candidate ${index} path escapes compete group ${ownership.group}`);
+	}
+	let fallback: RunGateWorktreeProvenance["fallback"] = "mux-unavailable";
+	if (mux?.available()) {
+		const created = await mux
+			.worktreeCreate({
+				cwd: ownership.root,
+				branch,
+				base: baseline,
+				path,
+				label: `clio compete ${ownership.group} candidate ${index}`,
+				focus: false,
+			})
+			.catch(() => null);
+		if (created !== null) {
+			if (resolve(created.worktree.path) !== resolve(path) || created.worktree.branch !== branch) {
+				throw new Error(`herdr created candidate ${index} at an unexpected path or branch`);
+			}
+			return {
+				index,
+				branch,
+				path,
+				provenance: { backend: "herdr", path, branch, workspaceId: created.workspaceId },
+			};
+		}
+		fallback = "mux-operation-failed";
+	}
+	const native = createCandidateWorktree(ownership, index, baseline);
+	return { ...native, provenance: { backend: "native", path, branch, fallback } };
+}
+
 /**
  * Seal a candidate's work as one commit on its branch. Returns false when the
  * builder changed nothing (an empty candidate is a legitimate ranking fact).
@@ -605,7 +669,7 @@ function removeRegisteredWorktree(root: string, path: string): void {
 	}
 }
 
-export function removeCandidateWorktree(
+function removeCandidateWorktree(
 	ownership: CompeteGroupOwnership,
 	worktree: CandidateWorktree,
 	deleteBranch: boolean,
@@ -633,6 +697,23 @@ export function removeCandidateWorktree(
 	}
 }
 
+/** Remove through herdr when it owns the workspace, then verify with Git. */
+export async function removeCandidateWorktreeMapped(
+	ownership: CompeteGroupOwnership,
+	worktree: CandidateWorktree,
+	deleteBranch: boolean,
+	mux?: CompeteMuxWorktrees,
+): Promise<void> {
+	const workspaceId = worktree.provenance?.backend === "herdr" ? worktree.provenance.workspaceId : undefined;
+	if (workspaceId && mux?.available()) {
+		await mux.worktreeRemove(workspaceId, { force: true }).catch(() => false);
+	}
+	// This is both the native fallback after mux loss and the postcondition check
+	// after a successful RPC. It prunes an already-removed path harmlessly and
+	// removes the candidate branch, which worktree.remove does not promise to do.
+	removeCandidateWorktree(ownership, worktree, deleteBranch);
+}
+
 /**
  * Merge the winning candidate branch into the current branch. Fast-forward
  * is impossible by construction (the candidate branched from HEAD and HEAD

package/src/tools/core-bootstrap.ts

@@ -184,6 +184,7 @@ export function assertRegisteredBuiltinTools(
 	registry: ToolRegistry,
 	registration: CoreToolRegistration,
 	includeDispatchTools: boolean,
+	includePanesTools = false,
 ): void {
-	assertBuiltinToolPolicy(registry.listAll(), { ...registration, includeDispatchTools });
+	assertBuiltinToolPolicy(registry.listAll(), { ...registration, includeDispatchTools, includePanesTools });
 }

package/src/tools/dispatch-admission.ts

@@ -4,11 +4,13 @@ import type { ExecutionPlan } from "../domains/dispatch/execution-plan.js";
 import { gateDeciderAgentId } from "../domains/dispatch/execution-role.js";
 import {
 	COUNCIL_JUDGE_PROMPT,
+	COUNCIL_MAX_MEMBERS,
+	COUNCIL_MIN_MEMBERS,
 	JUDGE_GATE_PROMPT,
 	REVIEWER_GATE_PROMPT,
 	renderCouncilVoteMemberTask,
 } from "../domains/dispatch/gate-role-prompts.js";
-import { normalizeDispatchIntent } from "../domains/dispatch/intent.js";
+import { narrowDispatchIntentToReadOnly, normalizeDispatchIntent } from "../domains/dispatch/intent.js";
 import { renderDispatchReviewerTask } from "../domains/dispatch/intent-requirements.js";
 import { approvedRouteCandidates } from "../domains/dispatch/route-approval.js";
 import { defaultRoutingIntent } from "../domains/dispatch/routing-intent.js";
@@ -109,7 +111,9 @@ function councilSettingsFromArgs(
 			members.push({ label, target, ...(model ? { model } : {}), ...(thinking ? { thinking } : {}) });
 		}
 	}
-	if (members.length < 2 || members.length > 5) return { ok: false, message: "council_members_out_of_range" };
+	if (members.length < COUNCIL_MIN_MEMBERS || members.length > COUNCIL_MAX_MEMBERS) {
+		return { ok: false, message: "council_members_out_of_range" };
+	}
 	const labels = new Set<string>();
 	for (const member of members) {
 		if (labels.has(member.label)) return { ok: false, message: `council_member_label_duplicate: ${member.label}` };
@@ -389,7 +393,9 @@ export function createDispatchAdmissionController(deps: DispatchToolDeps): Dispa
 			};
 		});
 		const reservation = deps.dispatch.reservations.prepare({
-			topology: artifact.topology === "fleet" || artifact.topology === "council" ? "parallel" : artifact.topology,
+			// A council keeps its own name so a capacity denial can say that its
+			// width has a floor. A fleet's waves are already parallel by shape.
+			topology: artifact.topology === "fleet" ? "parallel" : artifact.topology,
 			tasks,
 		});
 		try {
@@ -638,6 +644,11 @@ export function createDispatchAdmissionController(deps: DispatchToolDeps): Dispa
 							executionRole: "researcher",
 							autonomy: "read-only",
 							toolProfile: "council-read-only",
+							// A member inherits the caller's declared scope but never its
+							// write authority: the same trees arrive as read roots, so the
+							// declaration stays enforceable against a read-only run instead of
+							// claiming a write scope nothing can grant.
+							...(base.intent === undefined ? {} : { intent: narrowDispatchIntentToReadOnly(base.intent) }),
 							// The runner reuses this composed task from the resolved plan, so
 							// the approval artifact the plan hash binds shows the operator the
 							// exact ballot the member is asked to cast.

package/src/tools/dispatch-arguments.ts

@@ -1,12 +1,16 @@
 /** Pure model-argument parsing; every returned DispatchRequest has a concrete agent id. */
 
-import { pathBoundaryCovers } from "../core/path-boundary.js";
 import type { AgentAutomationAuthority } from "../domains/agents/spec.js";
 import { type AgentTaskType, classifyAgentTask } from "../domains/dispatch/agent-candidates.js";
 import { cloneDispatchBudgetRequest } from "../domains/dispatch/budget-envelope.js";
 import type { DispatchRequest } from "../domains/dispatch/contract.js";
 import { type AgentRoleFactsResolver, requestExecutionRole } from "../domains/dispatch/execution-role.js";
 import type { DispatchIntent } from "../domains/dispatch/intent.js";
+import {
+	classifyDispatchIntentCompatibility,
+	dispatchIntentRefusals,
+	dispatchIntentScopeWidening,
+} from "../domains/dispatch/intent-compatibility.js";
 import { parseRoutingIntent } from "../domains/dispatch/routing-intent.js";
 import { DISPATCH_BRIEFING_MAX_BYTES, type JobThinkingLevel } from "../domains/dispatch/validation.js";
 import { isToolProfileName, TOOL_PROFILE_NAMES } from "./profiles.js";
@@ -197,10 +201,17 @@ function dispatchRequestFromArgs(
 				? args.writeRoots.filter((entry): entry is string => typeof entry === "string")
 				: undefined;
 			if (legacy !== undefined) {
-				const left = [...new Set(legacy)].sort();
-				if (JSON.stringify(left) !== JSON.stringify(resolved.intent.writeRoots)) {
-					return { ok: false, message: "intent_write_roots_contradiction" };
-				}
+				// Asked through the same rule the job-spec validator asks, so the two
+				// cannot disagree about the same pair. A raw string comparison here
+				// would refuse './src/tools' against 'src/tools', which name one tree.
+				const refusal = dispatchIntentRefusals(
+					classifyDispatchIntentCompatibility({
+						intent: resolved.intent,
+						writeRoots: legacy,
+						...(cwd !== undefined ? { cwd } : {}),
+					}),
+				).find((entry) => entry.code === "intent_write_roots_contradiction");
+				if (refusal !== undefined) return { ok: false, message: refusal.message };
 				request.writeRoots = legacy;
 			} else {
 				request.writeRoots = resolved.intent.writeRoots;
@@ -273,21 +284,10 @@ export function dispatchRequestsFromArgs(
 			}
 			const ceiling = options.resolveIntent(sharedIntent, parsed.request.cwd);
 			if (!ceiling.ok) return { ok: false, message: `dispatch: task ${index + 1}: ${ceiling.message}` };
-			const pathCeilings = {
-				readRoots: [...ceiling.intent.readRoots, ...ceiling.intent.writeRoots],
-				writeRoots: ceiling.intent.writeRoots,
-				relevantPaths: [...ceiling.intent.readRoots, ...ceiling.intent.writeRoots, ...ceiling.intent.relevantPaths],
-			};
-			for (const field of ["readRoots", "writeRoots", "relevantPaths"] as const) {
-				const outside = parsed.request.intent?.[field].find(
-					(candidate) => !pathBoundaryCovers(pathCeilings[field], candidate),
-				);
-				if (outside !== undefined) {
-					return {
-						ok: false,
-						message: `dispatch: task ${index + 1}: intent_scope_widening: ${field} entry '${outside}' is outside the top-level intent ceiling`,
-					};
-				}
+			const widening =
+				parsed.request.intent === undefined ? null : dispatchIntentScopeWidening(ceiling.intent, parsed.request.intent);
+			if (widening !== null) {
+				return { ok: false, message: `dispatch: task ${index + 1}: ${widening.message}` };
 			}
 		}
 		requests.push(parsed.request);

package/src/tools/dispatch-plan.ts

@@ -236,15 +236,19 @@ function str(value: unknown): string | undefined {
 	return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
 }
 
-/** Keep terminal control bytes and line breaks out of approval artifacts. */
-function safeField(value: string): string {
+/** Keep terminal control bytes and line breaks out of approval artifacts without losing their identity. */
+function safeField(value: string, bindChangedValue = true): string {
 	let result = "";
 	for (const character of value) {
 		const code = character.codePointAt(0) ?? 0;
 		result += code < 32 || (code >= 127 && code <= 159) ? "?" : character;
-		if (result.length >= 256) return `${result.slice(0, 255)}…`;
+		if (result.length >= 256) {
+			result = `${result.slice(0, 255)}…`;
+			break;
+		}
 	}
-	return result;
+	if (!bindChangedValue || result === value) return result;
+	return `${result}{sha256=${createHash("sha256").update(value, "utf8").digest("hex")}}`;
 }
 
 function renderLegacyPathScope(task: DispatchPlanTaskView): string[] {
@@ -393,7 +397,7 @@ function renderPlanText(
 				? ""
 				: ` posture=${routing.posture} maxCostUsd=${routing.maxCostUsd ?? "none"} deadlineMs=${routing.deadlineMs ?? "none"} minimumQuality=${routing.minimumQuality ?? "none"} locality=${routing.locality}`;
 		lines.push(
-			`  ${index + 1}.${role} agent=${safeField(task.agent)}${target}${model}${node}${failover}${routingText} task=${JSON.stringify(safeField(task.task))}`,
+			`  ${index + 1}.${role} agent=${safeField(task.agent)}${target}${model}${node}${failover}${routingText} task_bytes=${Buffer.byteLength(task.task, "utf8")} task_sha256=${createHash("sha256").update(task.task, "utf8").digest("hex")} task_preview=${JSON.stringify(safeField(task.task, false))}`,
 		);
 		if (task.council !== undefined) {
 			lines.push(
@@ -420,25 +424,29 @@ function renderPlanText(
 		}
 		if (task.agentSelection !== null) {
 			lines.push(
-				`    agent-selection=auto baseline=${safeField(task.agentSelection.baselineAgentId)} authority=${task.agentSelection.approvedAuthorities.map(safeField).join(",")} basis=${task.agentSelection.authorityBasis}`,
+				`    agent-selection=auto baseline=${safeField(task.agentSelection.baselineAgentId)} authority=${task.agentSelection.approvedAuthorities.map((authority) => safeField(authority)).join(",")} basis=${task.agentSelection.authorityBasis}`,
 			);
 		}
 		if (task.stepId !== null) {
 			lines.push(
-				`    step=${safeField(task.stepId)} wave=${task.wave ?? "?"} role=${task.executionRole} dependencies=${task.dependencies.map(safeField).join(",") || "none"} result=${task.expectedResultContract ?? "none"} authority=${task.authorityGrant?.requested ?? "none"} basis=${task.authorityGrant?.basis ?? "none"}`,
+				`    step=${safeField(task.stepId)} wave=${task.wave ?? "?"} role=${task.executionRole} dependencies=${task.dependencies.map((dependency) => safeField(dependency)).join(",") || "none"} result=${task.expectedResultContract ?? "none"} authority=${task.authorityGrant?.requested ?? "none"} basis=${task.authorityGrant?.basis ?? "none"}`,
 			);
 			const agentReasons = task.agentDecision?.agentSelection.evaluations
 				.filter((evaluation) => evaluation.rejections.length > 0)
 				.slice(0, 8)
 				.map(
-					(evaluation) => `${safeField(evaluation.agentId)}:${evaluation.rejections.slice(0, 4).map(safeField).join(",")}`,
+					(evaluation) =>
+						`${safeField(evaluation.agentId)}:${evaluation.rejections
+							.slice(0, 4)
+							.map((rejection) => safeField(rejection))
+							.join(",")}`,
 				);
 			if (agentReasons !== undefined && agentReasons.length > 0)
 				lines.push(`    agent-exclusions=${agentReasons.join(";")}`);
 		}
 		if (task.briefing !== undefined) {
 			lines.push(
-				`    briefing_bytes=${Buffer.byteLength(task.briefing, "utf8")} briefing_sha256=${createHash("sha256").update(task.briefing, "utf8").digest("hex")} briefing_preview=${JSON.stringify(safeField(task.briefing))}`,
+				`    briefing_bytes=${Buffer.byteLength(task.briefing, "utf8")} briefing_sha256=${createHash("sha256").update(task.briefing, "utf8").digest("hex")} briefing_preview=${JSON.stringify(safeField(task.briefing, false))}`,
 			);
 		}
 		if (task.intent !== undefined) {

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

@@ -2,6 +2,7 @@ import { BusChannels } from "../core/bus-events.js";
 import type { SafeEventBus } from "../core/event-bus.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";
@@ -77,10 +78,95 @@ function eventDetail(event: unknown): string | undefined {
 	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" ? 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 +183,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 +259,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 +268,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 +304,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 +314,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,7 @@ import {
 	claimCompeteGroup,
 	cleanupCompeteGroup,
 	commitCandidateWork,
-	createCandidateWorktree,
+	createCandidateWorktreeMapped,
 	isGitRepository,
 	loadCompeteGroup,
 	markCompeteGroupCleanupReady,
@@ -65,7 +66,7 @@ import {
 	protectedPathsChangedByCompeteBranch,
 	recoverCleanupReadyCompeteGroups,
 	registerCompeteGroupRun,
-	removeCandidateWorktree,
+	removeCandidateWorktreeMapped,
 	settleCompeteGroupRun,
 	settleRecoveredCompeteDecision,
 } from "./compete-worktrees.js";
@@ -1255,10 +1256,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 +1292,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 +1533,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 +1550,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);
 			}
@@ -1885,6 +1900,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-scout.ts

@@ -256,7 +256,7 @@ export async function runScoutContinuationPlan<T, S>(input: {
 				};
 			},
 			cancel: (assignmentId) => input.dispatch.abort(assignmentId),
-			release: (ownerId) => input.dispatch.reservations?.rollbackUnconsumed(ownerId),
+			release: (ownerId) => input.dispatch.reservations?.release(ownerId),
 			releaseUnconsumed: (ownerId) => input.dispatch.reservations?.rollbackUnconsumed(ownerId),
 		},
 		input.signal,

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>;