@ait-co/devtools 0.1.116 → 0.1.118

package/dist/debug-server-krAOy6cl.js

@@ -0,0 +1,1891 @@
+import { n as buildRelayVerifyAuth, r as generateTotp, t as assertRelayAuthConfigured } from "./totp-DfekTBk3.js";
+import { createRelayConnectionFactory } from "./test-runner/relay-factory.js";
+import { a as startTunnelHealthProbe, i as startQuickTunnel, n as makeTunnelStatus, o as logError, r as printAttachBanner, s as logInfo, t as generateAttachToken } from "./attach-orchestrator-DEJfLm7V.js";
+import "./cell-Cv3e_qwn.js";
+import "./relay-secret-store-DNPJKHNs.js";
+import { createRequire } from "node:module";
+import { accessSync } from "node:fs";
+import * as path$1 from "node:path";
+import path, { isAbsolute, resolve } from "node:path";
+import "@modelcontextprotocol/sdk/server/index.js";
+import "@modelcontextprotocol/sdk/server/stdio.js";
+import "@modelcontextprotocol/sdk/types.js";
+import { parseArgs } from "node:util";
+import * as fs from "node:fs/promises";
+import { glob, mkdir, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { EventEmitter } from "node:events";
+import { WebSocket, WebSocketServer } from "ws";
+import { createServer } from "node:http";
+//#region src/test-runner/discover.ts
+/**
+* Test-file discovery shared by the `devtools-test` CLI and the `run_tests`
+* MCP tool, so both expand glob patterns with identical semantics.
+*
+* Uses Node's built-in `fs/promises` `glob` (Node 22+) — no extra dependency,
+* which keeps the MCP daemon install graph lean (a plain glob lib would land in
+* the `npx … devtools-mcp` path for no benefit).
+*
+* Pure Node IO only (`node:fs/promises` + `node:path`) — react-free, so it is
+* safe to import from the MCP daemon graph.
+*/
+/**
+* Expands `patterns` (globs or plain paths) into a sorted, de-duplicated list of
+* ABSOLUTE test file paths, resolved relative to `cwd`.
+*
+* A plain (non-glob) path passes through when it matches a real file; a glob
+* expands against `cwd`. Absolute matches are kept as-is; relative matches are
+* resolved against `cwd`. `bundleTestFile` requires an absolute path, so the
+* absolute output feeds it directly.
+*
+* @param patterns Glob patterns or file paths (e.g. `['src/**\/*.ait.test.ts']`).
+* @param cwd      Base directory for relative patterns/results.
+* @returns Sorted, de-duplicated absolute file paths. Empty when nothing matches.
+*/
+async function discoverTestFiles(patterns, cwd) {
+	const out = /* @__PURE__ */ new Set();
+	for await (const match of glob(patterns, { cwd })) out.add(isAbsolute(match) ? match : resolve(cwd, match));
+	return [...out].sort();
+}
+//#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"
+				};
+			});
+		}
+	};
+}
+/**
+* esbuild plugin that transforms the user test file into a module that exports
+* an async `__userFactory` function. The factory defers the user's top-level
+* test registration code (describe/it/test calls) so it only runs when
+* `runTestModule(__userFactory)` explicitly invokes it — AFTER the runtime has
+* installed describe/it/test/expect as globals.
+*
+* Algorithm:
+*   - Import declarations and re-export statements are kept at module top-level
+*     (the only valid ESM position for static `import`). A statement that spans
+*     multiple lines — e.g. a named import with one member per line:
+*       import {
+*         appLogin,
+*         getAnonymousKey,
+*       } from '@apps-in-toss/web-framework';
+*     is tracked as a single block: every line from the opening `import {` /
+*     `export {` through the closing `from '…'` (or side-effect `'…'`) line is
+*     kept together at top-level. This prevents the member lines and the
+*     closing `} from '…'` line from leaking into the factory body, which would
+*     leave an unterminated `import {` at module scope (the #678 env3 failure:
+*     esbuild threw `Expected "as" but found "{"` on multi-line SDK imports).
+*   - All other lines (describe/it/test calls, local declarations, etc.) are
+*     moved into the body of the exported async factory function.
+*
+* This preserves SDK import resolution (the sdk-redirect plugin processes
+* top-level imports normally) while deferring test registration to the factory.
+*/
+function userFactoryPlugin(absPath) {
+	const NAMESPACE = "user-test-factory";
+	return {
+		name: "user-test-factory",
+		setup(build) {
+			build.onResolve({ filter: /^user-test-factory$/ }, () => ({
+				path: absPath,
+				namespace: NAMESPACE
+			}));
+			build.onLoad({
+				filter: /.*/,
+				namespace: NAMESPACE
+			}, async (args) => {
+				const lines = (await fs.readFile(args.path, "utf8")).split("\n");
+				const topLevelLines = [];
+				const bodyLines = [];
+				const EXPORT_DECLARATION_RE = /^(export\s+)(default\s+|async\s+function\s+|function\s+|class\s+|const\s+|let\s+|var\s+)/;
+				const isImportStart = (trimmed) => trimmed.startsWith("import ") || trimmed.startsWith("import{") || trimmed.startsWith("import'") || trimmed.startsWith("import\"");
+				const endsStatement = (trimmed) => /['"]\s*;?\s*$/.test(trimmed.replace(/\/\/.*$/, "").trimEnd());
+				let inImportBlock = false;
+				for (const line of lines) {
+					const trimmed = line.trimStart();
+					const indent = line.slice(0, line.length - trimmed.length);
+					if (inImportBlock) {
+						topLevelLines.push(line);
+						if (endsStatement(trimmed)) inImportBlock = false;
+						continue;
+					}
+					if (isImportStart(trimmed)) {
+						topLevelLines.push(line);
+						if (!endsStatement(trimmed)) inImportBlock = true;
+					} else if (trimmed.startsWith("export ")) if (trimmed.match(EXPORT_DECLARATION_RE)) bodyLines.push(indent + trimmed.slice(7));
+					else {
+						topLevelLines.push(line);
+						if (/\bfrom\b/.test(trimmed) ? !endsStatement(trimmed) : trimmed.endsWith("{")) inImportBlock = true;
+					}
+					else bodyLines.push(line);
+				}
+				return {
+					contents: [
+						...topLevelLines,
+						"",
+						"// biome-ignore lint: generated factory wrapper",
+						"export default async function __userFactory(): Promise<void> {",
+						...bodyLines.map((l) => `  ${l}`),
+						"}"
+					].join("\n"),
+					loader: "ts",
+					resolveDir: path$1.dirname(absPath)
+				};
+			});
+		}
+	};
+}
+/**
+* Returns the absolute path to the test-runner runtime module.
+*
+* Searches candidates in priority order:
+*   1. Co-located `runtime.ts` / `runtime.js` — covers the source tree
+*      (tsx / ts-node) and the `dist/test-runner/` entry.
+*   2. `../test-runner/runtime.js` — covers the `dist/mcp/cli.js` entry,
+*      where `import.meta.url` resolves to `dist/mcp/` (a sibling directory
+*      of `dist/test-runner/`). Without this second candidate the MCP entry
+*      point would look for `dist/mcp/runtime.js`, which does not exist, and
+*      every `run_tests` call would fail with an esbuild "Could not resolve"
+*      error (#678).
+*
+* Returns the first candidate that exists on disk. Falls back to the
+* co-located `runtime.js` path so esbuild produces a clear "file not found"
+* error rather than a cryptic failure.
+*/
+function getRuntimePath() {
+	const dir = path$1.dirname(fileURLToPath(import.meta.url));
+	const candidates = [
+		path$1.join(dir, "runtime.ts"),
+		path$1.join(dir, "runtime.js"),
+		path$1.join(dir, "..", "test-runner", "runtime.js")
+	];
+	for (const candidate of candidates) try {
+		accessSync(candidate);
+		return candidate;
+	} catch {}
+	return path$1.join(dir, "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$1.dirname(absPath)
+		},
+		bundle: true,
+		format: "iife",
+		globalName,
+		platform: "browser",
+		target: "es2022",
+		write: false,
+		plugins: [
+			userFactoryPlugin(absPath),
+			vitestRedirectPlugin(),
+			sdkRedirectPlugin()
+		],
+		external: extraExternals,
+		treeShaking: true,
+		footer: { js: `globalThis[${JSON.stringify(globalName)}] = ${globalName};` }
+	});
+	const warnings = result.warnings.map((w) => `${path$1.relative(process.cwd(), w.location?.file ?? "")}:${w.location?.line ?? "?"}: ${w.text}`);
+	const outputFile = result.outputFiles?.[0];
+	if (!outputFile) throw new Error("bundleTestFile: esbuild produced no output — check entryPoints");
+	return {
+		code: outputFile.text,
+		warnings
+	};
+}
+//#endregion
+//#region src/test-runner/capture.ts
+/** The exact console-line prefix sdk-example's `flushCapture` emits. */
+const CAPTURE_PREFIX = "__AIT_CAPTURE__ ";
+/**
+* Parses raw console line texts into {@link AitCaptureLine}s.
+*
+* Filtering rules (each independently drops a line — never throws):
+*   - the line text must `startsWith(CAPTURE_PREFIX)` exactly (allowlist);
+*   - there must be a non-empty category token (up to the next space);
+*   - the remaining payload must be valid JSON (`JSON.parse` succeeds).
+*
+* Lines that fail any rule (wss/scheme noise, truncated, broken JSON) are
+* silently discarded — capture harvesting is best-effort and must never fail a
+* run or leak a malformed/secret-bearing line.
+*
+* @param raw - Console line objects (only `.text` is read).
+* @returns The captured lines, in input order.
+*/
+function parseCaptureLines(raw) {
+	const out = [];
+	for (const { text } of raw) {
+		if (!text.startsWith(CAPTURE_PREFIX)) continue;
+		const body = text.slice(16);
+		const spaceIdx = body.indexOf(" ");
+		if (spaceIdx === -1) continue;
+		const category = body.slice(0, spaceIdx);
+		const json = body.slice(spaceIdx + 1);
+		if (category === "" || json === "") continue;
+		try {
+			JSON.parse(json);
+		} catch {
+			continue;
+		}
+		out.push({
+			category,
+			json
+		});
+	}
+	return out;
+}
+//#endregion
+//#region src/test-runner/rpc.ts
+/** Maximum milliseconds to wait for a single evaluate round-trip. */
+const DEFAULT_TIMEOUT_MS = 3e4;
+/**
+* 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 timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error(`rpc: evaluate timed out after ${timeoutMs}ms`)), timeoutMs));
+	const evalPromise = connection.send("Runtime.evaluate", {
+		expression,
+		returnByValue: true,
+		awaitPromise: true
+	});
+	const cdpResult = await Promise.race([evalPromise, timeoutPromise]);
+	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
+/**
+* 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);
+				const rpcResult = await injectAndRunBundle(connection, code, opts?.timeoutMs);
+				if (rpcResult.ok) fileEntry = {
+					file,
+					result: rpcResult.report
+				};
+				else fileEntry = {
+					file,
+					result: { error: rpcResult.error }
+				};
+			} 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(" ");
+}
+//#endregion
+//#region src/test-runner/report.ts
+/**
+* Runner-agnostic report serialisation for env3 test runs (devtools#696).
+*
+* Both env3 execution paths — the Vitest custom pool (`pool.ts`) and the
+* standalone `devtools-test` CLI (`cli.ts`) — call the same core
+* `runTestFilesOverRelay` and so produce the same {@link RelayRunReport}. This
+* module is the single, runner-neutral place that turns that in-memory report
+* into a stable on-disk artifact so a 2.x run and a 3.0 run can be diffed
+* cell-by-cell after the fact.
+*
+* The serialised schema is deliberately MINIMAL and secret-free:
+*
+*   - file paths are stored RELATIVE to `projectRoot` (no absolute `/Users/...`
+*     leakage — see {@link RunnerAgnosticReport.files});
+*   - the cell metadata (sdkLine/platform) is baked INTO the body, not only the
+*     filename, so a moved artifact never loses its provenance;
+*   - NO relay wss / scheme / TOTP / relayUrl fields exist in the schema at all
+*     (enforced by the type + this comment) — error strings are the matcher
+*     message only, inherited from rpc.ts which already strips expression/value.
+*
+* react-free — depends only on the type-level `RelayRunReport` and `node:fs` /
+* `node:path`. Safe to bundle without pulling the chii/cloudflared graph.
+*/
+/**
+* Converts an absolute (or already-relative) file path to a projectRoot-relative
+* one. `path.relative` returns `''` when the paths are equal — guard that to the
+* basename so the field is never empty.
+*
+* SECRET-HANDLING: this is the single choke point that strips absolute project
+* paths from the artifact.
+*/
+function relativise(projectRoot, file) {
+	const rel = path.relative(projectRoot, file);
+	if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) return path.basename(file);
+	return rel;
+}
+/**
+* Serialises a {@link RelayRunReport} into the runner-agnostic, secret-free
+* on-disk shape. Pure — no IO; testable with a plain report + meta.
+*
+* @param report - The core relay run report.
+* @param meta   - Cell axes + projectRoot (projectRoot is consumed, not stored).
+*/
+function serializeRelayReport(report, meta) {
+	return {
+		cell: {
+			sdkLine: meta.sdkLine,
+			platform: meta.platform
+		},
+		startedAt: report.startedAt,
+		duration: report.duration,
+		totals: report.totals,
+		files: report.files.map((f) => {
+			const file = relativise(meta.projectRoot, f.file);
+			if ("error" in f.result) return {
+				file,
+				error: f.result.error
+			};
+			return {
+				file,
+				duration: f.result.duration,
+				passed: f.result.passed,
+				failed: f.result.failed,
+				skipped: f.result.skipped,
+				tests: f.result.tests
+			};
+		})
+	};
+}
+/**
+* Writes the serialised report to `<dir>/<sdkLine>.<platform>.json`, creating
+* `dir` if needed. Returns the absolute path written.
+*
+* The cell-suffixed filename keeps 2.x and 3.0 (and per-platform) runs as
+* distinct artifacts in the same directory; the same cell metadata is also baked
+* into the body so a renamed/moved file still carries its provenance.
+*
+* SECRET-HANDLING: the written body contains no relay/secret fields (the schema
+* has none). `dir`/`projectRoot` are local filesystem paths, never logged here.
+*
+* @param report - The core relay run report.
+* @param dir    - Output directory (created recursively if missing).
+* @param meta   - Cell axes + projectRoot.
+* @returns The absolute path of the written file.
+*/
+async function writeReportArtifact(report, dir, meta) {
+	const serialised = serializeRelayReport(report, meta);
+	await mkdir(dir, { recursive: true });
+	const outFile = path.join(dir, `${meta.sdkLine}.${meta.platform}.json`);
+	await writeFile(outFile, `${JSON.stringify(serialised, null, 2)}\n`, "utf8");
+	return outFile;
+}
+/**
+* Writes harvested `__AIT_CAPTURE__` lines to per-category files under `dir`,
+* named `<category>.<sdkLine>.<platform>.json` — the SAME convention
+* sdk-example's env1 `flushCapture` uses on the filesystem, so env1 and env3
+* capture artifacts line up for diffing.
+*
+* Each line's `json` payload is an opaque JSON array of capture records. Lines
+* sharing a category are concatenated into one array, in harvest order.
+*
+* SECRET-HANDLING: only allowlist-prefixed capture lines reach here (the parser
+* dropped wss/scheme noise); the `json` payload is written verbatim but is a
+* capture record array, not a relay/secret.
+*
+* @param captures - Parsed capture lines (from `RelayRunReport.captures`).
+* @param dir      - Output directory (created recursively if missing).
+* @param cell     - Cell axes for the filename suffix.
+* @returns The absolute paths written (one per category), in category order.
+*/
+async function writeCaptureArtifacts(captures, dir, cell) {
+	if (captures.length === 0) return [];
+	const byCategory = /* @__PURE__ */ new Map();
+	for (const { category, json } of captures) {
+		let merged = byCategory.get(category);
+		if (!merged) {
+			merged = [];
+			byCategory.set(category, merged);
+		}
+		const parsed = JSON.parse(json);
+		if (Array.isArray(parsed)) merged.push(...parsed);
+		else merged.push(parsed);
+	}
+	await mkdir(dir, { recursive: true });
+	const written = [];
+	for (const [category, records] of byCategory) {
+		const outFile = path.join(dir, `${category}.${cell.sdkLine}.${cell.platform}.json`);
+		await writeFile(outFile, `${JSON.stringify(records, null, 2)}\n`, "utf8");
+		written.push(outFile);
+	}
+	return written;
+}
+//#endregion
+//#region src/test-runner/cli.ts
+/**
+* `devtools-test` CLI.
+*
+* Shares test-file discovery with the `run_tests` MCP tool (`discoverTestFiles`)
+* and exposes `runWithConnection` — the pure run core that bundles, injects, and
+* collects each file over a CDP connection. The CLI's `main()` performs a
+* standalone relay attach (boot relay → QR → phone scan → cell inject → run).
+*
+* NOTE: no shebang in this source file — the tsdown entry's `banner` option
+* injects `#!/usr/bin/env node` into the compiled output (same pattern as
+* `src/mcp/cli.ts`).
+*/
+const USAGE = `
+devtools-test — run mini-app tests on a real device WebView over the CDP relay
+
+USAGE
+  devtools-test <glob> [<glob> ...] [options]
+
+OPTIONS
+  --scheme-url <url>      intoss-private:// URL from \`ait deploy --scheme-only\`
+                          (required for standalone relay attach / env3)
+  --timeout <ms>          Per-file evaluate timeout in ms (default: 30000)
+  --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();
+/**
+* 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) {
+		const { totals } = report;
+		process.stdout.write(`\ndevtools-test: ${totals.passed} passed, ${totals.failed} failed, ${totals.skipped} skipped (${report.duration}ms)\n`);
+	}
+	return report;
+}
+/**
+* Decides whether to suppress the QR/attach block on stdout.
+*
+* Suppress when EITHER the user passed `--no-qr-stdout`, OR stdout is not a TTY
+* / `CI` is set / `AIT_NO_QR_STDOUT` is set (non-interactive — a captured stdout
+* must not leak the relay wss + TOTP `at=` code that the QR block encodes). The
+* suppression is whole-chunk: `attachUrl` AND `relayUrl` ride in the same block.
+*
+* Exported for unit testing.
+*/
+function shouldSuppressQr(noQrFlag) {
+	return noQrFlag || !process.stdout.isTTY || process.env.CI !== void 0 || process.env.AIT_NO_QR_STDOUT !== void 0;
+}
+/**
+* CLI entry point.
+*
+* Performs a standalone relay attach → run lifecycle, sharing the attach
+* assembly with the Vitest pool via `createRelayConnectionFactory` (single
+* source — no drift):
+*
+* 1. Parse args: globs, --timeout, --cell-sdk-line, --cell-platform,
+*    --scheme-url (required for env3), --report-dir, --no-qr-stdout,
+*    --headless, --project-root.
+* 2. Discover test files; exit 1 if none.
+* 3. factory.open() — boot relay → render QR (suppressed on non-interactive
+*    stdout) → wait for phone → inject cell → enableDomains. Returns the conn.
+* 4. runWithConnection(conn, files, { timeoutMs, collectCaptures, printSummary }).
+* 5. With --report-dir: write the runner-agnostic report + capture files.
+* 6. factory.close(); process.exitCode = failed > 0 ? 1 : 0.
+*
+* The CLI is not a daemon — no lock, router, SSE, or tools_list is needed.
+* Attach timeout exits with code 1; test failures exit with code 1.
+*
+* SECRET-HANDLING: scheme_url / relay wssUrl / TOTP codes are never written to
+* stdout/stderr directly. The QR block (which encodes the TOTP `at=` code) is
+* printed only when stdout is interactive AND not suppressed.
+*/
+async function main(argv = process.argv.slice(2)) {
+	let parsed;
+	try {
+		parsed = parseArgs({
+			args: argv,
+			options: {
+				help: {
+					type: "boolean",
+					short: "h"
+				},
+				timeout: { type: "string" },
+				"scheme-url": { type: "string" },
+				"cell-sdk-line": { type: "string" },
+				"cell-platform": { type: "string" },
+				"report-dir": { type: "string" },
+				"no-qr-stdout": { type: "boolean" },
+				headless: { type: "boolean" },
+				"project-root": { type: "string" }
+			},
+			allowPositionals: true
+		});
+	} catch (e) {
+		process.stderr.write(`devtools-test: ${e instanceof Error ? e.message : String(e)}\n`);
+		process.exitCode = 1;
+		return;
+	}
+	if (parsed.values.help || argv.length === 0) {
+		process.stdout.write(USAGE);
+		return;
+	}
+	const vals = parsed.values;
+	const rawTimeout = typeof vals.timeout === "string" ? vals.timeout : void 0;
+	const timeoutMs = rawTimeout !== void 0 ? parseInt(rawTimeout, 10) : 3e4;
+	if (Number.isNaN(timeoutMs) || timeoutMs <= 0) {
+		process.stderr.write(`devtools-test: --timeout must be a positive integer\n`);
+		process.exitCode = 1;
+		return;
+	}
+	const schemeUrl = typeof vals["scheme-url"] === "string" ? vals["scheme-url"] : "";
+	if (schemeUrl === "") {
+		process.stderr.write("devtools-test: --scheme-url is required for standalone relay attach.\n  Pass the intoss-private:// URL from `ait deploy --scheme-only`.\n");
+		process.exitCode = 1;
+		return;
+	}
+	const headless = vals.headless === true;
+	const projectRoot = typeof vals["project-root"] === "string" ? vals["project-root"] : process.cwd();
+	const reportDir = typeof vals["report-dir"] === "string" ? vals["report-dir"] : void 0;
+	const suppressQr = shouldSuppressQr(vals["no-qr-stdout"] === true);
+	const cellSdkLine = typeof vals["cell-sdk-line"] === "string" ? vals["cell-sdk-line"] : void 0;
+	const cellPlatform = typeof vals["cell-platform"] === "string" ? vals["cell-platform"] : process.env.AIT_CELL_PLATFORM;
+	const hasCell = cellSdkLine !== void 0 || cellPlatform !== void 0;
+	const cell = {
+		sdkLine: cellSdkLine ?? "2.x",
+		platform: cellPlatform ?? "mock"
+	};
+	const globs = parsed.positionals;
+	if (globs.length === 0) {
+		process.stderr.write(`devtools-test: at least one glob pattern is required\n`);
+		process.stdout.write(USAGE);
+		process.exitCode = 1;
+		return;
+	}
+	const files = await discoverTestFiles(globs, process.cwd());
+	if (files.length === 0) {
+		process.stderr.write(`devtools-test: no test files matched ${globs.join(", ")}\n`);
+		process.exitCode = 1;
+		return;
+	}
+	process.stderr.write(`devtools-test: found ${files.length} test file(s)\n`);
+	if (hasCell) process.stderr.write(`devtools-test: injecting __AIT_CELL__ = ${JSON.stringify(cell)}\n`);
+	const factory = createRelayConnectionFactory({
+		schemeUrl,
+		projectRoot,
+		timeoutMs,
+		headless,
+		cell: hasCell ? cell : void 0,
+		onQrContent: (chunks) => {
+			if (suppressQr) {
+				process.stdout.write("QR suppressed (non-interactive)\n");
+				return;
+			}
+			for (const chunk of chunks) process.stdout.write(`${chunk}\n`);
+		}
+	});
+	let connection;
+	try {
+		connection = await factory.open();
+	} catch (e) {
+		process.stderr.write(`devtools-test: ${e instanceof Error ? e.message : String(e)}\n`);
+		process.exitCode = 1;
+		return;
+	}
+	let exitCode = 0;
+	try {
+		const report = await runWithConnection(connection, files, {
+			timeoutMs,
+			printSummary: true,
+			collectCaptures: reportDir !== void 0
+		});
+		if (reportDir !== void 0) try {
+			const reportPath = await writeReportArtifact(report, reportDir, {
+				sdkLine: cell.sdkLine,
+				platform: cell.platform,
+				projectRoot
+			});
+			process.stderr.write(`devtools-test: wrote report ${reportPath}\n`);
+			const capturePaths = await writeCaptureArtifacts(report.captures, `${reportDir}/.ait-capture`, cell);
+			if (capturePaths.length > 0) process.stderr.write(`devtools-test: wrote ${capturePaths.length} capture file(s)\n`);
+		} catch (e) {
+			process.stderr.write(`devtools-test: failed to write report artifacts: ${e instanceof Error ? e.message : String(e)}\n`);
+		}
+		exitCode = report.totals.failed > 0 ? 1 : 0;
+	} finally {
+		await factory.close(connection);
+		process.exitCode = exitCode;
+	}
+}
+if (import.meta.url === new URL(process.argv[1], "file://").href) main().catch((e) => {
+	process.stderr.write(`devtools-test: unexpected error: ${e instanceof Error ? e.message : String(e)}\n`);
+	process.exitCode = 1;
+});
+//#endregion
+//#region src/shared/relay-auth-close.ts
+/**
+* Shared constants for the relay's named TOTP-auth rejection (issue #478).
+*
+* Before #478 the relay rejected an unauthenticated WebSocket upgrade with a
+* raw `HTTP/1.1 401` + `socket.destroy()`. A handshake aborted that way is
+* indistinguishable from a network failure on the browser side — the
+* WebSocket only ever sees close code 1006, so the phone (env-2 launcher PWA)
+* could not tell "stale TOTP code" apart from "tunnel down" and stayed
+* silent. The fix is accept-then-close: complete the handshake, then close
+* with an application close code that NAMES the rejection.
+*
+* Three parties share this contract:
+*   - `src/mcp/chii-relay.ts` (Node) sends the close frame / HTTP error body;
+*   - `src/in-app/attach.ts` (browser) observes relay-bound WebSockets and
+*     surfaces the code to the launcher shell;
+*   - `src/mcp/chii-connection.ts` (Node daemon client) recognises the code
+*     as an auth failure on its own `/client` dial (defensive — #439's fresh
+*     code mint means it should not normally hit this).
+*
+* This module is intentionally dependency-free (no Node, no DOM) so it is
+* safe to import from both the browser in-app bundle and the MCP daemon
+* bundle.
+*
+* SECRET-HANDLING: these are fixed enum values. The close reason / error body
+* must never grow to carry a secret, a TOTP code, or a host.
+*/
+/**
+* WebSocket close code sent by the relay when TOTP auth is rejected.
+*
+* 4000–4999 is the application-reserved range (RFC 6455 §7.4.2); 4401 mirrors
+* HTTP 401 so it reads as "unauthorized" at a glance.
+*/
+const RELAY_AUTH_REJECT_CLOSE_CODE = 4401;
+/**
+* Close reason string accompanying {@link RELAY_AUTH_REJECT_CLOSE_CODE}, and
+* the `error` value of the relay's HTTP 401 JSON body. Enum string only —
+* never interpolated with request data.
+*/
+const RELAY_AUTH_REJECT_REASON = "totp-rejected";
+//#endregion
+//#region src/mcp/chii-connection.ts
+/**
+* Production `CdpConnection` backed by the local Chii relay.
+*
+* Topology (debug mode):
+*   phone target.js  --WS-->  Chii relay :9100  <--WS--  this connection
+*
+* The phone connects to the relay as a `target`; this module connects as a
+* `client` (the role a CDP frontend would take) so CDP events the page emits
+* (`Runtime.consoleAPICalled`, `Network.*`) flow back here. We buffer recent
+* events in ring buffers the tool layer reads via `getBufferedEvents`.
+*
+* Node-only: imports `ws`. Never bundled into the browser/in-app entries.
+*
+* Attach reliability (#281):
+*   `refreshTargets()` emits an internal 'target:attached' event whenever a
+*   new target is added to the relay. `waitForFirstTarget()` awaits that event
+*   (with a polling-interval fallback) so `start_attach`'s attach wait
+*   resolves deterministically rather than racing between polling rounds.
+*/
+/** Max events retained per domain ring buffer. */
+const DEFAULT_BUFFER_SIZE = 500;
+function isObject(value) {
+	return typeof value === "object" && value !== null;
+}
+function parseInbound(raw) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return null;
+	}
+	if (!isObject(parsed)) return null;
+	const message = {};
+	if (typeof parsed.id === "number") message.id = parsed.id;
+	if (typeof parsed.method === "string") message.method = parsed.method;
+	if ("params" in parsed) message.params = parsed.params;
+	if ("result" in parsed) message.result = parsed.result;
+	if (isObject(parsed.error) && typeof parsed.error.message === "string") message.error = { message: parsed.error.message };
+	return message;
+}
+const PHASE_1_EVENTS = [
+	"Runtime.consoleAPICalled",
+	"Network.requestWillBeSent",
+	"Network.responseReceived"
+];
+/**
+* Ring buffer size for `Runtime.exceptionThrown`.
+*
+* Exceptions are rarer than console messages but each is heavier (stack
+* trace). 50 is generous enough to cover a crash scenario while keeping
+* memory bounded.
+*
+* **Lifecycle note**: the exception buffer intentionally survives `replaced` /
+* `crashed` / `destroyed` lifecycle events — it is NOT cleared on target
+* transitions. Rationale: an exception fired just before a crash is exactly
+* the signal we want to preserve for root-cause analysis. The buffer
+* represents "exceptions seen in this MCP session", not "exceptions in the
+* current page".
+*/
+const EXCEPTION_BUFFER_SIZE = 50;
+/** Default per-command timeout if neither option nor env var is set. */
+const DEFAULT_COMMAND_TIMEOUT_MS = 3e4;
+/**
+* Production CDP connection. Polls the relay for the first attached target,
+* opens a client websocket to it, enables Phase 1 domains, and buffers events.
+*/
+var ChiiCdpConnection = class {
+	/** Authoritative connection kind (issue #348) — relay-backed. */
+	kind = "relay";
+	relayBaseUrl;
+	bufferSize;
+	commandTimeoutMs;
+	totpSecret;
+	emitter = new EventEmitter();
+	buffers = /* @__PURE__ */ new Map();
+	targets = /* @__PURE__ */ new Map();
+	ws = null;
+	connectionState = "idle";
+	nextCommandId = 1;
+	/**
+	* The single active target id under the single-attach model.
+	* Updated by `refreshTargets()` whenever a non-null target is present.
+	* Used to detect a new (different) target attach and evict the previous one.
+	*/
+	activeTargetId = null;
+	/** In-flight enableDomains() promise — concurrent callers share it. */
+	enablingPromise = null;
+	/** Pending request→response commands keyed by CDP message id. */
+	pending = /* @__PURE__ */ new Map();
+	/**
+	* Timestamp (ms since epoch) of the most recent crash/destroy/detach event,
+	* or `null` if no crash has been detected since the last `enableDomains()`.
+	*/
+	lastCrashDetectedAt = null;
+	/**
+	* Per-target last-seen timestamp (ms since epoch). Updated on any inbound
+	* CDP message carrying data from a target. Keyed by target id.
+	*/
+	targetLastSeenAt = /* @__PURE__ */ new Map();
+	/** Active heartbeat interval handle (only when `AIT_CDP_HEARTBEAT_MS` is set). */
+	heartbeatHandle = null;
+	/** Lifecycle event listeners (crash / destroyed / detached). */
+	lifecycleListeners = [];
+	constructor(options) {
+		this.relayBaseUrl = options.relayBaseUrl.replace(/\/$/, "");
+		this.bufferSize = options.bufferSize ?? DEFAULT_BUFFER_SIZE;
+		this.totpSecret = options.totpSecret;
+		const envMs = process.env.AIT_CDP_COMMAND_TIMEOUT_MS ? Number(process.env.AIT_CDP_COMMAND_TIMEOUT_MS) : void 0;
+		this.commandTimeoutMs = (envMs !== void 0 && Number.isFinite(envMs) && envMs > 0 ? envMs : void 0) ?? options.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
+		for (const event of PHASE_1_EVENTS) this.buffers.set(event, []);
+		this.buffers.set("Runtime.exceptionThrown", []);
+		this.emitter.setMaxListeners(0);
+	}
+	/** Refresh the attached-target list from the relay's `GET /targets`. */
+	async refreshTargets() {
+		let targetsUrl = `${this.relayBaseUrl}/targets`;
+		if (this.totpSecret) {
+			const code = generateTotp(this.totpSecret);
+			targetsUrl += `?at=${encodeURIComponent(code)}`;
+		}
+		const res = await fetch(targetsUrl);
+		if (!res.ok) throw new Error(`Chii relay /targets returned HTTP ${res.status} ${res.statusText}`);
+		const body = await res.json();
+		const list = isObject(body) && Array.isArray(body.targets) ? body.targets : [];
+		let newestTargetId = null;
+		for (const item of list) {
+			if (!isObject(item) || typeof item.id !== "string") continue;
+			newestTargetId = item.id;
+		}
+		if (newestTargetId !== null && this.activeTargetId !== null && newestTargetId !== this.activeTargetId) {
+			const prevId = this.activeTargetId;
+			logInfo("page.detached", { prevTargetId: prevId });
+			this.evictTarget(prevId);
+		}
+		this.targets.clear();
+		for (const item of list) {
+			if (!isObject(item) || typeof item.id !== "string") continue;
+			if (item.id !== newestTargetId) continue;
+			this.targets.set(item.id, {
+				id: item.id,
+				title: typeof item.title === "string" ? item.title : "",
+				url: typeof item.url === "string" ? item.url : ""
+			});
+		}
+		if (newestTargetId !== null) this.activeTargetId = newestTargetId;
+		else this.activeTargetId = null;
+		const result = [...this.targets.values()];
+		if (newestTargetId !== null) this.emitter.emit("target:attached", result);
+		return result;
+	}
+	listTargets() {
+		return [...this.targets.values()];
+	}
+	/**
+	* Waits until at least one target matching `filterFn` is attached, then
+	* resolves with the full target list at that moment.
+	*
+	* Resolution happens on whichever comes first:
+	*   (a) a `'target:attached'` event from `refreshTargets()` (triggered by
+	*       the /targets poll finding a new target), OR
+	*   (b) a `'target:attached'` event from `handleMessage()` (triggered by
+	*       the first inbound CDP message from a target — confirms the relay
+	*       websocket has data from the phone, not just a target entry in the map).
+	*
+	* This dual-signal approach eliminates the polling race that previously
+	* caused `wait_for_attach` to resolve before the first CDP message arrived.
+	*
+	* Falls back to checking `listTargets()` every `pollIntervalMs` in case the
+	* EventEmitter is missed (defensive belt-and-suspenders).
+	*
+	* @param filterFn  - Predicate that the returned targets must satisfy.
+	* @param timeoutMs - Reject after this many ms (default 90 000).
+	* @param pollIntervalMs - Fallback poll interval (default 500ms).
+	*/
+	waitForFirstTarget(filterFn, timeoutMs = 9e4, pollIntervalMs = 500) {
+		const current = this.listTargets();
+		if (filterFn(current)) return Promise.resolve(current);
+		return new Promise((resolve, reject) => {
+			let settled = false;
+			let pollHandle = null;
+			const settle = (targets) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timeoutHandle);
+				if (pollHandle !== null) {
+					clearInterval(pollHandle);
+					pollHandle = null;
+				}
+				this.emitter.off("target:attached", onAttach);
+				resolve(targets);
+			};
+			const onAttach = (targets) => {
+				if (filterFn(targets)) settle(targets);
+			};
+			const timeoutHandle = setTimeout(() => {
+				if (settled) return;
+				settled = true;
+				if (pollHandle !== null) {
+					clearInterval(pollHandle);
+					pollHandle = null;
+				}
+				this.emitter.off("target:attached", onAttach);
+				reject(/* @__PURE__ */ new Error(`waitForFirstTarget: 타임아웃 (${timeoutMs}ms) — 폰이 relay에 attach되지 않았습니다.`));
+			}, timeoutMs);
+			this.emitter.on("target:attached", onAttach);
+			pollHandle = setInterval(() => {
+				this.refreshTargets().then((targets) => {
+					if (filterFn(targets)) settle(targets);
+				}, () => {});
+			}, pollIntervalMs);
+		});
+	}
+	/**
+	* Timestamp (ms since epoch) of the most recent crash/destroy/detach event
+	* detected since the last `enableDomains()` call, or `null` if none.
+	*/
+	getLastCrashDetectedAt() {
+		return this.lastCrashDetectedAt;
+	}
+	/**
+	* Last-seen timestamp (ms since epoch) for a given target id, or `null` if
+	* the target is unknown / no message has been received from it yet.
+	*/
+	getTargetLastSeenAt(targetId) {
+		return this.targetLastSeenAt.get(targetId) ?? null;
+	}
+	/** Subscribe to target lifecycle events (crash / destroyed / detached). */
+	onLifecycle(listener) {
+		this.lifecycleListeners.push(listener);
+		return () => {
+			const idx = this.lifecycleListeners.indexOf(listener);
+			if (idx !== -1) this.lifecycleListeners.splice(idx, 1);
+		};
+	}
+	/**
+	* Connect a client websocket to the first attached target and enable Phase 1
+	* domains. Resolves once the socket is open and enable commands are sent.
+	*/
+	async enableDomains() {
+		if (this.ws && this.ws.readyState === WebSocket.OPEN) return;
+		if (this.enablingPromise) return this.enablingPromise;
+		this.enablingPromise = this._doEnableDomains().finally(() => {
+			this.enablingPromise = null;
+		});
+		return this.enablingPromise;
+	}
+	async _doEnableDomains() {
+		const target = (await this.refreshTargets())[0];
+		if (!target) throw new Error("No mini-app page attached to the Chii relay yet.");
+		let clientUrl = `${this.relayBaseUrl.replace(/^http/, "ws")}/client/${`devtools-mcp-${Date.now()}`}?target=${encodeURIComponent(target.id)}`;
+		if (this.totpSecret) {
+			const code = generateTotp(this.totpSecret);
+			clientUrl += `&at=${encodeURIComponent(code)}`;
+		}
+		const ws = new WebSocket(clientUrl);
+		this.ws = ws;
+		await new Promise((resolve, reject) => {
+			ws.once("open", () => resolve());
+			ws.once("error", (err) => reject(err));
+			ws.once("close", (code) => {
+				if (code === 4401) reject(/* @__PURE__ */ new Error("relay 인증(TOTP)이 거부됐습니다 (close 4401). 코드가 만료됐을 수 있습니다 — 재연결 시 새 코드가 발급됩니다."));
+			});
+		});
+		this.lastCrashDetectedAt = null;
+		this.targetLastSeenAt.clear();
+		this.connectionState = "connected";
+		ws.on("message", (data) => this.handleMessage(data.toString()));
+		ws.on("close", (code) => this.handleDisconnect(code === 4401 ? "relay 인증(TOTP)이 거부돼 연결이 종료됐습니다 (close 4401)" : "relay WebSocket 연결이 끊겼습니다"));
+		ws.on("error", (err) => this.handleDisconnect(`relay WebSocket 오류: ${err.message}`));
+		this.sendFireAndForget("Runtime.enable");
+		this.sendFireAndForget("Network.enable");
+		this.sendFireAndForget("DOM.enable");
+		this.sendFireAndForget("Page.enable");
+		this.sendFireAndForget("Inspector.enable");
+		this.sendFireAndForget("Target.setDiscoverTargets", { discover: true });
+		this.startHeartbeat(target.id);
+	}
+	/** Fire-and-forget CDP message (used for `*.enable`, no result awaited). */
+	sendFireAndForget(method, params = {}) {
+		if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+		const id = this.nextCommandId++;
+		this.ws.send(JSON.stringify({
+			id,
+			method,
+			params
+		}));
+	}
+	/**
+	* Issue a CDP command and resolve with its result (Phase 2). Rejects on a CDP
+	* error frame or when no websocket is open (no page attached yet).
+	*/
+	send(method, params) {
+		return this.sendCommand(method, params ?? {});
+	}
+	/**
+	* Issue an arbitrary request→response command over the relay and resolve with
+	* its raw result. Both the typed CDP {@link send} and the AIT domain (Phase 3
+	* `AIT.*` methods, forwarded over the same Chii channel) build on this.
+	*
+	* Rejects immediately if the connection is disconnected (fail-fast — no
+	* auto-reconnect). Caller should re-run `list_pages` or `enableDomains` to
+	* reattach.
+	*
+	* Times out after `commandTimeoutMs` (default 30s, env
+	* `AIT_CDP_COMMAND_TIMEOUT_MS`). On timeout the pending entry is cleaned up
+	* and the promise rejects with a descriptive Korean error.
+	*/
+	sendCommand(method, params = {}) {
+		if (this.connectionState === "disconnected") return Promise.reject(/* @__PURE__ */ new Error(`relay에 연결되어 있지 않습니다 (${method}). list_pages로 attach 상태를 확인하고 enableDomains()로 재연결하세요.`));
+		if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return Promise.reject(/* @__PURE__ */ new Error("No mini-app page attached to the Chii relay yet. Call enableDomains() first."));
+		const id = this.nextCommandId++;
+		const ws = this.ws;
+		const timeoutMs = this.commandTimeoutMs;
+		return new Promise((resolve, reject) => {
+			const handle = setTimeout(() => {
+				this.pending.delete(id);
+				reject(/* @__PURE__ */ new Error(`CDP 명령이 타임아웃됐습니다 (${method}, ${timeoutMs}ms). 폰 측 토스 앱이 백그라운드로 내려갔거나 미니앱이 unload됐을 수 있습니다. list_pages로 attach 상태를 확인하세요.`));
+			}, timeoutMs);
+			this.pending.set(id, {
+				resolve: (v) => {
+					clearTimeout(handle);
+					resolve(v);
+				},
+				reject: (e) => {
+					clearTimeout(handle);
+					reject(e);
+				}
+			});
+			ws.send(JSON.stringify({
+				id,
+				method,
+				params
+			}));
+		});
+	}
+	/**
+	* Called on WebSocket `close` or `error` after a successful connection.
+	* Rejects all pending commands and marks the connection as disconnected so
+	* subsequent `sendCommand` calls fail fast (no auto-reconnect).
+	*/
+	handleDisconnect(reason) {
+		if (this.connectionState === "disconnected") return;
+		this.connectionState = "disconnected";
+		this.ws = null;
+		this.stopHeartbeat();
+		const err = /* @__PURE__ */ new Error(`${reason}. list_pages로 attach 상태를 확인하고 enableDomains()로 재연결하세요.`);
+		for (const waiter of this.pending.values()) waiter.reject(err);
+		this.pending.clear();
+	}
+	/**
+	* Evict a previously active target under the single-attach model.
+	* Rejects pending commands with a 'replaced-by-new-attach' reason and emits
+	* a 'replaced' lifecycle event. Does NOT clear all targets — only the specific
+	* targetId. The caller is responsible for rebuilding the targets map afterwards.
+	*
+	* The error message uses 'replaced-by-new-attach' so test assertions can match it.
+	*/
+	evictTarget(targetId) {
+		const detectedAt = (/* @__PURE__ */ new Date()).toISOString();
+		this.targets.delete(targetId);
+		this.targetLastSeenAt.delete(targetId);
+		const err = /* @__PURE__ */ new Error(`[ait-debug] replaced-by-new-attach — 이전 page 세션이 새 attach로 교체됐습니다 (targetId=${targetId}). list_pages로 현재 attach 상태를 확인하세요.`);
+		for (const waiter of this.pending.values()) waiter.reject(err);
+		this.pending.clear();
+		const event = {
+			kind: "replaced",
+			targetId,
+			detectedAt
+		};
+		for (const listener of this.lifecycleListeners) try {
+			listener(event);
+		} catch {}
+	}
+	/**
+	* Handle a page-level crash or target destruction event.
+	* Removes the target from the in-memory map, rejects all pending commands,
+	* and emits a lifecycle event.
+	*
+	* @param kind - Event kind: 'crashed' | 'destroyed' | 'detached'
+	* @param targetId - The target ID from the event params (may be null for
+	*   Inspector.targetCrashed which has no targetId in the params).
+	*/
+	handleTargetGone(kind, targetId) {
+		const detectedAt = (/* @__PURE__ */ new Date()).toISOString();
+		this.lastCrashDetectedAt = Date.now();
+		if (targetId !== null) {
+			this.targets.delete(targetId);
+			this.targetLastSeenAt.delete(targetId);
+			if (this.activeTargetId === targetId) this.activeTargetId = null;
+		} else {
+			this.targets.clear();
+			this.targetLastSeenAt.clear();
+			this.activeTargetId = null;
+		}
+		const err = /* @__PURE__ */ new Error(`[ait-debug] ${kind === "crashed" ? "page crash (Inspector.targetCrashed)" : kind === "destroyed" ? "target 종료 (Target.targetDestroyed)" : "target detach (Target.detachedFromTarget)"} 감지됨 — relay에서 제거됐습니다. 새 attach가 필요합니다 (list_pages로 확인 → enableDomains()로 재연결).`);
+		for (const waiter of this.pending.values()) waiter.reject(err);
+		this.pending.clear();
+		const event = {
+			kind,
+			targetId,
+			detectedAt
+		};
+		for (const listener of this.lifecycleListeners) try {
+			listener(event);
+		} catch {}
+	}
+	/**
+	* Start the optional CDP heartbeat loop.
+	*
+	* When `AIT_CDP_HEARTBEAT_MS` is set to a positive integer, every interval
+	* we send `Runtime.evaluate({expression: '1'})` to each active target. If
+	* the command times out (2 s hard deadline) or errors, we treat the target
+	* as dead and call `handleTargetGone`.
+	*
+	* This is a zombie-detector fallback: cloudflared keeps-alive the tunnel ws
+	* even when the phone app has crashed, so the ws-level disconnect (#252) won't
+	* fire. The heartbeat catches this gap.
+	*
+	* Default: OFF. Only activates when `AIT_CDP_HEARTBEAT_MS` is set.
+	*/
+	startHeartbeat(initialTargetId) {
+		this.stopHeartbeat();
+		const envMs = process.env.AIT_CDP_HEARTBEAT_MS ? Number(process.env.AIT_CDP_HEARTBEAT_MS) : void 0;
+		if (envMs === void 0 || !Number.isFinite(envMs) || envMs <= 0) return;
+		const PING_TIMEOUT_MS = 2e3;
+		this.heartbeatHandle = setInterval(() => {
+			const targetIds = this.targets.size > 0 ? [...this.targets.keys()] : [initialTargetId];
+			for (const targetId of targetIds) {
+				const pingPromise = this.sendCommand("Runtime.evaluate", {
+					expression: "1",
+					returnByValue: true,
+					timeout: PING_TIMEOUT_MS
+				});
+				const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error("heartbeat timeout")), PING_TIMEOUT_MS + 500));
+				Promise.race([pingPromise, timeoutPromise]).catch(() => {
+					if (this.targets.has(targetId)) this.handleTargetGone("destroyed", targetId);
+				});
+			}
+		}, envMs);
+	}
+	stopHeartbeat() {
+		if (this.heartbeatHandle !== null) {
+			clearInterval(this.heartbeatHandle);
+			this.heartbeatHandle = null;
+		}
+	}
+	handleMessage(raw) {
+		const message = parseInbound(raw);
+		if (!message) return;
+		if (typeof message.id === "number" && this.pending.has(message.id)) {
+			const waiter = this.pending.get(message.id);
+			this.pending.delete(message.id);
+			if (waiter) if (message.error) waiter.reject(new Error(message.error.message));
+			else waiter.resolve(message.result);
+			return;
+		}
+		const now = Date.now();
+		let firstMessageSeen = false;
+		for (const targetId of this.targets.keys()) {
+			if (!this.targetLastSeenAt.has(targetId)) firstMessageSeen = true;
+			this.targetLastSeenAt.set(targetId, now);
+		}
+		if (firstMessageSeen && this.targets.size > 0) this.emitter.emit("target:attached", [...this.targets.values()]);
+		if (typeof message.method !== "string") return;
+		if (message.method === "Inspector.targetCrashed") {
+			this.handleTargetGone("crashed", null);
+			return;
+		}
+		if (message.method === "Target.targetDestroyed") {
+			const targetId = isObject(message.params) && typeof message.params.targetId === "string" ? message.params.targetId : null;
+			this.handleTargetGone("destroyed", targetId);
+			return;
+		}
+		if (message.method === "Target.detachedFromTarget") {
+			const targetId = isObject(message.params) && typeof message.params.targetId === "string" ? message.params.targetId : null;
+			this.handleTargetGone("detached", targetId);
+			return;
+		}
+		if (!this.buffers.has(message.method)) return;
+		const event = message.method;
+		const buffer = this.buffers.get(event);
+		if (!buffer) return;
+		buffer.push(message.params);
+		const cap = event === "Runtime.exceptionThrown" ? EXCEPTION_BUFFER_SIZE : this.bufferSize;
+		if (buffer.length > cap) buffer.shift();
+		this.emitter.emit(event, message.params);
+	}
+	getBufferedEvents(event) {
+		return this.buffers.get(event) ?? [];
+	}
+	on(event, listener) {
+		this.emitter.on(event, listener);
+		return () => this.emitter.off(event, listener);
+	}
+	/** Close the relay client websocket and reject any in-flight commands. */
+	close() {
+		const ws = this.ws;
+		this.stopHeartbeat();
+		this.handleDisconnect("Chii relay connection closed");
+		ws?.close();
+	}
+};
+//#endregion
+//#region src/mcp/chii-relay.ts
+/**
+* Boots the local Chii relay server.
+*
+* Chii (liriliri/chii) is a chobitsu-based CDP relay that lets non-Chrome
+* WebViews (iOS WKWebView / Android WebView — i.e. the Toss app) expose CDP.
+* The relay accepts a `target` websocket from the phone's injected `target.js`
+* and `client` websockets from CDP frontends (our MCP connection).
+*
+* Node-only: `chii` pulls in Koa + ws. Never bundled into the browser/in-app
+* entries.
+*
+* TOTP auth (relay-side, authoritative gate):
+*   When `verifyAuth` is provided, this module gates both inbound surfaces:
+*
+*   - HTTP 'request': a listener registered BEFORE `chii.start({server})`.
+*     Node's `http.Server` calls listeners in registration order; the first
+*     to call `res.end()` wins. Invalid auth → 401 + CORS header + a tiny
+*     JSON body (`{"error":"totp-rejected"}`) so a cross-origin script
+*     `fetch()` probe can READ the status (issue #478). Valid auth → return
+*     without side-effect (chii's Koa handler serves it).
+*
+*   - WS 'upgrade': after `chii.start()` has registered chii's own upgrade
+*     listener, we take over the upgrade chain (remove chii's listeners,
+*     re-dispatch manually). Invalid auth → accept-then-close: complete the
+*     handshake via a `noServer` WebSocketServer, then immediately close
+*     with code 4401 reason 'totp-rejected' (issue #478). A raw 401 +
+*     `socket.destroy()` only ever surfaced as close code 1006 in the
+*     browser — indistinguishable from a tunnel failure, which left the
+*     env-2 phone UI silent. The explicit dispatch (not listener ordering)
+*     is what keeps chii away from rejected sockets: accept-then-close
+*     leaves the socket alive, so an order-based early-return would let
+*     chii's later listener complete a SECOND handshake on the same socket
+*     — an auth bypass. Valid auth → forward to chii's captured listeners.
+*
+* TOTP code transports (issue #466) — two equivalent ways to carry the code:
+*   1. Query param `at=<code>` — used by the daemon-side `/client` connection
+*      (`chii-connection.ts` appends it; it holds the secret).
+*   2. Path prefix `/at/<code>/…` — used by the phone-side target. Chii's
+*      stock `target.js` derives its WS endpoint from the script `src`
+*      (`scriptEl.src.replace('target.js','')`), so the only way for the
+*      phone to carry a code is to embed it in the script URL path. The
+*      in-app attach injects `https://<host>/at/<code>/target.js`; both the
+*      script fetch and the derived `wss://<host>/at/<code>/target/<id>` WS
+*      dial then carry the prefix. The listeners below rewrite the prefix
+*      into the query form (`rewriteAtPathPrefix`) and MUTATE `req.url`
+*      before chii's own handlers (registered later) parse it — chii only
+*      ever sees the stripped URL.
+*
+* Threat model: "URL leak" — someone obtains the tunnel URL (Slack paste, QR
+*   screenshot, shoulder-surfing) but does not have the shared TOTP secret.
+*   Rotating 6-digit code makes the URL stale after 30 s.
+*   A determined attacker who extracts the secret from the dogfood bundle can
+*   still compute valid codes; that is out of scope (see umbrella CLAUDE.md §4).
+*
+* SECRET-HANDLING: The secret value and computed TOTP codes MUST NOT appear
+*   in any log, error message, or process output. `verifyAuth` is a black-box
+*   predicate from the caller's perspective; this module only forwards pass/fail.
+*/
+const require = createRequire(import.meta.url);
+/**
+* WS keepalive ping interval (ms).
+*
+* Cloudflare proxied connections are dropped after ~100 s of no traffic.
+* 45 s comfortably fits inside that window and lets both the phone-target leg
+* and the daemon-client leg survive idle CDP sessions.
+*/
+const DEFAULT_KEEPALIVE_INTERVAL_MS = 45e3;
+/**
+* Loads chii's internal WebSocketServer class and returns it together with a
+* flag indicating whether the real class was found.
+*
+* Returns `null` if the internal path is not resolvable (future chii release
+* changes the layout) — callers skip keepalive gracefully.
+*/
+function tryLoadChiiWssClass() {
+	try {
+		const mod = require("chii/server/lib/WebSocketServer");
+		if (typeof mod === "function") return mod;
+	} catch {}
+	return null;
+}
+/**
+* Calls `chii.start()` and returns the chii `WebSocketServer` instance that
+* was constructed during the call.
+*
+* How: `chii/server/index.js`'s `start()` creates `new WebSocketServer()`
+* where `WebSocketServer` is captured from `require('./lib/WebSocketServer')`
+* at module load time. The class reference is stable, so we can temporarily
+* patch `ChiiWssClass.prototype.start` — which runs *on the instance* —
+* to record `this` before the original `start` runs.
+*
+* The patch is installed before `chii.start()` and removed (via `finally`)
+* immediately after, so concurrent `startChiiRelay` calls nest correctly: each
+* call's patch overrides the previous in the prototype chain for the duration
+* of its own `chii.start()` call, restoring the prior descriptor on exit.
+*
+* If `ChiiWssClass` is null (internal path changed in a future chii release),
+* `chii.start()` runs unpatched and the function returns null — callers skip
+* keepalive gracefully without affecting relay correctness.
+*/
+async function startChiiWithCapture(chii, startOptions, ChiiWssClass) {
+	if (ChiiWssClass === null) {
+		await chii.start(startOptions);
+		return null;
+	}
+	let captured = null;
+	const proto = ChiiWssClass.prototype;
+	const originalStart = proto.start;
+	proto.start = function(server) {
+		captured = this;
+		return originalStart.call(this, server);
+	};
+	try {
+		await chii.start(startOptions);
+	} finally {
+		proto.start = originalStart;
+	}
+	return captured;
+}
+function loadChiiServer() {
+	const mod = require("chii");
+	if (typeof mod === "object" && mod !== null && "start" in mod && typeof mod.start === "function") return mod;
+	throw new Error("chii server module did not expose start()");
+}
+/**
+* Rewrites a `/at/<code>/…` path-prefixed request URL into the equivalent
+* query-based form, e.g.:
+*
+*   `/at/123456/target.js`        → `/target.js?at=123456`
+*   `/at/123456/target/x?url=u`   → `/target/x?url=u&at=123456`
+*   `/at/123456/`                 → `/?at=123456`
+*
+* Returns `null` when the URL does not carry the prefix (including an empty
+* code segment) — callers fall back to the unmodified URL and the existing
+* query-based auth path.
+*
+* Pure string surgery — this function knows nothing about secrets or code
+* validity; verification stays inside the caller-provided `verifyAuth`
+* predicate (which parses the query). The raw path segment is appended
+* verbatim to the query: both path segments and query values are
+* percent-decoded exactly once by their consumers, so no re-encoding is
+* needed (TOTP codes are 6 digits and never percent-encoded in practice).
+*/
+function rewriteAtPathPrefix(rawUrl) {
+	const match = /^\/at\/([^/?]+)(\/[^?]*)?(\?.*)?$/.exec(rawUrl);
+	if (match === null) return null;
+	const code = match[1];
+	const path = match[2] === void 0 || match[2] === "" ? "/" : match[2];
+	const query = match[3] ?? "";
+	return `${path}${query}${query === "" ? "?" : "&"}at=${code}`;
+}
+/**
+* Starts the Chii relay and resolves once listening.
+*
+* Default port is 0 (OS-assigned). With port 0 the OS picks a free ephemeral
+* port on every start, so a stale cloudflared orphan holding any particular
+* port cannot cause EADDRINUSE. The resolved `ChiiRelay.port` and `baseUrl`
+* always reflect the actual bound port.
+*
+* chii.start() is called with `server` (our pre-created httpServer) BEFORE
+* httpServer.listen(). This is intentional: chii attaches its Koa handler and
+* WS upgrade listener to the server object, but the actual TCP bind is
+* performed by our httpServer.listen() call below. The `port`/`domain` values
+* passed to chii.start() are used for display/banner purposes inside chii and
+* do not affect which port the server binds. The connection path (clients
+* connecting to `relay.baseUrl`) always uses the post-listen confirmed port.
+*/
+async function startChiiRelay(options = {}) {
+	const requestedPort = options.port ?? 0;
+	const host = options.host ?? "127.0.0.1";
+	const { verifyAuth, onAuthReject } = options;
+	const keepaliveIntervalMs = options.keepaliveIntervalMs !== void 0 ? options.keepaliveIntervalMs : DEFAULT_KEEPALIVE_INTERVAL_MS;
+	const httpServer = createServer();
+	const notifyAuthReject = (kind) => {
+		if (onAuthReject === void 0) return;
+		try {
+			onAuthReject({ kind });
+		} catch {}
+	};
+	if (verifyAuth) httpServer.on("request", (req, res) => {
+		const rewritten = rewriteAtPathPrefix(req.url ?? "");
+		if (rewritten !== null) {
+			req.url = rewritten;
+			if (!verifyAuth(req)) {
+				res.statusCode = 401;
+				res.setHeader("Access-Control-Allow-Origin", "*");
+				res.setHeader("Content-Type", "application/json");
+				res.end(JSON.stringify({ error: RELAY_AUTH_REJECT_REASON }));
+				notifyAuthReject("http-request");
+			}
+			return;
+		}
+		const pathname = (req.url ?? "").split("?")[0];
+		if (pathname === "/targets" || pathname === "/targets/") {
+			if (!verifyAuth(req)) {
+				res.statusCode = 401;
+				res.setHeader("Access-Control-Allow-Origin", "*");
+				res.setHeader("Content-Type", "application/json");
+				res.end(JSON.stringify({ error: RELAY_AUTH_REJECT_REASON }));
+				notifyAuthReject("http-request");
+				return;
+			}
+			return;
+		}
+	});
+	const chiiWssClass = keepaliveIntervalMs > 0 ? tryLoadChiiWssClass() : null;
+	const capturedChiiWss = await startChiiWithCapture(loadChiiServer(), {
+		server: httpServer,
+		domain: `${host}:${requestedPort}`,
+		port: requestedPort
+	}, chiiWssClass);
+	if (verifyAuth) {
+		const chiiUpgradeListeners = httpServer.listeners("upgrade");
+		httpServer.removeAllListeners("upgrade");
+		const rejectWss = new WebSocketServer({ noServer: true });
+		httpServer.on("upgrade", (req, socket, head) => {
+			const rewritten = rewriteAtPathPrefix(req.url ?? "");
+			if (rewritten !== null) req.url = rewritten;
+			if (!verifyAuth(req)) {
+				rejectWss.handleUpgrade(req, socket, head, (ws) => {
+					ws.close(RELAY_AUTH_REJECT_CLOSE_CODE, RELAY_AUTH_REJECT_REASON);
+				});
+				notifyAuthReject("ws-upgrade");
+				return;
+			}
+			for (const listener of chiiUpgradeListeners) listener(req, socket, head);
+		});
+	}
+	const actualPort = await new Promise((resolve, reject) => {
+		httpServer.once("error", reject);
+		httpServer.listen(requestedPort, host, () => {
+			httpServer.off("error", reject);
+			resolve(httpServer.address().port);
+		});
+	});
+	let keepaliveHandle = null;
+	if (keepaliveIntervalMs > 0 && capturedChiiWss !== null) {
+		const chiiWss = capturedChiiWss;
+		keepaliveHandle = setInterval(() => {
+			for (const client of chiiWss._wss.clients) if (client.readyState === 1) client.ping();
+		}, keepaliveIntervalMs);
+	}
+	return {
+		port: actualPort,
+		baseUrl: `http://${host}:${actualPort}`,
+		close: () => new Promise((resolve) => {
+			if (keepaliveHandle !== null) {
+				clearInterval(keepaliveHandle);
+				keepaliveHandle = null;
+			}
+			httpServer.close(() => resolve());
+		})
+	};
+}
+//#endregion
+//#region src/mcp/debug-server.ts
+/**
+* Factory that constructs a `ChiiCdpConnection` for the given relay base URL.
+*
+* Introduced as a named seam so PR-2 (dual-connection, #348) can defer
+* construction to first-activation time by moving or replacing this call. Since
+* #396 every family (relay included) is constructed lazily on its first
+* `start_debug`, so this is always called from the lazy boot path.
+*
+* The relay base URL is only available after `startChiiRelay()` resolves, so
+* the factory is called right after that point (same as before this refactor).
+*/
+function createRelayConnection(relayBaseUrl) {
+	return new ChiiCdpConnection({
+		relayBaseUrl,
+		totpSecret: process.env.AIT_DEBUG_TOTP_SECRET
+	});
+}
+/**
+* Boots the relay family (issues #348, #356): starts the Chii relay on an
+* OS-assigned port (with optional TOTP gate), opens a cloudflared quick tunnel
+* to the relay's confirmed port in the background, prints the attach banner,
+* and arms the tunnel health probe. Returns a {@link BootedFamily} whose
+* `getTunnelStatus()` reflects the live tunnel (it flips up once the background
+* tunnel resolves and follows reissues).
+*
+* Booted lazily via the dual router's `bootLazyFor('relay-intoss')` callback
+* (symmetry with {@link bootLocalFamily}), at most once on the first
+* `start_debug({ mode: 'relay-staging' })` (all-lazy, #396 — every relay boot now
+* flows through `switchMode` after the project-local secret load). `relay-live`
+* removed (#665).
+*
+* The relay base URL is only known after `startChiiRelay()` resolves, so the
+* `ChiiCdpConnection` (via {@link createRelayConnection}) is constructed inside
+* this function, after the relay port is confirmed.
+*
+* SECRET-HANDLING: the TOTP secret rides only inside `verifyAuth`; the wssUrl
+* (relay host) is never logged here directly.
+*/
+async function bootRelayFamily(options = {}) {
+	assertRelayAuthConfigured();
+	const relayPort = options.relayPort ?? 0;
+	const totpEnabled = options.verifyAuth !== void 0;
+	const relay = await startChiiRelay({
+		port: relayPort,
+		verifyAuth: options.verifyAuth,
+		onAuthReject: options.onAuthReject
+	});
+	logInfo("server.start", {
+		port: relay.port,
+		totpEnabled
+	});
+	let tunnel = null;
+	let tunnelStatus = makeTunnelStatus(false, null);
+	let tunnelProbe = null;
+	generateAttachToken();
+	startQuickTunnel(relay.port).then((t) => {
+		tunnel = t;
+		tunnelStatus = makeTunnelStatus(true, t.wssUrl);
+		options.onWssUrl?.(t.wssUrl);
+		if (t.childPid !== void 0) options.onTunnelChildPid?.(t.childPid);
+		logInfo("tunnel.up", { totpEnabled });
+		tunnelProbe = startTunnelHealthProbe(t, relay.port, {
+			onReissue: (newTunnel) => {
+				tunnel = newTunnel;
+				tunnelStatus = makeTunnelStatus(true, newTunnel.wssUrl, null, 0);
+				options.onWssUrl?.(newTunnel.wssUrl);
+				if (newTunnel.childPid !== void 0) options.onTunnelChildPid?.(newTunnel.childPid);
+				printAttachBanner({
+					wssUrl: newTunnel.wssUrl,
+					totpEnabled
+				}).then(() => {
+					logInfo("tunnel.up", {
+						totpEnabled,
+						reissued: true
+					});
+				});
+			},
+			onPermanentDrop: (droppedAt) => {
+				tunnelStatus = makeTunnelStatus(false, null, droppedAt, 3);
+				logError("tunnel.down", { msg: `tunnel permanently dropped (${droppedAt}). Restart: npx @ait-co/devtools devtools-mcp` });
+				options.onTunnelDown?.();
+			}
+		});
+		return printAttachBanner({
+			wssUrl: t.wssUrl,
+			totpEnabled
+		});
+	}, (err) => {
+		logError("tunnel.down", { msg: `Failed to open cloudflared quick tunnel: ${err instanceof Error ? err.message : String(err)}. The relay is up locally; attach over the public URL is unavailable until the tunnel starts.` });
+	});
+	const connection = createRelayConnection(relay.baseUrl);
+	return {
+		connection,
+		relayOrigin: "intoss-webview",
+		relayHttpUrl: relay.baseUrl,
+		getTunnelStatus: () => tunnelStatus,
+		stop() {
+			tunnelProbe?.stop();
+			tunnel?.stop();
+			connection.close();
+			relay.close();
+		}
+	};
+}
+//#endregion
+export { bootRelayFamily, buildRelayVerifyAuth };
+
+//# sourceMappingURL=debug-server-krAOy6cl.js.map