@ait-co/devtools 0.1.40 → 0.1.43

package/dist/mcp/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
-import { existsSync, realpathSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { argv } from "node:process";
 import { fileURLToPath } from "node:url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -11,27 +11,31 @@ import { WebSocket } from "ws";
 import { createServer } from "node:http";
 import { spawn } from "node:child_process";
 import net from "node:net";
-import { platform } from "node:os";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
 import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { Tunnel, bin, install } from "cloudflared";
+//#region \0rolldown/runtime.js
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+//#endregion
 //#region src/mcp/ait-chii-source.ts
-function isObject$3(value) {
+function isObject$4(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 };
+	if (isObject$4(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 : {};
+	return isObject$4(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
+		environment: isObject$4(raw) && typeof raw.environment === "string" ? raw.environment : "unknown",
+		sdkVersion: isObject$4(raw) && typeof raw.sdkVersion === "string" ? raw.sdkVersion : null
 	};
 }
 var ChiiAitSource = class {
@@ -62,10 +66,16 @@ var ChiiAitSource = class {
 * 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 `build_attach_url wait_for_attach`
+*   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) {
+function isObject$3(value) {
 	return typeof value === "object" && value !== null;
 }
 function parseInbound$1(raw) {
@@ -75,13 +85,13 @@ function parseInbound$1(raw) {
 	} catch {
 		return null;
 	}
-	if (!isObject$2(parsed)) 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$2(parsed.error) && typeof parsed.error.message === "string") message.error = { message: parsed.error.message };
+	if (isObject$3(parsed.error) && typeof parsed.error.message === "string") message.error = { message: parsed.error.message };
 	return message;
 }
 const PHASE_1_EVENTS$1 = [
@@ -90,25 +100,67 @@ const PHASE_1_EVENTS$1 = [
 	"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 {
 	relayBaseUrl;
 	bufferSize;
+	commandTimeoutMs;
 	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$1;
+		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$1) this.buffers.set(event, []);
+		this.buffers.set("Runtime.exceptionThrown", []);
 		this.emitter.setMaxListeners(0);
 	}
 	/** Refresh the attached-target list from the relay's `GET /targets`. */
@@ -116,22 +168,118 @@ var ChiiCdpConnection = class {
 		const res = await fetch(`${this.relayBaseUrl}/targets`);
 		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$3(item) || typeof item.id !== "string") continue;
+			newestTargetId = item.id;
+		}
+		if (newestTargetId !== null && this.activeTargetId !== null && newestTargetId !== this.activeTargetId) {
+			const prevId = this.activeTargetId;
+			process.stderr.write(`[ait-debug] 이전 page 세션 종료 — 새 attach로 교체 (prev=${prevId})\n`);
+			this.evictTarget(prevId);
+		}
 		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,
 				title: typeof item.title === "string" ? item.title : "",
 				url: typeof item.url === "string" ? item.url : ""
 			});
 		}
-		return [...this.targets.values()];
+		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.
 	*/
@@ -152,11 +300,19 @@ var ChiiCdpConnection = class {
 			ws.once("open", () => resolve());
 			ws.once("error", (err) => reject(err));
 		});
+		this.lastCrashDetectedAt = null;
+		this.targetLastSeenAt.clear();
+		this.connectionState = "connected";
 		ws.on("message", (data) => this.handleMessage(data.toString()));
+		ws.on("close", () => this.handleDisconnect("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 = {}) {
@@ -179,15 +335,35 @@ var ChiiCdpConnection = class {
 	* 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,
-				reject
+				resolve: (v) => {
+					clearTimeout(handle);
+					resolve(v);
+				},
+				reject: (e) => {
+					clearTimeout(handle);
+					reject(e);
+				}
 			});
 			ws.send(JSON.stringify({
 				id,
@@ -196,6 +372,117 @@ var ChiiCdpConnection = class {
 			}));
 		});
 	}
+	/**
+	* 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;
@@ -206,13 +493,35 @@ var ChiiCdpConnection = class {
 			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);
-		if (buffer.length > this.bufferSize) buffer.shift();
+		const cap = event === "Runtime.exceptionThrown" ? EXCEPTION_BUFFER_SIZE : this.bufferSize;
+		if (buffer.length > cap) buffer.shift();
 		this.emitter.emit(event, message.params);
 	}
 	getBufferedEvents(event) {
@@ -224,10 +533,10 @@ var ChiiCdpConnection = class {
 	}
 	/** Close the relay client websocket and reject any in-flight commands. */
 	close() {
-		this.ws?.close();
-		this.ws = null;
-		for (const waiter of this.pending.values()) waiter.reject(/* @__PURE__ */ new Error("Chii relay connection closed."));
-		this.pending.clear();
+		const ws = this.ws;
+		this.stopHeartbeat();
+		this.handleDisconnect("Chii relay connection closed");
+		ws?.close();
 	}
 };
 //#endregion
@@ -260,9 +569,9 @@ var ChiiCdpConnection = class {
 *   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);
+const require$1 = createRequire(import.meta.url);
 function loadChiiServer() {
-	const mod = require("chii");
+	const mod = require$1("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()");
 }
@@ -315,6 +624,206 @@ async function startChiiRelay(options = {}) {
 	};
 }
 //#endregion
+//#region src/mcp/devtools-opener.ts
+/**
+* Base URL for the Chrome DevTools inspector hosted on appspot.
+*
+* The `@` path segment is the "latest / bleeding edge" alias which tracks the
+* current Chrome stable CDP protocol version — compatible with the chobitsu-
+* based CDP that Chii injects. A specific commit hash may be pinned here if
+* a regression is observed.
+*/
+const DEVTOOLS_FRONTEND_BASE = "https://chrome-devtools-frontend.appspot.com/serve_file/@/inspector.html";
+/**
+* Assembles the Chrome DevTools inspector URL that connects to a Chii relay
+* WebSocket.
+*
+* The `wss=` parameter expects a host-and-path string without the `wss://`
+* scheme prefix — the DevTools frontend prepends it automatically.
+*
+* @param wssRelayUrl - Full `wss://` URL of the Chii relay (public tunnel).
+*   Example: `wss://abc.trycloudflare.com`
+* @param panel - Initial panel. Defaults to `"console"`.
+*
+* @example
+* buildChromeDevtoolsUrl('wss://abc.trycloudflare.com')
+* // → 'https://chrome-devtools-frontend.appspot.com/serve_file/@/inspector.html?wss=abc.trycloudflare.com&panel=console'
+*/
+function buildChromeDevtoolsUrl(wssRelayUrl, panel = "console") {
+	const wssParam = wssRelayUrl.replace(/^wss:\/\//i, "");
+	return `${DEVTOOLS_FRONTEND_BASE}?${new URLSearchParams({
+		wss: wssParam,
+		panel
+	}).toString()}`;
+}
+/**
+* Returns `true` when auto-open is **disabled** via the `AIT_AUTO_DEVTOOLS`
+* env var. Only the explicit `"0"` value disables it; anything else (including
+* absent) leaves auto-open enabled.
+*/
+function isAutoDevtoolsDisabled() {
+	return process.env.AIT_AUTO_DEVTOOLS === "0";
+}
+/**
+* Opens the given URL in the OS default browser using a platform-appropriate
+* command. Returns `true` on success.
+*
+* Failures are silent from the caller's perspective — the caller should log
+* the URL to stderr as a fallback before calling this function.
+*/
+function openUrlInBrowser(url) {
+	if (process.env.AIT_AUTO_DEVTOOLS_TEST_SKIP_SPAWN === "1") return false;
+	const { spawnSync } = __require("node:child_process");
+	const platform = process.platform;
+	let candidates;
+	if (platform === "darwin") candidates = [{
+		cmd: "open",
+		args: [url]
+	}];
+	else if (platform === "win32") candidates = [{
+		cmd: "cmd",
+		args: [
+			"/c",
+			"start",
+			"",
+			url
+		]
+	}];
+	else candidates = [
+		{
+			cmd: "xdg-open",
+			args: [url]
+		},
+		{
+			cmd: "sensible-browser",
+			args: [url]
+		},
+		{
+			cmd: "x-www-browser",
+			args: [url]
+		}
+	];
+	for (const { cmd, args } of candidates) try {
+		const result = spawnSync(cmd, args, {
+			encoding: "utf8",
+			timeout: 5e3
+		});
+		if (!result.error && result.status === 0) return true;
+	} catch {}
+	return false;
+}
+/**
+* Manages auto-opening Chrome DevTools exactly once per relay attach session.
+*
+* Create one instance per `runDebugServer` call and pass its `open()` method
+* as the `onFirstAttach` callback to `startAttachWatcher`.
+*
+* The open fires at most once. Subsequent `open()` calls are no-ops.
+* Opt-out and mock-environment guard are checked at call time.
+*/
+var AutoDevtoolsOpener = class {
+	_opened = false;
+	/**
+	* Attempts to auto-open Chrome DevTools.
+	*
+	* No-op when any of the following conditions hold:
+	*   1. Already opened this session (`_opened` is true).
+	*   2. `AIT_AUTO_DEVTOOLS=0` opt-out is set.
+	*   3. Environment is `mock` (env 1 — F12 is already available).
+	*   4. `wssRelayUrl` is null/undefined/empty (tunnel not yet up).
+	*
+	* Always writes the DevTools URL to stderr so the developer can copy it
+	* if the browser open fails or the popup is blocked.
+	*
+	* @param wssRelayUrl - The public `wss://` relay URL (from tunnel status).
+	* @param env - Current MCP environment (`mock` | `relay`).
+	*/
+	open(wssRelayUrl, env) {
+		if (this._opened) return;
+		if (isAutoDevtoolsDisabled()) return;
+		if (env === "mock") return;
+		if (!wssRelayUrl) return;
+		this._opened = true;
+		const devtoolsUrl = buildChromeDevtoolsUrl(wssRelayUrl);
+		process.stderr.write(`[ait-debug] 기기가 연결됐습니다 — Chrome DevTools를 자동으로 엽니다.
+[ait-debug] Chrome DevTools URL: ${devtoolsUrl}\n[ait-debug] (AIT_AUTO_DEVTOOLS=0 으로 자동 열기를 끌 수 있습니다)
+`);
+		if (!openUrlInBrowser(devtoolsUrl)) process.stderr.write("[ait-debug] 브라우저 자동 열기 실패 — 위 URL을 브라우저에서 직접 여세요.\n");
+	}
+	/** Returns `true` if `open()` has passed all guards and fired once. */
+	get opened() {
+		return this._opened;
+	}
+};
+//#endregion
+//#region src/mcp/environment.ts
+/**
+* URL patterns that mark a CDP target as a real-device WebView relay.
+*
+* - `intoss-private://` is the Toss in-app private scheme — only ever observed
+*   inside the real Toss app WebView.
+* - `*.trycloudflare.com` (host suffix) is the cloudflared quick tunnel used as
+*   the relay transport. A target whose URL is on that host is, by construction,
+*   reached over the relay.
+*
+* Pattern-only matches — no specific tunnel host or deploymentId is hard-coded.
+*/
+const RELAY_URL_PATTERNS = [/^intoss-private:\/\//i, /:\/\/[a-z0-9-]+\.trycloudflare\.com(\/|$|:|\?)/i];
+/**
+* Returns true when the URL string looks like a real-device WebView attached
+* over the Chii relay. Used for `getEnvironment()` precedence step 2.
+*/
+function isRelayUrl(url) {
+	if (typeof url !== "string" || url.length === 0) return false;
+	return RELAY_URL_PATTERNS.some((p) => p.test(url));
+}
+/**
+* Test/override hook — when non-null, `getEnvironment()` returns this value
+* regardless of env vars or connection state. Cleared with `null`.
+*/
+let envOverride = null;
+/** Parses the `MCP_ENV` env var into a `McpEnvironment` if valid. */
+function readEnvVar() {
+	const raw = process.env.MCP_ENV;
+	if (raw === "mock" || raw === "relay") return raw;
+}
+/**
+* Returns the current MCP environment, applying the precedence rules:
+*   1. test override (if set)
+*   2. `MCP_ENV` env var
+*   3. CDP target URL pattern match
+*   4. default `mock`
+*/
+function getEnvironment(input = {}) {
+	if (envOverride !== null) return envOverride;
+	const fromEnv = readEnvVar();
+	if (fromEnv !== void 0) return fromEnv;
+	const { connection } = input;
+	if (connection !== void 0) {
+		const targets = connection.listTargets();
+		for (const t of targets) if (isRelayUrl(t.url)) return "relay";
+	}
+	return "mock";
+}
+/**
+* Returns the `EnvironmentReason` that drove the current `getEnvironment()`
+* result. Used by stderr logs and the rejection-reason payload on Tier A/B
+* mismatch errors. SECRET-HANDLING: only stable enum strings — no URL or
+* secret value is ever returned.
+*/
+function getEnvironmentReason(input = {}) {
+	if (envOverride !== null) return envOverride === "mock" ? "env-var-mock" : "env-var-relay";
+	const fromEnv = readEnvVar();
+	if (fromEnv === "mock") return "env-var-mock";
+	if (fromEnv === "relay") return "env-var-relay";
+	const { connection } = input;
+	if (connection !== void 0) {
+		const targets = connection.listTargets();
+		for (const t of targets) if (isRelayUrl(t.url)) return "cdp-target-url-relay-pattern";
+	}
+	return "default-mock";
+}
+//#endregion
 //#region src/mcp/local-connection.ts
 /**
 * Local-browser `CdpConnection` — attaches directly to a Chromium instance
@@ -335,7 +844,7 @@ async function startChiiRelay(options = {}) {
 */
 /** Max events retained per domain ring buffer. */
 const DEFAULT_BUFFER_SIZE = 500;
-function isObject$1(value) {
+function isObject$2(value) {
 	return typeof value === "object" && value !== null;
 }
 function parseInbound(raw) {
@@ -345,13 +854,13 @@ function parseInbound(raw) {
 	} catch {
 		return null;
 	}
-	if (!isObject$1(parsed)) 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$1(parsed.error) && typeof parsed.error.message === "string") message.error = { message: parsed.error.message };
+	if (isObject$2(parsed.error) && typeof parsed.error.message === "string") message.error = { message: parsed.error.message };
 	return message;
 }
 const PHASE_1_EVENTS = [
@@ -404,7 +913,7 @@ var LocalCdpConnection = class {
 		this.targets.clear();
 		let selected = null;
 		for (const item of list) {
-			if (!isObject$1(item) || typeof item.id !== "string") continue;
+			if (!isObject$2(item) || typeof item.id !== "string") continue;
 			const cdpTarget = {
 				id: item.id,
 				title: typeof item.title === "string" ? item.title : "",
@@ -816,6 +1325,145 @@ function buildAttachHtml(qrDataUrl, safeLabel, safeAttachUrl) {
 </html>`;
 }
 //#endregion
+//#region src/mcp/server-lock.ts
+/**
+* Single debug session lock for the `devtools-mcp` debug server.
+*
+* At most one debug server process should run on a given machine at a time —
+* multiple concurrent instances create duplicate cloudflared tunnels, waste
+* resources, and confuse the user about which wssUrl to use.
+*
+* ## Lock file
+*
+* Location: `~/.ait-devtools/server.lock`
+*
+* Schema (JSON):
+* ```json
+* { "pid": 12345, "wssUrl": "wss://xxx.trycloudflare.com", "startedAt": "2026-01-01T00:00:00.000Z" }
+* ```
+*
+* ## Behaviour
+*
+* - **Acquire**: write PID + wssUrl + startedAt. Returns a `release()` handle.
+* - **Stale lock recovery**: if the stored PID is no longer alive
+*   (`process.kill(pid, 0)` throws ESRCH), the lock is silently replaced.
+* - **Live conflict (option B)**: if the stored PID is alive, `acquireLock`
+*   throws `ServerLockConflictError` with the existing PID and wssUrl so the
+*   caller can surface a clear message to the agent.
+* - **Release**: remove the lock file. Called on graceful shutdown (SIGINT /
+*   SIGTERM / SIGHUP). SIGKILL survivors leave a stale file — the next startup
+*   recovers it automatically via the alive check.
+*
+* ## wssUrl update
+*
+* The lock is written before cloudflared starts, so `wssUrl` begins as `null`
+* and is updated in place once the tunnel URL is known via `updateWssUrl`.
+*
+* Node-only.
+*/
+/** Thrown when a live server process already holds the lock. */
+var ServerLockConflictError = class extends Error {
+	/** PID of the existing server process. */
+	existingPid;
+	/** wssUrl from the existing lock — may be `null` if the tunnel is still starting. */
+	existingWssUrl;
+	constructor(existingPid, existingWssUrl) {
+		const urlNote = existingWssUrl != null ? `  relay URL: ${existingWssUrl}\n` : "  relay URL: (tunnel still starting — retry in a moment)\n";
+		super(`A debug server is already running (PID ${existingPid}).\n` + urlNote + `Stop the existing session before starting a new one.
+If it is already stopped but this error persists, remove the lock file:
+  rm "${lockFilePath()}"`);
+		this.name = "ServerLockConflictError";
+		this.existingPid = existingPid;
+		this.existingWssUrl = existingWssUrl;
+	}
+};
+/** Returns `~/.ait-devtools/server.lock` (or `AIT_DEVTOOLS_LOCK_DIR` override for tests). */
+function lockFilePath() {
+	return join(process.env.AIT_DEVTOOLS_LOCK_DIR ?? join(homedir(), ".ait-devtools"), "server.lock");
+}
+function ensureLockDir(lockPath) {
+	mkdirSync(join(lockPath, ".."), { recursive: true });
+}
+/**
+* Returns `true` when the given PID refers to a running process.
+*
+* Uses `process.kill(pid, 0)` — a no-op signal that succeeds when the process
+* exists and we have permission to signal it; throws ESRCH when it doesn't exist.
+*/
+function isPidAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		if (err.code === "EPERM") return true;
+		return false;
+	}
+}
+function readLock(lockPath) {
+	if (!existsSync(lockPath)) return null;
+	try {
+		const raw = readFileSync(lockPath, "utf8");
+		const parsed = JSON.parse(raw);
+		if (typeof parsed === "object" && parsed !== null && "pid" in parsed && typeof parsed.pid === "number" && "startedAt" in parsed && typeof parsed.startedAt === "string") {
+			const p = parsed;
+			return {
+				pid: p.pid,
+				wssUrl: typeof p.wssUrl === "string" ? p.wssUrl : null,
+				startedAt: p.startedAt
+			};
+		}
+		return null;
+	} catch {
+		return null;
+	}
+}
+function writeLock(lockPath, data) {
+	ensureLockDir(lockPath);
+	writeFileSync(lockPath, JSON.stringify(data, null, 2), { encoding: "utf8" });
+}
+function removeLock(lockPath) {
+	try {
+		rmSync(lockPath);
+	} catch {}
+}
+/**
+* Attempts to acquire the server lock.
+*
+* - If no lock exists (or the lock is stale): writes a new lock and returns a
+*   `LockHandle` with `updateWssUrl` + `release`.
+* - If a live process holds the lock: throws `ServerLockConflictError`.
+*
+* The initial `wssUrl` in the lock file is `null` — call
+* `handle.updateWssUrl(url)` once the cloudflared tunnel is ready.
+*/
+function acquireLock() {
+	const lockPath = lockFilePath();
+	const existing = readLock(lockPath);
+	if (existing !== null) {
+		if (isPidAlive(existing.pid)) throw new ServerLockConflictError(existing.pid, existing.wssUrl);
+		process.stderr.write(`[ait-debug] stale lock from PID ${existing.pid} recovered — starting fresh.\n`);
+	}
+	const data = {
+		pid: process.pid,
+		wssUrl: null,
+		startedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	writeLock(lockPath, data);
+	let released = false;
+	return {
+		updateWssUrl(wssUrl) {
+			if (released) return;
+			data.wssUrl = wssUrl;
+			writeLock(lockPath, data);
+		},
+		release() {
+			if (released) return;
+			released = true;
+			removeLock(lockPath);
+		}
+	};
+}
+//#endregion
 //#region src/mcp/deeplink.ts
 /**
 * Build a self-attaching dogfood deep link.
@@ -928,6 +1576,162 @@ function buildDeepLinkAttachUrl(schemeUrl, wssUrl, totpCode) {
 	return `${base}?${query}${hash}`;
 }
 //#endregion
+//#region src/mcp/sdk-signatures.ts
+function isObject$1(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function describeArgs(args) {
+	try {
+		return JSON.stringify(args);
+	} catch {
+		return String(args);
+	}
+}
+/**
+* 등록된 메서드 목록.
+*
+* 시그니처 출처 확인:
+*   - 함수가 인자를 받지 않으면 args[0] 없음 → `args.length === 0`을 체크하지 않고
+*     그냥 통과시킨다(args 무시하는 stub가 많아서 noArgs 체크가 noise).
+*   - 실 SDK 시그니처는 `src/__typecheck.ts`의 `Assert<Mock, Original>` 줄로 보장.
+*/
+const SIGNATURES = [
+	{
+		name: "setDeviceOrientation",
+		validateArgs(args) {
+			const arg = args[0];
+			if (!isObject$1(arg)) return {
+				ok: false,
+				expected: "{ type: 'portrait' | 'landscape' }",
+				received: describeArgs(args)
+			};
+			const type = arg.type;
+			if (type !== "portrait" && type !== "landscape") return {
+				ok: false,
+				expected: "{ type: 'portrait' | 'landscape' }",
+				received: describeArgs(args)
+			};
+			return { ok: true };
+		},
+		example: "call_sdk('setDeviceOrientation', [{ type: 'landscape' }])"
+	},
+	{
+		name: "setIosSwipeGestureEnabled",
+		validateArgs(args) {
+			const arg = args[0];
+			if (!isObject$1(arg) || typeof arg.isEnabled !== "boolean") return {
+				ok: false,
+				expected: "{ isEnabled: boolean }",
+				received: describeArgs(args)
+			};
+			return { ok: true };
+		},
+		example: "call_sdk('setIosSwipeGestureEnabled', [{ isEnabled: false }])"
+	},
+	{
+		name: "setSecureScreen",
+		validateArgs(args) {
+			const arg = args[0];
+			if (!isObject$1(arg) || typeof arg.enabled !== "boolean") return {
+				ok: false,
+				expected: "{ enabled: boolean }",
+				received: describeArgs(args)
+			};
+			return { ok: true };
+		},
+		example: "call_sdk('setSecureScreen', [{ enabled: true }])"
+	},
+	{
+		name: "setScreenAwakeMode",
+		validateArgs(args) {
+			const arg = args[0];
+			if (!isObject$1(arg) || typeof arg.enabled !== "boolean") return {
+				ok: false,
+				expected: "{ enabled: boolean }",
+				received: describeArgs(args)
+			};
+			return { ok: true };
+		},
+		example: "call_sdk('setScreenAwakeMode', [{ enabled: true }])"
+	},
+	{
+		name: "getOperationalEnvironment",
+		validateArgs(_args) {
+			return { ok: true };
+		},
+		example: "call_sdk('getOperationalEnvironment', [])"
+	},
+	{
+		name: "getPlatformOS",
+		validateArgs(_args) {
+			return { ok: true };
+		},
+		example: "call_sdk('getPlatformOS', [])"
+	},
+	{
+		name: "getDeviceId",
+		validateArgs(_args) {
+			return { ok: true };
+		},
+		example: "call_sdk('getDeviceId', [])"
+	},
+	{
+		name: "getLocale",
+		validateArgs(_args) {
+			return { ok: true };
+		},
+		example: "call_sdk('getLocale', [])"
+	},
+	{
+		name: "getNetworkStatus",
+		validateArgs(_args) {
+			return { ok: true };
+		},
+		example: "call_sdk('getNetworkStatus', [])"
+	},
+	{
+		name: "getSchemeUri",
+		validateArgs(_args) {
+			return { ok: true };
+		},
+		example: "call_sdk('getSchemeUri', [])"
+	},
+	{
+		name: "requestReview",
+		validateArgs(_args) {
+			return { ok: true };
+		},
+		example: "call_sdk('requestReview', [])"
+	},
+	{
+		name: "closeView",
+		validateArgs(_args) {
+			return { ok: true };
+		},
+		example: "call_sdk('closeView', [])"
+	}
+];
+const SIGNATURE_MAP = new Map(SIGNATURES.map((s) => [s.name, s]));
+/** 세션 내 passthrough 경고를 한 번만 emit하기 위한 Set */
+const _warnedPassthrough = /* @__PURE__ */ new Set();
+/**
+* 메서드 이름으로 시그니처를 조회한다.
+* 등록된 메서드이면 `SdkSignature`를 반환하고, 미등록이면 `undefined`.
+*/
+function lookupSignature(name) {
+	return SIGNATURE_MAP.get(name);
+}
+/**
+* 미등록 메서드에 대해 stderr에 passthrough 경고를 1회 출력한다.
+* 세션 내 동일 메서드 이름은 최초 1회만 출력.
+*/
+function warnPassthrough(name) {
+	if (_warnedPassthrough.has(name)) return;
+	_warnedPassthrough.add(name);
+	process.stderr.write(`[ait-debug] call_sdk: "${name}" 시그니처가 등록되지 않음 — passthrough\n`);
+}
+SIGNATURES.map((s) => s.name);
+//#endregion
 //#region src/mcp/tools.ts
 /** Static MCP tool descriptors (name + JSONSchema) for the full debug tool surface. */
 const DEBUG_TOOL_DEFINITIONS = [
@@ -938,7 +1742,8 @@ const DEBUG_TOOL_DEFINITIONS = [
 			type: "object",
 			properties: {},
 			required: []
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "list_network_requests",
@@ -947,16 +1752,18 @@ const DEBUG_TOOL_DEFINITIONS = [
 			type: "object",
 			properties: {},
 			required: []
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "list_pages",
-		description: "Lists the mini-app page(s) the Chii relay currently sees attached, plus whether the cloudflared tunnel is up and the public wss relay URL the phone uses to attach. Call this first to confirm a page is attached before reading console/network.",
+		description: "Returns the single active page (at most one) the relay sees attached. When a second page attaches, the previous one is evicted (last-attach wins — single-attach model). The result includes `singleAttachModel: true` so the agent knows the array is always 0 or 1 entries. Also returns whether the cloudflared tunnel is up and the public wss relay URL. Each page entry includes a `lastSeenAt` ISO timestamp (last inbound CDP message from that target — useful to detect stale entries when the phone app backgrounded). The result also includes `crashDetectedAt` (ISO timestamp or null): when non-null, a page crash was detected via Inspector.targetCrashed / Target.targetDestroyed since the last attach, the pages list will be empty, and `crashWarning` shows a Korean hint to re-attach. Call this first to confirm a page is attached before reading console/network.",
 		inputSchema: {
 			type: "object",
 			properties: {},
 			required: []
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "build_attach_url",
@@ -978,7 +1785,8 @@ const DEBUG_TOOL_DEFINITIONS = [
 				}
 			},
 			required: ["scheme_url"]
-		}
+		},
+		availableIn: "relay"
 	},
 	{
 		name: "get_dom_document",
@@ -987,7 +1795,8 @@ const DEBUG_TOOL_DEFINITIONS = [
 			type: "object",
 			properties: {},
 			required: []
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "take_snapshot",
@@ -996,7 +1805,8 @@ const DEBUG_TOOL_DEFINITIONS = [
 			type: "object",
 			properties: {},
 			required: []
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "take_screenshot",
@@ -1005,16 +1815,18 @@ const DEBUG_TOOL_DEFINITIONS = [
 			type: "object",
 			properties: {},
 			required: []
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "measure_safe_area",
-		description: "Runs a safe-area probe on the attached mini-app page via Runtime.evaluate and returns normalized safe-area insets, viewport geometry, device pixel ratio, and User-Agent. Read-only — does not modify page state. Use in a relay session (phone attached) to get ground-truth values for upgrading a viewport preset from extrapolated/placeholder to measured. Requires the relay to be attached — call list_pages first.",
+		description: "Runs a safe-area probe on the attached mini-app page via Runtime.evaluate and returns normalized safe-area insets, viewport geometry, device pixel ratio, and User-Agent. Read-only — does not modify page state. Tier C per RFC #277: the same Runtime.evaluate probe runs in both `mock` (devtools panel page with window.__ait state) and `relay` (real-device WebView with window.__sdk). The result includes a `source: \"mock\" | \"relay\"` field so consumers can identify provenance without inspecting payload values. Use in a relay session (phone attached) to get ground-truth values for upgrading a viewport preset from extrapolated/placeholder to measured. Requires a page to be attached — call list_pages first.",
 		inputSchema: {
 			type: "object",
 			properties: {},
 			required: []
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "evaluate",
@@ -1026,11 +1838,25 @@ const DEBUG_TOOL_DEFINITIONS = [
 				description: "JavaScript expression to evaluate in the page context."
 			} },
 			required: ["expression"]
-		}
+		},
+		availableIn: "both"
+	},
+	{
+		name: "list_exceptions",
+		description: "Lists JS-level exceptions captured via `Runtime.exceptionThrown` from the relay attached page. Includes timestamp, exception text, source URL/line, and stack trace. Use to root-cause SDK throws that may precede a Toss app crash (#265 / #267). The buffer holds up to 50 most recent exceptions and survives target replaced/crashed/destroyed events so an exception just before a crash is preserved. Returns up to 50 most recent by default.",
+		inputSchema: {
+			type: "object",
+			properties: { limit: {
+				type: "number",
+				description: "Maximum number of exceptions to return (default 50, max 50)."
+			} },
+			required: []
+		},
+		availableIn: "both"
 	},
 	{
 		name: "call_sdk",
-		description: "Calls a dogfood SDK method via the window.__sdkCall bridge (exported by @apps-in-toss/web-framework only in __DEBUG_BUILD__ bundles). NOT read-only — SDK calls have side effects (navigation, payments, permissions, etc.). On env 2/3 (real device relay) this hits the real SDK; on env 1 (local mock) it hits the mock SDK. Requires the relay to be attached — call list_pages first. Returns {ok: true, value} on success or {ok: false, error} on failure. Returns a clear error if window.__sdkCall is not available (non-dogfood bundle).",
+		description: "Calls a dogfood SDK method via the window.__sdkCall bridge (exported by @apps-in-toss/web-framework only in __DEBUG_BUILD__ bundles). NOT read-only — SDK calls have side effects (navigation, payments, permissions, etc.). On env 2/3 (real device relay) this hits the real SDK; on env 1 (local mock) it hits the mock SDK. Requires the relay to be attached — call list_pages first. Returns {ok: true, value} on success or {ok: false, error} on failure. If a Runtime.exceptionThrown event was observed within [callStart-50ms, callEnd+200ms], the result also includes `recentException` for crash triage. Returns a clear error if window.__sdkCall is not available (non-dogfood bundle).\n\nIMPORTANT — 인자 시그니처 (잘못된 인자로 호출하면 토스 앱 crash 위험):\n  setDeviceOrientation:        call_sdk(\"setDeviceOrientation\", [{ type: \"landscape\" }])  // NOT \"landscape\"\n  setIosSwipeGestureEnabled:   call_sdk(\"setIosSwipeGestureEnabled\", [{ isEnabled: false }])\n  setSecureScreen:             call_sdk(\"setSecureScreen\", [{ enabled: true }])\n  setScreenAwakeMode:          call_sdk(\"setScreenAwakeMode\", [{ enabled: true }])\n  getOperationalEnvironment:   call_sdk(\"getOperationalEnvironment\", [])\n  getPlatformOS:               call_sdk(\"getPlatformOS\", [])\n  getDeviceId:                 call_sdk(\"getDeviceId\", [])\n  getLocale:                   call_sdk(\"getLocale\", [])\n  getNetworkStatus:            call_sdk(\"getNetworkStatus\", [])\n  getSchemeUri:                call_sdk(\"getSchemeUri\", [])\n  requestReview:               call_sdk(\"requestReview\", [])\n  closeView:                   call_sdk(\"closeView\", [])",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -1045,7 +1871,8 @@ const DEBUG_TOOL_DEFINITIONS = [
 				}
 			},
 			required: ["name"]
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "AIT.getSdkCallHistory",
@@ -1054,7 +1881,8 @@ const DEBUG_TOOL_DEFINITIONS = [
 			type: "object",
 			properties: {},
 			required: []
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "AIT.getMockState",
@@ -1063,7 +1891,8 @@ const DEBUG_TOOL_DEFINITIONS = [
 			type: "object",
 			properties: {},
 			required: []
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "AIT.getOperationalEnvironment",
@@ -1072,7 +1901,8 @@ const DEBUG_TOOL_DEFINITIONS = [
 			type: "object",
 			properties: {},
 			required: []
-		}
+		},
+		availableIn: "both"
 	}
 ];
 const DEBUG_TOOL_NAMES = new Set(DEBUG_TOOL_DEFINITIONS.map((t) => t.name));
@@ -1080,6 +1910,34 @@ function isDebugToolName(name) {
 	return DEBUG_TOOL_NAMES.has(name);
 }
 /**
+* Returns the `ToolAvailability` declared on a registered debug tool, or
+* `undefined` when the name is not a known debug tool. Used by the tool
+* registry to filter `tools/list` by current env and by the call handler to
+* reject env-mismatch invocations.
+*/
+function getToolAvailability(name) {
+	for (const t of DEBUG_TOOL_DEFINITIONS) if (t.name === name) return t.availableIn;
+}
+/**
+* Returns true when the named tool is available in the given environment.
+* Unknown tools return `false` — callers should reject them as unknown rather
+* than as env-mismatched.
+*/
+function isToolAvailableIn(name, env) {
+	const availability = getToolAvailability(name);
+	if (availability === void 0) return false;
+	if (availability === "both") return true;
+	return availability === env;
+}
+/**
+* Filters a `DEBUG_TOOL_DEFINITIONS`-shaped list to those whose `availableIn`
+* matches the given env. Pure — preserves order; both Tier C ("both") and the
+* matching single-env tier pass through.
+*/
+function filterToolsByEnvironment(tools, env) {
+	return tools.filter((t) => t.availableIn === "both" || t.availableIn === env);
+}
+/**
 * Tool names that are available before any page attaches (bootstrap tier).
 *
 * `build_attach_url` — pure URL synthesis, no attach needed.
@@ -1133,10 +1991,58 @@ function listNetworkRequests(connection) {
 		};
 	});
 }
+/** Formats a single CDP call frame into `at fn (url:line:col)`. */
+function formatCallFrame(frame) {
+	return `at ${frame.functionName || "(anonymous)"} (${frame.url}:${frame.lineNumber}:${frame.columnNumber})`;
+}
+/** Normalizes a raw `Runtime.exceptionThrown` event into a `BufferedException`. */
+function normalizeException(event) {
+	const { timestamp, exceptionDetails } = event;
+	const frames = exceptionDetails.stackTrace?.callFrames;
+	const stack = frames && frames.length > 0 ? frames.map(formatCallFrame).join("\n") : void 0;
+	const exceptionText = exceptionDetails.exception?.description ?? void 0;
+	const result = {
+		timestamp,
+		text: exceptionDetails.text,
+		raw: event
+	};
+	if (exceptionDetails.url !== void 0) result.url = exceptionDetails.url;
+	if (exceptionDetails.lineNumber !== void 0) result.lineNumber = exceptionDetails.lineNumber;
+	if (exceptionDetails.columnNumber !== void 0) result.columnNumber = exceptionDetails.columnNumber;
+	if (exceptionText !== void 0) result.exceptionText = exceptionText;
+	if (stack !== void 0) result.stack = stack;
+	return result;
+}
+/**
+* Returns the most recent buffered `Runtime.exceptionThrown` events, normalized.
+* Oldest-first; limited to `limit` entries (default 50, max 50).
+*/
+function listExceptions(connection, limit = 50) {
+	const cap = Math.min(Math.max(1, limit), 50);
+	const events = connection.getBufferedEvents("Runtime.exceptionThrown");
+	return (events.length > cap ? events.slice(events.length - cap) : events).map((e) => normalizeException(e));
+}
+function isCrashAware(conn) {
+	return typeof conn.getLastCrashDetectedAt === "function" && typeof conn.getTargetLastSeenAt === "function";
+}
 function listPages(connection, tunnel) {
+	const pages = connection.listTargets().map((t) => {
+		const lastSeenMs = isCrashAware(connection) ? connection.getTargetLastSeenAt(t.id) : null;
+		return {
+			id: t.id,
+			title: t.title,
+			url: t.url,
+			lastSeenAt: lastSeenMs !== null ? new Date(lastSeenMs).toISOString() : null
+		};
+	});
+	const crashMs = isCrashAware(connection) ? connection.getLastCrashDetectedAt() : null;
+	const crashDetectedAt = crashMs !== null ? new Date(crashMs).toISOString() : null;
 	return {
-		pages: connection.listTargets(),
-		tunnel
+		pages,
+		tunnel,
+		crashDetectedAt,
+		crashWarning: crashDetectedAt ? `[ait-debug] page crash 감지됨 — 새 attach 필요 (관측 시각: ${crashDetectedAt})` : null,
+		singleAttachModel: true
 	};
 }
 /**
@@ -1332,11 +2238,13 @@ async function takeScreenshot(connection) {
 * The JS probe injected via `Runtime.evaluate`. It reads:
 *   1. `env(safe-area-inset-*)` via a temporary element with padding set to
 *      those CSS env vars, then `getComputedStyle`.
-*   2. `window.__sdk.SafeAreaInsets.get()` (1st priority) or
-*      `window.__sdk.getSafeAreaInsets()` (2nd priority) — both surfaces
-*      confirmed live on iPhone 15 Pro relay. `window.__sdk` is only present
-*      in dogfood (__DEBUG_BUILD__) bundles; outside those it is undefined.
-*      If both paths fail the result carries `sdkInsetsError` explaining why.
+*   2. SDK insets via a priority chain so the SAME probe works on both relay
+*      (real device) and mock (devtools panel page):
+*        a. `window.__sdk.SafeAreaInsets.get()`  — dogfood bundle on real device.
+*        b. `window.__sdk.getSafeAreaInsets()`   — dogfood bundle (deprecated).
+*        c. `window.__ait.state.safeAreaInsets`  — devtools mock state (mock env).
+*      The probe records `sdkInsetsSource` = `'window.__sdk'` | `'window.__ait'`
+*      | `null`. If all paths fail the result carries `sdkInsetsError`.
 *   3. nav bar geometry: the SDK does not expose navBar height as a standalone
 *      API — `.ait-navbar` DOM height is read as a cross-check, and
 *      `navBarHeightSource` records where it came from.
@@ -1344,9 +2252,15 @@ async function takeScreenshot(connection) {
 *
 * Returns a plain JSON-serialisable object so `returnByValue: true` works.
 *
-* NOTE: This expression is evaluated in the page context on the real device.
-* It does not mutate any page state — the temporary element is removed after
-* reading. No secret or auth token is read or returned.
+* NOTE: This expression is evaluated in the page context — on the real device
+* (relay) or on the mock panel page. It does not mutate any page state — the
+* temporary element is removed after reading. No secret or auth token is read
+* or returned.
+*
+* RFC #277 Tier C parity: the SAME probe string runs in both envs. Mock fidelity
+* comes from the panel's `applyViewport` / `computeSafeAreaInsets` correctly
+* setting `window.__ait.state.safeAreaInsets` (#275). When that is correct,
+* the cssEnv + sdkInsets pair returned here matches the relay's shape.
 */
 const SAFE_AREA_PROBE_EXPRESSION = `
 (function() {
@@ -1366,17 +2280,28 @@ const SAFE_AREA_PROBE_EXPRESSION = `
   };
   document.documentElement.removeChild(el);
   var sdkInsets = null;
+  var sdkInsetsSource = null;
   var sdkInsetsError = undefined;
   try {
     var sdk = window.__sdk;
+    var ait = window.__ait;
     if (sdk && sdk.SafeAreaInsets && typeof sdk.SafeAreaInsets.get === 'function') {
       sdkInsets = sdk.SafeAreaInsets.get();
+      sdkInsetsSource = 'window.__sdk';
     } else if (sdk && typeof sdk.getSafeAreaInsets === 'function') {
       sdkInsets = sdk.getSafeAreaInsets();
-    } else if (!sdk) {
-      sdkInsetsError = 'window.__sdk not available (non-dogfood bundle)';
-    } else {
+      sdkInsetsSource = 'window.__sdk';
+    } else if (ait && ait.state && ait.state.safeAreaInsets &&
+               typeof ait.state.safeAreaInsets.top === 'number') {
+      var s = ait.state.safeAreaInsets;
+      sdkInsets = { top: s.top, bottom: s.bottom, left: s.left, right: s.right };
+      sdkInsetsSource = 'window.__ait';
+    } else if (!sdk && !ait) {
+      sdkInsetsError = 'neither window.__sdk (relay) nor window.__ait (mock) available';
+    } else if (sdk) {
       sdkInsetsError = 'neither SafeAreaInsets.get nor getSafeAreaInsets found on window.__sdk';
+    } else {
+      sdkInsetsError = 'window.__ait.state.safeAreaInsets is missing or malformed';
     }
   } catch(e) {
     sdkInsetsError = String(e && e.message || e);
@@ -1393,6 +2318,7 @@ const SAFE_AREA_PROBE_EXPRESSION = `
   var result = {
     cssEnv: cssEnv,
     sdkInsets: sdkInsets,
+    sdkInsetsSource: sdkInsetsSource,
     navBarHeight: navBarHeight,
     navBarHeightSource: navBarHeightSource,
     innerWidth: window.innerWidth,
@@ -1409,9 +2335,11 @@ const SAFE_AREA_PROBE_EXPRESSION = `
 * The probe returns a JSON string (because `returnByValue:true` with a plain
 * object works unreliably across Chii relay versions — stringifying is safer).
 *
+* `source` is supplied by the caller (`measureSafeArea`) from the env SSoT.
+*
 * Throws if the result is missing, contains an exception, or cannot be parsed.
 */
-function normalizeSafeAreaResult(rawValue) {
+function normalizeSafeAreaResult(rawValue, source) {
 	if (typeof rawValue !== "string") throw new Error(`measure_safe_area: probe returned unexpected type "${typeof rawValue}" — expected JSON string`);
 	let parsed;
 	try {
@@ -1440,6 +2368,7 @@ function normalizeSafeAreaResult(rawValue) {
 		left: 0
 	};
 	const sdkInsets = requireInsets("sdkInsets");
+	const sdkInsetsSource = obj.sdkInsetsSource === "window.__sdk" || obj.sdkInsetsSource === "window.__ait" ? obj.sdkInsetsSource : null;
 	const sdkInsetsError = typeof obj.sdkInsetsError === "string" ? obj.sdkInsetsError : void 0;
 	const navBarHeight = typeof obj.navBarHeight === "number" ? obj.navBarHeight : null;
 	const navBarHeightSource = typeof obj.navBarHeightSource === "string" ? obj.navBarHeightSource : "not-exposed-by-sdk";
@@ -1448,8 +2377,10 @@ function normalizeSafeAreaResult(rawValue) {
 	const devicePixelRatio = typeof obj.devicePixelRatio === "number" ? obj.devicePixelRatio : 1;
 	const userAgent = typeof obj.userAgent === "string" ? obj.userAgent : "";
 	return {
+		source,
 		cssEnv,
 		sdkInsets,
+		sdkInsetsSource,
 		...sdkInsetsError !== void 0 ? { sdkInsetsError } : {},
 		navBarHeight,
 		navBarHeightSource,
@@ -1463,9 +2394,16 @@ function normalizeSafeAreaResult(rawValue) {
 * Runs the safe-area probe on the attached page and returns a normalized
 * `SafeAreaMeasurement`. Read-only — does not mutate page state.
 *
+* `source` is supplied by the caller from the env detection SSoT (see
+* `src/mcp/environment.ts`). The same `Runtime.evaluate` call runs in both
+* envs — the probe expression tries `window.__sdk` first (relay) then
+* `window.__ait` (mock), so mock fidelity is enforced by the panel's
+* `applyViewport`/`computeSafeAreaInsets` keeping `__ait.state.safeAreaInsets`
+* correct (RFC #277 Tier C parity, #275 model).
+*
 * Throws on CDP error, probe exception, or result parse failure.
 */
-async function measureSafeArea(connection) {
+async function measureSafeArea(connection, source) {
 	const result = await connection.send("Runtime.evaluate", {
 		expression: SAFE_AREA_PROBE_EXPRESSION,
 		returnByValue: true,
@@ -1475,7 +2413,7 @@ async function measureSafeArea(connection) {
 		const msg = result.exceptionDetails.exception?.description ?? result.exceptionDetails.text ?? "Runtime.evaluate threw an exception";
 		throw new Error(`measure_safe_area: probe threw — ${msg}`);
 	}
-	return normalizeSafeAreaResult(result.result.value);
+	return normalizeSafeAreaResult(result.result.value, source);
 }
 /**
 * Evaluates an arbitrary JS expression on the attached page via
@@ -1542,29 +2480,73 @@ function normalizeCallSdkResult(rawValue) {
 	throw new Error("call_sdk: bridge result missing \"ok\" field");
 }
 /**
+* Looks up the most recent exception from the buffer that falls within the
+* triage window [windowStart, windowEnd]. Returns `undefined` if none found.
+*
+* The heuristic window is:
+*   - windowStart = callStart - 50ms  (catch sync throws before bridge fires)
+*   - windowEnd   = callEnd + 200ms   (catch async throws resolved soon after)
+*
+* Only the most recent exception within the window is returned (the one most
+* likely to be causally related to the SDK call).
+*/
+function findRecentException(connection, windowStart, windowEnd) {
+	const events = connection.getBufferedEvents("Runtime.exceptionThrown");
+	for (let i = events.length - 1; i >= 0; i--) {
+		const e = events[i];
+		if (e.timestamp >= windowStart && e.timestamp <= windowEnd) return normalizeException(e);
+	}
+}
+/**
 * Calls a dogfood SDK method via `window.__sdkCall` on the attached page.
 * NOT read-only — SDK calls may have side effects.
 *
 * On env 2/3 (real device relay) this hits the real SDK; on env 1 (local
 * mock) it hits the mock SDK.
 *
+* 인자 시그니처 검증: 등록된 메서드는 bridge 호출 전에 인자를 검증하고, mismatch면
+* `{ok:false, error}` MCP 오류 결과를 반환한다(bridge에 도달하지 않음).
+* 미등록 메서드는 passthrough + stderr 경고 1회.
+*
 * Throws on CDP error or result parse failure. Returns `{ok:false, error}`
-* for bridge-level errors (method not found, SDK threw, bridge absent).
+* for bridge-level errors (method not found, SDK threw, bridge absent) or
+* argument schema violations.
+*
+* If a `Runtime.exceptionThrown` event was observed within the triage window
+* [callStart-50ms, callEnd+200ms], the result includes `recentException` for
+* crash triage. This window is a heuristic — it catches the common case of an
+* SDK throw immediately before/after the bridge resolves.
 *
 * SECRET-HANDLING: name, args, and the result value are NOT written to any log.
 */
 async function callSdk(connection, name, args) {
+	const signature = lookupSignature(name);
+	if (signature !== void 0) {
+		const validation = signature.validateArgs(args);
+		if (!validation.ok) return {
+			ok: false,
+			error: `call_sdk("${name}") 인자 시그니처 오류.\n받음: ${validation.received}\n기대: ${validation.expected}\n올바른 예시: ${signature.example}`
+		};
+	} else warnPassthrough(name);
+	const callStart = Date.now();
 	const expression = buildCallSdkExpression(name, args);
 	const result = await connection.send("Runtime.evaluate", {
 		expression,
 		returnByValue: true,
 		awaitPromise: true
 	});
+	const callEnd = Date.now();
 	if (result.exceptionDetails) {
 		const msg = result.exceptionDetails.exception?.description ?? result.exceptionDetails.text ?? "Runtime.evaluate threw an exception";
 		throw new Error(`call_sdk threw: ${msg}`);
 	}
-	return normalizeCallSdkResult(result.result.value);
+	const sdkResult = normalizeCallSdkResult(result.result.value);
+	const recentException = findRecentException(connection, callStart - 50, callEnd + 200);
+	if (recentException !== void 0) return {
+		...sdkResult,
+		recentException
+	};
+	return sdkResult;
 }
 /** Set of tool names served by the AIT source rather than the CDP connection. */
 const AIT_TOOL_NAMES = new Set([
@@ -1846,6 +2828,65 @@ async function printAttachBanner(input) {
 * Node-only.
 */
 /**
+* Parses `_deploymentId` from the query string of a scheme URL.
+*
+* Returns `null` when the param is absent or empty — callers treat that as
+* "no deploymentId filter; match on presence only" and fall back to the
+* original `attachedPages.length > 0` condition.
+*
+* SECRET-HANDLING: deploymentId is a public identifier and may appear in
+* debug output. Never confuse it with TOTP secrets or relay tunnel URLs.
+*/
+function extractDeploymentId(schemeUrl) {
+	try {
+		const qIndex = schemeUrl.indexOf("?");
+		if (qIndex === -1) return null;
+		const id = new URLSearchParams(schemeUrl.slice(qIndex + 1)).get("_deploymentId");
+		return id && id.length > 0 ? id : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Waits for the first target matching `filterFn` to attach, using the
+* event-driven `waitForFirstTarget()` on `ChiiCdpConnection` instances, or
+* falling back to a polling loop for generic `CdpConnection` fakes (tests).
+*
+* This eliminates the polling-only race that previously caused `wait_for_attach`
+* to resolve before the relay had observed the first inbound CDP message from
+* the phone.
+*
+* @param connection - The CDP connection (production or fake).
+* @param filterFn   - Resolves when this predicate is satisfied.
+* @param timeoutMs  - Maximum wait time in ms.
+* @param pollIntervalMs - Fallback poll interval for non-ChiiCdpConnection.
+*/
+function waitForAttachWithEvents(connection, filterFn, timeoutMs, pollIntervalMs = 1e3) {
+	if (connection instanceof ChiiCdpConnection) return connection.waitForFirstTarget(filterFn, timeoutMs, pollIntervalMs);
+	return new Promise((resolve, reject) => {
+		const deadline = Date.now() + timeoutMs;
+		let settled = false;
+		const poll = setInterval(() => {
+			const targets = connection.listTargets();
+			if (filterFn(targets)) {
+				settled = true;
+				clearInterval(poll);
+				resolve(targets);
+			} else if (Date.now() >= deadline) {
+				settled = true;
+				clearInterval(poll);
+				reject(/* @__PURE__ */ new Error(`waitForAttachWithEvents: 타임아웃 (${timeoutMs}ms)`));
+			}
+		}, pollIntervalMs);
+		const targets = connection.listTargets();
+		if (!settled && filterFn(targets)) {
+			settled = true;
+			clearInterval(poll);
+			resolve(targets);
+		}
+	});
+}
+/**
 * Builds the debug-mode MCP server around an injected CDP connection + AIT
 * source + tunnel status getter. Pure wiring — does not start a relay or
 * tunnel, which is what makes the tool surface unit-testable.
@@ -1858,13 +2899,18 @@ async function printAttachBanner(input) {
 * naturally via `enableDomains`). The tier only controls visibility.
 */
 function createDebugServer(deps) {
-	const { connection, aitSource, getTunnelStatus, waitForAttachTimeoutMs = 9e4, qrHttpServer } = deps;
+	const { connection, aitSource, getTunnelStatus, waitForAttachTimeoutMs = 9e4, qrHttpServer, getEnvironment: getEnvDep, getEnvironmentReason: getEnvReasonDep } = deps;
+	const resolveEnvironment = getEnvDep ?? (() => getEnvironment({ connection }));
+	const resolveEnvironmentReason = getEnvReasonDep ?? (() => getEnvironmentReason({ connection }));
 	const server = new Server({
 		name: "ait-debug",
-		version: "0.1.40"
+		version: "0.1.43"
 	}, { capabilities: { tools: { listChanged: true } } });
 	server.setRequestHandler(ListToolsRequestSchema, () => {
-		return { tools: connection.listTargets().length > 0 ? DEBUG_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) : DEBUG_TOOL_DEFINITIONS.filter((tool) => BOOTSTRAP_TOOL_NAMES.has(tool.name)).map((tool) => ({ ...tool })) };
+		const env = resolveEnvironment();
+		const attached = connection.listTargets().length > 0;
+		const envFiltered = filterToolsByEnvironment(DEBUG_TOOL_DEFINITIONS, env);
+		return { tools: attached ? envFiltered.map((tool) => ({ ...tool })) : envFiltered.filter((tool) => BOOTSTRAP_TOOL_NAMES.has(tool.name)).map((tool) => ({ ...tool })) };
 	});
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {
 		const name = request.params.name;
@@ -1875,6 +2921,18 @@ function createDebugServer(deps) {
 			}],
 			isError: true
 		};
+		const env = resolveEnvironment();
+		if (!isToolAvailableIn(name, env)) {
+			const reason = `tool ${name} is available only in ${getToolAvailability(name)}. Current environment is ${env} (${resolveEnvironmentReason()}).`;
+			process.stderr.write(`[ait-debug] tier-filter rejected ${name}: ${reason}\n`);
+			return {
+				content: [{
+					type: "text",
+					text: reason
+				}],
+				isError: true
+			};
+		}
 		if (isAitToolName(name)) try {
 			await connection.enableDomains();
 			switch (name) {
@@ -1897,6 +2955,20 @@ function createDebugServer(deps) {
 			};
 			const waitForAttach = request.params.arguments?.wait_for_attach === true;
 			const openInBrowser = request.params.arguments?.open_in_browser !== false;
+			const deploymentId = extractDeploymentId(schemeUrl);
+			if (!deploymentId) process.stderr.write("[ait-debug] build_attach_url: no _deploymentId in scheme_url; matching on presence only\n");
+			/** Returns true when the page list satisfies the attach condition. */
+			const isMatchingPage = (pages) => {
+				if (pages.length === 0) return false;
+				if (deploymentId === null) return true;
+				return pages.some((p) => p.url.includes(deploymentId));
+			};
+			/** Builds a timeout error message with diagnostic context. */
+			const buildTimeoutError = (baseText, timeoutSec, observed) => {
+				const observedUrls = observed.slice(0, 3).map((p) => p.url.slice(0, 80)).join(", ");
+				const observedNote = observed.length > 0 ? ` — previously attached pages: [${observedUrls}]` : "";
+				return `${baseText}\n\nNo page${deploymentId ? ` matching deploymentId=${deploymentId}` : ""} attached within ${timeoutSec}s${observedNote} — call list_pages to retry.`;
+			};
 			try {
 				const { attachUrl, relayUrl, authorityWarning } = buildAttachUrl(schemeUrl, getTunnelStatus());
 				const warningPrefix = authorityWarning ? `⚠️  scheme_url 경고: ${authorityWarning}\n\n` : "";
@@ -1909,22 +2981,19 @@ function createDebugServer(deps) {
 							type: "text",
 							text: shortText
 						}] };
-						const POLL_INTERVAL_MS = 1e3;
-						const TIMEOUT_MS = waitForAttachTimeoutMs;
-						const deadline = Date.now() + TIMEOUT_MS;
 						let attachedPages = [];
-						while (Date.now() < deadline) {
+						try {
+							attachedPages = await waitForAttachWithEvents(connection, isMatchingPage, waitForAttachTimeoutMs);
+						} catch {
 							attachedPages = connection.listTargets();
-							if (attachedPages.length > 0) break;
-							await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+							return {
+								content: [{
+									type: "text",
+									text: buildTimeoutError(shortText, waitForAttachTimeoutMs / 1e3, attachedPages)
+								}],
+								isError: true
+							};
 						}
-						if (attachedPages.length === 0) return {
-							content: [{
-								type: "text",
-								text: `${shortText}\n\nNo page attached within ${TIMEOUT_MS / 1e3}s — call list_pages to retry.`
-							}],
-							isError: true
-						};
 						const pagesResult = listPages(connection, getTunnelStatus());
 						return { content: [{
 							type: "text",
@@ -1942,22 +3011,19 @@ function createDebugServer(deps) {
 						type: "text",
 						text: baseText
 					}] };
-					const POLL_INTERVAL_MS_FB = 1e3;
-					const TIMEOUT_MS_FB = waitForAttachTimeoutMs;
-					const deadline2 = Date.now() + TIMEOUT_MS_FB;
 					let attachedPagesFb = [];
-					while (Date.now() < deadline2) {
+					try {
+						attachedPagesFb = await waitForAttachWithEvents(connection, isMatchingPage, waitForAttachTimeoutMs);
+					} catch {
 						attachedPagesFb = connection.listTargets();
-						if (attachedPagesFb.length > 0) break;
-						await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS_FB));
+						return {
+							content: [{
+								type: "text",
+								text: buildTimeoutError(baseText, waitForAttachTimeoutMs / 1e3, attachedPagesFb)
+							}],
+							isError: true
+						};
 					}
-					if (attachedPagesFb.length === 0) return {
-						content: [{
-							type: "text",
-							text: `${baseText}\n\nNo page attached within ${TIMEOUT_MS_FB / 1e3}s — call list_pages to retry.`
-						}],
-						isError: true
-					};
 					const pagesResultFb = listPages(connection, getTunnelStatus());
 					return { content: [{
 						type: "text",
@@ -1973,22 +3039,19 @@ function createDebugServer(deps) {
 					type: "text",
 					text: baseText
 				}] };
-				const POLL_INTERVAL_MS = 1e3;
-				const TIMEOUT_MS = waitForAttachTimeoutMs;
-				const deadline = Date.now() + TIMEOUT_MS;
 				let attachedPages = [];
-				while (Date.now() < deadline) {
+				try {
+					attachedPages = await waitForAttachWithEvents(connection, isMatchingPage, waitForAttachTimeoutMs);
+				} catch {
 					attachedPages = connection.listTargets();
-					if (attachedPages.length > 0) break;
-					await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+					return {
+						content: [{
+							type: "text",
+							text: buildTimeoutError(baseText, waitForAttachTimeoutMs / 1e3, attachedPages)
+						}],
+						isError: true
+					};
 				}
-				if (attachedPages.length === 0) return {
-					content: [{
-						type: "text",
-						text: `${baseText}\n\nNo page attached within ${TIMEOUT_MS / 1e3}s — call list_pages to retry.`
-					}],
-					isError: true
-				};
 				const pagesResult = listPages(connection, getTunnelStatus());
 				return { content: [{
 					type: "text",
@@ -2002,7 +3065,12 @@ function createDebugServer(deps) {
 			await connection.enableDomains();
 		} catch (err) {
 			const message = err instanceof Error ? err.message : String(err);
-			if (name === "list_pages") return jsonResult$1(listPages(connection, getTunnelStatus()));
+			if (name === "list_pages") {
+				if (connection instanceof ChiiCdpConnection) try {
+					await connection.refreshTargets();
+				} catch {}
+				return jsonResult$1(listPages(connection, getTunnelStatus()));
+			}
 			return {
 				content: [{
 					type: "text",
@@ -2014,8 +3082,16 @@ function createDebugServer(deps) {
 		try {
 			switch (name) {
 				case "list_console_messages": return jsonResult$1(listConsoleMessages(connection));
+				case "list_exceptions": {
+					const rawLimit = request.params.arguments?.limit;
+					return jsonResult$1({ exceptions: listExceptions(connection, typeof rawLimit === "number" && rawLimit > 0 ? rawLimit : 50) });
+				}
 				case "list_network_requests": return jsonResult$1(listNetworkRequests(connection));
-				case "list_pages": return jsonResult$1(listPages(connection, getTunnelStatus()));
+				case "list_pages":
+					if (connection instanceof ChiiCdpConnection) try {
+						await connection.refreshTargets();
+					} catch {}
+					return jsonResult$1(listPages(connection, getTunnelStatus()));
 				case "get_dom_document": return jsonResult$1(await getDomDocument(connection));
 				case "take_snapshot": return jsonResult$1(await takeSnapshot(connection));
 				case "take_screenshot": {
@@ -2026,7 +3102,7 @@ function createDebugServer(deps) {
 						mimeType: shot.mimeType
 					}] };
 				}
-				case "measure_safe_area": return jsonResult$1(await measureSafeArea(connection));
+				case "measure_safe_area": return jsonResult$1(await measureSafeArea(connection, resolveEnvironment()));
 				case "evaluate": {
 					const expression = request.params.arguments?.expression;
 					if (typeof expression !== "string" || expression === "") return {
@@ -2073,11 +3149,22 @@ function unknownTool(name) {
 		isError: true
 	};
 }
+/**
+* Detects whether an error is a relay/websocket disconnect error.
+* These are distinguished from "no page attached yet" errors because they
+* require enableDomains() to be called again (re-establish the websocket),
+* not just waiting for a target to appear.
+*/
+function isDisconnectError(err) {
+	if (!(err instanceof Error)) return false;
+	const msg = err.message;
+	return msg.includes("relay에 연결되어 있지 않습니다") || msg.includes("relay WebSocket") || msg.includes("replaced-by-new-attach") || msg.includes("Chii relay connection closed");
+}
 function errorResult(err, name) {
 	return {
 		content: [{
 			type: "text",
-			text: `${name} failed: ${err instanceof Error ? err.message : String(err)}\nCall list_pages to confirm a mini-app has attached over the relay.`
+			text: `${name} failed: ${err instanceof Error ? err.message : String(err)}${isDisconnectError(err) ? "\n\nrelay 연결이 끊겼습니다. list_pages → enableDomains() 재호출로 재연결하세요. 폰이 백그라운드로 내려갔거나 미니앱이 종료됐을 수 있습니다." : "\nCall list_pages to confirm a mini-app has attached over the relay."}`
 		}],
 		isError: true
 	};
@@ -2091,19 +3178,28 @@ function errorResult(err, name) {
 * `server.sendToolListChanged()` exactly once — on the first transition — then
 * clears itself. Shutdown calls `stop()` to clear the interval.
 *
+* `onFirstAttach` is called once on the 0→N transition (or immediately when
+* already attached). Use this to trigger side-effects such as auto-opening
+* Chrome DevTools (issue #282). The callback is optional; omitting it preserves
+* the previous behaviour exactly.
+*
 * SECRET-HANDLING: target `id`/`title`/`url` are not written to any log here.
 * Only an attach-detected stderr line is emitted (no target details).
 *
 * @returns `stop` — call this during shutdown to clear the interval.
 */
-function startAttachWatcher(connection, server, intervalMs = 1e3) {
+function startAttachWatcher(connection, server, intervalMs = 1e3, onFirstAttach) {
 	let wasAttached = connection.listTargets().length > 0;
-	if (wasAttached) server.sendToolListChanged();
+	if (wasAttached) {
+		server.sendToolListChanged();
+		onFirstAttach?.();
+	}
 	const handle = setInterval(() => {
 		const isAttached = connection.listTargets().length > 0;
 		if (!wasAttached && isAttached) {
 			wasAttached = true;
 			server.sendToolListChanged();
+			onFirstAttach?.();
 			clearInterval(handle);
 		}
 	}, intervalMs);
@@ -2143,6 +3239,7 @@ function buildRelayVerifyAuth() {
 *   4. expose the debug tools backed by a `ChiiCdpConnection` + `ChiiAitSource`.
 */
 async function runDebugServer(options = {}) {
+	const lockHandle = acquireLock();
 	const relayPort = options.relayPort ?? 0;
 	const verifyAuth = buildRelayVerifyAuth();
 	const totpEnabled = verifyAuth !== void 0;
@@ -2162,6 +3259,7 @@ async function runDebugServer(options = {}) {
 			up: true,
 			wssUrl: t.wssUrl
 		};
+		lockHandle.updateWssUrl(t.wssUrl);
 		return printAttachBanner({
 			wssUrl: t.wssUrl,
 			totpEnabled
@@ -2174,12 +3272,13 @@ async function runDebugServer(options = {}) {
 	const connection = new ChiiCdpConnection({ relayBaseUrl: relay.baseUrl });
 	const aitSource = new ChiiAitSource(connection);
 	let qrServer;
-	startQrHttpServer().then((s) => {
-		qrServer = s;
-	}, (err) => {
+	try {
+		qrServer = await startQrHttpServer();
+	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		process.stderr.write(`[ait-debug] QR HTTP 서버 시작 실패 (text QR fallback 사용): ${message}\n`);
-	});
+	}
+	const devtoolsOpener = new AutoDevtoolsOpener();
 	const server = createDebugServer({
 		connection,
 		aitSource,
@@ -2200,6 +3299,7 @@ async function runDebugServer(options = {}) {
 		relay.close();
 		server.close();
 		qrServer?.close();
+		lockHandle.release();
 	};
 	process.once("SIGINT", shutdown);
 	process.once("SIGTERM", shutdown);
@@ -2209,6 +3309,7 @@ async function runDebugServer(options = {}) {
 			closed = true;
 			attachWatcher?.stop();
 			tunnel?.stop();
+			lockHandle.release();
 		}
 	});
 	process.on("uncaughtException", (err) => {
@@ -2222,7 +3323,9 @@ async function runDebugServer(options = {}) {
 		process.exit(1);
 	});
 	await server.connect(transport);
-	attachWatcher = startAttachWatcher(connection, server);
+	attachWatcher = startAttachWatcher(connection, server, 1e3, () => {
+		devtoolsOpener.open(tunnelStatus.wssUrl, getEnvironment({ connection }));
+	});
 }
 /**
 * Boots the local-browser debug stack and serves it over stdio:
@@ -2243,6 +3346,7 @@ async function runDebugServer(options = {}) {
 * expected and noted in the PR as an explicit out-of-scope follow-up.
 */
 async function runLocalDebugServer(options = {}) {
+	const lockHandle = acquireLock();
 	const chromium = await launchChromium({
 		port: options.cdpPort ?? 0,
 		devUrl: options.devUrl ?? process.env.AIT_DEVTOOLS_URL ?? "http://localhost:5173"
@@ -2269,6 +3373,7 @@ async function runLocalDebugServer(options = {}) {
 		connection.close();
 		chromium.stop();
 		server.close();
+		lockHandle.release();
 	};
 	process.once("SIGINT", shutdown);
 	process.once("SIGTERM", shutdown);
@@ -2278,6 +3383,7 @@ async function runLocalDebugServer(options = {}) {
 			closed = true;
 			attachWatcher?.stop();
 			chromium.stop();
+			lockHandle.release();
 		}
 	});
 	process.on("uncaughtException", (err) => {
@@ -2366,7 +3472,13 @@ var HttpAitSource = class {
 *     }
 *   }
 */
-/** Tool descriptors served by the dev-mode server. */
+/**
+* Tool descriptors served by the dev-mode server.
+*
+* All dev-mode tools are Tier C (both envs) per RFC #277 — the dev-mode server
+* itself is the mock-side embodiment of those Tier C tools. `availableIn` is
+* declared so the surface stays consistent with the debug-mode registry.
+*/
 const DEV_TOOL_DEFINITIONS = [
 	{
 		name: "AIT.getMockState",
@@ -2375,7 +3487,8 @@ const DEV_TOOL_DEFINITIONS = [
 			type: "object",
 			properties: {},
 			required: []
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "AIT.getOperationalEnvironment",
@@ -2384,7 +3497,8 @@ const DEV_TOOL_DEFINITIONS = [
 			type: "object",
 			properties: {},
 			required: []
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "AIT.getSdkCallHistory",
@@ -2393,7 +3507,8 @@ const DEV_TOOL_DEFINITIONS = [
 			type: "object",
 			properties: {},
 			required: []
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "devtools_get_mock_state",
@@ -2402,7 +3517,8 @@ const DEV_TOOL_DEFINITIONS = [
 			type: "object",
 			properties: {},
 			required: []
-		}
+		},
+		availableIn: "both"
 	}
 ];
 const DEV_TOOL_NAMES = new Set(DEV_TOOL_DEFINITIONS.map((t) => t.name));
@@ -2412,7 +3528,7 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.40"
+		version: "0.1.43"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {