dsh-remote-web 0.7.3-beta.1 → 0.7.3-beta.3

package/lib/index.js

@@ -317,7 +317,10 @@ function hardenFile(file) {
 /** 执行 shell 命令，不抛异常，返回 { ok, stdout, stderr, code }。 */
 function sh(cmd) {
   try {
-    const stdout = execSync(cmd, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 15000 });
+    // windowsHide（C1 黑窗不变量）：Windows 上 execSync 经 cmd.exe 起控制台程序时，
+    // 若宿主（dsh web / 桌面端）没有控制台，系统会给子进程分配一个可见窗口。
+    // POSIX 上该选项被忽略。
+    const stdout = execSync(cmd, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 15000, windowsHide: true });
     return { ok: true, stdout: String(stdout ?? ""), stderr: "", code: 0 };
   } catch (e) {
     return { ok: false, stdout: String(e.stdout ?? ""), stderr: String(e.stderr ?? ""), code: e.status ?? -1 };
@@ -532,7 +535,9 @@ function safeSpawn(command, args, opts = {}) {
   const { onError, ...spawnOpts } = opts;
   let child;
   try {
-    child = spawn(command, args, spawnOpts);
+    // C1：默认 windowsHide（调用方显式传 false 才会覆盖）。插件派生的每一个子进程都是
+    // "后台辅助进程"，Windows 上绝不该出现可见控制台窗口（诊断报告 04 的 W1 黑窗）。
+    child = spawn(command, args, { windowsHide: true, ...spawnOpts });
   } catch (e) {
     return { child: null, error: e };
   }
@@ -553,7 +558,8 @@ function spawnAndConfirm(command, args, opts = {}) {
   return new Promise((resolve) => {
     let child;
     try {
-      child = spawn(command, args, opts);
+      // C1：同 safeSpawn，默认 windowsHide（Windows 上不弹控制台）。
+      child = spawn(command, args, { windowsHide: true, ...opts });
     } catch (e) {
       resolve({ child: null, error: e });
       return;
@@ -2325,6 +2331,12 @@ function startBridgeDetached(relayDir, fallbackReason = "") {
       // 上游端口**必须**透传：watcher 用它判断「dsh web 在线吗」，bridge 用它做转发目标。
       // 不传的话两边都回落到写死的 3080 —— dsh web 不在默认端口时 bridge 永远不启动（0.6.12 修）。
       DSH_BRIDGE_UPSTREAM: upstreamUrl(),
+      // C7：**必须显式**把 relayDir 传给 watcher。
+      // 旧实现只靠 spawnEnv 继承宿主的 DSH_RELAY_DIR（第 7800+ 行：relayDir 也可能来自
+      // config.relayDir），于是"relayDir 来自配置、宿主环境没有该变量"时，watcher/bridge 会
+      // 回落到 ~/.dsh-remote —— 面板看到的现象是「守护在跑、bridge 永远不出现」（1415 那类故障），
+      // 而且 pid 文件/日志也都写去了另一个目录。
+      DSH_RELAY_DIR: relayDir,
     }),
     stdio: ["ignore", out, out],
     windowsHide: true,
@@ -4220,6 +4232,93 @@ function spawnUpdater(relayDir, extraEnv, onError, spec = UPDATE_SPEC) {
   });
 }
 
+/* ── C8：升级/更新「覆盖运行时之前停旧进程 + 装完按命令行清残留」───────────────────
+ *
+ * 为什么必须停（诊断报告 04 §五 R1）：安装器的 ensureRuntimeCopy() 会把 clients/ 与
+ * node_modules/ws **覆盖式**拷进运行时目录，而旧 watcher/bridge 正在用这些文件跑。
+ * Windows 上杀软持有句柄 → 覆盖写失败 → 半装 → bridge `ERR_MODULE_NOT_FOUND: Cannot find
+ * package 'ws'`；同时旧 bridge 成孤儿、与新起的一份同 deviceId 互踢。
+ *
+ * 安全纪律（这套代码在**开发者的真机上**被测试执行，误杀/误停是不可接受的）：
+ *   · 只停「命令行里带**本 relayDir** 路径」的进程 —— 别的配置目录、别的用户的 bridge 一律不碰；
+ *   · 取不到命令行（ps/PowerShell 不可用）→ 不停（漏停由安装器自己接管处理，方向选安全侧）；
+ *   · 走 stopBridgeDetached/manualStatus 那条路（pid 文件 + 命令行扫描），**不碰 launchd/systemd**
+ *     —— 服务本身由安装器收尾时重写并重启，插件这一侧只负责"别让旧代码继续跑"。
+ */
+
+/** 该 pid 的完整命令行（Windows 复用带 TTL 缓存的 PowerShell 扫描；取不到返回空串）。 */
+function commandLineOfPid(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return "";
+  if (isWindows()) {
+    const hit = windowsNodeProcesses().find((p) => p.pid === pid);
+    return hit ? String(hit.commandLine || "") : "";
+  }
+  const r = sh(`ps -p ${pid} -o command=`);
+  return r.ok ? String(r.stdout || "").trim() : "";
+}
+
+/** 这个 pid 是否真的在跑**本 relayDir** 里的脚本（命令行校验；取不到 → false）。 */
+function pidRunsFrom(pid, relayDir) {
+  const cmd = commandLineOfPid(pid);
+  if (!cmd) return false; // 看不清就不动：误杀无关进程的代价远高于漏停
+  const norm = (v) => String(v).replace(/\\/g, "/").toLowerCase();
+  return norm(cmd).includes(norm(relayDir));
+}
+
+/** 收集本 relayDir 这套运行时的 watcher/bridge pid（pid 文件 + 命令行扫描）。 */
+function collectRuntimePids(relayDir) {
+  const pids = new Set();
+  for (const name of [WATCHER_PID_FILE, BRIDGE_PID_FILE]) {
+    const pid = readPidFile(relayDir, name);
+    if (Number.isInteger(pid) && pid > 0 && pid !== process.pid) pids.add(pid);
+  }
+  const ms = manualStatus(relayDir) || {};
+  for (const pid of [...(ms.watcher || []), ...(ms.bridge || []), ...(ms.allBridge || [])]) {
+    if (Number.isInteger(pid) && pid > 0 && pid !== process.pid) pids.add(pid);
+  }
+  return [...pids];
+}
+
+/**
+ * 覆盖运行时之前停掉本 relayDir 的旧 watcher/bridge（幂等）。
+ * @returns {{skipped: boolean, pids: number[]}}
+ */
+function stopBridgeForRuntimeReplace(relayDir) {
+  if (skipsSystemOps()) return { skipped: true, pids: [] };
+  const pids = collectRuntimePids(relayDir).filter((pid) => pidAlive(pid) !== false && pidRunsFrom(pid, relayDir));
+  for (const pid of pids) killPid(pid, "SIGKILL"); // Windows 上是 taskkill /T /F：连带子进程
+  for (const name of [WATCHER_PID_FILE, BRIDGE_PID_FILE]) {
+    try { rmSync(join(relayDir, name), { force: true }); } catch { /* 非关键 */ }
+  }
+  return { skipped: false, pids };
+}
+
+/**
+ * 装完清残留：只处理**本轮更新前就在跑**的那批 pid，且仍满足命令行校验。
+ * 为什么不用"扫所有本 relayDir 的 bridge"：npx 安装器的收尾会重启服务并拉起**新的** bridge，
+ * 那一个是新代码、必须留下；按"更新前的 pid 集合"点名清理才不会误杀新实例。
+ * @returns {number[]} 被结束的 pid
+ */
+function sweepBridgeAfterRuntimeReplace(relayDir, beforePids = []) {
+  if (skipsSystemOps() || !Array.isArray(beforePids) || !beforePids.length) return [];
+  const killed = [];
+  for (const pid of beforePids) {
+    if (pidAlive(pid) === false) continue;
+    if (!pidRunsFrom(pid, relayDir)) continue; // pid 可能已被系统回收 → 必须重新校验命令行
+    if (killPid(pid, "SIGKILL")) killed.push(pid);
+  }
+  return killed;
+}
+
+/** 更新失败/取消时把 bridge 恢复起来（否则用户会莫名失去远程访问）。只在本轮真停过进程时执行。 */
+function restoreBridgeAfterUpdate(relayDir, stoppedPids = []) {
+  if (skipsSystemOps() || !stoppedPids.length) return null;
+  try {
+    const r = startBridgeDetached(relayDir);
+    return r;
+  } catch { return null; }
+}
+
 /**
  * 后台执行在线一键更新：npx 按 dist-tag(默认 latest)（幂等自愈：补运行环境/更新 bridge/收敛 include）。
  * 稳健性：
@@ -4230,6 +4329,8 @@ function spawnUpdater(relayDir, extraEnv, onError, spec = UPDATE_SPEC) {
  *   - marker 记录 pid，子进程退出/出错即清理；宿主重启后由 sweepStaleMarkers 立即清掉死进程残留。
  */
 async function runOnlineUpdate(relayDir) {
+  /** C8：本轮更新前停掉的旧进程 pid（失败时要恢复；成功时要清残留）。 */
+  let stopInfo = { skipped: true, pids: [] };
   try {
     mkdirSync(relayDir, { recursive: true });
     const marker = join(relayDir, UPDATE_MARKER);
@@ -4256,6 +4357,30 @@ async function runOnlineUpdate(relayDir) {
       `[update] 开始在线更新 ${spec}（通道 ${UPDATE_TAG}；${target.why}）(${new Date().toISOString()})`);
     telemetryRecord(relayDir, "update_started"); // 匿名遥测：在线更新开始
 
+    // C8：**覆盖运行时之前**先停掉本 relayDir 的旧 watcher/bridge（幂等）。
+    // 安装器随后会覆盖写 clients/ 与 node_modules/ws —— 旧进程一边跑一边被覆盖，
+    // Windows 上极易半装（`Cannot find package 'ws'`）并留下孤儿进程新老互踢。
+    stopInfo = stopBridgeForRuntimeReplace(relayDir);
+    appendLogLine(relayDir, UPDATE_LOG, stopInfo.skipped
+      ? "[update] 测试隔离：跳过「停旧 bridge」（DSH_RELAY_SKIP_SERVICE=1）"
+      : (stopInfo.pids.length
+        ? `[update] 覆盖运行时前已停旧 bridge/watcher（pid ${stopInfo.pids.join(", ")}）`
+        : "[update] 覆盖运行时前检查：本 relayDir 没有旧 bridge/watcher 在跑"));
+    /** 失败/取消：把刚停掉的 bridge 拉回来（只在本轮真停过进程时执行，避免测试里碰真实服务）。 */
+    const restoreIfStopped = () => {
+      if (!stopInfo.pids.length) return;
+      const r = restoreBridgeAfterUpdate(relayDir, stopInfo.pids);
+      appendLogLine(relayDir, UPDATE_LOG,
+        `[update] 已重新拉起 bridge（${(r && r.status) || "unknown"}），远程访问不受影响`);
+    };
+    /** 成功：按"更新前那批 pid"点名清残留（保持命令行校验，绝不误杀安装器刚拉起的新实例）。 */
+    const sweepIfSucceeded = () => {
+      const killed = sweepBridgeAfterRuntimeReplace(relayDir, stopInfo.pids);
+      if (killed.length) {
+        appendLogLine(relayDir, UPDATE_LOG, `[update] 装完清残留：已结束旧 bridge 进程（pid ${killed.join(", ")}）`);
+      }
+    };
+
     let retried = false;
     let stalled = false; // 本轮是否因"长时间无输出"被判定卡住（决定失败归因与是否回退）
     const clear = () => {
@@ -4270,6 +4395,7 @@ async function runOnlineUpdate(relayDir) {
       const fc = telemetryFailCodeFromError(e);
       noteUpdateFailure(relayDir, e.message, fc); // ← 面板可查询，不再只躺在日志里
       telemetryRecord(relayDir, "update_failed", { fail_code: fc });
+      restoreIfStopped(); // C8：更新没起来 → 把刚停掉的 bridge 拉回来，别让用户失去远程访问
     };
     /**
      * 第三跳：离线通道（0.6.12）。
@@ -4319,6 +4445,7 @@ async function runOnlineUpdate(relayDir) {
         if (updateCancelledDirs.has(relayDir)) {
           updateCancelledDirs.delete(relayDir);
           appendLogLine(relayDir, UPDATE_LOG, "[update] 已取消：不再重试");
+          restoreIfStopped(); // C8：取消也要把 bridge 拉回来
           return;
         }
         appendLogLine(relayDir, UPDATE_LOG, `[update] 离线通道退出 code=${code ?? "?"}`);
@@ -4331,8 +4458,10 @@ async function runOnlineUpdate(relayDir) {
             ? "离线通道也长时间没有输出（已判定卡住并结束）：请检查本机能否访问 registry.npmjs.org"
             : (lastLine || `离线通道退出码 ${code}`), fc);
           telemetryRecord(relayDir, "update_failed", { fail_code: fc });
+          restoreIfStopped(); // C8
         } else {
           updateFailures.delete(String(relayDir));
+          sweepIfSucceeded(); // C8：装完清残留（按更新前的 pid 点名 + 命令行复核）
           // 更新成功 → 落一条「必须重启 dsh web」的强提醒（见 run() 成功分支的同款注释）
           markRestartPending(relayDir, "restart", "插件已更新，重启 dsh web 后生效");
         }
@@ -4373,6 +4502,7 @@ async function runOnlineUpdate(relayDir) {
         if (updateCancelledDirs.has(relayDir)) {
           updateCancelledDirs.delete(relayDir);
           appendLogLine(relayDir, UPDATE_LOG, "[update] 已取消：不再换源重试");
+          restoreIfStopped(); // C8：取消也要把 bridge 拉回来
           return;
         }
         if (!retried && (code !== 0 || stalled)) {
@@ -4407,8 +4537,10 @@ async function runOnlineUpdate(relayDir) {
             ? "更新进程长时间没有任何输出（已判定卡住并结束），通常是本机到 npm 官方源的链路不通"
             : (lastLine || `安装进程退出码 ${code}`), fc);
           telemetryRecord(relayDir, "update_failed", { fail_code: fc });
+          restoreIfStopped(); // C8：三次尝试都已失败 → 先把 bridge 拉回来（用户可以先继续用，再手动重试）
         } else {
           updateFailures.delete(String(relayDir)); // 成功即清掉旧失败
+          sweepIfSucceeded(); // C8：装完清残留（安装器可能又拉起一个新 bridge，只清更新前那批）
           // 【2026-09-26】更新成功 → 写一条 kind="restart" 的待重启标记。
           //
           // 修的是"文案与状态机不一致"：版本卡一直写「请重启 dsh web 后生效」（client.js 的
@@ -4438,6 +4570,11 @@ async function runOnlineUpdate(relayDir) {
   } catch (e) {
     try { rmSync(join(relayDir, UPDATE_MARKER), { force: true }); } catch { /* ignore */ }
     telemetryRecord(relayDir, "update_failed", { fail_code: telemetryFailCodeFromError(e) });
+    // C8：异常也要把停掉的 bridge 拉回来（否则"更新失败"= 远程访问直接没了）
+    if (stopInfo.pids.length && !skipsSystemOps()) {
+      const r = restoreBridgeAfterUpdate(relayDir, stopInfo.pids);
+      appendLogLine(relayDir, UPDATE_LOG, `[update] 响应异常，已重新拉起 bridge（${(r && r.status) || "unknown"}）`);
+    }
     return { ok: false, detail: String(e.message || e) };
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-remote-web",
-  "version": "0.7.3-beta.1",
+  "version": "0.7.3-beta.3",
   "description": "公网远程控制 DeepSeek Harness（dsh web）：安装即得专属加密地址，人在外面也能用手机访问电脑上的 dsh——无需同一局域网/WiFi、无需公网 IP 与内网穿透，全程加密；手机端 100% 还原电脑体验（对话/工具/审批/设置）。技术用户可选自建服务，流量走自己的服务器。Remote control DeepSeek Harness (dsh web) from anywhere over the public internet — install, get an encrypted URL, use it from your phone on any network (dual-half cordis plugin: Settings panel + same-origin /dsh-remote routes). (2026-09 由 dsh-remote-ui 更名 / renamed from dsh-remote-ui; dsh-remote 的 dsh web 插件半，不是纯 UI/皮肤插件)",
   "type": "module",
   "main": "lib/index.js",

package/runtime/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();
 }