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

package/packages/dsh-remote-web/test/selfheal-restart-guard.test.mjs

@@ -0,0 +1,420 @@
+/**
+ * ★★ 回归锁：自愈 watcher **不许**把"探测失败"翻译成"每 12 秒杀掉一次隧道"。
+ *
+ * 现场（线上反馈 `fb_3c4c5a13bc47`，用户 842，Linux fyf-MS-7D42，npx 安装，插件 0.6.18）：
+ *   用户原话「是给用户列出几个选项选择的那种窗口，总是一会出现、一会儿消失，持续不停。」
+ *
+ * 只读诊断（`dsh-relay-internal/2026-10-13-反馈fb_3c4c5a13bc47-诊断.md`）给出的证据链：
+ *   · `audit_log` 里该设备当天 `device.claim` **3567 次**，相邻间隔 p50 **12001ms**、p90 12281ms，
+ *     连续 10 小时整点 300 次/小时（300 × 12s = 3600s）。而 `device.claim` 是 **bridge 进程启动**
+ *     的必然产物（一个进程只登记一次）→ 3567 次 = 3567 次进程启动；
+ *   · `relay_sessions` 该设备 236 条 ws 会话里 235 条挤在 2h20m 内，单条时长均值 5.3s、最大 7.4s，
+ *     相邻间隔 p50 7.05s（+ 隧道建立 ≈12.3s 一个完整周期）；
+ *   · 每次新 bridge 连接顶掉旧隧道 → 中继 `close(1012 "bridge offline")` 掉该设备**所有**手机镜像
+ *     WS → 镜像页每 12 秒断线重连并**全量重放**界面（同一份 bytes 反复出现）→ 交互弹窗的临时
+ *     界面状态被反复销毁重建 = 用户看到的"一会儿显示、一会儿消失"；
+ *   · 全站性：上百台设备每天 1.1~1.5 万次重登记，多台设备间隔 p50 精确 ≈12.0s
+ *     （11996/11998/12000/12001/12002ms）—— 只可能来自客户端同一个 12s 常量；
+ *   · 中继侧对这类 churn 只做了日志抑制，所以**运维侧一直没发现**。
+ *
+ * 代码落点：`lib/index.js` 的 `scheduleRuntime()`（12s 定时器）→ 就绪判据只有
+ * `launchdStatus().running` 与 `manualStatus().watcher.length > 0`（后者靠 `pgrep` 名称匹配，
+ * 极易拿到空结果）→ 判据为假就 `startBridge()` → `startBridgeLinux()` → **无条件**
+ * `systemctl --user restart dsh-bridge`（restart 会杀掉正在健康运行的 bridge）。
+ *
+ * 本文件锁死的四件事（对应用户给的四条修复要求）：
+ *   ① **权威判据**：`systemctl --user is-active` 说 active ⇒ 就是"在跑"，pgrep 说什么都不算；
+ *   ② **幂等**：已 active 时自愈**绝不得**调用 `systemctl restart`（假 runner 断言调用次数为 0）；
+ *   ③ **成功即止**：一旦判定就绪，同一进程生命周期内定时器真的停摆（后续 systemctl 调用数冻结）；
+ *   ④ **熔断 + 退避 + 可观测**：最小重启间隔内不重复重启；同一进程内最多 3 次；触顶后停手
+ *      并把原因写进**可见**的安装日志（面板「复制诊断信息」与用户主动上报都会带它的尾部）。
+ *
+ * ⚠️ 测试隔离（与 `linux-bridge.test.mjs` 同一套手法）：
+ *   · 走**真实分支**（删掉 DSH_RELAY_SKIP_SERVICE），所以必须伪造 HOME 与 PATH；
+ *   · 所有系统命令都是假 PATH 上的假脚本（`systemctl` 只写调用日志 + 读写状态文件），
+ *     **不会**碰开发者本机上真实的 systemd/launchd；
+ *   · 预置一份 `.dsh-watcher.pid` 指向**本测试进程**（必然存活）→ `startBridgeDetached`
+ *     的"已在跑"分支立刻返回，因此**不会真的派生**任何后台进程。
+ */
+import assert from "node:assert/strict";
+import http from "node:http";
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { apply } from "../lib/index.js";
+import { __scheduleRuntime, __startBridge } from "../lib/index.js";
+import {
+  __linuxSystemdUnitState,
+  __selfhealRestartGate,
+  __noteSelfhealRestart,
+  __noteSelfhealBlocked,
+  __resetSelfhealGuard,
+  __selfhealGuardOf,
+  __SELFHEAL_MAX_RESTARTS,
+} from "../lib/index.js";
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** 本轮上游地址（显式给死，免得依赖 boundWebPort / 端口发现 → 用例结果与开发机状态耦合）。 */
+const UPSTREAM = "http://127.0.0.1:12345";
+/** 模拟"上游地址在抖"时被写回来的旧值。 */
+const UPSTREAM_OLD = "http://127.0.0.1:3080";
+
+/**
+ * 假 systemctl：**每一次调用都记进日志**（用例据此断言 `restart` 被调用了几次），
+ * 状态机放在一个文件里，于是"restart 之后 bridge 真的起来了没有"由用例决定：
+ *   · DSH_TEST_RESTART_HEALS=1 → restart 把状态置为 active（模拟重启后真的恢复）；
+ *   · =0 → restart 不改变状态（模拟"重启了但起不来"）。
+ */
+const FAKE_SYSTEMCTL = `#!/bin/sh
+printf '%s\\n' "$*" >> "$DSH_TEST_SYSTEMCTL_LOG"
+case "$*" in
+  *show-environment*) exit 0 ;;
+  *is-active*)
+    s="$(cat "$DSH_TEST_SYSTEMCTL_STATE" 2>/dev/null)"
+    [ -z "$s" ] && s=inactive
+    echo "$s"
+    [ "$s" = "active" ] && exit 0 || exit 3
+    ;;
+  *daemon-reload*) exit 0 ;;
+  *enable*) exit 0 ;;
+  *restart*)
+    if [ "$DSH_TEST_RESTART_HEALS" = "1" ]; then printf 'active\\n' > "$DSH_TEST_SYSTEMCTL_STATE"; fi
+    exit 0
+    ;;
+esac
+exit 0
+`;
+
+/**
+ * 隔离环境：假 HOME（systemd unit 落这里）+ 假 systemctl/pgrep/ps + 临时 relayDir。
+ * @param {{state?:string, heals?:boolean, minRestartMs?:number, selfhealMs?:number}} opts
+ *   state = 假 systemd 的初始状态（active/inactive/failed）；heals = restart 之后是否变成 active。
+ */
+function makeEnv({ state = "inactive", heals = false, minRestartMs = 60_000, selfhealMs = 25 } = {}) {
+  const root = mkdtempSync(path.join(os.tmpdir(), "dsh-selfheal-"));
+  const fakeBin = path.join(root, "bin");
+  const fakeHome = path.join(root, "home");
+  const relayDir = path.join(root, "relay");
+  mkdirSync(fakeBin, { recursive: true });
+  mkdirSync(fakeHome, { recursive: true });
+  mkdirSync(relayDir, { recursive: true });
+
+  const sysctlLog = path.join(root, "systemctl.log");
+  const sysctlState = path.join(root, "systemctl.state");
+  writeFileSync(sysctlLog, "");
+  writeFileSync(sysctlState, `${state}\n`);
+  writeFileSync(path.join(fakeBin, "systemctl"), FAKE_SYSTEMCTL);
+  chmodSync(path.join(fakeBin, "systemctl"), 0o755);
+  // 假 pgrep：**一个进程都不匹配**（= 本次故障里那个"极易拿到空结果"的探测）。
+  // 用例要证明的正是：即使它一无所获，只要 systemd 说 active，就绝不许 restart。
+  for (const n of ["pgrep", "ps"]) {
+    writeFileSync(path.join(fakeBin, n), "#!/bin/sh\nexit 1\n");
+    chmodSync(path.join(fakeBin, n), 0o755);
+  }
+
+  // 运行环境入口：无相对 import → runtimeReady 判定为就绪（不会去跑 npx 补装）。
+  writeFileSync(path.join(relayDir, "dsh-setup.mjs"), "// 测试用运行环境入口（无相对 import）\n");
+  // 已登录（local_key 即视为有账号）→ 自愈 watcher 才会走到"服务在不在跑"这一步。
+  writeFileSync(path.join(relayDir, ".dsh-config.json"), JSON.stringify({
+    api_url: "http://127.0.0.1:1", local_key: "test-local-key", device_id: "dev-test-selfheal",
+  }));
+  // 上游文件预先写成与 DSH_BRIDGE_UPSTREAM 一致 → publishUpstream() 回报 changed=false
+  // （否则"上游刚变过"本身就是一个合法的重启理由，会把用例的意图搅浑）。
+  writeFileSync(path.join(relayDir, ".dsh-upstream"), `${UPSTREAM}\n`);
+  // ⚠️ 关键隔离：pid 文件指向**本测试进程**（必然存活）→ startBridgeDetached 的
+  //   "已在跑，别再拉第二个"分支立刻返回 → 用例永远不会真的派生后台 bridge 进程。
+  writeFileSync(path.join(relayDir, ".dsh-watcher.pid"), `${process.pid}\n`);
+
+  const saved = {};
+  const keys = ["HOME", "PATH", "DSH_RELAY_PLATFORM", "DSH_RELAY_SKIP_SERVICE", "DSH_REMOTE_TELEMETRY",
+    "DSH_RELAY_SELFHEAL_MS", "DSH_RELAY_SELFHEAL_MIN_RESTART_MS", "DSH_RELAY_DEFAULT_API",
+    "DSH_BRIDGE_UPSTREAM", "DSH_WEB_URL", "XDG_RUNTIME_DIR", "DSH_BRIDGE_INSTALL_SOURCE",
+    "DSH_TEST_SYSTEMCTL_LOG", "DSH_TEST_SYSTEMCTL_STATE", "DSH_TEST_RESTART_HEALS"];
+  for (const k of keys) saved[k] = process.env[k];
+
+  process.env.HOME = fakeHome;
+  process.env.PATH = `${fakeBin}${path.delimiter}${saved.PATH || ""}`;
+  process.env.DSH_RELAY_PLATFORM = "linux";
+  process.env.DSH_REMOTE_TELEMETRY = "0";
+  process.env.DSH_RELAY_DEFAULT_API = "http://127.0.0.1:1";
+  process.env.DSH_BRIDGE_UPSTREAM = UPSTREAM;
+  process.env.XDG_RUNTIME_DIR = path.join(root, "run");
+  mkdirSync(process.env.XDG_RUNTIME_DIR, { recursive: true });
+  process.env.DSH_RELAY_SELFHEAL_MS = String(selfhealMs);
+  process.env.DSH_RELAY_SELFHEAL_MIN_RESTART_MS = String(minRestartMs);
+  process.env.DSH_TEST_SYSTEMCTL_LOG = sysctlLog;
+  process.env.DSH_TEST_SYSTEMCTL_STATE = sysctlState;
+  process.env.DSH_TEST_RESTART_HEALS = heals ? "1" : "0";
+  delete process.env.DSH_RELAY_SKIP_SERVICE; // 走真实分支，但系统命令全是假脚本
+  delete process.env.DSH_WEB_URL;
+  delete process.env.DSH_BRIDGE_INSTALL_SOURCE;
+
+  return {
+    root, relayDir, fakeHome, sysctlLog, sysctlState,
+    /** systemctl 被调用过的**所有**命令行（一行一次）。 */
+    calls: () => readFileSync(sysctlLog, "utf8").split("\n").filter(Boolean),
+    /** 断言用：某个子命令被调用了几次。 */
+    count: (needle) => readFileSync(sysctlLog, "utf8").split("\n").filter((l) => l.includes(needle)).length,
+    installLog: () => {
+      const p = path.join(relayDir, ".dsh-setup-install.log");
+      return existsSync(p) ? readFileSync(p, "utf8") : "";
+    },
+    /** 上游文件"抖"回旧值（见护栏用例）。 */
+    rewindUpstream: () => writeFileSync(path.join(relayDir, ".dsh-upstream"), `${UPSTREAM_OLD}\n`),
+    setState: (s) => writeFileSync(sysctlState, `${s}\n`),
+    restore() {
+      __resetSelfhealGuard(relayDir);
+      for (const [k, v] of Object.entries(saved)) { if (v === undefined) delete process.env[k]; else process.env[k] = v; }
+      rmSync(root, { recursive: true, force: true });
+    },
+  };
+}
+
+/** 起一个只跑插件路由的假宿主（与 `linux-bridge.test.mjs` 同一手法）：只为驱动真实的面板端点。 */
+function bootRoutes(relayDir) {
+  const routes = new Map();
+  const disposers = [];
+  apply({
+    webServer: { port: 0, register(route) { routes.set(route.path, route.handler); return () => {}; } },
+    get() { return null; },
+    effect(register) { const d = register(); if (typeof d === "function") disposers.push(d); return d; },
+    logger: { info() {}, warn() {} },
+  }, { relayDir });
+  routes.dispose = () => { for (const d of disposers) { try { d(); } catch { /* ignore */ } } };
+  return routes;
+}
+
+async function serveRoutes(routes) {
+  const host = http.createServer((req, res) => {
+    const handler = routes.get(new URL(req.url, "http://x").pathname);
+    (handler || ((_r, rs) => { rs.writeHead(404); rs.end(); }))(req, res);
+  });
+  await new Promise((resolve) => host.listen(0, "127.0.0.1", resolve));
+  return {
+    base: `http://127.0.0.1:${host.address().port}`,
+    async close() { await new Promise((r) => host.close(r)); },
+  };
+}
+
+// ─────────────── ① 权威判据 + ② 幂等：已 active 时自愈绝不得 restart ───────────────
+test("★ ①：systemctl 说 active（而 pgrep 一无所获）→ 自愈 watcher 必须判定「就绪」，restart 调用 0 次", async () => {
+  const env = makeEnv({ state: "active" });
+  let stop = null;
+  try {
+    // 前置：权威判据本身要能读出 active（三态里的"明确 active"）
+    assert.deepEqual(__linuxSystemdUnitState(), { known: true, active: true, raw: "active" });
+
+    stop = __scheduleRuntime(env.relayDir);
+    await sleep(400); // 自愈间隔 25ms → 这段窗口内本会跑十几拍
+
+    const calls = env.calls();
+    assert.equal(env.count("restart"), 0,
+      `★ 已 active 就绝不许 restart（那是这台机器上唯一会造成"手机镜像每 12 秒断一次"的动作）。`
+      + `实际调用：\n${calls.join("\n")}`);
+    assert.equal(env.count("stop"), 0, "更不许 stop：停掉正在跑的 bridge 会直接断掉用户的远程访问");
+    assert.ok(env.calls().some((l) => l.includes("is-active")), "应当用 is-active 做权威判据，而不是猜进程名");
+
+    // 判定就绪 → 循环停摆：调用数必须冻结（不只是"被限流"，是真的不再探了）
+    const frozen = env.calls().length;
+    await sleep(300);
+    assert.equal(env.calls().length, frozen, "★ 判定就绪后定时器必须真的停摆（调用数冻结）");
+
+    // 可观测：留下"判定就绪、已停止自愈循环"的一行（同一条结论只写一次）
+    const log = env.installLog();
+    assert.match(log, /自愈判定 bridge 已就绪，已停止自愈循环/, `安装日志必须留下判据与依据，实际：\n${log}`);
+    assert.match(log, /systemd --user is-active=active/, "日志要写清依据是 systemd 的权威回答");
+    assert.doesNotMatch(log, /自愈重启 bridge/, "既然没重启，就不该有重启记录");
+  } finally {
+    stop?.();
+    env.restore();
+  }
+});
+
+test("★ ②：已 active 时反复调用 startBridge（面板重试/自愈轮次）也必须幂等 —— restart 恒为 0 次", () => {
+  const env = makeEnv({ state: "active" });
+  try {
+    for (let i = 0; i < 6; i += 1) {
+      const r = __startBridge(env.relayDir);
+      assert.equal(r.ok, true, `已 active 时必须如实回报 ok（第 ${i + 1} 次），实际 ${JSON.stringify(r)}`);
+      assert.equal(r.reused, true, `已 active 时必须标记 reused（第 ${i + 1} 次）`);
+      assert.equal(r.status, "running");
+    }
+    assert.equal(env.count("restart"), 0,
+      `★ 幂等闸门失效：已 active 却调了 restart。实际调用：\n${env.calls().join("\n")}`);
+    assert.equal(env.count("daemon-reload"), 0, "既然没必要重启，就不该连 daemon-reload 一起做（避免无谓的 systemd 抖动）");
+    assert.equal(env.count("enable"), 0);
+  } finally {
+    env.restore();
+  }
+});
+
+// ─────────────── ② + ③：确实没在跑才重启，且最小间隔内不重复、成功即止 ───────────────
+
+test("★ ②③：真的不 active 时才重启**一次**；成功即止（同一进程生命周期内不再有 restart）", async () => {
+  // 模拟"systemd 里它确实没在跑，但 restart 之后真的起来了"
+  const env = makeEnv({ state: "inactive", heals: true, minRestartMs: 60_000, selfhealMs: 25 });
+  let stop = null;
+  try {
+    stop = __scheduleRuntime(env.relayDir);
+    await sleep(250);
+    assert.equal(env.count("restart"), 1,
+      `★ 只该重启一次，实际 ${env.count("restart")} 次：\n${env.calls().join("\n")}`);
+
+    // 成功即止：定时器必须停摆，后续调用数冻结（不是"每 25ms 被限流一次"）
+    const frozen = env.calls().length;
+    await sleep(300);
+    assert.equal(env.count("restart"), 1, "★ 判定成功后再也不许有 restart 调用");
+    assert.equal(env.calls().length, frozen, "★ 判定成功之后定时器必须停摆（调用数冻结）");
+
+    const log = env.installLog();
+    assert.match(log, /自愈重启 bridge（第 1\/3 次/, `重启必须留可见日志，实际：\n${log}`);
+    assert.match(log, /→ running/, "日志要带上重启后的结果");
+    assert.match(log, /自愈判定 bridge 已就绪，已停止自愈循环/, "就绪后要写「循环已停」的一行");
+  } finally {
+    stop?.();
+    env.restore();
+  }
+});
+
+test("★ ④：最小重启间隔内**不重复**重启，并且写下可见的「已暂缓」日志", () => {
+  // 起不来（heals=false）+ 最小间隔 60 秒：真实重启只许发生 1 次，后面的尝试全被拦下。
+  const env = makeEnv({ state: "inactive", heals: false, minRestartMs: 60_000 });
+  try {
+    for (let i = 0; i < 5; i += 1) __startBridge(env.relayDir);
+    assert.equal(env.count("restart"), 1,
+      `★ 最小间隔（60s）内不得重复 restart，实际 ${env.count("restart")} 次：\n${env.calls().join("\n")}`);
+
+    const log = env.installLog();
+    assert.match(log, /已暂缓自愈重启 bridge：距上次重启不足 60 秒/, `实际：\n${log}`);
+    // 去重：同一条结论只说一次（否则每 12 秒一行，用户复制过来的诊断里全是重复行）
+    const hits = log.split("\n").filter((l) => l.includes("已暂缓自愈重启 bridge")).length;
+    assert.equal(hits, 1, `同一条"已暂缓"结论不得刷屏，实际 ${hits} 行`);
+  } finally {
+    env.restore();
+  }
+});
+
+// ─────────────── ④ 熔断触顶：停手 + 明确报错 ───────────────
+
+test("★ ④：破坏性重启触顶（本进程最多 3 次）后**停手**，并写下明确的熔断日志", () => {
+  // 场景：上游地址在抖（上游文件被另一个组件写回旧值）→ 每轮都会认为"需要重启才能生效"。
+  // 这正是护栏存在的意义：哪怕上游真的在抖，也绝不能退化成"每 12 秒杀一次隧道"。
+  const env = makeEnv({ state: "active", minRestartMs: 0 });
+  try {
+    for (let i = 0; i < 6; i += 1) {
+      env.rewindUpstream();     // 上游地址又变了 → 又一个"合法的重启理由"
+      __startBridge(env.relayDir);
+    }
+    assert.equal(env.count("restart"), __SELFHEAL_MAX_RESTARTS,
+      `★ 同一进程内最多 ${__SELFHEAL_MAX_RESTARTS} 次破坏性重启，实际 ${env.count("restart")} 次：\n${env.calls().join("\n")}`);
+    assert.equal(__selfhealGuardOf(env.relayDir).count, __SELFHEAL_MAX_RESTARTS);
+
+    const log = env.installLog();
+    assert.match(log, /已停止自愈重启 bridge：本进程生命周期内已重启 3 次仍未就绪/, `实际：\n${log}`);
+    assert.match(log, /已熔断/, "要把「熔断」这个结论明确写给用户/运维");
+    assert.match(log, /一键更新/, "要给出下一步动作，而不是只报一个错误");
+    const hits = log.split("\n").filter((l) => l.includes("已停止自愈重启 bridge")).length;
+    assert.equal(hits, 1, `熔断结论只说一次，实际 ${hits} 行`);
+
+    // 触顶之后再怎么抖，也不许再动 bridge
+    for (let i = 0; i < 3; i += 1) { env.rewindUpstream(); __startBridge(env.relayDir); }
+    assert.equal(env.count("restart"), __SELFHEAL_MAX_RESTARTS, "★ 触顶后必须彻底停手");
+  } finally {
+    env.restore();
+  }
+});
+
+test("★ ④ 护栏本身：纯查询语义（不记账）+ 三态边界", () => {
+  const env = makeEnv({ state: "inactive", minRestartMs: 1000 });
+  try {
+    // 纯查询：反复问不许改变状态（否则"只查不做"的路径会凭空吃掉额度）
+    for (let i = 0; i < 5; i += 1) assert.equal(__selfhealRestartGate(env.relayDir).allowed, true);
+    assert.equal(__selfhealGuardOf(env.relayDir).count, 0, "查询不得记账");
+
+    __noteSelfhealRestart(env.relayDir, "测试", "running");
+    assert.equal(__selfhealGuardOf(env.relayDir).count, 1);
+    const tooSoon = __selfhealRestartGate(env.relayDir);
+    assert.equal(tooSoon.allowed, false);
+    assert.equal(tooSoon.reason, "too-soon");
+    assert.ok(tooSoon.waitMs > 0 && tooSoon.waitMs <= 1000, `waitMs 应落在剩余窗口内，实际 ${tooSoon.waitMs}`);
+
+    __noteSelfhealRestart(env.relayDir, "测试", "running");
+    __noteSelfhealRestart(env.relayDir, "测试", "running");
+    const exhausted = __selfhealRestartGate(env.relayDir);
+    assert.equal(exhausted.allowed, false);
+    assert.equal(exhausted.reason, "exhausted");
+    // 记一次重启会清掉"被拦下"的去重状态（结论变了要重新说）
+    assert.equal(__selfhealGuardOf(env.relayDir).blockedLine, "");
+
+    __resetSelfhealGuard(env.relayDir);
+    assert.equal(__selfhealGuardOf(env.relayDir).count, 0, "桥恢复后要能重新自愈");
+    assert.equal(__selfhealRestartGate(env.relayDir).allowed, true);
+  } finally {
+    env.restore();
+  }
+});
+
+test("★ ④ 护栏文案：被拦下时写进**可见**日志（面板诊断/用户上报会带它）", () => {
+  const env = makeEnv({ state: "inactive", minRestartMs: 5000, selfhealMs: 12_000 });
+  try {
+    assert.equal(__noteSelfhealBlocked(env.relayDir, { reason: "too-soon", count: 1, waitMs: 4000 }), true);
+    assert.equal(__noteSelfhealBlocked(env.relayDir, { reason: "too-soon", count: 1, waitMs: 1234 }), false,
+      "★ 文案里不得带倒计时秒数，否则每拍文本都不同、去重失效 → 又变成刷屏");
+    assert.equal(__noteSelfhealBlocked(env.relayDir, { reason: "exhausted", count: 3, waitMs: 0 }), true);
+    const log = env.installLog();
+    assert.match(log, /已暂缓自愈重启 bridge/);
+    assert.match(log, /已停止自愈重启 bridge/);
+    // 文案必须点出"那个 12 秒"本身：它就是这个故障的名字，也是用户能对上号的信息
+    assert.match(log, /每 12 秒重启一次/);
+    assert.match(log, /每 12 秒杀掉一次正在跑的隧道/);
+  } finally {
+    env.restore();
+  }
+});
+
+// ─────────────── 契约锁：护栏只约束"自动"，绝不约束"人" ───────────────
+
+test("★ 契约：面板「重试」（ensureConnection force=true）必须无视已熔断的护栏，仍然把 bridge 拉起来", async () => {
+  // 自愈间隔设成 10 分钟 → 定时器在本用例里绝不会自己跑，行为只来自面板这一次显式请求。
+  const env = makeEnv({ state: "inactive", heals: true, minRestartMs: 60_000, selfhealMs: 600_000 });
+  const routes = bootRoutes(env.relayDir);
+  const srv = await serveRoutes(routes);
+  try {
+    // 前置：模拟"自动自愈已经把 3 次额度用完并熔断"
+    for (let i = 0; i < __SELFHEAL_MAX_RESTARTS; i += 1) __noteSelfhealRestart(env.relayDir, "前置", "running");
+    assert.equal(__selfhealRestartGate(env.relayDir).reason, "exhausted", "前置条件：护栏必须已熔断");
+    assert.equal(__startBridge(env.relayDir).status, "selfheal-throttled", "前置条件：自动路径此刻确实被拦下");
+
+    // 用户点面板「重试」→ POST /dsh-remote/connect/retry（内部 force=true）
+    const res = await fetch(`${srv.base}/dsh-remote/connect/retry`, { method: "POST" });
+    assert.equal(res.status, 200);
+    assert.equal(env.count("restart"), 1,
+      `★ 人工操作必须永远立即放行（与 resetProvisionRetry 同一原则）——`
+      + `否则熔断会变成"用户被自己的插件锁在门外"。实际调用：\n${env.calls().join("\n")}`);
+    // 账号切换同理（resetBridgeForAccountChange 里也清了额度），这里只锁住"重试"这一条即可
+    assert.equal(__linuxSystemdUnitState().active, true, "重试之后 bridge 应当真的起来了");
+  } finally {
+    await srv.close();
+    routes.dispose();
+    env.restore();
+  }
+});
+
+// ─────────────── 隔离自检：本文件不得碰真实系统 ───────────────
+
+test("★ 隔离自检：本文件走的都是假 systemctl（真实系统命令一个都不碰）", () => {
+  const env = makeEnv({ state: "inactive" });
+  try {
+    __startBridge(env.relayDir);
+    const calls = env.calls();
+    assert.ok(calls.length > 0, "前置：假 systemctl 必须真的被调用过（否则下面的断言恒真）");
+    assert.ok(calls.every((l) => l.startsWith("--user ")), `假 runner 收到的是 systemctl --user 系列命令：${calls.join(" | ")}`);
+    // process.execPath 是本机 node，但 pid 文件指向本测试进程 → 绝不会派生真的 watcher
+    assert.equal(env.installLog().includes("脱离进程启动 bridge 失败"), false);
+  } finally {
+    env.restore();
+  }
+});

package/packages/dsh-remote-web/test/settings-entry-placement.test.mjs

@@ -1,9 +1,9 @@
-// dsh-remote-web 侧栏快捷入口「落点」回归（2026-10-09 桌面端事故）。
+// dsh-remote-web 侧栏快捷入口「落点」回归（2026-10-09 桌面端故障）。
 //
-// 【事故】桌面端（DSH 0.2）设置面板本身就是 `role="dialog" aria-modal="true"` 的弹层，
+// 【故障】桌面端（DSH 0.2）设置面板本身就是 `role="dialog" aria-modal="true"` 的弹层，
 //   它左侧栏目列表的第一项叫 **「通用设置」**。旧代码用「文本包含『设置』」（`indexOf !== -1`）
 //   去找侧栏那颗齿轮按钮 → **命中的是弹层里的「通用设置」**，于是我们的「📱 远程访问」
-//   快捷按钮被插进了设置面板栏目列表的最上面。业主截图反馈：「植入错了地方」。
+//   快捷按钮被插进了设置面板栏目列表的最上面。用户截图反馈：「植入错了地方」。
 //
 // 本用例把 client.js 里的导航注入辅助函数**原样切出来**，喂一个最小 DOM，逐条锁住：
 //   ① 官方「设置」触发器只按**语义锚点**（aria-haspopup="dialog"）识别，且必须在弹层之外；
@@ -129,13 +129,13 @@ function desktopFixture() {
 
 // ───────────────────────── 用例 ─────────────────────────
 
-test("★ 事故锁：官方「设置」触发器只认语义锚点，且必须落在**设置弹层之外**", () => {
+test("★ 回归锁：官方「设置」触发器只认语义锚点，且必须落在**设置弹层之外**", () => {
   const { doc, trigger } = desktopFixture();
   const { pickSettingsTrigger } = loadNavHelpers(doc);
   assert.equal(pickSettingsTrigger(), trigger, "必须命中侧栏那颗 aria-haspopup=dialog 的齿轮按钮");
 });
 
-test("★ 2026-10-11 业主实测：点入口弹出的是 token 用量弹窗 —— 官方设置槽位必须优先于底部槽邻居", () => {
+test("★ 2026-10-11 用户实测：点入口弹出的是 token 用量弹窗 —— 官方设置槽位必须优先于底部槽邻居", () => {
   // 现场：入口挂在 sidebar.footer.action，而同一底部区域的「token 本轮用量」按钮
   // 也带 aria-haspopup="dialog"（甚至带快捷键）→ 旧实现"谁先扫到谁"就点中了它。
   // 现在：① 官方设置槽位里的按钮排第一；② 底部槽（我们所在那块）里的候选直接排除。
@@ -159,7 +159,7 @@ test("★ 2026-10-11 业主实测：点入口弹出的是 token 用量弹窗 —
   assert.equal(pickSettingsTrigger(), trigger, "★ 必须选中官方设置槽位里的齿轮，而不是 token 用量按钮");
 });
 
-test("★ 事故锁：弹层里的「通用设置」永远不能成为落点", () => {
+test("★ 回归锁：弹层里的「通用设置」永远不能成为落点", () => {
   const { doc, general } = desktopFixture();
   const { pickSettingsTrigger, pickNavByToken } = loadNavHelpers(doc);
   assert.notEqual(pickSettingsTrigger(), general, "「通用设置」在弹层内，绝不能被当成侧栏设置按钮");

package/packages/dsh-remote-web/test/settings-entry.test.mjs

@@ -165,7 +165,7 @@ function loadPlugin(opts = {}) {
 test("入口：settings.section 栏目（id/order/label）+ 侧栏底部官方槽 sidebar.footer.action", () => {
   const plugin = loadPlugin();
 
-  // 2026-10-10 三修（业主口径「就要放侧栏底部那个位置」）：入口改注册进**官方列表槽**
+  // 2026-10-10 三修（用户约定「就要放侧栏底部那个位置」）：入口改注册进**官方列表槽**
   // `sidebar.footer.action`（宿主为侧栏底部区域提供的扩展点；0.2 实测该槽当前为空）。
   // 不再自己注入 DOM —— 前两次都是"自己找落点"找错的。
   assert.ok(plugin.injects.has("sidebar.footer.action"), "应注入官方侧栏底部槽");
@@ -359,7 +359,7 @@ test("源码约束：侧栏注入「远程访问」按钮与官方「设置」
 });
 
 test("源码约束：侧栏入口走官方槽位/无浮动面板/无切换账号；命名统一为「远程访问」", () => {
-  // 2026-10-10 三修：侧栏入口**改回**官方槽位（业主口径「就要放侧栏底部那个位置」），
+  // 2026-10-10 三修：侧栏入口**改回**官方槽位（用户约定「就要放侧栏底部那个位置」），
   // 所以这条从"不得出现 footer.action"翻转为"必须走官方槽位、不得自己注入 DOM"。
   assert.match(SOURCE, /slots\.inject\("sidebar\.footer\.action"/);
   assert.doesNotMatch(SOURCE, /insertBefore\(btn, host\)/, "不得再自己插 DOM 找落点");

package/packages/dsh-remote-web/test/settings-open-path.test.mjs

@@ -1,7 +1,7 @@
 /**
- * 「点入口怎么打开设置」契约测试（2026-10-11 业主反馈后的最终形态）。
+ * 「点入口怎么打开设置」契约测试（2026-10-11 用户反馈后的最终形态）。
  *
- * 背景（业主原话）：
+ * 背景（用户原话）：
  *   ① 「账号菜单里面的那个删掉。只保留官方槽位的那个。」
  *   ② 「设置界面出现了两个远程访问菜单。」—— 因为账号菜单注入的判据里加了"以设置结尾"，
  *      而「通用设置」正好以"设置"结尾 → 注入行被插进了**设置面板**里，多出一个"远程访问"。
@@ -63,9 +63,9 @@ test("★ 设置面板打开后自动点中「远程访问」栏目", () => {
   assert.deepEqual(clicked, ["远程访问"], "面板开了要顺手切到我们的栏目");
 });
 
-test("★ 不再往账号菜单里插任何东西（业主明确要求删掉）", () => {
+test("★ 不再往账号菜单里插任何东西（用户明确要求删掉）", () => {
   for (const banned of ["dru-menu-row", "accountMenuInjectTick", "MENU_ENTRY_SIG"]) {
-    assert.ok(!SOURCE.includes(banned), `不得再往账号菜单里插条目：${banned}（已按业主要求删除）`);
+    assert.ok(!SOURCE.includes(banned), `不得再往账号菜单里插条目：${banned}（已按用户要求删除）`);
   }
 });
 

package/packages/dsh-remote-web/test/setup-output.test.mjs

@@ -26,7 +26,7 @@ const SETUP = join(HERE, "..", "..", "..", "dsh-setup.mjs");
 const src = readFileSync(SETUP, "utf8");
 
 test("测试隔离：unset 系统操作开关的用例必须同时伪造 HOME（否则污染真实自启动）", () => {
-  // 事故复盘:harness-restart 用例 unset DSH_RELAY_SKIP_SERVICE 去走真实分支,
+  // 故障回顾:harness-restart 用例 unset DSH_RELAY_SKIP_SERVICE 去走真实分支,
   // 但没伪造 HOME → 插件写 plist 的路径是 join(homedir(), "Library/LaunchAgents/…"),
   // 于是把**指向测试临时目录**的 plist 覆盖到开发者真实的 ~/Library/LaunchAgents,
   // 临时目录随即被删 → 真实 bridge 自启动彻底失效(本机实测踩到,macOS 26 用户反馈排查时发现)。
@@ -105,13 +105,13 @@ test("安装输出:跳过/不支持自启动时不得自相矛盾地显示「运
 });
 
 test("安装输出:服务状态字符串仍是插件面板可解析的稳定契约", () => {
-  // 插件半按 running / 未运行 解析,不能因为排版调整改口径
-  assert.ok(/\? `✅ 运行中/.test(src), "running 口径保留(带 pid)");
-  assert.ok(/`未运行 \(\$\{st\.detail \|\| st\.status\}\)`/.test(src), "未运行口径保留(带原因)");
+  // 插件半按 running / 未运行 解析,不能因为排版调整改约定
+  assert.ok(/\? `✅ 运行中/.test(src), "running 约定保留(带 pid)");
+  assert.ok(/`未运行 \(\$\{st\.detail \|\| st\.status\}\)`/.test(src), "未运行约定保留(带原因)");
 });
 
 test("版本比较：预设版 < 同号正式版；beta.10 < beta.11（更新提示不能误判）", () => {
-  // 事故背景：面板原本用 `latest !== current` 判断"有没有新版本"，于是
+  // 故障背景：面板原本用 `latest !== current` 判断"有没有新版本"，于是
   // ① 0.6.4-beta.11 与 0.6.4-beta.10 无法比大小；② 正式版 0.6.4 发布后，
   // 装了 0.6.4-beta.11 的人反而被当成"落后"（其实预设版 semver 低于正式版）。
   const src = readFileSync(join(HERE, "..", "lib", "index.js"), "utf8");
@@ -135,8 +135,8 @@ test("版本比较：预设版 < 同号正式版；beta.10 < beta.11（更新提
   assert.match(src, /cmp === null \? Boolean\(latest && latest !== current\) : cmp > 0/);
 });
 
-test("★ 插件覆盖必须原子：staging → 必需文件自检 → rename 切换（2026-09-26「dsh 起不来」事故）", () => {
-  // 事故：旧实现 `rmSync(dest)` → `cpSync(pluginDir, dest)`，于是拷贝期间 dest 是"半个插件"：
+test("★ 插件覆盖必须原子：staging → 必需文件自检 → rename 切换（2026-09-26「dsh 起不来」故障）", () => {
+  // 故障：旧实现 `rmSync(dest)` → `cpSync(pluginDir, dest)`，于是拷贝期间 dest 是"半个插件"：
   //   dsh 恰在此刻启动 → package.json 已声明 bundle，但 cordis.patch.yml 还没拷到 →
   //   `failed to read overlay … cordis.patch.yml: ENOENT` → **整个 GUI 起不来**。
   //   时间证据：dsh 报错 23:46:03，cordis.patch.yml 写完 23:46:05（差 2 秒）。
@@ -153,12 +153,12 @@ test("★ 插件覆盖必须原子：staging → 必需文件自检 → rename
   assert.match(fn, /renameSync\(backup, dest\)/, "切换失败必须把 backup 改回来（旧版仍可用）");
   // 反向锁：绝不允许回到"先 rm dest、再 cpSync 逐文件"的旧写法
   assert.ok(!/fs\.rmSync\(dest,\s*\{\s*recursive:\s*true,\s*force:\s*true\s*\}\);\s*\n\s*fs\.cpSync\(/.test(fn),
-    "🔴 不得再出现「先删 dest 再原地逐文件拷贝」——那正是这次事故的成因");
+    "🔴 不得再出现「先删 dest 再原地逐文件拷贝」——那正是这次故障的成因");
   assert.match(fn, /\.staging-\$\{process\.pid\}|\.staging-/, "被强杀留下的 staging 要能清理");
 });
 
 test("★ 插件拷贝必须保留**自带的 runtime/node_modules**（ws 是桥唯一的裸依赖）", () => {
-  // 2026-10-10 事故形态：过滤规则写的是"任何一段叫 node_modules 就剔除"，
+  // 2026-10-10 故障形态：过滤规则写的是"任何一段叫 node_modules 就剔除"，
   // 本意只想去掉插件自己的依赖目录（那些由 profile 的包管理器管），
   // 却把 `runtime/node_modules/ws` 一起剔了 —— 而这份运行时正是"只有插件半"的机器
   // **自愈补装时的唯一来源**。剔掉它 → 自愈出来的运行环境缺 ws
@@ -228,8 +228,8 @@ test("★ 自启动配置里可以钉住上游（多 profile 时代，各宿主
 });
 
 test("★ 桌面应用在运行时，绝不改写它的 profile（否则应用会自己退出/重启）", () => {
-  // 2026-10-11 事故：在应用运行中改写 ~/.dsh/profiles/desktop/ 的插件文件 →
-  // 应用随即自己退出/重启（业主："怎么又触发了 dsh 的关闭"）。安装器文案早就写了"先完全退出应用"，
+  // 2026-10-11 故障：在应用运行中改写 ~/.dsh/profiles/desktop/ 的插件文件 →
+  // 应用随即自己退出/重启（用户："怎么又触发了 dsh 的关闭"）。安装器文案早就写了"先完全退出应用"，
   // 但必须由程序强制，不能靠人记得。
   const src = readFileSync(SETUP, "utf8");
   assert.match(src, /function dshDesktopAppRunning\(/, "要有「桌面应用是否在运行」的探测");

package/packages/dsh-remote-web/test/tarball-update.test.mjs

@@ -1,7 +1,7 @@
 /**
  * 零依赖 tarball 更新通道的回归测试（node:test，零框架）。
  *
- * 背景（真实事故，见 lib/tarball-update.js 顶部注释）：
+ * 背景（真实故障，见 lib/tarball-update.js 顶部注释）：
  *   Windows 上「一键更新」走的 `npx` 在 Node ≥20.12 起同步 EINVAL，0.6.6 及更早的升级通道
  *   本身是坏的 —— 79 台点过一键更新的 Windows 机器全部 update_failed，且产品内无出路。
  *   本文件就是给替代通道（HTTPS 取 tarball → 内置 zlib + 自解析 tar 落 staging）上锁：

package/packages/dsh-remote-web/test/telemetry.test.mjs

@@ -268,7 +268,7 @@ test("触发点：plugin_loaded → install_started → runtime_ready → bridge
 
     const { host, base } = await serve(routes);
     try {
-      // ③ 运行环境补齐（dsh-setup.mjs 落地）→ 面板轮询触达探针 → runtime_ready
+      // ③ 运行环境补齐（dsh-setup.mjs 落地）→ 面板轮询触达探测 → runtime_ready
       await writeFile(path.join(env.relayDir, "dsh-setup.mjs"), "// runtime stub");
       let r = await bridgeStatus(base);
       assert.equal(r.ok, true);
@@ -351,7 +351,7 @@ test("隐私审计：对抗性 extra 字段（手机号/hostname/machine_fp/路
     // 直接往唯一的构造点灌脏数据：字段白名单 + 事件名校验必须把它们全部丢掉
     TELEMETRY.record(env.relayDir, "install_started", { device_id: "dev-telemetry", machine_fp: "fp-abc" });
     TELEMETRY.record(env.relayDir, "plugin_loaded", { hostname: "mac.local", username: "mac" });
-    TELEMETRY.record(env.relayDir, "panel_opened", { path: "/Users/mac/.dsh-remote", phone: "13800000000" });
+    TELEMETRY.record(env.relayDir, "panel_opened", { path: "/home/user/relay", phone: "13800000000" });
     TELEMETRY.record(env.relayDir, "update_started", { email: "a@b.c", token: "jwt", password: "pw" });
     TELEMETRY.record(env.relayDir, "harness_restart", { ip: "1.2.3.4" });
     // 白名单外的事件名：一条都不入队
@@ -554,7 +554,7 @@ test("冻结契约：既有事件名与既有字段一字不改（本次只新
   assert.match(String(ev.node), /^\d+$/);
   assert.ok(!("fail_code" in ev), "fail_code 仍只出现在 *_failed 事件上");
   assert.equal(TELEMETRY.eventOf("user_login"), null, "白名单外事件名照旧不发");
-  // 通道与"一键更新"同源：面板看到的通道 = 上报的通道（两处口径必须是一处）
+  // 通道与"一键更新"同源：面板看到的通道 = 上报的通道（两处约定必须是一处）
   assert.equal(ev.channel, TELEMETRY.updateTag);
 });
 
@@ -845,7 +845,7 @@ test("面板可见性：关于卡片写明「匿名统计 + 关闭方式」，
     "客户端上报的事件，不是服务端的实时存量",
     "bot_id",
   ]) {
-    assert.ok(doc.includes(line), "docs/telemetry.md 必须写明微信通道事件的口径边界：" + line);
+    assert.ok(doc.includes(line), "docs/telemetry.md 必须写明微信通道事件的约定边界：" + line);
   }
   for (const code of TELEMETRY.failCodes) assert.ok(doc.includes(code), "docs/telemetry.md 必须列出失败码：" + code);
 });

package/packages/dsh-remote-web/test/uninstall-safety.test.mjs

@@ -89,7 +89,7 @@ async function plantProfile(home, { extraPatch = "", unmarked = false } = {}) {
   fs.mkdirSync(path.join(home, "relay"), { recursive: true });
   // ⚠️ api_url 必须指向本地死端口：这些是**假账号**，一旦按默认地址请求生产，
   //    /api/device-login 会带着假密码失败，而服务端登录限流是按出口 IP 计的（5 次/15 分钟）——
-  //    实测结果是把**本机真实的 bridge** 连坐进限流（2026-09-19 事故）。
+  //    实测结果是把**本机真实的 bridge** 连坐进限流（2026-09-19 故障）。
   fs.writeFileSync(path.join(home, "relay", ".dsh-config.json"),
     JSON.stringify({ phone: "13800000000", password: "pw", api_url: "http://127.0.0.1:1" }));
   return { profile, patchFile: path.join(profile, "cordis.patch.yml") };
@@ -418,7 +418,7 @@ test("安全：三处机密写入都要显式收紧 ACL（Windows 上 mode 0o600
 });
 
 test("安全：Cookie 的每个写入点都必须紧跟着 hardenFile（按 authority 分文件后不得漏收）", () => {
-  // 0.7.0-beta.2 把 Cookie 从「一份共享文件」改成「本宿主专属 + 旧版镜像」两份（见 P0-2 事故根治）。
+  // 0.7.0-beta.2 把 Cookie 从「一份共享文件」改成「本宿主专属 + 旧版镜像」两份（见 P0-2 故障根治）。
   // 写点从 1 个变 2 个 —— 逐个按变量名断言，漏收的那一份在 Windows 上就是 ACL 敞开状态。
   const mint = INDEX_SRC.slice(INDEX_SRC.indexOf("async function mintHarnessCookie"), INDEX_SRC.indexOf("function readHarnessCookie"));
   assert.ok(mint.length > 0, "应能定位到 mintHarnessCookie（找不到说明函数被改名，请同步本用例）");

package/packages/dsh-remote-web/test/watcher-upstream-port.test.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * watcher 的上游端口发现回归 —— 复现 2026-09-23 两起真实事故的**用户可见形态**。
+ * watcher 的上游端口发现回归 —— 复现 2026-09-23 两起真实故障的**用户可见形态**。
  *
  * 现场（用户报告，DSH Desktop 2.0.4 + 插件 0.6.10）：
  *   ```