@mrrisega/dsh-remote 0.7.6 → 0.7.9-beta.1

package/clients/dsh-remote/test/channel-ref.test.mjs

@@ -0,0 +1,250 @@
+// 渠道归因码（channel referral）全链路回归。
+//
+// 契约：dsh-relay-enterprise/docs/channel-referral-contract.md §1 / §5 ——
+//   `npx @mrrisega/dsh-remote --ref 368`
+//     → 安装器把 `--ref`（3~6 位数字）写进 ~/.dsh-remote/.dsh-config.json 的 `ref_code`
+//     → bridge `POST /api/devices` 带 `ref_code`；
+//     → 插件 `POST /api/install-report` 带 `ref_code`，面板注册 `POST /api/register` 带 `channel_code`。
+//   非法值一律静默忽略（归因是附加信息，绝不能因此让安装失败）。
+//
+// 三层锁（哪一层单独测都不够）：
+//   A. 解析/合并纯函数：非法值忽略、CLI > 环境变量、升级不覆盖已有值；
+//   B. 真起 bridge 进程 + 127.0.0.1 假账号 API：逐字断言 `/api/devices` 的 body；
+//   C. 真跑安装器子进程（隔离 HOME / DSH_RELAY_DIR）：断言磁盘上的 ref_code 行为。
+//
+// ⚠️ 所有测试进程只绑 127.0.0.1（仓库测试铁律：不许绑 0.0.0.0）。
+import assert from "node:assert/strict";
+import { execFile, spawn } from "node:child_process";
+import http from "node:http";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { setTimeout as delay } from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+import { WebSocketServer } from "ws";
+import { applyRefCodeToConfig, normalizeRefCode, resolveRefCode } from "../src/channel-ref.mjs";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const BRIDGE = path.join(HERE, "..", "dsh-bridge.mjs");
+const SETUP = path.join(HERE, "..", "..", "..", "dsh-setup.mjs");
+
+// ───────────────────────── A. 纯函数（安装器/桥共用同一份规则） ─────────────────────────
+
+test("ref 解析：3~12 位字母或数字才合法，其余一律空串（绝不抛错）", () => {
+  const valid = [
+    ["368", "368"],
+    [" 368 ", "368"],        // 前后空白容忍（argv 里偶尔带）
+    ["0368", "0368"],        // 保留前导零：码是字符串不是数字
+    ["123456789012", "123456789012"], // 12 位上限
+    ["bili", "bili"],        // ★字母短词（更隐蔽，业主 2026-10 口径）
+    ["BILI", "bili"],        // 大小写不敏感 → 归一化小写
+    [" Bili ", "bili"],
+    ["xhs8", "xhs8"],
+    [368, "368"],            // 配置被手改成数字也能救回来
+  ];
+  for (const [input, want] of valid) {
+    assert.equal(normalizeRefCode(input), want, `合法值 ${JSON.stringify(input)} 应归一化为 ${want}`);
+  }
+  const invalid = ["12", "a", "ab", "1234567890123", "36 8", "36-8", "-368", "3.68", "", "   ", null, undefined, {}, [], 12, 3.68, -368];
+  for (const input of invalid) {
+    assert.equal(normalizeRefCode(input), "", `非法值 ${JSON.stringify(input)} 必须是空串（调用方据此省略字段）`);
+  }
+});
+
+test("ref 解析优先级：命令行 --ref 优先；非法/缺值的命令行不悄悄回落环境变量", () => {
+  assert.equal(resolveRefCode(["--ref", "368"]), "368");
+  assert.equal(resolveRefCode(["--ref", "368"], { DSH_REF: "999" }), "368", "命令行优先于 DSH_REF");
+  assert.equal(resolveRefCode([], { DSH_REF: "456" }), "456", "命令行没给时用 DSH_REF");
+  assert.equal(resolveRefCode([], { DSH_REF: "x" }), "", "环境变量非法 → 忽略");
+  assert.equal(resolveRefCode(["--ref", "x"], { DSH_REF: "456" }), "", "命令行给了非法值 → 忽略，不回落到环境变量（避免来路不明的归因）");
+  assert.equal(resolveRefCode(["--ref"], { DSH_REF: "456" }), "", "--ref 后面没值 → 忽略");
+  assert.equal(resolveRefCode([], {}), "");
+  assert.equal(resolveRefCode(undefined, undefined), "", "参数异常也不得抛错");
+});
+
+test("配置合并：本次没带/非法 ref 时保留旧值（升级清空 = 归因永久丢失）", () => {
+  const old = { ref_code: "111", phone: "13800000000" };
+  assert.deepEqual(
+    applyRefCodeToConfig(old, []).ref_code,
+    "111",
+    "★升级（不带 --ref）必须保留配置里已有的 ref_code"
+  );
+  assert.equal(applyRefCodeToConfig(old, ["--ref", "x"]).ref_code, "111", "非法值不得覆盖旧值");
+  assert.equal(applyRefCodeToConfig(old, ["--ref", "368"]).ref_code, "368", "带合法 --ref → 覆盖");
+  assert.equal(applyRefCodeToConfig({}, ["--ref", "368"]).ref_code, "368", "首次安装 → 写入");
+  assert.ok(!("ref_code" in applyRefCodeToConfig({}, [])), "没有就没有：绝不写空串占位");
+  assert.equal(old.ref_code, "111", "不得原地改传入对象（调用方后面还要整份写回）");
+});
+
+// ───────────────────────── B. bridge：真的往 /api/devices 发什么 ─────────────────────────
+
+/** 起一个 127.0.0.1 假账号 API + 假 tunnel，拉真 bridge 进程，等它完成设备登记后交给断言。 */
+async function withBridge(configFile, fn) {
+  const seen = { devices: null };
+  const api = http.createServer((req, res) => {
+    let raw = "";
+    req.on("data", (c) => { raw += c; });
+    req.on("end", () => {
+      if (req.url === "/api/device-login") {
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({ token: "token-1" }));
+        return;
+      }
+      if (req.url === "/api/devices") {
+        try { seen.devices = JSON.parse(raw); } catch { seen.devices = { parseError: raw }; }
+        res.writeHead(201, { "content-type": "application/json" });
+        res.end(JSON.stringify({ device: { id: "dev-000000000009" } }));
+        return;
+      }
+      res.writeHead(404, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: "not found" }));
+    });
+  });
+  await new Promise((resolve) => api.listen(0, "127.0.0.1", resolve));
+  const wss = new WebSocketServer({ host: "127.0.0.1", port: 0 });
+  await new Promise((resolve) => wss.once("listening", resolve));
+
+  const tempDir = await mkdtemp(path.join(os.tmpdir(), "dsh-channel-ref-"));
+  const configPath = path.join(tempDir, "config.json");
+  if (configFile) await writeFile(configPath, JSON.stringify(configFile));
+  const child = spawn(process.execPath, [BRIDGE], {
+    env: {
+      ...process.env,
+      DSH_BRIDGE_API: `http://127.0.0.1:${api.address().port}`,
+      DSH_BRIDGE_TUNNEL_URL: `ws://127.0.0.1:${wss.address().port}`,
+      DSH_BRIDGE_PHONE: "test-account",
+      DSH_BRIDGE_PASSWORD: "test-password",
+      DSH_BRIDGE_DEVICE_ID: "dev-000000000009",
+      DSH_BRIDGE_CONFIG: configPath,
+    },
+    stdio: "ignore",
+  });
+  try {
+    for (let i = 0; i < 60 && !seen.devices; i += 1) await delay(100, null, { ref: false });
+    assert.ok(seen.devices, "bridge 应在 6 秒内完成设备登记（POST /api/devices）");
+    return await fn(seen.devices);
+  } finally {
+    try { child.kill("SIGKILL"); } catch { /* 已退出 */ }
+    await new Promise((r) => wss.close(r));
+    await new Promise((r) => api.close(r));
+    await rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+test("bridge 设备登记：配置里有 ref_code → POST /api/devices 必须带 ref_code", async () => {
+  await withBridge({ ref_code: "368" }, (body) => {
+    assert.equal(body.ref_code, "368", "★安装器 --ref 写的 ref_code 必须随设备登记上报（否则服务端无法归因）");
+    assert.equal(body.device_id, "dev-000000000009", "既有字段照旧");
+    assert.ok(body.pub_key && body.machine_fp, "既有登记字段不得丢失");
+  });
+});
+
+test("bridge 设备登记：没有/非法 ref_code → 字段整个省略（不发空串、不发脏值）", async () => {
+  // ① 配置里没有 ref_code
+  await withBridge({}, (body) => {
+    assert.ok(!("ref_code" in body), "没有归因码时字段必须缺席（服务端字段可选）");
+  });
+  // ② 配置里是被手改坏的值
+  await withBridge({ ref_code: "not-a-code" }, (body) => {
+    assert.ok(!("ref_code" in body), "非法值不得原样上报");
+  });
+});
+
+// ───────────────────────── C. 安装器：磁盘上的 ref_code ─────────────────────────
+
+/** 假 SaaS API：只要 public-config（安装器会读），其余 404。 */
+async function startMockApi() {
+  const server = http.createServer((req, res) => {
+    if (req.url === "/api/public-config") {
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify({ app_url: "http://127.0.0.1/app/" }));
+      return;
+    }
+    res.writeHead(404, { "content-type": "application/json" });
+    res.end(JSON.stringify({ error: "not found" }));
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  return { server, base: `http://127.0.0.1:${server.address().port}` };
+}
+
+/** 隔离 HOME 跑安装器（--no-autostart/--no-plugin/--no-restart：不碰真实服务与 profile）。 */
+function runSetup({ relayDir, home, api, args = [], env = {} }) {
+  const childEnv = {
+    ...process.env,
+    HOME: home,
+    DSH_RELAY_DIR: relayDir,
+    DSH_PROFILE_DIR: path.join(home, "dsh-profile"),
+    DSH_RELAY_SKIP_SERVICE: "1",
+    DSH_RELAY_DEFAULT_API: api,
+    DSH_REMOTE_TELEMETRY: "0",
+    ...env,
+  };
+  // 开发机上的变量不得泄漏进来（否则「环境变量回退」用例结论不可信）
+  for (const k of ["DSH_BRIDGE_CONFIG"]) delete childEnv[k];
+  if (!("DSH_REF" in env)) delete childEnv.DSH_REF;
+  return new Promise((resolve) => {
+    execFile(
+      process.execPath,
+      [SETUP, "--api", api, "--no-autostart", "--no-plugin", "--no-restart", ...args],
+      { env: childEnv, timeout: 60_000 },
+      (err, stdout, stderr) => resolve({ code: err ? err.code ?? 1 : 0, stdout: String(stdout || ""), stderr: String(stderr || "") })
+    );
+  });
+}
+
+async function readSetupConfig(relayDir) {
+  return JSON.parse(await readFile(path.join(relayDir, ".dsh-config.json"), "utf8"));
+}
+
+test("安装器：--ref 写入 ref_code；升级不带 --ref 必须保留；非法值忽略且安装照常成功", async () => {
+  const mock = await startMockApi();
+  const root = await mkdtemp(path.join(os.tmpdir(), "dsh-setup-ref-"));
+  try {
+    const home = path.join(root, "home");
+    await mkdir(home, { recursive: true });
+    const relayDir = path.join(root, ".dsh-remote");
+
+    // ① 首次安装：`npx @mrrisega/dsh-remote --ref 368`（同时给一个不同的 DSH_REF，锁「命令行优先」）
+    const first = await runSetup({ relayDir, home, api: mock.base, args: ["--ref", "368"], env: { DSH_REF: "999" } });
+    assert.equal(first.code, 0, `安装器应成功退出：${first.stderr}`);
+    const cfg1 = await readSetupConfig(relayDir);
+    assert.equal(cfg1.ref_code, "368", "★--ref 必须写进 .dsh-config.json 的 ref_code（命令行优先于 DSH_REF）");
+    assert.equal(typeof cfg1.ref_code, "string", "契约要求是字符串（不是数字）");
+
+    // ② 升级（重跑 setup，本次不带 --ref，环境里也没有 DSH_REF）→ 旧值必须原样保留
+    const second = await runSetup({ relayDir, home, api: mock.base });
+    assert.equal(second.code, 0, `升级也应成功退出：${second.stderr}`);
+    const cfg2 = await readSetupConfig(relayDir);
+    assert.equal(cfg2.ref_code, "368", "★升级时没带 --ref 不得清空已写入的 ref_code（saveConfig 是整对象覆盖）");
+
+    // ③ 全新目录 + 非法 --ref：静默忽略，但安装必须照常成功（主链路优先）
+    const home2 = path.join(root, "home2");
+    await mkdir(home2, { recursive: true });
+    const relayDir2 = path.join(root, ".dsh-remote-2");
+    const third = await runSetup({ relayDir: relayDir2, home: home2, api: mock.base, args: ["--ref", "x"] });
+    assert.equal(third.code, 0, `非法 --ref 绝不能导致安装失败：${third.stderr}`);
+    assert.match(third.stdout + third.stderr, /安装完成/, "安装器应走完正常流程并打印「安装完成」");
+    const cfg3 = await readSetupConfig(relayDir2);
+    assert.ok(!("ref_code" in cfg3), "非法值必须被静默丢弃（不写空串、不写脏值）");
+  } finally {
+    await new Promise((r) => mock.server.close(r));
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("安装器：命令行没给 --ref 时用环境变量 DSH_REF", async () => {
+  const mock = await startMockApi();
+  const root = await mkdtemp(path.join(os.tmpdir(), "dsh-setup-ref-env-"));
+  try {
+    const home = path.join(root, "home");
+    await mkdir(home, { recursive: true });
+    const relayDir = path.join(root, ".dsh-remote");
+    const r = await runSetup({ relayDir, home, api: mock.base, env: { DSH_REF: "456" } });
+    assert.equal(r.code, 0, `安装器应成功退出：${r.stderr}`);
+    assert.equal((await readSetupConfig(relayDir)).ref_code, "456", "DSH_REF 应作为 --ref 的回退写入配置");
+  } finally {
+    await new Promise((r2) => mock.server.close(r2));
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/clients/dsh-remote/test/device-locked.test.mjs

@@ -0,0 +1,271 @@
+// 设备超额锁定 —— bridge 侧行为回归（契约 docs/device-overquota-lock-contract.md §6）。
+//
+// 【为什么必须有】旧实现收到「设备不可用」只做两件事之一：
+//   · 旧版 409 device_limit_exceeded → persistBindError + process.exit(1)；
+//   · router tunnel-register-err → 写 state.last_error 然后**照常 2s 后重连**。
+// 两者都是"空转"：watcher 每 10s 重拉 / 隧道每 2s 重撞，用户看到的是「设备列表里明明有这台电脑，
+// 但手机永远连不上」，日志还被刷屏。本用例走真实 bridge 进程 + 假账号 API + 假 router，
+// 逐条钉住新契约：
+//   ① 锁定态**不退出进程**、写 phase=locked 详情、不重连隧道（只 30s 轮询 GET /api/devices）；
+//   ② 解锁（locked=false）→ 立即重连；设备行不存在（手机端解绑）→ 先登记再连；
+//   ③ 旧版 409 device_limit_exceeded 同样转等待（向后兼容，不再 exit(1)）；
+//   ④ device_bind_cap → 专用退出码 5 + .bind-error.json 带 device_id 等详情（watcher 据此指数退避）。
+//
+// ⚠️ 只连 127.0.0.1（test:bridge 带 test-net-guard）；轮询间隔用 DSH_BRIDGE_LOCK_POLL_MS 压到亚秒级。
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import http from "node:http";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { setTimeout as delay } from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+import { WebSocketServer } from "ws";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const BRIDGE = path.join(HERE, "..", "dsh-bridge.mjs");
+const DEVICE_ID = "dev-000000000001";
+const LOCK_POLL_MS = "80";
+
+const sleep = (ms) => delay(ms, null, { ref: false });
+async function waitFor(fn, { timeout = 5000, step = 40, label = "" } = {}) {
+  const deadline = Date.now() + timeout;
+  for (;;) {
+    if (await fn()) return true;
+    if (Date.now() > deadline) throw new Error(`等待超时${label ? `（${label}）` : ""}`);
+    await sleep(step);
+  }
+}
+function jsonOf(file) {
+  try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; }
+}
+
+/**
+ * 起一个假账号 API + 假 router；`scenario` 决定 register/getDevices/ws 的剧本。
+ * @returns {Promise<{child, api, wss, port, stateFile, bindErrorFile, counts, close}>}
+ */
+async function launch(scenario) {
+  const counts = { register: 0, get: 0, login: 0, ws: 0 };
+  const registrations = [];
+  const api = http.createServer((req, res) => {
+    const send = (status, body) => {
+      res.writeHead(status, { "content-type": "application/json" });
+      res.end(JSON.stringify(body));
+    };
+    if (req.url === "/api/device-login") {
+      counts.login += 1;
+      return send(200, { token: `tok-${counts.login}` });
+    }
+    if (req.url === "/api/devices" && req.method === "POST") {
+      counts.register += 1;
+      return send(...scenario.onRegister(counts.register, req));
+    }
+    if (req.url === "/api/devices" && req.method === "GET") {
+      counts.get += 1;
+      return send(...scenario.onGetDevices(counts.get, req));
+    }
+    return send(404, { error: { code: "not_found", message: "not found" } });
+  });
+  await new Promise((resolve) => api.listen(0, "127.0.0.1", resolve));
+
+  const wss = new WebSocketServer({ host: "127.0.0.1", port: 0 });
+  await new Promise((resolve) => wss.once("listening", resolve));
+  wss.on("connection", (ws) => {
+    counts.ws += 1;
+    ws.once("message", (raw) => {
+      try { registrations.push(JSON.parse(raw.toString())); } catch { registrations.push({ raw: String(raw) }); }
+      scenario.onRegisterWs(ws, registrations.length);
+    });
+  });
+
+  const tempDir = await mkdtemp(path.join(os.tmpdir(), "dsh-device-locked-"));
+  const configFile = path.join(tempDir, "config.json");
+  await writeFile(configFile, "{}");
+  const child = spawn(process.execPath, [BRIDGE], {
+    env: {
+      ...process.env,
+      DSH_BRIDGE_API: `http://127.0.0.1:${api.address().port}`,
+      DSH_BRIDGE_TUNNEL_URL: `ws://127.0.0.1:${wss.address().port}`,
+      DSH_BRIDGE_UPSTREAM: "http://127.0.0.1:1", // 不做端口发现：本用例只测锁定逻辑
+      DSH_BRIDGE_PHONE: "test-account",
+      DSH_BRIDGE_PASSWORD: "test-password",
+      DSH_BRIDGE_DEVICE_ID: DEVICE_ID,
+      DSH_BRIDGE_CONFIG: configFile,
+      DSH_BRIDGE_LOCK_POLL_MS: LOCK_POLL_MS,
+      DSH_WECHAT: "0", // 微信通道与本用例无关，别让它发起额外的网络请求
+      DSH_REMOTE_TELEMETRY: "0",
+    },
+    stdio: ["ignore", "ignore", "pipe"]
+  });
+  let stderr = "";
+  child.stderr.on("data", (c) => { stderr += String(c); });
+
+  const relayDir = path.dirname(configFile);
+  return {
+    child,
+    api,
+    wss,
+    counts,
+    registrations,
+    stderrText: () => stderr,
+    stateFile: path.join(relayDir, ".dsh-bridge-state.json"),
+    bindErrorFile: path.join(relayDir, ".bind-error.json"),
+    async close() {
+      try { child.kill("SIGKILL"); } catch { /* 已退出 */ }
+      await new Promise((r) => wss.close(r));
+      await new Promise((r) => api.close(r));
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  };
+}
+
+/** 201 响应体（契约 §4.2 形状）：device + locked + policy。 */
+const okRegister = () => [201, {
+  device: { id: DEVICE_ID },
+  locked: false,
+  policy: { plan: "free", limit: 1, online: 1, unlock_monthly: 3, registered: 1, locked_count: 0, upgrade_to: "pro_max", lock_enabled: true }
+}];
+const lockedFrame = {
+  type: "tunnel-register-err",
+  code: "device_locked",
+  message: "已超出当前套餐设备额度，升级 Pro Max 可多台设备同时使用",
+  plan: "free",
+  limit: 1,
+  upgrade_to: "pro_max"
+};
+const okFrame = { type: "tunnel-register-ok", caps: [] };
+
+test("锁定态：不退出、写 phase=locked 详情、期间不重连；解锁后自动重连", async () => {
+  const ctx = await launch({
+    // 第一次隧道注册 → 被 router 以 device_locked 拒绝；之后才允许成功
+    onRegisterWs(ws, n) {
+      if (n === 1) ws.send(JSON.stringify(lockedFrame));
+      else ws.send(JSON.stringify(okFrame));
+    },
+    onRegister: () => okRegister(),
+    // 前两拍仍锁定（验证"等待期间不重连"），第三拍起解锁
+    onGetDevices(getCount) {
+      return [200, {
+        devices: [{ id: DEVICE_ID, device_name: "test-host", locked: getCount < 3 }],
+        policy: { plan: "free", limit: 1, registered: 2, locked_count: getCount < 3 ? 1 : 0, upgrade_to: "pro_max", lock_enabled: true }
+      }];
+    }
+  });
+  try {
+    // ① 锁定态：进程活着 + 状态文件 phase=locked + locked 详情（面板据此显示升级引导）
+    await waitFor(() => {
+      const st = jsonOf(ctx.stateFile);
+      return st && st.phase === "locked" && st.locked && st.locked.limit === 1;
+    }, { label: "phase=locked" });
+    assert.equal(ctx.child.exitCode, null, "锁定态**不得退出进程**（旧实现 exit(1) 是空转）");
+    const st = jsonOf(ctx.stateFile);
+    assert.equal(st.locked.plan, "free");
+    assert.equal(st.locked.upgrade_to, "pro_max");
+    assert.match(String(st.locked.message), /额度/);
+    assert.equal(st.last_error, null, "锁定不是「注册错误」，last_error 必须清空");
+
+    // ② .bind-error.json 富化（契约 §6.3/§8.4）：带 device_id/plan/limit/upgrade_to
+    await waitFor(() => existsSync(ctx.bindErrorFile), { label: "bind-error" });
+    const be = jsonOf(ctx.bindErrorFile);
+    assert.equal(be.code, "device_locked");
+    assert.equal(be.device_id, DEVICE_ID);
+    assert.equal(be.plan, "free");
+    assert.equal(be.limit, 1);
+    assert.equal(be.upgrade_to, "pro_max");
+
+    // ③ 等待期间**不重连隧道**（只轮询 /api/devices；轮询带 Bearer token）
+    await waitFor(() => ctx.counts.get >= 2, { label: "poll >= 2" });
+    assert.equal(ctx.registrations.length, 1, "锁定等待期间不得重连隧道（否则每 2s 白撞一次 router）");
+    assert.equal(ctx.child.exitCode, null, "等待期间进程必须活着");
+
+    // ④ 解锁 → 自动重连（第二次 WS 注册）
+    await waitFor(() => ctx.registrations.length === 2, { label: "解锁后重连" });
+    assert.equal(ctx.registrations[0].deviceId, DEVICE_ID);
+    await waitFor(() => {
+      const cur = jsonOf(ctx.stateFile);
+      return cur && cur.phase === "online";
+    }, { label: "重连后 phase=online" });
+    assert.equal(existsSync(ctx.bindErrorFile), false, "解锁重连成功后应清掉 .bind-error.json");
+  } finally {
+    await ctx.close();
+  }
+});
+
+test("等待期间设备行被解绑（列表里没有本机）→ 先重新登记再重连", async () => {
+  const ctx = await launch({
+    onRegisterWs(ws, n) {
+      if (n === 1) ws.send(JSON.stringify(lockedFrame));
+      else ws.send(JSON.stringify(okFrame));
+    },
+    onRegister: () => okRegister(),
+    onGetDevices() {
+      // 手机端把本机解绑了：列表里没有本机 → bridge 必须 registerDeviceInAccount 后重连
+      return [200, { devices: [], policy: { plan: "free", limit: 1, registered: 0, locked_count: 0, upgrade_to: "pro_max", lock_enabled: true } }];
+    }
+  });
+  try {
+    await waitFor(() => {
+      const st = jsonOf(ctx.stateFile);
+      return st && st.phase === "locked";
+    }, { label: "phase=locked" });
+    await waitFor(() => ctx.counts.register >= 2, { label: "重新登记" });
+    await waitFor(() => ctx.registrations.length === 2, { label: "重连" });
+    assert.equal(ctx.child.exitCode, null);
+  } finally {
+    await ctx.close();
+  }
+});
+
+test("旧版服务端 409 device_limit_exceeded：不再 exit(1) 空转，改为轮询等待后重连", async () => {
+  const ctx = await launch({
+    onRegisterWs(ws) { ws.send(JSON.stringify(okFrame)); },
+    // 旧服务端：按套餐额度拒绝登记（新契约下已改为「可超绑 + 锁定」，这里验证向后兼容）
+    onRegister() {
+      return [409, { error: { code: "device_limit_exceeded", message: "当前套餐最多绑定 1 台设备，请先解绑旧设备" } }];
+    },
+    // 解绑后本机变为可用
+    onGetDevices() {
+      return [200, { devices: [{ id: DEVICE_ID, locked: false }], policy: { plan: "free", limit: 1, registered: 1, locked_count: 0, upgrade_to: "pro_max", lock_enabled: true } }];
+    }
+  });
+  try {
+    await waitFor(() => {
+      const st = jsonOf(ctx.stateFile);
+      return st && st.phase === "locked";
+    }, { label: "旧 409 → phase=locked" });
+    assert.equal(ctx.child.exitCode, null, "旧版 409 必须转为等待，不得 exit(1)");
+    // 旧服务端不返回 limit：从文案「最多绑定 1 台」里尽力解析（面板文案要能说 N 台）
+    const st = jsonOf(ctx.stateFile);
+    assert.equal(st.locked.limit, 1, "应从旧版文案解析出额度，避免面板显示「N 台」占位");
+    await waitFor(() => ctx.registrations.length === 1, { label: "解锁后首次连隧道" });
+    assert.equal(ctx.child.exitCode, null);
+  } finally {
+    await ctx.close();
+  }
+});
+
+test("device_bind_cap：写 .bind-error.json + 专用退出码 5（watcher 据此指数退避）", async () => {
+  const ctx = await launch({
+    onRegisterWs() { /* 不应连上：登记就失败了 */ },
+    onRegister() {
+      return [409, { error: { code: "device_bind_cap", message: "已绑定设备数已达上限(50 台)，请先在手机端「管理电脑」解绑" } }];
+    },
+    onGetDevices() { return [200, { devices: [] }]; }
+  });
+  try {
+    const code = await new Promise((resolve) => {
+      const timer = setTimeout(() => resolve("timeout"), 8000);
+      ctx.child.once("exit", (c) => { clearTimeout(timer); resolve(c); });
+    });
+    assert.equal(code, 5, "device_bind_cap 必须用专用退出码 5 退出（不能与瞬时失败共用 exit 1）");
+    const be = jsonOf(ctx.bindErrorFile);
+    assert.ok(be, "必须写 .bind-error.json 供面板展示");
+    assert.equal(be.code, "device_bind_cap");
+    assert.equal(be.device_id, DEVICE_ID, "详情里的 device_id 不能丢（P0：面板/诊断靠它定位）");
+    assert.equal(ctx.counts.ws, 0, "登记失败时不该去连隧道");
+  } finally {
+    await ctx.close();
+  }
+});