@oh-my-pi/pi-coding-agent 16.0.2 → 16.0.3

package/src/main.ts

@@ -55,6 +55,7 @@ import type { PrintModeOptions } from "./modes/print-mode";
 import { CURRENT_SETUP_VERSION } from "./modes/setup-version";
 import { initTheme, stopThemeWatcher } from "./modes/theme/theme";
 import type { SubmittedUserInput } from "./modes/types";
+import { AgentLifecycleManager } from "./registry/agent-lifecycle";
 import {
 	type CreateAgentSessionOptions,
 	type CreateAgentSessionResult,
@@ -68,6 +69,7 @@ import { resolveResumableSession, type SessionInfo } from "./session/session-lis
 import { SessionManager } from "./session/session-manager";
 import { executeBuiltinSlashCommand } from "./slash-commands/builtin-registry";
 import { discoverTitleSystemPromptFile, resolvePromptInput } from "./system-prompt";
+import { createPersistedSubagentReviverFactory } from "./task/persisted-revive";
 import { initTelemetryExport, isTelemetryExportEnabled } from "./telemetry-export";
 import { AUTO_THINKING } from "./thinking";
 import type { LspStartupServerInfo } from "./tools";
@@ -1262,6 +1264,24 @@ export async function runRootCommand(
 			eventBus,
 			preloadedExtensions: extensionsResult,
 		});
+
+		// Cold-revive support: a `parked` subagent ref restored from disk (Agent Hub
+		// scan, collab mirror, resumed process) has a sessionFile but no in-memory
+		// reviver, so `ensureLive` (IRC sends, hub focus) would refuse it. Install a
+		// factory — bound to THIS top-level session — that rebuilds the subagent from
+		// its persisted JSONL (see persisted-revive.ts). Scoped to the non-ACP
+		// bootstrap: ACP keeps several concurrent top-level sessions and a single
+		// process-global factory must not be clobbered by the most recent one.
+		AgentLifecycleManager.global().setPersistedSubagentReviverFactory(
+			createPersistedSubagentReviverFactory({
+				session,
+				authStorage,
+				modelRegistry,
+				settings: settingsInstance,
+				enableLsp: sessionOptions.enableLsp ?? true,
+			}),
+			Math.trunc(Number(settingsInstance.get("task.agentIdleTtlMs") ?? 420_000) || 0),
+		);
 		if (parsedArgs.apiKey && !sessionOptions.model && session.model) {
 			authStorage.setRuntimeApiKey(session.model.provider, parsedArgs.apiKey);
 		}

package/src/mcp/render.ts

@@ -18,6 +18,7 @@ import {
 	JSON_TREE_SCALAR_LEN_EXPANDED,
 	renderJsonTreeLines,
 } from "../tools/json-tree";
+import { formatStyledTruncationWarning, stripOutputNotice } from "../tools/output-meta";
 import { formatExpandHint, truncateToWidth } from "../tools/render-utils";
 import { renderStatusLine } from "../tui";
 import type { MCPToolDetails } from "./tool-bridge";
@@ -78,7 +79,14 @@ export function renderMCPResult(
 
 	// Output section
 	const textContent = result.content?.find(c => c.type === "text")?.text ?? "";
-	const trimmedOutput = textContent.trimEnd();
+	// Strip the LLM-facing spill notice before parsing/rendering: a spilled
+	// result appends `[Showing… artifact://N]` to the body, which would break
+	// JSON detection and bury the recovery link. Surface it as a styled warning
+	// instead, mirroring the built-in read/bash/ssh/browser renderers.
+	const trimmedOutput = stripOutputNotice(textContent, result.details?.meta).trimEnd();
+	const truncationWarning = result.details?.meta?.truncation
+		? formatStyledTruncationWarning(result.details.meta, theme)
+		: null;
 
 	if (!trimmedOutput) {
 		lines.push(theme.fg("dim", "(no output)"));
@@ -104,6 +112,7 @@ export function renderMCPResult(
 				} else if (tree.truncated) {
 					lines.push(theme.fg("dim", "…"));
 				}
+				if (truncationWarning) lines.push(truncationWarning);
 				return new Text(lines.join("\n"), 0, 0);
 			}
 		} catch {
@@ -128,5 +137,6 @@ export function renderMCPResult(
 		lines.push(formatExpandHint(theme, expanded, true));
 	}
 
+	if (truncationWarning) lines.push(truncationWarning);
 	return new Text(lines.join("\n"), 0, 0);
 }

package/src/mcp/tool-bridge.ts

@@ -15,6 +15,7 @@ import type {
 	RenderResultOptions,
 } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
+import type { OutputMeta } from "../tools/output-meta";
 import { ToolAbortError, throwIfAborted } from "../tools/tool-errors";
 import { callTool } from "./client";
 import { renderMCPCall, renderMCPResult } from "./render";
@@ -71,6 +72,8 @@ export interface MCPToolDetails {
 	provider?: string;
 	/** Provider display name (e.g., "Claude Code", "MCP Config") */
 	providerName?: string;
+	/** Structured output metadata (set by the spill wrapper when output is truncated to an artifact). */
+	meta?: OutputMeta;
 }
 /**
  * Format MCP content for LLM consumption.

package/src/modes/components/custom-editor.test.ts

@@ -1,7 +1,12 @@
-import { afterEach, beforeAll, describe, expect, it, vi } from "bun:test";
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "bun:test";
 import { $ } from "bun";
 import { getEditorTheme, initTheme } from "../theme/theme";
-import { CustomEditor, SPACE_HOLD_RELEASE_MS, SPACE_HOLD_THRESHOLD } from "./custom-editor";
+import {
+	CustomEditor,
+	SPACE_HOLD_MECHANICAL_RUN,
+	SPACE_HOLD_RELEASE_MS,
+	SPACE_REPEAT_MAX_GAP_MS,
+} from "./custom-editor";
 
 function makeEditor() {
 	const editor = new CustomEditor(getEditorTheme());
@@ -12,8 +17,26 @@ function makeEditor() {
 	return { editor, events };
 }
 
-function holdSpace(editor: CustomEditor, count: number): void {
-	for (let i = 0; i < count; i++) editor.handleInput(" ");
+/** A gap below SPACE_REPEAT_MAX_GAP_MS — looks like OS key auto-repeat (a held bar). */
+const REPEAT_GAP_MS = 30;
+/** A gap above the threshold — looks like a deliberate keypress. */
+const TAP_GAP_MS = SPACE_REPEAT_MAX_GAP_MS + 80;
+
+/** Feed `count` spaces `gapMs` apart on the fake clock. The first space of a run has no prior
+ *  space, so its gap is effectively infinite and it always reads as a deliberate tap. */
+function feedSpaces(editor: CustomEditor, count: number, gapMs: number): void {
+	for (let i = 0; i < count; i++) {
+		vi.advanceTimersByTime(gapMs);
+		editor.handleInput(" ");
+	}
+}
+
+/** Feed spaces at explicit per-press gaps (ms) on the fake clock — for simulating an irregular cadence. */
+function feedGaps(editor: CustomEditor, gaps: number[]): void {
+	for (const gapMs of gaps) {
+		vi.advanceTimersByTime(gapMs);
+		editor.handleInput(" ");
+	}
 }
 
 async function decorateInFreshProcess(text: string): Promise<string> {
@@ -47,29 +70,32 @@ describe("CustomEditor space-hold push-to-talk", () => {
 		await initTheme();
 	});
 
+	beforeEach(() => {
+		vi.useFakeTimers();
+	});
+
 	afterEach(() => {
 		vi.useRealTimers();
 	});
 
-	it("inserts spaces normally below the hold threshold", () => {
+	it("types deliberate space taps without triggering, even several in a row", () => {
 		const { editor, events } = makeEditor();
-		holdSpace(editor, SPACE_HOLD_THRESHOLD);
-		expect(editor.getText()).toBe(" ".repeat(SPACE_HOLD_THRESHOLD));
+		feedSpaces(editor, 3, TAP_GAP_MS);
+		expect(editor.getText()).toBe("   ");
 		expect(events).toEqual([]);
 	});
 
-	it("tracks back the space burst and drives the hold lifecycle", () => {
-		vi.useFakeTimers();
+	it("recognizes a held bar from a steady fast cadence and tracks back the burst", () => {
 		const { editor, events } = makeEditor();
 		editor.handleInput("h");
 		editor.handleInput("i");
-		// Crossing the threshold deletes the optimistically-inserted spaces and starts recording,
-		// leaving only the pre-burst text behind.
-		holdSpace(editor, SPACE_HOLD_THRESHOLD + 1);
+		// Metronomic auto-repeat: the few pre-burst spaces typed are tracked back out when the hold is
+		// recognized, leaving only the pre-burst text.
+		feedSpaces(editor, SPACE_HOLD_MECHANICAL_RUN + 2, REPEAT_GAP_MS);
 		expect(editor.getText()).toBe("hi");
 		expect(events).toEqual(["start"]);
 		// Continued auto-repeat while the bar is held is swallowed: no spam, no re-trigger.
-		holdSpace(editor, 5);
+		feedSpaces(editor, 5, REPEAT_GAP_MS);
 		expect(editor.getText()).toBe("hi");
 		expect(events).toEqual(["start"]);
 		// An idle gap with no further repeats means the bar was released -> stop + transcribe.
@@ -77,20 +103,39 @@ describe("CustomEditor space-hold push-to-talk", () => {
 		expect(events).toEqual(["start", "end"]);
 	});
 
+	it("does not trigger when the space bar is smashed at an irregular cadence", () => {
+		const { editor, events } = makeEditor();
+		// Fast but jittery, the way a human mashes — not the metronomic delta of OS auto-repeat.
+		const gaps = [40, 95, 45, 100, 35, 90, 50, 105];
+		feedGaps(editor, gaps);
+		expect(events).toEqual([]);
+		// Nothing is eaten: every smashed space still types a real space.
+		expect(editor.getText()).toBe(" ".repeat(gaps.length));
+	});
+
+	it("does not trigger on steady but slow spacing", () => {
+		const { editor, events } = makeEditor();
+		// Even cadence, but slower than auto-repeat: consistent deltas alone must not start recording.
+		feedSpaces(editor, 6, TAP_GAP_MS);
+		expect(events).toEqual([]);
+		expect(editor.getText()).toBe(" ".repeat(6));
+	});
+
 	it("does not trigger when a non-space breaks the run", () => {
 		const { editor, events } = makeEditor();
-		holdSpace(editor, SPACE_HOLD_THRESHOLD);
+		// Each partial run climbs the mechanical counter one short of the threshold; the non-space
+		// resets it so they never combine into a hold.
+		feedSpaces(editor, 3, REPEAT_GAP_MS);
 		editor.handleInput("x");
-		holdSpace(editor, SPACE_HOLD_THRESHOLD);
+		feedSpaces(editor, 3, REPEAT_GAP_MS);
 		expect(events).toEqual([]);
-		expect(editor.getText()).toBe(`${" ".repeat(SPACE_HOLD_THRESHOLD)}x${" ".repeat(SPACE_HOLD_THRESHOLD)}`);
 	});
 
 	it("leaves the space bar typing normally when the gesture is disabled", () => {
 		const { editor, events } = makeEditor();
 		editor.sttHoldEnabled = () => false;
-		holdSpace(editor, SPACE_HOLD_THRESHOLD + 5);
-		expect(editor.getText()).toBe(" ".repeat(SPACE_HOLD_THRESHOLD + 5));
+		feedSpaces(editor, 8, REPEAT_GAP_MS);
+		expect(editor.getText()).toBe(" ".repeat(8));
 		expect(events).toEqual([]);
 	});
 });

package/src/modes/components/custom-editor.ts

@@ -62,14 +62,34 @@ const BRACKETED_IMAGE_PATH_REGEX = /\.(?:png|jpe?g|gif|webp)$/i;
 const BRACKETED_IMAGE_PATH_BOUNDARY_REGEX = /\.(?:png|jpe?g|gif|webp)(?=$|["']?\s)/gi;
 const SHELL_ESCAPED_PATH_CHAR_REGEX = /\\([\\\s'"()[\]{}&;<>|?*!$`])/g;
 
-/** Plain spaces from one auto-repeat run that trigger the space-hold push-to-talk STT gesture.
- *  Holding the space bar makes the terminal emit a burst of spaces; once more than this many land
- *  in the editor we treat it as "space held", track them back out, and start recording. */
-export const SPACE_HOLD_THRESHOLD = 5;
+/** Max gap (ms) between two spaces for the later one to count as OS key auto-repeat rather than a
+ *  deliberate press. OS auto-repeat is fast; a deliberate tap (even a fast one) is slower. */
+export const SPACE_REPEAT_MAX_GAP_MS = 120;
+/** Two consecutive inter-space gaps are "mechanical" (machine-driven auto-repeat) when both are
+ *  within {@link SPACE_REPEAT_MAX_GAP_MS} and differ by no more than this — an absolute jitter floor
+ *  or, for slower repeat rates, {@link SPACE_REPEAT_JITTER_RATIO} of the smaller gap. OS key-repeat
+ *  is metronomic; a human smashing the bar is fast but irregular, so its deltas never stay this
+ *  steady. */
+export const SPACE_REPEAT_JITTER_MS = 18;
+export const SPACE_REPEAT_JITTER_RATIO = 0.35;
+/** Consecutive mechanical (fast + steady) deltas that confirm the space bar is held and start
+ *  recording. Needs a sustained metronomic cadence, so jittery smashing and deliberate taps never
+ *  reach it. */
+export const SPACE_HOLD_MECHANICAL_RUN = 2;
 /** Idle gap (ms) after the last repeated space that counts as the space bar being released, ending
  *  the push-to-talk recording. Must comfortably exceed the OS key-repeat interval. */
 export const SPACE_HOLD_RELEASE_MS = 250;
 
+/** Whether two consecutive inter-space gaps look machine-driven: both within the auto-repeat band
+ *  and steady enough (small absolute or proportional difference). OS key-repeat is metronomic, so
+ *  its successive deltas match closely; human smashing is fast but irregular and deliberate taps are
+ *  too slow, so neither passes. */
+function gapsAreMechanical(gap: number, prevGap: number): boolean {
+	if (gap > SPACE_REPEAT_MAX_GAP_MS || prevGap > SPACE_REPEAT_MAX_GAP_MS) return false;
+	const tolerance = Math.max(SPACE_REPEAT_JITTER_MS, Math.min(gap, prevGap) * SPACE_REPEAT_JITTER_RATIO);
+	return Math.abs(gap - prevGap) <= tolerance;
+}
+
 function isPastedPathSeparator(char: string | undefined): boolean {
 	return char === undefined || char === " " || char === "\t" || char === "\r" || char === "\n";
 }
@@ -266,8 +286,14 @@ export class CustomEditor extends Editor {
 	/** Custom key handlers from extensions and non-built-in app actions. */
 	#customKeyHandlers = new Map<KeyId, () => void>();
 	#customMatchKeys = new Map<string, () => void>();
-	/** Consecutive plain spaces inserted in the current run; any other key resets it. */
+	/** Spaces actually inserted in the current run; tracked back out when a hold is recognized. */
 	#spaceRunInserted = 0;
+	/** Consecutive "mechanical" deltas (fast + steady); a sustained run of these confirms a held bar. */
+	#mechanicalRun = 0;
+	/** Inter-space gap (ms) of the previous space pair, compared against the next to judge steadiness. */
+	#prevSpaceGap: number | undefined;
+	/** Monotonic timestamp (ms) of the last space, to measure the gap to the next one. */
+	#lastSpaceAt = Number.NEGATIVE_INFINITY;
 	/** True while a recognized space-hold push-to-talk recording is in progress. */
 	#spaceHoldActive = false;
 	/** Idle timer that fires `onSpaceHoldEnd` once repeated spaces stop arriving. */
@@ -334,9 +360,12 @@ export class CustomEditor extends Editor {
 	}
 
 	/** Drive the space-hold push-to-talk state machine. Returns true when the gesture consumed the
-	 *  input so it must not reach normal editing. Holding the space bar makes the terminal emit a
-	 *  burst of auto-repeat spaces; once more than {@link SPACE_HOLD_THRESHOLD} of them land we treat
-	 *  it as a hold, delete the spam, and start recording until the repeats stop. */
+	 *  input so it must not reach normal editing. A held space bar emits OS auto-repeat: a *steady*
+	 *  stream of spaces at a fixed fast interval. We watch the inter-space deltas and only recognize a
+	 *  hold once {@link SPACE_HOLD_MECHANICAL_RUN} consecutive deltas are "mechanical" — both
+	 *  auto-repeat-fast and near-identical (see {@link gapsAreMechanical}). Smashing the bar is fast
+	 *  but jittery and deliberate taps are too slow, so neither escalates and both keep typing real
+	 *  spaces; the few spaces typed before a real hold is recognized are tracked back out. */
 	#handleSpaceHold(data: string, canonical: string | undefined): boolean {
 		const isSpace = canonical === "space";
 		if (this.#spaceHoldActive) {
@@ -350,21 +379,40 @@ export class CustomEditor extends Editor {
 			return false;
 		}
 		if (!isSpace) {
-			this.#spaceRunInserted = 0;
+			this.#resetSpaceRun();
 			return false;
 		}
 		if (!this.#spaceHoldGestureEnabled()) return false;
-		// A short tap should still type a normal space, so insert optimistically and count the run.
-		super.handleInput(data);
-		this.#spaceRunInserted++;
-		if (this.#spaceRunInserted > SPACE_HOLD_THRESHOLD) {
+		const now = performance.now();
+		const gap = now - this.#lastSpaceAt;
+		const prevGap = this.#prevSpaceGap;
+		this.#lastSpaceAt = now;
+		this.#prevSpaceGap = gap;
+		if (prevGap === undefined || !gapsAreMechanical(gap, prevGap)) {
+			// First space, a deliberate tap, or jittery smashing: not a steady machine cadence yet, so
+			// type a real space and reset the mechanical run.
+			this.#mechanicalRun = 0;
+			super.handleInput(data);
+			this.#spaceRunInserted++;
+			return true;
+		}
+		// Steady fast repeat: swallow it. Once the cadence has held for SPACE_HOLD_MECHANICAL_RUN
+		// deltas it's a held bar — track back the few pre-burst spaces already typed and start.
+		if (++this.#mechanicalRun >= SPACE_HOLD_MECHANICAL_RUN) {
 			this.deleteBeforeCursor(this.#spaceRunInserted);
-			this.#spaceRunInserted = 0;
+			this.#resetSpaceRun();
 			this.#beginSpaceHold();
 		}
 		return true;
 	}
 
+	#resetSpaceRun(): void {
+		this.#spaceRunInserted = 0;
+		this.#mechanicalRun = 0;
+		this.#prevSpaceGap = undefined;
+		this.#lastSpaceAt = Number.NEGATIVE_INFINITY;
+	}
+
 	#beginSpaceHold(): void {
 		this.#spaceHoldActive = true;
 		this.#armSpaceHoldReleaseTimer();
@@ -383,7 +431,7 @@ export class CustomEditor extends Editor {
 	#endSpaceHold(): void {
 		if (!this.#spaceHoldActive) return;
 		this.#spaceHoldActive = false;
-		this.#spaceRunInserted = 0;
+		this.#resetSpaceRun();
 		if (this.#spaceHoldTimer) {
 			clearTimeout(this.#spaceHoldTimer);
 			this.#spaceHoldTimer = undefined;

package/src/modes/controllers/command-controller.ts

@@ -84,9 +84,9 @@ export class CommandController {
 		}
 	}
 
-	handleDumpCommand(isRaw = false) {
+	handleDumpCommand() {
 		try {
-			const formatted = this.ctx.session.formatSessionAsText({ compact: !isRaw });
+			const formatted = this.ctx.session.formatSessionAsText();
 			if (!formatted) {
 				this.ctx.showError("No messages to dump yet.");
 				return;

package/src/modes/controllers/input-controller.ts

@@ -708,21 +708,25 @@ export class InputController {
 				// No input waiter: the main loop is between turns (post-turn
 				// epilogue, retry backoff, or a scheduled continue) with the agent
 				// momentarily idle. The editor already cleared itself on Enter, so
-				// falling through here would silently swallow the message. Queue it
-				// as a steer instead: the idle drain in #queueSteer delivers it
-				// immediately when the session is resumable, and a retry/continue
-				// run picks it up at loop start otherwise.
+				// falling through here would silently swallow the message. Submit a
+				// real prompt directly; if a background turn starts in the gap,
+				// `streamingBehavior: "steer"` preserves the typed-message queueing
+				// semantics instead of throwing AgentBusyError.
 				this.ctx.editor.imageLinks = undefined;
 				const images = inputImages && inputImages.length > 0 ? [...inputImages] : undefined;
 				this.ctx.pendingImages = [];
 				this.ctx.pendingImageLinks = [];
 				try {
-					await this.ctx.withLocalSubmission(text, () => this.ctx.session.steer(text, images), {
-						imageCount: images?.length ?? 0,
-					});
+					await this.ctx.withLocalSubmission(
+						text,
+						() => this.ctx.session.prompt(text, { streamingBehavior: "steer", images }),
+						{
+							imageCount: images?.length ?? 0,
+						},
+					);
 				} catch (error) {
 					// Don't lose the message: hand the text and images back to the
-					// editor so the user can retry (e.g. steer() rejecting an
+					// editor so the user can retry (e.g. prompt dispatch rejecting an
 					// extension command).
 					this.ctx.editor.setText(text);
 					if (images && images.length > 0) {
@@ -994,7 +998,9 @@ export class InputController {
 
 	restoreQueuedMessagesToEditor(options?: { abort?: boolean; currentText?: string }): number {
 		this.ctx.locallySubmittedUserSignatures.clear();
-		const { steering, followUp } = this.ctx.session.clearQueue();
+		// On Esc (abort) drop non-user internal steers so the post-abort drain can't
+		// auto-resume; plain Alt+Up dequeue preserves them for the continuing stream.
+		const { steering, followUp } = this.ctx.session.clearQueue({ forInterrupt: options?.abort });
 		// Messages typed while compacting live in `compactionQueuedMessages`, not the
 		// agent queue `clearQueue()` drains — but the pending bar shows the same
 		// "Alt+Up to edit" hint for them (ui-helpers `updatePendingMessagesDisplay`).

package/src/modes/controllers/selector-controller.ts

@@ -1216,11 +1216,20 @@ export class SelectorController {
 			...this.ctx.keybindings.getKeys("app.session.observe"),
 		];
 		let hub: AgentHubOverlayComponent | undefined;
-		let overlayHandle: OverlayHandle | undefined;
 
+		// Render the hub inline in the editor slot — the same anchored region
+		// every other selector (model, session, tree, the `ask` tool) uses —
+		// rather than a floating overlay. A non-fullscreen overlay composited over
+		// a live transcript strands a stale copy in native scrollback every time a
+		// running subagent's progress grows the frame and scrolls the window; the
+		// hub is opened mid-run, so those copies stacked into a wall of duplicate
+		// "Agent Hub" frames bleeding the task tree behind them. As an editor-slot
+		// component it rides the normal append-only commit path: the transcript
+		// commits above it exactly once and the hub repaints in place.
 		const done = () => {
 			hub?.dispose();
-			overlayHandle?.hide();
+			this.ctx.editorContainer.clear();
+			this.ctx.editorContainer.addChild(this.ctx.editor);
 			this.ctx.ui.setFocus(this.ctx.editor);
 			this.ctx.ui.requestRender();
 		};
@@ -1251,12 +1260,8 @@ export class SelectorController {
 			return;
 		}
 
-		overlayHandle = this.ctx.ui.showOverlay(hub, {
-			anchor: "bottom-center",
-			width: "100%",
-			maxHeight: "100%",
-			margin: 0,
-		});
+		this.ctx.editorContainer.clear();
+		this.ctx.editorContainer.addChild(hub);
 		this.ctx.ui.setFocus(hub);
 		this.ctx.ui.requestRender();
 	}

package/src/modes/controllers/tan-command-controller.ts

@@ -122,6 +122,7 @@ export class TanCommandController {
 							agentId: cloneId,
 							agentDisplayName: "tan",
 							parentTaskPrefix: cloneId,
+							parentAgentId: ownerId,
 							agentRegistry,
 							disableExtensionDiscovery: true,
 						});

package/src/modes/interactive-mode.ts

@@ -151,6 +151,7 @@ import type { ObservableSession } from "./session-observer-registry";
 import { SessionObserverRegistry } from "./session-observer-registry";
 import { runProviderSetupWizard } from "./setup-wizard/lazy";
 import { interruptHint } from "./shared";
+import { clearMermaidCache } from "./theme/mermaid-cache";
 import { type ShimmerPalette, shimmerEnabled, shimmerSegments, shimmerText } from "./theme/shimmer";
 import type { Theme } from "./theme/theme";
 import {
@@ -854,6 +855,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		onThemeChange(() => {
 			this.#clearWorkingMessageAccentCache();
 			clearRenderCache();
+			clearMermaidCache();
 			this.ui.invalidate();
 			this.updateEditorBorderColor();
 			this.ui.requestRender();
@@ -3382,8 +3384,8 @@ export class InteractiveMode implements InteractiveModeContext {
 		return this.#commandController.handleExportCommand(text);
 	}
 
-	handleDumpCommand(isRaw?: boolean) {
-		return this.#commandController.handleDumpCommand(isRaw);
+	handleDumpCommand() {
+		return this.#commandController.handleDumpCommand();
 	}
 
 	handleAdvisorDumpCommand(isRaw?: boolean) {

package/src/modes/setup-wizard/wizard-overlay.ts

@@ -1,4 +1,12 @@
-import { type Component, matchesKey, padding, parseSgrMouse, truncateToWidth, visibleWidth } from "@oh-my-pi/pi-tui";
+import {
+	type Component,
+	matchesKey,
+	type OverlayFocusOwner,
+	padding,
+	parseSgrMouse,
+	truncateToWidth,
+	visibleWidth,
+} from "@oh-my-pi/pi-tui";
 import { APP_NAME } from "@oh-my-pi/pi-utils";
 import { gradientLogo, PI_LOGO } from "../components/welcome";
 import { theme } from "../theme/theme";
@@ -53,7 +61,7 @@ function dissolveFrames(from: string[], to: string[], progress: number, height:
 	return out;
 }
 
-export class SetupWizardComponent implements Component {
+export class SetupWizardComponent implements Component, OverlayFocusOwner {
 	#phase: WizardPhase = "splash";
 	#phaseStartedAt = performance.now();
 	#sceneIndex = 0;
@@ -63,6 +71,7 @@ export class SetupWizardComponent implements Component {
 	#disposed = false;
 	/** Screen row where the active scene's body began in the last rendered frame. */
 	#bodyRowStart = 0;
+	#sceneFocusTarget: Component | undefined;
 
 	constructor(
 		readonly ctx: InteractiveModeContext,
@@ -87,6 +96,11 @@ export class SetupWizardComponent implements Component {
 		this.#activeScene?.invalidate?.();
 	}
 
+	ownsOverlayFocusTarget(component: Component): boolean {
+		if (this.#sceneFocusTarget !== component) return false;
+		return true;
+	}
+
 	handleInput(data: string): void {
 		if (this.#phase === "done") return;
 		if (data.startsWith("\x1b[<")) {
@@ -260,12 +274,19 @@ export class SetupWizardComponent implements Component {
 			ctx: this.ctx,
 			requestRender: () => this.ctx.ui.requestRender(),
 			finish: (_result: SetupSceneResult) => this.#finishScene(),
-			setFocus: component => this.ctx.ui.setFocus(component),
-			restoreFocus: () => this.ctx.ui.setFocus(this),
+			setFocus: component => {
+				this.#sceneFocusTarget = component ?? undefined;
+				this.ctx.ui.setFocus(component);
+			},
+			restoreFocus: () => {
+				this.#sceneFocusTarget = undefined;
+				this.ctx.ui.setFocus(this);
+			},
 		};
 		this.#activeScene = scene.mount(host);
 		this.#phase = targetPhase;
 		this.#phaseStartedAt = performance.now();
+		this.#sceneFocusTarget = undefined;
 		this.ctx.ui.setFocus(this);
 		void this.#activeScene.onMount?.();
 		this.ctx.ui.requestRender();
@@ -288,6 +309,7 @@ export class SetupWizardComponent implements Component {
 	}
 
 	#unmountActiveScene(): void {
+		this.#sceneFocusTarget = undefined;
 		this.#activeScene?.onUnmount?.();
 		this.#activeScene?.dispose?.();
 		this.#activeScene = undefined;

package/src/modes/theme/mermaid-cache.ts

@@ -1,24 +1,87 @@
-import { renderMermaidAsciiSafe } from "@oh-my-pi/pi-utils";
+import { type MermaidAsciiRenderOptions, renderMermaidAsciiSafe } from "@oh-my-pi/pi-utils";
 
+/**
+ * Options controlling how fenced Mermaid source is resolved to terminal ASCII.
+ * Extends the raw render options (theme, color mode, spacing, `useAscii`) with a
+ * viewport-fitting hint.
+ */
+export interface MermaidResolveOptions extends MermaidAsciiRenderOptions {
+	/**
+	 * Maximum display width (terminal columns) the diagram should occupy. A
+	 * layout that overflows this width is re-rendered in the perpendicular
+	 * orientation — a wide horizontal chain collapses to a tall vertical column
+	 * (which the terminal can scroll), and a wide vertical fan-out collapses to a
+	 * tall horizontal column. Omit to keep the source's own layout regardless of
+	 * width.
+	 */
+	maxWidth?: number;
+}
+
+// Memoizes rendered ASCII (and failures) keyed on the render options + the
+// layout-direction variant + source. Width selection happens per call against
+// the cached renders, so a terminal resize re-decides without re-rendering.
 const cache = new Map<string, string | null>();
 
-function normalizeMermaidSource(source: string): string {
-	return source.replace(/\r\n?/g, "\n").trim();
+/** Widest rendered row in display columns (ANSI- and CJK-aware). */
+function asciiDisplayWidth(ascii: string): number {
+	let max = 0;
+	for (const line of ascii.split("\n")) {
+		const width = Bun.stringWidth(line);
+		if (width > max) max = width;
+	}
+	return max;
+}
+
+function renderVariant(
+	source: string,
+	baseOptions: MermaidAsciiRenderOptions,
+	baseKey: string,
+	direction: "TD" | "LR" | null,
+): string | null {
+	const key = `${baseKey}\x00${direction ?? ""}\x00${source}`;
+	const cached = cache.get(key);
+	if (cached !== undefined) return cached;
+
+	const ascii = renderMermaidAsciiSafe(source, direction ? { ...baseOptions, direction } : baseOptions);
+	cache.set(key, ascii);
+	return ascii;
 }
 
 /**
  * Resolve mermaid ASCII from fenced block source text.
  * Returns null when rendering fails, while memoizing failures to avoid repeated work.
  */
-export function resolveMermaidAscii(source: string): string | null {
-	const normalizedSource = normalizeMermaidSource(source);
-	if (cache.has(normalizedSource)) {
-		return cache.get(normalizedSource) ?? null;
-	}
+export function resolveMermaidAscii(source: string, options?: MermaidResolveOptions): string | null {
+	const normalizedSource = source.replace(/\r\n?/g, "\n").trim();
+	if (!normalizedSource) return null;
 
-	const ascii = normalizedSource ? renderMermaidAsciiSafe(normalizedSource) : null;
-	cache.set(normalizedSource, ascii);
-	return ascii;
+	const { maxWidth, ...rest } = options ?? {};
+	// Default to uncolored output; callers opt into a themed palette explicitly.
+	const baseOptions: MermaidAsciiRenderOptions = { colorMode: "none", ...rest };
+	const baseKey = JSON.stringify(baseOptions);
+
+	const base = renderVariant(normalizedSource, baseOptions, baseKey, null);
+	if (base === null) return null;
+	if (maxWidth === undefined) return base;
+
+	let best = base;
+	let bestWidth = asciiDisplayWidth(base);
+	if (bestWidth <= maxWidth) return base;
+
+	// The as-authored layout overflows. Render both forced orientations and keep
+	// the narrowest (clipping at the call site handles any residual overflow).
+	// Re-rendering the already-authored orientation is a cache hit, so this stays
+	// cheap, and one of the two will be the perpendicular fit.
+	for (const direction of ["TD", "LR"] as const) {
+		const variant = renderVariant(normalizedSource, baseOptions, baseKey, direction);
+		if (variant === null) continue;
+		const variantWidth = asciiDisplayWidth(variant);
+		if (variantWidth < bestWidth) {
+			best = variant;
+			bestWidth = variantWidth;
+		}
+	}
+	return best;
 }
 
 /**