@ait-co/devtools 0.1.128 → 0.1.131

package/dist/mcp/cli.js

@@ -2024,7 +2024,7 @@ async function readMcpSdkVersion() {
 * some test environments that skip the build step).
 */
 function readDevtoolsVersion() {
-	return "0.1.128";
+	return "0.1.131";
 }
 /**
 * Derives the next recommended action from a completed diagnostics snapshot.
@@ -2864,32 +2864,50 @@ async function renderAndMaybeWait(deps, prep, waitForAttach, callTimeoutMs, conn
 	}, null, 2)}\n\n${qr}`);
 }
 /**
-* Builds a self-contained IIFE DOM expression that renders a dismissible
-* "Debugger Connected" badge on the bottom-left of the phone screen.
+* Builds a self-contained IIFE DOM expression that renders a LIVE
+* "Debugger Connected" / "Debugger Disconnected" badge on the bottom-left of
+* the phone screen (#730).
 *
 * **Pure function** — returns a JS expression string; does NOT inject it.
 * Injection is performed by {@link injectDebugIndicator} in `cell.ts`.
 *
 * The expression, when evaluated on the page, does the following:
-*   1. Early-returns if `#__ait_debug_indicator` already exists (idempotent —
-*      prevents duplicate badges on re-injection after page reload).
-*   2. Appends a fixed-position `<div id="__ait_debug_indicator">` at the
-*      bottom-left, accounting for safe-area insets.
-*   3. Attaches a `{ once: true }` `pointerdown` listener that removes the
-*      badge on first touch — one-tap dismiss.
+*   1. Idempotent controller — a single `window.__ait_indicator` controller
+*      object is created once (keyed on its presence, not on the DOM node).
+*      Re-injection (e.g. explicit disconnect notice from `close()`) UPDATES
+*      the existing badge's state/label in place — it never duplicates the
+*      `<div>` or stacks a second observer.
+*   2. Renders a fixed-position `<div id="__ait_debug_indicator">` at the
+*      bottom-left, accounting for safe-area insets. Background/text flip
+*      between the attached (red) and disconnected (grey) visuals.
+*   3. A `pointerdown` listener dismisses (hides) the badge on tap — dismiss
+*      is NON-terminal: a later state transition un-dismisses it, so a
+*      genuine disconnect after a dismissed tap is still visible.
+*   4. Observes relay-socket lifecycle WITHOUT opening any new connection:
+*      - Preferred path: if the in-app module (`src/in-app/attach.ts`) has
+*        already installed its relay-WS observer (`window.__ait_relay_ws_observed`),
+*        subscribe to the `ait:relay-ws-state` CustomEvent it broadcasts.
+*      - Fallback path: wrap `window.WebSocket` in a `Proxy` and match dials
+*        by PATHNAME SHAPE only (`/target/`) — never by host/wss value — so a
+*        bare CDP-injected badge (no in-app bundle) still reacts to the
+*        chii target socket's own open/close lifecycle.
 *
 * The expression intentionally contains NO relay URLs, wss addresses, TOTP
-* codes, or any other secrets. It is pure DOM UI text only.
+* codes, or any other secrets. It is pure DOM UI text + enum state only.
 *
 * SECRET-HANDLING: this expression contains no secrets, relay URLs, wss
-* addresses, or TOTP codes whatsoever — DOM label text only.
+* addresses, or TOTP codes whatsoever — DOM label text + a structural
+* pathname match (`/target/`) only.
 *
-* @param opts.label - Badge text (default: `'Debugger Connected'`).
+* @param opts.label - Attached-state badge text (default: `'Debugger Connected'`).
+* @param opts.disconnectedLabel - Disconnected-state badge text (default: `'Debugger Disconnected'`).
+* @param opts.state - Initial/forced state for THIS injection call (default: `'attached'`).
 * @returns A JS expression string suitable for `Runtime.evaluate`.
 */
 function buildIndicatorExpression(opts) {
 	const label = opts?.label ?? "Debugger Connected";
-	return `(() => {if (document.getElementById('__ait_debug_indicator')) return;const el = document.createElement('div');el.id = '__ait_debug_indicator';el.style.cssText = ['position:fixed','left:max(12px,calc(env(safe-area-inset-left,0px) + 8px))','bottom:max(12px,calc(env(safe-area-inset-bottom,0px) + 8px))','z-index:2147483647','background:#e5484d','color:#fff','font:bold 11px/1 system-ui,sans-serif','padding:5px 9px','border-radius:6px','pointer-events:auto','user-select:none',].join(';');el.textContent = ${JSON.stringify(label)};el.addEventListener('pointerdown', () => el.remove(), { once: true });document.body.appendChild(el);})()`;
+	const disconnectedLabel = opts?.disconnectedLabel ?? "Debugger Disconnected";
+	return `(() => {var W = window;function render(c) {if (c.dismissed) { c.el.style.display = 'none'; return; }c.el.style.display = 'block';var up = c.state !== 'disconnected';c.el.style.background = up ? '#e5484d' : '#8a8f98';c.el.textContent = up ? ${JSON.stringify(label)} : ${JSON.stringify(disconnectedLabel)};}function setState(c, next) { c.state = next; c.dismissed = false; render(c); }var c = W.__ait_indicator;if (!c) {var el = document.createElement('div');el.id = '__ait_debug_indicator';el.style.cssText = ['position:fixed','left:max(12px,calc(env(safe-area-inset-left,0px) + 8px))','bottom:max(12px,calc(env(safe-area-inset-bottom,0px) + 8px))','z-index:2147483647','color:#fff','font:bold 11px/1 system-ui,sans-serif','padding:5px 9px','border-radius:6px','pointer-events:auto','user-select:none',].join(';');document.body.appendChild(el);c = { el: el, state: 'attached', dismissed: false };el.addEventListener('pointerdown', function () { c.dismissed = true; render(c); }, { passive: true });W.__ait_indicator = c;if (W.__ait_relay_ws_observed) {W.addEventListener('ait:relay-ws-state', function (e) {setState(c, e.detail && e.detail.state === 'open' ? 'attached' : 'disconnected');});} else {try {var Native = W.WebSocket;W.WebSocket = new Proxy(Native, {construct: function (t, a) {var ws = Reflect.construct(t, a);try {var u = new URL(String(a[0]), location.href);if (/\\/target\\//.test(u.pathname)) {ws.addEventListener('open', function () { setState(c, 'attached'); });ws.addEventListener('close', function () { setState(c, 'disconnected'); });ws.addEventListener('error', function () { setState(c, 'disconnected'); });}} catch (_) {}return ws;},});} catch (_) {}}}setState(c, ${JSON.stringify(opts?.state ?? "attached")});})()`;
 }
 //#endregion
 //#region src/test-runner/cell.ts
@@ -2935,12 +2953,16 @@ async function injectGlobals(conn, globals) {
 	}
 }
 /**
-* Injects the "Debugger Connected" on-phone indicator via `Runtime.evaluate`.
+* Injects (or updates) the "Debugger Connected"/"Debugger Disconnected"
+* on-phone indicator via `Runtime.evaluate` (#730).
 *
 * Uses the same CDP mechanism as {@link injectGlobals} — a single
 * `Runtime.evaluate` round-trip with the expression built by
-* {@link buildIndicatorExpression}. The indicator is a dismissible red badge
-* rendered at the bottom-left of the page (position:fixed, safe-area-aware).
+* {@link buildIndicatorExpression}. The indicator is a LIVE badge rendered at
+* the bottom-left of the page (position:fixed, safe-area-aware): the badge's
+* controller is idempotent, so calling this again (e.g. right before
+* `close()` with `{ state: 'disconnected' }`) UPDATES the existing badge in
+* place instead of injecting a duplicate.
 *
 * **Isolation**: unlike {@link injectGlobals}, this function NEVER throws to
 * its caller. Injection failure (e.g. page detached during inject, CSS not
@@ -2950,12 +2972,12 @@ async function injectGlobals(conn, globals) {
 * `src/in-app/attach.ts`.
 *
 * Call this ONLY on the manual debug paths (start_attach MCP, devtools-test
-* CLI). Do NOT call on the `run_tests` auto-attach path — the red badge
+* CLI). Do NOT call on the `run_tests` auto-attach path — the badge
 * would contaminate screenshots, measure_safe_area probes, and DOM snapshots
 * taken during automated measurement runs.
 *
 * SECRET-HANDLING: the injected expression contains no secrets, relay URLs,
-* wss addresses, or TOTP codes — it is pure DOM UI text built by
+* wss addresses, or TOTP codes — it is pure DOM UI text + enum state built by
 * {@link buildIndicatorExpression}.
 *
 * @param conn - The live CDP connection (relay-attached page).
@@ -3003,880 +3025,125 @@ async function discoverTestFiles(patterns, cwd) {
 	return [...out].sort();
 }
 //#endregion
-//#region src/test-runner/bundle.ts
+//#region src/shared/relay-auth-close.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.
+* Shared constants for the relay's named TOTP-auth rejection (issue #478).
 *
-* esbuild processes the re-generated module, following each static import
-* through the normal dependency graph (including the SDK-redirect plugin).
+* 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.
 *
-* ## SDK redirect
+* 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).
 *
-* 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.
+* 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: the returned bundle code is caller-managed; never log it.
+* 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.
 */
-/** 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`.
+* 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 VITEST_GLOBAL_NAMES = [
-	"describe",
-	"it",
-	"test",
-	"expect",
-	"beforeAll",
-	"afterAll",
-	"beforeEach",
-	"afterEach",
-	"vi"
-];
+const RELAY_AUTH_REJECT_CLOSE_CODE = 4401;
 /**
-* 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.
+* 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 SDK_IMPORT_FILTER = new RegExp(`^${SDK_PACKAGE.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`);
+const RELAY_AUTH_REJECT_REASON = "totp-rejected";
+//#endregion
+//#region src/mcp/chii-connection.ts
 /**
-* esbuild plugin that intercepts SDK imports and redirects them to the
-* `window.__sdk` proxy that `src/in-app/auto.ts` installs at runtime.
+* Production `CdpConnection` backed by the local Chii relay.
 *
-* 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.
+* Topology (debug mode):
+*   phone target.js  --WS-->  Chii relay :9100  <--WS--  this connection
 *
-* If `window.__sdk` is absent (non-dog-food build), every access throws a
-* descriptive error rather than returning `undefined` silently.
-*/
-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: `
-var __proxy = (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));
-      }
-    });
-module.exports = __proxy;
-`,
-				loader: "js"
-			}));
-		}
-	};
-}
-/**
-* 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 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`.
 *
-* 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.
+* Node-only: imports `ws`. Never bundled into the browser/in-app entries.
 *
-* 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.
+* 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$1 = 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에 연결되어 있지 않습니다 (...)`).
 *
-* 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.
+* 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`.
 */
-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"
-				};
-			});
-		}
-	};
+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$3(value) {
+	return typeof value === "object" && value !== null;
+}
+function parseInbound$1(raw) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return null;
+	}
+	if (!isObject$3(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$3(parsed.error) && typeof parsed.error.message === "string") message.error = { message: parsed.error.message };
+	return message;
 }
+const PHASE_1_EVENTS$1 = [
+	"Runtime.consoleAPICalled",
+	"Network.requestWillBeSent",
+	"Network.responseReceived"
+];
 /**
-* 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.
+* Ring buffer size for `Runtime.exceptionThrown`.
 *
-* 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.
+* 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.
 *
-* 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.dirname(absPath)
-				};
-			});
-		}
-	};
-}
-/**
-* Returns the absolute filesystem path to the test-runner runtime module
-* (dist/test-runner/runtime.js — a fully self-contained page-side bundle).
-*
-* 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 `runtime.js` and the nested `test-runner/runtime.js`,
-* then ascends one directory at a time (bounded) repeating both probes. The
-* nested probe catches dist/test-runner/runtime.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/runtime.js (tsdown entry
-* `'test-runner/runtime'`; guarded by scripts/check-test-runner-dist.sh).
-*
-* 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.
-*/
-function getRuntimePath() {
-	const startDir = path.dirname(fileURLToPath(import.meta.url));
-	const RELATIVE_PROBES = [
-		["runtime.js"],
-		["test-runner", "runtime.js"],
-		["runtime.ts"],
-		["test-runner", "runtime.ts"]
-	];
-	let dir = startDir;
-	for (let i = 0; i < 12; i++) {
-		for (const segs of RELATIVE_PROBES) {
-			const candidate = path.join(dir, ...segs);
-			try {
-				accessSync(candidate);
-				return candidate;
-			} catch {}
-		}
-		const parent = path.dirname(dir);
-		if (parent === dir) break;
-		dir = parent;
-	}
-	return path.join(startDir, "runtime.js");
-}
-/**
-* 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.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.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;
-/**
-* 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.  The 30-second CDP command timeout covers even
-* long-running test suites; split into smaller files if you hit it.
-*
-* @param connection   - Active CDP connection (relay or local).
-* @param bundleCode   - IIFE bundle string from `bundleTestFile`.
-* @param timeoutMs    - Override the default 30 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
-	});
-	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
-/**
-* 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);
-	});
-	try {
-		for (const file of files) {
-			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 (page
-				*     engine threw); treated as a final (non-retryable) error.
-				*
-				* The Promise.race timeout in rpc.ts RETURNS `{ok:false, error: '…'}` (it
-				* does NOT throw/reject).  Only genuine CDP `exceptionDetails` cause a throw.
-				* This distinction is what makes the EVALUATE_TIMEOUT_MARKER gate below
-				* reachable — the timeout result surfaces as `rpcResult.ok=false` with the
-				* marker string, not as a caught exception.
-				*/
-				const attempt = async () => {
-					let rpcResult;
-					try {
-						rpcResult = await injectAndRunBundle(connection, code, opts?.timeoutMs);
-					} 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 {
-					process.stderr.write(`relay-worker: evaluate timed out for ${file} — retrying once\n`);
-					const retryResult = await attempt();
-					if (retryResult !== null) fileEntry = retryResult;
-					else fileEntry = {
-						file,
-						result: { error: `${EVALUATE_TIMEOUT_MARKER} ${opts?.timeoutMs ?? 3e4}ms (after retry)` }
-					};
-				}
-			} catch (e) {
-				fileEntry = {
-					file,
-					result: { error: e instanceof Error ? e.message : String(e) }
-				};
-			}
-			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
-	};
-}
-/**
-* 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(" ");
-}
-`
-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)
-  --timeout <ms>          Per-file evaluate timeout in ms (default: 30000).
-                          Controls how long a single test file is allowed to run
-                          before it is considered hung. Does NOT affect how long
-                          the CLI waits for a human to scan the QR code — use
-                          --attach-timeout for that.
-  --attach-timeout <ms>   How long to wait for a human to scan the QR code with
-                          their phone (default: 600000 — 10 minutes). Omit to
-                          use the relay factory's generous default. Decrease for
-                          CI environments where a scan should arrive quickly.
-  --cell-sdk-line <line>  SDK line to inject as __AIT_CELL__.sdkLine (2.x|3.x)
-  --cell-platform <plat>  Platform to inject as __AIT_CELL__.platform
-                          (mock|ios|android, default: AIT_CELL_PLATFORM env)
-  --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.
-  --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)
-  --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
-  devtools-test 'src/**/*.ait.test.ts' \\
-    --scheme-url "intoss-private://..." \\
-    --cell-sdk-line 3.x \\
-    --cell-platform ios \\
-    --report-dir .ait-report \\
-    --timeout 60000
-
-`.trimStart();
-/**
-* 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;
-}
-//#endregion
-//#region src/mcp/ait-chii-source.ts
-function isObject$3(value) {
-	return typeof value === "object" && value !== null;
-}
-/** Narrows an `AIT.getSdkCallHistory` response, tolerating a missing array. */
-function asSdkCallHistory(raw) {
-	if (isObject$3(raw) && Array.isArray(raw.calls)) return { calls: raw.calls };
-	return { calls: [] };
-}
-/** Narrows an `AIT.getMockState` response to an opaque record. */
-function asMockState(raw) {
-	return isObject$3(raw) ? raw : {};
-}
-/** Narrows an `AIT.getOperationalEnvironment` response. */
-function asOperationalEnvironment(raw) {
-	return {
-		environment: isObject$3(raw) && typeof raw.environment === "string" ? raw.environment : "unknown",
-		sdkVersion: isObject$3(raw) && typeof raw.sdkVersion === "string" ? raw.sdkVersion : null
-	};
-}
-var ChiiAitSource = class {
-	constructor(sender) {
-		this.sender = sender;
-	}
-	async get(method) {
-		const raw = await this.sender.sendCommand(method);
-		switch (method) {
-			case "AIT.getSdkCallHistory": return asSdkCallHistory(raw);
-			case "AIT.getMockState": return asMockState(raw);
-			case "AIT.getOperationalEnvironment": return asOperationalEnvironment(raw);
-			default: throw new Error(`Unknown AIT method: ${String(method)}`);
-		}
-	}
-};
-//#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$1 = 500;
-function isObject$2(value) {
-	return typeof value === "object" && value !== null;
-}
-function parseInbound$1(raw) {
-	let parsed;
-	try {
-		parsed = JSON.parse(raw);
-	} catch {
-		return null;
-	}
-	if (!isObject$2(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$2(parsed.error) && typeof parsed.error.message === "string") message.error = { message: parsed.error.message };
-	return message;
-}
-const PHASE_1_EVENTS$1 = [
-	"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".
+* **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. */
@@ -3942,10 +3209,10 @@ var ChiiCdpConnection = class {
 		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$2(body) && Array.isArray(body.targets) ? body.targets : [];
+		const list = isObject$3(body) && Array.isArray(body.targets) ? body.targets : [];
 		let newestTargetId = null;
 		for (const item of list) {
-			if (!isObject$2(item) || typeof item.id !== "string") continue;
+			if (!isObject$3(item) || typeof item.id !== "string") continue;
 			newestTargetId = item.id;
 		}
 		if (newestTargetId !== null && this.activeTargetId !== null && newestTargetId !== this.activeTargetId) {
@@ -3955,7 +3222,7 @@ var ChiiCdpConnection = class {
 		}
 		this.targets.clear();
 		for (const item of list) {
-			if (!isObject$2(item) || typeof item.id !== "string") continue;
+			if (!isObject$3(item) || typeof item.id !== "string") continue;
 			if (item.id !== newestTargetId) continue;
 			this.targets.set(item.id, {
 				id: item.id,
@@ -3990,7 +3257,11 @@ var ChiiCdpConnection = class {
 	* 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).
+	* @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) {
@@ -4002,7 +3273,7 @@ var ChiiCdpConnection = class {
 			const settle = (targets) => {
 				if (settled) return;
 				settled = true;
-				clearTimeout(timeoutHandle);
+				if (timeoutHandle !== null) clearTimeout(timeoutHandle);
 				if (pollHandle !== null) {
 					clearInterval(pollHandle);
 					pollHandle = null;
@@ -4013,7 +3284,7 @@ var ChiiCdpConnection = class {
 			const onAttach = (targets) => {
 				if (filterFn(targets)) settle(targets);
 			};
-			const timeoutHandle = setTimeout(() => {
+			const timeoutHandle = Number.isFinite(timeoutMs) ? setTimeout(() => {
 				if (settled) return;
 				settled = true;
 				if (pollHandle !== null) {
@@ -4022,7 +3293,7 @@ var ChiiCdpConnection = class {
 				}
 				this.emitter.off("target:attached", onAttach);
 				reject(/* @__PURE__ */ new Error(`waitForFirstTarget: 타임아웃 (${timeoutMs}ms) — 폰이 relay에 attach되지 않았습니다.`));
-			}, timeoutMs);
+			}, timeoutMs) : null;
 			this.emitter.on("target:attached", onAttach);
 			pollHandle = setInterval(() => {
 				this.refreshTargets().then((targets) => {
@@ -4073,252 +3344,1060 @@ var ChiiCdpConnection = class {
 			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);
+		const ws = new WebSocket(clientUrl);
+		this.ws = ws;
+		await new Promise((resolve, reject) => {
+			ws.once("open", () => resolve());
+			ws.once("error", (err) => reject(err));
+			ws.once("close", (code) => {
+				if (code === 4401) reject(/* @__PURE__ */ new Error("relay 인증(TOTP)이 거부됐습니다 (close 4401). 코드가 만료됐을 수 있습니다 — 재연결 시 새 코드가 발급됩니다."));
+			});
+		});
+		this.lastCrashDetectedAt = null;
+		this.targetLastSeenAt.clear();
+		this.connectionState = "connected";
+		ws.on("message", (data) => this.handleMessage(data.toString()));
+		ws.on("close", (code) => this.handleDisconnect(code === 4401 ? "relay 인증(TOTP)이 거부돼 연결이 종료됐습니다 (close 4401)" : "relay WebSocket 연결이 끊겼습니다"));
+		ws.on("error", (err) => this.handleDisconnect(`relay WebSocket 오류: ${err.message}`));
+		this.sendFireAndForget("Runtime.enable");
+		this.sendFireAndForget("Network.enable");
+		this.sendFireAndForget("DOM.enable");
+		this.sendFireAndForget("Page.enable");
+		this.sendFireAndForget("Inspector.enable");
+		this.sendFireAndForget("Target.setDiscoverTargets", { discover: true });
+		this.startHeartbeat(target.id);
+	}
+	/** Fire-and-forget CDP message (used for `*.enable`, no result awaited). */
+	sendFireAndForget(method, params = {}) {
+		if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+		const id = this.nextCommandId++;
+		this.ws.send(JSON.stringify({
+			id,
+			method,
+			params
+		}));
+	}
+	/**
+	* Issue a CDP command and resolve with its result (Phase 2). Rejects on a CDP
+	* error frame or when no websocket is open (no page attached yet).
+	*/
+	send(method, params) {
+		return this.sendCommand(method, params ?? {});
+	}
+	/**
+	* Issue an arbitrary request→response command over the relay and resolve with
+	* its raw result. Both the typed CDP {@link send} and the AIT domain (Phase 3
+	* `AIT.*` methods, forwarded over the same Chii channel) build on this.
+	*
+	* Rejects immediately if the connection is disconnected (fail-fast — no
+	* auto-reconnect). Caller should re-run `list_pages` or `enableDomains` to
+	* reattach.
+	*
+	* Times out after `commandTimeoutMs` (default 30s, env
+	* `AIT_CDP_COMMAND_TIMEOUT_MS`). On timeout the pending entry is cleaned up
+	* and the promise rejects with a descriptive Korean error.
+	*/
+	sendCommand(method, params = {}) {
+		if (this.connectionState === "disconnected") return Promise.reject(/* @__PURE__ */ new Error(`relay에 연결되어 있지 않습니다 (${method}). list_pages로 attach 상태를 확인하고 enableDomains()로 재연결하세요.`));
+		if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return Promise.reject(/* @__PURE__ */ new Error("No mini-app page attached to the Chii relay yet. Call enableDomains() first."));
+		const id = this.nextCommandId++;
+		const ws = this.ws;
+		const timeoutMs = this.commandTimeoutMs;
+		return new Promise((resolve, reject) => {
+			const handle = setTimeout(() => {
+				this.pending.delete(id);
+				reject(/* @__PURE__ */ new Error(`CDP 명령이 타임아웃됐습니다 (${method}, ${timeoutMs}ms). 폰 측 토스 앱이 백그라운드로 내려갔거나 미니앱이 unload됐을 수 있습니다. list_pages로 attach 상태를 확인하세요.`));
+			}, timeoutMs);
+			this.pending.set(id, {
+				resolve: (v) => {
+					clearTimeout(handle);
+					resolve(v);
+				},
+				reject: (e) => {
+					clearTimeout(handle);
+					reject(e);
+				}
+			});
+			ws.send(JSON.stringify({
+				id,
+				method,
+				params
+			}));
+		});
+	}
+	/**
+	* Called on WebSocket `close` or `error` after a successful connection.
+	* Rejects all pending commands and marks the connection as disconnected so
+	* subsequent `sendCommand` calls fail fast (no auto-reconnect).
+	*/
+	handleDisconnect(reason) {
+		if (this.connectionState === "disconnected") return;
+		this.connectionState = "disconnected";
+		this.ws = null;
+		this.stopHeartbeat();
+		const err = /* @__PURE__ */ new Error(`${reason}. list_pages로 attach 상태를 확인하고 enableDomains()로 재연결하세요.`);
+		for (const waiter of this.pending.values()) waiter.reject(err);
+		this.pending.clear();
+	}
+	/**
+	* Evict a previously active target under the single-attach model.
+	* Rejects pending commands with a 'replaced-by-new-attach' reason and emits
+	* a 'replaced' lifecycle event. Does NOT clear all targets — only the specific
+	* targetId. The caller is responsible for rebuilding the targets map afterwards.
+	*
+	* The error message uses 'replaced-by-new-attach' so test assertions can match it.
+	*/
+	evictTarget(targetId) {
+		const detectedAt = (/* @__PURE__ */ new Date()).toISOString();
+		this.targets.delete(targetId);
+		this.targetLastSeenAt.delete(targetId);
+		const err = /* @__PURE__ */ new Error(`[ait-debug] replaced-by-new-attach — 이전 page 세션이 새 attach로 교체됐습니다 (targetId=${targetId}). list_pages로 현재 attach 상태를 확인하세요.`);
+		for (const waiter of this.pending.values()) waiter.reject(err);
+		this.pending.clear();
+		const event = {
+			kind: "replaced",
+			targetId,
+			detectedAt
+		};
+		for (const listener of this.lifecycleListeners) try {
+			listener(event);
+		} catch {}
+	}
+	/**
+	* Handle a page-level crash or target destruction event.
+	* Removes the target from the in-memory map, rejects all pending commands,
+	* and emits a lifecycle event.
+	*
+	* @param kind - Event kind: 'crashed' | 'destroyed' | 'detached'
+	* @param targetId - The target ID from the event params (may be null for
+	*   Inspector.targetCrashed which has no targetId in the params).
+	*/
+	handleTargetGone(kind, targetId) {
+		const detectedAt = (/* @__PURE__ */ new Date()).toISOString();
+		this.lastCrashDetectedAt = Date.now();
+		if (targetId !== null) {
+			this.targets.delete(targetId);
+			this.targetLastSeenAt.delete(targetId);
+			if (this.activeTargetId === targetId) this.activeTargetId = null;
+		} else {
+			this.targets.clear();
+			this.targetLastSeenAt.clear();
+			this.activeTargetId = null;
+		}
+		const err = /* @__PURE__ */ new Error(`[ait-debug] ${kind === "crashed" ? "page crash (Inspector.targetCrashed)" : kind === "destroyed" ? "target 종료 (Target.targetDestroyed)" : "target detach (Target.detachedFromTarget)"} 감지됨 — relay에서 제거됐습니다. 새 attach가 필요합니다 (list_pages로 확인 → enableDomains()로 재연결).`);
+		for (const waiter of this.pending.values()) waiter.reject(err);
+		this.pending.clear();
+		const event = {
+			kind,
+			targetId,
+			detectedAt
+		};
+		for (const listener of this.lifecycleListeners) try {
+			listener(event);
+		} catch {}
+	}
+	/**
+	* Start the optional CDP heartbeat loop.
+	*
+	* When `AIT_CDP_HEARTBEAT_MS` is set to a positive integer, every interval
+	* we send `Runtime.evaluate({expression: '1'})` to each active target. If
+	* the command times out (2 s hard deadline) or errors, we treat the target
+	* as dead and call `handleTargetGone`.
+	*
+	* This is a zombie-detector fallback: cloudflared keeps-alive the tunnel ws
+	* even when the phone app has crashed, so the ws-level disconnect (#252) won't
+	* fire. The heartbeat catches this gap.
+	*
+	* Default: OFF. Only activates when `AIT_CDP_HEARTBEAT_MS` is set.
+	*/
+	startHeartbeat(initialTargetId) {
+		this.stopHeartbeat();
+		const envMs = process.env.AIT_CDP_HEARTBEAT_MS ? Number(process.env.AIT_CDP_HEARTBEAT_MS) : void 0;
+		if (envMs === void 0 || !Number.isFinite(envMs) || envMs <= 0) return;
+		const PING_TIMEOUT_MS = 2e3;
+		this.heartbeatHandle = setInterval(() => {
+			const targetIds = this.targets.size > 0 ? [...this.targets.keys()] : [initialTargetId];
+			for (const targetId of targetIds) {
+				const pingPromise = this.sendCommand("Runtime.evaluate", {
+					expression: "1",
+					returnByValue: true,
+					timeout: PING_TIMEOUT_MS
+				});
+				const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error("heartbeat timeout")), PING_TIMEOUT_MS + 500));
+				Promise.race([pingPromise, timeoutPromise]).catch(() => {
+					if (this.targets.has(targetId)) this.handleTargetGone("destroyed", targetId);
+				});
+			}
+		}, envMs);
+	}
+	stopHeartbeat() {
+		if (this.heartbeatHandle !== null) {
+			clearInterval(this.heartbeatHandle);
+			this.heartbeatHandle = null;
+		}
+	}
+	handleMessage(raw) {
+		const message = parseInbound$1(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$3(message.params) && typeof message.params.targetId === "string" ? message.params.targetId : null;
+			this.handleTargetGone("destroyed", targetId);
+			return;
+		}
+		if (message.method === "Target.detachedFromTarget") {
+			const targetId = isObject$3(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);
 	}
-	/** 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
-		}));
+	getBufferedEvents(event) {
+		return this.buffers.get(event) ?? [];
 	}
-	/**
-	* Issue a CDP command and resolve with its result (Phase 2). Rejects on a CDP
-	* error frame or when no websocket is open (no page attached yet).
-	*/
-	send(method, params) {
-		return this.sendCommand(method, params ?? {});
+	on(event, listener) {
+		this.emitter.on(event, listener);
+		return () => this.emitter.off(event, listener);
 	}
-	/**
-	* Issue an arbitrary request→response command over the relay and resolve with
-	* its raw result. Both the typed CDP {@link send} and the AIT domain (Phase 3
-	* `AIT.*` methods, forwarded over the same Chii channel) build on this.
-	*
-	* Rejects immediately if the connection is disconnected (fail-fast — no
-	* auto-reconnect). Caller should re-run `list_pages` or `enableDomains` to
-	* reattach.
-	*
-	* Times out after `commandTimeoutMs` (default 30s, env
-	* `AIT_CDP_COMMAND_TIMEOUT_MS`). On timeout the pending entry is cleaned up
-	* and the promise rejects with a descriptive Korean error.
-	*/
-	sendCommand(method, params = {}) {
-		if (this.connectionState === "disconnected") return Promise.reject(/* @__PURE__ */ new Error(`relay에 연결되어 있지 않습니다 (${method}). list_pages로 attach 상태를 확인하고 enableDomains()로 재연결하세요.`));
-		if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return Promise.reject(/* @__PURE__ */ new Error("No mini-app page attached to the Chii relay yet. Call enableDomains() first."));
-		const id = this.nextCommandId++;
+	/** Close the relay client websocket and reject any in-flight commands. */
+	close() {
 		const ws = this.ws;
-		const timeoutMs = this.commandTimeoutMs;
-		return new Promise((resolve, reject) => {
-			const handle = setTimeout(() => {
-				this.pending.delete(id);
-				reject(/* @__PURE__ */ new Error(`CDP 명령이 타임아웃됐습니다 (${method}, ${timeoutMs}ms). 폰 측 토스 앱이 백그라운드로 내려갔거나 미니앱이 unload됐을 수 있습니다. list_pages로 attach 상태를 확인하세요.`));
-			}, timeoutMs);
-			this.pending.set(id, {
-				resolve: (v) => {
-					clearTimeout(handle);
-					resolve(v);
-				},
-				reject: (e) => {
-					clearTimeout(handle);
-					reject(e);
-				}
+		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.
+*/
+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: `
+var __proxy = (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));
+      }
+    });
+module.exports = __proxy;
+`,
+				loader: "js"
+			}));
+		}
+	};
+}
+/**
+* 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"
+				};
 			});
-			ws.send(JSON.stringify({
-				id,
-				method,
-				params
+		}
+	};
+}
+/**
+* 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.dirname(absPath)
+				};
+			});
+		}
+	};
+}
+/**
+* Returns the absolute filesystem path to the test-runner runtime module
+* (dist/test-runner/runtime.js — a fully self-contained page-side bundle).
+*
+* 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 `runtime.js` and the nested `test-runner/runtime.js`,
+* then ascends one directory at a time (bounded) repeating both probes. The
+* nested probe catches dist/test-runner/runtime.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/runtime.js (tsdown entry
+* `'test-runner/runtime'`; guarded by scripts/check-test-runner-dist.sh).
+*
+* 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.
+*/
+function getRuntimePath() {
+	const startDir = path.dirname(fileURLToPath(import.meta.url));
+	const RELATIVE_PROBES = [
+		["runtime.js"],
+		["test-runner", "runtime.js"],
+		["runtime.ts"],
+		["test-runner", "runtime.ts"]
+	];
+	let dir = startDir;
+	for (let i = 0; i < 12; i++) {
+		for (const segs of RELATIVE_PROBES) {
+			const candidate = path.join(dir, ...segs);
+			try {
+				accessSync(candidate);
+				return candidate;
+			} catch {}
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return path.join(startDir, "runtime.js");
+}
+/**
+* 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.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.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
 		});
 	}
-	/**
-	* 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();
+	return out;
+}
+//#endregion
+//#region src/test-runner/rpc.ts
+/** Maximum milliseconds to wait for a single evaluate round-trip. */
+const DEFAULT_TIMEOUT_MS = 6e4;
+/**
+* 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");
 	}
-	/**
-	* 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 {}
+	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.  The 30-second CDP command timeout covers even
+* long-running test suites; split into smaller files if you hit it.
+*
+* @param connection   - Active CDP connection (relay or local).
+* @param bundleCode   - IIFE bundle string from `bundleTestFile`.
+* @param timeoutMs    - Override the default 30 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
+	});
+	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}`);
 	}
-	/**
-	* 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 {}
+	return parseRunTestsResult(cdpResult.result.value);
+}
+//#endregion
+//#region src/test-runner/relay-worker.ts
+/**
+* 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;
 	/**
-	* 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`.
+	* 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).
 	*
-	* 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.
+	* `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).
 	*
-	* Default: OFF. Only activates when `AIT_CDP_HEARTBEAT_MS` is set.
+	* SECRET-HANDLING: fixed literals only — no relay wss URL, TOTP code, or
+	* tunnel host.
 	*/
-	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);
-				});
+	const attemptReconnect = async (context) => {
+		process.stderr.write(context === "next-file" ? "relay-worker: relay connection lost — attempting reconnect before next file\n" : "relay-worker: evaluate timed out — attempting reconnect before retry\n");
+		try {
+			await connection.enableDomains();
+			process.stderr.write("relay-worker: reconnect succeeded\n");
+		} catch (e) {
+			process.stderr.write(`relay-worker: reconnect failed (${e instanceof Error ? e.message : String(e)}) — continuing, remaining files may fail\n`);
+		}
+	};
+	try {
+		for (const file of files) {
+			if (pendingReconnectCheck) {
+				await attemptReconnect("next-file");
+				pendingReconnectCheck = false;
+			}
+			let fileEntry;
+			try {
+				const { code } = await bundleTestFile(file, opts?.bundleOptions);
+				/**
+				* 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, opts?.timeoutMs);
+					} 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)` }
+					};
+				}
+			} catch (e) {
+				fileEntry = {
+					file,
+					result: { error: e instanceof Error ? e.message : String(e) }
+				};
 			}
-		}, envMs);
-	}
-	stopHeartbeat() {
-		if (this.heartbeatHandle !== null) {
-			clearInterval(this.heartbeatHandle);
-			this.heartbeatHandle = null;
+			if ("error" in fileEntry.result && isRelayDisconnectMessage(fileEntry.result.error)) pendingReconnectCheck = true;
+			fileResults.push(fileEntry);
 		}
+	} finally {
+		unsubscribeConsole?.();
 	}
-	handleMessage(raw) {
-		const message = parseInbound$1(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;
+	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;
 		}
-		if (message.method === "Target.targetDestroyed") {
-			const targetId = isObject$2(message.params) && typeof message.params.targetId === "string" ? message.params.targetId : null;
-			this.handleTargetGone("destroyed", targetId);
-			return;
+		return acc;
+	}, {
+		passed: 0,
+		failed: 0,
+		skipped: 0,
+		total: 0
+	});
+	return {
+		startedAt,
+		duration: Date.now() - wallStart,
+		files: fileResults,
+		totals,
+		captures
+	};
+}
+/**
+* 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 (message.method === "Target.detachedFromTarget") {
-			const targetId = isObject$2(message.params) && typeof message.params.targetId === "string" ? message.params.targetId : null;
-			this.handleTargetGone("detached", targetId);
-			return;
+		if (arg.description !== void 0) return arg.description;
+		if (arg.className !== void 0) return arg.className;
+		return arg.subtype ?? arg.type;
+	}).join(" ");
+}
+`
+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)
+  --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, default: AIT_CELL_PLATFORM env)
+  --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.
+  --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)
+  --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
+  devtools-test 'src/**/*.ait.test.ts' \\
+    --scheme-url "intoss-private://..." \\
+    --cell-sdk-line 3.x \\
+    --cell-platform ios \\
+    --report-dir .ait-report \\
+    --timeout 60000
+
+`.trimStart();
+/**
+* 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}`);
 		}
-		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);
+	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;
+}
+//#endregion
+//#region src/mcp/ait-chii-source.ts
+function isObject$2(value) {
+	return typeof value === "object" && value !== null;
+}
+/** Narrows an `AIT.getSdkCallHistory` response, tolerating a missing array. */
+function asSdkCallHistory(raw) {
+	if (isObject$2(raw) && Array.isArray(raw.calls)) return { calls: raw.calls };
+	return { calls: [] };
+}
+/** Narrows an `AIT.getMockState` response to an opaque record. */
+function asMockState(raw) {
+	return isObject$2(raw) ? raw : {};
+}
+/** Narrows an `AIT.getOperationalEnvironment` response. */
+function asOperationalEnvironment(raw) {
+	return {
+		environment: isObject$2(raw) && typeof raw.environment === "string" ? raw.environment : "unknown",
+		sdkVersion: isObject$2(raw) && typeof raw.sdkVersion === "string" ? raw.sdkVersion : null
+	};
+}
+var ChiiAitSource = class {
+	constructor(sender) {
+		this.sender = sender;
 	}
-	/** 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();
+	async get(method) {
+		const raw = await this.sender.sendCommand(method);
+		switch (method) {
+			case "AIT.getSdkCallHistory": return asSdkCallHistory(raw);
+			case "AIT.getMockState": return asMockState(raw);
+			case "AIT.getOperationalEnvironment": return asOperationalEnvironment(raw);
+			default: throw new Error(`Unknown AIT method: ${String(method)}`);
+		}
 	}
 };
 //#endregion
@@ -5344,6 +5423,11 @@ const en = {
 	"dashboard.watchdog.title": "Server has shut down",
 	"dashboard.watchdog.body": "The MCP server has stopped. This session is no longer active. You may close this tab.",
 	"dashboard.watchdog.close": "Close tab",
+	"dashboard.conn.lost": "Connection lost — reconnecting…",
+	"dashboard.session.completeTitle": "Test run complete",
+	"dashboard.session.completeBody": "The runner exited cleanly. See your terminal for results.",
+	"dashboard.session.shutdownTitle": "Debug server stopped",
+	"dashboard.session.shutdownBody": "The MCP server has shut down; this session is no longer live. You can close this tab.",
 	"attach.title": "AIT Debug Session — QR Scan",
 	"attach.deployment": "deployment: {label}",
 	"attach.steps.section": "How to scan",
@@ -5582,6 +5666,11 @@ const tables = {
 		"dashboard.watchdog.title": "서버가 종료되었습니다",
 		"dashboard.watchdog.body": "MCP server가 종료되어 이 세션이 더 이상 유효하지 않습니다. 이 탭을 닫아도 됩니다.",
 		"dashboard.watchdog.close": "탭 닫기",
+		"dashboard.conn.lost": "연결 끊김 — 재연결 시도 중…",
+		"dashboard.session.completeTitle": "테스트 실행 완료",
+		"dashboard.session.completeBody": "러너가 정상 종료되었습니다. 결과는 터미널에서 확인하세요.",
+		"dashboard.session.shutdownTitle": "디버그 서버가 종료되었습니다",
+		"dashboard.session.shutdownBody": "MCP server가 종료되어 이 세션이 더 이상 유효하지 않습니다. 이 탭을 닫아도 됩니다.",
 		"attach.title": "AIT 디버그 세션 — QR 스캔",
 		"attach.deployment": "deployment: {label}",
 		"attach.steps.section": "스캔 절차",
@@ -6163,7 +6252,12 @@ function buildDashboardHtml(state, qrDataUrl, locale, path = "/", params = new U
 		watchdogTimeoutMs,
 		watchdogTitle: JSON.stringify(s("dashboard.watchdog.title")),
 		watchdogBody: JSON.stringify(s("dashboard.watchdog.body")),
-		watchdogCloseLabel: JSON.stringify(s("dashboard.watchdog.close"))
+		watchdogCloseLabel: JSON.stringify(s("dashboard.watchdog.close")),
+		connectionLost: JSON.stringify(s("dashboard.conn.lost")),
+		completeTitle: JSON.stringify(s("dashboard.session.completeTitle")),
+		completeBody: JSON.stringify(s("dashboard.session.completeBody")),
+		shutdownTitle: JSON.stringify(s("dashboard.session.shutdownTitle")),
+		shutdownBody: JSON.stringify(s("dashboard.session.shutdownBody"))
 	};
 	const langSwitcher = buildLangSwitcher(path, params, locale, s);
 	const filled = dashboardChromeByLocale[locale].replaceAll("__LANG_SWITCHER__", langSwitcher).replaceAll("__NOW__", escapeHtml(now)).replaceAll("__TUNNEL_CLASS__", tunnelClass).replaceAll("__TUNNEL_STATUS__", escapeHtml(tunnelStatus)).replaceAll("__ATTACH_SECTION__", attachSection).replaceAll("__INSPECTOR_SECTION__", inspectorSection).replaceAll("__PAGES_SECTION__", pagesSection);
@@ -6220,6 +6314,14 @@ function buildSseScript(strings) {
       var WATCHDOG_BODY = ${strings.watchdogBody};
       var WATCHDOG_CLOSE_LABEL = ${strings.watchdogCloseLabel};
 
+      // ── 실시간 상태 표면 상수 (#730) ───────────────────────────────────────
+      var CONN_LOST = ${strings.connectionLost};
+      var COMPLETE_TITLE = ${strings.completeTitle};
+      var COMPLETE_BODY = ${strings.completeBody};
+      var SHUTDOWN_TITLE = ${strings.shutdownTitle};
+      var SHUTDOWN_BODY = ${strings.shutdownBody};
+      var disconnectedShown = false;
+
       // ── 클립보드 복사 헬퍼 ────────────────────────────────────────────────
       function copyText(text) {
         if (navigator.clipboard && navigator.clipboard.writeText) {
@@ -6297,6 +6399,36 @@ function buildSseScript(strings) {
         }
       }
 
+      // ── Terminal 상태 배너 (#730) ─────────────────────────────────────────
+      // "완료"/"종료"는 watchdog(최대 210s 지연)을 기다리지 않고 close() 직전에
+      // 서버가 직접 push하는 마지막 SSE 프레임으로 즉시 렌더한다. watchdogFired를
+      // 함께 세워 뒤이은 onerror의 showConnLost가 이 배너를 덮어쓰지 않게 한다.
+      function showTerminalBanner(title, body) {
+        if (watchdogTimer) { clearInterval(watchdogTimer); watchdogTimer = null; }
+        watchdogFired = true; // 이후 watchdog/onerror 발화를 억제
+        if (document.body) {
+          document.body.innerHTML =
+            '<div style="display:flex;flex-direction:column;align-items:center;justify-content:center;' +
+            'height:100vh;font-family:sans-serif;text-align:center;padding:2rem;box-sizing:border-box;">' +
+            '<p style="font-size:1.4rem;font-weight:bold;margin-bottom:1rem;">' + title + '</p>' +
+            '<p style="color:#555;">' + body + '</p></div>';
+        }
+      }
+
+      // ── SSE onerror 즉시 신호 (#730) ──────────────────────────────────────
+      // EventSource는 "재시도 중"과 "서버 종료"를 구분하지 못하므로, onerror에서
+      // 즉시 구분되는 '연결 끊김' 상태를 tunnel-status 배지에 표시한다. 이미
+      // terminal 배너가 뜬 뒤(watchdogFired)라면 덮어쓰지 않는다.
+      function showConnLost() {
+        if (disconnectedShown || watchdogFired) return;
+        disconnectedShown = true;
+        var el = document.getElementById('tunnel-status');
+        if (el) { el.textContent = CONN_LOST; el.className = 'status status-down'; }
+      }
+      function clearConnLost() {
+        disconnectedShown = false;
+      }
+
       function fireWatchdog() {
         if (watchdogFired) return;
         watchdogFired = true;
@@ -6327,7 +6459,7 @@ function buildSseScript(strings) {
       src.onopen = function () {
         // 연결 복구 시 lastSeen 갱신 — 일시적 끊김이 watchdog을 발화시키지 않게.
         // watchdog이 이미 발화했으면 갱신하지 않는다(폴백 UI를 그대로 유지).
-        if (!watchdogFired) { lastSeen = Date.now(); }
+        if (!watchdogFired) { lastSeen = Date.now(); clearConnLost(); }
       };
       src.onmessage = function (e) {
         // SSE 메시지 수신 — lastSeen 갱신으로 watchdog 리셋.
@@ -6335,6 +6467,13 @@ function buildSseScript(strings) {
         if (!watchdogFired) { lastSeen = Date.now(); }
         try {
           var s = JSON.parse(e.data);
+          // 어떤 프레임이든 성공적으로 수신됐다는 건 서버가 살아있다는 뜻 —
+          // onerror가 세운 '연결 끊김' 표시를 해제한다 (#730).
+          clearConnLost();
+          // phase gate (#730) — 'complete'/'shutdown'은 terminal 상태이므로
+          // 나머지 필드 렌더보다 먼저 처리하고 즉시 반환한다.
+          if (s.phase === 'complete') { showTerminalBanner(COMPLETE_TITLE, COMPLETE_BODY); return; }
+          if (s.phase === 'shutdown') { showTerminalBanner(SHUTDOWN_TITLE, SHUTDOWN_BODY); return; }
           // 터널 상태 갱신
           var el = document.getElementById('tunnel-status');
           if (el) {
@@ -6413,7 +6552,11 @@ function buildSseScript(strings) {
         } catch (_) { /* 파싱 오류 무시 */ }
       };
       src.onerror = function () {
-        // 재연결은 EventSource가 자동 처리 (spec 기본 동작).
+        // EventSource는 "재시도 중"과 "서버 종료"를 구분하지 못하므로 즉시
+        // 구분되는 "연결 끊김"을 표시한다(#730). 네이티브 auto-reconnect는 그대로
+        // 진행되며 onopen/onmessage가 성공 즉시 이 상태를 해제한다. watchdog은
+        // 여전히 2차 fallback으로 남는다(최종 폴백 UI 전환).
+        showConnLost();
       };
     })();
   <\/script>`;
@@ -6462,7 +6605,12 @@ function buildAttachHtml(qrDataUrl, safeLabel, safeAttachUrl, locale, path = "/a
 		watchdogTimeoutMs,
 		watchdogTitle: JSON.stringify(s("dashboard.watchdog.title")),
 		watchdogBody: JSON.stringify(s("dashboard.watchdog.body")),
-		watchdogCloseLabel: JSON.stringify(s("dashboard.watchdog.close"))
+		watchdogCloseLabel: JSON.stringify(s("dashboard.watchdog.close")),
+		connectionLost: JSON.stringify(s("dashboard.conn.lost")),
+		completeTitle: JSON.stringify(s("dashboard.session.completeTitle")),
+		completeBody: JSON.stringify(s("dashboard.session.completeBody")),
+		shutdownTitle: JSON.stringify(s("dashboard.session.shutdownTitle")),
+		shutdownBody: JSON.stringify(s("dashboard.session.shutdownBody"))
 	});
 	return filled.replace("</body>", `${sseScript}\n</body>`);
 }
@@ -6489,7 +6637,8 @@ async function startQrHttpServer(getDashboardState, options) {
 			},
 			pages: state.pages,
 			attachUrl: state.attachUrl,
-			inspectorUrl: state.inspectorUrl ?? null
+			inspectorUrl: state.inspectorUrl ?? null,
+			phase: state.phase ?? "active"
 		});
 		res.write(`data: ${payload}\n\n`);
 	}
@@ -6798,7 +6947,7 @@ function createDebugServer(deps) {
 	};
 	const server = new Server({
 		name: "ait-debug",
-		version: "0.1.128"
+		version: "0.1.131"
 	}, { capabilities: { tools: { listChanged: true } } });
 	server.setRequestHandler(ListToolsRequestSchema, () => {
 		const conn = router.active;
@@ -7760,6 +7909,7 @@ async function runDebugServer(options = {}) {
 		return router.active;
 	});
 	let lastAttachParts = null;
+	let currentPhase = "active";
 	const getDashboardState = () => {
 		const targets = router.active.listTargets();
 		const inspectorUrl = qrServer?.inspectorStableUrl ?? null;
@@ -7774,7 +7924,8 @@ async function runDebugServer(options = {}) {
 			})),
 			attachUrl: lastAttachParts ? rebuildAttachUrl(lastAttachParts) : null,
 			inspectorUrl,
-			mode: deriveEnvironment(router.active.kind, router.activeRelayOrigin)
+			mode: deriveEnvironment(router.active.kind, router.activeRelayOrigin),
+			phase: currentPhase
 		};
 	};
 	const getDirectInspectorUrl = () => {
@@ -7838,6 +7989,8 @@ async function runDebugServer(options = {}) {
 	const shutdown = () => {
 		if (closed) return;
 		closed = true;
+		currentPhase = "shutdown";
+		qrServer?.notifyStateChange();
 		parentWatcher?.stop();
 		maxAgeWatchdog?.stop();
 		if (totpRefreshHandle) clearInterval(totpRefreshHandle);
@@ -7975,6 +8128,7 @@ async function runLocalDebugServer(options = {}) {
 		return router.active;
 	});
 	let lastAttachParts = null;
+	let currentPhase = "active";
 	const getDashboardState = () => {
 		const targets = router.active.listTargets();
 		const inspectorUrl = qrServer?.inspectorStableUrl ?? null;
@@ -7988,7 +8142,8 @@ async function runLocalDebugServer(options = {}) {
 				url: t.url
 			})),
 			attachUrl: lastAttachParts ? rebuildAttachUrl(lastAttachParts) : null,
-			inspectorUrl
+			inspectorUrl,
+			phase: currentPhase
 		};
 	};
 	const getDirectInspectorUrl = () => {
@@ -8052,6 +8207,8 @@ async function runLocalDebugServer(options = {}) {
 	const shutdown = () => {
 		if (closed) return;
 		closed = true;
+		currentPhase = "shutdown";
+		qrServer?.notifyStateChange();
 		parentWatcher?.stop();
 		maxAgeWatchdog?.stop();
 		if (totpRefreshHandle) clearInterval(totpRefreshHandle);
@@ -8172,6 +8329,7 @@ async function runMobileDebugServer(options = {}) {
 		return router.active;
 	});
 	let lastAttachParts = null;
+	let currentPhase = "active";
 	const getDashboardState = () => {
 		const targets = router.active.listTargets();
 		const inspectorUrl = qrServer?.inspectorStableUrl ?? null;
@@ -8185,7 +8343,8 @@ async function runMobileDebugServer(options = {}) {
 				url: t.url
 			})),
 			attachUrl: lastAttachParts ? rebuildAttachUrl(lastAttachParts) : null,
-			inspectorUrl
+			inspectorUrl,
+			phase: currentPhase
 		};
 	};
 	const getDirectInspectorUrl = () => {
@@ -8249,6 +8408,8 @@ async function runMobileDebugServer(options = {}) {
 	const shutdown = () => {
 		if (closed) return;
 		closed = true;
+		currentPhase = "shutdown";
+		qrServer?.notifyStateChange();
 		parentWatcher?.stop();
 		maxAgeWatchdog?.stop();
 		if (totpRefreshHandle) clearInterval(totpRefreshHandle);
@@ -8770,7 +8931,7 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.128"
+		version: "0.1.131"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {