dsh-mobile-plugin 0.4.0 → 0.4.1

package/lib/mobile/questions.js

@@ -3,31 +3,15 @@
 /**
  * 手机端提问桥（DSH 0.2.x）：`ask_user_question` 与「计划评审」。
  *
- * ≤0.1.x 的宿主把提问当成 apiProxy 事件流上的 server-request：
- * `{rpcId, payload:{type:'question/requested', sessionId, questions}}`，手机凭**帧级 rpcId**
- * 回答（`/question/respond` 把 rpcId 回给宿主那张 pending 表）。0.2.x 把 apiProxy 删了，
- * 提问只剩一个**进程内** waterfall 钩子 `user-questions/request`（`dsh-user-questions`
- * 发起，`dsh-tool-ask-user` 与 `dsh-plan-mode` 是它的两个调用方），帧级 rpcId 随之消失，
- * 于是手机既收不到卡片、也没有能回传的 id。
+ * 0.2.x 删掉了 apiProxy，提问只剩一个进程内 waterfall 钩子 `user-questions/request`，帧级
+ * rpcId 随之消失，手机既收不到卡片、也没有能回传的 id。这里按新形状补起来，App 契约不变：
+ * prepend 钩子、自己铸 rpcId 推卡、`/question/respond` 找到挂起项把回答交回钩子。
  *
- * 这里按 0.2.x 的形状把这条通道补起来，**手机端契约一行不改**（App 仍然收
- * `question/requested` + 帧级 rpcId，仍然 POST `/question/respond`）：
+ * 钩子必须 prepend：宿主的转发器在桌面窗口开着时会一直等桌面回答、不调用 `next()`。下游
+ * 总是拿到请求，桌面那张卡与手机那张同时存在，谁先答用谁的，落定后广播 `question/resolved`。
  *
- *   1. 听 `user-questions/request` 钩子（**prepend**，理由与审批桥同一条：宿主的转发器
- *      `dsh-api-remotes` 在桌面窗口开着时会一直等桌面回答、不调用 `next()`）。铸一个自己的
- *      rpcId，把卡片推给正在看这个会话的手机，然后把请求挂住。
- *   2. 下游**总是**拿到请求（桌面那张卡照旧出现，`dsh-plan-mode` 也一样），与手机那张
- *      卡同时存在：手机答得早就用手机的，桌面答得早就用桌面的，落定后广播
- *      `question/resolved`，另一边那张卡被收掉。手机在看的时候也照转，否则桌面根本
- *      没有卡可显示 —— 桌面那张卡只由「被转发的请求」长出来，切回去也补不回来
- *      （2026-10-24 用户报「APP 有卡、桌面什么都没有」的就是这条）。
- *   3. `/question/respond` 拿 rpcId 找到挂起项，把回答交回钩子 —— 这才是真正让 agent
- *      继续往下跑的那一步。
- *
- * 「计划评审」不走另一条通道：`dsh-plan-mode` 的 `exit_plan_mode` 就是拿
- * `ctx.userQuestions.ask()` 问的（问题带 `intent.kind='plan-review'`、`detail` 是计划正文、
- * 选项里有一个「批准」标签），所以这道桥同时修好它。App 的问题面板本来就渲染
- * `detail` 与 `options`，计划正文直接显示在详情里。
+ * 「计划评审」不走另一条通道：`exit_plan_mode` 就是拿 `ctx.userQuestions.ask()` 问的
+ * （`intent.kind='plan-review'`，detail 是计划正文），这道桥同时修好它。
  */
 
 const { randomUUID } = require('node:crypto');
@@ -298,17 +282,12 @@ function installQuestionBridge(ctx) {
 /**
  * POST /api/mobile/v1/question/respond —— `{rpcId, sessionId, answer:{answers}}`。
  *
- * 先查本桥的挂起项；查不到就交回 `ctx.apiProxy.respond`（0.1.x 宿主那份真 apiProxy 才是
- * 它的归宿；0.2.x 的兼容桥会如实回 `host-unsupported`，于是落到下面那条 409）。
+ * 先查本桥的挂起项；查不到就交回 `ctx.apiProxy.respond`（0.1.x 真 apiProxy 的归宿；0.2.x
+ * 兼容桥会回 `host-unsupported`，落到下面那条 409）。
  *
- * ⚠️ `respond` 在两条通道上的返回形态**不一样**，这里必须两种都受得住：
- *   - 0.1.x 的真 apiProxy → `Promise<{accepted}>`；
- *   - 0.2.x 的兼容桥（`mobile/host-bridge.js`）→ **同步对象**
- *     `{result:{ok:false,error:{code:'host-unsupported'}}}`，它压根不是 Promise。
- * 早先这里直接 `.catch()`，于是在 0.2.x 上表达缺席的那一发会抛
- * `TypeError: ctx.apiProxy.respond(...).catch is not a function`，被路由守卫兜成
- * **500 internal** 而不是下面那句 409。手机端因此只看到「提交失败」的原始异常，
- * 而桌面那张卡还挂着 —— 用户看到的就是「APP 提交没到 DSH，还得回桌面重答一遍」。
+ * respond 在两条通道上的返回形态不一样：0.1.x 是 `Promise<{accepted}>`，0.2.x 兼容桥是同步
+ * 对象。同步对象上没有 `.catch`，直接链 Promise 会抛 TypeError 被路由守卫兜成 500，而不是
+ * 409，手机只看到「提交失败」的原始异常。
  */
 async function handleQuestionRespond(ctx, req, res) {
   const body = await readJsonBody(req);
@@ -349,14 +328,10 @@ async function handleQuestionRespond(ctx, req, res) {
 }
 
 /**
- * 把回答交回旧通道的 `ctx.apiProxy.respond`，**Promise 与同步对象两种返回都收**。
- *
- * 两条通道的形态不同（见 `handleQuestionRespond` 的注释）：0.1.x 是 Promise，0.2.x 的兼容桥
- * 是同步的 `{result:{ok:false,...}}`。同步对象上没有 `.catch`，所以不能在这里链 Promise。
- * 抛错与「通道说没有」一律折算成 null —— 调用方据此如实回 409，而不是把 500 抛给手机。
+ * 把回答交回旧通道的 `ctx.apiProxy.respond`，Promise 与同步对象两种返回都收。
  *
- * 兼容桥那种 `{result:{ok:false,error:{code:'host-unsupported'}}}` 里没有任何 `accepted`
- * 字段，`accepted !== true` 自然落到 409，不必单独判 code。
+ * 0.1.x 是 Promise，0.2.x 兼容桥是同步的 `{result:{ok:false,...}}`；同步对象上没有 `.catch`，
+ * 不能链 Promise。抛错与「通道说没有」一律折算成 null，调用方据此如实回 409。
  */
 async function respondViaLegacyProxy(ctx, message) {
   const proxy = ctx && ctx.apiProxy;

package/lib/mobile/references.js

@@ -3,29 +3,15 @@
 /**
  * 移动端「引用发现」API：把桌面端输入框里的 @文件 / @会话 补全补齐到手机上。
  *
- * 桌面端由 dsh-client-ui-reference 渲染：输入 @ 后浏览器同时发起
- * fileReferences/list 与 sessionReferenceResolver/candidates 两个 Remote 调用，
- * 结果按「文件在前、会话在后」的确定性顺序分组展示；选中文件插入普通 @路径 文本，
- * 选中会话插入宿主给的规范 mention（@[label](dsh-session:…)）。
+ * 两个宿主服务（fileReferences、sessionReferenceResolver）不在 apiProxy 上，是 Typert
+ * Remote 服务，手机侧经 host-bridge/transport.js 的 `invoke` 到达。
  *
- * 关键：这两个宿主服务 **不在 apiProxy 上** —— 它们是 Typert Remote 服务
- * （dsh-file-reference 的 fileReferences、dsh-session-reference 的
- * sessionReferenceResolver）。手机侧本来就能到它们：dsh-mobile-plugin 与宿主同进程，
- * lib/mobile/sessions.js 已经派发过 commands.execute，lib/mobile/plugins.js 也走同一条路
- * 读 pluginInventory —— 都经 host-bridge/transport.js 的 `invoke`，这里照搬。
+ * 两条接口只转发发现域，不做排序或截断之外的加工：
+ *  - GET /file-references → fileReferences.list
+ *  - GET /session-references → sessionReferenceResolver.candidates
  *
- * 两条接口（都只是转发宿主的发现域，不做任何排序或截断之外的加工）：
- *  - GET /api/mobile/v1/file-references?sessionId=…&query=…     → fileReferences.list
- *  - GET /api/mobile/v1/session-references?sessionId=…&query=…  → sessionReferenceResolver.candidates
- *
- * 参数按宿主的 **wire 名** 精确校验：两个方法都是 { agentId, query }，query 是普通
- * JSON 字符串（与 messageFeedback 的 { request } 包装不同）。
- *
- * 语义按宿主原文透传：
- *  - query 是「@ 或 @" 后面的那段文字」；空串表示列出全部（宿主自己限量）。
- *  - 文件候选只有 path/kind，目录候选带在路径尾部追加 / 的责任在客户端。
- *  - 会话候选的 mention 是宿主的规范写法，客户端必须原样发送，不能拿 label 重建。
- *  - 两个域各自独立降级：任一域不可用不影响另一个域（桌面端也是这个约定）。
+ * 参数按宿主 wire 名精确校验（都是 `{ agentId, query }`）。语义透传：空 query 列出全部；
+ * 会话候选的 mention 必须原样发送，不能拿 label 重建；两个域各自独立降级。
  */
 
 const { sendJson } = require('../shared/http-util');
@@ -52,17 +38,11 @@ function errorText(error) {
 /**
  * 经网关调一次引用发现。
  *
- * 走 host-bridge/transport.js 的 `invoke`：Peer 身份与「服务/方法不存在」的收敛都在
- * 那里，本域只做自己的 503/400 翻译。**不要自己直连网关** —— 0.2.1 起
- * 要求每个请求自带 Peer，绕过去就是对 undefined 读 `.signal`，手机端 @ 补全整块失效。
+ * 走 host-bridge/transport.js 的 `invoke`：Peer 身份与「服务/方法不存在」的收敛都在那里。
+ * 不要自己直连网关 —— 0.2.1 起每个请求都要自带 Peer，绕过去就是对 undefined 读 `.signal`。
  *
- * 注意返回值形状：网关回的是 **decode 后的业务结果本体**
- * （dsh-api-gateway/lib/index.js:112 `return decode(descriptor.result, result, …)`），
- * 那层 `{ok:true,value}` 外壳是浏览器传输（connection.rpc.intercept('/api')）加的，
- * invoke 不负责包。所以形状取决于服务声明的 result schema：
- *  - messageFeedback 声明的是 ok/error 联合 → invoke 回来就是 {ok:true,value}
- *  - fileReferences.list 声明的是 z.array(…) → invoke 回来就是一个裸数组
- * 两个都认，这样宿主以后把 schema 换成联合也不会坏。
+ * 网关回的是 decode 后的业务结果本体，`{ok,value}` 外壳是浏览器传输加的：messageFeedback
+ * 声明的是联合，回 `{ok:true,value}`；fileReferences.list 声明的是数组，回裸数组。两个都认。
  *
  * @returns {Promise<{value?: unknown, error?: {code: string, message: string}}>}
  */

package/lib/mobile/relay-control.js

@@ -3,35 +3,14 @@
 /**
  * 移动端「这台设备的中转与连接配置」：读写、配对码、吊销、重连、端口自检、地址候选。
  *
- * ## 为什么手机要能改这些
+ * 这些项不会让插件代码变，最坏结果只是这台电脑从网上找不到，而重连的主动权在手机这一侧，
+ * 所以能力面有意放开给已配对手机；控制面那条 `localOnly` 路由防的是「中转进来的人」，不能
+ * 复用，这里直接持有同一份 settings 与 schema 校验，两个入口写同一份真值。
  *
- * 这七八项（中转地址、注册密钥、设备名、局域网开关与端口、手机优先走哪条、配对策略、
- * 遥控总开关）从前只有一个入口：电脑上当机面板（`/api/relay/*`，全部 `localOnly`）。
- * 于是「手机上发现连不上、想改个中转地址」这件事必须回电脑前坐下才能做，而那往往正是
- * 人不在电脑前的时候。
+ * 改地址 / 关遥控 / 吊销 / 重连 / 重启后台服务会掐断承载当前请求的隧道，所以一律先把响应
+ * 吐完再动手，手机看到 200 只代表「已受理」，结果靠重连后读状态。
  *
- * 这些项与「装/卸插件」不是一类东西：它们**不会让插件代码变**，最坏结果只是这台电脑从
- * 网上找不到 —— 而重连的主动权在手机这一侧（换地址、重新配对、同网走局域网），不会像
- * 装坏插件那样死锁。所以这一层的能力面是**有意放开给已配对手机**的。
- *
- * ## 直接调内部实现，不绕本机 HTTP
- *
- * 控制面那几条 `localOnly` 路由是为了防「中转进来的人」而存在的：它们能读进程级错误账本
- * （含堆栈）、能吊销全部授权。手机这边不能复用那道口子，所以这里**直接持有同一份
- * `settings`（relay.json 的 config store）**，走同一套 schema 校验 —— 两个入口写的是同一
- * 份真值，不会出现「面板说改了、手机说没改」。
- *
- * ## 会掐断自己那条隧道的动作
- *
- * 改中转地址 / 关遥控 / 吊销全部 / 重连 / 重启后台服务：这几条一动手，承载**这一发请求**
- * 的那条隧道就可能立刻断。所以它们一律「先把响应吐完再动手」（`AFTER_RESPONSE_MS`），
- * 手机看到 200 只代表「已经受理」，结果靠断线重连之后读状态判 —— 与插件自更新那条
- * `apply` 同一个手感，理由也一样：响应发不出去的时候，任何「返回结果」的设计都是假的。
- *
- * ## 注册密钥只进不出
- *
- * `status()` 与二维码都不回显它（宿主那边本来就这么写），这里也照做：只接受写入，
- * 状态里只报「设没设」。手机上看不到它，也就没有「读出来再抄走」这条路。
+ * 注册密钥只进不出：状态里只报「设没设」，手机看不到它。
  */
 
 const { randomBytes } = require('node:crypto');

package/lib/mobile/rpc.js

@@ -3,20 +3,12 @@
 /**
  * 调宿主 apiProxy 的两扇门：`sessions.*` 与 `agentPresets.*`。
  *
- * 抽出来是因为这两扇门此前各有两份实现——sessions.js 一份、agent-presets.js 一份
- * callAgentPresets（逐字相同），而 callSessions 是 sessions.js 内部 21 处的公共依赖，
- * 一旦 sessions.js 被拆分，21 处调用就得跟着搬家。
+ * 抽出来是因为两扇门此前各有一份逐字相同的实现，而 callSessions 是 sessions.js 里二十几处
+ * 的公共依赖。这里收的不只是转发，还有两件必须跟着走的语义：
  *
- * 这里收的不只是「转发」：callSessions 还带两件必须跟着转发走的语义。
- *
- * 1. signal 必须显式传。宿主 `sessions.<method>(request, signal)` 的第二个参数是
- *    取消信号，宿主内部 `isAborted(signal)` 直接读 `signal.aborted`、不做
- *    undefined 兜底：search 这类会查 signal 的方法不传就抛
- *    `Cannot read properties of undefined (reading 'aborted')`。
- * 2. list 的在途合流。sessions.list 会扫描所有压缩日志；同一个 Host 可能同时收到
- *    桌面 completion、移动端列表和通知监控的请求，不合流就是一次刷新被放大成 N 次
- *    磁盘扫描。**但写后刷新（?fresh=1）不能搭在途 list 的车**：被合流到的那个请求
- *    发起于写入之前，拿回来的是旧列表，于是「刚改完又显示成改之前」。
+ * 1. signal 必须显式传：宿主内部直接读 `signal.aborted`，不做 undefined 兜底，不传就抛。
+ * 2. list 的在途合流：每次 list 要扫全部压缩日志，不合流会把一次刷新放大成 N 次扫描。
+ *    但写后刷新（`?fresh=1`）不能搭车 —— 被合流到的请求发起于写入之前，拿回的是旧列表。
  *
  * 依赖方向：rpc.js → history-derive（只为 rpcId 前缀常量），是叶子之上的薄层。
  */

package/lib/mobile/schedule.js

@@ -3,42 +3,17 @@
 /**
  * 移动端「定时任务」API：把宿主 `ScheduleService` 的四件事转给手机。
  *
- * 桌面端有一套完整的定时任务：任务挂在会话上，到点把 prompt 投进会话，运行记录留在
- * 宿主里。手机端此前一条都看不到 —— 既不知道这个会话排了什么，也没法读「上次跑到
- * 什么时候」或者删掉一条排错的任务。本文件是宿主 `schedule` 服务的移动端代理。
+ * 服务走同进程直查 `ctx.get('schedule')`，不写进 `inject`：它是 Typert Remote 服务、不在
+ * apiProxy 命名空间里，写进 inject 会因为老宿主没有这个服务而挡住整个插件。
  *
- * 服务走同进程直查 `ctx.get('schedule')`，与 mobile/directory-browse.js 取
- * `directoryPicker` 是同一个先例：它是 Typert Remote 服务，不在 apiProxy 的命名空间
- * 里，写进 `inject` 反而会因为老宿主没有这个服务而挡住整个插件。
+ * 四条接口：catalog（全部任务）、list（该会话的任务）、history（一条任务的运行记录）、
+ * delete（硬删）。update 不做：手机端没有编辑入口，接一条没人调的路只会多一份参数校验。
  *
- * 四条接口对应宿主的四个公开方法：
- *  - GET  /api/mobile/v1/schedule/catalog  → `catalog()`         全部任务（active + inactive）
- *  - GET  /api/mobile/v1/schedule/list     → `catalog()` 里筛出该会话的任务（**active + inactive**）
- *  - GET  /api/mobile/v1/schedule/history  → `history({...})`    一条任务的运行记录
- *  - POST /api/mobile/v1/schedule/delete   → `delete({...})`     硬删
+ * list 走 `catalog()` 再按 sessionId 筛，不用宿主的 `list({sessionId})`：后者只回还在跑的
+ * 任务、行上没有 sessionId / status，一次性任务跑完就会从手机上「凭空消失」。
  *
- * `update` 这一批不做，别顺手接上：手机端暂时没有编辑入口，接一条没人调的路只会多一份
- * 要维护的参数校验。
- *
- * 宿主 catalog 的每项是「裸记录 + sessionId + status + 可选 lastDelivery」。手机只认一种
- * 形状：sessionId 必须带上，状态统一收成 `state`，删除 / 历史 / 修改都必须带行上的
- * sessionId，否则宿主恒回 not_found。
- *
- * **`list` 为什么不用宿主的 `list({sessionId})`**（2026-10-23 改）：宿主那个方法只回
- * **还在跑**的任务、而且回的是裸记录（没有 sessionId / status）。于是手机上按对话看任务时，
- * 一次性任务跑完就从这个入口消失了 —— 用户看到的是「任务凭空没了」，实际只是「结束了」。
- * 现在改成从 `catalog()`（active + inactive 全都有、行上带 status）里按 sessionId 筛，
- * 手机端因此能列出这条会话的全部任务（含已结束），筛选里那三档也才真正有意义。
- * 代价是一次多拉这份目录，它是宿主内存里的账、不是磁盘扫描，与统一页那一发等价。
- *
- * 收敛规则与 mobile/jobs.js 同口径：必填（id / kind / title / sessionId）坏了丢整条，
- * 可选字段坏了只丢字段 —— 少一个「下次运行时间」只是不显示，整条消失才是信息丢失。
- * 超长一律截断而不是丢整条：宿主已经校验过形状，这里的上限只防异常宿主把手机端列表
- * 撑爆。
- *
- * 服务不存在（老宿主）必须回 503 而不是空列表：App 要能分辨「这台电脑没有这个功能」
- * 和「一条任务都没有」，后者画空状态、前者画「升级宿主」。宿主调用抛错走 502，把原文
- * 带给 App —— 定时任务这块的错误多半是宿主的，插件不该换成一句「操作失败」。
+ * 收敛规则与 mobile/jobs.js 同口径：必填字段坏了丢整条，可选字段坏了只丢字段，超长截断。
+ * 服务不存在（老宿主）回 503 而不是空列表，App 才能分辨「没有这个功能」和「一条都没有」。
  */
 
 const { sendJson, readJsonBody } = require('../shared/http-util');

package/lib/mobile/self-check.cjs

@@ -3,46 +3,19 @@
 /**
  * 内存自检台账：内存出问题之后，用来回答「当时到底堆在哪儿」。
  *
- * 起因：宿主进程内存涨到 3.5～5G，排查时手上只有 Activity Monitor 的一个总数，
- * 分不出「插件推的镜像在堆」「遗弃的流订阅在堆」还是「宿主自己」。所以这里把三件事
- * 一次性报出来：两个**进程**的内存、各路**活着的流数**、以及插件自己那几个
- * 只增不减的容器有多大。
+ * 一次性报出两个进程的内存、各路活着的流数，以及插件自己那几个只增不减的容器有多大。
  *
- * ## 最重要的一条：口径
+ * 口径：插件住在宿主进程里，没有独立内存可测。`hostProcess` 报的是整个宿主进程的
+ * `process.memoryUsage()`，不是「插件占了多少」；侧车是另一个进程，记在 `sidecarProcess`
+ * 下，两个数不能相加成「插件内存」。字段名与 `caveat` 按这个口径写死。
  *
- * **插件住在宿主进程里，没有独立内存可测。** `hostProcess` 报的是**整个宿主进程**
- * （DSH host）的 `process.memoryUsage()`——插件、宿主自身、其它插件、V8 的堆外缓冲
- * 全在这个数里。它不是「插件占了多少」。要判断「插件占多少」只能拿它和流数、镜像
- * 缓存估算字节一起看趋势（插件侧唯一能量化的是 `mirror.cachedBytes`，那还是估算）。
- * 字段名与 `caveat` 都按这个口径写死，别把它改名成 pluginMemory 之类。
+ * 数据全走既有通道：本进程 memoryUsage、worker 的 `/status` 快照（没上报就报 null 并记进
+ * `unavailable`，不拿 0 顶替）、局域网 `stats()`、镜像推送记账与缓存。
  *
- * 侧车（sidecar facade worker）是**另一个进程**（lib/sidecar-facade.cjs 的 fork），
- * 它的内存在 `sidecarProcess` 下，与宿主分列——两个数不能相加成「插件内存」。
+ * 做成 `createSelfCheck(deps)` 而不是单例：镜像缓存按 ctx 隔离，拿不到 ctx 就读不到。
  *
- * ## 数据从哪儿来（全走既有通道，没有新开一条）
- *
- * - 宿主进程内存：本进程 `process.memoryUsage()` / `v8.getHeapStatistics()`。
- * - 侧车进程内存、流数：**worker 的 `/status` 快照**（`sidecarLifecycle.getSnapshot()`，
- *   与 `tunnel`/`lan` 状态同一个来源）。worker 没上报对应字段时如实报 `null` 并记进
- *   `unavailable`——**不拿 0 顶替**：0 是「一条流都没有」，与「不知道」是两件事。
- * - 局域网直连路的流数：由注入的 `getLanProxyStats()` 提供，约定形状
- *   `() => ({ upstreamOpen, sseOpen }) | null`（`lan-proxy.js` 的 `stats()`）。
- * - 镜像：`mirror.getMirrorPush()` / `getPushFailures()`（不在本模块重复记账），
- *   缓存本体走 `session-cache.js` 的 `mirrorHistoryStateOf(ctx)`。
- * - 凭据库：`credentials.listActive().length`（凭据包只暴露「活跃」这一档）。
- *
- * ## 为什么是工厂而不是模块级单例
- *
- * `desktop-half-stats.cjs` 是单例：它只记进程级的计数。这份不一样——镜像缓存按
- * `ctx` 隔离（WeakMap），拿不到 ctx 就读不到。所以做成 `createSelfCheck(deps)`，
- * 由 control-plane 用注入的 ctx 建一次，而不是往模块级塞一个 ctx。
- *
- * ## 字节估算的口径
- *
- * `mirror.cachedBytes` 是**估算**，不是精确占用：字符串按 `String.length`（会话正文
- * 以 ASCII 为主，字符数≈字节）、数字 8 字节、布尔 4、每个对象/数组 24 字节固定开销。
- * 走查有节点预算（`MAX_WALK_NODES`），用尽时 `cachedBytesComplete` 为 false，
- * 此时那个数是**下限**而不是总量。
+ * `mirror.cachedBytes` 是估算（字符串按 length、数字 8 字节、对象固定开销）；走查有节点
+ * 预算，用尽时 `cachedBytesComplete` 为 false，那个数是下限。
  */
 
 const v8 = require('node:v8');

package/lib/mobile/session-cache.js

@@ -198,9 +198,8 @@ function lastTurnFactsOf(ctx) {
 /**
  * 标记「这条会话读过了」：记一个水位，把当前的完成 / 失败提醒清掉，返回清掉的条数。
  *
- * **不删条目**（旧实现是 delete）。删掉之后重建的条目会丢掉水位，于是「读过的轮次」
- * 会在下一次 history 折叠里重新点亮 —— 2026-10-17 真机：桌面读过之后手机上红点 / 绿点
- * 还在或者反过来。水位才是「这个时刻之前的轮次不算数」的唯一凭据。
+ * 不删条目：删掉之后重建的条目会丢掉水位，「读过的轮次」会在下一次 history 折叠里重新点亮。
+ * 水位才是「这个时刻之前的轮次不算数」的唯一凭据。
  */
 function markCompletionRead(ctx, deviceKey, sessionId, at = Date.now()) {
   const state = completionStates.get(ctx)?.get(deviceKey)?.get(sessionId);
@@ -317,14 +316,11 @@ function writeIdempotencyStateOf(ctx) {
 /**
  * 丢弃会话列表缓存（含正在构建的那一次）。
  *
- * `/sessions` 的完整响应会缓存 SESSION_LIST_CACHE_MS（10 秒），本意是压住手机轮询对
- * 桌面的冲击。但凡是**改变列表内容**的动作都必须立刻把它丢掉，否则 App 在自己刚做完
- * 的动作上看到的是最长 10 秒前的旧数据——真机上「重命名会话」保存后侧栏那一行纹丝不
- * 动、「归档会话」按下去那一行照旧留着，看着都像没生效（宿主的标题其实早就改了）。
+ * `/sessions` 的完整响应缓存 10 秒，本意是压住手机轮询对桌面的冲击；但凡是改变列表内容的
+ * 动作都必须立刻丢掉它，否则 App 在自己刚做完的动作上看到的是最长 10 秒前的旧数据。
  *
- * 只清 `value` 不够：若此刻正有一次构建在飞，它读的是变更前的历史，落地后会把旧数据
- * 又写回缓存。所以连 `promise` 一起清，并用 completion generation 兜住（与
- * handleSessionRead 同款守卫，见那里的注释）。
+ * 只清 `value` 不够：正有一次构建在飞时，它读的是变更前的历史，落地后会把旧数据写回缓存。
+ * 所以连 `promise` 一起清，并用 completion generation 兜住。
  *
  * @param {object} ctx
  * @param {string} [deviceKey] 只清这一台设备的缓存；缺省清掉该 ctx 下所有设备。
@@ -344,17 +340,15 @@ function invalidateSessionList(ctx, deviceKey) {
 }
 
 /**
- * 丢弃会话列表缓存，但**不抬 completion generation**。
+ * 丢弃会话列表缓存，但不抬 completion generation。
  *
- * 与 invalidateSessionList 的分工：那个用于「写操作刚发生」，必须连在飞构建与完成态
- * 一起作废；这个用于「宿主的清单内容变了，我（镜像推送调度器）先看见了」。后者在生成期
- * 每 500ms 就会发生一次（会话的 updatedAt 一直在动），如果也抬 generation，
- * buildSessionsResponse 里那句 `completionGenerationOf(...) === generation` 就永远不成立，
- * `confirmCompletionFromHistory` 再也执行不到 —— 侧栏的 completed / 红点会彻底不亮。
+ * 与 invalidateSessionList 的分工：那个用于「写操作刚发生」，必须连在飞构建与完成态一起
+ * 作废；这个用于「宿主的清单内容变了，镜像推送调度器先看见了」。后者每 500ms 就会发生一次，
+ * 若也抬 generation，`confirmCompletionFromHistory` 就再也执行不到，侧栏 completed / 红点会
+ * 彻底不亮。
  *
- * 所以在飞构建靠状态自带的「朝代」（droppedAt）而不是 generation 来作废：handleSessions
- * 建构建前记下朝代，落地时发现朝代变了就不把旧内容写回缓存。这样既不需要抬 generation，
- * 又不会出现「变更前发起的那次构建在变更后落地，把旧列表按新时间戳缓存 10 秒」。
+ * 所以在飞构建靠状态自带的「朝代」（droppedAt）作废：建构建前记下朝代，落地时发现变了就不
+ * 把旧内容写回缓存。
  *
  * @param {object} ctx
  * @param {string} [deviceKey] 只丢这一台设备的缓存；缺省丢掉该 ctx 下所有设备。

package/lib/mobile/session-file.js

@@ -3,29 +3,16 @@
 /**
  * 交付文件的字节（POST /api/mobile/v1/session/file）。
  *
- * 轮尾那张「交付文件」卡在桌面上点一下就用系统默认程序打开；手机上没有那条路 ——
- * 文件在电脑上，宿主只给了路径，App 必须先取回字节。这条路由就是那条通道。
+ * 轮尾那张「交付文件」卡在桌面上点一下就打开；手机上没有那条路，App 必须先取回字节。
  *
- * 三条边界同时成立：
+ * 三条边界：
+ * 1. 放行面 = 本会话工作区里的文件 ∪ 本会话 present 声明过的路径。前者判「解析后的落点是否
+ *    在 cwd 之下」，`../x` 落在外面就退回白名单，不在声明里就 403；后者是字符串全等的显式
+ *    声明，用于工作区之外的文件。放开工作区不等于能读这台电脑上的任意文件。
+ * 2. 相对路径按会话工作区解析：cwd 取自会话列表摘要；没有 cwd 的会话只能走 present 白名单。
+ * 3. 流式回写，不在插件进程里缓冲：几十 MB 的录屏不该整包躺在内存里。
  *
- *  1. **放行面 = 本会话工作区里的文件 ∪ 本会话 present 声明过的路径**（2026-10-25 用户拍板
- *     的第二条，见 docs/decisions.md）。前者的判法是「解析后的落点在 cwd 之下」：相对路径
- *     按 cwd 拼、绝对路径原样，然后整条路径必须在 cwd 里 —— 所以 `../x` 这种穿越落在
- *     cwd 之外，退回旧的那条白名单，不在声明里就 403。后者保持原样（`deliverables/presented`
- *     里显式声明过的、**字符串全等**），它的用处是工作区之外的文件也能交付（绝对路径、
- *     cwd 变了的老会话）。
- *
- *     **为什么敢放开工作区**：正文里模型写的 `[报告](docs/报告.md)` 就是这条路上的用户预期
- *     —— 手机上点一下能看，比「点了没反应」有意义得多；而这条会话的模型本来就能读同一个
- *     工作区，手机与电脑是同一个使用者，放宽的是「同一份工作区能不能在手机上看」，不是
- *     「能不能读这台电脑上的任意文件」（那仍然是 403，与不暴露 shell / 任意写入同一条边界）。
- *  2. **相对路径按会话工作区解析**：cwd 取自会话列表摘要（与 /session 同一个来源）。没有
- *     cwd 的会话只能走 present 那条白名单，相对路径解析不出来就回 409。
- *  3. **流式回写、不在插件进程里缓冲**：几十 MB 的录屏不该整包躺在内存里，与会话日志
- *     导出同一个理由。
- *
- * 取不到时两种失败要分得开：两条口子都不认这个路径就回 403（`outside-workspace`），
- * 认了、盘上没了回 404（`missing`）—— 前者是「这个路径不该被读」，后者是「文件被挪走了」。
+ * 两种失败分开：两条口子都不认就 403（`outside-workspace`），认了但盘上没了回 404（`missing`）。
  */
 
 const fs = require('node:fs');

package/lib/mobile/session-flags.js

@@ -17,21 +17,15 @@ const approvals = require('./approvals.js');
 const questions = require('./questions.js');
 
 /**
- * 宿主的两个**会话集合**（同一次 `workspace.list` 快照里拿到）：
+ * 宿主的两个会话集合（同一次 `workspace.list` 快照里拿到）：
  *
- *   - `archivedSessionIds`：已归档的会话。桌面端侧边栏据此把它们藏起来，而
- *     `sessions.list` 自身**不过滤**归档，所以移动端必须自己读这个集合：此前完全没读，
- *     App 的「归档会话」写是写成功了（宿主确实把 id 记进了 archivedSessionIds），列表却
- *     照旧把那一行发回手机，用户看到的就是一次毫无反馈的空操作。
- *   - `pinnedSessionIds`：已置顶的会话（宿主侧「最近置顶的在前」）。桌面端也只从这份
- *     快照读置顶，`sessions.list` 的摘要里没有置顶字段，所以移动端同样要自己读，
- *     否则 App 既画不出置顶标记、也排不到工作区最前。
+ * - `archivedSessionIds`：已归档的会话。`sessions.list` 自身不过滤归档，移动端必须自己读，
+ *   否则「归档」写成功了、列表却照旧把那一行发回手机。
+ * - `pinnedSessionIds`：已置顶的会话。摘要里没有置顶字段，不读这份快照就画不出置顶标记、
+ *   也排不到工作区最前。
  *
- * 两个集合合并成一次 RPC：它们同源同一次快照，而会话列表每 10 秒就会重建一次，
- * 分两次 `workspace.list` 等于平白给手机多塞一轮往返。
- *
- * 取不到时两个集合都回空（失败放开）：宁可多显示几行、少几个置顶，也不能因为一次
- * RPC 抖动让整个会话列表凭空变空。
+ * 两个集合合并成一次 RPC：同源同一次快照，而会话列表每 10 秒重建一次。取不到时都回空 ——
+ * 宁可多显示几行，也不能因为一次 RPC 抖动让整个列表变空。
  */
 async function workspaceSessionFlags(ctx) {
   try {

package/lib/mobile/session-mirror.js

@@ -63,12 +63,9 @@ async function buildSingleSessionMirror(ctx, sessionId, options = { limit: 200 }
 /**
  * Build mirror warm snapshots for the host mirror push.
  *
- * Two modes:
- *   1. High-priority (sessionIds provided): build ALL specified sessions at once,
- *      up to `limit` messages each.
- *   2. Background (no sessionIds): build from summaries, one session at a time,
- *      returning after each session so the caller can push incrementally.
- *      Processes at most `maxSessions` sessions per call, using cache when fresh.
+ * Two modes: high-priority (sessionIds given) builds all specified sessions at once; background
+ * (no sessionIds) builds from summaries one at a time so the caller can push incrementally,
+ * at most `maxSessions` per call, using the cache when fresh.
  *
  * @param {object} ctx - harness context
  * @param {Array} summaries - session list summaries from host
@@ -77,15 +74,11 @@ async function buildSingleSessionMirror(ctx, sessionId, options = { limit: 200 }
  * @param {string[]} [options.sessionIds] - specific sessions to build (high-priority)
  * @param {number} [options.limit=200] - max messages per session (capped at 200)
  * @param {number} [options.maxSessions=32] - max sessions to build in one call
- * @param {boolean} [options.noCache=false] - 完全绕开时间型缓存（既不读也不写）。
- *   事件驱动的推送必须传它：那个缓存只认「宿主抬了 updatedAt」这一种内容变化，
- *   一条新消息落盘而摘要还没变时，读缓存会把上一份正文当成这一份发出去。
- *   注意**不能**靠「传一个必然不同的 updatedAt」来绕（调用方以前就是这么干的）：
- *   指纹是 `updatedAt:running:limit`，同一个毫秒里的两次推送指纹相同，照样命中旧正文。
- * @returns {Promise<object>} messages map { [sessionId]: { ok, items, lastSeq, hasMore } }
- *   In background mode (no sessionIds), also sets _moreSessions on the result when
- *   there are remaining sessions beyond maxSessions, and _builtCount for how many
- *   were actually built this call.
+ * @param {boolean} [options.noCache=false] - 完全绕开时间型缓存（既不读也不写）。事件驱动的
+ *   推送必须传它：缓存只认「宿主抬了 updatedAt」这一种变化，新消息落盘而摘要未变时会把上一份
+ *   正文当成这一份发出去。也不能靠传一个必然不同的 updatedAt 来绕：同一毫秒的两次推送指纹相同。
+ * @returns {Promise<object>} messages map { [sessionId]: { ok, items, lastSeq, hasMore } }；
+ *   后台模式还会带 _moreSessions（是否还有剩余会话）与 _builtCount（本次真正构建了几个）。
  */
 async function buildMirrorWarmSnapshots(ctx, summaries, activeSessionId, options = {}) {
   const maxSessions = Math.max(1, Math.min(Number(options.maxSessions) || 32, 256));

package/lib/mobile/session-models.js

@@ -165,9 +165,9 @@ async function buildModelsSnapshot(ctx, sessionId) {
 
 /** GET /api/mobile/v1/session/models?sessionId=…（token）
  * 返回会话当前模型选择与可用模型目录（透传宿主 session.models）。
- * 响应：{ ok, current:{provider,model,reasoningEffort?}, defaultModel:{provider,model,reasoningEffort?}, routable, groups:[{id,name,models:[{id,name,description?,reasoning?}]}], options?:[{id,title,value,choices:[{id,name,description?}]}], failures:[{id,name,message}] }
- * `current` 是**这个会话**实际会用的；`defaultModel` 是全局默认（宿主新建会话时的落点）。
- * `options` 是当前渠道的附加选项行（速度、输出详略……），没有就是没有这个字段。
+ * 响应：{ ok, current, defaultModel, routable, groups, options?, failures }。
+ * `current` 是这个会话实际会用的，`defaultModel` 是全局默认（新建会话的落点），
+ * `options` 是当前渠道的附加选项行，没有就没有这个字段。
  */
 async function handleModels(ctx, req, res) {
   const url = new URL(req.url, 'http://x');

package/lib/mobile/session-schedule-mark.js

@@ -1,23 +1,17 @@
 'use strict';
 
 /**
- * 会话行左边那只时钟：**这一条会话有没有还在生效的自动化任务**。
+ * 会话行左边那只时钟：这一条会话有没有还在生效的自动化任务。
  *
- * 桌面上那个标记在 `@deepseek-ai/dsh-client-ui-schedule` 的 `SessionScheduleMark`：它占
- * 会话行标题前那格 16px，画一颗 14px 的 `IconClockOutlineRegular`；只在 「这一行自己的
- * 主状态是空闲」时才挂得上（有审批 / 有新消息 / 正在跑时，那一格留给状态点），归档行那格
- * 留空。手机端此前没有这个标记，用户在桌面上排了定时任务，手机上那条会话看不出任何区别。
+ * 桌面上那个标记只在会话行的主状态空闲时挂得上（有审批 / 新消息 / 正在跑时那格留给状态点），
+ * 归档行留空；手机端此前没有这个标记。
  *
- * 数据从宿主的任务目录来：`schedule.catalog()` 一次给出全部任务的 sessionId + status，
- * 按 `status === 'active'` 收成一份「哪些会话有活动任务」的集合，列表每行只要查表。**不**
- * 每行发一次 `schedule/list` —— 会话列表每 10 秒重建一次，逐行请求等于每轮几十次往返。
+ * 数据从宿主的任务目录来：`schedule.catalog()` 一次给出全部任务的 sessionId + status，按
+ * `status === 'active'` 收成集合，列表每行查表。不逐行发 `schedule/list` —— 会话列表每 10 秒
+ * 重建一次，逐行请求等于每轮几十次往返。
  *
- * 三条取舍：
- *  - **服务不在就当没有任务**（老宿主 / 极简 profile 没装）：时钟是提示性信息，为它让整个
- *    会话列表失败是拿主要功能换装饰；
- *  - **读失败也当没有**，但只吞这一条，不缓存：下一个 10 秒周期照常重问，宿主的
- *    `schedule/changed` 与目录本身都是活的；
- *  - 只看 `active`：一次性任务投完就自动结束（`status` 转 inactive），桌面上那颗也跟着消失。
+ * 三条取舍：服务不在（老宿主 / 极简 profile）就当没有任务；读失败也只吞这一条、不缓存，
+ * 下个周期照常重问；只看 active，一次性任务投完转 inactive 后标记自然消失。
  */
 
 /** 目录一次最多收多少条（与 schedule.js 的 SCHEDULE_MAX_ENTRIES 同量级，这里只用来防异常宿主）。 */

package/lib/mobile/session-send.js

@@ -43,21 +43,15 @@ function singleTextOf(content) {
 }
 
 /**
- * 经网关执行 slash 命令（commands.execute——桌面 Web 端同一条派发路径：
- * 命令注册表命中才执行，绝不经 session.prompt 发给模型；agent 由 agentId 经同一
- * agent 查找器解析，与 session.prompt 的 turnAgentFor 同源，支持冷会话自动 resume）。
+ * 经网关执行 slash 命令（commands.execute，桌面 Web 端同一条派发路径：命令注册表命中才执行，
+ * 绝不经 session.prompt 发给模型；agent 由 agentId 经同一查找器解析，支持冷会话自动 resume）。
  *
- * ⚠️ args 的键名必须**恰好**是宿主 descriptor 的 wire 名（typertGateway 的
- * assertExactArguments 只认这组名字，多一个少一个都是 gateway/arguments-invalid）。
- * descriptor：`@deepseek-ai/dsh-commands#commands/execute`，scope wire = agentId，
- * 参数 = line + submittedAttachments（encoded images 与 staged file receipts，
- * 按提交顺序排列，纯命令调用传空数组即可）。
- * 这里曾经写成 `images: []`——少了 submittedAttachments 又多了 images，导致
- * /permission、/plan 等**所有** slash 命令 400；形状守卫见
- * test/commands-execute-shape.test.cjs（改这里必须同步那张表）。
+ * args 的键名必须恰好是宿主 descriptor 的 wire 名：scope = agentId，参数 = line +
+ * submittedAttachments（encoded images 与 staged file receipts，按提交顺序，纯命令传空数组）。
+ * 多一个少一个都是 gateway/arguments-invalid，形状守卫见 test/commands-execute-shape.test.cjs。
  *
- * @returns {execution} 派发成功（CommandExecution|undefined，undefined=未知命令/语法不符）
- *   | {error} 查找或派发失败 | {missing} 网关服务未组合（调用方回退普通消息）
+ * @returns {execution} 派发成功（undefined=未知命令/语法不符）| {error} 查找或派发失败
+ *   | {missing} 网关服务未组合（调用方回退普通消息）
  */
 async function executeCommand(ctx, sessionId, line) {
   // 走 host-bridge/transport.js 的 invoke：Peer 身份与「服务/方法不存在」的收敛都在
@@ -82,8 +76,7 @@ function promptOnce(ctx, clientMessageId, payload) {
   // 把这一发认回去的身份一起送进宿主的 prompt 请求（`request.requestId`，见
   // host-bridge/endpoints.js）。宿主要是不认识它，user 消息的 `source.rpcId` 就是那个
   // 端点自己生成的 `mobile-prompt-<uuid>` —— App 那边 `clientMessageId` 永远对不上，
-  // 只能靠「同文本 + 同图数」猜着认领乐观行（2026-10-20 真机：自己发的图一直「发送中」，
-  // 因为实时帧里的图还被漏读，张数一对不上就彻底认领不了）。
+  // 只能靠「同文本 + 同图数」猜着认领乐观行（实时帧里的图一旦漏读，张数对不上就彻底认领不了）。
   const request = clientMessageId ? { ...payload, requestId: rpcId } : payload;
   if (!clientMessageId) return callSessions(ctx, 'prompt', request, rpcId);
   // 同一个 clientMessageId 在本会话里只承诺一次：内核重试、以及隔了几分钟用户手点的
@@ -176,14 +169,13 @@ async function handleSend(ctx, req, res) {
   sendJson(res, 200, { ok: true, accepted: true });
 }
 
-/** GET /api/mobile/v1/commands?sessionId=…（token）：会话有效命令目录（与桌面 Web 端命令面板
- * 同源——commands.list，即服务端命令注册表对该 agent 生效的完整清单）。
+/** GET /api/mobile/v1/commands?sessionId=…（token）：会话有效命令目录（commands.list，与桌面
+ * Web 端命令面板同源）。
  * 响应：{ ok, items:[{name, description, input?:{hint}}] }；网关未组合或失败时降级为空清单，
- * 客户端菜单据此只展示真实可执行的命令（不再硬编码）。
+ * 客户端菜单据此只展示真实可执行的命令。
  *
- * 失败一律降级成空清单是**刻意设计**：输入区不能因为目录拉不到就报错。代价是这个端点
- * 出问题时手机上看不出任何提示，「+」菜单静默只剩媒体与文件两行 —— 2026-10 宿主升到
- * 0.2.1 要求每个请求自带 Peer，这条路径没跟上，用户看到的就是「目标、计划、指令全没了」。 */
+ * 失败一律降级成空清单是刻意设计：输入区不能因为目录拉不到就报错。代价是这个端点出问题时
+ * 手机上看不出提示，「+」菜单静默只剩媒体与文件两行。 */
 async function handleCommands(ctx, req, res) {
   const sessionId = new URL(req.url, 'http://x').searchParams.get('sessionId');
   if (!sessionId) return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '缺少 sessionId' } });