@iowarp/clio-coder 0.3.1 → 0.3.3

package/src/interactive/interactive-presentation.ts

@@ -1,18 +1,24 @@
+import { performance } from "node:perf_hooks";
 import type { ClioSettings } from "../core/config.js";
 import type { SafeEventBus } from "../core/event-bus.js";
 import type { ContextState } from "../domains/context/index.js";
 import type { DispatchContract } from "../domains/dispatch/contract.js";
 import type { TaskMemoryOperatorStatus } from "../domains/memory/index.js";
-import type { ObservabilityContract, ObservabilitySnapshot } from "../domains/observability/index.js";
+import type {
+	ObservabilityContract,
+	ObservabilitySnapshot,
+	TokenThroughputSnapshot,
+} from "../domains/observability/index.js";
 import { type ProvidersContract, resolveModelRuntimeCapabilitiesForProviders } from "../domains/providers/index.js";
 import type { ResourcesContract } from "../domains/resources/index.js";
 import { getMarketplaceSkills } from "../domains/resources/skills/marketplace.js";
+import { ceilChars, contentChars } from "../domains/session/context-accounting.js";
 import type { SessionContract, TaskBoardSnapshot } from "../domains/session/index.js";
 import type { Component, TUI } from "../engine/tui.js";
-import type { ChatLoop } from "./chat-loop.js";
+import type { ChatLoop, ChatLoopEvent } from "./chat-loop.js";
 import { type ChatPanel, createChatPanel } from "./chat-panel.js";
 import { type CoalescingChatRenderer, createCoalescingChatRenderer } from "./chat-renderer.js";
-import { ClioEditor } from "./clio-editor.js";
+import { ClioEditor, type EditorChrome } from "./clio-editor.js";
 import { createCommandOutputRunIo } from "./command-output.js";
 import { createContextActivityStore } from "./context-activity.js";
 import { createDispatchBoardStore, createDispatchBoardView, type DispatchBoardView } from "./dispatch-board.js";
@@ -29,6 +35,8 @@ import type { SessionTranscript } from "./session-transcript.js";
 import { createSlashCommandAutocompleteProvider } from "./slash-autocomplete.js";
 import { parseSlashCommand, type RunIo } from "./slash-commands.js";
 import { createStatusController, type StatusController, type TurnSummary } from "./status/index.js";
+import type { SmoothStreamingMode } from "./stream-pacer.js";
+import { processAutoPacingAllowed, resolveSmoothStreamingMode } from "./stream-pacing-policy.js";
 import { formatTargetLabel } from "./theme/index.js";
 import { createWelcomeDashboard, type WelcomeDashboardComponent } from "./welcome-dashboard.js";
 import type { WorkspaceFacts } from "./workspace-facts.js";
@@ -69,7 +77,13 @@ export interface InteractivePresentationDeps {
 	sessionTranscript: Pick<SessionTranscript, "liveSessionTurns">;
 	tui: TUI;
 	terminal: { readonly columns: number };
-	mount: (root: Component, editor: Component) => void;
+	mount?: (root: Component, editor: Component) => void;
+	/** Stage 0's exact editor; when present no replacement editor is constructed. */
+	editor?: ClioEditor;
+	/** Stage 0's already-installed keybinding manager and pi-tui global. */
+	keybindings?: ClioKeybindingManager;
+	/** Pending boot submissions remain visible until serial admission removes them. */
+	bootPending?: Component;
 	getSettings?: () => Readonly<ClioSettings>;
 	resources?: Pick<ResourcesContract, "skills">;
 	session?: Pick<SessionContract, "current">;
@@ -80,9 +94,19 @@ export interface InteractivePresentationDeps {
 	getContextState?: (cwd?: string) => ContextState;
 	/** Whether the Ctrl+G leader is armed and waiting for its next key. */
 	getLeaderArmed?: () => boolean;
+	/** Whether a Ctrl+C armed the double tap and its window is still open. */
+	getShutdownArmed?: () => boolean;
 	getCwd?: () => string;
+	resolveVisibleEventSequence?: (event: ChatLoopEvent) => number | null;
+	resolveStreamIngress?: (
+		event: ChatLoopEvent,
+	) => { sequence: number; generation: string | number; ingressAt: number } | null;
+	commitFrame?: (reason?: string) => Promise<unknown>;
+	hasObservedBackpressure?: () => boolean;
+	onSmoothStreamingMode?: (mode: SmoothStreamingMode, pacingActive: boolean) => void;
 	scheduleInterval?: (callback: () => void, intervalMs: number) => PresentationTickerHandle;
 	clearScheduledInterval?: (handle: PresentationTickerHandle) => void;
+	now?: () => number;
 	factories?: Partial<InteractivePresentationFactories>;
 }
 
@@ -107,11 +131,14 @@ export interface InteractivePresentation {
 	announceTaskMemorySeedOffer(): void;
 	collapseWelcomeDashboard(): void;
 	editor: ClioEditor;
+	editorChrome: EditorChrome;
 	dispatchBoard: DispatchBoardView;
 	chatRenderer: CoalescingChatRenderer;
 	io: RunIo;
 	root: Component;
 	getObservabilitySnapshot(): ObservabilitySnapshot;
+	/** Fold one raw chat event into the ephemeral throughput shown only while this turn is active. */
+	recordChatEvent(event: ChatLoopEvent): void;
 	recordToolStart(toolCallId: string, toolName: string): void;
 	recordToolEnd(result: PresentationToolEnd): void;
 	setLastTurnSummary(summary: TurnSummary | null): void;
@@ -175,9 +202,10 @@ function willEnterSteerActiveWork(deps: InteractivePresentationDeps, text: strin
 export function createInteractivePresentation(deps: InteractivePresentationDeps): InteractivePresentation {
 	const factories = { ...DEFAULT_FACTORIES, ...deps.factories };
 	const getCwd = deps.getCwd ?? (() => process.cwd());
+	const now = deps.now ?? performance.now.bind(performance);
 	const requestRender = (): void => deps.tui.requestRender();
 	const settings = deps.getSettings?.() ?? ({ keybindings: {} } as ClioSettings);
-	const keybindings = factories.createKeybindings(settings);
+	const keybindings = deps.keybindings ?? factories.createKeybindings(settings);
 	const { getExtensionStats, getLiveWorkspaceSnapshot, getWorkspaceSnapshot, refreshLiveWorkspaceGit } =
 		deps.workspaceFacts;
 
@@ -223,6 +251,69 @@ export function createInteractivePresentation(deps: InteractivePresentationDeps)
 	let footerToolTruncatedResults = 0;
 	let lastTurnSummary: TurnSummary | null = null;
 	let observabilitySnapshot = deps.observability.snapshot();
+	let liveThroughput: {
+		startedAt: number;
+		firstDeltaAt: number | null;
+		settledOutputTokens: number;
+		partialOutputTokens: number;
+	} | null = null;
+	const recordChatEvent = (event: ChatLoopEvent): void => {
+		if (event.type === "agent_start") {
+			liveThroughput = {
+				startedAt: now(),
+				firstDeltaAt: null,
+				settledOutputTokens: 0,
+				partialOutputTokens: 0,
+			};
+			return;
+		}
+		if (event.type === "agent_end") {
+			liveThroughput = null;
+			return;
+		}
+		if (!liveThroughput) return;
+		if (event.type === "message_start" && event.message?.role === "assistant") {
+			liveThroughput.partialOutputTokens = 0;
+			return;
+		}
+		if (event.type === "message_update") {
+			const update = event.assistantMessageEvent as { type?: unknown; partial?: { content?: unknown; payload?: unknown } };
+			if (
+				update.type !== "text_delta" &&
+				update.type !== "thinking_delta" &&
+				update.type !== "toolcall_start" &&
+				update.type !== "toolcall_delta"
+			) {
+				return;
+			}
+			liveThroughput.firstDeltaAt ??= now();
+			liveThroughput.partialOutputTokens = ceilChars(contentChars(update.partial?.payload ?? update.partial?.content));
+			return;
+		}
+		if (event.type === "message_end" && event.message?.role === "assistant") {
+			const output = (event.message as { usage?: { output?: unknown } }).usage?.output;
+			const reported = typeof output === "number" && Number.isFinite(output) && output > 0 ? output : null;
+			liveThroughput.settledOutputTokens += reported ?? liveThroughput.partialOutputTokens;
+			liveThroughput.partialOutputTokens = 0;
+		}
+	};
+	const currentLiveThroughput = (): TokenThroughputSnapshot | null => {
+		if (!liveThroughput || liveThroughput.firstDeltaAt === null) return null;
+		const outputTokens = liveThroughput.settledOutputTokens + liveThroughput.partialOutputTokens;
+		if (outputTokens <= 0) return null;
+		const at = now();
+		const durationMs = Math.max(1, at - liveThroughput.firstDeltaAt);
+		const settings = deps.getSettings?.();
+		return {
+			tokensPerSecond: outputTokens / (durationMs / 1000),
+			outputTokens,
+			durationMs,
+			ttftMs: Math.max(0, liveThroughput.firstDeltaAt - liveThroughput.startedAt),
+			providerId: settings?.orchestrator?.target ?? "",
+			modelId: settings?.orchestrator?.model ?? "",
+			recordedAt: Date.now(),
+		};
+	};
 	let footer: FooterDashboardPanel;
 	const notifications = factories.createNotificationCenter({
 		onChange: () => {
@@ -256,7 +347,8 @@ export function createInteractivePresentation(deps: InteractivePresentationDeps)
 		getAgentStatus: () => statusController.current(),
 		getTerminalColumns: () => deps.terminal.columns,
 		getSessionTokens: () => observabilitySnapshot.session.tokens,
-		getTokenThroughput: () => observabilitySnapshot.session.latestThroughput,
+		getTokenThroughput: () =>
+			liveThroughput === null ? observabilitySnapshot.session.latestThroughput : currentLiveThroughput(),
 		getSessionCost: () => observabilitySnapshot.session.cost,
 		getContextUsage: () => deps.chat.contextUsage(),
 		getContextLedger: () => deps.chat.contextLedger(),
@@ -265,6 +357,7 @@ export function createInteractivePresentation(deps: InteractivePresentationDeps)
 		...(deps.getTaskMemoryStatus ? { getTaskMemoryStatus: deps.getTaskMemoryStatus } : {}),
 		getContextActivity: () => contextActivityStore.current(),
 		...(deps.getLeaderArmed ? { getLeaderArmed: deps.getLeaderArmed } : {}),
+		...(deps.getShutdownArmed ? { getShutdownArmed: deps.getShutdownArmed } : {}),
 		getToolCounts: () => ({
 			tools: Object.fromEntries(footerToolCounts),
 			errors: footerToolErrors,
@@ -295,7 +388,7 @@ export function createInteractivePresentation(deps: InteractivePresentationDeps)
 		requestRender();
 	});
 
-	const editor = factories.createEditor(deps.tui, {
+	const editorChrome: EditorChrome = {
 		getModelLabel: () => {
 			const current = deps.getSettings?.();
 			// The rail is the narrowest of the three, so it drops the spaces.
@@ -318,7 +411,8 @@ export function createInteractivePresentation(deps: InteractivePresentationDeps)
 		willEnterSteer: (text) => willEnterSteerActiveWork(deps, text),
 		getSubmitKeyLabel: () => formatKeyLabel(keybindings.getKeys("tui.input.submit")[0], "Enter"),
 		getNewlineKeyLabel: () => formatKeyLabel(keybindings.getKeys("tui.input.newLine")[0], "Shift+Enter"),
-	});
+	};
+	const editor = deps.editor ?? factories.createEditor(deps.tui, editorChrome);
 	editor.focused = true;
 	const autocomplete: AutocompleteProvider = factories.createAutocomplete({
 		listSkills: () => ({
@@ -335,20 +429,55 @@ export function createInteractivePresentation(deps: InteractivePresentationDeps)
 	const chatRenderer = factories.createChatRenderer({
 		chatPanel,
 		requestRender,
-		...(renderTrace ? { onDelta: () => renderTrace.recordDelta() } : {}),
+		...(deps.resolveStreamIngress && deps.getSettings
+			? {
+					streamIngress: deps.resolveStreamIngress,
+					getSmoothStreamingMode: () => {
+						const mode = resolveSmoothStreamingMode(deps.getSettings?.().terminal.smoothStreaming ?? "off");
+						const autoAllowed = processAutoPacingAllowed(deps.hasObservedBackpressure?.() ?? false);
+						deps.onSmoothStreamingMode?.(mode, mode === "on" || (mode === "auto" && autoAllowed));
+						return mode;
+					},
+					isAutoPacingAllowed: () => processAutoPacingAllowed(deps.hasObservedBackpressure?.() ?? false),
+					...(deps.commitFrame ? { commitFrame: deps.commitFrame } : {}),
+				}
+			: {}),
+		...(renderTrace
+			? {
+					visibleEventSequence: (event) => deps.resolveVisibleEventSequence?.(event) ?? null,
+					onQueue: (eventSeq, action) => renderTrace.recordQueue(eventSeq, action),
+					onPanelApplied: (eventSeq) => renderTrace.recordPanelApplied(eventSeq),
+				}
+			: {}),
 	});
 	const io = factories.createIo({
-		appendReplayBlock: (renderBlock) => chatPanel.appendReplayBlock(renderBlock),
-		requestRender,
-	});
-	const root = factories.buildLayout({
-		banner,
-		chat: chatPanel,
-		pending: followUpQueuePanel,
-		editor,
-		footer: footer.view,
+		appendReplayBlock: (renderBlock) =>
+			chatRenderer.mutate(() => chatPanel.appendReplayBlock(renderBlock), "command-output"),
+		requestRender: () => {},
 	});
-	deps.mount(root, editor);
+	const pending: Component = deps.bootPending
+		? {
+				render: (width) => [...(deps.bootPending?.render(width) ?? []), ...followUpQueuePanel.render(width)],
+				invalidate: () => {
+					deps.bootPending?.invalidate();
+					followUpQueuePanel.invalidate();
+				},
+			}
+		: followUpQueuePanel;
+	const root = factories.buildLayout(
+		{
+			banner,
+			chat: chatPanel,
+			pending,
+			editor,
+			footer: footer.view,
+		},
+		{
+			mode: settings.terminal?.tuiMode ?? "regular",
+			fullscreenScrollbar: settings.terminal?.fullscreenScrollbar ?? "auto",
+		},
+	);
+	deps.mount?.(root, editor);
 
 	const scheduleInterval = deps.scheduleInterval ?? ((callback, intervalMs) => setInterval(callback, intervalMs));
 	const clearScheduledInterval =
@@ -414,11 +543,13 @@ export function createInteractivePresentation(deps: InteractivePresentationDeps)
 			if (banner.collapseToSessionHeader()) requestRender();
 		},
 		editor,
+		editorChrome,
 		dispatchBoard,
 		chatRenderer,
 		io,
 		root,
 		getObservabilitySnapshot: () => observabilitySnapshot,
+		recordChatEvent,
 		recordToolStart: (toolCallId, toolName) => {
 			footerActiveTools.add(toolCallId);
 			footerToolCounts.set(toolName, (footerToolCounts.get(toolName) ?? 0) + 1);
@@ -438,6 +569,7 @@ export function createInteractivePresentation(deps: InteractivePresentationDeps)
 			footerToolErrors = 0;
 			footerToolTruncatedResults = 0;
 			lastTurnSummary = null;
+			liveThroughput = null;
 			statusController.reset();
 		},
 		stopTickers,

package/src/interactive/interactive-shell.ts

@@ -1,13 +1,25 @@
-import type { Component, Terminal } from "../engine/tui.js";
-import { ProcessTerminal, TUI } from "../engine/tui.js";
-import { createRenderTrace, type RenderTrace, renderTracePath, traceTerminalWrites } from "./render-trace.js";
+import type { Component, Terminal, TuiMode, TuiRenderObserver } from "../engine/tui.js";
+import { InstrumentedTuiAltScreen, InstrumentedTuiMainScreen, ProcessTerminal, type TUI } from "../engine/tui.js";
+import {
+	createRenderTrace,
+	type RenderTrace,
+	renderTracePath,
+	traceComponentRenders,
+	traceProcessStdout,
+} from "./render-trace.js";
+import type { StdoutBackpressureGate } from "./stdout-backpressure.js";
+import { installStdoutBackpressureGate } from "./stdout-backpressure.js";
 
 export interface InteractiveShellTui {
+	readonly mode?: TuiMode;
 	addChild(component: Component): void;
+	removeChild?(component: Component): void;
+	setLayoutRoot?(component: Component | undefined): void;
 	setFocus(component: Component): void;
 	start(): void;
 	stop(): void;
 	requestRender(): void;
+	renderNow?(force?: boolean): void;
 }
 
 export interface InteractiveShellInterval {
@@ -22,6 +34,8 @@ export interface InteractiveShellDeps<
 	createTui: (terminal: TTerminal) => TTui;
 	scheduleInterval?: (callback: () => void, intervalMs: number) => InteractiveShellInterval;
 	clearScheduledInterval?: (handle: InteractiveShellInterval) => void;
+	prepareRoot?: (root: Component) => void;
+	onStop?: () => void | Promise<void>;
 }
 
 export interface InteractiveShell<
@@ -34,6 +48,16 @@ export interface InteractiveShell<
 	anchor(): Promise<number>;
 	releaseAnchor(): void;
 	stop(): void;
+	/** Issue the latest model frame and wait a finite bound for stdout drain. */
+	commitCurrentFrame(timeoutMs?: number): Promise<number | null>;
+	/** True after this process has observed stdout saturation at least once. */
+	hasObservedBackpressure(): boolean;
+	/** Enable admission control only while presentation pacing is actually active. */
+	setStreamPacingActive(active: boolean): void;
+	/** Await asynchronous teardown work started by stop(), including trace-file settlement. */
+	settle(): Promise<void>;
+	/** Resolve after the next render transaction that reaches terminal commit. */
+	nextCommittedFrame(): Promise<number | null>;
 	complete(code: number): void;
 }
 
@@ -62,6 +86,8 @@ export function createInteractiveShell<TTerminal extends Terminal, TTui extends
 	let resolveRun: ((code: number) => void) | null = null;
 	let run: Promise<number> | null = null;
 	let completedCode: number | null = null;
+	let stopped = false;
+	let stopSettlement: Promise<void> | null = null;
 
 	return {
 		terminal,
@@ -69,7 +95,9 @@ export function createInteractiveShell<TTerminal extends Terminal, TTui extends
 		mount(root, focus): void {
 			if (mounted) return;
 			mounted = true;
+			deps.prepareRoot?.(root);
 			tui.addChild(root);
+			if (tui.mode === "fullscreen") tui.setLayoutRoot?.(root);
 			tui.setFocus(focus);
 			tui.start();
 		},
@@ -90,12 +118,37 @@ export function createInteractiveShell<TTerminal extends Terminal, TTui extends
 			keepAlive = null;
 		},
 		stop(): void {
+			if (stopped) return;
+			stopped = true;
 			try {
 				tui.stop();
 			} catch {
 				// TUI may already be stopped by a closed input stream.
+			} finally {
+				try {
+					stopSettlement = Promise.resolve(deps.onStop?.()).then(() => undefined);
+				} catch {
+					// Teardown is best effort, like a terminal that already closed.
+					stopSettlement = Promise.resolve();
+				}
 			}
 		},
+		async commitCurrentFrame(): Promise<number | null> {
+			if (!tui.renderNow) {
+				tui.requestRender();
+				return null;
+			}
+			tui.renderNow(false);
+			return null;
+		},
+		hasObservedBackpressure: () => false,
+		setStreamPacingActive: () => {},
+		settle(): Promise<void> {
+			return stopSettlement ?? Promise.resolve();
+		},
+		nextCommittedFrame(): Promise<number | null> {
+			return Promise.resolve(null);
+		},
 		complete(code): void {
 			if (completedCode !== null) return;
 			completedCode = code;
@@ -115,20 +168,221 @@ export function getActiveRenderTrace(): RenderTrace | null {
 	return activeRenderTrace;
 }
 
+/**
+ * Wait for ordinary admission, but never let a missing drain erase the final
+ * 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(
+	gate: Pick<StdoutBackpressureGate, "whenWritable"> | null,
+	timeoutMs: number,
+	renderFrame: () => Promise<number>,
+): Promise<number> {
+	const writableBeforeRender = gate ? await gate.whenWritable(timeoutMs) : true;
+	const frameId = await renderFrame();
+	if (writableBeforeRender && gate) await gate.whenWritable(timeoutMs);
+	return frameId;
+}
+
 /** Production factories stay here so the composition root does not own them. */
-export function createProcessInteractiveShell(): InteractiveShell<ProcessTerminal, TUI> {
+export function createProcessInteractiveShell(
+	options: {
+		tuiMode?: TuiMode;
+		onFirstFrameCommit?: (frameId: number) => void;
+		streamPacingActive?: boolean;
+		/** Construction fault seams for process-global rollback contracts. */
+		testing?: {
+			createTerminal?: () => ProcessTerminal;
+			createTui?: (terminal: ProcessTerminal) => TUI;
+		};
+	} = {},
+): InteractiveShell<ProcessTerminal, TUI> {
 	const tracePath = renderTracePath();
+	let restoreStdout: (() => void) | null = null;
+	let restoreFirstFrameStdout: (() => void) | null = null;
+	let restoreRoot: (() => void) | null = null;
+	let backpressure: StdoutBackpressureGate | null = null;
+	let observedBackpressure = false;
 	if (tracePath) {
-		activeRenderTrace = createRenderTrace(tracePath);
-		const trace = activeRenderTrace;
-		process.once("exit", () => trace.close());
-	}
+		let candidate: RenderTrace | null = null;
+		try {
+			candidate = createRenderTrace(tracePath);
+			restoreStdout = traceProcessStdout(candidate);
+			activeRenderTrace = candidate;
+		} catch {
+			// A diagnostics path must never prevent the interactive application from starting.
+			restoreStdout?.();
+			restoreStdout = null;
+			void candidate?.close().catch(() => {});
+			activeRenderTrace = null;
+		}
+	} else activeRenderTrace = null;
 	const trace = activeRenderTrace;
-	return createInteractiveShell({
-		createTerminal: () => {
-			const terminal = new ProcessTerminal();
-			return trace ? traceTerminalWrites(terminal, trace) : terminal;
+	if (trace && options.onFirstFrameCommit) trace.onFirstFrameCommit(options.onFirstFrameCommit);
+	let firstFrameDelivered = false;
+	let firstFrameSeq = 0;
+	let firstFrameActive = false;
+	let firstFrameWrote = false;
+	if (!trace && options.onFirstFrameCommit) {
+		const stdout = process.stdout;
+		const original = stdout.write;
+		const wrapped = function (this: typeof stdout, ...args: unknown[]): boolean {
+			const returned = Reflect.apply(original, this, args) as boolean;
+			if (firstFrameActive) firstFrameWrote = true;
+			return returned;
+		} as typeof stdout.write;
+		stdout.write = wrapped;
+		restoreFirstFrameStdout = () => {
+			if (stdout.write === wrapped) stdout.write = original;
+		};
+	}
+	const firstFrameOnlyObserver: TuiRenderObserver = {
+		isEnabled: () => !firstFrameDelivered,
+		beginFrame: () => {
+			firstFrameSeq += 1;
+			firstFrameActive = true;
+			firstFrameWrote = false;
+			return firstFrameSeq;
+		},
+		endFrame: (frame) => {
+			firstFrameActive = false;
+			if (firstFrameDelivered || !firstFrameWrote) return;
+			firstFrameDelivered = true;
+			options.onFirstFrameCommit?.(frame as number);
+			restoreFirstFrameStdout?.();
+			restoreFirstFrameStdout = null;
+		},
+		beginPhase: () => null,
+		endPhase: () => {},
+	};
+	const primaryObserver = trace ?? (options.onFirstFrameCommit ? firstFrameOnlyObserver : null);
+	let committedFrameSequence = 0;
+	const frameWaiters: Array<{ resolve: (frameId: number) => void }> = [];
+	const renderObserver: TuiRenderObserver = {
+		isEnabled: () => frameWaiters.length > 0 || (primaryObserver !== null && (primaryObserver.isEnabled?.() ?? true)),
+		beginFrame: (fields) => ({
+			primary: primaryObserver?.beginFrame(fields),
+			primaryActive: primaryObserver !== null && (primaryObserver.isEnabled?.() ?? true),
+			frameId: ++committedFrameSequence,
+		}),
+		endFrame: (token) => {
+			const frame = token as { primary: unknown; primaryActive: boolean; frameId: number };
+			if (frame.primaryActive) primaryObserver?.endFrame(frame.primary);
+			for (const waiter of frameWaiters.splice(0)) waiter.resolve(frame.frameId);
+		},
+		beginPhase: (token, phase) => {
+			const frame = token as { primary: unknown; primaryActive: boolean };
+			return frame.primaryActive ? primaryObserver?.beginPhase(frame.primary, phase) : null;
 		},
-		createTui: (terminal) => new TUI(terminal),
-	});
+		endPhase: (token, phase, phaseToken) => {
+			const frame = token as { primary: unknown; primaryActive: boolean };
+			if (frame.primaryActive) primaryObserver?.endPhase(frame.primary, phase, phaseToken);
+		},
+	};
+	const renderAdmission = {
+		get blocked() {
+			return backpressure?.blocked ?? false;
+		},
+		onWritable(listener: () => void) {
+			if (backpressure) return backpressure.onWritable(listener);
+			queueMicrotask(listener);
+			return () => {};
+		},
+	};
+	const setStreamPacingActive = (active: boolean): void => {
+		if (active) {
+			backpressure ??= installStdoutBackpressureGate();
+			return;
+		}
+		if (!backpressure) return;
+		observedBackpressure ||= backpressure.observed;
+		backpressure.restore();
+		backpressure = null;
+	};
+	let instrumentationCleanupStarted = false;
+	let instrumentationCleanupPromise: Promise<void> = Promise.resolve();
+	const cleanupInstrumentation = (): Promise<void> => {
+		if (instrumentationCleanupStarted) return instrumentationCleanupPromise;
+		instrumentationCleanupStarted = true;
+		const errors: unknown[] = [];
+		const attempt = (operation: () => void): void => {
+			try {
+				operation();
+			} catch (error) {
+				errors.push(error);
+			}
+		};
+		attempt(() => setStreamPacingActive(false));
+		attempt(() => restoreRoot?.());
+		restoreRoot = null;
+		attempt(() => restoreStdout?.());
+		restoreStdout = null;
+		attempt(() => restoreFirstFrameStdout?.());
+		restoreFirstFrameStdout = null;
+		if (activeRenderTrace === trace) activeRenderTrace = null;
+		instrumentationCleanupPromise = (async () => {
+			if (trace) {
+				try {
+					await trace.close();
+				} catch (error) {
+					errors.push(error);
+				}
+			}
+			if (errors.length > 0) throw new AggregateError(errors, "interactive shell instrumentation cleanup failed");
+		})();
+		return instrumentationCleanupPromise;
+	};
+	let shell: InteractiveShell<ProcessTerminal, TUI>;
+	try {
+		setStreamPacingActive(options.streamPacingActive === true);
+		shell = createInteractiveShell({
+			createTerminal: options.testing?.createTerminal ?? (() => new ProcessTerminal()),
+			createTui: (terminal) =>
+				options.testing?.createTui?.(terminal) ??
+				(options.tuiMode === "fullscreen"
+					? new InstrumentedTuiAltScreen(terminal, renderObserver, undefined, undefined, undefined, renderAdmission)
+					: new InstrumentedTuiMainScreen(terminal, renderObserver, undefined, undefined, renderAdmission)),
+			prepareRoot: (root) => {
+				if (trace) restoreRoot = traceComponentRenders(root, trace);
+			},
+			onStop: cleanupInstrumentation,
+		});
+	} catch (error) {
+		void cleanupInstrumentation().catch(() => {});
+		throw error;
+	}
+	return {
+		...shell,
+		nextCommittedFrame(): Promise<number | null> {
+			return new Promise<number>((resolve) => {
+				frameWaiters.push({ resolve });
+			});
+		},
+		async commitCurrentFrame(timeoutMs = 30_000): Promise<number | null> {
+			return await settleLatestInteractiveFrame(backpressure, timeoutMs, async () => {
+				const tui = shell.tui as TUI & { renderNow(force?: boolean): void };
+				const waiter: { resolve: (frameId: number) => void } = { resolve: () => {} };
+				const frame = new Promise<number>((resolve) => {
+					waiter.resolve = resolve;
+					frameWaiters.push(waiter);
+				});
+				try {
+					// Even when the writable never drains, issue exactly one bounded
+					// final frame. Preserve the renderer's cursor/history state: forcing
+					// a reset here makes TuiMainScreen repaint from the current physical
+					// column and can concatenate the full frame onto the footer. A direct
+					// differential render is still synchronous and commits every newest
+					// component mutation without reopening ordinary frame production.
+					tui.renderNow(false);
+				} catch (error) {
+					const index = frameWaiters.indexOf(waiter);
+					if (index >= 0) frameWaiters.splice(index, 1);
+					throw error;
+				}
+				return await frame;
+			});
+		},
+		hasObservedBackpressure: () => observedBackpressure || backpressure?.observed === true,
+		setStreamPacingActive,
+	};
 }