@iowarp/clio-coder 0.3.9 → 0.4.1

package/src/interactive/interactive-shell.ts

@@ -70,7 +70,7 @@ const KEEP_ALIVE_INTERVAL_MS = 1 << 30;
  * before the keep-alive anchor. Keeping that seam explicit prevents an
  * extraction from silently changing initialization order.
  */
-export function createInteractiveShell<TTerminal extends Terminal, TTui extends InteractiveShellTui>(
+function createInteractiveShell<TTerminal extends Terminal, TTui extends InteractiveShellTui>(
 	deps: InteractiveShellDeps<TTerminal, TTui>,
 ): InteractiveShell<TTerminal, TTui> {
 	const terminal = deps.createTerminal();
@@ -175,7 +175,7 @@ export function getActiveRenderTrace(): RenderTrace | null {
  * model state. After the finite pre-render bound, exactly one caller-supplied
  * final frame is still issued; a post-render drain wait is likewise bounded.
  */
-export async function settleLatestInteractiveFrame(
+async function settleLatestInteractiveFrame(
 	gate: Pick<StdoutBackpressureGate, "whenWritable"> | null,
 	timeoutMs: number,
 	renderFrame: () => Promise<number>,

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,7 +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 { SettingsCenterRowId, SettingsSectionId } from "./overlays/settings.js";
+import type { PendingModelScope } from "./overlays/model-scope.js";
 import {
 	type ContextClearCommandOptions,
 	type CouncilDispatchOutcome,
@@ -44,11 +45,12 @@ import {
 	type InitCommandOptions,
 	parseSlashCommand,
 	type RunIo,
+	type SettingsAreaId,
 	type SlashCommandContext,
 	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,8 +137,16 @@ 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;
-	openSettings: (section?: SettingsSectionId, rowId?: SettingsCenterRowId) => 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: (area?: SettingsAreaId, group?: string) => void;
+	openFleetRuns?: () => void;
 	openResume: () => void;
 	startNewSession: () => void;
 	openTree: () => void;
@@ -165,11 +175,7 @@ export interface InteractiveSlashRuntime {
 }
 
 /** Owns slash-command context construction and its asynchronous command state. */
-const OUTPUT_VERBOSITIES: ReadonlyArray<ClioSettings["terminal"]["outputVerbosity"]> = [
-	"minimal",
-	"default",
-	"verbose",
-];
+const OUTPUT_VERBOSITIES: ReadonlyArray<ClioSettings["interface"]["outputDetail"]> = ["minimal", "default", "verbose"];
 
 /** Thinking capability of the active orchestrator target and model, or null when unresolved. */
 export function resolveThinkingCapability(
@@ -178,9 +184,9 @@ export function resolveThinkingCapability(
 ): ResolvedThinkingCapability | null {
 	const resolved = resolveModelRuntimeCapabilitiesForProviders(
 		providers,
-		settings.orchestrator.target,
-		settings.orchestrator.model,
-		settings.orchestrator.thinkingLevel ?? "off",
+		settings.chat.target,
+		settings.chat.model,
+		settings.chat.thinkingLevel ?? "off",
 	);
 	return resolved?.thinking ?? null;
 }
@@ -200,6 +206,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;
@@ -360,7 +367,8 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 			deps.requestRender();
 		}
 	};
-	const context: SlashCommandContext = {
+	let context: SlashCommandContext;
+	context = {
 		io: deps.io,
 		notice: appendCommandNotice,
 		echoOperatorCommand: (text) => {
@@ -382,7 +390,7 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 		openSkillsHub: deps.openSkillsHub,
 		listExtensions: () => deps.extensions?.list(cwd(), { all: true }) ?? [],
 		listAgents: () => deps.agents?.listSpecs().filter((spec) => spec.audience !== "internal") ?? [],
-		listDelegationAgents: () => deps.getSettings?.().delegation.agents ?? [],
+		listDelegationAgents: () => deps.getSettings?.().integrations.externalAgents.entries ?? [],
 		exportShareArchive: (outPath) => {
 			if (!deps.share) throw new Error("share domain is not loaded");
 			const path = resolve(outPath);
@@ -413,7 +421,8 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 		oracleBriefing: oracleBriefingSources,
 		startHandoff: deps.startHandoff,
 		...(deps.startFleetRun ? { startFleetRun: deps.startFleetRun } : {}),
-		...(deps.getSettings ? { getWorkerRosters: () => deps.getSettings?.().workers.rosters ?? {} } : {}),
+		...(deps.openFleetRuns ? { openFleetRuns: deps.openFleetRuns } : {}),
+		...(deps.getSettings ? { getWorkerRosters: () => deps.getSettings?.().fleet.rosters ?? {} } : {}),
 		...(deps.runCouncilDispatch ? { runCouncilDispatch: deps.runCouncilDispatch } : {}),
 		openContextView: deps.openContextView,
 		openTasks: deps.openTasks,
@@ -436,6 +445,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" };
@@ -456,24 +466,53 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 			// has no mandate to do.
 			if (deps.commitSetting) {
 				const next = structuredClone(settings) as ClioSettings;
-				next.orchestrator.thinkingLevel = match;
-				deps.commitSetting("orchestrator.thinkingLevel", next, "session");
+				next.chat.thinkingLevel = match;
+				deps.commitSetting("chat.thinkingLevel", next, "session");
 			} else {
 				deps.onSetThinkingLevel(match);
 			}
 			deps.refreshFooter();
 			return { status: "applied", level: match, display: labelFor(match) };
 		},
+		thinkingLevelChoices: () => {
+			const settings = deps.getSettings?.();
+			if (!settings) return [];
+			const thinking = resolveThinkingCapability(deps.providers, settings);
+			return (thinking?.supportedLevels ?? (["off"] as ReadonlyArray<ThinkingLevel>)).map((value) => ({
+				value,
+				label: thinkingLevelChoiceLabel(thinking?.mechanism ?? null, value),
+			}));
+		},
+		openThinkingPicker: () => {
+			const choices = context.thinkingLevelChoices?.() ?? [];
+			if (choices.length === 0) {
+				appendCommandNotice("error", "thinking level cannot be set right now");
+				return;
+			}
+			void deps
+				.openAskUser([
+					{
+						question: "Choose the thinking level for this chat.",
+						header: "Thinking",
+						options: choices.map(({ label }) => ({ label })),
+					},
+				])
+				.then((result) => {
+					const answer = result.cancelled ? undefined : result.answers[0]?.answer;
+					const selected = choices.find(({ label }) => label === answer);
+					if (selected) dispatchSlashCommand({ kind: "thinking-set", level: selected.value }, context);
+				});
+		},
 		setOutputVerbosity: (verbosity) => {
 			if (!deps.getSettings || !(deps.commitSetting || deps.writeSettings)) return { status: "unavailable" };
 			const requested = verbosity.trim().toLowerCase();
 			const match = OUTPUT_VERBOSITIES.find((candidate) => candidate === requested);
 			if (!match) return { status: "unsupported", verbosity, supported: OUTPUT_VERBOSITIES };
 			const next = structuredClone(deps.getSettings()) as ClioSettings;
-			next.terminal.outputVerbosity = match;
+			next.interface.outputDetail = match;
 			// Session scope: /output changes this session and leaves settings.yaml
 			// alone. Saving it as the default is what Settings → Terminal is for.
-			if (deps.commitSetting) deps.commitSetting("terminal.outputVerbosity", next, "session");
+			if (deps.commitSetting) deps.commitSetting("interface.outputDetail", next, "session");
 			else deps.writeSettings?.(next);
 			// `/output` is also the explicit reset action for transcript folds. Do
 			// this even when the requested level already matches the current one;
@@ -482,12 +521,41 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 			deps.refreshFooter();
 			return { status: "applied", verbosity: match };
 		},
+		openOutputPicker: () => {
+			void deps
+				.openAskUser([
+					{
+						question: "Choose transcript detail for this session.",
+						header: "Output",
+						options: OUTPUT_VERBOSITIES.map((value) => ({
+							label: `${value[0]?.toUpperCase()}${value.slice(1)}`,
+						})),
+					},
+				])
+				.then((result) => {
+					if (result.cancelled) return;
+					const answer = result.answers[0]?.answer.toLowerCase();
+					const selected = OUTPUT_VERBOSITIES.find((value) => value === answer);
+					if (selected) dispatchSlashCommand({ kind: "output-set", verbosity: selected }, context);
+				});
+		},
 		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 +702,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 +712,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 +724,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 +738,7 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 				activeAdmissionSignal = previousSignal;
 			}
 			if (latestAdmission !== before) await latestAdmission;
+			if (latestLocalOperation !== localBefore) await latestLocalOperation;
 		},
 	};
 }

package/src/interactive/interactive-subscriptions.ts

@@ -88,7 +88,7 @@ export function createInteractiveSubscriptions(deps: InteractiveSubscriptionsDep
 			BusChannels.DispatchProgress,
 			folded((payload) => {
 				const workerEvent = payload.event as { type?: unknown } | null | undefined;
-				if (workerEvent?.type === "clio_steer_received") {
+				if (workerEvent?.type === "clio_coder_steer_received") {
 					deps.notify("success", `steer received by ${payload.agentId} (${payload.runId})`, `steer:${payload.runId}`);
 				}
 				return workers.progress(payload);

package/src/interactive/interactive-tickers.ts

@@ -34,7 +34,7 @@ export interface InteractiveTickersDeps {
 	clearScheduledInterval?: (handle: InteractiveTickerHandle) => void;
 }
 
-export function formatTaskBoardIslandLines(board: TaskBoardSnapshot): string[] {
+function formatTaskBoardIslandLines(board: TaskBoardSnapshot): string[] {
 	const theme = clioTheme();
 	const counts = taskBoardCounts(board);
 	const active = board.tasks.find((task) => task.status === "active");

package/src/interactive/keybinding-manager.ts

@@ -18,7 +18,7 @@
  * so editor/select components honor overrides out of the box.
  *
  * User overrides go through `validateKeybindings` first. Unmappable strings
- * (e.g. `clio.exit: "banana"`) are dropped so they cannot silently replace
+ * (e.g. `clio-coder.exit: "banana"`) are dropped so they cannot silently replace
  * the default binding; they still surface through `invalidBindings()` so
  * `/settings` and the boot stderr notice can point at the offending entry.
  */
@@ -184,7 +184,7 @@ interface ValidationResult {
 }
 
 /**
- * Normalize and validate the raw `settings.keybindings` block. Invalid
+ * Normalize and validate the raw `settings.interface.keybindings` block. Invalid
  * entries are dropped from the returned `valid` config so pi-tui keeps
  * the default binding in effect; callers render `invalid` as a diagnostic.
  */
@@ -472,14 +472,14 @@ function buildManager(
  * Build a `ClioKeybindingManager` from the provided settings snapshot. The
  * resulting manager is also installed as pi-tui's global so editor and
  * select components pick up the same overrides. Callers are expected to
- * recreate the manager if `settings.keybindings` is replaced wholesale;
+ * recreate the manager if `settings.interface.keybindings` is replaced wholesale;
  * partial live updates should instead go through `manager` state.
  */
 export function createKeybindingManager(
 	settings: Readonly<ClioSettings>,
 	env: NodeJS.ProcessEnv | Readonly<Record<string, string | undefined>> = process.env,
 ): ClioKeybindingManager {
-	const { valid, invalid } = validateKeybindings(settings.keybindings ?? {});
+	const { valid, invalid } = validateKeybindings(settings.interface.keybindings ?? {});
 	const inner = new KeybindingsManager(CLIO_KEYBINDINGS, valid);
 	setKeybindings(inner);
 	return buildManager(inner, invalid, detectPlatformKeybindingWarnings(valid, detectTerminalKeySupport(env)));

package/src/interactive/layout.ts

@@ -20,7 +20,7 @@ export interface FullscreenLayout {
 	transcript: ScrollView;
 }
 
-export function buildFullscreenLayout(
+function buildFullscreenLayout(
 	parts: LayoutParts,
 	options: Pick<LayoutOptions, "fullscreenScrollbar"> = {},
 ): FullscreenLayout {

package/src/interactive/memory-overlay.ts

@@ -29,7 +29,7 @@ const EMPTY_MESSAGE = "no approved lessons, task-bank entries, or memory steps c
  * row of its own until it finishes, and an operator who cannot see it in flight
  * reads an unchanged bank as an idle memory agent.
  */
-export function formatMemoryStatusLine(status: TaskMemoryOperatorStatus, contentWidth: number): string {
+function formatMemoryStatusLine(status: TaskMemoryOperatorStatus, contentWidth: number): string {
 	const theme = clioTheme();
 	const width = Math.max(1, Math.floor(contentWidth));
 	const units = [
@@ -145,7 +145,7 @@ function activityItems(events: ReadonlyArray<TaskMemoryActivityEvent>, group: st
  * section titles and they are the only place a reader learns that a class is
  * empty: a group with no rows renders no header at all.
  */
-export function buildMemoryOverlayItems(
+function buildMemoryOverlayItems(
 	status: TaskMemoryOperatorStatus,
 	records: ReadonlyArray<MemoryRecord>,
 ): ListOverlayItem[] {
@@ -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,151 @@
+/**
+ * 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. */
+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}` : ""}]`;
+}
+
+/** 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() };
+}
+
+const 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);
+}

package/src/interactive/mutation-preview.ts

@@ -96,7 +96,7 @@ function canonicalJson(value: unknown): string {
  * anything else about the arguments does, which is the point: a call that
  * differs from the previewed one cannot inherit its preview.
  */
-export function callArgumentsDigest(args: Record<string, unknown> | undefined): string {
+function callArgumentsDigest(args: Record<string, unknown> | undefined): string {
 	return createHash("sha256")
 		.update(canonicalJson(args ?? {}), "utf8")
 		.digest("hex")