@aiwayds/dsh-tui-pi 2.17.0 → 2.18.0

package/README.md

@@ -2,7 +2,7 @@
 
 # dsh-tui-pi
 
-A fully-featured pi-style terminal UI for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) — a plugin suite that turns dsh into a pi-like coding-agent experience: /history look-back & fork-at-turn, guided preset switching, live subagent steering, model profiles, GitHub light/dark themes and a powerline footer.
+A fully-featured pi-style terminal UI for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) — a plugin suite that turns dsh into a pi-like coding-agent experience: /history look-back & fork-at-turn, guided preset switching, live subagent steering, model profiles, 20+ built-in themes (10 light + 10 dark) with user theme directory discovery, and a powerline footer.
 
 **Requires dsh >= 0.1.5-rc.2** — this plugin targets the dsh RC/stable line only (CI and releases resolve the newest of the `latest`/`next` dist-tags at runtime). **The alpha line is no longer supported.** A startup guard logs a one-line warning and exits cleanly when the host is older than the floor (opt out with `DSH_TUI_SKIP_HOST_CHECK=1`). See [ADR 0002](docs/adr/0002-target-dsh-0.1.2-alpha.3-single-target.md) for the now-superseded alpha single-target decision.
 
@@ -25,7 +25,7 @@ https://github.com/user-attachments/assets/67a7c6ca-ff42-4005-b543-437ba61771bb
 - [**Agent preset switching**](docs/features/preset-switch.md) — `/preset` between the shipped agent compositions (`standard`, `minimal`, …); a switch is confirmed and starts a NEW session on the preset (the current one stays resumable); what a preset really gates.
 - [**Sessions & resume**](docs/features/sessions-resume.md) — sessions stay tidy automatically and resume in a few keystrokes; the host's kernel write lease keeps the log single-writer across processes.
 - [**History browser**](docs/features/history.md) — `/history` opens a fixed two-pane look-back over the session: completed turns on the left, the selected turn's replies on the right; copy a prompt back to the editor, or cold-read any stored session without resuming it (read-only).
-- [**Themes**](docs/features/themes.md) — GitHub light/dark palettes, hot-switchable; `auto` follows your terminal.
+- [**Themes**](docs/features/themes.md) — 20 built-in palettes (10 light + 10 dark) plus user theme discovery (`~/.dsh/themes/`); hot-switchable, `auto` follows your terminal.
 - [**Search, selection & images**](docs/features/search-selection-images.md) — `Ctrl+Shift+F` over the whole transcript, drag-select copies to the OS clipboard, attachments from web/Feishu render inline, LaTeX replies draw as Unicode math.
 - [**Slash commands**](docs/features/slash-commands.md) — `/model`, `/resume`, `/btw`, … plus everything dsh-native.
 - [**Startup plugin tree**](docs/features/startup-tree.md) — every profile plugin with its installed npm version, printed at launch.
@@ -125,7 +125,7 @@ Every knob lives under the `dsh-tui` settings namespace in `~/.dsh/settings.yaml
 
 | Key | Default | Meaning |
 |---|---|---|
-| `theme` | `auto` | Color scheme: `auto` (follow the terminal) / `light` / `dark`; `/theme` writes back to the same key |
+| `theme` | `auto` | Color scheme: `auto` (follow the terminal) / `light` / `dark` / any registered theme name (`/theme` writes back to the same key) |
 | `panelHeight` | `'1'` | Think/tool panel height: `'1'` / `'5'` / `'7'` / `'10'` / `'all'` (full content) |
 | `maxAgents` | `4` | Max concurrently running subagents, `0` = unlimited (hot-tunable in `/agents → l` limits) |
 | `maxRounds` | `75` | Max assistant messages per subagent before a wrap-up request is injected; `0` = unlimited |

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 # dsh-tui-pi
 
-面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）的功能齐全的 pi 风格终端 UI——一套把 dsh 变成 pi 式编码代理体验的插件套件：/history 回看与任意轮分叉、确认式 preset 切换、subagent 实时操控、模型档案、GitHub 明/暗主题和 powerline 状态栏。
+面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）的功能齐全的 pi 风格终端 UI——一套把 dsh 变成 pi 式编码代理体验的插件套件：/history 回看与任意轮分叉、确认式 preset 切换、subagent 实时操控、模型档案、20+ 内置主题（10 亮 + 10 暗，支持用户主题目录自动发现）和 powerline 状态栏。
 
 **要求 dsh >= 0.1.5-rc.2** —— 本插件只跟随 dsh RC/stable 线（CI 与发版在运行时解析 latest/next 中更新的 dist-tag）。**不再支持 alpha 线。**宿主低于下限时，启动守卫会打一行 warning 并干净退出（可用 `DSH_TUI_SKIP_HOST_CHECK=1` 跳过）。alpha 单目标决策的历史见 [ADR 0002](docs/adr/0002-target-dsh-0.1.2-alpha.3-single-target.md)（已被取代）。
 
@@ -24,7 +24,7 @@ https://github.com/user-attachments/assets/67a7c6ca-ff42-4005-b543-437ba61771bb
 - [**模型 profile 与收藏**](docs/features/model-profiles.md) —— 按项目切换整套模型配置，选择器保持精简。
 - [**Agent preset 切换**](docs/features/preset-switch.md) —— `/preset` 在内置 agent 组合（`standard`、`minimal`……）间切换；切换需确认并会开启新会话（当前会话仍可 /resume 恢复）；preset 到底管什么。
 - [**Sessions 会话与恢复**](docs/features/sessions-resume.md) —— 会话自动保持整洁、几次按键恢复；跨进程写者守卫保证日志单写者。
-- [**Themes 主题**](docs/features/themes.md) —— GitHub 明/暗配色热切换；`auto` 跟随终端。
+- [**Themes 主题**](docs/features/themes.md) —— 20 个内置配色（10 亮 + 10 暗）+ 用户主题目录发现（`~/.dsh/themes/`）；热切换，`auto` 跟随终端。
 - [**搜索、选择与图片**](docs/features/search-selection-images.md) —— `Ctrl+Shift+F` 全文搜索、划选复制到系统剪贴板、web/飞书附件内联渲染、LaTeX 转 Unicode 数学。
 - [**斜杠命令**](docs/features/slash-commands.md) —— `/model`、`/resume`、`/btw`、`/profile-switch`……外加全部 dsh 原生命令。
 - [**启动插件树**](docs/features/startup-tree.md) —— 启动即打印每个 profile 插件及其安装的 npm 版本。
@@ -121,7 +121,7 @@ dsh plugin --profile tui add @aiwayds/dsh-topics-memory
 
 | 键 | 默认 | 作用 |
 |---|---|---|
-| `theme` | `auto` | 配色：`auto`（跟随终端）/`light`/`dark`；`/theme` 写回同一段 |
+| `theme` | `auto` | 配色：`auto`（跟随终端）/`light`/`dark`/任意已注册主题名；`/theme` 写回同一段 |
 | `panelHeight` | `'1'` | think/tool 面板高度：`'1'`/`'5'`/`'7'`/`'10'`/`'all'`（完整内容） |
 | `maxAgents` | `4` | 并发子代理上限，`0` = 不限（`/agents → l` limits 面板可热调） |
 | `maxRounds` | `75` | 每个子代理的 assistant 消息数上限，到达后注入收尾请求；`0` = 不限 |

package/lib/index.js

@@ -57,8 +57,9 @@ import { openSubmitRouteDialog } from "./route-dialog.js";
 import { BtwController, BTW_IDLE_NOTICE, BTW_USAGE, buildBtwSnapshot, parseBtwInput, resolveSnapshotLimit, } from "./btw.js";
 import { BtwOverlayWire } from "./btw-overlay.js";
 import { openPendingQueuePanel } from "./queue-panel.js";
-import { ansiFg, BOLD, darkTheme, lightTheme, RESET, resolveTheme } from "./theme/index.js";
+import { ansiFg, BOLD, RESET, resolveTheme } from "./theme/index.js";
 import { rgbIsLight } from "./theme/palette.js";
+import { discoverThemes, scanThemeDir, userThemesDir } from "./theme/registry.js";
 import { clipToWidth } from "./text.js";
 import {} from "./keymap.js";
 import { keybindingsPath, loadKeyBindings, openHotkeysManager } from "./hotkeys.js";
@@ -174,6 +175,15 @@ export function apply(ctx) {
     // silently dropping the bundled usage/config guide.
     ctx.skills.registerProvider(() => skillProvider);
     let handle;
+    // Theme registry: bundled themes/ plus $DSH_HOME/themes (user overrides
+    // bundled by name). Built ONCE per apply() and handed to every resolveTheme
+    // / pickTheme call site (startup, the settings watch sink, the /theme
+    // handler), so a custom theme named by DSH_TUI_THEME or by the persisted
+    // preference resolves through the same snapshot. `themeUserNames` marks
+    // which registry ids are user-owned (for the picker's "user theme" /
+    // "built-in" labels).
+    const themeRegistry = discoverThemes({ home: dshHome() });
+    const themeUserNames = new Set(scanThemeDir(userThemesDir(dshHome())).keys());
     // Live-session handle for the startup janitor (assigned inside the
     // render effect below, where the bridge is constructed): retention
     // polls the CURRENT session id at selection time and again right
@@ -525,6 +535,7 @@ export function apply(ctx) {
                 }
             },
             themePreference,
+            themeRegistry,
         });
         handle = ui;
         /**
@@ -591,7 +602,7 @@ export function apply(ctx) {
             // '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));
+            applyTheme(resolveTheme(process.env, pref, themeRegistry));
         };
         const renderer = new TranscriptRenderer(ui.transcript, ui.theme, () => ui.requestRender(), startupInfo);
         // Startup notices for a broken/misleading keybindings file — the TUI keeps
@@ -851,6 +862,20 @@ export function apply(ctx) {
         // Wiring through the handle: the editor is rebuilt on theme hot-swap, and
         // these providers are re-applied to the replacement instance.
         ui.setEditorAutocompleteProvider(commands.autocompleteProvider());
+        // One registration for both dispatch surfaces: CommandService.registerLocal
+        // (direct dispatch when no agent exists — no throwaway session) plus
+        // ctx.commands.register (discovery + lifecycle events against a live
+        // agent). Agentless bodies go through both, so autocomplete matches web.
+        const registerLocalCommand = (name, description, handler) => {
+            commands.registerLocal(name, handler);
+            ctx.effect(() => ctx.commands.register({
+                name,
+                description,
+                handler: invocation => handler(invocation.rawInput, invocation.signal),
+            }), `dsh-tui-pi: /${name}`);
+        };
+        /** Error message for notices — unknown catch values stringify safely. */
+        const messageOf = (e) => e instanceof Error ? e.message : String(e);
         // ------------------------------------------------------------ /btw (TUI-owned; ADR 0001) --
         // By-the-way side questions: one tool-less one-shot model call over a
         // read-only recent-conversation snapshot, streaming into a framed
@@ -928,12 +953,7 @@ export function apply(ctx) {
                     return { kind: 'error', text: `btw rejected — ${result.reason}.` };
             }
         };
-        commands.registerLocal('btw', btwHandler);
-        ctx.effect(() => ctx.commands.register({
-            name: 'btw',
-            description: 'Ask a side question while the main task runs (temp overlay, not kept)',
-            handler: invocation => btwHandler(invocation.rawInput, invocation.signal),
-        }), 'dsh-tui-pi: /btw');
+        registerLocalCommand('btw', 'Ask a side question while the main task runs (temp overlay, not kept)', btwHandler);
         // ------------------------------------------- TUI-owned slash commands --
         // Web-surface parity: `model` is a browser client contribution there and
         // `export` a web-only download plugin — the terminal gets native
@@ -960,12 +980,7 @@ export function apply(ctx) {
                 text: persistError === undefined ? modelText : `${modelText} · ⚠ not persisted: ${persistError}`,
             };
         };
-        commands.registerLocal('model', modelHandler);
-        ctx.effect(() => ctx.commands.register({
-            name: 'model',
-            description: 'Select the model (and think level) for this conversation',
-            handler: invocation => modelHandler(invocation.rawInput, invocation.signal),
-        }), 'dsh-tui-pi: /model');
+        registerLocalCommand('model', 'Select the model (and think level) for this conversation', modelHandler);
         // /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.
@@ -976,12 +991,7 @@ export function apply(ctx) {
                 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');
+        registerLocalCommand('agents', 'Manage agent definitions (model, think level, spawn depth) from markdown files', agentsHandler);
         // /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.
@@ -989,12 +999,7 @@ export function apply(ctx) {
             await openSubagentViewer(ctx, ui.tui, ui.theme, bridge, refocusEditor);
             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');
+        registerLocalCommand('subagents', 'Browse subagents and inspect their live transcript', subagentsHandler);
         // /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).
@@ -1037,12 +1042,7 @@ export function apply(ctx) {
                 text: persistError === undefined ? thinkText : `${thinkText} · ⚠ not persisted: ${persistError}`,
             };
         };
-        commands.registerLocal('think', thinkHandler);
-        ctx.effect(() => ctx.commands.register({
-            name: 'think',
-            description: 'Switch the current model\'s think (reasoning) level',
-            handler: invocation => thinkHandler(invocation.rawInput, invocation.signal),
-        }), 'dsh-tui-pi: /think');
+        registerLocalCommand('think', 'Switch the current model\'s think (reasoning) level', thinkHandler);
         /**
          * Record one committed preset as THIS workspace's remembered selection
          * (`$DSH_HOME/workspace-presets.json`, keyed by the session backend's
@@ -1179,12 +1179,7 @@ export function apply(ctx) {
                 persistRememberedPreset(target.id);
             return { kind: 'success', text: outcome.message };
         };
-        commands.registerLocal('preset', presetHandler);
-        ctx.effect(() => ctx.commands.register({
-            name: 'preset',
-            description: 'Switch the agent preset (starts a new session on it; /preset next cycles)',
-            handler: invocation => presetHandler(invocation.rawInput, invocation.signal),
-        }), 'dsh-tui-pi: /preset');
+        registerLocalCommand('preset', 'Switch the agent preset (starts a new session on it; /preset next cycles)', presetHandler);
         // Model profiles moved to the dsh-profile-switch plugin (ask-user based,
         // surface-agnostic). What stays HERE is the live-selection bridge it
         // consumes: the TUI's /model + /think ride the same selection ref, and
@@ -1226,12 +1221,7 @@ export function apply(ctx) {
             }, refocusEditor);
             return { kind: 'success', text: agent === undefined ? 'No active session.' : 'Session info shown.' };
         };
-        commands.registerLocal('session', sessionHandler);
-        ctx.effect(() => ctx.commands.register({
-            name: 'session',
-            description: 'Show the current session\'s info (id, model, stats)',
-            handler: invocation => sessionHandler(invocation.rawInput, invocation.signal),
-        }), 'dsh-tui-pi: /session');
+        registerLocalCommand('session', 'Show the current session\'s info (id, model, stats)', sessionHandler);
         // /resume: pick a persisted session, validate its log, swap the live
         // agent for it, and rebuild transcript + stats from the stored events.
         const resumeHandler = async () => {
@@ -1245,7 +1235,7 @@ export function apply(ctx) {
                 picked = await pickPersistedSession(ctx, ui.tui, ui.theme, currentId === undefined ? undefined : String(currentId), refocusEditor, resumeSettings);
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
+                const message = messageOf(error);
                 return { kind: 'error', text: message };
             }
             if (picked.kind === 'empty') {
@@ -1281,7 +1271,7 @@ export function apply(ctx) {
                     resumed = await bridge.resume(target.id);
                 }
                 catch (error) {
-                    const message = error instanceof Error ? error.message : String(error);
+                    const message = messageOf(error);
                     if (error instanceof SessionAlreadyOwnedError) {
                         // The host's kernel write lease refused the cold resume: another
                         // process drives this session. Rather than a dead end, degrade to
@@ -1302,7 +1292,7 @@ export function apply(ctx) {
                         catch (watchError) {
                             return {
                                 kind: 'error',
-                                text: `Cannot watch ${clipToWidth(String(target.id), 8)} read-only: ${watchError instanceof Error ? watchError.message : String(watchError)}`,
+                                text: `Cannot watch ${clipToWidth(String(target.id), 8)} read-only: ${messageOf(watchError)}`,
                             };
                         }
                     }
@@ -1366,7 +1356,7 @@ export function apply(ctx) {
                     notice = repairFailureNotice(await repairSessionLog(logPath));
                 }
                 catch (error) {
-                    const detail = error instanceof Error ? error.message : String(error);
+                    const detail = messageOf(error);
                     notice = `repair failed: ${detail} — log untouched`;
                 }
                 if (notice !== undefined)
@@ -1381,7 +1371,7 @@ export function apply(ctx) {
                 await inspectPersistedSession(ctx, picked.id);
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
+                const message = messageOf(error);
                 if (isCorruptLogError(message)) {
                     return offerCorruptedLogRepair(message);
                 }
@@ -1389,12 +1379,7 @@ export function apply(ctx) {
             }
             return resumeAndReplay();
         };
-        commands.registerLocal('resume', resumeHandler);
-        ctx.effect(() => ctx.commands.register({
-            name: 'resume',
-            description: 'Resume a persisted session',
-            handler: invocation => resumeHandler(invocation.rawInput, invocation.signal),
-        }), 'dsh-tui-pi: /resume');
+        registerLocalCommand('resume', 'Resume a persisted session', resumeHandler);
         // /history: the read-only two-pane look-back (ADR 0003) — left pane lists
         // the browsed session's completed turns, right pane shows the selected
         // turn's replies; Enter/c refills the editor with the turn's prompt (a
@@ -1460,12 +1445,7 @@ export function apply(ctx) {
             }, arg === '' ? undefined : arg);
             return { kind: result.error ? 'error' : 'success', text: result.text };
         };
-        commands.registerLocal('history', historyHandler);
-        ctx.effect(() => ctx.commands.register({
-            name: 'history',
-            description: 'Browse past turns of a session (read-only; /history <id> for a stored one)',
-            handler: invocation => historyHandler(invocation.rawInput, invocation.signal),
-        }), 'dsh-tui-pi: /history');
+        registerLocalCommand('history', 'Browse past turns of a session (read-only; /history <id> for a stored one)', historyHandler);
         // Auto-resume after a hot-reload: a `/reload` stashes the previously
         // current session id before this fiber's teardown, and the freshly
         // re-imported module consumes it best-effort here so the next prompt
@@ -1513,7 +1493,7 @@ export function apply(ctx) {
                     ui.requestRender();
                 }
                 catch (error) {
-                    const message = error instanceof Error ? error.message : String(error);
+                    const message = messageOf(error);
                     renderer.renderNotice(`--resume ${clipToWidth(bootResumeId, 8)}: ${message} — starting fresh.`, 'error');
                 }
             })();
@@ -1585,7 +1565,7 @@ export function apply(ctx) {
                 bridge.replay(session.snapshotEvents().filter(event => event.seq < session.firstLiveSeq));
             }
             catch (error) {
-                const detail = error instanceof Error ? error.message : String(error);
+                const detail = messageOf(error);
                 renderer.renderNotice('could not re-attach the previous session — it stays resumable via /resume;'
                     + ` the next prompt starts a fresh one (${detail})`, 'error');
             }
@@ -1595,12 +1575,7 @@ export function apply(ctx) {
             await startNewSession();
             return { kind: 'success', text: 'New session started.' };
         };
-        commands.registerLocal('new', newHandler);
-        ctx.effect(() => ctx.commands.register({
-            name: 'new',
-            description: 'Start a new session',
-            handler: invocation => newHandler(invocation.rawInput, invocation.signal),
-        }), 'dsh-tui-pi: /new');
+        registerLocalCommand('new', 'Start a new session', newHandler);
         // /settings: text-based configuration browser — the terminal counterpart
         // of the web GUI's settings surface. Enumerates ctx.settings.describe()
         // and walks each namespace's schema (drill-ins, cycle rows, inline editors,
@@ -1629,12 +1604,7 @@ export function apply(ctx) {
                     : `Settings: ${changes} change${changes === 1 ? '' : 's'} applied.`,
             };
         };
-        commands.registerLocal('settings', settingsHandler);
-        ctx.effect(() => ctx.commands.register({
-            name: 'settings',
-            description: 'Browse and edit configuration (namespaces, values, resets)',
-            handler: invocation => settingsHandler(invocation.rawInput, invocation.signal),
-        }), 'dsh-tui-pi: /settings');
+        registerLocalCommand('settings', 'Browse and edit configuration (namespaces, values, resets)', settingsHandler);
         // /skills: standalone skill browser with Installed/Available dual mode.
         // Enter/Space toggles or symlinks; Tab switches views; Esc exits.
         const skillsHandler = async () => {
@@ -1642,12 +1612,7 @@ export function apply(ctx) {
             openSkillsManagerPanel(ctx, ui.tui, ui.theme, refocusEditor, agent ?? undefined, () => { });
             return { kind: 'success', text: 'Skills manager opened.' };
         };
-        commands.registerLocal('skills', skillsHandler);
-        ctx.effect(() => ctx.commands.register({
-            name: 'skills',
-            description: 'Manage user skills (installed and available)',
-            handler: invocation => skillsHandler(invocation.rawInput, invocation.signal),
-        }), 'dsh-tui-pi: /skills');
+        registerLocalCommand('skills', 'Manage user skills (installed and available)', skillsHandler);
         // /theme: pick a color scheme and apply it immediately — the choice is
         // persisted to the dsh-tui settings namespace (`applies: 'live'`, so the
         // watch hook would re-apply the same change anyway) and hot-swapped into
@@ -1659,20 +1624,26 @@ export function apply(ctx) {
                 return { kind: 'error', text: 'Settings service is not available.' };
             }
             // Preselect from the live settings value (which may have changed since
-            // startup via the /settings browser), not the startup snapshot.
-            const picked = await pickTheme(ui.tui, ui.theme, currentThemePreference(ctx), refocusEditor);
+            // startup via the /settings browser), not the startup snapshot. The
+            // picker lists the registry themes (user + built-in) after the
+            // constant auto/light/dark rows.
+            const picked = await pickTheme(ui.tui, ui.theme, currentThemePreference(ctx), refocusEditor, {
+                themes: themeRegistry,
+                userNames: themeUserNames,
+            });
             if (picked === undefined)
                 return { kind: 'success', text: 'Theme unchanged.' };
             const writeError = await writeThemePreference(ctx, picked);
             if (writeError !== undefined)
                 return { kind: 'error', text: writeError };
             // DSH_TUI_THEME pins the display regardless of the preference — don't
-            // claim the pick was applied when it wasn't. The preference is still
-            // persisted (and shown once the env override is dropped); the notice
-            // goes through the buffered command echo, so no replay issue.
-            const applied = resolveTheme(process.env, picked);
+            // claim the pick was applied when it wasn't. Compare against the
+            // env-free resolution of the same pick (the bundle cache makes the
+            // reference comparison exact); 'auto' is skipped — it was never
+            // env-pin-sensitive (its display follows the terminal either way).
+            const applied = resolveTheme(process.env, picked, themeRegistry);
             applyTheme(applied);
-            const expected = picked === 'light' ? lightTheme : picked === 'dark' ? darkTheme : undefined;
+            const expected = picked === 'auto' ? undefined : resolveTheme({}, picked, themeRegistry);
             if (expected !== undefined && applied !== expected) {
                 return {
                     kind: 'success',
@@ -1681,12 +1652,7 @@ export function apply(ctx) {
             }
             return { kind: 'success', text: `Theme: ${picked} — applied.` };
         };
-        commands.registerLocal('theme', themeHandler);
-        ctx.effect(() => ctx.commands.register({
-            name: 'theme',
-            description: 'Set the terminal color scheme (applies immediately)',
-            handler: invocation => themeHandler(invocation.rawInput, invocation.signal),
-        }), 'dsh-tui-pi: /theme');
+        registerLocalCommand('theme', 'Set the terminal color scheme (applies immediately)', themeHandler);
         // /reload: hot-reload this plugin from the current source — re-imports the
         // module and its dependencies (picking up src changes after `pnpm build`)
         // and swaps the plugin runtime. The old fiber is disposed, so the TUI and
@@ -1696,12 +1662,7 @@ export function apply(ctx) {
             kind: 'success',
             text: await reloadPlugin(ctx, import.meta.url),
         });
-        commands.registerLocal('reload', reloadHandler);
-        ctx.effect(() => ctx.commands.register({
-            name: 'reload',
-            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');
+        registerLocalCommand('reload', 'Reload the TUI from the current source (apply code changes without restarting dsh)', reloadHandler);
         // /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).
@@ -1713,12 +1674,7 @@ export function apply(ctx) {
             });
             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');
+        registerLocalCommand('hotkeys', 'Show the current keybindings (custom file: ~/.dsh/keybindings.json)', hotkeysHandler);
         // /login: register provider credentials — the terminal counterpart of
         // pi-agent's /login, on the Models category's add-provider flow. Opens a
         // searchable provider directory (including already-configured routes, so
@@ -1749,12 +1705,7 @@ export function apply(ctx) {
                 return { kind: 'success', text: 'Login cancelled.' };
             return { kind: 'success', text: `Provider ${result.name} configured.` };
         };
-        commands.registerLocal('login', loginHandler);
-        ctx.effect(() => ctx.commands.register({
-            name: 'login',
-            description: 'Configure a provider API key (register or replace credentials)',
-            handler: invocation => loginHandler(invocation.rawInput, invocation.signal),
-        }), 'dsh-tui-pi: /login');
+        registerLocalCommand('login', 'Register provider credentials (API key) through the provider directory', loginHandler);
         // /logout: unsubscribe a provider — pi-agent's /logout on the dsh side.
         // Lists the providers with a stored credential; on selection removes the
         // key AND the settings.yaml provider entry, so the provider's models
@@ -1800,12 +1751,7 @@ export function apply(ctx) {
                 text: `Logged out ${result.name} — API key and provider configuration removed.`,
             };
         };
-        commands.registerLocal('logout', logoutHandler);
-        ctx.effect(() => ctx.commands.register({
-            name: 'logout',
-            description: 'Log out a provider (removes its API key and provider configuration)',
-            handler: invocation => logoutHandler(invocation.rawInput, invocation.signal),
-        }), 'dsh-tui-pi: /logout');
+        registerLocalCommand('logout', 'Log out a provider (removes its API key and provider configuration)', logoutHandler);
         // ------------------------------------------------- powerline footer + git --
         const git = new GitBranchWatcher(process.cwd());
         git.onChange = () => ui.requestRender();
@@ -1915,12 +1861,12 @@ export function apply(ctx) {
             void (async () => {
                 const scheme = await ui.tui.queryTerminalColorScheme({ timeoutMs: 200 }).catch(() => undefined);
                 if (scheme === 'light' || scheme === 'dark') {
-                    applyTheme(resolveTheme(process.env, scheme));
+                    applyTheme(resolveTheme(process.env, scheme, themeRegistry));
                     return;
                 }
                 const background = await ui.tui.queryTerminalBackgroundColor({ timeoutMs: 200 }).catch(() => undefined);
                 if (background !== undefined) {
-                    applyTheme(resolveTheme(process.env, rgbIsLight(background) ? 'light' : 'dark'));
+                    applyTheme(resolveTheme(process.env, rgbIsLight(background) ? 'light' : 'dark', themeRegistry));
                 }
             })();
         }
@@ -1930,7 +1876,7 @@ export function apply(ctx) {
         const stopTerminalFollow = ui.tui.onTerminalColorSchemeChange(scheme => {
             if (themePreferenceRef !== 'auto')
                 return;
-            applyTheme(resolveTheme(process.env, scheme));
+            applyTheme(resolveTheme(process.env, scheme, themeRegistry));
         });
         // Live clock: the footer is the only thing that changes each second.
         const clockTimer = setInterval(() => ui.requestRender(), 1000);
@@ -1982,7 +1928,7 @@ export function apply(ctx) {
                         // again; surface the failure in the transcript like every other
                         // dispatch error. Buffered notice: this line is the only record of
                         // the failure and must survive a theme-switch rebuild (doc.clear()).
-                        const message = error instanceof Error ? error.message : String(error);
+                        const message = messageOf(error);
                         renderer.renderNotice(message, 'error');
                         return;
                     }
@@ -2005,7 +1951,7 @@ export function apply(ctx) {
                 // the transcript instead of an unhandled rejection killing the TUI.
                 // Buffered notice: this line is the only record of the failure and
                 // must survive a theme-switch rebuild (doc.clear()).
-                const message = error instanceof Error ? error.message : String(error);
+                const message = messageOf(error);
                 renderer.renderNotice(message, 'error');
                 return;
             }
@@ -2045,7 +1991,7 @@ export function apply(ctx) {
             catch (error) {
                 // Buffered notice: the failure line is the only on-screen record and
                 // must survive a theme-switch rebuild (doc.clear()).
-                const message = error instanceof Error ? error.message : String(error);
+                const message = messageOf(error);
                 renderer.renderNotice(message, 'error');
             }
             // Session (re)created by the prompt: seed the badge cache. The initial