dsh-ssh-tui 0.7.0-rc.1 → 0.7.0

package/README.en.md

@@ -66,6 +66,16 @@ Reproducible, no model in the loop: `npm run screenshots:slow` writes
 `docs/screenshots/slow-link.json`. This capture is 14 paints, about
 **18.0 KB**, **8.8 s** at 2 kB/s. Byte ledger for this event sequence.
 
+0.7 highlights: drag-select any part of a model reply to copy it (OSC 52 into your local
+clipboard; a tool card still expands on click) · the footer is one priority-ordered chip
+strip, and `⚠` opens `/doctor` · the quota bar is on screen from the first frame and names
+its window (`5Hr`/`1Wk`/`1Mo`, smallest window by default, `?%` with a 15-second retry until
+a reading arrives) · `/mode` groups presets and filters with `/` · the compact view names
+every changed file · tool diffs are line-level, emphasise only what changed, and go
+side-by-side at 100 columns or more · `DSH_TUI_LINE_MODE=1` appends plain lines for screen
+readers and `tee` · `ssh-tui.keys` rebinds keys, refusing conflicts · `DSH_TUI_COLOR_DEPTH`
+pins the palette (truecolor / 256 / 8 / none).
+
 ## Requirements
 
 - Node.js >= 22.19
@@ -135,6 +145,7 @@ milliseconds; `0`/`off` restores the old behavior) and then exits, handing the
 lock back — long enough for the old window to reattach, after which `--resume`
 reopens the flushed log. A Host that never finishes its turn still falls back to
 `DSH_TUI_DETACHED_IDLE_MS` (6h). Optional: wrap the TUI in tmux.
+Copy-paste recipes for keeping a session reachable (tmux, screen, systemd --user, long turns) are in [`docs/remote-ops.md`](docs/remote-ops.md) (Chinese for now), together with what the `reconnected N times · away X` and `away …` transcript lines mean.
 
 New sessions inherit the directory you launched from. Resuming a session
 `chdir`s into that session's recorded working directory. The footer shows
@@ -285,68 +296,28 @@ You can reopen the wizard at any time with:
 
 ## Cross-platform support
 
-The plugin runs on Linux, macOS, and Windows (Node ≥ 22.19):
-
-- Linux/macOS: same command as above; the wizard persists credentials in
-  `~/.dsh/.credentials.yaml`, or `~/.dsh/env.sh` when a system-injected
-  environment variable must be overridden.
-- Windows (PowerShell or Windows Terminal): install with the same npm/dsh
-  commands — `dsh` is on PATH via npm's global bin. The wizard stores the key
-  through the dsh credential store, or runs `setx` (plus `env.cmd`) when an
-  environment variable shadows the store. Agent shell tools automatically use
-  PowerShell on Windows (the harness disables bash there).
-- Windows display channel: the Host/Display link is a named pipe
-  (`\\.\pipe\dsh-tui-<8-hex DSH_HOME>-<session name>-<8-hex session id>`), not a
-  `.sock` file — a named pipe is the only local socket Windows can listen on,
-  and it is reclaimed when the Host exits. Both digests are part of the name so
-  two homes or two sessions can never share one machine-wide pipe. Because `fs.access()` cannot see the pipe namespace, readiness is
-  probed with a real connect, and a Host that exits early is reported at once
-  with its stderr (kept in `%USERPROFILE%\.dsh\tui-socks\<session>.err`).
-- Windows session locks: with no `/proc`, a live pid is checked with
-  `Get-Process` (image name plus creation time), so a pid recycled by an
-  unrelated process is recognised as stale and the session resumes instead of
-  reporting a phantom zombie Host.
-- Footer speed (`135 tok/s`): measured from the first token the model emits
-  (reasoning or tool-call fragments included) to the settled step, and rebuilt
-  when a session is replayed on `--resume` — from the durable `assistant/chunk`
-  events on 0.1.2 hosts, or from the packed stream inside `assistant/message`
-  on 0.1.5. Steps with no usable timing fall back to `首字 1.2s`.
-- Emoji width: BMP symbols carrying the Unicode `Emoji` property are budgeted two cells. When the monospace font lacks the glyph, the terminal falls back to a colour emoji about 1.6 cells wide that still advances one cell — it covers its neighbours, and the second budgeted cell goes unspent so the row comes up short. `pinEmojiCells()` does both halves at paint time: VS15 asks for the narrow text form, and a reserving space spends the second cell (emitted unconditionally, so "two cells plus every space in the text" equals "one cell of glyph advance, one reserving space, and those same spaces" for every shape). Symbols that already default to emoji presentation (`✅` `⚡` …) and astral emoji (`😀` …) advance two cells and are left alone.
-- Reconnect: channel readiness is a real connect, so a `.sock` file left behind by a killed Host is no longer listed as attachable (it used to fail the first attach with `write EPIPE`); a Host still cancelling/flushing keeps itself alive when a relay HELLOs mid-hangup; a launcher that hits a vanished peer retries once automatically — silently, with the TTY kept in raw mode and queued bytes dropped so a stale cursor reply is never echoed as `^[[17;1R`; and a probe that misses its window is retried while the Host keeps the last measurement, so the footer chip does not fall back to four hollow circles.
-- Reporting a problem: `/diag` prints a local, read-only snapshot — plugin/dsh/node
-  versions, platform, session id, whether this process is the launcher or the detached
-  Host, `DSH_HOME`, the display channel address and whether it answers (including the
-  leftover-socket-file verdict), the Host pid/identity/lock state, the lock file path, link
-  RTT and paint interval, the session log format and size, other locks on the machine, and
-  a **verdict chain** ("attaches to the leftover Host (pid N), do not open a second
-  window", "the pid was recycled", "a leftover socket file that does not answer — the
-  source of the first-attach EPIPE"). Nothing leaves the machine; paste it into an issue.
-- When `/mode` reports a missing service or the preset tools vanish after an upgrade
-  (the 0.6.3 class of configuration regression), run `/doctor`. It judges the
-  **deployment composition** item by item: whether the profile patch parses, whether the
-  agent-presets roster and code-runtime are composed (naming the missing row), whether the
-  subagent model-selection settings row is mounted, whether any row is mounted twice (with
-  its line), whether the profile layer and the bundle layer both mount a row, whether the
-  host version is in the plugin's declared compatibility table, whether two
-  `@deepseek-ai/dsh-scope` installs exist (the nested-install copy trap), and whether the
-  default route and the subagent model are self-consistent. Every item carries its evidence
-  and the command that acts on it. `/doctor --fix` mounts the missing rows and merges
-  duplicates into `cordis.patch.yml`, keeping a `.bak-<timestamp>` beside it and never
-  touching an override or disable you wrote; `/fix code-runtime` repairs one row. A restart
-  picks it up, and like `/diag` nothing leaves the machine.
-- Leftover Host lifetime: the write lock a dropped-but-still-running Host holds is what makes the Web UI refuse the same session (`resume failed for session … is already owned by an active write handle`), and a drop that raced a reattach used to leave the honored-reattach flag set, so the *next* drop was ignored and the session lock kept its stale state. The flag is cleared once a turn runs again, and once the turn the Host stayed for settles it exits within `DSH_TUI_IDLE_EXIT_MS` (default 60s, `0` disables) instead of holding the session for six hours.
-- Subagent route: the identity row always carries `sub:<model>` — the route
-  every child inherits — suffixed with the effort when `/subeffort` set one,
-  and prefixed with the provider when `settings.yaml` pinned one
-  (`ssh-tui-subagent.provider`), e.g. `sub:xai/grok-4.5(xhigh)`.
-- Resize: the launcher picker unregisters its own `resize` listener when it
-  settles and refuses to paint afterwards, so resizing the window can no longer
-  redraw the finished picker over the running TUI (the launcher process keeps
-  owning the TTY as the display relay for the whole session).
-- Legacy Windows consoles without VT support: set `DSH_TUI_NO_ALT_SCREEN=1`
-  (and `--no-color` if needed) to skip the alternate-screen escape sequences.
-- Keyboard input accepts both `\x7f` and `\x08` backspace, and both `\r` /
-  `\r\n` line endings.
+- **Windows**: the display channel is a named pipe
+  (`\\.\pipe\dsh-tui-<8-hex DSH_HOME>-<session name>-<8-hex session id>`) — the only
+  local socket Windows can listen on — and it is reclaimed when the Host exits. Readiness
+  is probed with a real connect, and a Host that exits early is reported at once with its
+  stderr (`%USERPROFILE%\.dsh\tui-socks\<session>.err`). Session locks check a live pid
+  with `Get-Process` (image name plus creation time), so a recycled pid is recognised as
+  stale instead of reported as a phantom zombie Host.
+- **Legacy Windows consoles without VT support**: set `DSH_TUI_NO_ALT_SCREEN=1` (and
+  `--no-color` if needed) to skip the alternate-screen escape sequences.
+- **Footer speed** (`135 tok/s`) is measured from the first token the model emits to the
+  settled step, and is rebuilt when a session is replayed with `--resume`. A step with no
+  usable timing shows `首字 1.2s` instead.
+- **Emoji / CJK width**: BMP symbols carrying the Unicode `Emoji` property are budgeted two
+  cells, and the painter asks for the narrow text form (VS15) plus a reserving space. A
+  monospace font that lacks the glyph still makes the terminal fall back to a wider colour
+  emoji, so pick a font that covers what you use (Noto Sans Mono CJK, for instance).
+- **Keyboard input** accepts both `\x7f` and `\x08` backspace, and both `\r` / `\r\n`
+  line endings.
+- **Subagent route**: the identity row always carries `sub:<model>` — the route every child
+  inherits — with the effort in parentheses when `/subeffort` set one, e.g.
+  `sub:grok-4.5(xhigh)`. Only the model name is shown; the provider and the full route are
+  in `/status`.
 
 ## Usage
 
@@ -506,8 +477,8 @@ completion (`DSH_TUI_NO_BELL=1` disables it).
 
 Tool calls render as compact cards instead of raw argument JSON. The title
 stays the default foreground; the status dot is yellow / green / red for
-running / ok / error. Success no longer repeats `[ok]` next to the green
-dot; failures still show `[error]`, and in-flight calls still show
+running / ok / error. A successful call shows the dot alone — no `[ok]`
+suffix — while a failure still carries `[error]` and an in-flight call
 `[running…]` (plus `[退出码 N]` / `[信号 X]` when a shell exits). Consecutive
 reads or edits of the same path fold into one card (`×N`, cumulative
 chars/lines, appended diffs, a brief flip animation).
@@ -597,6 +568,105 @@ does not write into the transcript.
 Idle hangup exits the Host. A busy turn keeps it; `--resume` attaches to that
 process. Do not start a second Host.
 
+## Troubleshooting (Q&A)
+
+Find your symptom; each answer is what to do, not a change log.
+
+### Start-up and install
+
+- **`dsh-ssh-tui: both stdin and stdout must be TTYs`** — start it from a real terminal or
+  SSH session; a pipe, CI, or `&` background job will not do.
+- **Windows: `host display socket did not appear`** — upgrade
+  (`dsh plugin --profile tui add dsh-ssh-tui@latest`); older builds waited 15 seconds and
+  timed out on the named pipe. If it still fails, attach `/diag` to an issue.
+- **pnpm refuses to run the build script of a git dependency** — add the key pnpm prints to
+  `allowBuilds` in the profile's `pnpm-workspace.yaml`, then reinstall.
+- **After an upgrade `/mode` reports a missing service, or the preset tools vanish** — run
+  `/doctor`: it judges the deployment composition item by item (patch parses, roster and
+  code-runtime composed, no row mounted twice, host version inside the compatibility table,
+  two `@deepseek-ai/dsh-scope` installs) and gives a verdict, its evidence and the command
+  that acts on it. `/doctor --fix` writes the missing rows into `cordis.patch.yml`, keeping
+  a `.bak-<timestamp>`; a restart picks it up.
+- **"session is already running on pid N / attachable"** — that Host is alive: attach with
+  `dsh --profile tui --resume`. Do not open a second window; clear `$DSH_HOME/tui-locks/`
+  only once the pid is really gone.
+
+### Sessions and locks
+
+- **The Web UI refuses a session (`already owned by an active write handle`)** — the Host
+  left over from an SSH drop still holds the write lock; it exits within a minute of the
+  turn settling (`DSH_TUI_IDLE_EXIT_MS` / `ssh-tui.idleExit`). You can also attach to it
+  with `--resume` and keep working.
+- **The first `--resume` fails with `write EPIPE`, the second works** — the launcher waits
+  and retries once by itself. If it keeps failing, `/diag` prints the channel and lock
+  verdict chain, including the leftover-socket-file case.
+- **Too many history sessions to tell apart** — filter the `--resume` picker by title,
+  session id or working directory (`/` or `Ctrl+F`); older history is read on demand when
+  you filter or page to the end, and the counter shows how many are still unloaded.
+
+### Display and terminal
+
+- **Colours look wrong, or a diff is one solid block you cannot read** — pin the palette
+  with `DSH_TUI_COLOR_DEPTH=truecolor|256|8|none`. At `256` a diff is dark grey with green
+  or red text; at `none` there is no colour at all, but `+`/`-`, `●`, `⚠` and `✖` remain —
+  status is never carried by colour alone.
+- **CJK or emoji crowd the characters next to them** — use a monospace font that covers
+  them (Noto Sans Mono CJK, for instance). Those symbols are budgeted two cells and the
+  painter asks for the narrow text form; a font without the glyph still makes the terminal
+  fall back to a wider colour emoji.
+- **The screen cannot keep up on a slow link** — `DSH_TUI_PAINT_MS` sets the paint interval
+  (40–1000 ms: smaller is snappier and sends more); unset, it follows the round-trip
+  measured at start-up (80 / 160 / 250 / 400 ms).
+- **Screen reader, or you want a log** — start with `DSH_TUI_LINE_MODE=1`: plain appended
+  lines, no cursor control, safe to `tee`.
+- **Title bar or bell does nothing** — the terminal needs OSC 0 and BEL; `DSH_TUI_NO_BELL=1`
+  turns the bell off.
+- **Whole-row backgrounds are too loud on a dark terminal** — `DSH_TUI_COLOR_DEPTH=none`
+  drops them; diffs still read through `+`/`-`.
+
+### Status line and quota
+
+- **The quota widget shows `░░░░░░░░ ?%`** — no reading has arrived yet (the API is slow or
+  unreachable). It is not `0%`. The TUI asks again every 15 seconds and replaces it with the
+  real number and window; if it never does, `/quota` reports the error.
+- **There is no quota widget** — only SuperGrok, OpenCode Go and Command Code report quota;
+  DeepSeek shows a balance line and a metered Zen route shows none.
+- **What do `5Hr` / `1Wk` / `1Mo` mean?** — the window the number belongs to. The smallest
+  window is shown by default (5-hour → weekly → monthly); `/quota` lists every window with
+  its remaining share and reset time. Threshold alerts still fire on the tightest window.
+- **The model name has no provider prefix** — the status line shows the model alone
+  (`provider/model` is truncated to the model); the full route is in the header and
+  `/status`, and a `sub:` chip shows the child's model the same way.
+- **The subagent model is not what you want** — `/submodel` picks the model, `/subeffort`
+  the reasoning effort, `/status` shows the current pair.
+- **No `tok/s`** — that turn had no measurable model tokens; a step with only a first-token
+  time shows `首字 1.2s`.
+- **The plan strip asked for leftover todos only once** — that is deliberate: one reminder
+  per open list, so a turn end never spawns another turn forever. To see it again, complete
+  the list and start a new one.
+
+### Drops and proxies
+
+- **What happens when SSH drops** — idle: flush and exit. Busy (thinking, replying, a tool,
+  a subagent): the turn is cancelled by default and the Host stays, so
+  `dsh --profile tui --resume` attaches to it; `/disconnect continue` lets it run to
+  completion instead. Do not start a second Host.
+- **After reconnecting there is an extra notice line, `^[[17;1R` flashes, and the link chip
+  goes hollow** — upgrade; the automatic retry stays in raw mode and drops queued bytes, so
+  those replies are no longer echoed.
+- **Model requests must go through a proxy** — start dsh with `--use-env-proxy` (not via
+  `NODE_OPTIONS`) and split by domain with `NO_PROXY`, keeping domestic hosts that are faster
+  direct and every local/intranet address in the list. The recipe and its revert are in
+  [docs/remote-ops.md §4.7](docs/remote-ops.md).
+
+### Asking for help
+
+- **You need a readable report for a supporter** — type **`/diag`** in the session (local and
+  read-only): versions, platform, session id, `DSH_HOME`, the display channel and whether it
+  answers, the Host pid and lock state, link RTT, log format and size, and a verdict chain
+  ("attaches to the leftover Host (pid N), do not open a second window"). Deployment
+  questions go to **`/doctor`**. Paste both into an issue.
+
 ## Development
 
 ```text

package/README.md

@@ -67,8 +67,8 @@ dsh --profile tui
 - 转录区滚动回看（`PgUp`/`PgDn`、鼠标滚轮），点击思考/工具标题行直接展开收起；
 - 输入框下方两行底栏：第一行链路芯片 + 按宽度丢组的会话数字（轮次、入/出 token、速度）；
   第二行只留一个活动词（运行中 / 工具 N / 子代理 N / 压缩中…），身份收到右侧（含 `目录:srv`；点击打印完整工作目录）；
-  身份里始终带 `sub:<子代理模型>`：`/submodel` 选模型、`/subeffort` 选档位（带括号后缀）；提供商前缀只在
-  设置里固定过子代理提供商时出现（如 `sub:xai/grok-4.5(xhigh)`，`settings.yaml` 的 `ssh-tui-subagent.provider`）；
+  身份里始终带 `sub:<子代理模型>`（如 `sub:grok-4.5(xhigh)`）：`/submodel` 选模型、`/subeffort` 选档位（带括号后缀）；
+  只显示模型名——提供商与完整路由在顶栏与 `/status`；
 - 恢复旧会话会切到该会话记录的工作目录；新建会话用启动时的当前目录；
 - 历史会话启动选择器：`dsh --profile tui --resume`（或 `resume`）先选会话再进入；
 - 终端窗口标题栏：运行中旋转图标 + `运行中 · 工具 N`，完成后 `✓ 已完成`，并响
@@ -87,6 +87,13 @@ dsh --profile tui
   标题（还没出现就保持「处理中」），运行中的工具摘要在 `└` 下自动折行（最多 3 行，末行
   加省略号），带计时和 Esc 中断；回复开始流式输出时自动让位。
 
+- 0.7 起：模型回复可**拖选自由复制**（按住拖过一段，走 OSC 52 写回本机剪贴板；工具卡仍是点击展开）；
+  底栏收敛成一条带优先级的芯片带（先丢文字后丢组，`⚠` 可点击打开 `/doctor`）；**额度条常驻**并标注窗口
+  （`5Hr`/`1Wk`/`1Mo`，默认显示最小窗口，未取到时显示 `?%` 并每 15 秒重试）；`/mode` 分组显示并可用 `/` 过滤；
+  极简视图逐文件列 `+/-`；工具 diff 为**行级**、只高亮变化字符、≥100 列时并排显示；
+  `DSH_TUI_LINE_MODE=1` 纯行模式（屏幕阅读器 / `tee`）；`ssh-tui.keys` 可改键位（冲突会明确拒绝）；
+  `DSH_TUI_COLOR_DEPTH` 指定色深（truecolor / 256 / 8 / none）。
+
 ## 环境要求
 
 - Node.js ≥ 22.19
@@ -160,8 +167,14 @@ Host 在后台跑完这一轮；审批和提问等接上后再弹。空闲断线
 留下的 Host 持有该会话的内核写锁（`session.lock`），而 Web 端打开同一会话时正是被这把锁挡下的
 （`resume failed for session … is already owned by an active write handle`）。所以它**跑完留下来的那一轮后最多再等 1 分钟**
 （`DSH_TUI_IDLE_EXIT_MS`，或 settings.yaml 的 `ssh-tui.idleExit`，毫秒；设 `0`/`off` 恢复旧行为）
+
+按键可改：`ssh-tui.keys`（动作 `pageUp` / `pageDown` / `toggleCard` / `copy` / `cancel`，如 `keys: { pageUp: ctrl+b }`）。
+冲突或未知的名字**不会静默生效**：启动时提示，且该键保持默认或变成无操作。
+纯行模式：`DSH_TUI_LINE_MODE=1`（或 `ssh-tui.lineMode: true`）——不画帧，逐事件追加纯文本行，
+适合屏幕阅读器、`tee` 与录屏；代价是全屏交互（鼠标拖选、卡片展开、`/find` 高亮）不可用。
 就自行退出并让出锁：这段时间够原窗口重连接入，之后 `--resume` 重新打开已落盘的日志。
 完全没有显示器且一直空闲的兜底仍由 `DSH_TUI_DETACHED_IDLE_MS`（默认 6 小时）负责。可选：用 tmux 包一层。
+常驻与接管的可复制配方（tmux / screen / systemd --user / 长任务）见 [`docs/remote-ops.md`](docs/remote-ops.md)；重连后转录里的「已重连 N 次 · 断开 Xs」与「离开 …」两行的语义也在那里。
 
 启动时若 npm 上有更新，会弹出选单（类似 Codex / Claude Code 首启）：**现在更新 / 稍后 / 跳过此版本**。选「现在更新」会运行 `dsh plugin --profile tui add dsh-ssh-tui@latest`，完成后提示退出再启动。`DSH_TUI_NO_UPDATE_CHECK=1` 可关掉。`/status` 里也能看到当前插件版本、链路芯片、额度窗口，以及子代理模型是否与父路由同族。
 
@@ -500,79 +513,72 @@ npm run typecheck
 npm run build
 ```
 
-## 常见问题
-
-- **`dsh-ssh-tui: both stdin and stdout must be TTYs`**：必须从真实终端/SSH 会话启动。
-- **Windows 报 `dsh-ssh-tui: host display socket did not appear`**：0.5.7 及更早版本把显示通道
-  当成 Unix socket（`$DSH_HOME/tui-socks/*.sock`），而 Windows 只能监听 `\\.\pipe\` 命名管道，
-  Host 进程绑定失败；旧版本还用 `fs.access()` 判断通道是否就绪，而 Windows 的文件 API 看不到
-  命名管道，所以即使 Host 已经起来也只会等到 15 秒超时。0.5.8 起 Windows 自动改用命名管道
-  （按 `DSH_HOME` + 会话 id 生成唯一管道名），就绪判断改为真实连接探测，并在 Host 提前退出时
-  立即报错并附带其 stderr。升级到 0.5.8 即可：`dsh plugin --profile tui add dsh-ssh-tui@latest`。
-- **pnpm 拒绝 git 依赖的构建脚本**：git 安装的插件需要把 pnpm 打印的 key 加入
-  profile 的 `pnpm-workspace.yaml` 的 `allowBuilds`。
-- **标题栏或铃声不生效**：确认终端支持 OSC 0 与 BEL；铃声可用
-  `DSH_TUI_NO_BELL=1` 关闭。
-- **滚轮误触取消**：已加入转义序列缓冲，网络拆包也不会把 `ESC` 当取消。
-- **emoji 宽度**：带 Unicode `Emoji` 属性的 BMP 符号按 **2 格**预算。等宽字体缺字形时终端会回退到彩色 emoji 字形——它比所在单元格宽（实测约 1.6 格）却只前进 1 格，于是压住相邻字符；而预算的第二格没人用，整行又比终端宽度少算格子。绘制时 `pinEmojiCells()` 两件事一起做：补 **VS15** 请终端改用窄的文本字形；再补一个**占位空格**把第二格真正用掉（**无条件补**，即使后面本来就有空格——这样"预算 = 符号 2 格 + 文本里每个空格"与"终端实际 = 字形 1 格 + 占位 1 格 + 每个空格"在每种情况下都相等）。字形 1 格 + 占位 1 格正好等于预算的 2 格，所以既不压字也不会短算；已带 VS15/VS16 的会归一成一个 VS15，本就默认 emoji 呈现的符号（`✅` `⚡` 等）和星号区 emoji（`😀` 等）本来就走 2 格，不动。
-- **跳板机 / 多层代理 SSH 发画**：每一帧只发脏行，并且拼成一次 `stdout.write`。本机 80 ms；SSH 启动时用 CSI 6n 测往返，按 RTT 选 80/160/250/400 ms。`DSH_TUI_PAINT_MS` 始终优先（40–1000）。统计行最左是 `SSH ●●●○ 90ms`（一格红、两格黄、三格及以上绿）。探测不写进转录。
-- **SSH 断了**：空闲则 flush 后退出（不保活）。忙碌（思考/回复/工具/子代理）则默认取消当前轮次、flush 日志，Host 留下。`/disconnect continue` 则不取消，后台跑完。回来 `--resume` 会接入那个进程（见上文）。不要再开第二份 Host。
-- **提示会话已在 pid 运行 / 可接入**：那份 Host 还活着。用 `--resume` 接入；只有 pid 已死、显示通道也连不上时才删 `$DSH_HOME/tui-locks/` 再从日志恢复。
-  Windows 没有 `/proc`，0.5.8 起会用 `Get-Process` 核对 pid 的镜像名与创建时间：pid 被系统回收给
-  别的进程时会被判定为陈旧并自动接管，不再出现「明明没有 Host 却报 zombie」。
-- **状态栏没有速度指标（`tok/s`）**：第一行统计里的速度只在该轮有模型 token 时出现；只有首字耗时可算
-  时显示 `首字 1.2s`。0.5.8 修复了两处：实时流的 chunk 帧不带 turn/step，旧版会把它们归到第 0 步
-  导致速度永远是 0（顺带把 token 数重复计了一次）；`--resume` 重放日志时也不再用实时增量，而是从
-  日志里的 `assistant/chunk`（0.1.2）或消息内嵌的打包流（0.1.5）重建首字时间，恢复会话同样显示速度。
-- **断线后第一次 `--resume` 报 `write EPIPE`、第二次才接上**：三处互相叠加。其一，Host 掉线时按"掉线那一刻"的状态
-  决定去留，若它正在取消/落盘收尾，这时重连进来的显示端会被连同进程一起 dispose（表现就是第一次接入 EPIPE）；
-  现在收尾期间若有新 relay 完成 HELLO，就保留 Host 不退出。其二，就绪判断过去用 `fs.access` 看 `.sock` 文件在不在——
-  被杀的 Host 留下的空文件也算"就绪"，relay 往死 socket 写 HELLO 就 EPIPE，而且这种条目会被选择器当成
-  「可接入」优先排在最前面；现在就绪一律以真实连接探测为准，死会话判陈旧并连残留文件一起清掉。
-  其三，launcher 首次接入若立刻 EPIPE/ECONNRESET，会自动等待并重试一次，不必手动再跑一遍。
-- **断线重连会多出一行提示、还会闪出 `^[[17;1R` 之类的字符、延迟芯片变四个空心圆**：0.5.9 的自动重试会把
-  "正在收尾，稍候重试"打到屏幕上，而两次尝试之间终端回到 cooked 模式，上一次探测的 DSR 回复正好被回显；
-  同时重连时的整屏重绘会让终端的回复错过探测窗口，Host 收到"未知"就把已有测量擦成 `SSH ○○○○`。
-  现在：自动重试默认**静默**（`DSH_TUI_DEBUG=1` 才打印）；重试/等 Host 启动期间保持 raw 模式并丢弃排队字节，
-  不再回显；探测失败会自动补测一次，Host 侧也不会用"未知"覆盖已知测量。
-- **resume 选择器第一批列表出现不认识的会话 / 会话一多就要等很久**：早期版本第一轮画的是"骨架"
-  （活着的 Host 只拿会话 id 当标题），而为了不闪出裸 id 又得等标题；等于把一次全量扫描的时间摆在用户面前。
-  现在首批固定 9 条、**全部读到标题后才上屏**（期间显示「正在读取历史会话…」，屏幕上不会出现先裸 id、
-  一秒后变标题的行），更早的会话按需读取：在最后一条继续按 `↓`/`PgDn`、按 `End`，或直接输入筛选
-  （筛选会自己往更早历史里找，凑够一页就停）。计数行会显示还有多少条未加载。
-- **要给支持者一份可读的排障信息**：在会话里敲 `/diag`。它只读本地信息、不外传，输出
-  插件/dsh/node 版本、平台、会话 id、当前进程是启动器还是后台 Host、`DSH_HOME`、显示通道地址与
-  可连接性（含"残留 socket 文件"判定）、Host 的 pid/身份核对/锁状态/agent 状态、锁文件路径、
-  链路 RTT 与绘制间隔、会话日志格式与大小、本机其它会话的锁，最后是**判定链**——例如
-  "会接入后台 Host（pid N），不要另起第二个窗口"、"pid 被回收成别的程序"、
-  "通道上留着不响应的 socket 文件，这正是第一次接 EPIPE 的来源"。报 issue 时贴这段即可。
-- **升级后 `/mode` 报「服务不可用」、preset 工具消失**：敲 `/doctor`。它在 `/diag` 的会话事实之外
-  把**部署组合**逐项判定：profile 补丁能否解析、agent-presets 名单与 code-runtime 是否组合
-  （缺哪一行直接点名）、子代理模型选择设置行在不在、有没有行被挂载两次（带行号）、profile 层与
-  bundle 层是否重复挂载、dsh 版本是否在插件声明的兼容表内、是否装着两份 `@deepseek-ai/dsh-scope`
-  （npm 嵌套安装的副本陷阱），以及默认路由与子代理模型是否自洽。每项给「结论 + 证据 + 修复命令」。
-  `/doctor --fix` 会把缺的行补进 `cordis.patch.yml`、把重复的挂载合并掉，写前留
-  `.bak-<时间戳>` 备份，**不动你自己写的 override/disable**，重启 TUI 后生效；只想修一行时用
-  `/fix code-runtime`。与 `/diag` 一样只读本地信息、不外传。
-- **TUI 里进得去、Web 里打不开同一个会话**：会话的写锁（`session.lock`）是内核锁，同时只允许一个写者。
-  SSH 断开时那个还在跑轮的 Host 会留着锁，于是 Web 端打开时报
-  `resume failed for session "…" is already owned by an active write handle`——从 0.5.10 起
-  该 Host 在轮次结束后最多再等 1 分钟就退出并放锁（`DSH_TUI_IDLE_EXIT_MS`/`ssh-tui.idleExit`）。
-  若锁仍被某个 Host 占着，`--resume` 接入它即可正常继续（选择器里那条会话会标「可接入」）。
-- **断线重连后锁被标成「已暂停」/「接入中」，但窗口其实已经关了**：0.5.10 修掉了一个状态机 bug。
-  重连接的 relay 在 hangup 收尾期间 HELLO 后，Host 会记下"这次 hangup 要采纳它"的标记；但 hangup
-  走保留 Host 分支时没有清掉这个标记，于是**下一次真实掉线整个被忽略**：锁仍写着上一个状态
-  （例如「已暂停」），空闲退出计时器也不会武装。现在只要轮次重新开始（说明那场竞争早已结束），
-  标记就会归零，掉线、锁状态与空闲退出都以真实事件为准。
-- **状态栏看不到子代理模型**：0.3.6 起 `sub:<模型>` 只在子代理模型与父模型不同时才拼进身份行，
-  而默认子代理模型就是 `deepseek-v4-flash`，父模型也是它时整段消失；0.5.8 起恢复为始终显示，
-  并找回提供商前缀与 `/subeffort` 的括号后缀（提供商要先在 `settings.yaml` 的 `ssh-tui-subagent.provider`
-  里固定过）。查看或修改：`/status`、`/submodel`、`/subeffort`。
-- **缩放终端窗口时整屏闪烁、还闪出历史会话选择器**：启动选择器注册 `resize` 监听时用的是匿名函数，
-  退出时却按 `render` 这个引用去注销，于是监听器一直留在中继进程里（中继要活整个会话）。之后每次
-  缩放终端，那张已经结束的选择器都会被整屏重画一遍（`\x1b[H\x1b[J` + 整屏内容），紧接着再被 TUI
-  的整屏重画覆盖——看起来就是闪两下并闪出选择器内容。0.5.8 起改用命名监听器注销，并给已结束的
-  选择器加 `done` 守卫：结算后再触发 `resize` 一个字节都不会写（有回归测试）。
+## 常见问题（QA）
+
+按现象查；每条只讲怎么办，不讲版本历史。
+
+### 启动与安装
+
+- **`dsh-ssh-tui: both stdin and stdout must be TTYs`**：必须在真实终端 / SSH 会话里启动；管道、CI、`&` 后台都不行。
+- **Windows 报 `host display socket did not appear`**：升级到最新版：
+  `dsh plugin --profile tui add dsh-ssh-tui@latest`。仍失败请附 `/diag` 输出提 issue。
+- **pnpm 拒绝 git 依赖的构建脚本**：把 pnpm 打印的 key 加进 profile 的 `pnpm-workspace.yaml` 的 `allowBuilds`，再重装。
+- **升级后 `/mode` 报「服务不可用」、preset 工具消失**：敲 `/doctor`。它逐项判定部署组合（补丁能否解析、
+  名单与 code-runtime 是否组合、有没有行被挂载两次、dsh 版本是否在兼容表内、是否装着两份 `@deepseek-ai/dsh-scope`），
+  每项给「结论 + 证据 + 修复命令」；`/doctor --fix` 会补齐 patch、写前留 `.bak-<时间戳>` 备份，重启 TUI 生效。
+- **提示「会话已在 pid 运行 / 可接入」**：那个 Host 还活着，用 `dsh --profile tui --resume` 接入。
+  **不要**再开第二个窗口；只有 pid 确实已死时才清 `$DSH_HOME/tui-locks/` 再从日志恢复。
+
+### 会话与锁
+
+- **Web 端打不开同一会话（`already owned by an active write handle`）**：SSH 断开时仍在跑轮的 Host 会持有写锁，
+  轮次结束后最多 1 分钟自动退出并放锁（`DSH_TUI_IDLE_EXIT_MS` / `ssh-tui.idleExit` 可调）；也可以直接 `--resume` 接入它继续。
+- **`--resume` 第一次报 `write EPIPE`、第二次才接上**：launcher 会自动等待并重试一次。若持续失败，
+  用 `/diag` 看显示通道与锁的判定链（含"残留 socket 文件"这一常见来源）。
+- **历史会话太多、认不出哪条是哪个**：在 `--resume` 选择器里按标题 / session id / 工作目录筛选（`/` 或 `Ctrl+F`），
+  更早的历史会在筛选或翻到末尾时按需读取；计数行会显示还有多少条未加载。
+
+### 显示与终端
+
+- **颜色不对，或 diff 整块一个颜色、看不清字**：显式指定色深 `DSH_TUI_COLOR_DEPTH=truecolor|256|8|none`。
+  `256` 下 diff 是深灰底 + 绿/红字；`none` 完全没有颜色，但 `+`/`-`、`●`、`⚠`、`✖` 仍在，状态不只靠颜色表达。
+- **中文 / emoji 挤压相邻字符**：换一款覆盖这些字形的等宽字体（如 Noto Sans Mono CJK）。程序按 2 格预算这些符号
+  并请求文本字形；字体缺字时终端会回退到彩色 emoji 字形，视觉上仍可能偏宽。
+- **弱网下画面跟不上**：`DSH_TUI_PAINT_MS` 控制发画间隔（40–1000 ms，越小越快也越费流量）；
+  不设时按启动测得的 RTT 自动取 80 / 160 / 250 / 400 ms。
+- **要给屏幕阅读器或日志用**：`DSH_TUI_LINE_MODE=1` 启动纯行模式——只追加纯文本行、不发光标控制，可直接 `tee` 存档。
+- **标题栏 / 铃声不生效**：终端需支持 OSC 0 与 BEL；`DSH_TUI_NO_BELL=1` 可关闭铃声。
+- **深色终端下整行底色太抢眼**：`DSH_TUI_COLOR_DEPTH=none` 去掉底色，diff 仍用 `+`/`-` 区分。
+
+### 状态栏与额度
+
+- **额度条显示 `░░░░░░░░ ?%`**：**还没拿到读数**（接口慢或不通），不是 0%。TUI 每 15 秒重试一次，拿到后自动替换成
+  真实数值与窗口；一直不变成数值时用 `/quota` 看具体报错。
+- **没有额度条**：只有 SuperGrok / OpenCode Go / Command Code 有额度；DeepSeek 显示的是余额行，Zen 是计量制。
+- **`5Hr` / `1Wk` / `1Mo` 是什么**：该数值所属的额度窗口。默认显示**最小窗口**（5 小时 → 周 → 月），
+  `/quota` 列出全部窗口、剩余比例与重置时间。告警仍按"最紧的那个窗口"触发。
+- **状态栏模型名没有提供商前缀**：状态行只显示模型名（`provider/model` 会截断成模型名），完整路由在顶栏与 `/status`；
+  `sub:` 子代理同理，只显示模型名。
+- **看不到子代理模型 / 想换子代理**：`/submodel` 选模型、`/subeffort` 选思考档位，`/status` 查看当前值。
+- **没有 `tok/s`**：该轮没有可统计的模型 token；只有首字耗时时显示 `首字 1.2s`。
+- **计划条只提醒一次"补待办"**：有意如此——一条待办列表只问一次，避免每轮结束都开一个新回合。
+  想再次触发，先把列表全部标成完成，再新开一列待办。
+
+### 断线与代理
+
+- **SSH 断了会怎样**：空闲则落盘后退出；忙碌（思考 / 回复 / 工具 / 子代理）默认取消当轮、保留 Host，
+  回来 `dsh --profile tui --resume` 接入；`/disconnect continue` 则让它在后台跑完当前轮。**不要**再开第二个 Host。
+- **重连后多出一行提示、闪出 `^[[17;1R` 之类的字符、链路芯片变空心**：升级到最新版；自动重试期间保持 raw 模式
+  并丢弃排队字节，这些字符不会再被回显。
+- **模型请求要走公司 / 本机代理**：给 dsh 进程加 `--use-env-proxy`（不要用 `NODE_OPTIONS`），并用 `NO_PROXY`
+  按域名分流——国内直连更快的域名放进去，本地 / 内网地址务必保留在列表里。做法与回退见
+  [docs/remote-ops.md §4.7](docs/remote-ops.md)。
+
+### 排障入口
+
+- **要给支持者一份可读的排障信息**：在会话里敲 **`/diag`**（只读本地信息、不外传）：版本、平台、会话 id、
+  `DSH_HOME`、显示通道与可连接性、Host 的 pid / 锁状态、链路 RTT、日志格式与大小，最后是**判定链**
+  （例如"会接入后台 Host（pid N），不要另起第二个窗口"）。部署组合问题用 **`/doctor`**。报 issue 时贴这两段即可。
 
 ## License
 

package/docs/remote-ops.md

@@ -0,0 +1,154 @@
+# 远程运维手册：断线、接管与常驻
+
+这份文档回答一个问题：**在一条会断的 SSH 链路上，怎么让会话按你的预期活下来、又怎么把它接回来。**
+它只描述当前实现的行为与可复制的配方；机制本身写在 README 的排障一节。
+
+> 语言：本手册目前只有中文。README 的中英两版都指向这里，若要英文版请提 issue。
+
+## 1. 断线时会发生什么
+
+| 掉线时的状态 | 行为 |
+|---|---|
+| **空闲**（没有轮次在跑） | launcher 交还终端并退出，会话日志已落盘。回来 `--resume` 从日志恢复，**没有 Host 在等你** |
+| **忙碌**（思考 / 回复 / 工具 / 子代理在跑），默认策略 `pause` | 取消当前轮次、flush 日志，**Host 留下**并持有会话写锁，等你回来接入 |
+| **忙碌**，`/disconnect continue` | 不取消，Host 在后台把这一轮跑完；你回来时结果已经在转录里（可能还带着子代理的进度） |
+| 你开了第二个窗口去接同一个会话 | 新窗口接管显示，旧窗口退出（`replaced`）。**不要为同一个会话起第二份 Host** |
+
+会话写锁是内核锁：同一时刻只有一个写者。这是为什么"再开一个窗口"和"再起一份 Host"是两件不同的事——前者是接管，后者会失败（`already owned by an active write handle`）。
+
+## 2. 三个时间旋钮
+
+| 旋钮 | 默认 | 作用 |
+|---|---|---|
+| `DSH_TUI_IDLE_EXIT_MS`（或 settings.yaml 的 `ssh-tui.idleExit`） | `60000`（60s） | 忙碌掉线留下的 Host，在**轮次结束后**再等多久无人接入就自行退出并让出锁。`0`/`off` 恢复旧的"长时间保留"行为 |
+| `DSH_TUI_DETACHED_IDLE_MS` | `21600000`（6h） | 完全没有显示器、且一直空闲的兜底上限；轮次在跑时会自动续期 |
+| `/disconnect pause\|continue` | `pause` | 掉线时是否取消当前轮次（见上表） |
+
+**推荐**：留在默认。60s 足够你重连；把它调大只在一种场景下有意义——你确定自己会离开很久、且希望**轮次继续跑完**，那就配 `/disconnect continue`，而不是无限期留住锁。
+
+`DSH_TUI_NO_SESSION_LOCK=1` 会关掉锁，仅用于调试：两个 Host 同时写一个会话日志会互相覆盖。
+
+## 3. 回来后你会看到什么
+
+重连成功时，转录里会多出两行（都是 Host 侧写的，launcher 写不了——屏幕由 TUI 拥有并会立刻重绘）：
+
+```
+已重连 1 次 · 断开 1m
+离开 1m：自动审批 1 次放行 / 1 次拒绝 · 其中 1 次因无人确认被拒 · 1 条提问待回答
+```
+
+- **计数按 Host 计**：新起的 Host 从 1 开始，它确实不知道更早的 Host。
+- **摘要是增量**：只统计这次离开期间发生的事，不重复会话的总量。
+- 只有真发生过的部分才会出现；链路只是抖一下，就只有第一行。
+- 断线期间到达的**未识别审批会被拒绝**并把理由写进转录（模型据此调整）。这是有意的：挂起的轮次会撞上 idle-exit 兜底，最后既没跑完也没人确认。
+
+## 4. 配方
+
+### 4.1 tmux（最省事）
+
+```bash
+tmux new -As dsh            # 有就接入，没有就新建
+# 会话里：
+dsh --profile tui --resume  # 选择器；活着的 Host 优先接入
+# 断开终端：Ctrl-b d        下次 SSH 回来：tmux new -As dsh
+```
+
+tmux 保证的是**终端会话**不断；dsh 保证的是**会话日志与（忙碌时的）Host**不断。两者叠加，链路抖动就不再等于丢进度。
+
+### 4.2 screen
+
+```bash
+screen -S dsh
+dsh --profile tui --resume
+# Ctrl-a d 断开；回来 screen -r dsh
+```
+
+### 4.3 systemd --user：登录即有 tmux
+
+`~/.config/systemd/user/dsh-tui.service`：
+
+```ini
+[Unit]
+Description=Persistent tmux session for the dsh TUI
+After=default.target
+
+[Service]
+Type=forking
+Environment=DSH_HOME=%h/.dsh
+ExecStart=/usr/bin/tmux new-session -d -s dsh 'dsh --profile tui --resume'
+ExecStop=/usr/bin/tmux kill-session -t dsh
+Restart=no
+
+[Install]
+WantedBy=default.target
+```
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now dsh-tui.service
+loginctl enable-linger "$USER"     # 未登录时也保留（按需）
+```
+
+注意：unit 只是把 tmux 会话带起来，**dsh 的断线语义不变**——空闲掉线仍然会退出 Host，`--resume` 从日志恢复。不要把 `Restart=always` 配上：那会在你退出 `/exit` 后不断重开一个会话。
+
+### 4.4 长任务跨休眠 / 跨通勤
+
+```bash
+/disconnect continue           # 掉线不取消当前轮次
+DSH_TUI_IDLE_EXIT_MS=600000 dsh --profile tui --resume
+```
+
+轮次在跑时 `DSH_TUI_DETACHED_IDLE_MS` 会自动续期，空闲后按 `DSH_TUI_IDLE_EXIT_MS` 退出并让锁——把上限设大是为了"回来还能接上"，不是为了让 Host 常驻。
+
+### 4.5 一次性任务：官方 headless
+
+不需要交互、只要最后一条回复时，用官方 `dsh --profile headless "…"`：跑完把最终文本打到 stdout 就退出。思考、工具调用、子代理都在会话日志里，终端上看不到——这正是本 TUI 存在的理由（同一条任务的对照图见 README）。
+
+### 4.6 纯行模式（屏幕阅读器与日志录制）
+
+```bash
+DSH_TUI_LINE_MODE=1 dsh --profile tui --resume      # 每个事件追加若干纯文本行
+DSH_TUI_LINE_MODE=1 ssh host 'dsh --profile tui --resume' | tee session.log
+```
+
+行模式**不画帧**：不进备用屏、不做绝对光标寻址、不用回车原地重绘、不出动画。每个事件按顺序追加一次，
+多行内容（报告、diff、工具输出）按其自身结构展开，因此 `tee`、`script(1)`、屏幕阅读器都能完整读到。
+状态符号（● ⚠ ✖、diff 的 `+`/`-`）仍然保留，语义不依赖颜色。全屏交互（鼠标拖选、卡片展开、
+`/find` 高亮）在行模式下不可用——那是画帧的代价，需要时用普通模式。
+
+## 4.7 让 dsh 自己走网络代理
+
+插件跑在 dsh 进程里，所以"TUI 的网络"就是"dsh 的网络"。Node **不会**自动读 `HTTP_PROXY` /
+`HTTPS_PROXY`：`NODE_USE_ENV_PROXY=1` 单独在 v24.19 上不生效，必须给 Node 传
+**`--use-env-proxy`**（启动包装脚本里加，别用 `NODE_OPTIONS`——那会把模型跑测试、跑工具的
+每个 Node 子进程也一起塞进代理）。
+
+按域名分流用 `NO_PROXY`（后缀匹配，`deepseek.com` 覆盖整域）。国内直连更快、或直连比代理更稳的域名放这里，
+例如：
+
+```bash
+export NO_PROXY="${NO_PROXY:+$NO_PROXY,}deepseek.com,api.deepseek.com,commandcode.ai,api.commandcode.ai"
+exec /path/to/node --use-env-proxy /path/to/@deepseek-ai/dsh/lib/bin.js "$@"
+```
+
+`cli-chat-proxy.grok.com` / `api.x.ai` / `auth.x.ai` **不要**放进 `NO_PROXY`：这台机器上 Grok 直连会被 RST，必须走代理。
+
+容器/沙箱里如果只有代理出口，直连会成片超时——那种"直连失败"是出口的噪音，不能当成
+"某家必须走代理"的证据；判断标准应该是**该域名直连是否稳定**，而不是一次超时。
+`127.0.0.1` / 本机网段务必留在 `NO_PROXY` 里：显示通道虽然走 AF_UNIX，但别把本地流量也绕出去。
+
+## 5. 明确不做（以及为什么）
+
+- **内置 `--daemon` 常驻模式**：Host 不是服务。它是"某个会话的写者"，靠 idle-exit 把写锁交还；把它变成常驻服务会让 Web UI 与其它窗口长期打不开同一会话。
+- **`detachedApproval = pause`（断线时挂起审批等用户回来）**：看似更"尊重用户"，实际会与第 2 节的兜底打架——轮次停在一个没人能确认的审批上，直到 idle-exit 把它带走，结果既没执行也没拒绝。当前行为（拒绝 + 写清理由）让轮次能收尾，模型会在你回来前调整做法。
+- **多窗口同屏 / 只读旁观**：锁语义与收益都未验证，不做。
+
+## 6. 排障入口
+
+- `/diag`：这条会话的通道、锁、Host 身份、判定链（"会接入后台 Host，不要另开第二个窗口"）。
+- `/doctor`：profile 组合、依赖、兼容与 `dsh-scope` 副本数；`/doctor --fix` 修 profile 补丁（写前备份）。
+- 真机验收脚本：`node scripts/tui-probe.mjs`（启动/缩放//diag//doctor//copy error//preset/鼠标模式/退出）、
+  `node scripts/tui-drop-probe.mjs`（杀掉窗口再接管，断言转录保留、可输入、无乱码）与
+  `node scripts/tui-mock-probe.mjs`（**合成临时 profile + 脚本化模型**，跑一个真实轮次后验证"拖选复制"
+  与 `/find` 高亮；不碰你的 profile、不花额度）、同一脚本的 `--busy`（**忙碌断线**：轮次在飞时杀掉窗口，
+  断言 Host 仍持有会话、重连窗口打出「已重连 N 次」）；`node scripts/verify-batch.mjs --batch <批>` 一次跑完全部证据。