mslxdff 0.1.203 → 0.1.207

package/src/warp-pool/config.js

@@ -1,74 +1,74 @@
-// warp-pool · 配置解析：env 优先，缺省值集中在一处；纯函数，便于单测。
-import { join } from "node:path";
-import { logDir } from "../logs.js";
-
-/** 缺省开 + 429 时换身份换出口：他项目真机实测「同一身份连发 3 次 429，身份一换同一个请求立刻 200」⇒ 换身份＝换桶。 */
-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",
-  rotate: true,
-};
-
-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);
-  const rotate = envBool(env, "MSLXDFF_WARP_ROTATE", DEFAULTS.rotate);
-
-  return {
-    enabled,
-    active: enabled && mode === "leader",
-    mode,
-    count,
-    basePort,
-    strategy,
-    cooldownMs,
-    dir,
-    bin,
-    autodownload,
-    probePath,
-    rotate,
-    registerMinGapMs: DEFAULTS.registerMinGapMs,
-    registerMaxGapMs: DEFAULTS.registerMaxGapMs,
-    /** 节点端口列表：basePort .. basePort+count-1 */
-    ports: Array.from({ length: count }, (_, i) => basePort + i),
-  };
-}
+// warp-pool · 配置解析：env 优先，缺省值集中在一处；纯函数，便于单测。
+import { join } from "node:path";
+import { logDir } from "../logs.js";
+
+/** 缺省开 + 429 时换身份换出口：他项目真机实测「同一身份连发 3 次 429，身份一换同一个请求立刻 200」⇒ 换身份＝换桶。 */
+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",
+  rotate: true,
+};
+
+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);
+  const rotate = envBool(env, "MSLXDFF_WARP_ROTATE", DEFAULTS.rotate);
+
+  return {
+    enabled,
+    active: enabled && mode === "leader",
+    mode,
+    count,
+    basePort,
+    strategy,
+    cooldownMs,
+    dir,
+    bin,
+    autodownload,
+    probePath,
+    rotate,
+    registerMinGapMs: DEFAULTS.registerMinGapMs,
+    registerMaxGapMs: DEFAULTS.registerMaxGapMs,
+    /** 节点端口列表：basePort .. basePort+count-1 */
+    ports: Array.from({ length: count }, (_, i) => basePort + i),
+  };
+}

package/src/warp-pool/health.js

@@ -1,106 +1,106 @@
-// warp-pool · 节点健康：主动探活（经隧道打上游 models，不烧 token）+ 失败冷却 + 连续失败触发重拨换 IP。
-import { probeTunnel } from "./wireproxy.js";
-import { fmtHealth, fmtHeartbeat, dur, MARK } from "./report.js";
-
-export function createHealthMonitor({
-  dispatcher,
-  baseUrl = "https://opencode.ai",
-  probePath = "/zen/v1/models",
-  unhealthyAfter = 3,
-  intervalMs = 60_000,
-  heartbeatEvery = 10,
-  infoOf = null,
-  cooldownMs = 600_000,
-  onExhausted = null,
-  probe = probeTunnel,
-  headers = {},
-  now = Date.now,
-  log = () => {},
-} = {}) {
-  let timer = null;
-  let rounds = 0;
-  let ticks = 0;
-  let lastAllDownAt = "";
-  /** @type {Map<number, boolean>} 每端口上一轮通不通（用来只在「状态变化」时打日志） */
-  const lastOk = new Map();
-  const stamp = () => new Date(now()).toISOString().slice(11, 19);
-
-  /**
-   * 跑一轮全池探活。日志纪律：**只在「状态有变化」「全池不通」「心跳点」时打**——每分钟一行会把日志淹掉。
-   * 每个不通的节点都要报全：HTTP 状态、错误原文、耗时、连续第几次、冷却多久（这样才不用靠猜）。
-   */
-  async function tick() {
-    if (!dispatcher) return { checked: 0, healthy: 0 };
-    const list = dispatcher.entries();
-    let healthy = 0;
-    let slowestMs = 0;
-    const problems = [];
-    const changes = [];
-    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 (Number(r.ms) > slowestMs) slowestMs = Number(r.ms);
-      if (r.ok) {
-        dispatcher.markOk(e.index);
-        healthy += 1;
-        if (lastOk.get(e.port) === false) changes.push(`:${e.port} 恢复（HTTP ${r.status}，${dur(r.ms)}）`);
-        lastOk.set(e.port, true);
-        continue;
-      }
-      dispatcher.markFailure(e.index);
-      if (lastOk.get(e.port) !== false) {
-        changes.push(`:${e.port} 掉线（HTTP ${r.status || 0}${r.error ? ` ${String(r.error).slice(0, 80)}` : ""}）`);
-      }
-      lastOk.set(e.port, false);
-      problems.push({ port: e.port, status: r.status, error: r.error, ms: r.ms, fails: Number(e.fails || 0) + 1, cooldownMs });
-    }
-    const allDown = list.length > 0 && healthy === 0;
-    ticks += 1;
-    if (allDown) {
-      rounds += 1;
-      lastAllDownAt = stamp();
-    } else {
-      rounds = 0;
-    }
-    if (changes.length || allDown || ticks % heartbeatEvery === 0) {
-      log(fmtHealth({ healthy, total: list.length, slowestMs, problems }));
-    }
-    for (const c of changes) log(`[warp-pool] ${MARK.warn} 状态变化：${c}`);
-    if (ticks % heartbeatEvery === 0) {
-      const extra = typeof infoOf === "function" ? infoOf() || {} : {};
-      log(fmtHeartbeat({
-        alive: extra.alive ?? list.length,
-        total: list.length,
-        pooled: extra.pooled ?? list.length,
-        exits: extra.exits || [],
-        cooling: list.filter((e) => Number(e.cooldownUntil) > now()).length,
-        lastAllDown: lastAllDownAt,
-      }));
-    }
-    if (allDown && rounds >= 2 && typeof onExhausted === "function") {
-      rounds = 0;
-      await onExhausted().catch((e) => log(`[warp-pool] 重拨失败：${String(e?.message || e)}`));
-    }
-    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;
-    },
-  };
-}
+// warp-pool · 节点健康：主动探活（经隧道打上游 models，不烧 token）+ 失败冷却 + 连续失败触发重拨换 IP。
+import { probeTunnel } from "./wireproxy.js";
+import { fmtHealth, fmtHeartbeat, dur, MARK } from "./report.js";
+
+export function createHealthMonitor({
+  dispatcher,
+  baseUrl = "https://opencode.ai",
+  probePath = "/zen/v1/models",
+  unhealthyAfter = 3,
+  intervalMs = 60_000,
+  heartbeatEvery = 10,
+  infoOf = null,
+  cooldownMs = 600_000,
+  onExhausted = null,
+  probe = probeTunnel,
+  headers = {},
+  now = Date.now,
+  log = () => {},
+} = {}) {
+  let timer = null;
+  let rounds = 0;
+  let ticks = 0;
+  let lastAllDownAt = "";
+  /** @type {Map<number, boolean>} 每端口上一轮通不通（用来只在「状态变化」时打日志） */
+  const lastOk = new Map();
+  const stamp = () => new Date(now()).toISOString().slice(11, 19);
+
+  /**
+   * 跑一轮全池探活。日志纪律：**只在「状态有变化」「全池不通」「心跳点」时打**——每分钟一行会把日志淹掉。
+   * 每个不通的节点都要报全：HTTP 状态、错误原文、耗时、连续第几次、冷却多久（这样才不用靠猜）。
+   */
+  async function tick() {
+    if (!dispatcher) return { checked: 0, healthy: 0 };
+    const list = dispatcher.entries();
+    let healthy = 0;
+    let slowestMs = 0;
+    const problems = [];
+    const changes = [];
+    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 (Number(r.ms) > slowestMs) slowestMs = Number(r.ms);
+      if (r.ok) {
+        dispatcher.markOk(e.index);
+        healthy += 1;
+        if (lastOk.get(e.port) === false) changes.push(`:${e.port} 恢复（HTTP ${r.status}，${dur(r.ms)}）`);
+        lastOk.set(e.port, true);
+        continue;
+      }
+      dispatcher.markFailure(e.index);
+      if (lastOk.get(e.port) !== false) {
+        changes.push(`:${e.port} 掉线（HTTP ${r.status || 0}${r.error ? ` ${String(r.error).slice(0, 80)}` : ""}）`);
+      }
+      lastOk.set(e.port, false);
+      problems.push({ port: e.port, status: r.status, error: r.error, ms: r.ms, fails: Number(e.fails || 0) + 1, cooldownMs });
+    }
+    const allDown = list.length > 0 && healthy === 0;
+    ticks += 1;
+    if (allDown) {
+      rounds += 1;
+      lastAllDownAt = stamp();
+    } else {
+      rounds = 0;
+    }
+    if (changes.length || allDown || ticks % heartbeatEvery === 0) {
+      log(fmtHealth({ healthy, total: list.length, slowestMs, problems }));
+    }
+    for (const c of changes) log(`[warp-pool] ${MARK.warn} 状态变化：${c}`);
+    if (ticks % heartbeatEvery === 0) {
+      const extra = typeof infoOf === "function" ? infoOf() || {} : {};
+      log(fmtHeartbeat({
+        alive: extra.alive ?? list.length,
+        total: list.length,
+        pooled: extra.pooled ?? list.length,
+        exits: extra.exits || [],
+        cooling: list.filter((e) => Number(e.cooldownUntil) > now()).length,
+        lastAllDown: lastAllDownAt,
+      }));
+    }
+    if (allDown && rounds >= 2 && typeof onExhausted === "function") {
+      rounds = 0;
+      await onExhausted().catch((e) => log(`[warp-pool] 重拨失败：${String(e?.message || e)}`));
+    }
+    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/identity.js

@@ -1,141 +1,141 @@
-// warp-pool · 身份轮换：换一台 WARP 设备身份来换出口 IP。
-//
-// 依据（他项目真机实测，非推测）：kyomufs/zen-router 的 internal/zen/errors.go:32-42 记录
-//   同一身份连发 3 次 → 429 FreeUsageLimitError；身份一换，同一个请求立刻 200
-//   （104.28.198.244 → 429 ×3，104.28.198.247 → 200）。
-// 故「多名额」的正解不是「N 台设备同时在线」（真机实测同时注册会折叠成同一个出口），
-// 而是**串行换身份**：换一台设备 ⇒ 换一个出口 ⇒ 换一份按 IP 计的名额。
-//
-// 与 zen-router 对齐的三条纪律：
-// 1. 轮换后**必须实测确认出口真的变了**；没变就整个 cycle 重试（它用 4 次，这里同）。
-//    「注册成功」不等于「出口换了」——不校验就会拿同一个桶反复撞 429。
-// 2. 同端口并发轮换去重 + 最小间隔，防 429 风暴把 CF 注册刷到限流（同类项目事故）。
-// 3. 只轮换、不销毁别的节点：轮换失败保持原节点可用，绝不把池打空。
-import { probeTunnel } from "./wireproxy.js";
-import { EXIT_PROBE_URL, parseExitIp } from "./revive.js";
-
-/** 经隧道读该端口真实出口地址（CF trace）；取不到返回 ""，绝不抛。 */
-export async function readExitIp({ port, fetchImpl, timeoutMs = 12_000 } = {}) {
-  try {
-    const res = await probeTunnel({ port, baseUrl: EXIT_PROBE_URL, path: "", fetchImpl, timeoutMs, wantText: true });
-    return typeof res?.text === "string" ? parseExitIp(res.text) : "";
-  } catch {
-    return "";
-  }
-}
-
-/**
- * 身份轮换器。
- * @param {{ register: Function, apply: (node:object)=>Promise<void>, readIp?: Function,
- *           maxAttempts?: number, settleMs?: number, sleep?: Function, now?: Function,
- *           log?: (s:string)=>void }} opts
- *   apply 由调用方注入：把新身份落盘并起隧道（含停掉旧隧道）。
- */
-export function createIdentityRotator({
-  register,
-  apply,
-  readIp = readExitIp,
-  maxAttempts = 4,
-  settleMs = 3000,
-  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
-  now = Date.now,
-  log = () => {},
-} = {}) {
-  /** @type {Map<number, {ip:string, at:number}>} 各端口已知出口 */
-  const known = new Map();
-  /** @type {Map<number, Promise<object>>} 在途轮换（同端口去重） */
-  const inflight = new Map();
-
-  async function cycle(port, oldIp) {
-    for (let i = 1; i <= maxAttempts; i++) {
-      let reg;
-      try {
-        reg = await register({ log });
-      } catch (e) {
-        log(`[warp-pool] :${port} 轮换 ${i}/${maxAttempts}：注册失败（${String(e?.message || e).slice(0, 120)}）`);
-        await sleep(settleMs);
-        continue;
-      }
-      try {
-        await apply({ port, ...reg });
-      } catch (e) {
-        log(`[warp-pool] :${port} 轮换 ${i}/${maxAttempts}：起隧道失败（${String(e?.message || e).slice(0, 120)}）`);
-      }
-      await sleep(settleMs);
-      const ip = await readIp({ port });
-      if (ip && ip !== oldIp) {
-        known.set(port, { ip, at: now() });
-        log(`[warp-pool] :${port} 身份已轮换：出口 ${oldIp || "?"} → ${ip}（第 ${i}/${maxAttempts} 次）`);
-        return { ok: true, ip, attempts: i };
-      }
-      log(`[warp-pool] :${port} 轮换 ${i}/${maxAttempts}：出口未变（仍取到 ${ip || "空"}），重试`);
-    }
-    return { ok: false, attempts: maxAttempts };
-  }
-
-  return {
-    /** 记下入池时的实测出口（bootstrap 取证后调用）。 */
-    note(port, ip) {
-      if (ip) known.set(port, { ip, at: now() });
-    },
-    /** 该端口当前已知出口（"" = 未知）。 */
-    ipOf(port) {
-      return known.get(port)?.ip || "";
-    },
-    /**
-     * 轮换某节点身份换出口。同端口在途时返回同一个 Promise；minGapMs 内重复请求被掐
-     * （429 风暴时每个失败请求都触发一次轮换会把 CF 刷黑）。
-     * @returns {Promise<{ok:boolean, ip?:string, attempts?:number, skipped?:boolean}>}
-     */
-    rotate(port, { minGapMs = 60_000, force = false } = {}) {
-      const dup = inflight.get(port);
-      if (dup) return dup;
-      const prev = known.get(port);
-      if (!force && prev && now() - prev.at < minGapMs) {
-        return Promise.resolve({ ok: false, skipped: true });
-      }
-      const p = cycle(port, prev?.ip || "")
-        .catch((e) => {
-          log(`[warp-pool] :${port} 轮换异常：${String(e?.message || e)}`);
-          return { ok: false };
-        })
-        .finally(() => inflight.delete(port));
-      inflight.set(port, p);
-      return p;
-    },
-
-    /** 入池取证结果（labelExits 的分组）批量记账：每个节点的出口 IP 都要记住，轮换才能比对「是否真变了」。 */
-    noteExits(groups) {
-      for (const g of groups || []) for (const p of g.nodes || []) if (g.ip) known.set(p, { ip: g.ip, at: now() });
-    },
-    /** 轮换进行中 = 该节点正在换出口（调用方可据此避开它）。 */
-    busy(port) {
-      return inflight.has(port);
-    },
-    stats() {
-      return [...known.entries()].map(([port, v]) => ({ port, ip: v.ip, at: v.at }));
-    },
-  };
-}
-
-/**
- * 把「429 → 换身份换出口」接进一个已建好的池。轮换窗口内**先把该节点冷却**（端口已停，
- * 请求过去必失败），换好再放回。依赖全由调用方注入，本模块不反向依赖池。
- * @returns {{note:Function, noteExits:Function, ipOf:Function, rotate:Function, busy:Function, stats:Function}}
- */
-export function wireRotation({ dispatcher, register, tunnels, bringUp, swap = () => {}, log = () => {}, ...rest } = {}) {
-  return createIdentityRotator({
-    register,
-    apply: async (node) => {
-      const idx = dispatcher.entries().find((e) => e.port === node.port)?.index;
-      if (idx !== undefined) dispatcher.markFailure(idx); // 轮换窗口内先冷却：端口已停，请求过去必失败
-      tunnels.get(node.port)?.stop();
-      tunnels.delete(node.port);
-      swap(node.port, node);
-      await bringUp(node);
-      if (idx !== undefined) dispatcher.markOk(idx);
-    },
-    log,
-    ...rest,
-  });
-}
+// warp-pool · 身份轮换：换一台 WARP 设备身份来换出口 IP。
+//
+// 依据（他项目真机实测，非推测）：kyomufs/zen-router 的 internal/zen/errors.go:32-42 记录
+//   同一身份连发 3 次 → 429 FreeUsageLimitError；身份一换，同一个请求立刻 200
+//   （104.28.198.244 → 429 ×3，104.28.198.247 → 200）。
+// 故「多名额」的正解不是「N 台设备同时在线」（真机实测同时注册会折叠成同一个出口），
+// 而是**串行换身份**：换一台设备 ⇒ 换一个出口 ⇒ 换一份按 IP 计的名额。
+//
+// 与 zen-router 对齐的三条纪律：
+// 1. 轮换后**必须实测确认出口真的变了**；没变就整个 cycle 重试（它用 4 次，这里同）。
+//    「注册成功」不等于「出口换了」——不校验就会拿同一个桶反复撞 429。
+// 2. 同端口并发轮换去重 + 最小间隔，防 429 风暴把 CF 注册刷到限流（同类项目事故）。
+// 3. 只轮换、不销毁别的节点：轮换失败保持原节点可用，绝不把池打空。
+import { probeTunnel } from "./wireproxy.js";
+import { EXIT_PROBE_URL, parseExitIp } from "./revive.js";
+
+/** 经隧道读该端口真实出口地址（CF trace）；取不到返回 ""，绝不抛。 */
+export async function readExitIp({ port, fetchImpl, timeoutMs = 12_000 } = {}) {
+  try {
+    const res = await probeTunnel({ port, baseUrl: EXIT_PROBE_URL, path: "", fetchImpl, timeoutMs, wantText: true });
+    return typeof res?.text === "string" ? parseExitIp(res.text) : "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * 身份轮换器。
+ * @param {{ register: Function, apply: (node:object)=>Promise<void>, readIp?: Function,
+ *           maxAttempts?: number, settleMs?: number, sleep?: Function, now?: Function,
+ *           log?: (s:string)=>void }} opts
+ *   apply 由调用方注入：把新身份落盘并起隧道（含停掉旧隧道）。
+ */
+export function createIdentityRotator({
+  register,
+  apply,
+  readIp = readExitIp,
+  maxAttempts = 4,
+  settleMs = 3000,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+  now = Date.now,
+  log = () => {},
+} = {}) {
+  /** @type {Map<number, {ip:string, at:number}>} 各端口已知出口 */
+  const known = new Map();
+  /** @type {Map<number, Promise<object>>} 在途轮换（同端口去重） */
+  const inflight = new Map();
+
+  async function cycle(port, oldIp) {
+    for (let i = 1; i <= maxAttempts; i++) {
+      let reg;
+      try {
+        reg = await register({ log });
+      } catch (e) {
+        log(`[warp-pool] :${port} 轮换 ${i}/${maxAttempts}：注册失败（${String(e?.message || e).slice(0, 120)}）`);
+        await sleep(settleMs);
+        continue;
+      }
+      try {
+        await apply({ port, ...reg });
+      } catch (e) {
+        log(`[warp-pool] :${port} 轮换 ${i}/${maxAttempts}：起隧道失败（${String(e?.message || e).slice(0, 120)}）`);
+      }
+      await sleep(settleMs);
+      const ip = await readIp({ port });
+      if (ip && ip !== oldIp) {
+        known.set(port, { ip, at: now() });
+        log(`[warp-pool] :${port} 身份已轮换：出口 ${oldIp || "?"} → ${ip}（第 ${i}/${maxAttempts} 次）`);
+        return { ok: true, ip, attempts: i };
+      }
+      log(`[warp-pool] :${port} 轮换 ${i}/${maxAttempts}：出口未变（仍取到 ${ip || "空"}），重试`);
+    }
+    return { ok: false, attempts: maxAttempts };
+  }
+
+  return {
+    /** 记下入池时的实测出口（bootstrap 取证后调用）。 */
+    note(port, ip) {
+      if (ip) known.set(port, { ip, at: now() });
+    },
+    /** 该端口当前已知出口（"" = 未知）。 */
+    ipOf(port) {
+      return known.get(port)?.ip || "";
+    },
+    /**
+     * 轮换某节点身份换出口。同端口在途时返回同一个 Promise；minGapMs 内重复请求被掐
+     * （429 风暴时每个失败请求都触发一次轮换会把 CF 刷黑）。
+     * @returns {Promise<{ok:boolean, ip?:string, attempts?:number, skipped?:boolean}>}
+     */
+    rotate(port, { minGapMs = 60_000, force = false } = {}) {
+      const dup = inflight.get(port);
+      if (dup) return dup;
+      const prev = known.get(port);
+      if (!force && prev && now() - prev.at < minGapMs) {
+        return Promise.resolve({ ok: false, skipped: true });
+      }
+      const p = cycle(port, prev?.ip || "")
+        .catch((e) => {
+          log(`[warp-pool] :${port} 轮换异常：${String(e?.message || e)}`);
+          return { ok: false };
+        })
+        .finally(() => inflight.delete(port));
+      inflight.set(port, p);
+      return p;
+    },
+
+    /** 入池取证结果（labelExits 的分组）批量记账：每个节点的出口 IP 都要记住，轮换才能比对「是否真变了」。 */
+    noteExits(groups) {
+      for (const g of groups || []) for (const p of g.nodes || []) if (g.ip) known.set(p, { ip: g.ip, at: now() });
+    },
+    /** 轮换进行中 = 该节点正在换出口（调用方可据此避开它）。 */
+    busy(port) {
+      return inflight.has(port);
+    },
+    stats() {
+      return [...known.entries()].map(([port, v]) => ({ port, ip: v.ip, at: v.at }));
+    },
+  };
+}
+
+/**
+ * 把「429 → 换身份换出口」接进一个已建好的池。轮换窗口内**先把该节点冷却**（端口已停，
+ * 请求过去必失败），换好再放回。依赖全由调用方注入，本模块不反向依赖池。
+ * @returns {{note:Function, noteExits:Function, ipOf:Function, rotate:Function, busy:Function, stats:Function}}
+ */
+export function wireRotation({ dispatcher, register, tunnels, bringUp, swap = () => {}, log = () => {}, ...rest } = {}) {
+  return createIdentityRotator({
+    register,
+    apply: async (node) => {
+      const idx = dispatcher.entries().find((e) => e.port === node.port)?.index;
+      if (idx !== undefined) dispatcher.markFailure(idx); // 轮换窗口内先冷却：端口已停，请求过去必失败
+      tunnels.get(node.port)?.stop();
+      tunnels.delete(node.port);
+      swap(node.port, node);
+      await bringUp(node);
+      if (idx !== undefined) dispatcher.markOk(idx);
+    },
+    log,
+    ...rest,
+  });
+}