dsh-mobile-plugin 0.1.93 → 0.1.94

package/README.md

@@ -56,7 +56,7 @@ curl http://127.0.0.1:3080/api/relay/pairing
 
 移动 API 需要 Bearer token。设备事件流 `GET /api/mobile/v1/events/stream` 使用 SSE 转发宿主事件。创建会话时可传 `workspaceId` 或 `cwd`；前者优先，并将会话归入指定工作区。移动端排序也会同步到宿主工作区。
 
-配对策略默认为 `code`（凭配对码放行）；设为 `deny` 时拒绝所有新配对。自动归档只隐藏符合条件的闲置会话，不删除日志。`session_cleanup` 工具可归档会话，也可永久删除已归档会话；删除不可恢复，需要显式确认。
+配对策略默认为 `code`（凭配对码放行）；设为 `deny` 时拒绝所有新配对。自动归档只隐藏符合条件的闲置会话，不删除日志。`session_cleanup` 工具可归档会话，也可永久删除已归档会话；删除不可恢复，需要显式确认。删除是「排进待删队列」：会话立刻从列表里消失，日志与投影缓存等宿主下次启动时才从磁盘上删掉 —— 宿主没有「删除会话」的接口，进程活着的时候从它脚底下删文件会让它读到不存在的日志，那是未捕获异常，会带走整个宿主进程。
 
 ## 无头部署
 

package/lib/desktop-view.cjs

@@ -19,6 +19,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const paths = require('./shared/paths');
+const { desktopViewSignal } = require('./shared/desktop-view-signal.js');
 
 /** 单个键（workspaceId）长度上限；超长的一律丢弃（真实 id 只有十几字节）。 */
 const MAX_KEY_LENGTH = 200;
@@ -36,6 +37,17 @@ function stateFile() {
 let cached = null;
 let loaded = false;
 
+/**
+ * 折叠态内容指纹（键排序后序列化）。
+ *
+ * 只用来回答「这次上报真的改了折叠态吗」：两次 JSON.stringify 的键序不保证一致，
+ * 直接比会让同一份状态被认成两次变更。内容没变就既不重写文件、也不给手机推帧。
+ */
+function expansionFingerprint(groupExpansion) {
+  const keys = Object.keys(groupExpansion).sort();
+  return JSON.stringify(keys.map((key) => [key, groupExpansion[key]]));
+}
+
 /** 归一化上报的 groupExpansion：只保留布尔值、限长限量；形状不对返回 null。 */
 function normalizeGroupExpansion(input) {
   if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
@@ -91,11 +103,16 @@ function update(input, now = Date.now()) {
   const groupExpansion = normalizeGroupExpansion(input && input.groupExpansion);
   if (!groupExpansion) throw new Error('groupExpansion 必须是对象');
   const rawSource = input && (typeof input.source === 'string' ? input.source : input.storageKey);
+  const previous = load();
   const next = {
     groupExpansion,
     receivedAt: now,
     source: typeof rawSource === 'string' ? rawSource.slice(0, MAX_SOURCE_LENGTH) : '',
   };
+  // 折叠态没变就不落盘、不广播：客户端半边在页面重载 / 切窗口时会重发同一份。
+  // 什么都没变却写一次文件、给每台手机推一帧，等于把白问的轮询换成白推的帧。
+  const changed = !previous || expansionFingerprint(previous.groupExpansion) !== expansionFingerprint(groupExpansion);
+  if (!changed) return snapshot();
   const file = stateFile();
   fs.mkdirSync(path.dirname(file), { recursive: true });
   const tmp = `${file}.tmp`;
@@ -103,6 +120,9 @@ function update(input, now = Date.now()) {
   fs.renameSync(tmp, file);
   cached = next;
   loaded = true;
+  // 落盘之后再广播：订阅方收到帧会立刻回来读这条路（GET /desktop-view 读的是这份
+  // cached），先通知后落盘会把它引到上一份内容上。
+  desktopViewSignal.bump(next.receivedAt);
   return snapshot();
 }
 

package/lib/impl.js

@@ -295,7 +295,7 @@ function apply(ctx) {
   const { sidecarToken, syncSidecar, restartSidecar, tunnelConnected } = sidecarLifecycle
 
   // 镜像推送调度器：会话事件立即推，后台循环每个 tick 补推一个冷会话。
-  const mirror = createMirrorPusher({ ctx, tunnelConnected, getSidecar: sidecarLifecycle.getSidecar })
+  const mirror = createMirrorPusher({ ctx, tunnelConnected, getSidecar: sidecarLifecycle.getSidecar, lastMobileAt: activity.snapshot })
   // 隧道刚连上时补推一次全量：未连通期间每轮推送都被 worker 以 503 拒绝。
   sidecarLifecycle.onTunnelUp(() => { void mirror.pushMirror(); })
 

package/lib/mirror/pusher.cjs

@@ -39,6 +39,25 @@ const { observeCompletionEvent } = require('../mobile/completion.js');
 /** 后台循环每个 tick 补推一个冷会话，保证没人动的会话镜像也不长期不更新。 */
 const HIGH_PRIORITY_WINDOW_MS = 5 * 60 * 1000;
 const BG_TICK_INTERVAL_MS = 500;
+/**
+ * 没人看的时候，后台 tick 降到这个节拍。
+ *
+ * 500ms 那条节奏是给「手机正在用」准备的：清单或工作区一变，手机半秒内就该看到。
+ * 但宿主一天里大部分时间没人看 —— 那时每 500ms 整轮重建一次清单/工作区，走中转的
+ * 还要把快照推过一条隧道，纯属空转。
+ *
+ * 上限由 sidecar 的快照 TTL 卡着：镜像快照 15s 过期，降频必须明显小于它，
+ * 取 5s（= TTL/3，`test/mirror-tick-budget.test.cjs` 钉着这条比例）。
+ */
+const IDLE_TICK_INTERVAL_MS = 5_000;
+/**
+ * 多久没有手机请求就算「没人看」。
+ *
+ * 走中转的手机每个请求都会记一次 `mobile/activity.cjs` 的 `note()`；局域网直连的手机
+ * 不走那道守卫所以记不到，那种情况另有 `listSignal.watching()` 兜着（有人订阅清单变化时
+ * 它为真）。两个判据都不成立时才降频。
+ */
+const AUDIENCE_IDLE_MS = 30_000;
 /**
  * 冷会话轮转的最小间隔（清单/工作区都没变时才生效）。
  *
@@ -64,6 +83,19 @@ const MAX_CONSECUTIVE_EVENT_BUILDS = 3;
 
 function createMirrorPusher(deps) {
   const { ctx, tunnelConnected, getSidecar, listSignal = sharedListSignal, sessionSignal = sharedSessionSignal } = deps;
+  /**
+   * 「手机最近来过没有」的取值器（`mobile/activity.cjs` 的 `snapshot` 形态）。
+   *
+   * 不传就按「有人在看」处理、维持原来 500ms 的节拍：降频是个优化，不是契约，
+   * 别让一处漏接线的装配把镜像悄悄降成 5s 一份。
+   */
+  const lastMobileAt = typeof deps.lastMobileAt === 'function' ? deps.lastMobileAt : null;
+  const hasAudience = () => {
+    if (listSignal.watching()) return true;
+    if (!lastMobileAt) return true;
+    const at = Number(lastMobileAt()?.lastMobileAt) || 0;
+    return at > 0 && Date.now() - at <= AUDIENCE_IDLE_MS;
+  };
 
   // 移动镜像推送状态（供诊断/状态面板观测：最近推送时间 + 结果）
   let mirrorPushAt = 0
@@ -565,9 +597,17 @@ function createMirrorPusher(deps) {
   let bgQueueBusy = false;
   // 上一次真的跑过冷会话轮转的时刻（见 BG_COLD_ROTATE_MIN_INTERVAL_MS）。
   let lastColdRotateAt = 0;
+  // 上一轮后台扫描真正跑起来的时刻（见 IDLE_TICK_INTERVAL_MS 的降频）。
+  let lastBgScanAt = 0;
 
   const processBgQueue = async () => {
     if (bgQueueBusy) return;
+    // 降频：没人看的时候不必每 500ms 重建一轮清单。判据用「手机最近有没有请求」，
+    // 而不是「隧道连没连上」—— 隧道连着但人没在用，一样是空转。
+    // 有人在看时不加额外下限，节奏仍由 500ms 的定时器自己决定。
+    // 事件驱动那条路径（pushSessionImmediately）不受这里影响，会话真的变了仍是立即推。
+    if (!hasAudience() && lastBgScanAt && Date.now() - lastBgScanAt < IDLE_TICK_INTERVAL_MS) return;
+    lastBgScanAt = Date.now();
     const online = tunnelConnected();
     // 隧道未连接时这个 500ms 的 tick 只在**有人听**的时候才有意义：构建出来的快照没有
     // 任何去处（pushMirrorPayload 会短路），但「清单变了」这件事仍然要说给手机听 ——

package/lib/mobile/archive-clean.js

@@ -1,30 +1,33 @@
 'use strict';
 
 /**
- * 移动端「清理所有已归档的对话」：按宿主归档集合确定清理范围，并删掉它们的日志。
+ * 移动端「清理所有已归档的对话」：按宿主归档集合确定清理范围，把它们排进待删队列。
  *
  * 以 workspace.list 的 archivedSessionIds 为清理范围，不用可能过时的列表状态缩小范围；
  * 请求必须显式带 confirm: true —— 磁盘删除不可恢复，手机端「少点一次」不值得把它变成滑一下就没了的动作。
  *
- * 删除动作不重写：读日志 header.id → 删会话目录 + 投影缓存只在 session-cleanup.cjs 里存在
- * （见地图 A3-17），这里只是把它的触发面从 agent 工具扩到移动端路由。
+ * **这里不删磁盘**：只把 id 排进 session-cleanup.cjs 的待删队列，日志留到宿主下次启动时删
+ * （见那个文件的 deleteQueuedArchivedSessions）。宿主没有「删除会话」接口，进程活着的时候
+ * 它随时可能去打开那些文件 —— 文件不在就是一次未捕获的 ENOENT，宿主整个退出、桌面端闪退
+ * （2026-10-20 真机现场）。本进程只把 id 压进删除集，让手机列表立刻看不到它们。
  *
- * **这里不擦宿主的归档集合**（只把删掉的 id 记进本进程的删除集，挡住手机端列表里可能
- * 还没失效的旧快照）。进程里擦集合会把桌面端那份会话列表快照里、其实已经删掉的行放回
- * 正常列表——桌面端用户看到的就是「清理完它们又回来了，重启 DSH 才真的消失」。归档集合
- * 的收尾放在宿主启动时做，见 session-cleanup.cjs 的 pruneOrphanedArchivedSessionsOnce。
+ * 也**不擦宿主的归档集合**：进程里擦会把桌面端快照里那些其实已经没有日志的行放回正常列表。
+ * 归档集合的收尾同样在宿主启动时做，见 pruneOrphanedArchivedSessionsOnce。
  */
 
 const { sendJson, readJsonBody } = require('../shared/http-util');
 const { withIdempotency, requestIdOf } = require('./idempotency.js');
-const { canonicalDeviceKey, rememberDeletedSessionIds, deletedSessionIdsOf } = require('./session-cache.js');
+const { canonicalDeviceKey, rememberDeletedSessionIds } = require('./session-cache.js');
 const { invalidateSessionList } = require('./sessions.js');
 const { unwrap } = require('./envelope.js');
-const { deleteSessionData, sessionIdsWithoutAnyData } = require('../session-cleanup.cjs');
+const { queueArchivedClearIds } = require('../session-cleanup.cjs');
 
 /**
  * POST /api/mobile/v1/workspace/clear-archived（token）
  * body: { confirm: true } → { ok: true, deleted: N }。confirm 不为 true 一律 400。
+ *
+ * deleted = 这次被排进队列、手机上立刻消失的条数（含盘上早就没有数据的那些）；日志要到
+ * 宿主下次启动才真正从磁盘上消失。
  */
 async function handleClearArchived(ctx, req, res) {
   const body = await readJsonBody(req, 64 * 1024);
@@ -41,17 +44,13 @@ async function handleClearArchived(ctx, req, res) {
     const archivedIds = Array.isArray(workspaceResponse.value?.archivedSessionIds) ? workspaceResponse.value.archivedSessionIds : [];
     const selected = archivedIds.filter((id) => typeof id === 'string' && id);
     if (selected.length === 0) return { status: 200, body: { ok: true, deleted: 0 } };
-    const removed = await deleteSessionData(selected);
-    // 删的是列表里可见的行：手机端正开着列表，宿主那份快照可能还带着它们，先在本进程压住。
-    // 盘上已经没有数据的归档 id 一并压住：上一次删到一半抛错时，已删的那批没记进删除集，
-    // 宿主的进程内清单却还挂着它们 —— 不补记的话再点清理只回 0，手机上永远清不掉。
-    const already = deletedSessionIdsOf(ctx);
-    const cleared = new Set(removed);
-    for (const id of sessionIdsWithoutAnyData(selected)) if (!already.has(id)) cleared.add(id);
-    rememberDeletedSessionIds(ctx, cleared);
+    // 排不进队列就整次失败（路由回 500）：回「已清理」却没排上，重启之后它们原样回来。
+    queueArchivedClearIds(selected);
+    // 宿主那份快照可能还带着它们，先在本进程压住：手机列表与归档列表立刻看不到。
+    rememberDeletedSessionIds(ctx, selected);
     // 不立刻失效的话，最长 10 秒还能点到已删的行。
     invalidateSessionList(ctx);
-    return { status: 200, body: { ok: true, deleted: cleared.size } };
+    return { status: 200, body: { ok: true, deleted: selected.length } };
   });
   sendJson(res, outcome.status, outcome.body);
 }

package/lib/mobile/events.js

@@ -6,9 +6,10 @@
  * 但宿主在 DSH 0.2.0 兼容桥下只会订阅 workspace/follow + session/control，会话状态变化
  * 走的是 session/projection（被白名单丢掉），于是这条流连着却可能长时间一帧都不发；
  * 插件自己补了 device/list-changed（来自 lib/shared/list-signal.js，清单变了）、
- * device/session-activity（来自 lib/shared/session-signal.js，某个会话的正文水位涨了）
- * 与 device/heartbeat（心跳）三类自产帧，App 侧靠它们判断「这条流还活着」「该重拉列表」
- * 「该给某个会话补正文」并据此决定要不要把兜底轮询降频。
+ * device/session-activity（来自 lib/shared/session-signal.js，某个会话的正文水位涨了）、
+ * device/desktop-view-changed（来自 lib/shared/desktop-view-signal.js，桌面侧栏折叠态
+ * 变了）与 device/heartbeat（心跳）四类自产帧，App 侧靠它们判断「这条流还活着」
+ * 「该重拉列表」「该给某个会话补正文」「该重取折叠态」并据此决定要不要把兜底轮询降频。
  *
  * 断流补偿：这条流不做 Last-Event-ID 续传（App 只把它当信号，不当数据源），所以**连上时**
  * 会立刻补发「当前状态」——一帧最近已知 revision 的 device/list-changed + 每个已跟踪会话
@@ -19,6 +20,7 @@
 
 const { listSignal: sharedListSignal } = require('../shared/list-signal.js');
 const { sessionSignal: sharedSessionSignal } = require('../shared/session-signal.js');
+const { desktopViewSignal: sharedDesktopViewSignal } = require('../shared/desktop-view-signal.js');
 const { writeSse: sharedWriteSse, stableEventId: sharedEventId } = require('../shared/sse-write.js');
 
 const DEDUP_WINDOW = 2048;
@@ -194,6 +196,22 @@ async function handleDeviceStream(ctx, req, res) {
     if (ac.signal.aborted) return;
     if (!writeFrame({ type: 'device/session-activity', sessionId: event.sessionId, seq: event.seq, at: event.at })) ac.abort();
   });
+  /**
+   * 自产的「桌面侧栏折叠态变了」帧。
+   *
+   * 桌面端那份 groupExpansion 只活在浏览器 localStorage，插件靠客户端半边轮询上报，
+   * 落在 lib/desktop-view.cjs；手机要拿到它只能问 GET /desktop-view。过去 App 用
+   * 「跟列表刷新走 + 5 分钟最短间隔」去猜它有没有变，稳态下一天白问几百次 —— 而插件
+   * 早就知道它哪一刻变了（desktop-view.cjs 的 update()）。这里补上那个出口。
+   *
+   * 只发 updatedAt、不发内容：手机据此重拉那一发，拿到的是与列表同一口径的完整镜像，
+   * 也不必让这条「信号流」承担数据同步（它的帧一律可丢、可重放）。
+   * 同样必须直订 + 收尾注销，理由与上面两条一致。
+   */
+  const unsubscribeDesktopView = sharedDesktopViewSignal.onBump((event) => {
+    if (ac.signal.aborted) return;
+    if (!writeFrame({ type: 'device/desktop-view-changed', updatedAt: event.updatedAt, at: event.at })) ac.abort();
+  });
   /**
    * 连上就先补一帧「当前状态」。
    *
@@ -213,6 +231,12 @@ async function handleDeviceStream(ctx, req, res) {
     if (list && list.revision) {
       if (!writeFrame({ type: 'device/list-changed', revision: list.revision, at: list.at || Date.now() })) return false;
     }
+    // 桌面侧栏折叠态：手机从此只在变化时拉一次。老 App 不认识这一帧（走默认分支忽略），
+    // 所以补发它不会改变老客户端的任何行为。
+    const view = sharedDesktopViewSignal.snapshot();
+    if (view && view.updatedAt > 0) {
+      if (!writeFrame({ type: 'device/desktop-view-changed', updatedAt: view.updatedAt, at: view.at || Date.now() })) return false;
+    }
     for (const [sessionId, seq] of Object.entries(sharedSessionSignal.snapshot())) {
       if (!(seq > 0)) continue;
       if (!writeFrame({ type: 'device/session-activity', sessionId, seq, at: Date.now() })) return false;
@@ -279,6 +303,7 @@ async function handleDeviceStream(ctx, req, res) {
   clearInterval(keepAlive);
   unsubscribeSignal();
   unsubscribeActivity();
+  unsubscribeDesktopView();
   releaseSignal();
   try {
     if (!res.writableEnded) {

package/lib/mobile/host-bridge/endpoints.js

@@ -110,7 +110,6 @@ const ENDPOINTS = {
 
   // skills / subagents
   'skills.list': inv('skills', 'list'),
-  'subagents.history': inv('subagents', 'history'),
   'subagents.prompt': inv('subagents', 'prompt', (p) => ({
     request: {
       ...pick(p, ['parentSessionId', 'childSessionId', 'mode', 'content', 'clientTimeZone']),

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

@@ -21,6 +21,28 @@ function sessionHint(request) {
   return typeof sessionId === 'string' && sessionId ? sessionId : null;
 }
 
+/**
+ * 这条单会话流该按哪种地址订阅。
+ *
+ * 子会话必须换成 `{kind:'subagent'}` 的 durable 地址：宿主 `validateAddress` 对
+ * `origin === 'subagent'` 的会话拿普通地址一律回 agent-busy，subscribe 直接失败 ——
+ * 表现就是「子代理页面打得开，但内容永远不自己更新」。请求体里带上 `parentSessionId`
+ * 就是「这是个子会话」的信号（与历史那条同源，见 stream.js 的 handleStream）。
+ */
+function sessionAddress(payload) {
+  const sessionId = payload && payload.sessionId;
+  const parentSessionId = payload && payload.parentSessionId;
+  if (typeof parentSessionId === 'string' && parentSessionId) {
+    return {
+      kind: 'subagent',
+      parentSessionId,
+      childSessionId: sessionId,
+      mode: (payload && payload.mode) || 'continuable',
+    };
+  }
+  return { kind: 'session', sessionId };
+}
+
 /** 一条流跑不通不该拖垮其余流：这里把异常吃掉，只丢这一条源的帧。 */
 async function* tolerate(frames, what, ctx) {
   try {
@@ -207,20 +229,28 @@ async function* deviceFrames(ctx, signal) {
 /** 旧 `events.mux`：设备级帧流，带 sessionId 时收窄成单会话视角。 */
 function muxFrames(ctx, request, signal) {
   const sessionId = sessionHint(request);
+  const payload = request && request.payload;
   return (async function* run() {
     if (!sessionId) {
       yield* deviceFrames(ctx, signal);
       return;
     }
+    const address = sessionAddress(payload);
+    // 子会话没有 job 面板（任务归属父会话），也就不订阅那一条：拿子会话 id 去问 job.list
+    // 只会白打一发，而且它的失败会被 tolerate 吞成一条警告。
     const control = openStream(ctx, 'session', 'control', {}, signal).then((frames) => tolerate(frames, 'session/control', ctx));
-    const jobs = openStream(ctx, 'job', 'list', { request: { sessionId } }, signal).then((frames) => tolerate(frames, `job/${sessionId}`, ctx));
+    const jobs = address.kind === 'session'
+      ? openStream(ctx, 'job', 'list', { request: { sessionId } }, signal).then((frames) => tolerate(frames, `job/${sessionId}`, ctx))
+      : null;
     // assistantStream: 逐块增量只走这条流的 assistant-stream 通知（见 followFramePayloads）。
     const follow = openStream(ctx, 'session', 'follow', {
-      request: { address: { kind: 'session', sessionId }, maxMessages: 1, assistantStream: true },
+      request: { address, maxMessages: 1, assistantStream: true },
     }, signal).then((frames) => tolerate(frames, `session/${sessionId}`, ctx));
     const projections = projectionState();
     const followState = { turn: null, step: null, streaming: false };
-    const sources = await Promise.all([['control', control], ['jobs', jobs], ['follow', follow]].map(([source, promise]) => promise.then(async function* wrap(iterable) {
+    const opening = [['control', control], ['follow', follow]];
+    if (jobs !== null) opening.push(['jobs', jobs]);
+    const sources = await Promise.all(opening.map(([source, promise]) => promise.then(async function* wrap(iterable) {
       for await (const frame of iterable) {
         if (source === 'follow') {
           // follow 一帧可能产出 0..n 个 mux 帧（事件原样 + 增量通知合成 chunk 事件）。

package/lib/mobile/host-bridge/shims.js

@@ -13,13 +13,36 @@ const { invoke, invokeEnvelope, ok, fail, pick, warn, deadline, openStream, SYNT
  * follow 拿游标（读完首帧立刻 break，网关会取消这条流），再翻一页历史。
  * 返回值把 records 拆回旧形状的 events（history-derive.js 只认 events/hasMore）。
  */
+/**
+ * 这次 history 要读的是「谁」的地址。
+ *
+ * 普通会话是 `{kind:'session'}`；子会话必须换成**带父会话的 durable 地址**
+ * `{kind:'subagent'}` —— 宿主对 `origin === 'subagent'` 的会话拿普通地址一律回
+ * agent-busy（见 dsh-api-session-controller 的 validateAddress），这跟续话那条
+ * 是同一个门。`mode` 也要带：宿主会拿它跟子会话自己的 descriptor 对一遍。
+ */
+function historyAddress(payload) {
+  const sessionId = payload && payload.sessionId;
+  const parentSessionId = payload && payload.parentSessionId;
+  if (typeof parentSessionId === 'string' && parentSessionId) {
+    return {
+      kind: 'subagent',
+      parentSessionId,
+      childSessionId: sessionId,
+      mode: (payload && payload.mode) || 'continuable',
+    };
+  }
+  return { kind: 'session', sessionId };
+}
+
 async function historyViaPage(ctx, payload, signal) {
   const sessionId = payload && payload.sessionId;
   if (typeof sessionId !== 'string' || !sessionId) return fail({ code: 'bad-request', message: '缺少 sessionId' }, 'bad-request');
+  const address = historyAddress(payload);
   let throughSeq = -1;
   try {
     const frames = await openStream(ctx, 'session', 'follow', {
-      request: { address: { kind: 'session', sessionId }, maxMessages: 1 },
+      request: { address, maxMessages: 1 },
     }, deadline(signal, SYNTHETIC_DEADLINE_MS));
     for await (const frame of frames) {
       if (frame && frame.type === 'snapshot' && Number.isSafeInteger(frame.cursor)) {
@@ -31,7 +54,7 @@ async function historyViaPage(ctx, payload, signal) {
     return fail(error);
   }
   const request = {
-    address: { kind: 'session', sessionId },
+    address,
     throughSeq,
     ...pick(payload, ['maxMessages', 'beforeSeq', 'turnWindow']),
   };

package/lib/mobile/monitor.js

@@ -0,0 +1,135 @@
+'use strict';
+
+/**
+ * GET /api/mobile/v1/monitor —— 安卓后台提醒服务专用的「状态位」视图（只读）。
+ *
+ * 为什么单开一条：那条前台服务活在 JS 之外（App 退到后台、进程被系统回收，只有它还在），
+ * 所以「这一轮跑完了 / 跑挂了 / 停下来等你回话」只能由它自己定时去问。它此前问的是完整
+ * 会话清单（`?fresh=1`），而那份清单为了画侧栏还捎着**最后一条消息预览** —— 预览要为最近
+ * 20 个会话各读一次 history。后台每 8 秒白读 20 次日志，只为判断「completed 翻没翻」。
+ *
+ * 这条只回监控需要的那几格：在不在跑、刚完成没有、在等谁回话、上一轮是不是跑挂的、标题。
+ * 并支持 `?rev=` 条件刷新：状态位与上次一模一样时回一句 `unchanged`，连 items 都不带
+ * （稳态下这一发是几十字节）。
+ *
+ * 完成态仍以 completion 状态机为准，与 `/sessions` 用同一本账：常态下这里**不读 history**，
+ * 只有「跑过、现在不在跑、结局还没定」的那几条才读一次 —— 那是唯一能把 failedTurn 折出来
+ * 的地方（事件流漏帧时全靠它，见 completion.js 的坑）。
+ *
+ * 刻意不进 `/sessions`：那边一旦按调用方分叉视图，镜像推送与 App 的写后刷新也会跟着
+ * 受影响，而这两条都要求「一份完整清单」。分路由比加参数安全。
+ */
+
+const { sendJson } = require('../shared/http-util');
+const { stableRevision, unchangedListBody } = require('../shared/list-revision.js');
+const { callSessions } = require('./rpc.js');
+const { unwrap } = require('./envelope.js');
+const { listTitle } = require('./history-derive.js');
+const {
+  canonicalDeviceKey, deletedSessionIdsOf, completionGenerationOf,
+} = require('./session-cache.js');
+const { updateCompletionStates, confirmCompletionFromHistory } = require('./completion.js');
+const { sessionPreviewFor } = require('./session-preview.js');
+const { workspaceSessionFlags, pendingInteractionOf } = require('./session-flags.js');
+
+/**
+ * 一条会话在监控视图里的那几格。
+ *
+ * 字段名与完整清单**逐字一致**（sessionId / title / running / completed / pendingInteraction /
+ * lastTurnError），因为原生那边解析的是同一套字段：换名字就得同步改 Kotlin，而那段代码
+ * 在 App 之外，改错一次是「后台永远不提醒」这种看不见的故障。
+ */
+function monitorItem(summary, state) {
+  const item = {
+    sessionId: summary.sessionId,
+    title: listTitle(summary),
+    running: summary.running === true,
+    completed: state ? state.completed === true : false,
+  };
+  const pending = pendingInteractionOf(summary.sessionId, summary);
+  if (pending) item.pendingInteraction = pending;
+  if (state && state.failure) item.lastTurnError = state.failure;
+  return item;
+}
+
+/**
+ * 状态位视图：一次宿主 list + 归档集合，**零次 history 读取**（除非有刚跑完还没定结局的）。
+ *
+ * 返回 `{ items, revision }`；宿主列表形状不对时返回 `{ degraded: true }`，宿主报错时返回
+ * `{ error }` —— 两种都由调用方照 `/sessions` 的口径回，别在这里编一个空清单：空清单会被
+ * 原生当成「所有会话都没了」，基线一清，下一轮就为所有正在跑的会话重新报一次完成。
+ */
+async function buildMonitorState(ctx, deviceKey) {
+  const { value, error } = unwrap(await callSessions(ctx, 'list', {}, 'mobile'));
+  if (error) return { error };
+  const summaries = Array.isArray(value) ? value : (value && Array.isArray(value.items) ? value.items : null);
+  if (summaries === null) return { degraded: true };
+
+  const generation = completionGenerationOf(ctx, deviceKey);
+  const deleted = deletedSessionIdsOf(ctx);
+  const { archived } = await workspaceSessionFlags(ctx);
+  const live = summaries.filter((s) => s && typeof s.sessionId === 'string' && s.sessionId
+    && !deleted.has(s.sessionId) && !archived.has(s.sessionId));
+
+  // 状态机跟着这份清单走：归档 / 删除的会话在这里被踢掉，与完整列表同一口径。
+  const states = updateCompletionStates(ctx, live, deviceKey);
+
+  // 结局还没定的那几条：跑过、现在不在跑、既没完成也没失败。常态下这个集合是空的。
+  const unsettled = live.filter((s) => {
+    if (s.running) return false;
+    const state = states.get(s.sessionId);
+    return state && state.wasRunning === true && state.running !== true
+      && state.completed !== true && !state.failure;
+  });
+  if (unsettled.length > 0) {
+    await Promise.all(unsettled.map(async (summary) => {
+      try {
+        const preview = await sessionPreviewFor(ctx, summary);
+        if (!preview.events.length) return;
+        // 读到这些历史的这一刻，别处可能刚发起一次写后刷新（它会 bump 代次）；
+        // 用旧快照去确认结局等于把「还在跑的一轮」写成已完成。
+        if (completionGenerationOf(ctx, deviceKey) !== generation) return;
+        confirmCompletionFromHistory(states.get(summary.sessionId), preview.events, false);
+      } catch {
+        // 这一轮没读到就原样留着：判定条件（没完成、没失败）下一轮仍然成立，会再试。
+      }
+    }));
+  }
+
+  const items = live.map((summary) => monitorItem(summary, states.get(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();
+
+  let built;
+  try {
+    built = await buildMonitorState(ctx, deviceKey);
+  } catch (error) {
+    return sendJson(res, 500, {
+      ok: false,
+      error: { code: 'monitor-failed', message: (error && error.message) || '监控视图构建失败' },
+    });
+  }
+  if (built.error) return sendJson(res, 400, { ok: false, error: built.error });
+  if (built.degraded) {
+    // 与 /sessions 同一个码：中转见到 5xx 会退回上一份好副本，手机那侧因此是「没收到新东西」
+    // 而不是「一台会话都没有」。
+    return sendJson(res, 500, {
+      ok: false,
+      error: { code: 'host-session-list-degraded', message: '宿主会话列表形状异常：响应里没有 items 数组' },
+    });
+  }
+
+  const body = { ok: true, generatedAt: Date.now(), revision: built.revision, items: built.items };
+  sendJson(res, 200, unchangedListBody(body, rev) || body);
+}
+
+module.exports = { handleMonitor, buildMonitorState, monitorItem };

package/lib/mobile/session-flags.js

@@ -0,0 +1,63 @@
+'use strict';
+
+/**
+ * 会话行的两条共享判定：**哪些会话算这条设备的会话**、**它是不是在等人回话**。
+ *
+ * 抽出来的理由：`/sessions`（完整列表）与 `/monitor`（后台提醒的状态位视图）都要这两条，
+ * 而两份各写一遍的坏处不是多写几行，是判据会分叉 —— 表现成「侧栏里根本没有这条会话，
+ * 手机却为它响了一声」，或者「归档掉的会话还在后台提醒你」，从现象看不出是同一条判据
+ * 分家。所以让两条路由问同一个函数。
+ *
+ * 依赖方向：本文件只依赖 envelope / approvals / questions，**不** require sessions.js
+ * （否则 sessions.js 引它就成了环，见 module-split.test.cjs 的查环）。
+ */
+
+const { unwrap } = require('./envelope.js');
+const approvals = require('./approvals.js');
+const questions = require('./questions.js');
+
+/**
+ * 宿主的两个**会话集合**（同一次 `workspace.list` 快照里拿到）：
+ *
+ *   - `archivedSessionIds`：已归档的会话。桌面端侧边栏据此把它们藏起来，而
+ *     `sessions.list` 自身**不过滤**归档，所以移动端必须自己读这个集合：此前完全没读，
+ *     App 的「归档会话」写是写成功了（宿主确实把 id 记进了 archivedSessionIds），列表却
+ *     照旧把那一行发回手机，用户看到的就是一次毫无反馈的空操作。
+ *   - `pinnedSessionIds`：已置顶的会话（宿主侧「最近置顶的在前」）。桌面端也只从这份
+ *     快照读置顶，`sessions.list` 的摘要里没有置顶字段，所以移动端同样要自己读，
+ *     否则 App 既画不出置顶标记、也排不到工作区最前。
+ *
+ * 两个集合合并成一次 RPC：它们同源同一次快照，而会话列表每 10 秒就会重建一次，
+ * 分两次 `workspace.list` 等于平白给手机多塞一轮往返。
+ *
+ * 取不到时两个集合都回空（失败放开）：宁可多显示几行、少几个置顶，也不能因为一次
+ * RPC 抖动让整个会话列表凭空变空。
+ */
+async function workspaceSessionFlags(ctx) {
+  try {
+    const resp = await ctx.apiProxy.workspace.list({ rpcId: 'mobile', method: 'workspace.list', payload: {} });
+    const value = unwrap(resp).value;
+    const idSetOf = (field) => new Set(
+      value && Array.isArray(value[field]) ? value[field].filter(id => typeof id === 'string') : [],
+    );
+    return { archived: idSetOf('archivedSessionIds'), pinned: idSetOf('pinnedSessionIds') };
+  } catch {
+    return { archived: new Set(), pinned: new Set() };
+  }
+}
+
+/**
+ * 「这条会话是不是在等人回话」以及等的是什么。
+ *
+ * 宿主摘要里带就用它的（0.1.x / 桌面口径）；0.2.x 的宿主摘要**不带**这个字段（桌面上
+ * 那个标记是桌面客户端自己算的），这时用两道桥的账 —— 少了这一条，手机在列表页连黄点
+ * 都不会亮，后台也不会为「等你审批」响一声。审批优先：一次 turn 里审批总是挡在提问前面。
+ */
+function pendingInteractionOf(sessionId, summary) {
+  const reported = summary && summary.pendingInteraction;
+  if (reported === 'approval' || reported === 'plan-review' || reported === 'question') return reported;
+  if (approvals.hasPending(sessionId)) return 'approval';
+  return questions.pendingKind(sessionId);
+}
+
+module.exports = { workspaceSessionFlags, pendingInteractionOf };

package/lib/mobile/session-snapshot.js

@@ -144,23 +144,15 @@ async function handleMessages(ctx, req, res) {
   let value;
   let error;
   try {
-    if (hasSubagentAddress) {
-      const historyPayload = {
-        parentSessionId,
-        childSessionId: sessionId,
-        mode,
-        maxMessages: payload.maxMessages,
-      };
-      if (payload.beforeSeq !== undefined) historyPayload.beforeSeq = payload.beforeSeq;
-      const controller = new AbortController();
-      ({ value, error } = unwrap(await ctx.apiProxy.subagents.history({
-        rpcId: 'mobile',
-        method: 'subagent.history',
-        payload: historyPayload,
-      }, controller.signal)));
-    } else {
-      ({ value, error } = unwrap(await callSessions(ctx, 'history', payload)));
-    }
+    // 子会话走**同一条** session.page（historyViaPage），只是地址换成带父会话的 durable
+    // 地址：宿主 0.2.1 起子代理已经没有 `subagents.history` 这个远程方法了（它只剩
+    // prompt / interrupt / list），继续调它就是 `host-unavailable` → 手机端一条
+    // 「请求失败 (HTTP 503)」。宿主自己的 page/follow 本来就认 `{kind:'subagent'}` 地址
+    // （见 validateAddress），传对地址即可，不该另借一条已被删掉的接口。
+    const historyPayload = hasSubagentAddress
+      ? { ...payload, parentSessionId, mode }
+      : payload;
+    ({ value, error } = unwrap(await callSessions(ctx, 'history', historyPayload)));
   } catch (thrown) {
     error = normalizeHistoryError(thrown);
   }