@iowarp/clio-coder 0.3.9 → 0.4.0

package/src/interactive/mux-bridge.ts

@@ -0,0 +1,214 @@
+/**
+ * The dispatch-to-pane-host bridge.
+ *
+ * Two responsibilities, both projections of state the session already owns:
+ *
+ * - **Terminal-run notifications.** A finished dispatch raises a pane-host
+ *   toast per the `panes.notifications` policy, and a failure additionally
+ *   leaves a persistent transcript notice, which unlike a toast remains
+ *   auditable in the TUI and does not depend on the pane host being alive.
+ *
+ * - **Self-report (SA-3).** Clio's own hosting pane, in guest mode, carries
+ *   the interactive status machine's phase as a semantic agent state, on a
+ *   trailing-edge throttle: herdr answers one request per connection, and an
+ *   operator turn passes through several phases inside one window, of which
+ *   only the last is worth a wire call.
+ *
+ * What this bridge deliberately no longer does is open panes. The phase 3/4
+ * integration projected every dispatch onto a viewer pane in a hidden Fleet
+ * tab (an `agents` policy knob, a keep-failed close policy, resume adoption,
+ * role-vocabulary sidebar labels). All of it duplicated the native fleet
+ * surfaces into panes the operator had not asked for; the one pane that
+ * renders runs is now the operator-pulled watch pane (`watch-pane.ts`), and
+ * the policy line lives in `pane-policy.ts`.
+ */
+
+import { type AgentStatusChangedPayload, BusChannels, type DispatchRunIdentity } from "../core/bus-events.js";
+import type { SafeEventBus } from "../core/event-bus.js";
+import type { MuxContract, MuxLog } from "../domains/mux/index.js";
+import { sanitizeCallTargetText } from "../domains/safety/call-target.js";
+
+/** Trailing-edge window for the self-report; matches `WAIT_POLL_MS`. */
+export const MUX_BRIDGE_THROTTLE_MS = 250;
+
+/**
+ * A success worth a sound. Below it a finished run is one of many and a chime
+ * per run is noise; above it the operator has moved on and wants telling.
+ */
+const LONG_RUN_MS = 60_000;
+
+/** How much terminal detail may reach a toast body or a notice line. */
+const DETAIL_MAX_CHARS = 96;
+
+export type PanesNotificationsPolicy = "failures" | "all" | "off";
+
+/** Terminal outcomes that read as failure for the notification policy. */
+type BridgeRunOutcome = "succeeded" | "failed" | "canceled" | "timed_out";
+
+export interface MuxBridgeDeps {
+	bus: SafeEventBus;
+	mux: MuxContract;
+	/** Read live so a `/settings` change takes effect on the next terminal run. */
+	notificationsPolicy: () => PanesNotificationsPolicy;
+	/** Persistent transcript notice; unlike a herdr toast, this remains auditable in the TUI. */
+	notice?: (level: "error", text: string) => void;
+	log?: MuxLog;
+	now?: () => number;
+	throttleMs?: number;
+	setTimeoutFn?: typeof setTimeout;
+	clearTimeoutFn?: typeof clearTimeout;
+}
+
+export interface MuxBridge {
+	/** Settle every in-flight notification and self-report. Tests await it. */
+	flush(): Promise<void>;
+	dispose(): void;
+}
+
+function isFailure(outcome: BridgeRunOutcome): boolean {
+	return outcome === "failed" || outcome === "timed_out";
+}
+
+/** Clio's own pane state (SA-3), mapped from the interactive status machine. */
+function selfStateFor(phase: AgentStatusChangedPayload["phase"]): "working" | "blocked" | "idle" {
+	if (phase === "tool_blocked") return "blocked";
+	// `ended` is the settle step on the way back to idle, so both read idle.
+	return phase === "idle" || phase === "ended" ? "idle" : "working";
+}
+
+/**
+ * Clio's seven-member run outcome taxonomy narrowed to the four states the
+ * notification policy distinguishes. `stalled`, `denied_by_policy`,
+ * `spawn_failed`, and the synthetic `retry_denied` all read as failure, which
+ * is the safe direction: an unrecognized terminal state must not silently
+ * skip the failure notice.
+ */
+function terminalOutcome(outcome: string): BridgeRunOutcome {
+	if (outcome === "succeeded") return "succeeded";
+	if (outcome === "canceled") return "canceled";
+	if (outcome === "timed_out") return "timed_out";
+	return "failed";
+}
+
+export function createMuxBridge(deps: MuxBridgeDeps): MuxBridge {
+	const log = deps.log ?? ((): void => undefined);
+	const now = deps.now ?? Date.now;
+	const throttleMs = deps.throttleMs ?? MUX_BRIDGE_THROTTLE_MS;
+	const setTimeoutFn = deps.setTimeoutFn ?? setTimeout;
+	const clearTimeoutFn = deps.clearTimeoutFn ?? clearTimeout;
+
+	/** Start stamps, so a terminal event without a duration still gets one. */
+	const startedAt = new Map<string, number>();
+	let disposed = false;
+	let timer: ReturnType<typeof setTimeout> | null = null;
+	/** Serializes wire work: notifies and self-reports must not interleave. */
+	let draining: Promise<void> = Promise.resolve();
+	/** Pending self-report state, or null when nothing changed since the last flush. */
+	let pendingSelf: "working" | "blocked" | "idle" | null = null;
+	/** The last state actually reported, so a repeated phase costs no wire call. */
+	let reportedSelf: "working" | "blocked" | "idle" | null = null;
+
+	const schedule = (): void => {
+		if (disposed || timer !== null) return;
+		timer = setTimeoutFn(() => {
+			timer = null;
+			void drainSelf();
+		}, throttleMs);
+		timer.unref?.();
+	};
+
+	const drainSelf = (): Promise<void> => {
+		draining = draining.then(async () => {
+			if (disposed) return;
+			const self = pendingSelf;
+			pendingSelf = null;
+			if (self !== null && self !== reportedSelf) {
+				reportedSelf = self;
+				await deps.mux.reportSelf({ state: self }).catch(() => false);
+			}
+		});
+		return draining;
+	};
+
+	const boundedDetail = (value: string | null | undefined): string | null => {
+		if (typeof value !== "string" || value.length === 0) return null;
+		return sanitizeCallTargetText(value).slice(0, DETAIL_MAX_CHARS);
+	};
+
+	const onTerminal = (
+		identity: DispatchRunIdentity,
+		rawOutcome: string,
+		fields: { durationMs?: number | undefined; detail?: string | null | undefined },
+	): void => {
+		const outcome = terminalOutcome(rawOutcome);
+		const begun = startedAt.get(identity.runId);
+		startedAt.delete(identity.runId);
+		const policy = deps.notificationsPolicy();
+		const failed = isFailure(outcome);
+		const qualifies = policy === "all" || (policy === "failures" && failed);
+		if (!qualifies) return;
+		const detail = boundedDetail(fields.detail);
+		const durationMs =
+			typeof fields.durationMs === "number" ? fields.durationMs : begun === undefined ? null : now() - begun;
+		if (failed) {
+			deps.notice?.("error", `${identity.agentId} ${outcome} (${identity.runId})${detail ? `: ${detail}` : ""}`);
+		}
+		if (!deps.mux.available()) return;
+		draining = draining.then(async () => {
+			if (disposed) return;
+			try {
+				await deps.mux.notify({
+					title: `${identity.agentId} ${outcome}`,
+					...(detail ? { body: detail } : {}),
+					// A failure interrupts; a long success announces. A short success
+					// in `all` mode gets the toast without the chime.
+					sound: failed ? "request" : durationMs !== null && durationMs >= LONG_RUN_MS ? "done" : "none",
+				});
+			} catch (error) {
+				// The contract swallows its own failures; anything arriving here is a
+				// bug rather than a dead socket, and must still not kill the chain.
+				log("debug", `mux bridge notify failed: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		});
+	};
+
+	const unsubscribers = [
+		deps.bus.on(BusChannels.DispatchStarted, (payload) => {
+			startedAt.set(payload.runId, now());
+		}),
+		deps.bus.on(BusChannels.DispatchCompleted, (payload) => {
+			onTerminal(payload, payload.outcome, { durationMs: payload.durationMs, detail: payload.outcomeDetail });
+		}),
+		deps.bus.on(BusChannels.DispatchFailed, (payload) => {
+			onTerminal(payload, payload.reason, { durationMs: payload.durationMs, detail: payload.outcomeDetail });
+		}),
+		// SA-3. The interactive status machine is the one surface that already
+		// knows when a turn starts, when it ends, and when a tool call is parked
+		// on an approval, so the self-report rides its transitions rather than
+		// growing a second turn-lifecycle listener.
+		deps.bus.on(BusChannels.AgentStatusChanged, (payload) => {
+			const state = selfStateFor(payload.phase);
+			if (state === reportedSelf && pendingSelf === null) return;
+			pendingSelf = state;
+			schedule();
+		}),
+	];
+
+	return {
+		flush(): Promise<void> {
+			if (timer !== null) {
+				clearTimeoutFn(timer);
+				timer = null;
+			}
+			return drainSelf();
+		},
+		dispose(): void {
+			if (disposed) return;
+			disposed = true;
+			if (timer !== null) clearTimeoutFn(timer);
+			timer = null;
+			for (const unsubscribe of unsubscribers) unsubscribe();
+			startedAt.clear();
+		},
+	};
+}

package/src/interactive/overlay-frame.ts

@@ -4,12 +4,14 @@ import {
 	type Component,
 	type OverlayHandle,
 	type OverlayOptions,
+	type OverlayUnfocusOptions,
 	type SelectListTheme,
 	type SettingsListTheme,
 	type TUI,
 	truncateToWidth,
 	visibleWidth,
 } from "../engine/tui.js";
+import { enterModal, type ModalMarkerSink } from "./modal-marker.js";
 import { type ClioToken, clioTheme, padAnsi, screenTitle, selectListTheme, settingsListTheme } from "./theme/index.js";
 
 export const IDENTITY = (text: string): string => text;
@@ -464,6 +466,15 @@ export class ClioOverlayFrame implements Component {
  * screen at 40x12. It learns the terminal height through the `visible`
  * predicate, which the engine evaluates with the live dimensions in the same
  * pass that renders the overlay.
+ *
+ * This is also where the modal marker is claimed and released. Every framed
+ * overlay is modal and every modal is framed: the only two overlays Clio shows
+ * without a frame are the context and task islands, and both pass
+ * `nonCapturing: true` straight to the engine. Hanging the marker here rather
+ * than on the overlay lifecycle therefore covers the nested frames the
+ * lifecycle's single `OverlayState` cannot see, and it cannot drift out of
+ * sync with what actually owns the keyboard, because the same call that takes
+ * the screen takes the marker.
  */
 export function showClioOverlayFrame(
 	tui: TUI,
@@ -473,12 +484,21 @@ export function showClioOverlayFrame(
 		footerHint?: string | ((innerWidth: number) => string | undefined);
 		/** Border and title token; omitted leaves the informational frame. */
 		tone?: OverlayTone;
+		/**
+		 * Stable id for the modal marker, published on the terminal title while
+		 * this overlay owns the keys. Required, and deliberately not defaulted
+		 * from `title`: several titles carry a session id, a decision
+		 * classification, or the active tab, and an id that moves with the
+		 * content is not an identifier. Use `modalMarkerId(...)` where the title
+		 * really is fixed and surface-specific.
+		 */
+		markerId: string;
 	},
 ): OverlayHandle {
-	const { title, footerHint, tone, width, visible, maxHeight, margin, ...overlayOptions } = options;
+	const { title, footerHint, tone, width, visible, maxHeight, margin, markerId, ...overlayOptions } = options;
 	const boxWidth = typeof width === "number" ? width : 0;
 	const frame = new ClioOverlayFrame(child, title, footerHint, boxWidth, frameAlignForAnchor(options.anchor), tone);
-	return tui.showOverlay(frame, {
+	const handle = tui.showOverlay(frame, {
 		...overlayOptions,
 		...(margin !== undefined ? { margin } : {}),
 		width: "100%",
@@ -493,6 +513,42 @@ export function showClioOverlayFrame(
 			return shown;
 		},
 	});
+	const marker = enterModal(markerId, modalMarkerSink(tui));
+	return {
+		hide(): void {
+			marker.release();
+			handle.hide();
+		},
+		setHidden(hidden: boolean): void {
+			marker.setActive(!hidden);
+			handle.setHidden(hidden);
+		},
+		isHidden: (): boolean => handle.isHidden(),
+		focus(): void {
+			marker.raise();
+			handle.focus();
+		},
+		// A pure passthrough on purpose. The engine hands focus to the next
+		// visible capturing overlay, which is another modal, so the stack is
+		// unchanged; the surface that gives the keyboard back to the composer
+		// does it by hiding, which `setHidden` already reports.
+		unfocus: (unfocusOptions?: OverlayUnfocusOptions): void =>
+			unfocusOptions ? handle.unfocus(unfocusOptions) : handle.unfocus(),
+		isFocused: (): boolean => handle.isFocused(),
+	};
+}
+
+/**
+ * The title sink behind a TUI, or null when there is none.
+ *
+ * The engine's `Terminal` declares `setTitle`, but the stub TUIs the overlay
+ * tests mount against are structural casts that carry only what the overlay
+ * under test reads. Probing for the method keeps the marker inert on those
+ * rather than throwing inside a render path.
+ */
+function modalMarkerSink(tui: TUI): ModalMarkerSink | null {
+	const terminal: Partial<ModalMarkerSink> | undefined = tui.terminal;
+	return typeof terminal?.setTitle === "function" ? (terminal as ModalMarkerSink) : null;
 }
 
 /** Rows from an overlay size value, matching how the engine reads one. */

package/src/interactive/overlay-general-openers.ts

@@ -334,6 +334,7 @@ export function createOverlayGeneralOpeners(deps: OverlayGeneralOpenersDeps): Ov
 		deps.transitions.state = "dispatch-board";
 		deps.dispatchBoard.resetSelection();
 		deps.transitions.handle = showOverlayFrameFactory(deps.tui, deps.dispatchBoard, {
+			markerId: "dispatch-board",
 			title: "Fleet Runs",
 			footerHint: dispatchBoardHint,
 			anchor: "center",

package/src/interactive/overlay-key-routing.ts

@@ -15,6 +15,7 @@ export type OverlayState =
 	| "memory"
 	| "view"
 	| "model"
+	| "model-scope"
 	| "settings"
 	| "resume"
 	| "tree"
@@ -63,6 +64,12 @@ export interface DispatchBoardOverlayKeyDeps {
 	cancelSelectedDispatch: () => void;
 	/** Open or close the selected run's worker-progress detail. */
 	toggleSelectedDispatchDetail: () => void;
+	/**
+	 * Open or retarget the watch pane for the selected run. True when the pane
+	 * layer took the key; false hands Enter back to the inline detail toggle,
+	 * which is the whole behavior when panes are off or the run is terminal.
+	 */
+	watchSelectedDispatch: () => boolean;
 }
 
 interface CloseOverlayKeyDeps {
@@ -173,10 +180,11 @@ export function routeDispatchBoardOverlayKey(data: string, deps: DispatchBoardOv
 		deps.cancelSelectedDispatch();
 		return true;
 	}
-	// Worker progress is expanded detail the operator asks for. The default list
-	// stays compact so a fan-out of scouts costs one card each.
+	// Enter on a live run enters it: the watch pane opens (or retargets) and
+	// renders the run's stream beside the board. Where panes are off, absent,
+	// or the run is terminal, Enter keeps its inline worker-progress detail.
 	if (matchesKey(data, "enter")) {
-		deps.toggleSelectedDispatchDetail();
+		if (!deps.watchSelectedDispatch()) deps.toggleSelectedDispatchDetail();
 		return true;
 	}
 	return false;
@@ -280,6 +288,9 @@ export function routeOverlayKey(
 	if (overlayState === "memory") return false;
 	if (overlayState === "view") return false;
 	if (overlayState === "model") return routeModelOverlayKey(data, deps);
+	// The scope dialog owns Esc itself: cancelling it must leave the model where
+	// it was, and a router-level close cannot say that to the caller waiting on it.
+	if (overlayState === "model-scope") return false;
 	// Settings owns Esc itself: its stack is sections → rows → detail, and a
 	// router-level close made every Esc leave the overlay from wherever the
 	// operator was, so a cancelled picker and a finished visit looked the same.

package/src/interactive/overlay-lifecycle.ts

@@ -22,6 +22,7 @@ import {
 export * from "./overlay-key-routing.js";
 
 import type { OverlayState } from "./overlay-key-routing.js";
+import type { PendingModelScope } from "./overlays/model-scope.js";
 import type { SettingsCenterRowId, SettingsSectionId } from "./overlays/settings.js";
 
 // Runtime lifecycle construction lives beside the pure modal key router so the
@@ -48,6 +49,7 @@ export type OverlayLifecycleApplicationDeps = Pick<
 	| "onNewSession"
 	| "onResumeSession"
 	| "onSelectModel"
+	| "onSetThinkingLevel"
 	| "providers"
 	| "readSessionEntries"
 	| "registerAskUserHandler"
@@ -108,6 +110,7 @@ export interface OverlayLifecycleRuntimeDeps {
 	openAuthDialog?: typeof import("./overlays/auth-dialog.js").openAuthDialog;
 	openAskUserOverlay?: typeof import("./overlays/ask-user.js").openAskUserOverlay;
 	openModelOverlay?: typeof import("./overlays/model-selector.js").openModelOverlay;
+	openModelScopeOverlay?: typeof import("./overlays/model-scope.js").openModelScopeOverlay;
 	openSettingsOverlay?: typeof import("./overlays/settings.js").openSettingsOverlay;
 	openSessionOverlay?: typeof import("./overlays/session-selector.js").openSessionOverlay;
 	openTreeOverlay?: typeof import("./overlays/tree-selector.js").openTreeOverlay;
@@ -151,6 +154,8 @@ export interface OverlayLifecycleController {
 	startHandoffState(goal: string): void;
 	startFleetRunState(name: string, vars: Readonly<Record<string, string>>): void;
 	openModelOverlayState(): void;
+	/** `/model <pattern>` and the picker both land here: choose session or global before anything applies. */
+	openModelScopeState(ref: PendingModelScope): void;
 	openSettingsOverlayState(section?: SettingsSectionId, rowId?: SettingsCenterRowId): void;
 	openResumeOverlayState(): void;
 	openTreeOverlayState(): void;
@@ -196,6 +201,7 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		openAuthDialog: openAuthDialogFactory,
 		openAskUserOverlay: openAskUserOverlayFactory,
 		openModelOverlay: openModelOverlayFactory,
+		openModelScopeOverlay: openModelScopeOverlayFactory,
 		openSettingsOverlay: openSettingsOverlayFactory,
 		openSessionOverlay: openSessionOverlayFactory,
 		openTreeOverlay: openTreeOverlayFactory,
@@ -269,13 +275,15 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		getAutonomy: () => deps.app.getSettings?.().autonomy ?? "auto-edit",
 		getOverlayState: () => overlayTransitions.state,
 		openPermissionOverlay: (view, inspect) => {
-			if (overlayTransitions.state !== "closed") return false;
-			overlayTransitions.state = "permission-confirm";
+			if (overlayTransitions.state === "permission-confirm") return false;
 			const body = createPermissionOverlayBody(view, inspect);
 			permissionBody = body;
-			overlayTransitions.handle = showOverlayFrame(tui, body, {
+			const handle = showOverlayFrame(tui, body, {
 				...permissionOverlayPlacement(tui, editor, footer.view),
 				width: PERMISSION_OVERLAY_WIDTH,
+				// Not derived from the title: that one is classified per decision
+				// axis and is one of five strings for the same modal.
+				markerId: "permission-confirm",
 				title: permissionOverlayTitle(view),
 				tone: permissionOverlayTone(view),
 				// Read per frame: the footer names what Enter does right now, and
@@ -283,6 +291,11 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 				// the mutation is open.
 				footerHint: (innerWidth) => permissionOverlayHint(innerWidth, editor.getText().length > 0, inspectionHint()),
 			});
+			if (!overlayTransitions.showPermission(handle)) {
+				handle.hide();
+				permissionBody = null;
+				return false;
+			}
 			tui.requestRender();
 			return true;
 		},
@@ -331,10 +344,12 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		...(deps.app.writeSettings ? { writeSettings: deps.app.writeSettings } : {}),
 		...(deps.app.commitSetting ? { commitSetting: deps.app.commitSetting } : {}),
 		...(deps.app.onSelectModel ? { onSelectModel: deps.app.onSelectModel } : {}),
+		...(deps.app.onSetThinkingLevel ? { onSetThinkingLevel: deps.app.onSetThinkingLevel } : {}),
 		...(deps.app.getFleetNodes ? { getFleetNodes: deps.app.getFleetNodes } : {}),
 		connectTarget: (targetId) => overlayAuth.openConnectFlow(targetId),
 		...(deps.app.interop ? { getInteropProposals: interopProposalsFor(deps.app.interop) } : {}),
 		...(openModelOverlayFactory ? { openModelOverlay: openModelOverlayFactory } : {}),
+		...(openModelScopeOverlayFactory ? { openModelScopeOverlay: openModelScopeOverlayFactory } : {}),
 		...(openSettingsOverlayFactory ? { openSettingsOverlay: openSettingsOverlayFactory } : {}),
 	});
 
@@ -466,6 +481,7 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		startFleetRunState,
 		startHandoffState,
 		openModelOverlayState: overlayModelSelectors.openModelOverlayState,
+		openModelScopeState: overlayModelSelectors.openModelScopeState,
 		openSettingsOverlayState: overlayModelSelectors.openSettingsOverlayState,
 		openResumeOverlayState,
 		openTreeOverlayState,

package/src/interactive/overlay-model-selectors.ts

@@ -1,4 +1,5 @@
 import type { ClioSettings } from "../core/config.js";
+import type { ThinkingLevel } from "../core/defaults.js";
 import type { SafeEventBus } from "../core/event-bus.js";
 import type { InteropProposal } from "../domains/interop/index.js";
 import type { ProvidersContract } from "../domains/providers/index.js";
@@ -7,6 +8,12 @@ import type { TUI } from "../engine/tui.js";
 import type { FooterDashboardPanel } from "./footer/dashboard.js";
 import type { InteractiveNoticeLevel } from "./interactive-subscriptions.js";
 import type { OverlayTransitions } from "./overlay-transitions.js";
+import {
+	formatPendingModelScope,
+	type ModelScopeChoice,
+	openModelScopeOverlay,
+	type PendingModelScope,
+} from "./overlays/model-scope.js";
 import { openModelOverlay } from "./overlays/model-selector.js";
 import { openSettingsOverlay, type SettingsCenterRowId, type SettingsSectionId } from "./overlays/settings.js";
 
@@ -21,7 +28,9 @@ export interface OverlayModelSelectorsDeps {
 	getSettings?: () => Readonly<ClioSettings>;
 	writeSettings?: (next: ClioSettings) => void;
 	commitSetting?: (id: string, next: ClioSettings, scope: "session" | "global") => void;
-	onSelectModel?: (ref: { target: string; model: string }) => void;
+	onSelectModel?: (ref: { target: string; model: string }, scope: ModelScopeChoice) => void;
+	/** Applied with the chosen scope when the swap named a thinking level. */
+	onSetThinkingLevel?: (level: ThinkingLevel, scope?: ModelScopeChoice) => void;
 	/** Settings → Fleet shows live node placement health when the scheduler exposes it. */
 	getFleetNodes?: () => ReadonlyArray<FleetNodeSnapshot>;
 	/** Settings → Targets "connect" runs the auth flow over the open settings overlay. */
@@ -29,17 +38,21 @@ export interface OverlayModelSelectorsDeps {
 	/** Settings → Advanced offers detected agents on the delegation.agents row. */
 	getInteropProposals?: () => ReadonlyArray<InteropProposal>;
 	openModelOverlay?: typeof openModelOverlay;
+	openModelScopeOverlay?: typeof openModelScopeOverlay;
 	openSettingsOverlay?: typeof openSettingsOverlay;
 }
 
 export interface OverlayModelSelectors {
 	openModelOverlayState(): void;
+	/** Ask where a resolved swap lands, then apply it. Nothing changes until the operator answers. */
+	openModelScopeState(ref: PendingModelScope): void;
 	openSettingsOverlayState(section?: SettingsSectionId, rowId?: SettingsCenterRowId): void;
 	refreshSettingsOverlay(): void;
 }
 
 export function createOverlayModelSelectors(deps: OverlayModelSelectorsDeps): OverlayModelSelectors {
 	const openModel = deps.openModelOverlay ?? openModelOverlay;
+	const openModelScope = deps.openModelScopeOverlay ?? openModelScopeOverlay;
 	const openSettings = deps.openSettingsOverlay ?? openSettingsOverlay;
 	let settingsOverlayRefresh: (() => void) | null = null;
 
@@ -53,9 +66,11 @@ export function createOverlayModelSelectors(deps: OverlayModelSelectorsDeps): Ov
 			...(deps.getSettings ? { getSettings: deps.getSettings } : {}),
 			providers: deps.providers,
 			bus: deps.bus,
+			// The picker resolves what to run; the scope dialog resolves where it
+			// lands. Closing this overlay first keeps one modal on screen at a time.
 			onSelect: (ref) => {
-				deps.onSelectModel?.(ref);
-				deps.refreshFooter();
+				deps.closeOverlay();
+				openModelScopeState(ref);
 			},
 			onToggleFavorite: (ref, favorite) => {
 				if (!deps.getSettings || !deps.writeSettings) return;
@@ -76,6 +91,27 @@ export function createOverlayModelSelectors(deps: OverlayModelSelectorsDeps): Ov
 		deps.tui.requestRender();
 	};
 
+	const openModelScopeState = (ref: PendingModelScope): void => {
+		if (deps.transitions.state !== "closed") return;
+		deps.transitions.state = "model-scope";
+		deps.transitions.handle = openModelScope(deps.tui, {
+			ref,
+			onChoose: (scope) => {
+				deps.closeOverlay();
+				deps.onSelectModel?.({ target: ref.target, model: ref.model }, scope);
+				if (ref.thinkingLevel) deps.onSetThinkingLevel?.(ref.thinkingLevel, scope);
+				const swap = formatPendingModelScope(ref);
+				deps.notify("success", scope === "global" ? `active and saved globally: ${swap}` : `active this session: ${swap}`);
+				deps.refreshFooter();
+			},
+			onCancel: () => {
+				deps.closeOverlay();
+				deps.notify("info", "model unchanged");
+			},
+		});
+		deps.tui.requestRender();
+	};
+
 	const openSettingsOverlayState = (section?: SettingsSectionId, rowId?: SettingsCenterRowId): void => {
 		if (deps.transitions.state !== "closed" || !deps.getSettings || !deps.writeSettings) return;
 		deps.transitions.state = "settings";
@@ -121,6 +157,7 @@ export function createOverlayModelSelectors(deps: OverlayModelSelectorsDeps): Ov
 
 	return {
 		openModelOverlayState,
+		openModelScopeState,
 		openSettingsOverlayState,
 		refreshSettingsOverlay: () => settingsOverlayRefresh?.(),
 	};