@visual-z/xeno 0.2.1 → 0.4.0

package/src/apps/ui/app.ts

@@ -0,0 +1,1553 @@
+/**
+ * The interactive controller (D20): owns one OpenTUI renderer, turns key
+ * events into the same business operations line mode uses (shell.ts), and
+ * re-projects the log into view items after every change.
+ *
+ * Flow of a frame: something changes (a key, a stream delta, a log event)
+ * → `paint()` schedules one projection per tick → items, chrome and sidebar
+ * are pushed to the Screen → OpenTUI diffs cells and writes one frame.
+ * The log stays the only durable state; everything here is UI state that is
+ * either rebuilt from the log (transcript) or deliberately lost on exit
+ * (draft queue that was never sent, scroll position).
+ */
+import { homedir } from "node:os";
+import { basename, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createCliRenderer, resolveImageRenderProtocol, type CliRenderer, type KeyEvent, type PasteEvent, type Selection, type TerminalColors } from "@opentui/core";
+import type { LogEvent } from "../../core/events.ts";
+import { droppedImagePaths } from "../../core/attachment-input.ts";
+import { userInputData, type ImageRef, type UserInput } from "../../core/images.ts";
+import { fileReferences } from "../../core/file-references.ts";
+import { deliveryBatch, type Phase, type QueuedMessage, type QueueKind } from "../../core/queue.ts";
+import { DEFAULT_CONTEXT_POLICY } from "../../core/context-policy.ts";
+import { defaultKeymap } from "../../core/keymap.ts";
+import { pickerRows } from "../../core/model-picker.ts";
+import { modelKey } from "../../core/session-position.ts";
+import { flattenTree, type TreeFilter, type TreeNode } from "../../core/session-tree.ts";
+import { selectSessions, type SessionSort } from "../../core/session-browser.ts";
+import { DISPLAY_SETTINGS, mergeSettings, settingValue, settingValues } from "../../core/settings.ts";
+import { THINKING_LEVELS, asThinkingLevel, supportedThinkingLevels } from "../../core/thinking.ts";
+import { builtinTheme } from "../../core/theme.ts";
+import { projectTranscript, type TranscriptItem } from "../../core/transcript.ts";
+import { lastAssistantText } from "../../core/export.ts";
+import type { PermissionRequest } from "../../core/permissions.ts";
+import type { ApprovalChoice } from "../../runtime/tools.ts";
+import { attachImageBytes, attachImageFile } from "../../runtime/images.ts";
+import { readClipboard, writeClipboard, type ClipboardContent } from "../../runtime/clipboard.ts";
+import { highlightCode, transformMermaid, warmSyntaxLanguages } from "../../runtime/rich-text.ts";
+import { SOURCE_PROVIDERS } from "../../runtime/model-data.ts";
+import { SUBSCRIPTION_OPTIONS, subscriptionById, loginGitHubCopilot, startCallbackServer, XENO_VERSION } from "../../runtime/oauth.ts";
+import { reportedCost } from "../../runtime/usage.ts";
+import { fetchLatestVersion } from "../../runtime/update-check.ts";
+import { installKind, updateNotice, updatePlan } from "../../core/update-check.ts";
+import { isUpgrade } from "../../core/version.ts";
+import { packageLocation, readUpdateCache, writeUpdateCache } from "../../store/update-cache.ts";
+import type { Effort } from "../../runtime/model.ts";
+import { readNode, readCursor, setSessionLabel } from "../../store/log.ts";
+import { readNodeHistory } from "../../store/restore.ts";
+import { currentBranch } from "../../store/git-branch.ts";
+import { projectTrust } from "../../store/trust.ts";
+import { discoverResources, setResourceOverride } from "../../store/resource-index.ts";
+import { nextResourceOverride } from "../../core/resource-selection.ts";
+import { archiveSession, renameSession, scanSessionRoots, sessionRoots } from "../../store/session-browser.ts";
+import { discoverThemes, removeModelThinkingOverride, selectedThemePath, watchTheme, writeUserSettings, loadUiResources } from "../../store/resources.ts";
+import { fuzzyMatch } from "../../tui/fuzzy.ts";
+import type { DialogSpec, ListAction } from "../../tui/ui/dialog.ts";
+import { keyPress, bound, type KeyPress } from "../../tui/ui/keys.ts";
+import type { ListItem } from "../../tui/ui/list-model.ts";
+import { Screen } from "../../tui/ui/screen.ts";
+import type { StatusModel } from "../../tui/ui/status.ts";
+import { terminalTitle } from "../../tui/ui/status.ts";
+import { fileChanges, firstPrompt, handoffStatus, sessionClock } from "./status-model.ts";
+import { ANSI, createStyle } from "../../tui/style.ts";
+import { displayPath } from "../../tui/ui/paths.ts";
+import { approvalHeading, approvalItems, choiceFromValue } from "../approve.ts";
+import { completionAt, completionSources, commandEntries } from "../completions.ts";
+import { commandDefinition } from "../commands.ts";
+import { completionAction } from "../../core/completion-action.ts";
+import { expandInput } from "../input.ts";
+import type { TrustChoice } from "../project-trust.ts";
+import { describeError, firstLine } from "../render.ts";
+import { reloadAppResources } from "../resources.ts";
+import { contextBudget, editInExternalEditor, resolveEditorCommand, type ContextBudget, type interactiveHooks } from "../shell.ts";
+import type { App } from "../startup.ts";
+import { startConnect } from "../provider-connect.ts";
+import { ExtensionHost } from "./extension-host.ts";
+import { paletteItems, type PaletteInput } from "./palette.ts";
+import { imageView, projectItems, type LiveStream, type Notice } from "./project.ts";
+import type { ViewItem } from "../../tui/ui/items.ts";
+import type { OAuthEffects, Ui } from "./surface.ts";
+import { styleTokens, terminalPalette, uiColors } from "./theme.ts";
+import { ImageCache } from "./image-cache.ts";
+import { ImageDraft } from "../image-draft.ts";
+import { sessionControl, type SessionControl, type ControlSnapshot } from "../../runtime/session-control.ts";
+import { controlModel } from "./control-model.ts";
+import { controlPanelLines, type ControlTab, type ControlFocus } from "../../tui/ui/control-panel.ts";
+import { programStatus } from "../../core/program-status.ts";
+import { ProgramStatusReporter } from "../../runtime/program-status.ts";
+import type { PictureSource } from "../../tui/ui/pictures.ts";
+import { DEFAULT_CELL } from "../../tui/ui/image-size.ts";
+import type { TerminalPalette } from "../../tui/ui/ink.ts";
+
+type Hooks = typeof interactiveHooks;
+type Tone = "info" | "success" | "warning" | "error";
+
+const loginEffects: OAuthEffects = { fetch: ((input, init) => globalThis.fetch(input, init)) as typeof globalThis.fetch,
+  openBrowser: url => { try { Bun.spawn([process.platform === "darwin" ? "open" : "xdg-open", url], { stdout: "ignore", stderr: "ignore", stdin: "ignore" }); } catch { /* the URL is shown */ } },
+  callback: startCallbackServer, device: loginGitHubCopilot };
+
+/** Coalesce projections: at most one per frame interval while streaming. Assumed 16ms (60 fps). */
+const PAINT_INTERVAL_MS = 16;
+/** Handoff preview refresh window: about 5 Hz at most, inside the 100–250 ms the research suggests. */
+const DERIVED_DEBOUNCE_MS = 200;
+/** How long to wait for the terminal to report its palette. Ghostty, iTerm2, kitty and WezTerm answer within a few ms; assumed. */
+const PALETTE_TIMEOUT_MS = 500;
+
+function samePalette(a: TerminalPalette, b: TerminalPalette | null): boolean {
+  return b !== null && a.foreground === b.foreground && a.background === b.background && a.slots.every((slot, i) => slot === b.slots[i]);
+}
+
+export class InteractiveApp implements Ui {
+  readonly app: App;
+  readonly screen: Screen;
+  readonly renderer: CliRenderer;
+  private readonly hooks: Hooks;
+  private readonly extensions: ExtensionHost;
+  oauthEffects: OAuthEffects = { ...loginEffects };
+  clipboardWriter: (text: string) => boolean | Promise<boolean> = writeClipboard;
+  clipboardReader: () => Promise<ClipboardContent> = readClipboard;
+  /** Test seam for /provider custom endpoints. */
+  connectFetch: ((input: string, init?: RequestInit) => Promise<Response>) | undefined;
+  sessionName: string | null = null;
+  queue: QueuedMessage[] = [];
+  readonly imageDraft: ImageDraft;
+  get pendingImages(): ImageRef[] { return this.imageDraft.images; }
+  inflight = false;
+  toolsExpanded = false;
+  thinkingExpanded = false;
+  executionKind: "idle" | "model" | "bash" = "idle";
+  private abort: AbortController | null = null;
+  private turn: Promise<void> | null = null;
+  private readonly work = new Set<Promise<void>>();
+  private sessionTransition = false;
+  private transcriptItems: TranscriptItem[] = [];
+  private ancestors: LogEvent[] = [];
+  private historyDir = "";
+  private historyNode = -1;
+  private historyLength = -1;
+  private notices: Notice[] = [];
+  private noticeSerial = 0;
+  private live: { thinking: string; text: string; tools: Map<string, { name: string; arguments: string }>; output: string; bash: string | null; retryUntil: number; retryAttempt: number } = emptyLive();
+  private retryTimer: ReturnType<typeof setInterval> | undefined;
+  private bashDecoder = new TextDecoder();
+  private branch: string | null;
+  private paintTimer: ReturnType<typeof setTimeout> | undefined;
+  /** Handoff-derived status (sidebar / top bar), refreshed single-flight and debounced (DoD 9). */
+  private derived: ReturnType<typeof handoffStatus> | undefined;
+  private control: SessionControl | undefined;
+  private stopControl: (() => void) | undefined;
+  private controlSnapshot: ControlSnapshot | undefined;
+  private readonly program: ProgramStatusReporter | undefined;
+  private readonly stopOsc: (() => void) | undefined;
+  private programResult = false;
+  private derivedKey = "";
+  private derivedTimer: ReturnType<typeof setTimeout> | undefined;
+  private derivedRun: Promise<void> | null = null;
+  private derivedAgain = false;
+  private derivedLast = 0;
+  /** Projected views and transformed Markdown of durable items, reused across paints (refactor-tui-chrome-cleanup DoD 5). */
+  private readonly viewCache = new Map<string, { readonly key: string; readonly view: ViewItem | undefined }>();
+  private readonly textCache = new Map<string, { readonly key: string; readonly text: string }>();
+  private cacheLabel: string | undefined;
+  /** Transcript facts recomputed only when the log changes, not on every paint. */
+  private files: ReturnType<typeof fileChanges> = [];
+  private prompt: string | null = null;
+  private startedAt: string | undefined;
+  private budgetKey = "";
+  private budgetCache: ContextBudget | undefined;
+  /** An extension's own terminal title wins over ours; ours is written only when it changes. */
+  private titleOverride: string | undefined;
+  private writtenTitle = "";
+  private lastInterrupt = 0;
+  private lastEscape = 0;
+  private stopThemeWatch: (() => void) | undefined;
+  private readonly terminalThemeChanged = (mode: string): void => {
+    const name = this.app.ui?.settings.theme;
+    if ((name === "system" || name === "auto") && (mode === "light" || mode === "dark")) this.applyTheme(builtinTheme(mode));
+  };
+  /** Decoded pictures shared by every node that shows them (feat-tui-inline-images). */
+  private readonly images = new ImageCache(() => this.app.blobDir);
+  /** The background update check's request, aborted on close so quitting never waits on the registry. */
+  private readonly updateRequest = new AbortController();
+  /** The terminal finished answering capability queries: picture support may have changed. */
+  private readonly capabilitiesChanged = (): void => this.applyPictures();
+  /** What the terminal reported (OSC 4/10/11); null until it answers, or forever if it never does. */
+  private palette: TerminalPalette | null = null;
+  private readonly paletteChanged = (colors: TerminalColors): void => this.setPalette(terminalPalette(colors));
+  /**
+   * A finished mouse selection is copied, as the terminal's own copy-on-select
+   * would (feat-tui-copy-selection). The selection holds only text nodes, so
+   * borders, glyphs and rules never reach the clipboard. Pi's
+   * `fullscreenCopyOnSelect` turns it off; both TUI modes share this renderer,
+   * so it applies to both (fix-tui-copy-setting).
+   */
+  private readonly selectionFinished = (selection: Selection): void => {
+    if (this.disposed || selection.isDragging || this.app.ui?.settings.fullscreenCopyOnSelect === false) return;
+    const text = selection.getSelectedText();
+    if (text.trim()) this.track(() => this.copyText(text));
+  };
+  private fileIndex: readonly string[] = [];
+  private closedResolve!: () => void;
+  readonly closed: Promise<void>;
+  shutdownRequested = false;
+  /** Set once the renderer is gone; late async work (timers, warmed grammars) must not touch it. */
+  private disposed = false;
+
+  constructor(app: App, hooks: Hooks, renderer: CliRenderer, program?: ProgramStatusReporter) {
+    this.app = app;
+    this.hooks = hooks;
+    this.renderer = renderer;
+    this.program = program;
+    this.stopOsc = program ? renderer.subscribeOsc(sequence => program.receive(sequence)) : undefined;
+    this.closed = new Promise(resolve => { this.closedResolve = resolve; });
+    this.branch = currentBranch(app.workspace);
+    this.sessionName = app.args.sessionName || null;
+    this.thinkingExpanded = app.ui?.settings.hideThinkingBlock === false;
+    this.screen = new Screen(renderer, this.colors(), () => this.keymap().byAction, {
+      codeBlock: (code, language) => highlightCode(code, language, (token, text) => this.app.ui?.style.token?.(token, text) ?? ANSI.token?.(token, text) ?? text),
+    });
+    this.imageDraft = new ImageDraft(this.screen.composer);
+    this.extensions = new ExtensionHost({
+      dialog: spec => this.screen.dialogs.push(spec),
+      closeDialog: spec => this.screen.dialogs.remove(spec),
+      notify: (message, tone) => this.notice(message, tone),
+      redraw: () => this.paint(),
+      theme: () => this.app.ui?.theme ?? builtinTheme("dark"),
+      colored: () => true,
+      editorText: () => this.screen.composer.text,
+      setEditorText: text => this.screen.composer.setText(text),
+      insertEditorText: text => this.screen.composer.insert(text),
+      toolsExpanded: () => this.toolsExpanded,
+      setToolsExpanded: value => { this.toolsExpanded = value; this.paint(); },
+      setTitle: title => { this.titleOverride = title; this.writeTitle(title); },
+      cwd: () => this.app.workspace,
+    });
+    this.screen.dialogs.onError = error => this.notice(describeError(error), "error");
+    this.screen.composer.onChange = () => { this.updateCompletion(); this.paint(); };
+    this.screen.composer.onCursor = () => this.paint();
+    renderer.on("theme_mode", this.terminalThemeChanged);
+    // OpenTUI re-queries the palette after a light/dark switch only while someone listens.
+    renderer.on("palette", this.paletteChanged);
+    renderer.on("selection", this.selectionFinished);
+    renderer.on("capabilities", this.capabilitiesChanged);
+    renderer.keyInput.on("keypress", (event: KeyEvent) => this.onKey(event));
+    renderer.keyInput.on("paste", (event: PasteEvent) => this.onPaste(event));
+    // Chrome depends on width; a resize can also move status into view (bare → topbar / sidebar).
+    renderer.on("resize", () => { this.requestDerived(); this.paint(); });
+    void warmSyntaxLanguages().then(() => this.paint());
+  }
+
+  // ---------------------------------------------------------------- Ui surface
+  get extensionUi() { return this.extensions.context; }
+  get signal(): AbortSignal | undefined { return this.abort?.signal; }
+  get queueLength(): number { return this.queue.length; }
+
+  private keymap() { return this.app.ui?.keymap ?? defaultKeymap(); }
+  private colors() { return uiColors(this.app.ui?.theme ?? builtinTheme("dark"), this.palette); }
+
+  /** Ask the terminal for its palette once; until (or unless) it answers, colours use the dark/light hint. */
+  private async detectPalette(): Promise<void> {
+    try { this.setPalette(terminalPalette(await this.renderer.getPalette({ size: 16, timeout: PALETTE_TIMEOUT_MS }))); }
+    catch { /* no answer: the fallback inks stay */ }
+  }
+  private setPalette(palette: TerminalPalette | null): void {
+    if (this.disposed || !palette || samePalette(palette, this.palette)) return;
+    this.palette = palette;
+    const theme = this.app.ui?.theme;
+    if (this.app.ui && theme) this.app.ui.style = createStyle(styleTokens(theme, palette));
+    this.screen.setColors(this.colors());
+    this.paint();
+  }
+
+  notice(text: string, tone: Tone = "info"): void {
+    const trimmed = text.replace(/^\n+|\n+$/g, "");
+    if (!trimmed.trim()) return;
+    const after = this.transcriptItems.length;
+    const last = this.notices.at(-1);
+    // Consecutive lines from one command read as one block, not a ladder of gaps.
+    if (last && last.after === after && last.item.kind === "lines" && (last as Notice & { tone?: Tone }).tone === tone) {
+      const lines = [...(last as Notice & { lines: string[] }).lines, ...trimmed.split("\n")];
+      this.notices[this.notices.length - 1] = noticeOf(last.id, after, lines, tone);
+    } else this.notices.push(noticeOf(`notice:${this.noticeSerial++}`, after, trimmed.split("\n"), tone));
+    this.paint();
+  }
+  showDocument(title: string, text: string): void {
+    this.screen.dialogs.push({ kind: "lines", title, render: () => text.split("\n") });
+  }
+  toast(text: string, tone: Tone = "info"): void { this.screen.toast(text, tone); }
+  redraw(): void { this.paint(); }
+
+  askSecret(title: string, label: string, hint: string): Promise<string | undefined> {
+    const control = sessionControl(this.app.session); control.setWaiting("auth");
+    return new Promise(resolve => this.screen.dialogs.push({ kind: "form", title, label, secret: true, hint,
+      onSubmit: value => { control.setWaiting(null); resolve(value); },
+      onCancel: () => { control.setWaiting(null); resolve(undefined); } }));
+  }
+  confirm(title: string, message: string): Promise<boolean> {
+    const control = sessionControl(this.app.session); control.setWaiting("question");
+    return new Promise(resolve => this.screen.dialogs.push({ kind: "confirm", title, message, onAnswer: yes => { control.setWaiting(null); resolve(yes); } }));
+  }
+  waiting(title: string, lines: readonly string[], onCancel: () => void, pasteLabel?: string, onPaste?: (value: string) => void): () => void {
+    const control = sessionControl(this.app.session); control.setWaiting("auth");
+    const cancel = () => { control.setWaiting(null); onCancel(); };
+    const spec: DialogSpec = pasteLabel && onPaste
+      ? { kind: "form", title, label: pasteLabel, secret: true, intro: lines, hint: "waiting for the browser · paste the redirect URL + enter · esc cancel", onSubmit: onPaste, onCancel: cancel }
+      : { kind: "busy", title, message: lines.join("\n"), onCancel: cancel };
+    this.screen.dialogs.push(spec);
+    return () => { this.screen.dialogs.remove(spec); control.setWaiting(null); };
+  }
+
+  // ----------------------------------------------------------------- lifecycle
+  async start(): Promise<void> {
+    this.program?.start();
+    this.applyConfiguration();
+    this.followTheme();
+    void this.detectPalette();
+    await this.syncTranscript();
+    await this.hooks.bindExtensions(this.app, this);
+    this.app.askSlot.current = request => this.ask(request);
+    void this.refreshFileIndex();
+    this.requestDerived();
+    this.paint(true);
+    // Never awaited: startup and exit do not wait on the network (feat-update-check DoD 3).
+    void this.checkForUpdate();
+  }
+
+  /**
+   * Say once when a newer xeno is published (docs/tasks/feat-update-check.md).
+   * The cached answer is shown at startup; a due check runs in the background
+   * and is shown now only while the session is still empty, so it never
+   * interrupts work. xeno names the update command and never runs it.
+   */
+  private async checkForUpdate(): Promise<void> {
+    try {
+      const location = packageLocation();
+      const install = installKind(location.root, location.git);
+      const cache = await readUpdateCache();
+      const plan = updatePlan({ current: XENO_VERSION, now: Date.now(), cache, env: process.env, offline: this.app.args.offline === true,
+        enabled: this.app.ui?.settings.updateCheck, install });
+      if (plan.notice && !this.disposed && !this.inflight) this.notice(plan.notice);
+      if (!plan.check) return;
+      const latest = await fetchLatestVersion(process.env["npm_config_registry"], { signal: this.updateRequest.signal });
+      // Quitting cut the request short: that is no answer, so the next start asks again.
+      if (this.disposed) return;
+      // A failed attempt is recorded too, so a closed network is not retried on every start.
+      const known = latest ?? cache?.latest;
+      await writeUpdateCache({ checkedAt: Date.now(), ...(known ? { latest: known } : {}) });
+      if (!plan.notice && latest && isUpgrade(latest, XENO_VERSION) && this.emptySession()) this.notice(updateNotice(latest, XENO_VERSION, install));
+    } catch { /* an update hint is never worth an error */ }
+  }
+
+  private emptySession(): boolean {
+    return !this.disposed && !this.inflight && !this.transcriptItems.some(item => item.kind === "user" || item.kind === "assistant" || item.kind === "tool" || item.kind === "shell");
+  }
+
+  requestShutdown(): void {
+    if (this.shutdownRequested) return;
+    this.shutdownRequested = true;
+    void this.hooks.cancelPendingOAuth(this.app);
+    this.extensions.cancelDialogs();
+    this.screen.dialogs.clear();
+    this.abort?.abort();
+    this.closedResolve();
+  }
+  interrupt(): void {
+    this.abort?.abort();
+    const control = sessionControl(this.app.session);
+    if (control.activeTurnId) control.interrupt(control.activeTurnId);
+    this.returnQueueToEditor();
+  }
+
+  async settle(): Promise<void> {
+    await this.hooks.cancelPendingOAuth(this.app);
+    this.abort?.abort();
+    this.app.session.cancel();
+    await this.turn;
+    await this.app.session.whenIdle();
+    await Promise.all([...this.work]);
+    await this.screen.dialogs.idle();
+    await this.app.extensions?.settle();
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    this.stopControl?.();
+    this.stopOsc?.(); this.program?.close();
+    clearTimeout(this.paintTimer); clearInterval(this.retryTimer); clearTimeout(this.derivedTimer); this.derivedTimer = undefined;
+    this.stopThemeWatch?.();
+    this.renderer.off("theme_mode", this.terminalThemeChanged);
+    this.renderer.off("palette", this.paletteChanged);
+    this.renderer.off("selection", this.selectionFinished);
+    this.renderer.off("capabilities", this.capabilitiesChanged);
+    this.updateRequest.abort();
+    this.images.dispose();
+    this.screen.dispose();
+    delete this.app.askSlot.current;
+  }
+
+  snapshot(): { width: number; height: number; lines: string[] } {
+    const buffer = this.renderer.currentRenderBuffer;
+    const text = new TextDecoder().decode(buffer.getRealCharBytes(true));
+    return { width: this.renderer.width, height: this.renderer.height, lines: text.split("\n") };
+  }
+
+  // --------------------------------------------------------------- transcript
+  async syncTranscript(): Promise<void> {
+    this.bindControl();
+    const session = this.app.session, dir = this.app.logDir, node = session.state.node;
+    if (dir !== this.historyDir || node !== this.historyNode) {
+      const history = await readNodeHistory(dir, node);
+      if (!history.ok) { this.notice(`Cannot load complete session history: ${history.error}`, "error"); return; }
+      if (this.app.session !== session || this.app.logDir !== dir) return;
+      if (this.historyDir !== dir) {
+        // A different session: its notices, queue and draft attachments do not carry over.
+        if (this.historyDir) { this.notices = []; this.queue = []; this.imageDraft.reset(); this.screen.dialogs.clear(); }
+        this.clearStream();
+        this.branch = currentBranch(this.app.workspace);
+        this.sessionName = (await readCursor(dir))?.name ?? this.sessionName;
+        this.thinkingExpanded = this.app.ui?.settings.hideThinkingBlock === false;
+        void this.refreshFileIndex();
+      }
+      this.ancestors = history.nodes.filter(entry => entry.node !== node).flatMap(entry => entry.events);
+      // Another node's history: drop views of items it may not contain.
+      this.clearViewCache();
+      this.historyDir = dir; this.historyNode = node; this.historyLength = -1;
+    }
+    const physical = await readNode(dir, node);
+    if (this.app.session !== session || session.state.node !== node) return;
+    if (physical.corrupt.length > 0) throw new Error("Cannot render corrupt session history");
+    if (this.historyLength !== physical.events.length) {
+      const events = [...this.ancestors, ...physical.events];
+      this.transcriptItems = projectTranscript(events, new Set(this.app.extensions?.entryRenderers.keys()));
+      this.historyLength = physical.events.length;
+      this.files = fileChanges(this.transcriptItems);
+      this.prompt = firstPrompt(this.transcriptItems);
+      this.startedAt = events.find(event => typeof event.at === "string")?.at ?? physical.header?.created_at;
+      this.requestDerived();
+    }
+    this.paint();
+  }
+
+  pushDelta(kind: "text" | "thinking", text: string): void {
+    this.stopRetry();
+    this.screen.markActivity();
+    if (kind === "thinking") this.live.thinking += text; else this.live.text += text;
+    this.paint();
+  }
+  pushProgress(progress: NonNullable<import("../../runtime/loop.ts").LoopEvent["progress"]>): void {
+    this.screen.markActivity();
+    if (progress.kind === "retry") {
+      this.stopRetry();
+      this.live.retryUntil = Date.now() + progress.delayMs;
+      this.live.retryAttempt = progress.attempt;
+      this.retryTimer = setInterval(() => this.paint(), 200);
+    } else {
+      this.stopRetry();
+      if (progress.kind === "tool") this.live.tools.set(progress.id, { name: progress.name, arguments: progress.arguments });
+      else this.live.output = `${this.live.output}${progress.text}`.slice(-64 * 1024);
+    }
+    this.paint();
+  }
+  discardStream(): void { this.clearStream(); this.paint(); }
+  commitStream(): void { this.clearStream(); this.paint(); }
+  beginBash(_command: string): void { this.live.bash = ""; this.bashDecoder = new TextDecoder(); this.paint(); }
+  pushBash(chunk: Uint8Array): void {
+    this.screen.markActivity();
+    this.live.bash = `${this.live.bash ?? ""}${this.bashDecoder.decode(chunk, { stream: true })}`.slice(-64 * 1024);
+    this.paint();
+  }
+
+  private stopRetry(): void { clearInterval(this.retryTimer); this.retryTimer = undefined; this.live.retryUntil = 0; }
+  private clearStream(): void { this.stopRetry(); this.live = emptyLive(); this.extensions.clearPartials(); }
+
+  // ------------------------------------------------------------------ painting
+  /** Schedule one projection; `now` paints synchronously (start, tests). */
+  paint(now = false): void {
+    if (this.disposed) return;
+    if (now) { clearTimeout(this.paintTimer); this.paintTimer = undefined; this.project(); return; }
+    if (this.paintTimer) return;
+    this.paintTimer = setTimeout(() => { this.paintTimer = undefined; this.project(); }, PAINT_INTERVAL_MS);
+  }
+
+  private project(): void {
+    if (this.disposed) return;
+    const app = this.app, spec = app.providerConfig.spec;
+    this.screen.messages.setExpanded(this.toolsExpanded, this.thinkingExpanded);
+    const live = this.liveStream();
+    const mermaid = app.ui?.settings.markdown?.mermaid ?? "streaming";
+    // A changed thinking label changes every thinking view; start the caches over.
+    if (this.extensions.hiddenThinkingLabel !== this.cacheLabel) { this.cacheLabel = this.extensions.hiddenThinkingLabel; this.clearViewCache(); }
+    const width = Math.max(20, this.screen.width - 8);
+    const items = projectItems(this.transcriptItems, {
+      notices: this.notices,
+      style: () => app.ui?.style,
+      ...(live ? { live } : {}),
+      cache: this.viewCache,
+      customTool: item => this.extensions.toolRenderer(item.name, item.input, item.result, item.callId),
+      customMessage: item => this.extensions.messageRenderer(item.customType, item.text, item.data, item.entry),
+      ...(this.extensions.hiddenThinkingLabel !== undefined ? { hiddenThinkingLabel: this.extensions.hiddenThinkingLabel } : {}),
+    }).map(item => {
+      if (item.kind !== "assistant" && item.kind !== "thinking") return item;
+      const streaming = item.streaming === true;
+      // Durable text is transformed once per width; a streaming reply changes on every delta and is not cached.
+      const key = `${item.rev}|${width}|${mermaid}`;
+      const hit = streaming ? undefined : this.textCache.get(item.id);
+      let text: string;
+      if (hit && hit.key === key) text = hit.text;
+      else {
+        text = this.extensions.transformMarkdown(item.text, { streaming, messageType: item.kind === "assistant" ? "assistant" : "assistant-thinking", width });
+        if (item.kind === "assistant" && mermaid !== "off") text = transformMermaid(text, width, mermaid, streaming, (_token, value) => value);
+        if (!streaming) this.textCache.set(item.id, { key, text });
+      }
+      return text === item.text ? item : { ...item, text };
+    });
+    const home = !this.transcriptItems.some(item => item.kind === "user" || item.kind === "assistant" || item.kind === "tool" || item.kind === "shell" || item.kind === "custom") && !this.inflight;
+    const clock = this.startedAt ? sessionClock(this.startedAt, new Date()) : undefined;
+    const view = projectWithStart(items, clock);
+    this.screen.setGreeting(home ? {
+      version: XENO_VERSION, model: app.credential.ok ? spec.name : null, thinking: app.providerConfig.effort,
+      workspace: displayPath(app.workspace, homedir()), branch: this.branch,
+    } : undefined);
+    // Before the first prompt this region is command feedback, not a transcript.
+    // Segment provenance remains in the log and appears when conversation starts.
+    this.screen.setItems(home ? view.filter(item => item.kind !== "segment" || item.id === "session-start") : view);
+    const working = this.extensions.workingMessage ?? (this.executionKind === "bash" ? "running command" : "working");
+    this.screen.setDock({ model: spec.name, thinking: app.providerConfig.effort, busy: this.inflight,
+      activity: this.live.thinking && !this.live.text ? "thinking" : this.live.text ? "streaming" : working });
+    const status = this.statusModel(items);
+    this.screen.setStatus(status);
+    this.writeTitle(this.titleOverride ?? terminalTitle(status));
+    this.screen.setQueue(this.queue.map(item => `${item.kind === "steering" ? "steer" : "next"} · ${firstLine(item.text, 140)}${item.images?.length ? ` · ${item.images.length} image(s)` : ""}`));
+    const focused = !this.screen.dialogs.open && !this.screen.composer.completing ? this.imageDraft.focusedImage : undefined;
+    this.screen.setAttachments(focused ? [imageView(focused.image)] : []);
+    this.screen.setWidgets(this.extensions.widgetLines);
+  }
+
+  private statusModel(items: readonly import("../../tui/ui/items.ts").ViewItem[]): StatusModel {
+    const app = this.app, spec = app.providerConfig.spec, budget = this.budget();
+    const t = app.session.totals, cost = reportedCost(t, spec.price);
+    const tools = items.filter(item => item.kind === "tool");
+    const extension = [this.extensions.status, app.credential.ok ? "" : "no provider · /provider"].filter(Boolean).join(" · ");
+    return {
+      version: XENO_VERSION, title: this.sessionName ?? this.prompt, workspace: displayPath(app.workspace, homedir()),
+      workspaceShort: shortPath(displayPath(app.workspace, homedir())), branch: this.branch,
+      ...(budget ? { context: { used: budget.used, trigger: budget.trigger, estimated: budget.estimated, segment: app.session.state.node, ...(spec.contextWindow ? { window: spec.contextWindow } : {}) } } : {}),
+      ...(t.requests ? { usage: { input: t.prompt_tokens, output: t.output_tokens, cacheRate: t.cache_hit_rate,
+        // Under half a cent reads as $0.00, which says nothing (OpenCode #15903; Grok's status line hides it the same way).
+        cost: cost.kind === "usd" && cost.amount >= 0.005 ? `~$${cost.amount.toFixed(2)}` : cost.kind === "partial" && cost.known >= 0.005 ? `≥$${cost.known.toFixed(2)}` : null } } : {}),
+      tools: { running: tools.filter(tool => tool.status === "pending").length, done: tools.filter(tool => tool.status === "ok").length, failed: tools.filter(tool => tool.status === "error").length },
+      ...(this.derived ?? {}),
+      ...(this.controlSnapshot?.goal ? { goal: { text: this.controlSnapshot.goal.text,
+        status: this.controlSnapshot.goal.state.status,
+        execution: this.inflight ? "running" : this.controlSnapshot.goal.state.execution?.reason ?? "idle",
+        observations: this.controlSnapshot.goal.state.progress.observations.length,
+        retries: this.controlSnapshot.goal.state.progress.unchanged_retries.length } } : {}),
+      files: this.files,
+      resources: { contextFiles: app.loadedContext.agents.map(file => basename(file.path)), skills: app.slash?.skills.size ?? 0, extensions: app.extensions?.loaded.length ?? 0 },
+      ...(extension ? { extension } : {}),
+    };
+  }
+
+  private writeTitle(title: string): void {
+    if (title === this.writtenTitle || this.disposed) return;
+    this.writtenTitle = title;
+    this.renderer.setTerminalTitle(title);
+  }
+
+  private liveStream(): LiveStream | undefined {
+    const l = this.live;
+    if (!l.thinking && !l.text && !l.tools.size && !l.output && l.bash === null && !l.retryUntil) return undefined;
+    return { thinking: l.thinking, text: l.text, tools: [...l.tools].map(([id, tool]) => ({ id, ...tool })), output: l.output, bash: l.bash,
+      ...(l.retryUntil ? { retry: `retry ${l.retryAttempt} in ${Math.max(0, (l.retryUntil - Date.now()) / 1000).toFixed(1)}s · esc to cancel` } : {}) };
+  }
+
+  /** The context budget changes only with the log or the model; it is not recounted on every paint. */
+  private budget(): ContextBudget | undefined {
+    const s = this.app.session, spec = s.provider.config.spec;
+    const key = `${this.app.logDir}:${s.state.node}:${s.state.events.length}:${spec.provider}/${spec.id}:${s.config.contextPolicy ?? DEFAULT_CONTEXT_POLICY}`;
+    if (key === this.budgetKey) return this.budgetCache;
+    this.budgetKey = key;
+    try {
+      this.budgetCache = contextBudget({ ...s.contextInput(), anchor: s.state.anchor, policy: s.config.contextPolicy ?? DEFAULT_CONTEXT_POLICY,
+        contextWindow: spec.contextWindow, outputReserve: s.provider.config.maxTokens,
+        ...(s.config.counter ? { counter: s.config.counter } : {}), ...(s.config.boundary ? { boundary: s.config.boundary } : {}) });
+    } catch { this.budgetCache = undefined; }
+    return this.budgetCache;
+  }
+
+  /**
+   * The handoff preview replays the whole log, so it is refreshed at most once
+   * per debounce window, one run at a time, and only while a surface shows it.
+   */
+  private requestDerived(): void {
+    if (this.disposed || this.screen.tier === "bare") return;
+    if (this.derivedKey === this.derivedTarget()) return;
+    if (this.derivedRun || this.derivedTimer) { this.derivedAgain = true; return; }
+    // Throttle, not a pure debounce: the first change after a quiet spell refreshes at once,
+    // and a burst collapses into one trailing refresh.
+    const wait = Math.max(0, this.derivedLast + DERIVED_DEBOUNCE_MS - Date.now());
+    if (wait === 0) { this.track(() => this.refreshDerived()); return; }
+    this.derivedTimer = setTimeout(() => { this.derivedTimer = undefined; this.track(() => this.refreshDerived()); }, wait);
+  }
+  private derivedTarget(): string { return `${this.app.logDir}:${this.app.session.state.node}:${this.historyLength}`; }
+  private async refreshDerived(): Promise<void> {
+    this.derivedLast = Date.now();
+    const target = this.derivedTarget();
+    this.derivedRun = (async () => {
+      try {
+        const session = this.app.session;
+        const derived = handoffStatus(await session.previewHandoff());
+        const snapshot = await sessionControl(session).snapshot(false);
+        if (this.app.session !== session) return;
+        this.derived = derived; this.controlSnapshot = snapshot; this.derivedKey = target;
+        // Idle acceptance changes have no model delta. Reconcile terminal attention
+        // with the same evidence projection that refreshes the visible goal.
+        if (!this.inflight) this.program?.update(programStatus({ running: false, waiting: snapshot.waiting,
+          ...(snapshot.goal?.state.execution ? { outcome: snapshot.goal.state.execution } : {}),
+          ...(snapshot.goal ? { goal: snapshot.goal.state.status } : {}) }));
+        if (this.screen.dialogs.top?.title === "Control panel") this.screen.dialogs.refresh();
+      }
+      catch {
+        // Unavailable evidence cannot leave a stale verified goal visible.
+        this.controlSnapshot = undefined;
+        if (this.screen.dialogs.top?.title === "Control panel") this.screen.dialogs.refresh();
+      }
+    })();
+    await this.derivedRun;
+    this.derivedRun = null;
+    if (this.derivedAgain) { this.derivedAgain = false; this.requestDerived(); }
+    this.paint();
+  }
+
+  /** Timers this controller holds right now; none while idle (DoD 9). */
+  get timers(): number { return this.screen.timers + (this.paintTimer ? 1 : 0) + (this.retryTimer ? 1 : 0) + (this.derivedTimer ? 1 : 0); }
+
+  // ------------------------------------------------------------------- input
+  private onPaste(event: PasteEvent): void {
+    const text = new TextDecoder().decode(event.bytes);
+    if (this.screen.dialogs.open) { if (this.screen.dialogs.paste(text)) return; event.preventDefault(); return; }
+    const paths = droppedImagePaths(text);
+    if (paths) { event.preventDefault(); this.track(() => this.pasteClipboard({ files: paths })); }
+  }
+
+  private onKey(event: KeyEvent): void {
+    const key = keyPress(event);
+    if (this.handleKey(key)) event.preventDefault();
+  }
+
+  /** True when the key was handled and must not reach the focused textarea. Public for tests. */
+  handleKey(key: KeyPress): boolean {
+    const b = this.keymap().byAction;
+    if (bound(b, "app.exit", key) && !this.screen.dialogs.open && !this.screen.composer.text && !this.pendingImages.length) { this.requestShutdown(); return true; }
+    if (bound(b, "app.suspend", key)) { this.suspend(); return true; }
+    if (this.screen.dialogs.open) return this.screen.dialogs.key(key);
+    const composer = this.screen.composer;
+    if (composer.completing) {
+      if (key.chord === "up") { composer.moveCompletion(-1); return true; }
+      if (key.chord === "down") { composer.moveCompletion(1); return true; }
+      if (key.chord === "escape") { composer.setCompletion(undefined); return true; }
+      if (key.chord === "tab" || key.chord === "enter") {
+        const kind = composer.completionView!.kind;
+        const item = composer.acceptCompletion();
+        if (item) {
+          const definition = commandDefinition(composer.text);
+          const required = !!definition && "argumentHint" in definition && definition.argumentHint.startsWith("<");
+          if (completionAction(kind, key.chord, required) === "submit") {
+            const text = composer.text;
+            this.track(() => this.submit(text, "steering"));
+          } else { this.updateCompletion(); this.paint(); }
+        }
+        return true;
+      }
+    }
+    if (bound(b, "app.palette", key)) { this.openPalette(); return true; }
+    if (bound(b, "app.clear", key)) {
+      if (this.inflight) this.interrupt();
+      else if (composer.text || this.pendingImages.length) { composer.setText(""); }
+      else if (Date.now() - this.lastInterrupt < 1000) { this.requestShutdown(); return true; }
+      else this.toast("press ctrl+c again to quit");
+      this.lastInterrupt = Date.now(); this.paint(); return true;
+    }
+    if (bound(b, "app.interrupt", key)) {
+      if (this.inflight) this.interrupt();
+      else if (!this.screen.messages.atBottom) this.screen.messages.scrollToBottom();
+      else if (!composer.text && Date.now() - this.lastEscape < 500) {
+        const action = this.app.ui?.settings.doubleEscapeAction ?? "tree";
+        if (action === "tree") this.track(() => this.openTree()); else if (action === "fork") this.track(() => this.openFork());
+      }
+      this.lastEscape = Date.now(); this.paint(); return true;
+    }
+    if (bound(b, "app.toggleTools", key)) { this.toolsExpanded = !this.toolsExpanded; this.paint(); return true; }
+    if (bound(b, "app.toggleThinking", key)) { this.track(() => this.hooks.commitSetting(this.app, "hideThinkingBlock", this.thinkingExpanded ? "on" : "off", this)); return true; }
+    if (bound(b, "app.toggleSidebar", key)) { this.screen.toggleSidebar(); return true; }
+    if (bound(b, "app.scroll.pageUp", key)) { this.screen.messages.page(-1); return true; }
+    if (bound(b, "app.scroll.pageDown", key)) { this.screen.messages.page(1); return true; }
+    if (bound(b, "app.scroll.bottom", key)) { this.screen.messages.scrollToBottom(); return true; }
+    if (bound(b, "app.scroll.top", key)) { this.screen.messages.scrollToTop(); return true; }
+    if (bound(b, "app.externalEditor", key)) { this.track(() => this.externalEditor()); return true; }
+    if (bound(b, "app.clipboard.pasteImage", key)) { this.track(() => this.pasteClipboard()); return true; }
+    if (bound(b, "app.message.copy", key)) { this.track(() => this.copySelectionOrReply()); return true; }
+    if (bound(b, "app.message.dequeue", key)) { this.returnQueueToEditor(); this.paint(); return true; }
+    if (!this.inflight) {
+      if (bound(b, "app.model", key)) { this.openModel(); return true; }
+      if (bound(b, "app.cycleModel", key) || bound(b, "app.cycleModelReverse", key)) { this.track(async () => { await this.hooks.cycleScopedModel(this.app, bound(b, "app.cycleModel", key) ? 1 : -1); this.paint(); }); return true; }
+      if (bound(b, "app.cycleThinking", key)) { this.track(() => this.hooks.cycleThinking(this.app, this)); return true; }
+      for (const [action, run] of [["app.session.new", () => this.hooks.openNewSession(this.app, this)], ["app.session.tree", () => this.openTree()],
+        ["app.session.fork", () => this.openFork()], ["app.session.resume", () => this.openResume()]] as const)
+        if (bound(b, action, key)) { this.track(run); return true; }
+    }
+    if (bound(b, "app.message.followUp", key)) { const text = composer.text; this.track(() => this.submit(text, "followup")); return true; }
+    if (bound(b, "editor.newLine", key)) { composer.insert("\n"); return true; }
+    if (bound(b, "editor.submit", key)) { const text = composer.text; this.track(() => this.submit(text, "steering")); return true; }
+    if (bound(b, "editor.historyPrevious", key)) return composer.historyStep(-1);
+    if (bound(b, "editor.historyNext", key)) return composer.historyStep(1);
+    for (const [chord, shortcut] of this.app.extensions?.shortcuts ?? []) if (chord === key.chord) {
+      this.runExtensionAction(() => shortcut.handler(this.hooks.extensionContext(this.app, this))); return true;
+    }
+    return false;
+  }
+
+  /** Track async work started by a key so settle() and tests can await it. */
+  private track(action: () => unknown): void {
+    const job = Promise.resolve().then(action).then(() => undefined, (error: unknown) => this.notice(describeError(error), "error"))
+      .finally(() => { this.work.delete(job); this.paint(); });
+    this.work.add(job);
+  }
+  /**
+   * Everything a key started has finished, or is waiting for the user to
+   * answer an open dialog (that work cannot finish without them). A running
+   * turn is not waited for; see whenIdle.
+   */
+  async idle(): Promise<void> {
+    for (let round = 0; round < 400; round++) {
+      // A pending status refresh is started work too (it becomes tracked once its window opens).
+      if (!this.work.size && !this.screen.dialogs.busy && !this.derivedTimer) return;
+      if (this.screen.dialogs.open && !this.screen.dialogs.busy && this.work.size) {
+        // Give started work a moment to reach its dialog; then it is the user's turn.
+        await new Promise(resolve => setTimeout(resolve, 5));
+        if (this.screen.dialogs.open && !this.screen.dialogs.busy) return;
+      }
+      // With only the status timer pending there is nothing to await yet; wait for its window to open.
+      await Promise.race([Promise.all([...this.work, this.screen.dialogs.idle(), ...(this.work.size ? [] : [new Promise(resolve => setTimeout(resolve, 5))])]), new Promise(resolve => setTimeout(resolve, 5))]);
+    }
+  }
+  /** The running turn and everything it queued have finished, without interrupting anything. */
+  async whenIdle(): Promise<void> {
+    for (let round = 0; round < 50; round++) {
+      const turn = this.turn, work = this.work.size;
+      await turn; await this.control?.whenIdle().catch(() => {}); await this.idle(); await this.app.session.whenIdle(); await this.app.extensions?.settle();
+      if (turn === this.turn && !this.inflight && work === this.work.size && !this.work.size) return;
+    }
+  }
+
+  private updateCompletion(): void {
+    const composer = this.screen.composer;
+    if (this.screen.dialogs.open) { composer.setCompletion(undefined); return; }
+    const text = composer.text;
+    const cursor = composer.area.cursorOffset;
+    composer.setCompletion(completionAt(text, cursor, completionSources(this.app, this.fileIndex)));
+    if (text.includes("@") && !this.fileIndex.length) void this.refreshFileIndex();
+  }
+  private async refreshFileIndex(): Promise<void> {
+    try { this.fileIndex = (await this.hooks.fileIndexFor(this.app)).paths; } catch { /* completion only */ }
+  }
+
+  // ------------------------------------------------------------------ submit
+  private async submit(text: string, kind: QueueKind): Promise<void> {
+    const input = this.imageDraft.input(text);
+    const line = input.text.trim();
+    const composer = this.screen.composer;
+    if (this.sessionTransition) { this.toast("wait for the session import to finish", "warning"); return; }
+    if (!line && !input.images.length) return;
+    composer.remember(text);
+    composer.setText("");
+    composer.setCompletion(undefined);
+    this.screen.messages.scrollToBottom();
+    const command = this.hooks.parseLine(this.app, line);
+    if (command.kind === "prompt" && command.skill && this.inflight) { this.notice("This skill needs an idle session. Press Esc to interrupt the current turn first.", "warning"); composer.setText(text); return; }
+    if (command.kind !== "prompt") {
+      if (this.inflight && commandDefinition(line)?.busy === "idle") { this.notice("This command needs an idle session. Press Esc to interrupt the current turn first.", "warning"); composer.setText(text); return; }
+      this.imageDraft.insertImages(input.images);
+      const result = await this.hooks.handleLine(this.app, line, this);
+      await this.syncTranscript();
+      if (result === "quit") this.requestShutdown();
+      return;
+    }
+    const shell = command.text.startsWith("!");
+    const images = shell ? [] : input.images;
+    if (shell) this.imageDraft.insertImages(input.images);
+    if (this.inflight) { this.queue.push({ kind: shell ? "followup" : kind, text: command.text, ...(images.length ? { images } : {}) }); this.paint(); return; }
+    this.turn = this.runPromptTurn(command.text, images, command.skill).catch(error => this.notice(describeError(error), "error"));
+    this.paint();
+  }
+
+  private async runPromptTurn(text: string, images: readonly ImageRef[] = [], skill?: import("../../core/skills.ts").Skill): Promise<void> {
+    this.abort = new AbortController();
+    this.inflight = true;
+    this.programResult = false;
+    this.program?.update(programStatus({ running: true }));
+    this.executionKind = text.startsWith("!") ? "bash" : "model";
+    this.paint();
+    try {
+      const sent = await this.hooks.run(this.app, text, this.abort.signal, this, images, skill);
+      if (!sent && !this.app.credential.ok) {
+        this.programResult = true; this.program?.update(programStatus({ running: false, waiting: "auth" }));
+      }
+      if (sent && !this.abort.signal.aborted) await this.drainFollowUps();
+    } catch (error) {
+      this.programResult = true;
+      this.program?.update({ state: "error", msg: "Turn failed; inspect the session" });
+      throw error;
+    } finally {
+      if (!this.programResult) this.program?.update(programStatus({ running: false }));
+      await this.syncTranscript();
+      this.abort = null;
+      this.hooks.dropFileIndex(this.app.workspace);
+      this.inflight = false;
+      this.executionKind = "idle";
+      this.branch = currentBranch(this.app.workspace);
+      this.clearStream();
+      this.requestDerived();
+      this.paint();
+    }
+  }
+
+  /** send() calls this at after_tools. Files named in a queued line are read now, not when it was typed. */
+  async pullQueued(phase: Phase): Promise<UserInput | null> {
+    const batch = this.nextBatch(phase);
+    if (!batch.length) return null;
+    const expanded = await Promise.all(batch.map(item => this.expandQueued(item)));
+    this.queue = this.queue.filter(item => !batch.includes(item));
+    this.paint();
+    const present = expanded.filter((input): input is UserInput => input !== null).map(input => userInputData(input));
+    const text = present.map(input => input.text).join("\n\n"), images = present.flatMap(input => input.images ?? []);
+    return images.length ? { text, images } : text || null;
+  }
+  private async expandQueued(item: QueuedMessage): Promise<UserInput | null> {
+    const index = fileReferences(item.text).length > 0 ? await this.hooks.fileIndexFor(this.app) : { paths: [], truncated: false };
+    const expanded = await expandInput(item.text, { workspace: this.app.workspace, index, say: line => this.notice(line),
+      attachImage: path => attachImageFile(path, this.app.blobDir, this.app.ui?.settings.images?.autoResize ?? true) });
+    const images = [...item.images ?? [], ...expanded.images ?? []];
+    return images.length ? { text: expanded.message, images } : expanded.send ? expanded.message : null;
+  }
+  private async drainFollowUps(): Promise<void> {
+    while (this.abort !== null && !this.abort.signal.aborted) {
+      const batch = this.nextBatch("turn_end");
+      if (!batch.length) break;
+      this.queue = this.queue.filter(item => !batch.includes(item));
+      this.paint();
+      if (!await this.hooks.run(this.app, batch.map(item => item.text).join("\n\n"), this.abort.signal, this, batch.flatMap(item => item.images ?? []))) break;
+    }
+  }
+  private nextBatch(phase: Phase): readonly QueuedMessage[] {
+    const settings = this.app.ui?.settings;
+    return deliveryBatch(this.queue, phase, { steering: settings?.steeringMode ?? "one-at-a-time", followup: settings?.followUpMode ?? "one-at-a-time" });
+  }
+  private returnQueueToEditor(): void {
+    if (!this.queue.length) return;
+    for (const item of [...this.queue].reverse()) this.restoreDraft(item.text, item.images ?? []);
+    this.queue = [];
+  }
+  restoreDraft(text: string, images: readonly ImageRef[] = []): void {
+    const composer = this.screen.composer, current = composer.text;
+    composer.setText(text); this.imageDraft.insertImages(images);
+    composer.setText([composer.text, current].filter(Boolean).join("\n"));
+    this.paint();
+  }
+
+  // --------------------------------------------------------------- clipboard
+  async pasteClipboard(content?: ClipboardContent): Promise<void> {
+    const composer = this.screen.composer, revision = composer.revision, text = composer.text, cursor = composer.cursor;
+    const session = this.app.session, blobDir = this.app.blobDir;
+    const current = () => !this.disposed && !this.screen.dialogs.open && this.app.session === session &&
+      this.app.blobDir === blobDir && composer.revision === revision && composer.text === text && composer.cursor === cursor;
+    if (!current()) return;
+    try {
+      const value = content === undefined ? await this.clipboardReader() : content;
+      if (!value || !current()) return;
+      if ("files" in value) {
+        const text: string[] = [], images: ImageRef[] = [];
+        for (const path of value.files) {
+          if (/[\x00-\x1f]/.test(path)) throw new Error("Clipboard file path contains control characters");
+          const absolute = path.startsWith("file://") ? fileURLToPath(path) : resolve(this.app.workspace, path);
+          const image = await attachImageFile(absolute, blobDir, this.app.ui?.settings.images?.autoResize ?? true);
+          if (image) images.push(image); else text.push("@" + JSON.stringify(path));
+        }
+        if (!current()) return;
+        this.imageDraft.insertImages(images);
+        if (text.length) this.screen.composer.insert(text.join(" "));
+      } else if ("image" in value) {
+        const image = await attachImageBytes(value.image, "clipboard.png", blobDir, this.app.ui?.settings.images?.autoResize ?? true);
+        if (current()) this.imageDraft.insertImages([image]);
+      }
+      else this.screen.composer.insert(value.text);
+    } catch (error) { this.notice(`Paste failed: ${describeError(error)}`, "error"); }
+    this.paint();
+  }
+  private async copySelectionOrReply(): Promise<void> {
+    const selected = this.renderer.getSelection()?.getSelectedText();
+    if (selected?.trim()) { await this.copyText(selected); return; }
+    const reply = lastAssistantText(this.app.session.state.events);
+    if (!reply) { this.toast("nothing to copy yet"); return; }
+    await this.copyText(reply, "the last reply");
+  }
+
+  /**
+   * Local sessions write through the platform clipboard first and fall back
+   * to OSC 52; over SSH the platform clipboard is the remote host's, so OSC 52
+   * (the terminal's own clipboard) goes first (feat-tui-copy-selection DoD 3).
+   */
+  private async copyText(text: string, what?: string): Promise<void> {
+    const remote = Boolean(process.env["SSH_CONNECTION"] || process.env["SSH_TTY"]);
+    const osc52 = () => { try { return this.renderer.copyToClipboardOSC52(text); } catch { return false; } };
+    let ok = remote && osc52();
+    if (!ok) ok = await this.clipboardWriter(text);
+    if (!ok && !remote) ok = osc52();
+    this.toast(ok ? `copied ${what ?? `${[...text].length} chars`}` : "clipboard unavailable", ok ? "success" : "warning");
+  }
+
+  private async externalEditor(): Promise<void> {
+    this.renderer.suspend();
+    try {
+      const result = await editInExternalEditor({ content: this.screen.composer.text, command: this.app.ui?.settings.externalEditor ?? resolveEditorCommand() });
+      if (result.ok) this.screen.composer.setText(result.content); else this.notice(result.message, "warning");
+    } finally { this.renderer.resume(); this.paint(); }
+  }
+
+  private suspend(): void {
+    if (process.platform === "win32") return;
+    this.renderer.suspend();
+    process.once("SIGCONT", () => { this.renderer.resume(); this.paint(true); });
+    process.kill(process.pid, "SIGTSTP");
+  }
+
+  // -------------------------------------------------------------- extensions
+  bindExtensionRegistry(): void { this.extensions.bind(this.app.extensions); this.clearViewCache(); }
+  runExtensionAction(action: () => void | Promise<void>): void {
+    const job = Promise.resolve().then(action).catch(error => this.notice(describeError(error), "error"))
+      .finally(() => { this.work.delete(job); void this.syncTranscript(); });
+    this.work.add(job);
+  }
+  runExtensionCommand(name: string, args: string): void {
+    this.runExtensionAction(async () => { await this.hooks.bindExtensions(this.app, this); await this.app.extensions?.command(name, args); });
+  }
+  runSessionTransition(action: () => Promise<void>): void {
+    if (this.sessionTransition) return;
+    this.sessionTransition = true;
+    this.runExtensionAction(async () => { try { await action(); } finally { this.sessionTransition = false; } });
+  }
+  deliverExtension(text: string, kind: QueueKind): void {
+    if (this.inflight) { this.queue.push({ kind, text }); this.paint(); }
+    else this.turn = this.runPromptTurn(text).catch(error => this.notice(describeError(error), "error"));
+  }
+
+  /** Renderers or Markdown transforms changed (extension generation): cached views no longer hold. */
+  private clearViewCache(): void { this.viewCache.clear(); this.textCache.clear(); }
+
+  /** After /reload, /trust or a session switch: the new resource generation owns the extension UI. */
+  async refreshResources(): Promise<void> {
+    this.extensions.reset();
+    this.clearViewCache();
+    await this.hooks.bindExtensions(this.app, this);
+    this.applyConfiguration();
+    this.followTheme();
+    this.historyLength = -1;
+    await this.syncTranscript();
+  }
+  applyConfiguration(): void {
+    this.thinkingExpanded = this.app.ui?.settings.hideThinkingBlock === false;
+    this.screen.setColors(this.colors());
+    this.screen.setAnimations(this.app.ui?.settings.animations !== false && process.env["XENO_REDUCED_MOTION"] !== "1" && process.env["TERM"] !== "dumb");
+    // An explicit setting wins; the default keeps the transcript free of a scrollbar column.
+    const scrollbar = this.app.ui?.settings.fullscreenScrollbar;
+    this.screen.messages.setScrollbar(scrollbar === "always" || scrollbar === "auto" ? scrollbar : "hidden");
+    this.applyPictures();
+    this.paint();
+  }
+
+  /**
+   * How pictures are drawn now (feat-tui-inline-images DoD 3). `auto` uses the
+   * terminal's answer to OpenTUI's graphics probe; when that leaves only block
+   * characters (tmux, unknown terminals) pictures are named instead, because
+   * block-character pictures read as noise at thumbnail size.
+   */
+  private pictureSource(): PictureSource {
+    const terminal = this.app.ui?.settings.terminal;
+    const requested = terminal?.imageProtocol ?? "auto";
+    const resolution = this.renderer.resolution;
+    const effective = resolveImageRenderProtocol(requested, this.renderer.capabilities, resolution !== null);
+    const show = terminal?.showImages !== false && (requested !== "auto" || effective !== "blocks");
+    const cell = resolution && this.renderer.terminalWidth > 0 && this.renderer.terminalHeight > 0
+      ? { width: resolution.width / this.renderer.terminalWidth, height: resolution.height / this.renderer.terminalHeight } : DEFAULT_CELL;
+    return { mode: show ? "picture" : "chip", protocol: requested, cell, widthCells: terminal?.imageWidthCells ?? 60, load: sha => this.images.load(sha) };
+  }
+  private applyPictures(): void {
+    if (this.disposed) return;
+    this.screen.setPictures(this.pictureSource());
+  }
+  followTheme(): void {
+    this.stopThemeWatch?.();
+    this.stopThemeWatch = undefined;
+    const name = this.app.ui?.settings.theme ?? "dark";
+    const spec = this.app.resources ? selectedThemePath(this.app.resources, name, this.app.args.noThemes) : name;
+    if (spec === "system" || spec === "auto") {
+      // The terminal reports its own appearance; follow it instead of guessing.
+      const mode = this.renderer.themeMode;
+      this.applyTheme(builtinTheme(mode === "light" ? "light" : "dark"));
+      return;
+    }
+    this.stopThemeWatch = watchTheme(spec, theme => this.applyTheme(theme), message => this.notice(message, "warning"));
+  }
+
+  private applyTheme(theme: ReturnType<typeof builtinTheme>): void {
+    if (this.disposed) return;
+    if (this.app.ui) { this.app.ui.theme = theme; this.app.ui.style = createStyle(styleTokens(theme, this.palette)); }
+    this.screen.setColors(this.colors()); this.paint();
+  }
+
+  // ---------------------------------------------------------------- approval
+  ask(request: PermissionRequest): Promise<ApprovalChoice> {
+    this.program?.update(programStatus({ running: this.inflight, waiting: "permission" }));
+    // While the dialog is open the pending call shows ◌: it is waiting on the person, not running.
+    this.screen.messages.setWaiting(true);
+    const present = (_id: string, resolve: (choice: ApprovalChoice) => void) => {
+      const spec: DialogSpec = { kind: "list", title: "Tool approval", search: false, tone: "warning", intro: approvalHeading(request).split("\n"),
+        items: approvalItems(request), onPick: item => resolve(choiceFromValue(item.value)), onCancel: () => resolve("deny") };
+      this.screen.dialogs.push(spec);
+      return () => { this.screen.messages.setWaiting(false); this.screen.dialogs.remove(spec); this.program?.update(programStatus({ running: this.inflight })); };
+    };
+    // Isolated skills and user shell commands retain their existing local approval lifecycle.
+    const control = sessionControl(this.app.session);
+    if (control.activeTurnId) return control.ask(request, present);
+    return new Promise(resolve => {
+      let close: () => void;
+      close = present("local", choice => { close(); resolve(choice); });
+    });
+  }
+
+  private bindControl(): void {
+    const control = sessionControl(this.app.session);
+    if (this.control === control) return;
+    this.stopControl?.(); this.control = control; this.controlSnapshot = undefined;
+    const detachInput = control.attachInput(phase => this.pullQueued(phase));
+    const unsubscribe = control.subscribe(notice => {
+      if (this.disposed) return;
+      if (notice.method === "turn/started") this.program?.update(programStatus({ running: true }));
+      if (notice.method === "turn/error") {
+        this.programResult = true; this.program?.update({ state: "error", msg: "Turn failed; inspect the session" });
+        this.track(() => this.syncTranscript());
+      }
+      if (notice.method === "approval/request") this.program?.update(programStatus({ running: true, waiting: "permission" }));
+      if (notice.method === "thread/statusChanged" && "waiting" in notice.params)
+        this.program?.update(programStatus({ running: control.busy, waiting: notice.params["waiting"] as ControlSnapshot["waiting"] }));
+      // A remote client drives the same Session; local turns already have the shell's stream adapter.
+      if (!this.abort) {
+        if (notice.method === "turn/started") { this.inflight = true; this.executionKind = "model"; }
+        if (notice.method === "turn/completed") {
+          this.inflight = false; this.executionKind = "idle"; this.clearStream();
+          const outcome = notice.params["outcome"] as import("../../core/outcome.ts").ExecutionOutcome | undefined;
+          this.turn = this.continueRemoteTurn(control, outcome).catch(error => this.notice(describeError(error), "error"));
+        }
+        if (notice.method === "turn/event") {
+          const event = notice.params["event"] as import("../../runtime/loop.ts").LoopEvent;
+          this.observeEvent(event);
+          if (event.kind === "text_delta" || event.kind === "thinking_delta") this.pushDelta(event.kind === "text_delta" ? "text" : "thinking", event.text ?? "");
+          else if (event.kind === "discard") this.discardStream();
+          else if (event.kind === "progress") { if (event.progress) this.pushProgress(event.progress); }
+          else this.track(() => this.syncTranscript());
+        }
+      }
+      if (notice.method !== "turn/event") { this.derivedKey = ""; this.requestDerived(); this.paint(); }
+    });
+    this.stopControl = () => { detachInput(); unsubscribe(); };
+  }
+
+  private async continueRemoteTurn(control: SessionControl, outcome?: import("../../core/outcome.ts").ExecutionOutcome): Promise<void> {
+    // Completion is announced before the iterator releases execution. Follow-ups
+    // remain editor-owned until that release, preserving the existing queue contract.
+    await control.whenIdle().catch(() => {});
+    if (this.disposed || this.shutdownRequested || this.control !== control || this.inflight) return;
+    if (outcome?.status !== "completed") { this.returnQueueToEditor(); return; }
+    const batch = this.nextBatch("turn_end");
+    if (!batch.length) return;
+    this.queue = this.queue.filter(item => !batch.includes(item));
+    await this.runPromptTurn(batch.map(item => item.text).join("\n\n"), batch.flatMap(item => item.images ?? []));
+  }
+
+  observeEvent(event: import("../../runtime/loop.ts").LoopEvent): void {
+    if (event.kind === "done" || event.kind === "stop_and_ask") this.programResult = true;
+    if (event.kind === "done") this.program?.update(programStatus({ running: false,
+      ...(event.outcome ? { outcome: event.outcome } : {}), ...(event.request ? { goal: event.request.status } : {}) }));
+    if (event.kind === "stop_and_ask") this.program?.update(programStatus({ running: false, waiting: "question" }));
+  }
+
+  async openControl(tab: ControlTab = "goal"): Promise<void> {
+    this.bindControl();
+    this.controlSnapshot = await this.control!.snapshot();
+    const tabs: ControlTab[] = ["goal", "progress", "context"];
+    const lenses: ControlFocus[] = ["messages", "omitted", "history"];
+    let focus: ControlFocus = "messages", scroll = 0, total = 0;
+    this.screen.dialogs.push({ kind: "lines", title: "Control panel",
+      hint: "tab sections · ←→ lenses · ↑↓ scroll · r refresh · i interrupt · a accept",
+      render: width => {
+        if (!this.controlSnapshot) return ["Current evidence unavailable. Press r to refresh."];
+        const lines = controlPanelLines(controlModel(this.controlSnapshot), tab, width, focus);
+        const rows = Math.max(4, this.renderer.height - 14); total = lines.length;
+        scroll = Math.min(scroll, Math.max(0, total - rows));
+        return [...lines.slice(scroll, scroll + rows), ...(total > rows ? [`${scroll + 1}–${Math.min(total, scroll + rows)} / ${total} · ↑↓ scroll`] : [])];
+      },
+      handleKey: async key => {
+        if (key.name === "tab") { tab = tabs[(tabs.indexOf(tab) + 1) % tabs.length]!; scroll = 0; this.screen.dialogs.refresh(); return true; }
+        if (key.name === "up" || key.name === "down") { scroll = Math.max(0, Math.min(total - 1, scroll + (key.name === "down" ? 1 : -1))); this.screen.dialogs.refresh(); return true; }
+        if (tab === "context" && (key.name === "left" || key.name === "right")) {
+          focus = lenses[(lenses.indexOf(focus) + (key.name === "right" ? 1 : 2)) % 3]!; scroll = 0; this.screen.dialogs.refresh(); return true;
+        }
+        if (key.name === "r") { this.controlSnapshot = await sessionControl(this.app.session).snapshot(); this.screen.dialogs.refresh(); return true; }
+        if (key.name === "i") { this.interrupt(); return true; }
+        if (key.name === "a") {
+          const goal = this.controlSnapshot?.goal;
+          const criteria = goal?.state.acceptance?.criteria.filter(item => item.kind === "human" && item.status !== "pass" && item.status !== "accepted") ?? [];
+          if (this.inflight || !goal || !criteria.length) { this.toast("No human criterion ready for acceptance", "warning"); return true; }
+          this.screen.dialogs.push({ kind: "list", title: "Accept a human criterion", search: false,
+            items: criteria.map(item => ({ value: item.id, label: item.description, description: item.status })),
+            onPick: async item => {
+              await sessionControl(this.app.session).accept(goal.state.request.event, item.value);
+              this.controlSnapshot = await sessionControl(this.app.session).snapshot(); this.screen.dialogs.refresh();
+            } });
+          return true;
+        }
+        return false;
+      } });
+  }
+
+  // ----------------------------------------------------------------- palette
+  private paletteInput(): PaletteInput {
+    const current = modelKey(this.app.providerConfig.spec);
+    return {
+      bindings: this.keymap().byAction, busy: this.inflight, toolsExpanded: this.toolsExpanded, thinkingExpanded: this.thinkingExpanded, sidebar: this.screen.sidebarVisible,
+      extraCommands: commandEntries(this.app),
+      models: this.app.catalog.filter(spec => this.app.credentialOf(spec).ok).map(spec => ({ key: modelKey(spec), label: spec.name, description: `${spec.provider}/${spec.id}`, current: modelKey(spec) === current })),
+    };
+  }
+
+  openPalette(): void {
+    this.screen.dialogs.push({ kind: "list", title: "Command palette", items: paletteItems(this.paletteInput()), placeholder: "search commands, actions and models", rows: 14,
+      onPick: item => this.runPaletteItem(item.value) });
+  }
+
+  private async runPaletteItem(value: string): Promise<void> {
+    if (value.startsWith("command:")) {
+      const name = value.slice(8);
+      const definition = commandDefinition(`/${name}`);
+      // Commands with required arguments go to the composer instead of running empty.
+      if (definition && "argumentHint" in definition && definition.argumentHint?.startsWith("<")) { this.screen.composer.setText(`/${name} `); return; }
+      await this.submit(`/${name}`, "steering");
+      return;
+    }
+    if (value.startsWith("model:")) {
+      if (this.inflight) { this.toast("Models can be changed after this turn. Esc interrupts it.", "warning"); return; }
+      const spec = this.app.catalog.find(model => modelKey(model) === value.slice(6));
+      if (spec) await this.hooks.switchToModel(this.app, spec);
+      return;
+    }
+    switch (value) {
+      case "action:toggleTools": this.toolsExpanded = !this.toolsExpanded; break;
+      case "action:toggleThinking": await this.hooks.commitSetting(this.app, "hideThinkingBlock", this.thinkingExpanded ? "on" : "off", this); break;
+      case "action:toggleSidebar": this.screen.toggleSidebar(); break;
+      case "action:appearance": this.openSettingValues("theme"); break;
+      case "action:animations": this.openSettingValues("animations"); break;
+      case "action:bottom": this.screen.messages.scrollToBottom(); break;
+      case "action:top": this.screen.messages.scrollToTop(); break;
+      case "action:editor": await this.externalEditor(); break;
+      case "action:pasteImage": await this.pasteClipboard(); break;
+      case "action:cycleThinking": await this.hooks.cycleThinking(this.app, this); break;
+      case "action:interrupt": this.interrupt(); break;
+      case "action:quit": this.requestShutdown(); break;
+    }
+    this.paint();
+  }
+
+  // ----------------------------------------------------------------- dialogs
+  private push(spec: DialogSpec): void { this.screen.dialogs.push(spec); }
+
+  openModel(): void {
+    if (this.inflight) { this.toast("Models can be changed after this turn. Esc interrupts it.", "warning"); return; }
+    const current = modelKey(this.app.providerConfig.spec);
+    const rows = pickerRows(this.app.catalog.map(spec => ({
+      key: modelKey(spec), provider: spec.provider, providerName: SOURCE_PROVIDERS[spec.provider]?.name ?? spec.provider,
+      id: spec.id, name: spec.name, ready: this.app.credentialOf(spec).ok,
+    })), { current, recent: this.app.ui?.settings.recentModels ?? [] });
+    const items: ListItem[] = rows.map(row => ({ value: row.key, label: row.model.id, section: row.group,
+      description: [row.model.name !== row.model.id ? row.model.name : "", row.model.ready ? "" : "login required"].filter(Boolean).join(" · "),
+      keywords: `${row.model.provider} ${row.model.providerName}`, ...(row.current ? { hint: "● current" } : {}) }));
+    items.push({ value: "login", label: "＋ Connect a provider…", section: "More", description: "subscription, API key, gateway or local server" });
+    this.push({ kind: "list", title: `Model · ${rows.filter(row => row.model.ready).length} ready`, items, selected: current,
+      actions: [{ key: "ctrl+s", label: "save default", run: item => this.saveDefaultModel(item) }],
+      onPick: async item => {
+        if (item.value === "login") { this.openLogin(); return; }
+        const spec = this.app.catalog.find(model => modelKey(model) === item.value);
+        if (spec) await this.hooks.switchToModel(this.app, spec);
+      } });
+  }
+  private async saveDefaultModel(item: ListItem | undefined): Promise<void> {
+    const spec = item && this.app.catalog.find(model => modelKey(model) === item.value);
+    if (!spec || !this.app.ui) return;
+    const patch = { defaultModel: spec.id, defaultProvider: spec.provider };
+    await writeUserSettings(patch);
+    this.app.ui.userOverrides = { ...this.app.ui.userOverrides, ...patch };
+    this.app.ui.settings = { ...this.app.ui.settings, ...patch };
+    this.toast(`saved default model ${item.value}`, "success");
+  }
+
+  openThinking(): void {
+    const spec = this.app.providerConfig.spec, current = this.app.providerConfig.effort;
+    this.push({ kind: "list", title: "Thinking", search: false, selected: current,
+      items: THINKING_LEVELS.map(level => ({ value: level, label: level, disabled: !this.hooks.effortSupported(spec, level),
+        ...(level === current ? { hint: "● current" } : !this.hooks.effortSupported(spec, level) ? { description: "not supported by this model" } : {}) })),
+      actions: [{ key: "ctrl+s", label: "save default", run: async item => {
+        const effort = item && asThinkingLevel(item.value);
+        if (!effort || !this.hooks.effortSupported(spec, effort) || !this.app.ui) return;
+        const patch = { modelThinkingLevels: { [modelKey(spec)]: effort } };
+        await writeUserSettings(patch);
+        this.app.ui.userOverrides = mergeSettings({ builtin: this.app.ui.userOverrides, user: patch });
+        this.app.ui.settings = mergeSettings({ builtin: this.app.ui.settings, user: patch });
+        this.toast(`saved default thinking ${effort}`, "success");
+      } }],
+      onPick: async item => { const effort = asThinkingLevel(item.value) as Effort | undefined; if (effort) await this.hooks.applyThinking(this.app, effort, this); } });
+  }
+
+  openLogin(method?: "oauth" | "api_key"): void {
+    const providers = [...new Set(this.app.catalog.map(model => model.provider))].filter(provider => !subscriptionById(provider));
+    const status = (provider: string): string => {
+      const spec = this.app.catalog.find(model => model.provider === provider);
+      const resolved = spec ? this.app.credentialOf(spec) : undefined;
+      const stored = this.app.auth[provider];
+      return resolved?.ok ? `✓ ${stored?.type === "oauth" && resolved.source === "auth.json" ? "account" : "API key"} · ${resolved.source}` : stored ? "stored credential unavailable" : "";
+    };
+    const items: ListItem[] = [];
+    if (method !== "api_key") for (const option of SUBSCRIPTION_OPTIONS) items.push({ value: `oauth:${option.id}`, label: option.label, section: "Sign in with an account", description: status(option.provider) || "browser or device code" });
+    if (!method) {
+      items.push({ value: "connect:custom", label: "＋ Custom endpoint…", section: "Endpoints", description: "OpenAI / Anthropic / Gemini compatible URL, Ollama, LM Studio" });
+      items.push({ value: "connect:manage", label: "⚙ Manage connected…", section: "Endpoints", description: "choose models, replace a key, disconnect" });
+    }
+    if (method !== "oauth") for (const provider of providers) items.push({ value: `key:${provider}`, label: SOURCE_PROVIDERS[provider]?.name ?? provider, section: "API key",
+      description: status(provider) || provider, keywords: provider });
+    this.push({ kind: "list", title: "Connect a provider", items, placeholder: "search providers", rows: 14,
+      onPick: async item => {
+        const [kind, id] = [item.value.slice(0, item.value.indexOf(":")), item.value.slice(item.value.indexOf(":") + 1)];
+        if (kind === "oauth") { await this.hooks.startSubscriptionLogin(this.app, id, this); return; }
+        if (kind === "connect") { this.openConnect(id === "custom" ? "custom" : "manage"); return; }
+        const spec = this.app.catalog.find(model => model.provider === id);
+        const resolved = spec ? this.app.credentialOf(spec) : undefined;
+        const intro = resolved?.ok && resolved.source !== "auth.json" ? ` · current key from ${resolved.source}` : "";
+        const key = await this.askSecret(`API key · ${SOURCE_PROVIDERS[id]?.name ?? id}`, "Key", `paste the key${intro} · $VAR reads the environment · enter save · esc back`);
+        if (key) await this.hooks.login(this.app, id, key);
+      } });
+  }
+
+  private openConnect(entry: "custom" | "manage"): void {
+    startConnect({ app: this.app, wizard: this.screen.dialogs, close: () => this.screen.dialogs.clear(),
+      switchTo: spec => this.hooks.switchToModel(this.app, spec), ...(this.connectFetch ? { fetch: this.connectFetch } : {}) }, entry);
+  }
+
+  openLogout(): void {
+    const stored = Object.keys(this.app.auth).filter(provider => this.app.auth[provider] !== undefined);
+    this.push({ kind: "list", title: "Remove a stored credential", items: stored.map(provider => ({ value: provider, label: SOURCE_PROVIDERS[provider]?.name ?? provider, description: provider })),
+      empty: "No stored credentials", onPick: async item => { await this.hooks.logout(this.app, item.value); } });
+  }
+
+  openScopedModels(): void {
+    const ready = this.app.catalog.filter(spec => this.app.credentialOf(spec).ok);
+    const configured = this.app.ui?.settings.scopedModels;
+    const checked = configured ? ready.filter(spec => configured.some(pattern => pattern === modelKey(spec) || pattern === spec.id)).map(modelKey) : ready.map(modelKey);
+    this.push({ kind: "list", title: "Models to cycle with alt+m", multi: true, checked, empty: "No available models. Use /provider to add a credential.",
+      items: ready.map(spec => ({ value: modelKey(spec), label: spec.id, description: spec.provider, section: SOURCE_PROVIDERS[spec.provider]?.name ?? spec.provider })),
+      onSubmitChecked: async values => {
+        await writeUserSettings({ scopedModels: values });
+        if (this.app.ui) { this.app.ui.settings = { ...this.app.ui.settings, scopedModels: values }; this.app.ui.userOverrides = { ...this.app.ui.userOverrides, scopedModels: values }; }
+        this.app.args.models = ""; this.app.args.modelsExplicit = false;
+        this.toast(`saved ${values.length} scoped models`, "success");
+      } });
+  }
+
+  openSettings(field?: string): void {
+    if (field !== undefined) { this.openSettingValues(field); return; }
+    const settings = this.app.ui?.settings ?? {};
+    const entries: [string, string, string][] = [
+      ["theme", "Theme", settings.theme ?? "dark"],
+      ["thinking", "Thinking", this.app.providerConfig.effort],
+      ["defaultModel", "Default model", settings.defaultModel ? `${settings.defaultProvider}/${settings.defaultModel}` : "automatic"],
+      ["modelThinkingLevels", "Model thinking defaults", `${Object.keys(settings.modelThinkingLevels ?? {}).length} configured`],
+      ["steeringMode", "Steering delivery", settings.steeringMode ?? "one-at-a-time"],
+      ["followUpMode", "Follow-up delivery", settings.followUpMode ?? "one-at-a-time"],
+      ...DISPLAY_SETTINGS.map(item => [item.id, item.label, settingValue(settings, item.id, item.fallback)] as [string, string, string]),
+    ];
+    this.push({ kind: "list", title: "Settings", rows: 14, items: entries.map(([id, label, value]) => ({ value: id, label, hint: value, keywords: id })),
+      keep: true, onPick: item => this.openSettingValues(item.value) });
+  }
+
+  private openSettingValues(field: string): void {
+    const key = field.toLowerCase();
+    if (key === "defaultmodel") { this.openModel(); return; }
+    if (key === "modelthinkinglevels") { this.openModelThinkingDefaults(); return; }
+    const values = key === "thinking" ? [...supportedThinkingLevels(this.app.providerConfig.spec)] : key === "theme" ? ["dark", "light", "system"] : settingValues(field);
+    if (!values.length) { this.notice(`unknown setting: ${field}`, "warning"); return; }
+    const current = key === "thinking" ? this.app.providerConfig.effort : settingValue(this.app.ui?.settings ?? {}, field, "");
+    const spec: DialogSpec = { kind: "list", title: `Setting · ${field}`, search: values.length > 8, selected: current,
+      items: values.map(value => ({ value, label: value,
+        ...(key === "theme" ? { description: value === "dark" ? "Terminal colours · assume a dark background" : value === "light" ? "Terminal colours · assume a light background" : value === "system" ? "Terminal colours · follow its light/dark switch" : "Theme file" } : {}),
+        ...(value === current ? { hint: "● current" } : {}) })),
+      onPick: async item => { await this.hooks.commitSetting(this.app, field, item.value, this); this.reopenSettings(); } };
+    this.push(spec);
+    if (key === "theme") void discoverThemes(this.app.resources).then(names => {
+      if (this.screen.dialogs.top === spec) this.screen.dialogs.list?.setItems(names.map(name => spec.items.find(item => item.value === name) ?? ({ value: name, label: name, ...(name === current ? { hint: "● current" } : {}) })), current);
+    });
+  }
+  /** After a change, show the settings list with the new values (it stayed under the value list). */
+  private reopenSettings(): void { if (this.screen.dialogs.top?.title === "Settings") { this.screen.dialogs.pop(); this.openSettings(); } }
+
+  private openModelThinkingDefaults(): void {
+    const ui = this.app.ui;
+    if (!ui) return;
+    const keys = [...new Set([...this.app.catalog.filter(spec => this.app.credentialOf(spec).ok).map(modelKey), ...Object.keys(ui.settings.modelThinkingLevels ?? {})])];
+    this.push({ kind: "list", title: "Thinking default per model", keep: true, items: keys.map(key => ({ value: key, label: key, hint: ui.settings.modelThinkingLevels?.[key] ?? "inherited" })),
+      onPick: item => {
+        const model = this.app.catalog.find(spec => modelKey(spec) === item.value);
+        this.push({ kind: "list", title: `Thinking default · ${item.value}`, search: false, selected: ui.settings.modelThinkingLevels?.[item.value] ?? "clear",
+          items: [{ value: "clear", label: "Clear user override", description: "use the project or global default" },
+            ...(model ? supportedThinkingLevels(model).map(level => ({ value: level, label: level })) : [])],
+          onPick: async choice => {
+            if (choice.value === "clear") {
+              await removeModelThinkingOverride(item.value);
+              const loaded = await loadUiResources({ ...this.app.args, workspace: this.app.workspace, trusted: this.app.projectTrusted ?? this.app.args.approve ?? false });
+              ui.settings = { ...ui.settings, modelThinkingLevels: loaded.settings.modelThinkingLevels ?? {} };
+              ui.userOverrides = { ...ui.userOverrides, modelThinkingLevels: loaded.userOverrides.modelThinkingLevels ?? {} };
+            } else {
+              const patch = { modelThinkingLevels: { [item.value]: choice.value as Effort } };
+              await writeUserSettings(patch);
+              ui.settings = mergeSettings({ builtin: ui.settings, user: patch });
+              ui.userOverrides = mergeSettings({ builtin: ui.userOverrides, user: patch });
+            }
+            this.screen.dialogs.pop(); this.openModelThinkingDefaults();
+          } });
+      } });
+  }
+
+  async openResume(): Promise<void> {
+    type Row = Extract<Awaited<ReturnType<typeof collect>>[number], { ok: true }>;
+    let scope: "current" | "all" = "current", sort: SessionSort = "threaded", rows: Row[] = [];
+    const root = { path: dirname(this.app.logDir), workspace: this.app.workspace };
+    const scan = new AbortController();
+    const items = (query = ""): ListItem[] => selectSessions(rows, query, sort, false, sessionFuzzy).map(row => ({
+      value: row.path, label: "  ".repeat(Math.min(8, row.depth)) + (row.depth ? "↳ " : "") + (row.name?.trim() || row.text?.split("\n").find(Boolean)?.slice(0, 90) || row.id),
+      description: [row.updated_at?.slice(0, 16).replace("T", " ") ?? "", row.model ?? "", scope === "all" ? row.workspace ?? "" : ""].filter(Boolean).join(" · "),
+      ...(row.path === this.app.logDir ? { hint: "● current" } : {}),
+    }));
+    const load = async () => {
+      rows = [];
+      const roots = scope === "current" ? [root] : await sessionRoots(root);
+      for await (const batch of scanSessionRoots(roots, scan.signal)) {
+        rows.push(...batch.sessions.filter((row): row is Row => row.ok));
+        if (this.screen.dialogs.top === spec) this.screen.dialogs.list?.setItems(items(this.screen.dialogs.list.query));
+      }
+    };
+    const actions: ListAction[] = [
+      { key: "tab", label: "scope", run: async () => { scope = scope === "current" ? "all" : "current"; spec.title = `Resume · ${scope === "current" ? "this folder" : "all workspaces"}`; await load(); } },
+      { key: "ctrl+s", label: "sort", run: list => { sort = sort === "threaded" ? "recent" : sort === "recent" ? "relevance" : "threaded"; this.screen.dialogs.list?.setItems(items(this.screen.dialogs.list.query)); void list; } },
+      { key: "ctrl+r", label: "rename", run: item => { if (!item) return; this.push({ kind: "form", title: "Rename session", label: "Name", value: rows.find(row => row.path === item.value)?.name ?? "",
+        onSubmit: async name => { await renameSession(item.value, name); if (item.value === this.app.logDir) this.sessionName = name || null; await load(); } }); } },
+      { key: "ctrl+d", label: "remove", run: item => {
+        if (!item) return;
+        if (item.value === this.app.logDir) { this.toast("cannot remove the active session", "warning"); return; }
+        this.push({ kind: "confirm", title: "Remove session", message: "Remove it from this list? The log is kept in .trash and can be restored.", onAnswer: async yes => {
+          if (!yes) return;
+          const kept = await archiveSession(item.value, this.app.logDir);
+          this.notice(`Session kept at ${kept}`);
+          await load();
+        } });
+      } },
+    ];
+    const spec: DialogSpec & { kind: "list" } = { kind: "list", title: "Resume · this folder", items: [], placeholder: "search sessions · re:<regex> · \"phrase\"", rows: 14, empty: "Loading sessions…", actions,
+      onPick: async item => { scan.abort(); await this.hooks.resumeSession(this.app, item.value, this); }, onCancel: () => scan.abort() };
+    this.push(spec);
+    await load();
+    async function collect() { return [] as Awaited<ReturnType<typeof scanSessionRoots> extends AsyncGenerator<infer S> ? S : never>["sessions"]; }
+  }
+
+  async openFork(): Promise<void> {
+    const points = await this.app.session.userMessages();
+    this.push({ kind: "list", title: "Fork · edit a previous message", empty: "No user messages yet",
+      items: points.map((point, i) => ({ value: String(i + 1), label: firstLine(point.text, 110), description: `node ${point.node}` })).reverse(),
+      onPick: async item => { await this.hooks.forkSession(this.app, item.value, this); } });
+  }
+
+  async openTree(): Promise<void> {
+    const nodes = await this.hooks.treeNodesFor(this.app);
+    const filters: TreeFilter[] = ["default", "no-tools", "user-only", "labeled-only", "all"];
+    let filter: TreeFilter = this.app.ui?.settings.treeFilterMode ?? "default";
+    const items = (): ListItem[] => flattenTree(nodes, filter).map(row => ({ value: row.node.id, label: `${row.branch}${row.node.current ? "● " : row.node.onPath ? "" : "↩ "}${row.node.label ? `[${row.node.label}] ` : ""}${firstLine(row.node.prompt, 90)}`,
+      keywords: row.node.content ?? "", ...(row.node.current ? { hint: "here" } : {}), ...(row.node.target === undefined ? { disabled: true } : {}) }));
+    const byId = new Map<string, TreeNode>();
+    const index = (list: readonly TreeNode[]) => { const stack = [...list]; while (stack.length) { const node = stack.pop()!; byId.set(node.id, node); stack.push(...node.children); } };
+    index(nodes);
+    const current = flattenTree(nodes, filter).find(row => row.node.current)?.node.id;
+    const spec: DialogSpec & { kind: "list" } = { kind: "list", title: `Session tree · ${filter}`, items: items(), rows: 16, empty: "nothing to go back to — no exchange has completed yet",
+      ...(current ? { selected: current } : {}),
+      actions: [
+        { key: "tab", label: "filter", run: () => { filter = filters[(filters.indexOf(filter) + 1) % filters.length]!; spec.title = `Session tree · ${filter}`; this.screen.dialogs.list?.setItems(items()); } },
+        { key: "ctrl+l", label: "label", run: item => { const node = item && byId.get(item.value); if (!node?.target) return;
+          this.push({ kind: "form", title: "Label this point", label: "Label", value: node.label ?? "", onSubmit: async text => { await setSessionLabel(this.app.logDir, node.target!, text, this.app.session.clock.now()); } }); } },
+        { key: "ctrl+y", label: "copy", run: async item => { const node = item && byId.get(item.value); if (!node) return; const ok = await this.clipboardWriter(node.content ?? node.prompt); this.toast(ok ? "copied" : "clipboard unavailable"); } },
+      ],
+      onPick: async item => {
+        const node = byId.get(item.value);
+        if (!node?.target) return;
+        if (this.inflight) { await this.settle(); this.returnQueueToEditor(); }
+        const done = await this.app.session.navigateTo(node.target);
+        await this.syncTranscript();
+        if (done.editorText !== undefined) this.restoreDraft(done.editorText, done.images ?? []);
+        this.notice(`conversation at node ${this.app.session.state.node}`, "success");
+      } };
+    this.push(spec);
+  }
+
+  async openResources(): Promise<void> {
+    const trusted = (await projectTrust(this.app.workspace, this.app.projectTrusted ?? this.app.args.approve)).trusted;
+    const options = { ...this.app.args, workspace: this.app.workspace, trusted };
+    let index = await discoverResources(options);
+    let scope: "user" | "project" = "user";
+    const items = (): ListItem[] => index.entries.map(entry => ({ value: `${entry.kind}:${entry.path}`, label: `${entry.enabled ? "◉" : "○"} ${entry.name}`, section: entry.kind,
+      description: `${entry.scope}${entry.trusted ? "" : " · untrusted"}${scope === "project" ? ` · ${entry.override}` : ""}`, keywords: entry.path }));
+    const spec: DialogSpec & { kind: "list" } = { kind: "list", title: "Resources · global", items: items(), rows: 14, empty: "No resources found", hint: "space toggle · tab scope · esc close",
+      actions: [
+        { key: "tab", label: "scope", run: () => { scope = scope === "user" ? "project" : "user"; spec.title = `Resources · ${scope === "user" ? "global" : "project"}`; this.screen.dialogs.list?.setItems(items()); } },
+        { key: "space", label: "toggle", run: async item => {
+          const entry = index.entries.find(row => `${row.kind}:${row.path}` === item?.value);
+          if (!entry) return;
+          await setResourceOverride(index, entry, scope, scope === "project" ? nextResourceOverride(entry.override) : entry.inherited ? "skip" : "load");
+          index = await discoverResources(options);
+          await reloadAppResources(this.app); await this.refreshResources();
+          this.screen.dialogs.list?.setItems(items(), item?.value);
+          this.toast(entry.trusted ? "saved and reloaded" : "saved; project resources stay blocked until the project is trusted");
+        } },
+      ] };
+    this.push(spec);
+  }
+
+  async openTrust(): Promise<void> {
+    const trust = await projectTrust(this.app.workspace, this.app.projectTrusted ?? this.app.args.approve);
+    this.push({ kind: "list", title: "Project trust", search: false,
+      intro: [this.app.workspace, `Saved: ${trust.saved ? `${trust.saved.trusted ? "trusted" : "untrusted"} (${trust.saved.path})` : "none"} · this session: ${trust.trusted ? "trusted" : "untrusted"} · tool permissions are separate`],
+      items: trustItems(this.app.workspace),
+      onPick: async item => { await this.hooks.trustProject(this.app, item.value as TrustChoice, this); } });
+  }
+
+  openAttachments(): void {
+    this.push({ kind: "list", title: "Draft attachments · enter removes", search: false, empty: "No attachments on the draft",
+      items: this.pendingImages.map((image, i) => ({ value: String(i), label: image.name, description: `${image.width}×${image.height}` })),
+      onPick: item => { this.imageDraft.removeImage(Number(item.value)); this.paint(); } });
+  }
+}
+
+export function trustItems(workspace: string): ListItem[] {
+  return [
+    { value: "once", label: "Trust for this session", description: "load project resources without saving" },
+    { value: "here", label: "Trust this directory", description: workspace },
+    { value: "parent", label: "Trust the parent directory", description: dirname(workspace) },
+    { value: "never", label: "Do not trust", description: "skip project configuration and executable extensions" },
+  ];
+}
+
+function emptyLive() { return { thinking: "", text: "", tools: new Map<string, { name: string; arguments: string }>(), output: "", bash: null as string | null, retryUntil: 0, retryAttempt: 0 }; }
+
+function noticeOf(id: string, after: number, lines: string[], tone: Tone): Notice & { lines: string[]; tone: Tone } {
+  const prefix = tone === "error" ? "\x1b[31m" : tone === "warning" ? "\x1b[33m" : tone === "success" ? "\x1b[32m" : "";
+  return { id, after, lines, tone, item: { kind: "lines", id, rev: String(lines.length), render: () => lines.map(line => prefix ? `${prefix}${line}\x1b[39m` : line) } };
+}
+
+/**
+ * Process entry: own the terminal for the session, then give it back with
+ * the conversation printed (fullscreen leaves the alternate screen, so the
+ * transcript would otherwise vanish with it).
+ */
+export async function runInteractive(app: App, hooks: Hooks, releaseEarlyTty?: () => void, renderer?: CliRenderer): Promise<void> {
+  const fullscreen = (app.ui?.settings.tuiMode ?? "fullscreen") !== "regular";
+  releaseEarlyTty?.();
+  // Capture the real writer before OpenTUI owns stdout, so OSC never becomes transcript text.
+  const terminalWrite = process.stdout.write.bind(process.stdout);
+  const r = renderer ?? await createCliRenderer({ screenMode: fullscreen ? "alternate-screen" : "main-screen", exitOnCtrlC: false, exitSignals: [],
+    // Performance (refactor-tui-dock-layout DoD 9): no console capture, no stats, no hover tracking; bursts coalesce at 60 fps.
+    consoleMode: "disabled", openConsoleOnError: false, useMouse: true, enableMouseMovement: false, gatherStats: false, memorySnapshotInterval: 0, targetFps: 60, maxFps: 60 });
+  const program = new ProgramStatusReporter({ write: text => { terminalWrite(text); }, id: `xeno-${process.pid}`,
+    tty: !renderer && process.stdout.isTTY === true, mode: process.env["XENO_PROGRAM_STATUS"] ?? "auto",
+    multiplexed: Boolean(process.env["TMUX"] || process.env["STY"]) });
+  const ui = new InteractiveApp(app, hooks, r, program);
+  const previousSay = app.io.say;
+  app.io.say = line => ui.notice(line);
+  const stop = (code: number) => { process.exitCode = code; ui.requestShutdown(); };
+  // After a hangup the tty is gone: the final frame and terminal reset fail with EIO. Nobody can read them.
+  const ignoreDeadTty = (error: NodeJS.ErrnoException) => { if (error.code !== "EIO" && error.code !== "EPIPE") throw error; };
+  const terminate = () => stop(143);
+  const hangup = () => { process.stdout.on("error", ignoreDeadTty); process.stderr.on("error", ignoreDeadTty); stop(129); };
+  const crash = (error: unknown) => {
+    if (process.exitCode === 129 && typeof error === "object" && error !== null && ["EIO", "EPIPE"].includes(String((error as { code?: unknown }).code))) return;
+    stop(1); ui.notice(describeError(error), "error");
+  };
+  process.on("SIGTERM", terminate); process.on("SIGHUP", hangup); process.on("uncaughtException", crash); process.on("unhandledRejection", crash);
+  const lastResort = () => { try { r.destroy(); } catch { /* already restored */ } };
+  process.on("exit", lastResort);
+  try {
+    await ui.start();
+    await ui.closed;
+    await ui.settle();
+  } finally {
+    try { await app.session.dispose(); await app.extensions?.dispose(); await hooks.cancelPendingOAuth(app); }
+    finally {
+      ui.dispose();
+      if (!renderer) r.destroy();
+      app.io.say = previousSay;
+      process.off("SIGTERM", terminate); process.off("SIGHUP", hangup); process.off("uncaughtException", crash); process.off("unhandledRejection", crash); process.off("exit", lastResort);
+    }
+    if (!renderer && fullscreen) printExit(app);
+  }
+}
+
+/** After leaving the alternate screen: the conversation as plain text, then how to come back. */
+function printExit(app: App): void {
+  const mode = app.ui?.settings.fullscreenExitOutput ?? "transcript";
+  if (mode === "transcript") {
+    for (const item of projectTranscript(app.session.state.events)) {
+      if (item.kind === "user") process.stdout.write(`\n❯ ${item.text}\n`);
+      else if (item.kind === "assistant") process.stdout.write(`\n${item.text}\n`);
+      else if (item.kind === "tool") process.stdout.write(`  ⏺ ${item.name}${item.result ? item.result.ok ? "" : " (failed)" : " (pending)"}\n`);
+    }
+  }
+  process.stdout.write(`\n  resume with: xeno --session ${JSON.stringify(app.logDir)}\n`);
+}
+
+/** The session-start rule first, then the projection (refactor-tui-dock-layout DoD 7). */
+function projectWithStart(items: ReturnType<typeof projectItems>, clock: string | undefined): ReturnType<typeof projectItems> {
+  return clock ? [{ kind: "segment", id: "session-start", rev: clock, label: `session · ${clock}` }, ...items] : items;
+}
+
+/** "~/Projects/workspace/xeno-tui" → "~/P/w/xeno-tui": every directory but the last cut to its first letter. */
+export function shortPath(path: string): string {
+  const parts = path.split("/");
+  return parts.map((part, i) => i === parts.length - 1 || part === "~" || part === "" ? part : part.startsWith(".") ? part.slice(0, 2) : part.slice(0, 1)).join("/");
+}
+
+/** core/session-browser wants (query, text) → match; our fuzzy is (text, query) → score | null. */
+function sessionFuzzy(query: string, text: string): { matches: boolean; score: number } {
+  const score = fuzzyMatch(text, query);
+  return { matches: score !== null, score: score ?? Number.POSITIVE_INFINITY };
+}