@ait-co/devtools 0.1.144 → 0.2.1

package/dist/test-runner/bin.js

@@ -1,2584 +0,0 @@
-#!/usr/bin/env node
-import { m as logInfo } from "../attach-orchestrator-DL3NQ9ca.js";
-import { r as generateTotp } from "../totp-CZLLKfOC.js";
-import { r as runPermissionPreflight, t as PERMISSION_PREFLIGHT_TIMEOUT_MS } from "../cell-EBKKpAAT.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
-/**
-* Test-file discovery shared by the `devtools-test` CLI and the `run_tests`
-* MCP tool, so both expand glob patterns with identical semantics.
-*
-* Uses Node's built-in `fs/promises` `glob` (Node 22+) — no extra dependency,
-* which keeps the MCP daemon install graph lean (a plain glob lib would land in
-* the `npx … devtools-mcp` path for no benefit).
-*
-* Pure Node IO only (`node:fs/promises` + `node:path`) — react-free, so it is
-* safe to import from the MCP daemon graph.
-*/
-/**
-* Filename suffix that opts a test file into manual-variant scheduling
-* (devtools#741). A file named `<name>.manual.ait.test.ts` is EXCLUDED from
-* `discoverTestFiles`'s default output (so existing unattended runs are
-* unaffected — the zero-diff-when-off constraint) and is only surfaced when
-* the caller explicitly asks for manual files via {@link partitionManualTests}
-* (wired from the CLI's `--manual-blocking` flag).
-*
-* This is the entire tagging contract for v1 — no separate manifest/config,
-* just a filename convention. Documented here + in the CLI `--help` text
-* (cli.ts USAGE) and the test-runner README.
-*/
-const MANUAL_TEST_SUFFIX = ".manual.ait.test.ts";
-/** True when `file`'s basename ends with {@link MANUAL_TEST_SUFFIX}. */
-function isManualTestFile(file) {
-	return basename(file).endsWith(MANUAL_TEST_SUFFIX);
-}
-/**
-* Expands `patterns` (globs or plain paths) into a sorted, de-duplicated list of
-* ABSOLUTE test file paths, resolved relative to `cwd`.
-*
-* A plain (non-glob) path passes through when it matches a real file; a glob
-* expands against `cwd`. Absolute matches are kept as-is; relative matches are
-* resolved against `cwd`. `bundleTestFile` requires an absolute path, so the
-* absolute output feeds it directly.
-*
-* By default, files matching {@link MANUAL_TEST_SUFFIX} are EXCLUDED from the
-* result (devtools#741) — blocking-UI tests opt in via that filename
-* convention and must never appear in an unattended run unless the caller
-* explicitly asks for them via `includeManual: true`. This keeps the
-* default (flag-off) discovery path byte-for-byte identical to before this
-* option existed.
-*
-* @param patterns Glob patterns or file paths (e.g. `['src/**\/*.ait.test.ts']`).
-* @param cwd      Base directory for relative patterns/results.
-* @param opts     `{ includeManual }` — when true, manual-tagged files are kept
-*                 in the (still-sorted) output instead of being filtered out.
-*                 Use {@link partitionManualTests} to separate + reorder them.
-* @returns Sorted, de-duplicated absolute file paths. Empty when nothing matches.
-*/
-async function discoverTestFiles(patterns, cwd, opts) {
-	const out = /* @__PURE__ */ new Set();
-	for await (const match of glob(patterns, { cwd })) out.add(isAbsolute(match) ? match : resolve(cwd, match));
-	const sorted = [...out].sort();
-	if (opts?.includeManual) return sorted;
-	return sorted.filter((f) => !isManualTestFile(f));
-}
-/**
-* Splits an already-discovered file list into `{ regular, manual }`, each
-* still sorted. Used by the CLI's `--manual-blocking` path to schedule manual
-* files strictly AFTER every regular file (devtools#741) — regular files run
-* first (and produce the unattended-shaped part of the report) and manual
-* files run last, each preceded by a dashboard prompt.
-*
-* Pure partition — does not itself decide inclusion; call
-* `discoverTestFiles(patterns, cwd, { includeManual: true })` first so manual
-* files are present in `files` to partition.
-*/
-function partitionManualTests(files) {
-	const regular = [];
-	const manual = [];
-	for (const f of files) (isManualTestFile(f) ? manual : regular).push(f);
-	return {
-		regular,
-		manual
-	};
-}
-//#endregion
-//#region src/test-runner/relay-factory.ts
-/**
-* Builds a {@link RelayConnectionFactory} that opens a standalone relay
-* connection for env 3 (intoss-private scheme, default) or env 2 (AITC Sandbox
-* PWA launcher deep-link, when `opts.attachLauncher` is set — devtools#774).
-*
-* `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.
-* 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
-* one should have been `close()`d first).
-*/
-function createRelayConnectionFactory(opts) {
-	const projectRoot = opts.projectRoot ?? process.cwd();
-	const timeoutMs = opts.timeoutMs ?? Number.POSITIVE_INFINITY;
-	const headless = opts.headless === true;
-	let family;
-	let qrServer;
-	let attachWatcher;
-	let phase = "active";
-	let manualPrompt = null;
-	return {
-		async open() {
-			const { prepareAttach, renderAndMaybeWait, mintAttachUrl } = await import("../attach-orchestrator-DL3NQ9ca.js").then((n) => n.i);
-			const { injectDebugIndicator, injectGlobals } = await import("../cell-EBKKpAAT.js").then((n) => n.n);
-			const { loadRelaySecretReadOnly } = await import("../relay-secret-store-Bmyleu0A.js");
-			const { bootRelayFamily, buildRelayVerifyAuth, startAttachWatcher } = await import("../debug-server-B3ABDrRI.js");
-			const { buildChiiInspectorUrl } = await import("../devtools-opener-CJpEsXXQ.js");
-			const { generateTotp } = await import("../totp-CZLLKfOC.js").then((n) => n.i);
-			await loadRelaySecretReadOnly({ projectRoot });
-			let resolveTunnelUp;
-			const tunnelReady = new Promise((resolve) => {
-				resolveTunnelUp = resolve;
-			});
-			const booted = await bootRelayFamily({
-				verifyAuth: buildRelayVerifyAuth(),
-				onWssUrl: () => {
-					resolveTunnelUp();
-					qrServer?.notifyStateChange();
-				},
-				onTunnelDown: () => {
-					qrServer?.notifyStateChange();
-				}
-			});
-			family = booted;
-			if (booted.getTunnelStatus?.().up) resolveTunnelUp();
-			let lastAttachParts;
-			const attachDeps = {
-				getTunnelStatus: booted.getTunnelStatus ?? (() => ({
-					up: false,
-					wssUrl: null
-				})),
-				getTotpSecret: () => process.env.AIT_DEBUG_TOTP_SECRET,
-				qrHttpServer: void 0,
-				onAttachUrlBuilt: void 0,
-				canOpenBrowser: () => !headless
-			};
-			try {
-				const { startQrHttpServer } = await import("../qr-http-server-DrbIVDjO.js");
-				const getDashboardState = () => ({
-					tunnel: attachDeps.getTunnelStatus(),
-					pages: booted.connection.listTargets().map((t) => ({
-						id: t.id,
-						url: t.url
-					})),
-					attachUrl: lastAttachParts ? mintAttachUrl(attachDeps, lastAttachParts) : null,
-					mode: opts.attachLauncher === true ? "relay-mobile" : "relay-dev",
-					phase,
-					manualPrompt
-				});
-				const getDirectInspectorUrl = () => {
-					if (!booted.relayHttpUrl) return {
-						ok: false,
-						reason: "relayDown"
-					};
-					const targets = booted.connection.listTargets();
-					if (targets.length === 0) return {
-						ok: false,
-						reason: "noTarget"
-					};
-					const totpSecret = process.env.AIT_DEBUG_TOTP_SECRET;
-					if (!totpSecret) return {
-						ok: false,
-						reason: "totpUnavailable"
-					};
-					const url = buildChiiInspectorUrl(booted.relayHttpUrl, targets[0].id, () => generateTotp(totpSecret, Date.now()));
-					if (url === null) return {
-						ok: false,
-						reason: "totpUnavailable"
-					};
-					return {
-						ok: true,
-						url
-					};
-				};
-				qrServer = await startQrHttpServer(getDashboardState, {
-					dashboardPort: opts.dashboardPort,
-					getDirectInspectorUrl
-				});
-				attachDeps.qrHttpServer = qrServer;
-				attachDeps.onAttachUrlBuilt = (parts) => {
-					lastAttachParts = parts;
-					qrServer?.notifyStateChange();
-				};
-				attachWatcher = startAttachWatcher(booted.connection, void 0, 1e3, () => qrServer?.notifyStateChange(), () => qrServer?.notifyStateChange());
-				process.stderr.write(`devtools-test: QR dashboard: http://127.0.0.1:${qrServer.port}/\n`);
-			} catch {}
-			const TUNNEL_BOOT_TIMEOUT_MS = 15e3;
-			await Promise.race([tunnelReady, new Promise((resolve) => setTimeout(resolve, TUNNEL_BOOT_TIMEOUT_MS))]);
-			let prep;
-			if (opts.attachLauncher === true) {
-				const priorTunnelBaseUrl = process.env.AIT_TUNNEL_BASE_URL;
-				process.env.AIT_TUNNEL_BASE_URL = opts.appUrl ?? "";
-				try {
-					prep = await prepareAttach(attachDeps, "relay-mobile", {}, booted.connection);
-				} finally {
-					if (priorTunnelBaseUrl === void 0) delete process.env.AIT_TUNNEL_BASE_URL;
-					else process.env.AIT_TUNNEL_BASE_URL = priorTunnelBaseUrl;
-				}
-			} else prep = await prepareAttach(attachDeps, "relay-dev", { scheme_url: opts.schemeUrl }, booted.connection);
-			if (!prep.ok) {
-				booted.stop();
-				family = void 0;
-				attachWatcher?.stop();
-				attachWatcher = void 0;
-				await qrServer?.close();
-				qrServer = void 0;
-				throw new Error("createRelayConnectionFactory: attach preparation failed — check the scheme_url and that the relay tunnel is up");
-			}
-			const waitResult = await renderAndMaybeWait(attachDeps, prep, true, timeoutMs, booted.connection);
-			if (waitResult.isError) {
-				booted.stop();
-				family = void 0;
-				attachWatcher?.stop();
-				attachWatcher = void 0;
-				await qrServer?.close();
-				qrServer = void 0;
-				const timeoutSec = Math.round(timeoutMs / 1e3);
-				throw new Error(`createRelayConnectionFactory: attach timed out after ${timeoutSec}s — phone did not scan the QR within the timeout`);
-			}
-			const qrChunks = waitResult.content.filter((c) => c.type === "text").map((c) => c.text);
-			opts.onQrContent(qrChunks);
-			const PAGE_READY_RETRIES = 3;
-			const PAGE_READY_RETRY_DELAY_MS = 1500;
-			let lastEnableError;
-			for (let attempt = 1; attempt <= PAGE_READY_RETRIES; attempt++) try {
-				await booted.connection.enableDomains();
-				lastEnableError = void 0;
-				break;
-			} catch (err) {
-				lastEnableError = err instanceof Error ? err : new Error(String(err));
-				if (attempt < PAGE_READY_RETRIES) await new Promise((resolve) => setTimeout(resolve, PAGE_READY_RETRY_DELAY_MS));
-			}
-			if (lastEnableError !== void 0) {
-				booted.stop();
-				family = void 0;
-				attachWatcher?.stop();
-				attachWatcher = void 0;
-				await qrServer?.close();
-				qrServer = void 0;
-				throw new Error(`createRelayConnectionFactory: page did not become ready after ${PAGE_READY_RETRIES} attempts (${Math.round(PAGE_READY_RETRIES * PAGE_READY_RETRY_DELAY_MS / 1e3)}s) — the mini-app page may have disconnected before enableDomains() could open the CDP websocket`);
-			}
-			await injectDebugIndicator(booted.connection);
-			if (opts.cell !== void 0) await injectGlobals(booted.connection, { __AIT_CELL__: opts.cell });
-			if (opts.stubBlocking === true) await injectGlobals(booted.connection, { __AIT_STUB_BLOCKING__: true });
-			if (opts.paceMs !== void 0 && opts.paceMs > 0) await injectGlobals(booted.connection, { __AIT_PACE_MS__: opts.paceMs });
-			if (opts.paceMethodMs !== void 0 && opts.paceMethodMs > 0) await injectGlobals(booted.connection, { __AIT_PACE_METHOD_MS__: opts.paceMethodMs });
-			return booted.connection;
-		},
-		onSessionPhase(next) {
-			phase = next;
-			qrServer?.notifyStateChange();
-		},
-		onManualPrompt(next) {
-			manualPrompt = next;
-			qrServer?.notifyStateChange();
-		},
-		async close(connection) {
-			if (phase !== "complete") {
-				phase = "complete";
-				qrServer?.notifyStateChange();
-			}
-			try {
-				const { injectDebugIndicator } = await import("../cell-EBKKpAAT.js").then((n) => n.n);
-				await injectDebugIndicator(connection, { state: "disconnected" });
-			} catch {}
-			family?.stop();
-			family = void 0;
-			attachWatcher?.stop();
-			attachWatcher = void 0;
-			await qrServer?.close();
-			qrServer = void 0;
-		}
-	};
-}
-//#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/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).
-	*
-	* @param opts.timeoutMs - Per-call override for this connection's command
-	*   watchdog (devtools#747) — see the `CdpConnection.send` docblock for the
-	*   contract callers racing their own longer timeout must follow.
-	*/
-	send(method, params, opts) {
-		return this.sendCommand(method, params ?? {}, opts);
-	}
-	/**
-	* 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 `opts.timeoutMs` when given, else `commandTimeoutMs`
-	* (default 30s, env `AIT_CDP_COMMAND_TIMEOUT_MS`) — see devtools#747: the
-	* default 30s watchdog used to undercut the test-runner's own longer
-	* file-evaluate race no matter what `--timeout` the caller asked for. On
-	* timeout the pending entry is cleaned up and the promise rejects with a
-	* descriptive Korean error. `Number.isFinite` guards against a non-finite
-	* override (e.g. `Infinity`, mirroring `waitForFirstTarget`'s convention)
-	* so an intentional "no watchdog" override doesn't get clamped by
-	* `setTimeout`.
-	*/
-	sendCommand(method, params = {}, opts) {
-		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 = opts?.timeoutMs !== void 0 && Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0 ? opts.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.
-*
-* Bundles a single test file into a self-contained IIFE string that can be
-* injected into a WebView via `Runtime.evaluate`. The bundle includes the
-* test runtime (`runtime.ts`), which provides `describe/it/test/expect` and
-* the `runTestModule(factory)` entry point.
-*
-* ## How the wiring works
-*
-* The bundle exposes two exports on `globalThis.__testBundle`:
-*   - `runTestModule` — the runtime's entry function.
-*   - `__userFactory`  — an async function whose body is the user's top-level
-*     test registration code (describe/it/test calls).
-*
-* The Node-side RPC (`rpc.ts`) calls:
-*   `globalThis.__testBundle.runTestModule(globalThis.__testBundle.__userFactory)`
-*
-* `runTestModule` then installs `describe/it/test/expect` as globals, invokes
-* the factory (which registers all tests), runs them, and returns a `RunReport`.
-*
-* ## Why a factory wrapper is needed
-*
-* Naively adding the runtime to `entryPoints` and bundling the user file would
-* fail for two reasons:
-*   1. `describe/it/test/expect` from the runtime are module-local in the IIFE
-*      scope. The user's top-level `describe(...)` calls expect them as globals —
-*      they are not globals until `runTestModule` installs them.
-*   2. Even with globals pre-installed, the user file runs at IIFE-evaluation
-*      time, before the RPC layer calls `runTestModule` to reset state and start
-*      the test clock.
-*
-* The factory approach solves both: the user's registration code is deferred
-* into a function that `runTestModule` calls AFTER installing the globals.
-*
-* ## Factory extraction algorithm
-*
-* The `userFactoryPlugin` reads the user file and splits lines into:
-*   - **top-level**: `import …` and re-export lines — kept at module scope
-*     (the only valid position for static `import` in ESM).
-*   - **body**: all other statements — moved into the body of the exported
-*     `__userFactory` async function.
-*
-* esbuild processes the re-generated module, following each static import
-* through the normal dependency graph (including the SDK-redirect plugin).
-*
-* ## SDK redirect
-*
-* Imports of `@apps-in-toss/web-framework` (and sub-paths) are intercepted via
-* the `sdkRedirectPlugin` and replaced with a virtual `window.__sdk` proxy that
-* `src/in-app/auto.ts` installs at runtime. This works for both 2.x and 3.x SDK.
-*
-* SECRET-HANDLING: the returned bundle code is caller-managed; never log it.
-*/
-/** The SDK package name that mini-app test code imports from. */
-const SDK_PACKAGE = "@apps-in-toss/web-framework";
-/**
-* Names the runtime installs as globals before invoking the user factory.
-* The `vitest` virtual module re-exports each as a lazy getter that reads from
-* `globalThis` at access time. Keep in sync with the globals installed in
-* `runtime.ts#runTestModule`.
-*/
-const VITEST_GLOBAL_NAMES = [
-	"describe",
-	"it",
-	"test",
-	"expect",
-	"beforeAll",
-	"afterAll",
-	"beforeEach",
-	"afterEach",
-	"vi"
-];
-/**
-* Matches the bare SDK package and any sub-path import
-* (`@apps-in-toss/web-framework`, `@apps-in-toss/web-framework/foo`).
-* Built from {@link SDK_PACKAGE} so the package name has a single source.
-*/
-const SDK_IMPORT_FILTER = new RegExp(`^${SDK_PACKAGE.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`);
-/**
-* esbuild plugin that intercepts SDK imports and redirects them to the
-* `window.__sdk` proxy that `src/in-app/auto.ts` installs at runtime.
-*
-* Strategy: for every import of `@apps-in-toss/web-framework` (or sub-paths),
-* esbuild resolves it to a virtual module that re-exports all named exports
-* via `window.__sdk[name]`. This avoids bundling the real SDK (which may not
-* be available in the test environment) while still making named imports work.
-*
-* If `window.__sdk` is absent (non-dog-food build), every access throws a
-* descriptive error rather than returning `undefined` silently.
-*
-* Bridge-stub interception (devtools#740, DT-2): the virtual module runs the
-* resolved `window.__sdk` object through `wrapSdkWithStub` before exporting
-* it. `wrapSdkWithStub` is a pass-through (returns the same object,
-* unwrapped) unless `isStubBlockingEnabled()` reads `true` off
-* `globalThis.__AIT_STUB_BLOCKING__` — an opt-in flag injected the same way
-* `__AIT_CELL__` is (`cell.ts#injectGlobals`, wired from the CLI's
-* `--stub-blocking` flag). Default off => zero behavior change: every existing
-* (non-stub) test run resolves the exact same `window.__sdk` reference it did
-* before this plugin learned about stubbing.
-*
-* Per-method pacing (devtools#769): BEFORE the stub wrap, `window.__sdk` is
-* run through `wrapWithMethodPacing`, which enforces a minimum interval
-* between calls to the SAME named SDK function (`getPaceMethodMs()` reads the
-* `__AIT_PACE_METHOD_MS__` page global — see `method-pace.ts`). Composition
-* order is pacing INSIDE the stub (`wrapSdkWithStub(wrapWithMethodPacing(sdk,
-* gap), enabled)`): a stubbed name resolves instantly from
-* `bridge-stub.ts`'s fixtures without ever reaching the paced wrapper, and
-* only calls that fall through to the real bridge — the ones that can
-* actually trigger `APP_BRIDGE_THROTTLED` — pay the pacing cost. `gapMs <= 0`
-* (default, no `--pace-method` / non-2.x cell) is a no-op fast path — see
-* `method-pace.ts#wrapWithMethodPacing`'s doc for the full contract.
-*/
-/**
-* Builds the virtual CommonJS-style module contents the `sdk-redirect`
-* esbuild plugin loads for every `@apps-in-toss/web-framework` import.
-*
-* Pulled out to a pure, exported function (rather than inlined at the
-* `build.onLoad` call site) so unit tests can assert the exact composition
-* order (pacing wraps the raw SDK; the stub wraps the paced result) as a
-* string-level contract, independent of esbuild — esbuild cannot run inside
-* this repo's jsdom vitest environment (see `bundleTestFile`'s module doc's
-* lazy-import note), so a real bundling round-trip is out of unit-test reach
-* here; `wrapSdkWithStub`/`wrapWithMethodPacing`'s own composed-call behavior
-* is covered directly (see `bundle.test.ts`).
-*
-* Generates a virtual CommonJS-style module so that esbuild does NOT perform
-* strict named-export matching. When `format:'iife'` bundles a CJS module, it
-* wraps it with its own `__toCommonJS` helper and satisfies named imports via
-* property access on the `module.exports` object — which is our Proxy. This
-* means `import { getPlatformOS } from '...'` becomes
-* `__proxy.getPlatformOS` at runtime, which correctly reads from
-* `window.__sdk`.
-*
-* The bridge-stub and method-pace imports are STATIC imports of the real
-* `bridge-stub.ts`/`method-pace.ts` modules (not inlined JS) so esbuild
-* bundles each once and the fixture registry / pacing registry have a single
-* source of truth shared with their own unit tests.
-*
-* Exported for unit testing.
-*/
-function buildSdkRedirectModuleContents() {
-	return `
-import { wrapSdkWithStub, isStubBlockingEnabled } from ${JSON.stringify(getBridgeStubPath())};
-import { wrapWithMethodPacing, getPaceMethodMs } from ${JSON.stringify(getMethodPacePath())};
-var __rawSdk = (typeof window !== 'undefined' && window.__sdk)
-  ? window.__sdk
-  : new Proxy({}, {
-      get: function(_t, p) {
-        throw new Error('window.__sdk is not installed — run in a dog-food build. Missing: ' + String(p));
-      }
-    });
-var __pacedSdk = wrapWithMethodPacing(__rawSdk, getPaceMethodMs());
-var __proxy = wrapSdkWithStub(__pacedSdk, isStubBlockingEnabled());
-module.exports = __proxy;
-`;
-}
-function sdkRedirectPlugin() {
-	return {
-		name: "sdk-redirect",
-		setup(build) {
-			build.onResolve({ filter: SDK_IMPORT_FILTER }, (args) => ({
-				path: args.path,
-				namespace: "sdk-redirect"
-			}));
-			build.onLoad({
-				filter: /.*/,
-				namespace: "sdk-redirect"
-			}, () => ({
-				contents: buildSdkRedirectModuleContents(),
-				loader: "js",
-				resolveDir: process.cwd()
-			}));
-		}
-	};
-}
-/**
-* esbuild plugin that intercepts `import … from 'vitest'` and replaces it with
-* a virtual module that delegates every named import to `globalThis` at ACCESS
-* time (not at bundle-evaluation time).
-*
-* The runtime installs `describe/it/test/expect/beforeAll/afterAll/beforeEach/
-* afterEach/vi` as globals inside `runTestModule`, which runs AFTER the bundle
-* IIFE is evaluated. A value-copy redirect (`export var describe =
-* globalThis.describe`) would therefore capture `undefined` at evaluation time
-* and the user's `describe(...)` calls would be no-ops — registering zero tests.
-*
-* The fix defers the lookup to call time using per-name **getter** exports.
-* We emit a CommonJS module that:
-*   1. sets `__esModule = true` so esbuild's `__toESM` interop maps each named
-*      import directly to a property access on the module (NOT wrapped under a
-*      `default` shim — which is what happens for a bare Proxy whose own-keys
-*      are empty, leaving every named import `undefined`);
-*   2. defines each global name as a getter that reads `globalThis[name]` on
-*      every access. So `import { describe } from 'vitest'` compiles to
-*      `import_vitest.describe`, whose getter returns the real `describe` only
-*      when the factory calls it — after `runTestModule` installs the globals.
-*
-* A plain `module.exports = new Proxy(...)` does NOT work here: esbuild routes
-* the virtual module through `__toESM`, which enumerates own-keys (none on an
-* empty Proxy target) and therefore exposes zero named exports. Explicit getter
-* properties give `__toESM` real keys to map while keeping access lazy.
-*/
-function vitestRedirectPlugin() {
-	return {
-		name: "vitest-redirect",
-		setup(build) {
-			build.onResolve({ filter: /^vitest$/ }, () => ({
-				path: "vitest",
-				namespace: "vitest-redirect"
-			}));
-			build.onLoad({
-				filter: /^vitest$/,
-				namespace: "vitest-redirect"
-			}, () => {
-				return {
-					contents: `Object.defineProperty(exports, '__esModule', { value: true });\n${VITEST_GLOBAL_NAMES.map((name) => `Object.defineProperty(exports, ${JSON.stringify(name)}, { enumerable: true, get: function() { return globalThis[${JSON.stringify(name)}]; } });`).join("\n")}\n`,
-					loader: "js"
-				};
-			});
-		}
-	};
-}
-/**
-* esbuild plugin that transforms the user test file into a module that exports
-* an async `__userFactory` function. The factory defers the user's top-level
-* test registration code (describe/it/test calls) so it only runs when
-* `runTestModule(__userFactory)` explicitly invokes it — AFTER the runtime has
-* installed describe/it/test/expect as globals.
-*
-* Algorithm:
-*   - Import declarations and re-export statements are kept at module top-level
-*     (the only valid ESM position for static `import`). A statement that spans
-*     multiple lines — e.g. a named import with one member per line:
-*       import {
-*         appLogin,
-*         getAnonymousKey,
-*       } from '@apps-in-toss/web-framework';
-*     is tracked as a single block: every line from the opening `import {` /
-*     `export {` through the closing `from '…'` (or side-effect `'…'`) line is
-*     kept together at top-level. This prevents the member lines and the
-*     closing `} from '…'` line from leaking into the factory body, which would
-*     leave an unterminated `import {` at module scope (the #678 env3 failure:
-*     esbuild threw `Expected "as" but found "{"` on multi-line SDK imports).
-*   - All other lines (describe/it/test calls, local declarations, etc.) are
-*     moved into the body of the exported async factory function.
-*
-* This preserves SDK import resolution (the sdk-redirect plugin processes
-* top-level imports normally) while deferring test registration to the factory.
-*/
-function userFactoryPlugin(absPath) {
-	const NAMESPACE = "user-test-factory";
-	return {
-		name: "user-test-factory",
-		setup(build) {
-			build.onResolve({ filter: /^user-test-factory$/ }, () => ({
-				path: absPath,
-				namespace: NAMESPACE
-			}));
-			build.onLoad({
-				filter: /.*/,
-				namespace: NAMESPACE
-			}, async (args) => {
-				const lines = (await fs.readFile(args.path, "utf8")).split("\n");
-				const topLevelLines = [];
-				const bodyLines = [];
-				const EXPORT_DECLARATION_RE = /^(export\s+)(default\s+|async\s+function\s+|function\s+|class\s+|const\s+|let\s+|var\s+)/;
-				const isImportStart = (trimmed) => trimmed.startsWith("import ") || trimmed.startsWith("import{") || trimmed.startsWith("import'") || trimmed.startsWith("import\"");
-				const endsStatement = (trimmed) => /['"]\s*;?\s*$/.test(trimmed.replace(/\/\/.*$/, "").trimEnd());
-				let inImportBlock = false;
-				for (const line of lines) {
-					const trimmed = line.trimStart();
-					const indent = line.slice(0, line.length - trimmed.length);
-					if (inImportBlock) {
-						topLevelLines.push(line);
-						if (endsStatement(trimmed)) inImportBlock = false;
-						continue;
-					}
-					if (isImportStart(trimmed)) {
-						topLevelLines.push(line);
-						if (!endsStatement(trimmed)) inImportBlock = true;
-					} else if (trimmed.startsWith("export ")) if (trimmed.match(EXPORT_DECLARATION_RE)) bodyLines.push(indent + trimmed.slice(7));
-					else {
-						topLevelLines.push(line);
-						if (/\bfrom\b/.test(trimmed) ? !endsStatement(trimmed) : trimmed.endsWith("{")) inImportBlock = true;
-					}
-					else bodyLines.push(line);
-				}
-				return {
-					contents: [
-						...topLevelLines,
-						"",
-						"// biome-ignore lint: generated factory wrapper",
-						"export default async function __userFactory(): Promise<void> {",
-						...bodyLines.map((l) => `  ${l}`),
-						"}"
-					].join("\n"),
-					loader: "ts",
-					resolveDir: path$1.dirname(absPath)
-				};
-			});
-		}
-	};
-}
-/**
-* Returns the absolute filesystem path to a page-side leaf module shipped
-* alongside `bundle.ts` in dist (e.g. `runtime.js`, `bridge-stub.js`) — a
-* fully self-contained module with no further page-side deps of its own.
-*
-* Rolldown code-splitting duplicates this bundling logic into shared chunks
-* emitted at ARBITRARY dist depths: the `devtools-test` CLI pulls it from
-* dist/test-runner/bundle.js (dir = dist/test-runner/), while the `devtools-mcp`
-* daemon (dist/mcp/cli.js) pulls it through a ROOT chunk
-* (dist/debug-server-<hash>.js, dir = dist/). A fixed `..`-hop candidate list
-* is therefore wrong from at least one chunk — the live #697 regression.
-*
-* This resolves WITHOUT assuming chunk depth: from `import.meta.url`'s dir it
-* probes the co-located `<name>.js` and the nested `test-runner/<name>.js`,
-* then ascends one directory at a time (bounded) repeating both probes. The
-* nested probe catches dist/test-runner/<name>.js from the dist/ root level no
-* matter which depth the chunk was hoisted to (root, dist/mcp/, or a future
-* relocation). The build always emits dist/test-runner/<name>.js (tsdown entry
-* `'test-runner/<name>'`; guarded by scripts/check-test-runner-dist.sh for
-* `runtime`).
-*
-* An ABSOLUTE path is returned deliberately: esbuild loads it as a literal file
-* read, bypassing Node module resolution entirely, so this works identically in
-* the npx-daemon context (its own dist tree) and the consumer-CLI context
-* (the mini-app's installed @ait-co/devtools dist) — neither needs the package
-* to be node-resolvable from the caller.
-*
-* @param moduleName - The leaf module's basename without extension, e.g.
-*   `'runtime'` or `'bridge-stub'`.
-*/
-function getPageSideModulePath(moduleName) {
-	const startDir = path$1.dirname(fileURLToPath(import.meta.url));
-	const RELATIVE_PROBES = [
-		[`${moduleName}.js`],
-		["test-runner", `${moduleName}.js`],
-		[`${moduleName}.ts`],
-		["test-runner", `${moduleName}.ts`]
-	];
-	let dir = startDir;
-	for (let i = 0; i < 12; i++) {
-		for (const segs of RELATIVE_PROBES) {
-			const candidate = path$1.join(dir, ...segs);
-			try {
-				accessSync(candidate);
-				return candidate;
-			} catch {}
-		}
-		const parent = path$1.dirname(dir);
-		if (parent === dir) break;
-		dir = parent;
-	}
-	return path$1.join(startDir, `${moduleName}.js`);
-}
-/** Absolute path to the test-runner page-side runtime (describe/it/test/expect). */
-function getRuntimePath() {
-	return getPageSideModulePath("runtime");
-}
-/**
-* Absolute path to the bridge-stub interceptor (devtools#740, DT-2) —
-* `wrapSdkWithStub`/`isStubBlockingEnabled`, statically imported by the
-* `sdk-redirect` virtual module.
-*/
-function getBridgeStubPath() {
-	return getPageSideModulePath("bridge-stub");
-}
-/**
-* Absolute path to the per-method pacing wrapper (devtools#769) —
-* `wrapWithMethodPacing`/`getPaceMethodMs`, statically imported by the
-* `sdk-redirect` virtual module.
-*/
-function getMethodPacePath() {
-	return getPageSideModulePath("method-pace");
-}
-/**
-* Bundles `absPath` into a single IIFE string suitable for `Runtime.evaluate`.
-*
-* The IIFE installs `window.__testBundle` (or the custom `globalName`) with:
-*   - `runTestModule` — the runtime entry (from `runtime.ts`).
-*   - `__userFactory` — an async function wrapping the user's test registration
-*     code so it runs AFTER `runTestModule` installs the globals.
-*
-* Callers (rpc.ts) invoke:
-*   `globalThis.__testBundle.runTestModule(globalThis.__testBundle.__userFactory)`
-*
-* @param absPath - Absolute path to the user test file.
-* @param opts    - Optional bundling overrides.
-*/
-async function bundleTestFile(absPath, opts) {
-	const globalName = opts?.globalName ?? "__testBundle";
-	const extraExternals = opts?.extraExternals ?? [];
-	const esbuild = await import("esbuild");
-	const runtimePath = getRuntimePath();
-	const wrapperContent = [
-		`import { runTestModule } from ${JSON.stringify(runtimePath)};`,
-		`import __userFactory from "user-test-factory";`,
-		`export { runTestModule, __userFactory };`
-	].join("\n");
-	const result = await esbuild.build({
-		stdin: {
-			contents: wrapperContent,
-			loader: "ts",
-			resolveDir: path$1.dirname(absPath)
-		},
-		bundle: true,
-		format: "iife",
-		globalName,
-		platform: "browser",
-		target: "es2022",
-		write: false,
-		plugins: [
-			userFactoryPlugin(absPath),
-			vitestRedirectPlugin(),
-			sdkRedirectPlugin()
-		],
-		external: extraExternals,
-		treeShaking: true,
-		footer: { js: `globalThis[${JSON.stringify(globalName)}] = ${globalName};` }
-	});
-	const warnings = result.warnings.map((w) => `${path$1.relative(process.cwd(), w.location?.file ?? "")}:${w.location?.line ?? "?"}: ${w.text}`);
-	const outputFile = result.outputFiles?.[0];
-	if (!outputFile) throw new Error("bundleTestFile: esbuild produced no output — check entryPoints");
-	return {
-		code: outputFile.text,
-		warnings
-	};
-}
-//#endregion
-//#region src/test-runner/capture.ts
-/** The exact console-line prefix sdk-example's `flushCapture` emits. */
-const CAPTURE_PREFIX = "__AIT_CAPTURE__ ";
-/**
-* Parses raw console line texts into {@link AitCaptureLine}s.
-*
-* Filtering rules (each independently drops a line — never throws):
-*   - the line text must `startsWith(CAPTURE_PREFIX)` exactly (allowlist);
-*   - there must be a non-empty category token (up to the next space);
-*   - the remaining payload must be valid JSON (`JSON.parse` succeeds).
-*
-* Lines that fail any rule (wss/scheme noise, truncated, broken JSON) are
-* silently discarded — capture harvesting is best-effort and must never fail a
-* run or leak a malformed/secret-bearing line.
-*
-* @param raw - Console line objects (only `.text` is read).
-* @returns The captured lines, in input order.
-*/
-function parseCaptureLines(raw) {
-	const out = [];
-	for (const { text } of raw) {
-		if (!text.startsWith(CAPTURE_PREFIX)) continue;
-		const body = text.slice(16);
-		const spaceIdx = body.indexOf(" ");
-		if (spaceIdx === -1) continue;
-		const category = body.slice(0, spaceIdx);
-		const json = body.slice(spaceIdx + 1);
-		if (category === "" || json === "") continue;
-		try {
-			JSON.parse(json);
-		} catch {
-			continue;
-		}
-		out.push({
-			category,
-			json
-		});
-	}
-	return out;
-}
-//#endregion
-//#region src/test-runner/rpc.ts
-/** Maximum milliseconds to wait for a single evaluate round-trip. */
-const DEFAULT_TIMEOUT_MS = 6e4;
-/**
-* Extra headroom (ms) added on top of the rpc-level `timeoutMs` when telling
-* the underlying `CdpConnection` its per-command watchdog budget (devtools#747).
-* The rpc-level race above is the authoritative file timeout — this margin
-* only ensures the connection's own (shorter-by-default) watchdog never fires
-* first and masks the rpc-level timeout error with a connection-level one.
-*/
-const CONNECTION_TIMEOUT_MARGIN_MS = 5e3;
-/**
-* Wraps bundle code in a self-executing IIFE that:
-*   1. Evaluates the bundle (registering describe/it/test).
-*   2. Calls `__testBundle.runTestModule(...)` — the entry the runtime exports.
-*   3. Returns a JSON-serialised `RunReport` string.
-*
-* The double-serialisation (RunReport → JSON string → returnByValue string)
-* is intentional: CDP `returnByValue` reliably transports strings; deeply
-* nested objects can lose fidelity across the Chii relay.
-*
-* SECRET-HANDLING: `bundleCode` MUST NOT be logged by callers.
-*/
-function buildRunTestsExpression(bundleCode) {
-	return `(async () => {  try { ${bundleCode} } catch(e) {    return JSON.stringify({ok:false,error:'bundle-eval: ' + String(e && e.message || e)});  }  if (typeof globalThis.__testBundle !== 'object' || typeof globalThis.__testBundle.runTestModule !== 'function' || typeof globalThis.__testBundle.__userFactory !== 'function') {    return JSON.stringify({ok:false,error:'bundle-missing-export: __testBundle.runTestModule or __userFactory is not a function'});  }  try {    const report = await globalThis.__testBundle.runTestModule(globalThis.__testBundle.__userFactory);    return JSON.stringify({ok:true,value:report});  } catch(e) {    return JSON.stringify({ok:false,error:'test-run: ' + String(e && e.message || e)});  }})()`;
-}
-/**
-* Parses the raw CDP `returnByValue` result from a `buildRunTestsExpression`
-* evaluate call into a typed `RpcRunResult`.
-*
-* Throws only on parse failure — an `ok:false` envelope is a normal result.
-*
-* SECRET-HANDLING: `rawValue` is not included in error messages.
-*/
-function parseRunTestsResult(rawValue) {
-	if (typeof rawValue !== "string") throw new Error(`rpc.parseRunTestsResult: unexpected return type "${typeof rawValue}" — expected JSON string`);
-	let parsed;
-	try {
-		parsed = JSON.parse(rawValue);
-	} catch {
-		throw new Error("rpc.parseRunTestsResult: bridge returned non-JSON string");
-	}
-	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("rpc.parseRunTestsResult: parsed result is not an object");
-	const obj = parsed;
-	if (obj.ok === true) return {
-		ok: true,
-		report: obj.value
-	};
-	if (obj.ok === false) return {
-		ok: false,
-		error: typeof obj.error === "string" ? obj.error : String(obj.error)
-	};
-	throw new Error("rpc.parseRunTestsResult: result missing \"ok\" field");
-}
-/**
-* Injects `bundleCode` into the attached page and awaits test execution.
-*
-* Uses `Runtime.evaluate` with `awaitPromise: true` to wait for the
-* async IIFE to settle. `timeoutMs` (default 60s) is the authoritative file
-* timeout — this function races it against the evaluate call AND (devtools#747)
-* threads it down to the underlying `CdpConnection`'s own per-command watchdog
-* (plus a small margin) so that watchdog can never undercut this race. Split
-* into smaller files if you hit the timeout.
-*
-* @param connection   - Active CDP connection (relay or local).
-* @param bundleCode   - IIFE bundle string from `bundleTestFile`.
-* @param timeoutMs    - Override the default 60 s timeout.
-*
-* SECRET-HANDLING: `bundleCode` and the raw CDP result value are never logged.
-*/
-async function injectAndRunBundle(connection, bundleCode, timeoutMs = DEFAULT_TIMEOUT_MS) {
-	const expression = buildRunTestsExpression(bundleCode);
-	const TIMEOUT_SENTINEL = Symbol("timeout");
-	const timeoutPromise = new Promise((resolve) => setTimeout(() => resolve(TIMEOUT_SENTINEL), timeoutMs));
-	const evalPromise = connection.send("Runtime.evaluate", {
-		expression,
-		returnByValue: true,
-		awaitPromise: true
-	}, { timeoutMs: timeoutMs + CONNECTION_TIMEOUT_MARGIN_MS });
-	const raceResult = await Promise.race([evalPromise.then((v) => ({
-		tag: "eval",
-		v
-	})), timeoutPromise.then(() => ({ tag: "timeout" }))]);
-	if (raceResult.tag === "timeout") return {
-		ok: false,
-		error: `rpc: evaluate timed out after ${timeoutMs}ms`
-	};
-	const cdpResult = raceResult.v;
-	if (cdpResult.exceptionDetails) {
-		const msg = cdpResult.exceptionDetails.exception?.description ?? cdpResult.exceptionDetails.text ?? "Runtime.evaluate threw an exception";
-		throw new Error(`rpc.injectAndRunBundle: ${msg}`);
-	}
-	return parseRunTestsResult(cdpResult.result.value);
-}
-//#endregion
-//#region src/test-runner/relay-worker.ts
-/**
-* Per-file evaluate timeout (ms) for manual-variant files (devtools#741) — a
-* human is expected to be tapping through a native sheet, so the timeout must
-* be far longer than the unattended default (60s, rpc.ts DEFAULT_TIMEOUT_MS).
-* Fixed constant (not configurable in v1) — documented here + CLI `--help`.
-*/
-const MANUAL_FILE_TIMEOUT_MS = 5 * 6e4;
-/**
-* Sentinel string embedded in the error message by `injectAndRunBundle` when
-* the per-file evaluate race hits the timeout. Used by the retry guard so only
-* genuine timeouts get a second attempt — not bundle errors or parse failures.
-*
-* Exported for unit tests that assert the retry path is taken.
-*/
-const EVALUATE_TIMEOUT_MARKER = "rpc: evaluate timed out after";
-/**
-* Runs all `files` sequentially over the given CDP `connection`.
-*
-* For each file:
-*   1. Bundle with esbuild (includes SDK shim + runtime).
-*   2. Inject into the attached page via `Runtime.evaluate`.
-*   3. Await the `RunReport` JSON response.
-*   4. Accumulate results.
-*
-* Returns a `RelayRunReport` with per-file results and flattened totals.
-*
-* This function does NOT open or manage the relay connection — the caller
-* is responsible for attaching and closing it.
-*
-* TODO (#645): implement the Vitest `PoolRunnerInitializer` interface here
-* so that `runTestFilesOverRelay` can be used as a Vitest pool entry.
-*
-* @param connection - Active CDP connection (relay or local kind).
-* @param files      - Absolute paths to test files, run in order.
-* @param opts       - Optional per-run overrides.
-*/
-async function runTestFilesOverRelay(connection, files, opts) {
-	const wallStart = Date.now();
-	const startedAt = new Date(wallStart).toISOString();
-	const fileResults = [];
-	let domainsEnabled = false;
-	try {
-		await connection.enableDomains();
-		domainsEnabled = true;
-	} catch (e) {
-		process.stderr.write(`relay-worker: enableDomains() failed before run — console capture may be empty (${e instanceof Error ? e.message : String(e)})\n`);
-	}
-	const collectCaptures = opts?.collectCaptures === true;
-	const liveConsole = [];
-	let unsubscribeConsole;
-	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`);
-		}
-	};
-	const manualFiles = opts?.manualFiles;
-	const manualTotal = manualFiles?.size ?? 0;
-	let manualIndex = 0;
-	const stubBlockingFiles = opts?.stubBlockingFiles;
-	let preflightPermissions;
-	if (files.length > 0) preflightPermissions = await runPermissionPreflight(connection, PERMISSION_PREFLIGHT_TIMEOUT_MS, opts?.preflightSdkLine !== "3.x");
-	const paceMs = opts?.paceMs;
-	let ranFirstFile = false;
-	try {
-		for (const file of files) {
-			if (pendingReconnectCheck) {
-				await attemptReconnect("next-file");
-				pendingReconnectCheck = false;
-			}
-			if (paceMs !== void 0 && paceMs > 0 && ranFirstFile) await new Promise((resolve) => setTimeout(resolve, paceMs));
-			ranFirstFile = true;
-			const isStubbed = stubBlockingFiles?.has(file) === true;
-			const isManual = !isStubbed && manualFiles?.has(file) === true;
-			if (isManual) {
-				manualIndex += 1;
-				opts?.onManualFile?.(file, manualIndex, manualTotal);
-			}
-			const fileTimeoutMs = isManual ? MANUAL_FILE_TIMEOUT_MS : opts?.timeoutMs;
-			let fileEntry;
-			try {
-				const { code } = await bundleTestFile(file, opts?.bundleOptions);
-				/**
-				* Runs one evaluate attempt and returns a FileResult, or `null` when the
-				* result is a genuine timeout and the caller should retry.
-				*
-				* 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 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` (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;
-					try {
-						rpcResult = await injectAndRunBundle(connection, code, fileTimeoutMs);
-					} catch (e) {
-						return {
-							file,
-							result: { error: e instanceof Error ? e.message : String(e) }
-						};
-					}
-					if (rpcResult.ok) return {
-						file,
-						result: rpcResult.report
-					};
-					if (rpcResult.error.includes("rpc: evaluate timed out after")) return null;
-					return {
-						file,
-						result: { error: rpcResult.error }
-					};
-				};
-				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 ?? 6e4}ms (after retry) — the device's app may have been backgrounded` }
-					};
-				}
-			} catch (e) {
-				fileEntry = {
-					file,
-					result: { error: e instanceof Error ? e.message : String(e) }
-				};
-			}
-			if ("error" in fileEntry.result && isRelayDisconnectMessage(fileEntry.result.error)) pendingReconnectCheck = true;
-			if (isStubbed) fileEntry.mode = "stubbed";
-			else if (isManual) fileEntry.mode = "manual";
-			fileResults.push(fileEntry);
-		}
-	} finally {
-		unsubscribeConsole?.();
-	}
-	const captures = collectCaptures ? parseCaptureLines(liveConsole.map((e) => ({ text: renderConsoleLineText(e) }))) : [];
-	const totals = fileResults.reduce((acc, { result }) => {
-		if ("error" in result) {
-			acc.failed += 1;
-			acc.total += 1;
-		} else {
-			acc.passed += result.passed;
-			acc.failed += result.failed;
-			acc.skipped += result.skipped;
-			acc.total += result.passed + result.failed + result.skipped;
-		}
-		return acc;
-	}, {
-		passed: 0,
-		failed: 0,
-		skipped: 0,
-		total: 0
-	});
-	return {
-		startedAt,
-		duration: Date.now() - wallStart,
-		files: fileResults,
-		totals,
-		captures,
-		...preflightPermissions ? { preflight: { permissions: preflightPermissions } } : {}
-	};
-}
-/**
-* Renders one `Runtime.consoleAPICalled` event to a single line of text, the
-* same way `tools.ts#normalizeConsoleMessage` does (args rendered + space-
-* joined). Inlined here (≈8 lines) so this module avoids importing `tools.ts`,
-* which would drag the heavy MCP/Node graph (server-lock, parent-watcher, …)
-* onto the test-runner entry.
-*
-* SECRET-HANDLING: this only stringifies console args; the caller's
-* allowlist-prefix parser then discards everything that is not a genuine
-* `__AIT_CAPTURE__` line.
-*/
-function renderConsoleLineText(event) {
-	return event.args.map((arg) => {
-		if (arg.value !== void 0) {
-			if (typeof arg.value === "string") return arg.value;
-			try {
-				return JSON.stringify(arg.value);
-			} catch {
-				return String(arg.value);
-			}
-		}
-		if (arg.description !== void 0) return arg.description;
-		if (arg.className !== void 0) return arg.className;
-		return arg.subtype ?? arg.type;
-	}).join(" ");
-}
-//#endregion
-//#region src/test-runner/report.ts
-/**
-* Runner-agnostic report serialisation for env3 test runs (devtools#696).
-*
-* Both env3 execution paths — the Vitest custom pool (`pool.ts`) and the
-* standalone `devtools-test` CLI (`cli.ts`) — call the same core
-* `runTestFilesOverRelay` and so produce the same {@link RelayRunReport}. This
-* module is the single, runner-neutral place that turns that in-memory report
-* into a stable on-disk artifact so a 2.x run and a 3.0 run can be diffed
-* cell-by-cell after the fact.
-*
-* The serialised schema is deliberately MINIMAL and secret-free:
-*
-*   - file paths are stored RELATIVE to `projectRoot` (no absolute `/Users/...`
-*     leakage — see {@link RunnerAgnosticReport.files});
-*   - the cell metadata (sdkLine/platform) is baked INTO the body, not only the
-*     filename, so a moved artifact never loses its provenance;
-*   - NO relay wss / scheme / TOTP / relayUrl fields exist in the schema at all
-*     (enforced by the type + this comment) — error strings are the matcher
-*     message only, inherited from rpc.ts which already strips expression/value.
-*
-* react-free — depends only on the type-level `RelayRunReport` and `node:fs` /
-* `node:path`. Safe to bundle without pulling the chii/cloudflared graph.
-*/
-/**
-* Converts an absolute (or already-relative) file path to a projectRoot-relative
-* one. `path.relative` returns `''` when the paths are equal — guard that to the
-* basename so the field is never empty.
-*
-* SECRET-HANDLING: this is the single choke point that strips absolute project
-* paths from the artifact.
-*/
-function relativise(projectRoot, file) {
-	const rel = path.relative(projectRoot, file);
-	if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) return path.basename(file);
-	return rel;
-}
-/**
-* Serialises a {@link RelayRunReport} into the runner-agnostic, secret-free
-* on-disk shape. Pure — no IO; testable with a plain report + meta.
-*
-* @param report - The core relay run report.
-* @param meta   - Cell axes + projectRoot (projectRoot is consumed, not stored).
-*/
-function serializeRelayReport(report, meta) {
-	return {
-		cell: {
-			sdkLine: meta.sdkLine,
-			platform: meta.platform
-		},
-		startedAt: report.startedAt,
-		duration: report.duration,
-		totals: report.totals,
-		...report.preflight ? { preflight: report.preflight } : {},
-		files: report.files.map((f) => {
-			const file = relativise(meta.projectRoot, f.file);
-			const modeField = f.mode === "manual" || f.mode === "stubbed" ? { mode: f.mode } : {};
-			if ("error" in f.result) return {
-				file,
-				error: f.result.error,
-				...modeField
-			};
-			return {
-				file,
-				duration: f.result.duration,
-				passed: f.result.passed,
-				failed: f.result.failed,
-				skipped: f.result.skipped,
-				tests: f.result.tests,
-				...modeField
-			};
-		})
-	};
-}
-/**
-* Writes the serialised report to `<dir>/<sdkLine>.<platform>.json`, creating
-* `dir` if needed. Returns the absolute path(s) written.
-*
-* The cell-suffixed filename keeps 2.x and 3.0 (and per-platform) runs as
-* distinct artifacts in the same directory; the same cell metadata is also baked
-* into the body so a renamed/moved file still carries its provenance.
-*
-* Manual-run provenance (devtools#741): when `report.files` contains ANY
-* `mode: 'manual'` entry (i.e. this run included `--manual-blocking` files),
-* the manual-tagged files are written to a SEPARATE
-* `<dir>/<sdkLine>.<platform>.manual.json` artifact instead of the standard
-* one — the standard `<sdkLine>.<platform>.json` filename is reserved for the
-* regular (unattended) files only, so a manual run's presence never mutates
-* what the unattended-baseline filename means.
-*
-* Stub-blocking provenance (devtools#740, DT-2): `mode: 'stubbed'` files are
-* written to a THIRD, separate `<dir>/<sdkLine>.<platform>.stubbed.json`
-* artifact — never merged into the standard file (it is unattended, like the
-* standard file, so a naive filename split could conflate the two) and never
-* merged into `.manual.json` (it did NOT have a human present). Its body is
-* ALSO stamped `cell.bridgeStub: true` — the mandatory HYBRID-cell provenance
-* from the issue: a stubbed result must never be silently mixed into the
-* real-device baseline report.
-*
-* If ALL files in the run are regular, only the standard artifact is written
-* (today's behavior, unchanged). Any combination of the three modes present
-* in a single run writes ONLY the corresponding artifacts — each is additive,
-* never replacing another.
-*
-* SECRET-HANDLING: the written body contains no relay/secret fields (the schema
-* has none). `dir`/`projectRoot` are local filesystem paths, never logged here.
-*
-* @param report - The core relay run report.
-* @param dir    - Output directory (created recursively if missing).
-* @param meta   - Cell axes + projectRoot.
-* @returns The absolute path(s) written, in order: standard first (if any
-*   regular files ran), then manual (if any manual files ran), then stubbed
-*   (if any stubbed files ran). At least one path is always returned when
-*   `report.files` is non-empty.
-*/
-async function writeReportArtifact(report, dir, meta) {
-	const serialised = serializeRelayReport(report, meta);
-	await mkdir(dir, { recursive: true });
-	const regularFiles = serialised.files.filter((f) => f.mode === void 0);
-	const manualFiles = serialised.files.filter((f) => f.mode === "manual");
-	const stubbedFiles = serialised.files.filter((f) => f.mode === "stubbed");
-	const written = [];
-	if (regularFiles.length > 0 || serialised.files.length === 0) {
-		const outFile = path.join(dir, `${meta.sdkLine}.${meta.platform}.json`);
-		await writeFile(outFile, `${JSON.stringify({
-			...serialised,
-			files: regularFiles
-		}, null, 2)}\n`, "utf8");
-		written.push(outFile);
-	}
-	if (manualFiles.length > 0) {
-		const manualOutFile = path.join(dir, `${meta.sdkLine}.${meta.platform}.manual.json`);
-		await writeFile(manualOutFile, `${JSON.stringify({
-			...serialised,
-			files: manualFiles
-		}, null, 2)}\n`, "utf8");
-		written.push(manualOutFile);
-	}
-	if (stubbedFiles.length > 0) {
-		const stubbedOutFile = path.join(dir, `${meta.sdkLine}.${meta.platform}.stubbed.json`);
-		await writeFile(stubbedOutFile, `${JSON.stringify({
-			...serialised,
-			cell: {
-				...serialised.cell,
-				bridgeStub: true
-			},
-			files: stubbedFiles
-		}, null, 2)}\n`, "utf8");
-		written.push(stubbedOutFile);
-	}
-	return written;
-}
-/**
-* Writes harvested `__AIT_CAPTURE__` lines to per-category files under `dir`,
-* named `<category>.<sdkLine>.<platform>.json` — the SAME convention
-* sdk-example's env1 `flushCapture` uses on the filesystem, so env1 and env3
-* capture artifacts line up for diffing.
-*
-* Each line's `json` payload is an opaque JSON array of capture records. Lines
-* sharing a category are concatenated into one array, in harvest order.
-*
-* SECRET-HANDLING: only allowlist-prefixed capture lines reach here (the parser
-* dropped wss/scheme noise); the `json` payload is written verbatim but is a
-* capture record array, not a relay/secret.
-*
-* @param captures - Parsed capture lines (from `RelayRunReport.captures`).
-* @param dir      - Output directory (created recursively if missing).
-* @param cell     - Cell axes for the filename suffix.
-* @returns The absolute paths written (one per category), in category order.
-*/
-async function writeCaptureArtifacts(captures, dir, cell) {
-	if (captures.length === 0) return [];
-	const byCategory = /* @__PURE__ */ new Map();
-	for (const { category, json } of captures) {
-		let merged = byCategory.get(category);
-		if (!merged) {
-			merged = [];
-			byCategory.set(category, merged);
-		}
-		const parsed = JSON.parse(json);
-		if (Array.isArray(parsed)) merged.push(...parsed);
-		else merged.push(parsed);
-	}
-	await mkdir(dir, { recursive: true });
-	const written = [];
-	for (const [category, records] of byCategory) {
-		const outFile = path.join(dir, `${category}.${cell.sdkLine}.${cell.platform}.json`);
-		await writeFile(outFile, `${JSON.stringify(records, null, 2)}\n`, "utf8");
-		written.push(outFile);
-	}
-	return written;
-}
-//#endregion
-//#region src/test-runner/teardown.ts
-/**
-* Runs `steps` in strict order, each bounded by `perStepTimeoutMs` so a
-* single hung `close()` cannot block the rest — a later step (e.g. "close
-* the QR HTTP server") still runs even if an earlier one (e.g. "flip the
-* on-phone badge over CDP") times out.
-*
-* Order is load-bearing: `relay-factory.ts`'s existing `close()` already
-* encodes "badge over still-open channel, THEN close that channel" — this
-* function does not reorder or parallelize, it just bounds+reports whatever
-* sequence the caller provides.
-*/
-async function runTeardownSteps(steps, options = {}) {
-	const { perStepTimeoutMs = 5e3, setTimeoutFn = setTimeout, clearTimeoutFn = clearTimeout } = options;
-	const results = [];
-	for (const step of steps) results.push(await runOneStep(step, perStepTimeoutMs, setTimeoutFn, clearTimeoutFn));
-	return results;
-}
-async function runOneStep(step, perStepTimeoutMs, setTimeoutFn, clearTimeoutFn) {
-	let timeoutHandle;
-	const timeoutPromise = new Promise((resolve) => {
-		timeoutHandle = setTimeoutFn(() => resolve("timeout"), perStepTimeoutMs);
-	});
-	try {
-		const outcome = await Promise.race([Promise.resolve().then(() => step.close()).then(() => "ok"), timeoutPromise]);
-		if (timeoutHandle !== void 0) clearTimeoutFn(timeoutHandle);
-		return {
-			name: step.name,
-			status: outcome
-		};
-	} catch (e) {
-		if (timeoutHandle !== void 0) clearTimeoutFn(timeoutHandle);
-		return {
-			name: step.name,
-			status: "error",
-			error: e instanceof Error ? e.message : String(e)
-		};
-	}
-}
-/**
-* Arms a grace-period timer that force-exits the process if it has not
-* already exited on its own by the time the timer fires. The timer is
-* deliberately NOT `.unref()`'d — its entire purpose is to hold the event
-* loop open long enough to fire if nothing else does, so unref'ing it would
-* defeat the backstop. `disarm()` clears it — the CLI calls `disarm()`
-* immediately once `main()`'s own teardown (Step 6, cli.ts) has finished,
-* so on the happy path the timer never fires (Node drains the loop and
-* exits naturally at whatever `process.exitCode` was already set to).
-*
-* SECRET-HANDLING: this function never touches stdout/stderr content — the
-* caller (cli.ts) is responsible for flushing any final output before the
-* backstop's `exitFn` runs.
-*/
-function armExitBackstop(options) {
-	const { graceMs = 3e3, exitCode, setTimeoutFn = setTimeout, exitFn = (code) => process.exit(code) } = options;
-	let fired = false;
-	const handle = setTimeoutFn(() => {
-		fired = true;
-		exitFn(exitCode);
-	}, graceMs);
-	return {
-		disarm() {
-			clearTimeout(handle);
-		},
-		get fired() {
-			return fired;
-		}
-	};
-}
-//#endregion
-//#region src/test-runner/cli.ts
-/**
-* `devtools-test` CLI.
-*
-* Shares test-file discovery with the `run_tests` MCP tool (`discoverTestFiles`)
-* and exposes `runWithConnection` — the pure run core that bundles, injects, and
-* collects each file over a CDP connection. The CLI's `main()` performs a
-* standalone relay attach (boot relay → QR → phone scan → cell inject → run).
-*
-* NOTE: no shebang in this source file — the tsdown entry's `banner` option
-* injects `#!/usr/bin/env node` into the compiled output (same pattern as
-* `src/mcp/cli.ts`).
-*/
-const USAGE = `
-devtools-test — run mini-app tests on a real device WebView over the CDP relay
-
-USAGE
-  devtools-test <glob> [<glob> ...] [options]
-
-OPTIONS
-  --scheme-url <url>      intoss-private:// URL from \`ait deploy --scheme-only\`
-                          (required for standalone relay attach / env3). Unused
-                          and ignored when --attach-launcher is set.
-  --attach-launcher       Attach over the env-2 AITC Sandbox PWA launcher
-                          (real-device WebKit) instead of the env-3 intoss
-                          scheme deep-link. The relay/QR/dashboard/attach-wait
-                          are identical; only the QR is a launcher deep-link.
-                          Requires --app-url. The SDK still hits the mock in
-                          env 2, so this measures the mock + standard Web API
-                          layer's engine-attributable behavior (env1↔env2
-                          equivalence), NOT native-bridge fidelity (that is env3).
-  --app-url <url>         The consumer dev server's HTTP tunnel URL (e.g. the
-                          *.trycloudflare.com URL from \`pnpm dev:phone:cdp\`)
-                          that the launcher PWA frames. REQUIRED with
-                          --attach-launcher; ignored otherwise. SECRET: a tunnel
-                          host — never printed; it rides only inside the QR.
-  --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. 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|ios-pwa, default: AIT_CELL_PLATFORM
-                          env). Use ios-pwa for env-2 (--attach-launcher) runs
-                          so env1(mock@desktop) and env2(mock@WebKit) captures
-                          stay distinguishable. An unknown value is rejected.
-  --report-dir <dir>      Persist a runner-agnostic report + captures to <dir>
-                          (report: <sdkLine>.<platform>.json; captures:
-                          <dir>/.ait-capture/<category>.<sdkLine>.<platform>.json).
-                          Omitted = nothing saved. Enables console capture.
-  --dashboard-port <port> Base port for the QR dashboard HTTP server. On
-                          EADDRINUSE it increments (+1, up to 20 tries) before
-                          falling back to an ephemeral port. Omit to use
-                          AIT_DEBUG_HTTP_PORT env or the built-in default
-                          (8317) — pass 0 to force a random ephemeral port.
-  --no-qr-stdout          Suppress the QR/attach block on stdout (auto-on for
-                          non-interactive stdout / CI / AIT_NO_QR_STDOUT)
-  --headless              Disable browser auto-open (text QR only)
-  --project-root <dir>    Project root for .ait_relay secret lookup
-                          (default: current working directory)
-  --pace <ms>             Minimum delay in ms between test-to-test AND
-                          file-to-file bridge calls (default: 0, i.e. no
-                          added delay — today's behavior byte-for-byte).
-                          Falls back to the AIT_PACE env var when omitted
-                          (--pace takes precedence over the env var when both
-                          are given). Use on a 2.x cell scan when the native
-                          per-method bridge rate limit (APP_BRIDGE_THROTTLED,
-                          devtools#767) is rejecting rapid same-method calls —
-                          3.x cells are unaffected by that limiter and do not
-                          need this flag.
-  --pace-method <ms>      Minimum delay in ms BETWEEN calls to the SAME named
-                          SDK function — paces a same-method burst WITHIN a
-                          single test body (e.g. a clipboard happy-path loop
-                          calling setClipboardText/getClipboardText 8 times
-                          back to back), which --pace's test/file spacing
-                          cannot reach (devtools#769). Falls back to the
-                          AIT_PACE_METHOD env var when omitted (--pace-method
-                          takes precedence over the env var when both are
-                          given). Default: 250ms when --cell-sdk-line is 2.x
-                          (unset --cell-sdk-line also defaults to 2.x — see
-                          --cell-sdk-line), 0 (no added delay) otherwise. Pass
-                          --pace-method 0 to opt out even on a 2.x cell.
-  --manual-blocking       Run manual-tagged test files (*.manual.ait.test.ts)
-                          LAST, after all regular files, with a human present.
-                          Before each manual file, the QR dashboard is pushed
-                          a step-by-step Korean prompt naming the file + its
-                          progress (k/n), and the same line is printed to
-                          stdout. Manual files get a 5-minute per-file evaluate
-                          timeout (vs. --timeout for everything else) since a
-                          human is expected to tap through a native sheet
-                          (photo picker, permission dialog, fullscreen ad).
-                          Without this flag (default off), *.manual.ait.test.ts
-                          files are EXCLUDED from the glob expansion entirely —
-                          existing unattended runs are byte-for-byte unaffected.
-                          With --report-dir, a run that included manual files
-                          ALSO writes <sdkLine>.<platform>.manual.json
-                          alongside (never replacing) the standard report, and
-                          each manual file's report entry is stamped
-                          mode: 'manual' — never diff a manual run against an
-                          unattended baseline as if they were equivalent.
-  --stub-blocking         Run manual-tagged test files (*.manual.ait.test.ts)
-                          UNATTENDED (devtools#740, DT-2) by intercepting a
-                          fixed allowlist of blocking-UI SDK calls (ads
-                          show*, openPermissionDialog/requestPermission,
-                          saveBase64Data) in the page and answering them from
-                          fixtures captured by a real --manual-blocking run,
-                          instead of forwarding them to native UI. Implies
-                          --manual-blocking (manual files are included in the
-                          run); no human presence or QR-dashboard prompt is
-                          needed for them. HYBRID cell, not pure env3 — every
-                          other SDK call in the same run still hits the real
-                          native bridge. With --report-dir, files that ran
-                          under the stub are written to a SEPARATE
-                          <sdkLine>.<platform>.stubbed.json artifact (never
-                          merged into the standard or .manual.json report) and
-                          the report body is stamped cell.bridgeStub: true —
-                          never diff a stubbed run against a real device
-                          baseline (manual or unattended) as if equivalent.
-  --help, -h              Show this help message
-
-DESCRIPTION
-  Boots a Chii relay + cloudflared tunnel, renders a QR code, waits for a real
-  device to scan and attach, injects the cell globals (__AIT_CELL__), bundles
-  each matched test file with esbuild (SDK imports redirected to window.__sdk),
-  injects the bundle into the attached WebView via Runtime.evaluate, and prints
-  a summary.
-
-  With --report-dir, also harvests __AIT_CAPTURE__ console lines and writes a
-  runner-agnostic report + per-category capture files so 2.x↔3.0 runs can be
-  compared offline.
-
-  The test files run against the live relay connection started by this process;
-  no separate MCP daemon is required.
-
-EXAMPLE (env 3 — intoss-private scheme)
-  devtools-test 'src/**/*.ait.test.ts' \\
-    --scheme-url "intoss-private://..." \\
-    --cell-sdk-line 3.x \\
-    --cell-platform ios \\
-    --report-dir .ait-report \\
-    --timeout 60000
-
-EXAMPLE (env 2 — AITC Sandbox PWA launcher)
-  devtools-test 'src/**/*.ait.test.ts' \\
-    --attach-launcher \\
-    --app-url "https://<subdomain>.trycloudflare.com" \\
-    --cell-sdk-line 3.x \\
-    --cell-platform ios-pwa \\
-    --report-dir .ait-report
-
-`.trimStart();
-/**
-* Grace period (ms) for the exit backstop armed around Step 6 teardown
-* (devtools#755). See `teardown.ts`'s module doc for the root-cause writeup
-* — the two upstream `http.Server#close()` hangs are fixed at the source, so
-* this backstop is a last-mile safety net that should never fire in
-* practice. Exported so tests can assert the backstop is armed with the
-* expected value without hardcoding the literal twice.
-*/
-const EXIT_BACKSTOP_GRACE_MS = 3e3;
-/**
-* Parses --timeout and --attach-timeout raw string values into the two
-* distinct clocks.
-*
-* Returns an error string on invalid input, or the resolved timeouts on
-* success. The caller (main) writes the error to stderr and exits 1.
-*
-* Exported for unit testing — main() is the only other caller.
-*/
-function resolveTimeouts(rawTimeout, rawAttachTimeout) {
-	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";
-	return {
-		evaluateTimeoutMs,
-		attachTimeoutMs
-	};
-}
-/**
-* Parses the `--dashboard-port` raw string value into a validated port
-* number, or `undefined` when the flag was omitted (letting relay-factory /
-* qr-http-server resolve their own default — env then the built-in fixed
-* default, devtools#752).
-*
-* `0` is a valid, meaningful value (explicit opt-out to pure ephemeral) and
-* is passed through as-is — it must NOT be confused with "omitted".
-*
-* Returns an error string on invalid input (non-integer, negative, or
-* >65535), or the resolved port on success. Exported for unit testing.
-*/
-function resolveDashboardPort(raw) {
-	if (raw === void 0) return void 0;
-	const port = parseInt(raw, 10);
-	if (Number.isNaN(port) || port < 0 || port > 65535) return "--dashboard-port must be an integer between 0 and 65535";
-	return port;
-}
-/**
-* Rewrites a lone `--pace <value>` or `--pace-method <value>` pair from space
-* syntax to `=` syntax (`--pace=<value>` / `--pace-method=<value>`) when
-* `<value>` starts with `-` (devtools#768 review; extended to `--pace-method`
-* in devtools#769).
-*
-* Node's `util.parseArgs` treats a `type: 'string'` option's value as
-* "ambiguous" and throws its OWN parser error whenever that value starts with
-* a dash and was passed via the space form (`--pace -1`) — it never reaches
-* this module's `resolvePace`/`resolvePaceMethod`, so the friendly
-* `'--pace must be a non-negative integer'` message (and its unit-tested path)
-* was unreachable from the real CLI entry point for the single most natural
-* way a user would try a negative value, even though every other flag in
-* {@link USAGE} is documented in space syntax.
-*
-* Scoped narrowly to `--pace`/`--pace=...` and `--pace-method`/
-* `--pace-method=...` tokens only — every other flag is untouched, and
-* positionals/other options keep flowing through `parseArgs` unchanged. Only
-* rewrites the space form; `--pace=-1`/`--pace-method=-1` already parse fine
-* and are passed through untouched.
-*
-* Exported for unit testing.
-*/
-function normalizePaceArgv(argv) {
-	const out = [];
-	for (let i = 0; i < argv.length; i++) {
-		const arg = argv[i];
-		const next = argv[i + 1];
-		if ((arg === "--pace" || arg === "--pace-method") && next !== void 0 && next.startsWith("-") && next !== "--") {
-			out.push(`${arg}=${next}`);
-			i++;
-			continue;
-		}
-		out.push(arg);
-	}
-	return out;
-}
-/**
-* Parses `--pace` (falling back to the `AIT_PACE` env var when the flag is
-* omitted) into a validated millisecond delay (devtools#767).
-*
-* Opt-in, zero-diff-when-absent: BOTH omitted resolves to `0` — no pacing —
-* which is byte-for-byte today's behavior (`runtime.ts` treats `0`/absent
-* `__AIT_PACE_MS__` identically, and `relay-worker.ts`'s file-to-file gap is
-* skipped entirely when the resolved value is 0). `--pace` takes precedence
-* over `AIT_PACE` when both are present, mirroring `--cell-platform` /
-* `AIT_CELL_PLATFORM`'s existing flag-over-env precedent.
-*
-* Returns an error string on invalid input (non-integer or negative), or the
-* resolved delay (`>= 0`) on success. Exported for unit testing.
-*/
-function resolvePace(rawFlag, rawEnv) {
-	const raw = rawFlag ?? rawEnv;
-	if (raw === void 0) return 0;
-	const ms = parseInt(raw, 10);
-	if (Number.isNaN(ms) || ms < 0) return "--pace must be a non-negative integer";
-	return ms;
-}
-/**
-* Parses `--pace-method` (falling back to the `AIT_PACE_METHOD` env var when
-* the flag is omitted) into a validated millisecond per-method minimum
-* interval (devtools#769).
-*
-* Precedence, highest first: `--pace-method` flag > `AIT_PACE_METHOD` env >
-* sdkLine-aware default (`{@link DEFAULT_PACE_METHOD_MS_2X}` for a 2.x cell,
-* `0` otherwise) — an EXPLICIT flag or env value always wins, including
-* `--pace-method 0` to opt out on a 2.x cell. Mirrors `resolvePace`'s
-* flag-over-env precedent, with the sdkLine default spliced in only when
-* BOTH are absent.
-*
-* Returns an error string on invalid input (non-integer or negative), or the
-* resolved delay (`>= 0`) on success. Exported for unit testing.
-*
-* @param rawFlag        - The raw `--pace-method` string value, if passed.
-* @param rawEnv         - The raw `AIT_PACE_METHOD` env value, if set.
-* @param resolvedCellSdkLine - The effective `cell.sdkLine` value (already
-*   defaulted to '2.x' by the caller when `--cell-sdk-line` was omitted — see
-*   `main()`'s `cell` construction) — used ONLY to pick the sdkLine-aware
-*   default when both `rawFlag` and `rawEnv` are absent.
-*/
-function resolvePaceMethod(rawFlag, rawEnv, resolvedCellSdkLine) {
-	const raw = rawFlag ?? rawEnv;
-	if (raw === void 0) return resolvedCellSdkLine === "2.x" ? 250 : 0;
-	const ms = parseInt(raw, 10);
-	if (Number.isNaN(ms) || ms < 0) return "--pace-method must be a non-negative integer";
-	return ms;
-}
-/**
-* The set of `__AIT_CELL__.platform` values the runner accepts (devtools#774).
-*
-* `mock`/`ios`/`android` mirror sdk-example `aitCapture`'s existing `Platform`
-* union; `ios-pwa` is the new env-2 axis value (issue #774) — env 1 is
-* mock@desktop-Chromium and env 2 is mock@real-device-WebKit, so the two share
-* `sdkLine`/`ios` but must be DISTINGUISHABLE in the capture cell to diff
-* engine-attributable differences. `ios-pwa` names "mock SDK, real-device iOS
-* WebKit via the launcher PWA" — it is NOT `ios` (which is env 3's native
-* bridge). The consuming `aitCapture` type extension is a separate sdk-example
-* PR (out of scope here); the runner only needs to inject + validate the label.
-*
-* Kept as a validated allowlist (rather than a free string) purely as a
-* typo guard: `platform` flows into report/capture FILENAMES
-* (`<sdkLine>.<platform>.json`), so a silent typo would fork the artifact set
-* and break offline diffing. This is the first validation on `--cell-platform`
-* — before #774 it was an unvalidated free string defaulting to `mock`.
-*/
-const ALLOWED_CELL_PLATFORMS = [
-	"mock",
-	"ios",
-	"android",
-	"ios-pwa"
-];
-/**
-* Validates a resolved `--cell-platform` value against {@link ALLOWED_CELL_PLATFORMS}.
-*
-* `undefined` (flag + `AIT_CELL_PLATFORM` env both absent) passes through as
-* `{ ok: true, value: undefined }` — the caller applies its own `'mock'`
-* default, so an omitted platform is never an error. A present-but-unknown
-* value returns `{ ok: false, error }` naming the allowed set.
-*
-* Uses a tagged result (not the `string`-is-error convention of
-* `resolveDashboardPort`/`resolvePace`) because BOTH the success value and the
-* error message are strings here — a bare `string` return would be ambiguous.
-* Exported for unit testing.
-*/
-function resolveCellPlatform(raw) {
-	if (raw === void 0) return {
-		ok: true,
-		value: void 0
-	};
-	if (ALLOWED_CELL_PLATFORMS.includes(raw)) return {
-		ok: true,
-		value: raw
-	};
-	return {
-		ok: false,
-		error: `--cell-platform must be one of ${ALLOWED_CELL_PLATFORMS.join("|")} (got "${raw}")`
-	};
-}
-/**
-* Renders per-file result lines and the aggregate totals line to a string.
-*
-* Each file gets one line:
-*   - Error/timeout:  `FAIL <basename>: <error-class>`
-*   - Pass (0 tests): `OK   <basename>: 0 passed (empty file)`
-*   - Pass:           `OK   <basename>: N passed[, M failed][, K skipped]`
-*
-* The aggregate totals line always follows.
-*
-* SECRET-HANDLING: only `basename(file)` is used — no absolute paths, relay
-* URLs, wss URLs, scheme URLs, or TOTP codes appear in the output. The error
-* string comes from `result.error` which is already secret-free (relay-worker
-* produces only error-class messages like "rpc: evaluate timed out after
-* 30000ms").
-*
-* Exported so unit tests can assert the per-file lines without spawning a
-* subprocess or going through the full relay attach flow.
-*/
-function renderSummary(report) {
-	const lines = [];
-	for (const { file, result } of report.files) {
-		const name = basename(file);
-		if ("error" in result) lines.push(`FAIL ${name}: ${result.error}`);
-		else {
-			const parts = [`${result.passed} passed`];
-			if (result.failed > 0) parts.push(`${result.failed} failed`);
-			if (result.skipped > 0) parts.push(`${result.skipped} skipped`);
-			const suffix = result.passed + result.failed + result.skipped === 0 ? " (empty file)" : "";
-			lines.push(`OK   ${name}: ${parts.join(", ")}${suffix}`);
-		}
-	}
-	const { totals, duration } = report;
-	lines.push(`\ndevtools-test: ${totals.passed} passed, ${totals.failed} failed, ${totals.skipped} skipped (${duration}ms)`);
-	return lines.join("\n");
-}
-/**
-* Runs `files` over `connection` and returns the aggregate report.
-* This pure function is the testable core of the CLI (and is what the
-* `run_tests` MCP tool calls against the daemon's attached connection); it is
-* separate from `main()` so tests can call it without spawning a subprocess.
-*/
-async function runWithConnection(connection, files, opts) {
-	const report = await runTestFilesOverRelay(connection, files, opts);
-	if (opts?.printSummary) process.stdout.write(`\n${renderSummary(report)}\n`);
-	return report;
-}
-/**
-* Decides whether to suppress the QR/attach block on stdout.
-*
-* Suppress when EITHER the user passed `--no-qr-stdout`, OR stdout is not a TTY
-* / `CI` is set / `AIT_NO_QR_STDOUT` is set (non-interactive — a captured stdout
-* must not leak the relay wss + TOTP `at=` code that the QR block encodes). The
-* suppression is whole-chunk: `attachUrl` AND `relayUrl` ride in the same block.
-*
-* Exported for unit testing.
-*/
-function shouldSuppressQr(noQrFlag) {
-	return noQrFlag || !process.stdout.isTTY || process.env.CI !== void 0 || process.env.AIT_NO_QR_STDOUT !== void 0;
-}
-/**
-* CLI entry point.
-*
-* Performs a standalone relay attach → run lifecycle, sharing the attach
-* assembly with the Vitest pool via `createRelayConnectionFactory` (single
-* source — no drift):
-*
-* 1. Parse args: globs, --timeout (per-file evaluate), --attach-timeout (QR
-*    scan wait), --cell-sdk-line, --cell-platform, --scheme-url (required for
-*    env3) OR --attach-launcher + --app-url (env2, devtools#774), --report-dir,
-*    --dashboard-port, --no-qr-stdout, --headless, --project-root.
-* 2. Discover test files; exit 1 if none.
-* 3. factory.open() — boot relay → render QR (suppressed on non-interactive
-*    stdout) → wait for phone (up to attachTimeoutMs) → inject cell →
-*    enableDomains. Returns the conn.
-* 4. runWithConnection(conn, files, { evaluateTimeoutMs, collectCaptures,
-*    printSummary }).
-* 5. With --report-dir: write the runner-agnostic report + capture files.
-* 6. factory.close(); process.exitCode = failed > 0 ? 1 : 0.
-*
-* The CLI is not a daemon — no lock, router, SSE, or tools_list is needed.
-* Attach timeout exits with code 1; test failures exit with code 1.
-*
-* SECRET-HANDLING: scheme_url / relay wssUrl / TOTP codes are never written to
-* stdout/stderr directly. The QR block (which encodes the TOTP `at=` code) is
-* printed only when stdout is interactive AND not suppressed.
-*/
-async function main(argv = process.argv.slice(2)) {
-	let parsed;
-	try {
-		parsed = parseArgs({
-			args: normalizePaceArgv(argv),
-			options: {
-				help: {
-					type: "boolean",
-					short: "h"
-				},
-				timeout: { type: "string" },
-				"attach-timeout": { type: "string" },
-				"scheme-url": { type: "string" },
-				"attach-launcher": { type: "boolean" },
-				"app-url": { type: "string" },
-				"cell-sdk-line": { type: "string" },
-				"cell-platform": { type: "string" },
-				"report-dir": { type: "string" },
-				"dashboard-port": { type: "string" },
-				"no-qr-stdout": { type: "boolean" },
-				headless: { type: "boolean" },
-				"project-root": { type: "string" },
-				pace: { type: "string" },
-				"pace-method": { type: "string" },
-				"manual-blocking": { type: "boolean" },
-				"stub-blocking": { type: "boolean" }
-			},
-			allowPositionals: true
-		});
-	} catch (e) {
-		process.stderr.write(`devtools-test: ${e instanceof Error ? e.message : String(e)}\n`);
-		process.exitCode = 1;
-		return;
-	}
-	if (parsed.values.help || argv.length === 0) {
-		process.stdout.write(USAGE);
-		return;
-	}
-	const vals = parsed.values;
-	const timeouts = resolveTimeouts(typeof vals.timeout === "string" ? vals.timeout : void 0, typeof vals["attach-timeout"] === "string" ? vals["attach-timeout"] : void 0);
-	if (typeof timeouts === "string") {
-		process.stderr.write(`devtools-test: ${timeouts}\n`);
-		process.exitCode = 1;
-		return;
-	}
-	const { evaluateTimeoutMs, attachTimeoutMs } = timeouts;
-	const attachLauncher = vals["attach-launcher"] === true;
-	const schemeUrl = typeof vals["scheme-url"] === "string" ? vals["scheme-url"] : "";
-	const appUrl = typeof vals["app-url"] === "string" ? vals["app-url"] : "";
-	if (attachLauncher) {
-		if (appUrl === "") {
-			process.stderr.write("devtools-test: --app-url is required with --attach-launcher (env 2).\n  Pass the consumer dev server's tunnel URL (e.g. the HTTP *.trycloudflare.com\n  URL printed by `pnpm dev:phone:cdp`). --scheme-url is not used in this mode.\n");
-			process.exitCode = 1;
-			return;
-		}
-	} else if (schemeUrl === "") {
-		process.stderr.write("devtools-test: --scheme-url is required for standalone relay attach.\n  Pass the intoss-private:// URL from `ait deploy --scheme-only`.\n  (For env 2 / AITC Sandbox PWA, use --attach-launcher --app-url <tunnel-url> instead.)\n");
-		process.exitCode = 1;
-		return;
-	}
-	const headless = vals.headless === true;
-	const projectRoot = typeof vals["project-root"] === "string" ? vals["project-root"] : process.cwd();
-	const reportDir = typeof vals["report-dir"] === "string" ? vals["report-dir"] : void 0;
-	const dashboardPort = resolveDashboardPort(typeof vals["dashboard-port"] === "string" ? vals["dashboard-port"] : void 0);
-	if (typeof dashboardPort === "string") {
-		process.stderr.write(`devtools-test: ${dashboardPort}\n`);
-		process.exitCode = 1;
-		return;
-	}
-	const paceMs = resolvePace(typeof vals.pace === "string" ? vals.pace : void 0, process.env.AIT_PACE);
-	if (typeof paceMs === "string") {
-		process.stderr.write(`devtools-test: ${paceMs}\n`);
-		process.exitCode = 1;
-		return;
-	}
-	const suppressQr = shouldSuppressQr(vals["no-qr-stdout"] === true);
-	const stubBlocking = vals["stub-blocking"] === true;
-	const manualBlocking = vals["manual-blocking"] === true || stubBlocking;
-	const cellSdkLine = typeof vals["cell-sdk-line"] === "string" ? vals["cell-sdk-line"] : void 0;
-	const cellPlatformResult = resolveCellPlatform(typeof vals["cell-platform"] === "string" ? vals["cell-platform"] : process.env.AIT_CELL_PLATFORM);
-	if (!cellPlatformResult.ok) {
-		process.stderr.write(`devtools-test: ${cellPlatformResult.error}\n`);
-		process.exitCode = 1;
-		return;
-	}
-	const cellPlatform = cellPlatformResult.value;
-	const hasCell = cellSdkLine !== void 0 || cellPlatform !== void 0;
-	const cell = {
-		sdkLine: cellSdkLine ?? "2.x",
-		platform: cellPlatform ?? "mock"
-	};
-	const paceMethodMs = resolvePaceMethod(typeof vals["pace-method"] === "string" ? vals["pace-method"] : void 0, process.env.AIT_PACE_METHOD, cell.sdkLine);
-	if (typeof paceMethodMs === "string") {
-		process.stderr.write(`devtools-test: ${paceMethodMs}\n`);
-		process.exitCode = 1;
-		return;
-	}
-	const globs = parsed.positionals;
-	if (globs.length === 0) {
-		process.stderr.write(`devtools-test: at least one glob pattern is required\n`);
-		process.stdout.write(USAGE);
-		process.exitCode = 1;
-		return;
-	}
-	const discovered = await discoverTestFiles(globs, process.cwd(), { includeManual: manualBlocking });
-	if (discovered.length === 0) {
-		process.stderr.write(`devtools-test: no test files matched ${globs.join(", ")}\n`);
-		process.exitCode = 1;
-		return;
-	}
-	const { regular, manual } = partitionManualTests(discovered);
-	const files = manualBlocking ? [...regular, ...manual] : regular;
-	const manualFileSet = new Set(manual);
-	process.stderr.write(manualBlocking && manual.length > 0 ? `devtools-test: found ${regular.length} regular + ${manual.length} manual (${MANUAL_TEST_SUFFIX}) test file(s)\n` : `devtools-test: found ${files.length} test file(s)\n`);
-	if (hasCell) process.stderr.write(`devtools-test: injecting __AIT_CELL__ = ${JSON.stringify(cell)}\n`);
-	if (stubBlocking) process.stderr.write("devtools-test: --stub-blocking enabled — blocking-UI calls in manual-tagged files will be answered from fixtures (devtools#740), not forwarded to native UI\n");
-	if (paceMs > 0) process.stderr.write(`devtools-test: --pace ${paceMs}ms enabled (devtools#767)\n`);
-	if (paceMethodMs > 0) process.stderr.write(`devtools-test: --pace-method ${paceMethodMs}ms enabled (devtools#769)\n`);
-	const factory = createRelayConnectionFactory({
-		schemeUrl,
-		...attachLauncher ? {
-			attachLauncher: true,
-			appUrl
-		} : {},
-		projectRoot,
-		...attachTimeoutMs !== void 0 ? { timeoutMs: attachTimeoutMs } : {},
-		...dashboardPort !== void 0 ? { dashboardPort } : {},
-		headless,
-		cell: hasCell ? cell : void 0,
-		stubBlocking,
-		paceMs,
-		paceMethodMs,
-		onQrContent: (chunks) => {
-			if (suppressQr) {
-				process.stdout.write("QR suppressed (non-interactive)\n");
-				return;
-			}
-			for (const chunk of chunks) process.stdout.write(`${chunk}\n`);
-		}
-	});
-	let connection;
-	try {
-		connection = await factory.open();
-	} catch (e) {
-		process.stderr.write(`devtools-test: ${e instanceof Error ? e.message : String(e)}\n`);
-		process.exitCode = 1;
-		return;
-	}
-	let exitCode = 0;
-	try {
-		factory.onSessionPhase?.("running");
-		const report = await runWithConnection(connection, files, {
-			timeoutMs: evaluateTimeoutMs,
-			printSummary: true,
-			collectCaptures: reportDir !== void 0,
-			paceMs,
-			preflightSdkLine: cell.sdkLine,
-			manualFiles: manualBlocking && manualFileSet.size > 0 ? manualFileSet : void 0,
-			stubBlockingFiles: stubBlocking && manualFileSet.size > 0 ? manualFileSet : void 0,
-			onManualFile: (file, index, total) => {
-				const name = basename(file);
-				process.stdout.write(`수동 단계: ${name} — 폰에서 네이티브 시트가 뜨면 안내에 따라 조작하세요 (${index}/${total})\n`);
-				factory.onManualPrompt?.({
-					file: name,
-					index,
-					total
-				});
-			}
-		});
-		if (manualBlocking && manualFileSet.size > 0) factory.onManualPrompt?.(null);
-		if (reportDir !== void 0) try {
-			const reportPaths = await writeReportArtifact(report, reportDir, {
-				sdkLine: cell.sdkLine,
-				platform: cell.platform,
-				projectRoot
-			});
-			for (const reportPath of reportPaths) process.stderr.write(`devtools-test: wrote report ${reportPath}\n`);
-			const capturePaths = await writeCaptureArtifacts(report.captures, `${reportDir}/.ait-capture`, cell);
-			if (capturePaths.length > 0) process.stderr.write(`devtools-test: wrote ${capturePaths.length} capture file(s)\n`);
-		} catch (e) {
-			process.stderr.write(`devtools-test: failed to write report artifacts: ${e instanceof Error ? e.message : String(e)}\n`);
-		}
-		exitCode = report.totals.failed > 0 ? 1 : 0;
-	} finally {
-		factory.onSessionPhase?.("complete");
-		const backstop = armExitBackstop({
-			graceMs: EXIT_BACKSTOP_GRACE_MS,
-			exitCode
-		});
-		await runTeardownSteps([{
-			name: "factory.close",
-			close: () => factory.close(connection)
-		}]);
-		backstop.disarm();
-		process.exitCode = exitCode;
-	}
-}
-//#endregion
-//#region src/test-runner/bin.ts
-/**
-* `devtools-test` bin entry point — export-free by design.
-*
-* This file is intentionally export-free so that Rolldown (tsdown) emits the
-* main() call directly into the output bundle rather than hoisting the module
-* body into a shared chunk and replacing this file with a re-export wrapper.
-*
-* Background (#711): cli.ts exports `main`, `runWithConnection`, and
-* `shouldSuppressQr` for use by tests and relay-factory. When cli.ts was also
-* the bin entry, Rolldown split the module body into a shared chunk
-* (`cli-<hash>.js`) and reduced the bin output to a 3-line re-export wrapper.
-* The self-invoke guard (`import.meta.url === process.argv[1]`) evaluated
-* inside the shared chunk where `import.meta.url` is the chunk path, not the
-* bin path — a structural permanent mismatch — so main() was never called and
-* every `devtools-test` / `pnpm test:env3` invocation exited 0 as a silent
-* no-op.
-*
-* NOTE: no shebang in this source file — the tsdown entry's `banner` option
-* injects `#!/usr/bin/env node` into the compiled output (same pattern as
-* other Node bin entries in tsdown.config.ts).
-*/
-main().catch((e) => {
-	process.stderr.write(`devtools-test: unexpected error: ${e instanceof Error ? e.message : String(e)}\n`);
-	process.exitCode = 1;
-});
-//#endregion
-export { RELAY_AUTH_REJECT_CLOSE_CODE as n, RELAY_AUTH_REJECT_REASON as r, ChiiCdpConnection as t };
-
-//# sourceMappingURL=bin.js.map