@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/domains/middleware/memory-intervention.ts

@@ -4,7 +4,7 @@ import {
 	sanitizeToolResultDigest,
 	type ToolResultDigest,
 } from "../../tools/result-disposition.js";
-import { TASK_MEMORY_DEFAULT_PROCEDURAL_CAP, type TaskMemoryBank } from "../memory/task-bank.js";
+import { TASK_MEMORY_DEFAULT_PROCEDURAL_CAP, type TaskMemoryBank, type TaskMemoryEntry } from "../memory/task-bank.js";
 import {
 	runTaskMemoryPolicy,
 	TASK_MEMORY_POLICY_DEFAULT_TIMEOUT_MS,
@@ -12,6 +12,7 @@ import {
 	type TaskMemoryModelClient,
 	type TaskMemoryPolicyReason,
 	type TaskMemoryPolicyResult,
+	type TaskMemoryStepUsage,
 	type TaskMemoryTrajectoryStep,
 } from "../memory/task-memory-policy.js";
 import type { TaskMemoryActivityEvent } from "../memory/task-memory-status.js";
@@ -30,8 +31,10 @@ import type { MiddlewareEffect, MiddlewareHookInput } from "./types.js";
 
 export const MEMORY_INTERVENTION_REGISTRATION_ID = "observer.memory-intervention";
 export const MEMORY_INTERVENTION_DEFAULT_WINDOW_STEPS = 8;
-export const MEMORY_INTERVENTION_DEFAULT_MAX_TOKENS = 400;
+export const MEMORY_INTERVENTION_DEFAULT_MAX_TOKENS = 2_000;
 export const MEMORY_INTERVENTION_DEFAULT_EVERY_N_TOOLS = 10;
+/** Two full deadlines are enough evidence to stop spending this session's endpoint. */
+export const MEMORY_INTERVENTION_TIMEOUT_BACKOFF_THRESHOLD = 2;
 
 export const MEMORY_INTERVENTION_ACTIVITY_LIMIT = 20;
 
@@ -75,6 +78,27 @@ export interface MemoryInterventionDeps {
 	everyNTools?: number;
 	/** Lazily resolves the explicitly configured background role. Null means rules-only. */
 	getModelClient?: () => TaskMemoryModelClient | null;
+	/** Completion budget derived from the resolved background model capability. */
+	getModelMaxTokens?: (configuredMaxTokens: number) => number;
+	/**
+	 * True when the background target's inference endpoint is already serving the
+	 * chat target's stream. A memory step then either queues behind the operator's
+	 * own turn on a single-slot server or makes the server evict the resident
+	 * model to serve it, so the boundary is skipped and the skip is recorded.
+	 */
+	backgroundEndpointBusy?: () => boolean;
+	/**
+	 * Provider-reported spend for one completed model step. The composition root
+	 * routes it to the cost ledger; the middleware never prices anything.
+	 */
+	onStepUsage?: (usage: TaskMemoryStepUsage) => void;
+	/**
+	 * Bank entries an llm-tier reminder cited when it reached the operator. The
+	 * composition root proposes them into the durable memory store, which is what
+	 * connects the session bank to the records `/memory` and `clio-coder memory`
+	 * read. Best effort and content-bearing, exactly like `onEnvelope`.
+	 */
+	onInjectedEntries?: (entries: ReadonlyArray<TaskMemoryEntry>) => void;
 	/** Live next-turn settings view; individual fields above remain test-friendly fallbacks. */
 	getSettings?: () => Readonly<MemoryInterventionSettings>;
 	/** Best-effort content-free telemetry; sink failures never affect intervention. */
@@ -167,6 +191,7 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 	let outstandingStep: Promise<void> = Promise.resolve();
 	let rulesInjectedSincePromptedStep = false;
 	let annotatedSinceTurnEnd = false;
+	let consecutiveLlmTimeouts = 0;
 
 	return {
 		id: MEMORY_INTERVENTION_REGISTRATION_ID,
@@ -348,6 +373,7 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 			reminder: null,
 			inputTokens: 0,
 			outputTokens: 0,
+			usage: null,
 			effects: NO_EFFECTS,
 		});
 		const live = settings();
@@ -361,23 +387,38 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 		let tier: TaskMemoryTelemetryTier = "rules";
 		promptedStepTier = tier;
 		let promptedResult: TaskMemoryPolicyResult;
+		// A boundary that never reached the model is a skipped boundary rather than
+		// a policy decision, and `dropped` is the telemetry outcome for exactly
+		// that. The returned decision stays `silent`, since no reminder was
+		// produced and the policy vocabulary has no value for a step that never ran.
+		let telemetryDecision: TaskMemoryTelemetryDecision | null = null;
 		try {
-			const client = deps.getModelClient?.() ?? null;
-			if (client === null) {
-				promptedResult = silent("no_client");
+			if (consecutiveLlmTimeouts >= MEMORY_INTERVENTION_TIMEOUT_BACKOFF_THRESHOLD) {
+				promptedResult = silent("llm_timeout_backoff");
 			} else {
-				tier = "llm";
-				promptedStepTier = tier;
-				promptedResult = await runTaskMemoryPolicy(deps.bank, client, {
-					task: input.task?.trim() || currentTask,
-					trajectory: [...trajectory],
-					deterministicTrigger: input.deterministicTrigger,
-					maxTokens: live.maxTokens,
-					...(input.suppressIntervention === undefined ? {} : { suppressIntervention: input.suppressIntervention }),
-					previousReminder: lastInjectedMessage,
-					timeoutMs: live.timeoutMs,
-					...(deps.onEnvelope === undefined ? {} : { onEnvelope: deps.onEnvelope }),
-				});
+				const client = deps.getModelClient?.() ?? null;
+				if (client === null) {
+					promptedResult = silent("no_client");
+				} else if (deps.backgroundEndpointBusy?.() === true) {
+					tier = "llm";
+					promptedStepTier = tier;
+					promptedResult = silent("endpoint_busy");
+					telemetryDecision = "dropped";
+				} else {
+					tier = "llm";
+					promptedStepTier = tier;
+					promptedResult = await runTaskMemoryPolicy(deps.bank, client, {
+						task: input.task?.trim() || currentTask,
+						trajectory: [...trajectory],
+						deterministicTrigger: input.deterministicTrigger,
+						maxTokens: live.maxTokens,
+						modelMaxTokens: positiveInteger(deps.getModelMaxTokens?.(live.maxTokens), live.maxTokens),
+						...(input.suppressIntervention === undefined ? {} : { suppressIntervention: input.suppressIntervention }),
+						previousReminder: lastInjectedMessage,
+						timeoutMs: live.timeoutMs,
+						...(deps.onEnvelope === undefined ? {} : { onEnvelope: deps.onEnvelope }),
+					});
+				}
 			}
 		} catch (error) {
 			// runTaskMemoryPolicy resolves its own failures, so reaching here means
@@ -395,11 +436,21 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 				error: error instanceof Error ? error.message : "resolving the background model client failed",
 			});
 		}
+		if (tier === "llm" && promptedResult.decision === "timeout") consecutiveLlmTimeouts += 1;
+		else if (tier === "llm" && telemetryDecision !== "dropped") consecutiveLlmTimeouts = 0;
 		lastDecision = promptedResult.decision;
+		if (promptedResult.usage !== null) {
+			try {
+				deps.onStepUsage?.(promptedResult.usage);
+			} catch {
+				// Accounting is bookkeeping. A failing sink never changes memory behavior.
+			}
+		}
+		if (promptedResult.decision === "injected") reportInjectedEntries(promptedResult.reminder);
 		emitTelemetry(
 			triggers,
 			tier,
-			promptedResult.decision,
+			telemetryDecision ?? promptedResult.decision,
 			promptedResult.reason,
 			citedEntryCount(promptedResult.reminder),
 			promptedResult.inputTokens,
@@ -462,10 +513,35 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 		if (activity.length > MEMORY_INTERVENTION_ACTIVITY_LIMIT) activity.length = MEMORY_INTERVENTION_ACTIVITY_LIMIT;
 	}
 
-	function citedEntryCount(message: string | null): number {
-		if (message === null) return 0;
+	function citedEntries(message: string | null): TaskMemoryEntry[] {
+		if (message === null) return [];
 		const snapshot = deps.bank.snapshot();
-		return [...snapshot.knowledge, ...snapshot.procedural].filter((entry) => message.includes(`[${entry.id}]`)).length;
+		return [...snapshot.knowledge, ...snapshot.procedural].filter((entry) => message.includes(`[${entry.id}]`));
+	}
+
+	function citedEntryCount(message: string | null): number {
+		return citedEntries(message).length;
+	}
+
+	/**
+	 * Hand the cited entries to the durable store.
+	 *
+	 * Only the model tier reports here. A rules-tier reminder cites an entry this
+	 * middleware wrote itself out of one repeated tool failure, and proposing
+	 * every one of those as a durable lesson would fill the operator's review
+	 * queue with rows nobody asked for. The model tier's entries are the ones the
+	 * background plane produced, which is what #229 asks to be reviewable.
+	 */
+	function reportInjectedEntries(reminder: string | null): void {
+		if (deps.onInjectedEntries === undefined) return;
+		const entries = citedEntries(reminder);
+		if (entries.length === 0) return;
+		try {
+			deps.onInjectedEntries(entries);
+		} catch {
+			// A failing store is the composition root's problem to report, never a
+			// reason to fail the step that produced the reminder.
+		}
 	}
 
 	function observeBeforeTool(input: MiddlewareHookInput): void {

package/src/domains/middleware/memory-step-endpoint.ts

@@ -0,0 +1,71 @@
+/**
+ * Publishing and accounting for the endpoint a background memory step uses.
+ *
+ * A proactive-memory step that runs on the chat target's own endpoint moves
+ * that server's prefix cache, so the next turn is cold for a reason Clio caused
+ * and can name. The turn context turns {@link BusChannels.MemoryStepCompleted}
+ * into the `background_memory` expected-cold reason; without it `/context`
+ * reports the turn as an unexplained provider re-prefill.
+ *
+ * The disturbance is a property of the request having left the process, not of
+ * the answer coming back. A step that times out still had its whole trajectory
+ * prefilled into the single prefix slot, because aborting the HTTP request does
+ * not stop a llama.cpp prefill (the measurement is recorded in
+ * `src/interactive/turn-prewarm.ts`). Publishing from the usage sink instead
+ * missed exactly that case, since usage is only assigned once the call resolves.
+ *
+ * The same request also occupies real endpoint capacity. Both responsibilities
+ * live here around the client's `complete`: the slot is registered only after
+ * the middleware's `endpoint_busy` admission check, so a step never sees its
+ * own slot, then released in the `finally` that also announces the disturbance.
+ * Both happen on resolve, timeout, and transport throw, and neither happens for
+ * a boundary that skipped the model altogether (`endpoint_busy`, no configured
+ * route), because those never call `complete`.
+ */
+
+import { BusChannels } from "../../core/bus-events.js";
+import type { SafeEventBus } from "../../core/event-bus.js";
+import { registerForegroundStream } from "../providers/endpoint-capacity.js";
+
+/** What the announcer needs: somewhere to publish, and the route to name. */
+export interface MemoryStepEndpointAnnouncerDeps {
+	bus: Pick<SafeEventBus, "emit"> | null;
+	/** Canonical endpoint the step calls, or null when the route has none. */
+	endpointKey: string | null;
+	targetId: string;
+}
+
+/**
+ * Wrap one background memory `complete` so every request that leaves the
+ * process holds one endpoint slot and publishes its endpoint exactly once,
+ * whatever the call does next.
+ *
+ * A route with no canonical endpoint key is unchanged. A null bus suppresses
+ * the announcement but still counts capacity for a route whose key is known.
+ */
+export function announceMemoryStepEndpoint<Request, Response>(
+	deps: MemoryStepEndpointAnnouncerDeps,
+	complete: (request: Request) => Promise<Response>,
+): (request: Request) => Promise<Response> {
+	const { bus, endpointKey, targetId } = deps;
+	if (endpointKey === null) return complete;
+	return async (request: Request): Promise<Response> => {
+		// `runPromptedStep` performs its busy check before it invokes `complete`,
+		// so this registration counts the outgoing request without self-refusing.
+		const releaseEndpointSlot = registerForegroundStream(endpointKey);
+		try {
+			return await complete(request);
+		} finally {
+			releaseEndpointSlot();
+			// Bookkeeping never changes memory behavior, and a crashing subscriber
+			// must not turn a resolved step into a failed one.
+			if (bus !== null) {
+				try {
+					bus.emit(BusChannels.MemoryStepCompleted, { endpointKey, targetId });
+				} catch {
+					// The safe bus already contains listener errors; this covers the rest.
+				}
+			}
+		}
+	};
+}

package/src/domains/mux/contract.ts

@@ -0,0 +1,434 @@
+/**
+ * The pane layer's cross-domain surface.
+ *
+ * Every method is best-effort. A mux failure never fails a dispatch, never
+ * throws at a caller, and never blocks the event loop on a dead socket: it logs
+ * and degrades to `available() === false`, which the consumers read as "use the
+ * native fleet surfaces instead". That is why every method here returns a
+ * fallback value rather than rejecting.
+ *
+ * Two ownership rules run through the whole file. Clio acts only on panes it
+ * created, tracked in `pane-registry.ts` and tagged with the `clio_owner`
+ * metadata token so `clio doctor` can find orphans. The one documented
+ * exception is Clio's own hosting pane in guest mode, which `reportSelf`
+ * writes to under SA-3 of the v0.4.0 cycle plan.
+ *
+ * What is deliberately absent: per-run viewer panes. The v0.4.0 phase 3/4
+ * integration opened a pane per dispatched run in a hidden Fleet tab, with a
+ * focus ladder, run-state reporting, and resume adoption keyed on run ids. All
+ * of that projected fleet state the native surfaces already show onto panes
+ * nobody had asked for. The one run-viewing surface is now the workers-view
+ * watch pane (src/interactive/watch-pane.ts): a single utility pane following
+ * a selection file, opened on operator demand and retargeted by file writes
+ * that never touch this socket.
+ */
+
+import type { DomainContract } from "../../core/domain-loader.js";
+import type { MuxDetection } from "./detect.js";
+import { createPaneRegistry, type MuxPaneRegistry, paneRecord } from "./pane-registry.js";
+import { muxSupportsMethod } from "./protocol.js";
+import type {
+	MuxClient,
+	MuxSubscription,
+	MuxWorktreeCreatedResult,
+	MuxWorktreeCreateRequest,
+} from "./socket-client.js";
+import {
+	MuxError,
+	type MuxEvent,
+	type MuxLog,
+	type MuxMode,
+	type MuxNotificationSound,
+	type MuxPanePurpose,
+	type MuxPaneRecord,
+	type MuxPaneRef,
+	type MuxSelfReport,
+} from "./types.js";
+
+/** Metadata source for everything Clio's pane layer writes. */
+const METADATA_SOURCE = "clio:mux";
+/** Agent-authority source for Clio's own hosting pane, per SA-3. */
+const SELF_AGENT_SOURCE = "clio:coder";
+/** Token every Clio-created pane carries so orphans are findable. */
+const OWNER_TOKEN_KEY = "clio_owner";
+const OWNER_TOKEN_VALUE = "clio:mux";
+/** herdr caps a metadata token value at 80 characters. */
+const TOKEN_VALUE_MAX = 80;
+/** How long `available()` stays false after a transport failure before probing again. */
+const DEGRADE_COOLDOWN_MS = 5_000;
+
+export interface MuxOpenUtilityPaneRequest {
+	argv: ReadonlyArray<string>;
+	cwd: string;
+	label: string;
+	/** Operator-facing pane title. Omitted when the caller wants the shell default. */
+	title?: string;
+	purpose?: MuxPanePurpose;
+	direction?: "right" | "down";
+	env?: Readonly<Record<string, string>>;
+	/**
+	 * Absolute path the pane's stdout is redirected into. Full-screen programs
+	 * such as Yazi reopen `/dev/tty` for their interface when stdout is not a tty.
+	 */
+	stdoutPath?: string;
+}
+
+export interface MuxNotifyRequest {
+	title: string;
+	body?: string;
+	sound?: MuxNotificationSound;
+}
+
+export interface MuxContract extends DomainContract {
+	readonly mode: MuxMode;
+	/** `mode !== "none"` and the socket is currently healthy. */
+	available(): boolean;
+	/**
+	 * The rung detection resolved to, with the socket it answered on and the
+	 * protocol recorded from the handshake. `/panes` and `clio-coder doctor`
+	 * print it; the notify and worktree paths gate on its protocol.
+	 */
+	detection(): Readonly<MuxDetection>;
+	openUtilityPane(request: MuxOpenUtilityPaneRequest): Promise<MuxPaneRef | null>;
+	/** Close one Clio-created pane by pane id. Refuses a pane Clio did not create. */
+	closePane(paneId: string): Promise<boolean>;
+	/**
+	 * Re-adopt one pane of the given purpose that outlived the process that made
+	 * it. A fresh `session.snapshot` is scanned for a pane carrying Clio's owner
+	 * token and a matching `role` token; the first hit is recorded and returned.
+	 * This is what stops a restarted session's Enter-in-the-workers-view from
+	 * opening a second watch pane beside the surviving one.
+	 */
+	adoptPane(request: { purpose: MuxPanePurpose; label: string }): Promise<MuxPaneRef | null>;
+	notify(request: MuxNotifyRequest): Promise<void>;
+	/** Optional compete storage route. Protocol-gated with a native Git fallback at the caller. */
+	worktreeCreate(request: MuxWorktreeCreateRequest): Promise<MuxWorktreeCreatedResult | null>;
+	/** Remove a herdr worktree workspace. False tells the caller to use native Git cleanup. */
+	worktreeRemove(workspaceId: string, options?: { force?: boolean }): Promise<boolean>;
+	/**
+	 * Called when a pane Clio owns leaves, whether the user closed it or the
+	 * program in it exited. Callers record it and do not reopen: a closed pane
+	 * is a decision, not a fault.
+	 */
+	onPaneGone(handler: (record: MuxPaneRecord) => void): () => void;
+	/** Panes Clio created, with their purpose. */
+	list(): ReadonlyArray<MuxPaneRecord>;
+	/**
+	 * Report Clio's own state on its hosting pane (SA-3). Returns false when
+	 * there is no pane to report on, which is every mode but guest.
+	 */
+	reportSelf(report: MuxSelfReport): Promise<boolean>;
+	shutdown(): Promise<void>;
+}
+
+export interface MuxRuntimeOptions {
+	detection: MuxDetection;
+	client: MuxClient | null;
+	log?: MuxLog;
+	now?: () => number;
+}
+
+/** The contract plus the lifecycle handles the domain extension drives. */
+export interface MuxRuntime {
+	contract: MuxContract;
+	start(): Promise<void>;
+	stop(): Promise<void>;
+	/** Test seam: the registry the contract reconciles against. */
+	registry: MuxPaneRegistry;
+}
+
+/** POSIX single-quoting, so an argv element with spaces or quotes survives the shell. */
+function shellQuote(argv: ReadonlyArray<string>): string {
+	return argv.map((arg) => `'${arg.replaceAll("'", `'\\''`)}'`).join(" ");
+}
+
+function token(value: string | undefined | null): string | null {
+	if (typeof value !== "string" || value.length === 0) return null;
+	return value.length > TOKEN_VALUE_MAX ? value.slice(0, TOKEN_VALUE_MAX) : value;
+}
+
+export function createMuxRuntime(options: MuxRuntimeOptions): MuxRuntime {
+	const { detection, client } = options;
+	const log = options.log ?? ((): void => undefined);
+	const now = options.now ?? Date.now;
+	const registry = createPaneRegistry();
+
+	let healthy = client !== null;
+	let probeHealthAt = 0;
+	let stopped = false;
+	let subscription: MuxSubscription | null = null;
+	const paneGoneHandlers = new Set<(record: MuxPaneRecord) => void>();
+
+	const degrade = (what: string, error: unknown): void => {
+		const message = error instanceof Error ? error.message : String(error);
+		const transport = error instanceof MuxError && (error.kind === "transport" || error.kind === "timeout");
+		if (transport) {
+			healthy = false;
+			probeHealthAt = now() + DEGRADE_COOLDOWN_MS;
+		}
+		log(transport ? "warning" : "debug", `mux ${what} failed: ${message}`);
+	};
+
+	const usable = (): boolean => {
+		if (stopped || client === null || detection.mode === "none") return false;
+		return healthy || now() >= probeHealthAt;
+	};
+
+	/**
+	 * Runs one mux interaction and swallows everything it can throw. The fallback
+	 * is what the caller sees when the pane layer is not there, which is the same
+	 * value it sees in `none` mode.
+	 */
+	const attempt = async <T>(what: string, run: (live: MuxClient) => Promise<T>, fallback: T): Promise<T> => {
+		if (!usable() || client === null) return fallback;
+		try {
+			const value = await run(client);
+			healthy = true;
+			return value;
+		} catch (error) {
+			degrade(what, error);
+			return fallback;
+		}
+	};
+
+	const tagOwner = async (
+		live: MuxClient,
+		paneId: string,
+		tokens: Readonly<Record<string, string | null>>,
+		title?: string,
+	): Promise<void> => {
+		await live.paneReportMetadata({
+			paneId,
+			source: METADATA_SOURCE,
+			...(title === undefined ? {} : { title }),
+			tokens: { [OWNER_TOKEN_KEY]: OWNER_TOKEN_VALUE, ...tokens },
+		});
+	};
+
+	const onEvent = (event: MuxEvent): void => {
+		const dropped = registry.forget(event.paneId);
+		if (dropped) {
+			log("debug", `mux pane ${event.paneId} left on ${event.kind}; dropped from the registry`);
+			for (const handler of paneGoneHandlers) {
+				try {
+					handler(dropped);
+				} catch (error) {
+					log("debug", `mux pane-gone handler threw: ${error instanceof Error ? error.message : String(error)}`);
+				}
+			}
+		}
+	};
+
+	const contract: MuxContract = {
+		mode: detection.mode,
+
+		available(): boolean {
+			return usable();
+		},
+
+		detection(): Readonly<MuxDetection> {
+			return detection;
+		},
+
+		async openUtilityPane(request: MuxOpenUtilityPaneRequest): Promise<MuxPaneRef | null> {
+			return await attempt(
+				"openUtilityPane",
+				async (live) => {
+					const anchor = detection.self.paneId ?? (await live.paneCurrent()).paneId;
+					const pane = await live.paneSplit({
+						direction: request.direction ?? "right",
+						targetPaneId: anchor,
+						cwd: request.cwd,
+						focus: false,
+						...(request.env ? { env: request.env } : {}),
+					});
+					const ref: MuxPaneRef = { paneId: pane.paneId, tabId: pane.tabId, workspaceId: pane.workspaceId };
+					const purpose = request.purpose ?? "utility";
+					registry.record(paneRecord(ref, { purpose, label: request.label, openedAt: now() }));
+					const title = request.title;
+					const titleSupported = title !== undefined && muxSupportsMethod(detection.server, "pane.rename");
+					if (titleSupported) {
+						try {
+							await live.paneRename(pane.paneId, title);
+						} catch {
+							// Presentation is optional. A server that advertises the floor but
+							// lacks or refuses rename must not strand an otherwise healthy pane.
+						}
+					}
+					// The `role` token is what adoptPane finds again after a restart.
+					await tagOwner(live, pane.paneId, { role: token(purpose) }, titleSupported ? title : undefined);
+					if (request.argv.length > 0) {
+						// herdr has no argv parameter on pane.split, so the command goes in
+						// through the pane's shell. `exec` replaces the shell so the pane
+						// exits with the program and emits pane.exited for reconciliation.
+						const redirect = request.stdoutPath ? ` > ${shellQuote([request.stdoutPath])}` : "";
+						await live.paneSendText(pane.paneId, `exec ${shellQuote(request.argv)}${redirect}\n`);
+					}
+					return ref;
+				},
+				null,
+			);
+		},
+
+		async closePane(paneId: string): Promise<boolean> {
+			// The ownership rule, restated for the operator-facing path: `/panes
+			// close` addresses panes by id and must refuse anything the registry
+			// does not hold.
+			if (!registry.owns(paneId)) return false;
+			return await attempt(
+				"closePane",
+				async (live) => {
+					await live.paneClose(paneId);
+					registry.forget(paneId);
+					return true;
+				},
+				false,
+			);
+		},
+
+		async adoptPane(request: { purpose: MuxPanePurpose; label: string }): Promise<MuxPaneRef | null> {
+			const existing = registry.byPurpose(request.purpose);
+			if (existing) return existing.ref;
+			return await attempt(
+				"adoptPane",
+				async (live) => {
+					const snapshot = await live.snapshot();
+					for (const pane of snapshot.panes) {
+						if (pane.tokens[OWNER_TOKEN_KEY] !== OWNER_TOKEN_VALUE) continue;
+						if (pane.tokens.role !== request.purpose) continue;
+						if (registry.owns(pane.paneId)) continue;
+						// Another workspace's pane belongs to another session's screen;
+						// adopting it would retarget a surface the operator cannot see.
+						if (detection.self.workspaceId !== null && pane.workspaceId !== detection.self.workspaceId) continue;
+						const ref: MuxPaneRef = { paneId: pane.paneId, tabId: pane.tabId, workspaceId: pane.workspaceId };
+						registry.record(
+							paneRecord(ref, { purpose: request.purpose, label: request.label, openedAt: now(), adopted: true }),
+						);
+						log("info", `mux adopted a ${request.purpose} pane left open by a previous session`);
+						return ref;
+					}
+					return null;
+				},
+				null,
+			);
+		},
+
+		async notify(request: MuxNotifyRequest): Promise<void> {
+			if (!muxSupportsMethod(detection.server, "notification.show")) {
+				log("debug", `mux notify skipped, server protocol is below the notification.show floor: ${request.title}`);
+				return;
+			}
+			await attempt(
+				"notify",
+				async (live) => {
+					const result = await live.notificationShow({
+						title: request.title,
+						...(request.body ? { body: request.body } : {}),
+						...(request.sound ? { sound: request.sound } : {}),
+					});
+					// A suppressed toast is the operator's own herdr config talking
+					// (disabled, rate limited, no foreground client). Reporting it as a
+					// warning would turn their setting into Clio's error.
+					if (!result.shown) log("debug", `mux notify not shown (${result.reason}): ${request.title}`);
+					return undefined;
+				},
+				undefined,
+			);
+		},
+
+		async worktreeCreate(request: MuxWorktreeCreateRequest): Promise<MuxWorktreeCreatedResult | null> {
+			if (!muxSupportsMethod(detection.server, "worktree.create")) {
+				log("debug", "mux worktree.create skipped, server protocol is below the worktree floor");
+				return null;
+			}
+			return await attempt("worktreeCreate", (live) => live.worktreeCreate(request), null);
+		},
+
+		async worktreeRemove(workspaceId: string, removeOptions = {}): Promise<boolean> {
+			if (!muxSupportsMethod(detection.server, "worktree.remove")) {
+				log("debug", "mux worktree.remove skipped, server protocol is below the worktree floor");
+				return false;
+			}
+			return await attempt(
+				"worktreeRemove",
+				async (live) => {
+					await live.worktreeRemove(workspaceId, removeOptions);
+					return true;
+				},
+				false,
+			);
+		},
+
+		onPaneGone(handler: (record: MuxPaneRecord) => void): () => void {
+			paneGoneHandlers.add(handler);
+			return () => {
+				paneGoneHandlers.delete(handler);
+			};
+		},
+
+		list(): ReadonlyArray<MuxPaneRecord> {
+			return registry.list();
+		},
+
+		async reportSelf(report: MuxSelfReport): Promise<boolean> {
+			const paneId = detection.self.paneId;
+			if (detection.mode !== "guest" || !paneId) return false;
+			return await attempt(
+				"reportSelf",
+				async (live) => {
+					await live.paneReportAgent({
+						paneId,
+						source: SELF_AGENT_SOURCE,
+						agent: "clio-coder",
+						state: report.state,
+						...(report.message ? { message: report.message } : {}),
+					});
+					if (report.tokens || report.stateLabels || report.ttlMs !== undefined) {
+						await live.paneReportMetadata({
+							paneId,
+							source: METADATA_SOURCE,
+							...(report.tokens ? { tokens: report.tokens } : {}),
+							...(report.stateLabels ? { stateLabels: report.stateLabels } : {}),
+							...(report.ttlMs !== undefined ? { ttlMs: report.ttlMs } : {}),
+						});
+					}
+					return true;
+				},
+				false,
+			);
+		},
+
+		async shutdown(): Promise<void> {
+			if (stopped) return;
+			stopped = true;
+			subscription?.close();
+			subscription = null;
+			paneGoneHandlers.clear();
+			// Pane ownership is server-side and intentionally survives process
+			// shutdown. Keep the local snapshot too so the contract itself proves
+			// shutdown tears down sockets, never panes.
+			if (client) await client.close().catch(() => undefined);
+		},
+	};
+
+	const start = async (): Promise<void> => {
+		if (detection.mode === "none" || client === null) return;
+		try {
+			subscription = await client.subscribe(["pane.closed", "pane.exited"], onEvent, {
+				onResync: (snapshot) => {
+					// A reconnect means events were missed. The snapshot is the authority
+					// on which panes still exist, so anything Clio thinks it owns that is
+					// absent from it is gone.
+					const dropped = registry.reconcile(snapshot.panes.map((pane) => pane.paneId));
+					if (dropped.length > 0) {
+						log("info", `mux reconciled ${dropped.length} pane(s) closed while the socket was down`);
+					}
+				},
+			});
+		} catch (error) {
+			degrade("event subscription", error);
+		}
+	};
+
+	return { contract, start, stop: contract.shutdown, registry };
+}