@iowarp/clio-coder 0.4.0 → 0.4.2

package/src/domains/middleware/runtime.ts

@@ -1,4 +1,5 @@
 import { createHookBudgetTracker, type HookBudgetStats, type HookBudgetTracker } from "./budget.js";
+import type { MiddlewareRegistrationConflictTier, MiddlewareRegistrationOwner } from "./registrations.js";
 import { listMiddlewareRuleDefinitions } from "./rules.js";
 import {
 	MIDDLEWARE_HOOK_TEXT_MAX_CHARS,
@@ -90,6 +91,20 @@ export type MiddlewareDiagnostic =
 			steadyStateWarn: boolean;
 			/** Rolling-window stats (p50/p95/over-count) for diagnosis. */
 			stats: HookBudgetStats;
+	  }
+	| {
+			/**
+			 * An owned registration set offered an id already held by a builtin
+			 * rule or a host registration (dropped), or a later host registration
+			 * took an id an owner held (evicted). Bookkeeping only; nothing was
+			 * evaluated.
+			 */
+			kind: "registration_conflict";
+			registrationId: string;
+			owner: MiddlewareRegistrationOwner;
+			generation: number;
+			conflictsWith: MiddlewareRegistrationConflictTier;
+			action: "dropped" | "evicted";
 	  };
 
 export type MiddlewareDiagnosticSink = (diagnostic: MiddlewareDiagnostic) => void;
@@ -102,10 +117,14 @@ export type MiddlewareDiagnosticSink = (diagnostic: MiddlewareDiagnostic) => voi
 export function writeMiddlewareDiagnosticToStderr(diagnostic: MiddlewareDiagnostic): void {
 	if (diagnostic.kind === "hook_failed") {
 		process.stderr.write(
-			`[clio:middleware] registration '${diagnostic.registrationId}' failed on '${diagnostic.hook}': ${diagnostic.message}\n`,
+			`[clio-coder:middleware] registration '${diagnostic.registrationId}' failed on '${diagnostic.hook}': ${diagnostic.message}\n`,
 		);
 		return;
 	}
+	if (diagnostic.kind === "registration_conflict") {
+		process.stderr.write(`[clio-coder:middleware] ${formatRegistrationConflict(diagnostic)}\n`);
+		return;
+	}
 	// A single post-warmup spike is telemetry, not operator-facing noise: only
 	// consistent slowness prints, unless CLIO_CODER_HOOK_BUDGET_DEBUG=1 asks for all.
 	if (!diagnostic.steadyStateWarn && process.env.CLIO_CODER_HOOK_BUDGET_DEBUG !== "1") return;
@@ -115,11 +134,20 @@ export function writeMiddlewareDiagnosticToStderr(diagnostic: MiddlewareDiagnost
 			? ` (slow on ${stats.overCount}/${stats.window} recent ${diagnostic.hook} calls, p95 ${stats.p95Ms.toFixed(1)}ms)`
 			: "";
 	process.stderr.write(
-		`[clio:middleware] registration '${diagnostic.registrationId}' exceeded budget on '${diagnostic.hook}': ` +
+		`[clio-coder:middleware] registration '${diagnostic.registrationId}' exceeded budget on '${diagnostic.hook}': ` +
 			`${diagnostic.elapsedMs.toFixed(1)}ms > ${diagnostic.budgetMs}ms${trend}\n`,
 	);
 }
 
+/** One operator line for a registration_conflict diagnostic. */
+export function formatRegistrationConflict(
+	diagnostic: Extract<MiddlewareDiagnostic, { kind: "registration_conflict" }>,
+): string {
+	return diagnostic.action === "dropped"
+		? `${diagnostic.owner} registration '${diagnostic.registrationId}' (generation ${diagnostic.generation}) dropped: id is held by a ${diagnostic.conflictsWith} registration`
+		: `${diagnostic.owner} registration '${diagnostic.registrationId}' (generation ${diagnostic.generation}) evicted by a ${diagnostic.conflictsWith} registration with the same id`;
+}
+
 /**
  * Wrap a declarative rule definition as a degenerate coded registration so a
  * single ordered evaluation path serves both. The wrapped `evaluate` keeps the

package/src/domains/middleware/snapshot.ts

@@ -1,13 +1,14 @@
 import { createHookBudgetTracker, resolveHookBudgetsFromEnv, resolveHookBudgetTunablesFromEnv } from "./budget.js";
 import type { MiddlewareContract } from "./contract.js";
+import { createMiddlewareRegistrationTable } from "./registrations.js";
 import { cloneMiddlewareRule, listMiddlewareRuleDefinitions, listMiddlewareRules } from "./rules.js";
 import {
 	cloneMiddlewareEffect,
 	type MiddlewareDiagnosticSink,
-	type MiddlewareHookRegistration,
 	type MiddlewareRuleDefinition,
 	registrationFromRuleDefinition,
 	runMiddlewareRegistrations,
+	writeMiddlewareDiagnosticToStderr,
 } from "./runtime.js";
 import type { MiddlewareRule, MiddlewareSnapshot } from "./types.js";
 
@@ -39,15 +40,20 @@ export function createMiddlewareContractFromSnapshot(snapshot: MiddlewareSnapsho
 		if (builtin?.predicate !== undefined) definition.predicate = builtin.predicate;
 		return definition;
 	});
-	const registrations: MiddlewareHookRegistration[] = definitions.map(registrationFromRuleDefinition);
-	const registeredIds = new Set(registrations.map((registration) => registration.id));
+	let diagnosticSink: MiddlewareDiagnosticSink | undefined;
+	// Workers never receive owned registrations; the table exists so the
+	// worker contract satisfies the same interface with the same semantics.
+	const table = createMiddlewareRegistrationTable({
+		fixed: definitions.map(registrationFromRuleDefinition),
+		diagnosticSink: () => diagnosticSink ?? writeMiddlewareDiagnosticToStderr,
+	});
 	const budgetTracker = createHookBudgetTracker({
 		budgets: resolveHookBudgetsFromEnv(),
 		...resolveHookBudgetTunablesFromEnv(),
 	});
-	let diagnosticSink: MiddlewareDiagnosticSink | undefined;
 	return {
 		runHook(input) {
+			const registrations = table.list();
 			return runMiddlewareRegistrations(input, registrations, {
 				budgetTracker,
 				...(diagnosticSink !== undefined ? { onDiagnostic: diagnosticSink } : {}),
@@ -60,12 +66,19 @@ export function createMiddlewareContractFromSnapshot(snapshot: MiddlewareSnapsho
 			return createMiddlewareSnapshot(definitions.map((definition) => definition.rule));
 		},
 		registerHook(registration) {
-			if (registeredIds.has(registration.id)) return;
-			registeredIds.add(registration.id);
-			registrations.push(registration);
+			table.registerHook(registration);
 		},
 		setDiagnosticSink(sink) {
 			diagnosticSink = sink;
 		},
+		prepareRegistrationReplacement(owner, generation, registrations) {
+			return table.prepareReplacement(owner, generation, registrations);
+		},
+		replaceRegistrations(owner, generation, registrations) {
+			return table.replaceRegistrations(owner, generation, registrations);
+		},
+		ownedGeneration(owner) {
+			return table.ownedGeneration(owner);
+		},
 	};
 }

package/src/domains/mux/contract.ts

@@ -8,7 +8,7 @@
  * 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`
+ * created, tracked in `pane-registry.ts` and tagged with the `clio_coder_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.
@@ -25,6 +25,7 @@
 
 import type { DomainContract } from "../../core/domain-loader.js";
 import type { MuxDetection } from "./detect.js";
+import { createDockController, type DockController, type DockSlot, type DockState } from "./dock-controller.js";
 import { createPaneRegistry, type MuxPaneRegistry, paneRecord } from "./pane-registry.js";
 import { muxSupportsMethod } from "./protocol.js";
 import type {
@@ -46,12 +47,15 @@ import {
 } from "./types.js";
 
 /** Metadata source for everything Clio's pane layer writes. */
-const METADATA_SOURCE = "clio:mux";
+const METADATA_SOURCE = "clio-coder:mux";
 /** Agent-authority source for Clio's own hosting pane, per SA-3. */
-const SELF_AGENT_SOURCE = "clio:coder";
+const SELF_AGENT_SOURCE = "clio-coder:coder";
 /** Token every Clio-created pane carries so orphans are findable. */
-const OWNER_TOKEN_KEY = "clio_owner";
-const OWNER_TOKEN_VALUE = "clio:mux";
+const OWNER_TOKEN_KEY = "clio_coder_owner";
+const OWNER_TOKEN_VALUE = "clio-coder:mux";
+/** Old-host cleanup bridge; ownership readers retain this indefinitely. */
+const LEGACY_OWNER_TOKEN_KEY = "clio_owner";
+const LEGACY_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. */
@@ -71,6 +75,13 @@ export interface MuxOpenUtilityPaneRequest {
 	 * such as Yazi reopen `/dev/tty` for their interface when stdout is not a tty.
 	 */
 	stdoutPath?: string;
+	/**
+	 * Managed placement: the pane becomes this slot's dock, split from the
+	 * anchor with the slot's direction and sized to `share` of the axis
+	 * (clamped, cell-floored). Requires the layout tier (protocol 17); below
+	 * the floor the request degrades to a plain split and `direction` applies.
+	 */
+	dock?: { slot: DockSlot; share?: number };
 }
 
 export interface MuxNotifyRequest {
@@ -99,7 +110,33 @@ export interface MuxContract extends DomainContract {
 	 * 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>;
+	adoptPane(request: { purpose: MuxPanePurpose; label: string; dock?: DockSlot }): Promise<MuxPaneRef | null>;
+	/**
+	 * Focus one Clio-created pane, switching the user's view to it (pane.focus
+	 * moves the focused tab too). Explicit-request only; refuses foreign panes
+	 * and servers below the pane.focus floor.
+	 */
+	focusPane(paneId: string): Promise<boolean>;
+	/** Zoom one Clio-created pane on, off, or toggled. Zooming steals focus; same rule as focusPane. */
+	zoomPane(paneId: string, mode: "on" | "off" | "toggle"): Promise<boolean>;
+	/**
+	 * Bring keyboard focus back to Clio's own hosting pane. This is the return
+	 * half of every explicit pane interaction: a pick in the files pane, a
+	 * toggle that closed a pane the operator was looking at. False outside
+	 * guest mode, without an anchor pane, or below the pane.focus floor.
+	 */
+	focusSelf(): Promise<boolean>;
+	/**
+	 * Leave zoom on the tab that hosts Clio, so a dock split from the anchor is
+	 * visible again. A zoomed tab hides every pane but one; opening or focusing
+	 * the files pane behind a zoom would report success for a pane the operator
+	 * cannot see. False when nothing was zoomed or the tier is absent.
+	 */
+	unzoomSelf(): Promise<boolean>;
+	/** Set a dock's share of its axis. False when the slot has no dock or the tier is absent. */
+	resizeDock(slot: DockSlot, share: number): Promise<boolean>;
+	/** Live dock geometry states, for `/panes` status. */
+	docks(): ReadonlyArray<DockState>;
 	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>;
@@ -147,11 +184,25 @@ function token(value: string | undefined | null): string | null {
 	return value.length > TOKEN_VALUE_MAX ? value.slice(0, TOKEN_VALUE_MAX) : value;
 }
 
+function hasOwnedPaneToken(tokens: Readonly<Record<string, string>>): boolean {
+	return tokens[OWNER_TOKEN_KEY] === OWNER_TOKEN_VALUE || tokens[LEGACY_OWNER_TOKEN_KEY] === LEGACY_OWNER_TOKEN_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();
+	const anchorPaneId = detection.self.paneId;
+	/**
+	 * The managed dock tier needs an anchor to split from and the protocol-17
+	 * layout methods to converge with. Absent either, dock requests degrade to
+	 * plain utility splits and the rest of the tier answers false/empty.
+	 */
+	const docks: DockController | null =
+		client !== null && anchorPaneId !== null && muxSupportsMethod(detection.server, "layout.export")
+			? createDockController({ client, anchorPaneId, log })
+			: null;
 
 	let healthy = client !== null;
 	let probeHealthAt = 0;
@@ -201,11 +252,30 @@ export function createMuxRuntime(options: MuxRuntimeOptions): MuxRuntime {
 			paneId,
 			source: METADATA_SOURCE,
 			...(title === undefined ? {} : { title }),
-			tokens: { [OWNER_TOKEN_KEY]: OWNER_TOKEN_VALUE, ...tokens },
+			tokens: {
+				[OWNER_TOKEN_KEY]: OWNER_TOKEN_VALUE,
+				[LEGACY_OWNER_TOKEN_KEY]: LEGACY_OWNER_TOKEN_VALUE,
+				...tokens,
+			},
 		});
 	};
 
 	const onEvent = (event: MuxEvent): void => {
+		if (event.kind === "layout.updated") {
+			docks?.noteLayoutUpdated(event.geometry);
+			return;
+		}
+		if (event.kind === "pane.moved") {
+			// herdr rewrites the pane id on a move; the registry and dock state
+			// follow it so ownership is not lost to the user reorganizing.
+			const held = registry.forget(event.previousPaneId);
+			if (held) {
+				registry.record({ ...held, ref: { paneId: event.paneId, tabId: event.tabId, workspaceId: event.workspaceId } });
+				docks?.notePaneMoved(event.previousPaneId, event.paneId, event.tabId);
+			}
+			return;
+		}
+		docks?.notePaneGone(event.paneId);
 		const dropped = registry.forget(event.paneId);
 		if (dropped) {
 			log("debug", `mux pane ${event.paneId} left on ${event.kind}; dropped from the registry`);
@@ -231,38 +301,57 @@ export function createMuxRuntime(options: MuxRuntimeOptions): MuxRuntime {
 		},
 
 		async openUtilityPane(request: MuxOpenUtilityPaneRequest): Promise<MuxPaneRef | null> {
+			// Idempotence for docks: a slot that already has a pane answers with it.
+			const dockSlot = request.dock?.slot;
+			if (dockSlot && docks) {
+				const existing = docks.stateFor(dockSlot);
+				const held = existing ? registry.byPaneId(existing.paneId) : null;
+				if (held) return held.ref;
+			}
 			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 };
+					let ref: MuxPaneRef;
+					if (request.dock && docks) {
+						const placed = await docks.open(request.dock.slot, {
+							...(request.dock.share === undefined ? {} : { share: request.dock.share }),
+							cwd: request.cwd,
+							...(request.env ? { env: request.env } : {}),
+						});
+						// A refusal (anchor too small) is an answer, not a failure.
+						if (placed === null) return null;
+						ref = placed;
+					} else {
+						const anchor = anchorPaneId ?? (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 } : {}),
+						});
+						ref = { 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);
+							await live.paneRename(ref.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);
+					await tagOwner(live, ref.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`);
+						await live.paneSendText(ref.paneId, `exec ${shellQuote(request.argv)}${redirect}\n`);
 					}
 					return ref;
 				},
@@ -280,13 +369,18 @@ export function createMuxRuntime(options: MuxRuntimeOptions): MuxRuntime {
 				async (live) => {
 					await live.paneClose(paneId);
 					registry.forget(paneId);
+					// Dock state must fall with the registry entry, not ride on the async
+					// pane.closed push: if the event subscription failed at start(), no
+					// push ever comes, and a slot pointing at a dead pane makes every
+					// later dock open return the corpse.
+					docks?.notePaneGone(paneId);
 					return true;
 				},
 				false,
 			);
 		},
 
-		async adoptPane(request: { purpose: MuxPanePurpose; label: string }): Promise<MuxPaneRef | null> {
+		async adoptPane(request: { purpose: MuxPanePurpose; label: string; dock?: DockSlot }): Promise<MuxPaneRef | null> {
 			const existing = registry.byPurpose(request.purpose);
 			if (existing) return existing.ref;
 			return await attempt(
@@ -294,7 +388,7 @@ export function createMuxRuntime(options: MuxRuntimeOptions): MuxRuntime {
 				async (live) => {
 					const snapshot = await live.snapshot();
 					for (const pane of snapshot.panes) {
-						if (pane.tokens[OWNER_TOKEN_KEY] !== OWNER_TOKEN_VALUE) continue;
+						if (!hasOwnedPaneToken(pane.tokens)) continue;
 						if (pane.tokens.role !== request.purpose) continue;
 						if (registry.owns(pane.paneId)) continue;
 						// Another workspace's pane belongs to another session's screen;
@@ -304,6 +398,9 @@ export function createMuxRuntime(options: MuxRuntimeOptions): MuxRuntime {
 						registry.record(
 							paneRecord(ref, { purpose: request.purpose, label: request.label, openedAt: now(), adopted: true }),
 						);
+						// Crash recovery for a dock: the surviving pane takes the slot back so
+						// geometry management resumes instead of a second dock opening.
+						if (request.dock && docks) docks.adopt(request.dock, ref);
 						log("info", `mux adopted a ${request.purpose} pane left open by a previous session`);
 						return ref;
 					}
@@ -313,6 +410,68 @@ export function createMuxRuntime(options: MuxRuntimeOptions): MuxRuntime {
 			);
 		},
 
+		async focusPane(paneId: string): Promise<boolean> {
+			// Ownership first: focusing the user's own panes stays off the table
+			// even though the wire allows it.
+			if (!registry.owns(paneId)) return false;
+			if (!muxSupportsMethod(detection.server, "pane.focus")) return false;
+			return await attempt(
+				"focusPane",
+				async (live) => {
+					await live.paneFocus(paneId);
+					return true;
+				},
+				false,
+			);
+		},
+
+		async zoomPane(paneId: string, mode: "on" | "off" | "toggle"): Promise<boolean> {
+			if (!registry.owns(paneId)) return false;
+			if (!muxSupportsMethod(detection.server, "pane.zoom")) return false;
+			return await attempt(
+				"zoomPane",
+				async (live) => {
+					const result = await live.paneZoom(paneId, mode);
+					// A toggle always changes state; on/off report false when already there.
+					return result.changed;
+				},
+				false,
+			);
+		},
+
+		async focusSelf(): Promise<boolean> {
+			if (anchorPaneId === null || !muxSupportsMethod(detection.server, "pane.focus")) return false;
+			return await attempt(
+				"focusSelf",
+				async (live) => {
+					await live.paneFocus(anchorPaneId);
+					return true;
+				},
+				false,
+			);
+		},
+
+		async unzoomSelf(): Promise<boolean> {
+			if (anchorPaneId === null || !muxSupportsMethod(detection.server, "pane.zoom")) return false;
+			return await attempt(
+				"unzoomSelf",
+				async (live) => {
+					const result = await live.paneZoom(anchorPaneId, "off");
+					return result.changed;
+				},
+				false,
+			);
+		},
+
+		async resizeDock(slot: DockSlot, share: number): Promise<boolean> {
+			if (!docks) return false;
+			return await attempt("resizeDock", () => docks.resize(slot, share), false);
+		},
+
+		docks(): ReadonlyArray<DockState> {
+			return docks?.states() ?? [];
+		},
+
 		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}`);
@@ -404,9 +563,17 @@ export function createMuxRuntime(options: MuxRuntimeOptions): MuxRuntime {
 			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.
+			// Docks close with the session: a native application takes its windows
+			// with it. A crash never reaches this method, which is exactly what
+			// leaves dock panes behind for the next session's adoption path.
+			// Unmanaged utility panes are the operator's and stay open.
+			if (client && docks) {
+				for (const paneId of docks.paneIds()) {
+					await client.paneClose(paneId).catch(() => undefined);
+					registry.forget(paneId);
+				}
+				docks.clear();
+			}
 			if (client) await client.close().catch(() => undefined);
 		},
 	};
@@ -414,12 +581,15 @@ export function createMuxRuntime(options: MuxRuntimeOptions): MuxRuntime {
 	const start = async (): Promise<void> => {
 		if (detection.mode === "none" || client === null) return;
 		try {
-			subscription = await client.subscribe(["pane.closed", "pane.exited"], onEvent, {
+			const kinds: ("pane.closed" | "pane.exited" | "pane.moved" | "layout.updated")[] = ["pane.closed", "pane.exited"];
+			if (docks) kinds.push("pane.moved", "layout.updated");
+			subscription = await client.subscribe(kinds, 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));
+					for (const record of dropped) docks?.notePaneGone(record.ref.paneId);
 					if (dropped.length > 0) {
 						log("info", `mux reconciled ${dropped.length} pane(s) closed while the socket was down`);
 					}

package/src/domains/mux/detect.ts

@@ -9,8 +9,11 @@
  * call.
  *
  * Embedded mode resolves to `none` until Phase 5 lands the session bootstrap.
- * Asking for it is not an error; it degrades with a reason the doctor surface
- * can print.
+ * Asking for it is not an error, but it is a refusal rather than a quiet
+ * degrade: the detection carries `refused: true`, the boot prints the reason on
+ * stderr, and doctor's mode row warns. A session that asked for panes and got
+ * none should never have to guess why, and `embedded` costs guest mode too, so
+ * the reason names `auto` as the rung that works today.
  */
 
 import { homedir } from "node:os";
@@ -32,6 +35,15 @@ export interface MuxDetection {
 	candidates: ReadonlyArray<string>;
 	/** Human-readable reason, always set; for `guest` it names the socket that answered. */
 	reason: string;
+	/**
+	 * True when the operator asked for a rung Clio cannot provide, as opposed to
+	 * asking for panes on a machine that has no pane host. The two are both
+	 * `none` and neither is an error, but only the first is a promise Clio broke:
+	 * nothing about the environment would change the answer, and the operator has
+	 * to be told, because they configured a mode and got no panes. Callers raise
+	 * a refusal to a visible level; an ordinary `none` stays at debug.
+	 */
+	refused: boolean;
 }
 
 export interface DetectMuxOptions {
@@ -83,7 +95,7 @@ function readSelfLocation(env: NodeJS.ProcessEnv): MuxSelfLocation {
 	};
 }
 
-function none(reason: string, candidates: ReadonlyArray<string> = []): MuxDetection {
+function none(reason: string, candidates: ReadonlyArray<string> = [], refused = false): MuxDetection {
 	return {
 		mode: "none",
 		socketPath: null,
@@ -91,6 +103,7 @@ function none(reason: string, candidates: ReadonlyArray<string> = []): MuxDetect
 		self: { workspaceId: null, tabId: null, paneId: null },
 		candidates,
 		reason,
+		refused,
 	};
 }
 
@@ -113,9 +126,12 @@ export async function detectMux(options: DetectMuxOptions = {}): Promise<MuxDete
 		return { detection: none("panes are turned off"), client: null };
 	}
 	if (enabled === "embedded") {
-		// Phase 5 owns the session bootstrap. Until then the honest answer is that
-		// Clio cannot provide panes, not that it failed to find them.
-		return { detection: none("embedded mode is not implemented yet; it ships in phase 5"), client: null };
+		// Embedded mode (Clio owning the pane host) is not implemented yet. An
+		// operator who picked it wanted panes, so the rung degrades to guest
+		// detection instead of refusing everything; the notice below says which
+		// mode actually runs. When the guest ladder also fails, that failure is
+		// reported on its own terms.
+		log("info", "interface.panes.enabled=embedded is not implemented yet; detecting a guest pane host instead");
 	}
 	if (env.HERDR_ENV !== "1") {
 		return { detection: none("HERDR_ENV is not 1, so Clio is not running inside a pane host"), client: null };
@@ -137,6 +153,7 @@ export async function detectMux(options: DetectMuxOptions = {}): Promise<MuxDete
 					self: readSelfLocation(env),
 					candidates,
 					reason: `guest mode on ${socketPath} (herdr ${server.version}, protocol ${server.protocol})`,
+					refused: false,
 				},
 				client,
 			};