@ait-co/devtools 0.1.128 → 0.1.131

package/dist/test-runner/bin.js

@@ -1,9 +1,12 @@
 #!/usr/bin/env node
+import { r as generateTotp } from "../totp-DvOYkYim.js";
 import * as path$1 from "node:path";
 import path, { basename, isAbsolute, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import * as fs from "node:fs/promises";
 import { glob, mkdir, writeFile } from "node:fs/promises";
+import { EventEmitter } from "node:events";
+import { WebSocket } from "ws";
 import { accessSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 //#region src/test-runner/discover.ts
@@ -42,11 +45,14 @@ async function discoverTestFiles(patterns, cwd) {
 * Builds a {@link RelayConnectionFactory} that opens a standalone env3 relay
 * connection.
 *
-* `open()` performs the full attach lifecycle and BLOCKS for tens of seconds (up
-* to `timeoutMs`) while a human scans the rendered QR with their phone — there
-* is no way around the manual scan for env3. It resolves with the live
-* `CdpConnection` once a matching page attaches; `close()` tears the relay
-* family down.
+* `open()` performs the full attach lifecycle and BLOCKS while a human scans
+* the rendered QR with their phone — there is no way around the manual scan
+* for env3. By default the wait is UNBOUNDED (`opts.timeoutMs` omitted): the
+* runner stays up until the user stops it (Ctrl-C/SIGTERM), since QR-scan is
+* a human-paced action with no sound default bound (devtools#735). Passing an
+* explicit `timeoutMs` opts into the old bounded behavior (CI/headless
+* callers). It resolves with the live `CdpConnection` once a matching page
+* attaches; `close()` tears the relay family down.
 *
 * The factory holds the booted relay family in a closure so `close()` can stop
 * it. A second `open()` on the same factory boots a fresh family (the previous
@@ -54,16 +60,17 @@ async function discoverTestFiles(patterns, cwd) {
 */
 function createRelayConnectionFactory(opts) {
 	const projectRoot = opts.projectRoot ?? process.cwd();
-	const timeoutMs = opts.timeoutMs ?? 6e5;
+	const timeoutMs = opts.timeoutMs ?? Number.POSITIVE_INFINITY;
 	const headless = opts.headless === true;
 	let family;
 	let qrServer;
+	let phase = "active";
 	return {
 		async open() {
-			const { prepareAttach, renderAndMaybeWait, mintAttachUrl } = await import("../attach-orchestrator-CpE0dMew.js");
-			const { injectDebugIndicator, injectGlobals } = await import("../cell-CX92lDI0.js");
+			const { prepareAttach, renderAndMaybeWait, mintAttachUrl } = await import("../attach-orchestrator-ca34r46y.js");
+			const { injectDebugIndicator, injectGlobals } = await import("../cell-rr6gL9AT.js");
 			const { loadRelaySecretReadOnly } = await import("../relay-secret-store-CFc9n0OA.js");
-			const { bootRelayFamily, buildRelayVerifyAuth } = await import("../debug-server-BzzNkETg.js");
+			const { bootRelayFamily, buildRelayVerifyAuth } = await import("../debug-server-CD4zYBq4.js");
 			await loadRelaySecretReadOnly({ projectRoot });
 			let resolveTunnelUp;
 			const tunnelReady = new Promise((resolve) => {
@@ -74,6 +81,9 @@ function createRelayConnectionFactory(opts) {
 				onWssUrl: () => {
 					resolveTunnelUp();
 					qrServer?.notifyStateChange();
+				},
+				onTunnelDown: () => {
+					qrServer?.notifyStateChange();
 				}
 			});
 			family = booted;
@@ -90,12 +100,13 @@ function createRelayConnectionFactory(opts) {
 				canOpenBrowser: () => !headless
 			};
 			try {
-				const { startQrHttpServer } = await import("../qr-http-server-s1iW_5VQ.js");
+				const { startQrHttpServer } = await import("../qr-http-server-DCbjORFa.js");
 				const getDashboardState = () => ({
 					tunnel: attachDeps.getTunnelStatus(),
 					pages: null,
 					attachUrl: lastAttachParts ? mintAttachUrl(attachDeps, lastAttachParts) : null,
-					mode: "relay-dev"
+					mode: "relay-dev",
+					phase
 				});
 				qrServer = await startQrHttpServer(getDashboardState);
 				attachDeps.qrHttpServer = qrServer;
@@ -148,7 +159,19 @@ function createRelayConnectionFactory(opts) {
 			if (opts.cell !== void 0) await injectGlobals(booted.connection, { __AIT_CELL__: opts.cell });
 			return booted.connection;
 		},
-		async close(_connection) {
+		onSessionPhase(next) {
+			phase = next;
+			qrServer?.notifyStateChange();
+		},
+		async close(connection) {
+			if (phase !== "complete") {
+				phase = "complete";
+				qrServer?.notifyStateChange();
+			}
+			try {
+				const { injectDebugIndicator } = await import("../cell-rr6gL9AT.js");
+				await injectDebugIndicator(connection, { state: "disconnected" });
+			} catch {}
 			family?.stop();
 			family = void 0;
 			await qrServer?.close();
@@ -157,6 +180,666 @@ function createRelayConnectionFactory(opts) {
 	};
 }
 //#endregion
+//#region src/shared/relay-auth-close.ts
+/**
+* Shared constants for the relay's named TOTP-auth rejection (issue #478).
+*
+* Before #478 the relay rejected an unauthenticated WebSocket upgrade with a
+* raw `HTTP/1.1 401` + `socket.destroy()`. A handshake aborted that way is
+* indistinguishable from a network failure on the browser side — the
+* WebSocket only ever sees close code 1006, so the phone (env-2 launcher PWA)
+* could not tell "stale TOTP code" apart from "tunnel down" and stayed
+* silent. The fix is accept-then-close: complete the handshake, then close
+* with an application close code that NAMES the rejection.
+*
+* Three parties share this contract:
+*   - `src/mcp/chii-relay.ts` (Node) sends the close frame / HTTP error body;
+*   - `src/in-app/attach.ts` (browser) observes relay-bound WebSockets and
+*     surfaces the code to the launcher shell;
+*   - `src/mcp/chii-connection.ts` (Node daemon client) recognises the code
+*     as an auth failure on its own `/client` dial (defensive — #439's fresh
+*     code mint means it should not normally hit this).
+*
+* This module is intentionally dependency-free (no Node, no DOM) so it is
+* safe to import from both the browser in-app bundle and the MCP daemon
+* bundle.
+*
+* SECRET-HANDLING: these are fixed enum values. The close reason / error body
+* must never grow to carry a secret, a TOTP code, or a host.
+*/
+/**
+* WebSocket close code sent by the relay when TOTP auth is rejected.
+*
+* 4000–4999 is the application-reserved range (RFC 6455 §7.4.2); 4401 mirrors
+* HTTP 401 so it reads as "unauthorized" at a glance.
+*/
+const RELAY_AUTH_REJECT_CLOSE_CODE = 4401;
+/**
+* Close reason string accompanying {@link RELAY_AUTH_REJECT_CLOSE_CODE}, and
+* the `error` value of the relay's HTTP 401 JSON body. Enum string only —
+* never interpolated with request data.
+*/
+const RELAY_AUTH_REJECT_REASON = "totp-rejected";
+//#endregion
+//#region src/mcp/log.ts
+/**
+* Allowed field keys that may pass through to a log line.
+* Unknown keys are dropped. Values are still redact-scanned.
+*/
+const ALLOWED_KEYS = new Set([
+	"ts",
+	"level",
+	"event",
+	"msg",
+	"port",
+	"totpEnabled",
+	"env",
+	"tool",
+	"deploymentId",
+	"errorKind",
+	"reason",
+	"prevTargetId",
+	"mode",
+	"fileCount",
+	"passed",
+	"failed",
+	"skipped"
+]);
+/**
+* Patterns that match secret values.
+* Match order matters — more-specific patterns first.
+*
+* #268 redact script covers: relay=wss://…, at=<TOTP>, _deploymentId=<uuid>.
+* Here we extend to in-process value-level patterns used in server logs.
+*/
+const SECRET_PATTERNS = [
+	/^\d{6}$/,
+	/^(aitcc_|AITCC_)/i,
+	/^[A-Za-z0-9_-]+=.{4,}/,
+	/^wss:\/\//,
+	/(?:^|[?&])at=[A-Z0-9]{6}/i
+];
+/**
+* Returns `true` when the string value matches any known-secret pattern.
+* Only string values are tested — numbers/booleans are always safe.
+*/
+function isSecretValue(value) {
+	return SECRET_PATTERNS.some((re) => re.test(value));
+}
+/**
+* Redacts a single scalar value.
+* - strings: return "***" if the value matches a secret pattern.
+* - other: return as-is.
+*/
+function redactValue(value) {
+	if (typeof value === "string" && isSecretValue(value)) return "***";
+	return value;
+}
+/**
+* Builds a safe log payload from raw fields.
+*
+* - Only keys in `ALLOWED_KEYS` are included.
+* - String values are scanned for secret patterns and replaced with "***".
+* - `ts` and `level` and `event` are always included (they are injected by the
+*   logger functions below, not by callers).
+*/
+function buildPayload(level, event, fields) {
+	const out = {
+		ts: (/* @__PURE__ */ new Date()).toISOString(),
+		level,
+		event
+	};
+	for (const [key, value] of Object.entries(fields)) {
+		if (!ALLOWED_KEYS.has(key)) continue;
+		if (key === "ts" || key === "level" || key === "event") continue;
+		out[key] = redactValue(value);
+	}
+	return out;
+}
+/**
+* Writes a single JSON log line to stderr.
+* MCP stdio transport uses stdout; all diagnostics go to stderr.
+*/
+function writeLog(level, event, fields = {}) {
+	const payload = buildPayload(level, event, fields);
+	process.stderr.write(`${JSON.stringify(payload)}\n`);
+}
+/** Log an informational structured event. */
+function logInfo(event, fields = {}) {
+	writeLog("info", event, fields);
+}
+/** Log an error structured event. */
+function logError(event, fields = {}) {
+	writeLog("error", event, fields);
+}
+//#endregion
+//#region src/mcp/chii-connection.ts
+/**
+* Production `CdpConnection` backed by the local Chii relay.
+*
+* Topology (debug mode):
+*   phone target.js  --WS-->  Chii relay :9100  <--WS--  this connection
+*
+* The phone connects to the relay as a `target`; this module connects as a
+* `client` (the role a CDP frontend would take) so CDP events the page emits
+* (`Runtime.consoleAPICalled`, `Network.*`) flow back here. We buffer recent
+* events in ring buffers the tool layer reads via `getBufferedEvents`.
+*
+* Node-only: imports `ws`. Never bundled into the browser/in-app entries.
+*
+* Attach reliability (#281):
+*   `refreshTargets()` emits an internal 'target:attached' event whenever a
+*   new target is added to the relay. `waitForFirstTarget()` awaits that event
+*   (with a polling-interval fallback) so `start_attach`'s attach wait
+*   resolves deterministically rather than racing between polling rounds.
+*/
+/** Max events retained per domain ring buffer. */
+const DEFAULT_BUFFER_SIZE = 500;
+/**
+* Substrings that mark a "relay websocket is dead" class error, as produced by
+* `handleDisconnect('relay WebSocket 연결이 끊겼습니다')` (ws close handler) and
+* the fail-fast `sendCommand` rejection (`relay에 연결되어 있지 않습니다 (...)`).
+*
+* Exported so callers outside this module (e.g. `test-runner/relay-worker.ts`)
+* can detect the same error class without hardcoding a fragile full-sentence
+* match — mirrors the `EVALUATE_TIMEOUT_MARKER` precedent in
+* `test-runner/relay-worker.ts`. Kept in sync with `classifyToolError`'s
+* `relayDisconnectError` branch in `mcp/errors.ts`.
+*/
+const RELAY_DISCONNECT_MARKERS = ["relay WebSocket", "relay에 연결되어 있지 않습니다"];
+/**
+* Returns true when `message` matches the relay-websocket-dead error class
+* (socket closed, socket errored, or fail-fast "not connected" rejection).
+*/
+function isRelayDisconnectMessage(message) {
+	return RELAY_DISCONNECT_MARKERS.some((marker) => message.includes(marker));
+}
+function isObject(value) {
+	return typeof value === "object" && value !== null;
+}
+function parseInbound(raw) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return null;
+	}
+	if (!isObject(parsed)) return null;
+	const message = {};
+	if (typeof parsed.id === "number") message.id = parsed.id;
+	if (typeof parsed.method === "string") message.method = parsed.method;
+	if ("params" in parsed) message.params = parsed.params;
+	if ("result" in parsed) message.result = parsed.result;
+	if (isObject(parsed.error) && typeof parsed.error.message === "string") message.error = { message: parsed.error.message };
+	return message;
+}
+const PHASE_1_EVENTS = [
+	"Runtime.consoleAPICalled",
+	"Network.requestWillBeSent",
+	"Network.responseReceived"
+];
+/**
+* Ring buffer size for `Runtime.exceptionThrown`.
+*
+* Exceptions are rarer than console messages but each is heavier (stack
+* trace). 50 is generous enough to cover a crash scenario while keeping
+* memory bounded.
+*
+* **Lifecycle note**: the exception buffer intentionally survives `replaced` /
+* `crashed` / `destroyed` lifecycle events — it is NOT cleared on target
+* transitions. Rationale: an exception fired just before a crash is exactly
+* the signal we want to preserve for root-cause analysis. The buffer
+* represents "exceptions seen in this MCP session", not "exceptions in the
+* current page".
+*/
+const EXCEPTION_BUFFER_SIZE = 50;
+/** Default per-command timeout if neither option nor env var is set. */
+const DEFAULT_COMMAND_TIMEOUT_MS = 3e4;
+/**
+* Production CDP connection. Polls the relay for the first attached target,
+* opens a client websocket to it, enables Phase 1 domains, and buffers events.
+*/
+var ChiiCdpConnection = class {
+	/** Authoritative connection kind (issue #348) — relay-backed. */
+	kind = "relay";
+	relayBaseUrl;
+	bufferSize;
+	commandTimeoutMs;
+	totpSecret;
+	emitter = new EventEmitter();
+	buffers = /* @__PURE__ */ new Map();
+	targets = /* @__PURE__ */ new Map();
+	ws = null;
+	connectionState = "idle";
+	nextCommandId = 1;
+	/**
+	* The single active target id under the single-attach model.
+	* Updated by `refreshTargets()` whenever a non-null target is present.
+	* Used to detect a new (different) target attach and evict the previous one.
+	*/
+	activeTargetId = null;
+	/** In-flight enableDomains() promise — concurrent callers share it. */
+	enablingPromise = null;
+	/** Pending request→response commands keyed by CDP message id. */
+	pending = /* @__PURE__ */ new Map();
+	/**
+	* Timestamp (ms since epoch) of the most recent crash/destroy/detach event,
+	* or `null` if no crash has been detected since the last `enableDomains()`.
+	*/
+	lastCrashDetectedAt = null;
+	/**
+	* Per-target last-seen timestamp (ms since epoch). Updated on any inbound
+	* CDP message carrying data from a target. Keyed by target id.
+	*/
+	targetLastSeenAt = /* @__PURE__ */ new Map();
+	/** Active heartbeat interval handle (only when `AIT_CDP_HEARTBEAT_MS` is set). */
+	heartbeatHandle = null;
+	/** Lifecycle event listeners (crash / destroyed / detached). */
+	lifecycleListeners = [];
+	constructor(options) {
+		this.relayBaseUrl = options.relayBaseUrl.replace(/\/$/, "");
+		this.bufferSize = options.bufferSize ?? DEFAULT_BUFFER_SIZE;
+		this.totpSecret = options.totpSecret;
+		const envMs = process.env.AIT_CDP_COMMAND_TIMEOUT_MS ? Number(process.env.AIT_CDP_COMMAND_TIMEOUT_MS) : void 0;
+		this.commandTimeoutMs = (envMs !== void 0 && Number.isFinite(envMs) && envMs > 0 ? envMs : void 0) ?? options.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
+		for (const event of PHASE_1_EVENTS) this.buffers.set(event, []);
+		this.buffers.set("Runtime.exceptionThrown", []);
+		this.emitter.setMaxListeners(0);
+	}
+	/** Refresh the attached-target list from the relay's `GET /targets`. */
+	async refreshTargets() {
+		let targetsUrl = `${this.relayBaseUrl}/targets`;
+		if (this.totpSecret) {
+			const code = generateTotp(this.totpSecret);
+			targetsUrl += `?at=${encodeURIComponent(code)}`;
+		}
+		const res = await fetch(targetsUrl);
+		if (!res.ok) throw new Error(`Chii relay /targets returned HTTP ${res.status} ${res.statusText}`);
+		const body = await res.json();
+		const list = isObject(body) && Array.isArray(body.targets) ? body.targets : [];
+		let newestTargetId = null;
+		for (const item of list) {
+			if (!isObject(item) || typeof item.id !== "string") continue;
+			newestTargetId = item.id;
+		}
+		if (newestTargetId !== null && this.activeTargetId !== null && newestTargetId !== this.activeTargetId) {
+			const prevId = this.activeTargetId;
+			logInfo("page.detached", { prevTargetId: prevId });
+			this.evictTarget(prevId);
+		}
+		this.targets.clear();
+		for (const item of list) {
+			if (!isObject(item) || typeof item.id !== "string") continue;
+			if (item.id !== newestTargetId) continue;
+			this.targets.set(item.id, {
+				id: item.id,
+				title: typeof item.title === "string" ? item.title : "",
+				url: typeof item.url === "string" ? item.url : ""
+			});
+		}
+		if (newestTargetId !== null) this.activeTargetId = newestTargetId;
+		else this.activeTargetId = null;
+		const result = [...this.targets.values()];
+		if (newestTargetId !== null) this.emitter.emit("target:attached", result);
+		return result;
+	}
+	listTargets() {
+		return [...this.targets.values()];
+	}
+	/**
+	* Waits until at least one target matching `filterFn` is attached, then
+	* resolves with the full target list at that moment.
+	*
+	* Resolution happens on whichever comes first:
+	*   (a) a `'target:attached'` event from `refreshTargets()` (triggered by
+	*       the /targets poll finding a new target), OR
+	*   (b) a `'target:attached'` event from `handleMessage()` (triggered by
+	*       the first inbound CDP message from a target — confirms the relay
+	*       websocket has data from the phone, not just a target entry in the map).
+	*
+	* This dual-signal approach eliminates the polling race that previously
+	* caused `wait_for_attach` to resolve before the first CDP message arrived.
+	*
+	* Falls back to checking `listTargets()` every `pollIntervalMs` in case the
+	* EventEmitter is missed (defensive belt-and-suspenders).
+	*
+	* @param filterFn  - Predicate that the returned targets must satisfy.
+	* @param timeoutMs - Reject after this many ms (default 90 000). Pass a
+	*   non-finite value (`Infinity`) to disable the rejection timer entirely —
+	*   used by the test-runner's unbounded QR-attach wait (devtools#735). Node
+	*   clamps `setTimeout(fn, Infinity)` to ~1ms, so a non-finite value MUST
+	*   skip arming the timer rather than pass it through.
+	* @param pollIntervalMs - Fallback poll interval (default 500ms).
+	*/
+	waitForFirstTarget(filterFn, timeoutMs = 9e4, pollIntervalMs = 500) {
+		const current = this.listTargets();
+		if (filterFn(current)) return Promise.resolve(current);
+		return new Promise((resolve, reject) => {
+			let settled = false;
+			let pollHandle = null;
+			const settle = (targets) => {
+				if (settled) return;
+				settled = true;
+				if (timeoutHandle !== null) clearTimeout(timeoutHandle);
+				if (pollHandle !== null) {
+					clearInterval(pollHandle);
+					pollHandle = null;
+				}
+				this.emitter.off("target:attached", onAttach);
+				resolve(targets);
+			};
+			const onAttach = (targets) => {
+				if (filterFn(targets)) settle(targets);
+			};
+			const timeoutHandle = Number.isFinite(timeoutMs) ? setTimeout(() => {
+				if (settled) return;
+				settled = true;
+				if (pollHandle !== null) {
+					clearInterval(pollHandle);
+					pollHandle = null;
+				}
+				this.emitter.off("target:attached", onAttach);
+				reject(/* @__PURE__ */ new Error(`waitForFirstTarget: 타임아웃 (${timeoutMs}ms) — 폰이 relay에 attach되지 않았습니다.`));
+			}, timeoutMs) : null;
+			this.emitter.on("target:attached", onAttach);
+			pollHandle = setInterval(() => {
+				this.refreshTargets().then((targets) => {
+					if (filterFn(targets)) settle(targets);
+				}, () => {});
+			}, pollIntervalMs);
+		});
+	}
+	/**
+	* Timestamp (ms since epoch) of the most recent crash/destroy/detach event
+	* detected since the last `enableDomains()` call, or `null` if none.
+	*/
+	getLastCrashDetectedAt() {
+		return this.lastCrashDetectedAt;
+	}
+	/**
+	* Last-seen timestamp (ms since epoch) for a given target id, or `null` if
+	* the target is unknown / no message has been received from it yet.
+	*/
+	getTargetLastSeenAt(targetId) {
+		return this.targetLastSeenAt.get(targetId) ?? null;
+	}
+	/** Subscribe to target lifecycle events (crash / destroyed / detached). */
+	onLifecycle(listener) {
+		this.lifecycleListeners.push(listener);
+		return () => {
+			const idx = this.lifecycleListeners.indexOf(listener);
+			if (idx !== -1) this.lifecycleListeners.splice(idx, 1);
+		};
+	}
+	/**
+	* Connect a client websocket to the first attached target and enable Phase 1
+	* domains. Resolves once the socket is open and enable commands are sent.
+	*/
+	async enableDomains() {
+		if (this.ws && this.ws.readyState === WebSocket.OPEN) return;
+		if (this.enablingPromise) return this.enablingPromise;
+		this.enablingPromise = this._doEnableDomains().finally(() => {
+			this.enablingPromise = null;
+		});
+		return this.enablingPromise;
+	}
+	async _doEnableDomains() {
+		const target = (await this.refreshTargets())[0];
+		if (!target) throw new Error("No mini-app page attached to the Chii relay yet.");
+		let clientUrl = `${this.relayBaseUrl.replace(/^http/, "ws")}/client/${`devtools-mcp-${Date.now()}`}?target=${encodeURIComponent(target.id)}`;
+		if (this.totpSecret) {
+			const code = generateTotp(this.totpSecret);
+			clientUrl += `&at=${encodeURIComponent(code)}`;
+		}
+		const ws = new WebSocket(clientUrl);
+		this.ws = ws;
+		await new Promise((resolve, reject) => {
+			ws.once("open", () => resolve());
+			ws.once("error", (err) => reject(err));
+			ws.once("close", (code) => {
+				if (code === 4401) reject(/* @__PURE__ */ new Error("relay 인증(TOTP)이 거부됐습니다 (close 4401). 코드가 만료됐을 수 있습니다 — 재연결 시 새 코드가 발급됩니다."));
+			});
+		});
+		this.lastCrashDetectedAt = null;
+		this.targetLastSeenAt.clear();
+		this.connectionState = "connected";
+		ws.on("message", (data) => this.handleMessage(data.toString()));
+		ws.on("close", (code) => this.handleDisconnect(code === 4401 ? "relay 인증(TOTP)이 거부돼 연결이 종료됐습니다 (close 4401)" : "relay WebSocket 연결이 끊겼습니다"));
+		ws.on("error", (err) => this.handleDisconnect(`relay WebSocket 오류: ${err.message}`));
+		this.sendFireAndForget("Runtime.enable");
+		this.sendFireAndForget("Network.enable");
+		this.sendFireAndForget("DOM.enable");
+		this.sendFireAndForget("Page.enable");
+		this.sendFireAndForget("Inspector.enable");
+		this.sendFireAndForget("Target.setDiscoverTargets", { discover: true });
+		this.startHeartbeat(target.id);
+	}
+	/** Fire-and-forget CDP message (used for `*.enable`, no result awaited). */
+	sendFireAndForget(method, params = {}) {
+		if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+		const id = this.nextCommandId++;
+		this.ws.send(JSON.stringify({
+			id,
+			method,
+			params
+		}));
+	}
+	/**
+	* Issue a CDP command and resolve with its result (Phase 2). Rejects on a CDP
+	* error frame or when no websocket is open (no page attached yet).
+	*/
+	send(method, params) {
+		return this.sendCommand(method, params ?? {});
+	}
+	/**
+	* Issue an arbitrary request→response command over the relay and resolve with
+	* its raw result. Both the typed CDP {@link send} and the AIT domain (Phase 3
+	* `AIT.*` methods, forwarded over the same Chii channel) build on this.
+	*
+	* Rejects immediately if the connection is disconnected (fail-fast — no
+	* auto-reconnect). Caller should re-run `list_pages` or `enableDomains` to
+	* reattach.
+	*
+	* Times out after `commandTimeoutMs` (default 30s, env
+	* `AIT_CDP_COMMAND_TIMEOUT_MS`). On timeout the pending entry is cleaned up
+	* and the promise rejects with a descriptive Korean error.
+	*/
+	sendCommand(method, params = {}) {
+		if (this.connectionState === "disconnected") return Promise.reject(/* @__PURE__ */ new Error(`relay에 연결되어 있지 않습니다 (${method}). list_pages로 attach 상태를 확인하고 enableDomains()로 재연결하세요.`));
+		if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return Promise.reject(/* @__PURE__ */ new Error("No mini-app page attached to the Chii relay yet. Call enableDomains() first."));
+		const id = this.nextCommandId++;
+		const ws = this.ws;
+		const timeoutMs = this.commandTimeoutMs;
+		return new Promise((resolve, reject) => {
+			const handle = setTimeout(() => {
+				this.pending.delete(id);
+				reject(/* @__PURE__ */ new Error(`CDP 명령이 타임아웃됐습니다 (${method}, ${timeoutMs}ms). 폰 측 토스 앱이 백그라운드로 내려갔거나 미니앱이 unload됐을 수 있습니다. list_pages로 attach 상태를 확인하세요.`));
+			}, timeoutMs);
+			this.pending.set(id, {
+				resolve: (v) => {
+					clearTimeout(handle);
+					resolve(v);
+				},
+				reject: (e) => {
+					clearTimeout(handle);
+					reject(e);
+				}
+			});
+			ws.send(JSON.stringify({
+				id,
+				method,
+				params
+			}));
+		});
+	}
+	/**
+	* Called on WebSocket `close` or `error` after a successful connection.
+	* Rejects all pending commands and marks the connection as disconnected so
+	* subsequent `sendCommand` calls fail fast (no auto-reconnect).
+	*/
+	handleDisconnect(reason) {
+		if (this.connectionState === "disconnected") return;
+		this.connectionState = "disconnected";
+		this.ws = null;
+		this.stopHeartbeat();
+		const err = /* @__PURE__ */ new Error(`${reason}. list_pages로 attach 상태를 확인하고 enableDomains()로 재연결하세요.`);
+		for (const waiter of this.pending.values()) waiter.reject(err);
+		this.pending.clear();
+	}
+	/**
+	* Evict a previously active target under the single-attach model.
+	* Rejects pending commands with a 'replaced-by-new-attach' reason and emits
+	* a 'replaced' lifecycle event. Does NOT clear all targets — only the specific
+	* targetId. The caller is responsible for rebuilding the targets map afterwards.
+	*
+	* The error message uses 'replaced-by-new-attach' so test assertions can match it.
+	*/
+	evictTarget(targetId) {
+		const detectedAt = (/* @__PURE__ */ new Date()).toISOString();
+		this.targets.delete(targetId);
+		this.targetLastSeenAt.delete(targetId);
+		const err = /* @__PURE__ */ new Error(`[ait-debug] replaced-by-new-attach — 이전 page 세션이 새 attach로 교체됐습니다 (targetId=${targetId}). list_pages로 현재 attach 상태를 확인하세요.`);
+		for (const waiter of this.pending.values()) waiter.reject(err);
+		this.pending.clear();
+		const event = {
+			kind: "replaced",
+			targetId,
+			detectedAt
+		};
+		for (const listener of this.lifecycleListeners) try {
+			listener(event);
+		} catch {}
+	}
+	/**
+	* Handle a page-level crash or target destruction event.
+	* Removes the target from the in-memory map, rejects all pending commands,
+	* and emits a lifecycle event.
+	*
+	* @param kind - Event kind: 'crashed' | 'destroyed' | 'detached'
+	* @param targetId - The target ID from the event params (may be null for
+	*   Inspector.targetCrashed which has no targetId in the params).
+	*/
+	handleTargetGone(kind, targetId) {
+		const detectedAt = (/* @__PURE__ */ new Date()).toISOString();
+		this.lastCrashDetectedAt = Date.now();
+		if (targetId !== null) {
+			this.targets.delete(targetId);
+			this.targetLastSeenAt.delete(targetId);
+			if (this.activeTargetId === targetId) this.activeTargetId = null;
+		} else {
+			this.targets.clear();
+			this.targetLastSeenAt.clear();
+			this.activeTargetId = null;
+		}
+		const err = /* @__PURE__ */ new Error(`[ait-debug] ${kind === "crashed" ? "page crash (Inspector.targetCrashed)" : kind === "destroyed" ? "target 종료 (Target.targetDestroyed)" : "target detach (Target.detachedFromTarget)"} 감지됨 — relay에서 제거됐습니다. 새 attach가 필요합니다 (list_pages로 확인 → enableDomains()로 재연결).`);
+		for (const waiter of this.pending.values()) waiter.reject(err);
+		this.pending.clear();
+		const event = {
+			kind,
+			targetId,
+			detectedAt
+		};
+		for (const listener of this.lifecycleListeners) try {
+			listener(event);
+		} catch {}
+	}
+	/**
+	* Start the optional CDP heartbeat loop.
+	*
+	* When `AIT_CDP_HEARTBEAT_MS` is set to a positive integer, every interval
+	* we send `Runtime.evaluate({expression: '1'})` to each active target. If
+	* the command times out (2 s hard deadline) or errors, we treat the target
+	* as dead and call `handleTargetGone`.
+	*
+	* This is a zombie-detector fallback: cloudflared keeps-alive the tunnel ws
+	* even when the phone app has crashed, so the ws-level disconnect (#252) won't
+	* fire. The heartbeat catches this gap.
+	*
+	* Default: OFF. Only activates when `AIT_CDP_HEARTBEAT_MS` is set.
+	*/
+	startHeartbeat(initialTargetId) {
+		this.stopHeartbeat();
+		const envMs = process.env.AIT_CDP_HEARTBEAT_MS ? Number(process.env.AIT_CDP_HEARTBEAT_MS) : void 0;
+		if (envMs === void 0 || !Number.isFinite(envMs) || envMs <= 0) return;
+		const PING_TIMEOUT_MS = 2e3;
+		this.heartbeatHandle = setInterval(() => {
+			const targetIds = this.targets.size > 0 ? [...this.targets.keys()] : [initialTargetId];
+			for (const targetId of targetIds) {
+				const pingPromise = this.sendCommand("Runtime.evaluate", {
+					expression: "1",
+					returnByValue: true,
+					timeout: PING_TIMEOUT_MS
+				});
+				const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error("heartbeat timeout")), PING_TIMEOUT_MS + 500));
+				Promise.race([pingPromise, timeoutPromise]).catch(() => {
+					if (this.targets.has(targetId)) this.handleTargetGone("destroyed", targetId);
+				});
+			}
+		}, envMs);
+	}
+	stopHeartbeat() {
+		if (this.heartbeatHandle !== null) {
+			clearInterval(this.heartbeatHandle);
+			this.heartbeatHandle = null;
+		}
+	}
+	handleMessage(raw) {
+		const message = parseInbound(raw);
+		if (!message) return;
+		if (typeof message.id === "number" && this.pending.has(message.id)) {
+			const waiter = this.pending.get(message.id);
+			this.pending.delete(message.id);
+			if (waiter) if (message.error) waiter.reject(new Error(message.error.message));
+			else waiter.resolve(message.result);
+			return;
+		}
+		const now = Date.now();
+		let firstMessageSeen = false;
+		for (const targetId of this.targets.keys()) {
+			if (!this.targetLastSeenAt.has(targetId)) firstMessageSeen = true;
+			this.targetLastSeenAt.set(targetId, now);
+		}
+		if (firstMessageSeen && this.targets.size > 0) this.emitter.emit("target:attached", [...this.targets.values()]);
+		if (typeof message.method !== "string") return;
+		if (message.method === "Inspector.targetCrashed") {
+			this.handleTargetGone("crashed", null);
+			return;
+		}
+		if (message.method === "Target.targetDestroyed") {
+			const targetId = isObject(message.params) && typeof message.params.targetId === "string" ? message.params.targetId : null;
+			this.handleTargetGone("destroyed", targetId);
+			return;
+		}
+		if (message.method === "Target.detachedFromTarget") {
+			const targetId = isObject(message.params) && typeof message.params.targetId === "string" ? message.params.targetId : null;
+			this.handleTargetGone("detached", targetId);
+			return;
+		}
+		if (!this.buffers.has(message.method)) return;
+		const event = message.method;
+		const buffer = this.buffers.get(event);
+		if (!buffer) return;
+		buffer.push(message.params);
+		const cap = event === "Runtime.exceptionThrown" ? EXCEPTION_BUFFER_SIZE : this.bufferSize;
+		if (buffer.length > cap) buffer.shift();
+		this.emitter.emit(event, message.params);
+	}
+	getBufferedEvents(event) {
+		return this.buffers.get(event) ?? [];
+	}
+	on(event, listener) {
+		this.emitter.on(event, listener);
+		return () => this.emitter.off(event, listener);
+	}
+	/** Close the relay client websocket and reject any in-flight commands. */
+	close() {
+		const ws = this.ws;
+		this.stopHeartbeat();
+		this.handleDisconnect("Chii relay connection closed");
+		ws?.close();
+	}
+};
+//#endregion
 //#region src/test-runner/bundle.ts
 /**
 * esbuild-based bundler for user test files.
@@ -678,8 +1361,37 @@ async function runTestFilesOverRelay(connection, files, opts) {
 	if (collectCaptures && domainsEnabled) unsubscribeConsole = connection.on("Runtime.consoleAPICalled", (event) => {
 		liveConsole.push(event);
 	});
+	let pendingReconnectCheck = false;
+	/**
+	* Attempts one `enableDomains()` reconnect. Logs the attempt and outcome to
+	* stderr. Never throws — a failed reconnect just means the caller proceeds
+	* as today (each remaining file / the retry will fail-fast on the still-dead
+	* socket).
+	*
+	* `context` selects the fixed log literal: 'next-file' for the between-files
+	* case (a file's FINAL result was a WS-dead-class error — the primary #731
+	* scenario), 'retry-precheck' for the defensive reconnect before retrying a
+	* timed-out file (cheap no-op via `enableDomains()`'s idempotency when the
+	* socket never actually died).
+	*
+	* SECRET-HANDLING: fixed literals only — no relay wss URL, TOTP code, or
+	* tunnel host.
+	*/
+	const attemptReconnect = async (context) => {
+		process.stderr.write(context === "next-file" ? "relay-worker: relay connection lost — attempting reconnect before next file\n" : "relay-worker: evaluate timed out — attempting reconnect before retry\n");
+		try {
+			await connection.enableDomains();
+			process.stderr.write("relay-worker: reconnect succeeded\n");
+		} catch (e) {
+			process.stderr.write(`relay-worker: reconnect failed (${e instanceof Error ? e.message : String(e)}) — continuing, remaining files may fail\n`);
+		}
+	};
 	try {
 		for (const file of files) {
+			if (pendingReconnectCheck) {
+				await attemptReconnect("next-file");
+				pendingReconnectCheck = false;
+			}
 			let fileEntry;
 			try {
 				const { code } = await bundleTestFile(file, opts?.bundleOptions);
@@ -690,14 +1402,17 @@ async function runTestFilesOverRelay(connection, files, opts) {
 				* We need to distinguish:
 				*   - `rpcResult.ok = false` + timeout error → retry candidate (`return null`)
 				*   - `rpcResult.ok = false` + other error   → final error, no retry
-				*   - `injectAndRunBundle` throws             → CDP exceptionDetails (page
-				*     engine threw); treated as a final (non-retryable) error.
+				*   - `injectAndRunBundle` throws             → CDP exceptionDetails OR a
+				*     relay-disconnect rejection from `connection.send()` (page engine
+				*     threw, or the ws died mid-evaluate); treated as a final
+				*     (non-retryable) error either way.
 				*
 				* The Promise.race timeout in rpc.ts RETURNS `{ok:false, error: '…'}` (it
-				* does NOT throw/reject).  Only genuine CDP `exceptionDetails` cause a throw.
-				* This distinction is what makes the EVALUATE_TIMEOUT_MARKER gate below
-				* reachable — the timeout result surfaces as `rpcResult.ok=false` with the
-				* marker string, not as a caught exception.
+				* does NOT throw/reject).  Only genuine CDP `exceptionDetails` (or a dead
+				* `connection.send()`) cause a throw. This distinction is what makes the
+				* EVALUATE_TIMEOUT_MARKER gate below reachable — the timeout result
+				* surfaces as `rpcResult.ok=false` with the marker string, not as a
+				* caught exception.
 				*/
 				const attempt = async () => {
 					let rpcResult;
@@ -722,12 +1437,13 @@ async function runTestFilesOverRelay(connection, files, opts) {
 				const firstResult = await attempt();
 				if (firstResult !== null) fileEntry = firstResult;
 				else {
+					await attemptReconnect("retry-precheck");
 					process.stderr.write(`relay-worker: evaluate timed out for ${file} — retrying once\n`);
 					const retryResult = await attempt();
 					if (retryResult !== null) fileEntry = retryResult;
 					else fileEntry = {
 						file,
-						result: { error: `${EVALUATE_TIMEOUT_MARKER} ${opts?.timeoutMs ?? 3e4}ms (after retry)` }
+						result: { error: `${EVALUATE_TIMEOUT_MARKER} ${opts?.timeoutMs ?? 6e4}ms (after retry)` }
 					};
 				}
 			} catch (e) {
@@ -736,6 +1452,7 @@ async function runTestFilesOverRelay(connection, files, opts) {
 					result: { error: e instanceof Error ? e.message : String(e) }
 				};
 			}
+			if ("error" in fileEntry.result && isRelayDisconnectMessage(fileEntry.result.error)) pendingReconnectCheck = true;
 			fileResults.push(fileEntry);
 		}
 	} finally {
@@ -950,15 +1667,15 @@ USAGE
 OPTIONS
   --scheme-url <url>      intoss-private:// URL from \`ait deploy --scheme-only\`
                           (required for standalone relay attach / env3)
-  --timeout <ms>          Per-file evaluate timeout in ms (default: 30000).
+  --timeout <ms>          Per-file evaluate timeout in ms (default: 60000).
                           Controls how long a single test file is allowed to run
                           before it is considered hung. Does NOT affect how long
                           the CLI waits for a human to scan the QR code — use
                           --attach-timeout for that.
   --attach-timeout <ms>   How long to wait for a human to scan the QR code with
-                          their phone (default: 600000 — 10 minutes). Omit to
-                          use the relay factory's generous default. Decrease for
-                          CI environments where a scan should arrive quickly.
+                          their phone. Omit (default) to wait indefinitely — the
+                          runner stays up until you stop it (Ctrl-C/SIGTERM).
+                          Pass a value to bound the wait for CI/headless runs.
   --cell-sdk-line <line>  SDK line to inject as __AIT_CELL__.sdkLine (2.x|3.x)
   --cell-platform <plat>  Platform to inject as __AIT_CELL__.platform
                           (mock|ios|android, default: AIT_CELL_PLATFORM env)
@@ -1006,7 +1723,7 @@ EXAMPLE
 * Exported for unit testing — main() is the only other caller.
 */
 function resolveTimeouts(rawTimeout, rawAttachTimeout) {
-	const evaluateTimeoutMs = rawTimeout !== void 0 ? parseInt(rawTimeout, 10) : 3e4;
+	const evaluateTimeoutMs = rawTimeout !== void 0 ? parseInt(rawTimeout, 10) : 6e4;
 	if (Number.isNaN(evaluateTimeoutMs) || evaluateTimeoutMs <= 0) return "--timeout must be a positive integer";
 	const attachTimeoutMs = rawAttachTimeout !== void 0 ? parseInt(rawAttachTimeout, 10) : void 0;
 	if (attachTimeoutMs !== void 0 && (Number.isNaN(attachTimeoutMs) || attachTimeoutMs <= 0)) return "--attach-timeout must be a positive integer";
@@ -1196,6 +1913,7 @@ async function main(argv = process.argv.slice(2)) {
 	}
 	let exitCode = 0;
 	try {
+		factory.onSessionPhase?.("running");
 		const report = await runWithConnection(connection, files, {
 			timeoutMs: evaluateTimeoutMs,
 			printSummary: true,
@@ -1215,6 +1933,7 @@ async function main(argv = process.argv.slice(2)) {
 		}
 		exitCode = report.totals.failed > 0 ? 1 : 0;
 	} finally {
+		factory.onSessionPhase?.("complete");
 		await factory.close(connection);
 		process.exitCode = exitCode;
 	}
@@ -1247,6 +1966,6 @@ main().catch((e) => {
 	process.exitCode = 1;
 });
 //#endregion
-export {};
+export { RELAY_AUTH_REJECT_REASON as a, RELAY_AUTH_REJECT_CLOSE_CODE as i, logError as n, logInfo as r, ChiiCdpConnection as t };
 
 //# sourceMappingURL=bin.js.map