dsh-mobile-plugin 0.5.20 → 0.5.22

package/lib/relay/pairing-payload.cjs

@@ -58,10 +58,18 @@ function pairingPayload(state, lanPort) {
       ? withManualIpv6Candidate(ipv6Candidates(port), state.manualIpv6Url).map(candidate => candidate.url).filter(Boolean)
       : [],
   };
-  return {
-    payload,
-    text: `dshpair://v1?data=${encodeURIComponent(JSON.stringify(payload))}`,
-  };
+  return { payload, text: pairingText(payload) };
+}
+
+/**
+ * 载荷 → 二维码里那一串 `dshpair://`。
+ *
+ * 单独导出是因为**直连隧道那段信息要在拼 text 之前塞进 payload**：隧道窗口是异步起的
+ * （要拉一个节点），拼装函数本身是纯的，不能为了它变成异步。调用方拿到 payload、补上
+ * `tailcat`，再调这里生成 text —— 仍然只有这一处拼格式。
+ */
+function pairingText(payload) {
+  return `dshpair://v1?data=${encodeURIComponent(JSON.stringify(payload))}`;
 }
 
-module.exports = { pairingPayload };
+module.exports = { pairingPayload, pairingText };

package/lib/relay/snapshot-auth.js

@@ -0,0 +1,82 @@
+'use strict';
+
+/**
+ * 读取隔离（镜像快照直回）这层的鉴权。
+ *
+ * `snapshotRead` 命中本地快照时直接序列化好 JSON 回给手机，**绕开了主进程的守卫**。早先
+ * 这里只挡了「协议 v2 要回源信封」那一面，鉴权这一面还开着：只要知道实例号（它就印在配对
+ * 二维码上），不带任何凭据也能经中转读到会话列表、工作区列表。所以这条捷径在回任何快照
+ * 之前，必须自己按主进程守卫同样的口径验一遍凭据。
+ *
+ * 口径（与 `lib/mobile/auth.js` 的 `authOutcome`、`lib/relay/lan-proxy.js` 的 `authOutcome`
+ * 一致，顺序是这里唯一要紧的东西）：
+ *   - 凭据头 / `Authorization: Bearer` / `dsh_lan` cookie 三处，取所有非空候选；
+ *   - 候选里**只要有一枚**是本机签发过的记录，就以记录为准：被吊销、已过期立即判否，
+ *     **不许**再退回更宽松的无状态令牌（否则吊销永远不生效）；
+ *   - 本机**一枚都查不到**时，才回退旧的无状态 HMAC token（升级前配过的老 App 走这条）
+ *     与「中转签发的凭据」。
+ *
+ * 这里不复用 `authOutcome`：那条路每次都要读一遍 relay 状态文件拿实例号，而这是每条高频
+ * 读都走的快路径；实例号、lanSecret 在本进程的 config 里都是现成的，用依赖注入传进来即可。
+ *
+ * @param {object} headers 请求头（原始大小写都行）
+ * @param {{ lookup?: (presented: string) => object|null, verifyLanToken?: (token: string) => boolean }} deps
+ * @returns {boolean} 是否放行；false 时调用方应回源，交给主进程守卫如实驳回。
+ */
+function snapshotAuthorized(headers, deps = {}) {
+  const { lookup, verifyLanToken } = deps;
+  const candidates = credentialCandidates(headers);
+  if (!candidates.length) return false;
+
+  const now = Date.now();
+  for (const presented of candidates) {
+    const known = typeof lookup === 'function' ? lookup(presented) : null;
+    if (!known) continue;
+    if (known.revokedAt) return false;
+    if (known.expiresAt && known.expiresAt <= now) return false;
+    return true;
+  }
+
+  // 本机不认识这些凭据：可能是升级前的 HMAC token，或中转签的。按无状态令牌再验一次。
+  for (const presented of candidates) {
+    try {
+      if (typeof verifyLanToken === 'function' && verifyLanToken(presented)) return true;
+    } catch { /* 验不过就继续看下一枚 */ }
+  }
+  return false;
+}
+
+/** 按大小写不敏感取一个头部的值；数组取第一个，非字符串或空值返回空串。 */
+function headerValue(headers, target) {
+  if (!headers || typeof headers !== 'object') return '';
+  const lower = target.toLowerCase();
+  for (const key of Object.keys(headers)) {
+    if (key.toLowerCase() !== lower) continue;
+    const raw = headers[key];
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    return typeof value === 'string' ? value.trim() : '';
+  }
+  return '';
+}
+
+/** 三条出示凭据的通道：独立凭据头 → Bearer → dsh_lan cookie。去重后返回非空候选。 */
+function credentialCandidates(headers) {
+  const out = [];
+  const seen = new Set();
+  const push = (value) => {
+    if (typeof value !== 'string') return;
+    const token = value.trim();
+    if (!token || seen.has(token)) return;
+    seen.add(token);
+    out.push(token);
+  };
+
+  push(headerValue(headers, 'x-dsh-device-credential'));
+  const bearer = /^Bearer\s+([^\s]+)$/i.exec(headerValue(headers, 'authorization'));
+  if (bearer) push(bearer[1]);
+  const cookie = /(?:^|;\s*)dsh_lan=([^;]+)/.exec(headerValue(headers, 'cookie'));
+  if (cookie) push(cookie[1]);
+  return out;
+}
+
+module.exports = { snapshotAuthorized, credentialCandidates };

package/lib/relay/status.js

@@ -107,6 +107,9 @@ function createStatusView(deps) {
       ...hostMetadata(),
       localPort: webServerPort,
       tunnel: describeTunnel(sidecarSnapshot.tunnel),
+      // 直连隧道（tailcat）：手机据此自己把通道加进来，**不需要重新扫码**。
+      // 没开或起不来就是 null，老手机不认识这个字段也无害。
+      tailcat: typeof deps.getTailcat === 'function' ? deps.getTailcat() : null,
       // 以本进程解析出的实际端口为准：sidecar 的快照里 `port` 才是最终 bind 成功的
       // 那个（它在 listen 之后才拿得到），而这里在探测阶段就已经知道了，两个值一致
       // 才不会让状态接口和二维码互相打架。

package/lib/routes/control-plane.js

@@ -20,6 +20,7 @@ const fs = require('node:fs');
 const net = require('node:net');
 const path = require('node:path');
 const QRCode = require('qrcode');
+const { pairingText } = require('../relay/pairing-payload.cjs');
 const { randomBytes } = require('node:crypto');
 
 const core = require('../relay/core.js');
@@ -285,6 +286,7 @@ function registerControlPlaneRoutes(deps) {
     lanPortInUse,
     getLanPortAdjusted,
     pairingPayload,
+    tailcat,
     restartSidecar,
     // 「手机上最近来过没有」。**只往本机这条状态路由上补**（和 panelUrl 一样），
     // 不动 createStatusView——那份 JSON 手机端也在读，给它加字段是另一个决定。
@@ -503,12 +505,49 @@ function registerControlPlaneRoutes(deps) {
     const webAccess = body.enabled ? webAccessWindow.enable() : webAccessWindow.disable();
     return sendJson(res, 200, { ok: true, webAccess });
   }) });
-  registerRoute({ kind: 'exact', path: '/api/relay/status', handler: localOnly('GET', async (req, res) => sendJson(res, 200, { ...status(), panelUrl: panelUrlOf(req), panelScope: panelScopeOf(req), webAccess: webAccessWindow.status(), ...mobileActivity(), selfCheck: selfCheck.snapshot() })) })
+  registerRoute({ kind: 'exact', path: '/api/relay/status', handler: localOnly('GET', async (req, res) => sendJson(res, 200, { ...status(), tailcat: deps.tailcat && typeof deps.tailcat.status === 'function' ? deps.tailcat.status() : null, panelUrl: panelUrlOf(req), panelScope: panelScopeOf(req), webAccess: webAccessWindow.status(), ...mobileActivity(), selfCheck: selfCheck.snapshot() })) })
+
+  // ── 手机直连隧道（Tailcat）：面板查看与管理 ────────────────────────────────
+  //
+  // 状态那一格已经跟着 `/api/relay/status` 一起回了（`tailcat`），这里再补两条**动作**：
+  // 一是这整条通道的总开关，二是把某台手机从白名单里摘掉。两道都直接转给宿主侧的
+  // tailcat 会话（`lib/tailcat/session.cjs`），面板不碰 tailcat 的任何细节。
+  //
+  // 为什么白名单是「节点公钥」而不是设备 id：隧道那一层只认 WireGuard 公钥，和移动端
+  // 凭据是两套东西 —— 吊销设备凭据并不会把它从隧道白名单里摘掉（见 A3-87）。所以这里
+  // 单独给一个出口，否则「踢一台手机」在隧道这一层无法完成。
+  const tailcatSnapshot = () => {
+    const state = deps.tailcat && typeof deps.tailcat.status === 'function' ? deps.tailcat.status() : null
+    const allowed = deps.tailcat && typeof deps.tailcat.allowedClients === 'function' ? deps.tailcat.allowedClients() : []
+    return { ok: true, status: state, allowedClients: Array.isArray(allowed) ? allowed : [] }
+  }
+  registerRoute({ kind: 'exact', path: '/api/relay/tailcat', handler: localOnly('GET', async (_req, res) => {
+    sendJson(res, 200, tailcatSnapshot())
+  }) })
+  registerRoute({ kind: 'exact', path: '/api/relay/tailcat/enabled', handler: localOnly('POST', async (req, res) => {
+    const body = await readJson(req)
+    if (deps.tailcat && typeof deps.tailcat.setEnabled === 'function') {
+      deps.tailcat.setEnabled(Boolean(body && body.enabled))
+    }
+    sendJson(res, 200, tailcatSnapshot())
+  }) })
+  registerRoute({ kind: 'exact', path: '/api/relay/tailcat/revoke', handler: localOnly('POST', async (req, res) => {
+    const body = await readJson(req)
+    const client = body && typeof body.client === 'string' ? body.client.trim() : ''
+    if (!client) return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '缺少 client' } })
+    const current = deps.tailcat && typeof deps.tailcat.allowedClients === 'function' ? deps.tailcat.allowedClients() : []
+    const next = (Array.isArray(current) ? current : []).filter((key) => key !== client)
+    if (deps.tailcat && typeof deps.tailcat.setAllowed === 'function') {
+      deps.tailcat.setAllowed(next)
+    }
+    sendJson(res, 200, tailcatSnapshot())
+  }) })
   // 面板页本体：设置界面从客户端半边搬到这里，浏览器（或桌面端里的「打开配置页面」）
   // 直接打开它。三条地址吐的是同一份 HTML，分流在 React 侧（见 React/src/Root.tsx）：
   //   /api/relay/panel            看宿主记的「配没配过」，自己决定先走引导还是直接进主页
   //   /api/relay/panel/setup      强制走引导（想再看一遍流程时用）
   //   /api/relay/panel/settings   强制进主页（演示 / 排查时跳过引导）
+  //   /api/relay/panel/debug      强制进调试页（桌面端那颗手机图标点开的就是它）
   // 整页 HTML 不需要 token，但这几条仍然走 localOnly —— 它读的是本机运维界面，
   // 而局域网与中转那两条链路本来就不该看到它（它们带 dsh_pair/dsh_lan 凭据，会被挡掉）。
   const servePanel = (res) => {
@@ -527,6 +566,13 @@ function registerControlPlaneRoutes(deps) {
   registerRoute({ kind: 'exact', path: '/api/relay/panel', handler: localOnly('GET', async (_req, res) => servePanel(res), { allowDocumentNavigation: true }) })
   registerRoute({ kind: 'exact', path: '/api/relay/panel/setup', handler: localOnly('GET', async (_req, res) => servePanel(res), { allowDocumentNavigation: true }) })
   registerRoute({ kind: 'exact', path: '/api/relay/panel/settings', handler: localOnly('GET', async (_req, res) => servePanel(res), { allowDocumentNavigation: true }) })
+  // 调试页与上面几条吐同一份 HTML，分流同样在 React 侧（`React/src/Root.tsx` 认 `/debug`）。
+  //
+  // 为什么它也放开 `allowDocumentNavigation`：这一页唯一的入口是桌面端那颗手机图标弹的窗
+  // （同源 iframe），而社区桌面壳会把接住的链接原地打开、从自定义协议页跳过来必带
+  // `sec-fetch-site: cross-site` —— 与面板页同一条理由。页面本身仍是只读 HTML，
+  // 里面的 fetch 照样被 localOnly 与两小时窗口挡着。
+  registerRoute({ kind: 'exact', path: '/api/relay/panel/debug', handler: localOnly('GET', async (_req, res) => servePanel(res), { allowDocumentNavigation: true }) })
   // 桌面端画布页：整页吐同一份内联 HTML，并在 `</head>` 前补一句「这是桌面端」的标记 ——
   // 画布据此把路由从 BrowserRouter 换成 HashRouter（它被挂在 `/api/relay/canvas` 这种非根
   // 路径下，BrowserRouter 的 `/` 匹配不上会 404）。手机 WebView 那份不带这个标记，一个字不改。
@@ -647,8 +693,25 @@ function registerControlPlaneRoutes(deps) {
     const source = preview && /^https?:\/\/[^\s]+$/i.test(preview.trim())
       ? { ...state, relayUrl: preview.trim().replace(/\/+$/, '') }
       : state
-    const { payload, text } = pairingPayload(source, lanPortInUse())
-    if (!payload.relayUrl && payload.lanUrls.length === 0) {
+    const { payload } = pairingPayload(source, lanPortInUse())
+    // 直连隧道：这一个是「不配中转也能连」的那条路。窗口是现开的一次性小节点（两分钟、
+    // 只放行当场那把钥匙），开不出来就照旧只给局域网与中转——所以它永远只是加一条路，
+    // 不会让原来那套配不上。
+    const tailcat = deps.tailcat && typeof deps.tailcat.openPairingWindow === 'function'
+      ? await deps.tailcat.openPairingWindow(120).catch(() => null)
+      : null
+    if (tailcat) {
+      payload.tailcat = {
+        version: 1,
+        address: tailcat.address,
+        port: tailcat.port,
+        key: tailcat.key,
+        proof: tailcat.proof,
+        expiresAt: tailcat.expiresAt,
+      }
+    }
+    const text = pairingText(payload)
+    if (!payload.relayUrl && payload.lanUrls.length === 0 && !payload.tailcat) {
       sendJson(res, 409, { ok: false, error: '没有可用的局域网或中转连接地址' })
       return
     }
@@ -669,6 +732,9 @@ function registerControlPlaneRoutes(deps) {
         // 的 `lanPort` 不同，不说清楚会让人对着 18787 排查一个根本没在监听的端口。
         lanPort: lanPortInUse(),
         lanPortAdjusted: getLanPortAdjusted(),
+        // 手机拿到的那三样（地址 / 一次性私钥 / 证明串）——只在本机屏幕上出现，
+        // 与二维码同等敏感，所以面板以外的地方不要 log 它。
+        tailcat: tailcat ? { address: tailcat.address, port: tailcat.port, expiresAt: tailcat.expiresAt } : null,
         svg,
       })
     } catch (error) {
@@ -1076,6 +1142,7 @@ const WEB_ACCESS_ROUTES = new Set([
   '/api/relay/panel',
   '/api/relay/panel/setup',
   '/api/relay/panel/settings',
+  '/api/relay/panel/debug',
   '/api/relay/faults',
   // 配对二维码：里面是能派生整条链路密钥的一次性票据，所以它只在两小时窗口开着时给网页看
   // ——窗口由本机设置页亲手开，服务器部署没有「本机屏幕」可看，这条是它唯一的出口。
@@ -1085,6 +1152,10 @@ const WEB_ACCESS_ROUTES = new Set([
   '/api/relay/onboarded',
   '/api/relay/devices',
   '/api/relay/devices/revoke',
+  // 手机直连隧道（Tailcat）的查看与管理。
+  '/api/relay/tailcat',
+  '/api/relay/tailcat/enabled',
+  '/api/relay/tailcat/revoke',
   '/api/relay/revoke-all',
   '/api/relay/config',
   '/api/relay/check-port',

package/lib/routes/mobile-api.js

@@ -12,6 +12,7 @@
  */
 
 const { sendJson } = require('../http/routing.js');
+const { readJsonBody } = require('../shared/http-util.js');
 const { orderCandidates, withManualCandidate, withManualIpv6Candidate } = require('../relay/lan-network.cjs');
 
 const sessions = require('../mobile/sessions.js');
@@ -58,8 +59,13 @@ const { credentialsEntry } = require('../shared/credentials-entry.js');
 const { handleCredentialUpgrade } = require('../mobile/credential-upgrade.js');
 const extensions = require('../mobile/extensions.js');
 const extensionDev = require('../mobile/extension-dev.js');
+const extensionCatalog = require('../mobile/extension-catalog.js');
 const sessionDelivery = require('../mobile/session-delivery.js');
 const { createPhoneRoutes } = require('../mobile/phone/routes.js');
+// 公众号文章库（见 mobile/wechat.js）：AI 在对话里写、手机上翻阅。
+const wechat = require('../mobile/wechat.js');
+// 悬浮宠物的包目录（见 mobile/pets.js）：素材存在电脑上，手机连着哪台就看哪台。
+const pets = require('../mobile/pets.js');
 // 体检接口要自报身份：版本号只有一个来源，就是包自己的 package.json（与 relay/status.js 同）。
 const pkg = require('../../package.json');
 const desktopView = require('../desktop-view.cjs');
@@ -87,7 +93,7 @@ const API_VERSION = '1';
  *   所以它走 route() 即包 guarded。
  */
 function registerMobileRoutes(deps) {
-  const { registerRoute, registerUpgradeRoute, guarded, state, hostMetadata, getSidecarSnapshot, safeLanCandidates, safeIpv6Candidates, lanPortInUse, preview, core, pairingApproval, rotatePairing, terminalService, cliService, phoneService } = deps;
+  const { registerRoute, tailcat, registerUpgradeRoute, guarded, state, hostMetadata, getSidecarSnapshot, safeLanCandidates, safeIpv6Candidates, lanPortInUse, preview, core, pairingApproval, rotatePairing, terminalService, cliService, phoneService } = deps;
   // CLI 会话（`cli-*`）在这张表上分派一次（见 mobile/cli/mobile.js）：它们是 ACP 子进程、
   // 不是宿主的会话，但手机上必须像普通会话一样可用 —— 列表 / 历史 / 发送 / 停止 / 流 /
   // 审批 / 模型全走宿主那套端点。分派发生在 `route()` 里面，下面每条注册都还是原样一行，
@@ -198,6 +204,27 @@ function registerMobileRoutes(deps) {
   // 这里曾写成 `(_ctx, _req, res)`，于是 `res` 是 undefined，而 `sendJson` 的 catch 会把
   // TypeError 当成「连接已关闭」吞掉——既没报错也没回包，请求**永久挂住**；手机 5s 超时后
   // 退回探活接口拿到 ok，报「能连上但不是 DSH 移动端服务」。纯文本的路由表测试抓不到这类错。
+  /**
+   * 直连隧道：一台**已经配过对**的手机把自己的公钥发上来，换回它该拨的地址。
+   *
+   * 这是「插件更新之后老设备不用重新扫码」的那条路：手机手上本来就有这台电脑的凭据，
+   * 只是不知道有隧道这回事。宿主把它的公钥加进白名单、把节点拉起来，再把地址回给它。
+   * 隧道没开（或者这台机器上没有助手）就回 503 + `tunnel-unavailable`，手机照旧走原来的通道。
+   */
+  route('/api/mobile/v1/tunnel', async (_ctx, req, res) => {
+    if (req.method !== 'POST') { sendJson(res, 405, { ok: false }); return }
+    // 信封请求的明文在 `req.body`（守卫解开之后放那儿），原始流已经被守卫读掉了 —— 自己读流
+    // 只会拿到空串，公钥永远为空、一律 400，手机那边看到的却是一句笼统的失败。
+    const body = await readJsonBody(req, 64 * 1024)
+    const publicKey = typeof body?.publicKey === 'string' ? body.publicKey.trim() : ''
+    if (!/^nodekey:[0-9a-f]{64}$/.test(publicKey)) { sendJson(res, 400, { ok: false, error: { code: 'invalid-public-key' } }); return }
+    const entry = tailcat && typeof tailcat.enroll === 'function' ? await tailcat.enroll(publicKey).catch(() => null) : null
+    // 拿不到地址要回一个**非 2xx + 错误码**：手机那侧的 `unwrap` 见到 `ok:false` 会抛，和「请求
+    // 根本没送到」在同一条 catch 里混成一团，界面上就只剩一句笼统的失败（真机上正是这么卡的）。
+    if (!entry) { sendJson(res, 503, { ok: false, error: { code: 'tunnel-unavailable', message: '这台电脑现在给不出隧道地址' } }); return }
+    sendJson(res, 200, { ok: true, address: entry.address, port: entry.port })
+  })
+
   registerRoute({ kind: 'exact', path: '/api/mobile/v1/health', handler: async (_req, res) => {
     sendJson(res, 200, { ok: true, service: 'dsh-mobile-plugin', apiVersion: API_VERSION, version: pkg.version })
   } })
@@ -563,6 +590,13 @@ function registerMobileRoutes(deps) {
   route('/api/mobile/v1/extension/dev/packages', extensionDev.handleDevPackages)
   route('/api/mobile/v1/extension/dev/file', extensionDev.handleDevFile)
 
+  // 随插件 npm 包发布的已审核扩展（见 mobile/extension-catalog.js）：只读包内 extensions/
+  // 这一个固定目录，catalog.json 是审核清单，只有登记过的 slug 才下发。文件清单的 size 与
+  // sha256 由宿主扫目录现算，不信清单里的数字；取文件仍先 resolve 再判前缀，不接受任意路径。
+  // 能力面与开发包那两条同一档 —— 不暴露 shell / 系统设置 / 任意文件读写，也不给写。
+  route('/api/mobile/v1/extension/catalog', extensionCatalog.handleCatalog)
+  route('/api/mobile/v1/extension/catalog/file', extensionCatalog.handleCatalogFile)
+
   // 分享文件的落地通道（App 把手机分享进来的文件分片传上来，见 mobile/uploads.js）。
   // 手机端没有「把文件交给宿主」的路：图片能进 session.send 的 base64 内容块，其它格式
   // 一律进不去。四条端点只做「收字节 → 落盘」：默认落到 `~/.dsh/mobile-inbox/<日期>/<文件名>`，
@@ -664,6 +698,25 @@ function registerMobileRoutes(deps) {
     route('/api/mobile/v1/phone/unbind', phoneRoutes.unbind)
     registerUpgradeRoute({ path: '/api/mobile/v1/phone/control', handler: phoneService.handleUpgrade })
   }
+
+  // 公众号文章库（见 mobile/wechat.js）：文章存在这台电脑上，手机只读。
+  //
+  // 能力面只多「读这一个固定目录」：编号形状卡死（`wx` + 8 位十六进制）、图片名不含斜杠，
+  // 路径全由宿主拼。写文章那条正常走 AI 的工具（`wechat_article_write`）；这里那条 POST
+  // 是给以后「手机上改名 / 删除」留的，App 目前没有入口。
+  route('/api/mobile/v1/wechat/articles', wechat.handleArticleList)
+  route('/api/mobile/v1/wechat/article', wechat.handleArticleRead)
+  route('/api/mobile/v1/wechat/media', wechat.handleArticleMedia)
+  route('/api/mobile/v1/wechat/article/save', wechat.handleArticleWrite)
+  route('/api/mobile/v1/wechat/article/delete', wechat.handleArticleDelete)
+
+  // 悬浮宠物的包目录（见 mobile/pets.js）：内置包随插件包走、只读，用户包在
+  // `$DSH_HOME/storages/mobile-plugin/pets/`。能力面只多「读这两个固定目录 + 删一个用户包」：
+  // id 与文件名都卡成不含斜杠的形状，取文件还要对上列表里那一份，客户端给不了路径。
+  // 建包走 AI 的工具（`pet_pack_write`）；删是人的动作，所以只有那一条 POST。
+  route('/api/mobile/v1/pet/packs', pets.handlePackList)
+  route('/api/mobile/v1/pet/pack/file', pets.handlePackFile)
+  route('/api/mobile/v1/pet/pack/delete', pets.handlePackDelete)
 }
 
 module.exports = { registerMobileRoutes };

package/lib/session-cleanup.cjs

@@ -316,7 +316,7 @@ function restoreQueuedArchivedClearIds(ctx) {
   return queued
 }
 
-async function pruneOrphanedArchivedSessions(ctx) {
+async function pruneOrphanedArchivedSessions(ctx, skip) {
   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'
@@ -325,7 +325,8 @@ async function pruneOrphanedArchivedSessions(ctx) {
   const archived = value && Array.isArray(value.archivedSessionIds)
     ? value.archivedSessionIds.filter((id) => typeof id === 'string' && id)
     : []
-  const orphans = await archivedIdsWithoutLogs(archived)
+  const skipped = skip instanceof Set ? skip : new Set(Array.isArray(skip) ? skip : [])
+  const orphans = (await archivedIdsWithoutLogs(archived)).filter((id) => !skipped.has(id))
   if (orphans.length === 0) return 0
   const failed = await forgetArchivedSessions(ctx, orphans, rpcId)
   return orphans.length - failed.length
@@ -339,10 +340,12 @@ async function pruneOrphanedArchivedSessions(ctx) {
  *    就是一次未捕获的 ENOENT，宿主直接退出。
  *  - **擦归档集合**：桌面端的会话列表是「连上宿主时拉的一份快照 + 之后的事件增量」，
  *    进程活着的时候擦集合，宿主会把「归档集合变了」广播给桌面端，桌面端就把它快照里
- *    那些其实已经没有日志、本来被归档藏着的行放回正常列表 —— 用户报的正是「清理后
- *    它们又回来了，重启 DSH 才真的消失」。启动时快照本来就从磁盘重新拉，擦掉不会放出
- *    任何行。留在集合里的死 id 不显示在任何地方：「已归档」取的是会话列表与归档集合
- *    的交集，没有日志就没有那一行。
+ *    那些其实已经没有日志、本来被归档藏着的行放回正常列表。所以只在启动时擦，而且**本次
+ *    刚删掉日志的 id 这一轮也先不擦**：宿主启动和删日志是并发的，桌面端的快照完全可能
+ *    在删完之前就取走、把这些行带在身上；这时擦集合照样会把它们放回正常列表（一次重启
+ *    之后它们又出现，再重启才消失）。留到下一次启动再擦，那时它们早已没有日志，任何新
+ *    快照里都不会再有这些行。留在集合里的死 id 依然不显示：「已归档」取的是会话列表与
+ *    归档集合的交集，没有日志就没有那一行。
  *
  * 用进程级标记而不是模块变量：代际热替换会重跑 apply，而桌面端那条快照挂在同一个进程上。
  */
@@ -352,9 +355,21 @@ const PRUNE_RETRY_MS = 500
 async function pruneOrphanedArchivedSessionsOnce(ctx, log) {
   if (globalThis[PRUNE_ONCE]) return
   globalThis[PRUNE_ONCE] = true
+  // 本次启动前盘上就已经没有数据的 id：它们早就不在任何新快照里，这一轮可以直接擦。
+  const alreadyDataLess = new Set(sessionIdsWithoutAnyData(readPendingArchivedClearIds()))
+  let skip = []
   // 删日志不碰宿主，先做：越早越好，别等宿主把 workspace 服务挂齐（那时桌面端可能已经连上）。
   try {
     const { deleted, kept } = await deleteQueuedArchivedSessions(log, ctx)
+    // 本次刚删掉日志的 id，这一轮先别擦归档集合，留到下一次启动再擦。
+    //
+    // 桌面端的会话列表是「启动时拉的一份快照 + 之后的事件增量」，宿主没有删除会话的接口，
+    // 插件在磁盘上删日志它看不见 —— 它快照里还留着这些行，本来靠「已归档」藏着。这时一擦
+    // 集合，宿主就广播「归档集合变了」，桌面端把这些其实已经没有日志的行放回正常列表，用户
+    // 看到的就是「重启一次它们又回来了」。留到下一次启动：那时它们早就没有日志，任何新快照
+    // 里都不会再有这些行，擦集合的广播也就放不出东西来。代价是这些空 id 在归档集合里多留
+    // 一次启动（「已归档」取会话列表与归档集合的交集，没有日志就看不见它）。
+    skip = deleted.filter((id) => !alreadyDataLess.has(id))
     if (deleted.length > 0) log?.(`archived clear queue: deleted ${deleted.length} session logs`)
     if (kept.length > 0) log?.(`archived clear queue: ${kept.length} session logs kept for the next start`)
   } catch (error) {
@@ -365,7 +380,7 @@ async function pruneOrphanedArchivedSessionsOnce(ctx, log) {
   // 的死 id 一直没人清（实测宿主重启过一次，315 个没有日志的 id 原样挂着）。
   for (let attempt = 1; attempt <= PRUNE_ATTEMPTS; attempt += 1) {
     try {
-      const pruned = await pruneOrphanedArchivedSessions(ctx)
+      const pruned = await pruneOrphanedArchivedSessions(ctx, skip)
       if (pruned > 0) log?.(`archived session prune: dropped ${pruned} deleted session ids`)
       return
     } catch (error) {

package/lib/sidecar-facade-worker.cjs

@@ -26,6 +26,7 @@ const { lanUrls } = require('./relay/lan-network.cjs')
 const core = require('./relay/core.js')
 const { createReconnectScheduler } = require('./reconnect-scheduler.cjs')
 const { isMirrorSnapshotFresh } = require('./mirror-snapshot.cjs')
+const { snapshotAuthorized } = require('./relay/snapshot-auth.js')
 // 凭据库在这个进程里**只读**（§3.7）：写盘只有宿主主进程一家。签发与吊销都经 IPC 交给它，
 // 本地这份按文件指纹重载 —— 两个进程各持一份内存副本、各自整份覆写，后写的赢，于是
 // 「经中转配上的手机回局域网 401」「吊销被回滚」这两条必然出现。
@@ -242,6 +243,13 @@ function snapshotRead(info) {
   // 镜像只在中转连着时才会有新版本推来（原因见 mirror-snapshot.cjs 的说明）：冻结的快照必须
   // 回源主进程，否则中转一断、局域网仍健康时，新建的会话/工作区在 App 里永远不出现。
   if (!isMirrorSnapshotFresh(localSnapshot)) return null
+  // **鉴权**：这条捷径绕开主进程守卫直接回快照，必须自己验一遍凭据。否则只要知道实例号
+  // （印在配对二维码上），不带任何凭据也能经中转读到会话 / 工作区列表。验不过回 null 回源，
+  // 交给主进程守卫如实驳回（401）；被吊销 / 已过期的凭据同样回落，吊销才不会在这条路上失效。
+  if (!snapshotAuthorized(info && info.headers, {
+    lookup: (presented) => credentials.lookup(presented, config.instanceId),
+    verifyLanToken: (presented) => core.verifyLanToken(config.lanSecret, presented, config.instanceId),
+  })) return null
   let url
   try { url = new URL(String((info && info.path) || ''), 'http://127.0.0.1') } catch { return null }
   const pathname = url.pathname