@aiwayds/dsh-tui-pi 0.1.1 → 0.4.0

package/lib/index.js

@@ -11,38 +11,59 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
-import { Loader, Text } from '@earendil-works/pi-tui';
+import { Loader } from '@earendil-works/pi-tui';
 import { CommandService } from "./commands.js";
-import { PowerlineFooter } from "./footer.js";
+import { FooterHint, PowerlineFooter } from "./footer.js";
 import { GitBranchWatcher } from "./git.js";
-import { ensureAppendSystemFile, migrateAgentsMdTodoSection, readAppendSystem } from "./append-system.js";
+import { ensureAppendSystemFile, dshHome, migrateAgentsMdTodoSection } from "./append-system.js";
 import { TranscriptRenderer } from "./messages.js";
 import { AGENT_TICK_MS, LiveWidgets } from "./live-widgets.js";
 import { displayPermissionPreset } from "./permission.js";
 import { pickEffort, pickModel, pickPermission, pickTheme } from "./selectors.js";
 import { DshSessionBridge, persistDefaultModel, stashSessionIdForReload, takeStashedSessionId } from "./session.js";
-import { currentThemePreference, readPanelHeightPreference, readThemePreference, registerThemeSettings, writeThemePreference, } from "./theme-settings.js";
+import { currentThemePreference, readFooterHintsPreference, readPanelHeightPreference, readThemePreference, registerThemeSettings, writeThemePreference, } from "./theme-settings.js";
+import { openAgentManager } from "./agents.js";
 import { openSettingsBrowser } from "./settings.js";
 import { reloadPlugin } from "./reload.js";
 import { inspectPersistedSession, pickPersistedSession, showSessionInfo } from "./sessions.js";
+import { applySubagentPolicy } from "./subagent-policy.js";
+import { openSubagentViewer } from "./subagent-viewer.js";
 import { ansiFg, BOLD, darkTheme, lightTheme, RESET, resolveTheme } from "./theme/index.js";
+import { rgbIsLight } from "./theme/palette.js";
 import { clipToWidth } from "./text.js";
+import {} from "./keymap.js";
+import { keybindingsPath, loadKeyBindings, openHotkeysManager } from "./hotkeys.js";
 import { startTui } from "./tui.js";
 export const name = 'dsh-tui-pi';
+/**
+ * Delay (ms) before a double-Ctrl+C quit actually fires — a held key's first
+ * auto-repeat lands inside the 500ms double-press window looking like a
+ * deliberate second press, and a follow-up `key-repeat` (arriving within
+ * ~30-50ms) aborts the quit before this timer ever fires.
+ */
+const QUIT_CONFIRM_MS = 200;
+/**
+ * Delay (ms) before the double-Esc stop actually fires — the same held-key
+ * defence as the Ctrl+C quit: the OS repeat delay (~183ms-2s) puts the first
+ * auto-repeat of a held Esc exactly at the 500ms stop-window boundary; the
+ * stop is confirmed for this long and a follow-up `key-repeat` (betraying
+ * the held key) aborts it. A second HUMAN-speed press during the window
+ * fires the stop immediately (see `interrupt-cancel`).
+ */
+const STOP_CONFIRM_MS = 200;
 /** The TUI drives the agent factory and registers slash commands. */
-export const inject = ['agents', 'commands', 'systemPrompt'];
+export const inject = ['agents', 'commands'];
 export function apply(ctx) {
     let handle;
     // APPEND_SYSTEM.md (pi's convention; dsh side ~/.dsh/APPEND_SYSTEM.md): a
-    // user-editable file appended to the system prompt of every agent this TUI
-    // creates. The section text provider reads the file at each assembly, so
-    // edits apply to the next request without a restart or watcher. Empty
-    // content contributes nothing.
-    ctx.effect(() => ctx.systemPrompt.section({
-        name: 'dsh-tui-pi:append-system',
-        order: 200,
-        text: () => readAppendSystem(),
-    }), 'dsh-tui-pi: append-system');
+    // user-editable file appended to the system prompt of the MAIN agent this
+    // TUI creates - and to no subagent (an orchestrator identity riding on the
+    // children defeats its own purpose). The section is registered on the
+    // agent's scoped context inside DshSessionBridge's create/resume setup
+    // (see installAppendSystem in session.ts); the text provider reads the
+    // file at each assembly, so edits apply to the next request without a
+    // restart or watcher, and empty content contributes nothing.
+    //
     // The TUI's own todo-lifecycle guidance rides the same file (idempotent
     // marker); a fresh file is seeded with the orchestrator template. The
     // legacy AGENTS.md delivery is migrated out. All best-effort.
@@ -61,6 +82,12 @@ export function apply(ctx) {
      * the new row budget. Armed inside runTui once the renderer exists.
      */
     let applyPanelHeightRef;
+    /**
+     * Live footer-hints hot-reload sink, wired to the same watch hook: a
+     * committed `dsh-tui` footerHints change repaints the footer hint bar with
+     * the new segment selection. Armed inside runTui once the TUI exists.
+     */
+    let applyFooterHintsRef;
     ctx.effect(async () => {
         // The theme bundle is built once at TUI startup and held by every
         // component, so the persisted preference must land before startTui — the
@@ -68,7 +95,8 @@ export function apply(ctx) {
         // awaits it (bounded, degrades to the defaults without a settings
         // service). The registration also watches the namespace: `applies:
         // 'live'`, so later commits (the /theme picker, the /settings browser, an
-        // external edit) hot-apply through applyThemeRef / applyPanelHeightRef.
+        // external edit) hot-apply through applyThemeRef / applyPanelHeightRef /
+        // applyFooterHintsRef.
         // Panel height FIRST, theme second: a single commit of both fields (a
         // namespace-level reset, an external edit) must not replay twice at the
         // wrong height. setPanelHeight + relayout repaint the transcript at the
@@ -76,15 +104,17 @@ export function apply(ctx) {
         // that new height, so the theme rebuild is the one complete rebuild.
         // applyTheme carries the theme-bundle identity guard, so a height-only
         // commit never triggers a second rebuild.
-        registerThemeSettings(ctx, (pref, height) => {
+        registerThemeSettings(ctx, (pref, height, footerHints) => {
             applyPanelHeightRef?.(height);
             applyThemeRef?.(pref);
+            applyFooterHintsRef?.(footerHints);
         });
         const themePreference = await readThemePreference(ctx);
         const panelHeight = await readPanelHeightPreference(ctx);
+        const footerHints = await readFooterHintsPreference(ctx);
         let disposer;
         try {
-            disposer = runTui(themePreference, panelHeight);
+            disposer = runTui(themePreference, panelHeight, footerHints);
         }
         catch (error) {
             // An async-effect failure after startTui would otherwise orphan the
@@ -98,50 +128,189 @@ export function apply(ctx) {
         return disposer;
     }, 'dsh-tui-pi.render');
     /**
-     * Build the TUI and its slash commands for the resolved theme preference
-     * and panel height. Declared as a hoisted function so the effect body stays
-     * a thin wrapper: the whole build runs inside the try/catch above, so any
-     * failure disposes the TUI handle before the error reaches cordis. Returns
-     * the effect disposer handed back to cordis on teardown.
+     * Build the TUI and its slash commands for the resolved theme preference,
+     * panel height and footer-hint selection. Declared as a hoisted function so
+     * the effect body stays a thin wrapper: the whole build runs inside the
+     * try/catch above, so any failure disposes the TUI handle before the error
+     * reaches cordis. Returns the effect disposer handed back to cordis on
+     * teardown.
      */
-    function runTui(themePreference, panelHeight) {
-        // Graded Ctrl+C: while the agent is mid-turn the first press cancels the
-        // active turn (keepInbox preserves the queue) with on-screen feedback;
-        // any further press — or any press while idle — quits the TUI.
-        let cancelAttempted = false;
-        let lastInterrupt = 0;
+    function runTui(themePreference, panelHeight, footerHints) {
+        // User keybindings (`~/.dsh/keybindings.json`): a partial map of the app
+        // keys, read once per TUI start — `/reload` re-runs apply() and re-reads
+        // it. Broken entries surface as notices instead of breaking startup.
+        const keyFile = keybindingsPath(dshHome());
+        const keyBindings = loadKeyBindings(keyFile);
         const ui = startTui({
             onSubmit: text => {
                 void submit(text);
             },
-            onInterrupt: () => {
-                if (bridge.isRunning() && !cancelAttempted && Date.now() - lastInterrupt > 1500) {
-                    // First press mid-turn: cancel with on-screen feedback (mirrors the
-                    // web client's stop button). The next press — of any kind — quits.
-                    cancelAttempted = true;
-                    lastInterrupt = Date.now();
-                    // Transient notice: a second press quits and disposes the whole
-                    // TUI, so the line's replay entry only matters for theme-switch
-                    // repaints — buffering it keeps that rebuild faithful.
-                    renderer.renderNotice('⏹ canceling current turn…', 'info');
-                    void bridge.cancelActiveTurn().then(cancelled => {
-                        // Nothing was running (state raced idle): nothing to cancel — quit.
-                        if (!cancelled)
+            keyBindings: keyBindings.bindings,
+            // App-level keys (pi interrupt chain): Esc on a running task is a
+            // deliberate double-press — the first press arms the window (with
+            // feedback), the second within 500ms stops the whole task (parent +
+            // subagents); popup/autocomplete first, anti-misfire no-op on a
+            // non-empty editor, and an empty idle editor double-Esc opens /session.
+            // Ctrl+C cancels a running turn or clears the editor — a second press
+            // within 500ms quits — and Ctrl+D quits only on an empty editor.
+            // Ctrl+G opens the subagent picker while children run. All decisions
+            // live in keymap.ts.
+            isRunning: () => bridge.isRunning(),
+            getRunningAgents: () => bridge.getLiveChildren().length,
+            onKeyAction: (action) => {
+                switch (action.kind) {
+                    case 'interrupt-arm-stop':
+                        // First Esc while the task runs: the stop is ARMED, not fired —
+                        // a second Esc within the window confirms it, so a stray Esc can
+                        // never kill a running turn. The notice keeps the armed first
+                        // press from feeling dead and states the contract explicitly.
+                        renderer.renderNotice('Press Esc again to stop the current task', 'info');
+                        break;
+                    case 'interrupt-cancel': {
+                        // Second Esc while the task runs (parent + subagents). Like the
+                        // Ctrl+C quit, the stop is CONFIRMED, not immediate: a held
+                        // Esc's FIRST auto-repeat lands at the OS repeat delay (right at
+                        // the 500ms window boundary) looking exactly like a deliberate
+                        // second press. The stop fires after STOP_CONFIRM_MS unless a
+                        // follow-up `key-repeat` aborts it (a repeat betrays a held key),
+                        // while another HUMAN-speed press during the window stops right
+                        // away. The '⏹ stopping…' notice renders now, so the visible
+                        // feedback is immediate even though the cancellation (and its
+                        // '⏹ canceling current turn…' notice inside `stopTask`) is
+                        // deferred by the confirm window.
+                        if (stopConfirmTimer !== undefined) {
+                            clearTimeout(stopConfirmTimer);
+                            stopConfirmTimer = undefined;
+                            void stopTask();
+                            break;
+                        }
+                        renderer.renderNotice('⏹ stopping — Esc was double-pressed', 'info');
+                        stopConfirmTimer = setTimeout(() => {
+                            stopConfirmTimer = undefined;
+                            void stopTask();
+                        }, STOP_CONFIRM_MS);
+                        break;
+                    }
+                    case 'ctrl-c-cancel': {
+                        // First Ctrl+C mid-turn: cancel straight away with the same
+                        // on-screen feedback as Esc ×2 (mirrors the web client's stop
+                        // button; keepInbox preserves the queue).
+                        void stopTask();
+                        break;
+                    }
+                    case 'interrupt-double':
+                        // Double-Esc on an empty editor: pi's default double action is
+                        // /tree; dsh has no /tree, so this opens /session (the session
+                        // info panel — the closest non-invasive analogue).
+                        void sessionHandler('', new AbortController().signal);
+                        break;
+                    case 'ctrl-c-clear':
+                        // First Ctrl+C while idle: clear the editor (pi app.clear); a
+                        // second press within 500ms quits.
+                        ui.editor.setText('');
+                        ui.requestRender();
+                        break;
+                    case 'ctrl-c-quit': {
+                        // Double Ctrl+C quits — but a held key must not. The terminal
+                        // re-sends a held Ctrl+C every ~30-50ms after the OS repeat delay,
+                        // and the FIRST repeat can land inside the 500ms double-press
+                        // window looking exactly like a deliberate second press. So the
+                        // quit is confirmed, not immediate: it fires after
+                        // QUIT_CONFIRM_MS unless a `key-repeat` arrives (a repeat betrays
+                        // a held key → abort), while another HUMAN-speed press during the
+                        // window (a deliberate mash) quits right away.
+                        if (quitConfirmTimer !== undefined) {
+                            clearTimeout(quitConfirmTimer);
+                            quitConfirmTimer = undefined;
                             void disposeAndExit(0);
-                    });
-                }
-                else {
-                    void disposeAndExit(0);
+                            break;
+                        }
+                        renderer.renderNotice('⏹ Ctrl+C ×2 — quitting…', 'info');
+                        quitConfirmTimer = setTimeout(() => {
+                            quitConfirmTimer = undefined;
+                            void disposeAndExit(0);
+                        }, QUIT_CONFIRM_MS);
+                        break;
+                    }
+                    case 'key-repeat':
+                        // Auto-repeat of a held key — betrays a hold, never a double:
+                        // abort a pending Ctrl+C quit confirmation and/or a pending
+                        // double-Esc stop confirmation.
+                        if (action.key === 'ctrl-c' && quitConfirmTimer !== undefined) {
+                            clearTimeout(quitConfirmTimer);
+                            quitConfirmTimer = undefined;
+                            renderer.renderNotice('quit aborted — Ctrl+C was held, not double-pressed', 'info');
+                        }
+                        if (action.key === 'escape' && stopConfirmTimer !== undefined) {
+                            clearTimeout(stopConfirmTimer);
+                            stopConfirmTimer = undefined;
+                            renderer.renderNotice('stop aborted — Esc was held, not double-pressed', 'info');
+                        }
+                        break;
+                    case 'ctrl-d-quit':
+                        void disposeAndExit(0);
+                        break;
+                    case 'model-picker':
+                        // Ctrl+L: pi app.model.select — open the model/think picker.
+                        void modelHandler('', new AbortController().signal);
+                        break;
+                    case 'subagent-viewer':
+                        // Ctrl+G: open the subagent picker → transcript viewer while
+                        // children run (modal overlay; Esc / double-x closes).
+                        void openSubagentViewer(ctx, ui.tui, ui.theme, bridge, () => ui.tui.setFocus(ui.editor));
+                        break;
+                    default:
+                        break;
                 }
             },
             themePreference,
         });
         handle = ui;
+        // Live theme preference, tracked so terminal-following (below) can tell
+        // 'auto' (follow the terminal) from an explicit light/dark pin.
+        let themePreferenceRef = themePreference;
+        /**
+         * Pending Ctrl+C quit confirmation (see the `ctrl-c-quit` case): armed by
+         * a double press, fired after QUIT_CONFIRM_MS, aborted by a `key-repeat`
+         * (held key) or torn down with the TUI.
+         */
+        let quitConfirmTimer;
+        /**
+         * Pending double-Esc stop confirmation (see the `interrupt-cancel` case):
+         * armed by the second Esc while running, fired after STOP_CONFIRM_MS,
+         * aborted by a `key-repeat` (held key) or torn down with the TUI. The
+         * Ctrl+C quit and the Esc stop never share a timer — distinct keys, both
+         * could theoretically be in flight.
+         */
+        let stopConfirmTimer;
+        /**
+         * Stop the whole task (parent turn + subagents), mirroring the web
+         * client's stop button: `agent.cancel({ kind: 'user' }, { keepInbox:
+         * true })` via the bridge. Deferred by the confirm windows above (the
+         * ESC/Ctrl+C double-press guards); the notice renders immediately.
+         */
+        const stopTask = async () => {
+            renderer.renderNotice('⏹ canceling current turn…', 'info');
+            const cancelled = await bridge.cancelActiveTurn();
+            // State raced idle between the decision and the cancel call — nothing
+            // to cancel (e.g. the turn settled inside the confirm window).
+            if (!cancelled)
+                renderer.renderNotice('Nothing running to cancel.', 'info');
+        };
         // Arm the settings watch sink now that the renderer exists (see apply()).
         applyThemeRef = (pref) => {
+            themePreferenceRef = pref;
+            // 'auto' subscribes to the terminal's live color-scheme pushes; an
+            // explicit pin opts out. resolveTheme guards env-pinned displays.
+            ui.tui.setTerminalColorSchemeNotifications(pref === 'auto');
             applyTheme(resolveTheme(process.env, pref));
         };
         const renderer = new TranscriptRenderer(ui.transcript, ui.theme, () => ui.requestRender(), panelHeight);
+        // Startup notices for a broken/misleading keybindings file — the TUI keeps
+        // running with defaults; the panel shows the same warnings via /hotkeys.
+        for (const warning of keyBindings.warnings) {
+            renderer.renderNotice(`keybindings: ${warning}`, 'error');
+        }
         // Live Todos widget, pinned above the chat window, plus the running-agent
         // activity merged into the last-request area below the editor: shown while
         // the model has (incomplete) todos or subagents running, collapsed when
@@ -201,8 +370,8 @@ export function apply(ctx) {
         // with a repaint request here. The badge reads the cached current preset
         // (see the provider below), so a knob change must refresh the cache too.
         const PERMISSION_KNOB_EVENTS = new Set(['permission/preset', 'sandbox/mode', 'approval/policy']);
-        const bridge = new DshSessionBridge(ctx, {
-            onEvent: event => {
+        const bridgeCallbacks = {
+            onEvent: (event) => {
                 renderer.applyEvent(event);
                 if (event.type === 'todo/write') {
                     // Todos render in the fixed live widget, not the transcript.
@@ -214,10 +383,23 @@ export function apply(ctx) {
                 }
             },
             onStatus: setStatus,
-            onLive: agents => {
+            onLive: (agents) => {
                 liveWidgets.renderAgents(agents);
             },
+        };
+        const bridge = new DshSessionBridge(ctx, bridgeCallbacks);
+        // Subagent fine-grained control, all in-process (see subagent-policy.ts):
+        // a tools.guard denies spawn-tool calls once `maxAgents` children run
+        // (workflow fan-out, which bypasses the tool pipeline, is pruned on
+        // `subagent/start`), and when a child's completed turns reach `maxRounds`
+        // the policy queues one wrap-up message into its next turn. Limits are
+        // read live from the `dsh-tui` settings namespace (/agents → l limits).
+        const subagentPolicy = applySubagentPolicy(ctx, {
+            getLive: () => bridge.getLiveChildren(),
+            getTurnCount: childId => bridge.getTurnCount(childId),
+            isSettled: childId => bridge.isChildSettled(childId),
         });
+        bridgeCallbacks.onTurnCount = (childId, count) => subagentPolicy.onTurnCount(childId, count);
         /**
          * One O(events) fold of the session log into the effective preset, stored
          * for the badge provider. Runs once per session (ensure/resume, see the
@@ -270,6 +452,35 @@ export function apply(ctx) {
             description: 'Select the model (and think level) for this conversation',
             handler: invocation => modelHandler(invocation.rawInput, invocation.signal),
         }), 'dsh-tui-pi: /model');
+        // /agents: manage agent definition markdown files (model, think level,
+        // spawn depth) — the terminal counterpart of pi's /fun-agent-cfg. An
+        // optional argument preselects one agent by name.
+        const agentsHandler = async (rawInput) => {
+            const trimmed = rawInput?.trim() ?? '';
+            const result = await openAgentManager(ctx, ui.tui, ui.theme, () => ui.tui.setFocus(ui.editor), trimmed === '' ? undefined : trimmed);
+            if (result === undefined)
+                return { kind: 'success', text: 'Agents unchanged.' };
+            return { kind: 'success', text: result };
+        };
+        commands.registerLocal('agents', agentsHandler);
+        ctx.effect(() => ctx.commands.register({
+            name: 'agents',
+            description: 'Manage agent definitions (model, think level, spawn depth) from markdown files',
+            handler: invocation => agentsHandler(invocation.rawInput, invocation.signal),
+        }), 'dsh-tui-pi: /agents');
+        // /subagents: the command twin of Ctrl+G — pick a running (or recently
+        // settled) subagent and inspect its live transcript in the 80% viewer.
+        // Same flow as the key path; empty board closes immediately.
+        const subagentsHandler = async () => {
+            await openSubagentViewer(ctx, ui.tui, ui.theme, bridge, () => ui.tui.setFocus(ui.editor));
+            return { kind: 'success', text: 'Subagent viewer closed.' };
+        };
+        commands.registerLocal('subagents', subagentsHandler);
+        ctx.effect(() => ctx.commands.register({
+            name: 'subagents',
+            description: 'Browse subagents and inspect their live transcript',
+            handler: invocation => subagentsHandler(invocation.rawInput, invocation.signal),
+        }), 'dsh-tui-pi: /subagents');
         // /think: cycle the current model's reasoning effort without re-picking
         // the model. A no-session /think still lands in the selection ref and
         // survives the lazy session creation (bridge seeds only an empty ref).
@@ -318,6 +529,25 @@ export function apply(ctx) {
             description: 'Switch the current model\'s think (reasoning) level',
             handler: invocation => thinkHandler(invocation.rawInput, invocation.signal),
         }), 'dsh-tui-pi: /think');
+        // /models-sync: run one dsh-model-sync catalog round on demand and show
+        // its report. Agentless like the pickers above — the sync only touches the
+        // settings document, never a conversation, so no throwaway session. The
+        // service is optional: without the dsh-model-sync plugin loaded, the
+        // command says so instead of failing elsewhere.
+        const modelSyncHandler = async () => {
+            const modelSync = ctx.get('modelSync');
+            if (modelSync === undefined) {
+                return { kind: 'error', text: 'dsh-model-sync plugin is not loaded.' };
+            }
+            const report = await modelSync.syncNow();
+            return { kind: 'success', text: report };
+        };
+        commands.registerLocal('models-sync', modelSyncHandler);
+        ctx.effect(() => ctx.commands.register({
+            name: 'models-sync',
+            description: 'Sync the model catalog from configured providers (custom providers excluded)',
+            handler: invocation => modelSyncHandler(invocation.rawInput, invocation.signal),
+        }), 'dsh-tui-pi: /models-sync');
         const sessionHandler = async () => {
             const agent = bridge.getAgent();
             const stats = bridge.getStats();
@@ -575,6 +805,23 @@ export function apply(ctx) {
             description: 'Reload the TUI from the current source (apply code changes without restarting dsh)',
             handler: invocation => reloadHandler(invocation.rawInput, invocation.signal),
         }), 'dsh-tui-pi: /reload');
+        // /hotkeys — pi's keybinding browser, in the /agents select-panel style:
+        // a field list of the app keys, Enter opens an editor that writes
+        // ~/.dsh/keybindings.json and live-applies the change (no /reload).
+        const hotkeysHandler = async () => {
+            const summary = await openHotkeysManager(ui.tui, ui.theme, {
+                filePath: keyFile,
+                apply: bindings => ui.setKeyBindings(bindings),
+                restoreFocus: () => ui.tui.setFocus(ui.editor),
+            });
+            return { kind: 'success', text: summary ?? 'Keybindings unchanged.' };
+        };
+        commands.registerLocal('hotkeys', hotkeysHandler);
+        ctx.effect(() => ctx.commands.register({
+            name: 'hotkeys',
+            description: 'Show the current keybindings (custom file: ~/.dsh/keybindings.json)',
+            handler: invocation => hotkeysHandler(invocation.rawInput, invocation.signal),
+        }), 'dsh-tui-pi: /hotkeys');
         // ------------------------------------------------- powerline footer + git --
         const git = new GitBranchWatcher(process.cwd());
         git.onChange = () => ui.requestRender();
@@ -627,18 +874,18 @@ export function apply(ctx) {
         };
         ui.footer.clear();
         ui.footer.addChild(new PowerlineFooter(footerSource));
-        // Keybinding hint, added *after* the clear above: the placeholder line in
-        // tui.ts used to be wiped before first render. paddingX 1 aligns the text
-        // with the powerline segment labels (each starts with a leading space).
-        // The hint is the footer stack's only theme-dependent piece (the powerline
-        // segments carry fixed theme-agnostic colors) — `paintFooterHint` re-colors
-        // it under a theme hot-swap; the PowerlineFooter itself needs no rebuild.
-        const footerHint = new Text('', 1, 0);
-        const paintFooterHint = () => {
-            footerHint.setText(ansiFg(ui.theme.palette.fgSubtle) + '⌨ Enter: send · Ctrl+C: cancel / double: quit' + RESET);
-        };
-        paintFooterHint();
+        // Keybinding hint, added *after* the clear above: a single width-clipped
+        // row (never word-wraps) reading the live footer-hints selection through
+        // its getter — a /settings toggle applies on the next repaint, and the
+        // theme colors follow `ui.theme` (see FooterHint in footer.ts).
+        let footerHintsRef = footerHints;
+        const footerHint = new FooterHint(() => ui.theme, () => footerHintsRef);
         ui.footer.addChild(footerHint);
+        // Arm the footer-hints watch sink now that the TUI exists (see apply()).
+        applyFooterHintsRef = (hints) => {
+            footerHintsRef = hints;
+            ui.requestRender();
+        };
         /**
          * Hot-apply a theme bundle to the running TUI: the transcript rebuilds
          * from its replay buffer, the dock/editor swap to the new bundle, and the
@@ -654,7 +901,6 @@ export function apply(ctx) {
             renderer.setTheme(theme);
             liveWidgets.setTheme(theme);
             ui.applyTheme(theme);
-            paintFooterHint();
             if (loader !== undefined) {
                 loader.stop();
                 ui.status.removeChild(loader);
@@ -662,6 +908,34 @@ export function apply(ctx) {
                 setStatus(agentStatus);
             }
         };
+        // 'auto' refinement (the cmux/gostty case): COLORFGBG is often absent or
+        // wrong inside multiplexers, so the synchronous startup guess may be
+        // wrong. Ask the terminal itself — CSI ?996n color-scheme query first
+        // (Ghostty/cmux, kitty, iTerm answer), then the OSC 11 background color
+        // as ground truth — and hot-apply when the answer differs. Both queries
+        // time out silently on quiet terminals; the startup resolution stands.
+        if (themePreference === 'auto') {
+            ui.tui.setTerminalColorSchemeNotifications(true);
+            void (async () => {
+                const scheme = await ui.tui.queryTerminalColorScheme({ timeoutMs: 200 }).catch(() => undefined);
+                if (scheme === 'light' || scheme === 'dark') {
+                    applyTheme(resolveTheme(process.env, scheme));
+                    return;
+                }
+                const background = await ui.tui.queryTerminalBackgroundColor({ timeoutMs: 200 }).catch(() => undefined);
+                if (background !== undefined) {
+                    applyTheme(resolveTheme(process.env, rgbIsLight(background) ? 'light' : 'dark'));
+                }
+            })();
+        }
+        // Follow the terminal's live light/dark switches (CSI 997 pushes) while
+        // the preference is 'auto' — the terminal flips its OS appearance and the
+        // TUI repaints on the next frame, no restart. Explicit pins ignore it.
+        const stopTerminalFollow = ui.tui.onTerminalColorSchemeChange(scheme => {
+            if (themePreferenceRef !== 'auto')
+                return;
+            applyTheme(resolveTheme(process.env, scheme));
+        });
         // Live clock: the footer is the only thing that changes each second.
         const clockTimer = setInterval(() => ui.requestRender(), 1000);
         clockTimer.unref?.();
@@ -676,7 +950,7 @@ export function apply(ctx) {
          * "aborted due to timeout" — those run with a never-aborting signal
          * instead.
          */
-        const MODAL_COMMANDS = new Set(['settings', 'model', 'think', 'session', 'resume', 'theme', 'permission']);
+        const MODAL_COMMANDS = new Set(['settings', 'model', 'think', 'session', 'resume', 'theme', 'permission', 'agents', 'subagents']);
         /** Route one submitted line: dsh slash command first, model prompt second. */
         const submit = async (text) => {
             const line = text.trim();
@@ -785,11 +1059,13 @@ export function apply(ctx) {
             if (relayoutTimer !== undefined)
                 clearTimeout(relayoutTimer);
             process.stdout.removeListener('resize', onResize);
+            stopTerminalFollow();
             clearInterval(clockTimer);
             clearInterval(liveTimer);
             git.dispose();
             applyThemeRef = undefined;
             applyPanelHeightRef = undefined;
+            applyFooterHintsRef = undefined;
             // Stop the TUI FIRST, before the (possibly slow) agent teardown: the
             // terminal must be released while the fiber is still alone with it.
             // Deferring tui.stop() until after `await bridge.dispose()` lets any
@@ -803,6 +1079,11 @@ export function apply(ctx) {
             // fresh fiber. On shutdown the process exits and the stash dies with it
             // (harmless) — only /reload in the same process consumes it.
             stashSessionIdForReload(bridge.getSessionId());
+            if (quitConfirmTimer !== undefined)
+                clearTimeout(quitConfirmTimer);
+            if (stopConfirmTimer !== undefined)
+                clearTimeout(stopConfirmTimer);
+            subagentPolicy.dispose();
             try {
                 await bridge.dispose();
             }