@sagmans/dsh-tui 0.2.0 → 0.4.0

package/lib/index.js

@@ -4,18 +4,23 @@ import { resolve } from 'node:path';
 import { ProcessTerminal, ScrollView, VStack, 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";
 import { createPresetRoster, parsePresetArgument } from "./agent/presets.js";
 import { createToolPresenter } from "./agent/present.js";
 import { forkPoint } from "./agent/fork.js";
 import { PROFILE_NAME, resumeHint } from "./identity.js";
 import { createStatusFacts } from "./agent/status.js";
-import { ModelSwitch, createModelCatalog, parseModelArgument } from "./agent/model.js";
+import { ModelSwitch, createModelCatalog, parseModelArgument, readModelRouteKey } from "./agent/model.js";
 import { JOB_READ_LINES, createJobDirectory, describeJobs, parseJobsArgument } from "./jobs.js";
 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 { createCompletionProvider } from "./input/completion.js";
+import { ghostSuffix } from "./input/ghost.js";
 import { LOCAL_COMMANDS, classifySubmission } from "./input/submission.js";
+import { createDeferredNotice } from "./settings-notice.js";
+import { ChordReader, DEFAULT_PREFIX_KEYS, DEFAULT_PREFIX_WINDOW_S, chordBindings, chordKeysLine, installKeybindings, surfaceKeysLine, } from "./input/keymap.js";
+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";
@@ -23,21 +28,32 @@ import { WarningSafeTui } from "./terminal/warning-screen.js";
 import { BELL, shouldRingBell } from "./terminal/bell.js";
 import { clipboardSequence } from "./terminal/clipboard.js";
 import { CLEAR_TITLE, windowTitle } from "./terminal/title.js";
+import { sessionStartReason } from "./herdr/state.js";
+import { createHerdrReporter } from "./herdr/reporter.js";
 import { defaultExportFile, transcriptToText } from "./export.js";
 import { createTheme, forwardEditorTheme, forwardMarkdownTheme } from "./theme.js";
 import { detectColourMode } from "./theme-capability.js";
-import { defaultSettings, readScope, toOverrides, TUI_SETTINGS_NAMESPACE, TuiSettingsSchema } from "./theme-settings.js";
+import { defaultSettings, readScope, settingsProblemMessage, toOverrides, TUI_SETTINGS_NAMESPACE, TuiSettingsSchema } from "./theme-settings.js";
+import { pendingPrompts } from "./queue.js";
 import { renderThemeTable } from "./theme-command.js";
+import { KEYMAP_LAYERS, keymapLayer, renderKeymap } from "./keys-command.js";
+import { resetSequence } from "./theme-tokens.js";
 import { SessionId } from '@deepseek-ai/dsh-session';
 import { formatTokens } from "./tokens.js";
 import { TranscriptModel } from "./transcript.js";
-import { WorkFold, describeTodos } from "./work.js";
+import { WorkFold, describeTodos, planSelectedActive, planToggleLine, readPlanState } from "./work.js";
 import { WorkDock } from "./ui/dock.js";
-import { BoxedEditor } from "./ui/editor.js";
+import { GateInputBar } from "./ui/gate-input.js";
+import { HistoryPicker } from "./ui/history-picker.js";
+import { PromptBar } from "./ui/prompt.js";
 import { MarkdownRenderer } from "./ui/markdown.js";
-import { EffortPicker, PROVIDER_DEFAULT_EFFORT_ID, PresetPicker, SessionPicker, effortChoices, } from "./ui/picker.js";
-import { StatusBar } from "./ui/status.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 { DEFAULT_VIEW_STATE, TranscriptView } from "./ui/view.js";
+import { PromptStash } from "./stash.js";
+import { confirmedClear, StashConfirmPicker, StashPicker } from "./ui/stash-picker.js";
 export const name = 'tui';
 /**
  * Services the surface cannot run without.
@@ -47,14 +63,18 @@ export const name = 'tui';
  * every card to a bare generic row.
  */
 export const inject = ['agents', 'tools'];
-/** Keys the surface answers itself, listed wherever the reader asks for help. */
-const LOCAL_KEYS = 'ctrl+o tool detail · ctrl+y nested calls · shift+tab reasoning · ctrl+t reasoning effort · ctrl+b back to this session · ctrl+c interrupt or exit';
-/** The one thing to say about a view a reader did not open. */
-const LOCAL_KEYS_BACK = 'ctrl+b returns';
+/** One second in the unit a chord window is scheduled in. */
+const MS_PER_SECOND = 1000;
+/** What the back hint names when the reader has unbound the key it would advertise. */
+const BACK_HINT_FALLBACK = 'ctrl+b';
+/** What the reader presses to leave a view they did not open. */
+const backHint = (map) => `${hintKeys(map, 'surface.back') || BACK_HINT_FALLBACK} returns to this session`;
 /** Stored sessions titled at once when the picker opens. */
 const TITLE_CONCURRENCY = 4;
 /** How often the running-state clock repaints while a turn is open. */
 const STATUS_TICK_MS = 1000;
+/** Reverse video for the cell the cursor occupies, so a ghost keeps the cursor visible. */
+const GHOST_CURSOR_PREFIX = '\u001b[7m';
 function asRecord(value) {
     return typeof value === 'object' && value !== null ? value : undefined;
 }
@@ -108,11 +128,14 @@ export function apply(ctx, config) {
      * late-bound read that the injection point and the change event both use.
      */
     let readSection = () => defaultSettings();
-    /** A refused settings edit, kept until the surface can show it: stderr is behind the alt screen. */
-    let pendingSettingsProblem;
+    /**
+     * 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());
-    const applyTheme = () => {
-        current = createTheme(themeMode(), toOverrides(readSection()));
+    const applyTheme = (section) => {
+        current = createTheme(themeMode(), toOverrides(section));
     };
     const theme = {
         get revision() { return current.revision; },
@@ -137,13 +160,63 @@ export function apply(ctx, config) {
      */
     const viewState = { ...DEFAULT_VIEW_STATE };
     /**
-     * Seed the nested-call display the reader configured.
+     * How a reply's mermaid fences draw, seeded from the reader's section.
      *
-     * The key toggles it for one session, but a settings edit is a deliberate act,
-     * so it re-seeds and becomes the new starting point.
+     * The transform reads this per render instead of capturing it, because the
+     * settings document is hot-reloaded and a session already on screen has to
+     * follow the edit.
      */
-    const applyDisplay = () => {
-        viewState.expandSubCalls = readSection().subcalls === 'inline';
+    let mermaidMode = defaultSettings().mermaid;
+    /** 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;
+    /** Every action's keys in force; the settings document owns it and a press reads it live. */
+    let keymap = defaultKeymap();
+    /** Whether prompts are recorded and offered, and the cap on how many; the settings document owns all three. */
+    let historyEnabled = defaultSettings().history.enabled;
+    let historyGhost = defaultSettings().history.ghost;
+    let historyMaxEntries = defaultSettings().history.maxEntries;
+    /**
+     * The chord between a prefix and the action that follows it.
+     *
+     * Built here, before the terminal exists, because the settings scope applies
+     * first and has to be able to end a chord armed under the keymap it replaced.
+     * The repaint the window also wants is late-bound: only a key press reaches
+     * it, and no key can arrive before the surface has started.
+     */
+    const keyChord = new ChordReader(() => prefixKeys, () => chordBindings(keymap), () => prefixWindowMs, () => tui.requestRender());
+    /**
+     * Seed the display the reader configured.
+     *
+     * 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.
+     */
+    const applyDisplay = (section) => {
+        viewState.expandSubCalls = section.subcalls === 'inline';
+        mermaidMode = section.mermaid;
+        prefixKeys = section.prefixes;
+        prefixWindowMs = section.prefixWindow * MS_PER_SECOND;
+        keymap = section.keymap;
+        // Installed where the library reads it, so a remap lands on the next press
+        // rather than at the next restart.
+        installKeybindings(keymap);
+        historyEnabled = section.history.enabled;
+        historyGhost = section.history.ghost;
+        historyMaxEntries = section.history.maxEntries;
+        // A chord armed under the keymap the reader just replaced is not their chord.
+        keyChord.disarm();
+    };
+    /**
+     * Read the reader's section once and apply everything it configures.
+     *
+     * One read per change, because a refused section is reported on the way past:
+     * reading it once per field would show the reader the same refusal twice.
+     */
+    const applySettings = () => {
+        const section = readSection();
+        applyTheme(section);
+        applyDisplay(section);
     };
     /**
      * Own the section, so the harness validates and persists it for the reader.
@@ -154,10 +227,23 @@ export function apply(ctx, config) {
      * may be touched in.
      */
     ctx.inject(['settings'], settingsCtx => {
-        const scope = settingsCtx.settings.register(TUI_SETTINGS_NAMESPACE, TuiSettingsSchema);
-        readSection = () => readScope(scope, message => { pendingSettingsProblem = message; });
-        applyTheme();
-        applyDisplay();
+        // Registration parses the document against the schema, so a section the
+        // schema itself refuses throws here — inside a fiber whose failure the
+        // screen never shows. Reporting it through the same holder keeps a typo
+        // from costing the reader every setting they wrote, silently.
+        let scope;
+        try {
+            scope = settingsCtx.settings.register(TUI_SETTINGS_NAMESPACE, TuiSettingsSchema);
+        }
+        catch (error) {
+            // Nothing registered means nothing to read, so the reader's switch cannot
+            // be confirmed: recording stays off rather than falling back to on.
+            historyEnabled = false;
+            settingsNotice.post(settingsProblemMessage(error) + ' · prompt history stays off until the section parses');
+            return;
+        }
+        readSection = () => readScope(scope, message => settingsNotice.post(message));
+        applySettings();
     });
     /**
      * The agent scope the tool presenter resolves against.
@@ -169,6 +255,33 @@ export function apply(ctx, config) {
      */
     let presentScope;
     const model = new TranscriptModel(createToolPresenter(ctx, () => presentScope));
+    /**
+     * The reader's prompt history: global across projects, recorded from every
+     * submitted line, and offered back as they type. Built before the bar so its
+     * first load cannot race the first suggestion.
+     */
+    const promptHistory = createPromptHistory({
+        cap: () => historyMaxEntries,
+        warn: message => {
+            model.notice(message);
+            tui.requestRender();
+        },
+    });
+    /**
+     * The dimmed completion drawn from recorded prompts.
+     *
+     * Colour is the affordance: with styling off the suggestion would be
+     * unreadable text the reader could still accept, which is worse than none.
+     * The cursor cell is also reversed so the cursor stays visible on the ghost.
+     */
+    const ghostBrush = {
+        enabled: () => historyEnabled && historyGhost && theme.color && theme.visible('editor.ghost'),
+        suggestion: input => ghostSuffix({ entries: promptHistory.entries(), ...input }),
+        paint: (text, cell) => {
+            const styled = theme.style('editor.ghost', text);
+            return cell === 'cursor' ? GHOST_CURSOR_PREFIX + styled + resetSequence() : styled;
+        },
+    };
     const work = new WorkFold();
     const modelSwitch = new ModelSwitch();
     const agentPresets = createPresetRoster(ctx);
@@ -197,7 +310,7 @@ export function apply(ctx, config) {
     let jobs = [];
     const roster = new SubagentRoster();
     const subagentControl = createSubagentControl(ctx);
-    const markdown = new MarkdownRenderer(theme.markdown);
+    const markdown = new MarkdownRenderer(theme.markdown, createMermaidTransform({ theme, mode: () => mermaidMode }));
     const restore = createRestoreRegistry();
     const terminal = new ProcessTerminal();
     const tui = new WarningSafeTui(terminal);
@@ -207,14 +320,22 @@ export function apply(ctx, config) {
     let viewedSession = resolved.sessionId;
     let pending;
     let pendingPicker;
-    /** A pick being vetted owns the keyboard: a key would answer what is unanswered. */
+    /** A pick being vetted owns the list, not the keyboard: filtering stays live while its verdict is read. */
     let vetting = false;
     const view = new TranscriptView(model, theme, markdown, {
         state: () => viewState,
         gate: () => pending?.gate.card(),
         picker: () => pendingPicker?.picker.card(),
+        keys: () => keymap,
     });
-    const editor = new BoxedEditor(tui, theme.editor);
+    // 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
+    // point installs over it, which is why the bar reads the map per press.
+    installKeybindings(keymap);
+    const editor = new GateInputBar(tui, theme.editor, () => keymap, ghostBrush);
+    // Answers are written in the reader's own editor, which is why a question
+    // borrows the bar instead of drawing a second one beside it.
+    const promptBar = new PromptBar(editor);
     const disposers = [];
     // The presenter closure outlives the composition's own teardown, so it must
     // not keep an agent alive after its world unwinds.
@@ -232,25 +353,56 @@ export function apply(ctx, config) {
         jobs = agent === undefined || jobDirectory === undefined ? [] : jobDirectory.list(agent.agent);
         tui.requestRender();
     };
+    // The bank is built once the picker exists to answer for it, so the status
+    // source is late-bound: the footer must not read a half-constructed stash.
+    let stash;
     const statusFacts = createStatusFacts(ctx, {
         sessionId: () => activeSession,
         activity: () => ({ running: turnOpen, startedAt: turnStartedAt }),
         override: () => modelSwitch.current(),
         home: process.env.HOME,
+        chord: () => keyChord.hint(),
+        // Read per paint rather than written into the marker the view left behind:
+        // a hint stored with the transcript would keep naming the key of the day it
+        // was written, and the reader may remap it with the row already on screen.
+        back: () => (viewedSession === activeSession ? undefined : backHint(keymap)),
+        stash: () => stash?.entryCount,
     });
     const statusBar = new StatusBar(statusFacts, theme);
     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);
     // Only a running turn has anything to say over time, so the clock stops with it.
     const statusTicker = setInterval(() => {
         if (turnOpen)
             tui.requestRender();
     }, STATUS_TICK_MS);
     disposers.push(() => clearInterval(statusTicker));
+    // A window that outlived the surface would repaint a screen that is gone.
+    disposers.push(() => keyChord.disarm());
+    // A containing Herdr is told what this pane is doing; away from one the
+    // reporter is inert, so the surface never depends on being multiplexed.
+    const herdr = createHerdrReporter();
+    // Kept out of the disposal list on purpose: the row is handed back before
+    // this stops guarding it, so a host that leaves during the release still
+    // releases synchronously.
+    const unregisterExit = herdr.registerExitRelease();
     restore.add(() => tui.stop());
     ctx.effect(() => () => {
+        // 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
+        // reports already on the wire are settled first, because Herdr ignores a
+        // release for a pane nothing has claimed yet — the report that followed it
+        // would otherwise claim the row back. The promise is returned so a host that
+        // waits for teardown waits for the row too, and the exit listener outlives
+        // the wait, so one that does not still hands the row back synchronously.
+        const released = herdr.release().catch(() => undefined);
         restore.restore();
         for (const dispose of disposers.reverse())
             dispose();
+        return released.finally(unregisterExit);
     });
     tui.setLayoutRoot(new VStack([
         {
@@ -262,7 +414,11 @@ export function apply(ctx, config) {
         // 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 },
-        { component: new VStack([{ component: editor, basis: 'auto', shrink: 1, minSize: 1 }]), basis: 'auto', shrink: 1, minSize: 1 },
+        // 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.setFocus(editor);
@@ -271,37 +427,104 @@ export function apply(ctx, config) {
             return;
         exited = true;
         clearInterval(statusTicker);
-        // Hand the window label back before the screen does, so a shell that sets
-        // its own title can take over cleanly.
+        // The screen goes back at once, so leaving feels like leaving; the row goes
+        // back behind it. Reports already on the wire are settled first, because
+        // Herdr ignores the release of a pane nothing has claimed yet — the report
+        // that followed it would otherwise claim the row back during shutdown.
         terminal.write(CLEAR_TITLE);
         restore.restore();
-        // Everything below is written after the release: the alternate screen closes
-        // over whatever was painted on it, and a failure nobody can read is not a
-        // failure that was reported.
-        if (reason !== undefined)
-            terminal.write(`\ndsh-tui: ${reason}\n`);
-        // The hint is computed here rather than read from the context because only
-        // the surface knows which session it is leaving: a fork or a switch moves it.
-        // A run that opened nothing has nothing to offer back: the identity it was
-        // launched with names no log, so pointing at it would send the reader to a
-        // conversation that does not exist.
-        if (sessionOpened)
-            terminal.write(`\n${resumeHint(String(activeSession), PROFILE_NAME)}\n`);
-        appExit(code);
+        void herdr
+            .release()
+            // Nobody is left to report a release that failed on the way out, and a
+            // row that could not be cleared is not a reason to keep the process.
+            .catch(() => undefined)
+            .finally(() => {
+            // Everything below is written after the release: a failure nobody can
+            // read is not a failure that was reported.
+            if (reason !== undefined)
+                terminal.write(`\ndsh-tui: ${reason}\n`);
+            // The hint is computed here rather than read from the context because
+            // only the surface knows which session it is leaving: a fork or a
+            // switch moves it. A run that opened nothing has nothing to offer back:
+            // the identity it was launched with names no log, so pointing at it
+            // would send the reader to a conversation that does not exist.
+            if (sessionOpened)
+                terminal.write(`\n${resumeHint(String(activeSession), PROFILE_NAME)}\n`);
+            appExit(code);
+        });
     };
     const openGate = (next) => {
         pending = next;
+        // The card's own title names the decision, which is what a reader glancing
+        // at a wall of panes needs in order to know which one to open.
+        herdr.block(next.gate.card().title);
         // A gate owns the keyboard: the editor must not collect the decision keys.
         editor.disableSubmit = true;
         tui.setFocus(null);
+        // A question is answered in this editor, which the gate draws under the row
+        // being answered, so the hardware cursor belongs to it while it is borrowed.
+        // It is set after the focus is cleared, which unmarks the component it left.
+        editor.focused = next.kind === 'question';
         tui.requestRender();
     };
     const closeGate = () => {
         pending = undefined;
+        herdr.unblock();
         editor.disableSubmit = false;
+        // The question is answered or skipped, so the reader gets their prompt back
+        // in the bar they left it in.
+        promptBar.giveBack();
         tui.setFocus(editor);
         tui.requestRender();
     };
+    /**
+     * What each key the surface answers itself does; false hands the press back.
+     *
+     * Keyed by the table's own ids, so a key added to {@link SURFACE_ACTIONS}
+     * without a handler here fails to compile rather than doing nothing.
+     */
+    const surfaceActions = {
+        toolDetail: () => {
+            viewState.expandCards = !viewState.expandCards;
+            tui.requestRender();
+            return true;
+        },
+        subCalls: () => {
+            viewState.expandSubCalls = !viewState.expandSubCalls;
+            tui.requestRender();
+            return true;
+        },
+        reasoning: () => {
+            viewState.expandReasoning = !viewState.expandReasoning;
+            tui.requestRender();
+            return true;
+        },
+        effort: () => {
+            void openEffortPicker();
+            return true;
+        },
+        history: () => {
+            void openHistoryPicker();
+            return true;
+        },
+        back: () => {
+            if (viewedSession !== activeSession)
+                void showAgentSession();
+            return true;
+        },
+        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;
+            }
+            agent?.interrupt();
+            model.notice('interrupt requested');
+            tui.requestRender();
+            return true;
+        },
+    };
     disposers.push(tui.addInputListener(data => {
         // A key arrives as a press and a release once the surface asks the terminal
         // to report key events, and this library drops the release only for the
@@ -333,13 +556,19 @@ export function apply(ctx, config) {
             return { consume: true };
         }
         if (pendingPicker !== undefined) {
-            if (vetting)
-                return { consume: true };
             const action = pendingPicker.picker.handleKey(data);
             if (action === undefined) {
                 tui.requestRender();
                 return { consume: true };
             }
+            if (vetting) {
+                // A refusal check must not take the keyboard with it: the reader keeps
+                // filtering and can still leave, while a second pick waits for the
+                // first verdict rather than racing it.
+                if (action.kind === 'cancel')
+                    settlePicker(undefined);
+                return { consume: true };
+            }
             if (action.kind === 'cancel') {
                 settlePicker(undefined);
                 return { consume: true };
@@ -370,44 +599,23 @@ export function apply(ctx, config) {
             })();
             return { consume: true };
         }
-        // Detail the reader asked for is always available, even mid-turn: the
+        // A chord is the surface's second key: the prefix is consumed and the
+        // footer names what may follow, while a key that finishes nothing is handed
+        // on. Detail the reader asked for is always available, even mid-turn: the
         // collapsed view is a default, not the only state.
-        if (matchesKey(data, 'ctrl+o')) {
-            viewState.expandCards = !viewState.expandCards;
-            tui.requestRender();
-            return { consume: true };
-        }
-        if (matchesKey(data, 'shift+tab')) {
-            viewState.expandReasoning = !viewState.expandReasoning;
-            tui.requestRender();
-            return { consume: true };
-        }
-        if (matchesKey(data, 'ctrl+y')) {
-            viewState.expandSubCalls = !viewState.expandSubCalls;
+        const chorded = keyChord.handle(data);
+        if (chorded !== undefined) {
+            if (chorded.kind === 'action')
+                runSubmission(chorded.binding.submission);
             tui.requestRender();
             return { consume: true };
         }
-        if (matchesKey(data, 'ctrl+t')) {
-            void openEffortPicker();
-            return { consume: true };
-        }
-        if (matchesKey(data, 'ctrl+b')) {
-            if (viewedSession !== activeSession)
-                void showAgentSession();
-            return { consume: true };
-        }
-        // 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 (!matchesKey(data, 'ctrl+c'))
-            return undefined;
-        if (turnOpen) {
-            agent?.interrupt();
-            model.notice('interrupt requested');
-            tui.requestRender();
-            return { consume: true };
+        for (const binding of surfaceBindings(keymap)) {
+            if (!matchesKey(data, binding.key))
+                continue;
+            return surfaceActions[binding.action]() ? { consume: true } : undefined;
         }
-        requestExit(0);
-        return { consume: true };
+        return undefined;
     }));
     const registry = () => ctx.get('commands');
     /**
@@ -433,13 +641,14 @@ export function apply(ctx, config) {
     const askForSession = async (history, sessions) => {
         const titles = new Map();
         void loadTitles(history, sessions, titles);
-        const picked = await openPicker(new SessionPicker(sessions, () => titles), refuseReason);
+        const picked = await openPicker(new SessionPicker(sessions, () => titles, undefined, () => keymap), refuseReason);
         return picked === undefined ? undefined : SessionId(picked);
     };
     /** Give the keyboard back to the editor and answer whoever opened the picker. */
     const settlePicker = (id) => {
         const settle = pendingPicker?.settle;
         pendingPicker = undefined;
+        herdr.unblock();
         editor.disableSubmit = false;
         tui.setFocus(editor);
         settle?.(id);
@@ -466,10 +675,39 @@ export function apply(ctx, config) {
     /** 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 };
+        // 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);
         editor.disableSubmit = true;
         tui.setFocus(null);
         tui.requestRender();
     });
+    /**
+     * Reverse search over recorded prompts, seeded with whatever is in the bar.
+     *
+     * A pick replaces the draft; a cancel leaves it exactly as it was, because the
+     * list was opened to look rather than to lose what is already typed.
+     */
+    const openHistoryPicker = async () => {
+        if (!historyEnabled) {
+            model.notice('prompt history is disabled in ' + TUI_SETTINGS_NAMESPACE + ' settings');
+            tui.requestRender();
+            return;
+        }
+        if (promptHistory.entries().length === 0) {
+            const blocked = promptHistory.blockedReason();
+            model.notice(blocked === undefined ? 'no prompt history yet' : 'prompt history is unavailable: ' + blocked);
+            tui.requestRender();
+            return;
+        }
+        // The expanded text is what the reader wrote; a large paste sits in the bar
+        // as a marker, and seeding with it would filter out the prompt it came from.
+        const picked = await openPicker(new HistoryPicker(() => promptHistory.entries(), editor.getExpandedText(), () => keymap));
+        if (picked === undefined)
+            return;
+        editor.setText(picked);
+        tui.requestRender();
+    };
     /** The roster as the picker paints it, refreshed when the picker opens. */
     let presetRows = [];
     /** Choose the mode a session that has not started yet will run. */
@@ -477,8 +715,30 @@ export function apply(ctx, config) {
         if (agentPresets === undefined)
             return undefined;
         presetRows = await agentPresets.list();
-        return await openPicker(new PresetPicker(() => presetRows, () => currentId));
+        return await openPicker(new PresetPicker(() => presetRows, () => currentId, () => keymap));
     };
+    /**
+     * The prompt bank for this working directory.
+     *
+     * 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 => {
+            editor.setText(text);
+            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(),
+        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() });
     /** Title the listed sessions without making the reader wait for the slowest log. */
     const loadTitles = async (history, sessions, titles) => {
         const queue = [...sessions];
@@ -604,9 +864,7 @@ export function apply(ctx, config) {
             model.notice(`could not read that session: ${error instanceof Error ? error.message : String(error)}`);
         }
         const returned = id === activeSession && previous !== activeSession;
-        model.marker(returned
-            ? 'back to the session this terminal drives'
-            : `viewing ${id}${id === activeSession ? '' : ` — ${LOCAL_KEYS_BACK}`}`);
+        model.marker(returned ? 'back to the session this terminal drives' : `viewing ${id}`);
         tui.requestRender();
     };
     const showAgentSession = async () => {
@@ -690,6 +948,13 @@ export function apply(ctx, config) {
         activeSession = id;
         viewedSession = id;
         agent = handle;
+        // 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({
+            id: String(handle.sessionId),
+            cwd: process.cwd(),
+            reason: sessionStartReason({ forked: fork !== undefined, resumed: resume }),
+        });
         // A session with no history to fold still has to present its first live
         // card through the right scope, so the scope is set before any event can.
         presentScope = handle.agent;
@@ -966,19 +1231,11 @@ export function apply(ctx, config) {
         }
         const command = parseModelArgument(argument, catalog.providers(), modelSwitch.current());
         switch (command.kind) {
-            case 'current': {
-                const facts = statusFacts();
-                const current = modelSwitch.current();
-                const route = current === undefined
-                    // Without a choice of its own the surface reports what the next step
-                    // would actually use, not that it has no opinion.
-                    ? `${facts.model ?? 'unset'}${facts.effort === undefined ? '' : ` (${facts.effort})`} · composition default`
-                    : `${current.provider}/${current.model}${current.reasoningEffort === undefined ? '' : ` (${current.reasoningEffort})`}`;
-                const providers = catalog.providers().map(provider => provider.id);
-                model.notice(`model ${route} · providers: ${providers.length === 0 ? 'none' : providers.join(', ')} · /model <provider>/<model>[/<effort>] switches, /model <provider> lists its models`);
-                tui.requestRender();
+            case 'current':
+                // Choosing by eye is the point of a terminal selector; the picker
+                // heads itself with the route the next step will actually use.
+                void openModelPicker();
                 return;
-            }
             case 'list-models':
                 void catalog.models(command.provider).then(entries => {
                     model.notice(entries.length === 0
@@ -1038,6 +1295,124 @@ export function apply(ctx, config) {
         model.notice(`reasoning effort for ${provider}/${modelId} set to ${effortId === PROVIDER_DEFAULT_EFFORT_ID ? 'provider default' : effortId} for the next step`);
         tui.requestRender();
     };
+    /** Whether a model picker's catalog is being read, so a second key cannot race it. */
+    let openingModels = false;
+    /**
+     * The route the next step would actually use.
+     *
+     * Without a choice of its own the surface reports the composition default,
+     * not that it has no opinion: the picker's heading and its marked row have to
+     * agree with the status line about the route in force.
+     */
+    const effectiveRoute = () => {
+        const chosen = modelSwitch.current();
+        if (chosen !== undefined)
+            return chosen;
+        const facts = statusFacts();
+        if (facts.provider === undefined || facts.model === undefined)
+            return undefined;
+        return {
+            provider: facts.provider,
+            model: facts.model,
+            ...facts.effort === undefined ? {} : { reasoningEffort: facts.effort },
+        };
+    };
+    /** Put the reader's route choice in force for the next step. */
+    const applyRoute = (route) => {
+        const current = effectiveRoute();
+        // The levels belong to the route, so a switch clears an explicit effort
+        // while re-picking the route already in force is not a switch.
+        const keep = current !== undefined && current.provider === route.provider && current.model === route.model
+            ? current.reasoningEffort
+            : undefined;
+        modelSwitch.choose({
+            provider: route.provider,
+            model: route.model,
+            ...keep === undefined ? {} : { reasoningEffort: keep },
+        });
+        model.notice(`model set to ${route.provider}/${route.model} for the next step`);
+        tui.requestRender();
+    };
+    /**
+     * Offer the levels a route advertises, after the route is already in force.
+     *
+     * Cancelling the list is a real choice — the reader keeps the model with the
+     * provider's own default — which is why the route is applied first. The list
+     * is read before the picker opens because the rows are the route's own
+     * metadata; a menu painted before that arrived could offer a level the
+     * request would then be refused for.
+     */
+    const offerRouteEfforts = async (route) => {
+        if (catalog === undefined)
+            return;
+        try {
+            const info = await catalog.efforts(route.provider, route.model);
+            const efforts = info?.efforts ?? [];
+            if (efforts.length === 0)
+                return;
+            const current = effectiveRoute();
+            const effective = current !== undefined && current.provider === route.provider && current.model === route.model
+                ? current.reasoningEffort
+                : undefined;
+            const picked = await openPicker(new EffortPicker(() => effortChoices(efforts, effective), `reasoning effort · ${route.provider}/${route.model}`, () => keymap));
+            if (picked !== undefined)
+                applyEffort(route.provider, route.model, picked);
+        }
+        catch (error) {
+            model.notice(`could not read reasoning efforts: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        tui.requestRender();
+    };
+    /**
+     * Offer every model the configured routes advertise.
+     *
+     * Rows come from the routes the llm service registered — the providers this
+     * deployment configured — and each provider's models join the open list as
+     * its catalog resolves, so the picker is filterable before the slowest
+     * adapter answers. A route whose catalog cannot be read stays reachable by
+     * name through the text form rather than by an explanation in the list.
+     */
+    const openModelPicker = async () => {
+        if (catalog === undefined) {
+            model.notice('this profile has no llm service, so models cannot be listed or switched');
+            tui.requestRender();
+            return;
+        }
+        const providers = catalog.providers();
+        if (providers.length === 0) {
+            model.notice('no provider is configured; add one before choosing a model');
+            tui.requestRender();
+            return;
+        }
+        if (openingModels)
+            return;
+        openingModels = true;
+        try {
+            const routes = [];
+            for (const provider of providers) {
+                void catalog.models(provider.id).then(entries => {
+                    if (entries.length === 0)
+                        return;
+                    routes.push(...entries.map(entry => ({ provider: provider.id, model: entry.id, name: entry.name })));
+                    tui.requestRender();
+                }).catch(() => {
+                    // One adapter's discovery failure is not the list's to explain.
+                });
+            }
+            const picked = await openPicker(new ModelPicker(() => routes, effectiveRoute, () => keymap));
+            if (picked === undefined)
+                return;
+            const route = readModelRouteKey(picked);
+            if (route === undefined)
+                return;
+            applyRoute(route);
+            await offerRouteEfforts(route);
+        }
+        finally {
+            openingModels = false;
+            tui.requestRender();
+        }
+    };
     /**
      * Offer the efforts the route in force advertises.
      *
@@ -1067,7 +1442,7 @@ export function apply(ctx, config) {
                 model.notice(`${facts.provider}/${facts.model} advertises no reasoning efforts`);
                 return;
             }
-            const picked = await openPicker(new EffortPicker(() => effortChoices(efforts, facts.effort), `reasoning effort · ${facts.provider}/${facts.model}`));
+            const picked = await openPicker(new EffortPicker(() => effortChoices(efforts, facts.effort), `reasoning effort · ${facts.provider}/${facts.model}`, () => keymap));
             if (picked !== undefined)
                 applyEffort(facts.provider, facts.model, picked);
         }
@@ -1136,8 +1511,26 @@ export function apply(ctx, config) {
             ? []
             : registry()?.list(current).map(command => `/${command.name}`) ?? [];
         const commands = registered.length === 0 ? 'none registered yet' : registered.join(' ');
-        return `commands: ${commands} · surface: ${LOCAL_COMMANDS.join(' ')} · keys: ${LOCAL_KEYS}`;
+        return `commands: ${commands} · surface: ${LOCAL_COMMANDS.join(' ')} · keys: ${surfaceKeysLine(keymap)} · ${chordKeysLine(keymap)}`;
+    };
+    /**
+     * Whether the agent this surface is driving is in plan mode.
+     *
+     * The dock's fold is the fallback, for a composition without the plan
+     * package: with the controller present its answer is the agent's own state
+     * rather than a replay of the events this surface happened to see.
+     */
+    const planState = () => {
+        const current = agent?.agent;
+        if (current === undefined)
+            return undefined;
+        const presets = ctx.get('agentPresets');
+        return readPlanState({
+            direct: name => ctx.get(name),
+            forAgent: (target, name) => presets?.serviceFor(target, name),
+        }, current);
     };
+    const planActive = () => planSelectedActive(planState(), work.state().planMode);
     const runCommand = (name, line) => {
         const current = agent;
         const commands = registry();
@@ -1183,8 +1576,54 @@ export function apply(ctx, config) {
             ...(facts.effort === undefined ? {} : { reasoningEffort: facts.effort }),
         });
     };
-    editor.onSubmit = text => {
-        const submission = classifySubmission(text);
+    /** Show where history is kept, or forget it; the file is global to this machine. */
+    const runHistoryCommand = (argument) => {
+        // The line that asked for this is recorded before the command runs, but that
+        // write rides the store's queue; waiting for it lets the count describe the
+        // file the reader has, not the state before their own line landed.
+        void promptHistory.flush().then(() => {
+            if (argument === '') {
+                const count = promptHistory.entries().length;
+                const blocked = promptHistory.blockedReason();
+                model.notice([
+                    count + (count === 1 ? ' prompt recorded' : ' prompts recorded'),
+                    promptHistory.path(),
+                    blocked === undefined ? undefined : 'writes disabled: ' + blocked,
+                ].filter(part => part !== undefined).join(' · '));
+                tui.requestRender();
+                return;
+            }
+            if (argument !== 'clear') {
+                model.notice('usage: /history shows where history is kept · /history clear forgets every prompt');
+                tui.requestRender();
+                return;
+            }
+            // A refused write cannot remove anything, so saying "forgot 0 prompts"
+            // would describe a successful clear the file never had.
+            const blocked = promptHistory.blockedReason();
+            if (blocked !== undefined) {
+                model.notice('prompt history is unavailable: ' + blocked);
+                tui.requestRender();
+                return;
+            }
+            return promptHistory.clear().then(removed => {
+                model.notice('forgot ' + removed + (removed === 1 ? ' prompt' : ' prompts'));
+                tui.requestRender();
+            });
+        }).catch(error => {
+            // The store keeps what the file still holds, so the reader is told the
+            // clear failed rather than being shown a count that never landed.
+            model.notice('could not clear prompt history: ' + (error instanceof Error ? error.message : String(error)));
+            tui.requestRender();
+        });
+    };
+    /**
+     * Carry out one classified line, wherever it was asked for.
+     *
+     * A chord asks for the same things the command line does, so both arrive
+     * here: a chord cannot behave differently from the command it stands for.
+     */
+    const runSubmission = (submission) => {
         switch (submission.kind) {
             case 'empty':
                 return;
@@ -1223,9 +1662,51 @@ export function apply(ctx, config) {
                     model.notice(line);
                 tui.requestRender();
                 return;
+            case 'keys': {
+                const layer = submission.argument === '' ? undefined : keymapLayer(submission.argument);
+                if (submission.argument !== '' && layer === undefined) {
+                    model.notice(`unknown layer "${submission.argument}" · ${KEYMAP_LAYERS.join(' ')}`);
+                }
+                else {
+                    for (const line of renderKeymap(keymap, layer))
+                        model.notice(line);
+                }
+                tui.requestRender();
+                return;
+            }
             case 'copy':
                 runCopyCommand();
                 return;
+            case 'history':
+                runHistoryCommand(submission.argument);
+                return;
+            case 'stash':
+                // Submitting a command consumes the line it was typed on, so this path
+                // can only carry a draft it was given; parking the bar's own draft is
+                // what the chord is for.
+                if (submission.argument.trim() === '')
+                    model.notice('usage: /stash <draft>, or ctrl+x then s to park the editor');
+                else
+                    void stash?.stashEditor(submission.argument);
+                return;
+            case 'stash-draft':
+                void stash?.stashEditor();
+                return;
+            case 'stash-pop':
+                void stash?.pop(submission.selector);
+                return;
+            case 'stash-apply':
+                void stash?.apply(submission.selector);
+                return;
+            case 'stash-list':
+                void stash?.list(stashCwdLabel);
+                return;
+            case 'stash-drop':
+                void stash?.drop(submission.selector);
+                return;
+            case 'stash-clear':
+                void stash?.clear();
+                return;
             case 'status': {
                 const facts = statusFacts();
                 const context = facts.contextTokens === undefined
@@ -1263,6 +1744,11 @@ export function apply(ctx, config) {
                     tui.requestRender();
                 });
                 return;
+            // Plan mode is a command the harness owns, so the chord asks the host for
+            // the state and names the command for the other one: one key, both ways.
+            case 'plan':
+                runCommand('plan', planToggleLine(planActive()));
+                return;
             case 'command':
                 runCommand(submission.name, submission.line);
                 return;
@@ -1281,6 +1767,17 @@ export function apply(ctx, config) {
                 }
         }
     };
+    editor.onSubmit = text => {
+        const submission = classifySubmission(text);
+        if (submission.kind === 'empty')
+            return;
+        // The library's own history feeds the up/down keys; the store below feeds
+        // ghost completion and reverse search, and is global rather than per-session.
+        editor.addToHistory(text);
+        if (historyEnabled)
+            promptHistory.record(text);
+        runSubmission(submission);
+    };
     disposers.push(ctx.on('session/event', (session, event) => {
         // The surface state — activity, timer, title, bell, job board — belongs to
         // the agent this terminal drives, even while a child is on screen.
@@ -1289,18 +1786,24 @@ export function apply(ctx, config) {
                 turnOpen = true;
                 turnStartedAt = Date.now();
                 terminal.write(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'));
+                herdr.idle();
                 if (shouldRingBell({ bell: resolved.bell, ranForMs: ranFor, exiting: exited }))
                     terminal.write(BELL);
                 // A job the turn started may have settled while the reader was watching
                 // something else, and nothing else refreshes a live board.
                 refreshJobs();
             }
+            // A claim or a discard changes what is queued, and that belongs to this
+            // session even while the transcript shows a child's conversation.
+            if (event.type === 'agent/inbox/spliced')
+                tui.requestRender();
         }
         if (session.id !== viewedSession)
             return;
@@ -1338,7 +1841,7 @@ export function apply(ctx, config) {
         if (request.agent.id !== activeSession)
             return next();
         return new Promise(resolve => {
-            const gate = new ApprovalGate(request.toolName, request.reason);
+            const gate = new ApprovalGate(request.toolName, request.reason, () => keymap);
             request.signal?.addEventListener('abort', () => {
                 gate.cancel();
                 if (pending?.gate === gate)
@@ -1356,20 +1859,33 @@ export function apply(ctx, config) {
         if (questions.length === 0)
             return next();
         return new Promise(resolve => {
-            const gate = new QuestionGate(questions);
+            const gate = promptBar.borrow(() => new QuestionGate(questions, editor, () => keymap));
             // The seam takes mutable selection arrays and an optional custom field, so
             // the read-only gate answer is copied into that exact shape here.
-            openGate({
-                kind: 'question',
-                gate,
-                settle: answers => resolve({
+            const settle = (answers) => {
+                request.signal?.removeEventListener('abort', onAbort);
+                resolve({
                     answers: answers.map(answer => ({
                         id: answer.id,
                         selected: [...answer.selected],
                         ...(answer.custom === undefined ? {} : { custom: answer.custom }),
                     })),
-                }),
-            });
+                });
+            };
+            // A question whose caller is gone has no reader, so the gate must release
+            // the keyboard instead of collecting an answer the aborted call discards.
+            const onAbort = () => {
+                gate.cancel();
+                if (pending?.gate === gate)
+                    closeGate();
+                settle([]);
+            };
+            openGate({ kind: 'question', gate, settle });
+            request.signal?.addEventListener('abort', onAbort, { once: true });
+            // A signal that aborted before the listener existed never emits, so the
+            // state has to be read once after subscribing.
+            if (request.signal?.aborted === true)
+                onAbort();
         });
     }));
     disposers.push(ctx.on('commands/change', () => installCompletion()));
@@ -1404,17 +1920,11 @@ export function apply(ctx, config) {
     disposers.push(ctx.on('settings/updated', ns => {
         if (String(ns) !== TUI_SETTINGS_NAMESPACE)
             return;
-        pendingSettingsProblem = undefined;
-        applyTheme();
-        applyDisplay();
+        applySettings();
         // Both caches hold rows under the old table, so they have to be told the
         // table moved; a repaint alone would reuse what they already stored.
         markdown.invalidate();
         view.invalidate();
-        if (pendingSettingsProblem !== undefined) {
-            model.notice(`dsh-tui settings: ${pendingSettingsProblem}`);
-            pendingSettingsProblem = undefined;
-        }
         tui.requestRender();
     }));
     const degraded = describeMissingOptional(probe);
@@ -1458,13 +1968,16 @@ 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'));
+        // 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();
         // A refused settings edit is only visible now that the surface owns the
-        // screen; a bare stderr line would have been hidden behind it.
-        if (pendingSettingsProblem !== undefined) {
-            model.notice(`dsh-tui settings: ${pendingSettingsProblem}`);
-            pendingSettingsProblem = undefined;
-        }
+        // screen; whatever the scope found before this point prints here instead.
+        settingsNotice.open(message => model.notice(message));
         await boot();
     };
     void start().catch((error) => {