@aiwayds/dsh-tui-pi 0.20.0 → 0.21.0

package/README.md

@@ -116,7 +116,7 @@ Running subagent activity is shown in the **last-request area below the editor**
   ↳ ⠼ Subagent B 10s 任务 · 562 token · 6.0s
 ```
 
-Each line shows: spinner + agent **name**, retries (`↻N≤M`), compact **current-context usage** (`X/Y` — the child's latest request's billed input+output plus a CJK estimate of messages after it, over its context window; NOT the cumulative token spend, which only grows), rounds (`round N/M` — the assistant-message count against the cap, `M` only when `maxRounds > 0`), elapsed. No provider shown, no box, no header — just one line per running child.
+Each line shows: spinner + agent **name**, retries (`↻N≤M`), compact **current-context usage** (`X/Y` — the child's latest request's billed input+output plus a CJK estimate of messages after it, over its context window; NOT the cumulative token spend, which only grows), rounds (`round N/M` — the assistant-message count against the cap, `M` only when `maxRounds > 0`), elapsed, and a `⚡` marker when a policy injection (maxRounds wrap-up, steer) reached the child. No provider shown, no box, no header — just one line per running child.
 
 Both **spawn-driven** and **fork-driven** children are tracked — dsh creates both through `childSessionMeta`, which writes `origin: 'subagent'` + a `delegationDepth` budget together, so header discovery recognises either marker (a budget-without-origin header is admitted as a defensive fallback and labelled `fork <id8>`; current dsh does not produce that shape). Non-children stay off the board by **value**, not by field presence: the jsonl persistence backend materialises `delegationDepth: 0` on every restored header, so the gate requires a budget `> 0`. User-facing session forks (a forked *conversation*: `Session.fork` sets `parentSession` + `seedLength`, no budget) are deliberately kept off the subagent board and stay resumable via `/resume` — whose filter (`isResumableSessionHeader`) excludes exactly the delegated children (`origin: 'subagent'` or budget > 0).
 
@@ -143,7 +143,7 @@ Icons: `☑` completed, `◐` in-progress, `☐` pending. A settled child drops
 Two caps (`/agents` → `l` to configure):
 
 - **`maxAgents`** (default 4, `0` = unlimited) — spawns are denied when the cap is hit.
-- **`maxRounds`** (default 75, `0` = unlimited) — after a child's assistant messages (one per LLM round-trip — the "rounds") reach the cap, the TUI queues one wrap-up request and never force-stops.
+- **`maxRounds`** (default 75, `0` = unlimited) — after a child's assistant messages (one per LLM round-trip — the "rounds") reach the cap, the TUI injects one wrap-up directive and never force-stops: a running child receives it at its next step boundary (`steer` — the very next LLM round-trip), an idle child as its own next turn. The injection is visible: the compact line, the Ctrl+G picker row and the viewer header show a `⚡` marker, and the transcript renders the injected message as `⚡ <text>` — so a wrap-up the child LLM ignored can be told apart from one that never fired.
 
 ---
 
@@ -168,7 +168,7 @@ Inside a subagent, a committed compaction is visible too: DCP appends one `user/
 A user-editable markdown file whose content is appended to the **system prompt of the main agent this TUI creates** — borrows pi's `~/.pi/agent/APPEND_SYSTEM.md` convention, dsh side: `$DSH_HOME/APPEND_SYSTEM.md` (default `~/.dsh/APPEND_SYSTEM.md`, honors the same `$DSH_HOME` override as the rest of dsh).
 
 - **Hot-applied** — the section provider reads the file at every prompt assembly, so editing the file picks up on the **next request**: no restart, no watcher, no `/reload`.
-- **Auto-seeded on first run** — when the file is missing, the TUI seeds it once at startup from the shipped template `templates/APPEND_SYSTEM.md` (the English orchestrator-identity template: identity, core rules, execution workflow). An existing file is yours — the TUI never overwrites user content.
+- **Auto-seeded on first run** — when the file is missing, the TUI seeds it once at startup from the shipped template `templates/APPEND_SYSTEM.md` (the English orchestrator-identity template: identity, core rules, execution workflow — including the registered-subagents vocabulary rule: "subagent" means the registered subagents only). An existing file is yours — the TUI never overwrites user content; it only appends the marked todo-lifecycle section and (idempotently, by phrase match) the subagents rule when a file does not phrase them yet.
 - **TUI-owned section** — a marked block (`<!-- dsh-tui-pi:todo-lifecycle -->`) is appended once and then maintained idempotently so the model clears its `todo/write` list when every item is done. A marked file is left byte-identical on later startups.
 - **Legacy migration** — the same todo block used to be delivered through `~/.dsh/AGENTS.md`. On startup the TUI strips that block once (no-op when absent), so the guidance is never duplicated.
 - **Empty / unreadable = no section** — if the file is missing or can't be read, the section is silently dropped. No error, no TUI startup failure.
@@ -199,12 +199,12 @@ There's no slash command to toggle the feature — it's always on, controlled by
 
 ### Ask User Question
 
-While the model is mid-turn it can pause and ask you structured questions via the `ask_user_question` tool (`@deepseek-ai/dsh-tool-ask-user`, mounted by this profile's bundle patch). The TUI hosts the answering side: a framed overlay opens in place, the tool call stays pending until you answer, and your answers flow back to the model as a normal tool result.
+While the model is mid-turn it can pause and ask you structured questions via the `ask_user_question` tool (`@deepseek-ai/dsh-tool-ask-user`, mounted by this profile's bundle patch). The TUI hosts the answering side: a bordered panel pins itself directly above the chat input (the Todos-panel slot — no floating popup), takes the keyboard while open, the tool call stays pending until you answer, and your answers flow back to the model as a normal tool result.
 
-- **One overlay, all questions flattened** — every question renders as a header row followed by its supporting `detail` text (when the model supplies any), option rows, plus a `Type something.` sentinel row for free text. Single-select replaces on Enter; multi-select toggles (`[+]` marks).
+- **One panel, all questions flattened** — every question renders as a header row followed by its supporting `detail` text (when the model supplies any), option rows, plus a `Type something.` sentinel row for free text. Single-select replaces on Enter; multi-select toggles (`[+]` marks).
 - **Single-question fast path** — a lone single-select question submits immediately on Enter: picking an option or committing typed free text both submit right away (a question without options is answered by typing alone). A lone multiSelect question instead gets a `⏎ Confirm answers` row so you can pick several options before submitting.
 - **Multi-question review page** — with ≥ 2 questions a `⏎ Confirm answers` row hops to a review listing every answer, each row editable in place; `Submit answers` commits (Enter on it while an answer is missing flashes a hint instead of failing silently). After committing free text on one question the cursor hops to the next unanswered one.
-- **Double-Esc declines** — two Esc presses within 200 ms return a declined envelope (the model reads it as a normal reply that no answer was given); holding Esc does not accidentally fire (key auto-repeat below a minimum gap is ignored), and closing the overlay through any other path — theme swap, `/reload`, or the tool call being aborted — settles as declined too.
+- **Double-Esc declines** — two Esc presses within 200 ms return a declined envelope (the model reads it as a normal reply that no answer was given); holding Esc does not accidentally fire (key auto-repeat below a minimum gap is ignored), and the tool call being aborted settles as declined too. While the panel is open it owns the keyboard exactly like an open overlay: Esc never arms the running-task stop, and app keys (Ctrl+L/G/O, Tab) yield to the panel.
 - **Conservative-use guidance** — a system-prompt section nudges the model to ask only when it genuinely needs you (1–3 questions, 2–4 options each), so the TUI doesn't turn into a questionnaire.
 - **Keyboard** — `↑↓` navigate · `Enter` select/toggle/confirm · type into the sentinel for free text · `Esc` twice to decline.
 
@@ -219,7 +219,7 @@ Inspired by [juicesharp/rpiv-ask-user-question](https://github.com/juicesharp/rp
 | `/model` | Two-stage provider/model picker (then thinking level). Live switch, persisted; in-panel keys: `f` favorite · `h` hide · `/` filter (favorites/hidden persisted via settings). |
 | `/think` | Reasoning-effort picker for the current model (`Off`/`High`/`Max`). |
 | `/session` | Read-only info panel: id, cwd, model, token usage, event count. |
-| `/resume` | Pick a persisted session, validate its log, then restore it. |
+| `/resume` | Pick a persisted session, validate its log, then restore it. Ordered by last update (log-file mtime), newest first; the `Updated` column shows the effective time. |
 | `/new` | Detach the current session; the next prompt opens a fresh one. |
 | `/settings` | Text-based settings browser (namespaces, schema walk, inline editors, secrets masked). |
 | `/export` | Write the current session log as JSONL (`~/Downloads/dsh-session-<id>.jsonl`). |
@@ -229,6 +229,8 @@ Inspired by [juicesharp/rpiv-ask-user-question](https://github.com/juicesharp/rp
 | `/agents` | Manage agent markdown files + subagent limits (`maxAgents`, `maxRounds`). |
 | `/subagents` | Pick a running/recent subagent and watch its live transcript; `Enter` inside the viewer steers the child (see Subagents). |
 | `/reload` | Hot-reload the plugin from source (after `pnpm build`) without restarting dsh. |
+| `/login` | Log in to a provider: pick from the directory (or `/login openai` to jump), enter one API key. The **Custom provider…** entry (`/login custom`) opens a six-field form for any OpenAI/Anthropic-compatible gateway pi-ai does not ship — route id, display name, protocol, base URL, model list, API key — and writes the same hand-declared route the web Models page composes. |
+| `/logout` | Pick a logged-in provider and remove both the stored key and its provider profile. |
 | `/hotkeys` | Keybinding browser and live editor. |
 
 Anything that is not a resolvable command falls through to the model as an ordinary prompt.
@@ -390,7 +392,7 @@ dsh --profile tui        # or: dsh-tui-pi (bin shim)
 ```sh
 pnpm check    # tsc --noEmit
 pnpm build    # emit lib/
-pnpm test     # unit tests, node --test against lib/ (745 tests, pretest builds)
+pnpm test     # unit tests, node --test against lib/ (757 tests, pretest builds)
 ```
 
 Local type-checking symlinks `node_modules/@deepseek-ai/*` to the installed
@@ -421,8 +423,9 @@ src/
   footer.ts           PowerlineFooter (7 segments + clock)
   editor.ts           CwdBorderEditor (top border: cwd + git branch)
   subagent-policy.ts  maxAgents guard + maxRounds wrap-up injection
+                     (steer-when-running; ⚡-marked, visible in the viewer)
   subagent-viewer.ts  Ctrl+G picker + live transcript panel + Enter steer injection
-  ask-user.ts         Ask User Question overlay: pure state reducers +
+  ask-user.ts         Ask User Question docked panel: pure state reducers +
                       framed overlay UI + ctx.userQuestions provider
   steer-flow.ts       Steer / follow-up decision layer: routed delivery with
                       race fallback, queue actions (remove / promote), notices
@@ -431,7 +434,7 @@ src/
   queue-panel.ts      Ctrl+O pending-message queue: d remove · s steer now,
                       live-refreshed overlay
   theme/              GitHub light/dark palettes + terminal detection
-test/*.test.mjs       unit tests (728 across 44 files)
+test/*.test.mjs       unit tests (757 across 44 files)
 ```
 
 ---

package/README.zh.md

@@ -113,7 +113,7 @@ dsh ▸ volc-ark-plan ▸ deepseek-v4-flash ▸ high ▸ 48.7k/1.0M(4.6%) ▸
   ↳ ⠼ Subagent B 10s 任务 · 562 token · 6.0s
 ```
 
-每行显示：spinner + 代理**名称**，重试次数（`↻N≤M`），当前上下文占用（`X/Y` —— 子代理最近一次请求的 billed input+output 加上其后消息的 CJK 估算，除以它的上下文窗口；**不是**只增不减的累计 token 消耗），rounds（`round N/M` —— assistant 消息数对上限，`maxRounds > 0` 时才显示 `/M`），耗时。不显示 provider，无边框，无标题。
+每行显示：spinner + 代理**名称**，重试次数（`↻N≤M`），当前上下文占用（`X/Y` —— 子代理最近一次请求的 billed input+output 加上其后消息的 CJK 估算，除以它的上下文窗口；**不是**只增不减的累计 token 消耗），rounds（`round N/M` —— assistant 消息数对上限，`maxRounds > 0` 时才显示 `/M`），耗时，以及策略注入（maxRounds 收尾、steer）到达后出现的 `⚡` 标记。不显示 provider，无边框，无标题。
 
 **spawn 派生**与 **fork 派生**两类子代理都会被追踪——dsh 通过 `childSessionMeta` 同时写入 `origin: 'subagent'` 和 `delegationDepth` 预算，头部识别对两种标记都认得（只有预算没有 origin 的头部作为防御性兜底也会被接纳，标记为 `fork <id8>`；当前 dsh 不会产生这种形态）。非子代理会话按**值**而非字段有无被挡在板外：jsonl 持久化后端在每条恢复的头部上都会物化 `delegationDepth: 0`，所以闸门要求预算严格 `> 0`。面向用户的会话 fork（fork 出的*对话*：`Session.fork` 只设 `parentSession` + `seedLength`，不带预算）刻意不进子代理面板，仍可通过 `/resume` 恢复——`/resume` 的过滤器（`isResumableSessionHeader`）恰好排除被委派的子代理（`origin: 'subagent'` 或预算 > 0）。
 
@@ -138,7 +138,7 @@ dsh ▸ volc-ark-plan ▸ deepseek-v4-flash ▸ high ▸ 48.7k/1.0M(4.6%) ▸
 两个限制项（通过 `/agents` → `l` 配置）：
 
 - **`maxAgents`**（默认 4，`0` = 无限制）—— 超过上限时拒绝新的子代理创建。
-- **`maxRounds`**（默认 75，`0` = 无限制）—— 子代理的 assistant 消息数（每次 LLM 往返计 1 round）达到上限后，TUI 排队发送一个收尾请求，从不强制终止。
+- **`maxRounds`**（默认 75，`0` = 无限制）—— 子代理的 assistant 消息数（每次 LLM 往返计 1 round）达到上限后，TUI 注入一条收尾指令，从不强制终止：运行中的子代理在**下一步边界**收到（`steer`，即下一次 LLM 往返），空闲的作为自己的下一个 turn。注入可见：紧凑行、Ctrl+G 选择器行和查看器头部显示 `⚡`，对话记录里注入消息渲染为 `⚡ <文本>`——子代理 LLM 无视收尾指令与注入从未发生，现在可以区分。
 
 ---
 
@@ -163,7 +163,7 @@ dsh plugin --profile tui add @aiwayds/dsh-dcp
 一份用户可编辑的 markdown 文件，内容会**追加到 TUI 创建的主代理的系统提示末尾** —— 借鉴 pi 的 `~/.pi/agent/APPEND_SYSTEM.md` 约定，dsh 侧对应 `$DSH_HOME/APPEND_SYSTEM.md`（默认 `~/.dsh/APPEND_SYSTEM.md`，沿用 dsh 其余部分共用的 `$DSH_HOME` 覆盖）。
 
 - **热应用** —— section 提供者在每次组装提示词时读盘，改完文件**下一次请求**即生效：无需重启、无需 watcher、无需 `/reload`。
-- **首次启动自动播种** —— 文件不存在时，TUI 在启动时一次性从随包模板 `templates/APPEND_SYSTEM.md`（英文版协调者身份模板：身份、核心规则、执行工作流）创建。已有文件归用户所有 —— TUI 永远不会覆盖用户内容。
+- **首次启动自动播种** —— 文件不存在时，TUI 在启动时一次性从随包模板 `templates/APPEND_SYSTEM.md`（英文版协调者身份模板：身份、核心规则、执行工作流，含「subagent 仅指已注册子代理」的用语铁律）创建。已有文件归用户所有 —— TUI 永远不会覆盖用户内容；只在缺失标记的 todo-lifecycle 段、或尚未出现 subagents 铁律措辞（按短语匹配，幂等）时追加对应段落。
 - **TUI 自有段落** —— 一段带标记的 block（`<!-- dsh-tui-pi:todo-lifecycle -->`）只在缺失时追加一次，并保持幂等，确保模型在所有 todo 都完成时清空 `todo/write` 列表。已带标记的文件后续启动原样保留。
 - **旧版迁移** —— 同一段 todo block 早期通过 `~/.dsh/AGENTS.md` 下发。启动时 TUI 一次性把它剥掉（无标记时 no-op），避免重复下发。
 - **空 / 读不到 = 不挂载该 section** —— 文件缺失或读不了时该 section 被静默丢弃，无报错、不影响 TUI 启动。
@@ -199,7 +199,7 @@ EOF
 | `/model` | 两阶段选择 provider/model（然后选推理等级），实时切换并持久化。面板内按键：`f` 收藏 · `h` 隐藏 · `/` 过滤（收藏/隐藏经 settings 持久化）。 |
 | `/think` | 当前模型的推理强度选择（`Off`/`High`/`Max`）。 |
 | `/session` | 只读信息面板：id、cwd、模型、token 用量、事件计数。 |
-| `/resume` | 选择已保存的会话，验证日志后恢复。 |
+| `/resume` | 选择已保存的会话，验证日志后恢复。按最后更新时间排序（日志文件 mtime），新的在上；`Updated` 列显示生效时间。 |
 | `/new` | 分离当前会话；下一次输入开启新会话。 |
 | `/settings` | 文本式设置浏览器（命名空间、schema 遍历、内联编辑器、密钥脱敏）。 |
 | `/export` | 将当前会话日志导出为 JSONL（默认 `~/Downloads/dsh-session-<id>.jsonl`）。 |
@@ -209,6 +209,8 @@ EOF
 | `/agents` | 管理 agent markdown 文件 + 子代理限制（`maxAgents`、`maxRounds`）。 |
 | `/subagents` | 选择运行中/最近的子代理，查看其实时对话。 |
 | `/reload` | 从源码热重载插件（`pnpm build` 后执行，无需重启 dsh）。 |
+| `/login` | 登录 provider：从目录选择（或 `/login openai` 直达），输入一个 API key。**Custom provider…** 条目（`/login custom`）打开六字段表单，接入 pi-ai 未收录的任意 OpenAI/Anthropic 兼容网关 —— 路由 id、显示名、协议、base URL、模型列表、API key —— 写出与 Web Models 页相同的 hand-declared 路由。 |
+| `/logout` | 选择已登录的 provider，同时删除存储的 key 和 provider 配置。 |
 | `/hotkeys` | 快捷键浏览器和实时编辑。 |
 
 不是已注册命令的内容会作为普通提示词发送给模型。
@@ -383,6 +385,7 @@ src/
   footer.ts           PowerlineFooter（7 分段 + 时钟）
   editor.ts           CwdBorderEditor（顶部边框：cwd + git 分支）
   subagent-policy.ts  maxAgents 守卫 + maxRounds 收尾请求注入
+                     （运行中走 steer；⚡ 标记，查看器可见）
   subagent-viewer.ts  Ctrl+G 选择器 + 实时对话面板
   theme/              GitHub light/dark 配色 + 终端检测
 test/*.test.mjs       单元测试（569 个，覆盖 38 个文件）

package/lib/append-system.d.ts

@@ -26,6 +26,14 @@ export declare const TODO_LIFECYCLE_MARKER = "<!-- dsh-tui-pi:todo-lifecycle -->
  * an all-completed list would stay pinned above the chat input.
  */
 export declare const TODO_LIFECYCLE_SECTION = "<!-- dsh-tui-pi:todo-lifecycle -->\n## Todo list lifecycle (dsh-tui-pi)\n\nThe UI renders your todo list as a fixed panel above the chat input. Keep\nitems `pending` or `in_progress` while they are not done. When EVERY todo is\ncompleted \u2014 no pending or in-progress items remain \u2014 write an EMPTY todo list\n(`todos: []`) so the panel clears. Never leave a fully-completed list behind.\n";
+/**
+ * The subagent vocabulary rule (user iron rule, 2026-08-24): "subagent" means
+ * the registered subagents only. Shipped inside the template's Core rules for
+ * fresh installs; appended idempotently to pre-template files that lack it.
+ */
+export declare const SUBAGENTS_RULE_SECTION = "## Subagents\n\nWhen the user says \"subagent\", they mean the registered subagents only; never use unregistered subagents.\n";
+/** Idempotency phrase for the subagents rule (matches template and section). */
+export declare const SUBAGENTS_RULE_PHRASE = "registered subagents only";
 /** Default harness home: `$DSH_HOME` or `~/.dsh`. */
 export declare function dshHome(): string;
 /** The user-editable append file path (`$DSH_HOME/APPEND_SYSTEM.md`). */
@@ -49,12 +57,13 @@ export declare function readAppendSystem(path?: string): string;
  * marked todo-lifecycle section: a missing file is seeded from
  * `templates/APPEND_SYSTEM.md` (the English orchestrator template) followed
  * by the marked section; an existing file is user-owned — only the marked
- * section is appended when its marker is missing, and a marked file is left
- * untouched.
+ * section is appended when its marker is missing, a marked file is left
+ * untouched, and the subagents vocabulary rule is appended to any file that
+ * does not phrase it yet (template ships it as a Core rule).
  * @param path - target file (injectable for tests).
  * @param templatePath - the shipped template (injectable for tests).
  * @returns an error message on failure, undefined on success (including the
- *   no-op case where the marker is already present).
+ *   no-op case where the marker and the rule are already present).
  */
 export declare function ensureAppendSystemFile(path?: string, templatePath?: string): Promise<string | undefined>;
 /**

package/lib/append-system.js

@@ -38,6 +38,27 @@ items \`pending\` or \`in_progress\` while they are not done. When EVERY todo is
 completed — no pending or in-progress items remain — write an EMPTY todo list
 (\`todos: []\`) so the panel clears. Never leave a fully-completed list behind.
 `;
+/**
+ * The subagent vocabulary rule (user iron rule, 2026-08-24): "subagent" means
+ * the registered subagents only. Shipped inside the template's Core rules for
+ * fresh installs; appended idempotently to pre-template files that lack it.
+ */
+export const SUBAGENTS_RULE_SECTION = `## Subagents
+
+When the user says "subagent", they mean the registered subagents only; never use unregistered subagents.
+`;
+/** Idempotency phrase for the subagents rule (matches template and section). */
+export const SUBAGENTS_RULE_PHRASE = 'registered subagents only';
+/**
+ * Append the subagents rule unless the content already carries it (the shipped
+ * template embeds it as a Core rule; a hand-edited file may phrase it anywhere
+ * — the case-insensitive phrase check accepts both).
+ */
+function withSubagentsRule(content) {
+    if (content.toLowerCase().includes(SUBAGENTS_RULE_PHRASE))
+        return content;
+    return `${content.replace(/\s+$/u, '')}\n\n${SUBAGENTS_RULE_SECTION}`;
+}
 /** Default harness home: `$DSH_HOME` or `~/.dsh`. */
 export function dshHome() {
     return process.env.DSH_HOME ?? join(homedir(), '.dsh');
@@ -78,12 +99,13 @@ export function readAppendSystem(path = appendSystemPath()) {
  * marked todo-lifecycle section: a missing file is seeded from
  * `templates/APPEND_SYSTEM.md` (the English orchestrator template) followed
  * by the marked section; an existing file is user-owned — only the marked
- * section is appended when its marker is missing, and a marked file is left
- * untouched.
+ * section is appended when its marker is missing, a marked file is left
+ * untouched, and the subagents vocabulary rule is appended to any file that
+ * does not phrase it yet (template ships it as a Core rule).
  * @param path - target file (injectable for tests).
  * @param templatePath - the shipped template (injectable for tests).
  * @returns an error message on failure, undefined on success (including the
- *   no-op case where the marker is already present).
+ *   no-op case where the marker and the rule are already present).
  */
 export async function ensureAppendSystemFile(path = appendSystemPath(), templatePath = appendSystemTemplatePath()) {
     let existing;
@@ -93,10 +115,14 @@ export async function ensureAppendSystemFile(path = appendSystemPath(), template
     catch {
         existing = '';
     }
-    if (existing.includes(TODO_LIFECYCLE_MARKER))
-        return undefined;
+    if (existing.includes(TODO_LIFECYCLE_MARKER)) {
+        // Marker section already maintained — only the subagents rule may be new.
+        if (existing.toLowerCase().includes(SUBAGENTS_RULE_PHRASE))
+            return undefined;
+        return writeAtomically(path, withSubagentsRule(existing));
+    }
     if (existing !== '') {
-        return writeAtomically(path, `${existing.replace(/\s+$/u, '')}\n\n${TODO_LIFECYCLE_SECTION}`);
+        return writeAtomically(path, withSubagentsRule(`${existing.replace(/\s+$/u, '')}\n\n${TODO_LIFECYCLE_SECTION}`));
     }
     // Fresh file: seed from the shipped template, then the marked section. A
     // missing template (broken tarball) degrades to the marked section alone.
@@ -108,7 +134,7 @@ export async function ensureAppendSystemFile(path = appendSystemPath(), template
         template = '';
     }
     const seed = template === '' ? TODO_LIFECYCLE_SECTION : `${template.replace(/\s+$/u, '')}\n\n${TODO_LIFECYCLE_SECTION}`;
-    return writeAtomically(path, seed);
+    return writeAtomically(path, withSubagentsRule(seed));
 }
 /**
  * Migration: strip the TUI-owned todo-lifecycle block from `~/.dsh/AGENTS.md`

package/lib/append-system.js.map

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

package/lib/ask-user.d.ts

@@ -2,52 +2,62 @@
  * Ask the human a question while the model is mid-turn.
  *
  * Wires the upstream `ctx.userQuestions` capability seam (`dsh-user-questions`)
- * with a terminal-side UI: an in-place multi-question overlay that pauses the
- * tool call until the human answers, then feeds the canonical
+ * with a terminal-side UI: a DOCKED panel pinned above the chat input (the
+ * Todos-panel slot of the widgets dock — not a floating overlay) that pauses
+ * the tool call until the human answers, then feeds the canonical
  * `AskUserQuestionAnswer` envelope back to `dsh-tool-ask-user` as a normal
  * tool result.
  *
- * Layout — one framed overlay, all questions flattened (numbered rows, a
+ * Layout — one bordered dock panel, all questions flattened (numbered rows, a
  * divider between each question block and its options, and a scroll window
- * so the cursor row is always visible even when the overlay is height-capped):
+ * so the cursor row is always visible even when the dock is height-capped):
  *
- *   ● Questions (2)
- *     SELECTION
- *     ─────────────────────────────        (table chrome)
- *     Fruit  Where should we deploy?      (header — not selectable)
- *     ─────────────────────────────        (divider)
- *     ▸ ● 1. staging                      (cursor + inline selection mark)
- *       ○ 2. production
- *          red and round                  (option description, own muted line)
- *         3. Type something.              (sentinel row — inline input)
- *                                          (blank separator before confirm)
- *         ⏎ Confirm answers               (when ≥ 2 questions, or any multiSelect)
+ *   ┌────────────────────────────────────┐
+ *   │ ● Questions (2)                    │
+ *   │ SELECTION                          │
+ *   │ ─────────────────────────────      │   (table chrome)
+ *   │ Fruit  Where should we deploy?     │   (header — not selectable)
+ *   │ ─────────────────────────────      │   (divider)
+ *   │ ▸ ● 1. staging                     │   (cursor + inline selection mark)
+ *   │   ○ 2. production                  │
+ *   │      red and round                 │   (option description, own muted line)
+ *   │     3. Type something.             │   (sentinel row — inline input)
+ *   │                                    │   (blank separator before confirm)
+ *   │     ⏎ Confirm answers              │   (when ≥ 2 questions, or any multiSelect)
+ *   └────────────────────────────────────┘
+ *
+ * While the panel is open it owns the keyboard: it is mounted into the dock
+ * slot between the live widgets and the editor, takes focus through
+ * `tui.setFocus`, and `setModalActive(true)` routes the app keymap exactly
+ * like an open overlay (Esc/Ctrl+C/app keys yield to the panel — Esc never
+ * arms the running-task stop from inside a modal). On close the panel
+ * unmounts, clears the modal flag, and focus returns to the current editor
+ * through `restoreFocus`.
  *
  * The body renders through a scroll window sized from the live terminal
- * height (`askUserMaxVisibleForRows`; falls back to `ASK_USER_MAX_VISIBLE`
- * when the terminal row count is unknown):
- * pi-tui hard-clips overlay tails at `maxHeight`, so without an inner window
- * the last options fall off-screen while the cursor can still reach them
- * ("unselectable" bug). The window slides with the cursor and the footer
- * gains a `(n/m)` position readout while content overflows.
+ * height (`askUserMaxVisibleForRows`; the dock budget subtracts the editor,
+ * footer and a transcript floor, and falls back to `ASK_USER_MAX_VISIBLE`
+ * when the terminal row count is unknown): pi-tui would lay a taller dock
+ * out at full height and squeeze the transcript to nothing, so the window
+ * caps the body. The window slides with the cursor and the footer gains a
+ * `(n/m)` position readout while content overflows.
  *
- * Single-question single-select overlay: Enter on an option (or committing a
+ * Single-question single-select panel: Enter on an option (or committing a
  * filled sentinel) submits immediately. A multiSelect question — even a lone
  * one — gets a Confirm row instead of auto-submitting, so the user can pick
- * several options first. Multi-question overlay: Enter on the Confirm row
- * hops to the review page (all answers listed, each editable in place).
- * Esc double-press within 200 ms declines — but terminal key auto-repeat
- * (holding Esc) is ignored below `ESC_REPEAT_GUARD_MS`, so a long press
- * cannot accidentally fire the decline. The provider returns the "declined"
- * envelope and the model reads it as a normal user reply. An aborted
- * request signal (`request.signal`) settles declined too — we resolve the
- * declined envelope instead of rejecting ASK_ABORTED because the upstream
- * service already screens entry-time aborts and an aborted step discards
- * the result anyway.
+ * several options first. Multi-question panel: Enter on the Confirm row hops
+ * to the review page (all answers listed, each editable in place). Esc
+ * double-press within 200 ms declines — but terminal key auto-repeat (holding
+ * Esc) is ignored below `ESC_REPEAT_GUARD_MS`, so a long press cannot
+ * accidentally fire the decline. The provider returns the "declined" envelope
+ * and the model reads it as a normal user reply. An aborted request signal
+ * (`request.signal`) settles declined too — we resolve the declined envelope
+ * instead of rejecting ASK_ABORTED because the upstream service already
+ * screens entry-time aborts and an aborted step discards the result anyway.
  *
  * Pure logic lives in the top of this file (initial state, answer envelope,
- * declined envelope, double-Esc state machine, row-layout math) so it can
- * be unit-tested without a TTY. The component below owns the TUI render +
+ * declined envelope, double-Esc state machine, row-layout math) so it can be
+ * unit-tested without a TTY. The component below owns the TUI render +
  * keyboard handling; the install function at the bottom registers the
  * provider under `ctx.userQuestions` (a Cordis effect, single active
  * provider in the tree).
@@ -55,7 +65,7 @@
  * Inspired by juicesharp/rpiv-ask-user-question
  * (https://github.com/juicesharp/rpiv-ask-user-question).
  */
-import { type TUI } from '@earendil-works/pi-tui';
+import { type Component, type TUI } from '@earendil-works/pi-tui';
 import type { AskUserQuestionAnswer, AskUserQuestionItem, AskUserQuestionOption } from '@deepseek-ai/dsh-user-questions';
 import type { Context } from '@deepseek-ai/cordis';
 import { type TuiTheme } from './theme/index.ts';
@@ -77,23 +87,21 @@ export declare const INCOMPLETE_HINT = "Answer every question first";
 /**
  * Fallback visible body-line cap for the questions/review panes, used only
  * when the terminal row count is unknown (fake TUIs in tests, exotic
- * terminals). Derived for a 24-row terminal (the e2e matrix floor): 80%
- * maxHeight = 19 framed lines − 2 frame borders = 17 content lines, and
- * title(1) + table chrome(3) + 9 body lines + bottom rule + blank + footer
- * = 16, leaving one line of headroom for a hint. The live path derives the
- * window from the real terminal height via `askUserMaxVisibleForRows`.
+ * terminals). Matches the 24-row dock budget: 24 − 8 reserved (editor 3 +
+ * footer 1 + status 1 + transcript floor 3) − 10 panel chrome lines = 6.
+ * The live path derives the window from the real terminal height via
+ * `askUserMaxVisibleForRows`.
  */
-export declare const ASK_USER_MAX_VISIBLE = 9;
+export declare const ASK_USER_MAX_VISIBLE = 6;
 /**
- * Derive the scroll-window size from the terminal height so the window grows
- * with the terminal instead of pinning to the conservative 24-row budget:
- * pi-tui hard-clips the framed overlay at its resolved maxHeight, so body
- * lines beyond `budget − ASK_USER_VIEW_OVERHEAD` would be invisible anyway.
- * At the 24-row e2e floor this yields exactly ASK_USER_MAX_VISIBLE (9);
- * larger terminals scale up proportionally. Without a usable row count it
- * degrades to ASK_USER_MAX_VISIBLE.
+ * Derive the scroll-window size from the terminal height: the dock stacks
+ * (it does not float over the transcript like the old overlay did), so the
+ * panel budget is the terminal height minus the reserved dock rows, minus
+ * the panel's own chrome. At the 24-row e2e floor this yields exactly
+ * ASK_USER_MAX_VISIBLE (6); larger terminals scale up. Without a usable row
+ * count it degrades to ASK_USER_MAX_VISIBLE.
  */
-export declare function askUserMaxVisibleForRows(termRows: number | undefined, maxHeight?: AskUserPanelDeps['maxHeight']): number;
+export declare function askUserMaxVisibleForRows(termRows: number | undefined): number;
 /** A row in the multi-question view. */
 export interface FlatRow {
     kind: 'question-header' | 'option' | 'sentinel' | 'confirm';
@@ -237,28 +245,38 @@ export declare function renderReviewView(theme: TuiTheme, state: AskUserState, w
 /** Options for assembling the panel + provider function. */
 export interface AskUserPanelDeps {
     tui: TUI;
-    /** Live theme getter — re-read on every render so a mid-overlay hot-swap applies (frame included). */
+    /** Live theme getter — re-read on every render so a mid-panel hot-swap applies (borders included). */
     theme: () => TuiTheme;
-    /** Re-focus the current editor on overlay close. */
+    /** Re-focus the current editor on panel close. */
     restoreFocus: () => void;
+    /**
+     * Mount the panel component into the dock slot above the chat input (the
+     * Todos-panel slot); returns the unmount function. The panel is NOT an
+     * overlay — it renders pinned above the editor like the live widgets.
+     */
+    mount: (component: Component) => () => void;
+    /**
+     * Declare the docked modal's keyboard ownership. While active, the app
+     * keymap treats the panel exactly like an open overlay (app keys and the
+     * Esc/Ctrl+C chains yield to the focused panel) and `refocusEditor` must
+     * not steal focus from it.
+     */
+    setModalActive: (active: boolean) => void;
     /** Injectable clock for tests; defaults to Date.now. */
     now?: () => number;
-    /** Width and height of the framed overlay. */
-    width?: `${number}%` | number;
-    maxHeight?: `${number}%` | number;
 }
 /** Result promise from `openAskUserPanel`. Declined carries the canonical decline envelope. */
 export type AskUserResult = AskUserQuestionAnswer;
 /**
- * Open the AskUser overlay for one set of questions.
+ * Open the AskUser docked panel for one set of questions.
  *
  * `signal` is the caller's abort signal (the tool execution's). Already-aborted
- * settles declined WITHOUT staging an overlay; a live signal closes the
- * overlay and settles declined when it fires. We resolve the declined envelope
- * rather than rejecting with the upstream ASK_ABORTED code on purpose: the
- * upstream service already screens entry-time aborts, and a step aborted after
- * this point discards the tool result anyway — resolving keeps the pending
- * promise from ever hanging either way.
+ * settles declined WITHOUT mounting a panel; a live signal closes the panel
+ * and settles declined when it fires. We resolve the declined envelope rather
+ * than rejecting with the upstream ASK_ABORTED code on purpose: the upstream
+ * service already screens entry-time aborts, and a step aborted after this
+ * point discards the tool result anyway — resolving keeps the pending promise
+ * from ever hanging either way.
  */
 export declare function openAskUserPanel(deps: AskUserPanelDeps, questions: readonly AskUserQuestionItem[], signal?: AbortSignal): Promise<AskUserResult>;
 /**