dsh-mobile-plugin 0.1.92 → 0.1.94

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-models.js

@@ -33,6 +33,12 @@ function safeModelsValue(value) {
     }
   }
   if (typeof value.routable === 'boolean') result.routable = value.routable;
+  if (Array.isArray(value.routableProviders)) {
+    result.routableProviders = [...new Set(value.routableProviders
+      .filter((provider) => typeof provider === 'string' && provider.length > 0)
+      .slice(0, 128)
+      .map((provider) => provider.slice(0, 256)))];
+  }
   if (Array.isArray(value.groups)) {
     result.groups = value.groups
       .filter((group) => group && typeof group.id === 'string' && typeof group.name === 'string' && Array.isArray(group.models))

package/lib/mobile/session-preview.js

@@ -0,0 +1,70 @@
+'use strict';
+
+/**
+ * 会话列表的「最后一条消息」预览：为最近 / 运行中的会话补一次 history 折叠。
+ *
+ * 会话列表的标题与行数据都来自宿主 `sessions.list` 摘要，只有 `lastMessage` 要读日志，
+ * 属于重活，所以只对预览子集做（见 sessions.js 的 SESSIONS_PREVIEW_LIMIT）。
+ *
+ * 同一份预览按会话指纹复用：运行中的会话 `updatedAt` 几乎每轮都在变，指纹于是每轮都变，
+ * 10 秒的列表缓存一到期就要为每个运行中会话重读一次 history；一轮生成里手机侧 15s
+ * 轮询会反复撞上「指纹变了但预览内容其实没变」的中间态，所以另加一个更短的窗口。
+ * 非运行中的会话仍走指纹判定（它们的 updatedAt 不变，指纹不变，本来就不会重读）。
+ */
+
+const { callSessions } = require('./rpc.js');
+const { unwrap } = require('./envelope.js');
+const { deriveMessages, lastMessageOf } = require('./history-derive.js');
+const {
+  sessionPreviewStateOf, sessionPreviewInFlightStateOf, sessionPreviewClockOf,
+} = require('./session-cache.js');
+
+/** 补预览时拉取的消息条数（低到足够取最后一条预览，避免每次重活）。 */
+const HISTORY_FOR_ENRICH = 10;
+/** 运行中会话的预览重读下限。 */
+const RUNNING_PREVIEW_MIN_INTERVAL_MS = 3000;
+
+function sessionPreviewFingerprint(summary) {
+  return `${summary.updatedAt || 0}:${summary.running ? 'running' : 'idle'}:${summary.blank ? 'blank' : 'content'}`;
+}
+
+/** Read one preview at most once per unchanged session revision. */
+async function sessionPreviewFor(ctx, summary) {
+  const sessionId = summary.sessionId;
+  const fingerprint = sessionPreviewFingerprint(summary);
+  const cached = sessionPreviewStateOf(ctx).get(sessionId);
+  if (cached?.fingerprint === fingerprint) return { events: [], lastMessage: cached.lastMessage };
+
+  const inFlight = sessionPreviewInFlightStateOf(ctx);
+  const existing = inFlight.get(sessionId);
+  if (existing?.fingerprint === fingerprint) return existing.promise;
+
+  // 运行中会话的节流（见 RUNNING_PREVIEW_MIN_INTERVAL_MS）：窗口内复用上一次预览，
+  // 不为「updatedAt 又动了一下」再读一遍日志。返回空 events 与 cache-hit 分支一致
+  // ——完成态确认只在真正读回历史时进行，本轮不复用它的边沿判定。
+  const clock = sessionPreviewClockOf(ctx);
+  if (cached && summary.running && Date.now() - (clock.get(sessionId) || 0) < RUNNING_PREVIEW_MIN_INTERVAL_MS) {
+    return { events: [], lastMessage: cached.lastMessage };
+  }
+  clock.set(sessionId, Date.now());
+
+  const promise = Promise.resolve(callSessions(ctx, 'history', {
+    sessionId,
+    maxMessages: HISTORY_FOR_ENRICH,
+  })).then((response) => {
+    const h = unwrap(response);
+    if (h.error) return { events: [], lastMessage: null };
+    const events = (h.value && h.value.events) || [];
+    const messages = deriveMessages(events);
+    const last = lastMessageOf(messages);
+    const lastMessage = last ? { role: last.role, text: last.text.slice(0, 200), at: last.time } : null;
+    sessionPreviewStateOf(ctx).set(sessionId, { fingerprint, lastMessage });
+    return { events, lastMessage };
+  }).finally(() => {
+    if (inFlight.get(sessionId)?.promise === promise) inFlight.delete(sessionId);
+  });
+  inFlight.set(sessionId, { fingerprint, promise });
+  return promise;
+}
+
+module.exports = { HISTORY_FOR_ENRICH, RUNNING_PREVIEW_MIN_INTERVAL_MS, sessionPreviewFingerprint, sessionPreviewFor };

package/lib/mobile/session-send.js

@@ -71,7 +71,13 @@ async function executeCommand(ctx, sessionId, line) {
  */
 function promptOnce(ctx, clientMessageId, payload) {
   const rpcId = mobilePromptRpcId(clientMessageId);
-  if (!clientMessageId) return callSessions(ctx, 'prompt', payload, rpcId);
+  // 把这一发认回去的身份一起送进宿主的 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);
   const state = sendIdempotencyStateOf(ctx);
   const key = `${payload.sessionId}:${clientMessageId}`;
   const now = Date.now();
@@ -79,7 +85,7 @@ function promptOnce(ctx, clientMessageId, payload) {
   if (existing && now - existing.createdAt < 60_000) return existing.promise;
   if (existing) state.delete(key);
 
-  const promise = Promise.resolve(callSessions(ctx, 'prompt', payload, rpcId));
+  const promise = Promise.resolve(callSessions(ctx, 'prompt', request, rpcId));
   // Keep the short-lived record so an in-flight/concurrent send with the same
   // clientMessageId shares one prompt. Only cache a SUCCESS: a rejection must
   // not poison later retries (a transient error should be retryable), so the

package/lib/mobile/session-snapshot.js

@@ -55,8 +55,10 @@ async function buildMessagesSnapshot(ctx, sessionId, limit = MESSAGES_DEFAULT_LI
   const { value, error } = unwrap(await callSessions(ctx, 'history', { sessionId, maxMessages: limit }));
   if (error) return { ok: false, error };
   const events = (value && value.events) || [];
+  // 引用模式：图片只下发 attachmentId，不取字节（见 attachments.js）。正文里本机图片的
+  // 内联仍走 budget，与之前一致。
   const budget = createTextImageBudget();
-  const resolvedEvents = await Promise.all(events.map((entry) => resolveEventAttachments(ctx, sessionId, entry.event || entry, { budget }).then((event) => entry.event ? { ...entry, event } : event)));
+  const resolvedEvents = await Promise.all(events.map((entry) => resolveEventAttachments(ctx, sessionId, entry.event || entry, { budget, referencesOnly: true }).then((event) => entry.event ? { ...entry, event } : event)));
   const messages = deriveMessages(resolvedEvents);
   const lastSeq = events.length ? (eventSeqOf(events[events.length - 1]) ?? 0) : 0;
   const hasMore = !!(value && value.hasMore);
@@ -142,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);
   }
@@ -169,7 +163,7 @@ async function handleMessages(ctx, req, res) {
   // 一页历史共用一个内联图片预算：正文里的本机图片越多，越靠后的那些保持字面 markdown，
   // 而不是让单次响应无限膨胀（见 local-images.js 的三级预算）。
   const budget = createTextImageBudget();
-  const resolvedEvents = await Promise.all(filtered.map((entry) => resolveEventAttachments(ctx, sessionId, entry.event || entry, { budget }).then((event) => entry.event ? { ...entry, event } : event)));
+  const resolvedEvents = await Promise.all(filtered.map((entry) => resolveEventAttachments(ctx, sessionId, entry.event || entry, { budget, referencesOnly: true }).then((event) => entry.event ? { ...entry, event } : event)));
   const messages = deriveMessages(resolvedEvents);
   const hasMore = !!(value && value.hasMore);
   const seqs = events.map(eventSeqOf).filter((seq) => Number.isSafeInteger(seq) && seq >= 0);

package/lib/mobile/sessions.js

@@ -20,22 +20,25 @@
  *   session-mirror.js  镜像整帧构建
  *   session-goal.js    目标条动作
  *   session-presets.js Agent 预设目录
+ *   session-preview.js 列表行的 lastMessage 预览（按会话指纹复用 + 运行中会话的节流）
  *
- * 剩下的就是列表：GET /sessions（10 秒缓存 + fresh 绕过 + 完成态确认）、GET /session、
- * GET /session/stats、新建会话、排队消息动作。**本文件继续从各子模块转出导出**，
+ * 剩下的就是列表：GET /sessions（10 秒缓存 + fresh 绕过 + 完成态确认 + `?rev=` 条件刷新）、
+ * GET /session（单会话摘要）、GET /session/head（正文水位探针）、GET /session/stats、
+ * 新建会话、排队消息动作。**本文件继续从各子模块转出导出**，
  * 所以 lib/mobile 下所有 import 路径一行都不用改。
  */
 
 const { sendJson, readJsonBody } = require('../shared/http-util');
 const { isFreshRequest } = require('../shared/fresh-request');
-const { listRevision } = require('../shared/list-revision.js');
+const { listRevision, unchangedListBody } = require('../shared/list-revision.js');
+// 正文水位信号：session/head 探针直接读它的快照，**不**为了「看起来有值」去现读历史。
+const { sessionSignal } = require('../shared/session-signal.js');
 const { withIdempotency, requestIdOf } = require('./idempotency.js');
 const { listTitle, deriveMessages, lastMessageOf, promptErrorObject, MODEL_UNAVAILABLE_ERROR } = require('./history-derive.js');
 const { unwrap } = require('./envelope.js');
 const { callSessions } = require('./rpc.js');
 const {
   canonicalDeviceKey, sessionListResponseState, invalidateSessionList, deletedSessionIdsOf,
-  sessionPreviewStateOf, sessionPreviewInFlightStateOf, sessionPreviewClockOf,
   completionGenerationOf, bumpCompletionGeneration,
   completionStateOf, sessionModelsStateOf, invalidateSessionModels, sendIdempotencyStateOf,
 } = require('./session-cache.js');
@@ -49,94 +52,39 @@ const { promptOnce, handleSend, handleCommands, handleSessionRead, handleSession
 const { handleSessionSearch } = require('./session-search.js');
 const { handleAgentPresets } = require('./session-presets.js');
 const { handleGoalAction } = require('./session-goal.js');
-const approvals = require('./approvals.js');
-const questions = require('./questions.js');
+const { workspaceSessionFlags, pendingInteractionOf } = require('./session-flags.js');
+// 预览（lastMessage 补全）与它自己的重读节流：只读日志、不发写，单列一个子模块。
+const { HISTORY_FOR_ENRICH, sessionPreviewFor } = require('./session-preview.js');
 
-const HISTORY_FOR_ENRICH = 10;      // 补标题/预览时拉取的消息条数（低到足够取最后一条预览，避免每次重活）
 const SESSIONS_PREVIEW_LIMIT = 20;  // 仅为最近/运行中的会话补最后消息预览
 const SESSION_LIST_CACHE_MS = 10000;  // 会话列表增料缓存（降低手机轮询对桌面的冲击）
-/**
- * 运行中会话的预览重读下限。
- *
- * 运行中的会话 updatedAt 几乎每轮都在变，`sessionPreviewFingerprint` 于是每轮都变，
- * 10 秒的列表缓存一到期就要为每个运行中会话重读一次 history（HISTORY_FOR_ENRICH 条）。
- * 一轮生成里手机侧 15s 轮询会反复撞上「指纹变了但预览内容其实没变」的中间态。
- * 这里给运行中会话单独加一个更短的窗口：窗口内复用上一次预览，不重读日志。
- * 非运行中的会话仍走指纹判定（它们的 updatedAt 不变，指纹不变，本来就不会重读）。
- */
-const RUNNING_PREVIEW_MIN_INTERVAL_MS = 3000;
 
 /**
- * 宿主的两个**会话集合**（同一次 `workspace.list` 快照里拿到）：
+ * GET /api/mobile/v1/session/head?sessionId=…&parentSessionId=…&mode=…（token）
  *
- *   - `archivedSessionIds`：已归档的会话。桌面端侧边栏据此把它们藏起来，而
- *     `sessions.list` 自身**不过滤**归档，所以移动端必须自己读这个集合：此前完全没读，
- *     App 的「归档会话」写是写成功了（宿主确实把 id 记进了 archivedSessionIds），列表却
- *     照旧把那一行发回手机，用户看到的就是一次毫无反馈的空操作。
- *   - `pinnedSessionIds`：已置顶的会话（宿主侧「最近置顶的在前」）。桌面端也只从这份
- *     快照读置顶，`sessions.list` 的摘要里没有置顶字段，所以移动端同样要自己读，
- *     否则 App 既画不出置顶标记、也排不到工作区最前。
+ * 「这条会话的正文到哪个水位了」——App 进对话前先问一句，跟本地缓存水位一比就知道要不要
+ * 重新拉全量历史。几十字节换几兆。
  *
- * 两个集合合并成一次 RPC：它们同源同一次快照，而会话列表每 10 秒就会重建一次，
- * 分两次 `workspace.list` 等于平白给手机多塞一轮往返。
+ * `seq` 取 `sessionSignal.peek(sessionId)`：镜像推送每轮都会 bump，语义正是「快照里真正
+ * 装上的消息的最大 seq」，与 App 的缓存水位同一个 seq 空间。
  *
- * 取不到时两个集合都回空（失败放开）：宁可多显示几行、少几个置顶，也不能因为一次
- * RPC 抖动让整个会话列表凭空变空。
+ * `known` = `seq > 0`。**信号里没有时如实回 `known:false`**（插件刚重启、还没轮到推这个
+ * 会话），让 App 退回全量拉取；绝不为了「看起来有值」现读一次历史——那样这个探针本身
+ * 就变成了它要省掉的那次请求。
+ *
+ * 子代理（带 parentSessionId）直接回 `{seq:0, known:false}`：镜像里刻意不存子会话正文
+ * （见 dev-map A3-14 的「子会话的正文刻意不进镜像」），没有水位可言。
  */
-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() };
-  }
-}
-
-function sessionPreviewFingerprint(summary) {
-  return `${summary.updatedAt || 0}:${summary.running ? 'running' : 'idle'}:${summary.blank ? 'blank' : 'content'}`;
-}
-
-/** Read one preview at most once per unchanged session revision. */
-async function sessionPreviewFor(ctx, summary) {
-  const sessionId = summary.sessionId;
-  const fingerprint = sessionPreviewFingerprint(summary);
-  const cached = sessionPreviewStateOf(ctx).get(sessionId);
-  if (cached?.fingerprint === fingerprint) return { events: [], lastMessage: cached.lastMessage };
-
-  const inFlight = sessionPreviewInFlightStateOf(ctx);
-  const existing = inFlight.get(sessionId);
-  if (existing?.fingerprint === fingerprint) return existing.promise;
-
-  // 运行中会话的节流（见 RUNNING_PREVIEW_MIN_INTERVAL_MS）：窗口内复用上一次预览，
-  // 不为「updatedAt 又动了一下」再读一遍日志。返回空 events 与 cache-hit 分支一致
-  // ——完成态确认只在真正读回历史时进行，本轮不复用它的边沿判定。
-  const clock = sessionPreviewClockOf(ctx);
-  if (cached && summary.running && Date.now() - (clock.get(sessionId) || 0) < RUNNING_PREVIEW_MIN_INTERVAL_MS) {
-    return { events: [], lastMessage: cached.lastMessage };
+async function handleSessionHead(_ctx, req, res) {
+  const url = new URL(req.url, 'http://x');
+  const sessionId = url.searchParams.get('sessionId');
+  if (!sessionId) return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '缺少 sessionId' } });
+  const parentSessionId = url.searchParams.get('parentSessionId');
+  if (parentSessionId !== null && parentSessionId !== '') {
+    return sendJson(res, 200, { ok: true, seq: 0, known: false });
   }
-  clock.set(sessionId, Date.now());
-
-  const promise = Promise.resolve(callSessions(ctx, 'history', {
-    sessionId,
-    maxMessages: HISTORY_FOR_ENRICH,
-  })).then((response) => {
-    const h = unwrap(response);
-    if (h.error) return { events: [], lastMessage: null };
-    const events = (h.value && h.value.events) || [];
-    const messages = deriveMessages(events);
-    const last = lastMessageOf(messages);
-    const lastMessage = last ? { role: last.role, text: last.text.slice(0, 200), at: last.time } : null;
-    sessionPreviewStateOf(ctx).set(sessionId, { fingerprint, lastMessage });
-    return { events, lastMessage };
-  }).finally(() => {
-    if (inFlight.get(sessionId)?.promise === promise) inFlight.delete(sessionId);
-  });
-  inFlight.set(sessionId, { fingerprint, promise });
-  return promise;
+  const seq = sessionSignal.peek(sessionId);
+  sendJson(res, 200, { ok: true, seq, known: seq > 0 });
 }
 
 /** GET /api/mobile/v1/sessions（token） */
@@ -153,6 +101,10 @@ async function handleSessions(ctx, req, res) {
   // 与 fresh 的区别：它只绕开这层缓存，不需要作废在途构建，也不 bump 朝代号（没有写入）。
   const url = new URL(req.url, 'http://x');
   const archivedOnly = url.searchParams.get('archived') === '1';
+  // 条件刷新（?rev=<上次的 revision>）：内容没变就只回一句 unchanged，不带 items。
+  // fresh=1（写后刷新必须拿到真数据）与 archived=1（归档子集不是同一份内容）一律不走。
+  const rev = (url.searchParams.get('rev') || '').trim();
+  const revEligible = !wantFresh && !archivedOnly;
   // 只有新客户端显式带分页参数时才切片；旧客户端不带参数仍拿到完整归档列表。
   const hasPaging = archivedOnly && (url.searchParams.has('offset') || url.searchParams.has('limit'));
   const parsedOffset = Number(url.searchParams.get('offset') ?? 0);
@@ -168,13 +120,21 @@ async function handleSessions(ctx, req, res) {
     cache.updatedAt = 0;
     generation = bumpCompletionGeneration(ctx, deviceKey);
   }
+  // 条件刷新的转换点：拿到**最终要回的 body**之后才判，且只在上面那两条短路条件
+  // （rev 缺失/为空、fresh=1、archived=1）都不成立时才认。unchanged 响应本身不写缓存、
+  // 也不进在途构建的合流判定——它只是同一份内容的一句话说清。
+  const respond = (status, body) => {
+    const unchanged = status === 200 && revEligible ? unchangedListBody(body, rev) : null;
+    return sendJson(res, status, unchanged || body);
+  };
+
   if (!bypassCache && cache.value && now - cache.updatedAt < SESSION_LIST_CACHE_MS) {
-    return sendJson(res, 200, cache.value);
+    return respond(200, cache.value);
   }
 
   if (!bypassCache && cache.promise) {
     const response = await cache.promise;
-    return sendJson(res, response.status, response.body);
+    return respond(response.status, response.body);
   }
 
   // 变更信号（镜像推送调度器先看见清单变了）会调 dropSessionListCache 丢掉这层缓存，
@@ -197,7 +157,7 @@ async function handleSessions(ctx, req, res) {
         cache.updatedAt = Date.now();
       }
     }
-    return sendJson(res, response.status, response.body);
+    return respond(response.status, response.body);
   } finally {
     if (cache.promise === promise) cache.promise = null;
   }
@@ -238,12 +198,8 @@ async function buildSessionsResponse(ctx, deviceKey = 'legacy', generation = com
   // 该项是廉价字段；history 仅用于补「最后消息预览」，属于重活，见下方预览子集。
   const rows = allSummaries.map((s) => {
     const completionState = completionStatesForContext.get(s.sessionId);
-    // 待处理标记：宿主摘要里带就用它的（0.1.x / 桌面口径）；0.2.x 的宿主摘要**不带**这个
-    // 字段（桌面上那个标记是桌面客户端自己算的），这时用两道桥的账 —— 少了这一条，手机在
-    // 列表页连黄点都不会亮。审批优先（一次 turn 里审批总是挡在提问前面）。
-    const pendingInteraction = (s.pendingInteraction === 'approval' || s.pendingInteraction === 'plan-review' || s.pendingInteraction === 'question')
-      ? s.pendingInteraction
-      : (approvals.hasPending(s.sessionId) ? 'approval' : questions.pendingKind(s.sessionId));
+    // 待处理标记：判据与后台监控共用一份（见 session-flags.js），别再在这里写第二份。
+    const pendingInteraction = pendingInteractionOf(s.sessionId, s);
     const base = {
       sessionId: s.sessionId,
       title: listTitle(s),
@@ -455,6 +411,7 @@ module.exports = {
   SESSIONS_PREVIEW_LIMIT,
   handleSessions,
   handleSession,
+  handleSessionHead,
   handleStats,
   handleNew,
   handleQueueUpdate,