@mrrisega/dsh-remote 0.7.5 → 0.7.6-beta.10

package/clients/dsh-remote/dsh-bridge.mjs

@@ -82,6 +82,7 @@ import WebSocket from "ws";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import net from "node:net";
 import { execSync, spawnSync } from "node:child_process";
 import { randomBytes, generateKeyPairSync, createHash } from "node:crypto";
 import { pathToFileURL, fileURLToPath } from "node:url";
@@ -557,6 +558,19 @@ let upstreamRefreshInflight = null;
  * 重新解析上游地址(带身份校验;显式 DSH_BRIDGE_UPSTREAM 时是恒等操作)。
  * 上游端口变了(Desktop 换端口 / dsh web 重启到别的端口)时,靠它自愈而不必重启 bridge。
  */
+/** 轻量探测上游是否活着（refreshUpstream 用；4xx/5xx 也算活着）。 */
+async function upstreamReachableForRefresh(url, timeoutMs = 800) {
+  try {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    await fetch(String(url).replace(/\/+$/, "") + "/", { signal: ac.signal });
+    clearTimeout(timer);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 async function refreshUpstream(reason = "") {
   if (upstreamRefreshInflight) return upstreamRefreshInflight;
   const now = Date.now();
@@ -564,7 +578,22 @@ async function refreshUpstream(reason = "") {
   upstreamRefreshedAt = now;
   upstreamRefreshInflight = (async () => {
     try {
-      const found = await discoverUpstream({ relayDir: RELAY_DIR });
+      let found = null;
+      // 🔴 2026-10-25（设备掉线实测）：升级前装的 launchd plist 可能带着安装时的旧端口，
+      // 旧版 discoverUpstream 对「显式 env」**不探测直接采信** → 桥永久连旧端口、每次请求
+      // upstream_unreachable。这里先验证 env：死了就临时忽略它，按插件写的 .dsh-upstream/探测
+      // 重新发现；发现成功后清掉失效 env，后续都不再被它挡。
+      const envUrl = String(process.env.DSH_BRIDGE_UPSTREAM || "").trim().replace(/\/+$/, "");
+      if (envUrl && !(await upstreamReachableForRefresh(envUrl))) {
+        const env2 = { ...process.env };
+        delete env2.DSH_BRIDGE_UPSTREAM;
+        found = await discoverUpstream({ relayDir: RELAY_DIR, env: env2 });
+        if (found && found.url && found.source !== "fallback") {
+          delete process.env.DSH_BRIDGE_UPSTREAM;
+          console.log(`[bridge] 旧上游 ${envUrl} 已不可达 → 改用 ${found.url}（来源 ${found.source}）`);
+        }
+      }
+      if (!found) found = await discoverUpstream({ relayDir: RELAY_DIR });
       if (found.url && found.url !== UPSTREAM) {
         console.log(`[bridge] 上游地址切换: ${UPSTREAM} → ${found.url}（来源 ${found.source}${reason ? `,${reason}` : ""}）`);
         UPSTREAM = found.url;
@@ -630,7 +659,10 @@ export function dcSend(dc, obj) {
  *   · 每轮发送前先排空控制车道，并检查 `ws.bufferedAmount`：超过高水位就停手等它排空。
  *     于是控制帧前面最多只有「高水位 + 一片」的待发字节 —— 默认 64KB + 64KB，手机 1Mbps
  *     下 ≈1s，8Mbps 下 ≈0.13s，远小于 router 的 20s，也满足「大响应传输中 1s 内应答」目标。
- *   · 小帧（交互消息 / SSE 块）单独一条车道，优先于大帧的下一片（交互不被整帧传输拖住）。
+ *   · **数据帧严格 FIFO**（2026-10-24 修）：早期实现让小帧（交互/SSE 块）插到大帧下一片之前，
+ *     这在同一 WS 流里是**乱序** —— 生产表现为手机远程页「历史加载失败：session event stream
+ *     emitted an entry before its opening cursor」。现在只有一个数据队列，大帧按片就地推进，
+ *     绝不因大小/类型被后来的帧超越；只有控制帧（不承载有序数据）保留插队权。
  *   · 阈值 / 分片大小可用环境变量调（见 tunnelBulkOptionsFromEnv），弱网部署可再调低。
  */
 export const TUNNEL_BULK_HWM_DEFAULT = 64 * 1024;    // 发送缓冲高水位（字节）
@@ -679,13 +711,19 @@ export function makePrioritySender({
   let pumping = false;
   let scheduled = false;
   let timerPending = false;
-  const smallQ = []; // 小帧（可整帧直发）：交互消息 / SSE 块 —— 优先于大帧的下一片
-  const bigQ = [];   // 大帧：{ frames: string[], i }
-  const stats = { controlSent: 0, smallSent: 0, bigFrames: 0, bigChunks: 0, waits: 0, dropped: 0 };
-
-  function enqueueBulk(text) {
+  // 🔴 2026-10-24 事故修复：数据帧**必须严格 FIFO**。
+  //   旧实现分「小帧车道 / 大帧车道」，小帧会插到大帧下一片之前 —— 这违反了同一 WS 流里
+  //   消息的顺序语义，生产表现为手机远程页「历史加载失败：session event stream emitted an
+  //   entry before its opening cursor（gateway/internal）」：事件流请求/响应被乱序送达，
+  //   客户端的游标推进到了前面，重连时服务端按该游标回放就触发 cursor 错乱。
+  //   现在：控制帧仍可插队（它们是协议控制帧，不承载有序数据）；**数据帧只有一个队列**，
+  //   大帧按片就地推进，绝不因大小/类型被后来的帧超越。
+  const dataQ = []; // { frames: string[], i: number }；frames.length===1 = 未分片小帧
+  const stats = { controlSent: 0, dataSent: 0, bigFrames: 0, bigChunks: 0, waits: 0, dropped: 0 };
+
+  function enqueueData(text) {
     if (text.length <= chunkSize) {
-      smallQ.push(text);
+      dataQ.push({ frames: [text], i: 0 });
       return;
     }
     const cid = `c${++chunkSeq}`;
@@ -695,7 +733,7 @@ export function makePrioritySender({
       frames[i] = JSON.stringify({ __chunk: { id: cid, n, i, data: text.slice(i * chunkSize, (i + 1) * chunkSize) } });
     }
     stats.bigFrames += 1;
-    bigQ.push({ frames, i: 0 });
+    dataQ.push({ frames, i: 0 });
   }
 
   function scheduleNext(waitMs) {
@@ -715,7 +753,7 @@ export function makePrioritySender({
     if (pumping || closed) return;
     pumping = true;
     let yieldMode = ""; // ""=没有剩余，"schedule"=让出事件循环，"poll"=等缓冲排空
-    let budget = 32;    // 一轮最多发多少条小帧
+    let budget = 64;    // 一轮最多发多少条未分片小帧（大帧每轮只发一片）
     try {
       for (;;) {
         // ① 控制车道永远先走：哪怕大帧正传着 16MB，控制帧也在**下一轮**第一时间出去。
@@ -724,31 +762,31 @@ export function makePrioritySender({
           try { rawSend(frame); stats.controlSent += 1; } catch { closed = true; }
         }
         if (closed) { yieldMode = ""; break; }
-        // ② 小帧优先于大帧的下一片：大包传输期间，交互消息 / SSE 块不该排在它后面。
-        if (smallQ.length > 0 && budget > 0) {
-          try { rawSend(smallQ.shift()); stats.smallSent += 1; } catch { closed = true; break; }
+        if (dataQ.length === 0) { yieldMode = ""; break; }
+        if (budget <= 0) { yieldMode = "schedule"; break; }
+        const head = dataQ[0];
+        if (head.frames.length === 1) {
+          // 未分片小帧：可连着多发几条，但绝不越过队头（保证 FIFO）
+          try { rawSend(head.frames[0]); stats.dataSent += 1; } catch { closed = true; break; }
+          dataQ.shift();
           budget -= 1;
           continue; // 回环顶先查控制车道
         }
-        if (smallQ.length > 0) { yieldMode = "schedule"; break; } // 一轮预算用完
-        if (bigQ.length === 0) { yieldMode = ""; break; }
-        // ③ 背压：已入队字节超过高水位 → 停手等排空，别把控制帧埋进几十秒的队列里。
+        // 队头是大帧：每轮只推一片，片间让出事件循环（控制帧/入站帧不被饿死），顺序不变
         let pending = 0;
         try { pending = Number(bufferedAmount()) || 0; } catch { pending = 0; }
         if (pending > bulkHighWater) { stats.waits += 1; yieldMode = "poll"; break; }
-        const item = bigQ[0];
-        try { rawSend(item.frames[item.i]); stats.bigChunks += 1; } catch { closed = true; break; }
-        item.i += 1;
-        if (item.i >= item.frames.length) bigQ.shift();
-        yieldMode = "schedule"; // 大帧：一片一让，给入站帧 / 控制帧 / 小帧机会
+        try { rawSend(head.frames[head.i]); stats.dataSent += 1; stats.bigChunks += 1; } catch { closed = true; break; }
+        head.i += 1;
+        if (head.i >= head.frames.length) dataQ.shift();
+        yieldMode = "schedule";
         break;
       }
     } finally {
       pumping = false;
       if (closed) {
         controlQ.length = 0;
-        smallQ.length = 0;
-        bigQ.length = 0;
+        dataQ.length = 0;
       } else if (yieldMode) {
         scheduleNext(yieldMode === "poll" ? pollMs : 0);
       }
@@ -760,7 +798,7 @@ export function makePrioritySender({
     try { text = JSON.stringify(obj); } catch { return false; }
     if (closed) { stats.dropped += 1; return false; }
     if (isControlFrame(obj)) controlQ.push(text);
-    else enqueueBulk(text);
+    else enqueueData(text);
     pump();
     return true;
   }
@@ -769,8 +807,7 @@ export function makePrioritySender({
   function close() {
     closed = true;
     controlQ.length = 0;
-    smallQ.length = 0;
-    bigQ.length = 0;
+    dataQ.length = 0;
   }
 
   return {
@@ -778,11 +815,11 @@ export function makePrioritySender({
     close,
     stats: () => ({
       ...stats,
-      queued: smallQ.length + bigQ.length,
+      queued: dataQ.length,
       controlQueued: controlQ.length,
       closed
     }),
-    hasBacklog: () => smallQ.length > 0 || bigQ.length > 0 || controlQ.length > 0
+    hasBacklog: () => dataQ.length > 0 || controlQ.length > 0
   };
 }
 
@@ -2302,7 +2339,7 @@ async function initE2ee(token) {
     const storeEnabled = process.env.DSH_BRIDGE_E2EE_SESSIONS !== "0";
     const store = e2ee.attachStore(storeDir, { enabled: storeEnabled });
     if (store.restored > 0) {
-      console.log(`[bridge] 🔓 已恢复 ${store.restored} 个 E2EE 会话(加密落盘;手机重启/桥重启后免重新解锁)`);
+      console.log(`[bridge] 🔓 已恢复 ${store.restored} 个 E2EE 会话(加密落盘;安全策略=v2：全部标记「需重新握手」，不复用旧计数)`);
     }
     if (store.discarded) {
       // 丢弃 = 手机手里的旧票必然对不上：后续 ws-open/HTTP 会带 retryable 的 rehandshake 信号，
@@ -2723,9 +2760,109 @@ async function main() {
     console.log("[bridge] 单实例锁检查降级（取不到进程命令行或锁不可写）——照常启动；若出现 code=4000 互踢，本实例会自动让位。");
   }
   process.on("exit", releaseInstanceLock);
+  // 桌面端插件「暂存更新」自动安装（应用退出后生效；见 applyPendingPluginUpdate 注释）
+  startPendingPluginUpdateWatcher();
   return runTunnel();
 }
 
+// ── 桌面端插件「暫存安装」落地（2026-10-24）────────────────────────────────────────────
+// dsh-setup 在桌面应用运行时无法直接改写它的 profile（会触发应用退出/重启），改为暂存到
+// <relayDir>/pending-plugin/ 并写 marker；bridge 常驻、检测到应用退出后自动原子替换插件目录，
+// 用户下次打开应用即加载新版 —— 这样「一键更新」对桌面端也能真正生效（不再需要终端）。
+const PENDING_PLUGIN_MARKER = path.join(RELAY_DIR, ".plugin-update-pending.json");
+const PENDING_PLUGIN_REQUIRED = ["package.json", "lib/index.js", "lib/client.js", "cordis.patch.yml"];
+const PENDING_PLUGIN_DISABLED = process.env.DSH_BRIDGE_PENDING_UPDATE === "0";
+
+/** upstream 端口是否在监听（= DeepSeek Harness 桌面端在运行）。TCP 判断，跨平台。 */
+export function probeUpstreamListening({ host = "127.0.0.1", port, timeoutMs = 400 } = {}) {
+  return new Promise((resolve) => {
+    if (!port) return resolve(false);
+    const sock = net.connect({ host, port });
+    let done = false;
+    const finish = (v) => { if (done) return; done = true; try { sock.destroy(); } catch { /* 忽略 */ } resolve(v); };
+    sock.setTimeout(timeoutMs, () => finish(false));
+    sock.once("connect", () => finish(true));
+    sock.once("error", () => finish(false));
+  });
+}
+function upstreamPortOf(url) {
+  try { const u = new URL(String(url)); return Number(u.port) || (u.protocol === "https:" ? 443 : 80); } catch { return 0; }
+}
+
+/**
+ * 应用暂存的插件更新（仅在桌面应用不在运行时）。原子替换：staging → rename，失败保留旧版。
+ * @returns {{applied:boolean, reason?:string, version?:string, error?:string}}
+ */
+export async function applyPendingPluginUpdate({ relayDir = RELAY_DIR, isAppRunning, now = Date.now(), log = console } = {}) {
+  const markerPath = path.join(relayDir, ".plugin-update-pending.json");
+  let marker;
+  try { marker = JSON.parse(fs.readFileSync(markerPath, "utf8")); } catch { return { applied: false, reason: "no_pending" }; }
+  const stageDir = String(marker.stageDir || "");
+  const profileDir = String(marker.profileDir || "");
+  const name = String(marker.pluginDirName || "dsh-remote-web-plugin");
+  if (!stageDir || !profileDir || !fs.existsSync(stageDir)) {
+    try { fs.rmSync(markerPath, { force: true }); } catch { /* 忽略 */ }
+    return { applied: false, reason: "staging_missing" };
+  }
+  const running = typeof isAppRunning === "function"
+    ? await isAppRunning()
+    : await probeUpstreamListening({ port: upstreamPortOf(UPSTREAM) });
+  if (running) return { applied: false, reason: "app_running" };
+  const dest = path.join(profileDir, name);
+  const stage = `${dest}.staging-${process.pid}`;
+  const backup = `${dest}.backup-${process.pid}`;
+  try {
+    fs.rmSync(stage, { recursive: true, force: true });
+    fs.cpSync(stageDir, stage, { recursive: true });
+    for (const rel of PENDING_PLUGIN_REQUIRED) {
+      if (!fs.existsSync(path.join(stage, rel))) throw new Error(`暂存包缺少 ${rel}`);
+    }
+    fs.rmSync(backup, { recursive: true, force: true });
+    const had = fs.existsSync(dest);
+    if (had) fs.renameSync(dest, backup);
+    try {
+      fs.renameSync(stage, dest);
+    } catch (e) {
+      if (had) { try { fs.renameSync(backup, dest); } catch { /* 忽略 */ } }
+      throw e;
+    }
+    if (had) { try { fs.rmSync(backup, { recursive: true, force: true }); } catch { /* 忽略 */ } }
+    try {
+      fs.writeFileSync(
+        path.join(relayDir, ".plugin-update-applied.json"),
+        JSON.stringify({ version: marker.version, appliedAt: now, profileDir }, null, 2) + "\n"
+      );
+    } catch { /* 忽略 */ }
+    try { fs.rmSync(markerPath, { force: true }); fs.rmSync(stageDir, { recursive: true, force: true }); } catch { /* 忽略 */ }
+    log.info?.(`[bridge] ✅ 插件新版本 ${marker.version} 已自动安装到 ${profileDir}（桌面应用退出后）；重新打开应用即生效`);
+    return { applied: true, version: marker.version };
+  } catch (e) {
+    try { fs.rmSync(stage, { recursive: true, force: true }); } catch { /* 忽略 */ }
+    log.warn?.(`[bridge] 插件暂存安装失败（保留旧版可回退）：${e && e.message ? e.message : e}`);
+    return { applied: false, reason: "apply_failed", error: String((e && e.message) || e) };
+  }
+}
+
+function startPendingPluginUpdateWatcher() {
+  if (PENDING_PLUGIN_DISABLED) return null;
+  let closedStreak = 0;
+  const tick = async () => {
+    try {
+      if (!fs.existsSync(PENDING_PLUGIN_MARKER)) { closedStreak = 0; return; }
+      const running = await probeUpstreamListening({ port: upstreamPortOf(UPSTREAM) });
+      if (running) { closedStreak = 0; return; }
+      closedStreak += 1;
+      if (closedStreak < 2) return; // 连续两次（≈30s）判定不在运行才动手，避开退出/重启瞬间
+      await applyPendingPluginUpdate({});
+      closedStreak = 0;
+    } catch { /* 绝不影响隧道业务 */ }
+  };
+  const t = setInterval(tick, 15_000);
+  t.unref?.();
+  void tick();
+  return t;
+}
+
 // test hooks：镜像页加载看门狗的内部状态（给用例断言"后续请求会撤掉它"，见 test/bridge-html-inject.test.mjs）
 export function __mirrorLoadWatchState() { return mirrorLoadWatch ? { ...mirrorLoadWatch } : null; }
 export function __armMirrorLoadWatch(path) { armMirrorLoadWatch(path); }

package/clients/dsh-remote/e2ee-client.mjs

@@ -792,14 +792,17 @@ export class E2eeService {
           profile: String(row.profile || this.profile),
           epoch: Number(row.epoch) || 0
         });
-        session.verified = row.verified === true;
+        // ★ 2026-10-24 安全升级：从磁盘恢复的会话**一律标记未验证**，必须重新握手后才接受数据流。
+        //   原因：落盘的收发计数可能落后于手机侧（桥在 flush 与退出之间重启过），直接复用旧计数
+        //   会导致 nonce 重放/解不开 → 生产「无法解密」。宁可让手机自动重握手一次，也不冒错帧风险。
+        session.verified = false;
+        session.restoredNeedsHandshake = true;
         session.createdAt = Number(row.createdAt) || usedAt;
         session.usedAt = usedAt;
         this.sessions.set(sessId, session);
-        const guards = { p2b: new SequenceGuard(), b2p: new SequenceGuard() };
-        if (Number.isInteger(row.p2b)) guards.p2b.last = row.p2b;
-        if (Number.isInteger(row.b2p)) guards.b2p.last = row.b2p;
-        this.ctrlCounters.set(sessId, guards);
+        // ★ 计数同样**不恢复**：恢复的会话未验证，重新握手会从 0 重新计数；
+        //   继承旧计数只会在下一次探测时误判「nonce 重放」。
+        this.ctrlCounters.set(sessId, { p2b: new SequenceGuard(), b2p: new SequenceGuard() });
       } catch { /* 单条坏 → 跳过,不影响其它会话 */ }
     }
     this.prune();
@@ -932,7 +935,9 @@ export class E2eeService {
 // 会话持久化原语(2026-10-23;方案/信任边界见 E2eeService.attachStore 上方长注释)
 // ============================================================
 
-export const SESSION_STORE_VERSION = 1;
+// 2026-10-24 → 2：0.7.5 的 v1 库恢复后直接复用旧计数，生产出现「nonce 重放/无法解密」。
+// 升级到 v2 时**旧库一律作废**（restore 里版本不符会 clearSessionStore），手机重新握手一次。
+export const SESSION_STORE_VERSION = 2;
 export const SESSION_STORE_FILE = ".e2ee-sessions.enc";
 /** 会话库 AAD(域分隔;换格式/换用途必须改它,旧文件自动解不开 → 丢弃重握手)。 */
 export const SESSION_STORE_AAD = Buffer.from(`${E2EE_DOMAIN}\x00sessions-store-v1`, "utf8");

package/clients/dsh-remote/test/bridge-control-priority.test.mjs

@@ -151,7 +151,7 @@ test("契约②：发送缓冲高水位以上时停手（控制帧不会被埋
   assert.equal(pos, beforeControl, "排空后第一时间发控制帧（之前的背压不能把它排到分块后面）");
 });
 
-test("契约③：大帧传输中小帧优先（交互不被整帧传输拖住）；close() 丢弃未发内容", () => {
+test("契约③：数据帧严格 FIFO（大小不得插队，2026-10-24 历史游标错乱事故回归）；close() 丢弃未发内容", () => {
   const sock = fakeSocket();
   const sched = makeScheduler();
   const sender = makePrioritySender({
@@ -162,15 +162,23 @@ test("契约③：大帧传输中小帧优先（交互不被整帧传输拖住
   });
   // 大帧刚发出第一片（之后每轮只发一片）
   sender.send({ id: "big3", type: "http", body: "C".repeat(512 * 1024) });
-  // 传输中插入两条小帧（交互消息 / SSE 块）：必须插在大帧的下一片之前，而不是排在整帧之后
+  // 传输中插入两条小帧（交互消息 / SSE 块）：**不得插队**，必须排在大帧之后（FIFO）
   sender.send({ id: "i1", type: "ws-msg", data: "hello" });
   sender.send({ id: "i2", type: "http-chunk", body: "chunk" });
   const ids = sock.frames.map((s) => {
     const o = JSON.parse(s);
     return o.__chunk ? "__chunk" : o.id;
   });
-  assert.deepEqual(ids.slice(0, 3), ["__chunk", "i1", "i2"], "小帧必须插在大帧的下一片之前");
-  assert.equal(sender.stats().bigChunks, 1, "此时大帧只发了 1 片");
+  assert.equal(ids[0], "__chunk", "大帧第一片先发");
+  assert.ok(!ids.slice(0, 3).includes("i1"), "后入队的小帧绝不能插队到大帧分片之前（顺序语义）");
+  for (let i = 0; i < 5000 && sched.pending() > 0; i += 1) { sock.drain(10 * 1024 * 1024); sched.tick(); }
+  const orderedIds = sock.frames.map((s) => {
+    const o = JSON.parse(s);
+    return o.__chunk ? "__chunk" : o.id;
+  });
+  const firstNonChunk = orderedIds.findIndex((id) => id !== "__chunk");
+  assert.ok(firstNonChunk >= 8, `大帧的分片必须全部先发完（首个非分片位置 ${firstNonChunk}）`);
+  assert.deepEqual(orderedIds.slice(firstNonChunk), ["i1", "i2"], "小帧必须在大帧之后、且保持入队顺序");
 
   // close 后：未发内容丢弃，后续 send 返回 false（重连后不能把旧分片发到新连接上）
   const sock2 = fakeSocket();

package/clients/dsh-remote/test/e2ee-session-store.test.mjs

@@ -98,7 +98,7 @@ test("① 加密落盘：文件里没有 MK/SHK/salt 明文，权限 0600，格
   svc.disposeStore();
 });
 
-test("② 重启恢复：新 E2eeService 只凭 MK + 目录恢复 verified 会话 + ctrl 计数，旧票可直接用", () => {
+test("② 重启恢复（2026-10-24 安全策略）：只恢复会话材料但一律标记「需重新握手」，不复用旧计数", () => {
   const dir = tmpDir();
   const svc1 = mkSvc();
   const { sessId, client } = unlock(svc1);
@@ -113,15 +113,12 @@ test("② 重启恢复：新 E2eeService 只凭 MK + 目录恢复 verified 会
   assert.equal(restored.restored, 1);
   assert.equal(restored.discarded, "", "没有作废");
   const session = svc2.sessionOf(sessId);
-  assert.ok(session, "★ 旧 sessId 必须仍可用（这正是持久化的目的）");
-  assert.equal(session.verified, true, "verified 也要恢复（否则数据 WS 仍被判 locked）");
-  assert.equal(svc2.ctrlCounters.get(sessId).p2b.last, 3, "ctrl 防重放计数必须恢复（重启不能重置）");
-  // 恢复的会话密钥仍能正确解密手机端的信封（HTTP 请求）
-  const plain = Buffer.from(JSON.stringify({ m: "GET", p: "/x", h: {}, b: "" }), "utf8");
-  const env = client.seal({ kind: "http", dir: "p2b", counter: 1, data: plain });
-  assert.doesNotThrow(() => svc2.guardHttpRequest(sessId, env), "恢复后的会话必须能过 guardHttpRequest");
-  const opened = session.open({ kind: "http", dir: "p2b", env, counter: env.c });
-  assert.equal(JSON.parse(opened.data.toString("utf8")).p, "/x");
+  assert.ok(session, "旧 sessId 仍能查到（供重新握手复用）");
+  assert.equal(session.verified, false, "★ 恢复后必须未验证（数据 WS 一律先要求重新握手，绝不复用旧计数）");
+  assert.equal(session.restoredNeedsHandshake, true, "必须带「需重新握手」标记，便于上层给手机 rehandshake 信号");
+  assert.equal(svc2.ctrlCounters.get(sessId).p2b.last, -1, "旧计数不得恢复（否则下次探测误判 nonce 重放）");
+  // 未验证前，带旧信封的请求必须被拒（不是静默解密）
+  void client;
   svc2.disposeStore();
 });
 
@@ -243,7 +240,7 @@ test("⑦ 原语契约：save→load→clear 往返；版本/AAD 域隔离；sto
   assert.equal(loaded.payload.sessions.length, 1);
   // 换版本号 → 解不开（旧格式不能冒名顶替）
   const blob = JSON.parse(readFileSync(sessionStorePath(dir), "utf8"));
-  assert.throws(() => decryptSessionStore(MK, { ...blob, v: 2 }), /会话库版本|bad_store/);
+  assert.throws(() => decryptSessionStore(MK, { ...blob, v: SESSION_STORE_VERSION + 1 }), /会话库版本|bad_store/);
   // clear 后读回 absent
   assert.equal(clearSessionStore(dir), true);
   assert.equal(loadSessionStore(dir, MK).reason, "absent");

package/clients/dsh-remote/test/pending-plugin-update.test.mjs

@@ -0,0 +1,96 @@
+/**
+ * 桌面端插件「暂存更新」自动安装（2026-10-24）契约测试。
+ *
+ * 背景：桌面端应用独占自己的 profile，运行中不能改写（会触发应用退出/重启）。
+ * 一键更新在应用运行中只能「暂存」，由常驻 bridge 在检测到应用退出后自动安装，
+ * 用户下次打开应用即生效 —— 否则就会出现「更新成功但版本没变、还得开终端」。
+ *
+ * 这里钉住四条最容易破的语义：
+ *   ① 应用还在运行 → 绝不改写 profile（返回 app_running，marker 保留等待下一轮）；
+ *   ② 应用退出 → 原子替换插件目录、写 applied marker、清掉暂存与 marker；
+ *   ③ 暂存包不完整（缺必需文件）→ 不动旧版，返回 apply_failed；
+ *   ④ 没有 marker → no_pending（定时器空转，绝不能误删东西）。
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { applyPendingPluginUpdate } from "../dsh-bridge.mjs";
+
+function mkTmpDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "dsh-pending-plugin-"));
+}
+
+function writeFile(p, content) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, content);
+}
+
+/** 造一个「旧版插件已安装 + 新版已暂存 + marker」的环境。 */
+function setupFixture({ stageComplete = true } = {}) {
+  const relayDir = mkTmpDir();
+  const profileDir = mkTmpDir();
+  const pluginName = "dsh-remote-web-plugin";
+  const dest = path.join(profileDir, pluginName);
+  // 旧版
+  writeFile(path.join(dest, "package.json"), JSON.stringify({ name: "dsh-remote-web", version: "0.7.4" }));
+  writeFile(path.join(dest, "lib", "index.js"), "// old\n");
+  writeFile(path.join(dest, "lib", "client.js"), "// old\n");
+  writeFile(path.join(dest, "cordis.patch.yml"), "old: true\n");
+  // 新版暂存
+  const stageDir = path.join(relayDir, "pending-plugin");
+  writeFile(path.join(stageDir, "lib", "index.js"), "// new\n");
+  if (stageComplete) {
+    writeFile(path.join(stageDir, "package.json"), JSON.stringify({ name: "dsh-remote-web", version: "0.7.6-beta.2" }));
+    writeFile(path.join(stageDir, "lib", "client.js"), "// new\n");
+    writeFile(path.join(stageDir, "cordis.patch.yml"), "new: true\n");
+  }
+  writeFile(
+    path.join(relayDir, ".plugin-update-pending.json"),
+    JSON.stringify({ version: "0.7.6-beta.2", profileDir, pluginDirName: pluginName, stageDir, stagedAt: Date.now() })
+  );
+  return { relayDir, profileDir, dest, stageDir, pluginName };
+}
+
+test("① 应用仍在运行 → 不改写 profile，marker 保留", async () => {
+  const { relayDir, dest } = setupFixture();
+  const r = await applyPendingPluginUpdate({ relayDir, isAppRunning: async () => true });
+  assert.equal(r.applied, false);
+  assert.equal(r.reason, "app_running");
+  assert.match(fs.readFileSync(path.join(dest, "package.json"), "utf8"), /0\.7\.4/, "旧版必须原样保留");
+  assert.ok(fs.existsSync(path.join(relayDir, ".plugin-update-pending.json")), "marker 必须保留给下一轮");
+});
+
+test("② 应用已退出 → 原子替换为新版，写 applied marker 并清理暂存", async () => {
+  const { relayDir, dest, stageDir } = setupFixture();
+  const r = await applyPendingPluginUpdate({ relayDir, isAppRunning: async () => false });
+  assert.equal(r.applied, true);
+  assert.equal(r.version, "0.7.6-beta.2");
+  assert.match(fs.readFileSync(path.join(dest, "package.json"), "utf8"), /0\.7\.6-beta\.2/, "profile 内必须是新版");
+  assert.match(fs.readFileSync(path.join(dest, "lib", "index.js"), "utf8"), /new/);
+  const applied = JSON.parse(fs.readFileSync(path.join(relayDir, ".plugin-update-applied.json"), "utf8"));
+  assert.equal(applied.version, "0.7.6-beta.2");
+  assert.equal(fs.existsSync(path.join(relayDir, ".plugin-update-pending.json")), false, "marker 必须清掉");
+  assert.equal(fs.existsSync(stageDir), false, "暂存目录必须清掉");
+  // 不留 staging/backup 垃圾
+  const leftovers = fs.readdirSync(path.dirname(dest)).filter((n) => /\.(staging|backup)-/.test(n));
+  assert.deepEqual(leftovers, []);
+});
+
+test("③ 暂存包不完整 → 保留旧版、返回 apply_failed", async () => {
+  const { relayDir, dest } = setupFixture({ stageComplete: false });
+  const r = await applyPendingPluginUpdate({ relayDir, isAppRunning: async () => false });
+  assert.equal(r.applied, false);
+  assert.equal(r.reason, "apply_failed");
+  assert.ok(r.error && /缺少/.test(r.error), "错误里要写清缺哪个文件");
+  assert.match(fs.readFileSync(path.join(dest, "package.json"), "utf8"), /0\.7\.4/, "旧版必须可回退");
+  assert.ok(fs.existsSync(path.join(relayDir, ".plugin-update-pending.json")), "marker 保留，等下次修复后重试");
+});
+
+test("④ 没有 marker → no_pending（定时器不得误动作）", async () => {
+  const relayDir = mkTmpDir();
+  const r = await applyPendingPluginUpdate({ relayDir, isAppRunning: async () => false });
+  assert.equal(r.applied, false);
+  assert.equal(r.reason, "no_pending");
+});