dsh-mobile-plugin 0.1.82 → 0.1.85

package/lib/mobile/references.js

@@ -11,8 +11,8 @@
  * 关键：这两个宿主服务 **不在 apiProxy 上** —— 它们是 Typert Remote 服务
  * （dsh-file-reference 的 fileReferences、dsh-session-reference 的
  * sessionReferenceResolver）。手机侧本来就能到它们：dsh-mobile-plugin 与宿主同进程，
- * lib/mobile/sessions.js 已经用 `ctx.get('typertGateway')` 派发过 commands.execute，
- * lib/mobile/plugins.js 也走同一条路读 pluginInventory，这里照搬。
+ * lib/mobile/sessions.js 已经派发过 commands.execute，lib/mobile/plugins.js 也走同一条路
+ * 读 pluginInventory —— 都经 host-bridge/transport.js 的 `invoke`，这里照搬。
  *
  * 两条接口（都只是转发宿主的发现域，不做任何排序或截断之外的加工）：
  *  - GET /api/mobile/v1/file-references?sessionId=…&query=…     → fileReferences.list
@@ -29,17 +29,13 @@
  */
 
 const { sendJson } = require('../shared/http-util');
+const { invoke, UNAVAILABLE: GATEWAY_UNAVAILABLE } = require('./host-bridge/transport.js');
 
 const REFERENCE_ID_MAX_CHARS = 200;       // sessionId 长度上限
 const REFERENCE_QUERY_MAX_CHARS = 200;    // 查询串长度上限（宿主 schema 只要求 string）
 const REFERENCE_MAX_ITEMS = 50;           // 与宿主 session-reference 的 candidateLimit 默认值一致
 const REFERENCE_KINDS = new Set(['file', 'directory']);
 
-/** 宿主网关；宿主没组合 dsh-api-gateway 时返回 null，调用方回 503。 */
-function gatewayOf(ctx) {
-  return (ctx.get && ctx.get('typertGateway')) || null;
-}
-
 /** 网关缺失/命名空间缺失对客户端是同一件事：宿主这个能力没装。 */
 const UNAVAILABLE = Object.freeze({
   code: 'reference-unavailable',
@@ -54,9 +50,13 @@ function errorText(error) {
 }
 
 /**
- * 经 typertGateway 调一次引用发现。
+ * 经网关调一次引用发现。
+ *
+ * 走 host-bridge/transport.js 的 `invoke`：Peer 身份与「服务/方法不存在」的收敛都在
+ * 那里，本域只做自己的 503/400 翻译。**不要自己直连网关** —— 0.2.1 起
+ * 要求每个请求自带 Peer，绕过去就是对 undefined 读 `.signal`，手机端 @ 补全整块失效。
  *
- * 注意返回值形状：`gateway.invoke()` 返回的是 **decode 后的业务结果本体**
+ * 注意返回值形状：网关回的是 **decode 后的业务结果本体**
  * （dsh-api-gateway/lib/index.js:112 `return decode(descriptor.result, result, …)`），
  * 那层 `{ok:true,value}` 外壳是浏览器传输（connection.rpc.intercept('/api')）加的，
  * invoke 不负责包。所以形状取决于服务声明的 result schema：
@@ -67,28 +67,15 @@ function errorText(error) {
  * @returns {Promise<{value?: unknown, error?: {code: string, message: string}}>}
  */
 async function callReference(ctx, namespace, method, agentId, query) {
-  const gateway = gatewayOf(ctx);
-  if (!gateway) return { error: { ...UNAVAILABLE } };
-  let result;
-  try {
-    // 两个方法的声明参数都是 agent(wire=agentId) + query(wire=query)，args 必须精确匹配；
-    // 末位 signal 是可选的取消边界（gateway 会补 NEVER_ABORTED_SIGNAL），这里给真的，
-    // 客户端断开时能让宿主那次发现提前收工。
-    result = await gateway.invoke({
-      namespace,
-      method,
-      args: { agentId, query },
-      signal: new AbortController().signal,
-    });
-  } catch (error) {
-    // 0.2.0 的网关错误码带 `gateway/` 前缀（dsh-api-gateway/src/types.ts:117-136）；
-    // 0.1.x 时期是不带前缀的。两种都认，否则「宿主没装这个服务」的降级分支形同虚设。
-    const raw = error && typeof error.code === 'string' ? error.code.replace(/^gateway\//, '') : ''
-    const code = raw === 'invocation-unavailable' || raw === 'service-unavailable' || raw === 'method-unavailable'
-      ? UNAVAILABLE.code
-      : 'reference-error';
-    return { error: { code, message: errorText(error) } };
+  // 两个方法的声明参数都是 agent(wire=agentId) + query(wire=query)，args 必须精确匹配；
+  // 末位 signal 是可选的取消边界（gateway 会补 NEVER_ABORTED_SIGNAL），这里给真的，
+  // 客户端断开时能让宿主那次发现提前收工。
+  const called = await invoke(ctx, namespace, method, { agentId, query }, new AbortController().signal);
+  if (called.error) {
+    if (called.error.code === GATEWAY_UNAVAILABLE.code) return { error: { ...UNAVAILABLE } };
+    return { error: { code: 'reference-error', message: errorText(called.error) } };
   }
+  const result = called.value;
   // 正常形状：裸数组（宿主声明的 result 就是数组）
   if (Array.isArray(result)) return { value: result };
   if (result && typeof result === 'object') {

package/lib/mobile/session-cache.js

@@ -85,7 +85,7 @@ function sessionListResponseState(ctx, deviceKey = 'legacy') {
 function sessionCleanupStateOf(ctx) {
   let state = deletedSessionState.get(ctx);
   if (!state) {
-    state = { deleted: new Set(), pendingUnarchive: new Set() };
+    state = { deleted: new Set() };
     deletedSessionState.set(ctx, state);
   }
   return state;
@@ -96,7 +96,6 @@ function rememberDeletedSessionIds(ctx, sessionIds) {
   for (const sessionId of sessionIds) {
     if (typeof sessionId !== 'string' || !sessionId) continue;
     state.deleted.add(sessionId);
-    state.pendingUnarchive.add(sessionId);
   }
 }
 
@@ -104,15 +103,6 @@ function deletedSessionIdsOf(ctx) {
   return sessionCleanupStateOf(ctx).deleted;
 }
 
-function pendingUnarchiveSessionIdsOf(ctx) {
-  return sessionCleanupStateOf(ctx).pendingUnarchive;
-}
-
-function clearPendingUnarchiveSessionIds(ctx, sessionIds) {
-  const pending = sessionCleanupStateOf(ctx).pendingUnarchive;
-  for (const sessionId of sessionIds) pending.delete(sessionId);
-}
-
 function sessionPreviewStateOf(ctx) {
   let state = sessionPreviewCache.get(ctx);
   if (!state) {
@@ -162,24 +152,41 @@ function completionStateOf(ctx, deviceKey = 'legacy') {
   return states;
 }
 
+function completionStateMapsOf(ctx) {
+  return [...(completionStates.get(ctx)?.values() || [])];
+}
+
 /**
- * 清掉某个会话在**所有**设备维度上的完成提醒，返回真正清掉的设备数。
+ * 标记「这条会话读过了」：记一个水位，把当前的完成 / 失败提醒清掉，返回清掉的条数。
  *
- * 与 handleSessionRead 里那句 `completionStateOf(ctx, deviceKey).delete(...)` 的区别：
- * 那个只清「刚点开的那台手机」自己的提醒（每台手机各有一份，互不干扰）；这个用于
- * **桌面端说「我读过了」**——读一次就是读过了，不该只清某台设备。
+ * **不删条目**（旧实现是 delete）。删掉之后重建的条目会丢掉水位，于是「读过的轮次」
+ * 会在下一次 history 折叠里重新点亮 —— 2026-10-17 真机：桌面读过之后手机上红点 / 绿点
+ * 还在或者反过来。水位才是「这个时刻之前的轮次不算数」的唯一凭据。
+ */
+function markCompletionRead(ctx, deviceKey, sessionId, at = Date.now()) {
+  const state = completionStates.get(ctx)?.get(deviceKey)?.get(sessionId);
+  if (!state) return 0;
+  const had = state.completed === true || !!state.failure;
+  state.clearedAt = at;
+  state.completed = false;
+  state.failure = undefined;
+  // 已读要压过「本进程看见过它跑」这一条（见 completion.js 的 baselineOf）：
+  // 否则同一轮会在下一次列表折叠里又亮回来。
+  state.wasRunning = false;
+  return had ? 1 : 0;
+}
+
+/**
+ * 清掉某个会话在**所有**设备维度上的完成提醒，返回真正清掉过的设备数。
  *
- * 清掉（而不是标记成已读）是刻意的：重建出来的条目 `wasRunning` 为 false，历史折叠
- * （completion.js 的 confirmCompletionFromHistory）会因此拒绝确认，于是**之后**完成的
- * 轮次照样能重新亮起来 —— 「新一轮完成压过更早的已读」这条语义就落在这里。
+ * 用于**桌面端说「我读过了」**——读一次就是读过了，不该只清某台设备。手机上点开
+ * 走 markCompletionRead 只清自己那台（每台手机各有一份，互不干扰）。
  */
-function clearCompletionForAllDevices(ctx, sessionId) {
+function clearCompletionForAllDevices(ctx, sessionId, at = Date.now()) {
   const byDevice = completionStates.get(ctx);
   if (!byDevice) return 0;
   let cleared = 0;
-  for (const states of byDevice.values()) {
-    if (states.delete(sessionId)) cleared += 1;
-  }
+  for (const deviceKey of byDevice.keys()) cleared += markCompletionRead(ctx, deviceKey, sessionId, at);
   return cleared;
 }
 
@@ -283,14 +290,14 @@ module.exports = {
   invalidateSessionList,
   rememberDeletedSessionIds,
   deletedSessionIdsOf,
-  pendingUnarchiveSessionIdsOf,
-  clearPendingUnarchiveSessionIds,
   dropSessionListCache,
   sessionPreviewStateOf,
   sessionPreviewInFlightStateOf,
   sessionPreviewClockOf,
   mirrorHistoryStateOf,
   completionStateOf,
+  completionStateMapsOf,
+  markCompletionRead,
   clearCompletionForAllDevices,
   completionGenerationOf,
   bumpCompletionGeneration,

package/lib/mobile/session-send.js

@@ -17,10 +17,11 @@ const { unwrap } = require('./envelope.js');
 const { callSessions, mobilePromptRpcId } = require('./rpc.js');
 const {
   canonicalDeviceKey, invalidateSessionList, invalidateSessionModels,
-  completionStateOf, sendIdempotencyStateOf,
+  markCompletionRead, sendIdempotencyStateOf,
 } = require('./session-cache.js');
 const { promptErrorObject, MODEL_UNAVAILABLE_ERROR } = require('./history-derive.js');
 const { withIdempotency, requestIdOf } = require('./idempotency.js');
+const { invoke, UNAVAILABLE: GATEWAY_UNAVAILABLE } = require('./host-bridge/transport.js');
 const readReceipt = require('../read-receipt.cjs');
 
 const SEND_MAX_BODY = 8 * 1024 * 1024; // /send 请求体上限（图片 base64）
@@ -34,7 +35,7 @@ function singleTextOf(content) {
 }
 
 /**
- * 经宿主 typertGateway 执行 slash 命令（commands.execute——桌面 Web 端同一条派发路径：
+ * 经网关执行 slash 命令（commands.execute——桌面 Web 端同一条派发路径：
  * 命令注册表命中才执行，绝不经 session.prompt 发给模型；agent 由 agentId 经同一
  * agent 查找器解析，与 session.prompt 的 turnAgentFor 同源，支持冷会话自动 resume）。
  *
@@ -51,18 +52,13 @@ function singleTextOf(content) {
  *   | {error} 查找或派发失败 | {missing} 网关服务未组合（调用方回退普通消息）
  */
 async function executeCommand(ctx, sessionId, line) {
-  const gateway = ctx.get && ctx.get('typertGateway');
-  if (!gateway) return { missing: true };
-  try {
-    const execution = await gateway.invoke({
-      namespace: 'commands',
-      method: 'execute',
-      args: { agentId: sessionId, line, submittedAttachments: [] },
-    });
-    return { execution };
-  } catch (error) {
-    return { error };
+  // 走 host-bridge/transport.js 的 invoke：Peer 身份与「服务/方法不存在」的收敛都在
+  // 那里。这里只把「网关没组合」翻成 {missing}，让调用方回退普通消息。
+  const called = await invoke(ctx, 'commands', 'execute', { agentId: sessionId, line, submittedAttachments: [] });
+  if (called.error) {
+    return called.error.code === GATEWAY_UNAVAILABLE.code ? { missing: true } : { error: called.error };
   }
+  return { execution: called.value };
 }
 
 /**
@@ -172,36 +168,30 @@ async function handleSend(ctx, req, res) {
 }
 
 /** GET /api/mobile/v1/commands?sessionId=…（token）：会话有效命令目录（与桌面 Web 端命令面板
- * 同源——typertGateway commands.list，即服务端命令注册表对该 agent 生效的完整清单）。
+ * 同源——commands.list，即服务端命令注册表对该 agent 生效的完整清单）。
  * 响应：{ 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' } });
-  const gateway = ctx.get && ctx.get('typertGateway');
-  if (!gateway) return sendJson(res, 200, { ok: true, items: [] });
-  try {
-    const descriptors = await gateway.invoke({
-      namespace: 'commands',
-      method: 'list',
-      args: { agentId: sessionId },
-    });
-    const items = Array.isArray(descriptors)
-      ? descriptors
-          .filter((d) => d && typeof d.name === 'string' && d.name && typeof d.description === 'string')
-          .map((d) => ({
-            name: d.name,
-            description: d.description,
-            ...(d.input && typeof d.input === 'object' && typeof d.input.hint === 'string' && d.input.hint
-              ? { input: { hint: d.input.hint } }
-              : {}),
-          }))
-      : [];
-    sendJson(res, 200, { ok: true, items });
-  } catch (error) {
-    // 目录拉取失败不阻塞输入区：降级为空清单（等价桌面网关缺失）。
-    sendJson(res, 200, { ok: true, items: [] });
-  }
+  const called = await invoke(ctx, 'commands', 'list', { agentId: sessionId });
+  const descriptors = called.error ? null : called.value;
+  const items = Array.isArray(descriptors)
+    ? descriptors
+        .filter((d) => d && typeof d.name === 'string' && d.name && typeof d.description === 'string')
+        .map((d) => ({
+          name: d.name,
+          description: d.description,
+          ...(d.input && typeof d.input === 'object' && typeof d.input.hint === 'string' && d.input.hint
+            ? { input: { hint: d.input.hint } }
+            : {}),
+        }))
+    : [];
+  sendJson(res, 200, { ok: true, items });
 }
 
 /** POST /api/mobile/v1/session/read（token）{sessionId}：清除完成提醒。 */
@@ -211,7 +201,8 @@ async function handleSessionRead(ctx, req, res, fallbackDeviceKey = 'legacy') {
     return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '需要 { sessionId }' } });
   }
   const deviceKey = canonicalDeviceKey(req, fallbackDeviceKey);
-  completionStateOf(ctx, deviceKey).delete(body.sessionId);
+  // 只清这台设备自己的提醒；水位留在状态里，读过的轮次就不会再亮回来。
+  markCompletionRead(ctx, deviceKey, body.sessionId);
   // Invalidate the cache and any build already reading history. Its generation
   // check prevents a stale build from restoring `completed` after this ack.
   invalidateSessionList(ctx, deviceKey);

package/lib/mobile/stream.js

@@ -30,6 +30,20 @@ const SSE_RETRY_MS = 3000;
 // internal progress threshold. Pad each SSE record so onprogress exposes it
 // promptly; the padding is an SSE comment and is ignored by clients.
 const SSE_FLUSH_PADDING_BYTES = 2048;
+/**
+ * 写缓冲的两道水位（字节）。`res.write()` 在客户端读得慢时返回 false，字节留在 Node
+ * 的写队列里；以前没人看这个返回值，于是「手机停在一个生成中的会话上、网络又慢」时
+ * 帧无限堆积 —— 2026-10-17 真机现场：堆快照里 17.6 万条 SSE 帧（466MB）挂在
+ * `WriteWrap._chunks` 上，宿主 70 分钟涨到 3.9G 被 OOM 杀掉。
+ *
+ * 两道闸分开，因为两种帧的「丢了能不能补」不一样：
+ *  - 软水位：只丢**没有 seq 的增量帧**（`assistant/chunk`）。它本来就是可丢弃的草稿
+ *    增量，同一轮收尾的 `assistant/message` 带完整正文且有 seq，重连回放能补齐；
+ *  - 硬水位：连有 seq 的帧也放不下了，就返回 false 让上层收尾。客户端带 `lastSeq`
+ *    重连后走 `replaySince` 把缺口补齐 —— 断流可恢复，堆内存不会。
+ */
+const SSE_SHED_BUFFERED_BYTES = 4 * 1024 * 1024;
+const SSE_CLOSE_BUFFERED_BYTES = 16 * 1024 * 1024;
 const REPLAY_WINDOW = 3000; // 断线补偿回放的最大事件数
 
 /**
@@ -74,13 +88,27 @@ function stableEventId(payload, frame) {
   return frame && typeof frame.rpcId === 'string' && frame.rpcId ? frame.rpcId : undefined;
 }
 
+/**
+ * 写一条 SSE 记录。
+ *
+ * @returns {{ok: boolean, shed?: boolean}} `ok:false` 表示这条流该收尾了（客户端已经
+ *   走了，或者写缓冲超过硬水位）；`shed:true` 表示这条**增量**帧被主动丢掉、连接还
+ *   活着（见 SSE_SHED_BUFFERED_BYTES）。
+ *
+ * 丢增量必须只丢没有 seq 的帧：有 seq 的帧是客户端水位的一部分，丢了不回放就在手机
+ * 上留一个永久的洞，那比断流更糟。
+ */
 function writeSse(res, payload, frame) {
+  const buffered = Number(res.writableLength) || 0;
+  if (buffered > SSE_CLOSE_BUFFERED_BYTES) return { ok: false };
   const id = stableEventId(payload, frame);
+  const hasSeq = Number.isFinite(payload && payload.seq);
+  if (buffered > SSE_SHED_BUFFERED_BYTES && !hasSeq) return { ok: true, shed: true };
   const fields = [`retry: ${SSE_RETRY_MS}`];
   if (id) fields.push(`id: ${id}`);
   fields.push(`data: ${JSON.stringify(payload)}`);
   fields.push(`: ${' '.repeat(SSE_FLUSH_PADDING_BYTES)}`, '', '');
-  try { res.write(`${fields.join('\n')}\n`); return true; } catch { return false; }
+  try { res.write(`${fields.join('\n')}\n`); return { ok: true }; } catch { return { ok: false }; }
 }
 
 /**
@@ -163,7 +191,7 @@ async function handleStream(ctx, req, res) {
       if (replay.gap && !ac.signal.aborted) {
         const value = { type: 'session/resync-required', sessionId, resumeSeq, oldestSeq: replay.oldestSeq };
         // 旧实现在这里直接 `return`：既不清 keepAlive 也不 end，漏出一条永不收尾的连接。
-        if (!writeSse(res, value, { payload: value })) clientGone = true;
+        if (!writeSse(res, value, { payload: value }).ok) clientGone = true;
       }
     }
 
@@ -181,25 +209,31 @@ async function handleStream(ctx, req, res) {
           // 回放已覆盖该 seq（回放与实时交界处）→ 跳过，避免重复交付。
           if (seq !== null && seq <= lastDeliveredSeq) continue;
           const event = await resolveEventAttachments(ctx, sessionId, p.event);
-          if (!writeSse(res, event, { ...frame, payload: { ...p, event } })) { clientGone = true; break; }
+          // 被 shed 的只可能是没有 seq 的增量（见 writeSse 的软水位闸）；它不推进水位，
+          // 同一轮收尾的 assistant/message 会把完整正文补上。
+          const sent = writeSse(res, event, { ...frame, payload: { ...p, event } });
+          if (sent.shed) continue;
+          if (!sent.ok) { clientGone = true; break; }
           if (seq !== null) lastDeliveredSeq = seq;
         } else if (p.type === 'session/queue' || p.type === 'session/projection') {
           // 队列/投影整帧转发；不假定存在可重放的宿主 API。
-          if (!writeSse(res, p, frame)) { clientGone = true; break; }
+          const sent = writeSse(res, p, frame);
+          if (sent.shed) continue;
+          if (!sent.ok) { clientGone = true; break; }
         } else if (p.type === 'session/jobs') {
           // 后台任务整帧（桌面端会话头部任务面板的数据源）。宿主只在任务有变化时发，
           // 且**空数组也要转发** —— 那是「任务都结束了」的唯一信号，丢掉它就永远清不掉。
           const value = { type: 'session/jobs', sessionId, jobs: normalizeJobs(p.jobs) };
-          if (!writeSse(res, value, frame)) { clientGone = true; break; }
+          if (!writeSse(res, value, frame).ok) { clientGone = true; break; }
         } else if (p.type === 'question/requested') {
           // 问题是可回答的 mux server-request，而非 session/event；保留 rpcId 供回答关联。
           const value = { ...p, rpcId: frame.rpcId };
-          if (!writeSse(res, value, { ...frame, payload: value })) { clientGone = true; break; }
+          if (!writeSse(res, value, { ...frame, payload: value }).ok) { clientGone = true; break; }
         } else if (p.type === 'question/resolved' || p.type === 'approval/requested' || p.type === 'approval/asked' || p.type === 'approval/decided' || p.type === 'approval/resolved') {
           // Approval frames are server requests/resolutions, not session/event frames;
           // forward the rpcId and approval identity so the mobile client can answer safely.
           const value = ANSWERABLE_APPROVAL_TYPES.has(p.type) && frame.rpcId ? { ...p, rpcId: frame.rpcId } : p;
-          if (!writeSse(res, value, { ...frame, payload: value })) { clientGone = true; break; }
+          if (!writeSse(res, value, { ...frame, payload: value }).ok) { clientGone = true; break; }
         }
       }
       if (!clientGone) loopEnded = true;
@@ -255,7 +289,7 @@ async function replaySince(ctx, sessionId, sinceSeq, res, signal, onDelivered) {
       // Keep replay data identical to live SSE data: the client reducer consumes
       // the event's own type (turn/start, assistant/message, etc.).
       const payload = { type: 'session/event', sessionId, event };
-      if (!writeSse(res, event, { payload })) break;
+      if (!writeSse(res, event, { payload }).ok) break;
       if (Number.isFinite(event.seq)) onDelivered(event.seq);
     }
     return { gap, oldestSeq };

package/lib/relay/tunnel.js

@@ -381,6 +381,35 @@ class RelayTunnel {
     if (this.connected) this.sendJson(T.updatePairing, 0, { pairingCode: code });
   }
 
+  /** 注册帧的载荷。连接建立时发一次，之后元信息变了再由 updateRegistration 重发。 */
+  registrationPayload() {
+    return {
+      instanceId: this.instanceId,
+      pairingCode: this.pairingCode,
+      name: this.name,
+      // 可选：与中转端 TUNNEL_REGISTER_SECRET 对应，防止他人抢注 instanceId。
+      ...(this.registerSecret ? { secret: this.registerSecret } : {}),
+      ...(this.lanUrls.length ? { lanUrls: this.lanUrls } : {}),
+      ...(this.lanCandidates.length ? { lanCandidates: this.lanCandidates } : {}),
+    };
+  }
+
+  /**
+   * 在**现有连接上**重报一次注册信息（配对码 / 名字 / 局域网候选），不断连接。
+   *
+   * 中转那边同一个实例重复注册是幂等的（不会把自己顶掉），所以这条只是「更新名片」。
+   * 以前这类变化是把整条隧道拆了重建，代价是手机所有在途请求一起断——真机现场就是
+   * 「切个网络，接下来几秒点什么都失败」。真正决定「连到哪台」的字段（实例、中转
+   * 地址、注册密钥）不在这里更新，它们变了必须重建，由 worker 的 configure 判定。
+   */
+  updateRegistration(patch = {}) {
+    if (typeof patch.pairingCode === 'string' && patch.pairingCode) this.pairingCode = patch.pairingCode;
+    if (typeof patch.name === 'string') this.name = patch.name;
+    if (Array.isArray(patch.lanUrls)) this.lanUrls = patch.lanUrls.slice();
+    if (Array.isArray(patch.lanCandidates)) this.lanCandidates = patch.lanCandidates.slice();
+    if (this.connected) this.sendJson(T.register, 0, this.registrationPayload());
+  }
+
   /**
    * 回传桌面端弹窗授权结果：approved + 桌面签发的移动 token（拒绝时无 token）。
    * `hostPlatform` 是**宿主自己的** `process.platform`，经中转原样回给手机，
@@ -445,15 +474,7 @@ class RelayTunnel {
       });
 
       ws.on('open', () => {
-        this.sendJson(T.register, 0, {
-          instanceId: this.instanceId,
-          pairingCode: this.pairingCode,
-          name: this.name,
-          // 可选：与中转端 TUNNEL_REGISTER_SECRET 对应，防止他人抢注 instanceId。
-          ...(this.registerSecret ? { secret: this.registerSecret } : {}),
-          ...(this.lanUrls.length ? { lanUrls: this.lanUrls } : {}),
-          ...(this.lanCandidates.length ? { lanCandidates: this.lanCandidates } : {}),
-        });
+        this.sendJson(T.register, 0, this.registrationPayload());
       });
       ws.on('message', (data, isBinary) => push(Buffer.isBuffer(data) ? data : Buffer.from(data)));
       ws.on('close', (code, reason) => {

package/lib/session-cleanup.cjs

@@ -9,11 +9,13 @@
  *    CANONICAL_LOG_FILENAME + compressionSuffix：0 代不带 vN，压缩时才带 .zstd）。
  *    曾经只认 `session.jsonl.zstd`，于是 0.2.0 真在用的 `session.v4.jsonl.zstd`
  *    一个都认不到 —— 表现是「清理已归档」恒回 `deleted: 0`，静默不删。
- *  - 删之前先从宿主归档集合里摘掉这些 id：宿主不会自己修剪，删完还留着就是「已归档」
- *    里一排点不开的死行，且每清一次只增不减。
  *  - 解压用 Node 自带的 zstd（DSH 自己就是这么读写日志的，宿主并不需要系统 zstd
  *    命令），不再 shell 出去：没装 zstd 命令的机器上它一缺就是 readHeader 静默返回
  *    undefined，整条删除路径空转。id 仍然取自日志第一行那条 header。
+ *  - **进程活着的时候不擦宿主的归档集合**，只删日志；擦集合放到宿主启动时
+ *    （pruneOrphanedArchivedSessionsOnce）。理由写在那个函数上：桌面端的会话列表是
+ *    连上宿主时拉的一份快照 + 之后的事件增量，进程里擦集合等于把已经删掉、却还留在
+ *    快照里的行放回正常列表。
  */
 'use strict'
 
@@ -24,6 +26,9 @@ const zlib = require('node:zlib')
 const DEFAULT_OLDER_THAN_MINUTES = 30
 const MINUTES = 60 * 1000
 
+/** 认为「宿主刚起来」的上限：装载插件只在这段时间里算启动，之后出现的调用只能是热替换。 */
+const BOOT_PRUNE_WINDOW_SECONDS = 60
+
 // 宿主认可的会话日志名。非规范名（迁移中途的临时文件、大写、前导零、带 v0）宿主自己
 // 也不认，这里同样不认 —— 认多了会把没提交的代次当会话删掉。
 const CANONICAL_LOG_FILENAME = /^session(?:\.v[1-9][0-9]*)?\.jsonl(?:\.zstd)?$/
@@ -128,18 +133,12 @@ async function deleteSessionData(sessionIds) {
 }
 
 /**
- * 把已经从磁盘删掉的 id 从宿主归档集合里擦掉（删除路径的最后一步，best-effort）。
- *
- * 宿主不会自己修剪这份集合：日志删了它照样留着那些 id，于是「已归档」里是一排点不开的
- * 死行，而且每清一次就多几条、只增不减。它排在 `deleteSessionData` **之后**：日志没删成
- * 前先擦集合，中途失败就会留下「已取消归档、日志还在」的会话——用户看到的是清理只把会话
- * 移出了归档，还要重启宿主才恢复。先删后擦则日志一没就是真的删掉了，立刻生效；擦失败最多
- * 留一行死行，重试即可。宿主对本来就未归档的 id 是 no-op。
+ * 把一批 id 从宿主归档集合里擦掉（宿主对本来就未归档的 id 是 no-op）。
  *
- * 只传**真删掉**的 id：没匹配到日志的还留着日志，擦掉它的名字只会让那一行消失而没有东西被删。
+ * 唯一的调用方是宿主启动时的孤儿修剪：进程活着的时候擦集合会把桌面端快照里那些已经
+ * 删掉的行放回正常列表，理由见 pruneOrphanedArchivedSessionsOnce。
  *
- * 返回擦失败的 id（`failed`），**不抛异常**：日志已经删成功，擦集合坏了不该让整条清理
- * 报错——那等于告诉用户「没删掉」，而事实上已经删掉了。
+ * 返回擦失败的 id（`failed`），**不抛异常**：修剪是收尾，一条擦不动不该让整轮修剪停摆。
  */
 async function forgetArchivedSessions(ctx, sessionIds, rpcId) {
   const failed = []
@@ -154,6 +153,69 @@ async function forgetArchivedSessions(ctx, sessionIds, rpcId) {
   return failed
 }
 
+/**
+ * 归档集合里那些日志确实已经不在磁盘上的 id。
+ *
+ * 判据是磁盘而不是宿主的会话列表：`sessions.list` 会不会漏一条（比如没有 cwd 的会话、
+ * 宿主服务还没装好）不是这里能判断的，而「归档集合里挂着、磁盘上已经没有日志」正是
+ * 清理真正删掉的那个状态。宿主把会话 id 原样当目录名（`encodeSegment` 对正常 id 恒等），
+ * 所以先用目录名筛掉绝大多数，只对候选读一遍 header 复核 —— 别为了修剪把整库日志解一遍。
+ */
+async function archivedIdsWithoutLogs(archivedSessionIds) {
+  const orphans = new Set(archivedSessionIds)
+  if (orphans.size === 0) return []
+  for (const file of sessionFiles(path.join(dshHome(), 'sessions'))) {
+    const name = path.basename(path.dirname(file))
+    if (!orphans.has(name)) continue
+    const header = await readHeader(file)
+    // 日志读不出来也算「还在」：宁可这一轮不修剪，也不能把一条还有日志的会话移出归档。
+    orphans.delete(name)
+    if (header && typeof header.id === 'string') orphans.delete(header.id)
+    if (orphans.size === 0) break
+  }
+  return [...orphans]
+}
+
+async function pruneOrphanedArchivedSessions(ctx) {
+  const workspaceList = ctx && ctx.apiProxy && ctx.apiProxy.workspace ? ctx.apiProxy.workspace.list : undefined
+  if (typeof workspaceList !== 'function') return 0
+  const rpcId = 'dsh-mobile-plugin-archive-prune'
+  const { value, error } = unwrap(await workspaceList({ rpcId, method: 'workspace.list', payload: {} }))
+  if (error) throw new Error(`workspace.list 失败：${error.message || error.code || '未知错误'}`)
+  const archived = value && Array.isArray(value.archivedSessionIds)
+    ? value.archivedSessionIds.filter((id) => typeof id === 'string' && id)
+    : []
+  const orphans = await archivedIdsWithoutLogs(archived)
+  if (orphans.length === 0) return 0
+  const failed = await forgetArchivedSessions(ctx, orphans, rpcId)
+  return orphans.length - failed.length
+}
+
+/**
+ * 宿主进程启动时修剪一次归档集合，然后整个进程不再碰。
+ *
+ * 这件事只能在启动这一刻做：桌面端的会话列表是「连上宿主时拉的一份快照 + 之后的事件
+ * 增量」，宿主本身没有「删除会话」的接口，插件在磁盘上删日志它也看不见。进程活着的时候
+ * 擦归档集合，宿主会把「归档集合变了」广播给桌面端，桌面端就把它快照里那些其实已经
+ * 没有日志、本来被归档藏着的行放回正常列表 —— 用户报的正是「清理后它们又回来了，重启
+ * DSH 才真的消失」。启动时桌面端还没连上（或正要重连，快照本来就从磁盘重新拉），擦掉
+ * 不会放出任何行。留在集合里的死 id 不显示在任何地方：「已归档」取的是会话列表与归档
+ * 集合的交集，没有日志就没有那一行。
+ *
+ * 用进程级标记而不是模块变量：代际热替换会重跑 apply，而桌面端那条快照挂在同一个进程上。
+ */
+const PRUNE_ONCE = Symbol.for('dsh-mobile-plugin.archived-prune')
+async function pruneOrphanedArchivedSessionsOnce(ctx, log) {
+  if (globalThis[PRUNE_ONCE]) return
+  globalThis[PRUNE_ONCE] = true
+  try {
+    const pruned = await pruneOrphanedArchivedSessions(ctx)
+    if (pruned > 0) log?.(`archived session prune: dropped ${pruned} deleted session ids`)
+  } catch (error) {
+    log?.(`archived session prune failed: ${error && error.message ? error.message : String(error)}`)
+  }
+}
+
 async function cleanupSessions(ctx, args) {
   const list = ctx.apiProxy?.sessions?.list
   const workspaceList = ctx.apiProxy?.workspace?.list
@@ -188,11 +250,9 @@ async function cleanupSessions(ctx, args) {
   }
   if (args.confirm !== true) throw new Error('永久删除需要 confirm: true')
   const ids = selected.map(item => item.sessionId)
-  // 与移动端那条路由同一口径：**先删日志、再擦归档集合**。反过来会在链路中途失败时
-  // 留下「名字已从归档集合消失、日志还在」的会话（看着像只是被移出了归档，得重启宿主
-  // 才恢复）；先删则日志一没就是真的删掉了，立刻生效。擦集合是收尾，失败不改变结果。
+  // 与移动端那条路由同一口径：**只删日志**，归档集合留到宿主下次启动时修剪。进程里擦
+  // 集合会把桌面端快照里那些已经删掉的行放回正常列表（见 pruneOrphanedArchivedSessionsOnce）。
   const deletedIds = await deleteSessionData(ids)
-  await forgetArchivedSessions(ctx, deletedIds, 'dsh-mobile-plugin-session-cleanup')
   return { action: args.action, cwd, selected: ids.length, archived: 0, deleted: deletedIds.length, failed: ids.length - deletedIds.length, sessionIds: deletedIds }
 }
 
@@ -219,4 +279,23 @@ function registerSessionCleanupTool(ctx) {
   }))
 }
 
-module.exports = { cleanupSessions, registerSessionCleanupTool, deleteSessionData, forgetArchivedSessions }
+/**
+ * 装配层的入口：注册 agent 的清理工具，同时在「宿主刚起来」时修剪一遍归档集合。
+ *
+ * 两件事都是会话清理的一部分，所以共用装配层那一处 effect；impl.js 有行数兜底守卫，
+ * 别把实现搬回去。
+ */
+function installSessionCleanup(ctx) {
+  // 「宿主启动时」不能只看进程级标记：升级到这份实现那次是**热替换**进来的（进程早就在跑），
+  // 标记还没被谁设过。那一刻桌面端的会话列表快照里可能正挂着之前删掉的行，擦集合就会把它们
+  // 放回列表。所以只在进程刚起的这点窗口里修剪；晚于它就留给下次启动。
+  if (process.uptime() <= BOOT_PRUNE_WINDOW_SECONDS) {
+    // 修剪先挂：没有 tools 注入的 profile 注册不了工具（外层会吞掉这条错），但归档集合照样要收尾。
+    void pruneOrphanedArchivedSessionsOnce(ctx, (message) => {
+      try { ctx.logger?.info?.(message) } catch { /* 日志失败不影响修剪 */ }
+    })
+  }
+  registerSessionCleanupTool(ctx)
+}
+
+module.exports = { cleanupSessions, registerSessionCleanupTool, installSessionCleanup, deleteSessionData, forgetArchivedSessions, pruneOrphanedArchivedSessions, pruneOrphanedArchivedSessionsOnce }