dsh-mobile-plugin 0.4.0 → 0.4.1

package/lib/session-cleanup.cjs

@@ -1,30 +1,19 @@
 /**
  * 会话数据清理：按 sessionId 删除 dshHome 下的 sessions/** 目录与 project cache。
  *
- * 两个入口共用同一套落地代码：DSH agent 工具 registerSessionCleanupTool（action=delete
- * 必须 confirm:true 且只针对已归档）与移动 API /workspace/clear-archived（archive-clean.js）。
+ * 两个入口共用同一套落地代码：DSH agent 工具 `registerSessionCleanupTool`（action=delete 必须
+ * confirm 且只针对已归档）与移动 API `/workspace/clear-archived`。
  *
- * **两个入口都不在进程里删磁盘**：只把 id 排进待删队列（dshHome 下的
- * mobile-archived-clear.json），真正的删除放在宿主下次启动时做，见
- * deleteQueuedArchivedSessions。宿主没有「删除会话」接口，进程活着的时候它手上那些会话
- * 随时可能被读或写，文件不在就是一次未捕获的 ENOENT —— 宿主对未捕获异常是零容忍的，
- * 整个进程退出，桌面端跟着消失（2026-10-20 就是这么闪退的）。
+ * 两个入口都不在进程里删磁盘：只把 id 排进待删队列（dshHome 下的
+ * `mobile-archived-clear.json`），真正的删除放在宿主下次启动时做。宿主没有「删除会话」接口，
+ * 进程活着时那些会话随时可能被读或写，文件不在就是一次未捕获的 ENOENT，整个进程退出。
  *
- * 认哪份文件、怎么读 id 都以宿主自己的规则为准，不按目录名猜：
- *  - 文件名 = `session[.vN].jsonl[.zstd]`（宿主 `dsh-session-format` 的
- *    CANONICAL_LOG_FILENAME + compressionSuffix：0 代不带 vN，压缩时才带 .zstd）。
- *    曾经只认 `session.jsonl.zstd`，于是 0.2.0 真在用的 `session.v4.jsonl.zstd`
- *    一个都认不到 —— 表现是「清理已归档」恒回 `deleted: 0`，静默不删。
- *  - 解压用 Node 自带的 zstd（DSH 自己就是这么读写日志的，宿主并不需要系统 zstd
- *    命令），不再 shell 出去：没装 zstd 命令的机器上它一缺就是 readHeader 静默返回
- *    undefined，整条删除路径空转。id 仍然取自日志第一行那条 header。
- *  - **进程活着的时候不删日志、也不擦宿主的归档集合**；两件事都放到宿主启动时
- *    （pruneOrphanedArchivedSessionsOnce）。擦集合的理由写在那个函数上：桌面端的会话
- *    列表是连上宿主时拉的一份快照 + 之后的事件增量，进程里擦集合等于把已经删掉、却还
- *    留在快照里的行放回正常列表。删日志的理由见上面那段：进程里删 = 宿主随时可能踩空。
- *  - **Windows 上目录删不掉 ≠ 会话没删掉**：宿主对它打开过的会话一直握着 `session.lock`
- *    的写句柄，日志 unlink 成功后那个名字要等句柄关闭才消失（delete-pending），rmdir
- *    于是报 ENOTEMPTY。判据改成「目录里还有没有规范名日志」：没有就是删成了。
+ * 认哪份文件、怎么读 id 以宿主规则为准，不按目录名猜：
+ *  - 文件名是 `session[.vN].jsonl[.zstd]`（0 代不带 vN，压缩时才带 .zstd）；
+ *  - 解压用 Node 自带的 zstd，不 shell 出去，id 取自日志第一行的 header；
+ *  - 进程活着时不删日志、也不擦宿主的归档集合，两件事都放到宿主启动时；
+ *  - Windows 上目录删不掉不等于会话没删掉：宿主握着 `session.lock` 时名字要等句柄关闭才
+ *    消失，所以判据是「目录里还有没有规范名日志」。
  */
 'use strict'
 
@@ -198,9 +187,9 @@ async function archivedIdsWithoutLogs(archivedSessionIds) {
 /**
  * 盘上已经不剩任何会话数据的 id：目录没了，或者目录里只剩宿主锁着的 `session.lock`。
  *
- * 只给移动端的「清理所有已归档」补账用：更早一次删除如果删到一半抛错（2026-10-18 前
- * Windows 的 ENOTEMPTY 就是这样），已经删掉的那批 id 没能记进本进程的删除集，而宿主的
- * 进程内清单还挂着它们 —— 再点清理只会回 `deleted: 0`，手机上永远清不掉。
+ * 只给移动端的「清理所有已归档」补账用：更早一次删除如果删到一半抛错（Windows 上目录非空
+ * 时就是这样），已经删掉的那批 id 没能记进本进程的删除集，而宿主的进程内清单还挂着它们 ——
+ * 再点清理只会回 `deleted: 0`，手机上永远清不掉。
  *
  * 判据比 archivedIdsWithoutLogs 更宽（那个只认规范名日志），但**不许宽到把迁移中途的
  * 临时文件当成没有数据**：目录里只要还有任何非锁文件（含子目录）就算「还在」，读不出来
@@ -234,7 +223,7 @@ function sessionIdsWithoutAnyData(sessionIds) {
  * deleteQueuedArchivedSessions。原因是宿主没有「删除会话」这个接口：进程活着的时候，
  * 它内存里那些会话随时可能被读或写（列一遍会话、续写一条事件、开一条还没落盘的空白会话），
  * 文件不在就是一次没人接的 ENOENT —— 宿主对未捕获异常零容忍，进程直接退出，桌面端窗口
- * 跟着消失（2026-10-20 真机就是这么闪退的：清理删到一条 0 轮次的空白归档会话）。
+ * 跟着消失（清理删到一条 0 轮次的空白归档会话就会这样）。
  *
  * 队列是**并集**语义：同一批 id 点两次、两次清理之间换了批次，都只是往同一张表里加。
  */
@@ -345,7 +334,7 @@ async function pruneOrphanedArchivedSessions(ctx) {
  *
  * 这两件事都只能在启动这一刻做：
  *  - **删日志**：宿主没有「删除会话」接口，进程活着时它随时可能去开那些文件；文件不在
- *    就是一次未捕获的 ENOENT，宿主直接退出（2026-10-20 桌面端闪退就是这条）。
+ *    就是一次未捕获的 ENOENT，宿主直接退出。
  *  - **擦归档集合**：桌面端的会话列表是「连上宿主时拉的一份快照 + 之后的事件增量」，
  *    进程活着的时候擦集合，宿主会把「归档集合变了」广播给桌面端，桌面端就把它快照里
  *    那些其实已经没有日志、本来被归档藏着的行放回正常列表 —— 用户报的正是「清理后

package/lib/shared/credentials-entry.js

@@ -3,18 +3,11 @@
 /**
  * 凭据包 `dsh-mobile-credentials` 的入口。
  *
- * 它在盘上有**两代布局**：
+ * 它在盘上有两代布局：新布局嵌在插件包内（一代自包含，回滚时凭据跟着一起回滚），旧布局与
+ * 插件包同级。往哪里落由外壳的资产重映射决定，而外壳在进程启动时就被 Node 缓存住、换不掉；
+ * 迁移期新旧外壳可能各按一种布局放置，只认一条路就会「装完激活才炸 Cannot find module」。
  *
- *   - 新布局：嵌在插件包内 —— `<插件包>/dsh-mobile-credentials/lib/credentials.js`
- *     （一代自包含，回滚时凭据版本跟着一起回滚）；
- *   - 旧布局：与插件包同级 —— `node_modules/dsh-mobile-credentials/…`，
- *     代际目录下则是 `<代>/dsh-mobile-credentials/…`。
- *
- * 往哪里落由**外壳**（`lib/shell/ota.js` 的资产重映射）决定，而外壳在进程启动时就被 Node
- * 缓存住、换不掉。布局迁移那一次，旧外壳把凭据放进同级目录、新实现却按嵌套路径 require，
- * 结果是「装完激活才炸 Cannot find module」——热更半装成功，留下的一代还是残缺的。
- *
- * 所以这里两条路都试，谁在就用谁：旧外壳配新实现也能跑起来，布局迁移不再是地雷。
+ * 所以这里两条路都试，谁在就用谁。
  */
 
 /** 新布局：`<插件包>/dsh-mobile-credentials/`（本文件在 `<插件包>/lib/shared/`）。 */

package/lib/shared/dshtoken.js

@@ -24,10 +24,10 @@ function hmacPayload(secret, payload) {
 
 /**
  * 签发 LAN/mobile token：<instanceId>.<exp>.<sig>。
- * 缺省 ttlSec=30d（与 relay core / browser core 历史缺省一致），但**消费方必须显式传原值**
- * （LAN 主进程 3600、30d 处 30*24*3600），本函数不隐藏调用点的默认值差异。
- * @param {string} secret      lanSecret（~/.dsh/relay.json 密钥）
- * @param {string} instanceId  实例 id（~/.dsh/relay.json）
+ * 缺省 ttlSec=30d，但消费方必须显式传原值（LAN 主进程 3600、30d 处 30*24*3600），本函数不
+ * 隐藏调用点的默认值差异。
+ * @param {string} secret      lanSecret（relay 配置里的密钥）
+ * @param {string} instanceId  实例 id（relay 配置）
  * @param {number} ttlSec      有效期（秒），缺省 30*24*3600
  * @param {number} [nowSec]    秒级「当前时间」覆盖（测试/主进程签名用）；缺省 Date.now()/1000
  * @returns {string}

package/lib/shared/e2ee-request.js

@@ -291,7 +291,7 @@ const MAX_SEALED_BODY = Math.ceil(11 * 1024 * 1024 * 4 / 3);
 function readRawBody(req, maxBytes = MAX_SEALED_BODY) {
   // **没有请求体的请求不能等 `end`**：SSE 客户端（XHR）发出来的 GET 有时不会像普通
   // fetch 那样把请求流收尾，而守卫在读体这一步就把处理器挡住了 —— 表现是「手机一直在
-  // 重连、宿主侧连开流日志都没有」（2026-10-24 现场）。GET/HEAD 且既没有 content-length
+  // 重连、宿主侧连开流日志都没有」。GET/HEAD 且既没有 content-length
   // 也没有 transfer-encoding，就是没有体，直接回空。
   const method = String((req && req.method) || 'GET').toUpperCase();
   const headers = (req && req.headers) || {};

package/lib/shared/e2ee.js

@@ -1,22 +1,16 @@
 'use strict';
 
 /**
- * 链路加密（协议 v2）的字节级原语。App 侧有一份逐字节等价实现（`services/e2ee.ts`），
- * 两边的正确性靠同一份测试向量保证（`test/e2ee-vectors.json`），不靠互相阅读代码。
+ * 链路加密（协议 v2）的字节级原语。App 侧有一份逐字节等价实现（`services/e2ee.ts`），两边的
+ * 正确性靠同一份测试向量保证（`test/e2ee-vectors.json`），不靠互相阅读代码。
  *
- * 这一层只做「算字节」，不认识路由、不认识业务：信封放在哪里、什么时候加解密，由
- * `http/routing.js`（宿主侧）与 `services/http.ts`（App 侧）负责。
+ * 这一层只做「算字节」，不认识路由与业务：信封放在哪里、什么时候加解密由路由层负责。
+ * 算法只用三样、两端现成：AES-256-GCM、HKDF-SHA256、HMAC-SHA256。
  *
- * 算法只用三样，且都是两端现成的：AES-256-GCM、HKDF-SHA256、HMAC-SHA256。
- *
- * **AEAD 用 AES-256-GCM 而不是 ChaCha20-Poly1305**（2026-10-24 改）：桌面宿主跑在
- * Electron 里，那份 Node 链接的是 BoringSSL，`crypto.getCiphers()` 里根本没有
- * `chacha20-poly1305`（实测 `createCipheriv` 直接 `Unknown cipher`，`openssl 0.0.0`）。
- * 换过来之前，每一条协议 v2 的请求在宿主侧都会在解封那一步抛错 —— 表现成扫码配对
- * 一律「配对码错误」、已配对设备全线 401，而两端的离线测试（用真实 node:crypto）
- * 全绿，因为测试进程的 Node 是带 chacha 的那一种。
- * 不引 HPKE、不引新依赖 —— 理由（Node 不暴露 `crypto.hpke`，App 侧也没有
- * 现成的 X25519，而二维码里那张一次性票据已经解决了「怎么秘密交付密钥」）。
+ * AEAD 必须用 AES-256-GCM 而不是 ChaCha20-Poly1305：桌面宿主跑在 Electron 里，那份 Node
+ * 链接 BoringSSL，`crypto.getCiphers()` 里没有 chacha20-poly1305，解封会直接抛错，表现成
+ * 扫码配对一律「配对码错误」。不引 HPKE 也不引新依赖：Node 不暴露 `crypto.hpke`，App 侧也没有
+ * 现成的 X25519，而二维码里那张一次性票据已经解决了「怎么秘密交付密钥」。
  */
 
 const crypto = require('node:crypto');

package/lib/shared/fresh-request.js

@@ -1,29 +1,13 @@
 'use strict'
 
-// 「读己所写」(read-your-writes) 标记：移动端做完一次写操作之后紧接着的那次列表刷新，
-// 必须反映出这次写入，不能被任何「代读副本」顶掉。
+// 「读己所写」标记：写操作之后紧接着的那次列表刷新必须反映这次写入，不能被任何代读副本顶掉。
 //
-// 背景（真机缺陷，探针实测）：移动端的读请求会经过两层代读副本——
-//   1. sidecar 的镜像快照（mirror-snapshot.cjs 判定新鲜度）直接把 /sessions、
-//      /workspaces 回给手机，根本不连宿主插件；桌面侧 500ms 推一次，所以正常最多
-//      旧 500ms；
-//   2. 宿主插件自己的 10s 会话列表缓存（lib/mobile/sessions.js 的
-//      SESSION_LIST_CACHE_MS）。
-// 两层对「每 15s 一次的轮询」都无所谓，但写操作之后的第一次刷新撞上任何一层，就会把
-// 用户刚做完的事显示成没生效。
+// 读请求会经过两层代读副本：sidecar 的镜像快照（桌面侧 500ms 推一次）与宿主插件自己的 10s
+// 会话列表缓存。轮询撞上它们无所谓，写后第一次刷新撞上就会把刚做完的事显示成没生效。
 //
-// 实测（Mac 宿主 + MI 9，时间戳相对点击「归档」按钮）：
-//   + 311ms  HOST archive-session session-63acd828-…      ← 宿主侧已经改对了
-//   + 375ms  SNAPSHOT /api/mobile/v1/sessions fresh        ← App 的刷新读到 +286ms 推来的旧镜像
-//   +17233ms SNAPSHOT /api/mobile/v1/sessions fresh        ← 直到 15s 轮询才拿到新列表
-//
-// 于是约定 `?fresh=1`：带这个标记的读跳过所有代读副本，直接回源宿主插件。
-// 轮询、首屏、下拉刷新不带，快路径照旧。
-//
-// 权威实现在本文件；`dsh-mobile-server/lib/fresh-request.js` 是它的手工同步副本，
-// 两侧由 `test/shared-helpers-parity.test.cjs` 钉住。**改一边必须改另一边。**
-// 中转侧同样必须认这个标记：中转自己也持有镜像与响应缓存，它若把带 fresh 的读
-// 当普通读缓存掉，App 的下拉刷新就失去了唯一的自救手段。
+// 所以约定 `?fresh=1`：带这个标记的读跳过所有代读副本、直接回源；轮询 / 首屏 / 下拉刷新不带。
+// 权威实现在本文件，`dsh-mobile-server/lib/fresh-request.js` 是手工同步副本，两边必须一起改；
+// 中转也必须认这个标记，否则 App 就失去了唯一的自救手段。
 
 const FRESH_QUERY_RE = /(?:^|[?&])fresh=1(?:&|$)/
 

package/lib/shared/http-util.js

@@ -100,11 +100,10 @@ function sendHtml(res, status, html) {
 }
 
 /**
- * 读取请求体并 JSON.parse；超限/非法 JSON/IO 错误 → null。
+ * 读取请求体并 JSON.parse；超限 / 非法 JSON / IO 错误 → null。
  *
- * **协议 v2 的请求体已经被守卫解开了**（`req.body`），这里直接返回它：那条请求的字节流
- * 早被读走拿去验签与解封，再读只会拿到空串，于是所有 POST 都退化成「请求体不是合法
- * JSON」。上限按**明文**判（与线上字节的 4/3 放大分开算，见 §8.3(9)）。
+ * 协议 v2 的请求体已经被守卫解开了（`req.body`），这里直接返回它：那条请求的字节流早被读走
+ * 拿去验签与解封，再读只会拿到空串。上限按明文判（线上字节按 4/3 放大，两边分开算）。
  *
  * @param {object} req         node:http IncomingMessage
  * @param {number} [maxBytes]  请求体上限（字节，按明文），缺省 344KB

package/lib/shared/list-revision.js

@@ -3,21 +3,12 @@
 /**
  * 清单内容指纹（sessions / workspaces 共用）。
  *
- * 存在的理由：手机端有两件事需要「这份清单和上次是不是同一份」——
+ * 两处要用：列表响应带 `revision`，App 连同 `generatedAt` 存进快照就能说清数据是什么时候的；
+ * 镜像推送每 500ms 完整构建一次清单，内容没变时比对 revision 就能安全跳过。
  *
- *  1. 数据新鲜度：列表响应带 `revision`，App 把它连同 `generatedAt` 一起存进快照，
- *     就能把「数据是谁在什么时候给的」显示给用户，而不是让用户自己猜；
- *  2. 镜像推送判重（见 lib/mirror/pusher.cjs）：后台 500ms tick 每轮都会完整构建
- *     sessions + workspaces，内容没变时推送一份字节完全相同的 payload 纯属浪费，
- *     比对 revision 就能安全跳过。
- *
- * 为什么用内容哈希而不是自增序号：插件随桌面 harness 频繁重启，内存里的序号每次
- * 都从 0 开始，重启后第一份快照会因为「序号变了」而被当成新内容重推一遍；内容哈希
- * 跨重启稳定（同样的清单 → 同样的 revision），这才是判重想要的性质。
- *
- * 为什么用 sha1 而不是更省的 32 位哈希：这个值会被用来**跳过推送**，一次碰撞就等于
- * 一份该推的新数据被静默丢掉。sha1 足够便宜（清单量级下每 tick 亚毫秒），不值得为
- * 几个字节冒这个风险。截断到 16 个十六进制字符只是为了让日志短一点。
+ * 用内容哈希而不是自增序号：插件随桌面 harness 频繁重启，序号每次都从 0 开始，重启后第一份
+ * 快照会被当成新内容重推。用 sha1 而不是 32 位哈希：这个值会被用来跳过推送，一次碰撞等于
+ * 一份该推的新数据被静默丢掉。截断到 16 个十六进制字符只是为了让日志短一点。
  */
 
 const crypto = require('node:crypto');

package/lib/shared/session-signal.js

@@ -3,24 +3,15 @@
 /**
  * 设备级「某个会话的正文水位涨了」信号总线。
  *
- * 与 list-signal.js（清单变了）是同一形状的第二条通道，存在的理由是对话页的第二种场景：
- * 手机上**没有打开**某个会话时，那条会话的正文此前完全没人订阅 —— 只有打开的会话才建
- * `session/stream`（app/src/hooks/useChatStream.ts 的唯一调用点），所以「在别的地方盯着
- * 列表」时，运行中的助手回复只能等下一次点开该会话才被拉下来。
+ * 与 list-signal（清单变了）形状相同，但管的是另一种场景：手机上没打开某个会话时，那条会话
+ * 的正文没人订阅，运行中的回复只能等下次点开才拉下来。插件本来就把正文推进了中转镜像，缺的
+ * 只是「这个会话的正文又长了，可以来取」这句通知。
  *
- * 而插件这边本来就把正文推到了中转镜像：镜像调度器（lib/mirror/pusher.cjs）每轮为高优先
- * 会话（运行中 / 5 分钟内动过）构建 200 条消息快照，冷会话每 500ms 轮转补一个。缺的只是
- * 「这个会话的正文又长了，你（手机）可以来取」这一句通知，本模块就是那个出口。
+ * 清单信号是全局的（一个 revision），这条是按会话的（sessionId → 已广播的消息水位 seq）。
+ * 水位取快照里真正装上的消息的最大 seq，与 App 侧缓存水位同一个 seq 空间。
  *
- * 与 list-signal 的关键差别：清单信号是**全局**的（一个 revision），这条是**按会话**的
- * （sessionId → 已广播到的消息水位 seq）。水位取的是快照里**真正装上的消息的最大 seq**
- * （见 pusher 的 messageWatermarkOf），也就是 App 侧会话缓存的水位口径（同一个 seq 空间），
- * 手机拿它和自己的缓存水位一比就知道该不该增量拉一次。
- *
- * 为什么是模块级单例：生产端（mirror/pusher.cjs，CJS）与消费端（mobile/events.js，CJS）
- * 都 require 到同一个实例，两边不需要认识对方；测试可以 createSessionSignal() 造独立实例。
- * 为什么订阅者抛错要吞掉：bus 的调用方是镜像推送链，一条写坏的 SSE 连接不能把推送拖垮
- * （真故障会从连接自身的 close 反映出来）。
+ * 做成模块级单例：生产端与消费端 require 到同一个实例，互不认识；测试可以自己造实例。
+ * 订阅者抛错要吞掉——bus 的调用方是镜像推送链，一条写坏的 SSE 连接不能把推送拖垮。
  */
 
 const NOOP_RELEASE = () => {};

package/lib/shared/sse-write.js

@@ -1,26 +1,20 @@
 'use strict';
 
 /**
- * SSE 写帧的唯一实现：单会话流（lib/mobile/stream.js）与设备级流（lib/mobile/events.js）
- * 共用这一份。
+ * SSE 写帧的唯一实现：单会话流（lib/mobile/stream.js）与设备级流（lib/mobile/events.js）共用。
  *
- * 为什么要合并：两条流曾经各有一份几乎相同的实现，而 2026-10-17 的宿主 OOM（堆快照里
- * 17.6 万条 SSE 帧、466MB 挂在 `WriteWrap._chunks` 上，七十分钟涨到 3.9G 被杀）先修了
- * 会话流那份，隔一轮才发现设备流那份还漏着 —— 同一个坑修两遍，就是因为实现有两份。
- * 现在「这条连接上到底积压了多少字节」「软/硬水位怎么判」「SSE 记录长什么样」「稳定
- * 事件 id 怎么算」「写不动时怎么等 drain」都只在这里，两条流只在调用点上声明自己的策略。
+ * 合并是因为两份实现会让同一个坑修两遍：宿主 OOM 时先修了会话流那份，隔一轮才发现设备流那份
+ * 还漏着。现在积压字节数、软/硬水位、SSE 记录形状、稳定事件 id、等 drain 都只在这里，两条流
+ * 只在调用点声明自己的策略。
  *
- * 两条流刻意保留的差异（不是遗漏，改之前先看各自的理由）：
- *  - 丢帧口径：会话流的软水位只丢**明确可丢的增量**（只有 `assistant/chunk` 草稿：同一轮
- *    收尾的 `assistant/message` 带完整正文、重连 `replaySince` 能补齐）。`session/queue`、
- *    `session/jobs`、`session/resync-required` 这些控制帧没有 seq，但绝不能丢；设备级流的
- *    帧全是「有东西变了」的幂等信号，软水位丢弃后由调用方**断流重连**并用
- *    `replayKnownSignals()` 补发。由调用方传 `shedWhenBuffered`。
- *  - 写不动时：会话流 `await` 一次 drain（20s 超时再收尾）；设备级流直接收尾让客户端
- *    重连 —— 它没有 Last-Event-ID 续传，但连上时会 `replayKnownSignals()` 补发当前状态，
- *    所以「断开重连」是它的正常收敛路径。
- *  - 填充：会话流每条记录补 2048 字节 SSE 注释（Android RN 的 XHR 会攒小 chunk，
- *    不补就迟迟不触发 onprogress）；设备级流的帧很少、单帧也小，不补。
+ * 两条流刻意保留的差异（改之前先看理由）：
+ * - 丢帧口径：会话流的软水位只丢明确可丢的增量（`assistant/chunk` 草稿，收尾的
+ *   `assistant/message` 带完整正文）；`session/queue`、`session/jobs`、`resync-required` 这些
+ *   控制帧没有 seq 但绝不能丢。设备级流的帧全是幂等信号，丢掉后由调用方断流重连并补发。
+ * - 写不动时：会话流 await 一次 drain（20s 超时收尾）；设备级流直接收尾让客户端重连，重连
+ *   时会补发当前状态，所以断开是它的正常收敛路径。
+ * - 填充：会话流每条补 2048 字节注释（Android RN 的 XHR 会攒小 chunk，不补迟迟不触发
+ *   onprogress）；设备级流帧少且小，不补。
  */
 
 const crypto = require('crypto');
@@ -66,8 +60,8 @@ function ssePadding(bytes) {
  * 这条连接上真正「还没发出去」的字节数。
  *
  * 只看 `res.writableLength` 是错的：它只算响应对象自己那一层，真正的积压在底下的套接字
- * 写队列里（堆快照里那些 `{chunk, encoding, callback}`）。2026-10-18 复测证实：只看前者
- * 时闸门从不触发，内存照涨。所以顺着 socket 一起看，取较大值。
+ * 写队列里（堆快照里那些 `{chunk, encoding, callback}`）。实测只看前者时闸门从不触发，
+ * 内存照涨。所以顺着 socket 一起看，取较大值。
  */
 function bufferedBytesOf(res) {
   const own = Number(res.writableLength) || 0;

package/lib/shared/workspace-guard.js

@@ -2,23 +2,15 @@
 
 // 空清单守卫（工作区 / 会话列表共用）。
 //
-// 「没取到」与「真的什么都没有」在单份快照上长得一模一样：都是
-// `{ ok: true, items: [] }`。因此读取侧必须**如实报错**（见 lib/mobile/workspaces.js
-// 的 `host-workspace-list-degraded` 与 lib/mobile/sessions.js 的
-// `host-session-list-degraded`），守卫则负责兜住「宿主确实回了合法空列表」这种情况
-// ——它和真实删除无法区分，所以按时间兜底。
+// 「没取到」与「真的什么都没有」在单份快照上长得一模一样：都是 `{ ok: true, items: [] }`。
+// 读取侧必须如实报错（见 workspaces.js / sessions.js 的 `*-list-degraded`），守卫负责兜住
+// 「宿主确实回了合法空列表」——单看一份快照区分不了它和真实删除，所以按时间兜底。
 //
-// 后果（真机缺陷）：一份空快照会一路通过推送路径的 `.ok` 判定，被当成权威清单推给
-// 中转冻结下来。中转只在响应上附一个 `stale` 标记，而 App 根本不读它，于是下一次 15s
-// 轮询就把好数据覆盖成空 —— 侧边栏工作区整行消失、其下所有会话塌进「未分组」，
-// 设备仍显示「在线」（那是另一条独立的 /status 探测线），点不开，且全程零错误提示。
+// 一份空快照若被当成权威清单推给中转，下一次 15s 轮询就会把好数据覆盖成空：侧边栏工作区
+// 整行消失、会话塌进「未分组」，而且全程零错误提示。所以距上一次确认过的非空清单不到
+// graceMs 时拒绝空清单、保留上一份镜像；超过 graceMs 则放行，让真实删除也能收敛。
 //
-// 「用户真的把工作区/会话全删了」同样表现为空列表，单看一份快照区分不了，所以按时间兜底：
-// 距上一次确认过的非空清单还不到 graceMs 时拒绝空清单、保留上一份镜像；超过 graceMs
-// 则放行，让真实删除也能收敛，不会把侧边栏永久钉死在旧数据上。
-//
-// 抽成独立模块是为了能被真正单测（早期版本把这段逻辑内联在 lib/index.js 的闭包里，
-// 只能靠 grep 源码做契约测试，行为本身一次都跑不到）。
+// 抽成独立模块是为了能被真正单测。
 
 const fs = require('node:fs')
 

package/lib/shell/device-ota.js

@@ -7,12 +7,10 @@ import { movePath, readManifest, sha256Hex, unpackTarGz, verifyManifest } from '
 /**
  * OTA 包落在哪。
  *
- * 默认 `<DSH_HOME>/plugin-ota`，但外壳知道 profile 在哪之后会把它挪到**profile 里面**
- * （`<profile>/.dsh-mobile-ota`）。原因不是洁癖：DSH 宿主的 profile-resolution 拦截层
- * 只认 `profiles/` 树内的模块，树外的裸包名走的是原生解析 —— 而宿主提供的那批 peer
- * （`@deepseek-ai/dsh-tools` 之类）压根不在 profile 的 node_modules 里，于是 OTA 代
- * 第一句 `require('@deepseek-ai/dsh-tools')` 就 MODULE_NOT_FOUND（2026-10-17 真机：
- * 0.1.80 装载失败）。落在 profile 里之后，OTA 代与装进来的那一代走**同一条**解析链。
+ * 默认 `<DSH_HOME>/plugin-ota`，外壳知道 profile 在哪之后会把它挪进 profile 里面。原因是
+ * DSH 宿主对 `profiles/` 树外的模块走原生解析，而宿主提供的 peer 不在 profile 的
+ * node_modules 里，OTA 代第一句 require 就 MODULE_NOT_FOUND。落在 profile 里之后，OTA 代与
+ * 装进来的那一代走同一条解析链。
  */
 let storageRoot = ''
 export function configureOtaRoot(dir) {

package/lib/shell/manager.js

@@ -1,31 +1,17 @@
 /**
  * 代际装载器：把「插件实现」当成可以整代替换的东西。
  *
- * 起因：宿主进程启动时就把 profile 的插件树定死了，改一次插件代码就得**完整重启
- * DSH**（Node 缓存 realpath，换 profile 链接必须重启进程）。手机那边的主机是 systemd
- * 拉起来的，重启一条命令的事；桌面这边用户得自己退出再打开，而他不想每次都做这件事。
+ * 宿主启动时就把 profile 的插件树定死了，改一次插件代码就得完整重启 DSH（Node 缓存
+ * realpath）；桌面用户不想每次都做这件事，所以要能在进程里换代。
  *
- * ## 2026-10 改：npm 正式代与紧急 OTA 代并存
+ * 正式版本由 DSH 插件市场装进 profile，紧急 OTA 把完整包落在 profile 里，两者都由这里切换。
+ * pnpm 装新版会把 `node_modules/dsh-mobile-plugin` 指向一个全新的 store 目录 ——「新目录 =
+ * 新 realpath = 新 URL」，天然绕开 ESM 缓存；所以只要认出 profile 里当前装的是哪一份，把它
+ * 当成一代接上去就够了，不需要拷贝或校验。
  *
- * 正式版本由 DSH 插件市场装进 profile；紧急 OTA 将完整包落在 `$DSH_HOME/plugin-ota/`，两者都由代际装载器切换。正式版本安装仍通过 profile 里的 pnpm 完成，安装新版会把
- * `<profile>/node_modules/dsh-mobile-plugin` 这个链接指向**一个全新的 store 目录**：
- *
- *   <profile>/node_modules/dsh-mobile-plugin -> .pnpm/dsh-mobile-plugin@0.1.58/node_modules/dsh-mobile-plugin
- *
- * 「新目录 = 新 realpath = 新 URL」，正是当年必须靠 `.live/<releaseId>` 才能拿到的东西
- * （见 `importGeneration` 里 `?v=` 那一段：同一路径换代码是骗不过 ESM 缓存的）。所以这里
- * 只要**认出 profile 里当前装的是哪一份**，把它当成一代接上去就够了 —— 不需要拷贝、
- * 不需要下载，也不需要 sha256 校验（那是市场的活儿）。
- *
- * 一代 = 一个完整包目录，`package.json` 与 `lib/impl.js` 缺一不可：`lib/*.js` 内部有
- * 80 多处相对引用（`../shared/http-util` 之类），必须保持 `lib/` 这一层的相对结构；
- * 实现里还有 `require('../dsh-mobile-credentials/lib/credentials.js')` 这种跨包相对引用，
- * 而凭据包就嵌在插件包目录内部，所以一代是**自包含**的：回滚到旧代时连凭据版本一起
- * 回滚，不会出现「旧插件配新凭据」。
- *
- * 裸包名（`ws`、`@deepseek-ai/...`）依旧沿祖先目录解析：从 `<代>/lib` 往上会经过
- * `<代>/node_modules`、profile 的 `node_modules`，最终落在同一份插件自身依赖与 peer
- * 依赖上，与基础代解析到同一份 real path，不会出现两份实例。
+ * 一代 = 一个完整包目录，`package.json` 与 `lib/impl.js` 缺一不可：`lib/*.js` 内部有大量
+ * 相对引用，凭据包也嵌在插件包目录内部，所以一代是自包含的——回滚时连凭据版本一起回滚。
+ * 裸包名沿祖先目录解析，与基础代落到同一份依赖上。
  */
 
 import fs from 'node:fs'
@@ -249,8 +235,8 @@ function evictCommonJsTree(roots) {
  * 宿主对模块解析有一层拦截：**`profiles/` 树内**的模块，裸包名会先按 profile 的
  * 本地包解析、再回落到宿主自己那份；树外的模块走原生解析。而宿主提供的那批 peer
  * （`@deepseek-ai/dsh-tools` 等）并不在 profile 的 `node_modules` 里 —— 所以 OTA 包
- * 一旦落在树外，那一代 `require('@deepseek-ai/dsh-tools')` 就是 MODULE_NOT_FOUND
- * （2026-10-17 真机：0.1.80 装载失败）。位置挪进 profile 后，OTA 代与装进来的那一代
+ * 一旦落在树外，那一代 `require('@deepseek-ai/dsh-tools')` 就是 MODULE_NOT_FOUND。
+ * 位置挪进 profile 后，OTA 代与装进来的那一代
  * 走同一条解析链，不必再靠调用点逐个打补丁。
  *
  * 老位置残留的包顺手搬过来：换代失败时它还是磁盘上的回退包，不能在升级路径上丢。
@@ -282,8 +268,7 @@ function moveOtaRootIntoProfile() {
  * Node 只沿**自己的祖先目录**找 `node_modules`，而 OTA 落在
  * `<DSH_HOME>/plugin-ota/<version>/` —— 这条路径上没有任何一份 `node_modules`。于是
  * `lib/impl.js` 第一句 `import { z } from '@deepseek-ai/schemastery'` 就报
- * `Cannot find package`，一代整个装不起来（2026-10-17 真机：0.1.79 的 OTA 装载失败，
- * 外壳按规矩回滚到旧代，机器上什么都没变）。
+ * `Cannot find package`，一代整个装不起来。外壳按规矩回滚到旧代，机器上什么都没变。
  *
  * 修法是补上基础代本来就有、而 OTA 路径上没有的那两层软链：
  *   `<version>/node_modules`                    → profile 的 `node_modules`

package/lib/shell/ota-package.js

@@ -1,20 +1,15 @@
 /**
  * OTA 包（npm tarball）的读取、校验与落盘。
  *
- * 这一层存在的唯一理由是「换一台机器也照样能装」：以前解包是 `device-ota.js` 里的六十行
- * 手写代码，只认普通文件和目录，遇到 PAX 扩展头（macOS 的 tar 默认会带）、GNU 长文件名、
- * 长路径就直接抛「不支持的 tar 项」；反过来，包里少几个文件它又看不出来，于是装上去之后
- * 才在某一代运行时报「找不到某个 JS 文件」。这里把两件事一起解决：
+ * 这一层只为「换一台机器也照样能装」：手写解包只认普通文件和目录，遇到 PAX 扩展头、GNU 长名
+ * 或长路径就抛错，而包里少几个文件又看不出来。这里把两件事一起解决：
  *
- *  1. **解包要认得真实世界里的 tar**：ustar 的 prefix、PAX（`x` / `g`）、GNU 长名（`L` / `K`）
- *     都要能读；软链接、硬链接、设备文件要**明确拒绝**并说清原因（不静默跳过，否则会装出
- *     一个缺文件的代）。
- *  2. **装完要能证明它完整**：包里带一份 `lib/ota-manifest.json`（发布脚本生成，列出版本与
- *     每个文件的路径和字节数），解包后逐项核对。缺文件、大小不符都在**激活之前**失败，
- *     错误里直接点名是哪个文件。
+ * 1. 解包要认得真实世界里的 tar：ustar 的 prefix、PAX、GNU 长名都要能读；软链接、硬链接、
+ *    设备文件明确拒绝并说清原因，不静默跳过。
+ * 2. 装完要能证明完整：包里带一份发布时生成的清单（版本 + 每个文件的路径与字节数），解包后
+ *    逐项核对，缺文件或大小不符都在激活之前失败并点名。
  *
- * 手写 tar 解析而不是引依赖：这是发布链路上的一段自包含代码（OTA 包要能在一台刚装好
- * DSH 的机器上被解出来，不能要求它先装点别的），而 ustar 的头部格式是固定的 512 字节。
+ * 手写而不是引依赖：这是发布链路上要能在一台刚装好 DSH 的机器上跑的自包含代码。
  */
 
 import crypto from 'node:crypto'

package/lib/shell/runtime.js

@@ -1,22 +1,14 @@
 /**
  * 代际运行时：把「外壳」和「某一代实现」缝在一起，并负责换代那一刻的秩序。
  *
- * 外壳（`lib/index.js`）只做两件事：启动时激活版本最高的一代，以及把换代请求转给这里。
- * 实现侧完全不知道自己是被外壳装进来的 —— 它拿到的是一个普通的 cordis `Context`，
- * 照常 `ctx.effect(...)` / `ctx.webServer.register(...)` / `ctx.reflect.provide(...)`。
+ * 外壳只做两件事：启动时激活版本最高的一代，以及把换代请求转给这里。实现侧拿到的是一个普通
+ * 的 cordis `Context`，不知道自己是被外壳装进来的。
  *
- * ## 换代为什么必须串行、而且先停后起
+ * 换代必须串行、且先停后起：一代在 `apply` 里会注册同一条路径的路由（撞路径直接抛错）、绑
+ * sidecar、起镜像推送，只能先 dispose 旧代（每个 `ctx.effect` 反向清理），再装新代。
  *
- * 一个代在 `apply` 里会往宿主注册**同一条路径**的路由（`ctx.webServer.register` 撞路径会抛
- * `webserver: duplicate exact route`），还会绑 sidecar、起镜像推送。所以不能「先装新的再
- * 卸旧的」——只能先把旧代的 fiber dispose 掉（它的每个 `ctx.effect` 会反向执行清理：路由
- * 摘掉、子进程收掉），再装新的。这个文件里的 `swapping` 锁就是保证同一时刻只有一次换代。
- *
- * ## 让路
- *
- * 手机那边随时可能有一个请求在读事件流。直接 dispose 会把 `ctx.effect` 的清理跑在别人的
- * 请求中间。所以换代前先等 `inFlight` 归零，最多等 `DRAIN_TIMEOUT_MS`（等不到也照换——
- * 卡住的请求不该拖住一次修复性更新）。
+ * 换代前先等 `inFlight` 归零，最多等 `DRAIN_TIMEOUT_MS`——把清理跑在别人的请求中间会出事，
+ * 但卡住的请求也不该拖住一次修复性更新。
  */
 
 import { importGeneration, invalidateGeneration, resolveGeneration, resolveGenerations } from './manager.js'
@@ -199,7 +191,7 @@ export function createRuntime() {
    * 旧代先停、新代后起；新代起不来就回滚把旧代装回去，并把错误留在 `lastError` 里——
    * 「更新把自己弄挂了」必须能被看见，而不是静默少个插件。
    *
-   * `options.reread` 是给**开发机**的那条路（2026-10-19）：版本号与目录都没变，只是盘上
+   * `options.reread` 是给**开发机**的那条路：版本号与目录都没变，只是盘上
    * 那几个文件被改了。默认会走上面那句「身份一致就直接返回」，于是改完代码再触发也没有
    * 任何变化 —— 开发时看到的「改了不生效」就是这么来的。带上它就先把这一代从
    * `imported` 里作废、再让 `importGeneration` 清掉 CJS 子树，强制重新读盘。
@@ -288,7 +280,7 @@ export function createRuntime() {
   /**
    * 第一次激活；最高代装载失败时按优先级尝试保留的回退代；全失败则按固定间隔重试有限次。
    *
-   * 为什么要重试（2026-10-25 真机 404）：一次失败 = **整张控制面路由表都不在**，而设置页
+   * 为什么要重试：一次失败 = **整张控制面路由表都不在**，而设置页
    * 的「移动端」照样画得出来（客户端半边按包扫描，不看宿主 fiber 活没活），于是现场只表现成
    * 「读取宿主状态失败: HTTP 404」。失败最常见的原因恰好是**可能自己好**的：注入的服务
    * （typertGateway / apiProxy）比本插件晚就位、撞上 20s 装载上限，或者第一次装载撞上

package/lib/shell/self-check-after-swap.js

@@ -1,30 +1,16 @@
 /**
- * 换代之后的自检：新版装起来之后，**手机要打的那批接口**真的能用吗？不能就退回上一代。
+ * 换代之后的自检：新版装起来之后，手机要打的那批接口真的能用吗？不能就退回上一代。
  *
- * ## 为什么这一条不能交给手机
+ * 这条不能交给手机：装坏的后果是 App 连不上这台设备，那一刻手机上的回滚按钮发不出去。
+ * 必须由还活着的宿主做完，手机只在事后读到「上次装失败了，已自动退回 X」。
  *
- * 装坏的后果是「App 连不上这台设备」。那一刻手机上没有任何按钮发得出去 —— 让 App 去按
- * 「回滚」等于让一个已经断线的客户端去救自己的连接。所以这件事必须由**还活着的宿主进程**
- * 自己做完，手机那边只在事后读到一条「上次装失败了，已自动退回 X」。
+ * 判据是打本机的 `127.0.0.1:<宿主端口>`：200 且 `service: 'dsh-mobile-plugin'` 算活；401 也
+ * 算活（守卫先核 token，说明实现与守卫都在）；404 / 别的 service / 超时算死。连不上
+ * （ECONNREFUSED）不算数——那是宿主 webServer 自己没起来，与新代无关，退回去也救不了，
+ * 如实报 `skip`。
  *
- * ## 判据：问它自己的 `/health`，看回的是什么
- *
- * 不看日志、不猜堆栈，直接打本机的 `127.0.0.1:<宿主端口>`：
- *
- *  · 回 200 + `service: 'dsh-mobile-plugin'` → 活，路由挂上了；
- *  · 回 401 → 也活：移动端守卫先核 token 再谈路由，没带 token 回 401 说明实现与守卫都在；
- *  · 回 404 / 别的 service → **死了**：端口在、但插件那批路由没挂上，手机打过去就是这个 404；
- *  · 超时 → **死了**：连上了但不回包，多半是某个 handler 卡在等一个永远不来的依赖；
- *  · 连不上（ECONNREFUSED）→ **不算数**：那是宿主 webServer 自己没起来，与新代无关，
- *    退回去也救不了。如实报 `skip`。
- *
- * 最后那一条是这次刻意分开的：把「宿主没在监听」当成「新版坏了」会退掉一次其实成功的
- * 更新（开发机上跑测试时就是这么一种现场：假 webServer 有个端口号，但没有任何东西在听）。
- *
- * ## 端口从哪儿来
- *
- * 用宿主的 `ctx.webServer.port`（运行中那一份），不是配置里的默认值 —— 端口被改过之后，
- * 配置与实绑可能不同，按配置去问会问到一个没人监听的地方，于是「自检失败」全是假的。
+ * 端口用 `ctx.webServer.port`（运行中那份），不是配置里的默认值：端口被改过之后按配置去问
+ * 会问到一个没人监听的地方。
  */
 
 /** 自检的超时上限：本机环回，正常几十毫秒。给 3 秒已经很宽。 */