@iowarp/clio-coder 0.4.0 → 0.4.2

package/src/cli/upgrade.ts

@@ -1,12 +1,8 @@
 import { spawn } from "node:child_process";
-import { loadDomains } from "../core/domain-loader.js";
 import { initializeClioHome } from "../core/init.js";
 import { clioStateDir } from "../core/xdg.js";
-import { ConfigDomainModule } from "../domains/config/index.js";
-import type { LifecycleContract } from "../domains/lifecycle/contract.js";
-import { LifecycleDomainModule } from "../domains/lifecycle/index.js";
 import { detectInstallMethod } from "../domains/lifecycle/install-method.js";
-import { listMigrations } from "../domains/lifecycle/migrations/index.js";
+import { listMigrations, runPending } from "../domains/lifecycle/migrations/index.js";
 import { readStateInfo } from "../domains/lifecycle/state.js";
 import { getVersionInfo } from "../domains/lifecycle/version.js";
 import { printError, printHeader, printOk } from "./shared.js";
@@ -229,36 +225,35 @@ export async function runUpgradeCommand(argv: ReadonlyArray<string>): Promise<nu
 	if (opts.skipMigrations) {
 		process.stdout.write("[upgrade] skipping migrations (--skip-migrations)\n");
 	} else {
-		const loaded = await loadDomains([ConfigDomainModule, LifecycleDomainModule]);
+		// Migrations run on the state tree directly rather than through the
+		// lifecycle domain. Loading that domain pulls in `config`, whose start
+		// runs the strict settings reader, and a settings-repairing migration is
+		// precisely the one that cannot get past it: `clio-coder upgrade` on a
+		// home whose settings.yaml names a retired key failed the domain load and
+		// never reached the migration that removes the key. A runner that needs
+		// valid config in order to repair invalid config can never run. The
+		// domain's `runMigrations` is a passthrough to this same function, so
+		// nothing is lost by calling it where the circularity does not exist.
+		let result: Awaited<ReturnType<typeof runPending>>;
 		try {
-			const lifecycle = loaded.getContract<LifecycleContract>("lifecycle");
-			if (!lifecycle) {
-				printError("lifecycle domain unavailable");
-				return 1;
-			}
-			let result: Awaited<ReturnType<LifecycleContract["runMigrations"]>>;
-			try {
-				result = await lifecycle.runMigrations(stateDir);
-			} catch (err) {
-				// A migration reports why it could not run, but on its own that reads
-				// as the whole upgrade being impossible. It is not: the rest of the
-				// upgrade is independent of it, and naming the flag that runs the rest
-				// is the difference between a stuck operator and a moved one.
-				printError(
-					`migration failed: ${err instanceof Error ? err.message : String(err)}`,
-					"the rest of the upgrade does not depend on it; run `clio-coder upgrade --skip-migrations` to continue, then fix the cause and re-run `clio-coder upgrade`.",
-				);
-				return 1;
-			}
-			appliedIds = [...result.applied];
-			appliedCount = appliedIds.length;
-			if (appliedCount === 0) {
-				process.stdout.write("[upgrade] no pending migrations\n");
-			} else {
-				for (const id of appliedIds) process.stdout.write(`[upgrade] applied migration ${id}\n`);
-			}
-		} finally {
-			await loaded.stop();
+			result = await runPending(stateDir);
+		} catch (err) {
+			// A migration reports why it could not run, but on its own that reads
+			// as the whole upgrade being impossible. It is not: the rest of the
+			// upgrade is independent of it, and naming the flag that runs the rest
+			// is the difference between a stuck operator and a moved one.
+			printError(
+				`migration failed: ${err instanceof Error ? err.message : String(err)}`,
+				"the rest of the upgrade does not depend on it; run `clio-coder upgrade --skip-migrations` to continue, then fix the cause and re-run `clio-coder upgrade`.",
+			);
+			return 1;
+		}
+		appliedIds = [...result.applied];
+		appliedCount = appliedIds.length;
+		if (appliedCount === 0) {
+			process.stdout.write("[upgrade] no pending migrations\n");
+		} else {
+			for (const id of appliedIds) process.stdout.write(`[upgrade] applied migration ${id}\n`);
 		}
 	}
 

package/src/cli/usage.ts

@@ -788,7 +788,7 @@ function indent(text: string): string {
 		.join("\n");
 }
 
-export function inWindow(iso: string, start: number, end: number): boolean {
+function inWindow(iso: string, start: number, end: number): boolean {
 	const value = Date.parse(iso);
 	return Number.isFinite(value) && value >= start && value <= end + USAGE_WINDOW_FUTURE_SKEW_MS;
 }
@@ -968,7 +968,7 @@ function bashCommandFromToolCallPayload(payload: unknown): string | null {
  * assignments dropped, verb plus subcommand kept, flags kept with values
  * stripped, remaining arguments dropped.
  */
-export function bashShape(command: string): string {
+function bashShape(command: string): string {
 	const firstLine = command.split("\n").find((line) => {
 		const trimmed = line.trim();
 		return trimmed.length > 0 && !trimmed.startsWith("#");

package/src/cli/validate-model.ts

@@ -39,7 +39,7 @@ function describeLiveTarget(live: LiveModelInventory): string {
 }
 
 /** The refusal `configure` prints for a model the live target does not advertise. */
-export function formatUnadvertisedModelReason(modelId: string, live: LiveModelInventory): string {
+function formatUnadvertisedModelReason(modelId: string, live: LiveModelInventory): string {
 	const resident = live.resident.length > 0 ? live.resident.join(", ") : "none";
 	return (
 		`${describeLiveTarget(live)} does not advertise model '${modelId}'. ` +

package/src/cli/verifiers-inspect.ts

@@ -283,7 +283,7 @@ function projectCheck(check: AuthoringCheck): VerifiersInspectCheck | null {
 
 const ORIGIN_RANK: Record<VerifierOrigin, number> = { "package-script": 0, catalog: 1, proposed: 2 };
 
-export function verifiersInspectSnapshot(
+function verifiersInspectSnapshot(
 	now: () => number = Date.now,
 	workspaceRoot: string = process.cwd(),
 ): VerifiersInspectSnapshot {

package/src/cli/wiki-generate.ts

@@ -149,7 +149,7 @@ async function drainDispatchEvents(
 	let firstBlockReason: string | null = null;
 	// Every event is consumed so finalization cannot block on an unread iterator.
 	for await (const event of events) {
-		if (!isRecord(event) || event.type !== "clio_tool_finish") continue;
+		if (!isRecord(event) || event.type !== "clio_coder_tool_finish") continue;
 		const tool = eventPayloadString(event, "tool");
 		if (!tool) continue;
 		const outcome = eventPayloadString(event, "outcome") ?? "done";
@@ -190,7 +190,7 @@ interface WikiDispatchOutcome {
  * throws: a failed page must not take down the pages around it, and whatever
  * the run wrote before it stopped is already on disk.
  */
-export async function runWikiDispatch(input: {
+async function runWikiDispatch(input: {
 	dispatch: DispatchContract;
 	cwd: string;
 	outputDir: string;
@@ -236,7 +236,7 @@ export async function runWikiDispatch(input: {
 	} catch (err) {
 		return { ok: false, detail: err instanceof Error ? err.message : String(err) };
 	}
-	const deadline = armInternalDispatchDeadline(input.dispatch, handle.runId, input.label, process.env, input.deadlineMs);
+	const deadline = armInternalDispatchDeadline(input.dispatch, handle.runId, input.label, input.deadlineMs);
 	let lastHeartbeatAt = startedAtClock;
 	try {
 		const summary = await drainDispatchEvents(handle.events, (tools) => {
@@ -371,7 +371,7 @@ async function runPagePhase(
 	return next;
 }
 
-export async function generateWikiWithDocumenter(
+async function generateWikiWithDocumenter(
 	dispatch: DispatchContract,
 	input: WikiGenerateInput,
 	route: WikiModelRoute = {},
@@ -472,11 +472,11 @@ export async function resolveDocumenterModelId(route: WikiModelRoute = {}): Prom
 		const providers = loaded.getContract<ProvidersContract>("providers");
 		if (!config || !providers) return UNRESOLVED_DOCUMENTER_MODEL;
 		const settings = config.get();
-		const workers = settings.workers;
+		const workers = settings.fleet;
 		// Keyed on the dispatched agent id and nothing else, because that is what
 		// `placement.ts` reads. Falling back to another agent's binding here would
 		// record a model in wiki metadata that no dispatch ever ran.
-		const bindingProfileName = workers?.agentBindings?.[WIKI_AGENT_ID];
+		const bindingProfileName = workers?.agentProfiles?.[WIKI_AGENT_ID];
 		const profile = bindingProfileName ? workers?.profiles?.[bindingProfileName] : undefined;
 		const targetId = route.target ?? profile?.target ?? workers?.default?.target ?? settings.targets?.[0]?.id ?? null;
 		if (!targetId) return UNRESOLVED_DOCUMENTER_MODEL;

package/src/core/artifact-paths.ts

@@ -15,7 +15,7 @@
  * be checking a path the tool never writes. One artifact per kind is therefore
  * the contract; keep several by passing explicit paths.
  *
- * See docs/artifact-placement.md for the full taxonomy.
+ * See docs/architecture/artifact-placement.md for the full taxonomy.
  */
 
 /** Project-local directory holding everything Clio generates for one repo. */

package/src/core/bash-exec.ts

@@ -18,7 +18,7 @@ export { clampTimerDelayMs as clampTimeoutMs } from "./timers.js";
 // (failing assertion, compiler error, exit summary) must survive.
 export const BASH_HARD_CAP_BYTES = 16 * 1024 * 1024;
 
-const CLIO_CONTROL_ENV_KEYS = ["CLIO_CODER_INTERACTIVE", "CLIO_CODER_RESUME_SESSION_ID"] as const;
+const CLIO_CONTROL_ENV_KEYS = ["CLIO_CODER_INTERACTIVE"] as const;
 
 export interface BashCommandResult {
 	error: NodeJS.ErrnoException | null;
@@ -52,6 +52,129 @@ export interface RunBashCommandOptions {
 
 const BASH_UPDATE_THROTTLE_MS = 100;
 
+export interface BashProgressScheduler {
+	now(): number;
+	setTimeout(callback: () => void, delayMs: number): unknown;
+	clearTimeout(timer: unknown): void;
+}
+
+export interface BashOutputProgressController {
+	/** Emit the initial empty cumulative snapshot, when a callback is configured. */
+	start(): void;
+	/** Accept one stream chunk. Returns true only when this chunk reaches the hard cap. */
+	append(target: "stdout" | "stderr", chunk: Buffer): boolean;
+	/** Seal output, cancel progress work, emit the final snapshot, and return the result fields. */
+	settle(): Pick<BashCommandResult, "stdout" | "stderr" | "outputBytes" | "outputCapped">;
+}
+
+const SYSTEM_PROGRESS_SCHEDULER: BashProgressScheduler = {
+	now: Date.now,
+	setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+	clearTimeout: (timer) => clearTimeout(timer as ReturnType<typeof setTimeout>),
+};
+
+/**
+ * Cumulative stdout/stderr fold shared by the child stream handlers and a
+ * deterministic contract-test seam. Settlement is a phase, not just a final
+ * boolean: once it starts, re-entrant or queued stream work is rejected while
+ * the one final advisory snapshot is still allowed to publish.
+ */
+export function createBashOutputProgressController(
+	onUpdate?: (progress: BashCommandProgress) => void,
+	scheduler: BashProgressScheduler = SYSTEM_PROGRESS_SCHEDULER,
+): BashOutputProgressController {
+	let phase: "active" | "settling" | "settled" = "active";
+	let stdout = "";
+	let stderr = "";
+	const stdoutDecoder = new StringDecoder("utf8");
+	const stderrDecoder = new StringDecoder("utf8");
+	let decodersFinished = false;
+	let outputBytes = 0;
+	let outputCapped = false;
+	let updateTimer: unknown = null;
+	let updateDirty = false;
+	let lastUpdateAt = 0;
+
+	const snapshot = (): BashCommandProgress => ({ stdout, stderr, outputBytes });
+
+	const finishDecoders = (): void => {
+		if (decodersFinished) return;
+		decodersFinished = true;
+		// A hard byte cap may bisect a multibyte code point. Discard the
+		// decoder's incomplete suffix instead of manufacturing U+FFFD.
+		if (outputCapped) return;
+		stdout += stdoutDecoder.end();
+		stderr += stderrDecoder.end();
+	};
+
+	const emitUpdate = (final = false): void => {
+		if (onUpdate === undefined || !updateDirty) return;
+		if (phase !== "active" && !(final && phase === "settling")) return;
+		updateDirty = false;
+		lastUpdateAt = scheduler.now();
+		try {
+			onUpdate(snapshot());
+		} catch {
+			// Rendering progress is advisory and must never change command execution.
+		}
+	};
+
+	const clearUpdateTimer = (): void => {
+		if (updateTimer === null) return;
+		scheduler.clearTimeout(updateTimer);
+		updateTimer = null;
+	};
+
+	const scheduleUpdate = (): void => {
+		if (onUpdate === undefined || phase !== "active") return;
+		updateDirty = true;
+		const delay = BASH_UPDATE_THROTTLE_MS - (scheduler.now() - lastUpdateAt);
+		if (delay <= 0) {
+			clearUpdateTimer();
+			emitUpdate();
+			return;
+		}
+		updateTimer ??= scheduler.setTimeout(() => {
+			updateTimer = null;
+			// A timer already queued by the event loop may still invoke its callback
+			// after clearTimeout. The phase check makes that callback inert.
+			emitUpdate();
+		}, delay);
+	};
+
+	return {
+		start(): void {
+			if (phase !== "active" || onUpdate === undefined) return;
+			updateDirty = true;
+			emitUpdate();
+		},
+		append(target, chunk): boolean {
+			if (phase !== "active" || outputCapped) return false;
+			const remaining = BASH_HARD_CAP_BYTES - outputBytes;
+			const accepted = chunk.byteLength <= remaining ? chunk : chunk.subarray(0, Math.max(0, remaining));
+			outputBytes += accepted.byteLength;
+			if (accepted.byteLength > 0) {
+				const decoded = target === "stdout" ? stdoutDecoder.write(accepted) : stderrDecoder.write(accepted);
+				if (target === "stdout") stdout += decoded;
+				else stderr += decoded;
+			}
+			if (accepted.byteLength < chunk.byteLength) outputCapped = true;
+			scheduleUpdate();
+			return outputCapped;
+		},
+		settle() {
+			if (phase === "settled") return { ...snapshot(), outputCapped };
+			if (phase === "settling") return { ...snapshot(), outputCapped };
+			phase = "settling";
+			clearUpdateTimer();
+			finishDecoders();
+			emitUpdate(true);
+			phase = "settled";
+			return { ...snapshot(), outputCapped };
+		},
+	};
+}
+
 function buildToolEnv(): NodeJS.ProcessEnv {
 	const env = { ...process.env };
 	env.AI_AGENT = AI_AGENT_NAME;
@@ -75,7 +198,7 @@ const LOGIN_ENV_CAPTURE_TIMEOUT_MS = 10_000;
 let loginEnvCapture: Promise<NodeJS.ProcessEnv | null> | null = null;
 
 /** NUL-delimited `env -0` output to an env map; null when unusable (no PATH). */
-export function parseNullDelimitedEnv(raw: string): NodeJS.ProcessEnv | null {
+function parseNullDelimitedEnv(raw: string): NodeJS.ProcessEnv | null {
 	const env: NodeJS.ProcessEnv = {};
 	for (const entry of raw.split("\0")) {
 		if (entry.length === 0) continue;
@@ -152,16 +275,7 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 		let timeoutId: ReturnType<typeof setTimeout> | null = null;
 		let killGraceTimer: ReturnType<typeof setTimeout> | null = null;
 		let killSent = false;
-		let stdout = "";
-		let stderr = "";
-		const stdoutDecoder = new StringDecoder("utf8");
-		const stderrDecoder = new StringDecoder("utf8");
-		let decodersFinished = false;
-		let outputBytes = 0;
-		let outputCapped = false;
-		let updateTimer: ReturnType<typeof setTimeout> | null = null;
-		let updateDirty = false;
-		let lastUpdateAt = 0;
+		const output = createBashOutputProgressController(options.onUpdate);
 
 		const child = spawn("/bin/bash", [plan.mode, command], {
 			...(options.cwd === undefined ? {} : { cwd: options.cwd }),
@@ -170,53 +284,7 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 			stdio: ["ignore", "pipe", "pipe"],
 		});
 
-		const finishDecoders = (): void => {
-			if (decodersFinished) return;
-			decodersFinished = true;
-			// A hard byte cap may bisect a multibyte code point. Discard the
-			// decoder's incomplete suffix instead of manufacturing U+FFFD.
-			if (outputCapped) return;
-			stdout += stdoutDecoder.end();
-			stderr += stderrDecoder.end();
-		};
-
-		const emitUpdate = (): void => {
-			if (options.onUpdate === undefined || !updateDirty) return;
-			updateDirty = false;
-			lastUpdateAt = Date.now();
-			try {
-				options.onUpdate({ stdout, stderr, outputBytes: Math.min(outputBytes, BASH_HARD_CAP_BYTES) });
-			} catch {
-				// Rendering progress is advisory and must never change command execution.
-			}
-		};
-		const clearUpdateTimer = (): void => {
-			if (updateTimer === null) return;
-			clearTimeout(updateTimer);
-			updateTimer = null;
-		};
-		const scheduleUpdate = (): void => {
-			if (options.onUpdate === undefined) return;
-			updateDirty = true;
-			const delay = BASH_UPDATE_THROTTLE_MS - (Date.now() - lastUpdateAt);
-			if (delay <= 0) {
-				clearUpdateTimer();
-				emitUpdate();
-				return;
-			}
-			updateTimer ??= setTimeout(() => {
-				updateTimer = null;
-				emitUpdate();
-			}, delay);
-		};
-		const finishUpdates = (): void => {
-			clearUpdateTimer();
-			emitUpdate();
-		};
-		if (options.onUpdate !== undefined) {
-			updateDirty = true;
-			emitUpdate();
-		}
+		output.start();
 
 		const clearKillGraceTimer = (): void => {
 			if (!killGraceTimer) return;
@@ -265,22 +333,7 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 		}
 
 		const appendChunk = (target: "stdout" | "stderr", chunk: Buffer): void => {
-			if (outputCapped) return;
-			const remaining = BASH_HARD_CAP_BYTES - outputBytes;
-			const accepted = chunk.byteLength <= remaining ? chunk : chunk.subarray(0, Math.max(0, remaining));
-			outputBytes += accepted.byteLength;
-			if (accepted.byteLength > 0) {
-				const decoded = target === "stdout" ? stdoutDecoder.write(accepted) : stderrDecoder.write(accepted);
-				if (target === "stdout") stdout += decoded;
-				else stderr += decoded;
-			}
-			if (accepted.byteLength < chunk.byteLength) {
-				outputCapped = true;
-				scheduleUpdate();
-				killChild();
-				return;
-			}
-			scheduleUpdate();
+			if (output.append(target, chunk)) killChild();
 		};
 
 		child.stdout?.on("data", (chunk: Buffer) => appendChunk("stdout", chunk));
@@ -290,19 +343,15 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 			settled = true;
 			if (timeoutId) clearTimeout(timeoutId);
 			clearKillGraceTimer();
-			finishDecoders();
-			finishUpdates();
+			const finalOutput = output.settle();
 			options.signal?.removeEventListener("abort", onAbort);
 			resolve({
 				error: error as NodeJS.ErrnoException,
-				stdout,
-				stderr,
+				...finalOutput,
 				exitCode: null,
 				signal: null,
 				aborted,
 				timedOut,
-				outputCapped,
-				outputBytes,
 			});
 		});
 		child.on("close", (code, signalName) => {
@@ -310,8 +359,7 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 			settled = true;
 			if (timeoutId) clearTimeout(timeoutId);
 			clearKillGraceTimer();
-			finishDecoders();
-			finishUpdates();
+			const finalOutput = output.settle();
 			options.signal?.removeEventListener("abort", onAbort);
 			const error =
 				code === 0 && signalName === null
@@ -324,14 +372,11 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 						} as NodeJS.ErrnoException);
 			resolve({
 				error,
-				stdout,
-				stderr,
+				...finalOutput,
 				exitCode: code,
 				signal: signalName,
 				aborted,
 				timedOut,
-				outputCapped,
-				outputBytes,
 			});
 		});
 	});

package/src/core/boot-trace.ts

@@ -16,7 +16,7 @@
 const BOOT_TRACE_ENV = "CLIO_CODER_TRACE_BOOT";
 
 /** True when boot tracing is enabled for this process. */
-export function isBootTraceEnabled(): boolean {
+function isBootTraceEnabled(): boolean {
 	return process.env[BOOT_TRACE_ENV] === "1";
 }
 
@@ -24,11 +24,11 @@ export function isBootTraceEnabled(): boolean {
 export function formatBootTrace(phase: string, detail?: string): string | null {
 	if (!isBootTraceEnabled()) return null;
 	const suffix = detail !== undefined && detail.length > 0 ? ` (${detail})` : "";
-	return `[clio:boot] +${performance.now().toFixed(1)}ms ${phase}${suffix}\n`;
+	return `[clio-coder:boot] +${performance.now().toFixed(1)}ms ${phase}${suffix}\n`;
 }
 
 /**
- * Stamp a boot phase marker to stderr, e.g. `[clio:boot] +742.1ms cli entry`.
+ * Stamp a boot phase marker to stderr, e.g. `[clio-coder:boot] +742.1ms cli entry`.
  * `detail` appends a parenthetical (module counts, ids). No-op unless
  * `CLIO_CODER_TRACE_BOOT=1`. Never throws: a diagnostic must not affect boot.
  */

package/src/core/bus-events.ts

@@ -24,6 +24,7 @@ import type {
 	ToolActivitySummary,
 } from "../domains/dispatch/types.js";
 import type { MiddlewareHook } from "../domains/middleware/types.js";
+import type { ObservabilityRunEvidence } from "../domains/observability/contract.js";
 import type { TargetStatus } from "../domains/providers/contract.js";
 import type { CostProvenance } from "../domains/providers/index.js";
 import type { ClioSettings } from "./config.js";
@@ -58,9 +59,11 @@ export const BusChannels = {
 	DispatchProgress: "dispatch.progress",
 	DispatchCompleted: "dispatch.completed",
 	DispatchFailed: "dispatch.failed",
+	AccountabilityEvidenceReady: "accountability.evidenceReady",
 	CompactionBegin: "compaction.begin",
 	CompactionEnd: "compaction.end",
 	MiddlewareHookFailed: "middleware.hookFailed",
+	ExtensionsReloaded: "extensions.reloaded",
 	ContextActivity: "context.activity",
 	ContextWarning: "context.warning",
 	ContextPruned: "context.pruned",
@@ -628,8 +631,8 @@ export interface DispatchTerminalStats {
 	exitCode: number;
 	/** Honest activity record aggregated from the run's tool telemetry; null when the receipt predates it. */
 	toolActivity: ToolActivitySummary | null;
-	/** Host-run declared verification status when the request included checks. */
-	hostVerification?: "verified" | "rejected" | "skipped";
+	/** Host-run declared verification status when the request included checks; `not_implicated` is a batch member the failure was charged away from. */
+	hostVerification?: "verified" | "rejected" | "skipped" | "not_implicated";
 }
 
 /** Published on {@link BusChannels.DispatchCompleted} when a run finalizes as succeeded. */
@@ -667,6 +670,24 @@ export interface DispatchFailedPayload extends DispatchRunIdentity, Partial<Disp
 	skillActivations?: ReadonlyArray<SkillActivation>;
 }
 
+// ---------------------------------------------------------------------------
+// Accountability
+// ---------------------------------------------------------------------------
+
+/**
+ * Published on {@link BusChannels.AccountabilityEvidenceReady} by the
+ * observability extension once a finalized run's evidence bundle and its
+ * sidecar index row have landed. The evidence fields are exactly
+ * {@link ObservabilityRunEvidence}, the shape the projection already attaches
+ * to the run summary, so the bus and the snapshot cannot describe the same
+ * moment two ways. A failed build publishes nothing here: the projection's
+ * notice is the failure surface, and a client that never receives this event
+ * has learned only that no bundle is ready, which is the truth.
+ */
+export interface AccountabilityEvidenceReadyPayload extends ObservabilityRunEvidence {
+	runId: string;
+}
+
 // ---------------------------------------------------------------------------
 // Compaction
 // ---------------------------------------------------------------------------
@@ -677,6 +698,26 @@ export interface CompactionPayload {
 	at: number;
 }
 
+// ---------------------------------------------------------------------------
+// Extensions
+// ---------------------------------------------------------------------------
+
+/**
+ * Published on {@link BusChannels.ExtensionsReloaded} by the composition
+ * root after a new extension generation and its user-hook registrations
+ * have both been committed. Consumers that cache extension-sourced data
+ * (prompt fragments, agent recipes, the session prompt) refresh on
+ * `changed`; an unchanged generation carries the previous digest and needs
+ * no work. Never published between the two commits.
+ */
+export interface ExtensionsReloadedPayload {
+	generation: number;
+	previousGeneration: number;
+	changed: boolean;
+	/** Content identity of the committed snapshot. */
+	digest: string;
+}
+
 // ---------------------------------------------------------------------------
 // Middleware
 // ---------------------------------------------------------------------------
@@ -685,15 +726,17 @@ export interface CompactionPayload {
  * Published on {@link BusChannels.MiddlewareHookFailed} when a middleware hook
  * registration misbehaves: `hook_failed` for a thrown evaluate (its effects
  * are discarded and the turn proceeds), `budget_exceeded` for a soft
- * wall-time overrun (effects still apply). Diagnostics only; nothing
- * subscribing here may decide anything.
+ * wall-time overrun (effects still apply), `registration_conflict` when an
+ * owned registration set (user hooks) offered an id a builtin or host
+ * registration holds, or a host registration evicted an owned one.
+ * Diagnostics only; nothing subscribing here may decide anything.
  */
 export interface MiddlewareHookFailedPayload {
-	kind: "hook_failed" | "budget_exceeded";
+	kind: "hook_failed" | "budget_exceeded" | "registration_conflict";
 	registrationId: string;
 	hook: MiddlewareHook;
 	at: number;
-	/** Error text; hook_failed only. */
+	/** Error text for hook_failed; one formatted line for registration_conflict. */
 	message?: string | undefined;
 	/** Measured and allowed wall time in ms; budget_exceeded only. */
 	elapsedMs?: number | undefined;
@@ -798,9 +841,11 @@ export type BusPayloadMap = {
 	[BusChannels.DispatchProgress]: DispatchProgressPayload;
 	[BusChannels.DispatchCompleted]: DispatchCompletedPayload;
 	[BusChannels.DispatchFailed]: DispatchFailedPayload;
+	[BusChannels.AccountabilityEvidenceReady]: AccountabilityEvidenceReadyPayload;
 	[BusChannels.CompactionBegin]: CompactionPayload;
 	[BusChannels.CompactionEnd]: CompactionPayload;
 	[BusChannels.MiddlewareHookFailed]: MiddlewareHookFailedPayload;
+	[BusChannels.ExtensionsReloaded]: ExtensionsReloadedPayload;
 	[BusChannels.ContextActivity]: ContextActivityPayload;
 	[BusChannels.ContextWarning]: ContextWarningPayload;
 	[BusChannels.ContextPruned]: ContextPrunedPayload;

package/src/core/bus-trace.ts

@@ -11,7 +11,7 @@
  * orchestrator-wide observability, not a domain concern. Add channels to the
  * `TRACED_CHANNELS` list if a future front needs to observe them.
  *
- * Ordering invariant: the first `[clio:bus] shutdown.requested` line must
+ * Ordering invariant: the first `[clio-coder:bus] shutdown.requested` line must
  * never reach stderr before the `Clio Coder: received <SIGNAL>, shutting down...`
  * notice written by termination.installSignalHandlers in
  * src/core/termination.ts. Future edits to termination.ts must preserve that
@@ -47,7 +47,7 @@ export function installBusTracer(): void {
 	const bus = getSharedBus();
 	for (const channel of TRACED_CHANNELS) {
 		bus.on(channel, (payload) => {
-			process.stderr.write(`[clio:bus] ${channel}${traceSuffix(payload)}\n`);
+			process.stderr.write(`[clio-coder:bus] ${channel}${traceSuffix(payload)}\n`);
 		});
 	}
 }

package/src/core/compile-cache.ts

@@ -65,7 +65,7 @@ export interface CompileCacheHandle {
  * exercise the settle semantics without flipping the real process-global
  * cache.
  */
-export function createCompileCache(
+function createCompileCache(
 	enableFn: typeof enableCompileCache = enableCompileCache,
 	rootExists: (dir: string) => boolean = existsSync,
 ): CompileCacheHandle {