@ait-co/devtools 0.1.44 → 0.1.46

package/dist/mcp/cli.js

@@ -848,8 +848,75 @@ var AutoDevtoolsOpener = class {
 	}
 };
 //#endregion
+//#region src/mcp/envelope.ts
+/**
+* Returns `true` when `AIT_MCP_COMPAT=chrome-devtools` is set, which bypasses
+* envelope wrapping and returns raw payloads (0.1.x back-compat).
+*/
+function isCompatMode() {
+	return process.env.AIT_MCP_COMPAT === "chrome-devtools";
+}
+/**
+* Maps `McpEnvironment` to `EnvelopeEnv`. After #307 these are the same
+* union (`mock | relay-dev | relay-live`), so this is identity — kept as a
+* named export for surface stability if envelope env diverges in the future.
+*/
+function toEnvelopeEnv(env) {
+	return env;
+}
+/**
+* Wraps `data` in a `ToolEnvelope<T>` **unless** compat mode is active, in
+* which case `data` is returned as-is.
+*
+* Use this at every tool call-site in `debug-server.ts` and `server.ts`.
+*
+* @example
+* ```ts
+* return jsonResult(wrapEnvelope(listPages(connection, tunnel), {
+*   tool: 'list_pages',
+*   env: resolveEnvironment(),
+*   attached: connection.listTargets().length > 0,
+* }));
+* ```
+*/
+function wrapEnvelope(data, ctx) {
+	if (isCompatMode()) return data;
+	return {
+		ok: true,
+		data,
+		meta: {
+			tool: ctx.tool,
+			env: toEnvelopeEnv(ctx.env),
+			attached: ctx.attached,
+			contentType: ctx.contentType ?? "json"
+		}
+	};
+}
+//#endregion
 //#region src/mcp/environment.ts
 /**
+* Returns `true` when the environment is any relay variant (`relay-dev` or
+* `relay-live`). Use this instead of `env === 'relay'` for tier checks.
+*/
+function isRelayEnv(env) {
+	return env === "relay-dev" || env === "relay-live";
+}
+/**
+* Returns `true` when the environment is the LIVE relay (`relay-live`).
+* This is the guard condition for side-effect tool protection.
+*/
+function isLiveRelayEnv(env) {
+	return env === "relay-live";
+}
+/**
+* Maps the new `McpEnvironment` union to the legacy two-value union
+* (`'mock' | 'relay'`) for backward-compatible fields in diagnostics output.
+*/
+function toLegacyEnv(env) {
+	if (env === "mock") return "mock";
+	return "relay";
+}
+/**
 * 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
@@ -874,28 +941,43 @@ function isRelayUrl(url) {
 * regardless of env vars or connection state. Cleared with `null`.
 */
 let envOverride = null;
-/** Parses the `MCP_ENV` env var into a `McpEnvironment` if valid. */
+/**
+* Parses the `MCP_ENV` env var into a `McpEnvironment` if valid.
+*
+* Accepted values:
+*   - `mock`        → `mock`
+*   - `relay-dev`   → `relay-dev`
+*   - `relay-live`  → `relay-live`
+*   - `relay`       → `relay-dev`  (backward-compat alias — resolves to relay-dev)
+*
+* Any other value is ignored and falls through to the next precedence step.
+*/
 function readEnvVar() {
 	const raw = process.env.MCP_ENV;
-	if (raw === "mock" || raw === "relay") return raw;
+	if (raw === "mock") return "mock";
+	if (raw === "relay-dev") return "relay-dev";
+	if (raw === "relay-live") return "relay-live";
+	if (raw === "relay") return "relay-dev";
 }
 /**
 * 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`
+*   3. CDP target URL pattern match → `relay-dev` (conservative — LIVE
+*      requires explicit MCP_ENV=relay-live opt-in)
+*   4. caller-stated `defaultEnv` (intent hint from the CLI mode)
+*   5. baked-in default `mock`
 */
 function getEnvironment(input = {}) {
 	if (envOverride !== null) return envOverride;
 	const fromEnv = readEnvVar();
 	if (fromEnv !== void 0) return fromEnv;
-	const { connection } = input;
+	const { connection, defaultEnv } = input;
 	if (connection !== void 0) {
 		const targets = connection.listTargets();
-		for (const t of targets) if (isRelayUrl(t.url)) return "relay";
+		for (const t of targets) if (isRelayUrl(t.url)) return "relay-dev";
 	}
-	return "mock";
+	return defaultEnv ?? "mock";
 }
 /**
 * Returns the `EnvironmentReason` that drove the current `getEnvironment()`
@@ -904,15 +986,23 @@ function getEnvironment(input = {}) {
 * secret value is ever returned.
 */
 function getEnvironmentReason(input = {}) {
-	if (envOverride !== null) return envOverride === "mock" ? "env-var-mock" : "env-var-relay";
+	if (envOverride !== null) {
+		if (envOverride === "mock") return "env-var-mock";
+		if (envOverride === "relay-live") return "env-var-relay-live";
+		return "env-var-relay-dev";
+	}
+	const rawVar = process.env.MCP_ENV;
 	const fromEnv = readEnvVar();
 	if (fromEnv === "mock") return "env-var-mock";
-	if (fromEnv === "relay") return "env-var-relay";
-	const { connection } = input;
+	if (fromEnv === "relay-live") return "env-var-relay-live";
+	if (fromEnv === "relay-dev") return rawVar === "relay" ? "env-var-relay-compat" : "env-var-relay-dev";
+	const { connection, defaultEnv } = input;
 	if (connection !== void 0) {
 		const targets = connection.listTargets();
 		for (const t of targets) if (isRelayUrl(t.url)) return "cdp-target-url-relay-pattern";
 	}
+	if (defaultEnv === "relay-live") return "default-relay-live";
+	if (defaultEnv === "relay-dev") return "default-relay-dev";
 	return "default-mock";
 }
 //#endregion
@@ -940,7 +1030,7 @@ function mcpError(message) {
 * @param reason      - 환경이 결정된 근거 (EnvironmentReason 문자열).
 */
 function tierRejectionError(toolName, requiredEnv, currentEnv, reason) {
-	return mcpError(`${`${toolName}은 ${requiredEnv === "relay" ? "relay (실기기 연결)" : "mock (로컬 브라우저)"} 환경에서만 사용할 수 있습니다. 현재 환경: ${currentEnv === "relay" ? "relay" : "mock"} (${reason}). ${requiredEnv === "relay" ? "build_attach_url → QR 스캔으로 실기기를 attach하세요." : "MCP_ENV=mock 또는 relay 환경변수를 확인하세요."}`}\n\n${`tool ${toolName} is available only in ${requiredEnv}. Current environment is ${currentEnv} (${reason}).`}`);
+	return mcpError(`${`${toolName}은 ${requiredEnv === "relay" ? "relay (실기기 연결)" : "mock (로컬 브라우저)"} 환경에서만 사용할 수 있습니다. 현재 환경: ${currentEnv === "relay" ? "relay" : "mock"} (${reason}). ${requiredEnv === "relay" ? "relay로 전환하려면 MCP_ENV=relay 설정 후 서버를 재시작하고 build_attach_url → QR 스캔으로 실기기를 attach하세요." : "mock으로 전환하려면 MCP_ENV=mock 설정 후 서버를 재시작하세요."}`}\n\n${`tool ${toolName} is available only in ${requiredEnv}. Current environment is ${currentEnv} (${reason}).`}`);
 }
 /**
 * 상태 1: tunnel 미가동 — cloudflared 터널이 아직 뜨지 않았다.
@@ -956,7 +1046,7 @@ function tunnelDownError() {
 * enableDomains()가 "No mini-app page attached" 에러를 던질 때.
 */
 function pageMissingError(toolName) {
-	return mcpError(`${toolName ? `${toolName}: ` : ""}페이지가 attach 안 됨. build_attach_url로 deep link를 생성하고 QR을 스캔해 미니앱을 attach하세요.`);
+	return mcpError(`${toolName ? `${toolName}: ` : ""}페이지가 attach 안 됨. dogfood 번들 배포 후 build_attach_url을 호출해 QR을 생성하세요: \`ait deploy --scheme-only\` → \`build_attach_url(scheme_url)\` → QR 스캔.`);
 }
 /**
 * 상태 3: page crash — 연결됐던 페이지가 crash/destroy됐다.
@@ -973,7 +1063,24 @@ function pageCrashError(toolName) {
 * call_sdk 호출 시 브리지가 없을 때.
 */
 function sdkAbsentError(toolName) {
-	return mcpError(`${toolName ? `${toolName}: ` : ""}window.__sdkCall이 주입되지 않았습니다 (dogfood 빌드가 아닙니다). dogfood 채널(intoss-private)로 번들을 재배포한 뒤 재시도하세요.`);
+	return mcpError(`${toolName ? `${toolName}: ` : ""}window.__sdkCall이 주입되지 않았습니다 (dogfood 빌드가 아닙니다). dogfood 채널(intoss-private)로 재배포 후 QR을 다시 스캔하세요: \`ait build && aitcc app deploy\`.`);
+}
+/**
+* relay-live 환경에서 side-effect 도구(`call_sdk`, `evaluate`)를 `confirm: true`
+* 없이 호출했을 때 반환하는 거부 메시지.
+*
+* 다음 행동을 두 가지로 제시한다:
+*   1. 같은 호출에 `confirm: true` 인자를 추가해 재시도.
+*   2. 읽기 전용 환경(relay-dev, mock)으로 전환.
+*/
+function liveGuardError(toolName) {
+	return mcpError(`[LIVE relay guard] ${toolName}은 현재 relay-live(실 출시 런타임) 세션에서 side-effect 호출입니다. 실유저에게 영향을 줄 수 있어 명시적 동의가 필요합니다.
+
+다음 중 하나를 선택하세요:
+  1. \`confirm: true\` 인자를 추가해 재호출: ${toolName}(…, confirm: true)\n  2. 읽기 전용 도구(list_pages, list_console_messages, take_screenshot 등)를 사용하세요.
+  3. dogfood 빌드(relay-dev 환경)에서 먼저 검증 후 live에 적용하세요.
+
+live-guard: MCP_ENV=relay-live + confirm: true missing`);
 }
 /**
 * relay WebSocket 연결이 끊겼을 때 — 크래시가 아닌 네트워크/프로세스 종료.
@@ -1541,7 +1648,9 @@ var ServerLockConflictError = class extends Error {
 	existingPid;
 	/** wssUrl from the existing lock — may be `null` if the tunnel is still starting. */
 	existingWssUrl;
-	constructor(existingPid, existingWssUrl) {
+	/** ISO timestamp from the existing lock — when that session started. */
+	existingStartedAt;
+	constructor(existingPid, existingWssUrl, existingStartedAt) {
 		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:
@@ -1549,6 +1658,7 @@ If it is already stopped but this error persists, remove the lock file:
 		this.name = "ServerLockConflictError";
 		this.existingPid = existingPid;
 		this.existingWssUrl = existingWssUrl;
+		this.existingStartedAt = existingStartedAt;
 	}
 };
 /** Returns `~/.ait-devtools/server.lock` (or `AIT_DEVTOOLS_LOCK_DIR` override for tests). */
@@ -1601,6 +1711,29 @@ function removeLock(lockPath) {
 	} catch {}
 }
 /**
+* Sends SIGTERM to `pid` and waits up to `graceMs` (default 2 000 ms) for it
+* to exit; then falls back to SIGKILL.  Synchronous — uses a busy-wait loop so
+* it is usable in the top-level startup path without async plumbing.
+*
+* Ignores errors from `process.kill` so that a race where the target exits
+* between the alive check and the kill call does not crash the caller.
+*/
+function killAndWait(pid, graceMs = 2e3) {
+	try {
+		process.kill(pid, "SIGTERM");
+	} catch {
+		return;
+	}
+	const deadline = Date.now() + graceMs;
+	while (isPidAlive(pid) && Date.now() < deadline) {
+		const end = Date.now() + 100;
+		while (Date.now() < end);
+	}
+	if (isPidAlive(pid)) try {
+		process.kill(pid, "SIGKILL");
+	} catch {}
+}
+/**
 * Reads the current lock file without acquiring it. Returns the parsed
 * `LockData` when the file exists and is valid, otherwise `null`. Used by
 * `get_diagnostics` to surface the `serverLockHolder` field without
@@ -1614,18 +1747,28 @@ function readServerLock() {
 *
 * - 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`.
+* - If a live process holds the lock and `force` is `false` (default): writes
+*   a clear recovery message to stderr and throws `ServerLockConflictError`.
+* - If a live process holds the lock and `force` is `true`: sends SIGTERM to
+*   that process (waiting up to 2 s then SIGKILL) and takes over the lock.
 *
 * The initial `wssUrl` in the lock file is `null` — call
 * `handle.updateWssUrl(url)` once the cloudflared tunnel is ready.
 */
-function acquireLock() {
+function acquireLock(options = {}) {
+	const { force = false } = options;
 	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`);
+	if (existing !== null) if (isPidAlive(existing.pid)) if (force) {
+		process.stderr.write(`[ait-debug] --force: terminating existing session PID=${existing.pid} …\n`);
+		killAndWait(existing.pid);
+		process.stderr.write(`[ait-debug] --force: PID=${existing.pid} stopped, taking over.\n`);
+	} else {
+		const urlPart = existing.wssUrl != null ? `wssUrl=${existing.wssUrl}` : "wssUrl=(tunnel starting)";
+		process.stderr.write(`[ait-debug] 기존 debug-mode 세션이 이미 실행 중 — PID=${existing.pid}, started ${existing.startedAt}, ${urlPart}\n[ait-debug] 회복: \`kill ${existing.pid}\` 또는 \`npx @ait-co/devtools devtools-mcp --force\`\n`);
+		throw new ServerLockConflictError(existing.pid, existing.wssUrl, existing.startedAt);
 	}
+	else process.stderr.write(`[ait-debug] stale lock from PID ${existing.pid} recovered — starting fresh.\n`);
 	const data = {
 		pid: process.pid,
 		wssUrl: null,
@@ -1915,6 +2058,83 @@ function warnPassthrough(name) {
 }
 SIGNATURES.map((s) => s.name);
 //#endregion
+//#region src/mcp/totp.ts
+/**
+* RFC 6238 TOTP implementation (Node.js, node:crypto only).
+*
+* External TOTP libraries (otplib, speakeasy, …) are intentionally NOT used
+* to keep the dependency surface minimal. This hand-roll is ~30 lines and
+* covers exactly what relay-side auth needs.
+*
+* Algorithm summary (RFC 6238 + RFC 4226):
+*   T  = floor(now / 30)          — 30-second time step counter
+*   K  = Buffer.from(secret, 'hex') — shared secret (raw bytes, hex-encoded)
+*   MAC = HMAC-SHA1(K, T as 8-byte big-endian uint64)
+*   offset = MAC[19] & 0x0f
+*   code = (MAC[offset..offset+4] & 0x7fffffff) % 10^6  — 6 digits
+*
+* Security note (keep this comment accurate):
+*   The baked-in secret in a dogfood build is extractable from the bundle by a
+*   determined reverse engineer. This mechanism raises the bar from
+*   "anyone with the URL" to "URL + bundle extraction + live TOTP calculation".
+*   Casual URL leaks (Slack paste, QR screenshot, shoulder-surfing) are
+*   blocked; deliberate reverse engineering is not. See threat model in
+*   src/mcp/chii-relay.ts and umbrella CLAUDE.md §4.
+*
+* SECRET-HANDLING: secret values and computed codes MUST NOT appear in any
+* log, error message, or string visible outside this module. Only boolean
+* pass/fail and reason enum values are safe to surface.
+*/
+/** Time step window in seconds (RFC 6238 default). */
+const TIME_STEP = 30;
+/** Number of digits in the generated code. */
+const DIGITS = 6;
+/**
+* Derives a 6-digit TOTP code from a hex-encoded secret at the given wall-
+* clock time.
+*
+* @param secret - The shared secret as a hex string (e.g. 64 hex chars = 32
+*   bytes). Must be the output of `generateAttachToken()` or compatible.
+* @param when - Unix timestamp in milliseconds. Defaults to `Date.now()`.
+* @returns A zero-padded 6-digit decimal string, e.g. `"042193"`.
+*/
+function generateTotp(secret, when = Date.now()) {
+	const key = Buffer.from(secret, "hex");
+	const counter = Math.max(0, Math.floor(when / 1e3 / TIME_STEP));
+	const counterBuf = Buffer.alloc(8);
+	const hi = Math.floor(counter / 4294967296);
+	const lo = counter >>> 0;
+	counterBuf.writeUInt32BE(hi, 0);
+	counterBuf.writeUInt32BE(lo, 4);
+	const mac = createHmac("sha1", key).update(counterBuf).digest();
+	const offset = mac[19] & 15;
+	return (((mac[offset] & 127) << 24 | (mac[offset + 1] & 255) << 16 | (mac[offset + 2] & 255) << 8 | mac[offset + 3] & 255) % 10 ** DIGITS).toString().padStart(DIGITS, "0");
+}
+/**
+* Verifies a TOTP code against the secret, accepting ±`skew` time steps to
+* tolerate clock drift between the relay host and the client device.
+*
+* Uses `timingSafeEqual` for constant-time comparison to prevent timing
+* side-channel attacks.
+*
+* @param secret - Hex-encoded shared secret.
+* @param code - The 6-digit code to verify (string or numeric).
+* @param when - Unix timestamp in milliseconds. Defaults to `Date.now()`.
+* @param skew - Number of adjacent steps to accept on either side. Default 1
+*   (accepts T-1, T, T+1 — a 90-second acceptance window).
+* @returns `true` if the code matches any accepted step, `false` otherwise.
+*/
+function verifyTotp(secret, code, when = Date.now(), skew = 1) {
+	const normalised = String(code).padStart(DIGITS, "0");
+	if (normalised.length !== DIGITS || !/^\d{6}$/.test(normalised)) return false;
+	const candidateBuf = Buffer.from(normalised, "utf8");
+	for (let delta = -skew; delta <= skew; delta++) {
+		const expected = generateTotp(secret, when + delta * TIME_STEP * 1e3);
+		if (timingSafeEqual(Buffer.from(expected, "utf8"), candidateBuf)) return true;
+	}
+	return false;
+}
+//#endregion
 //#region src/mcp/tools.ts
 /** Static MCP tool descriptors (name + JSONSchema) for the full debug tool surface. */
 const DEBUG_TOOL_DEFINITIONS = [
@@ -1940,7 +2160,7 @@ const DEBUG_TOOL_DEFINITIONS = [
 	},
 	{
 		name: "list_pages",
-		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. The `tunnel` field includes `droppedAt` (ISO timestamp or null/undefined): when non-null the tunnel has permanently dropped after 3 failed reissue attempts — restart the debug server with `npx @ait-co/devtools devtools-mcp`. 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.",
+		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. The `tunnel` field includes `droppedAt` (ISO timestamp or null/undefined): when non-null the tunnel has permanently dropped after 3 failed reissue attempts — restart the debug server with `npx @ait-co/devtools devtools-mcp`. 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. When a page attaches or detaches the server emits notifications/tools/list_changed — call tools/list again to get the full updated tool surface.",
 		inputSchema: {
 			type: "object",
 			properties: {},
@@ -1950,7 +2170,7 @@ const DEBUG_TOOL_DEFINITIONS = [
 	},
 	{
 		name: "build_attach_url",
-		description: "The tool result already shows the QR to the user directly (Claude Code renders MCP tool output to the user's screen; they press Ctrl+O to expand if it's collapsed). Do NOT re-print or re-render the QR in your reply — that just wastes output tokens. Simply tell the user to scan the QR shown in this tool's output with their phone camera. Turns an `ait deploy --scheme-only` URL (intoss-private://…?_deploymentId=<uuid>) into a self-attaching deep link by splicing in debug=1 and the live relay URL for this session. Returns the deep link JSON and a unicode QR of that deep link. Scan the QR with the phone camera to open the mini-app and attach it to this debug session (QR is the single entry path — no USB cable or platform CLI needed). Requires the tunnel to be up — call list_pages first. Set wait_for_attach=true to block until the phone scans and a page attaches (polls listTargets up to 90 s), then returns the attached page info too. When open_in_browser=true (default), saves the QR as a PNG and opens it in the OS default browser — only works when the MCP server runs on a local GUI machine (not headless/remote containers).",
+		description: "The tool result already shows the QR to the user directly (Claude Code renders MCP tool output to the user's screen; they press Ctrl+O to expand if it's collapsed). Do NOT re-print or re-render the QR in your reply — that just wastes output tokens. Simply tell the user to scan the QR shown in this tool's output with their phone camera. Turns an `ait deploy --scheme-only` URL (intoss-private://…?_deploymentId=<uuid>) into a self-attaching deep link by splicing in debug=1 and the live relay URL for this session. Returns the deep link JSON and a unicode QR of that deep link. Scan the QR with the phone camera to open the mini-app and attach it to this debug session (QR is the single entry path — no USB cable or platform CLI needed). Requires the tunnel to be up — call list_pages first. If the tunnel is not up, restart the MCP server: `npx @ait-co/devtools devtools-mcp`. Set wait_for_attach=true to block until the phone scans and a page attaches (polls listTargets up to 30 s by default), then returns the attached page info too. On timeout, call build_attach_url again to resume polling. When open_in_browser=true (default), saves the QR as a PNG and opens it in the OS default browser — only works when the MCP server runs on a local GUI machine (not headless/remote containers). Requires MCP_ENV=relay-dev or relay-live (set automatically in debug-mode default).\n\nTOTP auth: when AIT_DEBUG_TOTP_SECRET is set on the MCP server, the returned attachUrl automatically includes the current one-time code (at=<code>) — the URL is single-use for that 30-second step. The response includes a `totp` field with `expiresAt` (ISO timestamp). If the phone scan happens after expiresAt, the relay will reject the code — just call build_attach_url again to get a fresh one-time URL. Without AIT_DEBUG_TOTP_SECRET, the attachUrl has no expiry.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -1960,7 +2180,7 @@ const DEBUG_TOOL_DEFINITIONS = [
 				},
 				wait_for_attach: {
 					type: "boolean",
-					description: "If true, block after returning the QR until a page attaches to the relay (polls listTargets ~1 s interval, timeout 90 s). On attach, the response includes the attached page list. On timeout, returns an error with a list_pages retry hint."
+					description: "If true, block after returning the QR until a page attaches to the relay (polls listTargets ~1 s interval, timeout 30 s). On attach, the response includes the attached page list. On timeout, call build_attach_url again to resume polling."
 				},
 				open_in_browser: {
 					type: "boolean",
@@ -1993,7 +2213,7 @@ const DEBUG_TOOL_DEFINITIONS = [
 	},
 	{
 		name: "take_screenshot",
-		description: "Captures a PNG screenshot of the attached mini-app page over CDP (Page.captureScreenshot) so the agent can see the phone screen directly. Read-only. Returns an image content block.",
+		description: "Captures a PNG screenshot of the attached mini-app page over CDP (Page.captureScreenshot) so the agent can see the phone screen directly. Read-only. Returns an image content block — this is the only debug tool that returns an image; all other debug tools return text (JSON).",
 		inputSchema: {
 			type: "object",
 			properties: {},
@@ -2013,13 +2233,19 @@ const DEBUG_TOOL_DEFINITIONS = [
 	},
 	{
 		name: "evaluate",
-		description: "Evaluates an arbitrary JavaScript expression on the attached mini-app page via CDP Runtime.evaluate (returnByValue: true) and returns the result. NOT read-only — the expression can have side effects (DOM mutations, SDK calls, state changes). Requires the relay to be attached — call list_pages first. Throws if the evaluation throws an exception on the page.",
+		description: "Evaluates an arbitrary JavaScript expression on the attached mini-app page via CDP Runtime.evaluate (returnByValue: true) and returns the result. NOT read-only — the expression can have side effects (DOM mutations, SDK calls, state changes). Requires the relay to be attached — call list_pages first. Throws if the evaluation throws an exception on the page.\n\nSECURITY: expression and result are not redacted — never include secrets or auth tokens in the expression.\n\nLIVE guard: when running against a live/production relay (relay-live env, MCP_ENV=relay-live), this tool requires `confirm: true` to acknowledge that the expression may affect real users. Without it the call is rejected with a structured error. mock and relay-dev sessions are unaffected.",
 		inputSchema: {
 			type: "object",
-			properties: { expression: {
-				type: "string",
-				description: "JavaScript expression to evaluate in the page context."
-			} },
+			properties: {
+				expression: {
+					type: "string",
+					description: "JavaScript expression to evaluate in the page context."
+				},
+				confirm: {
+					type: "boolean",
+					description: "Required when MCP_ENV=relay-live. Set to `true` to explicitly acknowledge that this expression may have side effects on real/live users. Omitting this in a relay-live session results in a structured rejection error. Has no effect in mock or relay-dev sessions."
+				}
+			},
 			required: ["expression"]
 		},
 		availableIn: "both"
@@ -2039,7 +2265,7 @@ const DEBUG_TOOL_DEFINITIONS = [
 	},
 	{
 		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. 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\", [])",
+		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) — redeploy via dogfood channel: `ait build && aitcc app deploy`.\n\nSECURITY: method name, args, and result value are not redacted — never include secrets.\n\nLIVE guard: when running against a live/production relay (relay-live env, MCP_ENV=relay-live), this tool requires `confirm: true` to acknowledge that the SDK call may affect real users. Without it the call is rejected with a structured error. mock and relay-dev sessions are unaffected.\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: {
@@ -2051,6 +2277,10 @@ const DEBUG_TOOL_DEFINITIONS = [
 					type: "array",
 					description: "Arguments to pass to the SDK method (optional, default []).",
 					items: {}
+				},
+				confirm: {
+					type: "boolean",
+					description: "Required when MCP_ENV=relay-live. Set to `true` to explicitly acknowledge that this SDK call may have side effects on real/live users. Omitting this in a relay-live session results in a structured rejection error. Has no effect in mock or relay-dev sessions."
 				}
 			},
 			required: ["name"]
@@ -2089,7 +2319,7 @@ const DEBUG_TOOL_DEFINITIONS = [
 	},
 	{
 		name: "get_diagnostics",
-		description: "Returns a single-call server status snapshot so the agent can diagnose \"why is this not working?\" without calling multiple tools. Fields: mcpVersion (MCP SDK version), devtoolsVersion (@ait-co/devtools package version), tunnel (up/wssUrl/pid/startedAt), pages (list_pages result + lastSeenAt stats), lastAttachAt, lastDetachAt, recentErrors (last N server-side errors, PII/secret redacted), environment (getEnvironment() result + reason), serverLockHolder (pid + startedAt from the lock file, or null). All fields are nullable — missing data is null, not an error. Tier C (both mock and relay). Call this first when debugging session state.",
+		description: "Returns a single-call server status snapshot so the agent can diagnose \"why is this not working?\" without calling multiple tools. Fields: mcpVersion (MCP SDK version), devtoolsVersion (@ait-co/devtools package version), tunnel (up/wssUrl/pid/startedAt), pages (list_pages result + lastSeenAt stats), lastAttachAt, lastDetachAt, recentErrors (last N server-side errors, PII/secret redacted), environment (kind: mock|relay-dev|relay-live, env: mock|relay backward-compat, reason, liveGuardActive: true when relay-live LIVE guard is active), serverLockHolder (pid + startedAt from the lock file, or null), nextRecommendedAction ({tool, reason} or null — the single next tool to call). All fields are nullable — missing data is null, not an error. debug-mode only — dev-mode (--mode=dev) does not support relay diagnostics. Tier C (both mock and relay). Call this first when debugging session state.",
 		inputSchema: {
 			type: "object",
 			properties: { recent_errors_limit: {
@@ -2118,20 +2348,26 @@ function getToolAvailability(name) {
 * 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.
+*
+* Relay variants (`relay-dev`, `relay-live`) both satisfy the `'relay'`
+* availability tier — `isRelayEnv()` is used for the check.
 */
 function isToolAvailableIn(name, env) {
 	const availability = getToolAvailability(name);
 	if (availability === void 0) return false;
 	if (availability === "both") return true;
+	if (availability === "relay") return isRelayEnv(env);
 	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.
+*
+* Relay variants (`relay-dev`, `relay-live`) both satisfy the `'relay'` tier.
 */
 function filterToolsByEnvironment(tools, env) {
-	return tools.filter((t) => t.availableIn === "both" || t.availableIn === env);
+	return tools.filter((t) => t.availableIn === "both" || t.availableIn === "relay" && isRelayEnv(env) || t.availableIn === env);
 }
 /**
 * Tool names that are available before any page attaches (bootstrap tier).
@@ -2250,20 +2486,50 @@ function listPages(connection, tunnel) {
 * URL plus this session's live relay. Throws if the tunnel is not up yet (no
 * relay URL to splice in) — the caller surfaces that as a tool error.
 *
+* When `AIT_DEBUG_TOTP_SECRET` is set, generates the current TOTP code and
+* splices it as `at=<code>` into the attach URL. The code is valid for one
+* 30-second time step (±1 skew accepted by the relay, so the effective window
+* is up to 90 s). If the scan happens after `totp.expiresAt`, call
+* `build_attach_url` again to get a fresh code.
+*
 * Also validates the scheme URL's authority. A suspicious authority (empty,
 * "web", "localhost", etc.) is surfaced as a non-fatal `authorityWarning` on
 * the result so the caller can show a helpful hint without blocking the link
 * generation (the warning is consistent with how other validation in
 * `buildDeepLinkAttachUrl` works — hard errors for relay, soft warning for
 * the scheme authority which is in the caller's input, not ours to own).
+*
+* SECRET-HANDLING: `totpSecret` (if provided) is used only to compute a code
+* and must never appear in any log, error message, or output outside of the
+* spliced `at=` param in `attachUrl`.
+*
+* @param schemeUrl - The `intoss-private://…?_deploymentId=<uuid>` URL.
+* @param tunnel - Current tunnel status from the running debug server.
+* @param totpSecret - Optional hex-encoded TOTP secret (from
+*   `AIT_DEBUG_TOTP_SECRET`). When provided, the current code is spliced into
+*   the attach URL as `at=<code>`.
 */
-function buildAttachUrl(schemeUrl, tunnel) {
+function buildAttachUrl(schemeUrl, tunnel, totpSecret) {
 	if (!tunnel.up || tunnel.wssUrl === null) throw new Error("tunnel-down: cloudflared 터널이 안 떠 있습니다. MCP 서버를 재시작하거나 잠시 후 list_pages로 터널 상태를 다시 확인하세요.");
 	const authorityWarning = validateSchemeAuthority(schemeUrl) ?? void 0;
+	let totpCode;
+	let totpMeta;
+	if (totpSecret !== void 0 && totpSecret !== "") {
+		const now = Date.now();
+		totpCode = generateTotp(totpSecret, now);
+		const STEP_SECONDS = 30;
+		const expiresAtMs = (Math.floor(now / 1e3 / STEP_SECONDS) + 1) * STEP_SECONDS * 1e3;
+		totpMeta = {
+			enabled: true,
+			ttlSeconds: STEP_SECONDS,
+			expiresAt: new Date(expiresAtMs).toISOString()
+		};
+	}
 	return {
-		attachUrl: buildDeepLinkAttachUrl(schemeUrl, tunnel.wssUrl),
+		attachUrl: buildDeepLinkAttachUrl(schemeUrl, tunnel.wssUrl, totpCode),
 		relayUrl: tunnel.wssUrl,
-		...authorityWarning !== void 0 ? { authorityWarning } : {}
+		...authorityWarning !== void 0 ? { authorityWarning } : {},
+		...totpMeta !== void 0 ? { totp: totpMeta } : {}
 	};
 }
 /**
@@ -2879,6 +3145,32 @@ function readDevtoolsVersion() {
 	}
 }
 /**
+* Derives the next recommended action from a completed diagnostics snapshot.
+*
+* Branch rules (evaluated in priority order):
+*   1. tunnel.up === false                        → restart
+*   2. tunnel.up, pages empty, env === relay      → build_attach_url (start attach)
+*   3. pages has entry + crashDetectedAt non-null → build_attach_url (re-attach after crash)
+*   4. otherwise                                  → null (session looks healthy)
+*
+* Pure — does not throw; receives the final assembled snapshot fields.
+*/
+function computeNextRecommendedAction(tunnel, pages, env) {
+	if (!tunnel.up) return {
+		tool: "restart",
+		reason: "tunnel not up — run `npx @ait-co/devtools devtools-mcp` to restart"
+	};
+	if (isRelayEnv(env) && pages !== null && pages.pages.length === 0 && !pages.crashDetectedAt) return {
+		tool: "build_attach_url",
+		reason: "tunnel ready, no pages attached — call build_attach_url to generate the attach QR"
+	};
+	if (pages !== null && pages.crashDetectedAt !== null) return {
+		tool: "build_attach_url",
+		reason: `page crashed at ${pages.crashDetectedAt} — call build_attach_url to re-attach`
+	};
+	return null;
+}
+/**
 * Builds the `get_diagnostics` response. Pure — does not throw; missing data
 * fields are `null`. Async because `readMcpSdkVersion` needs `import()`.
 *
@@ -2909,6 +3201,7 @@ async function getDiagnostics(input) {
 	} catch {}
 	const limit = Math.min(Math.max(1, recentErrorsLimit), 50);
 	const recentErrors = collector.getRecentErrors(limit);
+	const nextRecommendedAction = computeNextRecommendedAction(tunnelInfo, pages, env);
 	return {
 		mcpVersion,
 		devtoolsVersion,
@@ -2918,90 +3211,16 @@ async function getDiagnostics(input) {
 		lastDetachAt: collector.getLastDetachAt(),
 		recentErrors,
 		environment: {
-			env,
-			reason: envReason
+			kind: env,
+			env: toLegacyEnv(env),
+			reason: envReason,
+			liveGuardActive: isLiveRelayEnv(env)
 		},
-		serverLockHolder
+		serverLockHolder,
+		nextRecommendedAction
 	};
 }
 //#endregion
-//#region src/mcp/totp.ts
-/**
-* RFC 6238 TOTP implementation (Node.js, node:crypto only).
-*
-* External TOTP libraries (otplib, speakeasy, …) are intentionally NOT used
-* to keep the dependency surface minimal. This hand-roll is ~30 lines and
-* covers exactly what relay-side auth needs.
-*
-* Algorithm summary (RFC 6238 + RFC 4226):
-*   T  = floor(now / 30)          — 30-second time step counter
-*   K  = Buffer.from(secret, 'hex') — shared secret (raw bytes, hex-encoded)
-*   MAC = HMAC-SHA1(K, T as 8-byte big-endian uint64)
-*   offset = MAC[19] & 0x0f
-*   code = (MAC[offset..offset+4] & 0x7fffffff) % 10^6  — 6 digits
-*
-* Security note (keep this comment accurate):
-*   The baked-in secret in a dogfood build is extractable from the bundle by a
-*   determined reverse engineer. This mechanism raises the bar from
-*   "anyone with the URL" to "URL + bundle extraction + live TOTP calculation".
-*   Casual URL leaks (Slack paste, QR screenshot, shoulder-surfing) are
-*   blocked; deliberate reverse engineering is not. See threat model in
-*   src/mcp/chii-relay.ts and umbrella CLAUDE.md §4.
-*
-* SECRET-HANDLING: secret values and computed codes MUST NOT appear in any
-* log, error message, or string visible outside this module. Only boolean
-* pass/fail and reason enum values are safe to surface.
-*/
-/** Time step window in seconds (RFC 6238 default). */
-const TIME_STEP = 30;
-/** Number of digits in the generated code. */
-const DIGITS = 6;
-/**
-* Derives a 6-digit TOTP code from a hex-encoded secret at the given wall-
-* clock time.
-*
-* @param secret - The shared secret as a hex string (e.g. 64 hex chars = 32
-*   bytes). Must be the output of `generateAttachToken()` or compatible.
-* @param when - Unix timestamp in milliseconds. Defaults to `Date.now()`.
-* @returns A zero-padded 6-digit decimal string, e.g. `"042193"`.
-*/
-function generateTotp(secret, when = Date.now()) {
-	const key = Buffer.from(secret, "hex");
-	const counter = Math.max(0, Math.floor(when / 1e3 / TIME_STEP));
-	const counterBuf = Buffer.alloc(8);
-	const hi = Math.floor(counter / 4294967296);
-	const lo = counter >>> 0;
-	counterBuf.writeUInt32BE(hi, 0);
-	counterBuf.writeUInt32BE(lo, 4);
-	const mac = createHmac("sha1", key).update(counterBuf).digest();
-	const offset = mac[19] & 15;
-	return (((mac[offset] & 127) << 24 | (mac[offset + 1] & 255) << 16 | (mac[offset + 2] & 255) << 8 | mac[offset + 3] & 255) % 10 ** DIGITS).toString().padStart(DIGITS, "0");
-}
-/**
-* Verifies a TOTP code against the secret, accepting ±`skew` time steps to
-* tolerate clock drift between the relay host and the client device.
-*
-* Uses `timingSafeEqual` for constant-time comparison to prevent timing
-* side-channel attacks.
-*
-* @param secret - Hex-encoded shared secret.
-* @param code - The 6-digit code to verify (string or numeric).
-* @param when - Unix timestamp in milliseconds. Defaults to `Date.now()`.
-* @param skew - Number of adjacent steps to accept on either side. Default 1
-*   (accepts T-1, T, T+1 — a 90-second acceptance window).
-* @returns `true` if the code matches any accepted step, `false` otherwise.
-*/
-function verifyTotp(secret, code, when = Date.now(), skew = 1) {
-	const normalised = String(code).padStart(DIGITS, "0");
-	if (normalised.length !== DIGITS || !/^\d{6}$/.test(normalised)) return false;
-	const candidateBuf = Buffer.from(normalised, "utf8");
-	for (let delta = -skew; delta <= skew; delta++) {
-		const expected = generateTotp(secret, when + delta * TIME_STEP * 1e3);
-		if (timingSafeEqual(Buffer.from(expected, "utf8"), candidateBuf)) return true;
-	}
-	return false;
-}
-//#endregion
 //#region src/mcp/tunnel.ts
 /**
 * cloudflared quick tunnel + attach banner for the debug-mode MCP server.
@@ -3374,13 +3593,19 @@ function waitForAttachWithEvents(connection, filterFn, timeoutMs, pollIntervalMs
 * naturally via `enableDomains`). The tier only controls visibility.
 */
 function createDebugServer(deps) {
-	const { connection, aitSource, getTunnelStatus, waitForAttachTimeoutMs = 9e4, qrHttpServer, getEnvironment: getEnvDep, getEnvironmentReason: getEnvReasonDep, diagnosticsCollector: collectorDep } = deps;
-	const resolveEnvironment = getEnvDep ?? (() => getEnvironment({ connection }));
-	const resolveEnvironmentReason = getEnvReasonDep ?? (() => getEnvironmentReason({ connection }));
+	const { connection, aitSource, getTunnelStatus, waitForAttachTimeoutMs = 9e4, qrHttpServer, getEnvironment: getEnvDep, getEnvironmentReason: getEnvReasonDep, diagnosticsCollector: collectorDep, defaultEnv, totpSecret } = deps;
+	const resolveEnvironment = getEnvDep ?? (() => getEnvironment({
+		connection,
+		defaultEnv
+	}));
+	const resolveEnvironmentReason = getEnvReasonDep ?? (() => getEnvironmentReason({
+		connection,
+		defaultEnv
+	}));
 	const collector = collectorDep ?? new InMemoryDiagnosticsCollector();
 	const server = new Server({
 		name: "ait-debug",
-		version: "0.1.44"
+		version: "0.1.46"
 	}, { capabilities: { tools: { listChanged: true } } });
 	server.setRequestHandler(ListToolsRequestSchema, () => {
 		const env = resolveEnvironment();
@@ -3424,7 +3649,7 @@ function createDebugServer(deps) {
 		if (name === "get_diagnostics") try {
 			const rawLimit = request.params.arguments?.recent_errors_limit;
 			const recentErrorsLimit = typeof rawLimit === "number" && rawLimit > 0 ? rawLimit : 10;
-			return jsonResult$1(await getDiagnostics({
+			const result = await getDiagnostics({
 				tunnel: getTunnelStatus(),
 				connection,
 				env: resolveEnvironment(),
@@ -3432,7 +3657,9 @@ function createDebugServer(deps) {
 				collector,
 				readLock: readServerLock,
 				recentErrorsLimit
-			}));
+			});
+			const attached = connection.listTargets().length > 0;
+			return envelopeResult(result, name, resolveEnvironment(), attached);
 		} catch (err) {
 			return errorResult(err, name);
 		}
@@ -3459,7 +3686,7 @@ function createDebugServer(deps) {
 				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 { attachUrl, relayUrl, authorityWarning, totp } = buildAttachUrl(schemeUrl, getTunnelStatus(), totpSecret);
 				const warningPrefix = authorityWarning ? `⚠️  scheme_url 경고: ${authorityWarning}\n\n` : "";
 				const header = "This tool result is shown to the user directly — do NOT re-print the QR below in your reply (it wastes output tokens). Just tell the user to scan the QR in this output (Ctrl+O to expand if collapsed).";
 				const guiAvailable = canOpenBrowser();
@@ -3468,7 +3695,8 @@ function createDebugServer(deps) {
 					const qrHeadless = await renderQr(attachUrl);
 					const headlessText = `${warningPrefix}${headlessNote}${header}\n${JSON.stringify({
 						attachUrl,
-						relayUrl
+						relayUrl,
+						...totp ? { totp } : {}
 					}, null, 2)}\n\n${qrHeadless}`;
 					if (!waitForAttach) return { content: [{
 						type: "text",
@@ -3504,7 +3732,8 @@ function createDebugServer(deps) {
 						};
 						const shortText = `${warningPrefix}${header}\n${JSON.stringify({
 							relayUrl,
-							openResult
+							openResult,
+							...totp ? { totp } : {}
 						}, null, 2)}\n\n브라우저에서 QR을 열었습니다${retriedNote}. 폰 카메라로 스캔하세요.\nURL: ${browserResult.httpUrl}`;
 						if (!waitForAttach) return { content: [{
 							type: "text",
@@ -3543,7 +3772,8 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 					const baseText = `${warningPrefix}${fallbackNote}${header}\n${JSON.stringify({
 						attachUrl,
 						relayUrl,
-						openResult
+						openResult,
+						...totp ? { totp } : {}
 					}, null, 2)}\n\n${qr}`;
 					if (!waitForAttach) return { content: [{
 						type: "text",
@@ -3571,7 +3801,8 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 				const qr = await renderQr(attachUrl);
 				const baseText = `${warningPrefix}${header}\n${JSON.stringify({
 					attachUrl,
-					relayUrl
+					relayUrl,
+					...totp ? { totp } : {}
 				}, null, 2)}\n\n${qr}`;
 				if (!waitForAttach) return { content: [{
 					type: "text",
@@ -3606,7 +3837,9 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 				if (connection instanceof ChiiCdpConnection) try {
 					await connection.refreshTargets();
 				} catch {}
-				return jsonResult$1(listPages(connection, getTunnelStatus()));
+				const pagesData = listPages(connection, getTunnelStatus());
+				const attached = connection.listTargets().length > 0;
+				return envelopeResult(pagesData, name, resolveEnvironment(), attached);
 			}
 			return classifyEnableDomainError(err, name);
 		}
@@ -3618,11 +3851,14 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 					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":
+				case "list_pages": {
 					if (connection instanceof ChiiCdpConnection) try {
 						await connection.refreshTargets();
 					} catch {}
-					return jsonResult$1(listPages(connection, getTunnelStatus()));
+					const listPagesData = listPages(connection, getTunnelStatus());
+					const listPagesAttached = connection.listTargets().length > 0;
+					return envelopeResult(listPagesData, name, resolveEnvironment(), listPagesAttached);
+				}
 				case "get_dom_document": return jsonResult$1(await getDomDocument(connection));
 				case "take_snapshot": return jsonResult$1(await takeSnapshot(connection));
 				case "take_screenshot": {
@@ -3633,19 +3869,27 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 						mimeType: shot.mimeType
 					}] };
 				}
-				case "measure_safe_area": return jsonResult$1(await measureSafeArea(connection, resolveEnvironment()));
+				case "measure_safe_area": {
+					const safeAreaData = await measureSafeArea(connection, resolveEnvironment());
+					const safeAreaAttached = connection.listTargets().length > 0;
+					return envelopeResult(safeAreaData, name, resolveEnvironment(), safeAreaAttached);
+				}
 				case "evaluate": {
 					const expression = request.params.arguments?.expression;
 					if (typeof expression !== "string" || expression === "") return mcpError("evaluate: expression 인자가 비어 있습니다. 평가할 JavaScript 표현식을 전달하세요.");
+					if (isLiveRelayEnv(env) && request.params.arguments?.confirm !== true) return liveGuardError("evaluate");
 					return jsonResult$1(await evaluate(connection, expression));
 				}
 				case "call_sdk": {
 					const sdkName = request.params.arguments?.name;
 					if (typeof sdkName !== "string" || sdkName === "") return mcpError("call_sdk: name 인자가 비어 있습니다. 호출할 SDK 메서드 이름을 전달하세요.");
 					const rawArgs = request.params.arguments?.args;
-					const sdkResult = await callSdk(connection, sdkName, Array.isArray(rawArgs) ? rawArgs : []);
+					const sdkArgs = Array.isArray(rawArgs) ? rawArgs : [];
+					if (isLiveRelayEnv(env) && request.params.arguments?.confirm !== true) return liveGuardError("call_sdk");
+					const sdkResult = await callSdk(connection, sdkName, sdkArgs);
 					if (!sdkResult.ok && typeof sdkResult.error === "string" && sdkResult.error.startsWith("sdk-absent:")) return sdkAbsentError("call_sdk");
-					return jsonResult$1(sdkResult);
+					const callSdkAttached = connection.listTargets().length > 0;
+					return envelopeResult(sdkResult, name, resolveEnvironment(), callSdkAttached);
 				}
 				default: return unknownTool(name);
 			}
@@ -3661,6 +3905,22 @@ function jsonResult$1(value) {
 		text: JSON.stringify(value, null, 2)
 	}] };
 }
+/**
+* Wraps `value` in a `ToolEnvelope` (when compat mode is off) and returns it
+* as a text content block. When `AIT_MCP_COMPAT=chrome-devtools` is set the
+* envelope is skipped and the raw value is returned — identical to `jsonResult`.
+*/
+function envelopeResult(value, tool, env, attached) {
+	const wrapped = wrapEnvelope(value, {
+		tool,
+		env,
+		attached
+	});
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(wrapped, null, 2)
+	}] };
+}
 function unknownTool(name) {
 	return mcpError(`알 수 없는 tool: ${name}`);
 }
@@ -3756,7 +4016,7 @@ function buildRelayVerifyAuth() {
 *   4. expose the debug tools backed by a `ChiiCdpConnection` + `ChiiAitSource`.
 */
 async function runDebugServer(options = {}) {
-	const lockHandle = acquireLock();
+	const lockHandle = acquireLock({ force: options.force ?? false });
 	const relayPort = options.relayPort ?? 0;
 	const verifyAuth = buildRelayVerifyAuth();
 	const totpEnabled = verifyAuth !== void 0;
@@ -3821,7 +4081,9 @@ async function runDebugServer(options = {}) {
 		get qrHttpServer() {
 			return qrServer;
 		},
-		diagnosticsCollector
+		diagnosticsCollector,
+		defaultEnv: "relay-dev",
+		...process.env.AIT_DEBUG_TOTP_SECRET ? { totpSecret: process.env.AIT_DEBUG_TOTP_SECRET } : {}
 	});
 	const transport = new StdioServerTransport();
 	let closed = false;
@@ -3869,7 +4131,10 @@ async function runDebugServer(options = {}) {
 	await server.connect(transport);
 	attachWatcher = startAttachWatcher(connection, server, 1e3, () => {
 		diagnosticsCollector.recordAttach();
-		devtoolsOpener.open(tunnelStatus.wssUrl, getEnvironment({ connection }));
+		devtoolsOpener.open(tunnelStatus.wssUrl, getEnvironment({
+			connection,
+			defaultEnv: "relay-dev"
+		}));
 	});
 }
 /**
@@ -3891,7 +4156,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 lockHandle = acquireLock({ force: options.force ?? false });
 	const chromium = await launchChromium({
 		port: options.cdpPort ?? 0,
 		devUrl: options.devUrl ?? process.env.AIT_DEVTOOLS_URL ?? "http://localhost:5173"
@@ -3906,7 +4171,8 @@ async function runLocalDebugServer(options = {}) {
 	const server = createDebugServer({
 		connection,
 		aitSource,
-		getTunnelStatus: () => tunnelStatus
+		getTunnelStatus: () => tunnelStatus,
+		defaultEnv: "mock"
 	});
 	const transport = new StdioServerTransport();
 	let closed = false;
@@ -4011,6 +4277,27 @@ var HttpAitSource = class {
 * (dev). `devtools_get_mock_state` (the original devtools#130 name) is kept as a
 * backward-compatible alias of `AIT.getMockState`.
 *
+* Issue #305 (M2-1) — dev/debug tool-surface unification:
+* dev-mode now also exposes `list_pages`, `get_diagnostics`, `measure_safe_area`,
+* and `call_sdk` so the docs/qa/scenarios.md acceptance sequence
+* `list_pages → measure_safe_area → call_sdk` works in dev mode without
+* "Unknown tool" failures.
+*
+* - `list_pages`       — shim: returns the Vite dev URL as a single-entry array.
+* - `get_diagnostics`  — dumps dev-mode server state (endpoint URL, last fetch
+*                        error, reachability, mode/environment metadata).
+* - `measure_safe_area`— reads safeAreaInsets from the mock state snapshot
+*                        (source: 'mock-vite').
+* - `call_sdk`         — reads mock state and builds a mock-equivalent result
+*                        using window.__ait.state for supported methods; returns
+*                        an explicit tier-filter error for methods that require
+*                        a live CDP bridge.
+* - CDP-only tools (`evaluate`, `take_screenshot`, `get_dom_document`,
+*                   `take_snapshot`, `list_console_messages`,
+*                   `list_network_requests`, `list_exceptions`) — return an
+*                   explicit tier-filter error explaining that CDP is unavailable
+*                   in dev-mode and pointing to `--mode=local` or `--mode=debug`.
+*
 * This module is reached via the `devtools-mcp --mode=dev` CLI entry (see
 * `cli.ts`); the default (no flag) bin mode is the debug-mode CDP/Chii server.
 *
@@ -4025,12 +4312,18 @@ var HttpAitSource = class {
 *     }
 *   }
 */
+/** Error message prefix for CDP-dependent tools called in dev-mode. */
+const CDP_UNAVAILABLE_IN_DEV_MODE = "dev-mode에서는 CDP 연결이 없어 이 도구를 사용할 수 없습니다. 실기기 또는 로컬 Chromium에 붙이려면 `devtools-mcp --mode=local` 또는 `devtools-mcp` (debug 모드 기본)로 전환하세요.";
 /**
 * 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.
+*
+* Issue #305: CDP-only tools are also listed with explicit descriptions so
+* agents do not get "Unknown tool" failures — they get a clear tier-filter
+* error message instead.
 */
 const DEV_TOOL_DEFINITIONS = [
 	{
@@ -4072,30 +4365,290 @@ const DEV_TOOL_DEFINITIONS = [
 			required: []
 		},
 		availableIn: "both"
+	},
+	{
+		name: "list_pages",
+		description: "dev-mode: returns the Vite dev server URL as a single-entry page list. No CDP relay is involved — `tunnel.up` is always false and `devMode: true` marks this as a shim result. Call this first to confirm the dev server is reachable. In debug mode (`devtools-mcp` / `--mode=local`) this returns real attached pages.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "get_diagnostics",
+		description: "dev-mode: returns server diagnostics — Vite endpoint URL, last fetch timestamp/error, mock state endpoint reachability, mode (\"dev\"), and environment metadata. Call this when the dev server connection is suspect. In debug mode this returns tunnel/relay/attach status instead.",
+		inputSchema: {
+			type: "object",
+			properties: { recent_errors_limit: {
+				type: "number",
+				description: "Ignored in dev-mode (no error ring buffer). Present for schema parity."
+			} },
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "measure_safe_area",
+		description: "dev-mode: reads safe-area insets from the mock state snapshot via the Vite endpoint. Returns `{ source: \"mock-vite\", sdkInsets, sdkInsetsSource: \"window.__ait\", ... }`. Values reflect what the DevTools panel reports at the time of the last state push. In debug mode this runs a Runtime.evaluate CDP probe on the attached page.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "call_sdk",
+		description: "dev-mode: calls a mock SDK method via the Vite mock state endpoint. Supported methods read from window.__ait mock state (e.g. getOperationalEnvironment). Returns the same `{ok, value}` / `{ok, error}` envelope as debug mode. In debug mode this calls the real SDK via window.__sdkCall over CDP.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				name: {
+					type: "string",
+					description: "Mock SDK method name to call (e.g. \"getOperationalEnvironment\")."
+				},
+				args: {
+					type: "array",
+					description: "Arguments (ignored in dev-mode mock path; present for schema parity).",
+					items: {}
+				}
+			},
+			required: ["name"]
+		},
+		availableIn: "both"
+	},
+	{
+		name: "evaluate",
+		description: "Evaluates an arbitrary JavaScript expression via CDP Runtime.evaluate. NOT available in dev-mode (no CDP connection). Switch to `--mode=local` or `--mode=debug` for CDP access.",
+		inputSchema: {
+			type: "object",
+			properties: { expression: {
+				type: "string",
+				description: "JavaScript expression to evaluate."
+			} },
+			required: ["expression"]
+		},
+		availableIn: "both"
+	},
+	{
+		name: "take_screenshot",
+		description: "Captures a PNG screenshot via CDP Page.captureScreenshot. NOT available in dev-mode (no CDP connection). Switch to `--mode=local` or `--mode=debug`.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "get_dom_document",
+		description: "Returns the DOM tree via CDP DOM.getDocument. NOT available in dev-mode (no CDP connection). Switch to `--mode=local` or `--mode=debug`.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "take_snapshot",
+		description: "Captures a serialized page snapshot via CDP DOMSnapshot.captureSnapshot. NOT available in dev-mode (no CDP connection). Switch to `--mode=local` or `--mode=debug`.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "list_console_messages",
+		description: "Lists console messages captured via CDP Runtime.consoleAPICalled. NOT available in dev-mode (no CDP connection). Switch to `--mode=local` or `--mode=debug`.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "list_network_requests",
+		description: "Lists network requests captured via CDP Network events. NOT available in dev-mode (no CDP connection). Switch to `--mode=local` or `--mode=debug`.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "list_exceptions",
+		description: "Lists JS exceptions captured via CDP Runtime.exceptionThrown. NOT available in dev-mode (no CDP connection). Switch to `--mode=local` or `--mode=debug`.",
+		inputSchema: {
+			type: "object",
+			properties: { limit: {
+				type: "number",
+				description: "Maximum exceptions to return."
+			} },
+			required: []
+		},
+		availableIn: "both"
 	}
 ];
+/** All tool names served in dev-mode (including tier-filter stubs). */
 const DEV_TOOL_NAMES = new Set(DEV_TOOL_DEFINITIONS.map((t) => t.name));
+/** CDP-only tools — return a tier-filter error in dev-mode. */
+const CDP_ONLY_TOOL_NAMES = new Set([
+	"evaluate",
+	"take_screenshot",
+	"get_dom_document",
+	"take_snapshot",
+	"list_console_messages",
+	"list_network_requests",
+	"list_exceptions"
+]);
+/**
+* Builds the `list_pages` dev-mode shim response.
+* Returns the Vite dev URL as a single-entry page list with `devMode: true`.
+*/
+function buildDevListPagesResult(devtoolsUrl) {
+	return {
+		pages: [{
+			url: devtoolsUrl,
+			title: "dev fixture",
+			attached: true
+		}],
+		tunnel: { up: false },
+		devMode: true,
+		singleAttachModel: true
+	};
+}
+/**
+* Builds the `get_diagnostics` dev-mode response.
+* Probes the mock state endpoint reachability and returns server metadata.
+*/
+async function buildDevDiagnostics(devtoolsUrl, stateEndpoint, fetchImpl) {
+	let reachable = false;
+	let lastFetchError = null;
+	let lastFetchAt = null;
+	try {
+		const res = await fetchImpl(stateEndpoint);
+		reachable = res.ok;
+		lastFetchAt = (/* @__PURE__ */ new Date()).toISOString();
+		if (!res.ok) lastFetchError = `HTTP ${res.status} ${res.statusText}`;
+	} catch (err) {
+		lastFetchError = err instanceof Error ? err.message : String(err);
+		lastFetchAt = (/* @__PURE__ */ new Date()).toISOString();
+	}
+	return {
+		mode: "dev",
+		devtoolsUrl,
+		mcpStateEndpoint: stateEndpoint,
+		mockStateEndpointReachable: reachable,
+		lastFetchAt,
+		lastFetchError,
+		environment: {
+			kind: "mock",
+			reason: "dev-mode — Vite HTTP endpoint, no CDP connection"
+		},
+		nextRecommendedAction: reachable ? null : "mock state endpoint가 응답하지 않습니다. Vite dev 서버가 `mcp: true` 옵션으로 실행 중인지 확인하고, 필요하면 dev 서버를 재시작하세요."
+	};
+}
+/**
+* Builds the `measure_safe_area` dev-mode response from mock state.
+* Reads `safeAreaInsets` from the AIT mock state and returns a parity-schema
+* result with `source: 'mock-vite'`.
+*/
+async function buildDevMeasureSafeArea(aitSource) {
+	const rawInsets = (await aitSource.get("AIT.getMockState")).safeAreaInsets;
+	let sdkInsets = null;
+	if (rawInsets !== null && typeof rawInsets === "object" && !Array.isArray(rawInsets)) {
+		const r = rawInsets;
+		sdkInsets = {
+			top: typeof r.top === "number" ? r.top : 0,
+			right: typeof r.right === "number" ? r.right : 0,
+			bottom: typeof r.bottom === "number" ? r.bottom : 0,
+			left: typeof r.left === "number" ? r.left : 0
+		};
+	}
+	return {
+		source: "mock-vite",
+		cssEnv: {
+			top: 0,
+			right: 0,
+			bottom: 0,
+			left: 0
+		},
+		sdkInsets,
+		sdkInsetsSource: sdkInsets !== null ? "window.__ait" : null,
+		...sdkInsets === null ? { sdkInsetsError: "window.__ait.state.safeAreaInsets not found in mock state snapshot" } : {},
+		innerWidth: null,
+		innerHeight: null,
+		devicePixelRatio: null,
+		userAgent: null,
+		navBarHeight: null,
+		navBarHeightSource: "not-available-in-dev-mode"
+	};
+}
+/**
+* Builds the `call_sdk` dev-mode response.
+*
+* Supported methods are served from the mock state snapshot. Unsupported
+* methods return `{ ok: false, error: 'dev-mode-unsupported: ...' }` so the
+* agent gets an informative message rather than a generic failure.
+*/
+async function buildDevCallSdk(methodName, aitSource) {
+	switch (methodName) {
+		case "getOperationalEnvironment": {
+			const env = await aitSource.get("AIT.getOperationalEnvironment");
+			return {
+				ok: true,
+				value: {
+					environment: env.environment,
+					sdkVersion: env.sdkVersion
+				}
+			};
+		}
+		default: return {
+			ok: false,
+			error: `dev-mode-unsupported: "${methodName}"은 dev-mode에서 직접 호출할 수 없습니다. CDP bridge(window.__sdkCall)가 없으므로 실제 SDK 호출은 \`--mode=local\` 또는 debug 모드에서만 가능합니다. 지원 메서드: getOperationalEnvironment (mock state에서 읽음).`
+		};
+	}
+}
 /** Builds the dev-mode MCP server (does not connect a transport). */
 function createDevServer(deps = {}) {
-	const stateEndpoint = `${process.env.AIT_DEVTOOLS_URL ?? "http://localhost:5173"}/api/ait-devtools/state`;
+	const devtoolsUrl = process.env.AIT_DEVTOOLS_URL ?? "http://localhost:5173";
+	const stateEndpoint = `${devtoolsUrl}/api/ait-devtools/state`;
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.44"
+		version: "0.1.46"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {
 		const name = request.params.name;
 		if (!DEV_TOOL_NAMES.has(name)) return mcpError(`알 수 없는 tool: ${name}`);
+		if (CDP_ONLY_TOOL_NAMES.has(name)) return mcpError(`${name}: ${CDP_UNAVAILABLE_IN_DEV_MODE}`);
 		try {
 			const effective = name === "devtools_get_mock_state" ? "AIT.getMockState" : name;
-			if (!isAitToolName(effective)) return mcpError(`알 수 없는 tool: ${name}`);
-			switch (effective) {
+			if (isAitToolName(effective)) switch (effective) {
 				case "AIT.getMockState": return jsonResult(await getMockState(aitSource));
 				case "AIT.getOperationalEnvironment": return jsonResult(await getOperationalEnvironment(aitSource));
 				case "AIT.getSdkCallHistory": return jsonResult(await getSdkCallHistory(aitSource));
 				default: return mcpError(`알 수 없는 tool: ${name}`);
 			}
+			switch (name) {
+				case "list_pages": return jsonResult(buildDevListPagesResult(devtoolsUrl));
+				case "get_diagnostics": return jsonResult(await buildDevDiagnostics(devtoolsUrl, stateEndpoint, (url) => fetch(url)));
+				case "measure_safe_area": return jsonResult(await buildDevMeasureSafeArea(aitSource));
+				case "call_sdk": {
+					const sdkName = request.params.arguments?.name;
+					if (typeof sdkName !== "string" || sdkName === "") return mcpError("call_sdk: name 인자가 비어 있습니다. 호출할 메서드 이름을 전달하세요.");
+					return jsonResult(await buildDevCallSdk(sdkName, aitSource));
+				}
+				default: return mcpError(`알 수 없는 tool: ${name}`);
+			}
 		} catch (err) {
 			return mcpError(`${name} 실패: ${err instanceof Error ? err.message : String(err)}\nVite dev 서버가 @ait-co/devtools unplugin \`mcp: true\` 옵션으로 실행 중인지 확인하세요. AIT_DEVTOOLS_URL 환경변수가 올바르게 설정됐는지도 확인하세요.`);
 		}
@@ -4135,6 +4688,15 @@ async function runDevServer() {
 *
 * Node-only stdio process.
 */
+/**
+* Returns `true` when `--force` or `--takeover` is present in argv.
+*
+* Both flags are accepted as aliases — `--force` is the short form listed in
+* the `--help` output; `--takeover` is a longer synonym.
+*/
+function parseForce(argv) {
+	return argv.includes("--force") || argv.includes("--takeover");
+}
 /** Parses `--mode=<value>` / `--mode <value>` from argv; default `debug`. */
 function parseMode(argv) {
 	for (let i = 0; i < argv.length; i++) {
@@ -4182,8 +4744,12 @@ function normalizeTarget(value) {
 async function main() {
 	const args = process.argv.slice(2);
 	if (parseMode(args) === "dev") await runDevServer();
-	else if (parseTarget(args) === "local") await runLocalDebugServer();
-	else await runDebugServer();
+	else {
+		const target = parseTarget(args);
+		const force = parseForce(args);
+		if (target === "local") await runLocalDebugServer({ force });
+		else await runDebugServer({ force });
+	}
 }
 /**
 * True when this file is the process entry (the bin), not an import.
@@ -4210,6 +4776,6 @@ if (isEntrypoint()) main().catch((err) => {
 	process.exitCode = 1;
 });
 //#endregion
-export { parseMode, parseTarget };
+export { parseForce, parseMode, parseTarget };
 
 //# sourceMappingURL=cli.js.map