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

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

@@ -25,10 +25,86 @@ Profile 启动按顺序叠加：
 > 覆盖某一行时，`config` 是整块替换，不是逐字段深合并。需要继续生效的字段必须
 > 在用户补丁中全部重写。
 
+## 网页搜索与抓取（DSH 0.2.1-rc.2）
+
+标准 DSH profile 会加载新的 DeepSeek Search / Fetch API 提供者，默认仍使用
+Messages 搜索和本地 HTTP 抓取。在 `/settings` 的「网页搜索」分区，用左右键将
+「搜索」选为「搜索 API」、「抓取」选为「抓取 API」；选择立即保存，从下一次操作
+生效，不需要重启。切回 `Messages` / `HTTP` 可恢复原提供者。Enter 可输入第三方
+提供者 ID。分区使用插件实际的 Loader 行 ID，也支持自定义 ID。
+
+「网页搜索」分区只有一个 API key 输入框，可直接粘贴当前搜索 API 的密钥。
+输入时显示掩码，确认后保存到 DSH 凭据库，不写入 profile 配置；重新打开只显示
+是否已设置，不回显原值。留空保留已有密钥，切换搜索 API 后使用该 API 的凭据。
+
+「DeepSeek 搜索 / 抓取 API」分区可修改 API 基础地址、搜索结果数
+（1–50）和「发送原始问题」。基础地址包含路径前缀，不含 `/search` 或 `/fetch`，
+默认 `https://api.deepseek.com/v1/tools`。账号路由由 DSH 使用已授权的账号令牌。
+默认会将最近一条
+用户提示的前 128 个字符随搜索请求发送，可在该分区关闭。Messages 搜索的端点与
+最大搜索次数在独立分区设置。
+
+也可通过用户 profile 补丁选择两个提供者：
+
+```yaml
+- id: web
+  config:
+    searchProvider: deepseek-search-api
+    fetchProvider: deepseek-fetch-api
+```
+
+TUI 沿用 DSH 的工具、鉴权、取消和结果持久化，不额外发起模型请求；旧宿主或未加载
+API 插件的组合不显示这些新增设置。官方 `deepseek-official` / `deepseek-account`
+路由的 `DeepSeek-V4.1-Flash` 在模型列表中显示 `1017` 标记，路由 ID 不变。
+
+## 官方请求元数据与反馈上报
+
+TUI bundle 继承已安装 DSH 官方组合的上报配置；上游未提供的服务不会由 TUI
+补装。当前验证线的默认行为如下，profile、home 和命令行补丁仍可覆盖：
+
+| 配置 | 官方默认 | 发送内容与触发条件 |
+| --- | --- | --- |
+| `plugin-package-inventory-deepseek.enabled` | `true` | `deepseek-official` 路由请求中的 `dsh_plugin_packages`，包含活跃插件包的名称与版本，可用于识别 TUI 使用量 |
+| `session-log-deepseek.enabled` | `true` | `deepseek-official` 路由请求中的 `dsh_session_log`，增量携带规范会话事件，可能包括工作目录、提示词、对话内容、工具参数和结果；与插件包清单分别控制 |
+| `session-telemetry-otel.mode` | `FEEDBACK_ONLY` | 新的显式反馈授权通过 OTel 上传截至反馈的会话日志前缀，包含上下文；普通聊天不触发该通道 |
+
+前两项是模型输入之外的请求元数据，不增加模型输入 token。两项都会发送到
+适配器配置的 `baseURL`，包括第三方网关。它们只随对应的 DeepSeek 请求发送，
+不能据此统计 Claude/Codex 后端的全部 TUI 使用。
+
+反馈遥测支持上游环境变量：
+
+- `DSH_TELEMETRY_MODE=DISABLED`：停止 OTel 会话日志上传；默认的 `FEEDBACK_ONLY`
+  仍只在反馈后授权上传。
+- `DSH_TELEMETRY_DISABLED`：任何非空值（包括 `0`、`false`）都会在启动时禁用
+  `session-telemetry-otel` 行。恢复时删除变量；它不控制上述两项 API 请求元数据。
+- `DSH_TELEMETRY_OTLP_URL`：覆盖 OTel collector 地址；未设置时使用已安装官方
+  版本的端点和导出参数。
+
+若需停止 API 请求元数据，可在用户 profile 补丁中分别关闭：
+
+```yaml
+- id: plugin-package-inventory-deepseek
+  config:
+    enabled: false
+- id: session-log-deepseek
+  config:
+    enabled: false
+```
+
+修改 bundle 或启动环境后重启 TUI，既有用户补丁不会被恢复默认的操作删除。
+
 ## TUI 配置
 
-DSH 0.1.7 的 `/settings` 写入当前 profile 的 `cordis.patch.yml`，字段属于插件
-Config；旧版仍使用 `~/.dsh/settings.yaml`。不要把旧文件路径当成新版设置入口。
+`/settings` 的 `dsh-tui` 分区存放在 TUI 自己的 `~/.dsh-tui/settings.json`，所有内核
+（DSH、Claude、Codex）共用这一份。第一次启动时，若该文件不存在，会从当前 profile 的
+`cordis.patch.yml` 里 `dsh-tui` 行的 `config` 一次性导入可编辑字段（只读，不改 profile；
+`!!js` 表达式不导入），之后不再重复导入。旧版 host 存在 `~/.dsh/settings.yaml` 里的
+`dsh-tui` 分区同时导入：尚未被 DSH 迁走的文件优先于补丁行；DSH 已迁入补丁、改名为
+`settings.yaml.imported` 的，补丁行优先。导入后 profile 补丁里残留的这些字段只在 DSH
+内核下作为静态部署层生效（用户层未设置时兜底），建议从补丁里删掉，避免两个内核看到
+不同的默认值。其他插件的分区仍由 DSH 的设置服务读写（写入当前 profile 的
+`cordis.patch.yml`；旧版是 `~/.dsh/settings.yaml`）。
 语言、布局等偏好实时更新；全屏和图片预览需 `/restart`。
 
 下面是完整的常用覆盖示例：
@@ -55,33 +131,44 @@ Config；旧版仍使用 `~/.dsh/settings.yaml`。不要把旧文件路径当成
 | 字段 | 默认/来源 | 说明 |
 | --- | --- | --- |
 | `provider` | Harness `agentDefaultModel`；裸组合回落 `deepseek-official` | DSH 模型路由名称；只有 provider 与 model 同时配置才构成显式路由 |
-| `model` | Harness `agentDefaultModel`；裸组合回落 `deepseek-flash` | 启动模型；`/model` 可通过 session fork 实时切换 |
+| `model` | Harness `agentDefaultModel`；裸组合回落 `deepseek-flash` | 启动模型；`/model` 可在同一 session 内切换后续请求的模型。优先级：`/model` 持久化选择（`~/.dsh-tui/model.json`，上次实际运行的路由，完整 pair）> 此处的完整 `provider`+`model` 对（部署默认值）> Harness 默认。半 pin（只有 `provider` 或只有 `model`）视为未设置，绝不与偏好拼成半个路由（issue #67） |
 | `cwd` | 启动目录所在的 git worktree 根（不在任何 worktree 内时为 `process.cwd()`；家目录的 dotfiles 仓不算） | TUI 会话侧工作区：agent meta、`@` 补全/提及展开、/resume 过滤、状态栏；恢复已有会话时以该会话持久化的 cwd 为准。注意 bash/fs-policy/sandbox 的根仍由组合层 cordis 配置决定（默认启动目录，归 dsh-base 管），与这里的会话侧 cwd 可能不同 |
 | `workspace` | 未设置 | 启动工作区目标；可用本地路径、`file://` URI 或插件提供的 URI，设置后优先于 `cwd` |
-| `effort` | 配置层通常为 `max` | 每个请求实际生效的推理等级（按运行时模型档位校验，非法档位静默回落默认；兼作顶栏启动显示）。优先级：/settings 的 `effortDefault`（`auto` 时让位）> 本字段 > `/effort` 持久化选择（`~/.dsh-tui/effort.json`）> 模型默认 |
-| `effortDefault` | 未设置 | 新会话默认推理强度；`auto` 让位给 `effort`，可经 `/settings` 修改 |
+| `effort` | 配置层通常为 `max` | 每个请求实际生效的推理等级（按运行时模型档位校验，非法档位静默回落默认；兼作顶栏启动显示）。优先级：/settings 的 `effortDefault`（`auto` 时让位）> `/effort` 持久化选择（`~/.dsh-tui/effort.json`，上次实际运行的档位）> 本字段（部署默认值）> 模型默认 |
+| `effortDefault` | 未设置 | 新会话默认推理强度（`/settings` 用户层，显式设定时优先于持久化 `/effort`）；`auto` 让位给持久化选择与 `effort`，可经 `/settings` 修改 |
 | `whale` / `whaleIdle` | `true` / `true` | 标题鲸鱼与欢迎页鲸鱼闲置动画 |
 | `splashFont` | `daily` | 开屏大字字体：`daily` 按本地日期轮换（默认），其余取字体 id（`bold` / `square` / `bevel` / `wide` / `dot` / `stencil` / `classic` / `slab`）pin 住那一款；非法值回落 `daily`。也可经 `/settings` 修改 |
-| `whaleGirl` | `false` | 把标题的像素鲸鱼换成女仆娘：**最优先**真图（Kitty/Sixel）；不支持时回落字符画版女仆娘 |
+| `whaleGirl` | `false` | 女仆娘立绘开关：DeepSeek 品牌下，宠物皮肤 deepy 或 whaleGirl 会占据开屏艺术槽；选 whale 并开启「女仆娘立绘」才会显示女仆娘。Claude 使用自己的图案，Codex 使用自己的真图或女仆娘字符画回退；这两个品牌的开屏图案不受宠物皮肤和女仆娘开关影响。这里「宠物皮肤」即 `companion.skin`；立绘生效时优先走终端图像协议（Kitty/Sixel）的真图，终端不支持则回落字符画版女仆娘。见下方的优先级小表 |
 | `minimal` | `false` | 极简界面（Minimal UI）：精简标题装饰与配色。**这是界面显示开关**，与下面 `preset` 里的内核「极简模式」预设完全是两件事（那个才决定模型能用哪些工具） |
 | `sidePanel.splitEnabled` | `true`（布尔） | 分栏总开关：开启时 `Ctrl+B` 与 `/panel` 在聊天右侧展开侧栏；关闭时两者都不再分栏，`/jobs` 等仍走整屏面板。立即生效 |
 | `sidePanel.open` | `false`（布尔） | 启动时侧栏是否已展开；默认关闭，升级后布局与原来一致。会话内的 `Ctrl+B` / `/panel toggle` 不写回这里。立即生效 |
 | `sidePanel.ratio` | `0.68`（数值，0.1–0.95） | 聊天列占内容宽度的比例；侧栏有焦点时 `+`/`-` 在当前会话内实时微调（不写回）。立即生效 |
 | `sidePanel.panels` | `todo,jobs,agents,info,trajectory,workspace,btw,companion`（逗号分隔文本） | 默认启用全部 8 个内置面板；这里控制面板 id 与顺序。格式合法但暂无面板认领的 id 会留在标签栏等插件注册，格式非法的条目被拒绝。面板栏右端的 `⤢` 把当前面板放大成整屏（只对声明了整屏形态的面板出现）。立即生效 |
- | `companion.skin` | `deepy` | 宠物面板的皮肤：`deepy`（默认，deepy 小鲸鱼素材包）、`whaleGirl`（鲸娘表情包，22 个动画含互动反应）或 `whale`（与开屏同款分层像素鲸鱼）；面板默认启用，可在 `sidePanel.panels` 调整。立即生效 |
+| `companion.skin` | `deepy` | 宠物面板的皮肤：`deepy`（默认，deepy 小鲸鱼素材包）、`whaleGirl`（鲸娘表情包，22 个动画含互动反应）或 `whale`（与开屏同款分层像素鲸鱼）；面板默认启用，可在 `sidePanel.panels` 调整。**DeepSeek 品牌下，它同时决定开屏（标题）艺术槽**：宠物皮肤为 deepy 或 whaleGirl 时，该槽由对应吉祥物占据（像素鲸鱼与女仆娘立绘都不出现），「女仆娘立绘」（`whaleGirl`）开关不生效；把宠物皮肤设为 whale 才回到原路径（像素鲸鱼；打开「女仆娘立绘」后为立绘）。立即生效，另见下方的优先级小表 |
 | `btw.contextTurns` | `4`（数值，1–8） | `/btw` 追问时带上的最近已完成问答组数；更早的组不进请求，线程和面板里仍保留。立即生效 |
 | `btw.contextBudget` | `24000`（数值，1000–200000） | `/btw` 追问携带的最近问答总字符数上限，超出时从最旧的一组开始丢。立即生效 |
 | `codeFrameStyle` | `light` | 回复里代码块的边框：`light` 只有顶部标签和左侧竖线，不多占行；`full` 是封闭的框。终端太窄时总是用纯文本 fence。立即生效 |
 | `turnUsageRow` | `false`（布尔） | 每回合末尾显示一行右对齐的用量（输入/输出、缓存、耗时、重试）；关闭时 `/tokens`、`/status` 和底栏悬停照样能看到这些数字 |
 | `modes` | 内置三档 | Shift+Tab 会话模式循环（plan/sandbox/approval 原子组合）；缺省为 默认 → 计划 → 完全访问 |
+| `upstreamRetry` | `true` | 为当前会话实际使用的 `llm-pi-ai` 渠道播种重试策略（最多重试 5 次，失败码覆盖传输类中断、含 `STREAM_CLOSED` 上游断链）：每次绑定（启动、`/model` 切换、resume）时检查该渠道，未声明 `retryPolicy` 才写入官方 `llm-pi-ai` settings 分节——内核 `llm-retry` 插件执行的就是这份策略。从不写闲置渠道；已显式声明 `retryPolicy` 的渠道（cordis.yml 或手改 settings）不会被覆盖；`false` 整体关闭 |
 | `activity` | `true` | 是否显示实时工作状态行 |
 | `activityFrames` | `moon8` | 工作状态动画预设；也可通过 `/activity` 修改。旧配置值 `claude` 读取时映射为 `moon8`，选择器不再显示该旧预设 |
 | `contextBar` | `true` | 输入框下方的分段上下文进度条；`false` 隐藏该行。与 `/settings → statusBar.contextBar`（默认开）同时为开才显示 |
 | `fullscreen` | `true`（0.9.0 起出厂默认） | `true` 使用 alternate screen、应用内滚动和鼠标选区；`false` 使用 inline 模式 |
 | `terminalImages` | `true` | 允许在支持的终端预览图片；`false` 保留文字信息，跳过图片探测与预览解码。修改后重启生效 |
-| `preset` | 名册默认 `standard` | 新会话 Agent preset；显式配置优先于持久化偏好 |
+| `preset` | 名册默认 `standard` | 新会话 Agent preset；优先级：`DSH_TUI_PRESET`（本次运行）> `/preset` 持久化选择 > 本字段（部署默认值）> 名册默认 |
 | `sessionId` | 未设置 | 要恢复的会话 ID，通常由 Windows `--resume` 启动器注入 |
-| `backend` | 未设置（`/kernel` 记住的选择，否则 `dsh`） | 会话后端：`dsh`，或实验性的 `claude` / `codex`（不区分大小写，未知值按 `dsh`）。profile 行读取 `DSH_TUI_BACKEND`，`dsh-tui --backend <id>` 会设置它。见 [Claude 后端](claude-backend.md) |
+| `backend` | 未设置（`/kernel` 记住的选择，否则 `dsh`） | 会话后端：内置 `dsh`，或已装的后端（实验性的 `claude` / `codex`，以及插件后端；不区分大小写）。**未安装或未知的取值一律按 `dsh` 启动并告警**，不会崩。profile 行读取 `DSH_TUI_BACKEND`，`dsh-tui --backend <id>` 会设置它。profile 自己的补丁里若把它写成 `!!js` 表达式（只转发 `DSH_TUI_BACKEND` 的写法除外，例如随包行的 `process.env.DSH_TUI_BACKEND \|\| undefined`），本次启动改走 `dsh --profile`（只有 profile 的 Loader 能求值），`/kernel` 切换除外。见 [Claude 后端](claude-backend.md) |
+
+DeepSeek 品牌下，开启标题图形（`whale`）时，`companion.skin` 与「女仆娘立绘」（`whaleGirl`）按下表决定开屏艺术槽：
+
+| `companion.skin` | 开屏（标题）艺术槽 | 女仆娘立绘开关 |
+| --- | --- | --- |
+| `deepy`（默认） | Deepy 吉祥物（字母格动画；**无真图**） | **不生效** |
+| `whaleGirl` | 鲸娘吉祥物（图像协议真图；无协议回落字母格） | **不生效** |
+| `whale` | 原路径：像素鲸鱼；打开女仆娘立绘后为立绘（真图优先，回落字符画） | **生效** |
+
+上表适用于「品牌外观」（`brand`）解析为 `deepseek` 时（包括 DSH 后端的 `auto`）。Claude 使用自己的真图或字符画；Codex 使用自己的真图，真图不可用或加载失败时回落女仆娘字符画。两者都不受 `companion.skin` 和 `whaleGirl` 影响；要使用表中的皮肤或女仆娘，先选 DeepSeek 品牌外观。关闭标题图形会隐藏所有品牌的图形。
 
 ### 优先级与强制关闭
 
@@ -160,8 +247,8 @@ Config；旧版仍使用 `~/.dsh/settings.yaml`。不要把旧文件路径当成
 ### 默认值与优先级
 
 - 默认值保存在 `~/.dsh-tui/agent-preset.json`。
-- 优先级：显式 `config.preset` 或 `DSH_TUI_PRESET` → 持久化偏好 → 名册
-  默认值 `standard`。
+- 优先级：`DSH_TUI_PRESET`（本次运行的显式指令）→ 持久化偏好 → 显式
+  `config.preset`（部署默认值）→ 名册默认值 `standard`。
 - 名册不再提供 `code` 时，旧偏好回退解析为 `ptc`，解析成功后迁移；rc 名册
   仍保留真实 `code` id，历史会话日志始终不改写。
 - 恢复旧会话时，以该会话日志记录的 preset 为准，不读取当前默认值覆盖它。
@@ -178,6 +265,44 @@ Config；旧版仍使用 `~/.dsh/settings.yaml`。不要把旧文件路径当成
 - 环境变量 `DSH_TUI_LIANGSHEN_BASH_PATH` 可显式指定 `bash.exe` 绝对路径。
 - 设置后即为唯一候选；找不到即告警并跳过注册，首轮直接放开完整工具目录。
 
+### Windows bash 工具（winbash）
+
+`presets/winbash.mjs` 是随包分发的 Windows `bash` 工具插件，挂载在 host 层后
+**对任意 Agent preset 生效**（与梁神模式无关、不进 `/preset` 名单）。行为对齐官方
+`dsh-tool-bash`——官方 bash 执行器 `dsh-bash-local` 为 POSIX-only，Windows 不适用，故有此件。
+
+- 每次调用在新 shell 中执行（`bash -c`），状态不跨调用保留；`description` 必填（UI 标题）。
+- `run_in_background: true`：命令登记为后台 job，立即返回 job id；`job_output`/`job_kill`
+  收集与停止，后台运行无超时。
+- 前台命令到超时不杀：转后台继续跑并返回 job id（`promoteOnTimeout`，可配置关闭）。
+- 非零退出以 `[exit code: N]` 标记报告，不算工具错误。
+- 无 job registry 的组合自动降级为纯前台（超时即杀），不暴露 `run_in_background`。
+- Git Bash 探测链与梁神模式相同（见上节）；环境变量 `DSH_TUI_WINBASH_BASH_PATH`
+  （兼容旧名 `DSH_TUI_LIANGSHEN_BASH_PATH`）可显式指定 `bash.exe`。
+
+挂载：把 `presets/winbash.mjs` 复制到 profile 根目录，在 `cordis.patch.yml`
+的插件列表追加：
+
+```yaml
+- id: windows-bash
+  name: './custom-bash.mjs'
+  disabled: !!js process.platform !== 'win32'
+```
+
+配置项（挂载行的 `config`）：
+
+| 键 | 默认 | 说明 |
+|---|---|---|
+| `timeoutMs` | `120000` | 前台默认超时（毫秒） |
+| `maxTimeoutMs` | `600000` | 单次调用超时上限（带 job 时也是工具级硬顶） |
+| `maxOutputBytes` | `64000` | 单流输出内存上限 |
+| `enableRunInBackground` | `true` | 是否暴露后台参数（需 job registry 在场） |
+| `promoteOnTimeout` | `true` | 前台超时是否转后台而非杀 |
+| `bashPath` | — | 显式指定 `bash.exe`（同环境变量） |
+
+> 与梁神模式内置的 `custom-bash` 注册同名工具 `bash`：同一 profile 只挂其一。
+> 同时使用梁神 preset 时把本行 `disabled` 置 `true`（梁神内置那份为前台版）。
+
 ### 自定义 preset
 
 0.1.7 通过 profile/bundle 声明 `@deepseek-ai/dsh-agent-preset`，配置包含 `id`、
@@ -229,16 +354,19 @@ Profile 模式不再使用旧的 `DSH_TUI_COMPACT_RATIO`、`DSH_TUI_COMPACT_RETA
 | `DSH_HOME` | harness 家目录（profile、会话、凭据、附件）；未设置时用上游默认 `~/.dsh` |
 | `DSH_TUI_PERSONA` | 覆盖组合注入的 Agent persona |
 | `DSH_TUI_PRESET` | 覆盖新会话默认 Agent preset |
-| `DSH_TUI_THEME` | 锁定内置（`auto`/`light`/`dark`/`dark-ansi`）、静态主题或已注册的插件主题，优先于持久化选择 |
+| `DSH_TUI_THEME` | 锁定内置（`auto`/`light`/`dark`/`dark-ansi`/`pink-day`/`pink-night`/`pink-ansi`）、静态主题或已注册的插件主题，优先于持久化选择 |
 | `DSH_TUI_DISABLE_MOUSE` | 在 fullscreen 模式临时关闭鼠标处理 |
 | `DSH_TUI_DISABLE_TERMINAL_IMAGES` | 设为 `1` 时强制关闭 Kitty/Sixel 探测、预览读取/解码与终端图片渲染，优先于 config 和 /settings；保留文字信息 |
 | `DSH_TUI_IMAGE_PROTOCOL` | `auto`（默认）、`kitty`、`sixel` 或 `none`；覆盖协议选择，但不绕过图片预览偏好、禁用开关、非全屏、无障碍和多路复用器限制 |
 | `DSH_TUI_RESUME_SESSION` | 启动时恢复指定会话，通常由启动器设置 |
-| `DSH_TUI_BACKEND` | 会话后端（`dsh` / `claude`），通常由 `dsh-tui --backend` 设置 |
+| `DSH_TUI_RESUME_BACKEND` | `DSH_TUI_RESUME_SESSION` 的来源后端，只在启动器**派生**恢复目标时（裸 `--resume` 读该后端的上次会话、安全模式重试按最后运行记录）设置；boot 若落在别的后端（未装的 id 回落 `dsh`、没给 `DSH_TUI_BACKEND` 时跟随记住的内核），该目标一律**明确报错并非零退出**——不跨后端恢复、不静默冷启动、不新建会话（安全模式重试是唯一例外，降级为告警 + 冷启动）。用户显式给出的 id 不带此标记、原样透传 |
+| `DSH_TUI_RESUME_RETRY` | 一次性标记：本次启动是安全模式的「重试正常启动」。重试的目标派生自最后运行记录，记录里的内核可能已经不在注册表里，所以带此标记的那次启动在恢复目标被撤销时降级为告警 + 冷启动，而不是报错退出。boot 读到即从 `process.env` 删除 |
+| `DSH_TUI_BACKEND` | 会话后端（内置 `dsh` / `claude` / `codex`，或已装的插件后端），通常由 `dsh-tui --backend` 设置；未安装或写错的 id 按 `dsh` 启动并告警（若同时带了 `--resume` 请求则改为报错退出，见上） |
+| `DSH_TUI_HOST_ENTRY` | 设为 `0` 时两个内核都经 `dsh --profile` 启动（默认两个内核都从本包入口启动）。入口用不了已安装的 dsh（`PATH` 上的 `dsh` 不是 `@deepseek-ai/dsh`、启动脚本跟不进去、所需模块或导出缺失）时，DSH 启动自动回退到 `dsh --profile`，并在终端与界面里说明原因 |
 | `DSH_TUI_CLAUDE_PERMISSION_MODE` | Claude 后端的起始权限模式（`default`/`acceptEdits`/`plan`/`dontAsk`/`bypassPermissions`），优先于 `/permission` 记住的选择 |
 | `DSH_TUI_WORKSPACE_TARGET` | 启动时解析的工作区路径或 URI，通常由 `dsh-tui <目标>` 设置 |
 | `DSH_TUI_SESSION_ROOT` | 覆盖 JSONL 会话根目录；profile 默认 `$DSH_HOME/sessions`，裸 `cordis.yml` 默认 `~/.dsh-tui/sessions` |
-| `DSH_PERMISSION_MODE` | 非 Windows 平台覆盖 sandbox policy，例如 `workspace-write` 或 `danger-full-access` |
+| `DSH_PERMISSION_MODE` | 非 Windows 平台覆盖 sandbox policy，例如 `workspace-write` 或 `danger-full-access`；作为本次启动的初始权限面，优先于 `/permission` 记住的选择 |
 | `DSH_TUI_WORKSPACE` | Windows `dsh-tui.cmd` 采用的工作目录 |
 | `DSH_TUI_DEBUG` | 启用写往 stderr 的 dsh-tui 调试日志 |
 | `DSH_TUI_RENDER_LOG` | 指定文件路径，记录原始 ANSI 渲染帧用于取证 |
@@ -286,8 +414,8 @@ Profile 模式不再使用旧的 `DSH_TUI_COMPACT_RATIO`、`DSH_TUI_COMPACT_RETA
 `dsh-auth` 插件包**。`/provider` 的添加分支提供 ChatGPT/Codex（`openai-codex`）、
 Claude（`anthropic`）、Grok（`xai`）订阅账号登录。宿主 pi-ai catalog 提供相应流程
 时还可使用 OpenAI 直连 ChatGPT 登录（`openai`，使用 OpenAI API 而非旧版 Codex
-后端）和 Meta Muse（`meta`）。当前主验证线 DSH `0.2.0-rc.2` 携带 pi-ai
-`0.87.1`，包含 Meta Muse，但不提供 OpenAI 直连登录。`/auth status`、`/auth login [provider]`、
+后端）和 Meta Muse（`meta`）。当前主验证线 DSH `0.2.1-rc.2` 的开发依赖解析到 pi-ai
+`1.2.0`，包含 Meta Muse 与 OpenAI 直连登录。`/auth status`、`/auth login [provider]`、
 `/auth logout <provider>` 对这些 pi-ai 路由操作同一套凭据。浏览器授权会尝试自动打开页面，并在同一
 问卷中提供授权链接与手动粘贴回调 URL/代码的输入；设备码流程在轮询期间显示可复制的
 短码。无交互问卷服务的宿主会明确拒绝登录。

package/guide/dsh-tui-guide/getting-started.en.md

@@ -387,6 +387,21 @@ that starts `dsh`. Check `DEEPSEEK_BASE_URL` too for a custom endpoint. For
 `deepseek-account` or a subscription model, inspect `/auth status` and sign in again with
 `/auth login <provider>` if needed.
 
+### The browser connects but dsh-tui cannot reach a self-hosted HTTPS endpoint (self-signed cert / private CA)
+
+Self-hosted LLM token servers on a private network are often fronted with HTTPS certificates issued by Caddy, mkcert, Step CA, or similar, whose root certificate is not in Node.js's built-in Mozilla CA bundle. The browser and system `curl` then work fine, but after switching dsh-tui to that provider the TLS handshake fails with `self-signed certificate in certificate chain` or `UNABLE_TO_VERIFY_LEAF_SIGNATURE`.
+
+The reason is that dsh-tui's HTTP requests run on Node.js's TLS layer, and Node.js trusts only two things: the Mozilla CA bundle compiled into it, plus the PEM file named by the `NODE_EXTRA_CA_CERTS` environment variable (merged with the built-in list). macOS Keychain "trust" settings have no effect on a Node.js process — Node does not call the system Security.framework, so the trust chain the browser and `curl` use is irrelevant here.
+
+Export the root certificate as PEM and set the variable before launching dsh-tui:
+
+```sh
+export NODE_EXTRA_CA_CERTS=/path/to/your-ca-root.pem
+dsh-tui
+```
+
+Note that `NODE_EXTRA_CA_CERTS` is a bootstrap-protected variable for the DSH launcher: no `.env` file may set it (neither the project directory's `.env` nor `~/.dsh/.env`), and putting it there makes startup fail with an error telling you to `export` it instead — it can only come from the shell environment that launches dsh. The same protected group covers other certificate / TLS variables such as `SSL_CERT_FILE`, `SSL_CERT_DIR`, and `NODE_TLS_REJECT_UNAUTHORIZED`.
+
 ### The activity row appears twice
 
 Check whether `dsh-working-activity` was added separately to the profile. Keep

package/guide/dsh-tui-guide/getting-started.md

@@ -387,6 +387,21 @@ dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui@latest
 自定义端点同时检查 `DEEPSEEK_BASE_URL`。若使用 `deepseek-account` 或订阅模型，
 用 `/auth status` 检查登录状态，必要时重新运行 `/auth login <provider>`。
 
+### 浏览器能访问、dsh-tui 连不上自建 HTTPS 端点（自签证书 / 私有 CA）
+
+内网自建的 LLM token 服务器常用 Caddy、mkcert、Step CA 等签发 HTTPS 证书，这类根证书不在 Node.js 内置的 Mozilla CA 列表里。于是浏览器和系统级 `curl` 都能正常访问，dsh-tui 切到该 provider 后却在 TLS 握手阶段失败，报 `self-signed certificate in certificate chain` 或 `UNABLE_TO_VERIFY_LEAF_SIGNATURE`。
+
+原因是 dsh-tui 的 HTTP 请求跑在 Node.js 的 TLS 层上，而 Node.js 只信任两样东西：编译时打包的 Mozilla CA bundle，以及环境变量 `NODE_EXTRA_CA_CERTS` 指向的 PEM 文件（与内置列表合并）。macOS Keychain 里的「信任」设置对 Node.js 进程无效——Node 不调用系统的 Security.framework，浏览器和 `curl` 用的信任链跟它无关。
+
+解决办法是把根证书导出成 PEM，在启动 dsh-tui 之前设置该变量：
+
+```sh
+export NODE_EXTRA_CA_CERTS=/path/to/your-ca-root.pem
+dsh-tui
+```
+
+注意 `NODE_EXTRA_CA_CERTS` 属于 DSH 启动器的 bootstrap 保护变量：任何 `.env` 文件（项目目录的 `.env` 与 `~/.dsh/.env` 都算）都不允许设置它，写进去会在启动时直接报错退出并提示改用 `export`，只能由启动 dsh 的那个 Shell 环境继承。同组受保护的证书 / TLS 变量还有 `SSL_CERT_FILE`、`SSL_CERT_DIR`、`NODE_TLS_REJECT_UNAUTHORIZED` 等。
+
 ### 工作状态行重复
 
 检查 profile 是否曾单独添加 `dsh-working-activity`。保留本包 patch 自动插入的

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

@@ -64,10 +64,13 @@ side panel (`Ctrl+B`/`Alt+Z`), subagent dashboard, show-all, and todo fold are r
 - Plugins may also contribute one text line above the prompt, or a compact rich status view of up to three rows when the host exposes `tuiStatus.registerView`.
 - Rich views receive only host `Box`, `Text`, `Image`, and terminal size. Click/hover/drag work in fullscreen, and the view never owns the keyboard.
 - `Image` takes decoded RGBA pixels plus a same-size cell fallback.
-- After a successful Kitty probe, the host centers the image at its natural aspect ratio
-  using terminal-reported cell geometry (or a conservative default), adding transparent
-  letterboxing and downsampling when needed. Otherwise it renders the fallback (including
+- After a successful Kitty probe, the host enlarges or downsamples the image to the
+  reserved cell box's physical pixels, preserving its aspect ratio with centered transparent
+  letterboxing. It uses terminal-reported cell geometry (or a conservative default) and
+  downsamples boxes that exceed the pixel budget. Otherwise it renders the fallback (including
   inline, accessibility, and multiplexer sessions).
+- The 16 MiB frame budget bounds both decoded sources and fitted rasters;
+  images over the budget keep their text fallback.
 - Plugins provide the keyboard path for the same action through a slash command or `tuiShortcuts`.
 - A refused rich registration returns `undefined`; an admitted one returns a disposer that removes both the view and its Cordis effect.
 
@@ -77,16 +80,16 @@ The startup **launchpad** and the **first-run wizard** each own the keyboard; bo
 results back to the chat screen and add no new behavior.
 
 - **Launchpad**: printable input goes into the input box (the prefix turns from `❯` to `⌘` when the line
-  starts with `/`), `Backspace`/`Delete`/`←`/`→`/`Home`/`End` edit it; the caret is an **inverse block
-  sitting on the current character** (inverse on that one character; an inverse blank cell at end of
-  line — a theme that declares the `cursor` key paints a solid fill with a contrasting glyph instead,
-  see [Themes](themes.en.md)), blinking is a pure style toggle (inverse ↔ regular, ~550ms per phase)
-  and never occupies an extra cell or eats a character; `Alt+R` continues the most recent session
+  starts with `/`), `Backspace`/`Delete`/`←`/`→`/`Home`/`End` edit it; the **native terminal cursor**
+  inherits your terminal's shape, color, blinking, and enabled animation or trail effects.
+  Cursor movement never adds a cell or eats a character. Static rendering retains the
+  [theme-painted fallback](themes.en.md); `Alt+R` continues the most recent session
   (= the first entry row slot, bound only on this screen, no-op when there is nothing to continue,
   remappable in `/settings`);
   a leading `/` opens the
   **command palette** (the same data source and component as the chat composer: `↑`/`↓` move the selection,
-  `Enter`/`Tab`/click **run** the selected command, `Esc` dismisses only the palette and keeps the draft);
+  `Tab` **completes** the selected command in the input box with the caret at the end,
+  `Enter`/click **run** it and clear the input, `Esc` dismisses only the palette and keeps the draft);
   with the palette dismissed, `Enter` **sends** the line straight away (a leading `/` line — including
   plugin/registry commands — goes through the chat page's merged command table and never reaches the model);
   `↑`/`↓`/`Tab` walk the focus ring (input box → the four param segments under the box → the quick
@@ -126,13 +129,16 @@ results back to the chat screen and add no new behavior.
 - **Corner plates**: the bottom-left working directory is **clickable** — it opens the existing
   `/workspace` menu (rendered above the launchpad; `Esc` returns to the launchpad), keyboard path =
   the focus ring's last slot + `Enter`, hover/focus = text highlight; the bottom-right plate starts
-  with `dsh-tui v<TUI>`, followed by one row for each of the two kernels:
-  `▸ DSH · dsh-core v<kernel>` / `Claude · claude-code v<CLI>`. `▸` marks the current kernel and the
-  other row stays dim; an unavailable kernel adds the reason after its version (such as *Not installed*
-  or *Not signed in*), a row whose version cannot be read shows just the name, and *Checking…* shows
-  while the probe runs. The whole block is clickable and opens the same kernel picker (keyboard path =
-  focus ring + `Enter`). Rows are right-aligned, the cwd plate is top-aligned to the first row, and
-  narrow terminals truncate per the existing truncate-middle contract.
+  with `dsh-tui v<TUI>`, followed by one row for **each registered backend**:
+  `▸ DSH · dsh-core v<kernel>` / `Claude · claude-code v<CLI>` (then `Codex · codex-cli v<CLI>`, and any
+  installed plugin backend after it). The name is the backend manifest's short label; `▸` marks the
+  current kernel and the other rows stay dim; an unavailable kernel adds the reason after its version (such as *Not installed*
+  or *Too old · upgrade needed*), a row whose version cannot be read shows just the name, and *Checking…* shows
+  while the probe runs. Sign-in state never enters the plate — check it in the picker when switching (a signed-out
+  row is selectable, its subtitle says *Not signed in*). The whole block is clickable
+  and opens the same kernel picker (keyboard path =
+  focus ring + `Enter`). Every row ends flush at the same right edge, the cwd plate is top-aligned to the
+  first row, and narrow terminals truncate per the existing truncate-middle contract.
 - **Wizard**: `←`/`→` change step (except the effort slider in step 3 and a drilled-in model list, where the
   horizontal keys belong to the child control), `Tab` switches between the language/theme and
   model/effort/workspace panes, `↑`/`↓` move the selection; `Enter` runs the step (step 1 = re-check
@@ -330,6 +336,7 @@ The four commands and the `⌸` entry at the head of the prompt row all open the
 
 - The workspace rail (the durable registry) on the left.
 - The sessions of the selected workspace on the right, every row carrying that session's live state.
+- Focus starts on the most recently used session in the current workspace, ready for `Enter`; with no history, it starts on the new-session card.
 
 They used to be three implementations that grew apart — a session browser, an agent view,
 a workspace home — each listing the same session with its own selection model and its own
@@ -350,7 +357,7 @@ brings it back.
 
 | Key | Action |
 | --- | --- |
-| `←` `→` | Choose the column that owns the keyboard (rail / sessions); exactly one `❯` is on screen |
+| `←` `→` | Choose the column that owns the keyboard (rail / sessions), preserving the selected session in the same workspace; exactly one `❯` is on screen |
 | `↑` `↓` / `PgUp` `PgDn` / wheel | Move in the rail; move in the session list (row 0 is the new-session card) |
 | Type | Filter the selected workspace's sessions live (title, directory, branch, model) |
 | `Enter` | Sessions: enter the row under the cursor (row 0 = start a session in this workspace). Rail: open that workspace's action menu |
@@ -361,6 +368,10 @@ brings it back.
 | `Tab` / `Shift+Tab` | Next / previous source tab (when other agents have sessions) |
 | `Esc` | Dismiss a notice → clear the filter → leave the screen |
 
+Each workspace starts on its most recent visible session, or the new-session card if it has no matches. Changing columns or moving the mouse into the list preserves the current selection. Changing workspace chooses that workspace's newest session; returning chooses the newest again, without remembering past selections per workspace. Until you choose a list row, partial results, complete reads, and later refreshes keep following the newest visible session. After you select a session or the new-session card, refreshes preserve that choice.
+
+The native cursor follows the last-used region, as in the model picker: workspace navigation parks it on the workspace row, session navigation on the session row or new-session card, and typing or clicking the filter on its text caret. Row carets hide after 0.5 seconds at rest; the search caret stays visible. Animation and trail effects come from your terminal settings. Narrow layouts keep the caret on a visible target when the workspace rail is hidden. Arrow and Enter actions keep the same meaning while filtering.
+
 The right side of the title row is the **source strip**: `DSH │ Claude Code  Codex …`.
 
 - A tab appears only for another coding agent on this machine (Claude Code, Codex, Grok Build, zcode) that has conversations, in a fixed order; with none, there is no strip. Opening the screen only checks whether each source has any conversation; a source's list is read when its tab is opened.
@@ -462,6 +473,13 @@ Notes:
   and never reaches the main context or token counts (closing the panel discards it).
 - **Never interrupts the running turn**: it can be triggered while the model is streaming; the main task keeps going.
 - Inside the panel: `↑`/`↓` scroll, `Space`/`Enter`/`Esc` dismiss, `c` copies the answer; `Esc` cancels while the answer is still pending.
+- The sidebar panel (when the panel column is open) has two layers: the default **reading layer** — `←`/`→` switch panels, `↑`/`↓` move the **selection** between turns, `PgUp`/`PgDn` page, `n` starts a new topic, `s` sends the **selected** turn's answer to the main composer (press `s` again to take it back), `c` copies the selected turn's answer; `Enter`/`Tab` (or a click on the input) enters the **editing layer** (`Esc` leaves one layer at a time: editing first, draft kept), where `←`/`→` move the caret first and, once the caret sits at the start/end, the same key falls through and switches panels again, while `↑` goes straight back up to the titles.
+- The sidebar's bottom hint line **follows the layer** (the panel advertises it, the host only stitches it): with the cursor in the **list** it says `↑/↓ select · s to chat · c copy` (or `s unsend` for the attached turn); with the cursor in the **input** it drops s/c (there `s` is just a letter) and says `↑ select` instead. An empty thread advertises nothing there. The input box keeps only an `Enter to ask` placeholder.
+- The selection shows itself in exactly two ways: the title's **text** is inverted (not the whole row) and the terminal cursor parks on that row — so `↑`/`↓` visibly walks the native caret between titles. Both are hidden while the cursor sits in the main input or the side composer: they mean "the list owns the keyboard". **Clicking a title row** moves the selection there too.
+- Scrolling only happens when it must: a target title already inside the viewport scrolls nothing at all; one outside it scrolls just far enough to **exactly reveal** that row (flush to the top edge when walking up, flush to the bottom edge when walking down).
+- **Focus returns to the main composer after sending**: the chip is right there, you can keep typing, and `Esc` removes it immediately (inside the panel `Esc` leaves the panel instead of dropping the chip).
+- Clicking the **message area** (question or answer text) only hands the column focus to the panel, exactly like clicking anywhere else in it — it never injects anything; `s` is the only way in.
+- The `⤢` full-screen scene shares the sidebar's keys and selection state (both read the same thread store); the only difference is that after sending it steps aside and returns you to the main composer.
 - Triggering `/btw` again aborts the previous side question.
 
 ### Trajectory scene (/trace / Ctrl+T)
@@ -491,9 +509,15 @@ A full-screen scene (no scrollback pollution) over the whole session timeline:
 
 ### Model and preset
 
-`/model` switches through a session fork at the end of current history, because DSH has no in-place model-switch API. The old session remains in `/resume`.
+`/model` shows the model list and the highlighted model's reasoning effort on one page. DSH also has provider tabs, with **Recently used** first; opening records the current model as the latest use and moves it to the front without duplicates, initially focusing it when it is still in the catalog.
+Codex and Claude show their complete model catalogs directly, without provider or recents tabs; the current model is initially focused when the catalog loads.
+In DSH, `Tab` selects the next provider and `Shift+Tab` the previous one, wrapping at either end; all backends use `↑/↓` to select a model and `←/→` to adjust its effort.
+The native terminal cursor follows the **region you used last**: `Tab`/`Shift+Tab` moves to the provider tab, `↑/↓` to the focused model's `❯`, and `←/→` to the effort level. Movement shows the terminal's original cursor shape, blinking, and enabled animation or trail effects; the cursor hides after **0.5 seconds at rest**, then reappears and restarts the timer on the next movement. Ordinary repaints do not extend this window; text input carets stay visible, and accessibility mode retains visible focus anchors. Clipped tabs or unavailable effort levels fall back to the model row. Inverse tabs and the `❯` pointer always remain visible, including in static rendering.
+Confirmation submits only explicit effort drafts. Changing only the model leaves saved-effort validation to the backend; candidate defaults do not become new preferences. While the picker is open, `Ctrl+B` and `Alt+Z` still control the sidebar, and picker navigation stays with the model picker.
+`Enter` applies the model and effort; `Esc` cancels the draft. Shortcuts sit below the title, and a separate effort heading and level strip sit below the models, with the `←/→` hint beside the effort heading. Selectable levels use the body text color and the current level is highlighted. DSH, Claude, and Codex use the terminal background while covering the text underneath.
+Click tabs, models, and effort levels, then click **select** or **cancel** below the title; the wheel moves through the model list. When space above the input is tight, navigation hints, model descriptions and neighboring models are omitted, effort collapses to one row, and Select / Cancel stay at the bottom. With only two rows, effort is hidden too, keeping the focused model and actions visible.
 
-- A session nobody has typed into records no branch: switching models there yields an independent session with no `parentSession` (inheriting the same session-scaffolding prefix), so the first real prompt you send still triggers automatic session-title generation. A session that already holds a conversation keeps its lineage as before.
+`/model` selects the next request’s route within the same DSH session, preserving its ID, history, and title. Switching is refused during a running turn. The next request records the actual route and a model-change notice. Parked agents retain their selection when reattached. After the process exits, a choice with no subsequent request is saved only as a global default; disk resume resolves the last recorded request route. DSH versions before `0.1.2-alpha.3` refuse switching and prompt an upgrade so legacy subagents cannot silently use the original model.
 
 - `/preset` switches in place only for a blank session. In a started session, the choice becomes the default for the next `/new` or launch.
 
@@ -604,8 +628,9 @@ In inline mode, the terminal emulator owns native scrollback and selection.
   transcript behind an open overlay. Moves the cursor in the trajectory scene (±3 rows per
   notch on the timeline, ±1 in hotspot; scrolls the detail while expanded). Walks the
   focused row in /settings.
-- **Drag** — Select text, copy on release, then clear the selection; a "Copied N characters"
-  notice pops up. With `dsh-tui.scrollGutter: scrollbar`, the right-edge scrollbar is a drag
+- **Drag** — Select text and copy on release, keeping the selection; a "Copied N characters"
+  notice pops up. A new selection replaces the retained one. With
+  `dsh-tui.scrollGutter: scrollbar`, the right-edge scrollbar is a drag
   target: an unmodified left drag scrubs the transcript to the track position (same mapping
   as a track click — drag to point), while `Shift`/`Alt`/`Ctrl`+drag still selects text (the
   drag protocol opens only for unmodified left presses).
@@ -784,7 +809,7 @@ The command menu merges local commands with the DSH command registry. Type `/` t
 
 **Account and policy**
 
-- `/provider`, `/login`, `/logout`, `/permission`, `/add-dir`, `/hooks`, `/mcp`, `/plugins` — `check <path>` validates a plugin manifest.
+- `/provider`, `/login`, `/logout`, `/permission`, `/add-dir`, `/hooks`, `/mcp`, `/plugin` — `list` shows the plugins you added (the installation-supplied bundles stay out); `install <spec>` installs a plugin into this profile (a pre-install notice and a trust confirmation; first-party packages on the packaged feed skip the confirmation; `esc` closes the pane, and during an install it attempts cancellation and waits for writes to settle, or for completion if too late; exemptions already written remain; blocked build scripts are approved in the pane, and an incompatible version can be exempted for that exact version); `remove <bundle>` / `enable <name|id>` / `disable <name|id>` are the lifecycle actions (a bundle name wins over a row identity; a module name matching multiple rows requires a specific row ID; gate 2 refuses the bundle providing this app, the host layer `dsh-base` and this package's own rows, with a reason and no service call, while every enable and removal asks first because installed sources cannot be verified; **no cancellation** — `esc` only closes the pane and the write goes on, and a removal does not delete your own data); `check <path>` validates a plugin manifest, `info <id>` describes an installed entry or an install spec, `registries` lists where installations ask; bare `/plugin` gives the full diagnostics.
 - After `/auth login deepseek-account` or `/provider` signs in, a Platform-confirmed, unshown login bonus appears with its amount and expiry as a “Whale coupon” in the whale-maid dialog; Enter/Esc closes it.
 
 **Skills**
@@ -796,7 +821,7 @@ The command menu merges local commands with the DSH command registry. Type `/` t
 - `/update`, `/vim` — vim editing mode toggle, see "Editing keys".
 - `/terminal-setup`, `/connect`, `/help`, `/exit` — aliases `/quit`, `/q`.
 - `/kernel` — opens the kernel picker (the current kernel is ticked; every row
-  carries a version and a one-line explanation), on DSH and Claude sessions alike.
+  carries a version and a one-line explanation), on DSH, Codex and Claude sessions alike.
   Picking the other kernel remembers it and restarts into it with a new session;
   the old session stays in `/resume`, and if the new session fails to start you
   are back on the old one. A running turn blocks the switch. The launchpad's
@@ -805,6 +830,11 @@ The command menu merges local commands with the DSH command registry. Type `/` t
   a later direct launch follows the flag. A fresh launch lands on the launchpad
   whichever kernel is remembered; a launch with a resume target goes straight
   into the session.
+- `/dsh`, `/codex`, `/claude` — directly choose the named kernel through the same
+  checks and restart flow as `/kernel`. Choosing the current kernel only reports
+  that it is already current; a running turn blocks switching. Missing Claude
+  opens the install wizard; missing or outdated Codex shows install/upgrade guidance.
+  These shortcuts also work before startup is ready.
 
 **Registry**
 
@@ -829,7 +859,7 @@ Additional forms:
 - `/model` opens a two-level picker:
   - A pinned **Recently used** group first — the last 10 switched models, persisted at `~/.dsh-tui/model-recents.json` — then provider groups.
   - `Enter` drills into a group's models, and a single provider with no recents skips straight to the list.
-  - Switching = fork continuation, history preserved.
+  - Switching keeps the current session and history; the new model is used for the next request.
 - `/theme <name>` and `/theme status` are described in the theme guide.
 - `/permission` reads the DSH `permissionPresets` registry, preserving registry order for
   the picker, completion and the `Shift+Tab` cycle. Third-party presets need no TUI
@@ -842,6 +872,16 @@ Additional forms:
   path (the same handler, real events) and confirms via event/readback. When neither is
   available, it fails loudly instead of sending the input to the model.
 - Exiting plan mode restores the pre-plan atoms first, then the durable preset you were on before plan mode (while the registry still offers it).
+- The DSH `/permission` pick is persisted the same way at `~/.dsh-tui/permission.json`: every durable
+  preset switch teaches it (picker, typed command, Shift+Tab static mode, or a switch the official
+  command performed on its own), and a session that never customized its permission planes starts on
+  the remembered preset — applied through the same official switch path. "Never customized" means the
+  USER never touched it: the composition itself writes its default preset into every fresh session at
+  creation (`dsh-permission-presets`' `session/created` → `pinInitialPermission`), and those events are
+  not a user choice — only a session that ran a turn, or whose identity is not the composition default,
+  keeps its own planes. Plan-mode transients are excluded (entering plan keeps the pre-plan memory; the
+  exit restore teaches it again), `DSH_PERMISSION_MODE` is this launch's initial permission plane and
+  outranks the file when set, and an identity the mounted roster no longer offers is skipped.
 - When the registry service is absent, TUI uses its legacy three-row compatibility roster; a mounted but broken service is unavailable and fails closed.
 - Non-DSH backends (Claude) that declare native permission modes answer
   `/permission` with that backend's own modes: `default` (ask before each risky