mslxdff 0.1.199 → 0.1.203

package/src/v6pool/detect.js

@@ -1,130 +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",
-  });
-}
+// 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

@@ -1,152 +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 });
-}
-
+// 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 });
+}
+