@sagmans/dsh-tui 0.1.2 → 0.3.0

package/lib/index.js

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { Editor, ProcessTerminal, ScrollView, TuiAltScreen, VStack, isKeyRelease, matchesKey } from '@earendil-works/pi-tui';
+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 { createPresetRoster, parsePresetArgument } from "./agent/presets.js";
@@ -9,35 +9,58 @@ 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";
+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 { defaultExportFile, transcriptToText } from "./export.js";
-import { colorEnabled, createTheme } from "./theme.js";
+import { createTheme, forwardEditorTheme, forwardMarkdownTheme } from "./theme.js";
+import { detectColourMode } from "./theme-capability.js";
+import { defaultSettings, readScope, settingsProblemMessage, toOverrides, TUI_SETTINGS_NAMESPACE, TuiSettingsSchema } from "./theme-settings.js";
+import { 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 { GateInputBar } from "./ui/gate-input.js";
+import { PromptBar } from "./ui/prompt.js";
 import { MarkdownRenderer } from "./ui/markdown.js";
-import { PresetPicker, SessionPicker } from "./ui/picker.js";
-import { StatusBar, formatTokens } from "./ui/status.js";
-import { TranscriptView } from "./ui/view.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';
-/** `agents` is the only service the surface cannot run without. */
-export const inject = ['agents'];
-/** Keys the surface answers itself, listed wherever the reader asks for help. */
-const LOCAL_KEYS = 'ctrl+o tool detail · ctrl+t reasoning · 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';
+/**
+ * Services the surface cannot run without.
+ *
+ * `tools` is what lets a card read its tool's own render intent; a context that
+ * has not injected it throws on the property read, which silently degraded
+ * every card to a bare generic row.
+ */
+export const inject = ['agents', 'tools'];
+/** 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. */
@@ -78,47 +101,200 @@ export function apply(ctx, config) {
     if (appExit === undefined) {
         throw new Error('dsh-tui: the dsh launcher must provide appExit; start this surface with dsh --profile tui');
     }
-    const theme = createTheme(colorEnabled(resolved.color));
-    const model = new TranscriptModel(createToolPresenter(ctx));
+    /**
+     * The surface's appearance, rebuilt whenever the reader's settings change.
+     *
+     * Renderers hold this object for the life of the session, so the current
+     * theme is swapped *behind* a stable delegate rather than reassigned: every
+     * row then reads one whole table, and a repaint can never observe a
+     * half-applied one. `--no-color` still outranks anything configured.
+     */
+    const themeMode = () => (resolved.color ? detectColourMode(process.env) : 'none');
+    /**
+     * The reader's section, or nothing when the service is not mounted.
+     *
+     * The service is only readable inside an `inject` scope — asking for it
+     * outside one is a composition error, not a missing value — so this stays a
+     * 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, and the section is read on a schedule of its own.
+     */
+    const settingsNotice = createDeferredNotice();
+    let current = createTheme(themeMode());
+    const applyTheme = (section) => {
+        current = createTheme(themeMode(), toOverrides(section));
+    };
+    const theme = {
+        get revision() { return current.revision; },
+        get color() { return current.color; },
+        style: (token, text) => current.style(token, text),
+        cut: (text, width, ellipsis) => current.cut(text, width, ellipsis),
+        glyph: token => current.glyph(token),
+        visible: token => current.visible(token),
+        // Forwarded rather than read, because the editor and the markdown view keep
+        // the theme object they were built with: a settings change has to reach them
+        // through a stable delegate or they would keep the boot appearance.
+        editor: forwardEditorTheme(() => current.editor),
+        markdown: forwardMarkdownTheme(() => current.markdown),
+    };
+    /**
+     * Rows the reader has opened. The model stays untouched; only the view reads
+     * this. A thought starts folded: it is the longest, least scannable row in the
+     * transcript, so leaving it open pushes the answer a reader came for off the
+     * screen, and a folded row still names itself and its key. A PTC card's calls
+     * start open for the opposite reason: each is one clipped line under a header
+     * that already names the program.
+     */
+    const viewState = { ...DEFAULT_VIEW_STATE };
+    /**
+     * 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.
+     *
+     * 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.
+     *
+     * Registration is how the document learns the section exists at all; without
+     * it a hand-written `dsh-tui:` block would be dropped on the next save. The
+     * first read happens here too, because this is the only scope the service
+     * may be touched in.
+     */
+    ctx.inject(['settings'], settingsCtx => {
+        // 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.
+     *
+     * Tools are registered in the scoped world the session's preset mounts, so a
+     * card can only read its tool's own render intent while this names that
+     * agent. It follows whatever session the transcript is folding, because a
+     * child on screen reads through the child's scope, not the parent's.
+     */
+    let presentScope;
+    const model = new TranscriptModel(createToolPresenter(ctx, () => presentScope));
     const work = new WorkFold();
     const modelSwitch = new ModelSwitch();
     const agentPresets = createPresetRoster(ctx);
+    /** The mode named on the command line, which is the only one that may conflict. */
+    const requestedPreset = resolved.preset;
     /**
      * The mode a session the reader starts from here on joins.
      *
      * A launch flag seeds it and a successful switch updates it, so `/new` and
      * `/fork` land in the mode the reader last chose; nothing is written to
      * settings, because the mode of a session is not a property of the machine.
+     * Unset means nobody chose, which is where the roster's default applies.
      */
-    /** The mode named on the command line, which is the only one that may conflict. */
-    const requestedPreset = resolved.preset;
-    let seat = requestedPreset ?? agentPresets?.defaultId;
+    let seat = requestedPreset;
+    /**
+     * The mode a session takes its seat in: the reader's latest choice, or the
+     * roster's default read at this moment.
+     *
+     * The default cannot be captured when this row applies: it comes from the
+     * settings document, which may be read after that, so a captured copy would
+     * pin every later session to the mode the bundle happened to ship.
+     */
+    const seatMode = () => seat ?? agentPresets?.defaultId;
     const catalog = createModelCatalog(ctx);
     const jobDirectory = createJobDirectory(ctx);
     let jobs = [];
     const roster = new SubagentRoster();
     const subagentControl = createSubagentControl(ctx);
-    const markdown = new MarkdownRenderer(theme.markdown);
-    /** Rows the reader has opened. The model stays untouched; only the view reads this. */
-    const viewState = { expandCards: false, expandReasoning: false };
+    const markdown = new MarkdownRenderer(theme.markdown, createMermaidTransform({ theme, mode: () => mermaidMode }));
     const restore = createRestoreRegistry();
     const terminal = new ProcessTerminal();
-    const tui = new TuiAltScreen(terminal);
+    const tui = new WarningSafeTui(terminal);
     /** The session this surface drives: commands, approvals, and the bell belong to it. */
     let activeSession = resolved.sessionId;
     /** The session the transcript is showing, which can be one of its children. */
     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 Editor(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.
+    disposers.push(() => {
+        presentScope = undefined;
+    });
     let agent;
     let turnOpen = false;
     let turnStartedAt;
@@ -135,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();
@@ -160,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);
@@ -192,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
@@ -231,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 };
@@ -268,35 +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;
-            tui.requestRender();
-            return { consume: true };
-        }
-        if (matchesKey(data, 'ctrl+t')) {
-            viewState.expandReasoning = !viewState.expandReasoning;
+        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+b')) {
-            if (viewedSession !== activeSession)
-                void showAgentSession();
-            return { consume: true };
+        for (const binding of surfaceBindings(keymap)) {
+            if (!matchesKey(data, binding.key))
+                continue;
+            return surfaceActions[binding.action]() ? { consume: true } : undefined;
         }
-        // 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');
     /**
@@ -322,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. */
@@ -366,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) => {
@@ -429,11 +664,31 @@ export function apply(ctx, config) {
      * materialized; a session this process is not running falls back to storage.
      */
     const liveSession = (id) => ctx.get('sessions')?.get?.(id);
+    /**
+     * The fold's place in the viewed session's durable sequence.
+     *
+     * A resumed session is folded while its agent's loop is already live, so the
+     * same event can reach the surface twice: once on the stream and once from the
+     * log the fold is reading. The sequence number every durable event carries is
+     * what tells the two apart.
+     */
+    const foldCursor = new FoldCursor();
+    /** Feed one durable event to the model, unless a fold has already folded it. */
+    const applyDurable = (event) => {
+        if (foldCursor.accept(event))
+            applyEvent(event);
+    };
     const foldHistory = async (id) => {
+        // Resolved before the fold so every card reads its tool through the scope
+        // that actually registered it; a stored session nobody runs has none.
+        presentScope = ctx.agents?.get(id);
+        // Every fold starts a cleared transcript, so this session's own numbering is
+        // where the cursor begins rather than the previous session's.
+        foldCursor.reset();
         const inMemory = liveSession(id)?.snapshotEvents?.();
         if (inMemory !== undefined) {
             for (const event of inMemory)
-                applyEvent(event);
+                applyDurable(event);
             return inMemory.length;
         }
         const history = createSessionHistory(ctx);
@@ -441,7 +696,7 @@ export function apply(ctx, config) {
             return 0;
         const events = await history.read(id);
         for (const event of events)
-            applyEvent(event);
+            applyDurable(event);
         return events.length;
     };
     const replayHistory = async (id) => {
@@ -473,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 () => {
@@ -507,13 +760,13 @@ export function apply(ctx, config) {
         if (agentPresets === undefined)
             return undefined;
         if (fork !== undefined)
-            return agentPresets.current(liveSession(fork.from)) ?? seat;
+            return agentPresets.current(liveSession(fork.from)) ?? seatMode();
         if (!resume)
-            return seat;
+            return seatMode();
         const history = createSessionHistory(ctx);
         const stored = history === undefined ? undefined : await presetOfStoredSession(history, id);
         if (stored === undefined)
-            return seat;
+            return seatMode();
         const resolvedStored = await resolveStored(id, stored);
         if (resolvedStored === undefined) {
             // The composition this session recorded is gone. Naming one explicitly is
@@ -541,8 +794,6 @@ export function apply(ctx, config) {
         // Settled before the transcript is touched, so a refusal leaves neither a
         // half-replayed session nor a half-composed agent behind.
         const preset = await presetFor(id, resume, fork);
-        if (resume)
-            await replayHistory(id);
         const handle = await startAgent(ctx, {
             sessionId: id,
             resume,
@@ -561,6 +812,16 @@ export function apply(ctx, config) {
         activeSession = id;
         viewedSession = id;
         agent = handle;
+        // 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;
+        // Replayed only once the agent exists, because the fold reads every card
+        // through the scope the preset mounted; a fold before that scope existed
+        // degraded each replayed card to a bare generic row. The agent's loop is
+        // live by now, so the fold and the stream race over the same events; the
+        // durable sequence number is what keeps one event from landing twice.
+        if (resume)
+            await replayHistory(id);
         // A branch inherits the conversation the reader was already reading, so it
         // opens on that history rather than on an empty screen.
         if (fork !== undefined)
@@ -576,6 +837,9 @@ export function apply(ctx, config) {
     const switchSession = async (id) => {
         const previous = agent;
         agent = undefined;
+        // Drop the outgoing scope before its agent is disposed, so no card folded
+        // during the transition can read a torn-down world.
+        presentScope = undefined;
         turnOpen = false;
         model.reset();
         work.reset();
@@ -824,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> 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
@@ -848,17 +1104,213 @@ export function apply(ctx, config) {
                     tui.requestRender();
                 });
                 return;
-            case 'switch':
-                modelSwitch.choose(command.choice);
-                model.notice(`model set to ${command.choice.provider}/${command.choice.model} for the next step`);
-                tui.requestRender();
+            case 'switch': {
+                const choice = command.choice;
+                if (choice.reasoningEffort === undefined) {
+                    modelSwitch.choose(choice);
+                    model.notice(`model set to ${choice.provider}/${choice.model} for the next step`);
+                    tui.requestRender();
+                    return;
+                }
+                // The route decides which efforts exist, so an explicit one is checked
+                // against the adapter before it is put in force: a typo must not become
+                // a request the provider rejects.
+                void (async () => {
+                    try {
+                        const info = await catalog.efforts(choice.provider, choice.model);
+                        const efforts = info?.efforts ?? [];
+                        if (!efforts.some(effort => effort.id === choice.reasoningEffort)) {
+                            model.notice(efforts.length === 0
+                                ? `/model: ${choice.provider}/${choice.model} advertises no reasoning efforts`
+                                : `/model: ${choice.provider}/${choice.model} does not offer reasoning effort "${choice.reasoningEffort}" — offers: ${efforts.map(effort => effort.id).join(' ')}`);
+                            tui.requestRender();
+                            return;
+                        }
+                        modelSwitch.choose(choice);
+                        model.notice(`model set to ${choice.provider}/${choice.model} (${choice.reasoningEffort}) for the next step`);
+                    }
+                    catch (error) {
+                        model.notice(`/model: could not read reasoning efforts: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                    tui.requestRender();
+                })();
                 return;
+            }
             case 'invalid':
                 model.notice(`/model: ${command.reason}`);
                 tui.requestRender();
                 return;
         }
     };
+    /** Whether a route's effort list is being read, so a second key cannot race it. */
+    let openingEfforts = false;
+    /** Put the reader's effort choice in force for the next step. */
+    const applyEffort = (provider, modelId, effortId) => {
+        modelSwitch.choose(effortId === PROVIDER_DEFAULT_EFFORT_ID
+            ? { provider, model: modelId }
+            : { provider, model: modelId, reasoningEffort: effortId });
+        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.
+     *
+     * 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 openEffortPicker = async () => {
+        if (catalog === undefined) {
+            model.notice('this profile has no llm service, so reasoning efforts cannot be read');
+            tui.requestRender();
+            return;
+        }
+        const facts = statusFacts();
+        if (facts.provider === undefined || facts.model === undefined) {
+            model.notice('no model route is in use; /model <provider>/<model> picks one first');
+            tui.requestRender();
+            return;
+        }
+        if (openingEfforts)
+            return;
+        openingEfforts = true;
+        try {
+            const info = await catalog.efforts(facts.provider, facts.model);
+            const efforts = info?.efforts ?? [];
+            if (efforts.length === 0) {
+                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}`, () => keymap));
+            if (picked !== undefined)
+                applyEffort(facts.provider, facts.model, picked);
+        }
+        catch (error) {
+            model.notice(`could not read reasoning efforts: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            openingEfforts = false;
+            tui.requestRender();
+        }
+    };
     /**
      * Show or choose the mode this session runs.
      *
@@ -916,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();
@@ -943,8 +1413,33 @@ export function apply(ctx, config) {
             tui.requestRender();
         });
     };
-    editor.onSubmit = text => {
-        const submission = classifySubmission(text);
+    /**
+     * Put the deployment default in force before the first turn.
+     *
+     * The agent is created before the settings file has been read, so the route
+     * its loop captured is the composition placeholder; the reader's default —
+     * effort included — only exists by the time they can type. Adopting it here
+     * is what makes the status line's route the one the request actually uses.
+     */
+    const adoptDefaultRoute = () => {
+        if (modelSwitch.current() !== undefined)
+            return;
+        const facts = statusFacts();
+        if (facts.provider === undefined || facts.model === undefined)
+            return;
+        modelSwitch.adopt({
+            provider: facts.provider,
+            model: facts.model,
+            ...(facts.effort === undefined ? {} : { reasoningEffort: facts.effort }),
+        });
+    };
+    /**
+     * 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;
@@ -978,6 +1473,23 @@ export function apply(ctx, config) {
             case 'todo':
                 runTodoCommand();
                 return;
+            case 'theme':
+                for (const line of renderThemeTable(toOverrides(readSection())))
+                    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;
@@ -1018,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;
@@ -1030,10 +1547,13 @@ export function apply(ctx, config) {
                 // While a turn is running the human is steering it, not opening another.
                 if (turnOpen)
                     agent.steer(submission.text);
-                else
+                else {
+                    adoptDefaultRoute();
                     agent.submit(submission.text);
+                }
         }
     };
+    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.
@@ -1054,10 +1574,15 @@ 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;
-        applyEvent(event);
+        presentScope = ctx.agents?.get(session.id);
+        applyDurable(event);
         tui.requestRender();
     }));
     /**
@@ -1090,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)
@@ -1108,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()));
@@ -1145,6 +1683,24 @@ export function apply(ctx, config) {
         model.applyStreamChunk(payload.frame.chunk);
         tui.requestRender();
     }));
+    /**
+     * Restyle a running session when the reader's section changes.
+     *
+     * The settings document is hot-reloaded by the host, so a reader watching a
+     * shade land never has to leave the session to see it — which is what makes
+     * tuning one bearable instead of a restart per attempt. The event is
+     * namespace-filtered: another surface's preferences are not our repaint.
+     */
+    disposers.push(ctx.on('settings/updated', ns => {
+        if (String(ns) !== TUI_SETTINGS_NAMESPACE)
+            return;
+        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();
+        tui.requestRender();
+    }));
     const degraded = describeMissingOptional(probe);
     if (degraded !== undefined)
         model.notice(degraded);
@@ -1187,6 +1743,9 @@ export function apply(ctx, config) {
             await presetFor(resolved.sessionId, resolved.resume, undefined);
         tui.start();
         terminal.write(windowTitle(process.cwd(), 'ready'));
+        // A refused settings edit is only visible now that the surface owns the
+        // screen; whatever the scope found before this point prints here instead.
+        settingsNotice.open(message => model.notice(message));
         await boot();
     };
     void start().catch((error) => {