@deepseek-harness-tui/dsh-tui 0.14.1 → 0.16.0

package/guide/dsh-tui-guide/claude-backend.md

@@ -14,7 +14,10 @@ dsh-TUI 可以把会话跑在 Claude Agent 后端上，而不是 DeepSeek Harnes
 - Claude Agent SDK。它是可选依赖，默认不装。最省事的装法：打开内核选择器（启动页
   「内核」或 `/kernel`），对未安装的 Claude 行按 Enter，按引导一键安装——dsh-TUI
   自己定位 profile 目录，用 pnpm 装锁定版本的 SDK，装完该行即变亮可选（独立构建
-  与无 profile 的启动给手动指引）。手动等价形式，在 dsh-tui 的 profile 目录（默认
+  与无 profile 的启动给手动指引）。安装前会把 profile 的 pnpm store 钉到稳定路径
+  （storeDir: ../../.pnpm-store，写入 pnpm-workspace.yaml），环境变量漂移
+  （沙箱、中转改过的 XDG_DATA_HOME 等）导致的 store 错位不再复发；万一装的时候
+  已经错位，安装器会自动重建依赖再重试，无需手动清理。手动等价形式，在 dsh-tui 的 profile 目录（默认
   `~/.dsh/profiles/dsh-tui`，设置了 `DSH_HOME` 时是 `$DSH_HOME/profiles/dsh-tui`）
   执行一次：
 
@@ -23,15 +26,22 @@ dsh-TUI 可以把会话跑在 Claude Agent 后端上，而不是 DeepSeek Harnes
   ```
 
 - 一份 Claude 凭据，见下面的「登录」。
-- `claude` 命令不是必需的：`PATH` 上有能运行的 `claude` 就用它（与你平时用的 CLI 同版本、
-  同一个会话库），否则用 SDK 自带的二进制。
+- `claude` 命令不是必需的：按**显式指定的可执行路径**（环境变量，设置后原样采用，不做版本校验；
+  变量名见[多后端架构](agent-backend-design.md)）→ `PATH` 上的 `claude` → 用户主目录下的
+  `.local/bin`（Windows `%USERPROFILE%\.local\bin\claude.exe`、POSIX `~/.local/bin/claude`）
+  的顺序探测，`PATH` 命中的那份仍然优先；每个候选都要能启动并报出版本才会被采用（与你平时用的
+  CLI 同版本、同一个会话库），全部落空才交给 SDK 自带的二进制。SDK 没装但本机已有 Claude Code
+  时，安装向导的确认面板也会把发现的那个 CLI（版本与路径）报出来。
 
 选择后端，任选一种：
 
 - 启动页的「内核」入口、右下角的内核区，或在会话里输入 `/kernel`，打开内核选择器。
   选中另一个内核后 dsh-TUI 记住选择（`~/.dsh-tui/kernel.json`）并重启，在新内核里开
-  一个新会话；原来的会话仍可在 `/resume` 找到。回合进行中不能切换。SDK 没装或没有
-  凭据时，选择器会把 Claude 标为「未安装」或「未登录」。
+  一个新会话；原来的会话仍可在 `/resume` 找到。回合进行中不能切换。SDK 没装时，选择器
+  会把 Claude 标为「未安装」；凭据检测不出**不会**拦住选择——key 完全可以放在检测看不到
+  的地方（Claude 设置的 `env`、`apiKeyHelper`、中转渠道），行仍可选（右下角铭牌不显示登录
+  状态，未登录在选择器里以副标题标注）。进去后 CLI 会应用自己的配置；订阅登录在会话里
+  `/login`，中转渠道用 `/channel` 配。
 - `dsh-tui --backend claude`（只对这一次启动生效）。
 - 在 dsh-tui 的配置行写 `backend: claude`。
 
@@ -81,7 +91,7 @@ IDE 选区、状态栏的 git 分支、`/clear`（只清屏，Claude 保留上
 
 不可用（不出现在补全里，直接输入会提示不可用，不会发给模型）：`/tree`、`/agentview`、
 `/bg`、`/home`、`/workspace`、`/preset`、`/provider`、`/balance`、`/config`、
-`/reload`、`/setup`、`/migrate`、`/skills`、`/plugins`、`/hooks`、
+`/reload`、`/setup`、`/migrate`、`/skills`、`/plugin`、`/hooks`、
 `/add-dir`、`/goal`（Claude 没有目标能力）。DSH 组合注册的其他命令（如 `/plan`）也不会出现。
 
 启动时仍先到启动页；首启引导和工作区首页只在 DSH 下出现。带恢复目标的启动直接进入
@@ -120,6 +130,10 @@ Claude 设置 > `default`。Claude 设置里的 `defaultMode: bypassPermissions`
   dsh-TUI 创建的会话也在其中（Claude Code 自己的 `/resume` 选择器不显示它们，要用
   `claude --resume <id>` 打开）。`Enter` 恢复（先回放历史再继续），`Ctrl+R` 重命名，
   `Ctrl+D` 删除；当前会话和另一个 dsh-TUI 终端正在用的会话不能删。置顶按后端分开保存。
+  再次打开或重启后先显示上次完整列表，同时仍从 SDK 刷新。首屏快照按 Claude 配置
+  目录隔离；没有快照时按 SDK 默认项目范围（当前工作目录及同仓库的 Git worktree）
+  先显示最近的最多 32 条，再补齐该项目及其他项目的完整列表；全部项目读取失败时
+  也保留该项目的 worktree 会话。读取失败时保留上次完整快照。
 - 从 shell 恢复：`dsh-tui --backend claude --resume <id>`；不带 id 时恢复本机最近一次
   用过的 Claude 会话。退出时 dsh-TUI 会打印这条命令。另一个 dsh-TUI 终端已打开的会话会
   被拒绝；`--resume` 打不开时直接报错，不会改开新会话。状态栏的短会话 id 就是
@@ -153,6 +167,14 @@ Claude 设置 > `default`。Claude 设置里的 `defaultMode: bypassPermissions`
 ## 已知限制
 
 - 一个 dsh-TUI 进程只用一个后端，切换要经 `/kernel` 重启。
+- Claude 内核下 `dsh-tui` 从本包自己的入口启动，只组合轻量 profile（本包与 profile
+  声明的第三方插件，不含 DSH 的 agent 核心）：界面先出现，
+  会话打开后才能发送：在此之前按 Enter 草稿留在原处并提示还在启动，命令行带的首句在
+  会话打开后发出；打开失败会说明原因（落地页自动收起），`/new` 重试。第三方
+  DSH/Cordis 插件（主题、面板、决策拦截）照常加载，在界面出现后加入；依赖 DSH 自身
+  服务（agent、工具、LLM 层）的插件在这个内核下不会激活。`DSH_TUI_HOST_ENTRY=0` 回到经
+  `dsh --profile dsh-tui` 启动。（DSH 内核默认也从本包入口启动，但会在同一进程里组合
+  完整的 DSH profile。）
 - 侧栏的工作区面板在 Claude 会话下提示不支持，轨迹面板为空。
 - 不支持 `/add-dir`；拒答对话框只有「重试」和「取消」；需要浏览器操作的 MCP 请求不会
   自动打开浏览器。

package/guide/dsh-tui-guide/codex-backend.en.md

@@ -92,6 +92,21 @@ is handed to Codex unchanged. Non-first-party routes should use their own provid
 credentials or a channel key. Account status shows only credential source, subscription
 type and host, not an email address or key.
 
+One bridging exception: when the active provider takes its credential from an `env_key`
+(say `DEEPSEEK_API_KEY`) that the launching environment did not export but the DSH credential
+store declares, the stored value is injected into the app-server child after `config/read`
+(the hub is re-acquired; the key joins the hub fingerprint through `injectedEnvKeys`). Reads
+take the active store first (`$DSH_HOME/.credentials.yaml`, or `~/.dsh/.credentials.yaml`
+when `DSH_HOME` is unset) and then the default `~/.dsh` store, so a `DSH_HOME` override does
+not orphan a key stored where both READMEs name it; writes only ever target the active home. A key
+stored once in the credential store therefore works without exporting a shell variable. The
+value only ever travels into the spawn pipeline, never into logs, notices or events.
+
+When nothing can supply the key, startup is **not** blocked: Codex itself rejects every turn
+of that provider, so the runtime reports the reason once as a start notice (naming the
+provider and the variable, never a value) — export the key, store it, or move the provider to
+a channel.
+
 ### The three `/login` methods
 
 | Method | Purpose and storage |
@@ -156,9 +171,11 @@ changes during a turn apply to the next one, not to reasoning already in progres
 
 - **`Shift+Tab` only toggles Plan**, returning to the previous permission preset when leaving
   it. It does not cycle into Full Access.
-- `/plan` enters Plan; `/plan <task>` enters it and submits the task. Choosing an explicit
-  permission preset returns to Default collaboration. Plan does not mean all tools are
-  forbidden: the actual security boundary remains Codex’s permission policy.
+- `/plan` enters Plan; `/plan <task>` enters it and submits the task; `/plan off` returns to
+  the permission preset that was active before Plan. The `on`/`off` rows in the completion
+  menu are dsh-TUI’s own state words, not task text. Choosing an explicit permission preset
+  returns to Default collaboration. Plan does not mean all tools are forbidden: the actual
+  security boundary remains Codex’s permission policy.
 - Defaults resolve per field: an explicit dsh-TUI choice > your Codex configuration >
   `auto` when unset. An unreadable configuration is not overwritten with `auto`.
 - Completed plans offer implementation, implementation with cleared context, or staying
@@ -167,13 +184,20 @@ changes during a turn apply to the next one, not to reasoning already in progres
 - Command, file, network and permission approvals use server-provided choices. Allow-once,
   session allowance or remembered rules appear only when supported. Questions and MCP forms
   share the existing panel, with secret answers masked.
+- Codex's `request_user_input_async` opens the questionnaire while the agent continues
+  working. The first suggestion is selected by default; free text is also available.
+  Answers use the native question-reply envelope to steer, falling back to a queued
+  follow-up when steering is unavailable. Dismissal closes that question without
+  interrupting. Turn completion, connection loss and exit withdraw unanswered questions;
+  historical resume never reopens old questionnaires. Codex's persisted echo renders
+  as a quoted question and answer, including when rebuilding history.
 
 ## Daily commands and input
 
 | Entry | Behavior |
 | --- | --- |
 | `Enter` / `Tab` / `Ctrl+Enter` while working | Steer / queue a follow-up / interrupt and send now; non-steerable turns fall back to follow-up |
-| `Esc` / `Ctrl+C` | Dismiss the focused panel or interrupt. Cancelling a model question also interrupts its turn rather than leaving it hung |
+| `Esc` / `Ctrl+C` | Dismiss the focused panel or interrupt. Cancelling a blocking question interrupts its turn; dismissing an async question only closes that question |
 | `/review` | Review uncommitted changes inline; requires idle state and consumes model usage |
 | `/review base <branch>` / `/review commit <sha>` | Review against a branch or commit; other arguments are custom review instructions |
 | `/diff` | Latest turn’s aggregated diff; otherwise try Git diff against the remote, then show an empty-state notice |
@@ -212,11 +236,20 @@ past tokens/cost. Fresh usage notifications update the readings.
   say the transcript is retained, not physically deleted. Current, occupied or active-worker
   threads cannot be archived. The catalog lists up to 500 recent ordinary threads, excluding
   ephemeral forks and child threads from the main list.
+  Reopening or restarting first paints the last complete list while the native catalog
+  refreshes; a cold scan shows pages as they arrive. Without a snapshot, the native state
+  database supplies up to 32 recent threads from the current workspace first, then the
+  rollout scan repairs titles and fills in that workspace followed by other workspaces;
+  an unavailable database falls back to scanning. First-paint snapshots are isolated by
+  Codex storage directory; failed or incomplete reads never replace a complete snapshot.
 - `/rename` changes the official thread title; `/color` stores a session accent, not a global theme.
 - `/fork` creates a resumable copy without switching. Double `Esc` or `/rewind` conversation
   rewind creates a copy before the selected question, returns the question to the composer
-  and preserves the original. Rewinding the first question creates an empty thread. **File-only
-  and conversation+files rewind are unsupported**; the Git working tree does not revert.
+  and preserves the original. Rewinding the first question creates an empty, resumable fork.
+  First-question rewind, or rewind without a loaded predecessor, requires Codex app-server
+  **0.160.1+**, checked from the connection handshake. Older or unknown server versions
+  receive an explicit upgrade notice; rewind with a loaded predecessor keeps its existing path.
+  **File-only and conversation+files rewind are unsupported**; the Git working tree does not revert.
 - Resume replays the newest 20 full turns before live continuation. Load older messages uses
   prefetched full-item pages, not tool-omitting summaries. Retry when prefetch is still pending;
   repeated failure reports a notice. Active resume deduplicates redelivered approvals and
@@ -265,10 +298,14 @@ Real model vision and image generation were not tested in this round.
 
 usageLimited/budgetLimited goals show a blocked state and reason. Unsupported goal APIs
 do not expose the capability. `/btw`/`/recap` use a read-only sandbox with no approval
-escalation, request answer-only behavior and reject tool/approval requests. Cancellation
-interrupts the temporary turn and unsubscribes the fork. They consume model quota, not
-free local summaries. Ephemeral fork creation/non-persistence was checked offline; actual
-side-query model answers were not tested in this round.
+escalation, request answer-only behavior and reject tool/approval requests. The fork never
+carries `deferGoalContinuation` (app-servers from 0.162 reject it combined with `ephemeral`),
+and when the thread has no rollout on disk yet (nothing persisted, e.g. a brand-new session)
+the side call falls back to a fresh ephemeral `thread/start` — the conversation is empty in
+exactly that state, so no context is lost. Cancellation interrupts the temporary turn and
+unsubscribes the fork. They consume model quota, not free local summaries. Ephemeral fork
+creation/non-persistence was checked offline; actual side-query model answers were not
+tested in this round.
 
 ## Limitations and troubleshooting
 

package/guide/dsh-tui-guide/codex-backend.md

@@ -75,6 +75,15 @@ thread 时，恢复保留原来的错误，不会启动后台服务或另开新
 路由应使用自己的 provider 凭据或渠道 key。读取账户状态只显示凭据来源、订阅类型
 与主机，不显示邮箱或 key。
 
+一个桥接例外：当前 provider 用 `env_key`（如 `DEEPSEEK_API_KEY`）取凭据、启动环境没导出、
+而 DSH 凭据库声明了该 ref 时，`config/read` 之后把库里的值注入 app-server 子进程（重取 hub，
+key 记入 `injectedEnvKeys` 参与指纹）。读取先看活动 home 的库，再回退默认 `~/.dsh` 的库，
+所以 `DSH_HOME` 覆盖不会让写在文档位置的 key 失联；写入只进活动 home。key 只走 spawn 管道，
+不进日志、提示或事件。
+
+两边都拿不到时不拦启动：Codex 自己会拒绝该 provider 的每个回合，运行时只在启动时报一次
+原因（点名 provider 与变量名，不含值）——导出该变量、写入凭据库，或把 provider 换成渠道。
+
 ### `/login` 的三种方式
 
 | 方式 | 用途与存储 |
@@ -130,21 +139,27 @@ Chat Completions 端点当作 Responses 使用。通过 `/channel` 选择/新建
 | Plan（`plan`） | 规划协作模式；保留已有权限档，不以 Plan 替代沙箱 |
 
 - **`Shift+Tab` 只开/关 Plan**，退出回到进入前的权限档，不循环到 Full Access。
-- `/plan` 切到 Plan；`/plan <任务>` 切换后立刻提交任务。选择一个具体权限档会回到
-  Default 协作模式。Plan 不等于“所有工具都被禁止”，安全边界仍由 Codex 权限决定。
+- `/plan` 切到 Plan；`/plan <任务>` 切换后立刻提交任务；`/plan off` 退回进入 Plan 前的
+  权限档。补全菜单里的 `on`/`off` 是 dsh-TUI 自己的状态词，不是任务文本。选择一个具体
+  权限档会回到 Default 协作模式。Plan 不等于“所有工具都被禁止”，安全边界仍由 Codex
+  权限决定。
 - 默认来源按字段为：dsh-TUI 中明确选过的值 > 用户 Codex 配置 > 未设置时的
   `auto`。读取配置失败时不拿 `auto` 覆盖未知配置。
 - 计划完成后会出现实施确认：实施、清上下文后实施、留在规划/反馈继续。清上下文
   的路径以新 thread 继续，原 thread 保留；批准计划不会暗中打开 Full Access。
 - 命令、文件改动、网络/权限请求由 Codex 给出的选项驱动；允许本次、会话内允许、
   记住规则等选项只在服务端支持时出现。问卷与 MCP 表单共用现有面板，保密答案掩码。
+- Codex 的 `request_user_input_async` 在运行中打开问卷，智能体继续执行。建议答案默认
+  聚焦第一项，也可自由输入；提交通过原生问题回复信封插话，不可插话时排队到下一回合。
+  取消只关闭该题，不中断回合。回合结束、连接断开或退出时撤回未答问题；历史恢复不会
+  重新打开旧问卷。答案由 Codex 持久化回显投影成「问题 + 答案」，恢复历史时同样显示。
 
 ## 日常命令与输入
 
 | 入口 | 行为 |
 | --- | --- |
 | 工作时 `Enter` / `Tab` / `Ctrl+Enter` | 插话（steer）/ 排队下一回合 / 打断并立即发送；不可 steer 时退为排队 |
-| `Esc` / `Ctrl+C` | 按当前焦点关闭面板或中断；取消提问也会中断相应回合，避免挂起 |
+| `Esc` / `Ctrl+C` | 按当前焦点关闭面板或中断；取消阻塞提问会中断相应回合，取消异步提问只关闭该题 |
 | `/review` | 审查未提交改动，结果 inline 展示；需要空闲，消耗模型用量 |
 | `/review base <branch>` / `/review commit <sha>` | 按分支基线或提交审查；其他参数作为自定义审查说明 |
 | `/diff` | 最近回合的聚合 diff；没有时尝试相对远端的 Git diff，再无内容则提示 |
@@ -181,10 +196,17 @@ used      = max(0, T - 12000)
   `Ctrl+R` 改名、`Ctrl+D` **归档**；确认和完成提示都说明记录保留，不物理删除。
   当前使用中、其他终端占用或内部 worker 活动的 thread 不能归档。目录最多列出
   最近 500 条普通 thread，临时 fork 与子 thread 不混进主列表。
+  再次打开或重启后先显示上次完整列表，后台仍从官方目录刷新；首次读取时分页到达
+  就显示。没有快照时先从官方状态数据库显示当前工作区最近的最多 32 条，再由历史
+  扫描修正标题并补齐当前工作区及其他工作区；数据库不可用时照常扫描。首屏快照
+  按 Codex 存储目录隔离，失败或未读完的分页不会覆盖完整快照。
 - `/rename` 改官方 thread 标题；`/color` 只保存会话强调色，不改全局主题。
 - `/fork` 创建可恢复副本，不自动切换；双击 `Esc` 或 `/rewind` 的对话回退在
   所选提问之前创建副本并继续，提问回到输入框、原 thread 保留。首条提问回退会
-  得到空 thread。**不支持文件回退或对话+文件回退**，Git 工作树不会随对话恢复。
+  得到可恢复的空分支。首条消息及上一回合未加载时的回退需要 Codex app-server
+  **0.160.1+**；按连接握手中的服务端版本判断，版本未知或更旧时明确拒绝并提示升级。
+  上一回合已加载时沿用原有回退方式。
+  **不支持文件回退或对话+文件回退**，Git 工作树不会随对话恢复。
 - 恢复先回放最近 20 个完整回合，再接 live；加载更早消息使用预取的完整分页，
   不拿省略工具项的 summary 当全转录。预取尚未就绪时可再试一次，连续失败会提示。
   运行中的恢复会去重重发审批；历史没有的完整用量不伪造。

package/guide/dsh-tui-guide/configuration.en.md

@@ -26,12 +26,102 @@ only for a genuinely new service.
 > When a row is overridden, its `config` block is replaced as a whole. It is
 > not deep-merged, so repeat every key that must remain active.
 
+## Web search and fetch (DSH 0.2.1-rc.2)
+
+The standard DSH profile loads the new DeepSeek Search / Fetch API providers,
+while Messages search and local HTTP fetch remain the defaults. In `/settings`,
+use the arrow keys in **Web search** to select **Search API** and **Fetch API**.
+Each selection saves immediately and applies to the next operation. Choose
+**Messages** / **HTTP** to restore the original providers. Enter accepts a custom
+provider ID. Sections use the plugin's actual Loader entry ID, including custom IDs.
+
+**Web search** has one **API key** input. Paste the key for the selected search API;
+typing is masked and confirmation saves it in DSH's credential store, outside
+profile configuration. Reopening shows only whether a key is configured. Blank
+input preserves the saved key, and switching APIs selects that API's credential.
+
+The **DeepSeek Search / Fetch API** section edits the API base URL,
+result count (1–50), and **Send original question**. The base URL
+includes the path prefix without `/search` or `/fetch`; its default is
+`https://api.deepseek.com/v1/tools`. DSH supplies an authorized account token for the account route.
+Search sends the first 128 characters of the latest user prompt by default;
+the section can disable this. Messages search has its own endpoint and maximum
+search count section.
+
+The user profile patch can also select both providers:
+
+```yaml
+- id: web
+  config:
+    searchProvider: deepseek-search-api
+    fetchProvider: deepseek-fetch-api
+```
+
+The TUI uses DSH's tools, authentication, cancellation and persisted results;
+it does not make an additional model request. Older hosts and compositions
+without the API plugin omit these new settings. The official `deepseek-official`
+and `deepseek-account` routes show a `1017` marker for `DeepSeek-V4.1-Flash` in
+the model list, retaining the original route IDs.
+
+## Official request metadata and feedback reporting
+
+The TUI bundle inherits reporting configuration from the installed official DSH
+composition; it does not add services absent from that composition. The current
+validated line has these defaults, with profile, home and CLI patches still able
+to override them:
+
+| Setting | Official default | Data and trigger |
+| --- | --- | --- |
+| `plugin-package-inventory-deepseek.enabled` | `true` | `dsh_plugin_packages` on `deepseek-official` requests, containing active plugin package names and versions so TUI usage can be identified |
+| `session-log-deepseek.enabled` | `true` | `dsh_session_log` on `deepseek-official` requests, incrementally carrying canonical Session events that may include the working directory, prompts, conversation content, and tool arguments and results; controlled independently of package inventory |
+| `session-telemetry-otel.mode` | `FEEDBACK_ONLY` | New explicit feedback authorizes OTel upload of the Session-log prefix through that feedback, including context; ordinary chat does not trigger this channel |
+
+The first two fields are request metadata outside model input and add no model
+input tokens. Both go to the adapter's configured `baseURL`, including third-party
+gateways. They accompany the corresponding DeepSeek requests and do not measure
+all TUI usage through the Claude/Codex backends.
+
+Feedback telemetry supports the upstream environment variables:
+
+- `DSH_TELEMETRY_MODE=DISABLED` stops OTel Session-log upload; the default
+  `FEEDBACK_ONLY` authorizes upload only after feedback.
+- Any non-empty `DSH_TELEMETRY_DISABLED` value, including `0` or `false`, disables
+  the `session-telemetry-otel` row at startup. Remove the variable to restore it;
+  it does not control the two API request metadata fields above.
+- `DSH_TELEMETRY_OTLP_URL` overrides the OTel collector address. When unset, the
+  installed official version supplies the endpoint and exporter parameters.
+
+To stop API request metadata, disable either field in the user profile patch:
+
+```yaml
+- id: plugin-package-inventory-deepseek
+  config:
+    enabled: false
+- id: session-log-deepseek
+  config:
+    enabled: false
+```
+
+Restart the TUI after changing its bundle or launch environment. Restoring bundle
+defaults does not remove existing user patches.
+
 ## TUI configuration
 
-On DSH 0.1.7, `/settings` writes plugin Config fields to the active profile's
-`cordis.patch.yml`. Older hosts still use `~/.dsh/settings.yaml`; that file is
-not the new settings entry point. Language and layout preferences update live;
-fullscreen and image previews require `/restart`.
+The `dsh-tui` section of `/settings` lives in the TUI's own
+`~/.dsh-tui/settings.json`, shared by every kernel (DSH, Claude, Codex). When that file
+does not exist yet, the first launch imports the editable fields of the `dsh-tui`
+row's `config` from the active profile's `cordis.patch.yml` once (read only; the
+profile is not changed and `!!js` expressions are not imported), and never again.
+The `dsh-tui` section an older host kept in `~/.dsh/settings.yaml` is imported too:
+a file DSH has not moved yet wins over the patch row; one DSH already moved into the
+patch (renamed `settings.yaml.imported`) sits beneath it.
+After the import, those fields left in the profile patch only act as a static
+deployment layer under the DSH kernel (a fallback while the user layer is unset);
+remove them from the patch so both kernels see the same defaults. Other plugins'
+sections still go through DSH's settings service (written to the active profile's
+`cordis.patch.yml`; older hosts use `~/.dsh/settings.yaml`).
+Language and layout preferences update live; fullscreen and image previews
+require `/restart`.
 
 A complete common override looks like this:
 
@@ -58,33 +148,44 @@ A complete common override looks like this:
 | Field | Default/source | Meaning |
 | --- | --- | --- |
 | `provider` | Harness `agentDefaultModel`; bare compositions fall back to `deepseek-official` | DSH model route; provider and model must both be set to form an explicit route |
-| `model` | Harness `agentDefaultModel`; bare compositions fall back to `deepseek-flash` | Startup model; `/model` can switch through a session fork |
+| `model` | Harness `agentDefaultModel`; bare compositions fall back to `deepseek-flash` | Startup model; `/model` selects the next request’s model within the same session. Precedence: the persisted `/model` choice (`~/.dsh-tui/model.json`, the route the last session ran, whole pair) > a complete `provider`+`model` pair here (deployment default) > the harness default. A half pin (provider or model alone) counts as unset and never merges with half the preference (issue #67) |
 | `cwd` | git worktree root containing the launch directory (`process.cwd()` when outside any worktree; a dotfiles repo at `$HOME` does not count) | TUI-side session workspace: agent meta, `@` completion/mention expansion, /resume filtering, statusline; resuming an existing session adopts that session's persisted cwd. Note the bash/fs-policy/sandbox roots are still owned by the composition layer's cordis config (default: the launch directory, governed by dsh-base) and may differ from this session-side cwd |
 | `workspace` | unset | Startup workspace target: a local path, `file://` URL, or plugin-provided URI; takes precedence over `cwd` |
-| `effort` | normally `max` in the bundle | Reasoning effort applied to every request (validated against the runtime model's levels; invalid levels silently fall back to the adapter default), also shown in the header at startup. Precedence: /settings `effortDefault` (`auto` defers) > this field > the persisted `/effort` choice (`~/.dsh-tui/effort.json`) > the model default |
-| `effortDefault` | unset | Default reasoning effort for new sessions; `auto` defers to `effort`; editable through `/settings` |
+| `effort` | normally `max` in the bundle | Reasoning effort applied to every request (validated against the runtime model's levels; invalid levels silently fall back to the adapter default), also shown in the header at startup. Precedence: /settings `effortDefault` (`auto` defers) > the persisted `/effort` choice (`~/.dsh-tui/effort.json`, the level the last session ran on) > this field (deployment default) > the model default |
+| `effortDefault` | unset | Default reasoning effort for new sessions (the `/settings` user layer; an explicit value outranks the persisted `/effort` choice); `auto` defers to the persisted choice and `effort`; editable through `/settings` |
 | `whale` / `whaleIdle` | `true` / `true` | Header whale and welcome-page idle animation |
 | `splashFont` | `daily` | Big-text face on the header splash: `daily` rotates by local date (the default), any other value is a face id (`bold` / `square` / `bevel` / `wide` / `dot` / `stencil` / `classic` / `slab`) pinning that one; an unknown value falls back to `daily`. Also editable through `/settings` |
-| `whaleGirl` | `false` | Swap the header's pixel whale for the maid: real raster FIRST (Kitty/Sixel); falls back to the character-art maid without them |
+| `whaleGirl` | `false` | Maid-portrait toggle: For the DeepSeek brand, Companion skins deepy and whaleGirl take the splash art slot; choose whale and enable Maid portrait to show the maid. Claude uses its own artwork; Codex uses its own raster portrait or the maid character-art fallback. Both brands ignore these settings for splash artwork. "Companion skin" is `companion.skin`; when the toggle does apply, the portrait renders the real raster through the terminal image protocols (Kitty/Sixel) and falls back to the character-art maid without them. See the precedence table below |
 | `minimal` | `false` | Minimal UI (极简界面): reduce header decoration and colors. **A display switch only** — a different thing from the kernel's `minimal` agent preset under `preset` below (that one decides which tools the model can use) |
 | `sidePanel.splitEnabled` | `true` (boolean) | Master switch of the split layout: on, `Ctrl+B` and `/panel` open the side column next to the chat; off, neither splits and `/jobs` & co. keep their full-screen panels. Applies immediately |
 | `sidePanel.open` | `false` (boolean) | Whether a session opens with the sidebar already expanded; off by default, so the upgrade leaves the layout as it was. An in-session `Ctrl+B` / `/panel toggle` is not written back here. Applies immediately |
 | `sidePanel.ratio` | `0.68` (number, 0.1–0.95) | Chat column as a fraction of the content width; while the panel has focus, `+`/`-` nudge it live for the current session (not written back). Applies immediately |
 | `sidePanel.panels` | `todo,jobs,agents,info,trajectory,workspace,btw,companion` (comma-separated text) | All eight built-in panels are enabled by default; this controls their ids and order. A well-formed id no panel claims yet stays in the tab bar for a plugin to register later; a malformed entry is refused. The `⤢` on the right edge of the bar blows the active panel up to full screen (drawn only for panels that declare a fullscreen form). Applies immediately |
- | `companion.skin` | `deepy` | Skin of the companion-panel pet: `deepy` (default, the deepy whale kit), `whaleGirl` (the whale-girl sticker pack, 22 animations incl. interaction reactions) or `whale` (the splash's layered pixel whale); the panel is enabled by default and can be changed in `sidePanel.panels`. Applies immediately |
+| `companion.skin` | `deepy` | Skin of the companion-panel pet: `deepy` (default, the deepy whale kit), `whaleGirl` (the whale-girl sticker pack, 22 animations incl. interaction reactions) or `whale` (the splash's layered pixel whale); the panel is enabled by default and can be changed in `sidePanel.panels`. **For the DeepSeek brand it also picks the splash (header) art slot**: while Companion skin is deepy or whaleGirl, that mascot takes the slot (neither the pixel whale nor the maid portrait is drawn) and the Maid-portrait toggle (`whaleGirl`) has no effect; set Companion skin to whale to get the original path back (the pixel whale, or the maid portrait once the toggle is on). Applies immediately; see the precedence table below |
 | `btw.contextTurns` | `4` (number, 1–8) | Completed Q/A pairs a `/btw` follow-up carries; older pairs stay in the thread and panel but are not sent. Applies immediately |
 | `btw.contextBudget` | `24000` (number, 1000–200000) | Character budget for the recent Q/A pairs a `/btw` follow-up carries; the oldest pairs drop first. Applies immediately |
 | `codeFrameStyle` | `light` | Frame of fenced code blocks in replies: `light` is a top label plus a left rail and costs no extra rows; `full` closes the box. Very narrow terminals always use a plain fence. Applies immediately |
 | `turnUsageRow` | `false` (boolean) | Show a right-aligned usage row at the end of each turn (tokens in/out, cache, duration, retries); `/tokens`, `/status` and the footer hover report the same numbers either way |
 | `modes` | built-in trio | Shift+Tab session-mode cycle (plan/sandbox/approval atom bundles); defaults to default → plan → full-access |
+| `upstreamRetry` | `true` | Seed a retry policy (5 attempts, transport-drop-aware failure codes including `STREAM_CLOSED`) on the `llm-pi-ai` provider route the bound session actually uses, whenever it declares no `retryPolicy` — at every bind (boot, `/model` switch, resume), through the official `llm-pi-ai` settings section (the policy the kernel's `llm-retry` plugin executes). Dormant channels are never written; routes with an explicit `retryPolicy` (cordis.yml or hand-edited settings) are never overwritten; `false` opts out entirely |
 | `activity` | `true` | Show the live activity row |
 | `activityFrames` | `moon8` | Activity animation preset; `/activity` changes it at runtime. A legacy saved value of `claude` is read as `moon8`, and the picker no longer offers that legacy preset |
 | `contextBar` | `true` | Segmented context-usage bar below the input box; `false` hides the row. Both this and `/settings → statusBar.contextBar` (also on by default) must be on for it to render |
 | `fullscreen` | `true` (factory default since 0.9.0) | `true` uses the alternate screen, app scrolling, and mouse selection; `false` uses inline mode |
 | `terminalImages` | `true` | Allow previews in supported terminals; `false` keeps text metadata and skips image probing and preview decoding. Restart to apply changes |
-| `preset` | roster default `standard` | Agent preset for new sessions; explicit configuration wins over persisted preference |
+| `preset` | roster default `standard` | Agent preset for new sessions; precedence: `DSH_TUI_PRESET` (this run) > the persisted `/preset` choice > this field (deployment default) > the roster default |
 | `sessionId` | unset | Session to resume, normally injected by the Windows `--resume` launcher |
-| `backend` | unset (the backend `/kernel` remembers, else `dsh`) | Session backend: `dsh`, or the experimental `claude` / `codex` (case-insensitive; an unknown value means `dsh`). The profile row reads `DSH_TUI_BACKEND`, which `dsh-tui --backend <id>` sets. See [Claude backend](claude-backend.en.md) |
+| `backend` | unset (the backend `/kernel` remembers, else `dsh`) | Session backend: the built-in `dsh`, or an installed backend (the experimental `claude` / `codex`, plus plugin backends; case-insensitive). **An unknown or uninstalled value starts on `dsh` with a warning**, never a crash. The profile row reads `DSH_TUI_BACKEND`, which `dsh-tui --backend <id>` sets. When the profile's own patch writes it as a `!!js` expression (other than one that only forwards `DSH_TUI_BACKEND`, such as the bundled row's `process.env.DSH_TUI_BACKEND \|\| undefined`), the launch goes through `dsh --profile` (only the profile's Loader evaluates it), except for a `/kernel` switch. See [Claude backend](claude-backend.en.md) |
+
+For the DeepSeek brand, when header art (`whale`) is enabled, `companion.skin` and the Maid-portrait toggle (`whaleGirl`) choose the splash art with this precedence:
+
+| `companion.skin` | Splash (header) art slot | Maid-portrait toggle |
+| --- | --- | --- |
+| `deepy` (default) | the Deepy mascot (letter-grid animation only — no raster) | **No effect** |
+| `whaleGirl` | Whale-girl mascot (real image through the image protocol; letter-grid fallback without it) | **No effect** |
+| `whale` | Original path: the pixel whale; the maid portrait once the Maid-portrait toggle is on (real image preferred, character-art fallback) | **Applies** |
+
+The table applies when Brand look (`brand`) resolves to `deepseek` (including `auto` on the DSH backend). Claude uses its own raster or character artwork. Codex uses its own raster portrait, falling back to the maid character art when raster images are unavailable or fail to load. Neither brand uses `companion.skin` or `whaleGirl`; choose the DeepSeek brand look to use the skins or maid portrait above. Turning header art off hides the art for every brand.
 
 ### Precedence and force-off
 
@@ -178,8 +279,9 @@ preset registry: `@deepseek-ai/dsh-agent-preset-registry` on 0.1.7, or
 ### Default and precedence
 
 - The default is stored in `~/.dsh-tui/agent-preset.json`.
-- Precedence: explicit `config.preset` or `DSH_TUI_PRESET`, then persisted
-  preference, then the roster default `standard`.
+- Precedence: `DSH_TUI_PRESET` (this run's explicit instruction), then the
+  persisted preference, then an explicit `config.preset` (deployment default),
+  then the roster default `standard`.
 - A legacy `code` preference resolves to `ptc` when the active roster no
   longer provides `code`, then migrates after that successful resolution;
   rc rosters keep their real `code` id, and session logs are never rewritten.
@@ -202,6 +304,51 @@ preset registry: `@deepseek-ai/dsh-agent-preset-registry` on 0.1.7, or
 - The pin is the only candidate; a miss warns and skips registration, exposing
   the full tool catalog on the first round.
 
+### Windows bash tool (winbash)
+
+`presets/winbash.mjs` is a bundled Windows `bash` tool plugin. Mounted at
+the host layer it serves **every Agent preset** (unrelated to Liangshen mode; it is not a
+`/preset` entry). Its behavior mirrors the official `dsh-tool-bash` — the official bash
+executor `dsh-bash-local` is POSIX-only and does not support Windows, hence this plugin.
+
+- Every call runs `bash -c <command>` in a fresh shell; state never persists across calls.
+  `description` is required (labels the call in the UI).
+- `run_in_background: true` admits the command as a background job and returns the job id
+  at once; collect with `job_output`, stop with `job_kill`. No timeout applies in the
+  background.
+- A foreground command that outlives its timeout keeps running as its background job and
+  hands the id back (`promoteOnTimeout`; can be disabled).
+- Non-zero exits are reported as `[exit code: N]` markers, not tool errors.
+- Compositions without a job registry degrade to foreground-only (timeout kills) and do
+  not expose `run_in_background`.
+- Git Bash discovery follows the Liangshen chain (see above); set
+  `DSH_TUI_WINBASH_BASH_PATH` (legacy name `DSH_TUI_LIANGSHEN_BASH_PATH` still works)
+  to pin `bash.exe`.
+
+Mounting: copy `presets/winbash.mjs` into the profile root and append to the
+plugin list of `cordis.patch.yml`:
+
+```yaml
+- id: windows-bash
+  name: './custom-bash.mjs'
+  disabled: !!js process.platform !== 'win32'
+```
+
+Configuration (the mount row's `config`):
+
+| Key | Default | Meaning |
+|---|---|---|
+| `timeoutMs` | `120000` | Default foreground timeout (ms) |
+| `maxTimeoutMs` | `600000` | Per-call timeout cap (also the tool-level hard cap with jobs) |
+| `maxOutputBytes` | `64000` | Per-stream in-memory output cap |
+| `enableRunInBackground` | `true` | Expose the background flag (needs a job registry) |
+| `promoteOnTimeout` | `true` | Promote a timed-out foreground call instead of killing it |
+| `bashPath` | — | Pin `bash.exe` explicitly (same as the env variable) |
+
+> The Liangshen preset's built-in `custom-bash` registers the same `bash` tool name:
+> mount at most one of them per profile. When running the Liangshen preset, set this
+> row's `disabled` to `true` (the Liangshen copy is foreground-only).
+
 ### Custom presets
 
 On 0.1.7, declare `@deepseek-ai/dsh-agent-preset` through a profile/bundle with
@@ -256,16 +403,19 @@ for the complete field reference.
 | `DSH_HOME` | Harness home (profiles, sessions, credentials, attachments); falls back to the upstream default `~/.dsh` |
 | `DSH_TUI_PERSONA` | Override the Agent persona injected by the composition |
 | `DSH_TUI_PRESET` | Override the default Agent preset for new sessions |
-| `DSH_TUI_THEME` | Pin a built-in (`auto`/`light`/`dark`/`dark-ansi`), static theme, or registered plugin theme ahead of persisted selection |
+| `DSH_TUI_THEME` | Pin a built-in (`auto`/`light`/`dark`/`dark-ansi`/`pink-day`/`pink-night`/`pink-ansi`), static theme, or registered plugin theme ahead of persisted selection |
 | `DSH_TUI_DISABLE_MOUSE` | Temporarily disable mouse handling in fullscreen mode |
 | `DSH_TUI_DISABLE_TERMINAL_IMAGES` | Set to `1` to force Kitty/Sixel probing, preview reads/decoding, and terminal image rendering off, overriding config and /settings; text metadata remains visible |
 | `DSH_TUI_IMAGE_PROTOCOL` | `auto` (default), `kitty`, `sixel`, or `none`; override protocol selection without bypassing the preview preference, disable switch, non-fullscreen, accessibility or multiplexer guards |
 | `DSH_TUI_RESUME_SESSION` | Resume a session at startup, normally set by a launcher |
-| `DSH_TUI_BACKEND` | Session backend (`dsh` / `claude`), normally set by `dsh-tui --backend` |
+| `DSH_TUI_RESUME_BACKEND` | The backend `DSH_TUI_RESUME_SESSION` was read from; set only when the launcher **derived** the target (a bare `--resume` reading that backend's last session, or the safe-mode retry following the last-run record). When the boot lands on another backend — an uninstalled id falling back to `dsh`, or the remembered kernel when `DSH_TUI_BACKEND` is absent — that target **refuses with a non-zero exit**: never carried across, never a silent cold start, never a new session (the safe-mode retry is the one exception, degrading to a warning plus a cold start). An id the user passed explicitly carries no mark and is handed over as it is |
+| `DSH_TUI_RESUME_RETRY` | One-shot marker: this boot is safe mode's "retry normal startup". A retry derives its target from the last-run record, whose backend may no longer be registered, so a launch carrying this marker degrades a revoked resume target to a warning plus a cold start instead of failing. The boot deletes it from `process.env` as soon as it reads it |
+| `DSH_TUI_BACKEND` | Session backend (built-in `dsh` / `claude` / `codex`, or an installed plugin backend), normally set by `dsh-tui --backend`; an uninstalled or misspelled id starts on `dsh` with a warning (with a resume request in play it refuses instead, see above) |
+| `DSH_TUI_HOST_ENTRY` | Set to `0` to start both kernels through `dsh --profile` (by default both start from the package's own entry). When the entry cannot use the installed dsh (the `dsh` on `PATH` is not `@deepseek-ai/dsh`, its launcher script cannot be followed, or a module or export it needs is missing), a DSH launch falls back to `dsh --profile` by itself and says why in the terminal and on screen |
 | `DSH_TUI_CLAUDE_PERMISSION_MODE` | Start permission mode of the Claude backend (`default`/`acceptEdits`/`plan`/`dontAsk`/`bypassPermissions`); wins over the mode `/permission` remembered |
 | `DSH_TUI_WORKSPACE_TARGET` | Workspace path or URI resolved at startup, normally set by `dsh-tui <target>` |
 | `DSH_TUI_SESSION_ROOT` | Override the JSONL session root; profile default `$DSH_HOME/sessions`, bare `cordis.yml` default `~/.dsh-tui/sessions` |
-| `DSH_PERMISSION_MODE` | Override non-Windows sandbox policy, such as `workspace-write` or `danger-full-access` |
+| `DSH_PERMISSION_MODE` | Override the non-Windows sandbox policy, such as `workspace-write` or `danger-full-access`; the initial permission plane of this launch, outranking the remembered `/permission` choice |
 | `DSH_TUI_WORKSPACE` | Working directory used by the Windows `dsh-tui.cmd` launcher |
 | `DSH_TUI_DEBUG` | Enable dsh-tui diagnostics on stderr |
 | `DSH_TUI_RENDER_LOG` | File path for raw ANSI frame capture |
@@ -325,8 +475,8 @@ The `/provider` add branch signs in to ChatGPT/Codex (`openai-codex`), Claude
 (`anthropic`), or Grok (`xai`) subscriptions. When the installed host's pi-ai
 catalog ships the corresponding flows, it also offers OpenAI direct ChatGPT sign-in
 (`openai`, using the OpenAI API rather than the legacy Codex backend) and Meta
-Muse (`meta`). The primary validated DSH `0.2.0-rc.2` fixture carries pi-ai
-`0.87.1`, which includes Meta Muse but not OpenAI direct sign-in.
+Muse (`meta`). The primary validated DSH `0.2.1-rc.2` development fixture resolves pi-ai
+`1.2.0`, which includes Meta Muse and OpenAI direct sign-in.
 `/auth status`, `/auth login [provider]`, and `/auth logout <provider>` use
 that credential store for these pi-ai routes. Browser authorization tries to open the page
 automatically and offers the authorization link and manual callback URL/code