# @hyzyn/dsh-docker 路线图（待办）

> **本文只放「还没做的事」；「已经发生的事」在 [DEFECTS.md](./DEFECTS.md)。**
> 已完成的待办就地打勾并回填「落点 + 门槛」（保留在列表里，便于追溯当初的验收口径）。
> 从 DEFECTS.md 的「待办 / 路线图」一节原样拆出（2026-09-25），**没有删减任何一条**。
> 缺陷仍按 `Dxx` 编号记在 DEFECTS.md 的索引表里；本文每一项在动手前先转成可验收条目
> （做完回填「落点 + 门槛」），不要只停留在规划里。

## 待办（3 项，其中 2 项已完成）

> 下面都是**规划**，不是缺陷：单人项目不另开 Issue，待办记在这里，做完打勾。
> 新发现的缺陷接着编号记进 [DEFECTS.md](./DEFECTS.md) 的索引表（加一行），不在本文展开。
>
> **2026-09-25 分档**：原有 8 项里 5 项**要同时改 ≥2 个包**（跳板机、统一安全围栏、变更端点的信任模型、
> `isConcurrencySafe`、面板端 i18n），已按 [docs/conventions.md 的边界判据](../../docs/conventions.md#l0--l1-的边界判据)
> 上提到项目级 [ROADMAP.md](../../ROADMAP.md)，**原文在那里逐字保留**。本文只留「改 docker 一个包就能做完」的 3 项。

- **agent 侧的网络 / 卷变更工具** —— 面板有 `networks/remove|prune`、`volumes/remove|prune` 的按钮，
  agent 侧一个都没有（当前是有意为之：这类删除最容易误伤）。若要做，必须与面板**同一把** `allowMutations`
  闸门 + 破坏性后果复述。
- [x] **日志真虚拟滚动** —— **2026-09-29 完成（D152）**。落点：`client-src/log-window.js`（实测行高
  缓存 + 前缀和 + 窗口定位 + 锚点修正的纯逻辑）、`client-src/index.js` 的 `useLogRows`（两个日志视图
  共用，量高 / 锚点修正 / 贴底钉住都在绘制前的 layout effect 里一次做完）、`.dk_logPad` 上下垫高。
  门槛（`scripts/log-perf.mjs`，改前 → 改后实测）：持续洪泛 20k 行/秒 × 6s 最大延迟 70~97ms →
  **6ms**、>50ms 长帧 25~26 → **0**、正文 DOM 节点 ~10000 → **213**；突发 20k 行最大延迟 52~97ms →
  **2ms**；新增两条**正确性**断言（滚到顶第一行必须是 `seq=0`、滚到底最后一行必须是 `seq=4999`、
  洪泛结束后最后一行必须是最新行）。约束（都守住了）：`content-visibility` 不开（D91）、虚拟化用
  **实测**行高缓存撑垫高、右键「问 Agent」的前后 20 行上下文由 `overscan ≥ 20` 保住（有断言）、
  导出走数据层不受影响。细节与取舍见 [DEFECTS.md](./DEFECTS.md) 的 D152。
- [x] **跨目标聚合的取消语义** —— **2026-10-06 完成（D161）**。原先 45s 超时只
  `Promise.race`、不取消底层命令：外层拿到 `ok:false` 时那条 SSH channel 还在跑，仍占着
  `MaxSessions` 的会话槽（sshd 在子进程活着时不释放，见 D150），于是这台慢机器上的后续
  短命令被远端拒绝。落点：`src/docker.ts` 的 `Runner.run` 新增**可选** `signal` +
  `createRunner()` 的 local / ssh **两个分支都透传**；`src/ssh-exec.ts` 的 `ExecOptions.signal`
  与 `RemoteExec.run` / `runLocal` 的 abort 收尾（各自**并入已有的那一条**收尾路径——SSH 是
  `signal('KILL')` + `close()` + `finish(null)`，本地是 `SIGKILL` + 复用 D159 的 `KILL_GRACE_MS`
  收敛期）；`src/index.ts` 的 `aggregateAcrossTargets`（AbortController 建在 `run()` 之前、
  超时先 `abort()` 再 `reject`、`finally` 兜底 `abort()`）。
  预算取舍：**内层每命令超时是唯一真相源，外层只做兜底**（`attention` 最坏 = 1 条 ps +
  最多 9 批 inspect，10 × 30s ≈ 300s，按「大于单目标最坏序列」设会把总览拖到五分钟），
  外层取 3 × 单条预算 = 90s，
  `DSH_DOCKER_AGG_TIMEOUT_MS` 可覆盖（仅测试 / 排障）。返回契约不变：超时只污染自己那一格。
  门槛：`test/aggregate-cancel.test.ts` **16 条**（假 channel / 假 ChildProcess / 假宿主三套桩）——
  **判据是「abort 后底层真的收到取消」而不是「返回了 ok:false」**：SSH 断言 `channel.signal('KILL')`
  与 `close()` 被调用、`inflight` 归零、闸门名额归还；本地断言子进程 `kill('SIGKILL')`、
  D159 收敛期仍在 500ms 内落定、已 abort 不再 spawn；端到端断言超时那一格被 SIGKILL 而
  正常那格不被杀。
  **判别性已实测**：去掉超时分支的 `controller.abort()` → 3 条红；摘掉 `createRunner` 的
  signal 透传 → 5 条红。
  > ⚠️ **与 `feat/dev-data-suite` 分支有重叠**：那份 `src/index.ts` 改的是同一片区域
  > （它那边 `AGG_TIMEOUT_MS` 在约 1010 行、`aggregateAcrossTargets` 在约 1037 行），且两边
  > 已双向分叉——将来合并大概率要在这里解冲突，别再把它当回归查。

**2026-09-25 追加**：能力开关的信任模型按项目级 ROADMAP 第 5.1 节落地——`allowMutations` /
`allowExec` 的**提权只认宿主侧环境变量**（启动时采样一次），HTTP 只能关不能开；未授权时卡片里
那两个开关点不动 + 附一行说明。落点：`normalizeConfig` 折叠出有效值（二十多处使用点一处都不用
改）、`/config` 写盘前 400、快照新增 `allowMutationsGranted` / `allowExecGranted`。

**2026-10-05 追加**（用户反馈「直接连接本机不方便」）——**一键连接本机**，已落地：
**只在「还没有配置 Docker 目标」的空态**里一个**连接本机**按钮，agent 侧同一条操作是
`docker_connect_local`。落点：宿主 `connectLocal()`（面板按钮 / `POST /connect-local` /
工具三条入口共用同一份实现）、纯函数 `nextLocalTargetName` / `findLocalTargetName` /
`describeLocalProbeFailure`、客户端 `api.connectLocal` + 空态按钮节点、宿主
`/connect-local` 路由（写路径，受同源证明）。
门槛：`test/connect-local.test.ts` 23 条（命名确定性 / 复用不重复创建 / SSH 与自定义目标原样保留 /
空 `targets` 无隐式默认目标 / 设置不可用 503、保存失败 500 且**不改内存配置** / 连点与并发幂等 /
daemon 未启动与 CLI 缺失的成因文案 / 工具-路由同一实现）、`scripts/route-smoke.mjs` 四个端到端用例、
`scripts/client-smoke.mjs` 三条（**已配目标时工具条不得出现**（反向判据）、HTTP 接线、空态里可点）。

**同日回修 ①（用户看着截图说「这个连接本机有点多余」）**：第一版把按钮**常驻在工具条**
（目标选择器右侧），并且在没有本机目标时用强调色渲染——已有 `目标2 · root@…` 这类可用目标时，
它既占掉选择器右边最值钱的位置，又一直喊人点，属于纯噪音。而且**当时的用例把它钉死了**
（`client-smoke` 断言「工具条里应恰有一个连接本机入口」）——错的不是漏测，是测了错的行为。
改法：工具条**不挂**该按钮，只在 `target === ''` 的空态渲染；随之删掉 `data-fresh` 强调样式、
i18n 死键 `btn.connectLocalCurrent` 与客户端那份 `localTargetName`（复用判定本就只属于宿主的写路径）。
断言方向反过来：**有目标时必须不出现**。

**同日回修 ②（用户接着问「现在我怎么看到本机的容器」）**：回修 ① **改过头了**——撤掉工具条入口后，
「手上几台 SSH、想再加一台本机」这种常见情况就只剩「开设置卡片手配」，正好退回这次改动原本要
消灭的那条路（用户最初的原话就是「直接连接本机还不是很方便」）。空态那个入口只覆盖「一个目标
都没有」，覆盖不到这一种。现在补**第二个非常驻入口**：目标下拉的**末一项** `+ 连接本机`——
入口放在「用户找机器」的地方，点开下拉才出现，不占任何常驻位置。两处**互斥**（没有目标时走
空态那个大按钮，下拉里不再重复列），**已有本机目标时两处都不出现**。

门槛（回修 ②）：`shouldOfferConnectLocal(targets)` 抽成**纯函数**再驱动——离线冒烟的 React 桩把
`useState` 冻在初值上（组件里 `targets` 恒为 `[]`），遍历渲染树根本走不到那一项；这也是这一版
先把判定抽出来的原因。哨兵值用 **NUL 前缀**（`'\0connect-local'`）：目标名是用户自由填的，
普通字符串哨兵可能与真实目标重名——那样点「连接本机」会切到**别的机器**。用例另有一条源码级
判据钉住「哨兵分支必须排在 `setTarget(event.target.value)` **之前**」，否则当前目标会被换成一个
不存在的名字。真机复验（隔离宿主 + 真 Chrome）：3 台 SSH 时下拉末项为 `+ 连接本机`，选中后
变成 `local · 本机` 且该项消失。
边界（刻意不做，已写进 README）：不改空 `targets` / `clearTargets` 的既有语义、不凭空造隐式默认
目标、不自动装 Docker / 起 daemon / 切 docker context / 改环境变量、**不放开任何能力授权**
（只写插件自己的配置 + 只读探测）。

**同日回修 ③（用户对着「docker CLI = docker」那张截图问「是否需要先检测本机是否有 docker
或者 pdman」）**：探测本来就有，但有两处把话说死/说空，记在 [DEFECTS.md](./DEFECTS.md) 的 D159：
① `probe()` 不认超时——`docker version` 挂住时 `code` 是 `null`，兜底文案「退出码 null」零信息量，
而超时（daemon 卡死 / `docker context` 指向连不上的远端）与「daemon 没起」的可修动作完全不同；
② 探测只认 `dockerBin` 一个二进制，只有 podman 的机器上收到的是「请先安装 Docker」。
改法：超时单独一档（`ProbeResult.timedOut` + 一句可执行的话）；`PATH` 里只读地找候选 CLI
（`docker` → `podman` → `nerdctl`）并**点名**它，但**绝不替用户改写 `dockerBin`**——静默改配置
违背本插件「不替用户决定」的一贯取向，且 podman 与本插件输出格式的兼容性未逐项验证。
超时还顺带修了实测出来的放大器：只杀直接子进程时，包装脚本的孙进程握着管道会把 15s 上限
拖成分钟级（真机 3s→60.3s）。

门槛（回修 ③）：`isLocalCliMissing` 当**单一来源**（文案分档与「要不要找候选」共用，两处各写
一遍正则会漂移）；候选比对按 **basename**——按原字符串比会在 `dockerBin=/usr/local/bin/docker`
时给出「把 docker 改成 docker」的废话（这条已被用例钉住，且实测判别性）；「只在 CLI 缺失那档
才 accessSync」（其余档位纯文本判断，不必白跑文件系统）。用例用临时目录造**隔离 PATH + 可执行
位**，不依赖跑测试的机器恰好装了什么。路由级用例断言 `dockerBin` **未被改写**。
**判别性已实测**：移除 `probe()` 的超时分支 → `streams.test.ts` 对应断言失败；把 basename 退回
原字符串比对 → `connect-local.test.ts` 那条失败；断开 `localProbeReason` 的候选接线 → 路由级
那条失败（旧代码报的是「找不到 docker CLI」而拿不到「装了 podman」）。

**同日回修 ④（用户看着「活动 · 事件流已断开」的截图问「刷新无法重连断开的事件流吗」）**：
答对了，⟳ **救不活**。事件流进 `closed` 是终止态（`docker events` 退出 / 服务端发 `end` 都会
`close()`），而 `refresh()` 只刷列表 + 自增 `refreshToken`——那个令牌根本没进事件流 effect 的依赖
（`[active, view, target]`），它只被详情抽屉的三个 effect 消费。所以当时只有刷新整个页面或切页 /
切目标能恢复。记在 [DEFECTS.md](./DEFECTS.md) 的 D160。改法：新增自增的重连令牌并进依赖；
活动条断开时给一个 **重连** 按钮（`closed` 才有；`unsupported` 不给——重连必然再失败）；⟳ 走
新的 `refreshManually()`（刷列表 + 重连），而 **AUTO REFRESH 轮询仍只调 `refresh()`**——塞进轮询
会让终止态被不断重开，既掩盖「它断了」又白建 SSE。

门槛（回修 ④）：`canReconnectEvents` 抽**纯函数**（离线冒烟的 React 桩把 `useState` 冻在初值，
组件里 `eventsStatus` 恒为 `''`，判定必须能直接驱动）；重连按钮必须是折叠头的**兄弟**——那层
已经是 `<button>`，按钮里嵌按钮既非法 HTML 也让读屏把「折叠」「重连」听成一个动作（用例同时
断言「不在折叠头的 children 里」）；补偿判据是 `opened || manualReconnect`，只按 `opened` 会漏掉
「daemon 全程没起、流从未 open 过」——那时重连成功却不刷列表，活动条绿了而列表还停在错误态。
**判别性已实测**：移除依赖里的令牌 / 把重连按钮挪进折叠头 / 退回只按 `opened` 判，三条用例分别红。

## 已完成（落点 + 门槛）

### ✅ 诊断历史：把「一次诊断」变成「趋势判断」（2026-11-03 完成）

**动机**：单次诊断只回答「现在怎么样」。**缓慢变坏**（内存一点点涨、重启越来越频繁、报错逐渐变多）
在单次结果里根本看不出来——而这正是「容器还能撑几天」这类问题的真实形状。所以把每次诊断落成样本，
让它变成一条时间序列 + 一组判据。

**落点**

- `src/history.ts`（新，纯逻辑零 IO）：`DiagnosisSample` 压缩、30 秒去重判据、per-container / 整文件
  两级配额、`historyTrend()` 七条判据（restart-growth / oom-recurring / memory-creep / error-growth /
  new-serious-findings / severity-creep / stable）+ `insufficient`；时钟由调用方注入（文件里 0 处
  `Date.now()`，与 `diagnose.ts` 同一口径）。
- `src/history-store.ts`（新，薄 IO）：`diagnosisHistoryPaths()` 是**唯一**拼路径处
  （`<DSH home>/dsh-docker/diagnosis-history.jsonl`，目录 0700 / 文件 0600，`DSH_DOCKER_HISTORY_DIR` 可覆写）；
  追加 = 读全文 → 去重/裁剪 → 超限才**原子重写**（临时文件 + rename）；坏行 / 半行 / 未知 `v` 一律跳过。
- `src/index.ts`：`/diagnose` 与 `docker_diagnose` 各加一个 `history?` 参数（0~50，默认 10，越界夹紧），
  响应与工具输出加 `history:{samples, trend, recorded}`。**没有新增工具**——历史不是新的采集面，
  只是同一份诊断的第二种视图（与 `logs` / `logs_grep` 那种「预算模型不同才拆」不是一回事）。
  写盘失败只降级（`recorded=false` + stdout 一行），绝不拖垮诊断本身。
- `client-src/index.js`：诊断页在**结论卡之后、「发现」之前**加「历史」块——严重度色带（hover 给时间与
  code）、趋势句（`aggravating` 走既有 warning 视觉）、只列真变化的数字行、判据「新出现 / 已消失」两行、
  样本 <2 的空态、底部一句「历史只记结论与数字，不存日志原文」。`recorded` 做成**三态**
  （`true` / `false` / 字段缺失）——缺字段时**不猜**，否则老宿主会被说成「本次与上次一致」。

**隐私边界（这是本轮的硬取舍）**：样本**只存结论与数字**，**绝不落盘**日志原文与 finding 的 detail
（detail 里会嵌日志行，可能带凭证）。代价写进 README：那份文件不能用来回放排障现场。

**刻意不做**：历史不按时间自动采样（只在「有人诊断」时落点——后台定时诊断要给每个目标跑四条命令，
在 SSH 上就是定时烧通道，且没人看的时候它在写盘）；不做跨容器/跨目标的历史聚合（趋势是「这个容器
在不在变坏」，聚合会让判据互相污染）；不给文件加锁（丢一次更新的代价远小于加锁的复杂度与死锁面）；
不加 `history.*` i18n 域（那是按特性开域，与既有**语义域**白名单口径不一致）。

**门槛**：单测 **+49**（history 40 + 噪声闸与归一 9；包内 31 files / **630** 例）；
`route-smoke` **86/86**（84 → 86，含「两次调用第二次被去重」与 `history:0` 不返回样本）；
`client-smoke` **120/120**（113 → 120）；`client-lint` 十六条全过；全仓 `pnpm -r typecheck` 与
`vitest run` 全绿。**判别性已实测**：去掉 30 秒窗口（2 条红）、把 `logTail` 塞进样本（1 条红）、
关掉每容器配额（1 条红）、去掉噪声闸（4 条红）、去掉归一（4 条红）、客户端去掉 `data-aggravating`
（1 条红）、未知指标回落字段名（1 条红）、去重提示无条件显示（1 条红）。

**真机实测（2026-11-03，隔离 profile 副本 + 真宿主 + 真 SSH 目标 + 真 Chrome）**：
① 首调 `/diagnose` → `samples=1, recorded=true`；② **立刻再调 → `recorded=false`**（30 秒去重真的生效）；
③ 32 秒后 → `samples=2, recorded=true`；④ 面板「诊断」页色带 3 格、`title` 为本地时间 + code、
趋势句为「容器状态没有明显变化」、数字行为「报错行数 22 → 21」；⑤ 落盘文件 `0600`、内含 0 处日志关键词
（隐私自证：`grep ERROR|Exception` 命中 0）。

**真机数据反过来改了实现**（本轮最有价值的一处）：第一次真机跑出来的 `trend.numbers` 是
`{"key":"cpuPercent","from":1.11,"to":1.09,"delta":-0.020000000000000018}` ——**瞬时采样噪声**进了趋势，
还带着浮点尾巴。于是补了两条：① 每个指标的**最小有意义变化**（重启 ≥1 / 内存 ≥1 个百分点 /
CPU ≥5 个百分点 / 报错 ≥3 行 / 事件 ≥5 / 日志行数 ≥50）；② 输出前**归一**（百分比 1 位小数、计数取整，
delta 由归一后的值相减再归一）。第二轮真机再验：CPU 噪声消失；又发现「报错行数 22 → 21」仍是
**滑动窗口漂移**（一条老报错滑出去就 −1），把 `errorLines` 阈值从 1 提到 3 才收口。
——这三步都不是设计阶段想得到的，是**真数据**逼出来的。

**一处与契约的偏离（已报备）**：工具侧样本的 `null` 字段是「省略」而不是 `null`——`defineTool` 的输出
schema 没有 null 类型，写 null 会让宿主校验挡掉**整条**结果（`toToolEvidence` 的注释里记着同一个坑）；
HTTP 侧仍是 `null`（JSON 无此限制），两处各有断言。

**发版前复查（2026-11-03，真宿主 + 真 docker 目标 + 真 Chrome）抓到第二处（D169）**：同一容器连续
3 次诊断严重度都是 `critical`、findings 与数字全都没变，趋势却判 `severity-creep`、界面写「连续 3 次
诊断的结论在变严重」——判据 6 只要求「非降」，平手也满足单调。README 写的是「严重度连续走高」，
判据以它为准：改成**较窗口起点严格走高**（`[warning, critical, critical]` 仍算，三次平手不算），
补平手反例 2 条（包内 31 files / **633** 例）。判别性已实测：把 `rose` 判据去掉，这两条立刻红。

### ✅ 排障闭环 + 存储治理：诊断单、进程快照、磁盘与「谁在用」、等价 `docker run`（2026-11-02 完成）

**动机**：能力面已经齐了（14 只读 + 5 变更、7 个视图、四条 SSE），但缺的是**把数据变成判断**的那一层——
`attention` 只给 `reasons` 列表，用户仍得自己把 inspect + logs + events 拼起来；`ContainerDetail` 里
`exitCode / oomKilled / restartCount / healthLogTail` 全都采到了，只差判据。另一块空白是**存储治理**：
全仓 0 处 `system df`，镜像 / 卷没有「谁在用我」，只能靠 `rm` 失败后看报错（真机盘点：镜像 2.0GB /
可回收 1.1GB，SSH 目标上可回收 **159GB**）。

**落点**

- `src/diagnose.ts`（新，纯函数零 IO）：15 条判据表（OOM / 非零退出 / 反复重启 / 不健康 / 健康检查未通过 /
  正常退出 / 未运行 / 内存压力 / CPU 压力 / 日志报错 / 无健康检查 + 三条 `*-unavailable`）、
  `containerStatusText()` 复刻 docker 的 ps 风格状态串（`Up 4 hours (healthy)`）、`buildTimeline()`。
  时钟由调用方注入（`nowMs`），模块不读时钟。
- `src/docker.ts`：`top()`（`-eo` 八列，表头驱动解析）、`diagnose()`（inspect 先跑，日志 / 事件 / 统计三路
  并发且**任一失败只降级**）、`systemDf()`（汇总与明细两条命令两份预算）、`recreate()`；
  `events()` 新增可选 `container` 过滤（既有调用点 argv 逐字不变）。
- `src/recreate.ts`（新，纯模块零 IO）：从 inspect **原始行**反推等价 `docker run`；`omittedArgs()` 是
  「故意没还原」的唯一出口；敏感键名只进 `secretKeys`，**值不改写**。
- `src/index.ts`：四条只读工具（`docker_diagnose` / `docker_top` / `docker_disk_usage` / `docker_run_command`，
  17 只读 / 22 总数）+ 四条路由（`/diagnose` `/top` `/system-df` `/run-command`）+ `toToolEvidence` /
  render；引用白名单与 `assertSince` 都放在**路由层的 400 段**（D37 / D45 同口径，别让客户端错误落成 500）。
- `client-src/index.js`：容器详情五页签（新增「诊断」「进程」）、磁盘视图（第六段）、概览底部可折叠的
  等价 `docker run`；i18n 67 键 × 2 语言（**语义域**，不新开 `diag.*` —— 扩 `KEY_DOMAINS` 要给
  `scripts/check-i18n.mjs` 与 `docs/i18n.md` 同时加行，为两个特性不值得）；`formatCollectedAt()` 让
  **界面显示本地时间、投递文本仍是 ISO**。

**刻意不做**：agent 侧网络 / 卷删除（ROADMAP 待办第 1 项，那扩大的是破坏面，不是亮点）；镜像 build /
push / save（要目标机文件上下文，违背只读定位）；容器内文件浏览（要写临时文件 + SSH 拉取，成本与安全面
都不划算）；磁盘页的 prune 入口（逐行删除 + 确认框更安全，prune 已在镜像 / 卷页各有一个）；
`--filter event=`（9 个动作要拼 9 个 filter，漏一个就静默丢事件，换 3 倍字节不划算）。

**门槛**：单测 **+126**（diagnose 58 / top 18 / recreate 35 / disk-usage 15；包内 30 files / **581** 例）；
`route-smoke` **84/84**（79 → 84，含 5 条端到端）；`client-smoke` **113/113**（104 → 113）；
`client-lint` 十六条全过；全仓 `pnpm -r typecheck` 与 `vitest run`（3982 例）全绿。
**判别性已实测**（每条都真红过再改回）：去掉 `--filter container`（2 条红）、改内存压力阈值（1 条红）、
去掉明细排序（2 条红）、去掉敏感键名识别（2 条红 + route-smoke 82/84）、去掉客户端排序（冒烟 1 条红）、
把「点开才请求」退成「只看 open」（冒烟 1 条红）、删掉投递文本里的「目标」行（冒烟 1 条红）。
**真机验收**（隔离 profile 副本 + 真宿主 + 真 Chrome，SSH 目标 `root@…:22`）：五页签 `概览 | 日志 | 统计 |
诊断 | 进程`；诊断页出结论卡（真实命中「日志里有 31 行疑似报错」）+ 三个折叠块 + 三个动作；结论卡时间
为本地 `2026-11-02 23:39:32`；进程表 8 列有真实行；磁盘视图四卡 + 合计可回收 **159 GB** + 镜像 / 卷明细
（按独占降序、`未使用` 徽标、截断提示）；「等价 docker run」展开后真的取到命令且带「复制命令」。
15 项断言 15 通过（其中一条是我驱动脚本的正则转义写错，产品侧无误）。

### ✅ 活动条不再假绿：宿主发 `ready`，客户端只认它（D166 / D167，2026-10-11 完成）

**现场甲（D166）**：用户拿着一张面板截图问「重连中的文案不对」——切目标 / 重连期间活动条已经是
**绿点 +「实时接收中（docker events）」**，而正文还停在「读取中…」。查下去不是文案问题：
`openSseStream` 先 `writeHead(200) + flushHeaders()`、**再**去起 `docker events`，浏览器收到响应头
就 `onopen`，而旧客户端在 `onopen` 里直接置 `open`。「连上了」与「在收数据」是两件事。**实测**
（黑洞地址 `192.0.2.1` + 真 Chrome）：响应头 0.027s、`error` 20.03s、同窗口 `onopen` 41ms 且
`readyState=1`、一帧数据都没有——旧代码这 20 秒全程绿。改法：`StreamHandlers.onStart`（本机 `spawn` /
远端 `openChannel`）+ 四条 SSE 路由发一帧 `ready{}`，客户端四条流的「已就绪」只认它（详见
[DEFECTS.md](./DEFECTS.md) D166）。

**现场乙（D167，本插件自己引入的回归）**：用户接着在 test profile 实测「切换到新的目标并连接后依然
显示连接中」——卡片已经列出容器，活动条永远在「正在连接事件流…」。线级实测那台宿主：`/config` 里
**没有 `streamProtocol`**、`events/stream` 8s 内**一帧都没有** ⇒ **宿主进程还是改动前的旧模块，而浏览器
每次刷新都读到新的 `client.js`**：旧宿主从不发 `ready`，新客户端死等。改法：版本协商
（`/config.streamProtocol`）+ 每条流一条「真实数据帧」兜底 + config 晚到时只补一次重开。

**门槛（两条一起）**：`test/streams.test.ts` 5 例 + `test/logs-stream.test.ts` 1 例 + `route-smoke` 四条流
各一条「首帧必须是 `ready`」+ `client-smoke` 两条接线判据（含四个纯函数态与「旧宿主不许卡死」）。
**判别性已实测**：摘掉任一路由的 `onStart` → 对应用例红；拆掉四条兜底与协议字段 →
`route-smoke` 71/72、`client-smoke` 92/94。**真机双向复核**（隔离宿主 + 真 Chrome，用户真实配置全程只读）：
① 仿真旧宿主包（打包产物上去掉 `ready`/`streamProtocol`，客户端保持新版，形状与用户那台一致）+ 可用
目标 → 立即绿；② 现代宿主 + 黑洞目标 → 黄「正在连接事件流…」(0ms) → 红「事件流已断开」(4.6s)，
全程无绿。

**给后人的一句**：真机复现这类问题要**同时看两侧版本**——「宿主有没有发这帧」与「浏览器跑的是哪版
`client.js`」是两件事，只差一侧就会出现本文这种「看着像产品缺陷、其实是开发档错位」的现象。

### ✅ docker_logs_grep：日志服务端检索 + `--until` 时间窗（2026-10-09 完成）

**现场**：`docker_logs` 是「取尾工具」不是「检索工具」——三个结构性缺口都在代码里：
① 没有服务端过滤参数（面板的「过滤日志」在前端、发生在「输出上限（KB）」截断**之后**，
大日志里深处的报错永远搜不到）；② 只有 `--since` 没有 `--until`，圈不出「凌晨 2:00~2:15
事故窗口」；③ `tail` 硬上限 5000 行，话痨容器只覆盖最近几十秒。

**为什么不把 `filter` 塞进 `docker_logs`**（决策记档）：两者预算模型不同——`logs` 是
「返回 = 收到」（keepTail 丢旧留新），grep 是「扫得多、返回少」，混在一个工具里同一个
参数要当两种闸用、返回形状表达不了「扫了 40 万行命中 3 行」，条件化 schema 还会诱发
模型误用。**同领域、不同语义 = 不同工具**（与 ps/attention、快照/FOLLOW 流的既有分法一致）。

**落点**：
- `src/docker.ts`——`LogsOptions.until`（与 `since` 同一构造点 `logsArgv`，`tailOverride`
  参数供 grep 传 `all`）；`logsGrep()`：**宿主侧逐行过滤，不碰远端 shell**（绝不拼
  `| grep`——违反「argv 构造」铁律，且 SSH 路径转义面完全不同）；默认字面子串
  （grep -F 语义，零 ReDoS），`regexp:true` 才按 JS 正则、pattern ≤512 字符；上下文
  窗口合并去重（相邻命中共享行只输出一份）；**扫描预算与返回预算分离**（扫描侧
  8~32MB、60s 档、keepTail；返回侧 limit × context 夹住），`truncated`（扫描溢出，
  窗口偏新）与 `limited`（命中超上限）两个独立信号位；`matched` 如实报全量命中即使
  没返回。
- `src/index.ts`——`docker_logs_grep` 工具（恒注册、只读档 `read`、`isConcurrencySafe`）；
  `docker_logs` 加 `until` 参数（`assertSince(v,'until')` 同口径校验，D45）；能力公告
  写明两工具分工（「尾部看不到成因就 grep」），推荐排障顺序同步。

**刻意不做**：这一轮只做 **agent 工具层**——不加 `/logs/grep` HTTP 路由、面板日志页维持
前端过滤（面板有人眼看，工具没有「扫过一遍再人眼挑」的路）；不做跨容器 grep（聚合是
面板的事）；不加远端 `grep`（安全铁律）；stderr/stdout 编号沿用 `logs()` 的
「两段拼接」语义（D44），不假装真实到达序。

**门槛**：`test/logs-grep.test.ts` 17 条（argv 逐字：`--tail all` 缺省 / 数字夹紧 /
timestamps 默认开 / since+until 透传；参数校验：pattern 必填 / 512 上限 / 无效正则点名 /
字面模式不误伤 `[`；匹配内核：大小写 / ignoreCase 高亮取原文 / 正则 match[0]；返回契约：
±context 边界不越界 / 窗口合并去重 / `limit` 截返回但 `matched` 报全量 / `truncated` 与
`limited` 各自独立 / out-err 分段编号 / docker 报错走 assertOk）；`logs()` 的 `--until`
正反两条（不传时 argv 与旧行为逐字一致）。`scripts/route-smoke.mjs`：挂载与
`toolsRegistered` 两处清单进 13 只读、重启用清单进 grep、render 冒烟进 grep、新增端到端
一条（假 CLI：out/err 各一行命中、0 命中可渲染不抛、非法 since/until 同口径报错）。
`test/tool-concurrency.test.ts` 守卫如期变红并把 grep 归进只读侧（**反向验证了这张表
确实在拦新增工具**）。全仓 `pnpm --filter @hyzyn/dsh-docker typecheck && smoke`、
`pnpm vitest run packages/docker/test` 全绿。

**真机验收补正（2026-10-09，同轮）**：真 daemon 复验 10.7MB / 30 万行日志时发现 `lines` 的
**第一行是半行**——`keepTail` 按**字节**保留尾部，切口落在行中间，于是窗口开头是
`"g line 174798"`（`…padding line 174798` 的尾巴），没有时间戳、内容从中途开始，会以噪音
形式进模型上下文，看起来像「检索结果里有脏行」。落点：`ExecOptions.lineAlign`（**opt-in**，
只对 `keepTail` 有意义）→ `ByteSink.decode()` 丢掉首个不完整行（切口正好落在换行上时只丢
那个换行、整行保住；窗口内连一个换行都没有则整段都是碎片，只能全丢）；`logsGrep()` 传
`lineAlign: true`。刻意**不改** `keepTail` 自身的契约：D14/D123 的逐字断言（`xxxxTAIL`）是
prune / pull / 面板日志尾部共同依赖的「按字节保留尾部」，所以对齐做成开关而不是改语义；顺手
把 `Runner.run` 与 `createRunner` 的 `withSignal` 里各写一份的选项字面量收成具名类型 `RunnerRunOptions`
（`lineAlign` 先只加在一份上，是 tsc 在对象字面量处报出来的）。门槛：`ssh-connect.test.ts`
两条行为用例（反例：不传 `lineAlign` 仍逐字节保留尾部，即 D14/D123 契约未动；边界：切口
正好落在换行上时整行保住、窗口内无换行则整段全丢、未截断时完全不动输出）+
`logs-grep.test.ts` 的接线钉子（grep 路径确实开了这个开关；本节上方的「17 条」是当时基线，
补正后 18 条）。真机复验：同一容器重跑，首行恢复为带时间戳的完整行，`scanned` 由 125204
→ 125203 —— 少掉的正是那半行。

**后续可选**（未立项，遇到再说）：面板日志页要「先扫全量再挑」时补 `/logs/grep` 路由；
正则灾难性回溯的显式超时护栏（当前靠 60s 命令级超时兜底）。

### ✅ 就地提权：两个能力一次粘贴全部解锁（2026-10-07 完成）

**现场**：就地提权是**逐能力**的（`allowMutations` / `allowExec` 各有自己的 challenge），而客户端的
`elevation` 是**单槽** state（`setElevation({ capability })`）——面板开着时再点另一个开关，前一个
能力的面板被**替换**、它的命令从界面消失（宿主侧 challenge 仍在 pending，`begin` 幂等、不耗额度）。
2026-09-26 的设置卡片截图实测：两次授权时刻差 14 秒，用户必须在宿主终端**粘贴两次**。纯客户端
可解的高频摩擦点。

**落点**：新增 `client-src/elevation.js`（纯逻辑：逐能力记录的增改 / 留痕 / 收尾，取哪几条命令、
按什么顺序、怎么连接）；`client-src/index.js` 的 `elevation` 单槽 → **逐能力数组**（按发起顺序），
`elevationPanelsView`（factory 级**纯渲染函数**，入参是纯数据 + 回调，与 `overviewBody` 同形）
渲染纵向堆叠的多块面板，组顶部在「≥2 个能力拿到过命令且有可复制命令」时出一个「复制全部（N 条）」；
轮询 effect 从单能力改为**轮询全部 pending 能力**（某个 granted → 走既有 `finishElevation(cap)`，
该块面板消失）；`copied` 反馈逐能力隔离（合并按钮用 `'__all__'` 哨兵键）；`docker.css` 加
`dk_elevPanels` / `dk_elevMerge` 两条最小间距规则；i18n 新增 `elev.copyAll` / `elev.copyAllHint` /
`elev.copyAllCopied`（zh + en 齐平）。

**合并命令的连接方式是换行符，刻意不用 `&&` / `;`**：bash / zsh / PowerShell / cmd 粘贴多行都
逐行执行，平台无关；`&&` 在 PowerShell 5.1 上不认、`;` 在 cmd 上不认。文案只说「执行后全部开关
自动解锁」，**不承诺同一时刻**——两个 challenge 的 TTL 与探测周期各自独立，倒计时仍逐面板显示。

**已授权的那条记录只「留痕」不立刻删**：合并按钮的存续跟着「这一组里点过几个能力」，不是跟着
「当前还有几条命令」——两个都点过、其中一个先解锁是常态，此时按钮要留着把**剩下那条**交给用户；
全都解锁后留痕由 `pruneElevationRecords` 收掉、按钮自然消失；只点过一个时压根不出按钮（那条命令
就在自己的面板里）。过期的命令从合并里剔掉（复制过去只会让宿主落一个过期后才出现的文件）。

**边界（明确不做）**：不改 kit、不改 `/elevate` 任何路由与响应形状、不碰 nonce / 日志 / 限流语义
（`begin` 幂等、`status` 不回 nonce、TTL 与每小时 3 次全原样）；不做跨插件合并（docker 与 tty 的
challenge 在不同插件进程）；「重新生成」仍逐能力。「kit 侧 `begin` 返回合并命令」这条备选**已否**：
`finishElevation` 只处理被轮询到的那个能力，另一个会停在「宿主已授权、配置开关没开」的半状态，
还要处理两条独立探测定时器的授权竞态——客户端合并零 API 变更、零新安全面。

**门槛**：`test/elevation.test.ts` 27 条（增改不替换 / 原地替换不重排 / 留痕与收尾 / 发起顺序不是
字典序 / 过期与边界 / 换行连接逐字节且不含 `&&` 与 `;` / 按钮出与不出的六种组合 / 参与计数口径）；
`scripts/client-smoke.mjs` 新增 7 条**渲染树级**用例（两个 pending → 驱动合并按钮的 onClick，
断言交下去的字符串逐字节等于两条命令的换行连接、顺序 = 发起顺序、反馈键与单条隔离；单个 pending
无按钮；一个 granted 后按钮只剩一条且已授权的面板消失、全部 granted 后整组清空；过期的不进合并；
✕ 只关一个；一条出错 / 在途不影响另一条；i18n 双份 + 产物钩子）。
**判别性已实测**（三条反证各自红）：把连接符换成 `&&` → 冒烟 1 条 + 单测 3 条红；把按钮门槛从
「≥2 个拿到过命令」放宽到 ≥1 → 冒烟 3 条红；让已授权的留痕不参与计数 → 冒烟 2 条红。

### ✅ 能力使用审计（capability-use）：把「授权了」和「用了」接成闭环（2026-10-07 完成）

**落点**：新增 `src/audit.ts`（行格式 + `sanitizeAuditValue` 的统一 200 截断与控制字符转义 +
`audited` 的计时包装；文件头写明**晋升条件**：当第二个插件（tty）也需要使用审计时才上提
`@hyzyn/dsh-kit`——按 conventions 的 L0/L1 边界判据，现在只有一个包需要，不提前抽象）。
`src/index.ts` 接线：八条变更 / exec 路由（`/action`、`/images/remove|prune`、
`/networks/remove|prune`、`/volumes/remove|prune`、`/exec`）在 403 判定之后包
`audited(logger, …, () => api.xxx(...))`（成功与失败都记、失败原样 rethrow，不改既有错误处理）；
`/images/pull/stream` 在 run 里记 `event=start` / `event=end` 两行（宿主中途挂掉时至少 start
还在；被中止时 runner 以 code=null 落定，end 省略 code）；agent 工具 `docker_action` /
`docker_image_remove` / `docker_image_prune` / `docker_image_pull` / `docker_exec` 在 api 调用处
包 `audited(..., source='tool')`——它们走 DockerApi 不经 HTTP 路由，两条入口不重复计数。
语义（单一）：**使用 = 过了闸**——403 与参数校验 400 不记、tier-gate 的 ask / deny 不记
（宿主 approval 日志已覆盖）、docker 报错也算一次使用（`ok=false` + `detail=` 截断后的错误
文案）。exec 的命令随行进日志（`detail=code=… cmd=…`），这是写进 README 已知限制的代价；
截断与转义只在 helper 一处发生，不靠调用点自觉。

**门槛**：`test/capability-audit.test.ts` 26 条——helper 单测（200 截断带 `…` 信号、控制字符
转义保证一行就是一次事件、缺 ref 字段省略、`audited` 成功/失败两路与原样 rethrow）；逐操作
断言（每条路由 / 工具**恰好一行**、`capability/source/action/target/ref/ok` 逐字段对上、pull 流
start+end 两行、只读路由与 `/connect-local` 零行、403 零行）；失败路径（`ok=false` + detail
截断、错误按原路径返回不吞）；`scripts/route-smoke.mjs` 新增 5 个端到端用例（八条路由逐字段、
pull 流两行、只读与 connect-local 零行、工具 `source=tool`、403 不记且开关恢复后照旧）。

**真机验收（2026-10-07，真宿主 + 真 Chrome + 真 docker）**：隔离一次性 profile 驱动设置卡片，
撤销 → 提权 → 真实 exec 走 `audited()` 路径全通；顺带挖出 **D162**（出口走了 `ctx.logger`，
真宿主上无处可查）——出口已改 `console.log`，测试与冒烟的断言面随之改为 console 捕获（捕到的
就是真宿主 stdout 上会出现的字节）。kit elevation 授权行的同一问题记在根 ROADMAP 待办 11。

### ✅ 长流被中止后 `busy` 账不平 + 拒绝原因被客户端丢掉（2026-10-08 完成）

**现场**：用户拿着面板截图问「点击重连没反应」——248 上的活动条停在「事件流已断开」，
点那个按钮页面毫无变化。探针复现：`GET /events/stream?target=248` 连续 12 次都回同一句
`已有 8 条实时流（上限 8）…`，跨 15 分钟一字不差；而同一时刻浏览器到宿主只握着 4~5 条
TCP（真有 8 条流在推的话不该是这个数）。对照组：切到没被面板占用的 目标2，同样的实验
一次连开 8 条成功、8 条退出后再连仍是 8 条成功——**配额逻辑本身会正常释放**。

**根因（两件事叠在一起，记在 [DEFECTS.md](./DEFECTS.md) 的 D164）**：
① `RemoteExec.stream()` 的 `onAbort` 只做 `signal('KILL') + channel.close()` 就**等远端回话**。
部分 sshd 会拒绝那个 KILL（D150 实测原文），通道也可能静默（既不 `emit('close')` 也不
`emit('error')`）——于是 Promise 永不落定、`finally` 里的 `release()` 永不执行、`busy` **永久
+1**。累积 8 次之后该目标的每条长流都被 `streamBudgetError` 拒绝，且没有任何自愈路径
（`openChannel` 的重建分支只在**开通道被远端拒绝**时触发，而这一层拒绝发生在开门之前）。
这是 D112（`run()` 超时）与 D161（`run()` 的 abort）**同一个坑的第三次出现**。
② 客户端把 `event: error` 的 `data` **整个丢掉**、只置 `closed`（统计流一直是读 message 的），
于是「被拒 → 回到原位」与「点了没反应」在界面上逐像素相同，用户只能反复点。

**落点**：`src/ssh-exec.ts`——`onAbort` 补 `finish(null)`（当场 settle，幂等靠已有的 `settled`
守卫），数据回调各加 `if (settled) return`（收尾后的分片不再投递）。`client-src/index.js`
——新增纯函数 `eventsErrorMessage()`，`onError` 把服务端那句话写进新的 `eventsRefused`
state，活动条据此显示「上次重连被拒绝：<原文>」（i18n `hint.eventsReconnectRefused`，zh/en
各一份），重连成功 / 重新建流时清空。

**门槛**：`test/logs-stream.test.ts` 新增 3 条（远端不确认时 `busy` 归零且 Promise 落定 /
累积 8 次后第 9 条仍被放行 / 收尾后的分片不投递），`scripts/client-smoke.mjs` 新增 2 条
（`errorMessage` 的六种输入语义 + 接线判据）。**判别性已实测**：退回 `onAbort`（去掉
`finish(null)`）→ 单测 3 条红，其中两条挂满 20s 超时正是「Promise 永不落定」的现场；
退回客户端（`setEventsRefused` 不接）→ 冒烟 1 条红（91/92）。
**顺带实测的负结论**（免得后人重做）：`StringDecoder.end()` 之后再 `write` 不抛、只返回空串，
所以那两个 `settled` 守卫是**防重复投递**，不是防崩溃。

**真机验收（2026-10-08，test profile 宿主 + 真 Chrome + 真实 SSH 目标）**：
`test` profile 本就以 `link:` 指向本仓（`dsh plugin --profile test add link:<仓>/packages/docker`），
产物与仓库逐字节一致，所以**无需另装**——起宿主即加载修复版：

- **宿主侧（配额真的会回收）**：对 248 连开 10 条 → 恰好 8 条被接受、2 条被拒（上限仍然生效）；
  被 `--max-time` 掐断（= 模拟远端不确认关通道）后**再开一轮仍是 8 条被接受**；连做 3 轮、
  累计 24 次 abort 之后**仍然稳定 8/8**。修前第二轮就会被自己的账钉死在 8/8。
  短命令（`POST /containers`）全程正常，配额不误伤。
- **浏览器侧（拒绝原因真的显示出来了）**：把 248 打满后，在真 Chrome 里打开面板并触发重连，
  活动条文案为「**重连被拒：root@hosths-test-248 实时流已达上限（8/8）：关掉一些日志跟随、
  或减少聚合容器数后重试**」并保留「重连」按钮。修前这里只有「事件流已断开」，点按钮
  在像素上毫无变化。
- 应用壳加载：`scripts/verify-client-ui.mjs --mode boot` **6 PASS / 0 FAIL**（10 个
  `@hyzyn` bundle 全加载、0 未捕获异常、0 控制台 error、0 失败请求）。
- 清理后复核：杀掉全部占位流 → 248 **立即恢复**（新流正常连上），确认没有残留账。

**同日回修 ⑤（用户看着活动条截图说「这个文字提示啰嗦又生硬」）**：断开时右侧那句是
**折叠头里的单行小字**，而原来的写法把三件事叠在一起——「事件流断开后不会自己回来」+
括号里的实现细节（`EventSource` 只在连接层抖动时自愈、`docker events` 进程退出属于终止态）
+ 操作指引，铺成四行墙；配额那句也带着 `OpenSSH MaxSessions 默认 10` 这种用户不需要的术语。
改法（**只说「怎么了 + 怎么办」，成因留给文档**）：

| 位置 | 改前 | 改后 |
|---|---|---|
| 断开提示 | `事件流断开后不会自己回来（EventSource 只在连接层抖动时自愈；docker events 进程退出属于终止态）——点它重连，或点右上角刷新列表` | `不会自动恢复，点「重连」` |
| 被拒提示 | `事件流断开后不会自己回来（…）——上次重连被拒绝：{message}` | `重连被拒：{message}` |
| 配额文案 | `{target} 上已有 8 条实时流（上限 8）：同一连接上的通道额度（OpenSSH MaxSessions 默认 10）…请关掉部分实时跟随、把聚合容器数减到 6 个以内，或稍后重试。` | `{target} 实时流已达上限（8/8）：关掉一些日志跟随、或减少聚合容器数后重试` |
| 通道满文案 | `（远端 sshd 拒绝了新通道：同一连接上的通道额度可能已被实时流占满——OpenSSH MaxSessions 默认 10；插件遇到该错误会重建连接自动重试一次，仍失败请关掉部分实时跟随 / 减少聚合容器数后重试）` | `（远端 sshd 通道已满：关掉一些日志跟随、或减少聚合容器数后重试；插件已自动重建连接重试过一次）` |

状态行左边已经写着「事件流已断开」，所以这句**不再复述**；配额文案从 108 字压到 54 字。
**门槛**：`test/ssh-stream-budget.test.ts` 增加长度上限判据（≤60 字）与「不得再出现
`MaxSessions`」的负判据——否则下一个人「补说明」时又会把它写长；冒烟的文案断言同步。
真机复核：把 248 打满后用真 Chrome 打开面板，活动条为
「重连被拒：root@hosths-test-248 实时流已达上限（8/8）：关掉一些日志跟随、或减少聚合容器数后重试」，
从四行降到两行、术语为零。

> 受限环境提示：本机沙箱下 headless Chrome 会因 GPU 进程崩溃而连不上 CDP
> （`Runtime.enable 超时`），按 `scripts/verify-client-ui.mjs` 文件头加
> `--chrome-arg --no-sandbox` 即可——那是**环境限制**，不是代码问题
> （见 [agent-real-test.md § 三条硬约束 ②](../../docs/agent-real-test.md)）。

### ✅ 聚合上限压到浏览器同源连接预算之内（2026-10-08 完成）

**现场**：修完 D164 之后用户追问「docker 重连的时候是不是会影响 dsh 页面的加载，我发现重连
的时候页面就很卡」——**这个怀疑是对的，而且是产品缺陷**，不是错觉也不是环境问题。

**机制**：宿主是 **HTTP/1.1**（无 h2 多路复用），浏览器对每个源只放有限几条 TCP，而每条
`EventSource` **独占一条连接且永不主动释放**；吃满后同页面**所有**普通请求一起排队。

**实测（真 Chrome + test profile 宿主，页内连打 10 次普通请求 / 2s 超时）**：

| 常驻流 | 页内请求 | 进程外请求（同一时刻） |
|---|---|---|
| 0 条 | 10/10 成功，中位 27ms | 26ms |
| 4 条 | 8/8 成功，中位 25ms | — |
| **5 条** | **0/10 全部超时** | **41ms（正常）** |

最后一列是判别性的：**堵在浏览器，不在宿主**。真实操作路径复现：开 **6 条聚合流**（正是
仓库自己给 SSH 目标设的 `PICK_MAX_SSH = 6`）→ 页内请求 **0/6 全超时**；关掉立即恢复。

**根因（记在 [DEFECTS.md](./DEFECTS.md) 的 D165）**：旧代码把这笔账算在了**宿主侧**
（`MaxSessions`：一条 SSH 连接要同时装下聚合流、统计流、事件流与刷新等短命令），
于是 `PICK_MAX = 8` / `PICK_MAX_SSH = 6`——**那是另一笔账**（由 `MAX_STREAMS_PER_TARGET = 8`
管），与浏览器这一层是两笔独立的账，写成同一个数字正好把两边都算错：6 与 8 都**大于实测
安全值 4**。旁证：`PICK_SOFT_MAX` 那几行的注释早就写着「浏览器并发长连接有限制」，
说明当初意识到了这一层，只是**上限值仍定在悬崖之上**。

**落点**：`client-src/index.js` 新增 `SAME_ORIGIN_STREAM_BUDGET = 4`（实测值）与
`RESERVED_STREAMS = 1`（容器页常开的事件流），`PICK_MAX = 4 − 1 = 3`、`PICK_MAX_SSH = PICK_MAX`、
`PICK_SOFT_MAX` 6 → 2；三条 i18n 改成点明后果，新增 `hint.pickBudget` 由 `PickBar` 渲染在
选择条上（**上限的来由要写在脸上**，否则 3 看起来只是个随手定的数字）。

**刻意不做**：不按目标类型分档（真正卡页面的是浏览器，与目标是不是 SSH 无关）；不动
`MAX_STREAMS_PER_TARGET`（宿主侧那笔账另有依据）。

**门槛**：聚合用例改成钉住**推导链**（`MAX=3` / `SSH_MAX=3` / `BUDGET=4` / `RESERVED=1`，
`decide(3)` 可点 + 软提示、`decide(4)` 置灰）+ 源码级接线判据（`budget` 真传进 `PickBar`
且被渲染）。**判别性已实测**：`PICK_MAX` 退回 8 → 三条断言红。

**真机复核**：新上限形状（3 聚合 + 1 事件流 = 4 条）下页内请求 **8/8 成功、中位 26ms**；
修复前同一形状 0/6 全超时。`verify-client-ui.mjs --mode boot` 5 PASS / 0 FAIL。

**两条实测负结论**（免得后人重做）：① **WebSocket 不占这份预算**——tty 终端那条 WS 与
4 条 SSE 共存时页面仍正常，悬崖仍在第 5 条 SSE；② 重连**动作**本身不额外恶化（每 700ms
全断全连的风暴下仍 26ms）——卡的是**数量**，用户感觉「重连时卡」是因为那一刻已经开了
足够多的流。

### ✅ 聚合日志改成单连接多容器，docker 常驻流 4 → 1（2026-10-24 完成）

**触发**：一份用户缺陷报告说 `@hyzyn/dsh-docker` 用 4 条 `EventSource` 占满浏览器
HTTP/1.1 配额，打开「容器」面板后整页请求永久 pending。**逐条核对 0.13.3 源码后，报告
的复现不成立**：打开面板只建 **1** 条（活动条 `/events/stream`），日志 / 统计 FOLLOW
默认关、拉取流只在拉取时存在。但报告指向的放大器是真的：多选聚合与 Compose 项目日志
对**每个容器各开一条** `/logs/stream`（Compose 项目页甚至没有数量上限），3 个容器 +
事件流 = **4 条**，正好落在 D165 实测的悬崖边上；再叠上宿主自己的 SSE（`dsh-client-hmr`
等），一条新请求就会让整页排队。报告把「重连 + 详情 + 聚合」的瞬时组合当成了稳态，
但「4 条 docker 常驻流」确实可达。

**修法（[DEFECTS.md](./DEFECTS.md) 的 D168）**：宿主 `/logs/stream` 新增 `ids=`——
一条 SSE 里跑 N 个 `docker logs -f`，帧带 `id`，单源失败只发 `source-error`、不拖垮
整条连接；客户端聚合 / Compose 日志改走这一条；事件流只在**列表真的在屏幕上**时建
（详情 / 聚合 / 拉取视图断流，回来重连并补一次全量刷新）。结果：docker 面板在任何
视图下的常驻流都是 **1 条**（列表 = 事件流；详情 = 日志或统计；聚合 / Compose = 一条
多源流；拉取 = 一条进度流）。`streamProtocol` 升 **3**，老宿主退回「每容器一条」。

**刻意不做**：不把统计 / 事件流也塞进同一条连接（它们的分帧与去重都按「一条流一个源」
写死）；不把 `PICK_MAX` 重新绑回浏览器预算（它现在是「可读性 + SSH 8 条通道额度」的
上限）；**多标签页那一层不在本包**——宿主自身每标签就有 2 条常驻 SSE，3 个标签页 = 6 条
已经到悬崖，真要治本得让宿主换 WebSocket / h2 或共用一条多路复用连接。

**真机复核**（2026-10-24，隔离 `DSH_HOME` + 拷 `test` profile + 假 docker CLI，真 Chrome
与真宿主；本机 docker daemon 未运行，所以用假 CLI 供容器列表 / 事件 / 日志）。页内活动
`EventSource` 由注入的 `EventSource` 包装器现算：

| 状态 | 页内活动 EventSource | 其中属于 docker |
|---|---|---|
| 页面打开、面板关闭 | 2（宿主 `plugins/events` + `/api/our-free-model/events`） | 0 |
| 打开「容器」列表 | 3 | **1**（`events/stream`） |
| 聚合 2 个容器日志 | 3 | **1**（`logs/stream?...ids=<web>,<db>...`） |
| 关掉面板 | 2 | 0 |

聚合视图下页内 20 次 `fetch('/')`：**中位 1ms / 最大 3ms**（全部成功）。同一个连接下
确有两个 `docker logs -f` 子进程在跑，界面按 `[web]` / `[db]` 前缀分别落行（帧里的 `id`
派回正确）。收尾自证真实 `~/.dsh/cordis.patch.yml` 逐字节未变（`true`）。

**门槛**：`test/logs-stream.test.ts` §5b 七例（多源帧带 id / `line → source-end → end`
顺序 / 单源失败不关连接 / `ids` 校验矩阵 / 两源只发一帧 ready / 断开杀全部子进程）；
`scripts/client-smoke.mjs` 两例（`streamProtocol` 协商 + 列表可见性判据 + 源码级接线）；
`scripts/route-smoke.mjs` 的 `streamProtocol === 3`。**判别性已实测**：把多源分支退成
单源（`multiSource` 恒 false）→ §5b 七例红；把事件流判据退回 `!active` 判断 → client
smoke 的列表可见性断言红。

## 已上提到项目级（不在本文展开）

跳板机（ProxyJump）· 统一安全围栏（对齐 tty / dsh-mcp）· 变更端点的信任模型（一次性 token）·
`isConcurrencySafe` 未声明 · 面板端 i18n —— 见 [项目级 ROADMAP.md](../../ROADMAP.md)。

**在项目级待办（代码已落地）**：**插件工具接入会话权限档位（tier gate）**——项目级
[ROADMAP.md § 待办](../../ROADMAP.md#待办) 第 10 项（2026-10-07 立项并实施）。本包的分工：全部
agent 工具的档位分类表（`docker_action` / `docker_image_*` 归 `write`、`docker_exec` 归 `exec`）
与 `tools/pre-execute` 接线，已落在 `src/index.ts`（`DOCKER_TIER_CLASS`）；与既有 `allowMutations` /
`allowExec` 静态开关是**双层并存**（静态管注册、档位管已注册调用的放行），不是取代。决策矩阵、
真机验收 V0–V8 与开放决策 R1–R4 的决议都在
[docs/permission-tier-plan.md](../../docs/permission-tier-plan.md)，本文不复述。

**2026-09-25 更新**（三项已落地，落点与门槛见项目级 ROADMAP 的 § 已完成）：

- **统一安全围栏**：本包那份加固档（D31 / D32 / D80 / D110 / D139 的实现）**整体上提到
  `@hyzyn/dsh-kit`**，docker 改走 kit 的导出——行为一字未改（12 个既有路由 / 流用例未动一行
  即全绿），三包共用一份；DEFECTS.md 的「安全围栏」节下有落点迁移标注；
- **`isConcurrencySafe`**：11 个只读工具声明、5 个变更工具**刻意不声明**；
- **跳板机（ProxyJump / ProxyCommand）**：**已全部落地**（2026-09-25）。先把「短期一半」
  （超时 / 通道错误 / 条目缺失三处文案点出成因）补上，随后做完整实现：`readTtyBooks` 把
  `jump` 带进规格、`poolKey` 并入 `|jump:<user@host:port>`（不同跳板机到同一目标不再并成一条
  连接）、`acquire` 先拨跳板机再把 `forwardOut` 通道当 `sock`、`disposeAll` / 空闲回收 /
  传输错误重连都成对收尾。
- **`ProxyCommand`**：同样落地，但**闸门只有一处**——读 tty settings 的 `allowProxyCommand`
  （**默认关**），且**每次拨号现读**（关掉立刻生效，不留缓存）；关着时携带代理命令的目标
  明确失败（不退回直连）。本包**不新建界面**：连接簿在 tty 配一次，两个面板一起生效；
  池键并入 `|cmd:<sha256 前 12 位>`——**只并入摘要**，因为命令原文可能含凭据而池键会进诊断路径。
  方案与全部已知坑见 [docs/proxyjump-plan.md](../../docs/proxyjump-plan.md)（§6.1 闸门定案表）。