@bubblebrain-ai/bubble 0.0.51 → 0.0.53

package/dist/tui/app.js

@@ -0,0 +1,1647 @@
+/**
+ * Bubble production TUI on the vendored pi-tui renderer.
+ *
+ * Owns Bubble's terminal product surface: transcript (user cards, assistant
+ * text, reasoning, tool traces), composer
+ * with native history, queue/steer while running, status footer, blocking
+ * overlays (plan approval, tool approval, questions), model/theme pickers,
+ * task wake notices, and clean terminal lifecycle on exit.
+ *
+ * All runtime logic flows through BubbleTuiController + OverlayRequestController;
+ * this file owns rendering and input routing only.
+ */
+import process from "node:process";
+import { ProcessTerminal, TuiAltScreen, TuiMainScreen, VStack, Editor, Input, ScrollView, Markdown, matchesKey, isKeyRelease, isViewportTUI, } from "@bubblebrain-ai/pi-tui";
+import { StreamingMessageComponent } from "./components/streaming-message.js";
+import { ResponsiveTranscriptComponent } from "./components/responsive-transcript.js";
+import { WelcomeBannerComponent } from "./components/welcome.js";
+import { ApprovalDialogComponent } from "./components/approval-dialog.js";
+import { PlanDialogComponent } from "./components/plan-dialog.js";
+import { FeedbackDialogComponent } from "./components/feedback-dialog.js";
+import { FeishuSetupDialogComponent } from "./components/feishu-setup-dialog.js";
+import { QuestionDialogComponent } from "./components/question-dialog.js";
+import { ProviderKeyInputComponent } from "./components/provider-key-input.js";
+import { RewindPickerComponent, } from "./components/rewind-picker.js";
+import { TaskStatusBarComponent, TasksPaneComponent, } from "./components/tasks-pane.js";
+import { WorkflowInspectorComponent } from "./components/workflow-inspector.js";
+import { SubagentInspectorComponent } from "./components/subagent-inspector.js";
+import { TaskInspectorComponent } from "./components/task-inspector.js";
+import { ContextInfoComponent } from "./components/context-info.js";
+import { StatsPanelComponent } from "./components/stats-panel.js";
+import { SkillsPanelComponent } from "./components/skills-panel.js";
+import { SessionPickerComponent } from "./components/session-picker.js";
+import { ComposerImagePreviewComponent, ImageViewerComponent } from "./components/image-preview.js";
+import { registry as slashRegistry } from "../slash-commands/index.js";
+import { collectUsageStatsBundle } from "../stats/usage.js";
+import { ComposerController, } from "./controller/composer-controller.js";
+import { OverlayRequestController } from "./controller/overlay-controller.js";
+import { createTranscriptTheme, projectTranscript } from "./components/transcript.js";
+import { friendlyCwd, sessionBasename } from "./formatting/summary.js";
+import { formatExternalRuntimeFooterLabel, ResponsiveFooterComponent } from "./footer.js";
+import { ComposerAutocompleteProvider } from "./composer-autocomplete.js";
+import { COMPOSER_EDITOR_OPTIONS, createComposerEditorTheme } from "./composer-style.js";
+import { SessionManager } from "../session.js";
+import { collectFeedback } from "../feedback/collect.js";
+import { TraceInteractionState } from "./model/trace-interaction.js";
+import { parseSkillInvocation } from "../skills/invocation.js";
+import { getNextPermissionMode } from "../permission/mode.js";
+import { maskKey } from "../config.js";
+import { copyToClipboard } from "../clipboard.js";
+import { displayImagesFromPayload, formatImageUserDisplayText, nextImageDisplayLabelStart } from "./image-display.js";
+import { createAssistantMarkdownTheme } from "./markdown-style.js";
+import { resolveThemePalette, } from "./model/theme.js";
+import { themeBackgroundCodes, themeDim, themeForeground } from "./model/theme-style.js";
+import { TuiAnimationClock } from "./animation-clock.js";
+export class PiTuiApp {
+    options;
+    tui;
+    editor;
+    composer;
+    composerPreview;
+    composerSlot = new VStack([]);
+    viewportScroll = null;
+    transcriptBox = new VStack([]);
+    streamingMessage;
+    markdown;
+    markdownRenderer = (text, width) => {
+        this.markdown.setText(text);
+        return this.markdown.render(width);
+    };
+    settledTranscript;
+    welcome;
+    footer;
+    tasksPane;
+    taskStatusBar;
+    animationClock;
+    traceInteraction = new TraceInteractionState();
+    overlays;
+    themeMode;
+    detectedTheme;
+    themeOverrides;
+    theme;
+    transcriptTheme;
+    gitBranch;
+    metadataManager = null;
+    metadataUnsubscribe = null;
+    currentUpdateNotice;
+    updateNoticeRefreshStarted = false;
+    showReasoning = false;
+    verboseTrace = false;
+    controllerUnsubscribe = null;
+    questionUnsubscribe = null;
+    activeQuestion = null;
+    questionQueue = [];
+    providerKeyPhase = null;
+    rewindPhase = null;
+    rewindPreviewMessageIndex;
+    feishuSetupPhase = null;
+    disposed = false;
+    /** Compatibility/debug view backed by the canonical persistent history. */
+    get history() {
+        return this.composer.historyTexts();
+    }
+    constructor(options) {
+        this.options = options;
+        const terminal = options.terminal ?? new ProcessTerminal();
+        this.currentUpdateNotice = options.updateNotice;
+        this.themeMode = options.themeMode ?? "auto";
+        this.detectedTheme = options.detectedTheme
+            ?? (this.themeMode === "auto" ? "dark" : this.themeMode);
+        this.themeOverrides = options.themeOverrides;
+        this.theme = resolveThemePalette(this.themeMode, this.detectedTheme, this.themeOverrides).palette;
+        this.transcriptTheme = createTranscriptTheme(() => this.theme);
+        // Pick the renderer before start(). Entering fullscreen after the regular
+        // renderer has painted necessarily exposes a main-screen frame first.
+        // Constructing TuiAltScreen here makes its 1049h transition the first UI
+        // write and keeps the entire product surface on one application instance.
+        this.tui = (options.uiMode ?? "fullscreen") === "fullscreen"
+            ? new TuiAltScreen(terminal, undefined, undefined, {
+                mouseMotion: "all",
+                screenBackground: () => themeBackgroundCodes(this.theme.background),
+            })
+            : new TuiMainScreen(terminal);
+        this.markdown = new Markdown("", 0, 0, createAssistantMarkdownTheme(() => this.theme));
+        this.streamingMessage = new StreamingMessageComponent(8, () => this.tui.requestRender(), (action) => this.handleTraceAction(action), () => this.theme);
+        this.editor = new Editor(this.tui, createComposerEditorTheme(() => this.theme), COMPOSER_EDITOR_OPTIONS);
+        this.composer = new ComposerController({
+            editor: this.editor,
+            scope: {
+                sessionFile: this.activeSessionManager().getSessionFile(),
+                cwd: process.cwd(),
+            },
+            nextImageLabelStart: nextImageDisplayLabelStart(options.controller.getTranscript()),
+            onSubmit: (payload) => this.handleSubmit(payload),
+            onNotice: (message) => this.pushNotice(message),
+            onStateChange: () => this.renderSnapshot(),
+            onOpenImage: (item) => this.openImageViewer(item),
+            allowImageAttachments: () => !this.activeSessionManager().getMetadata?.().externalRuntime,
+            readClipboardImage: options.readClipboardImage,
+            historyFilePath: options.inputHistoryFilePath,
+            getTheme: () => this.theme,
+            // Injected terminals are isolated hosts and must not mutate the user's
+            // real ~/.bubble history unless they explicitly provide a history file.
+            persistHistory: options.terminal === undefined || options.inputHistoryFilePath !== undefined,
+        });
+        this.composerPreview = new ComposerImagePreviewComponent(() => this.composer.previewAttachment(), () => this.theme);
+        this.editor.setAutocompleteProvider(new ComposerAutocompleteProvider({
+            cwd: process.cwd(),
+            commands: () => slashRegistry.list(),
+            skills: () => this.options.skillRegistry?.summaries() ?? [],
+            uiMode: () => this.tui.mode,
+            registry: this.options.registry,
+            thinkingLevel: () => this.options.agent.thinking,
+            providerId: () => this.options.agent.providerId,
+            themeMode: () => this.themeMode,
+            detectedTheme: () => this.detectedTheme,
+            onModelSuggestionsChanged: () => {
+                if (!this.disposed)
+                    this.editor.refreshAutocomplete();
+            },
+        }));
+        this.settledTranscript = new ResponsiveTranscriptComponent(() => ({
+            messages: this.options.controller.getTranscript(),
+            options: this.transcriptRenderOptions(),
+        }), { onTraceAction: (action) => this.handleTraceAction(action) });
+        this.welcome = new WelcomeBannerComponent(() => {
+            const { agent } = this.options;
+            return {
+                cwd: friendlyCwd(process.cwd()),
+                session: sessionBasename(this.activeSessionManager().getSessionFile()),
+                model: agent.model,
+                provider: agent.providerId,
+                thinking: agent.thinking,
+                updateNotice: this.currentUpdateNotice,
+                theme: this.theme,
+            };
+        });
+        this.footer = new ResponsiveFooterComponent(() => {
+            const extra = [];
+            const steerCount = this.options.controller.pendingSteerCount();
+            const queuedCount = this.options.controller.queuedInputCount();
+            const pendingImages = this.composer.pendingImageCount();
+            if (steerCount)
+                extra.push(themeForeground(this.theme.warning, `steer ×${steerCount}`));
+            if (queuedCount)
+                extra.push(themeForeground(this.theme.warning, `queue ×${queuedCount}`));
+            if (pendingImages)
+                extra.push(themeDim(this.theme.dim, `reading image ×${pendingImages}`));
+            const session = this.activeSessionManager();
+            const metadata = typeof session?.getMetadata === "function" ? session.getMetadata() : undefined;
+            const runtimeLabel = formatExternalRuntimeFooterLabel(metadata?.externalRuntime);
+            return {
+                agent: this.options.agent,
+                cwd: friendlyCwd(process.cwd()),
+                branch: this.gitBranch,
+                sessionTitle: runtimeLabel ? undefined : metadata?.title,
+                runtimeLabel,
+                extra,
+                mode: this.options.agent.mode,
+                goalLine: runtimeLabel ? undefined : this.options.controller.getGoalIndicator?.(),
+                theme: this.theme,
+                // At two rows or fewer, preserve the focused editor body + border.
+                hidden: this.tui.terminal.rows <= 2,
+            };
+        });
+        this.tasksPane = new TasksPaneComponent(() => ({
+            groups: this.options.controller.getSubagentGroups?.() ?? [],
+            workflows: this.options.controller.getWorkflows?.() ?? [],
+            tasks: this.options.controller.getBackgroundTasks?.() ?? [],
+        }), () => this.tui.terminal.rows, {
+            // Pane navigation only changes local presentation state. Reprojecting
+            // the live trace/Markdown here is both unnecessary and expensive.
+            onRender: () => this.tui.requestRender(),
+            onOpenWorkflow: (item) => this.openWorkflowInspector(item),
+            onOpenSubagent: (item) => this.openSubagentInspector(item),
+            onOpenTask: (item) => this.openTaskInspector(item),
+            onStopWorkflow: (id) => this.options.controller.stopWorkflow(id),
+            onStopSubagent: (id) => this.options.controller.stopSubagent(id),
+            onStopTask: (id) => this.options.controller.stopBackgroundTask(id),
+            onCopyTaskOutput: (id) => {
+                const output = this.options.controller.getBackgroundTaskOutput(id);
+                if (!output)
+                    return;
+                void copyToClipboard(output).then(() => this.pushNotice("Copied task output."));
+            },
+            onEscape: () => {
+                this.tasksPane.focused = false;
+                this.tui.setFocus(this.editor);
+                this.tui.requestRender();
+            },
+        }, () => this.theme);
+        this.animationClock = new TuiAnimationClock((elapsedMs) => {
+            const streamingChanged = this.streamingMessage.advanceAnimationFrame(elapsedMs);
+            const tasksChanged = this.tasksPane.advanceAnimationFrame();
+            if (streamingChanged || tasksChanged)
+                this.tui.requestRender();
+        });
+        this.taskStatusBar = new TaskStatusBarComponent(this.tasksPane);
+        this.overlays = new OverlayRequestController({ questionController: options.questionController });
+        this.syncMetadataSubscription();
+        this.installBlockingHandlers();
+        this.buildLayout();
+        this.wireInput();
+        this.renderSnapshot();
+        void options.resolveGitBranch?.(process.cwd()).then((branch) => {
+            if (this.disposed)
+                return;
+            this.gitBranch = branch?.trim() || undefined;
+            this.renderSnapshot();
+        }).catch(() => undefined);
+    }
+    activeSessionManager() {
+        return this.options.controller.getSessionManager?.() ?? this.options.sessionManager;
+    }
+    syncMetadataSubscription() {
+        const manager = this.activeSessionManager();
+        if (manager === this.metadataManager)
+            return;
+        this.metadataUnsubscribe?.();
+        this.metadataManager = manager;
+        this.metadataUnsubscribe = typeof manager?.subscribeMetadata === "function"
+            ? manager.subscribeMetadata(() => this.renderSnapshot())
+            : null;
+    }
+    installBlockingHandlers() {
+        const { planHandlerRef, approvalHandlerRef, questionController } = this.options;
+        if (planHandlerRef) {
+            planHandlerRef.current = async (plan) => {
+                return this.planDialog(plan);
+            };
+        }
+        if (approvalHandlerRef) {
+            approvalHandlerRef.current = async (request) => {
+                const choice = await this.approvalDialog(request);
+                if (choice.kind === "approve_bash_prefix") {
+                    if (request.type !== "bash" || !this.options.bashAllowlist) {
+                        return {
+                            action: "reject",
+                            feedback: "This host cannot remember Bash approvals for the current session.",
+                        };
+                    }
+                    // Session-scoped and command-scoped: PermissionAwareApprovalController
+                    // consults this same instance before opening the next dialog.
+                    this.options.bashAllowlist.add(choice.prefix);
+                    return { action: "approve" };
+                }
+                return choice.kind === "approve_once"
+                    ? { action: "approve" }
+                    : { action: "reject", feedback: "User denied the tool call." };
+            };
+        }
+        if (questionController) {
+            this.questionUnsubscribe = questionController.subscribe((event) => {
+                if (event.type === "asked") {
+                    this.questionQueue.push(event.request);
+                    this.openNextQuestion();
+                    return;
+                }
+                this.removeQueuedQuestion(event.request.id);
+                if (this.activeQuestion?.id === event.request.id) {
+                    this.activeQuestion.close();
+                }
+            });
+        }
+    }
+    buildLayout() {
+        // Keep the live component permanently after the settled transcript. It
+        // renders zero rows while idle. Appending it per turn eventually placed
+        // the same component reference in the tree multiple times and let settled
+        // rows land after it, breaking spacing/order on later turns.
+        this.transcriptBox.addChild(this.settledTranscript);
+        this.transcriptBox.addChild(this.streamingMessage);
+        this.composerSlot.addChild(this.composerPreview);
+        this.composerSlot.addChild(this.editor);
+        if (isViewportTUI(this.tui)) {
+            // Fullscreen owns a bounded viewport. History scrolls while the composer
+            // and footer stay docked. The activity lane is a permanent one-row
+            // boundary: spinner text changes, its geometry never does.
+            const document = new VStack([this.welcome, this.transcriptBox]);
+            const scroll = new ScrollView(document, { follow: "end", primary: true });
+            this.viewportScroll = scroll;
+            this.tui.setLayoutRoot(new VStack([
+                { component: scroll, basis: 0, grow: 1, minSize: 0 },
+                { component: this.taskStatusBar, basis: "auto", shrink: 0 },
+                { component: this.tasksPane, basis: "auto", shrink: 0 },
+                { component: this.streamingMessage.activityLane, basis: "auto", shrink: 0 },
+                { component: this.composerSlot, basis: "auto", shrink: 0 },
+                { component: this.footer, basis: "auto", shrink: 0 },
+            ]));
+        }
+        else {
+            this.tui.addChild(this.welcome);
+            this.tui.addChild(this.transcriptBox);
+            this.tui.addChild(this.taskStatusBar);
+            this.tui.addChild(this.tasksPane);
+            this.tui.addChild(this.streamingMessage.activityLane);
+            this.tui.addChild(this.composerSlot);
+            this.tui.addChild(this.footer);
+        }
+        this.tui.setFocus(this.editor);
+        this.controllerUnsubscribe = this.options.controller.subscribe(() => {
+            this.syncMetadataSubscription();
+            this.composer.setScope({
+                sessionFile: this.activeSessionManager().getSessionFile(),
+                cwd: process.cwd(),
+            }, nextImageDisplayLabelStart(this.options.controller.getTranscript()));
+            this.renderSnapshot();
+        });
+    }
+    wireInput() {
+        let ctrlCArmed = false;
+        let rewindEscapeArmed = false;
+        this.tui.addInputListener((data) => {
+            // Global shortcuts act on key presses only. Kitty keyboard protocol also
+            // reports releases; allowing those through can trigger a shortcut twice.
+            if (isKeyRelease(data))
+                return { consume: true };
+            // Modal dialogs own their complete keyboard contract. In particular,
+            // an approval arrives while a run is active, so letting the global
+            // Escape/Ctrl+C handler run first would cancel the agent and strand the
+            // unresolved permission request instead of rejecting the dialog.
+            if (this.tui.hasOverlay())
+                return undefined;
+            // The inline credential phase owns all of its input. In particular,
+            // Escape returns to /provider instead of cancelling an unrelated run,
+            // and Shift+Tab must not change permissions while a key is being typed.
+            if (this.providerKeyPhase)
+                return undefined;
+            if (this.rewindPhase)
+                return undefined;
+            if (this.editor.focused
+                && (matchesKey(data, "ctrl+v") || matchesKey(data, "super+v"))) {
+                // A terminal can only bracket text that it receives from the clipboard.
+                // Image-only Cmd+V is therefore silent in some terminals; Ctrl+V (and
+                // Kitty's super+v when available) gives the composer an explicit,
+                // terminal-independent signal to probe the native image clipboard.
+                this.composer.requestClipboardImagePaste();
+                return { consume: true };
+            }
+            if (matchesKey(data, "ctrl+g")) {
+                if (this.tasksPane.isOpen() && this.tasksPane.focused) {
+                    this.tasksPane.close();
+                    this.tasksPane.focused = false;
+                    this.tui.setFocus(this.editor);
+                }
+                else {
+                    if (!this.tasksPane.isOpen())
+                        this.tasksPane.toggle(true);
+                    this.tasksPane.focused = true;
+                    this.tui.setFocus(this.tasksPane);
+                }
+                this.renderSnapshot();
+                return { consume: true };
+            }
+            if (matchesKey(data, "ctrl+b") && this.options.controller.isRunning()) {
+                // Current Grok contract: Ctrl+B transfers a live Execute into Tasks;
+                // Ctrl+G remains dedicated to opening and closing the Tasks Pane.
+                this.options.controller.promoteActiveBash?.();
+                return { consume: true };
+            }
+            // A focused Tasks Pane owns Escape. It returns focus to the composer;
+            // it must never fall through and cancel the running parent Agent.
+            if (this.tasksPane.focused && matchesKey(data, "escape"))
+                return undefined;
+            if (matchesKey(data, "shift+tab")) {
+                this.options.agent.setMode(getNextPermissionMode(this.options.agent.mode));
+                this.renderSnapshot();
+                return { consume: true };
+            }
+            if (matchesKey(data, "escape") && this.options.controller.cancelActiveRun()) {
+                // Ink parity: Escape interrupts an active run. When idle, leave the
+                // key unconsumed so the editor/autocomplete layer can handle it.
+                return { consume: true };
+            }
+            if (matchesKey(data, "escape") && this.options.controller.isBusy?.()) {
+                // A second Escape while the provider is acknowledging Compact
+                // cancellation must not arm rewind or leak into the editor.
+                return { consume: true };
+            }
+            if (matchesKey(data, "escape") && !this.options.controller.isRunning() && !this.editor.getText()) {
+                if (rewindEscapeArmed) {
+                    rewindEscapeArmed = false;
+                    this.openRewindPicker();
+                    return { consume: true };
+                }
+                rewindEscapeArmed = true;
+                setTimeout(() => { rewindEscapeArmed = false; }, 650);
+                return undefined;
+            }
+            rewindEscapeArmed = false;
+            if (matchesKey(data, "ctrl+c")) {
+                // Match Ink: the first Ctrl+C interrupts the active run. Requiring a
+                // second keypress here made cancellation feel like a quit gesture and
+                // left the tool trace running behind the composer.
+                if (this.options.controller.cancelActiveRun()) {
+                    ctrlCArmed = false;
+                    return { consume: true };
+                }
+                if (this.options.controller.isBusy?.())
+                    return { consume: true };
+                if (ctrlCArmed) {
+                    this.dispose();
+                    return { consume: true };
+                }
+                ctrlCArmed = true;
+                setTimeout(() => {
+                    ctrlCArmed = false;
+                }, 1_500);
+                return { consume: true };
+            }
+            if (data === "\x14") {
+                this.showReasoning = !this.showReasoning;
+                this.renderSnapshot();
+                return { consume: true };
+            }
+            if (data === "\x0f") {
+                this.verboseTrace = !this.verboseTrace;
+                this.renderSnapshot();
+                return { consume: true };
+            }
+            return undefined;
+        });
+    }
+    handleSubmit(input) {
+        const payload = typeof input === "string"
+            ? { text: input, images: [] }
+            : input;
+        const trimmed = payload.text.trim();
+        if (!trimmed && payload.images.length === 0)
+            return;
+        // Passive output preserves a user's manual history position, but an
+        // explicit Composer submission changes their point of attention to the
+        // new turn. Re-enable follow-end before appending the user row so the same
+        // layout pass that renders it also brings it into view.
+        this.viewportScroll?.scrollToEnd();
+        if (trimmed.startsWith("/")) {
+            void this.handleCommand(trimmed);
+            return;
+        }
+        const controller = this.options.controller;
+        if (controller.isRunning()) {
+            // AgentRunInputQueue is intentionally text-only. Image payloads retain
+            // their bytes by waiting for the next provider turn instead of degrading
+            // into a text steer.
+            if (payload.images.length > 0)
+                controller.queueInput(payload);
+            else
+                controller.steer(trimmed);
+            this.renderSnapshot();
+        }
+        else if (controller.queueAfterCommand?.(payload)) {
+            this.renderSnapshot();
+        }
+        else {
+            this.pushUserRow(payload);
+            const agentInput = payload.images.length > 0 ? payload : trimmed;
+            void controller.runTurn(agentInput, process.cwd()).finally(() => this.renderSnapshot());
+        }
+    }
+    async handleCommand(command) {
+        const [name, ...rest] = command.slice(1).split(/\s+/);
+        const args = rest.join(" ");
+        // pi-tui-local commands first (renderer-specific modes).
+        if (name === "fullscreen") {
+            if (this.fullscreen) {
+                this.exitFullscreen();
+                return;
+            }
+            if (this.tui.mode === "fullscreen") {
+                this.pushNotice("Already in fullscreen mode");
+                this.renderSnapshot();
+                return;
+            }
+            void this.enterFullscreen();
+            return;
+        }
+        const skillInvocation = this.options.skillRegistry
+            ? parseSkillInvocation(command, this.options.skillRegistry)
+            : undefined;
+        if (skillInvocation) {
+            this.pushUserRow({ text: command, images: [] });
+            const controller = this.options.controller;
+            if (controller.isRunning()) {
+                controller.steer(skillInvocation.actualPrompt);
+                this.renderSnapshot();
+            }
+            else {
+                void controller.runTurn(skillInvocation.actualPrompt, process.cwd()).finally(() => this.renderSnapshot());
+            }
+            return;
+        }
+        // Everything else routes through the shared registry (21 builtin
+        // commands + MCP dynamic prompts + skill fallback) — the same surface
+        // the Ink TUI exposed.
+        const compactCommand = name === "compact";
+        let compactSignal;
+        try {
+            if (compactCommand)
+                compactSignal = this.options.controller.beginCommandActivity?.("compact");
+            const ctx = this.buildSlashContext(compactSignal);
+            const outcome = await slashRegistry.execute(`/${name}${args ? ` ${args}` : ""}`, ctx);
+            if (compactCommand) {
+                const text = outcome.result ?? (outcome.handled ? undefined : `Unknown command: /${name}`);
+                const compactionSummary = outcome.detail?.kind === "compaction-summary"
+                    ? outcome.detail.content.trim()
+                    : "";
+                this.options.controller.finishCommandActivity?.("compact", text ? {
+                    key: `compact-${Date.now()}`,
+                    role: text.startsWith("Error:") ? "error" : "assistant",
+                    content: text,
+                    syntheticKind: text.startsWith("Error:")
+                        ? undefined
+                        : compactionSummary
+                            ? "ui_compact_summary"
+                            : "ui_notice",
+                    compactionSummary: compactionSummary || undefined,
+                } : undefined);
+                void this.options.controller.drainQueuedInputs?.(process.cwd());
+                return;
+            }
+            if (outcome.inject) {
+                // Command produced model-facing input (e.g. /rewind restore).
+                void this.handleSubmit(outcome.inject);
+            }
+            else if (outcome.result) {
+                this.pushNotice(outcome.result);
+            }
+            else if (!outcome.handled) {
+                this.pushNotice(`Unknown command: /${name}`);
+            }
+        }
+        catch (error) {
+            const text = error instanceof Error ? error.message : String(error);
+            if (compactCommand && compactSignal) {
+                this.options.controller.finishCommandActivity?.("compact", {
+                    key: `compact-error-${Date.now()}`,
+                    role: "error",
+                    content: text,
+                });
+            }
+            else {
+                this.pushNotice(text);
+            }
+        }
+        finally {
+            if (compactSignal && this.options.controller.getCommandActivity?.()?.kind === "compact") {
+                this.options.controller.finishCommandActivity?.("compact");
+            }
+            this.renderSnapshot();
+        }
+    }
+    buildSlashContext(compactionAbortSignal) {
+        const options = this.options;
+        const agent = options.agent;
+        const addMessage = (role, content) => {
+            options.controller.appendDisplayMessage({
+                key: `cmd-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`,
+                role,
+                content,
+                syntheticKind: role === "assistant" ? "ui_notice" : undefined,
+            });
+        };
+        return {
+            agent,
+            addMessage,
+            clearMessages: () => options.controller.clearTranscript(),
+            cwd: process.cwd(),
+            exit: () => this.dispose(),
+            // Embedded/test hosts created before session switching may only expose
+            // the constructor manager; production controllers provide the live one.
+            sessionManager: (options.controller.getSessionManager?.() ?? options.sessionManager),
+            createProvider: options.createProvider,
+            openPicker: (mode, providerId) => {
+                if (mode === "model" || mode === "provider" || mode === "theme") {
+                    // A bare picker command can still arrive from a fast Enter or a
+                    // non-composer command host. Keep pi-tui on the shared inline
+                    // command surface instead of falling back to a centered overlay.
+                    this.composer.replaceDraft(mode === "model" ? "/model " : mode === "provider" ? "/provider " : "/theme ");
+                    this.editor.refreshAutocomplete();
+                }
+                else if (mode === "key" && providerId) {
+                    this.openProviderKeyPhase(providerId);
+                }
+                else if (mode === "skill") {
+                    this.openSkills();
+                }
+                else if (mode === "feishu-setup") {
+                    this.openFeishuSetup();
+                }
+            },
+            registry: options.registry,
+            skillRegistry: options.skillRegistry,
+            bashAllowlist: options.bashAllowlist,
+            settingsManager: options.settingsManager,
+            hookController: options.hookController,
+            mcpManager: options.mcpManager,
+            lspService: options.lspService,
+            flushMemory: options.flushMemory,
+            runMemoryCompaction: options.runMemoryCompaction,
+            runMemorySummary: options.runMemorySummary,
+            runMemoryRefresh: options.runMemoryRefresh,
+            getThemeMode: () => this.themeMode,
+            getResolvedTheme: () => this.resolvedTheme(),
+            setThemeMode: (mode) => this.applyThemeMode(mode),
+            openFeedback: (initialDescription) => this.openFeedback(initialDescription),
+            openStats: () => this.openStats(),
+            ...(this.tui.mode === "fullscreen"
+                ? { openContextInfo: (snapshot) => this.openContextInfo(snapshot) }
+                : {}),
+            handleGoalCommand: (input) => options.controller.handleGoalCommand(input, process.cwd()),
+            openRewindPicker: () => this.openRewindPicker(),
+            fillComposer: (text) => {
+                this.composer.replaceDraft(text);
+                this.tui.setFocus(this.editor);
+            },
+            rebuildTranscript: () => options.controller.rebuildTranscriptFromAgent(),
+            openSessionPicker: () => this.openSessionPicker(),
+            compactionProgress: () => { },
+            compactionAbortSignal,
+        };
+    }
+    pushUserRow(payload) {
+        this.appendTranscriptRow({
+            key: `user-${Date.now()}`,
+            role: "user",
+            content: formatImageUserDisplayText(payload.displayText ?? payload.text, payload.images.length, payload.imageDisplayStart),
+            images: displayImagesFromPayload(payload),
+        });
+    }
+    resolvedTheme() {
+        return this.themeMode === "auto" ? this.detectedTheme : this.themeMode;
+    }
+    applyThemeMode(mode) {
+        if (this.themeMode === mode) {
+            // Persist an explicit selection even when it resolves to the palette
+            // already on screen (e.g. auto-dark -> forced dark).
+            this.options.callbacks.onThemeModeChange?.(mode);
+            return;
+        }
+        this.themeMode = mode;
+        // Preserve object identity so already-open panels that received this
+        // palette also repaint in place.
+        Object.assign(this.theme, resolveThemePalette(mode, this.detectedTheme, this.themeOverrides).palette);
+        this.options.callbacks.onThemeModeChange?.(mode);
+        this.tui.invalidate();
+        this.renderSnapshot();
+    }
+    pushNotice(text) {
+        this.appendTranscriptRow({
+            key: `notice-${Date.now()}`,
+            role: "assistant",
+            content: text,
+            syntheticKind: "ui_notice",
+        });
+    }
+    appendTranscriptRow(message) {
+        this.options.controller.appendDisplayMessage(message);
+    }
+    streamingMounted = false;
+    /** One display policy feeds both committed history and the live row pool. */
+    transcriptRenderOptions() {
+        return {
+            showReasoning: this.showReasoning,
+            verboseTrace: this.verboseTrace,
+            traceInteraction: this.traceInteraction,
+            dimFromMessageIndex: this.rewindPreviewMessageIndex,
+            theme: this.transcriptTheme,
+            // Stable identity lets the settled transcript cache survive composer-only
+            // frames. The stateful Markdown instance is still updated on cache misses.
+            markdownRenderer: this.markdownRenderer,
+        };
+    }
+    renderSnapshot() {
+        if (this.disposed)
+            return;
+        const columns = this.tui.terminal.columns || process.stdout.columns || 80;
+        this.updateStreamingRegion(columns);
+        this.tui.requestRender();
+    }
+    /**
+     * The streaming preview is a persistent row-pool component mounted as the
+     * transcript's LAST child (upstream AssistantMessageComponent pattern).
+     * Rows are only ever setText — re-creating components per frame is what
+     * leaked every intermediate prefix into scrollback (verified with a
+     * VirtualTerminal matrix). On turn end it collapses to zero rows in the
+     * same frame the settled message commits, so the full answer replaces the
+     * preview with no duplicate.
+     */
+    updateStreamingRegion(columns) {
+        const controller = this.options.controller;
+        const tail = controller.isRunning() ? controller.getStreamingTail() : null;
+        const commandActivity = controller.getCommandActivity?.() ?? null;
+        if (tail) {
+            if (!this.streamingMounted) {
+                this.streamingMounted = true;
+                this.streamingMessage.startSpinner();
+            }
+            this.streamingMessage.noteWidth(columns);
+            this.streamingMessage.update(tail, columns, this.transcriptRenderOptions());
+        }
+        else if (commandActivity) {
+            if (!this.streamingMounted) {
+                this.streamingMounted = true;
+                this.streamingMessage.startSpinner();
+            }
+            this.streamingMessage.noteWidth(columns);
+            this.streamingMessage.updateCommandActivity(commandActivity.kind === "compact" ? "Compacting" : commandActivity.kind, commandActivity.status === "cancelling", columns);
+        }
+        else if (this.streamingMounted) {
+            this.streamingMounted = false;
+            this.streamingMessage.clearToNothing();
+        }
+        this.syncAnimationClock();
+    }
+    syncAnimationClock() {
+        this.animationClock.setActive(this.fullscreen === null
+            && (this.streamingMessage.isAnimationActive() || this.tasksPane.isAnimationActive()));
+    }
+    // ---- Fullscreen mode ----------------------------------------------------
+    fullscreen = null;
+    /**
+     * Switch to the alternate-screen transcript view. The main screen stays
+     * mounted but paused (stopped renderer); both modes subscribe to the same
+     * controller so the transcript stays in sync. Escape / Ctrl+C / /fullscreen
+     * return here.
+     */
+    async enterFullscreen() {
+        if (this.fullscreen)
+            return;
+        this.animationClock.setActive(false);
+        this.tui.stop();
+        const { FullscreenApp } = await import("./fullscreen.js");
+        this.fullscreen = new FullscreenApp({
+            controller: this.options.controller,
+            agent: this.options.agent,
+            onExit: () => this.exitFullscreen(),
+            onCommand: (command) => {
+                // Pickers and dialogs are owned by the main-screen TUI. Return to it
+                // before executing so every slash command uses the same registry and
+                // never leaks into the model as ordinary fullscreen input.
+                this.exitFullscreen();
+                void this.handleCommand(command);
+            },
+            terminal: this.options.terminal,
+            traceInteraction: this.traceInteraction,
+            composer: this.composer,
+            getTheme: () => this.theme,
+        });
+        this.fullscreen.start();
+    }
+    exitFullscreen() {
+        if (!this.fullscreen)
+            return;
+        this.fullscreen.dispose();
+        this.fullscreen = null;
+        this.composer.attachEditor(this.editor);
+        this.composer.setOpenImageHandler((item) => this.openImageViewer(item));
+        this.tui.start();
+        this.renderSnapshot();
+    }
+    // ---- Overlays -----------------------------------------------------------
+    openImageViewer(image) {
+        let handle;
+        const close = () => {
+            handle?.hide();
+            this.tui.setFocus(this.editor);
+            this.renderSnapshot();
+        };
+        const component = new ImageViewerComponent(image, close, () => this.tui.terminal.rows, () => this.theme);
+        handle = this.tui.showOverlay(component, {
+            anchor: "center",
+            width: "70%",
+            minWidth: 36,
+            maxWidth: 110,
+            maxHeight: "85%",
+            margin: { top: 2, right: 1, bottom: 2, left: 1 },
+            dismissOnOutsideClick: true,
+        });
+        this.tui.setFocus(component);
+    }
+    openStats() {
+        let handle;
+        const component = new StatsPanelComponent(collectUsageStatsBundle(), {
+            getTerminalRows: () => this.tui.terminal.rows,
+            onClose: () => handle?.hide(),
+            onRender: () => this.renderSnapshot(),
+            theme: this.theme,
+        });
+        handle = this.tui.showOverlay(component, {
+            anchor: "center",
+            width: "65%",
+            minWidth: 44,
+            maxWidth: 100,
+            maxHeight: 30,
+            margin: { top: 2, right: 0, bottom: 2, left: 0 },
+        });
+        this.tui.setFocus(component);
+    }
+    openSkills() {
+        const skillRegistry = this.options.skillRegistry;
+        if (!skillRegistry) {
+            this.pushNotice("No skill registry is attached to this session.");
+            return;
+        }
+        let handle;
+        const component = new SkillsPanelComponent(skillRegistry, {
+            getTerminalRows: () => this.tui.terminal.rows,
+            onClose: () => handle?.hide(),
+            onRender: () => this.renderSnapshot(),
+            onSkillsChanged: () => {
+                this.options.agent.setSkillSummaries(skillRegistry.summaries());
+                this.editor.refreshAutocomplete();
+                this.renderSnapshot();
+            },
+            theme: this.theme,
+        });
+        handle = this.tui.showOverlay(component, {
+            anchor: "center",
+            width: "65%",
+            minWidth: 40,
+            maxWidth: 160,
+            maxHeight: 34,
+            margin: { top: 3, right: 0, bottom: 3, left: 0 },
+            dismissOnOutsideClick: true,
+        });
+        this.tui.setFocus(component);
+    }
+    openSessionPicker() {
+        if (this.options.controller.isBusy?.()) {
+            this.appendTranscriptRow({
+                key: `session-error-${Date.now()}`,
+                role: "error",
+                content: "Stop the current run before switching sessions.",
+            });
+            return;
+        }
+        const activeFile = this.activeSessionManager().getSessionFile();
+        const currentSessions = SessionManager.summarizeSessionsForCwd(process.cwd());
+        const allSessions = SessionManager.listAllSessions();
+        let handle;
+        const close = () => {
+            handle?.hide();
+            this.tui.setFocus(this.editor);
+            this.renderSnapshot();
+        };
+        const fail = (prefix, error) => {
+            close();
+            this.appendTranscriptRow({
+                key: `session-error-${Date.now()}`,
+                role: "error",
+                content: `${prefix}: ${error || "unknown error"}`,
+            });
+        };
+        const component = new SessionPickerComponent({
+            currentCwd: process.cwd(),
+            currentSessions,
+            allSessions,
+            activeFile,
+            getTerminalRows: () => this.tui.terminal.rows,
+            onClose: close,
+            onNewSession: () => {
+                const outcome = this.options.controller.createFreshSession(process.cwd());
+                if (!outcome.ok) {
+                    fail("Failed to start a new session", outcome.error);
+                    return;
+                }
+                this.composer.setScope({
+                    sessionFile: this.activeSessionManager().getSessionFile(),
+                    cwd: process.cwd(),
+                }, nextImageDisplayLabelStart(this.options.controller.getTranscript()));
+                this.viewportScroll?.scrollToEnd();
+                close();
+            },
+            onSelect: (file) => {
+                if (file === this.activeSessionManager().getSessionFile()) {
+                    close();
+                    return;
+                }
+                const summary = allSessions.find((session) => session.file === file);
+                const displayName = summary?.title || summary?.preview || sessionBasename(file) || "Session";
+                const outcome = this.options.controller.switchSession({
+                    targetFile: file,
+                    notice: `⤷ Resumed session: ${displayName}`,
+                });
+                if (!outcome.ok) {
+                    fail("Failed to switch session", outcome.error);
+                    return;
+                }
+                this.composer.setScope({
+                    sessionFile: this.activeSessionManager().getSessionFile(),
+                    cwd: process.cwd(),
+                }, nextImageDisplayLabelStart(this.options.controller.getTranscript()));
+                this.viewportScroll?.scrollToEnd();
+                close();
+            },
+            onRender: () => this.renderSnapshot(),
+            theme: this.theme,
+        });
+        handle = this.tui.showOverlay(component, {
+            anchor: "center",
+            width: "70%",
+            minWidth: 40,
+            maxWidth: 120,
+            maxHeight: 30,
+            margin: { top: 2, right: 0, bottom: 2, left: 0 },
+            dismissOnOutsideClick: true,
+        });
+        this.tui.setFocus(component);
+    }
+    openContextInfo(snapshot) {
+        let handle;
+        const messages = this.options.agent.messages;
+        const turnCount = messages.filter((message) => message.role === "user").length;
+        const toolCallCount = messages.reduce((count, message) => (count + (message.role === "assistant" ? message.toolCalls?.length ?? 0 : 0)), 0);
+        const compactionCount = this.options.agent.getCompactionStats().fired;
+        const mcpStates = this.options.mcpManager?.getStates?.() ?? [];
+        const sessionId = sessionBasename(this.activeSessionManager().getSessionFile());
+        const component = new ContextInfoComponent({
+            snapshot,
+            sessionId,
+            cwd: friendlyCwd(process.cwd()),
+            thinking: this.options.agent.thinking,
+            permissionMode: this.options.agent.mode,
+            turnCount,
+            toolCallCount,
+            compactionCount,
+            mcpServerCount: mcpStates.length,
+        }, {
+            getTerminalRows: () => this.tui.terminal.rows,
+            onClose: () => handle?.hide(),
+            onRender: () => this.renderSnapshot(),
+            ...(sessionId ? { copySessionId: () => copyToClipboard(sessionId) } : {}),
+            theme: this.theme,
+        });
+        handle = this.tui.showOverlay(component, {
+            anchor: "center",
+            width: "65%",
+            minWidth: 44,
+            maxWidth: 100,
+            maxHeight: 30,
+            margin: { top: 2, right: 0, bottom: 2, left: 0 },
+        });
+        this.tui.setFocus(component);
+    }
+    openProviderKeyPhase(providerId) {
+        const registry = this.options.registry;
+        const provider = registry?.getConfigured().find((candidate) => candidate.id === providerId);
+        if (!registry || !provider) {
+            this.pushNotice(`Provider ${providerId} could not be prepared for API key setup.`);
+            this.renderSnapshot();
+            return;
+        }
+        this.closeProviderKeyPhase(false);
+        const input = new Input({ prompt: "◆ ", mask: "•" });
+        const component = new ProviderKeyInputComponent(input, provider.name, () => this.theme);
+        const phase = { input, component, submitting: false };
+        this.providerKeyPhase = phase;
+        this.composerSlot.removeChild(this.editor);
+        this.composerSlot.addChild(component);
+        input.onEscape = () => this.closeProviderKeyPhase(true);
+        input.onBackspaceAtStart = () => this.closeProviderKeyPhase(true);
+        input.onSubmit = (rawKey) => {
+            const key = rawKey.replace(/[\r\n\t]/g, "").trim();
+            if (!key || phase.submitting || this.providerKeyPhase !== phase)
+                return;
+            phase.submitting = true;
+            this.closeProviderKeyPhase(false);
+            void this.saveProviderKey(providerId, key);
+        };
+        this.tui.setFocus(input);
+        this.renderSnapshot();
+    }
+    closeProviderKeyPhase(returnToProviderPicker) {
+        const phase = this.providerKeyPhase;
+        if (!phase)
+            return;
+        // Erase the component-owned copy before releasing the phase. The caller
+        // may retain the submitted value just long enough to persist it, but UI
+        // state never keeps the raw credential after this point.
+        phase.input.setValue("");
+        phase.input.onSubmit = undefined;
+        phase.input.onEscape = undefined;
+        phase.input.onBackspaceAtStart = undefined;
+        this.composerSlot.removeChild(phase.component);
+        this.composerSlot.addChild(this.editor);
+        this.providerKeyPhase = null;
+        this.composer.replaceDraft(returnToProviderPicker ? "/provider " : "");
+        if (returnToProviderPicker)
+            this.editor.refreshAutocomplete();
+        this.tui.setFocus(this.editor);
+        this.renderSnapshot();
+    }
+    async saveProviderKey(providerId, key) {
+        const registry = this.options.registry;
+        if (!registry)
+            return;
+        try {
+            registry.updateProviderKey(providerId, key);
+            const provider = registry.getConfigured().find((candidate) => candidate.id === providerId);
+            if (!provider)
+                throw new Error("provider disappeared after saving credentials");
+            // Saving credentials configures the provider; it must not partially
+            // mutate the active route. Provider + model + thinking + prompt + session
+            // move together only through the shared /model switch transaction.
+            registry.setDefault(providerId);
+            this.pushNotice(`API key updated for ${provider.name} to ${maskKey(key)}. Use /model to select a compatible model.`);
+        }
+        catch (error) {
+            const message = (error instanceof Error ? error.message : String(error)).replaceAll(key, "[redacted]");
+            this.pushNotice(`Failed to update API key for ${providerId}: ${message}`);
+        }
+        this.renderSnapshot();
+    }
+    openRewindPicker() {
+        if (this.rewindPhase || this.providerKeyPhase || this.disposed)
+            return;
+        const controller = this.options.controller;
+        const points = controller.isRunning() ? [] : this.collectRewindPoints();
+        if (!controller.isRunning() && points.length === 0) {
+            this.pushNotice("Nothing to rewind: no user messages in this session.");
+            this.renderSnapshot();
+            return;
+        }
+        const draft = this.composer.snapshotDraft();
+        const component = new RewindPickerComponent(controller.isRunning() ? "cancel-offer" : "picker", points, {
+            getTerminalRows: () => this.tui.terminal.rows,
+            onPreview: (point, scope) => this.previewRewindPoint(point, scope),
+            onScopeChange: (point, scope) => this.previewRewindPoint(point, scope),
+            onCancel: () => this.closeRewindPicker(true),
+            onCancelRun: () => void this.cancelRunForRewind(component),
+            onConfirm: (point, scope) => void this.executeRewindFromPicker(component, point, scope),
+            onRender: () => this.renderSnapshot(),
+            theme: this.theme,
+        });
+        this.rewindPhase = {
+            component,
+            draft,
+            previousScrollTop: this.viewportScroll?.scrollTop ?? 0,
+        };
+        this.composerSlot.removeChild(this.editor);
+        this.composerSlot.addChild(component);
+        this.tui.setFocus(component);
+        const selected = component.getSelectedPoint();
+        if (selected)
+            this.previewRewindPoint(selected, "all");
+        this.renderSnapshot();
+    }
+    collectRewindPoints() {
+        const session = this.options.controller.getSessionManager();
+        const turns = session.listUserTurns();
+        const checkpoints = session.getCheckpoints();
+        return turns.map((turn, turnIndex) => ({
+            turn,
+            turnIndex,
+            fileCount: checkpoints.filesTouchedAt(turn.id).length,
+        }));
+    }
+    async cancelRunForRewind(component) {
+        if (this.rewindPhase?.component !== component || component.getPhase() !== "cancel-offer")
+            return;
+        component.showLoading();
+        this.options.controller.cancelActiveRun("Cancelled before rewind");
+        await this.waitForControllerIdle();
+        if (this.rewindPhase?.component !== component || this.disposed)
+            return;
+        component.showPicker(this.collectRewindPoints());
+    }
+    waitForControllerIdle() {
+        const controller = this.options.controller;
+        if (!controller.isRunning())
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const unsubscribe = controller.subscribe(() => {
+                if (controller.isRunning())
+                    return;
+                unsubscribe();
+                resolve();
+            });
+            // The run can settle between the first check and subscription.
+            if (!controller.isRunning()) {
+                unsubscribe();
+                resolve();
+            }
+        });
+    }
+    async executeRewindFromPicker(component, point, scope) {
+        if (this.rewindPhase?.component !== component || component.getPhase() === "executing")
+            return;
+        component.showExecuting();
+        try {
+            const result = await this.options.controller.rewindToTurn(point.turn.id, scope);
+            const targetText = result.target.text;
+            // Swap the panel, final composer value, transcript dim, and focus before
+            // requesting the success paint. This prevents an empty-composer frame
+            // between "Rewinding..." and the restored prompt.
+            this.closeRewindPicker(scope === "code", scope === "code" ? undefined : targetText, false);
+            this.viewportScroll?.scrollToEnd();
+            const fileCount = result.files.restored.length + result.files.deleted.length;
+            const failed = result.files.failed.length;
+            if (scope === "code") {
+                this.pushNotice(failed > 0
+                    ? `Files restored with ${failed} failure${failed === 1 ? "" : "s"}.`
+                    : fileCount > 0
+                        ? `Restored ${fileCount} file${fileCount === 1 ? "" : "s"}.`
+                        : "No tracked file edits to undo.");
+            }
+            else {
+                const fileSuffix = scope === "all"
+                    ? failed > 0
+                        ? ` · ${failed} file restore failure${failed === 1 ? "" : "s"}`
+                        : fileCount > 0
+                            ? ` · ${fileCount} file${fileCount === 1 ? "" : "s"} restored`
+                            : " · no tracked file edits"
+                    : "";
+                this.pushNotice(`Reverted conversation${fileSuffix}`);
+            }
+            this.renderSnapshot();
+        }
+        catch (error) {
+            if (this.rewindPhase?.component !== component)
+                return;
+            component.showError(error instanceof Error ? error.message : String(error));
+        }
+    }
+    closeRewindPicker(restoreDraft, replacementText, render = true) {
+        const phase = this.rewindPhase;
+        if (!phase)
+            return;
+        this.composerSlot.removeChild(phase.component);
+        this.composerSlot.addChild(this.editor);
+        this.rewindPhase = null;
+        this.rewindPreviewMessageIndex = undefined;
+        if (restoreDraft)
+            this.composer.restoreDraft(phase.draft);
+        else if (replacementText !== undefined)
+            this.composer.replaceDraft(replacementText);
+        if (restoreDraft) {
+            this.viewportScroll?.scrollTo(phase.previousScrollTop, { disableFollow: true });
+        }
+        this.tui.setFocus(this.editor);
+        if (render)
+            this.renderSnapshot();
+    }
+    previewRewindPoint(point, scope) {
+        if (!point) {
+            this.rewindPreviewMessageIndex = undefined;
+            this.renderSnapshot();
+            return;
+        }
+        const transcript = this.options.controller.getTranscript();
+        const userIndexes = transcript
+            .map((message, index) => message.role === "user" ? index : -1)
+            .filter((index) => index >= 0);
+        const turnCount = this.options.controller.getSessionManager().listUserTurns().length;
+        const relevantUsers = userIndexes.slice(Math.max(0, userIndexes.length - turnCount));
+        const messageIndex = relevantUsers[point.turnIndex];
+        this.rewindPreviewMessageIndex = scope === "code" ? undefined : messageIndex;
+        if (messageIndex !== undefined && this.viewportScroll) {
+            const columns = this.tui.terminal.columns || process.stdout.columns || 80;
+            const rowsBefore = this.welcome.render(columns).length + projectTranscript(transcript.slice(0, messageIndex), { ...this.transcriptRenderOptions(), columns, trailingSpacer: false, dimFromMessageIndex: undefined }).rows.length;
+            const centeredTop = rowsBefore - Math.floor(this.viewportScroll.viewportHeight / 2);
+            this.viewportScroll.scrollTo(centeredTop, { disableFollow: true });
+        }
+        this.renderSnapshot();
+    }
+    planDialog(plan) {
+        return new Promise((resolve) => {
+            const dialog = new PlanDialogComponent(this.tui, plan, () => this.tui.terminal.rows, () => this.theme);
+            const handle = this.tui.showOverlay(dialog, {
+                anchor: "bottom-center",
+                width: "100%",
+                margin: { left: 1, right: 1 },
+            });
+            let settled = false;
+            const finish = (decision) => {
+                if (settled)
+                    return;
+                settled = true;
+                handle.hide();
+                resolve(decision);
+            };
+            dialog.onApprove = (finalPlan) => finish({ action: "approve", plan: finalPlan });
+            dialog.onReject = () => finish({ action: "reject", reason: "User rejected the plan." });
+            this.tui.setFocus(dialog);
+        });
+    }
+    openFeedback(initialDescription) {
+        const collected = collectFeedback(this.options.agent, { description: "" });
+        const { description: _description, ...base } = collected;
+        let handle;
+        const close = () => {
+            handle?.hide();
+            this.tui.setFocus(this.editor);
+            this.renderSnapshot();
+        };
+        const recordResult = (result) => {
+            if (result.kind === "success") {
+                this.pushNotice(`Feedback submitted: ${result.url}`);
+            }
+            else if (result.kind === "error") {
+                this.appendTranscriptRow({
+                    key: `feedback-error-${Date.now()}`,
+                    role: "error",
+                    content: `Feedback failed: ${result.message}`,
+                });
+            }
+        };
+        const dialog = new FeedbackDialogComponent(this.tui, base, initialDescription, {
+            getTerminalRows: () => this.tui.terminal.rows,
+            getTheme: () => this.theme,
+            submit: this.options.submitFeedback,
+            onDismiss: close,
+            onResult: recordResult,
+            onRender: () => this.renderSnapshot(),
+        });
+        handle = this.tui.showOverlay(dialog, {
+            anchor: "bottom-center",
+            width: "100%",
+            margin: { left: 1, right: 1 },
+        });
+        this.tui.setFocus(dialog);
+    }
+    openFeishuSetup() {
+        if (this.feishuSetupPhase)
+            return;
+        let handle;
+        let closed = false;
+        const close = (result) => {
+            if (closed)
+                return;
+            closed = true;
+            handle?.hide();
+            this.feishuSetupPhase = null;
+            this.tui.setFocus(this.editor);
+            if (result.kind === "completed") {
+                this.appendTranscriptRow({
+                    key: `feishu-setup-${Date.now()}`,
+                    role: "assistant",
+                    content: result.summary,
+                    syntheticKind: "ui_notice",
+                });
+            }
+            else if (result.kind === "error") {
+                this.appendTranscriptRow({
+                    key: `feishu-setup-error-${Date.now()}`,
+                    role: "error",
+                    content: `Feishu setup failed: ${result.message}`,
+                });
+            }
+            else {
+                this.pushNotice("已取消 Feishu setup。");
+            }
+            this.renderSnapshot();
+        };
+        const dialog = new FeishuSetupDialogComponent({
+            getTerminalRows: () => this.tui.terminal.rows,
+            getTheme: () => this.theme,
+            onResult: close,
+            onRender: () => this.renderSnapshot(),
+        });
+        handle = this.tui.showOverlay(dialog, {
+            anchor: "bottom-center",
+            width: "100%",
+            margin: { left: 1, right: 1 },
+        });
+        this.feishuSetupPhase = { component: dialog, handle };
+        this.tui.setFocus(dialog);
+        dialog.start();
+    }
+    openWorkflowInspector(item) {
+        let handle;
+        const getSnapshot = () => {
+            const workflow = this.options.controller.getWorkflows().find((candidate) => candidate.runId === item.id);
+            const group = this.options.controller.getSubagentGroups().find((candidate) => (candidate.kind === "workflow" && (candidate.runId === item.id || candidate.id === item.id)));
+            const members = workflow?.snapshots.length
+                ? workflow.snapshots.map((snapshot) => ({
+                    subAgentId: snapshot.agentId,
+                    agentName: snapshot.agentName,
+                    nickname: snapshot.nickname,
+                    status: snapshot.status,
+                    category: snapshot.category,
+                    phase: snapshot.phase,
+                    route: snapshot.route,
+                    task: snapshot.task,
+                    summary: snapshot.summary,
+                    toolNotes: snapshot.toolNotes,
+                    error: snapshot.error,
+                    usage: snapshot.usage,
+                    createdAt: snapshot.createdAt,
+                    updatedAt: snapshot.updatedAt,
+                }))
+                : group?.members ?? item.members;
+            return {
+                id: item.id,
+                title: workflow?.title ?? group?.label ?? item.title,
+                status: workflow?.status ?? item.status,
+                members,
+                createdAt: workflow?.createdAt ?? item.createdAt,
+                updatedAt: workflow?.updatedAt ?? item.updatedAt,
+            };
+        };
+        const component = new WorkflowInspectorComponent({
+            getSnapshot,
+            getTerminalRows: () => this.tui.terminal.rows,
+            theme: this.theme,
+            onClose: () => handle?.hide(),
+            onOpenAgent: (agentId) => {
+                handle?.hide();
+                const member = getSnapshot().members.find((candidate) => candidate.subAgentId === agentId);
+                if (!member)
+                    return;
+                this.openSubagentInspector({
+                    kind: "subagent",
+                    id: agentId,
+                    title: member.nickname ?? member.agentName ?? "subagent",
+                    status: member.status ?? "running",
+                    member,
+                }, () => this.openWorkflowInspector(item));
+            },
+            onStop: (runId) => this.options.controller.stopWorkflow(runId),
+            onRender: () => this.renderSnapshot(),
+        });
+        handle = this.tui.showOverlay(component, {
+            width: "100%",
+            maxHeight: "100%",
+            margin: 1,
+        });
+        this.tui.setFocus(component);
+    }
+    openSubagentInspector(item, onClose) {
+        let handle;
+        const allAgentIds = () => this.options.controller.getSubagentGroups()
+            .flatMap((group) => group.members)
+            .map((member) => member.subAgentId)
+            .filter((id) => !!id);
+        const close = () => {
+            handle?.hide();
+            onClose?.();
+        };
+        const component = new SubagentInspectorComponent({
+            agentId: item.id,
+            controller: this.options.controller,
+            theme: this.theme,
+            getMember: () => this.options.controller.getSubagentGroups()
+                .flatMap((group) => group.members)
+                .find((member) => member.subAgentId === item.id) ?? item.member,
+            getTerminalRows: () => this.tui.terminal.rows,
+            renderOptions: () => this.transcriptRenderOptions(),
+            onClose: close,
+            onNavigate: (direction) => {
+                const ids = allAgentIds();
+                const current = ids.indexOf(item.id);
+                if (current < 0 || ids.length < 2)
+                    return;
+                const nextId = ids[(current + direction + ids.length) % ids.length];
+                const member = this.options.controller.getSubagentGroups().flatMap((group) => group.members).find((candidate) => candidate.subAgentId === nextId);
+                if (!member)
+                    return;
+                handle?.hide();
+                this.openSubagentInspector({
+                    kind: "subagent",
+                    id: nextId,
+                    title: member.nickname ?? member.agentName ?? "subagent",
+                    status: member.status ?? "running",
+                    member,
+                }, onClose);
+            },
+            onRender: () => this.renderSnapshot(),
+        });
+        handle = this.tui.showOverlay(component, {
+            width: "100%",
+            maxHeight: "100%",
+            margin: 1,
+        });
+        this.tui.setFocus(component);
+    }
+    handleTraceAction(action) {
+        if (action.kind === "open-image") {
+            const message = this.options.controller.getTranscript().find((candidate) => candidate.key === action.messageKey);
+            const image = message?.images?.find((candidate) => candidate.label === action.imageLabel);
+            if (image)
+                this.openImageViewer(image);
+            return;
+        }
+        if (action.kind === "open-task") {
+            const task = this.options.controller.getBackgroundTasks()
+                .find((candidate) => candidate.id === action.taskId);
+            if (task) {
+                this.openTaskInspector({
+                    kind: "task",
+                    id: task.id,
+                    title: task.description || task.command,
+                    status: task.status,
+                    task,
+                });
+            }
+            else {
+                const tool = this.options.controller.getTranscript()
+                    .flatMap((message) => message.toolCalls ?? [])
+                    .find((candidate) => candidate.metadata?.taskId === action.taskId
+                    && candidate.metadata?.taskLifecycle !== undefined);
+                if (tool) {
+                    const lifecycle = String(tool.metadata?.taskLifecycle ?? "completed");
+                    const command = String(tool.args.command ?? action.taskId);
+                    const description = typeof tool.args.description === "string" ? tool.args.description : undefined;
+                    const startedAt = tool.startedAt ?? Date.now();
+                    const endedAt = typeof tool.metadata?.endedAt === "number" ? tool.metadata.endedAt : startedAt;
+                    this.openTaskInspector({
+                        kind: "task",
+                        id: action.taskId,
+                        title: description || command,
+                        status: lifecycle,
+                        task: {
+                            kind: "task",
+                            id: action.taskId,
+                            command,
+                            description,
+                            cwd: process.cwd(),
+                            status: lifecycle === "failed" ? "failed" : lifecycle === "killed" ? "killed" : "completed",
+                            exitCode: typeof tool.metadata?.exitCode === "number" ? tool.metadata.exitCode : null,
+                            startedAt,
+                            endedAt,
+                            outputTruncated: false,
+                            outputLines: typeof tool.metadata?.outputLines === "number" ? tool.metadata.outputLines : 0,
+                        },
+                    }, tool.result ?? "");
+                }
+            }
+            return;
+        }
+        if (action.kind !== "open-subagent")
+            return;
+        const member = this.options.controller.getSubagentGroups()
+            .flatMap((group) => group.members)
+            .find((candidate) => candidate.subAgentId === action.subAgentId);
+        if (!member)
+            return;
+        this.openSubagentInspector({
+            kind: "subagent",
+            id: action.subAgentId,
+            title: member.nickname ?? member.agentName ?? "subagent",
+            status: member.status ?? "running",
+            member,
+        });
+    }
+    openTaskInspector(item, fallbackOutput = "") {
+        let handle;
+        const taskOutput = () => this.options.controller.getBackgroundTaskOutput(item.id) || fallbackOutput;
+        const component = new TaskInspectorComponent({
+            id: item.id,
+            title: item.title,
+            getStatus: () => this.options.controller.getBackgroundTasks().find((task) => task.id === item.id)?.status ?? item.status,
+            getOutput: taskOutput,
+            getTerminalRows: () => this.tui.terminal.rows,
+            onClose: () => handle?.hide(),
+            onStop: () => this.options.controller.stopBackgroundTask(item.id),
+            onCopy: () => copyToClipboard(taskOutput()),
+            onRender: () => this.renderSnapshot(),
+            theme: this.theme,
+        });
+        handle = this.tui.showOverlay(component, {
+            width: "100%",
+            maxHeight: "100%",
+            margin: 1,
+        });
+        this.tui.setFocus(component);
+    }
+    approvalDialog(request) {
+        return new Promise((resolve) => {
+            const dialog = new ApprovalDialogComponent(request, () => this.tui.terminal.rows, {
+                allowBashPrefix: this.options.bashAllowlist !== undefined,
+                getTheme: () => this.theme,
+            });
+            const handle = this.tui.showOverlay(dialog, {
+                anchor: "bottom-center",
+                width: "100%",
+                margin: { left: 1, right: 1 },
+            });
+            const finish = (choice) => {
+                handle.hide();
+                resolve(choice);
+            };
+            dialog.onSelect = finish;
+            dialog.onCancel = () => finish({ kind: "reject" });
+            this.tui.setFocus(dialog);
+        });
+    }
+    openNextQuestion() {
+        if (this.disposed || this.activeQuestion)
+            return;
+        const request = this.questionQueue.shift();
+        if (!request)
+            return;
+        const questionController = this.options.questionController;
+        if (!questionController)
+            return;
+        const dialog = new QuestionDialogComponent(request, () => this.tui.terminal.rows, () => this.theme);
+        const handle = this.tui.showOverlay(dialog, {
+            anchor: "bottom-center",
+            width: "100%",
+            margin: { left: 1, right: 1 },
+        });
+        let closed = false;
+        const close = () => {
+            if (closed)
+                return;
+            closed = true;
+            handle.hide();
+            if (this.activeQuestion?.id === request.id)
+                this.activeQuestion = null;
+            this.openNextQuestion();
+        };
+        this.activeQuestion = { id: request.id, close };
+        dialog.onSubmit = (answers) => {
+            close();
+            questionController.reply(request.id, answers);
+        };
+        dialog.onCancel = () => {
+            close();
+            questionController.reject(request.id);
+        };
+        this.tui.setFocus(dialog);
+    }
+    removeQueuedQuestion(id) {
+        const index = this.questionQueue.findIndex((request) => request.id === id);
+        if (index >= 0)
+            this.questionQueue.splice(index, 1);
+    }
+    // ---- Lifecycle ----------------------------------------------------------
+    start() {
+        this.tui.start();
+        this.renderSnapshot();
+        this.watchUpdateNoticeRefresh();
+    }
+    watchUpdateNoticeRefresh() {
+        if (this.updateNoticeRefreshStarted)
+            return;
+        this.updateNoticeRefreshStarted = true;
+        const refresh = this.options.updateNoticeRefresh;
+        if (!refresh)
+            return;
+        void refresh.then((notice) => {
+            if (this.disposed || !notice || notice === this.currentUpdateNotice)
+                return;
+            this.currentUpdateNotice = notice;
+            // The root fullscreen renderer includes the welcome card. The legacy
+            // main-to-fullscreen transition does not, so it needs a transcript row
+            // even before the first user turn.
+            if (this.fullscreen || this.options.controller.getTranscript().length > 0) {
+                this.pushNotice(notice);
+            }
+            else {
+                this.renderSnapshot();
+            }
+        }).catch(() => {
+            // Update checks are best-effort and must never disturb an active session.
+        });
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.controllerUnsubscribe?.();
+        this.controllerUnsubscribe = null;
+        this.metadataUnsubscribe?.();
+        this.metadataUnsubscribe = null;
+        this.metadataManager = null;
+        this.questionUnsubscribe?.();
+        this.questionUnsubscribe = null;
+        this.activeQuestion?.close();
+        this.activeQuestion = null;
+        this.questionQueue.length = 0;
+        this.feishuSetupPhase?.component.dispose();
+        this.feishuSetupPhase?.handle.hide();
+        this.feishuSetupPhase = null;
+        if (this.providerKeyPhase) {
+            this.providerKeyPhase.input.setValue("");
+            this.providerKeyPhase = null;
+        }
+        this.options.questionController?.rejectAll();
+        // Root lifecycle events (notably SIGTERM) can dispose the app while the
+        // alternate screen is still open. Tear it down directly so its controller
+        // listener, spinner timers, and terminal mode cannot outlive the root app.
+        this.fullscreen?.dispose();
+        this.fullscreen = null;
+        this.animationClock.dispose();
+        this.composer.dispose();
+        this.streamingMessage.dispose();
+        this.tasksPane.dispose();
+        this.options.controller.shutdown("user-quit");
+        this.overlays.dispose();
+        this.options.callbacks.onExitRequest();
+        // The fullscreen frame is transient application chrome. Reprinting it
+        // into the restored main buffer leaves the docked composer above the
+        // post-session summary. Exit the alternate screen without exporting that
+        // frame; regular mode keeps its native scrollback behavior unchanged.
+        this.tui.stop({ preserveScreen: this.tui.mode === "fullscreen" });
+    }
+    async waitUntilExit() {
+        await new Promise((resolve) => {
+            const original = this.dispose.bind(this);
+            this.dispose = () => {
+                original();
+                resolve();
+            };
+        });
+    }
+}