mslxdff 0.1.173 → 0.1.175

package/src/warp-pool/config.js

@@ -0,0 +1,71 @@
+// warp-pool · 配置解析：env 优先，缺省值集中在一处；纯函数，便于单测。
+import { join } from "node:path";
+import { logDir } from "../logs.js";
+
+/** 缺省即开：组长升级/重启后无需改任何环境变量即可生效；不想用的节点设 MSLXDFF_WARP_POOL=0。 */
+export const DEFAULTS = {
+  enabled: true,
+  mode: "leader",
+  count: 4,
+  basePort: 10800,
+  strategy: "session",
+  cooldownMs: 600_000,
+  autodownload: true,
+  registerMinGapMs: 6_000,
+  registerMaxGapMs: 15_000,
+  probePath: "/zen/v1/models",
+};
+
+const OFF = ["0", "off", "false", "no", "disable", "disabled"];
+
+function envBool(env, name, fallback) {
+  const raw = env[name];
+  if (raw === undefined || raw === null || raw === "") return fallback;
+  return !OFF.includes(String(raw).trim().toLowerCase());
+}
+
+function envInt(env, name, fallback) {
+  const v = Number(env[name]);
+  return Number.isInteger(v) && v > 0 ? v : fallback;
+}
+
+function envStr(env, name, fallback) {
+  const raw = env[name];
+  return typeof raw === "string" && raw.trim() ? raw.trim() : fallback;
+}
+
+/**
+ * 解析 warp-pool 运行时配置。
+ * @param {Record<string,string|undefined>} env
+ * @param {{ logDirFn?: () => string }} [deps] 测试可注入 logDir
+ */
+export function resolveWarpConfig(env = process.env, { logDirFn = logDir } = {}) {
+  const enabled = envBool(env, "MSLXDFF_WARP_POOL", DEFAULTS.enabled);
+  const mode = envStr(env, "MSLXDFF_WARP_MODE", DEFAULTS.mode);
+  const count = envInt(env, "MSLXDFF_WARP_COUNT", DEFAULTS.count);
+  const basePort = envInt(env, "MSLXDFF_WARP_BASE_PORT", DEFAULTS.basePort);
+  const strategy = envStr(env, "MSLXDFF_WARP_STRATEGY", DEFAULTS.strategy) === "request" ? "request" : "session";
+  const cooldownMs = envInt(env, "MSLXDFF_WARP_COOLDOWN_MS", DEFAULTS.cooldownMs);
+  const dir = envStr(env, "MSLXDFF_WARP_DIR", join(logDirFn(), "warp-pool"));
+  const bin = envStr(env, "MSLXDFF_WARP_BIN", "");
+  const autodownload = envBool(env, "MSLXDFF_WARP_AUTODOWNLOAD", DEFAULTS.autodownload);
+  const probePath = envStr(env, "MSLXDFF_WARP_PROBE_PATH", DEFAULTS.probePath);
+
+  return {
+    enabled,
+    active: enabled && mode === "leader",
+    mode,
+    count,
+    basePort,
+    strategy,
+    cooldownMs,
+    dir,
+    bin,
+    autodownload,
+    probePath,
+    registerMinGapMs: DEFAULTS.registerMinGapMs,
+    registerMaxGapMs: DEFAULTS.registerMaxGapMs,
+    /** 节点端口列表：basePort .. basePort+count-1 */
+    ports: Array.from({ length: count }, (_, i) => basePort + i),
+  };
+}

package/src/warp-pool/health.js

@@ -0,0 +1,65 @@
+// warp-pool · 节点健康：主动探活（经隧道打上游 models，不烧 token）+ 失败冷却 + 连续失败触发重拨换 IP。
+import { probeTunnel } from "./wireproxy.js";
+
+export function createHealthMonitor({
+  dispatcher,
+  baseUrl = "https://opencode.ai",
+  probePath = "/zen/v1/models",
+  unhealthyAfter = 3,
+  intervalMs = 60_000,
+  onExhausted = null,
+  probe = probeTunnel,
+  headers = {},
+  log = () => {},
+} = {}) {
+  let timer = null;
+  let rounds = 0;
+
+  /** 跑一轮全池探活。返回 { checked, healthy }。 */
+  async function tick() {
+    if (!dispatcher) return { checked: 0, healthy: 0 };
+    const list = dispatcher.entries();
+    let healthy = 0;
+    for (const e of list) {
+      const r = await probe({ port: e.port, baseUrl, path: probePath, headers }).catch((err) => ({
+        ok: false,
+        error: String(err?.message || err),
+      }));
+      if (r.ok) {
+        dispatcher.markOk(e.index);
+        healthy += 1;
+      } else {
+        dispatcher.markFailure(e.index);
+      }
+    }
+    if (list.length > 0 && healthy === 0) {
+      rounds += 1;
+      log(`[warp-pool] 全池 ${list.length} 个节点均不可用（连续第 ${rounds} 轮）`);
+      if (rounds >= 2 && typeof onExhausted === "function") {
+        rounds = 0;
+        await onExhausted().catch((e) => log(`[warp-pool] 重拨失败：${String(e?.message || e)}`));
+      }
+    } else {
+      rounds = 0;
+    }
+    return { checked: list.length, healthy };
+  }
+
+  return {
+    tick,
+    start() {
+      if (timer || !(intervalMs > 0)) return;
+      timer = setInterval(() => {
+        tick().catch(() => {});
+      }, intervalMs);
+      if (typeof timer.unref === "function") timer.unref();
+    },
+    stop() {
+      if (timer) clearInterval(timer);
+      timer = null;
+    },
+    get running() {
+      return !!timer;
+    },
+  };
+}

package/src/warp-pool/index.js

@@ -0,0 +1,252 @@
+// warp-pool · 装配入口。
+//
+// 定位（见 MODULES.md §0）：WARP 池是**增量**出口，不是替代成员自身出口；
+// 开关缺省即开（MSLXDFF_WARP_POOL 缺省 1；设 0 则零副作用）；只有组长（MSLXDFF_WARP_MODE=leader）才真建池。
+//
+// 关键约束：bootstrap（注册设备 + 起隧道）很慢（注册有 6–15s 间隔、可能退避 60–120s），
+// 因此**绝不阻塞 daemon 启动**——createWarpPool 同步返回，dispatcher 先是空池（直连兜底），
+// bootstrap 完成后 setNodes() 换上真实出口。
+import { resolveWarpConfig } from "./config.js";
+import { createRotatingDispatcher } from "./rotate.js";
+import { createHealthMonitor } from "./health.js";
+import { ensureDir, loadNodes, removeNode, saveNode } from "./nodes.js";
+import { registerWarpDevice } from "./register.js";
+import { ensureBinary, resolveAsset, startTunnel, writeTunnelConf } from "./wireproxy.js";
+/** 重拨节流：连续失败指数退避。缺省开之后，网络不通的机器绝不能让重注册把 CF 刷到 429。 */
+const REDIAL_MIN_GAP_MS = 5 * 60_000;
+const REDIAL_MAX_GAP_MS = 30 * 60_000;
+
+/** 注册间隔（同类项目实测：密集注册会让设备落同一网段，且触发 CF 429）。 */
+function gapMs(cfg, rnd = Math.random) {
+  const span = Math.max(0, cfg.registerMaxGapMs - cfg.registerMinGapMs);
+  return Math.round(cfg.registerMinGapMs + rnd() * span);
+}
+
+
+/**
+ * 建池。开关缺省即开，故「未启用」= 显式 MSLXDFF_WARP_POOL=0 或 非 leader；那时返回 null，调用方据此不注入。
+ * @returns {null | { dispatcher: object, ready: Promise<void>, close: () => Promise<void>, stats: () => object }}
+ */
+export function createWarpPool({
+  env = process.env,
+  baseUrl = "https://opencode.ai",
+  log = (m) => console.error(m),
+  register = registerWarpDevice,
+  ensureBin = ensureBinary,
+  start = startTunnel,
+  now = Date.now,
+  rnd = Math.random,
+  wait = (ms) => new Promise((r) => setTimeout(r, ms)),
+} = {}) {
+  const cfg = resolveWarpConfig(env);
+  if (!cfg.active) return null;
+
+  const dispatcher = createRotatingDispatcher({ nodes: [], strategy: cfg.strategy, cooldownMs: cfg.cooldownMs, log });
+  /** @type {Map<number, {stop: () => void}>} */
+  const tunnels = new Map();
+  let binPath = "";
+  let closed = false;
+  let lastRedialAt = 0;
+  let redialGapMs = REDIAL_MIN_GAP_MS;
+
+  // 兜底清理：Node 退出不会回收 spawn 的子进程，daemon 突然退出时同步杀掉隧道。
+  process.once("exit", () => {
+    for (const t of tunnels.values()) {
+      try {
+        t.stop();
+      } catch {}
+    }
+  });
+
+  async function bringUp(node) {
+    writeTunnelConf(cfg.dir, node);
+    if (tunnels.has(node.port)) return;
+    const t = start({
+      binPath,
+      dir: cfg.dir,
+      port: node.port,
+      log,
+      onExit: ({ port, code }) => {
+        tunnels.delete(port);
+        log(`[warp-pool] 隧道 :${port} 退出（code=${code}）`);
+      },
+    });
+    tunnels.set(node.port, t);
+  }
+
+  async function bootstrap() {
+    if (closed) return;
+    ensureDir(cfg.dir);
+    try {
+      binPath = await ensureBin({ dir: cfg.dir, bin: cfg.bin, autodownload: cfg.autodownload, log });
+    } catch (e) {
+      const why = !cfg.bin && !resolveAsset()
+        ? `本平台（${process.platform}-${process.arch}）无预编译 wireproxy，如需启用请设 MSLXDFF_WARP_BIN`
+        : String(e?.message || e);
+      log(`[warp-pool] 出口池跳过：${why}`);
+      return;
+    }
+    if (closed) return;
+
+    // 1. 复用磁盘上已注册的节点
+    let nodes = loadNodes(cfg.dir, cfg.ports);
+    log(`[warp-pool] 已有节点 ${nodes.length}/${cfg.count}`);
+
+    // 2. 补足：逐个注册（拉长间隔，避免 CF 注册限流与同网段撞车）
+    const used = new Set(nodes.map((n) => n.port));
+    const free = cfg.ports.filter((p) => !used.has(p));
+    for (const port of free) {
+      if (closed) return;
+      if (nodes.length >= cfg.count) break;
+      try {
+        if (nodes.length > 0) await wait(gapMs(cfg, rnd));
+        const reg = await register({ log });
+        const node = {
+          port,
+          id: reg.id,
+          token: reg.token,
+          v4: reg.v4,
+          v6: reg.v6,
+          endpoint: reg.endpoint,
+          peerKey: reg.peerKey,
+          privateKey: reg.privateKey,
+          registeredAt: new Date(now()).toISOString(),
+        };
+        saveNode(cfg.dir, node);
+        nodes.push(node);
+        log(`[warp-pool] 注册节点 :${port}（v6=${reg.v6}）`);
+      } catch (e) {
+        log(`[warp-pool] 注册节点 :${port} 失败：${String(e?.message || e)}`);
+      }
+    }
+
+    // 3. 起隧道
+    for (const n of nodes) {
+      try {
+        await bringUp(n);
+      } catch (e) {
+        log(`[warp-pool] 起隧道 :${n.port} 失败：${String(e?.message || e)}`);
+      }
+    }
+
+    // 4. 换上真实出口（失败/退出中的节点仍会被 health 摘除）
+    const live = nodes.filter((n) => tunnels.has(n.port));
+    if (live.length) {
+      await dispatcher.setNodes(live.map((n) => ({ port: n.port, uri: `http://127.0.0.1:${n.port}` })));
+      log(`[warp-pool] 出口池就绪：${live.length} 个节点`);
+    } else {
+      log("[warp-pool] 无可用节点，保持直连");
+    }
+  }
+
+  const monitor = createHealthMonitor({
+    dispatcher,
+    baseUrl,
+    probePath: cfg.probePath,
+    log,
+    onExhausted: async () => {
+      // 重拨 = 重新注册 = 换新出口 IP（代价与限流见 MODULES.md）。
+      // 隧道全活却探活全挂 ⇒ 网络路径问题（实测墙内到 CF 的 UDP 被选择性屏蔽），
+      // 重注册换不来出路，只会把 CF 注册接口刷到 429 拉黑——故必须过 redialPlan 这道门。
+      const plan = redialPlan({ ports: cfg.ports, alivePorts: [...tunnels.keys()], lastRedialAt, redialGapMs, now });
+      if (plan.reason === "all-alive") {
+        log("[warp-pool] 隧道均存活但全池不通，判定为网络路径问题，跳过重拨");
+        return;
+      }
+      if (plan.reason === "throttled") {
+        log(`[warp-pool] 距上次重拨不足 ${Math.round(redialGapMs / 1000)}s，跳过本轮`);
+        return;
+      }
+      const dead = plan.dead;
+      lastRedialAt = now();
+      redialGapMs = Math.min(redialGapMs * 2, REDIAL_MAX_GAP_MS);
+      log(`[warp-pool] ${dead.length} 条隧道已死，重拨（下次最短间隔 ${Math.round(redialGapMs / 1000)}s）`);
+      for (const port of dead) {
+        if (closed) return;
+        try {
+          tunnels.get(port)?.stop();
+          tunnels.delete(port);
+          removeNode(cfg.dir, port);
+          const reg = await register({ log });
+          saveNode(cfg.dir, {
+            port,
+            id: reg.id,
+            token: reg.token,
+            v4: reg.v4,
+            v6: reg.v6,
+            endpoint: reg.endpoint,
+            peerKey: reg.peerKey,
+            privateKey: reg.privateKey,
+            registeredAt: new Date(now()).toISOString(),
+          });
+          await bringUp({ port, ...reg });
+        } catch (e) {
+          log(`[warp-pool] 重拨 :${port} 失败：${String(e?.message || e)}`);
+        }
+        await wait(gapMs(cfg, rnd));
+      }
+      if (!closed && [...tunnels.keys()].length) {
+        // 重拨确实把隧道拉起来了 ⇒ 退避复位，别让一次网络抖动永久拖慢恢复。
+        redialGapMs = REDIAL_MIN_GAP_MS;
+        await dispatcher.setNodes([...tunnels.keys()].map((port) => ({ port, uri: `http://127.0.0.1:${port}` })));
+      }
+    },
+  });
+
+  const ready = bootstrap()
+    .then(() => {
+      if (!closed) monitor.start();
+    })
+    .catch((e) => log(`[warp-pool] bootstrap 失败：${String(e?.message || e)}`));
+
+  return {
+    dispatcher,
+    ready,
+    config: cfg,
+    async close() {
+      if (closed) return;
+      closed = true;
+      monitor.stop();
+      for (const t of tunnels.values()) {
+        try {
+          t.stop();
+        } catch {}
+      }
+      tunnels.clear();
+      await dispatcher.close();
+    },
+    stats() {
+      return {
+        enabled: true,
+        mode: cfg.mode,
+        strategy: cfg.strategy,
+        dir: cfg.dir,
+        tunnels: tunnels.size,
+        nodes: dispatcher.stats(),
+      };
+    },
+  };
+}
+
+
+/**
+ * 只取轮换 dispatcher 的便捷入口（隧道进程由模块内的 process exit 钩子兜底清理）。
+ * 未启用（开关关 / 非 leader）时返回 undefined —— 调用方直接透传即是"关闭态"。
+ */
+export function createWarpDispatcher(opts) {
+  return createWarpPool(opts)?.dispatcher;
+}
+
+/**
+ * 重拨门（纯函数，便于单测）：只有「有隧道进程已死」且「距上次重拨超过当前退避间隔」才放行。
+ * 隧道全活却探活全挂 ⇒ 网络路径问题（实测：墙内到 CF 的 UDP 被选择性屏蔽），
+ * 此时重拨换不来出路，只会把 CF 注册接口刷到 429 拉黑。
+ * @returns {{ dead: number[], reason: "ok" | "all-alive" | "throttled" }}
+ */
+export function redialPlan({ ports = [], alivePorts = [], lastRedialAt = 0, redialGapMs = REDIAL_MIN_GAP_MS, now = Date.now } = {}) {
+  const alive = new Set(alivePorts);
+  const dead = ports.filter((p) => !alive.has(p));
+  if (!dead.length) return { dead, reason: "all-alive" };
+  if (now() - lastRedialAt < redialGapMs) return { dead, reason: "throttled" };
+  return { dead, reason: "ok" };
+}

package/src/warp-pool/keys.js

@@ -0,0 +1,29 @@
+// warp-pool · WireGuard 密钥（`wg genkey` / `wg pubkey` 的 Node 原生等价物）。
+// WireGuard 用 Curve25519(x25519)：密钥是 32 字节 raw，编码为 44 字符 base64。
+// Node 原生 generateKeyPairSync('x25519') 导出的 DER 末 32 字节即 raw key（本机实测通过）。
+import crypto from "node:crypto";
+
+const RAW_BYTES = 32;
+
+/** DER(SPKI/PKCS8) 的末 32 字节就是 Curve25519 raw key。 */
+function rawTail(der) {
+  const raw = der.subarray(-RAW_BYTES);
+  if (raw.length !== RAW_BYTES) throw new Error("x25519 密钥导出异常：DER 长度不足 32 字节");
+  return raw;
+}
+
+/**
+ * 生成一对 WireGuard 密钥（base64，44 字符）。
+ * 注册 WARP 设备时把 publicKey 填进请求体的 `key` 字段。
+ */
+export function generateWgKeyPair() {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync("x25519");
+  const privateKeyB64 = rawTail(privateKey.export({ type: "pkcs8", format: "der" })).toString("base64");
+  const publicKeyB64 = rawTail(publicKey.export({ type: "spki", format: "der" })).toString("base64");
+  return { privateKey: privateKeyB64, publicKey: publicKeyB64 };
+}
+
+/** WireGuard base64 密钥形状自检：恒 44 字符、以 '=' 收尾（Nothing-up-my-sleeve 检查用）。 */
+export function isWgKey(v) {
+  return typeof v === "string" && /^[A-Za-z0-9+/]{43}=$/.test(v);
+}

package/src/warp-pool/nodes.js

@@ -0,0 +1,94 @@
+// warp-pool · 节点元数据持久化。
+// 含 WireGuard 私钥文件与设备 token ⇒ 一律 0600，且只落在日志根（MSLXDFF_WARP_DIR），不进工作树。
+import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const SECRET_MODE = 0o600;
+
+/** 节点两件套：WireGuard 配置（含私钥）与元数据（含设备 token）。 */
+export function nodePaths(dir, port) {
+  return {
+    conf: join(dir, `node-${port}.conf`),
+    meta: join(dir, `node-${port}.json`),
+  };
+}
+
+/** 写敏感文件：新建用 0600，存量补 chmod（mode 只在新建时生效）。 */
+export function writeSecret(file, content) {
+  const existed = existsSync(file);
+  writeFileSync(file, content, existed ? undefined : { mode: SECRET_MODE });
+  try { chmodSync(file, SECRET_MODE); } catch {}
+  return file;
+}
+
+export function ensureDir(dir) {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+
+/** 读单个节点元数据；文件缺失/损坏返回 null，绝不抛。 */
+export function loadNode(dir, port) {
+  const { meta } = nodePaths(dir, port);
+  try {
+    const j = JSON.parse(readFileSync(meta, "utf8"));
+    if (!j || typeof j !== "object") return null;
+    return {
+      port,
+      id: String(j.id || ""),
+      token: String(j.token || ""),
+      v4: String(j.v4 || ""),
+      v6: String(j.v6 || ""),
+      endpoint: String(j.endpoint || ""),
+      peerKey: String(j.peerKey || ""),
+      registeredAt: String(j.registeredAt || ""),
+      ...(j.cooldownUntil ? { cooldownUntil: Number(j.cooldownUntil) } : {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function saveNode(dir, node) {
+  const { meta } = nodePaths(dir, node.port);
+  return writeSecret(meta, `${JSON.stringify(node, null, 2)}\n`);
+}
+
+export function removeNode(dir, port) {
+  const { conf, meta } = nodePaths(dir, port);
+  for (const f of [conf, meta]) {
+    try { if (existsSync(f)) unlinkSync(f); } catch {}
+  }
+}
+
+/** 读回配置目录里已注册的节点（按端口升序）。 */
+export function loadNodes(dir, ports) {
+  const out = [];
+  for (const p of ports) {
+    const n = loadNode(dir, p);
+    if (n && n.id && n.token) out.push(n);
+  }
+  return out;
+}
+
+/** WireGuard + wireproxy INI（[http] 段把隧道暴露成本地 HTTP 代理出口；undici v5 的 ProxyAgent 只吃 http/https）。 */
+export function renderWireproxyConf({ privateKey, v4, v6, endpoint, peerKey, port }) {
+  const addresses = [
+    v4 ? `Address = ${v4}/32` : "",
+    v6 ? `Address = ${v6}/128` : "",
+  ].filter(Boolean).join("\n");
+  return `[Interface]
+PrivateKey = ${privateKey}
+${addresses}
+DNS = 1.1.1.1
+MTU = 1280
+
+[Peer]
+PublicKey = ${peerKey}
+AllowedIPs = 0.0.0.0/0, ::/0
+Endpoint = ${endpoint}
+PersistentKeepalive = 25
+
+[http]
+BindAddress = 127.0.0.1:${port}
+`;
+}

package/src/warp-pool/register.js

@@ -0,0 +1,113 @@
+// warp-pool · 注册 Cloudflare WARP 设备（换回一份 WireGuard 配置 + 设备 token）。
+// API 形状与限流纪律来自同类项目实战（catoncat/warp-pool）+ 本机实测（200 响应字段已核对）。
+import crypto from "node:crypto";
+import { compatFetch } from "../compat.js";
+import { generateWgKeyPair } from "./keys.js";
+
+export const REG_URL = "https://api.cloudflareclient.com/v0a2483/reg";
+// 客户端版本头：Cloudflare 换版后旧值会被 403/400 拒（届时换成最新 app 版本号）。
+export const CF_CLIENT_VERSION = "a-6.81-2410032352.1";
+export const MAX_ATTEMPTS = 4;
+
+export function buildRegisterBody({ publicKey, uuid = crypto.randomUUID(), now = Date.now } = {}) {
+  return {
+    install_id: "",
+    tos: new Date(now()).toISOString().replace(/\.\d{3}Z$/, ".000Z"),
+    key: publicKey,
+    fcm_token: "",
+    serial_number: uuid,
+    type: "Android",
+    model: "PC",
+    locale: "zh_CN",
+  };
+}
+
+/** 从注册响应抽建隧道所需字段；缺 config/id/token 视为失败。 */
+export function parseRegisterResponse(json = {}) {
+  const cfg = json?.config;
+  const peer = Array.isArray(cfg?.peers) ? cfg.peers[0] : null;
+  const addr = cfg?.interface?.addresses || {};
+  if (!peer?.public_key || !addr.v4 || !json?.id || !json?.token) {
+    throw new Error("注册响应缺少必要字段（config.peers/interface.addresses/id/token）");
+  }
+  return {
+    id: String(json.id),
+    token: String(json.token),
+    v4: String(addr.v4),
+    v6: String(addr.v6 || ""),
+    peerKey: String(peer.public_key),
+    endpoint: String(peer?.endpoint?.host || "engage.cloudflareclient.com:2408"),
+  };
+}
+
+/**
+ * 退避：429/403 走长退避（短退避会被续封，同类项目 2026-08-18 事故记录），
+ * 其它错误（网络层）走短随机退避。
+ */
+export function backoffMs(status, attempt, rnd = Math.random) {
+  if (status === 429 || status === 403) return Math.round(60_000 + rnd() * 60_000);
+  return Math.round(12_000 * attempt + 5_000 + rnd() * 3_000);
+}
+
+/**
+ * 注册一个 WARP 设备。成功返回 { id, token, v4, v6, peerKey, endpoint, privateKey, publicKey }。
+ * @param {{ fetchImpl?: Function, keyPair?: {privateKey:string,publicKey:string}, uuid?: string,
+ *           now?: () => number, sleep?: (ms:number)=>Promise<void>, log?: (s:string)=>void,
+ *           maxAttempts?: number, timeoutMs?: number }} [opts]
+ */
+export async function registerWarpDevice({
+  fetchImpl = compatFetch,
+  keyPair = generateWgKeyPair(),
+  uuid = crypto.randomUUID(),
+  now = Date.now,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+  log = () => {},
+  maxAttempts = MAX_ATTEMPTS,
+  timeoutMs = 30_000,
+} = {}) {
+  const body = buildRegisterBody({ publicKey: keyPair.publicKey, uuid, now });
+  let lastStatus = 0;
+  let lastErr = null;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    if (attempt > 1) {
+      const wait = backoffMs(lastStatus, attempt);
+      log(`[warp-pool] 注册重试 ${attempt}/${maxAttempts}（上次 HTTP ${lastStatus || "网络错误"}），退避 ${Math.round(wait / 1000)}s`);
+      await sleep(wait);
+    }
+    let res;
+    try {
+      res = await fetchImpl(REG_URL, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "CF-Client-Version": CF_CLIENT_VERSION,
+          Accept: "application/json",
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+    } catch (e) {
+      lastStatus = 0;
+      lastErr = e;
+      continue;
+    }
+    lastStatus = res.status;
+    const text = await res.text().catch(() => "");
+    if (res.status !== 200) {
+      lastErr = new Error(`HTTP ${res.status}: ${String(text).slice(0, 200)}`);
+      continue;
+    }
+    let json;
+    try {
+      json = JSON.parse(text);
+    } catch (e) {
+      lastErr = e;
+      continue;
+    }
+    return { ...parseRegisterResponse(json), privateKey: keyPair.privateKey, publicKey: keyPair.publicKey };
+  }
+  throw new Error(
+    `WARP 注册失败（已试 ${maxAttempts} 次，最后 HTTP ${lastStatus || "网络错误"}）：${String(lastErr?.message || lastErr)}`,
+  );
+}