mslxdff 0.1.185 → 0.1.187

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mslxdff",
-  "version": "0.1.185",
+  "version": "0.1.187",
   "description": "测试项目，请勿使用。",
   "type": "module",
   "bin": {

package/src/runtime/providers-setup.js

@@ -13,7 +13,7 @@ import { createOpenCodeProvider } from "../providers/opencode.js";
 import { loadProviderKeys, loadProviderAuths, loadProviderConfigs } from "../state.js";
 import { refreshIntervalMs, modelCooldownMs, slowCooldownMs, peerCooldownMs, peerLimitCooldownMs, peerHeatMs, banWindowMs, banThreshold } from "../cli/policy.js";
 import { errMsg } from "../cli/util.js";
-import { createWarpDispatcher } from "../warp-pool/index.js";
+import { createPreferredDispatcher } from "../v6pool/index.js";
 
 
 import { shouldEnableCustomProvider, loadAuthDocs } from "./provider-gate.js";
@@ -51,7 +51,7 @@ export async function setupProviders() {
   const baseUrl = process.env.UPSTREAM_BASE_URL || "https://opencode.ai";
   let providers = [];
 
-  const warpDispatcher = createWarpDispatcher({ baseUrl });
+  const outboundDispatcher = createPreferredDispatcher({ baseUrl });
   if (providerPlugin) {
     if (!upstream) {
       try {
@@ -63,9 +63,9 @@ export async function setupProviders() {
         appendEvent({ ts: Date.now(), type: "plugin-upstream-error", plugin: providerPlugin.name, error: errMsg(err) });
       }
     }
-    if (!upstream) upstream = createUpstreamClient({ hooks: upstreamHooks, dispatcher: warpDispatcher });
+    if (!upstream) upstream = createUpstreamClient({ hooks: upstreamHooks, dispatcher: outboundDispatcher });
   } else {
-    const opencodeClient = createUpstreamEngine({ hooks: upstreamHooks, dispatcher: warpDispatcher });
+    const opencodeClient = createUpstreamEngine({ hooks: upstreamHooks, dispatcher: outboundDispatcher });
     const opencodeModels = createModelsService({
       baseUrl,
       headers: opencodeClient.headers,

package/src/v6pool/claim.js

@@ -0,0 +1,157 @@
+// v6pool · 让内核接受池里的源地址（bind 直用 / ip addr add 认领）+ 认领账 + 释放。
+//
+// 两条路（Linux 上 bind() 一个没分配给本机的源地址会直接 EADDRNOTAVAIL）：
+//   bind：net.ipv6.ip_nonlocal_bind=1 ⇒ 直接 bind 任意地址，**不碰网卡**（首选，零副作用）；
+//   add ：ip -6 addr add <addr>/128 dev <iface> nodad ⇒ 加进网卡（需 root）。
+//
+// 为什么要记账（本轮手工实测的教训）：加进网卡的地址会改变内核的**默认源地址选择**——
+// 我在 A 机上留了两个临时地址，结果不带 --interface 的请求也走了新地址（生产机上这是事故）。
+// 所以：每次 add/del 都落 `<dir>/claimed.json`（0600、非工作树）；close 时全部释放；
+// 启动时按这份账清上一代残留（崩溃 / 被 SIGKILL 时 close 跑不到）。
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { execFile, execFileSync } from "node:child_process";
+import { fmtClaim, fmtClaimFail, fmtSweep } from "./report.js";
+
+export const CLAIM_FILE = "claimed.json";
+
+/** 默认执行器：失败时把 stderr 原文带进 Error（不许把 stderr 吞掉——否则只剩「失败了」）。 */
+export function defaultExec(file, args, { timeoutMs = 10_000 } = {}) {
+  return new Promise((resolve, reject) => {
+    execFile(file, args, { timeout: timeoutMs }, (err, stdout, stderr) => {
+      if (err) {
+        const e = new Error(`${file} ${args.join(" ")} 失败：${String(stderr || err.message || "").trim()}`);
+        e.code = err.code;
+        e.stderr = String(stderr || "");
+        reject(e);
+        return;
+      }
+      resolve({ stdout: String(stdout || ""), stderr: String(stderr || "") });
+    });
+  });
+}
+
+/** 退出钩子专用（同步）：`process.on("exit")` 里跑不了 async，但地址必须清。 */
+export function defaultExecSync(file, args, { timeoutMs = 10_000 } = {}) {
+  execFileSync(file, args, { timeout: timeoutMs, stdio: "ignore" });
+}
+
+/** 幂等判据：`ip addr add` 报 File exists = 已经在网卡上了，不算失败。 */
+export function isAlreadyThere(e) {
+  return /File exists|already assigned/i.test(String(e?.stderr || e?.message || ""));
+}
+
+/** 释放时「它已经不在了」也不算失败（上一代残留已被别处清掉 / 手工删掉）。 */
+export function isAlreadyGone(e) {
+  return /Cannot assign requested address|Cannot find device|does not exist/i.test(String(e?.stderr || e?.message || ""));
+}
+
+/**
+ * @param {{ iface?: string, mode?: "bind"|"add", dir?: string, log?: (s:string)=>void, exec?: Function, fs?: object }} opts
+ */
+export function createClaimer({ iface = "", mode = "bind", dir = "", log = () => {}, exec = defaultExec, fs = { mkdirSync, writeFileSync, chmodSync, readFileSync } } = {}) {
+  /** 只有 add 模式需要记账（bind 模式没改网卡，无残留可言）。 */
+  const claimed = new Set();
+
+  function persist() {
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+      const file = join(dir, CLAIM_FILE);
+      fs.writeFileSync(file, `${JSON.stringify({ iface, mode, addrs: [...claimed], updatedAt: new Date().toISOString() }, null, 2)}\n`, { mode: 0o600 });
+      fs.chmodSync(file, 0o600); // mode 只在新建时生效，存量必须补
+    } catch (e) {
+      log(`[v6pool] ⚠ 认领账写盘失败（本次照跑，但崩溃后无法自动清残留）：${String(e?.message || e)}`);
+    }
+  }
+
+  async function ensure(addr) {
+    if (mode !== "add") return addr;
+    try {
+      await exec("ip", ["-6", "addr", "add", `${addr}/128`, "dev", iface, "nodad"]);
+      log(fmtClaim({ addr, iface }));
+    } catch (e) {
+      if (!isAlreadyThere(e)) {
+        log(fmtClaimFail({ addr, iface, error: String(e?.message || e) }));
+        throw e;
+      }
+    }
+    claimed.add(addr);
+    persist();
+    return addr;
+  }
+
+  async function release(addr) {
+    if (mode !== "add" || !claimed.has(addr)) return false;
+    claimed.delete(addr);
+    persist();
+    try {
+      await exec("ip", ["-6", "addr", "del", `${addr}/128`, "dev", iface]);
+      return true;
+    } catch (e) {
+      if (isAlreadyGone(e)) return false;
+      log(`[v6pool] ⚠ 释放源地址失败（重启时由启动清残留兜底）：${addr} — ${String(e?.stderr || e?.message || "").trim()}`);
+      return false;
+    }
+  }
+
+  async function releaseAll() {
+    const done = [];
+    for (const a of [...claimed]) if (await release(a)) done.push(a);
+    return done;
+  }
+
+  /** 退出钩子专用：进程正在退出，只能跑同步命令；清不掉的交给下次启动的 sweepStale。 */
+  function releaseAllSync({ execSync = defaultExecSync } = {}) {
+    if (mode !== "add" || !claimed.size) return [];
+    const done = [];
+    for (const a of [...claimed]) {
+      try {
+        execSync("ip", ["-6", "addr", "del", `${a}/128`, "dev", iface]);
+        done.push(a);
+      } catch {
+        /* 删不掉不抛：进程正在退出，抛了也没人接 */
+      }
+    }
+    claimed.clear();
+    return done;
+  }
+
+  /** 启动清残留：只删**上一代自己记在账上的**地址，绝不猜（不扫全表，不碰别人的地址）。 */
+  async function sweepStale() {
+    if (mode !== "add") return { removed: [], failed: [] };
+    let prev = [];
+    try {
+      prev = JSON.parse(fs.readFileSync(join(dir, CLAIM_FILE), "utf8"))?.addrs || [];
+    } catch {
+      return { removed: [], failed: [] };
+    }
+    const removed = [];
+    const failed = [];
+    for (const a of prev) {
+      if (typeof a !== "string" || !a) continue;
+      try {
+        await exec("ip", ["-6", "addr", "del", `${a}/128`, "dev", iface]);
+        removed.push(a);
+      } catch (e) {
+        if (!isAlreadyGone(e)) failed.push({ addr: a, error: String(e?.stderr || e?.message || "").trim() });
+      }
+    }
+    claimed.clear();
+    persist();
+    const r = { removed, failed };
+    if (removed.length || failed.length) log(fmtSweep({ iface, ...r }));
+    return r;
+  }
+
+  return {
+    ensure,
+    release,
+    releaseAll,
+    releaseAllSync,
+    sweepStale,
+    claimed: () => [...claimed],
+    get mode() {
+      return mode;
+    },
+  };
+}

package/src/v6pool/config.js

@@ -0,0 +1,65 @@
+// v6pool · 配置解析：env 优先，缺省值集中一处；纯函数，便于单测。
+import { join } from "node:path";
+import { logDir } from "../logs.js";
+
+/**
+ * 缺省**开** + **自动判断**：本机有整段路由的 IPv6 前缀就启用（判据见 detect.js），
+ * 没有就诚实跳过（行为与今天完全一致）。判据不靠 env，靠事实。
+ */
+export const DEFAULTS = {
+  enabled: true,
+  count: 4,
+  strategy: "session",
+  cooldownMs: 600_000,
+  rotate: true,
+  minHostBits: 8,
+  claim: "auto",
+  probePath: "/zen/v1/models",
+  retireMs: 60_000,
+  debug: false,
+};
+
+const OFF = ["0", "off", "false", "no", "disable", "disabled"];
+const CLAIM_MODES = ["auto", "bind", "add"];
+
+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;
+}
+
+/**
+ * 解析 v6 出口池配置。
+ * @param {Record<string,string|undefined>} env
+ * @param {{ logDirFn?: () => string }} [deps] 测试可注入 logDir
+ */
+export function resolveV6Config(env = process.env, { logDirFn = logDir } = {}) {
+  const strategy = envStr(env, "MSLXDFF_V6_STRATEGY", DEFAULTS.strategy) === "request" ? "request" : "session";
+  const claimRaw = envStr(env, "MSLXDFF_V6_CLAIM", DEFAULTS.claim).toLowerCase();
+  return {
+    enabled: envBool(env, "MSLXDFF_V6_POOL", DEFAULTS.enabled),
+    /** 显式池前缀（`2001:db8::/64`）；空 = 取本机全局地址的前缀 */
+    prefix: envStr(env, "MSLXDFF_V6_PREFIX", ""),
+    iface: envStr(env, "MSLXDFF_V6_IFACE", ""),
+    count: envInt(env, "MSLXDFF_V6_COUNT", DEFAULTS.count),
+    strategy,
+    cooldownMs: envInt(env, "MSLXDFF_V6_COOLDOWN_MS", DEFAULTS.cooldownMs),
+    rotate: envBool(env, "MSLXDFF_V6_ROTATE", DEFAULTS.rotate),
+    minHostBits: envInt(env, "MSLXDFF_V6_MIN_HOST_BITS", DEFAULTS.minHostBits),
+    claim: CLAIM_MODES.includes(claimRaw) ? claimRaw : DEFAULTS.claim,
+    dir: envStr(env, "MSLXDFF_V6_DIR", join(logDirFn(), "v6pool")),
+    probePath: envStr(env, "MSLXDFF_V6_PROBE_PATH", DEFAULTS.probePath),
+    retireMs: envInt(env, "MSLXDFF_V6_RETIRE_MS", DEFAULTS.retireMs),
+    debug: envBool(env, "MSLXDFF_V6_DEBUG", DEFAULTS.debug),
+  };
+}

package/src/v6pool/detect.js

@@ -0,0 +1,130 @@
+// v6pool · 自动判断本机有没有可用的 IPv6 池（纯解析 + 可注入 IO，便于单测）。
+//
+// 四关，任一不过就诚实跳过（并给出「下一步该跑什么」）：
+//   ① 平台：只有 Linux 能读 /proc 并用 ip 命令（与 wireproxy 预编译平台限制同口径）；
+//   ② 地址：/proc/net/if_inet6 里必须有 scope=global 的地址；
+//   ③ 前缀：该地址的前缀主机位 ≥ minHostBits（/128 只有 1 个地址，不构成池）；
+//   ④ 认领：ip_nonlocal_bind=1（直接 bind，零改动）或 root（能 ip addr add）。
+//
+// ⚠ 本模块**不假装知道**「整段有没有真路由到本机」——那只能靠 probe.js 从池里的地址实测。
+// 内核接受地址（bind 成功）≠ 机房把回包送回来；两者混为一谈正是「池看起来就绪、请求全黑洞」的根因。
+import { readFileSync } from "node:fs";
+import { formatV6, hostBitsOf, networkOf, parsePrefix, parseV6 } from "./prefix.js";
+
+/** /proc/net/if_inet6 的 scope 列：00=global、10=host、20=link、40=site（都是 hex）。 */
+export const SCOPE_GLOBAL = 0;
+
+/** 解析 /proc/net/if_inet6：`<32 位 hex 地址> <ifindex> <prefixlen> <scope> <flags> <网卡>`。 */
+export function parseIfInet6(raw) {
+  const out = [];
+  for (const line of String(raw ?? "").split("\n")) {
+    const f = line.trim().split(/\s+/);
+    if (f.length < 6 || !/^[0-9a-f]{32}$/i.test(f[0])) continue;
+    const addr = parseV6(f[0].toLowerCase().match(/.{4}/g).join(":"));
+    if (addr === null) continue;
+    out.push({
+      addr,
+      text: formatV6(addr),
+      ifindex: parseInt(f[1], 16),
+      bits: parseInt(f[2], 16),
+      scope: parseInt(f[3], 16),
+      iface: f[5],
+    });
+  }
+  return out;
+}
+
+function skip(reason, hint) {
+  return { ok: false, reason, hint };
+}
+
+/**
+ * 四关判定：把「本机事实」变成「可用池 或 具体跳过原因」。
+ * 全部依赖注入（测试不用真读 /proc、不用真 root）。
+ */
+export function pickPool({
+  entries = [],
+  nonlocalBind = 0,
+  uid = -1,
+  platform = process.platform,
+  explicitPrefix = "",
+  explicitIface = "",
+  minHostBits = 8,
+  claim = "auto",
+} = {}) {
+  if (platform !== "linux") {
+    return skip(`本平台（${platform}）不支持：需要 Linux 的 /proc 与 ip 命令`, "非 Linux 机器不需要本功能（WARP 池同样只在 Linux 可用）");
+  }
+  const globals = entries.filter((e) => e.scope === SCOPE_GLOBAL);
+  let addr;
+  let bits;
+  let iface;
+  let source;
+  if (explicitPrefix) {
+    const p = parsePrefix(explicitPrefix);
+    if (!p) return skip(`MSLXDFF_V6_PREFIX 解析失败：${explicitPrefix}`, "格式形如 2001:db8:1:2::/64");
+    addr = p.addr;
+    bits = p.bits;
+    source = "env";
+    iface = explicitIface || globals[0]?.iface || "";
+  } else {
+    if (!globals.length) {
+      return skip("本机没有任何全局 IPv6 地址（只有 link-local / loopback）", "确认网卡上启用了 IPv6，且运营商或机房确实给了 IPv6");
+    }
+    const picked = (explicitIface && globals.find((e) => e.iface === explicitIface)) || globals[0];
+    addr = picked.addr;
+    bits = picked.bits;
+    iface = explicitIface || picked.iface;
+    source = "proc";
+  }
+  const hostBits = hostBitsOf(bits);
+  if (hostBits < minHostBits) {
+    return skip(
+      `前缀 /${bits} 只有 ${hostBits} 位主机位（< ${minHostBits}），不构成池`,
+      `该地址是 /${bits}：整段没路由到本机时换不了 IP。若确认整段可用，用 MSLXDFF_V6_PREFIX=<段>/<位数> 显式指定`,
+    );
+  }
+  const mode = claim === "auto" ? (nonlocalBind === 1 ? "bind" : uid === 0 ? "add" : "none") : claim;
+  if (mode === "bind" && nonlocalBind !== 1) {
+    return skip("MSLXDFF_V6_CLAIM=bind 但 net.ipv6.ip_nonlocal_bind≠1", "sysctl -w net.ipv6.ip_nonlocal_bind=1，或改用 MSLXDFF_V6_CLAIM=add");
+  }
+  if (mode === "add" && uid !== 0) {
+    return skip(`MSLXDFF_V6_CLAIM=add 需要 root（当前 uid=${uid}）`, "以 root 跑 daemon，或 sysctl -w net.ipv6.ip_nonlocal_bind=1 后设 MSLXDFF_V6_CLAIM=bind");
+  }
+  if (mode === "none") {
+    return skip("既没有 ip_nonlocal_bind=1，也不是 root ⇒ 内核会拒绝 bind 池里的地址（EADDRNOTAVAIL）", "二选一：sysctl -w net.ipv6.ip_nonlocal_bind=1，或以 root 跑（可 ip addr add）");
+  }
+  return {
+    ok: true,
+    addr,
+    bits,
+    iface,
+    hostBits,
+    mode,
+    source,
+    prefix: `${formatV6(networkOf(addr, bits))}/${bits}`,
+    /** 本机自己的全局地址：造池时避开它们（别把机器正在用的地址当池里的"新"地址） */
+    mine: globals.map((e) => e.text),
+  };
+}
+
+/** 真机路径：读 /proc 与 /proc/sys（可整体注入，测试零 IO）。 */
+export function detectPool({ cfg = {}, entries, nonlocalBind, uid, platform = process.platform, readFile = (p) => readFileSync(p, "utf8") } = {}) {
+  const read = (p, dflt) => {
+    try {
+      return readFile(p);
+    } catch {
+      return dflt;
+    }
+  };
+  return pickPool({
+    entries: entries ?? parseIfInet6(read("/proc/net/if_inet6", "")),
+    nonlocalBind: nonlocalBind ?? (Number(String(read("/proc/sys/net/ipv6/ip_nonlocal_bind", "0")).trim()) || 0),
+    uid: uid ?? (typeof process.getuid === "function" ? process.getuid() : -1),
+    platform,
+    explicitPrefix: cfg.prefix || "",
+    explicitIface: cfg.iface || "",
+    minHostBits: cfg.minHostBits || 8,
+    claim: cfg.claim || "auto",
+  });
+}

package/src/v6pool/index.js

@@ -0,0 +1,152 @@
+// v6pool · 装配入口（MODULES.md §0/§1）。
+//
+// 定位：**自动判断**本机有没有可用的 IPv6 池；有就启用（出口 = 池里的源地址），
+// 没有就诚实跳过一行日志（行为与今天完全一致）。缺省开，MSLXDFF_V6_POOL=0 关。
+//
+// 与 WARP 池的关系：v6 池可用 ⇒ 不建 WARP 池（v6 严格更优：地址无限、零子进程、换址成本≈0）；
+// 检测通过但探活全失败 ⇒ 池为空 ⇒ dispatcher 走直连兜底，日志点名 MSLXDFF_V6_POOL=0 可恢复 WARP。
+import { getUndici } from "../compat.js";
+import { resolveV6Config } from "./config.js";
+import { detectPool } from "./detect.js";
+import { createClaimer } from "./claim.js";
+import { createV6Dispatcher } from "./rotate.js";
+import { probeFrom } from "./probe.js";
+import { randomAddress } from "./prefix.js";
+import { fmtClose, fmtConfig, fmtDetect, fmtDisabled, fmtPool, fmtPoolEmpty, fmtProbe, fmtReadyFail, fmtSkip } from "./report.js";
+import { createWarpDispatcher } from "../warp-pool/index.js";
+
+/** 每槽 Agent 的连接池参数。注入 dispatcher 后 transport 不建自带池（transport/index.js L28），所以必须自带。 */
+export const AGENT_OPTIONS = { connections: 4, pipelining: 1, keepAliveTimeout: 30_000, keepAliveMaxTimeout: 60_000 };
+
+/** 初始地址集的去重重试上限（前缀足够大时一次就成）。 */
+export const DISTINCT_TRIES = 16;
+
+/**
+ * 建池。检测不过 / 平台不支持 / 无权限 / undici 缺失 ⇒ 返回 null（调用方据此不注入、退回原行为）。
+ * @returns {null | { dispatcher: object, ready: Promise<void>, config: object, detect: object,
+ *                    close: () => Promise<void>, stats: () => object }}
+ */
+export function createV6Pool({ env = process.env, baseUrl = "https://opencode.ai", log = (m) => console.error(m), deps = {} } = {}) {
+  const cfg = resolveV6Config(env);
+  if (!cfg.enabled) {
+    log(fmtDisabled());
+    return null;
+  }
+  log(fmtConfig(cfg));
+
+  const d = deps.detect ? deps.detect(cfg) : detectPool({ cfg, env });
+  if (!d.ok) {
+    log(fmtSkip(d));
+    return null;
+  }
+  log(fmtDetect(d));
+
+  const { Agent } = getUndici();
+  if (typeof Agent !== "function") {
+    log(fmtReadyFail({ error: "undici Agent 不可用（未安装 undici 且 Node <18）" }));
+    return null;
+  }
+
+  const prefix = { addr: d.addr, bits: d.bits };
+  const mine = new Set(d.mine || []);
+  const agentFactory = deps.agentFactory || ((addr) => new Agent({ connect: { localAddress: addr }, ...AGENT_OPTIONS }));
+  const claimer = deps.claimer ? deps.claimer(d) : createClaimer({ iface: d.iface, mode: d.mode, dir: cfg.dir, log });
+  const probe = deps.probe || probeFrom;
+
+  /** 挑一个池内地址：避开本机自己的全局地址（别把机器正在用的地址当"新"地址）。 */
+  function pickAddress() {
+    for (let i = 0; i < DISTINCT_TRIES; i++) {
+      const a = randomAddress(prefix);
+      if (!mine.has(a)) return a;
+    }
+    return randomAddress(prefix);
+  }
+
+  const dispatcher = createV6Dispatcher({
+    addrs: [],
+    strategy: cfg.strategy,
+    retireMs: cfg.retireMs,
+    rotate: cfg.rotate,
+    debug: cfg.debug,
+    log,
+    claimer,
+    pickAddress,
+    agentFactory,
+  });
+
+  let closed = false;
+  const ready = (async () => {
+    try {
+      await claimer.sweepStale();
+      const addrs = [];
+      const taken = new Set();
+      for (let i = 0; i < cfg.count; i++) {
+        if (closed) return;
+        let a = pickAddress();
+        for (let k = 0; k < DISTINCT_TRIES && taken.has(a); k++) a = pickAddress();
+        await claimer.ensure(a);
+        taken.add(a);
+        addrs.push(a);
+      }
+      // 逐个实证探活：内核接受了地址 ≠ 机房把整段路由到本机。探不通的当场释放，绝不进池。
+      const passed = [];
+      for (let i = 0; i < addrs.length; i++) {
+        if (closed) return;
+        const r = await probe({ addr: addrs[i], baseUrl, path: cfg.probePath, agentFactory });
+        log(fmtProbe({ addr: addrs[i], i: i + 1, n: addrs.length, ...r }));
+        if (r.ok) passed.push(addrs[i]);
+        else await claimer.release(addrs[i]);
+      }
+      if (!passed.length) {
+        log(fmtPoolEmpty({ tried: addrs.length }));
+        return;
+      }
+      dispatcher.setAddresses(passed);
+      log(fmtPool({ prefix: d.prefix, addrs: passed, claimed: addrs.length, mode: d.mode }));
+    } catch (e) {
+      log(fmtReadyFail({ error: String(e?.message || e) }));
+    }
+  })();
+
+  // 退出钩子：`process.on("exit")` 里只能跑同步代码，但地址必须清——加进网卡的地址会改变内核的
+  // 默认源地址选择，影响同机其它服务（本轮手工实测踩过）。清不掉就交给下次启动的 sweepStale。
+  if (deps.exitHook !== false) {
+    process.once("exit", () => {
+      try {
+        claimer.releaseAllSync?.();
+      } catch {
+        /* 清残留兜底见 claim.js 的 sweepStale */
+      }
+    });
+  }
+
+  return {
+    dispatcher,
+    ready,
+    config: cfg,
+    detect: d,
+    async close() {
+      if (closed) return;
+      closed = true;
+      await dispatcher.close();
+      const released = await claimer.releaseAll();
+      log(fmtClose({ released }));
+    },
+    stats() {
+      return { enabled: true, mode: d.mode, prefix: d.prefix, iface: d.iface, claimed: claimer.claimed(), ...dispatcher.stats() };
+    },
+  };
+}
+
+/**
+ * 出口池二选一（唯一接线点用）：v6 池可用就用它，否则退回 WARP 池。
+ * 两者都只产出一个 dispatcher 对象，注入点与契约完全一致（见 MODULES.md §1）。
+ * 放在这里而不是 providers-setup：那里是 10KB 硬门下的文件，多一行都是风险。
+ */
+export function createPreferredDispatcher({ baseUrl = "https://opencode.ai", env = process.env, log, deps = {} } = {}) {
+  const pool = createV6Pool({ env, baseUrl, log, deps });
+  if (pool) return pool.dispatcher;
+  // 单向依赖：warp-pool 不 import v6pool（见 MODULES.md §2「已知耦合」）。
+  return createWarpDispatcher({ baseUrl, env, log });
+}
+

package/src/v6pool/prefix.js

@@ -0,0 +1,140 @@
+// v6pool · IPv6 前缀算术（纯函数，零 IO）：解析 / 规范化 / 取网络号 / 随机主机号。
+//
+// 为什么自己写：Node 没有内建 IPv6 前缀算术（`net.isIPv6` 只判形状），
+// 而本功能的核心动作就是「在给定前缀里造一个合法、不与现有地址撞车的主机号」。
+// 卫生规则（跳过 0/1/全 1、扰动 EUI-64 的 ff:fe 标记）照抄 v6pool 的 sanitizeHost——
+// 那几条是为了让出口地址看起来不像 SLAAC 自生成的地址（v6pool 的「unlinkable exits」）。
+const M16 = 0xffffn;
+
+/** 解析 IPv6 字面量 → BigInt(128bit)。非法返回 null。支持 `::` 压缩、`[..]` 包裹、`%zone`、v4 尾巴。 */
+export function parseV6(raw) {
+  let s = String(raw ?? "").trim().toLowerCase();
+  if (!s) return null;
+  if (s.startsWith("[") && s.endsWith("]")) s = s.slice(1, -1);
+  const zone = s.indexOf("%");
+  if (zone >= 0) s = s.slice(0, zone);
+  if (s.includes(".")) {
+    const at = s.lastIndexOf(":");
+    if (at < 0) return null;
+    const v4 = s.slice(at + 1).split(".");
+    if (v4.length !== 4 || !v4.every((x) => /^\d{1,3}$/.test(x) && Number(x) <= 255)) return null;
+    const n = v4.reduce((a, x) => ((a << 8) | Number(x)) >>> 0, 0) >>> 0;
+    s = `${s.slice(0, at)}:${(n >>> 16).toString(16)}:${(n & 0xffff).toString(16)}`;
+  }
+  const halves = s.split("::");
+  if (halves.length > 2) return null;
+  const head = halves[0] ? halves[0].split(":") : [];
+  const tail = halves.length === 2 ? (halves[1] ? halves[1].split(":") : []) : [];
+  if (halves.length === 1 && head.length !== 8) return null;
+  if (head.length + tail.length > 8) return null;
+  const fill = 8 - head.length - tail.length;
+  const groups = [...head, ...Array(halves.length === 2 ? fill : 0).fill("0"), ...tail];
+  if (groups.length !== 8) return null;
+  let out = 0n;
+  for (const g of groups) {
+    if (!/^[0-9a-f]{1,4}$/.test(g)) return null;
+    out = (out << 16n) | BigInt(`0x${g}`);
+  }
+  return out;
+}
+
+/** BigInt → 规范化 IPv6 文本（小写；最长零段压缩成 `::`，RFC 5952 只压 ≥2 段）。 */
+export function formatV6(big) {
+  const groups = [];
+  for (let i = 7; i >= 0; i--) groups.push(Number((big >> BigInt(i * 16)) & M16));
+  let bestAt = -1;
+  let bestLen = 0;
+  let curAt = -1;
+  let curLen = 0;
+  for (let i = 0; i < 8; i++) {
+    if (groups[i] === 0) {
+      if (curAt < 0) curAt = i;
+      curLen += 1;
+      if (curLen > bestLen) {
+        bestLen = curLen;
+        bestAt = curAt;
+      }
+    } else {
+      curAt = -1;
+      curLen = 0;
+    }
+  }
+  const hex = groups.map((g) => g.toString(16));
+  if (bestLen < 2) return hex.join(":");
+  return `${hex.slice(0, bestAt).join(":")}::${hex.slice(bestAt + bestLen).join(":")}`;
+}
+
+/** `"2001:db8::/64"` → `{ addr: BigInt, bits: 64, text: "2001:db8::" }`；非法返回 null。 */
+export function parsePrefix(raw) {
+  const s = String(raw ?? "").trim();
+  const slash = s.lastIndexOf("/");
+  if (slash < 0) return null;
+  const bits = Number(s.slice(slash + 1));
+  if (!Number.isInteger(bits) || bits < 0 || bits > 128) return null;
+  const addr = parseV6(s.slice(0, slash));
+  if (addr === null) return null;
+  return { addr, bits, text: formatV6(networkOf(addr, bits)) };
+}
+
+/** /bits 前缀里有几位主机位（= 可用地址的指数）。 */
+export function hostBitsOf(bits) {
+  return 128 - Number(bits);
+}
+
+/** 该地址在 /bits 下的网络号（主机位清零）。 */
+export function networkOf(addr, bits) {
+  if (bits <= 0) return 0n;
+  if (bits >= 128) return addr;
+  return addr & ~((1n << BigInt(128 - bits)) - 1n);
+}
+
+/** 随机主机号（m 位）。用 rnd() 拼 32bit 块，避免一次 Math.random 只有 53 位精度。 */
+export function randomHost(m, rnd = Math.random) {
+  let v = 0n;
+  let got = 0;
+  while (got < m) {
+    const take = Math.min(32, m - got);
+    const r = Math.floor(rnd() * 0x100000000) >>> 0;
+    v = (v << BigInt(take)) | (BigInt(r) & ((1n << BigInt(take)) - 1n));
+    got += take;
+  }
+  return v;
+}
+
+/** 该 64 位 IID 是否带 EUI-64 的 ff:fe 标记（RFC 4291 附录 A：MAC 派生的 SLAAC 地址）。 */
+export function isEui64(iid) {
+  return ((iid >> 24n) & M16) === 0xfffen;
+}
+
+/**
+ * 主机号卫生：m>2 时跳过 0/1/全 1；m>=40 时扰动 ff:fe 标记。循环有界（8 次）且确定。
+ */
+export function sanitizeHost(v, m) {
+  const mask = m >= 128 ? (1n << 128n) - 1n : (1n << BigInt(m)) - 1n;
+  let x = v & mask;
+  for (let i = 0; i < 8; i++) {
+    if (m >= 40 && isEui64(x)) {
+      x = (x ^ 0x0000000200000000n) & mask;
+      continue;
+    }
+    if (m > 2 && (x === 0n || x === 1n || x === mask)) {
+      x = (x + 1n) & mask;
+      continue;
+    }
+    return x;
+  }
+  return x;
+}
+
+/** 在前缀里造一个随机地址（主机号随机 + 卫生规则）。m<=0（/128）时只能返回前缀自身。 */
+export function randomAddress(prefix, rnd = Math.random) {
+  const m = hostBitsOf(prefix.bits);
+  if (m <= 0) return formatV6(prefix.addr);
+  const host = sanitizeHost(randomHost(m, rnd), m);
+  return formatV6(networkOf(prefix.addr, prefix.bits) | host);
+}
+
+/** 地址是否落在该前缀里。 */
+export function inPrefix(addr, prefix) {
+  return networkOf(addr, prefix.bits) === networkOf(prefix.addr, prefix.bits);
+}

package/src/v6pool/probe.js

@@ -0,0 +1,40 @@
+// v6pool · 起池前的实证探活：**用池里的源地址**打一次上游。
+//
+// 为什么必须有（这是本功能唯一不能省的实测）：内核接受地址（bind 成功）≠ 机房真把整段路由到本机。
+// 只路由单个 /128 的机器上，从段内随机地址发出的包全部黑洞——那种池进了池就是「请求挂到超时」，
+// 比直连更糟。判据只有一条：**从该地址真的能拿到上游响应**。
+import { compatFetch, getUndici, timeoutSignal } from "../compat.js";
+import { opencodeUa } from "../opencode-identity.js";
+
+/**
+ * @param {{ addr: string, baseUrl?: string, path?: string, agentFactory: Function, fetchImpl?: Function, timeoutMs?: number }} opts
+ * @returns {Promise<{ ok: boolean, status: number, ms: number, error?: string }>}
+ */
+export async function probeFrom({ addr, baseUrl = "https://opencode.ai", path = "/zen/v1/models", agentFactory, fetchImpl, timeoutMs = 8000 } = {}) {
+  const agent = agentFactory(addr);
+  const url = `${String(baseUrl).replace(/\/+$/, "")}${path}`;
+  const t0 = Date.now();
+  try {
+    const f = fetchImpl || getUndici().fetch || compatFetch;
+    const res = await f(url, {
+      method: "GET",
+      headers: { "User-Agent": opencodeUa() },
+      dispatcher: agent,
+      signal: timeoutSignal(timeoutMs),
+    });
+    try {
+      await res.text();
+    } catch {
+      /* 读不完不影响判活：拿到状态码就算数 */
+    }
+    return { ok: !!res.ok, status: res.status, ms: Date.now() - t0 };
+  } catch (e) {
+    return { ok: false, status: 0, ms: Date.now() - t0, error: String(e?.message || e) };
+  } finally {
+    try {
+      await agent?.close?.();
+    } catch {
+      /* 探活用的 Agent 是一次性的，关不掉也不影响后续 */
+    }
+  }
+}

package/src/v6pool/report.js

@@ -0,0 +1,104 @@
+// v6pool · 日志文案（纯函数，零 IO）。
+//
+// 判据（ADR-0059）：**看完日志还需要的下一个命令，就是日志没写好的地方**。
+// 所以每一行都必须自带定位信息：哪个源地址、哪个前缀、第几次换、旧地址当时打了多少发什么状态。
+// 行首标记沿用 warp-pool/report.js 的 MARK（▸步骤 / ✓正常 / ✗失败 / ⚠警告）。
+export const MARK = { step: "▸", ok: "✓", fail: "✗", warn: "⚠" };
+const TAG = "[v6pool]";
+
+/** `{200: 3, 429: 1}` → `200×3 429×1`（按次数降序；空则"无响应"）。 */
+export function fmtCounts(counts = {}) {
+  const parts = Object.entries(counts)
+    .filter(([, n]) => Number(n) > 0)
+    .sort((a, b) => Number(b[1]) - Number(a[1]))
+    .map(([s, n]) => `${s}×${n}`);
+  return parts.length ? parts.join(" ") : "无响应";
+}
+
+export function fmtConfig(cfg = {}) {
+  return `${TAG} ${MARK.step} 配置 开关=${cfg.enabled ? "开" : "关"} 槽位=${cfg.count} 策略=${cfg.strategy} 换址=${cfg.rotate ? "开" : "关"} 认领=${cfg.claim} 冷却=${Math.round((cfg.cooldownMs || 0) / 1000)}s 退休=${Math.round((cfg.retireMs || 0) / 1000)}s 前缀=${cfg.prefix || "(自动判断)"}`;
+}
+
+export function fmtDisabled() {
+  return `${TAG} ${MARK.step} 出口池关着（MSLXDFF_V6_POOL=0）⇒ 请求走直连或 WARP 池`;
+}
+
+export function fmtDetect(d = {}) {
+  return `${TAG} ${MARK.step} 自检 网卡=${d.iface || "?"} 前缀=${d.prefix} 主机位=${d.hostBits}（可用地址 2^${d.hostBits}） 认领=${d.mode === "bind" ? "bind（ip_nonlocal_bind=1，不碰网卡）" : "add（root，ip addr add）"} 来源=${d.source}`;
+}
+
+export function fmtSkip({ reason = "", hint = "" } = {}) {
+  return `${TAG} ${MARK.fail} 出口池本次不启用（请求走直连）：${reason}｜下一步：${hint}`;
+}
+
+export function fmtClaim({ addr, iface }) {
+  return `${TAG} ${MARK.step} 认领源地址 ${addr}/128 dev ${iface} nodad（记进认领账，收摊时释放）`;
+}
+
+export function fmtClaimFail({ addr, iface, error }) {
+  return `${TAG} ${MARK.fail} 认领源地址失败 ${addr} dev ${iface}：${error}`;
+}
+
+export function fmtSweep({ iface, removed = [], failed = [] } = {}) {
+  const r = removed.length ? `删掉 ${removed.length} 个：${removed.slice(0, 4).join(" ")}${removed.length > 4 ? " …" : ""}` : "无";
+  const f = failed.length ? `｜失败 ${failed.length} 个：${failed.map((x) => `${x.addr}（${x.error}）`).join(" ")}` : "";
+  return `${TAG} ${MARK.step} 清上一代残留地址（dev ${iface}）：${r}${f}`;
+}
+
+export function fmtProbe({ addr, i, n, ok, status, ms, error }) {
+  return ok
+    ? `${TAG} ${MARK.step} 探活 ${i}/${n} 源=${addr} → HTTP ${status} ${ms}ms`
+    : `${TAG} ${MARK.warn} 探活 ${i}/${n} 源=${addr} → 失败 ${ms}ms ${error || `HTTP ${status}`}`;
+}
+
+export function fmtPool({ prefix, addrs = [], claimed, mode }) {
+  return `${TAG} ${MARK.ok} 出口池就绪：前缀 ${prefix}｜源地址 ${addrs.length} 个：${addrs.join(" ")}｜认领方式 ${mode}｜配额信号即换新地址（不重注册、不握手，成本≈0）`;
+}
+
+export function fmtPoolEmpty({ tried = 0 } = {}) {
+  return `${TAG} ${MARK.fail} 池里 ${tried} 个源地址**全部**探活失败（内核接受了地址，但整段没真路由到本机）⇒ 本次走直连。下一步：① 确认机房把整段路由到本机；② 或设 MSLXDFF_V6_POOL=0 恢复 WARP 池；③ 或 MSLXDFF_V6_PREFIX=<真正路由过来的段>/<位数>`;
+}
+
+export function fmtReadyFail({ error }) {
+  return `${TAG} ${MARK.fail} 建池过程出错，本次走直连：${error}`;
+}
+
+export function fmtSwap({ from, to, status, kind, forced, swaps, prevCounts }) {
+  return `${TAG} ${MARK.warn} 源 ${from} 上游 ${status} 判为「${kind}」⇒ 换源地址 ${to}（本槽第 ${swaps} 次${forced ? "，强制跳过冷却" : ""}；旧地址计数 ${fmtCounts(prevCounts)}）`;
+}
+
+export function fmtSwapFail({ addr, error }) {
+  return `${TAG} ${MARK.fail} 源 ${addr} 换址失败（该槽保持原地址，继续用）：${error}`;
+}
+
+export function fmtFirstOk({ addr, swaps, counts }) {
+  return swaps > 0
+    ? `${TAG} ${MARK.ok} 源 ${addr} 首个响应 200 ⇒ **换址后立刻恢复**（第 ${swaps} 次换址有效；新地址计数 ${fmtCounts(counts)}）`
+    : `${TAG} ${MARK.ok} 源 ${addr} 首个响应 200（池内地址工作正常）`;
+}
+
+export function fmtNoRotate({ addr, status, kind }) {
+  return `${TAG} ${MARK.warn} 源 ${addr} 上游 ${status}（${kind}）—— 换址开关关着（MSLXDFF_V6_ROTATE=0），不换源地址`;
+}
+
+export function fmtVerdictNo({ addr, status, kind, why }) {
+  return `${TAG} ${MARK.step} 源 ${addr} 上游 ${status} 判为「${kind}」⇒ 不换源地址：${why}`;
+}
+
+export function fmtRetire({ addr }) {
+  return `${TAG} ${MARK.step} 退休旧出口 ${addr}（关 Agent + 释放地址；留到最后是为让在飞请求走完）`;
+}
+
+export function fmtClose({ released = [] } = {}) {
+  return released.length
+    ? `${TAG} ${MARK.step} 收摊：释放源地址 ${released.length} 个：${released.join(" ")}`
+    : `${TAG} ${MARK.step} 收摊：没有需要释放的源地址（bind 模式不碰网卡）`;
+}
+
+export function fmtDispatch({ addr, session }) {
+  return `${TAG} · 源=${addr} 会话=${session}`;
+}
+
+export function fmtDirect({ reason }) {
+  return `${TAG} ${MARK.warn} 本次走直连：${reason}`;
+}

package/src/v6pool/rotate.js

@@ -0,0 +1,239 @@
+// v6pool · 槽位 dispatcher：每槽一个源地址 + 一个自带 `localAddress` 的 undici Agent。
+//
+// 契约与 warp-pool 的轮换 dispatcher 一致：`dispatch(opts, handler)` + `close()`，
+// 注入点同为 `transport` 的 extDispatcher（legacy 与 SDK 两条路共用同一个对象，见 MODULES.md §1）。
+//
+// 与 WARP 池的差别只在「换出口」这一步：
+//   WARP：重注册设备 + 重启隧道（实测 5~8 秒，还会被 CF 注册限流）
+//   v6  ：从前缀里挑一个新地址（≈0 成本：只多一条 `ip addr add`，bind 模式下连这条都省）
+// 判决表照旧复用 warp-pool/verdict.js（403 FreeTierError 与 429 FreeUsageLimitError 同一条件 ⇒ 强制换）。
+//
+// 两个刻意的设计：
+//   ① 换址**不重置**旧槽的冷却账，而是把旧地址推进 retiring：先关旧 Agent、延后释放地址，
+//      在飞请求（SSE 长连接）不会因为源地址被抽走而断。retiring 有硬上限 RETAIN_MAX。
+//   ② 每次响应都记账（不只 403/429）：`fmtFirstOk` 那行「新地址首个 200」就是
+//      「429 换 IP 到底有没有换来新额度」的直接证据——这正是本次要回答的问题。
+import { getUndici } from "../compat.js";
+import { headerValue, tapHandler } from "../warp-pool/rotate.js";
+import { createSelector } from "../warp-pool/strategy.js";
+import { SIGNAL_STATUSES, classifyWarpSignal } from "../warp-pool/verdict.js";
+import { fmtDirect, fmtDispatch, fmtFirstOk, fmtNoRotate, fmtRetire, fmtSwap, fmtSwapFail, fmtVerdictNo } from "./report.js";
+
+const SESSION_HEADER = "x-opencode-session";
+
+/** 最多留几个「已换下但地址还在网卡上」的旧出口：保护在飞请求，同时给地址数量一个硬上限。 */
+export const RETAIN_MAX = 8;
+/** 挑新地址时最多重试几次（前缀太小/已在用的地址太多时会一直撞）。 */
+export const PICK_TRIES = 16;
+
+/**
+ * @param {{ addrs?: string[], strategy?: "session"|"request", retireMs?: number, rotate?: boolean, debug?: boolean,
+ *           now?: () => number, log?: (s: string) => void, claimer?: object|null, pickAddress?: () => string,
+ *           agentFactory?: (addr: string) => object, agentOptions?: object, fallbackAgent?: object, selector?: object }} [opts]
+ */
+export function createV6Dispatcher({
+  addrs = [],
+  strategy = "session",
+  retireMs = 60_000,
+  rotate = true,
+  debug = false,
+  now = Date.now,
+  log = () => {},
+  claimer = null,
+  pickAddress = () => "",
+  agentFactory,
+  agentOptions = { connections: 4, pipelining: 1, keepAliveTimeout: 30_000, keepAliveMaxTimeout: 60_000 },
+  fallbackAgent,
+  selector = createSelector({ strategy }),
+} = {}) {
+  const { Agent } = getUndici();
+  if (typeof agentFactory !== "function") {
+    if (typeof Agent !== "function") throw new Error("undici Agent 不可用：无法建立 v6 出口池");
+    agentFactory = (addr) => new Agent({ connect: { localAddress: addr }, ...agentOptions });
+  }
+  const fallback = fallbackAgent !== undefined ? fallbackAgent : typeof Agent === "function" ? new Agent(agentOptions) : null;
+
+  let list = [];
+  /** @type {Array<{addr:string, agent:object, at:number, release:null|Function, counts:object, swaps:number}>} */
+  const retiring = [];
+  const history = [];
+  let directWarned = false;
+
+  function buildSlot(index, addr) {
+    return { index, addr, agent: agentFactory(addr), cooldownUntil: 0, swaps: 0, swapping: false, counts: {}, firstOkAt: 0 };
+  }
+
+  /** 装上源地址（bootstrap 探活通过后调用；空数组 = 池为空 ⇒ 直连兜底）。 */
+  function setAddresses(next = []) {
+    list = (next || []).map((a, i) => buildSlot(i, a));
+    return list.length;
+  }
+  // 构造时就装上地址（与 warp-pool 的轮换 dispatcher 同形状：入参即初始池）。
+  setAddresses(addrs);
+
+  function availableIndexes() {
+    const t = now();
+    return list.filter((e) => e.cooldownUntil <= t && !e.swapping).map((e) => e.index);
+  }
+
+  /** 退休账结算：只有「已过退休时长」且「超出保留上限」的才真关+真释放（close 时 force 全清）。 */
+  async function flushRetired({ force = false } = {}) {
+    const sorted = [...retiring].sort((a, b) => a.at - b.at);
+    const over = Math.max(0, sorted.length - RETAIN_MAX);
+    const keep = [];
+    for (let i = 0; i < sorted.length; i++) {
+      const r = sorted[i];
+      const aged = now() - r.at >= retireMs;
+      if (!force && !(aged && i < over)) {
+        keep.push(r);
+        continue;
+      }
+      try {
+        await r.agent?.close?.();
+      } catch {
+        /* 关不掉旧 Agent 不影响新出口 */
+      }
+      if (r.release) {
+        try {
+          await r.release();
+        } catch {
+          /* 释放失败已由 claim.js 自己打日志 */
+        }
+      }
+      history.push({ addr: r.addr, swaps: r.swaps, counts: { ...r.counts } });
+      if (history.length > 32) history.shift();
+      log(fmtRetire({ addr: r.addr }));
+    }
+    retiring.length = 0;
+    retiring.push(...keep);
+  }
+
+  /** 换该槽的源地址：挑新地址 → 认领 → 建新 Agent → 旧 Agent 退休（先关 Agent 再延后释放地址）。 */
+  async function swap(index, verdict = {}) {
+    const e = list[index];
+    if (!e) return { skipped: true };
+    if (e.swapping) return { skipped: true, reason: "该槽已在换址中" };
+    e.swapping = true;
+    try {
+      const taken = new Set(list.map((s) => s.addr));
+      let addr = "";
+      for (let i = 0; i < PICK_TRIES && (!addr || taken.has(addr)); i++) addr = pickAddress();
+      if (!addr || taken.has(addr)) throw new Error(`前缀里连续 ${PICK_TRIES} 次都撞上已在用的地址（前缀太小？）`);
+      if (claimer) await claimer.ensure(addr);
+      const oldAddr = e.addr;
+      const prevCounts = { ...e.counts };
+      const prevSwaps = e.swaps;
+      retiring.push({
+        addr: oldAddr,
+        agent: e.agent,
+        at: now(),
+        release: claimer ? () => claimer.release(oldAddr) : null,
+        counts: prevCounts,
+        swaps: prevSwaps,
+      });
+      e.addr = addr;
+      e.agent = agentFactory(addr);
+      e.cooldownUntil = 0;
+      e.swaps = prevSwaps + 1;
+      e.counts = {};
+      e.firstOkAt = 0;
+      log(fmtSwap({ from: oldAddr, to: addr, status: verdict.status, kind: verdict.kind, forced: verdict.forced, swaps: e.swaps, prevCounts }));
+      await flushRetired();
+      return { ok: true, from: oldAddr, to: addr };
+    } finally {
+      e.swapping = false;
+    }
+  }
+
+  /** 上游响应旁听：记账 → 换址后首个 200 的取证行 → 配额信号才换址。 */
+  function onTap(signal, e) {
+    const status = Number(signal?.status);
+    e.counts[status] = (e.counts[status] || 0) + 1;
+    if (status === 200 && !e.firstOkAt) {
+      e.firstOkAt = now();
+      log(fmtFirstOk({ addr: e.addr, swaps: e.swaps, counts: e.counts }));
+    }
+    if (!SIGNAL_STATUSES.includes(status)) return;
+    const v = classifyWarpSignal(signal);
+    if (!rotate) {
+      log(fmtNoRotate({ addr: e.addr, status, kind: v.kind }));
+      return;
+    }
+    if (!v.rotate) {
+      log(fmtVerdictNo({ addr: e.addr, status, kind: v.kind, why: v.why }));
+      return;
+    }
+    const addr = e.addr;
+    void swap(e.index, { ...v, status }).catch((err) => log(fmtSwapFail({ addr, error: String(err?.message || err) })));
+  }
+
+  return {
+    /** 每次请求调一次 = 选槽粒度（session 策略下同会话粘同一源地址）。 */
+    dispatch(opts, handler) {
+      if (!list.length) {
+        if (fallback) return fallback.dispatch(opts, handler);
+        throw new Error("v6pool：源地址池为空且无直连兜底");
+      }
+      const avail = availableIndexes();
+      if (!avail.length) {
+        // 全池都在冷却/换址中 ⇒ 直连兜底优先：硬派给正在换址的槽 = 把请求挂到超时
+        if (!directWarned) {
+          directWarned = true;
+          log(fmtDirect({ reason: `全部 ${list.length} 个源地址都在冷却/换址中（下一条恢复后自动回到池内）` }));
+        }
+        return (fallback || list[0].agent).dispatch(opts, handler);
+      }
+      directWarned = false;
+      const sessionKey = strategy === "session" ? headerValue(opts?.headers, SESSION_HEADER) : "";
+      const e = list[selector.pick(avail, sessionKey)];
+      if (debug) log(fmtDispatch({ addr: e.addr, session: sessionKey || "(无)" }));
+      return e.agent.dispatch(opts, tapHandler(handler, (sig) => onTap(sig, e)));
+    },
+
+    setAddresses,
+
+    /** 手动换某个槽的源地址（供运维/测试；正常路径由配额信号触发）。 */
+    swap,
+
+    /** 只读快照（含已退休出口的最终计数——"换址到底有没有换来新额度"看这里）。 */
+    stats() {
+      const t = now();
+      return {
+        slots: list.map((e) => ({ addr: e.addr, cooling: e.cooldownUntil > t, swaps: e.swaps, swapping: e.swapping, counts: { ...e.counts }, firstOk: !!e.firstOkAt })),
+        history: history.map((h) => ({ ...h, counts: { ...h.counts } })),
+      };
+    },
+
+    entries() {
+      return list.map((e) => ({ index: e.index, addr: e.addr, cooldownUntil: e.cooldownUntil, swaps: e.swaps }));
+    },
+
+    async close() {
+      const slots = list;
+      list = [];
+      for (const e of slots) {
+        try {
+          await e.agent?.close?.();
+        } catch {
+          /* 收摊时关不掉就算了 */
+        }
+      }
+      await flushRetired({ force: true });
+      if (fallback) {
+        try {
+          await fallback.close?.();
+        } catch {
+          /* 同上 */
+        }
+      }
+    },
+
+    async destroy() {
+      return this.close();
+    },
+
+    get size() {
+      return list.length;
+    },
+  };
+}

package/src/warp-pool/report.js

@@ -115,25 +115,37 @@ export function fmtPool({ pooled, total, exits }) {
 }
 
 /**
- * 身份指纹：每个端口的短设备 id / WARP 内网地址 / 对端端点 / 注册时间。
+ * 身份指纹：每个端口的短设备 id / WARP 内网 IPv6 尾段 / 对端端点 / 注册时间。
  * 为什么必须有：4 条隧道只拿到 2 个出口地址时（真机 2026-10-17），只有这组读数能区分
- * 「设备本身被写重复了」和「CF 的共享 NAT 把不同设备折叠成一个出口」——没有它就只能猜。
+ * 「设备本身被写重复了」和「CF 把不同设备折叠成一个出口」——没有它就只能猜。
+ *
+ * ⚠ 判据**不看 IPv4**：`172.16.0.2` 是 WARP 的**固定接口地址**（6 次实测全是它：组长 4 台 +
+ * 本机 2 台；公开的 wgcf 生成配置里同样是 `Address = 172.16.0.2/32`），按它判「重复」是误报
+ * （2026-10-17 十一次修订前确实这么误报过）。每台设备真正唯一的是 **IPv6**（`2606:4700:110:…`）
+ * 与密钥对，所以指纹打 v6 尾段。
  */
+/** v6 尾段做指纹（`2606:4700:110:81b5:56ec:72b3:9542:e3de` → `…:9542:e3de`）；缺了给「无」。 */
+export function v6Tail(v6) {
+  const s = String(v6 || "");
+  if (!s) return "无";
+  const parts = s.split(":");
+  return parts.length > 2 ? `…:${parts.slice(-2).join(":")}` : s;
+}
 export function fmtIdentityDetail(nodes = []) {
   const out = [];
   const byId = new Map();
-  const byV4 = new Map();
+  const byEp = new Map();
   for (const n of nodes || []) {
     if (n?.id) byId.set(n.id, [...(byId.get(n.id) || []), n.port]);
-    if (n?.v4) byV4.set(n.v4, [...(byV4.get(n.v4) || []), n.port]);
-    out.push(`[warp-pool]     :${n?.port} 设备=${n?.id ? String(n.id).slice(0, 8) : "无id"} 内网=${n?.v4 || "无"} 端点=${n?.endpoint || "?"} 注册=${String(n?.registeredAt || "?").slice(0, 19)}`);
+    if (n?.endpoint) byEp.set(n.endpoint, [...(byEp.get(n.endpoint) || []), n.port]);
+    out.push(`[warp-pool]     :${n?.port} 设备=${n?.id ? String(n.id).slice(0, 8) : "无id"} 内网v6=${v6Tail(n?.v6)} 端点=${n?.endpoint || "?"} 注册=${String(n?.registeredAt || "?").slice(0, 19)}`);
   }
-  // cut 只给设备 id 用（UUID 太长）：内网地址必须原样打，截短了就成了「172.16.0」
-  const dups = (m, cut = 0) => [...m.entries()].filter(([, p]) => p.length > 1).map(([k, p]) => `${cut ? String(k).slice(0, cut) : String(k)} ← :${p.join(",:")}`).join("；");
-  const dupId = dups(byId, 8);
-  const dupV4 = dups(byV4);
+  const dupId = [...byId.entries()].filter(([, p]) => p.length > 1).map(([k, p]) => `${String(k).slice(0, 8)} ← :${p.join(",:")}`).join("；");
   if (dupId) out.push(`[warp-pool] ${MARK.warn} 设备 id 重复：${dupId} —— 同一个 WARP 设备被写到多个端口，出口必然相同；删掉重复端口的 node-<port>.json 再重启，它会重新注册`);
-  if (dupV4) out.push(`[warp-pool] ${MARK.warn} WARP 内网地址重复：${dupV4} —— 同一内网地址必是同一出口`);
+  // 端点全同 = 大家都从同一个 CF 入口出去（CF 对每次注册都回同一个 hostname）：出口撞车由此而来
+  const total = (nodes || []).length;
+  const sameEp = [...byEp.entries()].find(([, p]) => total > 1 && p.length === total);
+  if (sameEp) out.push(`[warp-pool] ${MARK.step} ${total} 条隧道都用同一个端点（${sameEp[0]}）—— CF 对每次注册都回同一个 hostname，故大家都从同一个 CF 入口出去，出口地址撞车由此而来（想分散：把 node-<port>.json 的 endpoint 改成别的 WARP 入口 IP 后重启）`);
   return out;
 }