@mrrisega/dsh-remote 0.7.0-beta.8 → 0.7.1-beta.1

package/packages/dsh-remote-web/lib/index.js

@@ -15,7 +15,7 @@
 //     （no_account/no_runtime/installing/starting/connecting/online/error），并在返回前自动补装运行环境、
 //     拉起 bridge、清理卡死标记（带退避）；区分「bridge 进程在跑」与「设备已在中继注册成功（online）」。
 //     面板用 2~3s 短轮询自动推进到 online（无需点按钮/刷新页面），error 才给重试与诊断信息；
-//     另 POST /dsh-remote/connect/retry 手动重试、POST <api>/api/install-report 上报安装口径
+//     另 POST /dsh-remote/connect/retry 手动重试、POST <api>/api/install-report 上报安装约定
 //     （install_source/version + host_os/arch，详见 installSourceOf）。
 //   - 0.1.2+ ?token 浏览器鉴权会话代持（0.4.1 起）
 //
@@ -90,14 +90,14 @@ const DEFAULT_RELAY_DIR = process.env.DSH_RELAY_DIR || join(homedir(), ".dsh-rem
 // 默认云端服务地址（SaaS 入口；自建用户在设置页/面板切换）。
 // DSH_RELAY_DEFAULT_API 只改「配置里根本没写 api_url」时的兜底：测试脚本把它指向本地死端口，
 // 这样任何**在临时目录被拆掉之后**才跑到的后台请求（如装机上报的重试）都不会打生产。
-// 真实事故形态见 test/wechat-bind-telemetry.test.mjs 的注释：用例拆目录 → 读到空配置 → 回落生产。
+// 真实故障形态见 test/wechat-bind-telemetry.test.mjs 的注释：用例拆目录 → 读到空配置 → 回落生产。
 const DEFAULT_API = String(process.env.DSH_RELAY_DEFAULT_API || "").trim()
   || "https://n.risegao.cn:13443/relay-api";
 const DEFAULT_APP_URL = "https://n.risegao.cn:13443/app/";
 
 // ---------- 上游 dsh web 地址（bridge/watcher 都要连它，绝不写死 3080） ----------
 //
-// 【2026-09-23 用户实测事故】这里（以及运行时的 checkUpstream）原本把上游**写死**
+// 【2026-09-23 用户实测故障】这里（以及运行时的 checkUpstream）原本把上游**写死**
 // `http://127.0.0.1:3080`：只要用户的 dsh web 不在默认端口（`dsh web --port 8090`、
 // profile 里配了 port、或 `--port 0` 让系统分配空闲端口），watcher 的「dsh web 在线吗」
 // 探测就永远失败 → **bridge 永远不启动**，而面板只会说「正在启动 Bridge…」（错误为空）
@@ -215,19 +215,28 @@ async function discoverUpstreamSelf(relayDir, { force = false } = {}) {
  * 开机自启的 watcher（Windows 登录任务 / launchd）由系统拉起，拿不到本进程的 env，
  * 只有插件半知道 dsh web 真实监听在哪个端口。运行时（0.6.12+）读这个文件当第二优先来源。
  * 内容没变就不写（面板每轮都会走到这里，别把磁盘写热）。
+ *
+ * @returns {{changed:boolean, url:string}} `changed=true` = **这一次真的改写了文件**。
+ *   ★ 2026-10-13 为什么必须回报这个：修「12 秒重启风暴」时，唯一还站得住的"需要重启一个
+ *   **正在健康运行**的 bridge"的理由就是"它的上游地址变了（进程环境里是旧地址，不重启不生效）"。
+ *   而这个判据必须是**磁盘上的真实变化**，不能是"我觉得它可能变了" —— 后者又会变成
+ *   每轮自愈都重启一次。调用方一律忽略返回值也没关系（旧行为不变）。
  */
 const UPSTREAM_FILE = ".dsh-upstream";
 function publishUpstream(relayDir) {
-  if (skipsSystemOps()) return; // 测试/诊断隔离：不得对磁盘产生任何副作用（含创建配置目录）
+  if (skipsSystemOps()) return { changed: false, url: "", skipped: true }; // 测试/诊断隔离：不得对磁盘产生任何副作用（含创建配置目录）
   try {
     const url = upstreamUrl();
     const file = join(relayDir, UPSTREAM_FILE);
     let cur = "";
     try { cur = readFileSync(file, "utf8").trim(); } catch { /* 首次 */ }
-    if (cur === url) return;
+    if (cur === url) return { changed: false, url };
     mkdirSync(relayDir, { recursive: true });
     writeFileSync(file, url + "\n", { mode: 0o600 });
-  } catch { /* 非关键：读不到就沿用运行时的回退链 */ }
+    return { changed: true, url };
+  } catch { /* 非关键：读不到就沿用运行时的回退链 */
+    return { changed: false, url: "" };
+  }
 }
 
 /**
@@ -491,7 +500,7 @@ function npxInvocation() {
 /** 子进程环境：把 node 目录补进 PATH（npx 及其 shebang 需要），可附加额外变量。 */
 function spawnEnv(extra) {
   // ⚠️ 这里刻意用 **process.execPath**，不是 NODE_BIN：PATH 首位的用途是让 npx 的
-  // `#!/usr/bin/env node` 解析到**正在跑本插件的那个 node**（与 npxInvocation 同口径）。
+  // `#!/usr/bin/env node` 解析到**正在跑本插件的那个 node**（与 npxInvocation 同约定）。
   // NODE_BIN 回答的是另一个问题——"自启动服务里该登记哪个解释器"（真实 node 优先）。
   // 两者语义不同，混用会悄悄改掉 web 版上 npx 用哪个 node。
   const nodeDir = dirname(process.execPath);
@@ -759,9 +768,9 @@ function fetchFailReason(e) {
 }
 
 /**
- * Cookie 按 **authority 分文件**(0.7.0-beta.2 起,2026-10-09 事故根治)。
+ * Cookie 按 **authority 分文件**(0.7.0-beta.2 起,2026-10-09 故障根治)。
  *
- * 【事故】`~/.dsh-remote/` 只有一份 `.harness-cookie.json`,而 Web 端(3080)与桌面端(每次启动
+ * 【故障】`~/.dsh-remote/` 只有一份 `.harness-cookie.json`,而 Web 端(3080)与桌面端(每次启动
  *   随机端口)是**两个宿主进程**,各自的插件都往里写"自己 authority 的 Cookie" → 互相覆盖。
  *   桥撞 401 后重读磁盘,拿到的是另一个宿主刚写的 Cookie → 重试 → 还是 401 → 再读 → 又被
  *   覆盖回去……**乒乓,永不自愈**,手机端持续白页(现象与"自愈坏了"一模一样,极易误判)。
@@ -782,7 +791,7 @@ function harnessCookieFileFor(authority) {
 function harnessCookieRevokedFileFor(authority) {
   return `${HARNESS_COOKIE_REVOKED_FILE}.${authoritySlug(authority)}`;
 }
-/** 由本进程 webServer 端口推出 authority(与 bridge 的 Host 口径一致)。 */
+/** 由本进程 webServer 端口推出 authority(与 bridge 的 Host 约定一致)。 */
 function harnessAuthorityOfPort(port) {
   return port ? `127.0.0.1:${port}` : "";
 }
@@ -832,7 +841,7 @@ async function mintHarnessCookie(ctx, relayDir) {
     if (UNINSTALLED_DIRS.has(relayDir)) return false;
     const out = { authority: `127.0.0.1:${port}`, cookie, mintedAt: Date.now() };
     mkdirSync(dirname(configPathOf(relayDir)), { recursive: true });
-    // ① 本宿主专属文件(权威,两个宿主互不覆盖 —— 事故根治点)
+    // ① 本宿主专属文件(权威,两个宿主互不覆盖 —— 故障根治点)
     const ownPath = join(relayDir, harnessCookieFileFor(out.authority));
     writeFileSync(ownPath, JSON.stringify(out, null, 2), { mode: 0o600 });
     hardenFile(ownPath); // 会话 Cookie ≈ dsh web 的完整访问权，同样要收紧
@@ -1003,7 +1012,7 @@ function runtimeManifest(relayDir) {
 /**
  * 桌面运行环境缺失/不完整的文件清单（空 = 就绪）。
  *
- * 【2026-09-23 用户实测事故】判据原本是「`dsh-setup.mjs` 存在即就绪」——**存在 ≠ 能加载**。
+ * 【2026-09-23 用户实测故障】判据原本是「`dsh-setup.mjs` 存在即就绪」——**存在 ≠ 能加载**。
  * npx 补装是「先拷入口脚本、再递归拷 clients/」，中途被打断（用户关窗口 / 杀软锁文件 /
  * 机器休眠 / 看门狗判超时结束进程）就会留下一个**只有入口脚本的半装运行时**。此后：
  *   · runtimeReady() 恒为 true → 插件再也不补装（自愈彻底停摆）；
@@ -1049,7 +1058,7 @@ function launchAgentPath() {
 /**
  * ★ 这份自启动 plist 是否**确实是为本 relayDir 装的**（内容里写着 `<relayDir>/dsh-setup.mjs`）。
  *
- * 🔴 2026-10-10 事故（两次，同一根因）：`reapBrokenAutostart()` 用**当前 relayDir** 判断
+ * 🔴 2026-10-10 故障（两次，同一根因）：`reapBrokenAutostart()` 用**当前 relayDir** 判断
  *   "入口脚本缺失"（测试的临时 relayDir 当然没有 dsh-setup.mjs → 判 true），
  *   但删除的却是 `launchAgentPath()` = **真实 HOME 下那份 plist** → 把开发者本机的自启动
  *   连 bootout 带删文件一起干掉了（远程访问中断，且日志里看不出异常）。
@@ -1102,6 +1111,41 @@ function systemdUserAvailableCached(ttlMs = 60_000) {
   return ok;
 }
 
+/**
+ * ★★ 2026-10-13 修复（线上反馈 fb_3c4c5a13bc47 / 用户 842）：Linux 上「bridge 到底在不在跑」的
+ * **权威**判据 —— 问服务管理器本人，而不是猜进程名。
+ *
+ * 为什么 `pgrep` 不能当就绪判据：自愈 watcher 每 `selfhealIntervalMs()`（默认 12s）拍一次，
+ * 旧就绪判据是 `manualStatus(relayDir).watcher.length > 0`，它靠
+ * `pgrep -fl 'dsh-setup.mjs|dsh-bridge.mjs'` 的名称匹配。这个探测**极易拿到空结果**
+ * （PATH 里没有 /usr/bin、pgrep 不存在、进程名与模式不匹配、进程属于别的会话……），
+ * 而拿到空结果后的动作是 `systemctl --user restart dsh-bridge` —— **restart 会杀掉正在
+ * 健康运行的 bridge**。实测后果：该设备 `audit_log` 的 `device.claim`（= bridge 进程启动的
+ * 必然产物）一天 **3567** 次、相邻间隔 p50 **12001ms**、连续 10 小时整点 300 次/小时；
+ * 全站上百台设备每天 1.1~1.5 万次重登记。每次重启都以新连接顶掉旧隧道，中继随即把该设备
+ * **所有手机镜像 WS 关掉（close 1012 "bridge offline"）**，镜像页每 ~12.3 秒断线重连并全量重放
+ * 界面状态 —— 用户看到的就是"选项窗口一会儿显示、一会儿消失"。
+ * 而中继侧对这类 churn 只做了日志抑制，所以运维侧长期看不见。
+ *
+ * 🔴 结论：**探测失败 ≠ 进程死了**，绝不允许把前者翻译成"每 12 秒杀一次隧道"。
+ *
+ * 为什么必须是三态而不是布尔：`known:false`（问不到 systemd —— NAS/容器里没有 user manager、
+ * 甚至没有 systemctl 命令）与「问了，明确不是 active」在语义上完全不同：
+ *   · known=false → 回退到进程探测（与旧行为一致，不能因为问不到就认为它死了）；
+ *   · known=true & active=false → 才可以动手拉起。
+ * 把这两种混成一个 `false`，等于又制造了一次"判据失败就重启"的事故。
+ */
+function linuxSystemdUnitState() {
+  if (!isLinux()) return { known: false, active: false, raw: "" };
+  const r = sh("systemctl --user is-active dsh-bridge");
+  const raw = String(r.stdout || "").trim();
+  if (raw === "active") return { known: true, active: true, raw };
+  // is-active 对 inactive/failed/activating… 会以非 0 退出，但**会打印状态字** —— 那是有效回答。
+  // 一个字都没打印 = systemctl 根本没回答（没有 user manager / 没有这个命令）→ 未知，不是"死"。
+  if (!raw) return { known: false, active: false, raw };
+  return { known: true, active: false, raw };
+}
+
 /** 写 Linux systemd user unit（与 dsh-setup.mjs 同内容）。写不了返回 null（不致命，还有脱离进程兜底）。 */
 function writeLinuxUnit(relayDir) {
   const unitPath = linuxUnitPath();
@@ -1136,7 +1180,7 @@ WantedBy=default.target
 /**
  * Linux：拉起 bridge 的阶梯（**与 macOS 同构：可自愈优先，可用兜底**）。
  *
- * 【0.6.15 事故根因】0.6.14 及更早，`startBridge` 只认 macOS 的 launchd，Linux 直接返回
+ * 【0.6.15 故障根因】0.6.14 及更早，`startBridge` 只认 macOS 的 launchd，Linux 直接返回
  * `unsupported: 当前平台（linux）暂不支持自启动服务`。于是：
  *   · 自愈轮次每轮都调用它、每轮都拿到 unsupported、**bridge 永远起不来**；
  *   · 用户面板上的表现是永远停在「正在启动 Bridge…」+「bridge 进程: 未运行」；
@@ -1160,18 +1204,64 @@ function startBridgeLinux(relayDir) {
       detail: "桌面运行环境（bridge）尚未安装，已在后台自动安装，完成后会自动启动 bridge——请稍候刷新面板（也可点下方「一键更新」查看进度）",
     };
   }
-  publishUpstream(relayDir); // 脱离进程拉起的 watcher 没有本进程 env，只认这个文件
+  const up = publishUpstream(relayDir); // 脱离进程拉起的 watcher 没有本进程 env，只认这个文件
   const unit = writeLinuxUnit(relayDir);
   if (unit && systemdUserAvailable()) {
-    sh("systemctl --user daemon-reload");
-    const en = sh("systemctl --user enable dsh-bridge");
-    const rs = sh("systemctl --user restart dsh-bridge");
-    const act = rs.ok ? sh("systemctl --user is-active dsh-bridge") : { ok: false, stdout: "", stderr: "" };
-    if (rs.ok && act.ok && act.stdout.trim() === "active") {
-      return { ok: true, status: "running", pid: null, detail: "已由 systemd --user 托管 bridge（开机自启 + 崩溃自愈）" };
+    // ★★ 2026-10-13 幂等闸门（修「12 秒重启风暴」的核心）：
+    //   先问**服务管理器本人**这个 unit 是不是 active，而不是拿 pgrep 猜进程名。
+    //   active = systemd 把它拉起来了、正在跑 —— 此时绝不能 restart（restart 会杀掉旧进程、
+    //   新建隧道，中继随即 close(1012) 掉该设备所有手机镜像 WS，镜像页全量重放）。
+    //   旧代码在这里**无条件 restart**：只要上游判据（pgrep）拿不到，它就每 12 秒把一台
+    //   健康运行的 bridge 杀掉重建一次，一天 3567 次（见 linuxSystemdUnitState 的长注释）。
+    const state = linuxSystemdUnitState();
+    if (state.active && !up.changed) {
+      // 唯一还站得住的"需要重启"的理由不存在 → 什么都不做，如实回报"在跑、没重启"。
+      return {
+        ok: true, status: "running", pid: null, reused: true,
+        detail: "已由 systemd --user 托管 bridge（运行中，未重启）",
+      };
+    }
+    const why = state.active
+      // 上游地址**确实变了**（运行中的进程环境里是旧地址，不重启就会对着旧端口转发）——
+      // 这是唯一允许动一个健康服务的理由，所以必须过护栏：万一上游地址在抖，
+      // 也不能退化成"每 12 秒重启一次"（那正是本次故障的形态）。
+      ? `上游地址变更为 ${up.url}`
+      // 没在跑（含 is-active=activating/failed 这类瞬时态）：本该起它，但**反复 restart 一个
+      // 起不来的 unit** 每次都会派生一个新 bridge 进程（= 一次 device.claim = 顶掉一次隧道），
+      // 所以这里的 restart 同样要过护栏 —— 护栏就该放在"破坏性动作"的调用点上，
+      // 而不是指望每个调用者自己记得限流。
+      : `systemd --user 说它没在跑（is-active=${state.raw || "无回答"}）`;
+    const g = guardedSystemdRestart(relayDir, why);
+    if (!g.allowed) {
+      // ⚠️ 被护栏拦下时**绝不能**再落到下面的"脱离进程"兜底：那条路会直接派生一个新 watcher，
+      //    每拍一个 —— 护栏就形同虚设（这正是我们要止住的东西）。
+      // 而回报要分两种：unit 本来就 active 时它**仍在运行**，不能因为"我们没重启"就报失败
+      // （否则面板会把一台好机器显示成故障）。
+      if (state.active) {
+        return {
+          ok: true, status: "running", pid: null, reused: true, staleUpstream: true,
+          detail: `bridge 正在运行；上游地址已变更为 ${up.url}，但为避免重启风暴暂不重启它（重开 dsh web 后自然生效）`,
+        };
+      }
+      return {
+        ok: false, status: "selfheal-throttled",
+        detail: `自愈护栏拦下了对 systemd unit 的重启（${g.gate.reason === "exhausted" ? "已达本进程重启上限" : "距上次重启过近"}），本轮不重启 bridge`,
+      };
+    }
+    if (g.ok) {
+      // accounted: true = 这次破坏性重启已经在 guardedSystemdRestart 里记过账（护栏额度 + 可见日志）。
+      // 调用方（自愈 watcher）据此**不得再记一次**，否则一次尝试吃掉两格额度，5 分钟退避缩水成 2.5 分钟。
+      return { ok: true, status: "running", pid: null, accounted: true, detail: "已由 systemd --user 托管 bridge（开机自启 + 崩溃自愈）" };
+    }
+    if (state.active) {
+      // 因上游变更而重启、但重启后仍不是 active：如实回报（已在 guardedSystemdRestart 里记账）
+      return {
+        ok: true, status: "running", pid: null, reused: true, staleUpstream: true,
+        detail: `bridge 仍在运行，但上游地址已变更为 ${up.url} 且本次重启未确认生效（详见安装日志）`,
+      };
     }
     appendLogLine(relayDir, AUTO_INSTALL_LOG,
-      `[dsh-remote-web] systemd --user 拉起 bridge 失败（enable=${en.ok ? "ok" : "fail"}, restart=${rs.ok ? "ok" : "fail"}），改用后台进程`);
+      `[dsh-remote-web] systemd --user 拉起 bridge 失败（restart=${g.rs.ok ? "ok" : "fail"}），改用后台进程`);
   }
   const d = startBridgeDetached(relayDir, unit
     ? "本机没有可用的 user systemd 会话（NAS / 容器 / 精简系统常见），已改为后台进程"
@@ -1179,6 +1269,30 @@ function startBridgeLinux(relayDir) {
   return d;
 }
 
+/**
+ * 执行一次「systemd 破坏性重启 bridge」：**先过护栏，过了才真的 restart**，并记账 + 写可见日志。
+ *
+ * 为什么要把 `systemctl --user restart` 收敛到这一个函数里：这条命令是本次故障里唯一真正
+ * 造成伤害的动作（杀旧 bridge → 新进程 → 新隧道 → 中继 close(1012) 掉手机镜像）。
+ * 它散落在多处调用点时，任何一处忘了限流就又是一次"十二秒杀一次隧道"；
+ * 收到一处之后，"什么情况下允许执行它"就有了唯一答案，也能被单测直接钉住。
+ * @returns {{allowed:boolean, gate:object, ok:boolean, en:object, rs:object, act:object}}
+ */
+function guardedSystemdRestart(relayDir, why) {
+  const gate = selfhealRestartGate(relayDir);
+  if (!gate.allowed) {
+    noteSelfhealBlocked(relayDir, gate);
+    return { allowed: false, gate, ok: false, en: null, rs: null, act: null };
+  }
+  sh("systemctl --user daemon-reload");
+  const en = sh("systemctl --user enable dsh-bridge");
+  const rs = sh("systemctl --user restart dsh-bridge");
+  const act = rs.ok ? sh("systemctl --user is-active dsh-bridge") : { ok: false, stdout: "", stderr: "" };
+  const active = Boolean(rs.ok && act.ok && String(act.stdout).trim() === "active");
+  noteSelfhealRestart(relayDir, why, active ? "running" : `restart=${rs.ok ? "ok" : "fail"}/is-active=${String(act.stdout).trim() || "?"}`);
+  return { allowed: true, gate, ok: active, en, rs, act };
+}
+
 /**
  * launchd 作业 target（`gui/<uid>/<label>`）。
  * **Windows/Linux 上没有 launchctl、也没有 process.getuid**——旧实现无条件调
@@ -1188,7 +1302,7 @@ function startBridgeLinux(relayDir) {
 /**
  * launchd 域名阶梯（**必须与 dsh-setup.mjs 一致**）。
  *
- * 事故（2026-09-19 实测）：安装器按 macOS 26 的修复把作业装在 **`user/<uid>`** 域
+ * 故障（2026-09-19 实测）：安装器按 macOS 26 的修复把作业装在 **`user/<uid>`** 域
  * （gui 域会被系统置为 on-demand-only，RunAtLoad/KeepAlive 失效），
  * 但插件这边只认 `gui/<uid>` → 切换账号时那次"重启 bridge"实际执行的是
  *   launchctl bootout gui/501/com.dshremote.bridge   → 找不到
@@ -1427,6 +1541,97 @@ function selfhealIntervalMs() {
   return Math.max(200, Number(process.env.DSH_RELAY_SELFHEAL_MS) || 12_000);
 }
 
+/**
+ * ★★ 2026-10-13 自愈重启护栏（熔断 + 退避）—— 修「12 秒重启风暴」的第二道闸。
+ *
+ * 为什么在"权威存活判据"之外还必须再有一道：
+ *   权威判据解决的是"**活着却被判成死**"（见 `linuxSystemdUnitState()`）。
+ *   但如果 bridge **真的**起不来（上游端口不对、运行环境半装、unit 写不进去、unit 一直 failed），
+ *   旧的 12s 循环同样会每拍重启一次 —— 那是同一个病的另一种形态：
+ *   **一次真实故障被翻译成"每天 7200 次重启"**（历史上 Windows 补装失败就出过 12 秒一次、
+ *   累计 606 次的失败风暴，见 `provisionRetryGate` 的注释）。所以：
+ *     · 同一 relayDir、**本进程生命周期内**的破坏性重启最多 `SELFHEAL_MAX_RESTARTS` 次；
+ *     · 两次之间至少隔 `selfhealMinRestartMs()`（默认 5 分钟）；
+ *     · 超限就**停手**，并把原因明确写进安装日志（面板「复制诊断信息」与用户主动上报的
+ *       诊断包里都会带上它）——而不是静默地每 12 秒再来一次。
+ *
+ * 为什么上限按"本进程生命周期"而不是"每天"：合法的上游变更（dsh web 换端口）几乎总伴随着
+ * dsh web 重启，而重启就会重置这份记录 —— 所以 3 次对正常用户绰绰有余，对故障循环刚好够呛。
+ * `DSH_RELAY_SELFHEAL_MIN_RESTART_MS` 仅供本仓库测试把节奏压到亚秒级
+ * （与 `DSH_RELAY_SELFHEAL_MS` / `DSH_RELAY_WEDGE_MS` 同一约定）：生产不设置。
+ */
+const SELFHEAL_MAX_RESTARTS = 3;
+const SELFHEAL_MIN_RESTART_MS = 5 * 60 * 1000;
+function selfhealMinRestartMs() {
+  const v = Number(process.env.DSH_RELAY_SELFHEAL_MIN_RESTART_MS);
+  return Number.isFinite(v) && v >= 0 ? v : SELFHEAL_MIN_RESTART_MS;
+}
+/** relayDir → { count, lastAt, blockedLine }；blockedLine = 已经告知过的"被拦下"结论（防刷屏）。 */
+const selfhealRestarts = new Map();
+function selfhealGuardOf(relayDir) {
+  return selfhealRestarts.get(relayDir) || { count: 0, lastAt: 0, blockedLine: "" };
+}
+
+/**
+ * 现在允许对这个 relayDir 做**破坏性重启**吗？（纯查询，不改状态 —— 调用方在真的重启之后
+ * 用 `noteSelfhealRestart` 记账，这样"只查不记"的路径不会凭空消耗额度。）
+ * @returns {{allowed:boolean, reason:"ok"|"too-soon"|"exhausted", count:number, waitMs:number}}
+ */
+function selfhealRestartGate(relayDir, now = Date.now()) {
+  const rec = selfhealGuardOf(relayDir);
+  if (rec.count >= SELFHEAL_MAX_RESTARTS) return { allowed: false, reason: "exhausted", count: rec.count, waitMs: 0 };
+  const min = selfhealMinRestartMs();
+  const since = now - (rec.lastAt || 0);
+  if (rec.lastAt && since < min) return { allowed: false, reason: "too-soon", count: rec.count, waitMs: min - since };
+  return { allowed: true, reason: "ok", count: rec.count, waitMs: 0 };
+}
+
+/**
+ * 记一次**真的做了**破坏性重启，并留下一行可见日志。
+ *
+ * ★ 可观测性是这次修复的一半：这个故障拖了 3 个月才被定位，直接原因就是"重连风暴在中继侧
+ *   只被日志抑制、在客户端侧又什么都没记"——运维侧全程看不见。所以重启事件必须留痕：
+ *   写既有的安装日志（`.dsh-setup-install.log`，面板诊断与用户上报都会带它的尾部），不新造通道。
+ * @param {string} why 人类可读的原因（"权威判据说没在跑" / "上游地址变更"）
+ * @param {string} outcome 重启后的结果（"running" / "failed: …"）
+ */
+function noteSelfhealRestart(relayDir, why, outcome = "") {
+  const rec = selfhealGuardOf(relayDir);
+  rec.count += 1;
+  rec.lastAt = Date.now();
+  rec.blockedLine = ""; // 结论变了：下一次"被拦下"要重新说一遍
+  selfhealRestarts.set(relayDir, rec);
+  appendLogLine(relayDir, AUTO_INSTALL_LOG,
+    `[dsh-remote-web] 自愈重启 bridge（第 ${rec.count}/${SELFHEAL_MAX_RESTARTS} 次·本进程生命周期内，`
+    + `之后 ${Math.round(selfhealMinRestartMs() / 1000)} 秒内不再重启）：${why}${outcome ? ` → ${outcome}` : ""}`);
+  return rec;
+}
+
+/**
+ * 「这一拍本来想重启，但被护栏拦下了」——**同一条结论只说一次**（理由同 `noteAutostartFailure`：
+ * 每 12 秒写一行的日志等于没有日志，用户复制过来的诊断里会全是重复行，第一现场反而被淹没）。
+ * 注意：文案里**不得带倒计时秒数**，否则每一拍的文本都不同，去重就失效了。
+ */
+function noteSelfhealBlocked(relayDir, gate) {
+  const rec = selfhealGuardOf(relayDir);
+  const line = gate.reason === "exhausted"
+    ? `已停止自愈重启 bridge：本进程生命周期内已重启 ${SELFHEAL_MAX_RESTARTS} 次仍未就绪，`
+      + `为避免"每 ${Math.round(selfhealIntervalMs() / 1000)} 秒杀掉一次正在跑的隧道"已熔断；`
+      + `请点面板「一键更新」，或查看 bridge 日志确认真正的失败原因`
+    : `已暂缓自愈重启 bridge：距上次重启不足 ${Math.round(selfhealMinRestartMs() / 1000)} 秒`
+      + `（不会每 ${Math.round(selfhealIntervalMs() / 1000)} 秒重启一次，那样会反复切断手机镜像连接）`;
+  if (rec.blockedLine === line) return false;
+  rec.blockedLine = line;
+  selfhealRestarts.set(relayDir, rec);
+  appendLogLine(relayDir, AUTO_INSTALL_LOG, `[dsh-remote-web] ${line}`);
+  return true;
+}
+
+/** 桥已确认就绪：清掉护栏状态，让"后来真的再挂一次"能重新自愈（否则额度会被历史故障吃光）。 */
+function resetSelfhealGuard(relayDir) {
+  selfhealRestarts.delete(relayDir);
+}
+
 /** 向日志追加一行（多个子进程写同一日志用 append 模式，互不覆盖）。 */
 function appendLogLine(relayDir, name, line) {
   try {
@@ -1449,7 +1654,7 @@ function appendLogLine(relayDir, name, line) {
  * 注意：默认优先官方源——镜像(npmmirror)可能滞后于刚发布的版本，装到旧版会把
  * 已被 0.4.5 移除的“用户 include”重新写回 profile（历史上造成 dsh web 重复 ID 崩溃）。 */
 /**
- * 补装失败退避（2026-09-15 生产事故）。
+ * 补装失败退避（2026-09-15 生产故障）。
  *
  * 背景：Windows 用户补装 `npx @mrrisega/dsh-remote` 持续失败时，自愈调度每轮都重试，
  * 生产遥测里看到单机 12 秒一次、累计 606 次的失败风暴（1659 次 install_failed 全在 Windows）。
@@ -1673,7 +1878,7 @@ function ensureRuntime(relayDir) {
 /**
  * 生成 plist（与 dsh-setup.mjs 的 writeAutostartFile **必须同构**），返回路径。
  *
- * ⚠️ 两份模板历史上漂移过、并因此各造成一个真机事故（插件每次自愈/启动都会重写 plist，
+ * ⚠️ 两份模板历史上漂移过、并因此各造成一个真机故障（插件每次自愈/启动都会重写 plist，
  *    所以**插件这份谁写谁说了算**，漂移等于把安装器那份正确的覆盖掉）：
  *   · 漏 `/usr/sbin`、`/sbin`（SERVICE_PATH）→ bridge 找不到 `ioreg` → 机器指纹静默退化成
  *     hostname 哈希（改一次主机名就被当成新设备）；
@@ -1936,6 +2141,26 @@ function startBridge(relayDir) {
  *     → watcher `done = true` 永久停摆，自动补装（ensureRuntime）再也不会执行，
  *     这正是「市场装完插件、bridge 却起不来」且永不恢复的直接原因；
  *   - 补装运行环境不该等用户先登录：市场安装只给到插件半，登录那一刻就会 startBridge。
+ *
+ * ★★ 2026-10-13 重写就绪判据与"动手"策略（修线上反馈 fb_3c4c5a13bc47 的 12 秒重启风暴）：
+ *   【症状】Linux 用户（npx 安装，0.6.18）的 bridge 被本函数**每 12.001 秒重启一次**，
+ *     一天 3567 次；每次重启换一条新隧道 → 中继 close(1012) 掉该设备所有手机镜像 WS →
+ *     镜像页每 ~12.3 秒断线重连并全量重放 → 用户看到的交互选择窗口"一会显示、一会儿消失"。
+ *     全站上百台设备每天 1.1~1.5 万次重登记，多台设备间隔 p50 精确 ≈12.0s。
+ *   【成因】就绪判据只有 `launchdStatus().running`（macOS）与
+ *     `manualStatus().watcher.length > 0`（靠 pgrep 名称匹配，Linux/Windows 共用）。
+ *     这两个判据都**可能在服务其实健康时返回"没在跑"**，而拿到"没在跑"之后直接
+ *     `startBridge()` → `systemctl --user restart`（**破坏性**：杀旧进程、建新隧道）。
+ *     于是"判据失败"被逐字翻译成"每 12 秒杀一次隧道"，而且 `done` 永远不置位。
+ *   【现在】三层，缺一不可：
+ *     ① **权威判据优先**：Linux 问 `systemctl --user is-active dsh-bridge`（见
+ *        `linuxSystemdUnitState()`），pgrep 只作为"问不到 systemd 时"的兜底；
+ *     ② **成功即止**：任一判据确认就绪 → 立刻 `done = true; clearInterval`，
+ *        不再依赖下一拍去重新猜（旧代码即使这次 startBridge 成功，也要等下一拍 pgrep 认得出来
+ *        才算成功，而它恰恰认不出来 → 永远重启）；
+ *     ③ **护栏**：确需动手时先过 `selfhealRestartGate()`（≥5 分钟最小间隔 + 本进程内最多 3 次），
+ *        被拦下或触顶都写入**可见**的安装日志（这个故障之所以拖了三个月，正是因为客户端侧
+ *        什么都没记、中继侧又把 churn 日志抑制了，运维全程看不见）。
  */
 function scheduleRuntime(relayDir) {
   let done = false;
@@ -1963,21 +2188,85 @@ function scheduleRuntime(relayDir) {
       const cfg = loadConfig(relayDir);
       const hasAcct = Boolean((cfg.phone || cfg.email) && cfg.password) || Boolean(cfg.local_key);
       if (!hasAcct) return;
+      // ── ① 权威判据（按平台各问各的服务管理器）──
       // 运行环境已在，看服务是否已在运行（runtime 可能位于 npx 缓存/固化目录，不必重复安装）
       const st = launchdStatus();
-      if (st.running) { done = true; clearInterval(iv); return; }
+      if (st.running) {
+        done = true; clearInterval(iv); resetSelfhealGuard(relayDir);
+        logSelfhealReady(relayDir, cfg, `launchd state=${st.state || "running"}`);
+        return;
+      }
+      // Linux：**systemd 才是权威**。它说 active 就是 bridge 真的在跑（隧道是它的职责），
+      // 此时哪怕 pgrep 一个进程都没匹配上，也必须认为"就绪"并停摆 —— 这正是本次故障的正解。
+      if (isLinux()) {
+        const sys = linuxSystemdUnitState();
+        if (sys.active) {
+          done = true; clearInterval(iv); resetSelfhealGuard(relayDir);
+          logSelfhealReady(relayDir, cfg, "systemd --user is-active=active");
+          return;
+        }
+      }
+      // ── ② 兜底判据（问不到服务管理器时，还是得靠进程探测；Windows 只有这一条）──
       // 非 macOS（Windows **与 Linux**）没有 launchd：以「watcher 进程在跑」为就绪判据。
       // 否则 launchdStatus 永远是 false，done 永远不置位，watcher 会一直空转。
       // ★ Linux 也必须走这一支：`startBridge` 现在能在 Linux 上真正拉起 bridge（0.6.15），
       //   但就绪判据漏了 Linux 的话，每轮自愈都会重复走一遍"写 unit + 起进程"。
-      if (!isDarwin() && manualStatus(relayDir).watcher.length > 0) { done = true; clearInterval(iv); return; }
-      startBridge(relayDir); // 环境在但服务没起 → 拉起
+      if (!isDarwin() && manualStatus(relayDir).watcher.length > 0) {
+        done = true; clearInterval(iv); resetSelfhealGuard(relayDir);
+        logSelfhealReady(relayDir, cfg, "进程探测（pgrep/pid 文件）");
+        return;
+      }
+      // ── ③ 确实没在跑 → 过护栏后才动手（绝不允许"判据失败"直接变成"每 12 秒杀一次隧道"）──
+      const gate = selfhealRestartGate(relayDir);
+      if (!gate.allowed) { noteSelfhealBlocked(relayDir, gate); return; }
+      const r = startBridge(relayDir); // 环境在但服务没起 → 拉起
+      if (r && r.ok) {
+        // 起来了：立刻置位 + 记账 + 清掉失败去重状态。**不再等下一拍重新判据** ——
+        // 旧代码把"是否成功"交给下一拍的 pgrep 去回答，而它答不出来，于是永远重启。
+        // `accounted` = 这次重启已经在 startBridgeLinux/guardedSystemdRestart 里记过账，别再记一次。
+        if (!r.reused && !r.accounted) noteSelfhealRestart(relayDir, "权威判据说没在跑", r.status || "running");
+        clearAutostartFailure(relayDir);
+        done = true; clearInterval(iv); resetSelfhealGuard(relayDir);
+        logSelfhealReady(relayDir, cfg, `startBridge=${r.status || "running"}${r.reused ? "（幂等：本来就在跑）" : ""}`);
+        return;
+      }
+      // 测试隔离（DSH_RELAY_SKIP_SERVICE=1）：startBridge 只会返回 `skipped` —— 它**什么都没做**，
+      // 既不该吃掉护栏额度，也不该往安装日志里写"自愈重启"（生产不会出现这个状态）。
+      if (r && r.status === "skipped") return;
+      // Linux 的 systemd 重启已经在 `guardedSystemdRestart` 里记过账、也写过日志（含"被拦下"），
+      // 这里不能再记一次 —— 否则一次尝试吃掉两格额度，5 分钟的退避会缩水成 2.5 分钟。
+      if (r && r.status === "selfheal-throttled") return;
+      // 其它路径（macOS launchd 失败 / Windows / 脱离进程）没有自带护栏：在此记账 + 写可见日志，
+      // 否则"拉起失败 → 下一拍再试 → 每 12 秒一次"就是同一个病换个平台复发。
+      noteSelfhealRestart(relayDir, "权威判据说没在跑", (r && r.detail) || (r && r.status) || "未知原因");
+      // 触顶：护栏会在下一拍开始拦住我们并写一行"已停止自愈重启"，这里不再做任何动作。
     } catch { /* 下一轮再试 */ }
   }, selfhealIntervalMs());
   iv.unref?.();
   return () => clearInterval(iv);
 }
 
+/**
+ * 自愈判定「已就绪、循环停摆」时留一行可见日志（同一条结论只写一次）。
+ *
+ * 为什么值得单独记一行：用户反馈里"连接是不是自己在修、修好了没有"无从判断 ——
+ * 旧代码在就绪时**什么都不写**，于是"自愈watcher 判据失败→每 12 秒重启"这种故障
+ * 在日志里只留下 bridge 反复重启的痕迹，看不出是插件在动手。这一行把"是我判定的、依据是什么"钉住。
+ * ⚠️ 带上**隧道注册**证据（bridge 状态文件里的 device_id / 日志尾部），但不拿它当就绪判据：
+ *   它比进程存活更容易闪断，若用它当 done 的条件，等于又造一个会抖的判据（正是本次故障的病因）。
+ */
+function logSelfhealReady(relayDir, cfg, basis) {
+  if (lastSelfhealReadyLine.get(relayDir) === basis) return;
+  lastSelfhealReadyLine.set(relayDir, basis);
+  const state = bridgeStateFile(relayDir);
+  const registered = Boolean(state && state.device_id) && (!cfg || !cfg.device_id || String(state.device_id) === String(cfg.device_id));
+  appendLogLine(relayDir, AUTO_INSTALL_LOG,
+    `[dsh-remote-web] 自愈判定 bridge 已就绪，已停止自愈循环（依据：${basis}；`
+    + `隧道注册：${registered ? `已登记（device_id=${state.device_id}）` : "尚无登记证据（不影响就绪判定，注册由 bridge/watcher 自己负责）"}）`);
+}
+/** `logSelfhealReady` 的去重状态：同一个 relayDir 只有判据变了才再写一行。 */
+const lastSelfhealReadyLine = new Map();
+
 /** 停止 bridge：macOS 走 launchctl bootout；Linux 走 systemd/脱离进程；Windows 结束 watcher/bridge 进程。 */
 function stopBridge(relayDir) {
   if (isWindows()) return stopBridgeDetached(relayDir);
@@ -2007,7 +2296,7 @@ function stopBridge(relayDir) {
   }
   const targets = launchTargets();
   if (!targets.length) return { ok: false, status: "unsupported", detail: `当前平台（${osPlatform()}）没有 launchd 服务可停，请手动结束 \`dsh-remote run\` 进程` };
-  // 两个域都要停：作业可能由安装器装在 user/<uid>，而旧版插件只会去 gui/<uid> 找不到（实测事故）
+  // 两个域都要停：作业可能由安装器装在 user/<uid>，而旧版插件只会去 gui/<uid> 找不到（实测故障）
   let lastErr = "";
   for (const target of targets) {
     const r = sh(`launchctl bootout ${target}`);
@@ -2065,7 +2354,7 @@ function uninstallRuntime(relayDir, protectedPath) {
     // a) 停服务 + 移除自启动文件
     try {
       if (isDarwin()) {
-        /* 🔴 2026-10-10 事故护栏：**relayDir 不在当前 HOME 之下时，绝不碰真实自启动**。
+        /* 🔴 2026-10-10 故障护栏：**relayDir 不在当前 HOME 之下时，绝不碰真实自启动**。
            当天某个用例用「真 HOME + 临时 relayDir」调到了这里：plist 路径解析到真实的
            ~/Library/LaunchAgents/com.dshremote.bridge.plist → 先 bootout 真桥、再把 plist 删了
            → **开发者本机的远程访问被测试整个卸掉**（job 消失、桥停摆）。
@@ -2085,7 +2374,7 @@ function uninstallRuntime(relayDir, protectedPath) {
         // 只处理「plist 位于当前 HOME」的服务：本插件/dsh-setup.mjs 安装的服务一定在此
         const plistPath = launchAgentPath();
         if (plistPath && existsSync(plistPath)) {
-          /* ★★ 归属校验（2026-10-10 事故的最终护栏）：
+          /* ★★ 归属校验（2026-10-10 故障的最终护栏）：
              这份 plist 必须**确实是为本 relayDir 装的**（内容里写着 <relayDir>/dsh-setup.mjs）。
              不校验的话，只要有用例拿「真 HOME + 临时 relayDir」走到这里，就会把开发者本机
              真实的服务**先 bootout 再删文件**（当天实测发生：桥停摆、远程访问中断）。
@@ -3240,7 +3529,7 @@ async function proxyFeedback(relayDir, req, res, pathname) {
 
 /**
  * 把 `/dsh-remote/announcements*` 代理到云端公告 API（契约冻结见
- * dsh-relay-enterprise/docs/announcements-contract.md §3）：
+ * 服务端公告契约文档（冻结 v1） §3）：
  *   · GET  /dsh-remote/announcements       → 上游 GET  {api}/api/announcements?client=desktop[&install_id=…]
  *   · POST /dsh-remote/announcements/click → 上游 POST {api}/api/announcements/click  {id[, install_id]}
  *
@@ -3251,7 +3540,7 @@ async function proxyFeedback(relayDir, req, res, pathname) {
  *    两者**同时**带上会让唯一索引 (announcement_id, user_id, install_id) 把"同一人两台机器"
  *    算成两行 —— UV 直接翻倍。所以下面是有 Bearer 就不带 install_id，反之亦然。
  * ② **install_id 复用本机既有的 device_id，绝不新造 ID**：服务端那个维度就是"这台电脑"，
- *    再生成一个 ID 只会让同一台机器在统计里变成两台（且新 ID 与反馈/设备列表的口径对不上）。
+ *    再生成一个 ID 只会让同一台机器在统计里变成两台（且新 ID 与反馈/设备列表的约定对不上）。
  *    注意 `cfg.device_id` 是**本机设备标识**，与遥测的 `.telemetry-install-id` 不是一回事：
  *    后者在 DSH_REMOTE_TELEMETRY=0 时根本不生成，公告不该被遥测开关牵连。
  * ③ **失败一律软着陆**：上游 404（老服务端）/ 不可达 / 超时都只回一个 JSON，**绝不抛**。
@@ -3271,7 +3560,7 @@ async function proxyAnnouncements(relayDir, req, res, pathname) {
     }
 
     const headers = { "x-dsh-client": `dsh-remote-web/${PLUGIN_VERSION}` };
-    // 浏览器已带的 Bearer 优先透传（与 proxyFeedback 同口径：那是请求方自己的身份）；
+    // 浏览器已带的 Bearer 优先透传（与 proxyFeedback 同约定：那是请求方自己的身份）；
     // 否则由 node 半附当前账号 JWT —— 只有"确实配了账号"才值得为此跑一次 device-login。
     const auth = req.headers.authorization;
     let bearer = "";
@@ -3497,7 +3786,7 @@ async function fetchDistTags() {
   return {};
 }
 
-/** 在「当前通道」与 latest 之间取更高者（**更新与"检查更新"必须用同一口径**，否则面板会说"已是最新"而更新却装新版）。 */
+/** 在「当前通道」与 latest 之间取更高者（**更新与"检查更新"必须用同一约定**，否则面板会说"已是最新"而更新却装新版）。 */
 function pickBestTag(tags) {
   const t = tags || {};
   const channelVer = typeof t[UPDATE_TAG] === "string" ? t[UPDATE_TAG] : "";
@@ -3511,7 +3800,7 @@ function pickBestTag(tags) {
   return { tag: UPDATE_TAG, version: channelVer, why: `当前通道 ${UPDATE_TAG}(${channelVer}) 不低于 latest(${latestVer})` };
 }
 
-/** 查询"对我而言"的最新版本号（口径同 pickBestTag）。 */
+/** 查询"对我而言"的最新版本号（约定同 pickBestTag）。 */
 async function npmLatestVersion() {
   return pickBestTag(await fetchDistTags()).version;
 }
@@ -3607,7 +3896,7 @@ function spawnUpdater(relayDir, extraEnv, onError, spec = UPDATE_SPEC) {
     // Windows 上跑 npx.cmd 必须经 shell（Node ≥20.12 起否则 EINVAL）；走 node+npx-cli.js 时不需要。
     shell: npx.shell,
     windowsHide: true, // Windows：不弹控制台窗口（POSIX 上该选项被忽略）
-    // PATH 补 node 目录：App 最小 PATH 下也能跑 npx；同时保持本机既有的安装来源口径
+    // PATH 补 node 目录：App 最小 PATH 下也能跑 npx；同时保持本机既有的安装来源约定
     // （在线更新会重跑安装器并重写 plist，若不带来源就会把 plugin_market 误记成 npx）。
     env: spawnEnv({
       DSH_BRIDGE_INSTALL_SOURCE: installSourceOf(relayDir),
@@ -3877,7 +4166,7 @@ function rotateUpdateLog(relayDir) {
 /**
  * 判断 patch 文本是否是「合法的顶层 YAML 数组文档」。
  *
- * 为什么必须判（2026-09-18 Windows 用户实测的致命事故）：dsh 解析 cordis.patch.yml 时
+ * 为什么必须判（2026-09-18 Windows 用户实测的致命故障）：dsh 解析 cordis.patch.yml 时
  * **要求顶层是数组**，而**纯注释文档的 YAML 解析结果是 `null` 而不是空数组**，于是 dsh 直接：
  *   `Error: dsh: overlay …/cordis.patch.yml must be a top-level YAML array of loader patch entries`
  * 官方空 profile 模板是「注释 + `[]`」——`[]` 这个占位符不能省。
@@ -3907,7 +4196,7 @@ function stripOwnEntriesFromPatch(patch) {
   // ① 管理标记块（dsh-setup 写入的形式）
   // 结尾标记后面可能还有残留文字（历史变体），用 [^\n]* 吃掉整行，避免留下半截内容
   const out = String(patch ?? "").replace(/\n?# >>> dsh-remote-(?:web|ui)[^\n]*\n[\s\S]*?# <<< dsh-remote-(?:web|ui)[^\n]*\n?/g, "\n");
-  // ② 无标记的 insert 块（旧版 / 其它工具写入的形式，历史事故里出现过）。
+  // ② 无标记的 insert 块（旧版 / 其它工具写入的形式，历史故障里出现过）。
   //    只摘标记块是不够的：目录已删而 patch 仍引用 → dsh 插件树加载失败 → 整个 dsh web 起不来。
   const lines = out.split("\n");
   const kept = [];
@@ -3949,7 +4238,7 @@ function writePatchDocument(patchFile, text) {
 /**
  * 「运行时清理助手」源码（卸载用；由插件生成、detached 执行）。
  *
- * 为什么必须是独立进程（2026-09-18 用户实测的僵死事故）：
+ * 为什么必须是独立进程（2026-09-18 用户实测的僵死故障）：
  *   uninstallRuntime() 里有 spawnSync("schtasks"/"powershell"/"taskkill")，同步子进程调用会把
  *   **dsh web 的事件循环整个钉死** —— 不只是这一个请求不返回，手机端隧道、其它页面、所有 API
  *   一起停摆，表现为「端口在听、连接建立、但永不响应」。而 spawnSync 的 timeout 在 Windows 上
@@ -3959,7 +4248,7 @@ function writePatchDocument(patchFile, text) {
  * 助手做的是「宁可少做也不卡住」的有界清理：杀残留进程 → 删自启动 → 清配置目录，每步独立 try/catch。
  */
 function buildRuntimeCleanupHelper(relayDir, protectedPath) {
-  /* ★ 归属校验（2026-10-10 事故第三条路径）：计划里的 plistPath 用的是**当前 homedir**，
+  /* ★ 归属校验（2026-10-10 故障第三条路径）：计划里的 plistPath 用的是**当前 homedir**，
      而 relayDir 来自调用方 —— 两者不必是同一个目录。曾有测试用「真 HOME + 临时 relayDir」
      走到这里，于是这个 detached 助手把**开发者本机真实的自启动 plist 删了**（异步删，
      所以在进程内插桩根本抓不到）。现在：plist 里没写着本 relayDir 的入口脚本 → **不给路径**，
@@ -3986,7 +4275,7 @@ import { dirname, join, sep } from "node:path";
 
 const PLAN = ${plan};
 // 与主进程一致的测试隔离开关：置位时**绝不做任何真实系统操作**（不碰 launchctl/systemctl/schtasks/taskkill），
-// 但仍清空配置目录 —— 否则用例会去动开发者本机真实的自启动服务（历史事故，见 setup-output 用例的护栏）。
+// 但仍清空配置目录 —— 否则用例会去动开发者本机真实的自启动服务（历史故障，见 setup-output 用例的护栏）。
 const SKIP_SYSTEM_OPS = process.env.DSH_RELAY_SKIP_SERVICE === "1";
 function log(m) { try { appendFileSync(PLAN.log, "\\n[" + new Date().toISOString() + "] " + m + "\\n"); } catch (e) { /* 日志失败不阻断清理 */ } }
 function run(cmd, args, timeout) {
@@ -4086,7 +4375,7 @@ function accountFingerprintOf(cfg) {
 /**
  * 账号（或模式/设备身份）变化后，**必须让 bridge 用新凭据重新登记**。
  *
- * 事故（2026-09-19 实测）：从 A 账号切到 B 账号后，配置已经改了、device_id 也清了，
+ * 故障（2026-09-19 实测）：从 A 账号切到 B 账号后，配置已经改了、device_id 也清了，
  * 但**正在运行的 bridge 是启动时把账号/密码固化在环境变量里的**，它不会自己换账号；
  * 而那次"重启 bridge"又因 launchd 域名不一致（插件只认 gui/<uid>，安装器装在 user/<uid>）静默失败
  * → 设备继续留在 A 账号，B 账号的设备列表里永远看不到这台机器。
@@ -4096,6 +4385,10 @@ function accountFingerprintOf(cfg) {
  * 自愈也就永远不会去纠正）；③ 交给调用方随后重新启动。
  */
 function resetBridgeForAccountChange(relayDir, why) {
+  // ★ 2026-10-13：账号/模式变更是**人**做的决定（登录、切换账号、改自建模式），
+  //   它必须无条件生效 —— 所以顺手清掉自愈护栏额度，绝不允许"自愈循环之前用完了 3 次额度"
+  //   导致切换账号后新 bridge 起不来（那会让设备继续留在旧账号里，是 2026-09-19 那个老故障的翻版）。
+  resetSelfhealGuard(relayDir);
   const stopped = stopBridge(relayDir);
   // 脱离进程形态（launchd 托管不住时的兜底）也要收干净，否则它会用旧凭据继续跑
   try { stopBridgeDetached(relayDir, { force: true }); } catch { /* 非关键 */ }
@@ -4477,7 +4770,7 @@ async function composeConnect(relayDir, opts = {}) {
   // ── 中继注册证据（只有 bridge 进程在跑时才算「现在能用」） ──
   // ⚠️ 先判「这个 bridge 是不是当前账号的」：账号切换后进程不会自己换凭据，
   // 旧账号留下的状态文件（phase=online + 旧 device_id）会让面板谎报「已连接」，
-  // 自愈也就永远不会去重启它（2026-09-19 实测事故）。
+  // 自愈也就永远不会去重启它（2026-09-19 实测故障）。
   const accountCurrent = bridgeMatchesCurrentAccount(relayDir, cfg);
   let registered = false;
   let registerSource = "";
@@ -4626,6 +4919,10 @@ async function composeConnect(relayDir, opts = {}) {
     watcherAgeMs: wedge.known ? wedge.ageMs : 0,
     watcherWedged: Boolean(wedge.wedged),
     watcherRestarts: wedge.restarts,
+    // 自愈循环自己的重启账本（见 scheduleRuntime 的长注释）：面板诊断据此如实说明
+    // "插件为这台机器重启过几次 bridge、是不是已经熔断停手"。默认 0 = 正常，不产生任何文案。
+    selfhealRestarts: selfhealGuardOf(relayDir).count,
+    selfhealExhausted: selfhealGuardOf(relayDir).count >= SELFHEAL_MAX_RESTARTS,
     upstreamUrl: upstreamUrl(),
     upstreamSource: upstreamSourceLabel(),
     // 宿主形态：桌面端（Electron）与 Web 版（node）在若干动作上语义不同 ——
@@ -4723,6 +5020,12 @@ function buildConnectDiagnostics(relayDir, conn, log) {
       : `运行环境缺文件: ${conn.runtimeMissing.slice(0, 8).join(", ")}${conn.runtimeMissing.length > 8 ? ` 等 ${conn.runtimeMissing.length} 个` : ""}`,
     `bridge 进程: ${conn.bridgeRunning ? "在运行" : "未运行"}（pid=${conn.bridgePids && conn.bridgePids.length ? conn.bridgePids.join(",") : "-"}，launchd state=${conn.launchdState || "-"}，崩溃循环=${conn.launchdCrashLoop ? "是" : "否"}）`,
     `后台守护: ${conn.watcherRunning ? `在运行（pid=${conn.watcherPids.join(",")}${conn.watcherAgeMs ? `，已 ${Math.round(conn.watcherAgeMs / 1000)} 秒` : ""}${conn.watcherWedged ? "，⚠️ 迟迟未拉起 bridge" : ""}${conn.watcherRestarts ? `，已自动重启 ${conn.watcherRestarts} 次` : ""}）` : "未运行"}`,
+    // 只在真的重启过 bridge 时才出现这一行（正常用户零新增文案，不制造噪音）：
+    // 它回答的是"插件自己有没有在反复重启 bridge"—— 2026-10-13 那个故障里，这个问题
+    // 在客户端侧完全没有答案，运维只能从服务端 audit_log 反推。
+    conn.selfhealRestarts
+      ? `自愈重启: 本进程内已重启 bridge ${conn.selfhealRestarts} 次${conn.selfhealExhausted ? "（⚠️ 已达上限，已停止自动重启，请点「一键更新」）" : ""}`
+      : "",
     `上游 dsh web: ${conn.upstreamUrl}（${conn.upstreamSource}${conn.upstreamReachable === null ? "" : conn.upstreamReachable ? "，可达" : `，⚠️ 不可达：${conn.upstreamError}`}）`,
     `目录选择器: ${pickerPinState.kind === "native" ? "⚠️ 系统原生（远程时对话框弹在电脑那台机器上 → 手机上点「添加工作区」会像没反应）" : (pickerPinState.kind || "未知")}${pickerPinState.detail ? `（${pickerPinState.detail}）` : ""}`,
     `中继注册: ${conn.registered ? "已注册（" + conn.registerSource + "）" : "未注册"}`,
@@ -4782,7 +5085,7 @@ async function buildDiagReport(relayDir, opts = {}) {
     `【插件】v${PLUGIN_VERSION}　运行时 ${runtimeVersionOf(relayDir) || "未知"}　宿主 ${harnessVersion() || "未知"}　${osPlatform()}/${process.arch}　node ${String(process.versions.node).split(".")[0]}`,
     `【阶段】${conn.phase}（${conn.text}）`,
     `【设备】ID=${conn.deviceId || "（未生成）"}　运行环境=${conn.runtimeReady ? "就绪" : `缺失${conn.runtimeMissing && conn.runtimeMissing.length ? `（缺 ${conn.runtimeMissing.slice(0, 3).join("、")}）` : ""}`}`,
-    `【bridge】${conn.bridgeRunning ? `在运行 pid=${conn.bridgePids.join(",")}` : "未运行"}　守护=${conn.watcherRunning ? `在运行 pid=${conn.watcherPids.join(",")}${conn.watcherAgeMs ? `（${Math.round(conn.watcherAgeMs / 1000)}s）` : ""}` : "未运行"}${conn.watcherWedged ? " ⚠️活着但拉不起 bridge" : ""}${conn.watcherRestarts ? ` 已自动重启 ${conn.watcherRestarts} 次` : ""}`,
+    `【bridge】${conn.bridgeRunning ? `在运行 pid=${conn.bridgePids.join(",")}` : "未运行"}　守护=${conn.watcherRunning ? `在运行 pid=${conn.watcherPids.join(",")}${conn.watcherAgeMs ? `（${Math.round(conn.watcherAgeMs / 1000)}s）` : ""}` : "未运行"}${conn.watcherWedged ? " ⚠️活着但拉不起 bridge" : ""}${conn.watcherRestarts ? ` 已自动重启 ${conn.watcherRestarts} 次` : ""}${conn.selfhealRestarts ? `　【自愈重启】本进程内 ${conn.selfhealRestarts} 次${conn.selfhealExhausted ? "（已达上限，已停止自动重启）" : ""}` : ""}`,
     `【上游】${conn.upstreamUrl}（${conn.upstreamSource}${conn.upstreamReachable === null ? "" : conn.upstreamReachable ? "，可达" : `，⚠️不可达：${conn.upstreamError}`}）`,
     `【中继】${conn.registered ? `已注册（${conn.registerSource}）` : "未注册"}　账号=${conn.accountCurrent === false ? "⚠️上一个账号（需重启 bridge）" : "当前账号"}　自动重试=${conn.attempts} 次`,
     `【错误】${conn.error ? `${conn.error.code}: ${conn.error.message}` : (conn.detail ? "无（见上方阶段说明）" : "无")}`,
@@ -4815,7 +5118,7 @@ async function submitFeedback(relayDir, payload) {
     "content-type": "application/json",
     "x-dsh-device": cfg.device_id || "",
     "x-dsh-client": `dsh-remote-web/${PLUGIN_VERSION}`,
-    // 与 proxyFeedback 同一口径：结构化平台字段 + 真实 UA（此处没有浏览器请求可转发，
+    // 与 proxyFeedback 同一约定：结构化平台字段 + 真实 UA（此处没有浏览器请求可转发，
     // 就如实写本机平台，绝不冒充浏览器 UA）。
     "user-agent": `dsh-remote-web/${PLUGIN_VERSION} (${process.platform}; ${process.arch})`,
     "x-dsh-platform": process.platform,
@@ -4868,6 +5171,10 @@ function ensureConnection(relayDir, opts = {}) {
   // 顺手治一次「卡住的更新」（复用面板已有的轮询，不需要新定时器 —— 诊断报告 F5）
   healStalledJobs(relayDir);
   const book = connectBook(relayDir);
+  // ★ 2026-10-13：**人工操作永远立即放行**（与 provisionRetryGate 的 resetProvisionRetry 同一原则）。
+  //   面板的「重试 / 一键修复」走的就是 force=true；若不放行，护栏触顶后用户点重试会静默无效 ——
+  //   那就把"安全阀"变成了"用户被自己的插件锁在门外"。护栏只约束**自动**自愈，不约束人。
+  if (opts.force) resetSelfhealGuard(relayDir);
   if (opts.force) { book.attempts = 0; book.lastAttemptAt = 0; }
   const now = Date.now();
   if (!opts.force && book.lastAttemptAt && now - book.lastAttemptAt < connectBackoffMs(book.attempts)) return null;
@@ -4890,7 +5197,7 @@ function ensureConnection(relayDir, opts = {}) {
   const watcherRunning = Boolean(launchd.running || watcherProcs.length);
   if (bridgeProcs.length || watcherRunning) {
     // 进程在跑 ≠ 跑对了账号：切换账号后旧 bridge 会一直用旧凭据，
-    // 只看"有没有进程"会让自愈永久停摆（实测事故）。这里多判一次账号归属。
+    // 只看"有没有进程"会让自愈永久停摆（实测故障）。这里多判一次账号归属。
     if (bridgeProcs.length && !bridgeMatchesCurrentAccount(relayDir, cfg)) {
       book.lastAttemptAt = now;
       book.attempts += 1;
@@ -5473,7 +5780,7 @@ function telemetryRuntimeReady(relayDir) {
 }
 
 /**
- * 运行环境探针（在补装 watcher 与面板轮询里顺手调用，不额外起定时器）：
+ * 运行环境探测（在补装 watcher 与面板轮询里顺手调用，不额外起定时器）：
  *   - 现在缺运行环境 → 记下「本进程见过缺失」，并在超过 INSTALL_STALE_MS 仍缺时归因为
  *     install_failed(runtime_install_timeout)（每进程一次）；
  *   - 之前见过缺失、现在已就绪 → runtime_ready（每进程一次）。
@@ -5729,7 +6036,7 @@ export const __telemetryInternals = {
 
 /**
  * 安装信息上报（插件侧通道）：登录后把本机安装信息发给企业端，供「已登录用户升级插件后刷新版本号」
- * 之类的口径统计。无账号凭据不上报；失败静默（绝不阻塞面板、不弹错误）。
+ * 之类的约定统计。无账号凭据不上报；失败静默（绝不阻塞面板、不弹错误）。
  * 契约：POST <api_url>/api/install-report，头 `authorization: Bearer <device-login JWT>`，
  * body { device_id?, install_source, install_version, harness_version, host_os, host_arch }，成功 200 {ok:true}；
  * 404/400 一律忽略（老服务端没有该接口时不能报错）。
@@ -6218,7 +6525,7 @@ function registerRoutes(ctx, relayDir) {
       handler: async (_req, res) => {
         // 彻底卸载 = ① 插件 profile 清理（快、纯 fs、可预期）② 运行时/bridge 清理（慢、要调外部命令）
         //
-        // ⚠️ 顺序是刻意的，别改回去（2026-09-18 用户实测的僵死事故）：
+        // ⚠️ 顺序是刻意的，别改回去（2026-09-18 用户实测的僵死故障）：
         //   旧实现把**慢的** uninstallRuntime 排在最前、uninstallSelf 排在其后，于是
         //   uninstallRuntime 里任何一次 spawnSync 卡住（Windows 沙箱拦 schtasks，而 spawnSync 的
         //   timeout 在 Windows 上并不可靠，实测 18s+ 未返回），uninstallSelf 就**永远不执行**
@@ -6596,7 +6903,7 @@ function registerRoutes(ctx, relayDir) {
         invalidateRelayToken(relayDir); // 账号可能变了：丢弃旧 token 缓存，立即用新账号认证
         if (accountFingerprintOf(cfg) !== accountFpBefore) resetBridgeForAccountChange(relayDir, "账号/模式已变更");
         const bridgeRestart = startBridge(relayDir);
-        // 登录成功即上报本机安装信息（企业端用于「升级插件后刷新版本号」口径）；失败静默。
+        // 登录成功即上报本机安装信息（企业端用于「升级插件后刷新版本号」约定）；失败静默。
         maybeReportInstall(relayDir, { force: true });
         sendJson(res, 200, { ok: true, bridgeRestart, ...(await composeStatus(relayDir)) });
       },
@@ -6627,7 +6934,7 @@ function registerRoutes(ctx, relayDir) {
         // 首次安装/在线更新后重启 DeepSeek harness：插件本体与浏览器半在进程启动时装载，
         // 不重启则面板入口与 /dsh-remote/* 路由都不会出现。只重启承载本插件的进程。
         //
-        // 🔴 2026-10-11 业主口径：**桌面端绝不代为重启**。
+        // 🔴 2026-10-11 用户约定：**桌面端绝不代为重启**。
         //   "自动重启会很突兀地把窗口给关掉，关没了……我们应该提示用户自己重启，不要由我们来重启。"
         //   桌面端 Host 由 Electron 托管，重启 = 强杀承载窗口的进程（还会弹原生致命错误）。
         //   这里做成**硬拒绝**（不只是前端藏按钮）：任何调用方都拿不到"被重启"的结果，
@@ -6651,6 +6958,9 @@ function registerRoutes(ctx, relayDir) {
       method: "POST",
       path: "/dsh-remote/start",
       handler: async (_req, res) => {
+        // 用户点了「启动」= 人工指令：清掉自愈护栏额度再动手（同 resetProvisionRetry 的原则），
+        // 否则"自动自愈刚刚熔断"会把用户这一次明确的操作也一起挡掉。
+        resetSelfhealGuard(relayDir);
         const r = startBridge(relayDir);
         // 【0.6.2】composeStatus 自带 ok:true（那是「状态查询成功」），必须先展开再覆盖，
         // 否则不管启动成没成功都回 ok:true → 面板一律弹「✅ bridge 已启动」。
@@ -6754,7 +7064,7 @@ function registerRoutes(ctx, relayDir) {
         const password = String(body.password ?? "");
         if (!phone || !smsCode || !password) return sendJson(res, 400, { ok: false, error: "手机号、短信验证码与密码必填" });
         // 全量透传 body（不挑字段）：注册来源 reg_source（面板=panel_register／手机端网页=remoteweb_register）
-        // 等扩展字段必须原样进企业端，否则「用户从哪注册的」这类增长口径会全部丢失。
+        // 等扩展字段必须原样进企业端，否则「用户从哪注册的」这类增长约定会全部丢失。
         const payload = { ...body, phone, sms_code: smsCode, password };
         delete payload.__parseError;
         const captchaId = body.captcha_id ?? body.captchaId;
@@ -6904,7 +7214,7 @@ function registerRoutes(ctx, relayDir) {
 // 自己持有 webserver 配置（实测监听 43120 / 回环），我们的 LAN 绑定补丁并不生效，于是它一直
 // 用的是原生那条路。**不能把"手机能不能选工作区"押在宿主的绑定地址上。**
 //
-// 【0.6.15 事故修正 —— 0.6.14 的"先建 browse、后摘 auto"在 DSH Desktop 上必然失败】
+// 【0.6.15 故障修正 —— 0.6.14 的"先建 browse、后摘 auto"在 DSH Desktop 上必然失败】
 //
 // 现场（用户诊断日志）：
 //   error: service "directoryPicker" has been registered at .dLateDirectoryPicker3
@@ -7064,9 +7374,9 @@ const PICKER_PIN_PROBE_WAIT_MS = 30_000;  // 等服务挂出来的上限（只
 const PICKER_PIN_PROBE_GAP_MS = 3_000;    // 上面那段轮询间隔
 
 /**
- * 目录选择器的**延后**接线 —— 这是 2026-09-26 启动事故的直接修复。
+ * 目录选择器的**延后**接线 —— 这是 2026-09-26 启动故障的直接修复。
  *
- * 🔴 事故：旧实现在 `apply()` 里**立刻**调 `pinBrowseDirectoryPicker(ctx)`（最多 6 次 × 700ms 轮询）。
+ * 🔴 故障：旧实现在 `apply()` 里**立刻**调 `pinBrowseDirectoryPicker(ctx)`（最多 6 次 × 700ms 轮询）。
  *    `loader.remove()` / `loader.create()` 会触发 dsh 的 `internal/plugin` 事件，而
  *    `@deepseek-ai/dsh-client-modules` 收到事件就**重新 compose 整张前端插件图**
  *    （`ClientModuleRegistry.flush() → buildCombo() → newlineCount()/identitySectionMap()`）。
@@ -7184,7 +7494,7 @@ export function apply(ctx, config = {}) {
   // 0.1.2-rc.1+ 浏览器会话代持：换取 Harness 会话 Cookie 供 bridge 上游携带（手机点设备不再 401 白页）
   ctx.effect(() => scheduleHarnessMint(ctx, relayDir), "dsh-remote-web: harness browser-session mint");
   // 目录选择器:远程控制下必须用浏览器内实现(否则手机点「添加工作区」像没反应) —— 见上方长注释
-  // ⚠️ **必须延后**：绝不能在 apply() 里直接切 Loader —— 会把宿主启动拖成假死（2026-09-26 事故，
+  // ⚠️ **必须延后**：绝不能在 apply() 里直接切 Loader —— 会把宿主启动拖成假死（2026-09-26 故障，
   //    见 schedulePickerPin 上方长注释）。schedulePickerPin 自己等"宿主已 listen + 静置"再动手。
   ctx.effect(() => schedulePickerPin(ctx), "dsh-remote-web: pin browser directory picker");
   // 插件市场一键全功能:缺桌面运行环境则自动安装,登录后自动拉起 bridge(不依赖用户跑 npx)
@@ -7200,7 +7510,7 @@ export function apply(ctx, config = {}) {
     telemetryRuntimeProbe(relayDir); // 匿名遥测：记下「本进程见过运行环境缺失」（装好后发 runtime_ready）
   }
   // 插件启动即上报本机安装信息（install_source/version + 主机 OS/架构；仅有账号凭据时上报，失败静默）。
-  // 面板登录成功（POST /dsh-remote/config）时会再上报一次，覆盖「已登录用户升级插件」的口径。
+  // 面板登录成功（POST /dsh-remote/config）时会再上报一次，覆盖「已登录用户升级插件」的约定。
   maybeReportInstall(relayDir);
   ctx.logger?.info?.(`dsh-remote-web: /dsh-remote routes ready (relayDir=${relayDir})`);
 }
@@ -7210,4 +7520,15 @@ export function apply(ctx, config = {}) {
 // 单独导出才能把「**先摘 auto、后建 browse**」这个顺序契约钉死。
 export { pinBrowseDirectoryPicker as __pinBrowseDirectoryPicker, schedulePickerPin as __schedulePickerPin, pickerPinState as __pickerPinState, directoryPickerKind as __directoryPickerKind, PICKER_AUTO_ENTRY_ID as __PICKER_AUTO_ENTRY_ID, PICKER_AUTO_PACKAGE as __PICKER_AUTO_PACKAGE, PICKER_BROWSE_PACKAGES as __PICKER_BROWSE_PACKAGES,
   // 日志去重（同一条失败不刷屏）也要能被单测钉住 —— 它属于「诊断可读性」，见 test/linux-bridge.test.mjs
-  noteAutostartFailure as __noteAutostartFailure, clearAutostartFailure as __clearAutostartFailure };
+  noteAutostartFailure as __noteAutostartFailure, clearAutostartFailure as __clearAutostartFailure,
+  // ★ 2026-10-13 自愈重启策略（修 12 秒重启风暴）必须能被**行为级**单测钉住，见 test/selfheal-restart-guard.test.mjs。
+  //   为什么必须导出而不是只靠 apply()：这一组用例要断言的是"定时器跑 N 拍之后，
+  //   `systemctl restart` 到底被调用了几次"——只有把定时器本体拿到用例里才能确定性地驱动它，
+  //   靠 apply() 间接跑就得靠真实 sleep 猜拍数（脆弱且慢）。
+  //   系统命令仍然走**假 PATH 上的假 systemctl**（与 test/linux-bridge.test.mjs 同一套手法），
+  //   所以不需要为了可测性往生产代码里插入任何依赖注入层。
+  scheduleRuntime as __scheduleRuntime, startBridge as __startBridge, manualStatus as __manualStatus,
+  linuxSystemdUnitState as __linuxSystemdUnitState,
+  selfhealRestartGate as __selfhealRestartGate, noteSelfhealRestart as __noteSelfhealRestart,
+  noteSelfhealBlocked as __noteSelfhealBlocked, resetSelfhealGuard as __resetSelfhealGuard,
+  selfhealGuardOf as __selfhealGuardOf, SELFHEAL_MAX_RESTARTS as __SELFHEAL_MAX_RESTARTS };