@ait-co/devtools 0.1.41 → 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,9 +11,13 @@ 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$4(value) {
 	return typeof value === "object" && value !== null;
@@ -62,6 +66,12 @@ 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;
@@ -181,12 +191,73 @@ var ChiiCdpConnection = class {
 		}
 		if (newestTargetId !== null) this.activeTargetId = newestTargetId;
 		else this.activeTargetId = null;
-		return [...this.targets.values()];
+		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.
 	*/
@@ -423,7 +494,12 @@ var ChiiCdpConnection = class {
 			return;
 		}
 		const now = Date.now();
-		for (const targetId of this.targets.keys()) this.targetLastSeenAt.set(targetId, 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);
@@ -493,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()");
 }
@@ -548,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
@@ -1049,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.
@@ -1327,7 +1742,8 @@ const DEBUG_TOOL_DEFINITIONS = [
 			type: "object",
 			properties: {},
 			required: []
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "list_network_requests",
@@ -1336,7 +1752,8 @@ const DEBUG_TOOL_DEFINITIONS = [
 			type: "object",
 			properties: {},
 			required: []
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "list_pages",
@@ -1345,7 +1762,8 @@ const DEBUG_TOOL_DEFINITIONS = [
 			type: "object",
 			properties: {},
 			required: []
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "build_attach_url",
@@ -1367,7 +1785,8 @@ const DEBUG_TOOL_DEFINITIONS = [
 				}
 			},
 			required: ["scheme_url"]
-		}
+		},
+		availableIn: "relay"
 	},
 	{
 		name: "get_dom_document",
@@ -1376,7 +1795,8 @@ const DEBUG_TOOL_DEFINITIONS = [
 			type: "object",
 			properties: {},
 			required: []
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "take_snapshot",
@@ -1385,7 +1805,8 @@ const DEBUG_TOOL_DEFINITIONS = [
 			type: "object",
 			properties: {},
 			required: []
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "take_screenshot",
@@ -1394,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",
@@ -1415,7 +1838,8 @@ const DEBUG_TOOL_DEFINITIONS = [
 				description: "JavaScript expression to evaluate in the page context."
 			} },
 			required: ["expression"]
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "list_exceptions",
@@ -1427,7 +1851,8 @@ const DEBUG_TOOL_DEFINITIONS = [
 				description: "Maximum number of exceptions to return (default 50, max 50)."
 			} },
 			required: []
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "call_sdk",
@@ -1446,7 +1871,8 @@ const DEBUG_TOOL_DEFINITIONS = [
 				}
 			},
 			required: ["name"]
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "AIT.getSdkCallHistory",
@@ -1455,7 +1881,8 @@ const DEBUG_TOOL_DEFINITIONS = [
 			type: "object",
 			properties: {},
 			required: []
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "AIT.getMockState",
@@ -1464,7 +1891,8 @@ const DEBUG_TOOL_DEFINITIONS = [
 			type: "object",
 			properties: {},
 			required: []
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "AIT.getOperationalEnvironment",
@@ -1473,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));
@@ -1481,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.
@@ -1781,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.
@@ -1793,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() {
@@ -1815,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);
@@ -1842,6 +2318,7 @@ const SAFE_AREA_PROBE_EXPRESSION = `
   var result = {
     cssEnv: cssEnv,
     sdkInsets: sdkInsets,
+    sdkInsetsSource: sdkInsetsSource,
     navBarHeight: navBarHeight,
     navBarHeightSource: navBarHeightSource,
     innerWidth: window.innerWidth,
@@ -1858,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 {
@@ -1889,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";
@@ -1897,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,
@@ -1912,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,
@@ -1924,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
@@ -2339,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.
@@ -2351,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.41"
+		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;
@@ -2368,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) {
@@ -2390,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` : "";
@@ -2402,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",
@@ -2435,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",
@@ -2466,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",
@@ -2495,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",
@@ -2512,7 +3087,11 @@ function createDebugServer(deps) {
 					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": {
@@ -2523,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 {
@@ -2570,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
 	};
@@ -2588,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);
@@ -2640,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;
@@ -2659,6 +3259,7 @@ async function runDebugServer(options = {}) {
 			up: true,
 			wssUrl: t.wssUrl
 		};
+		lockHandle.updateWssUrl(t.wssUrl);
 		return printAttachBanner({
 			wssUrl: t.wssUrl,
 			totpEnabled
@@ -2677,6 +3278,7 @@ async function runDebugServer(options = {}) {
 		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,
@@ -2697,6 +3299,7 @@ async function runDebugServer(options = {}) {
 		relay.close();
 		server.close();
 		qrServer?.close();
+		lockHandle.release();
 	};
 	process.once("SIGINT", shutdown);
 	process.once("SIGTERM", shutdown);
@@ -2706,6 +3309,7 @@ async function runDebugServer(options = {}) {
 			closed = true;
 			attachWatcher?.stop();
 			tunnel?.stop();
+			lockHandle.release();
 		}
 	});
 	process.on("uncaughtException", (err) => {
@@ -2719,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:
@@ -2740,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"
@@ -2766,6 +3373,7 @@ async function runLocalDebugServer(options = {}) {
 		connection.close();
 		chromium.stop();
 		server.close();
+		lockHandle.release();
 	};
 	process.once("SIGINT", shutdown);
 	process.once("SIGTERM", shutdown);
@@ -2775,6 +3383,7 @@ async function runLocalDebugServer(options = {}) {
 			closed = true;
 			attachWatcher?.stop();
 			chromium.stop();
+			lockHandle.release();
 		}
 	});
 	process.on("uncaughtException", (err) => {
@@ -2863,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",
@@ -2872,7 +3487,8 @@ const DEV_TOOL_DEFINITIONS = [
 			type: "object",
 			properties: {},
 			required: []
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "AIT.getOperationalEnvironment",
@@ -2881,7 +3497,8 @@ const DEV_TOOL_DEFINITIONS = [
 			type: "object",
 			properties: {},
 			required: []
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "AIT.getSdkCallHistory",
@@ -2890,7 +3507,8 @@ const DEV_TOOL_DEFINITIONS = [
 			type: "object",
 			properties: {},
 			required: []
-		}
+		},
+		availableIn: "both"
 	},
 	{
 		name: "devtools_get_mock_state",
@@ -2899,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));
@@ -2909,7 +3528,7 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.41"
+		version: "0.1.43"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {