@iowarp/clio-coder 0.3.9 → 0.4.0

package/src/interactive/dispatch-board.ts

@@ -41,13 +41,8 @@ import { type CostProvenance, foregroundStreamUsage } from "../domains/providers
 import { sanitizeCallTargetText } from "../domains/safety/call-target.js";
 import { type Component, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "../engine/tui.js";
 import { formatWorkerContextMeter } from "./context-meter.js";
-import {
-	COUNCIL_SYNTHESIS_LABEL,
-	type CouncilGroupView,
-	type CouncilMemberView,
-	councilGroupBody,
-	councilIslandLines,
-} from "./council-grid.js";
+import { COUNCIL_SYNTHESIS_LABEL } from "./council.js";
+import { type CouncilGroupView, type CouncilMemberView, councilGroupBody, councilIslandLines } from "./council-grid.js";
 import { formatFooterTokens } from "./footer-panel.js";
 import {
 	type ClioTheme,
@@ -631,9 +626,15 @@ export function renderDispatchCard(
 	row: DispatchBoardRow,
 	width: number,
 	evidence?: RunEvidencePresentation,
-	options: { selected?: boolean; expanded?: boolean; endpointActive?: number } = {},
+	options: {
+		selected?: boolean;
+		expanded?: boolean;
+		endpointActive?: number;
+		endpointQueued?: number;
+		theme?: ClioTheme;
+	} = {},
 ): string[] {
-	const theme = clioTheme();
+	const theme = options.theme ?? clioTheme();
 	const contentWidth = Math.max(0, width - 4);
 	const agentLabel = agentDisplayLabel(row);
 	const elapsed = formatCompactMs(row.elapsedMs);
@@ -683,7 +684,12 @@ export function renderDispatchCard(
 		statusStr,
 		theme.fg("muted", `node ${row.node ?? "local"}`),
 		...(row.endpoint !== undefined
-			? [theme.fg("info", `slots ${options.endpointActive ?? 0}/${row.endpoint.limit} ${row.endpoint.label}`)]
+			? [
+					theme.fg(
+						"info",
+						`slots ${options.endpointActive ?? 0}/${row.endpoint.limit}${(options.endpointQueued ?? 0) > 0 ? ` +${options.endpointQueued} queued` : ""} ${row.endpoint.label}`,
+					),
+				]
 			: []),
 		...(row.gate !== undefined ? [theme.fg("info", `gate ${row.gate.role} c${row.gate.cycle}`)] : []),
 		...(row.rerouteCount !== undefined && row.rerouteCount > 0
@@ -1003,13 +1009,12 @@ export function formatDispatchBoardLines(
 	}
 
 	const endpointActive: Record<string, number> = { ...foregroundStreamUsage() };
+	const endpointQueued: Record<string, number> = {};
 	for (const row of rows) {
-		if (
-			row.endpoint !== undefined &&
-			(row.status === "running" || row.status === "stale" || row.status === "enqueued" || row.status === "cancelling")
-		) {
+		if (row.endpoint === undefined) continue;
+		if (row.status === "enqueued") endpointQueued[row.endpoint.key] = (endpointQueued[row.endpoint.key] ?? 0) + 1;
+		else if (row.status === "running" || row.status === "stale" || row.status === "cancelling")
 			endpointActive[row.endpoint.key] = (endpointActive[row.endpoint.key] ?? 0) + 1;
-		}
 	}
 
 	// A council is one question asked of several members, so its rows render as
@@ -1020,7 +1025,12 @@ export function formatDispatchBoardLines(
 			: renderDispatchCard(item.row, width, deriveRunEvidenceState(observability, item.row.runId), {
 					selected: item.row.runId === selectedRunId,
 					expanded: detailExpanded && item.row.runId === selectedRunId,
-					...(item.row.endpoint !== undefined ? { endpointActive: endpointActive[item.row.endpoint.key] ?? 0 } : {}),
+					...(item.row.endpoint !== undefined
+						? {
+								endpointActive: endpointActive[item.row.endpoint.key] ?? 0,
+								endpointQueued: endpointQueued[item.row.endpoint.key] ?? 0,
+							}
+						: {}),
 				}),
 	);
 	const body: string[] = [];

package/src/interactive/interactive-application.ts

@@ -12,6 +12,8 @@ import type { ExtensionsContract } from "../domains/extensions/index.js";
 import type { InteropContract } from "../domains/interop/index.js";
 import type { TaskMemoryOperatorStatus } from "../domains/memory/index.js";
 import { openDetachedBatchViews } from "../domains/middleware/index.js";
+import type { MuxContract } from "../domains/mux/index.js";
+import type { PanesOperations, PanesWatchController } from "../domains/mux/operations.js";
 import type { ObservabilityContract } from "../domains/observability/index.js";
 import type { ProvidersContract, ThinkingLevel } from "../domains/providers/index.js";
 import type { ResourcesContract } from "../domains/resources/index.js";
@@ -40,8 +42,10 @@ import { createProcessInteractiveShell, getActiveRenderTrace } from "./interacti
 import { createInteractiveSlashRuntime, resolveAvailableThinkingLevels } from "./interactive-slash-runtime.js";
 import { createInteractiveSubscriptions } from "./interactive-subscriptions.js";
 import { createInteractiveTickers } from "./interactive-tickers.js";
+import type { createMuxBridge } from "./mux-bridge.js";
 import { createOverlayLifecycle, type OverlayLifecycleController, type OverlayState } from "./overlay-lifecycle.js";
 import { interopOverlaySurface } from "./overlays/interop.js";
+import { paneWatchDecision } from "./pane-policy.js";
 import { writeInputWedgeDump } from "./render-trace.js";
 import { settleChatBeforeSessionSwitch } from "./session-switch-settlement.js";
 import { createSessionTranscript } from "./session-transcript.js";
@@ -53,7 +57,9 @@ import type {
 } from "./slash-commands.js";
 import { processAutoPacingAllowed, resolveSmoothStreamingMode } from "./stream-pacing-policy.js";
 import type { TerminalLease } from "./terminal-lease.js";
+import type { createWatchPaneController } from "./watch-pane.js";
 import { createWorkspaceFacts } from "./workspace-facts.js";
+import type { createYaziBridge, YaziBridge } from "./yazi-bridge.js";
 
 export {
 	IDLE_LEADER_STATE,
@@ -130,6 +136,36 @@ export interface InteractiveDeps {
 	extensions?: ExtensionsContract;
 	interop?: InteropContract;
 	share?: ShareContract;
+	/**
+	 * Pane layer. A `none` contract still reaches the interactive surface so the
+	 * files preset can use its terminal chooser; every mux operation remains
+	 * best-effort and never reaches a dispatch or a turn.
+	 */
+	mux?: MuxContract;
+	/**
+	 * Pane-layer operations behind `/panes` and the `panes` tool. Built by the
+	 * composition root so the tool registry and this surface drive one instance.
+	 */
+	panes?: PanesOperations;
+	/**
+	 * Factory seam for the dispatch-to-pane bridge, so a contract test can drive
+	 * it without a TUI. Production leaves it unset and gets `createMuxBridge`.
+	 */
+	createMuxBridge?: typeof createMuxBridge;
+	/** Bind the file-pane return path after the composer and TUI exist. */
+	attachYaziBridge?: (bridge: YaziBridge) => () => void;
+	/**
+	 * Watch-pane factory from the `--with-panes` composition root; absent on a
+	 * plain boot. The controller it builds backs Enter in the workers view.
+	 */
+	createWatchPane?: typeof createWatchPaneController;
+	/** Bind the watch controller into the shared PanesOperations for `/panes show`. */
+	attachWatchPane?: (controller: PanesWatchController) => () => void;
+	/**
+	 * File-pane factory. Supplied by the `--with-panes` composition root (or a
+	 * contract test); absent on a plain boot, which therefore loads no yazi code.
+	 */
+	createYaziBridge?: typeof createYaziBridge;
 	/**
 	 * Shared tool registry. When wired, the permission overlay opens automatically
 	 * whenever a tool call is parked waiting for operator confirmation, and the
@@ -173,12 +209,19 @@ export interface InteractiveDeps {
 	registerAskUserHandler?: (handler: AskUserHandler) => () => void;
 	/** Live CLIO-CODER.md and memory state for the footer Context quadrant. */
 	getContextState?: (cwd?: string) => ContextState;
-	/** Persist a thinking level set by `/thinking <level>` or `/model <pattern>:<level>`. */
-	onSetThinkingLevel?: (level: ThinkingLevel) => void;
+	/**
+	 * Persist a thinking level set by `/thinking <level>` or `/model <pattern>:<level>`.
+	 * Scope "session" leaves settings.yaml alone; omitted means the historical
+	 * write-through, which is what the Shift+Tab cycle and `/thinking` still want.
+	 */
+	onSetThinkingLevel?: (level: ThinkingLevel, scope?: "session" | "global") => void;
 	/** Persist the next thinking level when Shift+Tab is pressed. */
 	onCycleThinking?: () => void;
-	/** Persist the orchestrator target selected in /model. */
-	onSelectModel?: (ref: { target: string; model: string }) => void;
+	/**
+	 * Apply the orchestrator target selected in /model at the scope the operator
+	 * chose. "session" routes this session only and never touches settings.yaml.
+	 */
+	onSelectModel?: (ref: { target: string; model: string }, scope: "session" | "global") => void;
 	/** Write handler the /settings overlay uses to persist cycled values. */
 	writeSettings?: (next: ClioSettings) => void;
 	/**
@@ -567,6 +610,31 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 		chatRenderer,
 		io,
 	} = presentation;
+	// The factory arrives only from an active `--with-panes` boot (or a test); a
+	// plain session has no deps.panes and no factory, and loads no yazi code.
+	const yaziBridge =
+		deps.panes && deps.createYaziBridge
+			? deps.createYaziBridge({
+					...(deps.mux ? { mux: deps.mux } : {}),
+					getDraft: () => editor.getText(),
+					setDraft: (text) => editor.setText(text),
+					requestRender: () => tui.requestRender(),
+					notice: (level, text) => notify(level, text, `yazi:${level}`),
+					getCwd: () => process.cwd(),
+					getSettings: () =>
+						deps.getSettings?.().panes.yazi ?? {
+							mode: "companion",
+							profile: "managed",
+							followCwd: true,
+						},
+					stopUi: () => tui.stop(),
+					startUi: () => {
+						tui.start();
+						tui.requestRender(true);
+					},
+				})
+			: null;
+	const detachYaziBridge = yaziBridge ? deps.attachYaziBridge?.(yaziBridge) : undefined;
 	refreshPresentationFooter = () => footer.refresh();
 	const agentProgress = createAgentProgress(terminal);
 	// Desktop notifications are a protocol write on the terminal owner, issued
@@ -681,7 +749,9 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 		openMemory: () => openMemoryOverlayState(),
 		...(deps.seedTaskMemory ? { seedTaskMemory: deps.seedTaskMemory } : {}),
 		openView: (filter) => openViewOverlayState(filter),
+		...(deps.panes ? { panes: deps.panes } : {}),
 		openModel: () => openModelOverlayState(),
+		openModelScope: (ref) => openModelScopeState(ref),
 		openSettings: (section, rowId) => openSettingsOverlayState(section, rowId),
 		openResume: () => openResumeOverlayState(),
 		startNewSession: () => startNewSession(),
@@ -789,6 +859,7 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 		openMemoryOverlayState,
 		openViewOverlayState,
 		openModelOverlayState,
+		openModelScopeState,
 		openSettingsOverlayState,
 		openResumeOverlayState,
 		openTreeOverlayState,
@@ -866,6 +937,64 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 		};
 		notify(outcome.ok ? "success" : "info", outcome.message, "dispatch:background");
 	};
+	// Built only when a pane host answered detection, so a session with no
+	// panes subscribes to nothing and the bus handlers do not exist at all.
+	// The factories arrive from the `--with-panes` composition root (or a
+	// test); a plain session loads none of the bridge code.
+	const mux = deps.mux;
+	const muxBridge =
+		mux && mux.mode !== "none" && deps.createMuxBridge
+			? deps.createMuxBridge({
+					bus: deps.bus,
+					mux,
+					notificationsPolicy: () => deps.getSettings?.().panes.notifications ?? "failures",
+					log: (level, message) => {
+						if (level === "warning") notify("warning", message, "mux:bridge");
+					},
+					notice: (level, text) => appendNotice(level, text, busNoticeSink),
+				})
+			: null;
+	// The workers-view watch pane: opened on Enter over a live run, retargeted
+	// by arrow keys through its selection file. `/panes show` and the panes
+	// tool drive the same controller through the shared operations object.
+	const watchPane =
+		mux && mux.mode !== "none" && deps.createWatchPane
+			? deps.createWatchPane({ mux, getCwd: () => process.cwd() })
+			: null;
+	const detachWatchPane = watchPane ? deps.attachWatchPane?.(watchPane) : undefined;
+	const selectedWatchableRun = (): { runId: string; agentId: string } | null => {
+		if (!watchPane) return null;
+		const row = dispatchBoard.selectedRow();
+		if (!row) return null;
+		const decision = paneWatchDecision({ source: "workers-view", runStatus: row.status });
+		return decision.open ? { runId: row.runId, agentId: row.agentId } : null;
+	};
+	/**
+	 * Enter in the workers view. True means the watch pane took the key; false
+	 * (panes off, nothing watchable under the policy) falls back to the inline
+	 * worker-progress detail, so a terminal run's Enter still expands its card.
+	 */
+	const watchSelectedDispatch = (): boolean => {
+		const selected = selectedWatchableRun();
+		if (!watchPane || !selected) return false;
+		void watchPane.watch(selected.runId).then((result) => {
+			if (result.status === "watching") {
+				if (result.opened) {
+					notify("success", `watching ${selected.agentId} (${selected.runId}) in a pane`, "panes:watch");
+				}
+			} else {
+				notify("warning", result.reason, "panes:watch");
+			}
+			tui.requestRender();
+		});
+		return true;
+	};
+	/** Arrow keys: the watch pane follows the cursor, but only once it exists. */
+	const followBoardSelection = (): void => {
+		if (!watchPane?.isOpen()) return;
+		const selected = selectedWatchableRun();
+		if (selected) watchPane.follow(selected.runId);
+	};
 	const interactiveSubscriptions = createInteractiveSubscriptions({
 		bus: deps.bus,
 		refreshFooter: () => footer.refresh(),
@@ -916,7 +1045,18 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 		onShutdownArmedChange: (armed) => {
 			shutdownArmed = armed;
 		},
-		dispatchBoard,
+		dispatchBoard: {
+			selectPrevious: () => {
+				dispatchBoard.selectPrevious();
+				followBoardSelection();
+			},
+			selectNext: () => {
+				dispatchBoard.selectNext();
+				followBoardSelection();
+			},
+			toggleDetail: () => dispatchBoard.toggleDetail(),
+		},
+		watchSelectedDispatch,
 		steerSelectedDispatch,
 		cancelSelectedDispatch,
 		cancelActiveEditorBash: () => editorSubmit.cancelActiveEditorBash(),
@@ -955,7 +1095,14 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 			disposeOverlay: overlayLifecycle.dispose,
 			stopAgentProgress: agentProgress.stop,
 			disposeChat: () => deps.chat.dispose(),
-			disposeSubscriptions: interactiveSubscriptions.dispose,
+			disposeSubscriptions: () => {
+				detachYaziBridge?.();
+				yaziBridge?.dispose();
+				detachWatchPane?.();
+				watchPane?.dispose();
+				muxBridge?.dispose();
+				interactiveSubscriptions.dispose();
+			},
 		},
 		beforeStopUi: (() => {
 			let settlement: Promise<void> | null = null;

package/src/interactive/interactive-input-runtime.ts

@@ -82,6 +82,8 @@ export interface InteractiveInputRuntimeDeps {
 		selectNext(): void;
 		toggleDetail(): void;
 	};
+	/** Enter in the workers view; false falls through to the detail toggle. */
+	watchSelectedDispatch: () => boolean;
 	steerSelectedDispatch: () => void;
 	cancelSelectedDispatch: () => void;
 	cancelActiveEditorBash: () => boolean;
@@ -238,6 +240,11 @@ export function createInteractiveInputRuntime(deps: InteractiveInputRuntimeDeps)
 						deps.dispatchBoard.toggleDetail();
 						deps.requestRender();
 					},
+					watchSelectedDispatch: () => {
+						const handled = deps.watchSelectedDispatch();
+						if (handled) deps.requestRender();
+						return handled;
+					},
 					steerSelectedDispatch: deps.steerSelectedDispatch,
 					cancelSelectedDispatch: deps.cancelSelectedDispatch,
 					cancelAskUser: () => deps.overlay.cancelAskUser(),

package/src/interactive/interactive-slash-runtime.ts

@@ -9,6 +9,7 @@ import type { AgentsContract } from "../domains/agents/contract.js";
 import type { DispatchContract } from "../domains/dispatch/contract.js";
 import { agentRoleFactsResolver } from "../domains/dispatch/execution-role.js";
 import type { ExtensionsContract } from "../domains/extensions/index.js";
+import type { PanesOperations } from "../domains/mux/operations.js";
 import {
 	type ProvidersContract,
 	type ResolvedThinkingCapability,
@@ -36,6 +37,7 @@ import { runOperatorRecall } from "./context-recall-command.js";
 import { renderSessionHtml } from "./export-html/index.js";
 import { dateLocal } from "./format-time.js";
 import type { OracleDigestSources } from "./oracle.js";
+import type { PendingModelScope } from "./overlays/model-scope.js";
 import type { SettingsCenterRowId, SettingsSectionId } from "./overlays/settings.js";
 import {
 	type ContextClearCommandOptions,
@@ -48,7 +50,7 @@ import {
 	type SlashCommandDispatchResult,
 	type TaskMemorySeedCommandResult,
 } from "./slash-commands.js";
-import { verifyReceiptFile } from "./view/artifacts.js";
+import { verifyReceiptFileReport } from "./view/artifacts.js";
 import type { WorkerEntryState } from "./worker-stream.js";
 
 const EXPORT_RENDER_WIDTH = 100;
@@ -89,8 +91,8 @@ export interface InteractiveSlashRuntimeDeps {
 	 * making a value permanent stays the Settings overlay's explicit choice.
 	 */
 	commitSetting?: (id: string, next: ClioSettings, scope: "session" | "global") => void;
-	onSelectModel?: (ref: { target: string; model: string }) => void;
-	onSetThinkingLevel?: (level: ThinkingLevel) => void;
+	onSelectModel?: (ref: { target: string; model: string }, scope: "session" | "global") => void;
+	onSetThinkingLevel?: (level: ThinkingLevel, scope?: "session" | "global") => void;
 	onCompact?: (instructions: string | undefined) => Promise<void>;
 	onInit?: (options: InitCommandOptions, io?: RunIo) => Promise<void>;
 	onContextClear?: (options: ContextClearCommandOptions) => Promise<void>;
@@ -135,7 +137,14 @@ export interface InteractiveSlashRuntimeDeps {
 	openMemory: () => void;
 	seedTaskMemory?: () => TaskMemorySeedCommandResult;
 	openView: (filter?: string) => void;
+	/** Pane-layer operations behind `/panes`. Absent when the mux resolved to `none`. */
+	panes?: PanesOperations;
 	openModel: () => void;
+	/**
+	 * Ask where a resolved `/model <pattern>` swap lands before anything applies.
+	 * Absent on a host with no overlay layer, where the swap stays session-scoped.
+	 */
+	openModelScope?: (ref: PendingModelScope) => void;
 	openSettings: (section?: SettingsSectionId, rowId?: SettingsCenterRowId) => void;
 	openResume: () => void;
 	startNewSession: () => void;
@@ -200,6 +209,7 @@ export function resolveAvailableThinkingLevels(
 export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps): InteractiveSlashRuntime {
 	let activeContextInit = false;
 	let latestAdmission: Promise<void> = Promise.resolve();
+	let latestLocalOperation: Promise<void> = Promise.resolve();
 	let activeAdmissionSignal: AbortSignal | undefined;
 	const cwd = (): string => deps.getCwd?.() ?? process.cwd();
 	const resources = deps.resources;
@@ -436,6 +446,7 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 			return result;
 		},
 		openView: deps.openView,
+		...(deps.panes ? { panes: deps.panes } : {}),
 		setThinkingLevel: (level) => {
 			const settings = deps.getSettings?.();
 			if (!settings || !deps.onSetThinkingLevel) return { status: "unavailable" };
@@ -485,9 +496,20 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 		openModel: deps.openModel,
 		providers: deps.providers,
 		applyModelRef: (ref) => {
-			deps.onSelectModel?.({ target: ref.target, model: ref.model });
-			if (ref.thinkingLevel) deps.onSetThinkingLevel?.(ref.thinkingLevel);
+			// A mid-conversation swap used to rewrite the orchestrator role in
+			// settings.yaml with no prompt, so the next launch could come up on a
+			// dead endpoint (smoke pass 2, G3). The scope dialog owns the commit
+			// now, and it applies nothing until the operator answers.
+			if (deps.openModelScope) {
+				deps.openModelScope(ref);
+				return "pending";
+			}
+			// No overlay layer to ask with: session scope is the answer that cannot
+			// outlive the session that chose it.
+			deps.onSelectModel?.({ target: ref.target, model: ref.model }, "session");
+			if (ref.thinkingLevel) deps.onSetThinkingLevel?.(ref.thinkingLevel, "session");
 			deps.requestRender();
+			return "applied";
 		},
 		openSettings: deps.openSettings,
 		openResume: deps.openResume,
@@ -634,7 +656,7 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 				})
 				.finally(deps.requestRender);
 		},
-		verifyReceipt: (runId) => verifyReceiptFile(deps.stateDir, runId),
+		verifyReceipt: (runId) => verifyReceiptFileReport(deps.stateDir, runId),
 		...(deps.listWorkerRuns ? { listWorkerRuns: deps.listWorkerRuns } : {}),
 		// The user-turn path, minus expansion. A worker's answer is literal text:
 		// running it through the prompt, skill, and @file expanders would let a
@@ -644,6 +666,9 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 			latestAdmission = admitChat(text, activeAdmissionSignal);
 			void latestAdmission;
 		},
+		runLocalOperation: (operation) => {
+			latestLocalOperation = latestLocalOperation.catch(() => undefined).then(operation);
+		},
 		render: deps.requestRender,
 	};
 
@@ -653,8 +678,12 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 		dispatchCommand: (text) => dispatchSlashCommand(parseSlashCommand(text), context),
 		admitCommand: async (text, signal) => {
 			signal?.throwIfAborted();
+			// Pane opens and focus changes mutate a remote registry. A following
+			// slash read must observe their settled state, just as the tool path does.
+			await latestLocalOperation;
 			const command = parseSlashCommand(text);
 			const before = latestAdmission;
+			const localBefore = latestLocalOperation;
 			const previousSignal = activeAdmissionSignal;
 			activeAdmissionSignal = signal;
 			try {
@@ -663,6 +692,7 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 				activeAdmissionSignal = previousSignal;
 			}
 			if (latestAdmission !== before) await latestAdmission;
+			if (latestLocalOperation !== localBefore) await latestLocalOperation;
 		},
 	};
 }

package/src/interactive/memory-overlay.ts

@@ -358,6 +358,7 @@ export function openMemoryOverlay(
 	const handle = showClioOverlayFrame(tui, view, {
 		anchor: "center",
 		width: MEMORY_OVERLAY_WIDTH,
+		markerId: "memory",
 		title: () => "Memory",
 		footerHint: () => view.getHint(),
 	});

package/src/interactive/modal-marker.ts

@@ -0,0 +1,170 @@
+/**
+ * The outward signal that a modal overlay owns the keyboard.
+ *
+ * Every framed Clio overlay captures input for as long as it is up, and until
+ * now it announced that only by being on screen. An external driver feeding
+ * keys into the pane, and herdr deciding whether the pane is idle, working, or
+ * blocked, had to infer modality from whatever the overlay happened to draw:
+ * its box title, its hint row, a footer pill. Those are per-overlay strings
+ * that move on every reskin, and the tall modals cover the very rows a screen
+ * scraper reads, so the signal is weakest exactly when a modal is largest.
+ *
+ * The marker publishes the fact out of band instead, as an OSC 0 terminal
+ * title. Three properties make the title the reliable channel here:
+ *
+ *   1. It is not screen content. No overlay can composite over it, no
+ *      transcript line can counterfeit it, and no terminal height changes
+ *      whether it is readable.
+ *   2. herdr already consumes it. `region = "osc_title"` is a first-class
+ *      detection region (herdr `src/detect/manifest.rs`), fed from the pane's
+ *      own emulator, and its rules outrank every screen rule.
+ *   3. Clio has never written a title, so the channel carries exactly one
+ *      meaning and nothing else contends for it.
+ *
+ * The grammar is fixed and machine-first:
+ *
+ *   clio                                 no modal owns the keys
+ *   clio [modal:permission-confirm]      one modal, named
+ *   clio [modal:library-install+2]       top modal named, two more beneath it
+ *
+ * Nothing is written until the first modal opens, so a Clio that never opens
+ * an overlay leaves the pane's inherited title alone. From the first modal
+ * onward the title toggles between the marker and the bare base, which is what
+ * makes the absence of a marker a positive statement rather than an unknown.
+ */
+
+/** The write side of a terminal title. `ProcessTerminal` satisfies it structurally. */
+export interface ModalMarkerSink {
+	setTitle(title: string): void;
+}
+
+/** What the title reads when nothing modal owns the keyboard. */
+export const MODAL_MARKER_BASE_TITLE = "clio";
+
+/**
+ * The one regular expression an external reader needs. Exported so Clio's own
+ * contract test and herdr's manifest rule are written against the same shape
+ * rather than two hand-copied spellings of it.
+ */
+export const MODAL_MARKER_TITLE_PATTERN = /^clio \[modal:([a-z0-9][a-z0-9-]*)(?:\+([1-9]\d*))?\]$/u;
+
+/** Render the title for a modal stack, outermost first. */
+export function formatModalMarkerTitle(stack: readonly string[]): string {
+	const top = stack.at(-1);
+	if (top === undefined) return MODAL_MARKER_BASE_TITLE;
+	const beneath = stack.length - 1;
+	return `${MODAL_MARKER_BASE_TITLE} [modal:${top}${beneath > 0 ? `+${beneath}` : ""}]`;
+}
+
+/** Read a marker title back. Returns null for the base title and for anything else. */
+export function parseModalMarkerTitle(title: string): { id: string; depth: number } | null {
+	const match = MODAL_MARKER_TITLE_PATTERN.exec(title);
+	const id = match?.[1];
+	if (id === undefined) return null;
+	const beneath = match?.[2];
+	return { id, depth: beneath === undefined ? 1 : 1 + Number.parseInt(beneath, 10) };
+}
+
+/** One modal's claim on the keyboard, released when the overlay goes away. */
+export interface ModalMarkerHandle {
+	/** Drop this modal from the stack. Idempotent; a second call is inert. */
+	release(): void;
+	/**
+	 * Whether this modal currently owns keys. The engine's `setHidden` takes a
+	 * visible overlay out of the focus order without destroying it, which is how
+	 * a surface that shells out to a child process gets off the screen, so a
+	 * hidden modal must stop claiming the keyboard without leaving the stack.
+	 */
+	setActive(active: boolean): void;
+	/** Bring this modal back to the top of the stack, as `handle.focus()` does on screen. */
+	raise(): void;
+}
+
+interface ModalMarkerRegistry {
+	/**
+	 * Push a modal. The sink is taken from the caller rather than installed at
+	 * startup so the marker has no lifecycle of its own: it exists exactly when
+	 * an overlay exists, and a stub terminal with no `setTitle` makes the whole
+	 * mechanism inert instead of throwing.
+	 */
+	enter(id: string, sink?: ModalMarkerSink | null): ModalMarkerHandle;
+	/** The ids that currently own keys, outermost first. */
+	stack(): readonly string[];
+}
+
+interface ModalMarkerEntry {
+	readonly id: string;
+	active: boolean;
+}
+
+function createModalMarkerRegistry(): ModalMarkerRegistry {
+	const entries: ModalMarkerEntry[] = [];
+	let sink: ModalMarkerSink | null = null;
+	let published: string | null = null;
+
+	function activeIds(): string[] {
+		return entries.filter((entry) => entry.active).map((entry) => entry.id);
+	}
+
+	function publish(): void {
+		if (sink === null) return;
+		const title = formatModalMarkerTitle(activeIds());
+		// Before the first marker there is no stale claim to clear, so the pane
+		// keeps whatever title the shell or the multiplexer gave it.
+		if (published === null && title === MODAL_MARKER_BASE_TITLE) return;
+		if (title === published) return;
+		published = title;
+		sink.setTitle(title);
+	}
+
+	function enter(id: string, nextSink?: ModalMarkerSink | null): ModalMarkerHandle {
+		if (nextSink) sink = nextSink;
+		const entry: ModalMarkerEntry = { id, active: true };
+		entries.push(entry);
+		publish();
+		let released = false;
+		return {
+			release(): void {
+				if (released) return;
+				released = true;
+				const index = entries.indexOf(entry);
+				if (index !== -1) entries.splice(index, 1);
+				publish();
+			},
+			setActive(active: boolean): void {
+				if (released || entry.active === active) return;
+				entry.active = active;
+				publish();
+			},
+			raise(): void {
+				if (released) return;
+				entry.active = true;
+				const index = entries.indexOf(entry);
+				if (index !== -1 && index !== entries.length - 1) {
+					entries.splice(index, 1);
+					entries.push(entry);
+				}
+				publish();
+			},
+		};
+	}
+
+	return { enter, stack: (): readonly string[] => activeIds() };
+}
+
+let registry = createModalMarkerRegistry();
+
+/** Push a modal onto the process-wide stack. See {@link ModalMarkerRegistry.enter}. */
+export function enterModal(id: string, sink?: ModalMarkerSink | null): ModalMarkerHandle {
+	return registry.enter(id, sink);
+}
+
+/** The ids that currently own keys, outermost first. */
+export function modalMarkerStack(): readonly string[] {
+	return registry.stack();
+}
+
+/** Drop every claim and forget the sink. Tests use it to isolate; nothing in the app does. */
+export function resetModalMarker(): void {
+	registry = createModalMarkerRegistry();
+}