@sagmans/dsh-tui 0.4.0 → 0.5.0

package/lib/index.js

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { ProcessTerminal, ScrollView, VStack, isKeyRelease, matchesKey } from '@earendil-works/pi-tui';
+import { ProcessTerminal, ScrollView, isKeyRelease, matchesKey } from '@earendil-works/pi-tui';
 import { startAgent } from "./agent/host.js";
 import { PICKER_LIMIT, createSessionHistory, presetOfStoredSession, readSessionTitle, } from "./agent/history.js";
 import { createPromptHistory } from "./agent/prompt-history.js";
@@ -15,6 +15,7 @@ import { JOB_READ_LINES, createJobDirectory, describeJobs, parseJobsArgument } f
 import { SubagentRoster, createSubagentControl, describeSubagents, parseSubagentsArgument, resolveRun, } from "./subagents.js";
 import { describeMissingOptional, describeMissingRequired, probeComposition } from "./compat/probe.js";
 import { ApprovalGate, QuestionGate, toGateQuestions } from "./gates.js";
+import { cancelStep, quitStep } from "./input/cancel.js";
 import { createCompletionProvider } from "./input/completion.js";
 import { ghostSuffix } from "./input/ghost.js";
 import { LOCAL_COMMANDS, classifySubmission } from "./input/submission.js";
@@ -24,6 +25,8 @@ import { defaultKeymap, hintKeys, surfaceBindings } from "./input/actions.js";
 import { resolveConfig } from "./config.js";
 import { FoldCursor } from "./fold-cursor.js";
 import { createRestoreRegistry } from "./terminal/restore.js";
+import { ExternalEditor } from "./terminal/external-editor.js";
+import { installSignalRestore } from "./terminal/signals.js";
 import { WarningSafeTui } from "./terminal/warning-screen.js";
 import { BELL, shouldRingBell } from "./terminal/bell.js";
 import { clipboardSequence } from "./terminal/clipboard.js";
@@ -34,9 +37,11 @@ import { defaultExportFile, transcriptToText } from "./export.js";
 import { createTheme, forwardEditorTheme, forwardMarkdownTheme } from "./theme.js";
 import { detectColourMode } from "./theme-capability.js";
 import { defaultSettings, readScope, settingsProblemMessage, toOverrides, TUI_SETTINGS_NAMESPACE, TuiSettingsSchema } from "./theme-settings.js";
+import { toolDisplayFor } from "./tool-display.js";
 import { pendingPrompts } from "./queue.js";
 import { renderThemeTable } from "./theme-command.js";
-import { KEYMAP_LAYERS, keymapLayer, renderKeymap } from "./keys-command.js";
+import { DEFAULT_THEME, builtinNames, builtinThemesDir, ensureThemesHome, exportTheme, loadThemes, themesHomeDir, watchThemes } from "./theme-files.js";
+import { KEYMAP_LAYERS, keymapLayer } from "./keys-command.js";
 import { resetSequence } from "./theme-tokens.js";
 import { SessionId } from '@deepseek-ai/dsh-session';
 import { formatTokens } from "./tokens.js";
@@ -45,15 +50,19 @@ import { WorkFold, describeTodos, planSelectedActive, planToggleLine, readPlanSt
 import { WorkDock } from "./ui/dock.js";
 import { GateInputBar } from "./ui/gate-input.js";
 import { HistoryPicker } from "./ui/history-picker.js";
+import { surfaceLayout } from "./ui/layout.js";
+import { KeymapPicker } from "./ui/keymap-picker.js";
+import { PickerPopup, POPUP_MAX_HEIGHT, popupWidth } from "./ui/picker-card.js";
 import { PromptBar } from "./ui/prompt.js";
 import { MarkdownRenderer } from "./ui/markdown.js";
 import { createMermaidTransform } from "./ui/mermaid.js";
 import { EffortPicker, ModelPicker, PROVIDER_DEFAULT_EFFORT_ID, PresetPicker, SessionPicker, effortChoices, } from "./ui/picker.js";
 import { QueueBar } from "./ui/queue.js";
-import { shortPath, StatusBar } from "./ui/status.js";
+import { StatusBar } from "./ui/status.js";
 import { DEFAULT_VIEW_STATE, TranscriptView } from "./ui/view.js";
 import { PromptStash } from "./stash.js";
 import { confirmedClear, StashConfirmPicker, StashPicker } from "./ui/stash-picker.js";
+import { ThemePicker } from "./ui/theme-picker.js";
 export const name = 'tui';
 /**
  * Services the surface cannot run without.
@@ -128,19 +137,76 @@ export function apply(ctx, config) {
      * late-bound read that the injection point and the change event both use.
      */
     let readSection = () => defaultSettings();
+    /**
+     * The themes this session can draw.
+     *
+     * Read from disk rather than compiled in, so a file the reader saves is a theme
+     * the moment the save lands. Held beside the settings rather than inside them
+     * because the two answer different questions: the section says which name the
+     * reader chose, and this says which names exist — including the one they typed
+     * into the directory a second ago.
+     */
+    const themesHome = themesHomeDir();
+    let themeLibrary = loadThemes(themesHome, builtinThemesDir());
+    /**
+     * Persist a theme choice, replaced once the section is registered.
+     *
+     * A theme picked mid-session has to outlive it, so the choice is written
+     * through the same scope the reader's document is read from instead of kept
+     * in memory: the host persists it, and the change comes back through
+     * `settings/updated` like any other edit — which is what restyles the screen.
+     */
+    let chooseTheme = (_name) => { };
     /**
      * A refused settings edit, kept until the surface can show it: stderr is
      * behind the alt screen, and the section is read on a schedule of its own.
      */
     const settingsNotice = createDeferredNotice();
     let current = createTheme(themeMode());
+    /**
+     * The section as it was last read.
+     *
+     * Held so a preview can rebuild the table without reading the document again:
+     * the picker repaints on every arrow key, and a read there would report a
+     * refused section once per press.
+     */
+    let appliedSection;
+    /**
+     * The theme the picker's cursor is on, while its list is open.
+     *
+     * A preview is a name and nothing else — the document is not written — so
+     * leaving the list is one more rebuild from the section, and a session that
+     * ends mid-preview has still persisted only what the reader chose.
+     */
+    let previewTheme;
     const applyTheme = (section) => {
-        current = createTheme(themeMode(), toOverrides(section));
+        // The row under the cursor outranks the document while a list is open, so a
+        // theme is judged on the reader's own transcript before it is taken.
+        current = createTheme(themeMode(), toOverrides({ ...section, theme: previewTheme ?? section.theme }, themeLibrary));
+    };
+    /**
+     * Show a theme without choosing it.
+     *
+     * The list's cursor is the preview: every row paints the surface and writes
+     * nothing, so two themes are compared on the reader's own transcript rather
+     * than on a name. Clearing the name puts back what the document says, which is
+     * what cancelling the list has to leave behind.
+     */
+    const showTheme = (name) => {
+        previewTheme = name;
+        // Nothing to rebuild from before the first read, and nothing to show either.
+        if (appliedSection === undefined)
+            return;
+        applyTheme(appliedSection);
+        markdown.invalidate();
+        view.invalidate();
+        tui.requestRender();
     };
     const theme = {
         get revision() { return current.revision; },
         get color() { return current.color; },
         style: (token, text) => current.style(token, text),
+        rich: (raw, options) => current.rich(raw, options),
         cut: (text, width, ellipsis) => current.cut(text, width, ellipsis),
         glyph: token => current.glyph(token),
         visible: token => current.visible(token),
@@ -151,12 +217,13 @@ export function apply(ctx, config) {
         markdown: forwardMarkdownTheme(() => current.markdown),
     };
     /**
-     * Rows the reader has opened. The model stays untouched; only the view reads
-     * this. A thought starts folded: it is the longest, least scannable row in the
-     * transcript, so leaving it open pushes the answer a reader came for off the
-     * screen, and a folded row still names itself and its key. A PTC card's calls
-     * start open for the opposite reason: each is one clipped line under a header
-     * that already names the program.
+     * Rows the reader has opened by key. The model stays untouched; only the view
+     * reads this, and a click on one message overrides it there. A thought starts
+     * folded: it is the longest, least scannable row in the transcript, so leaving
+     * it open pushes the answer a reader came for off the screen, and a folded row
+     * still names itself and its key. Cards start from the reader's own `tools:`
+     * settings, and a PTC card's calls start open for the opposite reason: each is
+     * one clipped line under a header that already names the program.
      */
     const viewState = { ...DEFAULT_VIEW_STATE };
     /**
@@ -167,6 +234,8 @@ export function apply(ctx, config) {
      * follow the edit.
      */
     let mermaidMode = defaultSettings().mermaid;
+    /** How each tool's cards draw; the settings document owns it and the view reads it live. */
+    let toolDisplay = defaultSettings().tools;
     /** The keys that start a chord, and how long one waits; the settings document owns all of it. */
     let prefixKeys = DEFAULT_PREFIX_KEYS;
     let prefixWindowMs = DEFAULT_PREFIX_WINDOW_S * MS_PER_SECOND;
@@ -190,11 +259,13 @@ export function apply(ctx, config) {
      *
      * The key toggles nested calls for one session, but a settings edit is a
      * deliberate act, so it re-seeds and becomes the new starting point; the
-     * mermaid mode has no key of its own and only ever comes from the document.
+     * mermaid mode and the per-tool card fold have no key of their own and only
+     * ever come from the document.
      */
     const applyDisplay = (section) => {
         viewState.expandSubCalls = section.subcalls === 'inline';
         mermaidMode = section.mermaid;
+        toolDisplay = section.tools;
         prefixKeys = section.prefixes;
         prefixWindowMs = section.prefixWindow * MS_PER_SECOND;
         keymap = section.keymap;
@@ -215,9 +286,30 @@ export function apply(ctx, config) {
      */
     const applySettings = () => {
         const section = readSection();
+        appliedSection = section;
+        // A settings edit ends any preview: what the document says is now the choice,
+        // and a name left over from a list would outrank it.
+        previewTheme = undefined;
+        reportMissingTheme(section);
         applyTheme(section);
         applyDisplay(section);
     };
+    /**
+     * Say so when the reader named a theme that nothing answers to.
+     *
+     * The schema cannot refuse the name: a theme is a file, so the set of names is
+     * known to the directory rather than to this build, and one can stop answering
+     * between two reads. Falling back to the default without a word would leave the
+     * reader looking at shades they did not choose, so the refusal lands here
+     * instead — beside the read that found it, and alongside the rest of the
+     * section, which is still theirs.
+     */
+    const reportMissingTheme = (section) => {
+        const name = section.theme;
+        if (name === undefined || themeLibrary.get(name) !== undefined)
+            return;
+        settingsNotice.post(`dsh-tui theme "${name}" is not a theme · themes: ${themeLibrary.names().join(' · ')} · the default, ${DEFAULT_THEME}, is drawn instead`);
+    };
     /**
      * Own the section, so the harness validates and persists it for the reader.
      *
@@ -243,6 +335,9 @@ export function apply(ctx, config) {
             return;
         }
         readSection = () => readScope(scope, message => settingsNotice.post(message));
+        chooseTheme = name => {
+            void scope.update({ theme: name }).then(() => model.notice(`theme · ${name} · written to the settings document`), (error) => settingsNotice.post(settingsProblemMessage(error)));
+        };
         applySettings();
     });
     /**
@@ -314,6 +409,28 @@ export function apply(ctx, config) {
     const restore = createRestoreRegistry();
     const terminal = new ProcessTerminal();
     const tui = new WarningSafeTui(terminal);
+    // A frame that cannot be drawn leaves the last good screen up, so the failure
+    // has to reach the transcript: otherwise the surface looks frozen and nothing
+    // on screen can say why.
+    tui.onFrameError = error => model.reportError(error);
+    /** Whether a child process owns the terminal, which is when nothing here may write to it. */
+    let handedOver = false;
+    /** Whether the host has unloaded this surface, after which nothing may start it again. */
+    let disposed = false;
+    /** An exit asked for while a child owned the terminal, run once the screen is ours again. */
+    let deferredExit;
+    /**
+     * Write to the tty, but only while this surface owns it.
+     *
+     * An editor the reader opened draws its own screen on the same terminal, so a
+     * title or a bell from here would land on top of it and, for a bell, sound as
+     * if the editor had failed. The title is written again when the screen comes
+     * back; a bell that fell in the gap is dropped rather than rung late.
+     */
+    const writeTerminal = (text) => {
+        if (!handedOver)
+            terminal.write(text);
+    };
     /** The session this surface drives: commands, approvals, and the bell belong to it. */
     let activeSession = resolved.sessionId;
     /** The session the transcript is showing, which can be one of its children. */
@@ -325,8 +442,9 @@ export function apply(ctx, config) {
     const view = new TranscriptView(model, theme, markdown, {
         state: () => viewState,
         gate: () => pending?.gate.card(),
-        picker: () => pendingPicker?.picker.card(),
+        picker: () => pendingPicker?.card?.(),
         keys: () => keymap,
+        toolDisplay: tool => toolDisplayFor(toolDisplay, tool),
     });
     // The key map goes in before the bar exists, so no press can be read as the
     // send the library submits on by default. A settings document read after this
@@ -372,7 +490,8 @@ export function apply(ctx, config) {
     const dock = new WorkDock(() => work.state(), theme, () => jobs, () => roster.list());
     // The queue is read from the agent this terminal drives rather than from the
     // session on screen, because it sits on the editor that submits to that agent.
-    const queue = new QueueBar(() => pendingPrompts(ctx, liveSession(activeSession)), theme);
+    const queuedPrompts = () => pendingPrompts(ctx, liveSession(activeSession));
+    const queue = new QueueBar(queuedPrompts, theme);
     // Only a running turn has anything to say over time, so the clock stops with it.
     const statusTicker = setInterval(() => {
         if (turnOpen)
@@ -390,6 +509,9 @@ export function apply(ctx, config) {
     const unregisterExit = herdr.registerExitRelease();
     restore.add(() => tui.stop());
     ctx.effect(() => () => {
+        // A surface the host unloads owns no screen and keeps no listeners, so a
+        // child still running in another process must not be handed a start().
+        disposed = true;
         // The pane stops being an agent before the process that claimed it unwinds:
         // a release that ran after the reports were unregistered would race them,
         // and one that never ran would leave a row that reads as a live agent. The
@@ -404,27 +526,24 @@ export function apply(ctx, config) {
             dispose();
         return released.finally(unregisterExit);
     });
-    tui.setLayoutRoot(new VStack([
-        {
-            component: new ScrollView(view, { follow: 'end', primary: true, overscroll: 'chain' }),
-            basis: 0,
-            grow: 1,
-            minSize: 1,
-        },
-        // Work state earns rows only when there is some: a dock that always
-        // occupied a row would cost every conversation one line of transcript.
-        { component: dock, basis: 'auto', shrink: 0, minSize: 0 },
-        // Queued input earns rows only while something is waiting, and it gives
-        // them up before the editor does: the bar being typed in outranks what is
-        // waiting behind it.
-        { component: queue, basis: 'auto', shrink: 2, minSize: 0 },
-        { component: new VStack([{ component: promptBar, basis: 'auto', shrink: 1, minSize: 1 }]), basis: 'auto', shrink: 1, minSize: 0 },
-        { component: statusBar, basis: 'auto', shrink: 0, minSize: 1 },
-    ]));
+    tui.setLayoutRoot(surfaceLayout({
+        transcript: new ScrollView(view, { follow: 'end', primary: true, overscroll: 'chain' }),
+        dock,
+        queue,
+        prompt: promptBar,
+        status: statusBar,
+    }));
     tui.setFocus(editor);
     const requestExit = (code, reason) => {
         if (exited)
             return;
+        // A child owns the terminal: restoring it here would leave the reader a
+        // shell behind an editor that is still running, and would put its tty back
+        // into cooked mode under it. The exit waits for the screen to come back.
+        if (handedOver) {
+            deferredExit = { code, reason };
+            return;
+        }
         exited = true;
         clearInterval(statusTicker);
         // The screen goes back at once, so leaving feels like leaving; the row goes
@@ -453,6 +572,10 @@ export function apply(ctx, config) {
             appExit(code);
         });
     };
+    // A signal ends the process from outside the surface, and the default action
+    // would leave the reader on a screen no shell prompt is drawn in: the same
+    // shutdown a quit key runs goes to the signals a supervisor sends.
+    disposers.push(installSignalRestore({ shutdown: code => requestExit(code, 'interrupted') }));
     const openGate = (next) => {
         pending = next;
         // The card's own title names the decision, which is what a reader glancing
@@ -477,6 +600,14 @@ export function apply(ctx, config) {
         tui.setFocus(editor);
         tui.requestRender();
     };
+    /**
+     * Whether the bar holds anything the reader wrote.
+     *
+     * Whitespace counts: it is a character the editor holds, and a press that
+     * clears it is the press the reader asked for. A paste counts expanded,
+     * because a marker is content rather than an absence of it.
+     */
+    const barHasText = () => editor.getExpandedText() !== '';
     /**
      * What each key the surface answers itself does; false hands the press back.
      *
@@ -514,15 +645,57 @@ export function apply(ctx, config) {
         },
         interrupt: () => {
             // In raw mode Ctrl+C never reaches the process as SIGINT, so the surface
-            // decides: stop the work in flight, or leave when there is none.
-            if (!turnOpen) {
-                requestExit(0);
-                return true;
+            // decides what one press takes back — and a press with nothing left to
+            // cancel is handed back rather than spent on leaving.
+            const queued = queuedPrompts();
+            const step = cancelStep({
+                barHasText: barHasText(),
+                queuedPrompts: queued.length,
+                turnRunning: turnOpen,
+                viewingChild: viewedSession !== activeSession,
+            });
+            switch (step) {
+                case 'clear-editor':
+                    editor.setText('');
+                    tui.requestRender();
+                    return true;
+                case 'reclaim-queued':
+                    // The interrupt drops whatever the agent had not started, so the words
+                    // are read before it is stopped and handed back to the bar: a key that
+                    // means "stop" must not be the key that loses the reader's own prompts.
+                    agent?.interrupt();
+                    editor.setText(queued.join('\n'));
+                    model.notice(`interrupt requested · ${queued.length} queued ${queued.length === 1 ? 'prompt' : 'prompts'} back in the bar`);
+                    tui.requestRender();
+                    return true;
+                case 'interrupt-turn':
+                    agent?.interrupt();
+                    model.notice('interrupt requested');
+                    tui.requestRender();
+                    return true;
+                case 'leave-child-view':
+                    void showAgentSession();
+                    return true;
+                case 'hand-back':
+                    return false;
+            }
+        },
+        quit: () => {
+            // The only key that leaves. Text in the bar keeps it for the editor, so
+            // the library's delete forward is never taken from a reader who is editing.
+            switch (quitStep({ barHasText: barHasText(), overlayOpen: tui.hasOverlay(), turnRunning: turnOpen })) {
+                case 'cancel-then-quit':
+                    // An exit that waits on a tool call is not an exit, so the turn is
+                    // asked to stop and the leave does not wait for the answer.
+                    agent?.interrupt();
+                    requestExit(0);
+                    return true;
+                case 'quit':
+                    requestExit(0);
+                    return true;
+                case 'hand-back':
+                    return false;
             }
-            agent?.interrupt();
-            model.notice('interrupt requested');
-            tui.requestRender();
-            return true;
         },
     };
     disposers.push(tui.addInputListener(data => {
@@ -647,6 +820,9 @@ export function apply(ctx, config) {
     /** Give the keyboard back to the editor and answer whoever opened the picker. */
     const settlePicker = (id) => {
         const settle = pendingPicker?.settle;
+        // The screen goes back before the keyboard does: a box left behind a settled
+        // list would sit over the transcript until something else repainted.
+        pendingPicker?.release?.();
         pendingPicker = undefined;
         herdr.unblock();
         editor.disableSubmit = false;
@@ -672,9 +848,36 @@ export function apply(ctx, config) {
             return error instanceof Error ? error.message : String(error);
         }
     };
-    /** Take the keyboard for a picker and answer with the id it settled on. */
-    const openPicker = (picker, vet) => new Promise(resolve => {
-        pendingPicker = { picker, settle: resolve, vet };
+    /**
+     * Take the keyboard for a picker and answer with the id it settled on.
+     *
+     * Where the list is drawn is the caller's decision, because it is a decision
+     * about the reader's attention. A list that is the destination — a session to
+     * open, a model to switch to — joins the transcript and is read with it. A
+     * list that is a reference for the work in front of the reader is drawn over
+     * that work instead, so looking something up does not cost them their place.
+     * The keyboard is owned the same way either way.
+     */
+    const openPicker = (picker, vet, placement = 'inline') => new Promise(resolve => {
+        const overlay = placement === 'popup'
+            ? tui.showOverlay(new PickerPopup(rows => picker.card(rows), () => terminal.rows, theme), {
+                width: popupWidth(terminal.columns),
+                maxHeight: POPUP_MAX_HEIGHT,
+                anchor: 'center',
+                margin: 1,
+                // The surface's own listener reads every press before a focused
+                // component does, so the box needs no focus to be driven; taking it
+                // would only move focus away from where the reader left it.
+                nonCapturing: true,
+            })
+            : undefined;
+        pendingPicker = {
+            picker,
+            settle: resolve,
+            vet,
+            card: overlay === undefined ? () => picker.card() : undefined,
+            release: overlay === undefined ? undefined : () => overlay.hide(),
+        };
         // A picker owns the keyboard exactly as a gate does: nothing moves until
         // the reader chooses, so it is the same kind of wait.
         herdr.block(picker.card().title);
@@ -682,6 +885,36 @@ export function apply(ctx, config) {
         tui.setFocus(null);
         tui.requestRender();
     });
+    /**
+     * Open the key map over the surface.
+     *
+     * Nothing here is a pick: a row names an action and the keys reaching it, so
+     * the id the list settles on is thrown away. What the reader came for is the
+     * list itself, and the filter that narrows it.
+     */
+    const openKeyMap = (layer) => {
+        void openPicker(new KeymapPicker(() => keymap, layer), undefined, 'popup');
+    };
+    /**
+     * Choose a theme from a list the screen follows.
+     *
+     * Enter writes the choice through the settings document, the same path a typed
+     * name takes, so what lands is what the reader was looking at. Leaving the list
+     * restores the theme in force, because the document never changed while they
+     * looked.
+     */
+    const openThemePicker = async () => {
+        const picked = await openPicker(new ThemePicker(() => themeLibrary, () => appliedSection?.theme, () => keymap, theme => showTheme(theme?.name)));
+        if (picked === undefined) {
+            showTheme(undefined);
+            return;
+        }
+        // The row stays on screen until the document carries it: restoring first
+        // would flash the theme the reader just left. The write clears the preview as
+        // it lands, and a write that fails says so, leaving a theme that is still one
+        // of theirs rather than shades nothing chose.
+        chooseTheme(picked);
+    };
     /**
      * Reverse search over recorded prompts, seeded with whatever is in the bar.
      *
@@ -718,13 +951,12 @@ export function apply(ctx, config) {
         return await openPicker(new PresetPicker(() => presetRows, () => currentId, () => keymap));
     };
     /**
-     * The prompt bank for this working directory.
+     * The prompt bank for the session this surface drives.
      *
      * The surface owns the editor, the picker, and the notices, so the bank is
      * handed the few things it needs to reach them and nothing else: the commands
      * stay free of terminal state and are exercised without one in the tests.
      */
-    const stashCwdLabel = shortPath(process.cwd(), process.env.HOME);
     stash = new PromptStash({
         getEditorText: () => editor.getExpandedText(),
         setEditorText: text => {
@@ -732,13 +964,65 @@ export function apply(ctx, config) {
             tui.requestRender();
         },
         // A question answers in this editor, so a draft written into a borrowed bar
-        // would become somebody's answer instead of a parked prompt.
-        editorIsAvailable: () => !promptBar.isBorrowed(),
+        // would become somebody's answer instead of a parked prompt. An editor
+        // holding the draft in another program owns it just as firmly: a pop that
+        // landed then would be deleted from the bank and then overwritten.
+        editorIsAvailable: () => !promptBar.isBorrowed() && !handedOver,
         notice: message => model.notice(message),
         pick: (entries, label) => openPicker(new StashPicker(entries, label, () => keymap)),
         confirm: async (count) => confirmedClear(await openPicker(new StashConfirmPicker(count, () => keymap))),
         render: () => tui.requestRender(),
-    }, { cwd: process.cwd() });
+    }, 
+    // The bank follows the session this surface drives, not the directory it
+    // runs in: two terminals in one checkout keep separate drafts, and a resume
+    // finds the ones it parked. Read per command so a switch retargets it.
+    { sessionId: () => String(activeSession) });
+    /**
+     * The reader's own editor, opened over the draft the bar holds.
+     *
+     * The screen is handed over rather than drawn beside: an editor needs the
+     * terminal, so this is the one moment the surface is not the process painting
+     * on it. Every failure is reported as a notice and leaves the bar as it was,
+     * because the caller is a key press with nowhere to put an error.
+     */
+    const externalEditor = new ExternalEditor({
+        suspend: () => {
+            handedOver = true;
+            try {
+                // The frame is left in place rather than repainted into the normal
+                // buffer: the editor is about to paint over that same screen.
+                tui.stop({ preserveScreen: true });
+            }
+            catch (error) {
+                // A stop that failed leaves the screen ours; leaving the flag up would
+                // suppress every later title and defer every exit for good.
+                handedOver = false;
+                throw error;
+            }
+        },
+        resume: () => {
+            // Whatever the host unloaded is not coming back: starting it again would
+            // paint on a terminal this process is done with, into listeners that are gone.
+            if (disposed)
+                return;
+            try {
+                tui.start();
+            }
+            finally {
+                handedOver = false;
+            }
+            // Entering the alternate screen clears it, and any render asked for while
+            // the child owned the terminal was dropped after setting the very flag that
+            // makes the next ordinary request a no-op: without a forced one the reader
+            // would get a blank screen with a working keyboard under it.
+            tui.requestRender(true);
+            // The title is state this surface owns and the handoff swallowed any change
+            // to it, so a turn that ended while the editor was open would leave
+            // "working" up until the next turn.
+            writeTerminal(windowTitle(process.cwd(), turnOpen ? 'working' : 'ready'));
+        },
+        notice: message => model.notice(message),
+    });
     /** Title the listed sessions without making the reader wait for the slowest log. */
     const loadTitles = async (history, sessions, titles) => {
         const queue = [...sessions];
@@ -810,21 +1094,21 @@ export function apply(ctx, config) {
      */
     const foldCursor = new FoldCursor();
     /** Feed one durable event to the model, unless a fold has already folded it. */
-    const applyDurable = (event) => {
-        if (foldCursor.accept(event))
+    const applyDurable = (session, event) => {
+        if (foldCursor.accept(session, event))
             applyEvent(event);
     };
     const foldHistory = async (id) => {
         // Resolved before the fold so every card reads its tool through the scope
         // that actually registered it; a stored session nobody runs has none.
         presentScope = ctx.agents?.get(id);
-        // Every fold starts a cleared transcript, so this session's own numbering is
-        // where the cursor begins rather than the previous session's.
+        // Every fold starts a cleared transcript, so a session already known to the
+        // cursor is read from its first event rather than from where it left off.
         foldCursor.reset();
         const inMemory = liveSession(id)?.snapshotEvents?.();
         if (inMemory !== undefined) {
             for (const event of inMemory)
-                applyDurable(event);
+                applyDurable(id, event);
             return inMemory.length;
         }
         const history = createSessionHistory(ctx);
@@ -832,7 +1116,7 @@ export function apply(ctx, config) {
             return 0;
         const events = await history.read(id);
         for (const event of events)
-            applyDurable(event);
+            applyDurable(id, event);
         return events.length;
     };
     const replayHistory = async (id) => {
@@ -948,6 +1232,9 @@ export function apply(ctx, config) {
         activeSession = id;
         viewedSession = id;
         agent = handle;
+        // The bank follows the session, so the footer stops counting the drafts of
+        // the session just left and the next command reads this session's file.
+        void stash?.open();
         // The agent's own id is reported rather than the requested one: a resume can
         // be answered by the session the log actually holds.
         herdr.session({
@@ -1657,21 +1944,66 @@ export function apply(ctx, config) {
             case 'todo':
                 runTodoCommand();
                 return;
-            case 'theme':
-                for (const line of renderThemeTable(toOverrides(readSection())))
-                    model.notice(line);
-                tui.requestRender();
+            case 'theme': {
+                const argument = submission.argument;
+                // A bare command is the list: a theme is judged by looking at it, so
+                // choosing one belongs in a list the screen follows rather than in a name
+                // the reader has to already know.
+                if (argument === '') {
+                    void openThemePicker();
+                    return;
+                }
+                const [head = '', ...rest] = argument.split(/\s+/u);
+                // The table answers the other question a theme raises — which layer drew a
+                // shade — and stays reachable by name now that the list has the command.
+                if (head === 'tokens') {
+                    for (const line of renderThemeTable(toOverrides(readSection(), themeLibrary), themeLibrary))
+                        model.notice(line);
+                    tui.requestRender();
+                    return;
+                }
+                // The one way a built-in becomes editable. Its file ships inside the
+                // package and the next version replaces it, so a reader who wants to
+                // change one needs a copy that is theirs — and the copy is a theme the
+                // moment it lands, which is why the table is re-read rather than patched.
+                if (head === 'export') {
+                    const chosen = rest.join(' ').trim();
+                    if (chosen === '') {
+                        model.notice(`theme export · which built-in? ${builtinNames(themeLibrary).join(' · ')}`);
+                        tui.requestRender();
+                        return;
+                    }
+                    const outcome = exportTheme(themeLibrary, chosen);
+                    if (outcome.ok) {
+                        themeLibrary = loadThemes(themesHome, builtinThemesDir());
+                        model.notice(`theme · exported ${chosen} to ${outcome.path} · /theme ${outcome.select} applies it`);
+                    }
+                    else {
+                        model.notice(outcome.problem);
+                    }
+                    tui.requestRender();
+                    return;
+                }
+                // A name nothing answers to is refused by name, like an unknown key
+                // layer: the reader asked for something, so the answer lists names.
+                if (themeLibrary.get(head) === undefined) {
+                    model.notice(`unknown theme "${head}" · themes: ${themeLibrary.names().join(' · ')}`);
+                    tui.requestRender();
+                    return;
+                }
+                chooseTheme(head);
                 return;
+            }
             case 'keys': {
                 const layer = submission.argument === '' ? undefined : keymapLayer(submission.argument);
+                // A layer that does not exist is not a filter that matches nothing: the
+                // reader asked for something by name, so the answer names the names.
                 if (submission.argument !== '' && layer === undefined) {
                     model.notice(`unknown layer "${submission.argument}" · ${KEYMAP_LAYERS.join(' ')}`);
+                    tui.requestRender();
+                    return;
                 }
-                else {
-                    for (const line of renderKeymap(keymap, layer))
-                        model.notice(line);
-                }
-                tui.requestRender();
+                openKeyMap(layer);
                 return;
             }
             case 'copy':
@@ -1699,7 +2031,7 @@ export function apply(ctx, config) {
                 void stash?.apply(submission.selector);
                 return;
             case 'stash-list':
-                void stash?.list(stashCwdLabel);
+                void stash?.list(String(activeSession));
                 return;
             case 'stash-drop':
                 void stash?.drop(submission.selector);
@@ -1707,6 +2039,24 @@ export function apply(ctx, config) {
             case 'stash-clear':
                 void stash?.clear();
                 return;
+            case 'editor':
+                void externalEditor.edit(editor.getExpandedText()).then(text => {
+                    if (text !== undefined) {
+                        // A gate can open while the child owns the screen, and the bar then
+                        // holds somebody's answer: the edited draft waits behind it instead
+                        // of being written into a question the reader never answered.
+                        if (promptBar.isBorrowed())
+                            promptBar.replaceHeld(text);
+                        else
+                            editor.setText(text);
+                        tui.requestRender();
+                    }
+                    const pendingExit = deferredExit;
+                    deferredExit = undefined;
+                    if (pendingExit !== undefined)
+                        requestExit(pendingExit.code, pendingExit.reason);
+                });
+                return;
             case 'status': {
                 const facts = statusFacts();
                 const context = facts.contextTokens === undefined
@@ -1785,17 +2135,17 @@ export function apply(ctx, config) {
             if (event.type === 'turn/start') {
                 turnOpen = true;
                 turnStartedAt = Date.now();
-                terminal.write(windowTitle(process.cwd(), 'working'));
+                writeTerminal(windowTitle(process.cwd(), 'working'));
                 herdr.working();
             }
             if (event.type === 'turn/end') {
                 const ranFor = turnStartedAt === undefined ? 0 : Date.now() - turnStartedAt;
                 turnOpen = false;
                 turnStartedAt = undefined;
-                terminal.write(windowTitle(process.cwd(), 'ready'));
+                writeTerminal(windowTitle(process.cwd(), 'ready'));
                 herdr.idle();
                 if (shouldRingBell({ bell: resolved.bell, ranForMs: ranFor, exiting: exited }))
-                    terminal.write(BELL);
+                    writeTerminal(BELL);
                 // A job the turn started may have settled while the reader was watching
                 // something else, and nothing else refreshes a live board.
                 refreshJobs();
@@ -1808,7 +2158,7 @@ export function apply(ctx, config) {
         if (session.id !== viewedSession)
             return;
         presentScope = ctx.agents?.get(session.id);
-        applyDurable(event);
+        applyDurable(session.id, event);
         tui.requestRender();
     }));
     /**
@@ -1895,14 +2245,18 @@ export function apply(ctx, config) {
             return;
         refreshJobs();
     }) ?? (() => { }));
+    // The transcript belongs to the session on screen, while status, the bell,
+    // and the queue stay with the agent this terminal drives. A live delta or a
+    // failure folded into the wrong model would print one session's words as
+    // another's, and the durable copy that follows would never correct it.
     disposers.push(ctx.on('agent/error', payload => {
-        if (payload.agent.id !== activeSession)
+        if (payload.agent.id !== viewedSession)
             return;
         model.reportError(payload.error);
         tui.requestRender();
     }));
     disposers.push(ctx.on('agent/assistant-stream', payload => {
-        if (payload.agent.id !== activeSession)
+        if (payload.agent.id !== viewedSession)
             return;
         if (payload.frame.type !== 'chunk')
             return;
@@ -1927,6 +2281,42 @@ export function apply(ctx, config) {
         view.invalidate();
         tui.requestRender();
     }));
+    /**
+     * The reader's own themes: created, reported, and then watched.
+     *
+     * Created because a directory that is not there is a command that cannot work —
+     * `/theme export` names a path the reader should find where the surface said it
+     * would be. Watched because a theme is a file they are editing by hand, so
+     * saving one is how they ask for it; a session that needed a restart per shade
+     * would make the whole table useless for tuning. Everything unreadable is
+     * reported through the deferred notice rather than stderr, which the alternate
+     * screen is drawn over.
+     */
+    let reportedThemes = new Set();
+    const reportThemes = () => {
+        // Only what is newly wrong: the watcher re-reads the whole directory on every
+        // save, so an unfixed file would otherwise repeat its complaint on each one,
+        // and a reader who has just been told is not helped by being told again.
+        const problems = themeLibrary.problems();
+        for (const problem of problems) {
+            if (!reportedThemes.has(problem))
+                settingsNotice.post(problem);
+        }
+        reportedThemes = new Set(problems);
+    };
+    for (const problem of ensureThemesHome(themesHome))
+        settingsNotice.post(problem);
+    reportThemes();
+    disposers.push(watchThemes(themesHome, () => {
+        themeLibrary = loadThemes(themesHome, builtinThemesDir());
+        reportThemes();
+        // The file that was just saved may be the theme already in force, so the
+        // table is rebuilt rather than only repainted.
+        applySettings();
+        markdown.invalidate();
+        view.invalidate();
+        tui.requestRender();
+    }));
     const degraded = describeMissingOptional(probe);
     if (degraded !== undefined)
         model.notice(degraded);
@@ -1968,10 +2358,7 @@ export function apply(ctx, config) {
         if (!resolved.resumePicker)
             await presetFor(resolved.sessionId, resolved.resume, undefined);
         tui.start();
-        // Loaded now so the footer's count is real from the first paint, and because
-        // a bank that cannot be read should say so before a reader trusts it.
-        void stash?.open();
-        terminal.write(windowTitle(process.cwd(), 'ready'));
+        writeTerminal(windowTitle(process.cwd(), 'ready'));
         // Claiming the pane's agent row does not wait for a session: the pane is
         // already on screen and already idle, and a session may still be chosen.
         herdr.publish();