mslxdff 0.1.203 → 0.1.207

package/src/warp-pool/verdict.js

@@ -1,69 +1,69 @@
-// warp-pool · 上游失败信号的「换不换出口」判决（纯函数，零 IO）。
-//
-// 判据逐字对齐参照实现 kyomufs/zen-router：
-//   - internal/zen/errors.go 的 Kind 分类表（哪些错误算「按出口 IP 计的限额」）；
-//   - internal/router/stage.go 的 NextAttempt 决策表（每种 Kind 该换什么、要不要绕过冷却）。
-//
-// 立此模块的原因（2026-10-17 十次修订）：我原先只在 rotate.js 的 onStatus 里认 `status === 429`，
-// 漏掉了参照实现表里**最重要的一格**——`403 FreeTierError` 与 `429 FreeUsageLimitError` 是
-// **同一个条件的两种状态码**（上游按自己的窗口状态二选一，文案完全相同）。参照实现实测：
-// 同一身份连发 3 次 429，**身份一换同一个请求立刻 200**（errors.go:32-42）；
-// 而它最初把 403 当通用 403 不重试，代价是整轮请求直接死掉（errors.go:50-61 记录得很清楚）。
-// 我这边更糟：`terminal-verdict.js` 把 FreeTierError 判成**终局**（跳过接力），
-// warp-pool 又只认 429 ⇒ **403 FreeTierError 从来没有任何换出口动作**。
-//
-// 反向护栏同样照抄：`BlackUsageLimitError` 是真正的**账号日配额**，换出口抬不动，
-// 参照实现明确「绝不旋转身份」（stage.go:125-128、errors.go:28-31）；换 key 才是它的正解。
-// 裸 403（正文没有 FreeTier 判决）也不旋转：参照实现的 kindByStatus 把 403 归为
-// KindClient（不可重试），换出口对形状/区域/凭据类 403 毫无用处。
-//
-// 读不到正文时的退路也照抄 kindByStatus：429 → 当出口 IP 限流（换）；403 → 不换。
-
-/** 上游失败正文里判定免费层资格的具名判决（与 terminal-verdict.js 的 FREE_TIER_PATTERNS 同源口径）。 */
-const FREE_TIER_RE = /FreeTierError|free tier can only be used/i;
-/** 匿名免费层 429（参照实现实测：按出口 IP 计，换身份即换桶）。 */
-const FREE_QUOTA_RE = /FreeUsageLimitError|GoUsageLimitError/i;
-/** 黑名单层：真账号日配额，换出口抬不动。 */
-const BLACK_QUOTA_RE = /BlackUsageLimitError/i;
-
-/** 只这两类状态码参与判决；其余（含 200）一律不参与、也不许刷日志。 */
-export const SIGNAL_STATUSES = [403, 429];
-
-/** 正文捕获上限（判据只需要文案里的类名，2KB 足够，且防大 body 拖成慢扫描）。 */
-export const SIGNAL_MAX_BYTES = 2048;
-
-/** 正文里出现了具名判决（供 tapHandler 一凑够就提前判决，不必等整条 body 读完）。 */
-export function looksLikeQuotaSignal(text) {
-  const t = typeof text === "string" ? text : "";
-  return FREE_TIER_RE.test(t) || FREE_QUOTA_RE.test(t) || BLACK_QUOTA_RE.test(t);
-}
-
-/**
- * 一次上游失败该不该换出口。
- * @param {{ status?: number, text?: string }} signal 上游状态码 + 正文（≤ SIGNAL_MAX_BYTES；读不到给空串）
- * @returns {{ kind: "free-tier"|"free-quota"|"black-quota"|"ip-limit"|"none", rotate: boolean,
- *            forced: boolean, why: string }}
- *   forced=true 表示必须**跳过**冷却（参照实现的 RotateForced：冷却曾把第一次真实反应吞掉，
- *   于是重试复用了同一个已限额的出口 —— stage.go:315-324）。
- */
-export function classifyWarpSignal({ status, text = "" } = {}) {
-  const code = Number(status);
-  const body = typeof text === "string" ? text : "";
-  if (!SIGNAL_STATUSES.includes(code)) {
-    return { kind: "none", rotate: false, forced: false, why: `上游 ${code || "?"} 不是 403/429，与出口限额无关` };
-  }
-  // 顺序即优先级，照抄 errors.go 的 classify()：先认正文里的具名判决，再退回状态码。
-  if (BLACK_QUOTA_RE.test(body)) {
-    return { kind: "black-quota", rotate: false, forced: false, why: "BlackUsageLimitError 是真正的账号日配额，换出口抬不动（参照实现同样绝不旋转）——该换 key，不是换 IP" };
-  }
-  if (FREE_TIER_RE.test(body)) {
-    return { kind: "free-tier", rotate: true, forced: true, why: "403 FreeTierError 与 429 FreeUsageLimitError 是同一条件的两种状态码；参照实现实测换身份后同一个请求立刻 200 ⇒ 强制换出口，跳过冷却" };
-  }
-  if (FREE_QUOTA_RE.test(body)) {
-    return { kind: "free-quota", rotate: true, forced: true, why: "匿名免费层 429 实测是**按出口 IP** 计的限额（同一身份连发 3 次全 429，换身份立刻 200）⇒ 强制换出口，跳过冷却" };
-  }
-  if (code === 429) {
-    return { kind: "ip-limit", rotate: true, forced: false, why: "裸 429（正文无配额判决）= 出口 IP 限流信号 ⇒ 换出口；保留冷却，防 429 风暴把 CF 注册刷爆" };
-  }
-  return { kind: "none", rotate: false, forced: false, why: "403 但正文没有 FreeTier 判决 ⇒ 不是配额信号（形状/区域/凭据类），换出口无用" };
-}
+// warp-pool · 上游失败信号的「换不换出口」判决（纯函数，零 IO）。
+//
+// 判据逐字对齐参照实现 kyomufs/zen-router：
+//   - internal/zen/errors.go 的 Kind 分类表（哪些错误算「按出口 IP 计的限额」）；
+//   - internal/router/stage.go 的 NextAttempt 决策表（每种 Kind 该换什么、要不要绕过冷却）。
+//
+// 立此模块的原因（2026-10-17 十次修订）：我原先只在 rotate.js 的 onStatus 里认 `status === 429`，
+// 漏掉了参照实现表里**最重要的一格**——`403 FreeTierError` 与 `429 FreeUsageLimitError` 是
+// **同一个条件的两种状态码**（上游按自己的窗口状态二选一，文案完全相同）。参照实现实测：
+// 同一身份连发 3 次 429，**身份一换同一个请求立刻 200**（errors.go:32-42）；
+// 而它最初把 403 当通用 403 不重试，代价是整轮请求直接死掉（errors.go:50-61 记录得很清楚）。
+// 我这边更糟：`terminal-verdict.js` 把 FreeTierError 判成**终局**（跳过接力），
+// warp-pool 又只认 429 ⇒ **403 FreeTierError 从来没有任何换出口动作**。
+//
+// 反向护栏同样照抄：`BlackUsageLimitError` 是真正的**账号日配额**，换出口抬不动，
+// 参照实现明确「绝不旋转身份」（stage.go:125-128、errors.go:28-31）；换 key 才是它的正解。
+// 裸 403（正文没有 FreeTier 判决）也不旋转：参照实现的 kindByStatus 把 403 归为
+// KindClient（不可重试），换出口对形状/区域/凭据类 403 毫无用处。
+//
+// 读不到正文时的退路也照抄 kindByStatus：429 → 当出口 IP 限流（换）；403 → 不换。
+
+/** 上游失败正文里判定免费层资格的具名判决（与 terminal-verdict.js 的 FREE_TIER_PATTERNS 同源口径）。 */
+const FREE_TIER_RE = /FreeTierError|free tier can only be used/i;
+/** 匿名免费层 429（参照实现实测：按出口 IP 计，换身份即换桶）。 */
+const FREE_QUOTA_RE = /FreeUsageLimitError|GoUsageLimitError/i;
+/** 黑名单层：真账号日配额，换出口抬不动。 */
+const BLACK_QUOTA_RE = /BlackUsageLimitError/i;
+
+/** 只这两类状态码参与判决；其余（含 200）一律不参与、也不许刷日志。 */
+export const SIGNAL_STATUSES = [403, 429];
+
+/** 正文捕获上限（判据只需要文案里的类名，2KB 足够，且防大 body 拖成慢扫描）。 */
+export const SIGNAL_MAX_BYTES = 2048;
+
+/** 正文里出现了具名判决（供 tapHandler 一凑够就提前判决，不必等整条 body 读完）。 */
+export function looksLikeQuotaSignal(text) {
+  const t = typeof text === "string" ? text : "";
+  return FREE_TIER_RE.test(t) || FREE_QUOTA_RE.test(t) || BLACK_QUOTA_RE.test(t);
+}
+
+/**
+ * 一次上游失败该不该换出口。
+ * @param {{ status?: number, text?: string }} signal 上游状态码 + 正文（≤ SIGNAL_MAX_BYTES；读不到给空串）
+ * @returns {{ kind: "free-tier"|"free-quota"|"black-quota"|"ip-limit"|"none", rotate: boolean,
+ *            forced: boolean, why: string }}
+ *   forced=true 表示必须**跳过**冷却（参照实现的 RotateForced：冷却曾把第一次真实反应吞掉，
+ *   于是重试复用了同一个已限额的出口 —— stage.go:315-324）。
+ */
+export function classifyWarpSignal({ status, text = "" } = {}) {
+  const code = Number(status);
+  const body = typeof text === "string" ? text : "";
+  if (!SIGNAL_STATUSES.includes(code)) {
+    return { kind: "none", rotate: false, forced: false, why: `上游 ${code || "?"} 不是 403/429，与出口限额无关` };
+  }
+  // 顺序即优先级，照抄 errors.go 的 classify()：先认正文里的具名判决，再退回状态码。
+  if (BLACK_QUOTA_RE.test(body)) {
+    return { kind: "black-quota", rotate: false, forced: false, why: "BlackUsageLimitError 是真正的账号日配额，换出口抬不动（参照实现同样绝不旋转）——该换 key，不是换 IP" };
+  }
+  if (FREE_TIER_RE.test(body)) {
+    return { kind: "free-tier", rotate: true, forced: true, why: "403 FreeTierError 与 429 FreeUsageLimitError 是同一条件的两种状态码；参照实现实测换身份后同一个请求立刻 200 ⇒ 强制换出口，跳过冷却" };
+  }
+  if (FREE_QUOTA_RE.test(body)) {
+    return { kind: "free-quota", rotate: true, forced: true, why: "匿名免费层 429 实测是**按出口 IP** 计的限额（同一身份连发 3 次全 429，换身份立刻 200）⇒ 强制换出口，跳过冷却" };
+  }
+  if (code === 429) {
+    return { kind: "ip-limit", rotate: true, forced: false, why: "裸 429（正文无配额判决）= 出口 IP 限流信号 ⇒ 换出口；保留冷却，防 429 风暴把 CF 注册刷爆" };
+  }
+  return { kind: "none", rotate: false, forced: false, why: "403 但正文没有 FreeTier 判决 ⇒ 不是配额信号（形状/区域/凭据类），换出口无用" };
+}

package/src/warp-pool/wireproxy.js

@@ -1,162 +1,162 @@
-// warp-pool · wireproxy 进程管理：取二进制 → 生成配置 → 启动 → 守护/销毁。
-// wireproxy（octeep/wireproxy，Go，用户态 WireGuard，无需 root/TUN）把 WARP 隧道暴露为本地 HTTP 代理。
-// 为什么是 [http] 而非 [Socks5]：项目 undici 为 v5（实测 5.29.0），其 ProxyAgent 只接受 http/https，
-// 「SOCKS5 支持」是 undici 后续版本才加的（实测 socks5:// 直接抛 Invalid URL protocol）。
-import { spawn } from "node:child_process";
-import { chmodSync, existsSync, createWriteStream, readdirSync, rmSync } from "node:fs";
-import { join } from "node:path";
-import { pipeline } from "node:stream/promises";
-import { compatFetch, getUndici } from "../compat.js";
-import { ensureDir, nodePaths, renderWireproxyConf, writeSecret } from "./nodes.js";
-
-export const WIREPROXY_VERSION = "v1.1.3";
-const RELEASE_BASE = "https://github.com/octeep/wireproxy/releases/download";
-
-const ASSETS = {
-  "linux-x64": "wireproxy_linux_amd64.tar.gz",
-  "linux-arm64": "wireproxy_linux_arm64.tar.gz",
-  "darwin-x64": "wireproxy_darwin_amd64.tar.gz",
-  "darwin-arm64": "wireproxy_darwin_arm64.tar.gz",
-};
-
-/** 依平台选发布包；不支持的平台返回 null（改用 MSLXDFF_WARP_BIN 自备二进制）。 */
-export function resolveAsset(platform = process.platform, arch = process.arch) {
-  const key = `${platform}-${arch}`;
-  return ASSETS[key] || null;
-}
-
-/** 本地二进制路径（bin/ 下按平台固定名）。 */
-export function binaryPath(dir) {
-  return join(dir, "bin", process.platform === "win32" ? "wireproxy.exe" : "wireproxy");
-}
-
-/**
- * 确保 wireproxy 可用：优先 env 指定 → 本地已下载 → 自动下载解包。
- * @returns {Promise<string>} 可执行文件绝对路径
- */
-export async function ensureBinary({ dir, bin = "", autodownload = true, fetchImpl = compatFetch, log = () => {}, platform = process.platform, arch = process.arch } = {}) {
-  if (bin) {
-    if (!existsSync(bin)) throw new Error(`MSLXDFF_WARP_BIN 指向的文件不存在：${bin}`);
-    return bin;
-  }
-  const local = binaryPath(dir);
-  if (existsSync(local)) return local;
-
-  if (!autodownload) throw new Error(`未找到 wireproxy（${local}），且已关闭自动下载：请设 MSLXDFF_WARP_BIN 或开启 MSLXDFF_WARP_AUTODOWNLOAD`);
-  const asset = resolveAsset(platform, arch);
-  if (!asset) throw new Error(`暂不支持自动下载 wireproxy（平台 ${platform}-${arch}）：请自备二进制并设 MSLXDFF_WARP_BIN`);
-
-  ensureDir(join(dir, "bin"));
-  const url = `${RELEASE_BASE}/${WIREPROXY_VERSION}/${asset}`;
-  const tarball = join(dir, "bin", asset);
-  log(`[warp-pool] 下载 wireproxy ${WIREPROXY_VERSION}（${asset}）`);
-  const res = await fetchImpl(url, { signal: AbortSignal.timeout(120_000) });
-  if (!res.ok) throw new Error(`下载 wireproxy 失败：HTTP ${res.status}`);
-  await pipeline(res.body, createWriteStream(tarball));
-
-  // 解包用系统 tar（Linux/macOS 必带；不引入 npm 依赖去解析 tar 格式）。
-  await runCommand("tar", ["-xzf", tarball, "-C", join(dir, "bin")], { log });
-  try { rmSync(tarball, { force: true }); } catch {}
-
-  const extracted = findWireproxy(join(dir, "bin"));
-  if (!extracted) throw new Error(`解包后未找到 wireproxy 可执行文件（目录：${join(dir, "bin")}）`);
-  if (extracted !== local) {
-    try { chmodSync(extracted, 0o755); } catch {}
-  }
-  try { chmodSync(local, 0o755); } catch {}
-  return existsSync(local) ? local : extracted;
-}
-
-function findWireproxy(binDir) {
-  try {
-    const hit = readdirSync(binDir).find((f) => f === "wireproxy" || f === "wireproxy.exe");
-    return hit ? join(binDir, hit) : null;
-  } catch {
-    return null;
-  }
-}
-
-function runCommand(cmd, args, { log = () => {} } = {}) {
-  return new Promise((resolve, reject) => {
-    let err = "";
-    const p = spawn(cmd, args, { stdio: ["ignore", "ignore", "pipe"] });
-    p.stderr.on("data", (d) => { err += String(d); });
-    p.on("error", reject);
-    p.on("close", (code) => {
-      if (code === 0) resolve();
-      else reject(new Error(`${cmd} 退出码 ${code}${err ? `：${err.slice(0, 200)}` : ""}`));
-    });
-  });
-}
-
-/** 写出某节点的 wireproxy 配置（含私钥 ⇒ 0600）。 */
-export function writeTunnelConf(dir, node) {
-  if (!node?.privateKey) throw new Error(`节点 :${node?.port} 缺 WireGuard 私钥，拒绝写出一份跑不起来的配置`);
-  const { conf } = nodePaths(dir, node.port);
-  const text = renderWireproxyConf({ ...node, port: node.port });
-  writeSecret(conf, text);
-  return { conf, bytes: Buffer.byteLength(text) };
-}
-
-/**
- * 启动一条隧道。返回 { port, conf, stop() }。
- * 进程退出即视为隧道失效（不自动重启：由 health 层决策重拨换 IP）。
- */
-export function startTunnel({ binPath: exe, dir, port, log = () => {}, onExit = () => {}, now = Date.now } = {}) {
-  const { conf } = nodePaths(dir, port);
-  const child = spawn(exe, ["-c", conf], { stdio: ["ignore", "pipe", "pipe"] });
-  const startedAt = now();
-  let tail = "";
-  const keepTail = (d) => {
-    tail = (tail + String(d)).slice(-800);
-  };
-  child.stdout.on("data", keepTail);
-  child.stderr.on("data", keepTail);
-
-  let stopped = false;
-  child.on("exit", (code, signal) => {
-    if (!stopped) onExit({ port, code, signal, tail, pid: child.pid, aliveMs: now() - startedAt });
-  });
-
-  return {
-    port,
-    conf,
-    get pid() {
-      return child.pid;
-    },
-    get alive() {
-      return !stopped && child.exitCode === null;
-    },
-    get tail() {
-      return tail;
-    },
-    stop() {
-      if (stopped) return;
-      stopped = true;
-      try { child.kill("SIGTERM"); } catch {}
-    },
-  };
-}
-
-/** 探活一个已起的隧道：经该端口访问上游 models 路径（不烧 token）。 */
-export async function probeTunnel({ port, baseUrl = "https://opencode.ai", path = "/zen/v1/models", fetchImpl = compatFetch, timeoutMs = 8000, headers = {}, wantText = false } = {}) {
-  const { ProxyAgent } = getUndici();
-  const agent = new ProxyAgent({ uri: `http://127.0.0.1:${port}`, connections: 2, keepAliveTimeout: 10_000 });
-  const url = `${String(baseUrl).replace(/\/+$/, "")}${path}`;
-  const t0 = Date.now();
-  try {
-    const res = await fetchImpl(url, {
-      headers,
-      signal: AbortSignal.timeout(timeoutMs),
-      dispatcher: agent,
-    });
-    const base = { ok: res.ok, status: res.status, ms: Date.now() - t0, url };
-    if (!wantText) return base;
-    const text = await res.text().catch(() => "");
-    return { ...base, text: String(text).slice(0, 2000) };
-  } catch (e) {
-    return { ok: false, status: 0, error: String(e?.message || e), ms: Date.now() - t0, url };
-  } finally {
-    try { await agent.close(); } catch {}
-  }
-}
+// warp-pool · wireproxy 进程管理：取二进制 → 生成配置 → 启动 → 守护/销毁。
+// wireproxy（octeep/wireproxy，Go，用户态 WireGuard，无需 root/TUN）把 WARP 隧道暴露为本地 HTTP 代理。
+// 为什么是 [http] 而非 [Socks5]：项目 undici 为 v5（实测 5.29.0），其 ProxyAgent 只接受 http/https，
+// 「SOCKS5 支持」是 undici 后续版本才加的（实测 socks5:// 直接抛 Invalid URL protocol）。
+import { spawn } from "node:child_process";
+import { chmodSync, existsSync, createWriteStream, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { compatFetch, getUndici } from "../compat.js";
+import { ensureDir, nodePaths, renderWireproxyConf, writeSecret } from "./nodes.js";
+
+export const WIREPROXY_VERSION = "v1.1.3";
+const RELEASE_BASE = "https://github.com/octeep/wireproxy/releases/download";
+
+const ASSETS = {
+  "linux-x64": "wireproxy_linux_amd64.tar.gz",
+  "linux-arm64": "wireproxy_linux_arm64.tar.gz",
+  "darwin-x64": "wireproxy_darwin_amd64.tar.gz",
+  "darwin-arm64": "wireproxy_darwin_arm64.tar.gz",
+};
+
+/** 依平台选发布包；不支持的平台返回 null（改用 MSLXDFF_WARP_BIN 自备二进制）。 */
+export function resolveAsset(platform = process.platform, arch = process.arch) {
+  const key = `${platform}-${arch}`;
+  return ASSETS[key] || null;
+}
+
+/** 本地二进制路径（bin/ 下按平台固定名）。 */
+export function binaryPath(dir) {
+  return join(dir, "bin", process.platform === "win32" ? "wireproxy.exe" : "wireproxy");
+}
+
+/**
+ * 确保 wireproxy 可用：优先 env 指定 → 本地已下载 → 自动下载解包。
+ * @returns {Promise<string>} 可执行文件绝对路径
+ */
+export async function ensureBinary({ dir, bin = "", autodownload = true, fetchImpl = compatFetch, log = () => {}, platform = process.platform, arch = process.arch } = {}) {
+  if (bin) {
+    if (!existsSync(bin)) throw new Error(`MSLXDFF_WARP_BIN 指向的文件不存在：${bin}`);
+    return bin;
+  }
+  const local = binaryPath(dir);
+  if (existsSync(local)) return local;
+
+  if (!autodownload) throw new Error(`未找到 wireproxy（${local}），且已关闭自动下载：请设 MSLXDFF_WARP_BIN 或开启 MSLXDFF_WARP_AUTODOWNLOAD`);
+  const asset = resolveAsset(platform, arch);
+  if (!asset) throw new Error(`暂不支持自动下载 wireproxy（平台 ${platform}-${arch}）：请自备二进制并设 MSLXDFF_WARP_BIN`);
+
+  ensureDir(join(dir, "bin"));
+  const url = `${RELEASE_BASE}/${WIREPROXY_VERSION}/${asset}`;
+  const tarball = join(dir, "bin", asset);
+  log(`[warp-pool] 下载 wireproxy ${WIREPROXY_VERSION}（${asset}）`);
+  const res = await fetchImpl(url, { signal: AbortSignal.timeout(120_000) });
+  if (!res.ok) throw new Error(`下载 wireproxy 失败：HTTP ${res.status}`);
+  await pipeline(res.body, createWriteStream(tarball));
+
+  // 解包用系统 tar（Linux/macOS 必带；不引入 npm 依赖去解析 tar 格式）。
+  await runCommand("tar", ["-xzf", tarball, "-C", join(dir, "bin")], { log });
+  try { rmSync(tarball, { force: true }); } catch {}
+
+  const extracted = findWireproxy(join(dir, "bin"));
+  if (!extracted) throw new Error(`解包后未找到 wireproxy 可执行文件（目录：${join(dir, "bin")}）`);
+  if (extracted !== local) {
+    try { chmodSync(extracted, 0o755); } catch {}
+  }
+  try { chmodSync(local, 0o755); } catch {}
+  return existsSync(local) ? local : extracted;
+}
+
+function findWireproxy(binDir) {
+  try {
+    const hit = readdirSync(binDir).find((f) => f === "wireproxy" || f === "wireproxy.exe");
+    return hit ? join(binDir, hit) : null;
+  } catch {
+    return null;
+  }
+}
+
+function runCommand(cmd, args, { log = () => {} } = {}) {
+  return new Promise((resolve, reject) => {
+    let err = "";
+    const p = spawn(cmd, args, { stdio: ["ignore", "ignore", "pipe"] });
+    p.stderr.on("data", (d) => { err += String(d); });
+    p.on("error", reject);
+    p.on("close", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${cmd} 退出码 ${code}${err ? `：${err.slice(0, 200)}` : ""}`));
+    });
+  });
+}
+
+/** 写出某节点的 wireproxy 配置（含私钥 ⇒ 0600）。 */
+export function writeTunnelConf(dir, node) {
+  if (!node?.privateKey) throw new Error(`节点 :${node?.port} 缺 WireGuard 私钥，拒绝写出一份跑不起来的配置`);
+  const { conf } = nodePaths(dir, node.port);
+  const text = renderWireproxyConf({ ...node, port: node.port });
+  writeSecret(conf, text);
+  return { conf, bytes: Buffer.byteLength(text) };
+}
+
+/**
+ * 启动一条隧道。返回 { port, conf, stop() }。
+ * 进程退出即视为隧道失效（不自动重启：由 health 层决策重拨换 IP）。
+ */
+export function startTunnel({ binPath: exe, dir, port, log = () => {}, onExit = () => {}, now = Date.now } = {}) {
+  const { conf } = nodePaths(dir, port);
+  const child = spawn(exe, ["-c", conf], { stdio: ["ignore", "pipe", "pipe"] });
+  const startedAt = now();
+  let tail = "";
+  const keepTail = (d) => {
+    tail = (tail + String(d)).slice(-800);
+  };
+  child.stdout.on("data", keepTail);
+  child.stderr.on("data", keepTail);
+
+  let stopped = false;
+  child.on("exit", (code, signal) => {
+    if (!stopped) onExit({ port, code, signal, tail, pid: child.pid, aliveMs: now() - startedAt });
+  });
+
+  return {
+    port,
+    conf,
+    get pid() {
+      return child.pid;
+    },
+    get alive() {
+      return !stopped && child.exitCode === null;
+    },
+    get tail() {
+      return tail;
+    },
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      try { child.kill("SIGTERM"); } catch {}
+    },
+  };
+}
+
+/** 探活一个已起的隧道：经该端口访问上游 models 路径（不烧 token）。 */
+export async function probeTunnel({ port, baseUrl = "https://opencode.ai", path = "/zen/v1/models", fetchImpl = compatFetch, timeoutMs = 8000, headers = {}, wantText = false } = {}) {
+  const { ProxyAgent } = getUndici();
+  const agent = new ProxyAgent({ uri: `http://127.0.0.1:${port}`, connections: 2, keepAliveTimeout: 10_000 });
+  const url = `${String(baseUrl).replace(/\/+$/, "")}${path}`;
+  const t0 = Date.now();
+  try {
+    const res = await fetchImpl(url, {
+      headers,
+      signal: AbortSignal.timeout(timeoutMs),
+      dispatcher: agent,
+    });
+    const base = { ok: res.ok, status: res.status, ms: Date.now() - t0, url };
+    if (!wantText) return base;
+    const text = await res.text().catch(() => "");
+    return { ...base, text: String(text).slice(0, 2000) };
+  } catch (e) {
+    return { ok: false, status: 0, error: String(e?.message || e), ms: Date.now() - t0, url };
+  } finally {
+    try { await agent.close(); } catch {}
+  }
+}