@sagmans/dsh-tui 0.2.0 → 0.3.0

package/lib/index.js

@@ -9,13 +9,16 @@ 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 { 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";
@@ -26,16 +29,21 @@ import { CLEAR_TITLE, windowTitle } from "./terminal/title.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 { 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 { 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 { 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 { StatusBar } from "./ui/status.js";
 import { DEFAULT_VIEW_STATE, TranscriptView } from "./ui/view.js";
 export const name = 'tui';
@@ -47,10 +55,12 @@ 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. */
@@ -108,11 +118,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 +150,56 @@ 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 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.
+     */
+    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();
+    /**
+     * 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);
+        // 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.
      *
-     * 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.
+     * 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 applyDisplay = () => {
-        viewState.expandSubCalls = readSection().subcalls === 'inline';
+    const applySettings = () => {
+        const section = readSection();
+        applyTheme(section);
+        applyDisplay(section);
     };
     /**
      * Own the section, so the harness validates and persists it for the reader.
@@ -154,10 +210,20 @@ 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) {
+            settingsNotice.post(settingsProblemMessage(error));
+            return;
+        }
+        readSection = () => readScope(scope, message => settingsNotice.post(message));
+        applySettings();
     });
     /**
      * The agent scope the tool presenter resolves against.
@@ -197,7 +263,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 +273,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);
+    // 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.
@@ -237,15 +311,25 @@ export function apply(ctx, config) {
         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)),
     });
     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());
     restore.add(() => tui.stop());
     ctx.effect(() => () => {
         restore.restore();
@@ -262,7 +346,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);
@@ -294,14 +382,65 @@ export function apply(ctx, config) {
         // 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;
         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_KEYS}
+     * 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;
+        },
+        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 +472,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 +515,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;
+        const chorded = keyChord.handle(data);
+        if (chorded !== undefined) {
+            if (chorded.kind === 'action')
+                runSubmission(chorded.binding.submission);
             tui.requestRender();
             return { consume: true };
         }
-        if (matchesKey(data, 'shift+tab')) {
-            viewState.expandReasoning = !viewState.expandReasoning;
-            tui.requestRender();
-            return { consume: true };
+        for (const binding of surfaceBindings(keymap)) {
+            if (!matchesKey(data, binding.key))
+                continue;
+            return surfaceActions[binding.action]() ? { consume: true } : undefined;
         }
-        if (matchesKey(data, 'ctrl+y')) {
-            viewState.expandSubCalls = !viewState.expandSubCalls;
-            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 };
-        }
-        requestExit(0);
-        return { consume: true };
+        return undefined;
     }));
     const registry = () => ctx.get('commands');
     /**
@@ -433,7 +557,7 @@ 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. */
@@ -477,7 +601,7 @@ 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));
     };
     /** Title the listed sessions without making the reader wait for the slowest log. */
     const loadTitles = async (history, sessions, titles) => {
@@ -604,9 +728,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 () => {
@@ -966,19 +1088,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 +1152,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 +1299,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 +1368,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 +1433,13 @@ export function apply(ctx, config) {
             ...(facts.effort === undefined ? {} : { reasoningEffort: facts.effort }),
         });
     };
-    editor.onSubmit = text => {
-        const submission = classifySubmission(text);
+    /**
+     * 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,6 +1478,18 @@ 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;
@@ -1263,6 +1530,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 +1553,7 @@ export function apply(ctx, config) {
                 }
         }
     };
+    editor.onSubmit = text => runSubmission(classifySubmission(text));
     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.
@@ -1301,6 +1574,10 @@ export function apply(ctx, config) {
                 // 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 +1615,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 +1633,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 +1694,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);
@@ -1460,11 +1744,8 @@ export function apply(ctx, config) {
         tui.start();
         terminal.write(windowTitle(process.cwd(), 'ready'));
         // 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) => {