@mrrisega/dsh-remote 0.7.2 → 0.7.3-beta.2

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

@@ -117,7 +117,19 @@ const DEFAULT_CONFIG = path.join(
 const CONFIG_PATH = process.env.DSH_BRIDGE_CONFIG || DEFAULT_CONFIG;
 // 隧道模式(唯一):bridge 主动 WS 连 relay-router 的 /_bridge
 const TUNNEL_URL = (process.env.DSH_BRIDGE_TUNNEL_URL || "").replace(/\/+$/, "");
-const TUNNEL_HEARTBEAT_MS = Math.max(100, Number(process.env.DSH_BRIDGE_HEARTBEAT_MS) || 15_000);
+/**
+ * 隧道心跳间隔（C5）。
+ *
+ * 为什么从 15s 调到 20s：生产上"30 秒级断连、75% 的隧道会话活不过 60s"（诊断报告 R2），
+ * 15s 的心跳 + "丢一次 pong 就断" 让弱网（丢包 5%）下的正常抖动被当成故障，
+ * 每次误断都会重连重建隧道 + 打断在途请求。20s 与中继/nginx 的 3600s read timeout 无关，
+ * 只影响"多久发现半开连接"：最坏 3 个心跳周期（≈60s）发现真死的连接，仍远小于移动网络
+ * 常见的 NAT 空闲超时（通常 2~5 分钟）。
+ */
+export const TUNNEL_HEARTBEAT_DEFAULT_MS = 20_000;
+/** 连续丢多少个 pong 才判定隧道已死（C5：旧实现丢 1 次就 terminate，弱网误判率过高）。 */
+export const HEARTBEAT_MAX_MISSED_PONGS = 2;
+const TUNNEL_HEARTBEAT_MS = Math.max(100, Number(process.env.DSH_BRIDGE_HEARTBEAT_MS) || TUNNEL_HEARTBEAT_DEFAULT_MS);
 /**
  * 上游 dsh web 的地址。
  *
@@ -1402,6 +1414,61 @@ async function resolveToken(refresh = false) {
 // ============================================================
 
 let tunnelRetry = 0;
+/** C2：连续收到 close code=4000 的次数（跨 connectTunnel 保留；非 4000 的断开清零）。 */
+let consecutive4000 = 0;
+
+/* ── 重连策略（C2 + C5）────────────────────────────────────────────────────────
+ *
+ * code=4000 的语义（中继 relay-router/src/index.mjs 唯一用途）：**同 deviceId 的新连接
+ * 把本条连接顶掉了**（replaced by new connection）。所以对被踢的一方，"重连"的唯一效果
+ * 是把对方再顶一次 —— 两个实例就这么以 2~3.5s 的周期乒乓（生产日志 dev-a50dced9cc19
+ * 327 次/10min、win32 持续互踢 6 台里 3 台全 0.7.2）。
+ *
+ * 修法（诊断报告 04 §4.4.2 的 P0-1）：
+ *   · 第 1 次 4000 → 长退避 30~60s（是原来 2s 的 15~30 倍），让"新连接"先站稳；
+ *   · 连续第 2 次 4000 → 直接优雅退出（退出码 4），把设备让给对方。watcher 收到 code=4
+ *     会暂停 5 分钟再拉，避免继续对新实例发起第 3 次顶撞。
+ *   · 非 4000 的普通断线保持原有指数退避，但上限 30s→10s 并加 0~3s 抖动（C5）：
+ *     30s 上限会让"一次瞬时断网"恢复得比必要慢得多；抖动则避免多台设备同秒重连造成
+ *     中继/nginx 连接尖峰（诊断 R1 的连接耗尽与重连风暴互相放大）。
+ *     抖动只加在 base ≥4s 的档位：第一档（2s）保持确定值，测试里"5 秒内必须重连"的
+ *     硬期限才不会被随机数撞破。
+ */
+export const DUPLICATE_CLOSE_CODE = 4000;
+/** bridge 判定"本机已有另一个同 deviceId 实例"后的退出码（必须与 dsh-setup.mjs 的常量一致）。 */
+export const DUPLICATE_INSTANCE_EXIT_CODE = 4;
+export const DUPLICATE_RECONNECT_BASE_MS = 30_000;
+export const MAX_RECONNECT_DELAY_MS = 10_000;
+export const RECONNECT_JITTER_MS = 3_000;
+export const RECONNECT_JITTER_MIN_BASE_MS = 4_000;
+
+/**
+ * 算下一次重连：返回 { exit, delayMs, consecutive4000, reason }。
+ * @param {{ code?: number, retry?: number, consecutive4000?: number, rand?: () => number }} args
+ */
+export function reconnectPlan({ code, retry = 0, consecutive4000: prev = 0, rand = Math.random } = {}) {
+  if (code === DUPLICATE_CLOSE_CODE) {
+    const next = Math.max(0, prev) + 1;
+    if (next >= 2) return { exit: true, delayMs: 0, consecutive4000: next, reason: "duplicate-exit" };
+    const delayMs = DUPLICATE_RECONNECT_BASE_MS + Math.floor(rand() * DUPLICATE_RECONNECT_BASE_MS);
+    return { exit: false, delayMs, consecutive4000: next, reason: "duplicate-backoff" };
+  }
+  const n = Math.max(0, retry);
+  const base = Math.min(MAX_RECONNECT_DELAY_MS, 2_000 * 2 ** n);
+  const jitter = base >= RECONNECT_JITTER_MIN_BASE_MS ? Math.floor(rand() * RECONNECT_JITTER_MS) : 0;
+  return { exit: false, delayMs: base + jitter, consecutive4000: 0, reason: "normal" };
+}
+
+/**
+ * 心跳一拍（C5）：连续丢 HEARTBEAT_MAX_MISSED_PONGS 次 pong 才判定隧道已死。
+ * 纯函数，便于单测（"丢 1 次就断"是这次要改掉的旧契约）。
+ */
+export function heartbeatStep({ pongReceived, missedPongs = 0 }) {
+  if (pongReceived) return { missedPongs: 0, terminate: false, ping: true };
+  const missed = Math.max(0, missedPongs) + 1;
+  const terminate = missed >= HEARTBEAT_MAX_MISSED_PONGS;
+  return { missedPongs: missed, terminate, ping: !terminate };
+}
 
 /** 把 DSH_BRIDGE_TUNNEL_URL 归一化为 router 注册端点(缺省补 / _bridge)。 */
 function tunnelEndpoint(raw) {
@@ -1473,6 +1540,7 @@ function connectTunnel(token) {
   const send = makeChunkedSender((s) => { if (ws.readyState === WebSocket.OPEN) ws.send(s); });
   let heartbeat;
   let pongReceived = true;
+  let missedPongs = 0;
 
   ws.on("open", () => {
     tunnelRetry = 0;
@@ -1483,16 +1551,21 @@ function connectTunnel(token) {
       ws.send(JSON.stringify({ type: "tunnel-register", deviceId: DEVICE_ID, token, name: os.hostname() || "dsh-bridge", caps: e2ee.caps() }));
     } catch (e) { console.log(`[bridge] 注册发送失败: ${e.message}`); }
     heartbeat = setInterval(() => {
-      if (!pongReceived) {
-        console.log("[bridge] 隧道心跳超时,主动重连...");
-        ws.terminate();
+      // C5：连续 2 次没收到 pong 才判定半开（旧实现丢 1 次就断 → 弱网下正常的单次丢包
+      // 也会被当成故障重连，直接贡献了"75% 的隧道会话活不过 60s"）。
+      const step = heartbeatStep({ pongReceived, missedPongs });
+      missedPongs = step.missedPongs;
+      pongReceived = false;
+      if (step.terminate) {
+        console.log(`[bridge] 隧道连续 ${missedPongs} 次心跳无响应,主动重连...`);
+        try { ws.terminate(); } catch { /* 已关闭 */ }
         return;
       }
-      pongReceived = false;
+      if (missedPongs > 0) console.log(`[bridge] 隧道心跳无响应(${missedPongs}/${HEARTBEAT_MAX_MISSED_PONGS}),继续探测...`);
       try { ws.ping(); } catch { ws.terminate(); }
     }, TUNNEL_HEARTBEAT_MS);
   });
-  ws.on("pong", () => { pongReceived = true; });
+  ws.on("pong", () => { pongReceived = true; missedPongs = 0; });
   ws.on("message", (raw) => {
     const receive = makeFrameReceiver();
     try {
@@ -1520,10 +1593,24 @@ function connectTunnel(token) {
     clearInterval(heartbeat);
     console.log(`[bridge] 隧道断开(code=${code}${reason ? ", " + reason : ""})`);
     closeAllWsSessions();
-    const delay = Math.min(30_000, 2_000 * 2 ** tunnelRetry);
+    // C2 + C5：4000（被同 deviceId 的新连接顶掉）走长退避/退出；其余走 2/4/8/10s + 抖动。
+    const plan = reconnectPlan({ code, retry: tunnelRetry, consecutive4000 });
+    consecutive4000 = plan.consecutive4000;
     tunnelRetry += 1;
-    console.log(`[bridge] ${Math.round(delay / 1000)}s 后重连...`);
-    setTimeout(async () => connectTunnel(code === 4003 ? await resolveToken(true) : token), delay);
+    if (plan.exit) {
+      // 连续两次被顶 = 本机确实还有另一个 bridge 在同一 deviceId 上活着。再重连只会把它再顶一次，
+      // 所以让位：用专用退出码退出，watcher 据此暂停拉起（见 dsh-setup.mjs 的 DUPLICATE_INSTANCE_EXIT_CODE）。
+      console.error("[bridge] 检测到同 deviceId 的另一个 bridge，本实例退出（连续 2 次被顶，不再重连以免互踢）。");
+      console.error("[bridge] 若这是升级/重装留下的旧实例：重启一次 dsh web（或运行 dsh-remote doctor）即可只保留一个。");
+      try { closeAllWsSessions(); } catch { /* 已关闭 */ }
+      process.exit(DUPLICATE_INSTANCE_EXIT_CODE);
+    }
+    if (plan.reason === "duplicate-backoff") {
+      console.log(`[bridge] 本实例被同 deviceId 的新连接顶替，${Math.round(plan.delayMs / 1000)}s 后再试（期间不重连，避免互踢）...`);
+    } else {
+      console.log(`[bridge] ${Math.round(plan.delayMs / 1000)}s 后重连...`);
+    }
+    setTimeout(async () => connectTunnel(code === 4003 ? await resolveToken(true) : token), plan.delayMs);
   });
   ws.on("error", (e) => console.log(`[bridge] 隧道错误: ${e.message || ""}`));
 }
@@ -1757,6 +1844,112 @@ function redactText(e) {
   return String(e && e.message ? e.message : e).slice(0, 200);
 }
 
+/* ── C2：同机单实例保护（lock 文件 + PID/命令行校验，失败安全）────────────────────
+ *
+ * 为什么需要（诊断报告 04 §4.4）：同机两个 bridge 用同一个 deviceId 连中继会**互相顶号**
+ *（router close(4000)），周期 2~3.5s 的乒乓。来源有孤儿进程（watcher 被 TerminateProcess
+ * 收掉、bridge 漏成孤儿）、升级后旧进程未退、插件自愈与任务计划同时拉。watcher 层的 pid 文件
+ * 管不住这几种，所以 bridge 自己再上一把"本配置目录内只允许一个实例"的锁。
+ *
+ * 判定纪律（误杀/误挡的代价不对称）：
+ *   · pid 死了 / pid 被系统回收给**无关进程** → 抢锁（陈旧锁绝不能把 bridge 永久挡在门外）；
+ *   · pid 活着且命令行确认是 `dsh-bridge.mjs` → 判定"已有实例"，本实例退出（退出码 4，
+ *     watcher 会暂停 5 分钟，见 dsh-setup.mjs）；
+ *   · 取不到命令行（ps/PowerShell 不可用）→ **放行**（fail-safe 方向）：宁可冒着多开的风险也
+ *     不能让"锁检查失败"变成"bridge 永远起不来"，多开由上面的 4000 长退避/退出兜底。
+ */
+const INSTANCE_LOCK_FILE = ".dsh-bridge-instance.lock";
+/**
+ * 是否启用单实例锁：生产形态（配置目录运行时 / npm 安装）恒启用；
+ * 仓库里直接 `node clients/dsh-remote/dsh-bridge.mjs` 调试时不落锁，避免把锁文件写进工作区。
+ */
+const INSTANCE_GUARD_ENABLED = Boolean(process.env.DSH_BRIDGE_CONFIG) || ROOT.includes(`${path.sep}node_modules${path.sep}`);
+
+/** 该 pid 的完整命令行（取不到返回空串 —— 调用方据此走 fail-safe）。 */
+function commandLineOfPid(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return "";
+  if (process.platform === "win32") {
+    const script = `(Get-CimInstance Win32_Process -Filter "ProcessId=${pid}").CommandLine`;
+    const encoded = Buffer.from(script, "utf16le").toString("base64");
+    try {
+      return String(spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-EncodedCommand", encoded],
+        { encoding: "utf8", timeout: 8000, windowsHide: true }).stdout || "").trim();
+    } catch { return ""; }
+  }
+  try {
+    return String(execSync(`ps -p ${pid} -o command=`, { encoding: "utf8", timeout: 3000, windowsHide: true }) || "").trim();
+  } catch { return ""; }
+}
+
+function isOurBridgeCommand(cmd) {
+  const c = String(cmd || "");
+  return /dsh-bridge\.mjs/.test(c) && /clients[\\/]dsh-remote/.test(c);
+}
+
+/**
+ * 锁归属判定（纯函数，便于单测）：steal=可以抢锁；blocked=已有真实例；unknown=看不住但别阻塞。
+ * @returns {"steal"|"blocked"|"unknown"}
+ */
+export function instanceLockVerdict({ selfPid = 0, pid = 0, alive = false, isOurBridge = false, commandKnown = true } = {}) {
+  if (!Number.isInteger(pid) || pid <= 0) return "steal";
+  if (pid === selfPid) return "steal";
+  if (!alive) return "steal";
+  if (isOurBridge) return "blocked";
+  if (!commandKnown) return "unknown";
+  return "steal"; // pid 被系统回收给了无关进程
+}
+
+/** 抢单实例锁。返回 { ok, pid?, degraded? }；ok=false 表示确实有另一个实例。 */
+function acquireInstanceLock() {
+  if (!INSTANCE_GUARD_ENABLED) return { ok: true, skipped: true };
+  const file = path.join(RELAY_DIR, INSTANCE_LOCK_FILE);
+  const payload = JSON.stringify({ pid: process.pid, at: Date.now(), script: "dsh-bridge.mjs" });
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      fs.mkdirSync(RELAY_DIR, { recursive: true });
+      const fd = fs.openSync(file, "wx"); // 排他创建：要么拿到，要么 EEXIST
+      fs.writeSync(fd, payload);
+      fs.closeSync(fd);
+      return { ok: true };
+    } catch (e) {
+      if (e && e.code !== "EEXIST") return { ok: true, degraded: true }; // 写不了锁 → 失败安全：照常启动
+      let info = null;
+      try { info = JSON.parse(fs.readFileSync(file, "utf8")); } catch { info = null; }
+      const pid = Number(info && info.pid);
+      const alive = Number.isInteger(pid) && pid > 0 ? isPidAlive(pid) : false;
+      const cmd = alive ? commandLineOfPid(pid) : "";
+      const verdict = instanceLockVerdict({
+        selfPid: process.pid, pid, alive,
+        isOurBridge: isOurBridgeCommand(cmd),
+        commandKnown: Boolean(cmd)
+      });
+      if (verdict === "blocked") return { ok: false, pid };
+      if (verdict === "unknown") {
+        // 看不住：不删别人的锁，也不阻塞自己（多开由 4000 处理兜底）。
+        return { ok: true, degraded: true, pid };
+      }
+      try { fs.rmSync(file, { force: true }); } catch { /* 抢不到就算了，下一轮 */ }
+    }
+  }
+  return { ok: true, degraded: true };
+}
+
+/** 释放自己那把锁（只删 owner === 本进程 的锁，绝不删别人的）。 */
+function releaseInstanceLock() {
+  if (!INSTANCE_GUARD_ENABLED) return;
+  const file = path.join(RELAY_DIR, INSTANCE_LOCK_FILE);
+  try {
+    const info = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (Number(info && info.pid) === process.pid) fs.rmSync(file, { force: true });
+  } catch { /* 没锁/已被抢 → 忽略 */ }
+}
+
+/** 本进程 pid 是否活着（不影响别的进程；EPERM 视为活着）。 */
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; }
+}
+
 async function runTunnel() {
   // 先动态确定上游再连隧道：上游端口不是 3080 时（DSH Desktop 默认 43120）这一步是关键 ——
   // 否则 bridge 会连上中继、手机也能打开页面，但每个请求都打到一个没人听的端口。
@@ -1834,6 +2027,18 @@ async function main() {
   process.on("message", (m) => {
     if (m && m.type === "shutdown") shutdown("IPC shutdown");
   });
+  // C2：同机单实例锁（理由/判定纪律见 acquireInstanceLock 上方的长注释）。
+  // 放在认证之前：被挡下的第二个实例**不消耗一次 device-login**（登录接口按出口 IP 限流）。
+  const lock = acquireInstanceLock();
+  if (!lock.ok) {
+    console.error(`[bridge] 本机已有另一个 bridge 实例在运行（pid=${lock.pid}，同一配置目录），本实例退出以免两个实例互踢。`);
+    console.error("[bridge] 若这来自升级/重装留下的旧实例：结束该进程后重启一次 dsh web 即可。");
+    process.exit(DUPLICATE_INSTANCE_EXIT_CODE); // watcher 据此暂停 5 分钟再拉，避免继续顶撞
+  }
+  if (lock.degraded) {
+    console.log("[bridge] 单实例锁检查降级（取不到进程命令行或锁不可写）——照常启动；若出现 code=4000 互踢，本实例会自动让位。");
+  }
+  process.on("exit", releaseInstanceLock);
   return runTunnel();
 }
 

package/clients/dsh-remote/e2ee-shim-script.js

@@ -438,6 +438,8 @@
         明文过境(见 :39 的策略表),那是安全红线。 */
   var seStaleSessionHook = null;
   var seLastStaleCode = "";
+  /** 「每页最多一次受控 reload」的闸门键(sessionStorage:同一标签页刷新后仍在 → 最多一次)。 */
+  var SE_RELOAD_GUARD_KEY = "dsh-e2ee-dead-reload";
   /** 清掉本机保存的 E2EE 交接单(sessionStorage 一次性 + localStorage 持久)。node 测试无 storage → 静默跳过。 */
   function seForgetHandoverStores() {
     try { if (typeof sessionStorage !== "undefined" && sessionStorage && sessionStorage.removeItem) sessionStorage.removeItem(DSH_E2EE_HANDOVER_KEY); } catch (e) { /* ignore */ }
@@ -447,34 +449,91 @@
   function seE2eeErrorOf(res) {
     try { return String((res && res.headers && res.headers.get && res.headers.get("x-dsh-e2ee-error")) || ""); } catch (e) { return ""; }
   }
-  /** 收到带 x-dsh-e2ee-error 的响应 → 清失效会话 + 上报(同一个码只报一次,避免刷屏)。 */
-  function seNoteE2eeError(res) {
+  /**
+   * 收到带 x-dsh-e2ee-error 的响应 → 清失效会话 + 上报(同一个码只报一次,避免刷屏)。
+   *
+   * 🔴 C3(2026-10-20 诊断,03 报告 §2.4 D1 的真缺陷):旧实现**只清 storage**,
+   *    本页内存里的 `_ctx.sess` 一直是那张死票 —— 全文只有 `_install()` 一处给它赋值,
+   *    之后再没有任何地方置空。于是这个页面的**后续每一个** HTTP/WS 仍然继续带死 sessId:
+   *      · WS 被桥端 `1008 e2ee_session_locked` 拒 → 官方客户端安静重连 → 再拒…… 无限循环;
+   *      · 该页每个受保护请求全 502,但页面"看起来在、其实全死"。
+   *    实测规模:dev-08b73ba9de67 单设备一天 nginx 009 8997 次、同时 4064 个 HTTP 200。
+   *    所以清 storage 只解决"**下次**进页面",清 `ctx.sess` 才解决"**这一页**别再送死票"。
+   *    @param {Response} res
+   *    @param {{sess: *}|null} [ctx] 本页上下文(有就给,给了就同时置空内存会话)
+   *    @returns {string} 桥端错误码(没有则 "")
+   */
+  function seNoteE2eeError(res, ctx) {
     var code = seE2eeErrorOf(res);
     if (!code) return "";
+    var dropped = false;
+    try { if (ctx && ctx.sess) { ctx.sess = null; dropped = true; } } catch (e) { /* ignore */ }
     seForgetHandoverStores();
     if (code !== seLastStaleCode) {
       seLastStaleCode = code;
-      try { if (typeof seStaleSessionHook === "function") seStaleSessionHook(code); } catch (e) { /* ignore */ }
+      try { if (typeof seStaleSessionHook === "function") seStaleSessionHook(code, dropped); } catch (e) { /* ignore */ }
       seNotifyFail("加密会话已失效(" + code + "):本机保存的会话已不可用,需要重新解锁。");
     }
     return code;
   }
 
+  /**
+   * 「每页最多一次」受控 reload(C3 第 3 条;防止修好"死循环"却换来"reload 风暴")。
+   *
+   * 只在这种场合用:桥端**明确**回了 unknown_session(它不认识这张交接单,这张票 100% 是死的),
+   * 而本页刚才真的挂着一张死会话(dropped=true)。此时本页所有受保护请求都会 502,
+   * 官方客户端也可能已经卡在自己的错误态里 —— 一次刷新能让它从干净的明文态重新起步
+   * (没有交接单 → 走"未解锁/明文"分支,功能可用,也不再送死 sessId)。
+   * 闸门放 sessionStorage:同一标签页刷新后仍在 → **最多 reload 一次**,不会变成新的 499 来源。
+   * node 测试没有 sessionStorage/location → 直接返回 false(纯逻辑不依赖 DOM)。
+   * @returns {boolean} 是否真的发起了 reload
+   */
+  function seReloadOnceForDeadSession() {
+    try {
+      if (typeof sessionStorage === "undefined" || !sessionStorage) return false;
+      if (sessionStorage.getItem(SE_RELOAD_GUARD_KEY)) return false;
+      sessionStorage.setItem(SE_RELOAD_GUARD_KEY, String(Date.now()));
+    } catch (e) { return false; }
+    try {
+      if (typeof location === "undefined" || !location || typeof location.reload !== "function") return false;
+      location.reload();
+      return true;
+    } catch (e2) { return false; }
+  }
+
   /* ---- 数据 WS 握手失败上报(2026-09-26:线上 mux 握手 404/009 → 用户只看到"什么都没发生") ----
      mux WS 是镜像页与电脑端之间**唯一**的实时数据通道;它连不上时页面不报错,只是所有数据都停住。
-     这里只做**可观测**:把"没连上"作为明确原因交给徽标(区分"会话未建立/设备离线/网络中断"),
-     绝不在这里做重连 —— 官方客户端自己会重连,我们再加一层只会变成"静默无限重连"。 */
+     这里只做**可观测 + 死会话自愈**:把"没连上"作为明确原因交给徽标(区分"会话未建立/设备离线/网络中断"),
+     连续握手失败 ≥3 次且本页还挂着会话时,判定桥端已不认这张交接单(C3,同 seNoteE2eeError 的处置:
+     清交接单 + 清内存 ctx.sess + 徽标「加密会话已失效，需要重新解锁」)。
+     仍然**绝不在这里重连** —— 官方客户端自己会重连,我们再加一层只会变成"静默无限重连"。 */
   var seWsFailHook = null;
-  var seWsFailCount = 0;
+  var seWsFailCount = 0;      // 累计失败次数(徽标展示"第 N 次")
+  var seWsFailStreak = 0;     // **连续**失败次数(握手成功一次即清零) —— 死会话判定只看它
   var seWsFailReported = false;
-  function seNoteWsHandshakeFail(label, detail) {
+  /** 连续握手失败到这个次数 → 判定桥端已不认本页的加密会话(2026-10-20 C3)。 */
+  var SE_WS_FAIL_INVALIDATE = 3;
+  /**
+   * @param {string} label  WS 标签(日志/徽标用,不含密钥)
+   * @param {string} detail "error" 或关闭码/原因
+   * @param {{sess: *}|null} [ctx] 本页上下文;给了才可能清会话(没有会话就只上报)
+   */
+  function seNoteWsHandshakeFail(label, detail, ctx) {
     seWsFailCount++;
-    if (seWsFailReported) return;
+    seWsFailStreak++;
+    var dropped = false;
+    if (ctx && ctx.sess && seWsFailStreak >= SE_WS_FAIL_INVALIDATE) {
+      /* 桥端连"握手"都不认(1008 e2ee_session_locked / 升级被拒),而本页还挂着会话:
+         这张交接单在桥端已经不存在(bridge 重启 / 24h TTL / CAP=32 挤出),留着只会无限重连。 */
+      try { ctx.sess = null; dropped = true; } catch (e) { /* ignore */ }
+      seForgetHandoverStores();
+    }
+    if (seWsFailReported && !dropped) return;
     seWsFailReported = true;
-    try { if (typeof seWsFailHook === "function") seWsFailHook(String(label || ""), String(detail || ""), seWsFailCount); } catch (e) { /* ignore */ }
+    try { if (typeof seWsFailHook === "function") seWsFailHook(String(label || ""), String(detail || ""), seWsFailCount, dropped); } catch (e) { /* ignore */ }
   }
-  /** 握手成功后复位(下一次再断时还能再报一次;不清 count,用于展示"重试了几次")。 */
-  function seNoteWsOpened() { seWsFailReported = false; }
+  /** 握手成功后复位(下一次再断时还能再报一次;连续计数清零,累计 count 保留用于展示"重试了几次")。 */
+  function seNoteWsOpened() { seWsFailReported = false; seWsFailStreak = 0; }
 
   /* ---- HTTP 信封传输包装(与 native e2eeFetchEnveloped 同构;输入/输出为 fetch 语义) ---- */
   var SE_OUTER_STRIP = {
@@ -558,7 +617,7 @@
     } catch (e) { throw e; }
     /* router/桥端明文错误页 → 原样透传(零行为)，但**先看一眼**是不是桥端在说"会话我不认识"
        (x-dsh-e2ee-error)——是的话清掉本机失效交接单并给出明确原因(见 seNoteE2eeError)。 */
-    if (!seIsEnvelopeResponse(res)) { seNoteE2eeError(res); return res; }
+    if (!seIsEnvelopeResponse(res)) { seNoteE2eeError(res, ctx); return res; }
     var envResp = null;
     try { envResp = await res.json(); } catch (e) {
       seNotifyFail("响应信封非法");
@@ -606,12 +665,12 @@
       /* 握手上就失败(error 早于任何 open)→ 让用户知道"加密数据通道没建立"。
          这是 2026-09-26 故障里最缺的一条信号:mux 被 404 掐掉时页面**一声不响**,
          用户只看到所有数据都停住。 */
-      if (!self._opened) seNoteWsHandshakeFail(self._meta && self._meta.wsLabel, "error");
+      if (!self._opened) seNoteWsHandshakeFail(self._meta && self._meta.wsLabel, "error", self._meta && self._meta.ctx);
       if (typeof self._onerror === "function") self._onerror(ev || { type: "error", target: self });
     };
     inner.onclose = function (ev) {
       self._state = 3;
-      if (!self._opened) seNoteWsHandshakeFail(self._meta && self._meta.wsLabel, (ev && (ev.code || ev.reason)) || "close");
+      if (!self._opened) seNoteWsHandshakeFail(self._meta && self._meta.wsLabel, (ev && (ev.code || ev.reason)) || "close", self._meta && self._meta.ctx);
       if (typeof self._onclose === "function") self._onclose(ev || { type: "close", target: self });
     };
     inner.onmessage = function (ev) { self._enqueueInbound(ev); };
@@ -740,7 +799,7 @@
       if (!should) return new NativeWS(passUrl, protocols);
       var target = seBuildWsTarget(scoped, ctx.sess.sessId, seRandomHex(8), base);
       if (!target) return new NativeWS(passUrl, protocols);
-      return new SeE2eeWs(NativeWS, target.href, protocols, { sess: ctx.sess, wsLabel: target.wsLabel });
+      return new SeE2eeWs(NativeWS, target.href, protocols, { sess: ctx.sess, wsLabel: target.wsLabel, ctx: ctx });
     }
     SeWs.OPEN = 1; SeWs.CONNECTING = 0; SeWs.CLOSING = 2; SeWs.CLOSED = 3;
     return SeWs;
@@ -865,14 +924,35 @@
     bad_envelope: "响应信封非法。",
     bad_plain: "响应明文非法。"
   };
-  function _reportStaleSession(code) {
+  /**
+   * @param {string} code 桥端错误码
+   * @param {boolean} [dropped] 刚才是否真的清掉了一张**本页正挂着的**死会话
+   */
+  function _reportStaleSession(code, dropped) {
     var hint = _STALE_HINT[String(code || "")] || ("电脑端返回:" + String(code || "") + "。");
     _badge("warn", "加密会话已失效，需要重新解锁", hint + " 已清除本机保存的会话；返回设备列表重新点选设备解锁即可恢复加密。");
+    /* C3 第 3 条：只有"刚才真的扔掉了一张本页死会话"时才做**一次**受控刷新。
+       为什么只在这个分支刷：HTTP 的 x-dsh-e2ee-error 是桥端**主动回答**"我不认识这个会话"
+       （这张票是确定的死票），而 WS 握手失败还可能只是电脑端暂时离线 —— 那种情况清了会话就够了，
+       刷新只会打断用户。刷新后页面没有交接单 → 走未解锁明文态，明文可用，也不再送死 sessId
+       （每标签页最多一次）。 */
+    if (dropped) seReloadOnceForDeadSession();
   }
   /* 加密数据 WS（mux）**握手就没成功**：官方客户端只会安静地重连，页面不报错、数据全停。
      这里把原因分档说清楚（会话/设备/网络），但**不做任何重连**（重连是官方的事，
-     我们再叠一层就变成"静默无限重连"——正是这次要修掉的形态）。 */
-  function _reportWsFail(label, detail, count) {
+     我们再叠一层就变成"静默无限重连"——正是这次要修掉的形态）。
+     @param {boolean} [dropped] 连续失败 ≥3 次且刚才清掉了本页死会话（C3 自愈分支） */
+  function _reportWsFail(label, detail, count, dropped) {
+    if (dropped) {
+      /* 徽标文案按 C3 验收口径固定为「加密会话已失效，需要重新解锁」——
+         用户据此只有一个动作：回设备列表重新解锁。 */
+      _badge("warn", "加密会话已失效，需要重新解锁",
+        "与电脑端的加密数据通道连续 " + (Number(count) || SE_WS_FAIL_INVALIDATE) + " 次握手失败，"
+        + "电脑端已不认这个加密会话（通常是电脑端重启过，或会话太多被挤掉）。"
+        + "已清除本机保存的会话，本页数据改为明文继续（功能可用，但不再加密）；"
+        + "返回设备列表重新点选设备解锁即可恢复加密。");
+      return;
+    }
     var n = Number(count) || 1;
     var why = String(detail || "") === "error"
       ? "电脑端可能未连接(设备离线)、网络中断，或加密会话已失效。"

package/clients/dsh-remote/mirror-diag-script.js

@@ -124,6 +124,23 @@
     } catch (e) { return ""; }
   }
 
+  /** 适配层（mobile-adapter）暴露的只读诊断：首屏自动重试次数 / compat-official 降级 / scrim 计数。
+   *  为什么从这里带出去（2026-10-20 C4/C6）：服务端只有 nginx/mirror_diag 两层时，
+   *  分不清"失败后是自愈了还是永久坏了" —— 这三个计数就是"自愈有没有发生"的第一手证据。
+   *  没有适配层（宽屏/未注入/旧版本）时返回 undefined：字段整体缺省，不改变既有 payload 形状。 */
+  function uiDiag() {
+    try {
+      var r = W.__dshMaRetryStats;
+      var d = W.__dshMaDiag;
+      if (!r && !d) return undefined;
+      var out = {};
+      if (r) out.retry = { page: Number(r.page) || 0, res: Number(r.res) || 0, kind: clip(r.kind || r.lastKind || "", 40) };
+      if (d && d.compatOfficial) out.compat = d.compatOfficial.on ? 1 : 0;
+      if (d && d.scrim) out.scrim = { on: Number(d.scrim.activations) || 0, fix: Number(d.scrim.invariantHits) || 0 };
+      return out;
+    } catch (e) { return undefined; }
+  }
+
   function flush() {
     timer = null;
     if (sent || (items.length === 0 && bootFailed.length === 0)) return;
@@ -138,6 +155,8 @@
       boot_failed: bootFailed.slice(0, 10),
       at: now()
     };
+    var ui = uiDiag();
+    if (ui) payload.ui = ui;   // 可选字段：老服务端无视即可
     try {
       fetch(ENDPOINT, {
         method: "POST",