@aiwayds/dsh-tui-pi 0.1.0 → 0.3.0

package/lib/theme/palette.d.ts

@@ -10,13 +10,19 @@
  *   fills are solid approximations of alpha tints blended over `canvas`
  *   (the terminal can't carry alpha) — same values as `blend()` below.
  *
- * The TUI never paints the main canvas (the terminal background shows
- * through), so `canvas` is the semantic base used by the dark muted blends
- * and by contrast design; `canvasSubtle` is the visible raised surface.
+ * The TUI paints every rendered row with `canvas` (patched pi-tui
+ * `setCanvasBackground`, see src/tui.ts) — the app owns its background, so
+ * a theme switch recolors the whole screen and the terminal/multiplexer
+ * background never shows through. `canvasSubtle` stays the visible raised
+ * surface on top of it. DSH_TUI_TRANSPARENT=1 reverts to the old
+ * see-through canvas, where `canvas` is only the semantic base for the dark
+ * muted blends and contrast design.
  */
 export interface Palette {
     /** Theme id, used by the theme switcher. */
     readonly name: string;
+    /** True for dark themes — components pick bright/light color variants on it. */
+    readonly dark: boolean;
     /** Main background (chat canvas). */
     readonly canvas: string;
     /** Slightly offset surface (message bubbles, code blocks, tool cards). */
@@ -54,3 +60,15 @@ export declare const githubDark: Palette;
  * this, so this only inspects terminal environment signals.
  */
 export declare function detectDarkPalette(env?: NodeJS.ProcessEnv): boolean;
+/** RGB triple as reported by pi-tui's OSC 11 background query. */
+export interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+}
+/**
+ * True when an OSC 11 background color reads as a light terminal (the same
+ * 0.5 luminance threshold pi uses for its terminal detection). Structural
+ * match for pi-tui's `RgbColor`, so the query result passes through as-is.
+ */
+export declare function rgbIsLight(rgb: Rgb): boolean;

package/lib/theme/palette.js

@@ -10,16 +10,20 @@
  *   fills are solid approximations of alpha tints blended over `canvas`
  *   (the terminal can't carry alpha) — same values as `blend()` below.
  *
- * The TUI never paints the main canvas (the terminal background shows
- * through), so `canvas` is the semantic base used by the dark muted blends
- * and by contrast design; `canvasSubtle` is the visible raised surface.
+ * The TUI paints every rendered row with `canvas` (patched pi-tui
+ * `setCanvasBackground`, see src/tui.ts) — the app owns its background, so
+ * a theme switch recolors the whole screen and the terminal/multiplexer
+ * background never shows through. `canvasSubtle` stays the visible raised
+ * surface on top of it. DSH_TUI_TRANSPARENT=1 reverts to the old
+ * see-through canvas, where `canvas` is only the semantic base for the dark
+ * muted blends and contrast design.
  */
 export const githubLight = {
     name: 'github-light',
+    dark: false,
     // Main canvas: near-white with a faint cool-green cast (not the harsh
-    // pure #fff); paper feel. The TUI never paints it — the terminal
-    // background (#f6f8fa) shows through; kept as the semantic base for the
-    // dark muted blends and contrast design.
+    // pure #fff); paper feel. Painted on every rendered row (see the module
+    // header) — the whole screen carries it.
     canvas: '#fcfdfc',
     // Raised surface (message bubbles, think/tool panels, overlays, code
     // blocks): one step darker than the canvas, clear gray-green.
@@ -83,6 +87,7 @@ function blend(base, over, alpha) {
 }
 export const githubDark = {
     name: 'github-dark',
+    dark: true,
     // Main canvas: deep gray-blue (the GitHub dark family).
     canvas: '#0d1117',
     // Raised surface (bubbles, panels, overlays): one step lighter gray-blue.
@@ -151,4 +156,20 @@ export function detectDarkPalette(env = process.env) {
     // Default to dark — GitHub's terminal default and the safer contrast choice.
     return true;
 }
+/** WCAG relative luminance of an RGB triple (0 = black, 1 = white). */
+function rgbLuminance({ r, g, b }) {
+    const toLinear = (channel) => {
+        const value = channel / 255;
+        return value <= 0.03928 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+    };
+    return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
+}
+/**
+ * True when an OSC 11 background color reads as a light terminal (the same
+ * 0.5 luminance threshold pi uses for its terminal detection). Structural
+ * match for pi-tui's `RgbColor`, so the query result passes through as-is.
+ */
+export function rgbIsLight(rgb) {
+    return rgbLuminance(rgb) >= 0.5;
+}
 //# sourceMappingURL=palette.js.map

package/lib/theme/palette.js.map

@@ -1 +1 @@
-{"version":3,"file":"palette.js","sourceRoot":"","sources":["../../src/theme/palette.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"palette.js","sourceRoot":"","sources":["../../src/theme/palette.ts"],"names":[],"mappings":"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"}

package/lib/theme-settings.d.ts

@@ -1,8 +1,10 @@
 /**
- * Theme settings: persists the user's theme preference and the think/tool
- * panel height under the `dsh-tui` settings namespace, surfaced by the
- * /settings browser and the /theme command. The preferences are read once at
- * TUI startup (`readThemePreference` / `readPanelHeightPreference`), and the
+ * Theme settings: persists the user's theme preference, the think/tool panel
+ * height, and the subagent concurrency/rounds limits under the `dsh-tui`
+ * settings namespace, surfaced by the /settings browser and the /theme
+ * command. The theme and panel-height preferences are read once at TUI
+ * startup (`readThemePreference` / `readPanelHeightPreference`); the subagent
+ * limits are read live at every policy decision (`readSubagentLimits`). The
  * namespace is marked `applies: 'live'`: a committed change (the /theme
  * picker, the /settings browser, an external edit) is pushed through the
  * watch hook, so the running TUI repaints without a restart.
@@ -13,6 +15,19 @@ import { type PanelHeight } from './messages.ts';
 import type { ThemePreference } from './theme/index.ts';
 /** Settings namespace carrying the persisted dsh-tui preferences. */
 export declare const THEME_SETTINGS_NAMESPACE: SettingsNamespace;
+/** Subagent concurrency/rounds knobs read by the subagent policy. */
+export interface SubagentLimits {
+    /** Concurrent live children allowed; 0 lifts the cap (the guard stays off). */
+    maxAgents: number;
+    /** Completed turns per child before a summary request is injected; 0 disables. */
+    maxRounds: number;
+}
+/**
+ * Default subagent limits, applied whenever the settings service, namespace,
+ * or a field cannot be read. 4 concurrent children and 50 rounds per child are
+ * the documented out-of-the-box behavior.
+ */
+export declare const DEFAULT_SUBAGENT_LIMITS: SubagentLimits;
 /**
  * Register the `dsh-tui` settings namespace with the settings provider.
  *
@@ -66,3 +81,23 @@ export declare function currentThemePreference(ctx: Context): ThemePreference;
  * @returns undefined on success, the failure message otherwise.
  */
 export declare function writeThemePreference(ctx: Context, pref: ThemePreference): Promise<string | undefined>;
+/**
+ * Read the currently resolved subagent limits, synchronously. Unlike the
+ * startup-snapshot readers, this does not wait for the namespace registration
+ * — it describes whatever the settings service exposes right now, so every
+ * policy decision (the guard at each spawn, `onTurnCount` at each child turn)
+ * reflects the latest committed value without a watcher. Missing settings
+ * service or namespace, or a non-integer/negative field, degrades to the
+ * defaults — a settings-less deployment keeps the documented caps.
+ */
+export declare function readSubagentLimits(ctx: Context): SubagentLimits;
+/**
+ * Persist one subagent limit (maxAgents or maxRounds) to the `dsh-tui`
+ * settings namespace. The namespace is `applies: 'live'`, so the commit
+ * hot-applies without a restart — the policy reads `readSubagentLimits` at
+ * the next decision point. Never throws: a deployment without the settings
+ * provider, or an unregistered namespace, surfaces a failure message for the
+ * caller.
+ * @returns undefined on success, the failure message otherwise.
+ */
+export declare function writeSubagentLimit(ctx: Context, key: 'maxAgents' | 'maxRounds', value: number): Promise<string | undefined>;

package/lib/theme-settings.js

@@ -1,8 +1,10 @@
 /**
- * Theme settings: persists the user's theme preference and the think/tool
- * panel height under the `dsh-tui` settings namespace, surfaced by the
- * /settings browser and the /theme command. The preferences are read once at
- * TUI startup (`readThemePreference` / `readPanelHeightPreference`), and the
+ * Theme settings: persists the user's theme preference, the think/tool panel
+ * height, and the subagent concurrency/rounds limits under the `dsh-tui`
+ * settings namespace, surfaced by the /settings browser and the /theme
+ * command. The theme and panel-height preferences are read once at TUI
+ * startup (`readThemePreference` / `readPanelHeightPreference`); the subagent
+ * limits are read live at every policy decision (`readSubagentLimits`). The
  * namespace is marked `applies: 'live'`: a committed change (the /theme
  * picker, the /settings browser, an external edit) is pushed through the
  * watch hook, so the running TUI repaints without a restart.
@@ -12,6 +14,12 @@ import z from '@deepseek-ai/schemastery';
 import { DEFAULT_PANEL_HEIGHT } from "./messages.js";
 /** Settings namespace carrying the persisted dsh-tui preferences. */
 export const THEME_SETTINGS_NAMESPACE = settingsNamespace('dsh-tui');
+/**
+ * Default subagent limits, applied whenever the settings service, namespace,
+ * or a field cannot be read. 4 concurrent children and 50 rounds per child are
+ * the documented out-of-the-box behavior.
+ */
+export const DEFAULT_SUBAGENT_LIMITS = Object.freeze({ maxAgents: 4, maxRounds: 50 });
 /** Schema of the `dsh-tui` settings section. */
 const THEME_SETTINGS_SCHEMA = z.object({
     theme: z
@@ -24,11 +32,23 @@ const THEME_SETTINGS_SCHEMA = z.object({
         .description("Think/tool panel height in displayed rows ('5'/'7'/'10' — header + content lines; "
         + "box borders add 2 more) or 'all' to print the full content — a streaming "
         + 'reasoning panel shows a 200-line live tail and tool results cap at 2000 lines'),
+    // `z.natural()` is schemastery's constraint for a non-negative integer
+    // (the `z.number().int().min(0)` intent — no `.int()` chain exists here).
+    maxAgents: z
+        .natural()
+        .default(DEFAULT_SUBAGENT_LIMITS.maxAgents)
+        .description('Max concurrently running subagents (0 = unlimited)'),
+    maxRounds: z
+        .natural()
+        .default(DEFAULT_SUBAGENT_LIMITS.maxRounds)
+        .description('Max rounds per subagent before the TUI sends a summary request (0 = unlimited)'),
 });
 /** Composition entry below the user layer: fall back to the defaults. */
 const THEME_SETTINGS_ENTRY = {
     theme: 'auto',
     panelHeight: DEFAULT_PANEL_HEIGHT,
+    maxAgents: DEFAULT_SUBAGENT_LIMITS.maxAgents,
+    maxRounds: DEFAULT_SUBAGENT_LIMITS.maxRounds,
 };
 /**
  * In-flight namespace registration. The registration rides the settings
@@ -178,14 +198,14 @@ export function currentThemePreference(ctx) {
     return 'auto';
 }
 /**
- * Persist one `dsh-tui` preference (theme or panelHeight) to the settings
- * namespace. The namespace is `applies: 'live'`, so the commit (observed
- * through the registration's watch hook) hot-applies the change to the
- * running TUI. Best-effort: a deployment without a settings provider reports
- * the failure; a failed write returns its error message for the caller to
- * surface. A concurrent writer moving the namespace rejects with
- * `SettingsConflictError` — retried once against a fresh revision; a second
- * conflict surfaces a friendly message instead of the raw error.
+ * Persist one `dsh-tui` preference (theme, panelHeight, or a subagent limit)
+ * to the settings namespace. The namespace is `applies: 'live'`, so the
+ * commit (observed through the registration's watch hook) hot-applies the
+ * change to the running TUI. Best-effort: a deployment without a settings
+ * provider reports the failure; a failed write returns its error message for
+ * the caller to surface. A concurrent writer moving the namespace rejects
+ * with `SettingsConflictError` — retried once against a fresh revision; a
+ * second conflict surfaces a friendly message instead of the raw error.
  * @returns undefined on success, the failure message otherwise.
  */
 async function writeDshTuiPreference(ctx, key, value) {
@@ -220,4 +240,41 @@ async function writeDshTuiPreference(ctx, key, value) {
 export async function writeThemePreference(ctx, pref) {
     return writeDshTuiPreference(ctx, 'theme', pref);
 }
+/**
+ * Read the currently resolved subagent limits, synchronously. Unlike the
+ * startup-snapshot readers, this does not wait for the namespace registration
+ * — it describes whatever the settings service exposes right now, so every
+ * policy decision (the guard at each spawn, `onTurnCount` at each child turn)
+ * reflects the latest committed value without a watcher. Missing settings
+ * service or namespace, or a non-integer/negative field, degrades to the
+ * defaults — a settings-less deployment keeps the documented caps.
+ */
+export function readSubagentLimits(ctx) {
+    const settings = ctx.get('settings');
+    if (settings === undefined)
+        return { ...DEFAULT_SUBAGENT_LIMITS };
+    // The descriptor's `value` is the whole resolved section
+    // (`{ theme: ..., panelHeight: ..., maxAgents: ..., maxRounds: ... }`) — narrow
+    // the unknown to the two observed numeric fields.
+    const section = settings
+        .describe()
+        .find((descriptor) => descriptor.ns === THEME_SETTINGS_NAMESPACE)?.value;
+    const natural = (value, fallback) => typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : fallback;
+    return {
+        maxAgents: natural(section?.maxAgents, DEFAULT_SUBAGENT_LIMITS.maxAgents),
+        maxRounds: natural(section?.maxRounds, DEFAULT_SUBAGENT_LIMITS.maxRounds),
+    };
+}
+/**
+ * Persist one subagent limit (maxAgents or maxRounds) to the `dsh-tui`
+ * settings namespace. The namespace is `applies: 'live'`, so the commit
+ * hot-applies without a restart — the policy reads `readSubagentLimits` at
+ * the next decision point. Never throws: a deployment without the settings
+ * provider, or an unregistered namespace, surfaces a failure message for the
+ * caller.
+ * @returns undefined on success, the failure message otherwise.
+ */
+export async function writeSubagentLimit(ctx, key, value) {
+    return writeDshTuiPreference(ctx, key, value);
+}
 //# sourceMappingURL=theme-settings.js.map

package/lib/theme-settings.js.map

@@ -1 +1 @@
-{"version":3,"file":"theme-settings.js","sourceRoot":"","sources":["../src/theme-settings.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"theme-settings.js","sourceRoot":"","sources":["../src/theme-settings.ts"],"names":[],"mappings":"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"}

package/lib/tui.d.ts

@@ -7,8 +7,10 @@
  *   │ scrollable transcript (ScrollView)   │  basis 0 / grow 1 — fills the rest
  *   ├──────────────────────────────────────┤
  *   │ statusContainer                      │  ┐
- *   │ widgetsContainer (Todos/Agents)      │  │ dock — basis auto / grow 0,
+ *   │ widgetsContainer (Todos)             │  │ dock — basis auto / grow 0,
  *   │ editor                               │  │ sized to its content
+ *   │ lastRequestContainer                 │  │  ← also hosts the merged
+ *   │   (last-request + activity lines)    │  │    running-agent activity
  *   │ footerContainer                      │  ┘
  *   └──────────────────────────────────────┘
  *
@@ -18,12 +20,24 @@
  */
 import { Container, type AutocompleteProvider, type TUI } from '@earendil-works/pi-tui';
 import { CwdBorderEditor } from './editor.ts';
+import { type KeyAction, type KeyBindings } from './keymap.ts';
 import { type ThemePreference, type TuiTheme } from './theme/index.ts';
 export interface StartTuiOptions {
     /** Submit handler for the editor. Defaults to a local echo (smoke-test mode). */
     onSubmit?: (text: string) => void;
-    /** Ctrl+C handler. Defaults to a plain exit (smoke-test mode). */
-    onInterrupt?: () => void;
+    /**
+     * Executes an app-level key action (see keymap.ts for the pi-aligned
+     * interrupt chain: double-Esc stop, windowed Ctrl+C, empty-editor Ctrl+D
+     * quit). Absent (smoke-test mode): Ctrl+C family and Ctrl+D quit fall back
+     * to a plain exit(130); interrupt-arm/arm-stop/double are no-ops.
+     */
+    onKeyAction?: (action: KeyAction) => void;
+    /** Whether the agent is mid-turn; feeds the Esc/Ctrl+C decision. Defaults to false. */
+    isRunning?: () => boolean;
+    /** Live running-subagent count; feeds the Ctrl+G viewer decision. Defaults to 0. */
+    getRunningAgents?: () => number;
+    /** User keybindings overrides (`~/.dsh/keybindings.json`); partial merge. */
+    keyBindings?: Partial<KeyBindings>;
     /** Persisted theme preference; 'auto' falls back to terminal detection. */
     themePreference?: ThemePreference;
 }
@@ -34,8 +48,13 @@ export interface TuiHandle {
     readonly tui: TUI;
     /** The scrollable transcript document container. */
     readonly transcript: Container;
-    /** Fixed slot pinned above the chat window — live Todos/Agents widgets. */
+    /** Fixed slot pinned above the chat window — the live Todos widget. */
     readonly widgets: Container;
+    /**
+     * Fixed dock slot below the editor — the last-request line + merged
+     * running-agent activity (LiveWidgets owns both).
+     */
+    readonly lastRequest: Container;
     /** Fixed dock slot rendered between transcript and editor. */
     readonly status: Container;
     /** The input editor. */
@@ -50,12 +69,13 @@ export interface TuiHandle {
      */
     readonly theme: TuiTheme;
     /**
-     * Hot-swap the theme bundle: repaints the editor border, the last-request
-     * line and (when empty) the placeholder, and updates every subsequent
-     * `theme` read. Transcript repainting is the TranscriptRenderer's job
-     * (`setTheme`), owned by the caller; call it before `applyTheme` so the
-     * one throttled render frame paints everything at once. No-op when the
-     * bundle is unchanged (themes are module singletons).
+     * Hot-swap the theme bundle: repaints the canvas background, the editor
+     * border and the placeholder, and updates every subsequent `theme` read.
+     * Transcript repainting is the TranscriptRenderer's job (`setTheme`), and
+     * the last-request / running-agent lines are the LiveWidgets' job
+     * (`setTheme`) — both owned by the caller; call them before `applyTheme`
+     * so the one throttled render frame paints everything at once. No-op when
+     * the bundle is unchanged (themes are module singletons).
      */
     applyTheme(theme: TuiTheme): void;
     /** Autocomplete provider for the editor; re-applied across editor rebuilds. */
@@ -64,7 +84,7 @@ export interface TuiHandle {
     setEditorBranchProvider(provider: () => string | undefined): void;
     /** Live permission-preset display-name source for the editor; re-applied across editor rebuilds. */
     setEditorPermissionProvider(provider: () => string | undefined): void;
-    /** Show/hide the "last request" widget below the editor. */
-    setLastRequest(text: string | undefined): void;
+    /** Swap the user keybindings live (`/hotkeys` writes → apply immediately). */
+    setKeyBindings(bindings: Partial<KeyBindings>): void;
 }
 export declare function startTui(options?: StartTuiOptions): TuiHandle;

package/lib/tui.js

@@ -7,8 +7,10 @@
  *   │ scrollable transcript (ScrollView)   │  basis 0 / grow 1 — fills the rest
  *   ├──────────────────────────────────────┤
  *   │ statusContainer                      │  ┐
- *   │ widgetsContainer (Todos/Agents)      │  │ dock — basis auto / grow 0,
+ *   │ widgetsContainer (Todos)             │  │ dock — basis auto / grow 0,
  *   │ editor                               │  │ sized to its content
+ *   │ lastRequestContainer                 │  │  ← also hosts the merged
+ *   │   (last-request + activity lines)    │  │    running-agent activity
  *   │ footerContainer                      │  ┘
  *   └──────────────────────────────────────┘
  *
@@ -16,20 +18,31 @@
  * session log during render; all session-derived state (messages, usage,
  * counts) is maintained incrementally by event listeners and read O(1) here.
  */
-import { Container, matchesKey, ProcessTerminal, ScrollView, Spacer, Text, TuiAltScreen, VStack, } from '@earendil-works/pi-tui';
+import { Container, ProcessTerminal, ScrollView, Spacer, Text, TuiAltScreen, VStack, } from '@earendil-works/pi-tui';
 import { CwdBorderEditor } from "./editor.js";
-import { ansiFg, RESET, resolveTheme } from "./theme/index.js";
-import { clipToWidth } from "./text.js";
+import { resolveKeyAction } from "./keymap.js";
+import { ansiBg, ansiFg, RESET, resolveTheme } from "./theme/index.js";
 export function startTui(options = {}) {
     const terminal = new ProcessTerminal();
     const tui = new TuiAltScreen(terminal, true);
     // Mutable theme ref: `applyTheme` swaps it and every later read (handle
     // getter, baked closures below) observes the new bundle on the next call.
     let themeRef = resolveTheme(process.env, options.themePreference ?? 'auto');
+    // App-owned canvas: every rendered row is painted with the palette's
+    // canvas background (patched pi-tui — see setCanvasBackground), so a theme
+    // switch recolors the WHOLE screen, not only the surfaces that paint their
+    // own bg. Without it the terminal default background shows through the
+    // unpainted rows and "freezes" on switch — most visible inside cmux/gostty,
+    // where the pane background belongs to the multiplexer. DSH_TUI_TRANSPARENT=1
+    // opts back into the old see-through canvas for users who want their
+    // terminal theme to stay visible.
+    const paintCanvas = process.env.DSH_TUI_TRANSPARENT !== '1';
+    if (paintCanvas)
+        tui.setCanvasBackground(ansiBg(themeRef.palette.canvas));
     // ------------------------------------------------------------- component tree --
-    // Live Todos/Agents widgets, pinned ABOVE the chat input: a plain Container
-    // with auto height — it renders zero rows while empty and grows to its
-    // (bordered-panel) content while the model has todos or subagents running.
+    // Live Todos widget, pinned ABOVE the chat input: a plain Container with
+    // auto height — it renders zero rows while empty and grows to its
+    // (bordered-panel) content while the model has todos.
     const widgets = new Container();
     const transcript = new Container();
     const transcriptView = new ScrollView(transcript, {
@@ -44,14 +57,19 @@ export function startTui(options = {}) {
     let editor = new CwdBorderEditor(tui, themeRef.editor, process.cwd(), {
         infoColor: text => ansiFg(themeRef.palette.fgMuted) + text + RESET,
     });
+    // User keybindings overrides — mutable so `/hotkeys` can live-apply a
+    // write without restarting the TUI (see `setKeyBindings`).
+    let keyBindingsRef = options.keyBindings;
     // External wiring that must survive editor rebuilds.
     let autocompleteProvider;
     let branchProvider;
     let permissionProvider;
+    // Last-request + merged running-agent activity, pinned BELOW the editor: a
+    // plain Container with auto height; LiveWidgets owns the ` ↳ ` line and the
+    // compact agent lines it hosts. It collapses to zero rows when both the
+    // last-request line is cleared and no subagent runs.
     const lastRequest = new Container();
     const footer = new Container();
-    let lastRequestText;
-    let lastRequestDisplay;
     const dock = new VStack([
         { component: status, shrink: 1, minSize: 0 },
         { component: widgets, shrink: 1, minSize: 0 },
@@ -71,6 +89,10 @@ export function startTui(options = {}) {
     editor.onSubmit = (text) => {
         if (text.trim() === '')
             return;
+        // Record the submitted message for Up/Down browse before dispatching —
+        // covers both the real path and the smoke-test fallback echo path. The
+        // editor's own `submitValue()` never calls `addToHistory` in pi-tui 0.84.2.
+        editor.addToHistory(text);
         if (options.onSubmit !== undefined) {
             options.onSubmit(text);
             return;
@@ -91,12 +113,23 @@ export function startTui(options = {}) {
      */
     function rebuildEditor() {
         const text = editor.getText();
+        // Preserve the Up/Down browse history AND the mid-browse cursor/draft
+        // across a theme-swap rebuild: the rebuild fires asynchronously (settings
+        // watch, CSI 997 terminal-follow) — precisely while the user may be sitting
+        // mid-browse with a pre-browse draft saved in the base. Copies `history`
+        // and `browse` so the swap restores exactly where the user was.
+        const history = editor.getHistory();
+        const browse = editor.getBrowseState();
         const hadFocus = editor.focused;
         const next = new CwdBorderEditor(tui, themeRef.editor, process.cwd(), {
             infoColor: text => ansiFg(themeRef.palette.fgMuted) + text + RESET,
         });
         next.setText(text);
         next.onSubmit = editor.onSubmit;
+        // `addToHistory` unshifts, so reseed oldest→newest to land in the same
+        // order on the new instance; then restore the browse cursor/draft.
+        next.reseedHistory(history);
+        next.restoreBrowseState(browse);
         if (autocompleteProvider !== undefined)
             next.setAutocompleteProvider(autocompleteProvider);
         if (branchProvider !== undefined)
@@ -121,6 +154,7 @@ export function startTui(options = {}) {
         tui,
         transcript,
         widgets,
+        lastRequest,
         status,
         get editor() {
             return editor;
@@ -136,10 +170,9 @@ export function startTui(options = {}) {
             if (theme === themeRef)
                 return;
             themeRef = theme;
+            if (paintCanvas)
+                tui.setCanvasBackground(ansiBg(theme.palette.canvas));
             rebuildEditor();
-            if (lastRequestDisplay !== undefined && lastRequestText !== undefined) {
-                lastRequestText.setText(ansiFg(themeRef.palette.fgMuted) + ` ↳ ${lastRequestDisplay}` + RESET);
-            }
             tui.requestRender();
         },
         setEditorAutocompleteProvider(provider) {
@@ -154,40 +187,80 @@ export function startTui(options = {}) {
             permissionProvider = provider;
             editor.setPermissionProvider(provider);
         },
-        setLastRequest(text) {
-            if (text === undefined || text.trim() === '') {
-                if (lastRequestText !== undefined) {
-                    lastRequest.removeChild(lastRequestText);
-                    lastRequestText = undefined;
-                    lastRequestDisplay = undefined;
-                }
-            }
-            else {
-                const display = clipToWidth(text, 200);
-                if (lastRequestText === undefined) {
-                    lastRequestText = new Text('', 1, 0);
-                    lastRequest.addChild(lastRequestText);
-                }
-                lastRequestDisplay = display;
-                lastRequestText.setText(ansiFg(themeRef.palette.fgMuted) + ` ↳ ${display}` + RESET);
-            }
-            tui.requestRender();
+        setKeyBindings(bindings) {
+            keyBindingsRef = bindings;
         },
     };
     // ------------------------------------------------------------- input & focus --
     tui.setFocus(editor);
+    /**
+     * App-level key dispatch — the pi interrupt chain (see keymap.ts):
+     * popup/overlay first (a popup closes itself and never stops the running
+     * task), then the editor's autocomplete, then the running agent — where a
+     * DOUBLE Esc within `DOUBLE_PRESS_MS` stops the whole task (parent +
+     * subagents; the first press only arms the stop window) — and finally the
+     * empty-editor double-press windows. Every decision is delegated to the
+     * pure `resolveKeyAction`; the listener only composes live state, advances
+     * the double-press timestamps, and reports whether the key was consumed.
+     * `matchesKey('escape')` is true for the lone ESC byte `\x1b` — and,
+     * because legacy terminal Ctrl+[ sends the same byte, for Ctrl+[ too
+     * (pi-tui keys.js normalizes both to `escape`).
+     */
+    let lastEscPress = 0;
+    let lastRunningEscPress = 0;
+    let lastCtrlCPress = 0;
+    const isRunning = options.isRunning ?? (() => false);
+    const getRunningAgents = options.getRunningAgents ?? (() => 0);
     tui.addInputListener((data) => {
-        if (matchesKey(data, 'ctrl+c')) {
-            if (options.onInterrupt !== undefined) {
-                options.onInterrupt();
+        const action = resolveKeyAction(data, {
+            running: isRunning(),
+            overlayOpen: tui.hasOverlay(),
+            editorHasText: editor.getText() !== '',
+            autocompleteOpen: editor.isShowingAutocomplete(),
+            runningAgents: getRunningAgents(),
+            lastEscPress,
+            lastRunningEscPress,
+            lastCtrlCPress,
+        }, Date.now(), keyBindingsRef);
+        // Advance the double-press windows for the keys this chain owns. Two
+        // separate Esc windows keep their own clocks: the running-stop arm
+        // (`interrupt-arm-stop` → `interrupt-cancel`) and the idle double-Esc
+        // (`interrupt-arm` → `interrupt-double`), so an Esc that armed a stop
+        // never pops /session once the turn settles inside the window, and vice
+        // versa. A fired stop re-arms the running clock at the cancel timestamp
+        // (Date.now() on `interrupt-cancel`): lashes of held-key Esc after the
+        // cancel land <80ms later and resolve as swallowable `key-repeat`
+        // instead of re-noticing another arm. `key-repeat` never advances a
+        // window — a held key must not arm or complete a double press
+        // (see keymap.ts).
+        if (action.kind === 'interrupt-arm' || action.kind === 'interrupt-double') {
+            lastEscPress = Date.now();
+        }
+        else if (action.kind === 'interrupt-arm-stop' || action.kind === 'interrupt-cancel') {
+            lastRunningEscPress = Date.now();
+        }
+        else if (action.kind === 'ctrl-c-cancel' || action.kind === 'ctrl-c-clear' || action.kind === 'ctrl-c-quit') {
+            lastCtrlCPress = Date.now();
+        }
+        // Pass-through outcomes (popup, autocomplete, unbound keys) let the
+        // focused component handle the key; actionable ones (key-repeat included,
+        // so the executor can abort a pending quit confirmation on it) go to the
+        // caller.
+        if (action.kind !== 'overlay' && action.kind !== 'autocomplete-close' && action.kind !== 'noop') {
+            if (options.onKeyAction !== undefined) {
+                options.onKeyAction(action);
             }
-            else {
+            else if (action.kind === 'ctrl-c-cancel' || action.kind === 'ctrl-c-clear'
+                || action.kind === 'ctrl-c-quit' || action.kind === 'ctrl-d-quit') {
+                // Smoke-test fallback: any Ctrl+C family press, or an empty-editor
+                // Ctrl+D, exits — Ctrl+C behaves like the pre-keymap build. (key-repeat
+                // deliberately excluded: no terminal is attached in smoke mode, but a
+                // repeat must never be an exit path by itself.)
                 handle.dispose();
                 process.exit(130);
             }
-            return { consume: true };
         }
-        return undefined;
+        return action.consumes ? { consume: true } : undefined;
     });
     tui.setLayoutRoot(root);
     try {