@inobit/pi-instabox 0.0.0-stage → 0.1.0

package/src/pool.ts

@@ -0,0 +1,651 @@
+/**
+ * @inobit/pi-instabox — per-box 远端客户端池 + 唤醒链（方案 §4.4 D4、§4.7、§5.1、T11）。
+ *
+ * 契约：
+ * - **一台 box 一个连接**：池里的客户端只要还活着（`!isDead()`）就复用；`dead` 或不在池里
+ *   才新建。复用不查 `ls`：状态只在确实要建连时读一次（否则每次工具调用都多一轮 CLI）。
+ *   `remote.ts` 的客户端是「单次连接一实例、终态不自动重连」，重建责任在本模块。
+ * - **先看状态，再唤醒，最后建连**（用户裁决的取舍：不依赖服务端在请求里唤醒）：
+ *   `get` 先 `listBoxes({ force: true })` 查一次状态，`state === "running"` 直接建连；
+ *   其余（`suspended` / `suspending` / `resuming` / 未知态）才进唤醒链。
+ * - **唤醒链 `wake` → `start` → `resume`**：`wake` 覆盖自动暂停（实测 6s 左右成功）；
+ *   用户手动 suspend/stop 的箱 `wake` 会**退出码 0 但 stderr 自报**
+ *   `machine_not_running` / `start it with …`（`cli.ts` 已按 stderr 判失败）→ 退 `start`，
+ *   再失败退 `resume`。每步之前 `onProgress("正在唤醒 <box>…")`，单步上限取 `timeouts.wakeMs`
+ *   （`wake`）/ `timeouts.startMs`（`start`、`resume`），失败都把该步 `stderr` 尾部带进错误文本。
+ * - **准备阶段共享一个截止时间**（{@link PrepareBudget}）：一次 `get` 从查状态开始就建立
+ *   `deadline = clock() + timeouts.prepareMs`，每一步（`wake`/`start`/`resume`、确认轮询、建连）
+ *   实际超时都是 `min(单步上限, 剩余预算)`，退避与轮询的等待也按剩余收窄。因此**卡住的一步
+ *   不会把总时长顶成各步上限之和**（那曾是最多 8 分钟的由来）；预算耗尽就回
+ *   `prepare timed out after <prepareMs>ms (box "…", step: wake|start|resume|confirm|connect)`，
+ *   并带上该步 `stderr` 尾部。两个固有限制（有意为之）：`listBoxes` 的预算由列表器自己把关
+ *   （`LIST_BOXES_TIMEOUT_MS`），本模块只能在它返回后按剩余预算决定是否继续；`initialize` 的
+ *   超时在建客户端时就固定了，所以这里用「进建连前先看剩余预算」的截止判定，而不是临时改它。
+ * - **每步之后都确认 `running`**（方案 §4.4 / R4）：命令退 0 也可能只是「已提交」，服务端状态
+ *   才是判据。因此以 {@link WAKE_POLL_INTERVAL_MS}（1s）间隔、带 `force: true` 重查 `ls`，直到
+ *   `state === "running"`。**命令成功时**的确认预算取该步剩余的 `min(单步上限, 准备阶段剩余)`
+ *   （且不越过截止时间），超时就把当时的 `state` 带进失败记录并继续下一命令；**命令已报失败
+ *   时只做一次即时采样**（不空等整步预算——用户手动暂停的箱 `wake` 会立刻报
+ *   `machine_not_running`，空等 `wakeMs` 只会拖慢退到 `start`），采样到 `running` 仍算成功。
+ *   确认通过后才建连。
+ * - **`allowWake === false`（`session_start` 的后台路径）**：非 `running` 时**不跑**
+ *   `wake`/`start`/`resume`，直接回 `{ ok: false, error }`（内部带 `reason: "not-running"`，
+ *   供 {@link Pool.get} 判断能否让后来允许唤醒的调用重跑），也不报唤醒进度。
+ * - **冷却期不可自愈**：平台文案是
+ *   `sandbox X is cooling down until <RFC3339>; try again after cooldown`，命中
+ *   {@link COOLDOWN_RE}（`is cooling down until`）时**不换下一条命令、也不重试连接**，直接报错
+ *   并保留原文时间戳（stderr 里若另有 `retryAfterSeconds`/`Retry-After` 也一并透出）。
+ * - **网关唤醒中的兜底**：SSH 网关自己只等 15 秒，没等到就拒连并回
+ *   `machine … is waking up; try again in a few seconds`。正常路径下先 `wake` 已避免它，但状态
+ *   与网关仍可能不同步，因此命中 {@link WAKING_UP_RE} 时按 {@link WAKE_RETRY_DELAYS_MS}
+ *   （5s/10s/15s，共 3 次）**退避重试连接**；其余建连失败原样报握手失败。
+ * - 状态与箱名**只来自注入的 `listBoxes`**（T15 传 `createBoxLister(...).list`，其签名天然
+ *   可赋值）；本模块不读配置、不自己跑 `ls`。`ls` 失败/箱不存在都回错误，不猜状态。
+ * - 建客户端后立刻 `initialize(signal)`，**只在握手成功时入池**：失败即 `close()` 丢弃并返回
+ *   错误，下次 `get` 重建（失败驱逐）。建连期间被 `dispose` 的连接同样丢弃（per-box 代数
+ *   校验），不留孤儿进程。
+ * - 同一 box 的并发 `get` 共享同一个 in-flight Promise（先到者的 `opts` 决定
+ *   `signal`/`allowWake`/`onProgress`），不会为同一 box 起两条 ssh。唯一例外：共享到的结果
+ *   是 `reason: "not-running"` 而本次 `allowWake !== false` 时，本次自己重跑一遍——否则
+ *   后台拉取的「不唤醒」结论会劫持本该唤醒的工具调用。
+ * - `dispose` 先 `close()` 再删表，且**不抛**（`close()` 的异常被吞掉：关停不是用户可见失败）。
+ *   它**不是终态**：池之后照常可用，也**不清**在飞的 `get`——在飞的那次连接靠代数校验发现
+ *   自己被抛弃，`close()` 后回 `{ ok: false, error: "… pool was disposed while connecting" }`。
+ *   因此 `dispose` 之后的第一次 `get` 可能立刻拿到这个 doomed 结果，重试即成功。
+ *   `size()` 只数已握手入池的连接（在飞的不计），`dispose` 后为 0。
+ * - **埋点**：`pool.prepare` 一次 `get` 一条（`{ box, ok, ms, step?, timeoutMs? }`，成功 info /
+ *   失败 warn）——`ms` 是准备阶段（查状态 ＋ 唤醒链）本身的耗时，`step`/`timeoutMs` 是报错的
+ *   那一步与它拿到的预算；`pool.wake` 每条命令一条并带该步实际的 `timeoutMs`，两者合起来就能
+ *   看出「每步用了多少预算、总共用了多久」。
+ * - 绝不 throw 到会话层：所有失败都是 `{ ok: false, error }`。
+ * - 注入面：`exec` / `listBoxes` / `clientFactory` / `clock` / `sleep` / `onProgress` 全部可替；
+ *   单测不 spawn 真进程、不碰真实 CLI、不等真实时间。
+ */
+
+import type { BoxInfo, ListBoxesResult } from "./boxes.ts";
+import { type CliOutcome, type ExecFn, resume, start, wake } from "./cli.ts";
+import type { InstaboxTimeouts } from "./config.ts";
+import { logEvent } from "./log.ts";
+import { type RemoteClient, createRemoteClient } from "./remote.ts";
+
+/** CLI 可执行文件名（与 `cli.ts` 一致，argv[0]，不经 shell）。 */
+const INSTABOX_BIN = "instabox";
+
+/** 远端桌面工具 MCP server 的可执行文件名（`instabox ssh <box> -- <它> mcp`）。 */
+const COMPUTER_USE_BIN = "instabox-computer-use";
+
+/** `ls` 的 `state` 里唯一可用的值；其余（含空串＝未知态）都算「还没起来」。 */
+const RUNNING_STATE = "running";
+
+/** 唤醒命令成功后确认 `running` 的轮询间隔（方案 §4.4：1s 间隔重新 `ls`）。 */
+export const WAKE_POLL_INTERVAL_MS = 1_000;
+
+/**
+ * 网关唤醒中的重试间隔（毫秒）：5s / 10s / 15s，共 3 次，退避合计 30s。
+ * 每次重试都是一次完整的新连接（`initialize`），成功即入池；耗尽才报错。
+ * 退避也吃准备预算：剩余不足就不睡，直接按「准备阶段超时」报错。
+ */
+export const WAKE_RETRY_DELAYS_MS: readonly number[] = [5_000, 10_000, 15_000];
+
+/**
+ * 「网关还在唤醒」的可重试错误：SSH 网关的自动唤醒**只等 15 秒**，没等到就拒连并回
+ * `machine … is waking up; try again in a few seconds`。正常路径先 `wake` 已避免它，这里只是
+ * 状态与网关不同步时的兜底：不 `start`、不 `resume`，退避重试连接。
+ */
+const WAKING_UP_RE = /is waking up|try again in a few seconds/i;
+
+/**
+ * 冷却期：真实文案是 `sandbox X is cooling down until <RFC3339>; try again after cooldown`。
+ * 不可自愈——换下一条命令与重连都白费，只报错并保留原文时间。
+ */
+const COOLDOWN_RE = /is cooling down until/i;
+
+/** `retryAfterSeconds` 的两种出现形态：JSON 字段，或 `retry after 30`/`Retry-After: 30` 文本。 */
+const RETRY_AFTER_JSON_RE = /"retryAfterSeconds"\s*:\s*(\d+)/i;
+const RETRY_AFTER_TEXT_RE = /retry[- ]?after\s*(?:seconds?\s*)?[:=]?\s*(\d+)/i;
+
+/** 内部失败标记：只有 `allowWake === false` 的「箱不在 running」带它，供 `get` 决定是否重跑。 */
+const NOT_RUNNING_REASON = "not-running";
+
+/**
+ * 唤醒链：`wake`（自动暂停）→ `start`（手动 suspend/stop）→ `resume`（兜底）。
+ * 顺序固定，每步失败都退到下一条。
+ */
+const WAKE_COMMANDS = ["wake", "start", "resume"] as const;
+
+/** 唤醒链的一步。 */
+type WakeCommand = (typeof WAKE_COMMANDS)[number];
+
+/**
+ * 准备阶段的步骤名：唤醒链三条命令 ＋ 确认轮询 ＋ 建连。
+ * 错误文案与埋点共用这一种拼写（`prepare timed out … (step: <它>)`）。
+ */
+type PrepareStep = WakeCommand | "confirm" | "connect";
+
+/** `get` 的结果：失败分支必带可直接展示的 `error`（绝不 throw）。 */
+export type PoolGetResult = { ok: true; client: RemoteClient } | { ok: false; error: string };
+
+/** 准备阶段的失败面：`step`/`timeoutMs` 只在「预算耗尽」时出现（错误文案与埋点共用）。 */
+type PrepareFailure = { ok: false; error: string; step?: PrepareStep; timeoutMs?: number };
+
+/** 准备阶段（查状态 ＋ 唤醒链）的结果：`ok: true` 只表示「箱已在 running」。 */
+type PrepareResult = { ok: true } | PrepareFailure;
+
+/**
+ * 内部结果：比 {@link PoolGetResult} 多一个 `reason`（后台路径拒唤醒）与准备阶段的
+ * `step`/`timeoutMs`。只用于 `get` 内部流转；对外返回类型仍是 `PoolGetResult`。
+ */
+type ConnectResult = { ok: true; client: RemoteClient } | (PrepareFailure & { reason?: typeof NOT_RUNNING_REASON });
+
+/** 单次 `get` 的选项。 */
+export interface PoolGetOptions {
+	/** 取消信号：透传给唤醒链的 CLI 命令、确认轮询与 `initialize` */
+	signal?: AbortSignal;
+	/** 本次的唤醒进度回调（覆盖 {@link PoolDeps.onProgress}，用于工具的 `onUpdate`） */
+	onProgress?: (message: string) => void;
+	/** `false` = `session_start` 路径：**绝不**唤醒，箱不在 `running` 就报错（默认允许唤醒） */
+	allowWake?: boolean;
+}
+
+/**
+ * `listBoxes` 的选项：`force` 跳过 `ls` 缓存（开头的状态查询与确认阶段都必须带，否则 5s TTL
+ * 会看到陈旧状态），`signal` 是建议字段（`createBoxLister(...).list` 忽略它；本模块每轮自查 abort）。
+ */
+export interface PoolListOptions {
+	force?: boolean;
+	signal?: AbortSignal;
+}
+
+/** 注入的 box 列表来源；`createBoxLister(...).list` 的签名天然可赋值。 */
+export type ListBoxesFn = (opts?: PoolListOptions) => Promise<ListBoxesResult>;
+
+/** 注入的等待函数（毫秒）；默认真实 `setTimeout`，单测换成即时返回，绝不等真实时间。 */
+export type SleepFn = (ms: number) => Promise<void>;
+
+/** 池的注入面。 */
+export interface PoolDeps {
+	/** per-box 客户端工厂；默认 {@link createRemoteClient} + `instabox ssh <box> -- … mcp` */
+	clientFactory?: (box: string) => RemoteClient;
+	/** 注入的 CLI 执行函数（唤醒链的 `wake`/`start`/`resume`） */
+	exec: ExecFn;
+	/** 注入的 box 列表（T15 传 `createBoxLister(...).list`）；失败即本模块失败，不降级 */
+	listBoxes: ListBoxesFn;
+	/** 准备阶段预算：`prepareMs` 是总截止时间，`wakeMs`/`startMs` 只是单步上限 */
+	timeouts: InstaboxTimeouts;
+	/** 注入的时钟（毫秒）：确认阶段的预算判定 + 错误文本里的耗时；默认 `Date.now` */
+	clock?: () => number;
+	/** 注入的等待（确认轮询的 1s 间隔）；默认真实 `setTimeout` */
+	sleep?: SleepFn;
+	/** 默认唤醒进度出口（被单次 `get` 的 `onProgress` 覆盖） */
+	onProgress?: (message: string) => void;
+}
+
+/** per-box 客户端池。 */
+export interface Pool {
+	/** 取某 box 的可用客户端：复用 / 查状态唤醒 / 建连三选一，失败回 `{ ok: false, error }` */
+	get(box: string, opts?: PoolGetOptions): Promise<PoolGetResult>;
+	/** 关停并移除某 box 的连接（不给参数时等于 {@link Pool.disposeAll}） */
+	dispose(box?: string): void;
+	/** 关停并移除所有连接 */
+	disposeAll(): void;
+	/** 当前池里可用（已握手）的连接数 */
+	size(): number;
+}
+
+/** 本次调用是否已被取消（用一个函数封装：`readonly` 字段的窄化会跨 `await` 残留）。 */
+function isAborted(opts: PoolGetOptions): boolean {
+	return opts.signal?.aborted === true;
+}
+
+/** 每一步命令的单步上限：`wake` 只等自动暂停，`start`/`resume` 是整箱冷启。 */
+function commandTimeoutMs(command: WakeCommand, timeouts: InstaboxTimeouts): number {
+	return command === "wake" ? timeouts.wakeMs : timeouts.startMs;
+}
+
+/**
+ * 一次 `get` 的准备阶段预算：所有步骤共享同一个截止时间。
+ * 每一步的实际超时取 {@link stepTimeout}（`min(单步上限, 剩余预算)`），所以某一步卡住
+ * 只会吃掉它自己那一段，总时长不会变成各步上限之和。
+ */
+interface PrepareBudget {
+	/** 总预算（毫秒）：错误文案与 `pool.prepare` 埋点用 */
+	prepareMs: number;
+	/** 起点（`clock()` 口径）：`pool.prepare` 的 `ms` 从这里算 */
+	startedAt: number;
+	/** 截止时间（`clock()` 口径）：唤醒、确认轮询、建连共用 */
+	deadline: number;
+	/** 剩余预算（0..prepareMs，不为负） */
+	remaining: () => number;
+	/** 准备阶段结束时刻（`clock()` 口径；`undefined` = 还没结束） */
+	endedAt?: number;
+}
+
+function createPrepareBudget(clock: () => number, prepareMs: number): PrepareBudget {
+	const startedAt = clock();
+	const deadline = startedAt + prepareMs;
+	return { prepareMs, startedAt, deadline, remaining: () => Math.max(0, deadline - clock()) };
+}
+
+/** 该步的实际超时 = `min(单步上限, 剩余准备预算)`。 */
+function stepTimeout(budget: PrepareBudget, stepCapMs: number): number {
+	return Math.min(stepCapMs, budget.remaining());
+}
+
+/** 预算耗尽时的统一结果：写明总预算、是哪一步、以及该步的 `stderr` 尾部。 */
+function prepareTimeout(
+	box: string,
+	step: PrepareStep,
+	budget: PrepareBudget,
+	timeoutMs: number,
+	stderrTail?: string,
+): PrepareFailure & { step: PrepareStep; timeoutMs: number } {
+	const detail = stderrTail === undefined ? "" : `; stderr: ${stderrTail}`;
+	return {
+		ok: false,
+		step,
+		timeoutMs,
+		error: `prepare timed out after ${budget.prepareMs}ms (box "${box}", step: ${step})${detail}`,
+	};
+}
+
+/** 唤醒链单步：转调 `cli.ts` 的同名薄封装（不在这里拼 argv）。 */
+function runWakeCommand(
+	exec: ExecFn,
+	command: WakeCommand,
+	box: string,
+	timeout: number,
+	signal: AbortSignal | undefined,
+): Promise<CliOutcome> {
+	if (command === "wake") return wake(exec, box, { timeout, signal });
+	if (command === "start") return start(exec, box, { timeout, signal });
+	return resume(exec, box, { timeout, signal });
+}
+
+/** `unknown` → message 文本（错误文本里不出现 `[object Object]`）。 */
+function messageOf(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+/** `state` 的展示形式：空串是「未知」，其余加引号（错误文本用）。 */
+function stateLabel(state: string): string {
+	return state === "" ? "unknown" : `"${state}"`;
+}
+
+/** 候选箱名列表（错误文本用；空列表给更明确的一句话）。 */
+function availableBoxes(boxes: readonly BoxInfo[]): string {
+	const names = boxes.map((box) => box.name).filter((name) => name !== "");
+	return names.length > 0 ? `available boxes: ${names.join(", ")}` : "instabox ls returned no boxes";
+}
+
+/** 从失败文本里取 `retryAfterSeconds`（没有就 `undefined`，错误文本里也就不提数字）。 */
+function retryAfterSeconds(text: string): number | undefined {
+	const match = RETRY_AFTER_JSON_RE.exec(text) ?? RETRY_AFTER_TEXT_RE.exec(text);
+	if (match === null) return undefined;
+	const seconds = Number(match[1]);
+	return Number.isFinite(seconds) ? seconds : undefined;
+}
+
+/** 冷却期错误的可展示形态：原文（含 `until <RFC3339>`）原样保留，附带可透出的重试时间。 */
+function cooldownError(box: string, text: string): string {
+	const seconds = retryAfterSeconds(text);
+	const retry = seconds === undefined ? "" : `; retryAfterSeconds=${seconds}`;
+	return `box "${box}" is cooling down (not retryable, do not start)${retry}: ${text}`;
+}
+
+/** 网关唤醒重试耗尽的形态：说清「已经重试过几次」，并保留平台原文。 */
+function stillWakingUp(box: string, text: string, retries: number): string {
+	return `box "${box}": machine did not finish waking up after ${retries} connection retries: ${text}`;
+}
+
+/** 握手失败的统一形态（非「唤醒中」/非冷却期都走这里）。 */
+function handshakeError(box: string, text: string): string {
+	return `box "${box}": remote MCP handshake failed: ${text}`;
+}
+
+/** 默认等待：真实 `setTimeout`（宿主/单测都可整体替换）。 */
+const defaultSleep: SleepFn = (ms) =>
+	new Promise<void>((resolve) => {
+		globalThis.setTimeout(resolve, ms);
+	});
+
+/**
+ * 建 per-box 客户端池。
+ *
+ * 取连接的顺序：复用 → 查状态（非 `running` 才 `wake` → `start` → `resume`，每步确认 `running`）
+ * → 建连；`allowWake === false` 时非 `running` 直接报错。
+ */
+export function createPool(deps: PoolDeps): Pool {
+	const { exec, listBoxes, timeouts } = deps;
+	const clock = deps.clock ?? Date.now;
+	const sleep = deps.sleep ?? defaultSleep;
+	const factory =
+		deps.clientFactory ??
+		((box: string): RemoteClient =>
+			createRemoteClient({
+				command: INSTABOX_BIN,
+				args: ["ssh", box, "--", COMPUTER_USE_BIN, "mcp"],
+				timeouts: {
+					connect: timeouts.connectMs,
+					initialize: timeouts.initializeMs,
+					listTools: timeouts.listToolsMs,
+					callTool: timeouts.callMs,
+				},
+			}));
+
+	/** 已握手可用的连接 */
+	const clients = new Map<string, RemoteClient>();
+	/** 在飞的 `get`（同一 box 的并发调用共享它；`dispose` 不清它，结果由代数校验兜住） */
+	const inflight = new Map<string, Promise<ConnectResult>>();
+	/**
+	 * per-box 代数：`dispose` 递增。建连期间代数变了说明该连接在关停之后才建好，
+	 * 必须丢弃（否则 `dispose` 之后仍会泄漏一个 ssh 子进程）。
+	 */
+	const generation = new Map<string, number>();
+
+	function currentGeneration(box: string): number {
+		return generation.get(box) ?? 0;
+	}
+
+	function bumpGeneration(box: string): void {
+		generation.set(box, currentGeneration(box) + 1);
+	}
+
+	/** `close()` 是尽力而为：关停失败不能变成用户可见错误。 */
+	function closeQuietly(client: RemoteClient | undefined): void {
+		if (client === undefined) return;
+		try {
+			client.close();
+		} catch {
+			// 忽略：上层已经在删表，连接对象即将失去引用
+		}
+	}
+
+	/** 关停并移除某 box 的连接（幂等）。 */
+	function evict(box: string): void {
+		const client = clients.get(box);
+		clients.delete(box);
+		bumpGeneration(box);
+		closeQuietly(client);
+	}
+
+	function dispose(box?: string): void {
+		// 不给参数 = disposeAll：此时箱名字段缺席（`logEvent` 丢掉 `undefined`）
+		logEvent("pool.dispose", { box }, "debug");
+		if (box !== undefined) {
+			evict(box);
+			return;
+		}
+		for (const name of new Set([...clients.keys(), ...inflight.keys()])) evict(name);
+	}
+
+	/** 一次 `listBoxes` 调用：异常与失败都归一成 `{ ok: false, error }`。 */
+	async function listBoxesOnce(opts: PoolListOptions): Promise<{ ok: true; boxes: BoxInfo[] } | { ok: false; error: string }> {
+		try {
+			const listed = await listBoxes(opts);
+			if (!listed.ok) return { ok: false, error: `cannot list boxes: ${listed.error ?? "unknown error"}` };
+			return { ok: true, boxes: listed.boxes };
+		} catch (error) {
+			return { ok: false, error: `cannot list boxes: ${messageOf(error)}` };
+		}
+	}
+
+	/** 状态查询失败/箱不存在都回错误：不猜状态，也不静默降级到唤醒。 */
+	async function resolveState(box: string): Promise<{ ok: true; info: BoxInfo } | { ok: false; error: string }> {
+		const listed = await listBoxesOnce({ force: true });
+		if (!listed.ok) return listed;
+		const info = listed.boxes.find((candidate) => candidate.name === box);
+		if (info === undefined) {
+			return { ok: false, error: `unknown box "${box}"; ${availableBoxes(listed.boxes)}` };
+		}
+		logEvent("pool.state", { box, state: info.state, desiredState: info.desiredState }, "debug");
+		return { ok: true, info };
+	}
+
+	/**
+	 * 一次建连尝试：新客户端 + `initialize(signal)`。
+	 * 失败即 `close()` 丢弃（失败驱逐：下次 `get` 重建），并回**原始**错误文本。
+	 */
+	async function attemptConnect(
+		box: string,
+		opts: PoolGetOptions,
+	): Promise<{ ok: true; client: RemoteClient } | { ok: false; error: string }> {
+		const client = factory(box);
+		try {
+			await client.initialize(opts.signal);
+			return { ok: true, client };
+		} catch (error) {
+			closeQuietly(client);
+			return { ok: false, error: messageOf(error) };
+		}
+	}
+
+	/**
+	 * 建连 + 「网关唤醒中」退避重试：`is waking up` / `try again in a few seconds` 是可重试错误
+	 * （网关只等 15s），按 {@link WAKE_RETRY_DELAYS_MS} 重连，最多 3 次。
+	 * 返回最后一次的原始失败文本与已重试次数；非「唤醒中」的失败**不重试**，立刻返回。
+	 * 退避也吃准备预算：剩余不足就不再睡（保留原始错误文本，由调用方按「准备阶段超时」报错）。
+	 */
+	async function connectWithWakeRetry(
+		box: string,
+		opts: PoolGetOptions,
+		budget: PrepareBudget,
+	): Promise<{ ok: true; client: RemoteClient } | { ok: false; error: string; retries: number }> {
+		let attempt = await attemptConnect(box, opts);
+		let retries = 0;
+		for (const delay of WAKE_RETRY_DELAYS_MS) {
+			if (attempt.ok || !WAKING_UP_RE.test(attempt.error)) break;
+			if (isAborted(opts)) return { ok: false, error: `box "${box}": connect cancelled by caller`, retries };
+			const wait = Math.min(delay, budget.remaining());
+			if (wait <= 0) break;
+			await sleep(wait);
+			if (isAborted(opts)) return { ok: false, error: `box "${box}": connect cancelled by caller`, retries };
+			retries += 1;
+			attempt = await attemptConnect(box, opts);
+		}
+		if (attempt.ok) return attempt;
+		return { ok: false, error: attempt.error, retries };
+	}
+
+	/**
+	 * 唤醒命令之后的确认（方案 §4.4 / R4）：`force: true` 每 1s 重查，直到 `running`。
+	 * 第一次采样不等 1s（命令刚返回，箱子可能已经好了）；预算是该步的 `min(单步上限, 剩余
+	 * 准备预算)`，且绝不越过准备阶段的截止时间——最后一觉按剩余时间收窄，因此轮询不会把
+	 * 总时长顶出预算。`budgetMs === 0`（命令已报失败）时只做一次即时采样。
+	 */
+	async function confirmRunning(
+		box: string,
+		opts: PoolGetOptions,
+		budget: PrepareBudget,
+		budgetMs: number,
+	): Promise<{ ok: true } | { ok: false; error: string }> {
+		const startedAt = clock();
+		const until = Math.min(startedAt + budgetMs, budget.deadline);
+		for (;;) {
+			if (isAborted(opts)) return { ok: false, error: `box "${box}": wake cancelled by caller` };
+			const listed = await listBoxesOnce({ force: true, signal: opts.signal });
+			if (!listed.ok) return { ok: false, error: `${listed.error} (while confirming box "${box}")` };
+			const info = listed.boxes.find((candidate) => candidate.name === box);
+			if (info === undefined) {
+				return { ok: false, error: `unknown box "${box}"; ${availableBoxes(listed.boxes)}` };
+			}
+			if (info.state === RUNNING_STATE) return { ok: true };
+			const left = until - clock();
+			if (left <= 0) {
+				return {
+					ok: false,
+					error: `box "${box}" did not reach "${RUNNING_STATE}" within ${until - startedAt}ms of the wake attempt (state ${stateLabel(info.state)})`,
+				};
+			}
+			await sleep(Math.min(WAKE_POLL_INTERVAL_MS, left));
+		}
+	}
+
+	/** `allowWake === false` 的拒答：说清状态，并给出两条可执行补救。 */
+	function notRunning(box: string, info: BoxInfo): ConnectResult {
+		return {
+			ok: false,
+			reason: NOT_RUNNING_REASON,
+			error: `box "${box}" is ${stateLabel(info.state)}, not running; this path does not wake boxes — run /instabox-use ${box} (or "instabox start ${box}") first`,
+		};
+	}
+
+	/**
+	 * 唤醒链：`wake` → `start` → `resume`，每步之后都确认 `running`（命令退 0 也可能只是提交成功）。
+	 * 每步超时取 `min(单步上限, 剩余准备预算)`：成功 → 按该步剩余的预算轮询；失败 → 只做一
+	 * 次即时采样（不空等，见文件头契约）。命令失败、确认超时都记一笔并继续下一条命令；全失败
+	 * 才报错。冷却期直接终止（不可自愈）；预算耗尽立即报 `prepare timed out` 并带上该步 stderr
+	 * 尾部（不再进下一条命令，否则总时长又会变成各步上限之和）。
+	 * 只在状态非 `running` 且 `allowWake !== false` 时调用。
+	 */
+	async function ensureRunning(box: string, opts: PoolGetOptions, budget: PrepareBudget): Promise<PrepareResult> {
+		const progress = opts.onProgress ?? deps.onProgress;
+		const failures: string[] = [];
+		for (const command of WAKE_COMMANDS) {
+			if (isAborted(opts)) return { ok: false, error: `box "${box}": wake cancelled by caller` };
+			const stepCapMs = commandTimeoutMs(command, timeouts);
+			const timeoutMs = stepTimeout(budget, stepCapMs);
+			if (timeoutMs <= 0) return prepareTimeout(box, command, budget, 0);
+			progress?.(`正在唤醒 ${box}…`);
+			const startedAt = clock();
+			const outcome = await runWakeCommand(exec, command, box, timeoutMs, opts.signal);
+			const ms = clock() - startedAt;
+			// 每一步都记：`wake` → `start` → `resume` 的退化路径靠这个时间线排查；
+			// `timeoutMs` 是该步实际拿到的预算（clamp 之后），与 `ms` 一起看就知道谁吃掉了预算
+			logEvent(
+				"pool.wake",
+				{ box, step: command, ok: outcome.ok, ms, timeoutMs },
+				outcome.ok ? "info" : "warn",
+			);
+			if (!outcome.ok) {
+				// 冷却期不可自愈：不确认、不换下一条命令，直接透出原文时间
+				if (COOLDOWN_RE.test(outcome.error)) return { ok: false, error: cooldownError(box, outcome.error) };
+				failures.push(`${outcome.error} (after ${ms}ms)`);
+			}
+			// 成功才值得等；失败只即时采样一次，避免用户手动暂停的箱白等一整步预算
+			const confirmBudgetMs = outcome.ok ? stepTimeout(budget, stepCapMs) : 0;
+			const confirmed = await confirmRunning(box, opts, budget, confirmBudgetMs);
+			if (confirmed.ok) return { ok: true };
+			if (isAborted(opts)) return confirmed;
+			failures.push(confirmed.error);
+			// 预算耗尽：不再退到下一条命令，直接报准备阶段超时（带该步 stderr 尾部）
+			if (budget.remaining() <= 0) return prepareTimeout(box, command, budget, timeoutMs, outcome.stderrTail);
+		}
+		return { ok: false, error: `could not wake box "${box}": ${failures.join("; ")}` };
+	}
+
+	/** 握手成功后的入池：建连期间被 `dispose` 过的连接必须丢弃（不留孤儿进程）。 */
+	function adopt(box: string, stamp: number, client: RemoteClient): ConnectResult {
+		if (currentGeneration(box) !== stamp) {
+			closeQuietly(client);
+			return { ok: false, error: `box "${box}": pool was disposed while connecting` };
+		}
+		clients.set(box, client);
+		return { ok: true, client };
+	}
+
+	/**
+	 * 准备阶段：查状态，非 `running` 才进唤醒链（`allowWake === false` 直接拒答）。
+	 * 整段共享 {@link PrepareBudget} 的截止时间；`ls` 自己的预算由列表器把关，这里只能在它
+	 * 返回后按剩余预算决定后续步骤。
+	 */
+	async function prepareBox(box: string, opts: PoolGetOptions, budget: PrepareBudget): Promise<PrepareResult> {
+		const state = await resolveState(box);
+		if (!state.ok) return state;
+		if (state.info.state === RUNNING_STATE) return { ok: true };
+		if (opts.allowWake === false) return notRunning(box, state.info);
+		return ensureRunning(box, opts, budget);
+	}
+
+	async function connectBox(box: string, opts: PoolGetOptions, budget: PrepareBudget): Promise<ConnectResult> {
+		const stamp = currentGeneration(box);
+		try {
+			// 先看状态：running 直接连；非 running 才进唤醒链（allowWake=false 直接拒答）
+			const prepared = await prepareBox(box, opts, budget);
+			// 准备阶段到此结束：`pool.prepare` 的 `ms` 只量这一段，不含建连握手
+			budget.endedAt = clock();
+			if (!prepared.ok) return prepared;
+			// 预算已耗尽就不再 spawn：`initialize` 的超时在建客户端时就固定了，这里只能拦住起点
+			const connectTimeoutMs = stepTimeout(budget, timeouts.connectMs);
+			if (connectTimeoutMs <= 0) return prepareTimeout(box, "connect", budget, 0);
+			// 确认 running 之后才建连；`is waking up` 是网关侧的兜底（理论上先 wake 后不会遇到）
+			const attempt = await connectWithWakeRetry(box, opts, budget);
+			if (attempt.ok) return adopt(box, stamp, attempt.client);
+			if (budget.remaining() <= 0) {
+				return prepareTimeout(box, "connect", budget, connectTimeoutMs, attempt.error);
+			}
+			if (WAKING_UP_RE.test(attempt.error)) {
+				return { ok: false, error: stillWakingUp(box, attempt.error, attempt.retries) };
+			}
+			if (COOLDOWN_RE.test(attempt.error)) {
+				return { ok: false, error: cooldownError(box, attempt.error) };
+			}
+			return { ok: false, error: handshakeError(box, attempt.error) };
+		} catch (error) {
+			// 兜底：任何意外异常都不外抛（池的失败面只有 `{ ok: false, error }`）
+			return { ok: false, error: `box "${box}": ${messageOf(error)}` };
+		}
+	}
+
+	/**
+	 * 一次建连尝试的埋点包装：`pool.prepare`（准备阶段本身的 `ms` ＋ 失败时报错的那一步与它
+	 * 拿到的预算）与 `pool.connect`（整段建连）各一条，返回值与错误文案不动。
+	 */
+	async function connect(box: string, opts: PoolGetOptions): Promise<ConnectResult> {
+		const budget = createPrepareBudget(clock, timeouts.prepareMs);
+		const result = await connectBox(box, opts, budget);
+		const endedAt = budget.endedAt ?? clock();
+		logEvent(
+			"pool.prepare",
+			{
+				box,
+				ok: result.ok,
+				ms: endedAt - budget.startedAt,
+				step: result.ok ? undefined : result.step,
+				timeoutMs: result.ok ? undefined : result.timeoutMs,
+			},
+			result.ok ? "info" : "warn",
+		);
+		logEvent("pool.connect", {
+			box,
+			ok: result.ok,
+			ms: clock() - budget.startedAt,
+			error: result.ok ? undefined : result.error,
+		});
+		return result;
+	}
+
+	/** 起一次建连并登记为 in-flight（同一 box 的下一个调用会共享它）。 */
+	function startConnect(box: string, opts: PoolGetOptions): Promise<ConnectResult> {
+		const started = connect(box, opts);
+		inflight.set(box, started);
+		// 登记者自己也等待完成后的清理：只有还挂着「自己」时才删，不误删重跑出来的新条目
+		return started.finally(() => {
+			if (inflight.get(box) === started) inflight.delete(box);
+		});
+	}
+
+	function get(box: string, opts: PoolGetOptions = {}): Promise<PoolGetResult> {
+		const existing = clients.get(box);
+		if (existing !== undefined) {
+			if (!existing.isDead()) {
+				logEvent("pool.reuse", { box }, "debug");
+				return Promise.resolve({ ok: true, client: existing });
+			}
+			evict(box);
+		}
+		const pending = inflight.get(box);
+		if (pending === undefined) return startConnect(box, opts);
+		return pending.then((result) => {
+			// 共享到的若是后台路径的「不唤醒」结论，而本次允许唤醒：自己重跑一遍
+			if (result.ok || result.reason !== NOT_RUNNING_REASON || opts.allowWake === false) return result;
+			return startConnect(box, opts);
+		});
+	}
+
+	return {
+		get,
+		dispose,
+		disposeAll: () => dispose(),
+		size: () => clients.size,
+	};
+}