@aiwayds/dsh-tui-pi 0.20.1 → 0.22.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.
@@ -275,6 +277,57 @@ theme color via BCE, no patched dependencies.
 
 ---
 
+## Session management
+
+Two knobs clusters govern the session store, both living under the
+`dsh-tui` settings namespace (`~/.dsh/settings.yaml`) with an environment
+escape hatch each:
+
+```yaml
+dsh-tui:
+  # Startup janitor for ~/.dsh/sessions — DELETES whole session log
+  # directories outside the window. Runs once per process at startup.
+  retention:
+    maxCount: 100      # keep at most this many sessions; <= 0 DISABLES the janitor
+    maxAgeDays: 7      # delete logs untouched for more than this many days (> 0)
+    minIdleHours: 24   # count-rule-only idle guard in hours (>= 0)
+
+  # /resume display filter — only HIDES picker rows, never deletes.
+  # Resolved fresh at every picker open (a settings change applies to
+  # the next /resume, no restart).
+  resume:
+    maxAgeDays: 7      # only sessions with log activity inside this window (> 0)
+    minBytes: 20480    # minimum compressed on-disk log size for a row (>= 0)
+```
+
+Precedence per field: an explicit value in settings.yaml > the
+`DSH_TUI_RETENTION_MAX_COUNT` / `DSH_TUI_RETENTION_MAX_AGE_DAYS` /
+`DSH_TUI_RETENTION_MIN_IDLE_HOURS` and `DSH_TUI_RESUME_MAX_AGE_DAYS` /
+`DSH_TUI_RESUME_MIN_BYTES` environment variables > the defaults above.
+An invalid settings value warns once on stderr and falls to the next
+level; an invalid env value falls back silently to the default — a typo
+never widens or guts the policy. `maxCount` and `minBytes` must be
+integers at every layer (a fractional cap or byte floor is garbage, not a
+window).
+
+**Disabling retention entirely** — for a long-lived process (a remote
+bridge, a headless cron run) that read-attaches old sessions the default
+window would prune:
+
+```yaml
+dsh-tui:
+  retention:
+    maxCount: 0    # or: DSH_TUI_RETENTION_MAX_COUNT=0
+```
+
+Timing: **retention runs once at startup** (never mid-session; a
+`/reload` does not re-run it — the next cold start does), while the
+**resume filter applies at every `/resume` open**. The two `7`s default
+to the same "one week is the working set" decision but serve different
+masters — retention deletes logs, the resume filter only hides rows.
+
+---
+
 ## Fonts
 
 The TUI's only Private-Use-Area glyph is the powerline segment separator
@@ -421,8 +474,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

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/assets/deepseek-icon.svg

@@ -0,0 +1,4 @@
+<!-- DeepSeek official whale logo (brand blue #4D6BFE). Source: DeepSeek (deepseek.com) brand asset. Kept in-repo for future branding/README use; not referenced by code yet. © DeepSeek. -->
+<svg xmlns="http://www.w3.org/2000/svg" width="50" height="50" viewBox="0 0 50 50" fill="none">
+	<path d="M48.8354 10.0479C48.3232 9.79199 48.1025 10.2798 47.8032 10.5278C47.7007 10.6079 47.6143 10.7119 47.5273 10.8076C46.7793 11.624 45.9048 12.1597 44.7622 12.0957C43.0923 12 41.666 12.5356 40.4058 13.8398C40.1377 12.2319 39.2476 11.272 37.8926 10.6558C37.1836 10.3359 36.4668 10.0156 35.9702 9.31982C35.6235 8.82373 35.5293 8.27197 35.356 7.72754C35.2456 7.3999 35.1353 7.06396 34.7651 7.00781C34.3633 6.94385 34.2056 7.2876 34.0479 7.57568C33.418 8.75195 33.1733 10.0479 33.1973 11.3599C33.2524 14.312 34.4736 16.6641 36.8999 18.3359C37.1758 18.5278 37.2466 18.7197 37.1597 19C36.9946 19.5757 36.7974 20.1357 36.624 20.7119C36.5137 21.0801 36.3486 21.1597 35.9624 21C34.6309 20.4321 33.481 19.5918 32.4644 18.5757C30.7393 16.8721 29.1792 14.9917 27.2334 13.52C26.7764 13.1758 26.3193 12.856 25.8467 12.5518C23.8618 10.584 26.1069 8.96777 26.627 8.77588C27.1704 8.57568 26.8159 7.8877 25.0591 7.896C23.3022 7.90381 21.6953 8.50391 19.647 9.30371C19.3477 9.42383 19.0322 9.51172 18.7095 9.58398C16.8501 9.22363 14.9199 9.14355 12.9033 9.37598C9.10596 9.80762 6.07275 11.6396 3.84326 14.7681C1.16455 18.5278 0.53418 22.7998 1.30664 27.2559C2.11768 31.9521 4.46582 35.8398 8.07373 38.8799C11.8159 42.0322 16.1255 43.5762 21.041 43.2803C24.0269 43.104 27.3516 42.6963 31.1016 39.4561C32.0469 39.936 33.0396 40.1279 34.686 40.272C35.9546 40.3921 37.1758 40.208 38.1211 40.0078C39.6021 39.688 39.4995 38.2881 38.9639 38.0322C34.623 35.9678 35.5762 36.8081 34.71 36.1279C36.9155 33.4639 40.2402 30.6958 41.54 21.728C41.6426 21.0161 41.5557 20.5679 41.54 19.9917C41.5322 19.6396 41.6108 19.5039 42.0049 19.4639C43.0923 19.3359 44.1479 19.0317 45.1167 18.4878C47.9292 16.9199 49.064 14.3438 49.3315 11.2559C49.3711 10.7837 49.3237 10.2959 48.8354 10.0479ZM24.3262 37.8398C20.1196 34.4639 18.0791 33.3521 17.2358 33.3999C16.4482 33.4482 16.5898 34.3682 16.7632 34.9678C16.9443 35.5601 17.1812 35.9683 17.5117 36.4878C17.7402 36.832 17.8979 37.3442 17.2832 37.728C15.9282 38.584 13.5728 37.4399 13.4624 37.3838C10.7207 35.7358 8.42822 33.5601 6.81348 30.584C5.25342 27.7197 4.34766 24.6479 4.19775 21.3677C4.1582 20.5757 4.38672 20.2959 5.15869 20.1519C6.17529 19.96 7.22314 19.9199 8.23926 20.0718C12.5327 20.7119 16.1885 22.6719 19.2529 25.7759C21.002 27.5439 22.3252 29.6558 23.6885 31.7202C25.1377 33.9121 26.6978 36 28.6831 37.7119C29.3843 38.312 29.9434 38.7681 30.479 39.104C28.8643 39.2881 26.1699 39.3281 24.3262 37.8398ZM26.3433 24.6001C26.3433 24.248 26.6191 23.9678 26.9658 23.9678C27.0444 23.9678 27.1152 23.9839 27.1782 24.0078C27.2651 24.04 27.3438 24.0879 27.4067 24.1602C27.5171 24.272 27.5801 24.4321 27.5801 24.6001C27.5801 24.9521 27.3042 25.2319 26.9575 25.2319C26.6108 25.2319 26.3433 24.9521 26.3433 24.6001ZM32.6064 27.8799C32.2046 28.0479 31.8027 28.1919 31.4165 28.208C30.8179 28.2397 30.1641 27.9922 29.8096 27.688C29.2583 27.2158 28.8643 26.9521 28.6987 26.1279C28.6279 25.7759 28.6675 25.2319 28.7305 24.9199C28.8721 24.248 28.7144 23.8159 28.2495 23.4238C27.8716 23.104 27.3911 23.0161 26.8633 23.0161C26.666 23.0161 26.4849 22.9277 26.3511 22.856C26.1304 22.7441 25.9492 22.4639 26.1226 22.1201C26.1777 22.0078 26.4458 21.7358 26.5088 21.688C27.2256 21.272 28.0527 21.4077 28.8169 21.7197C29.5259 22.0161 30.0615 22.5601 30.834 23.3281C31.6216 24.2559 31.7632 24.5117 32.2124 25.208C32.5669 25.752 32.8901 26.312 33.1104 26.9521C33.2446 27.3521 33.0713 27.6802 32.6064 27.8799Z" fill="#4D6BFE" fill-rule="nonzero"/>
+</svg>

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>;
 /**