dsh-mobile-plugin 0.2.0 → 0.2.2

package/README.md

@@ -138,7 +138,7 @@ npm test
 1. 跑 `node scripts/bump-version.mjs` 更新版本号（演示页的 `DEMO_VERSION` 会一起改，别手改）。
 2. 改过 `React/` 就跑 `cd React && pnpm run build`。
 3. 提交这次发版该带的文件，别 `git add -A`。
-4. 在**主仓**的插件目录跑 `npm run release:check`。它按固定顺序查六件事：是不是在主仓里（跨仓对账要读 `app/`）、版本号与 tag（三段 `0..999`、这个 tag 没打过、不比上一版低）、工作区干不干净、面板产物有没有跟上面板源码、整套测试、真打一次包看文件清单。任何一步红就停，并说明该修哪里。**它要求在提交之后跑**，因为查的是「发出去的那一份」。
+4. 在**主仓**的插件目录跑 `npm run release:check`。它按固定顺序查六件事：是不是在主仓里（跨仓对账要读 `app/`）、版本号与 tag（三段 `0..999`、这个 tag 没打过、不比上一版低）、工作区干不干净、面板产物跟不跟得上源码（拿当前源码真重建一次，与盘上那份逐字节比）、整套测试、真打一次包看文件清单。任何一步红就停，并说明该修哪里。**它要求在提交之后跑**，因为查的是「发出去的那一份」。
 5. 把提交同步到公开仓库 `WNLUO/dsh-mobile-plugin`。
 6. 推一个与版本号同名的 tag（版本 0.1.99 就推 `v0.1.99`）。那个仓库的 `.github/workflows/publish.yml` 会跑测试并直接发布，不需要人在浏览器里点二次验证 —— 它走 npm 的 trusted publishing（OIDC），npm 认的是这条流水线而不是某个令牌。
 7. 等流水线绿。它末尾自己会核 `npm view dsh-mobile-plugin version`，你也可以手动看一眼。

package/lib/impl.js

@@ -27,7 +27,7 @@ const { viaChannel } = require('./shared/via-header')
 const { createSidecarLifecycle } = require('./sidecar-lifecycle.cjs')
 const { createMirrorPusher } = require('./mirror/pusher.cjs')
 const { randomBytes } = require('node:crypto')
-const { lanUrls, advertisedCandidates, orderCandidates, ipv6Candidates } = require('./relay/lan-network.cjs')
+const { lanUrls, advertisedCandidates, phoneCandidates, ipv6Candidates } = require('./relay/lan-network.cjs')
 const { resolvePort } = require('./relay/port-allocator.cjs')
 const { createPreviewService } = require('./relay/preview.js')
 // 本机设备凭据库：/api/relay/revoke-all 必须同时吊销局域网直连的 dshc_ 凭据，
@@ -98,6 +98,8 @@ export const RemoteControlSettingsSchema = z.object({
   // 手机优先用哪条地址：空 = 不指定（按宿主网卡优先级排）。选择只挪候选顺序、不删候选，
   // 理由与边界见 relay/lan-network.cjs 的 orderCandidates 与 relay.json 那条地图条目。
   preferredLanAddress: z.string().max(64).default(''),
+  // 用户手填的直连地址（`manualLanUrl`，内网穿透域名）也随二维码一起走，见 lan-network.cjs。
+  manualLanUrl: z.string().max(200).default(''),
 })
 
 
@@ -115,6 +117,7 @@ function configOf(state) {
     // 不会把它回显给手机、二维码或日志。
     registerSecret: typeof state.registerSecret === 'string' ? state.registerSecret : '',
     preferredLanAddress: typeof state.preferredLanAddress === 'string' ? state.preferredLanAddress : '',
+    manualLanUrl: typeof state.manualLanUrl === 'string' ? state.manualLanUrl : '',
   }
 }
 
@@ -173,7 +176,9 @@ function createConfigStore(state) {
 function pairingPayload(state, lanPort) {
   const port = Number.isInteger(lanPort) ? lanPort : state.lanPort
   // 面板上选过的「手机优先用这条」在这里兑现：只挪到最前，其余继续当兜底（App 按顺序挨个试）。
-  const candidates = state.lanEnabled ? orderCandidates(advertisedCandidates(port), state.preferredLanAddress) : []
+  const candidates = state.lanEnabled
+    ? phoneCandidates(advertisedCandidates(port), { preferred: state.preferredLanAddress, manual: state.manualLanUrl })
+    : []
   const urls = candidates.map(candidate => candidate.url).filter(Boolean)
   const relayUrl = state.relayUrl || ''
   const payload = {
@@ -468,8 +473,8 @@ function apply(ctx) {
     // 一进来就 ReferenceError。同一个 apply() 里给 createStatusView 传的是
     // `sidecarLifecycle.getSnapshot`，两处不一致才让这个笔误活了下来。
     getSidecarSnapshot: sidecarLifecycle.getSnapshot,
-    // 移动端路由表那边叫它「局域网候选」，取的是同一份私网优先的清单。
-    safeLanCandidates: advertisedCandidates,
+    // 移动端那边的「局域网候选」：私网优先的清单 + 用户手填的直连地址（网卡扫不出的域名）。
+    safeLanCandidates: (port) => phoneCandidates(advertisedCandidates(port), { manual: state.manualLanUrl }),
     // IPv6 直连候选单独一份：App 拿它单开一条通道、和公网中转比速度，不掺进上面那份的排序。
     safeIpv6Candidates: ipv6Candidates,
     lanPortInUse: advertisedLanPort, // LAN 候选用实绑端口

package/lib/index.js

@@ -158,7 +158,8 @@ export function apply(ctx) {
     .then(() => {
       log('info', 'dsh-mobile-plugin: 已装载 %s（来源 %s）', runtime.status().version, runtime.status().source)
       // 每 10 分钟让已落盘的正式版接管 OTA，并补上「盘上比运行中新」的那一次换代；
-      // 自动安装仍由开关控制。补换代不受开关管：它不下载任何东西，只是让已经在盘上的代码生效。
+      // 自动安装仍由开关控制，开着就**不等正在跑的对话**（`auto` 那一档，见 update-install）。
+      // 补换代不受开关管：它不下载任何东西，只是让已经在盘上的代码生效。
       const timer = setInterval(() => {
         deviceOta.reconcileOfficial()
           .then(() => updater.reconcileInstalledGeneration({ runtime, log }))

package/lib/mobile/credential-upgrade.js

@@ -14,10 +14,16 @@
  * 不这么做就只能让用户重新扫一次码。升级之后所有流量仍由这把钥匙端到端加密。
  *
  * 换成什么不在本次判断里：拿到完整一套（凭据 + 密钥 + 标识）才回补丁，缺一样就当没升级。
+ *
+ * **请求体必须现读**（2026-10-25 修）：这条路服务的恰好是协议 v1 的老会话，而老会话发的
+ * 是明文 —— 守卫只为「带信封」的那条路预先解好 `req.body`，明文请求的字节还挂在 socket 上
+ * 没人读过。原来这里直接取 `req.body`，于是永远拿到空对象、宿主每次都回「没升级」，手机
+ * 那边一次都没成功过（真机表现是「App 与插件都更新了，设备行仍旧写链路未加密」）。
+ * 现在与其它移动端路由同一条读法（`readJsonBody`：`req.body` 有就用，没有就读流）。
  */
 
 const crypto = require('node:crypto');
-const { sendJson } = require('../shared/http-util.js');
+const { sendJson, readJsonBody } = require('../shared/http-util.js');
 const { DEVICE_KEY_RE, KEY_ID_RE } = require('../shared/e2ee-pair.js');
 
 /** 请求出示的设备凭据：独立头优先，`Authorization` 只用于兼容早期客户端。 */
@@ -51,14 +57,16 @@ function deviceSecretOf(body) {
  * @param {object} res
  * @param {{ instanceId: string, store: object, log?: Function }} deps
  */
-function handleCredentialUpgrade(req, res, deps) {
+async function handleCredentialUpgrade(req, res, deps) {
   const instanceId = String((deps && deps.instanceId) || '');
   const store = deps && deps.store;
   if (!store) return sendJson(res, 503, { ok: false, error: { code: 'unavailable', message: '凭据库不可用' } });
 
   const presented = presentedCredential(req);
   const record = presented ? store.lookup(presented, instanceId) : null;
-  const body = req.body && typeof req.body === 'object' ? req.body : {};
+  // 见文件头：明文请求的体没人读过，必须在这里现读（读法与其它移动端路由一致）。
+  const parsed = await readJsonBody(req, 64 * 1024);
+  const body = parsed && typeof parsed === 'object' ? parsed : {};
   const meta = body.device && typeof body.device === 'object' ? body.device : body;
   const deviceId = String(meta.deviceId || meta.id || (record && record.deviceId) || '');
 

package/lib/mobile/directory-listing.js

@@ -0,0 +1,144 @@
+'use strict';
+
+/**
+ * 手机端右栏「文件浏览器」的目录列表：**文件与文件夹都列**，每条带类型、大小、修改时间。
+ *
+ * 与 `/directory/list` 的分工：那条是「为设备挑一个工作区目录」用的，走宿主 directoryPicker，
+ * 只列**能进去的目录**、每条只有 `{name,path,hidden}`（见 lib/mobile/workspaces.js）。右栏
+ * 要的是「这个目录里有什么」——文件也是内容，而且要知道类型、大小、修改时间，所以那条路
+ * 一个字段都对不上。老那条**一个字都不改**：选目录那条流程还挂在它上面。
+ *
+ * 这条直接读宿主自己的文件系统，**不经 directoryPicker 网关**。能力面没有因此变大：宿主
+ * 那份 browse 后端与本地兜底原语（lib/mobile/directory-browse.js）本来都是全文件系统范围、
+ * 没有白名单，`workspace.create` 也接受任意已存在目录；而「桌面 profile 宿主 + 手机远程连」
+ * 这一格宿主只服务 native，经网关只会拿到那句 `needs the browse capability`，右栏一个条目
+ * 都没有。策略原语（隐藏项标记、上限、面包屑）直接 import 那份副本，不抄第二份。
+ *
+ * 契约（App 侧 app/src/services/viewmodels/apiPaths.ts 的 directoryListing 同时按这份改）：
+ *   - `path` 可选、绝对路径；缺省 / 空串 / 全空白 = 被控端主目录（os.homedir()）。相对路径
+ *     直接 400 —— 不拿宿主进程的当前目录去猜，那是另一个语义；
+ *   - entries 名字升序（**大小写不敏感**），文件与文件夹混在一份里，分组由客户端做；
+ *   - hidden = 名字以 '.' 开头，照旧标记但返回，过滤交给客户端；
+ *   - kind 由 stat 得出（**跟随符号链接**）：目录是 'folder'，其余是 'file'，指向目录的
+ *     链接算 'folder'；
+ *   - size（字节）/ modified（epoch 毫秒）**只对文件给**；单条 stat 失败（断链、权限）按
+ *     'file' 返回且不带这两格 —— 一个坏条目不许把整条列表带走；
+ *   - 上限复用 directory-browse.js 的 DEFAULT_MAX_ENTRIES，超了截断并置 truncated = true；
+ *   - crumbs 复用 directory-browse.js 的 ancestryCrumbs（根 → 当前），形状与选目录那条一致。
+ * 失败一律 400 + `{ ok:false, error:{ code, message } }`，code 取 bad-request / not-found /
+ * not-directory / permission，message 是简短英文，人话由 App 侧自己的字典翻。
+ */
+
+const { opendir, stat } = require('node:fs/promises');
+const { join, resolve } = require('node:path');
+
+const { sendJson } = require('../shared/http-util');
+const { DEFAULT_MAX_ENTRIES, ancestryCrumbs, fullyQualified, homeDirectory } = require('./directory-browse.js');
+
+/** 400 信封：与其余移动端接口同形，App 按 code 翻人话。 */
+function fail(res, code, message) {
+  return sendJson(res, 400, { ok: false, error: { code, message } });
+}
+
+/** 任意抛出值 → 文案（abort reason 之类可以不是 Error）。 */
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** 一次失败的 syscall → 契约里那四个码之一。 */
+function codeOf(error) {
+  const raw = error && typeof error === 'object' ? error.code : undefined;
+  if (raw === 'EACCES' || raw === 'EPERM') return 'permission';
+  if (raw === 'ENOENT' || raw === 'ENOTDIR') return 'not-found';
+  return 'bad-request';
+}
+
+/**
+ * 名字升序、大小写不敏感（契约）。折成同一个主权重后仍视为相同的（`README.md` 与
+ * `readme.md`）用码位序兜底：否则比较器回 0，顺序就跟 readdir 的返回顺序走，同一个目录
+ * 两次请求可能给出不同顺序。
+ */
+function compareNames(a, b) {
+  const folded = a.localeCompare(b, undefined, { sensitivity: 'base' });
+  if (folded !== 0) return folded;
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** 一条列表行：stat 跟到最终目标上，目录为 folder，其余为 file（断了也照样是 file）。 */
+async function listingRow(directory, name) {
+  const path = join(directory, name);
+  const row = { name, path, hidden: name.startsWith('.') };
+  let stats = null;
+  try {
+    stats = await stat(path);
+  } catch {
+    // 断链 / 权限：这一条按 file 返回、不带 size 与 modified，整条列表继续。
+  }
+  if (stats && stats.isDirectory()) {
+    row.kind = 'folder';
+    return row;
+  }
+  row.kind = 'file';
+  if (stats) {
+    row.size = stats.size;
+    row.modified = Math.round(stats.mtimeMs);
+  }
+  return row;
+}
+
+/**
+ * GET /api/mobile/v1/directory/listing?path=…（token，path 缺省 = 被控端主目录）
+ *
+ * 200：`{ ok:true, listing:{ path, home, crumbs, entries, truncated } }`。
+ * 名字必须整体排序（大小写不敏感）才谈得上「升序」，所以这里读全量名字再截断：上限约束的
+ * 是随响应下发的行数与后面逐条 stat 的次数，那两样才是这条路的成本。
+ */
+async function handleDirectoryListing(_ctx, req, res) {
+  const url = new URL(req.url, 'http://x');
+  const asked = (url.searchParams.get('path') || '').trim();
+  if (asked && !fullyQualified(asked)) {
+    return fail(res, 'bad-request', `cannot list "${asked}": not a fully qualified path`);
+  }
+  const home = homeDirectory();
+  const target = resolve(asked || home);
+  let info;
+  try {
+    // 先 stat 一次：它把「不存在」「不是目录」「权限不够」三件事分开，也跟随符号链接
+    //（指向目录的链接按目录列）。opendir 在非目录上的报错各平台不一致，分不出这三种。
+    info = await stat(target);
+  } catch (error) {
+    return fail(res, codeOf(error), `cannot list ${target}: ${messageOf(error)}`);
+  }
+  if (!info.isDirectory()) {
+    return fail(res, 'not-directory', `cannot list ${target}: not a directory`);
+  }
+
+  const names = [];
+  try {
+    const level = await opendir(target);
+    try {
+      for (;;) {
+        const dirent = await level.read();
+        if (dirent === null) break;
+        names.push(dirent.name);
+      }
+    } finally {
+      await level.close();
+    }
+  } catch (error) {
+    return fail(res, codeOf(error), `cannot list ${target}: ${messageOf(error)}`);
+  }
+
+  names.sort(compareNames);
+  const truncated = names.length > DEFAULT_MAX_ENTRIES;
+  const kept = truncated ? names.slice(0, DEFAULT_MAX_ENTRIES) : names;
+  const entries = [];
+  for (const name of kept) entries.push(await listingRow(target, name));
+
+  sendJson(res, 200, {
+    ok: true,
+    listing: { path: target, home, crumbs: ancestryCrumbs(target), entries, truncated },
+  });
+}
+
+module.exports = { handleDirectoryListing };

package/lib/mobile/history-derive.js

@@ -170,8 +170,14 @@ function buildToolResultMap(events) {
  * `items` 里的 tool-call 块本来就是同一张表构出来的，输出/图片/diff 再传一遍等于同一份
  * 工具输出在一条响应里走两趟。客户端打补丁时状态照写、正文只在给了的时候才覆盖，所以
  * 那几格省掉是安全的；消息块不在这份窗口里时才带全。
+ *
+ * `bodies: false`（增量拉取）连「消息块不在这份窗口里」的那些也只回状态。理由是同一个：
+ * 增量拉取的调用方手上已经有一份完整的会话，缺的只是「这几次调用结束了没有」；把整窗的
+ * 工具输出再灌一遍，等于每 15 秒把最近两百条消息里的工具输出重发一次（读文件、跑命令的
+ * 输出几十到几百 KB 很常见）。要全文的那条路是入口整份拉取（无游标）与展开时重新拉。
  */
-function toolResultPatchesFor(events, items) {
+function toolResultPatchesFor(events, items, options = {}) {
+  const bodies = options.bodies !== false;
   const delivered = new Set();
   for (const item of items || []) {
     if (!item || !Array.isArray(item.blocks)) continue;
@@ -183,7 +189,7 @@ function toolResultPatchesFor(events, items) {
   }
   return [...buildToolResultMap(events).entries()].map(([callId, result]) => {
     const state = result.isError ? (result.code === 'interrupted' ? 'stopped' : 'error') : 'ok';
-    if (delivered.has(callId)) return { callId, state };
+    if (!bodies || delivered.has(callId)) return { callId, state };
     return {
       callId,
       state,
@@ -373,6 +379,19 @@ function deriveMessages(events) {
     if (bucket.length > 0) presentedByTurn.set(data.turn, bucket);
   }
 
+  /**
+   * 这一轮**被 write / edit 动过**的文件，按轮攒。
+   *
+   * 为什么按轮而不是按单条消息：一份文件是一轮里某一步写的，而收尾答复那条消息自己一个
+   * 写操作都没有 —— 按消息算的话，正文里提到刚写好的文件时那份清单永远是空的（2026-10-25
+   * 现场：手机上那个文件名一直是灰的，数一遍 54 条消息只有 4 条带得动这份清单）。
+   * 桌面 `dsh-client-ui-deliverables` 的 `selectProducedFiles(owner)` 也是按**整轮**取。
+   *
+   * 攒完在循环之后回填：同一轮里先发的消息也要能看到这一轮后几步才写出来的文件。
+   */
+  const producedByTurn = new Map();
+  const producedItems = [];
+
   // 单步计时预扫描：为每条 assistant 消息派生「本轮」的 ttft / decode / 输出 token
   // （对齐桌面 turn-metrics/assistant-timing：ttftMs = 首个非空 delta − step/start；
   // decodeMs = 落定 − 首个 delta；outputTokens = assistant/message.usage.outputTokens）。
@@ -490,17 +509,27 @@ function deriveMessages(events) {
       seq: e.seq,
       time: e.time,
     };
-    const producedFiles = blocks.filter((block) => block.type === 'tool-call' && (block.name === 'write' || block.name === 'edit') && block.state === 'ok').map((block) => {
-       try {
-         const args = JSON.parse(block.argsRaw || '{}');
-         return typeof args.path === 'string' ? args.path : typeof args.file_path === 'string' ? args.file_path : null;
-       } catch { return null; }
-     }).filter((path) => typeof path === 'string');
-     if (producedFiles.length > 0) item.producedFiles = [...new Set(producedFiles)];
-     // 这一轮模型显式声明的交付文件：轮尾那张交付卡的唯一依据（与 producedFiles 分开，
-     // 后者只给收尾正文的行内引用解析用）。事件没有 turn 号的（老日志）不挂。
-     const turn = e.data && typeof e.data.turn === 'number' ? e.data.turn : undefined;
-     if (turn !== undefined) {
+    // 这一轮的轮号（老日志没有）：产出清单与交付声明都按它归并。
+    const turn = e.data && typeof e.data.turn === 'number' ? e.data.turn : undefined;
+    // 本条消息自己写 / 改过的文件：并进**这一轮**的那一份，不单独挂在它自己头上。
+    const ownWrites = blocks
+      .filter((block) => block.type === 'tool-call' && (block.name === 'write' || block.name === 'edit') && block.state === 'ok')
+      .map((block) => {
+        try {
+          const args = JSON.parse(block.argsRaw || '{}');
+          return typeof args.path === 'string' ? args.path : typeof args.file_path === 'string' ? args.file_path : null;
+        } catch { return null; }
+      })
+      .filter((path) => typeof path === 'string');
+    if (turn !== undefined && ownWrites.length > 0) {
+      const bucket = producedByTurn.get(turn) || new Set();
+      for (const path of ownWrites) bucket.add(path);
+      producedByTurn.set(turn, bucket);
+    }
+    // 回填要等循环跑完（这一轮后面几步写的也要算进来），先把这条记下来。
+    if (turn !== undefined) producedItems.push({ item, turn });
+     // 这一轮模型显式声明的交付文件：轮尾那张交付卡的唯一依据（与产出的清单分开）。
+    if (turn !== undefined) {
        const presented = presentedByTurn.get(turn);
        if (presented && presented.length > 0) item.presentedFiles = presented.map((file) => ({ ...file }));
      }
@@ -756,6 +785,16 @@ function deriveMessages(events) {
     }
     // tool/result 等其余类型照旧忽略（工具结果在预扫描里配对回填；compaction 行由 start/end 发出）。
   }
+  // 产出清单按轮回填：这一轮所有 write / edit 的并集，挂到这一轮每条 assistant 消息上。
+  // 挂「整轮」而不是「从写那一刻起」，与桌面 `selectProducedFiles(owner)` 同口径；正文里
+  // 提到这一轮写的文件就能解析成可点（App 侧按文件名或整条路径唯一命中才画，见
+  // `viewmodels/file-mentions`）。
+  if (producedItems.length > 0) {
+    for (const { item, turn } of producedItems) {
+      const bucket = producedByTurn.get(turn);
+      if (bucket && bucket.size > 0) item.producedFiles = [...bucket];
+    }
+  }
   // 严格按事件 seq 升序（与消息混排；compaction 行升级/替换后位置以最终事件为准）。
   out.sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));
   return out;

package/lib/mobile/host-bridge/event-synthesis.js

@@ -304,19 +304,31 @@ function projectionState() {
  * `Array.isArray(items)` 判定失败、整帧被静默丢弃 —— 排队条一次都不显示。
  *
  * `next-turn`（等下一轮才开始的消息）→ `placement: 'queued'`，QueueDock 只认这一个值。
- * `next-step`（本步末尾注入的插话）暂不合成 `steering`：手机发起的插话已有本地待发气泡
- * （`useChatStream` 的 `pending-<clientMessageId>`）与落定后的正文行，多推一份会在同一处
- * 多画一条用户气泡。`message.id` 用宿主行自己的 id，App 靠它与正文去重（chatRenderRows）。
+ * `next-step`（已收下、等本步末尾注入的插话）→ `placement: 'steering'`：排队条与正文列表都
+ * 只认 `queued`，所以它不会多画一行；它的用处是「宿主已经收下了」这条回执 —— 插话从发出去
+ * 到真被插进去中间可能隔着好几个工具往返，此前手机上只挂着一颗「发送中…」。页脚那排插话
+ * 气泡会把本机自己发的那几条排掉（`steeringForFooter`），不会与待发气泡双画。
+ * `message.id` 用宿主行自己的 id，App 靠它与正文去重（chatRenderRows）。
  */
 function queueItems(inbox, ctx) {
-  const rows = inbox && Array.isArray(inbox['next-turn']) ? inbox['next-turn'] : [];
   const items = [];
   let dropped = 0;
-  for (const message of rows) {
-    if (!message || typeof message !== 'object') continue;
-    const id = typeof message.id === 'string' && message.id ? message.id : '';
-    if (!id) { dropped += 1; continue; } // 没有 id 的行没法被 session.updateQueue 定位，别发出去
-    items.push({ id, placement: 'queued', message: { id, content: message.content } });
+  /**
+   * 摊平一组待发行。`placement` 只标语义：`queued` 进排队条，`steering` 只是回执。
+   * 没有 id 的行丢弃并计数（理由见下面的注释）。
+   */
+  const absorb = (rows, placement) => {
+    if (!Array.isArray(rows)) return;
+    for (const message of rows) {
+      if (!message || typeof message !== 'object') continue;
+      const id = typeof message.id === 'string' && message.id ? message.id : '';
+      if (!id) { dropped += 1; continue; } // 没有 id 的行没法被 session.updateQueue 定位，别发出去
+      items.push({ id, placement, message: { id, content: message.content } });
+    }
+  };
+  if (inbox && typeof inbox === 'object') {
+    absorb(inbox['next-turn'], 'queued');
+    absorb(inbox['next-step'], 'steering');
   }
   // 丢弃必须留痕：旧实现是裸 continue，手机上少一条待发消息而宿主侧一行日志都没有，
   // 只能靠人对着桌面端数气泡。凭空造 id 更糟——App 的 session.updateQueue 按 id 定位，

package/lib/mobile/monitor.js

@@ -10,7 +10,8 @@
  *
  * 这条只回监控需要的那几格：在不在跑、刚完成没有、在等谁回话、上一轮是不是跑挂的、标题。
  * 并支持 `?rev=` 条件刷新：状态位与上次一模一样时回一句 `unchanged`，连 items 都不带
- * （稳态下这一发是几十字节）。
+ * （稳态下这一发是几十字节）。再带上 `?wait=秒` 时，条件刷新的那一发**先挂住**，等状态位
+ * 真的变了才回 —— 安卓后台服务靠它把「定时去问」变成「一有变化立刻送到」。
  *
  * 完成态仍以 completion 状态机为准，与 `/sessions` 用同一本账：常态下这里**不读 history**，
  * 只有「跑过、现在不在跑、结局还没定」的那几条才读一次 —— 那是唯一能把 failedTurn 折出来
@@ -22,6 +23,8 @@
 
 const { sendJson } = require('../shared/http-util');
 const { stableRevision, unchangedListBody } = require('../shared/list-revision.js');
+const { listSignal } = require('../shared/list-signal.js');
+const { sessionSignal } = require('../shared/session-signal.js');
 const { callSessions } = require('./rpc.js');
 const { unwrap } = require('./envelope.js');
 const { listTitle } = require('./history-derive.js');
@@ -29,6 +32,7 @@ const {
   canonicalDeviceKey, deletedSessionIdsOf, completionGenerationOf,
 } = require('./session-cache.js');
 const { updateCompletionStates, confirmCompletionFromHistory } = require('./completion.js');
+const { lastTurnOf } = require('./session-last-turn.js');
 const { sessionPreviewFor } = require('./session-preview.js');
 const { workspaceSessionFlags, pendingInteractionOf } = require('./session-flags.js');
 
@@ -39,16 +43,46 @@ const { workspaceSessionFlags, pendingInteractionOf } = require('./session-flags
  * lastTurnError），因为原生那边解析的是同一套字段：换名字就得同步改 Kotlin，而那段代码
  * 在 App 之外，改错一次是「后台永远不提醒」这种看不见的故障。
  */
-function monitorItem(summary, state) {
+function monitorItem(summary, state, fact) {
+  const running = summary.running === true;
+  // 完成/失败优先用**上一轮事实**（`session-last-turn`），不再等 `state.completed`。
+  //
+  // 为什么：那个按设备记账的完成态要靠「这一次真的读回了 history」才折得出来，而
+  // 「刚跑完」那一刻宿主的镜像推送早把同一份预览按新指纹写进缓存了 —— 监控这一侧
+  // 拿到的是缓存命中（events 为空）、永远折不出来，`completed` 就一直 false，后台
+  // 一条提醒都不会响（2026-10-25 真机：宿主日志里全是「preview cache-hit」）。
+  // 事实那本账由 turn/end 事件当场记下，不依赖预览缓存，所以拿它判完成。
+  //
+  // 已读水位仍然生效：这一轮结束在「这台手机读过」之前就不算提醒。
+  const clearedAt = typeof state?.clearedAt === 'number' ? state.clearedAt : null;
+  const settledForThisDevice = fact != null && (clearedAt === null || fact.endedAt > clearedAt);
+  const completed = fact
+    ? (!running && fact.status === 'completed' && settledForThisDevice)
+    : (state ? state.completed === true : false);
   const item = {
     sessionId: summary.sessionId,
     title: listTitle(summary),
-    running: summary.running === true,
-    completed: state ? state.completed === true : false,
+    running,
+    completed,
   };
   const pending = pendingInteractionOf(summary.sessionId, summary);
   if (pending) item.pendingInteraction = pending;
-  if (state && state.failure) item.lastTurnError = state.failure;
+  const failure = fact
+    ? (fact.status === 'failed' && settledForThisDevice
+      ? { turn: fact.turn, code: fact.code ?? null, message: fact.message ?? null }
+      : null)
+    : (state && state.failure ? state.failure : null);
+  if (failure) item.lastTurnError = failure;
+  // 上一轮事实整份透给原生：它按「轮次前进」判完成 / 失败，比 completed 翻面可靠
+  // （两次轮询之间跑完一整轮时 completed 可能一直是 true）。字段与列表那条同源。
+  if (fact) {
+    item.lastTurn = {
+      turn: fact.turn,
+      endedAt: fact.endedAt,
+      status: fact.status,
+      ...(fact.status === 'failed' ? { code: fact.code ?? null, message: fact.message ?? null } : {}),
+    };
+  }
   return item;
 }
 
@@ -68,7 +102,10 @@ async function buildMonitorState(ctx, deviceKey) {
   const generation = completionGenerationOf(ctx, deviceKey);
   const deleted = deletedSessionIdsOf(ctx);
   const { archived } = await workspaceSessionFlags(ctx);
+  // 子代理会话不参与后台提醒：它们是主轮内部的执行单元，App 侧栏也不列；把它们算进来
+  // 会在后台弹一堆「子代理跑完了」（2026-10-26 真机日志里四十多个 UUID 会话都是这种）。
   const live = summaries.filter((s) => s && typeof s.sessionId === 'string' && s.sessionId
+    && s.origin !== 'subagent'
     && !deleted.has(s.sessionId) && !archived.has(s.sessionId));
 
   // 状态机跟着这份清单走：归档 / 删除的会话在这里被踢掉，与完整列表同一口径。
@@ -85,51 +122,129 @@ async function buildMonitorState(ctx, deviceKey) {
     await Promise.all(unsettled.map(async (summary) => {
       try {
         const preview = await sessionPreviewFor(ctx, summary);
-        if (!preview.events.length) return;
+        if (!preview.events.length) {
+          return;
+        }
         // 读到这些历史的这一刻，别处可能刚发起一次写后刷新（它会 bump 代次）；
         // 用旧快照去确认结局等于把「还在跑的一轮」写成已完成。
-        if (completionGenerationOf(ctx, deviceKey) !== generation) return;
+        if (completionGenerationOf(ctx, deviceKey) !== generation) {
+          return;
+        }
+        const before = states.get(summary.sessionId)?.completed;
         confirmCompletionFromHistory(states.get(summary.sessionId), preview.events, false, ctx, summary.sessionId);
-      } catch {
+      } catch (error) {
         // 这一轮没读到就原样留着：判定条件（没完成、没失败）下一轮仍然成立，会再试。
       }
     }));
   }
 
-  const items = live.map((summary) => monitorItem(summary, states.get(summary.sessionId)));
+  const items = live.map((summary) => monitorItem(
+    summary,
+    states.get(summary.sessionId),
+    lastTurnOf(ctx, summary.sessionId),
+  ));
   // 按 id 排序后再算指纹：宿主是按 updatedAt 排的，聊一句话顺序就换，指纹会跟着每轮都变，
   // 条件刷新等于白做。监控视图不关心顺序。
   items.sort((a, b) => (a.sessionId < b.sessionId ? -1 : a.sessionId > b.sessionId ? 1 : 0));
   return { items, revision: stableRevision(items) };
 }
 
-/** GET /api/mobile/v1/monitor?rev=…（token） */
-async function handleMonitor(ctx, req, res) {
-  const deviceKey = canonicalDeviceKey(req);
-  const url = new URL(req.url, 'http://x');
-  const rev = (url.searchParams.get('rev') || '').trim();
+/** 一次挂起的上限。手机侧每次挂 20 秒，再长没有意义：断线重连比占着一条连接便宜。 */
+const WAIT_MAX_MS = 25_000;
+
+/**
+ * 挂在「有东西变了」的信号上，最多等 timeoutMs。
+ *
+ * 只有两条总线会唤醒它：清单变了（list-signal）、某个会话的正文水位涨了（session-signal）
+ * —— 一轮跑完、跑挂、开始等你回话，都会至少踩中其中一条。两条都是模块级单例，生产端在
+ * 镜像推送链上，不需要认识这条请求。
+ *
+ * 为什么用总线而不是自己轮着算一遍：这里的等待必须是**事件驱动**的，自己定时重算就成了
+ * 换了个地方的轮询，而这条接口存在的全部理由就是让手机不必轮询。
+ */
+function waitForChange(timeoutMs, res) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let releaseList = () => {};
+    let releaseSession = () => {};
+    const timer = setTimeout(() => finish(), timeoutMs);
+    function finish() {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      releaseList();
+      releaseSession();
+      resolve();
+    }
+    releaseList = listSignal.onBump(finish);
+    releaseSession = sessionSignal.onBump(finish);
+    // 手机切网 / 进程被杀时连接会断，没必要再替它挂满整个窗口。
+    if (res && typeof res.once === 'function') res.once('close', finish);
+  });
+}
 
+/** 算一次监控视图，把「宿主出错 / 形状异常」也收成一个可下发的响应。 */
+async function buildMonitorView(ctx, deviceKey) {
   let built;
   try {
     built = await buildMonitorState(ctx, deviceKey);
   } catch (error) {
-    return sendJson(res, 500, {
-      ok: false,
-      error: { code: 'monitor-failed', message: (error && error.message) || '监控视图构建失败' },
-    });
+    return {
+      status: 500,
+      body: { ok: false, error: { code: 'monitor-failed', message: (error && error.message) || '监控视图构建失败' } },
+    };
   }
-  if (built.error) return sendJson(res, 400, { ok: false, error: built.error });
+  if (built.error) return { status: 400, body: { ok: false, error: built.error } };
   if (built.degraded) {
     // 与 /sessions 同一个码：中转见到 5xx 会退回上一份好副本，手机那侧因此是「没收到新东西」
     // 而不是「一台会话都没有」。
-    return sendJson(res, 500, {
-      ok: false,
-      error: { code: 'host-session-list-degraded', message: '宿主会话列表形状异常：响应里没有 items 数组' },
-    });
+    return {
+      status: 500,
+      body: { ok: false, error: { code: 'host-session-list-degraded', message: '宿主会话列表形状异常：响应里没有 items 数组' } },
+    };
+  }
+  return { status: 200, body: { ok: true, generatedAt: Date.now(), revision: built.revision, items: built.items } };
+}
+
+/**
+ * GET /api/mobile/v1/monitor?rev=…[&wait=秒]（token）
+ *
+ * `wait` 是实时那条路：带上它，且状态位与 `rev` 一字不差时，这次请求**先不回**，
+ * 挂到有变化（或挂满）才回。安卓那条前台服务在后台就挂着它，于是「一轮跑完」到
+ * 「手机响」只差一次本地网络往返，不再等下一拍轮询。
+ *
+ * 只挂一次：醒来之后不管变没变都如实回（变没变由 revision 说了算），由手机自己决定
+ * 要不要再挂。这样这里没有循环、没有重试，断线也不会在宿主侧留下一个转不停的请求。
+ */
+async function handleMonitor(ctx, req, res) {
+  const deviceKey = canonicalDeviceKey(req);
+  const url = new URL(req.url, 'http://x');
+  const rev = (url.searchParams.get('rev') || '').trim();
+  const waitSeconds = Number(url.searchParams.get('wait') || 0) || 0;
+  // 没有 rev 就不挂：那不是「确认一下有没有变」，而是「给我一份完整状态」，立刻回。
+  const waitMs = rev ? Math.max(0, Math.min(WAIT_MAX_MS, Math.round(waitSeconds * 1000))) : 0;
+
+  const first = await buildMonitorView(ctx, deviceKey);
+  if (first.status !== 200) {
+    return sendJson(res, first.status, first.body);
   }
+  const unchanged = unchangedListBody(first.body, rev);
+  if (!unchanged) return sendJson(res, 200, first.body);
+  if (waitMs <= 0) return sendJson(res, 200, unchanged);
 
-  const body = { ok: true, generatedAt: Date.now(), revision: built.revision, items: built.items };
-  sendJson(res, 200, unchangedListBody(body, rev) || body);
+  // 头必须在挂起**之前**发出去。走中转那条路上，「等响应头」只有 7 秒
+  // （lib/relay/tunnel.js 的 UPSTREAM_HEADER_TIMEOUT_MS），不先发头，这次挂起会被
+  // 当成死请求掐掉，手机收到的是一次网络错误而不是一次「没变化」。发完头再等，
+  // 中转那边看的是「响应空转 30 秒」，20 秒的挂起正好在它之内。
+  res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', vary: 'accept-encoding' });
+  if (typeof res.flushHeaders === 'function') res.flushHeaders();
+  await waitForChange(waitMs, res);
+  // 手机在这段时间里断了（切网 / 进程被杀）：别为一个没人收的响应再算一遍。
+  if (res.destroyed || res.writableEnded) return;
+  const again = await buildMonitorView(ctx, deviceKey);
+  const body = again.status === 200 ? (unchangedListBody(again.body, rev) || again.body) : again.body;
+  // 头已经出去了，不能再走 sendJson（它会再写一次头）：这里只补正文。
+  try { res.end(JSON.stringify(body)); } catch { /* 连接已断开 */ }
 }
 
 module.exports = { handleMonitor, buildMonitorState, monitorItem };