@ait-co/devtools 0.1.55 → 0.1.57

package/dist/mcp/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { i as generateTotp, n as assertRelayAuthConfigured, r as buildRelayVerifyAuth } from "../totp-D0a8VwoR.js";
 import { createRequire } from "node:module";
 import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { argv } from "node:process";
@@ -12,8 +13,8 @@ import { createServer } from "node:http";
 import { spawn } from "node:child_process";
 import net from "node:net";
 import { homedir, platform } from "node:os";
-import { join } from "node:path";
-import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
 import { Tunnel, bin, install } from "cloudflared";
 //#region \0rolldown/runtime.js
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
@@ -718,6 +719,157 @@ async function startChiiRelay(options = {}) {
 	};
 }
 //#endregion
+//#region src/mcp/deeplink.ts
+/**
+* URL of the AITC Sandbox launcher PWA.
+*
+* Declared here (not imported from `src/unplugin/tunnel.ts`) to respect the
+* mcp → unplugin layering boundary. unplugin/tunnel.ts declares its own copy
+* for the same reason — keep the two in sync when the URL changes.
+*/
+const LAUNCHER_URL = "https://devtools.aitc.dev/launcher/";
+/**
+* Builds a launcher PWA deep-link for env-2 MCP-attach (issue #378).
+*
+* The launcher at {@link LAUNCHER_URL} renders tunnelUrl in a full-viewport
+* iframe. `&debug=1&relay=<wssUrl>` is forwarded onto the iframe src so the
+* framed page's in-app debug gate (Layer C) is satisfied and a Chii target.js
+* is injected. `&at=<totpCode>` is added only when a code is provided (same
+* conditional as {@link buildDeepLinkAttachUrl}).
+*
+* Unlike `buildDeepLinkAttachUrl` (which splices onto a non-special scheme URL
+* via raw string manipulation), this function uses WHATWG `encodeURIComponent`
+* because the target is a standard `https:` URL.
+*
+* SECRET-HANDLING: `totpCode` (when provided) is placed into the `at=` param
+* only — never logged or returned separately. Callers must NOT log the result
+* of this function to stdout/stderr.
+*
+* @param tunnelUrl - The `https://*.trycloudflare.com` app tunnel URL
+*   (`AIT_TUNNEL_BASE_URL`). This is the URL the launcher frames.
+* @param wssUrl - The `wss://` relay URL the framed page will attach to.
+* @param totpCode - Optional current TOTP code (6 digits). When provided, it
+*   is appended as `at=<totpCode>`. Must be computed at call time — it rotates
+*   every 30 s. Omit when TOTP is disabled.
+* @returns The launcher deep-link URL with `?url=<enc>&debug=1&relay=<enc>
+*   [&at=<code>]` params.
+*/
+function buildLauncherAttachUrl(tunnelUrl, wssUrl, totpCode) {
+	let url = `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}&debug=1&relay=${encodeURIComponent(wssUrl)}`;
+	if (totpCode !== void 0 && totpCode !== "") url += `&at=${encodeURIComponent(totpCode)}`;
+	return url;
+}
+/**
+* Build a self-attaching dogfood deep link.
+*
+* `ait deploy --scheme-only` prints an `intoss-private://…?_deploymentId=<uuid>`
+* URL that opens a dogfood bundle on a phone. The in-app debug gate
+* (`src/in-app/gate.ts`) auto-attaches when the entry URL also carries
+* `debug=1` and `relay=<wss-url>`. This helper splices those params (plus
+* `at=<code>` when TOTP is enabled) into the scheme URL; rendering the result
+* as a QR code and scanning it with the phone camera opens the mini-app and
+* attaches it to the live Chii relay. QR is the single entry path — it needs
+* no USB cable, platform CLI, or driver, and works the same on iOS/Android.
+*
+* The Toss app propagates extra query params from the entry deep link into the
+* mini-app WebView's `location.search` (confirmed behavior), so the gate reads
+* them at attach time.
+*
+* TOTP `at=` param:
+*   When a TOTP secret is active, `buildDeepLinkAttachUrl` accepts an optional
+*   `totpCode` argument and splices `at=<code>` alongside `debug` and `relay`.
+*   The code must be computed by the caller at call time — do NOT pre-compute
+*   and cache it, because the 30-second window expires quickly. The in-app gate
+*   (`src/in-app/gate.ts` Layer C) validates this code against the baked secret.
+*
+* Why not `URL`/`URLSearchParams`: `intoss-private:` is a non-special scheme.
+* The WHATWG `URL` parser treats such schemes opaquely (no host/path/query
+* decomposition you can rely on across runtimes), so query manipulation via
+* `url.searchParams` is not portable here. We splice the query string directly
+* on the raw string instead, which keeps the scheme, authority, path, and any
+* pre-existing params (notably `_deploymentId`) byte-for-byte intact.
+*/
+/**
+* Suspicious/generic authority values that indicate a malformed or placeholder
+* scheme URL. These are host strings that will almost certainly cause the Toss
+* app to fail with "bundle not found" silently.
+*
+* The expected form from `ait deploy --scheme-only` is:
+*   intoss-private://<appName>?_deploymentId=<uuid>
+* where `<appName>` is a non-generic string like `aitc-sdk-example`.
+*/
+const SUSPICIOUS_AUTHORITIES = new Set([
+	"",
+	"web",
+	"localhost",
+	"127.0.0.1",
+	"app"
+]);
+/**
+* Validates the authority (host) portion of a scheme URL.
+*
+* Returns a warning message if the authority is missing or looks like a
+* placeholder, or `null` if the authority looks valid.
+*
+* Expected form: `intoss-private://<appName>?_deploymentId=<uuid>`
+* The authority must be a non-empty, non-generic app name (e.g. `aitc-sdk-example`).
+*/
+function validateSchemeAuthority(schemeUrl) {
+	const afterScheme = schemeUrl.replace(/^[a-zA-Z][a-zA-Z0-9+\-.]*:\/\//, "");
+	if (afterScheme === schemeUrl) return "scheme_url does not look like a scheme URL (expected `intoss-private://<appName>?_deploymentId=<uuid>`). Use the URL printed by `ait deploy --scheme-only`.";
+	const authorityEnd = afterScheme.search(/[/?#]/);
+	const authority = authorityEnd === -1 ? afterScheme : afterScheme.slice(0, authorityEnd);
+	if (SUSPICIOUS_AUTHORITIES.has(authority.toLowerCase())) return `scheme_url authority ${authority === "" ? "(empty)" : `"${authority}"`} looks like a placeholder. Expected an app name like \`intoss-private://aitc-sdk-example?_deploymentId=<uuid>\`. Use the URL printed by \`ait deploy --scheme-only\` — it includes the correct app name as the host.`;
+	return null;
+}
+function stripExisting(query, key) {
+	if (query === "") return "";
+	return query.split("&").filter((pair) => pair !== "" && pair.split("=")[0] !== key).join("&");
+}
+/**
+* Splices `debug=1`, `relay=<wssUrl>`, and (optionally) `at=<totpCode>` into a
+* scheme URL's query string, preserving everything else (scheme, authority,
+* path, hash, and the existing `_deploymentId` param). If any of the spliced
+* params is already present it is replaced so the helper is idempotent.
+*
+* @param schemeUrl - The `intoss-private://…?_deploymentId=<uuid>` URL printed
+*   by `ait deploy --scheme-only`. Must already carry `_deploymentId` (Layer B
+*   of the gate); this helper does not invent one.
+* @param wssUrl - The live relay URL (`wss://…trycloudflare.com`) from the
+*   running debug MCP server's quick tunnel.
+* @param totpCode - Optional current TOTP code (6 digits). When provided, it
+*   is spliced as `at=<totpCode>`. Must be computed at call time — it rotates
+*   every 30 s. Pass `undefined` or omit when TOTP is disabled.
+* @returns The same URL with `debug=1&relay=<encoded wssUrl>[&at=<totpCode>]`
+*   appended.
+* @throws If `wssUrl` is not a `wss:` URL (the gate rejects anything else, so
+*   producing such a link would be a silent dead end).
+*/
+function buildDeepLinkAttachUrl(schemeUrl, wssUrl, totpCode) {
+	let relay;
+	try {
+		relay = new URL(wssUrl);
+	} catch {
+		throw new Error(`relay URL is not a valid URL: ${wssUrl}`);
+	}
+	if (relay.protocol !== "wss:") throw new Error(`relay URL must use the wss: scheme, got ${relay.protocol} (${wssUrl})`);
+	const hashIndex = schemeUrl.indexOf("#");
+	const hash = hashIndex === -1 ? "" : schemeUrl.slice(hashIndex);
+	const beforeHash = hashIndex === -1 ? schemeUrl : schemeUrl.slice(0, hashIndex);
+	const queryIndex = beforeHash.indexOf("?");
+	const base = queryIndex === -1 ? beforeHash : beforeHash.slice(0, queryIndex);
+	let query = queryIndex === -1 ? "" : beforeHash.slice(queryIndex + 1);
+	const appended = [["debug", "1"], ["relay", wssUrl]];
+	if (totpCode !== void 0 && totpCode !== "") appended.push(["at", totpCode]);
+	query = stripExisting(query, "at");
+	for (const [key] of appended) query = stripExisting(query, key);
+	for (const [key, value] of appended) {
+		const pair = `${key}=${encodeURIComponent(value)}`;
+		query = query === "" ? pair : `${query}&${pair}`;
+	}
+	return `${base}?${query}${hash}`;
+}
+//#endregion
 //#region src/mcp/devtools-opener.ts
 /**
 * Base URL for the Chrome DevTools inspector hosted on appspot.
@@ -897,15 +1049,25 @@ function wrapEnvelope(data, ctx) {
 //#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.
+* Returns `true` when the environment is any relay variant (`relay-dev`,
+* `relay-live`, or `relay-mobile`). Use this instead of `env === 'relay'` for
+* tier checks — every relay env surfaces the Tier B / relay-only tool set.
+*
+* Written as an exhaustive switch so a future `McpEnvironment` member that is
+* missing an arm is a TS compile error rather than a silent `false`.
 */
 function isRelayEnv(env) {
-	return env === "relay-dev" || env === "relay-live";
+	switch (env) {
+		case "relay-dev":
+		case "relay-live":
+		case "relay-mobile": return true;
+		case "mock": return false;
+	}
 }
 /**
 * Returns `true` when the environment is the LIVE relay (`relay-live`).
-* This is the guard condition for side-effect tool protection.
+* This is the guard condition for side-effect tool protection. `relay-mobile`
+* is a dev-intent env (env 2 PWA) and is NOT live.
 */
 function isLiveRelayEnv(env) {
 	return env === "relay-live";
@@ -913,25 +1075,38 @@ function isLiveRelayEnv(env) {
 /**
 * Maps the `McpEnvironment` union to the legacy two-value union
 * (`'mock' | 'relay'`) for backward-compatible fields in diagnostics output.
+* Every relay variant (incl. `relay-mobile`) collapses to `'relay'`.
 */
 function toLegacyEnv(env) {
 	if (env === "mock") return "mock";
 	return "relay";
 }
 /**
-* Reconstructs the three-value `McpEnvironment` output string from the two
-* orthogonal signals (issue #348):
+* Reconstructs the four-value `McpEnvironment` output string from the
+* orthogonal signals (issues #348, #378):
+*
+*   - `kind === 'local'`                                          → `'mock'`
+*   - `kind === 'relay'` &&  liveIntent                           → `'relay-live'`
+*   - `kind === 'relay'` && !liveIntent && origin 'external-pwa'  → `'relay-mobile'`
+*   - `kind === 'relay'` && !liveIntent && origin intoss/undefined → `'relay-dev'`
 *
-*   - `kind === 'local'`                 → `'mock'`
-*   - `kind === 'relay'` &&  liveIntent  → `'relay-live'`
-*   - `kind === 'relay'` && !liveIntent  → `'relay-dev'`
+* `relayOrigin` is the booted-family discriminator (NOT sniffed from the URL)
+* that distinguishes the env-2 external-PWA relay (`relay-mobile`) from the
+* intoss-private dogfood relay (`relay-dev`); both are `kind: 'relay'`.
 *
 * Pure — used at every output boundary (envelope `meta.env`, `get_diagnostics`,
 * `measure_safe_area` provenance) so the surface never sniffs a URL again.
+*
+* Written switch-style so a missing arm is a TS compile error (never falls
+* through to a default).
 */
-function deriveEnvironment(kind, liveIntent) {
-	if (kind === "local") return "mock";
-	return liveIntent ? "relay-live" : "relay-dev";
+function deriveEnvironment(kind, liveIntent, relayOrigin) {
+	switch (kind) {
+		case "local": return "mock";
+		case "relay":
+			if (liveIntent) return "relay-live";
+			return relayOrigin === "external-pwa" ? "relay-mobile" : "relay-dev";
+	}
 }
 /**
 * Module-level `relay-dev` vs `relay-live` intent bit (issue #348).
@@ -1010,12 +1185,23 @@ function pageCrashError(toolName) {
 	return mcpError(`${toolName ? `${toolName}: ` : ""}페이지가 crash됐습니다. 토스 앱을 재실행한 뒤 build_attach_url → QR 스캔으로 재attach하세요.`);
 }
 /**
-* 상태 4: SDK 부재 — window.__sdkCall이 주입되지 않았다 (dogfood 빌드가 아님).
-*
-* call_sdk 호출 시 브리지가 없을 때.
+* 상태 4: SDK 부재 — window.__sdkCall이 주입되지 않았다.
+*
+* call_sdk 호출 시 브리지가 없을 때. 같은 "브리지 부재"라도 다음 행동은
+* connection 종류에 따라 정반대다 (issue #360):
+*   - relay(`--target` 없는 intoss / env-2): dogfood 빌드가 아니다 → dogfood
+*     채널로 재배포 후 QR 재스캔.
+*   - local(`--target=local`, env 1 로컬 브라우저): 재배포가 아니라 dev 서버를
+*     `pnpm dev`로 띄웠는지 + unplugin alias가 `@apps-in-toss/web-framework`를
+*     devtools mock으로 resolve하는지 확인. dev 빌드면 `import.meta.env.DEV`
+*     경로로 `window.__sdkCall`이 자동 설치된다.
+*
+* `isLocal`이 생략되면 relay 안내(이전 동작)를 유지한다.
 */
-function sdkAbsentError(toolName) {
-	return mcpError(`${toolName ? `${toolName}: ` : ""}window.__sdkCall이 주입되지 않았습니다 (dogfood 빌드가 아닙니다). dogfood 채널(intoss-private)로 재배포 후 QR을 다시 스캔하세요: \`ait build && aitcc app deploy\`.`);
+function sdkAbsentError(toolName, isLocal = false) {
+	const prefix = toolName ? `${toolName}: ` : "";
+	if (isLocal) return mcpError(`${prefix}window.__sdkCall이 주입되지 않았습니다 (로컬 dev 브리지 부재). sdk-example을 \`pnpm dev\`로 띄웠는지, 그리고 unplugin alias가 \`@apps-in-toss/web-framework\`를 devtools mock으로 resolve하는지 확인하세요. dev 빌드(\`import.meta.env.DEV\`)면 \`window.__sdkCall\`이 자동 설치됩니다.`);
+	return mcpError(`${prefix}window.__sdkCall이 주입되지 않았습니다 (dogfood 빌드가 아닙니다). dogfood 채널(intoss-private)로 재배포 후 QR을 다시 스캔하세요: \`ait build && aitcc app deploy\`.`);
 }
 /**
 * relay-live 환경에서 side-effect 도구(`call_sdk`, `evaluate`)를 `confirm: true`
@@ -1048,10 +1234,10 @@ function relayDisconnectError(toolName) {
 * - 연결 끊김 패턴 (`relay에 연결되어 있지 않습니다`, `relay WebSocket`) → relayDisconnectError
 * - 그 외 (일반 에러) → 원본 메시지를 포함한 mcpError
 */
-function classifyToolError(err, toolName) {
+function classifyToolError(err, toolName, isLocal = false) {
 	const message = err instanceof Error ? err.message : String(err);
 	if (message.startsWith("tunnel-down:") || message.includes("터널이 안 떠 있습니다")) return tunnelDownError();
-	if (message.startsWith("sdk-absent:") || message.includes("__sdkCall이 주입되지 않았습니다") || message.includes("window.__sdkCall is not available") || message.includes("__sdkCall") && message.includes("not available")) return sdkAbsentError(toolName);
+	if (message.startsWith("sdk-absent:") || message.includes("__sdkCall이 주입되지 않았습니다") || message.includes("window.__sdkCall is not available") || message.includes("__sdkCall") && message.includes("not available")) return sdkAbsentError(toolName, isLocal);
 	if (message.includes("replaced-by-new-attach") || message.includes("targetCrashed") || message.includes("targetDestroyed") || message.includes("detachedFromTarget")) return pageCrashError(toolName);
 	if (message.includes("relay에 연결되어 있지 않습니다") || message.includes("relay WebSocket")) return relayDisconnectError(toolName);
 	return mcpError(`${toolName} 실패: ${message}\nlist_pages로 미니앱이 relay에 attach됐는지 확인하세요.`);
@@ -1397,12 +1583,71 @@ async function launchChromium(options = {}) {
 /**
 * 로컬 HTTP 서버를 127.0.0.1 random port(또는 `AIT_DEBUG_HTTP_PORT` env)로 시작한다.
 * MCP debug server 생애주기에 묶어 사용 — `runDebugServer` shutdown 시 `close()`로 정리.
+*
+* @param getDashboardState - dashboard 상태를 반환하는 클로저. 주입 시 `GET /` dashboard와
+*   `GET /events` SSE 스트림이 활성화된다. 미주입 시 두 라우트는 204/서비스 없음으로 응답.
 */
-async function startQrHttpServer() {
+async function startQrHttpServer(getDashboardState) {
 	const { default: QRCode } = await import("qrcode");
-	const server = createServer((req, res) => {
+	/** SSE 활성 연결 목록 — `notifyStateChange()` 시 전체 push. */
+	const sseClients = [];
+	/** SSE 연결 하나에 상태 이벤트를 flush한다. */
+	function pushStateToClient(res, state) {
+		const payload = JSON.stringify({
+			tunnel: {
+				up: state.tunnel.up,
+				wssUrl: state.tunnel.wssUrl
+			},
+			pages: state.pages,
+			attachUrl: state.attachUrl
+		});
+		res.write(`data: ${payload}\n\n`);
+	}
+	const server = createServer(async (req, res) => {
 		const [path, query = ""] = (req.url ?? "/").split("?", 2);
 		const params = new URLSearchParams(query ?? "");
+		if (path === "/") {
+			if (!getDashboardState) {
+				res.writeHead(204, { "Content-Type": "text/plain; charset=utf-8" });
+				res.end();
+				return;
+			}
+			const state = getDashboardState();
+			let qrDataUrl = null;
+			if (state.attachUrl) try {
+				qrDataUrl = await QRCode.toDataURL(state.attachUrl, {
+					type: "image/png",
+					errorCorrectionLevel: "M"
+				});
+			} catch {}
+			const html = buildDashboardHtml(state, qrDataUrl);
+			res.writeHead(200, {
+				"Content-Type": "text/html; charset=utf-8",
+				"Cache-Control": "no-store"
+			});
+			res.end(html);
+			return;
+		}
+		if (path === "/events") {
+			if (!getDashboardState) {
+				res.writeHead(204, { "Content-Type": "text/plain; charset=utf-8" });
+				res.end();
+				return;
+			}
+			res.writeHead(200, {
+				"Content-Type": "text/event-stream",
+				"Cache-Control": "no-cache",
+				Connection: "keep-alive",
+				"X-Accel-Buffering": "no"
+			});
+			pushStateToClient(res, getDashboardState());
+			sseClients.push(res);
+			req.once("close", () => {
+				const idx = sseClients.indexOf(res);
+				if (idx !== -1) sseClients.splice(idx, 1);
+			});
+			return;
+		}
 		if (path === "/attach") {
 			const encodedU = params.get("u") ?? "";
 			let attachUrl;
@@ -1476,6 +1721,13 @@ async function startQrHttpServer() {
 		buildAttachPageUrl(attachUrl) {
 			return `http://127.0.0.1:${port}/attach?u=${encodeURIComponent(attachUrl)}`;
 		},
+		notifyStateChange() {
+			if (!getDashboardState) return;
+			const state = getDashboardState();
+			for (const client of sseClients) try {
+				pushStateToClient(client, state);
+			} catch {}
+		},
 		close() {
 			return new Promise((resolve, reject) => {
 				server.close((err) => err ? reject(err) : resolve());
@@ -1484,6 +1736,147 @@ async function startQrHttpServer() {
 	};
 }
 /**
+* Dashboard HTML — 터널/page/attachUrl 상태를 표시하고 SSE로 자동 갱신.
+*
+* SECRET-HANDLING:
+*   - attachUrl은 url-box 안에서만 노출 (TOTP at= 코드 캡슐 그대로).
+*   - tunnel wssUrl은 "터널 연결됨" 상태 표시에서 HOST가 아닌 UP/DOWN만 노출.
+*     wssUrl 값 자체는 dashboard HTML에 넣지 않는다 — 브라우저 탭이 보안 경계 밖에 있음.
+*   - inline <script>로 /events SSE 구독 — 빌드 파이프라인 추가 없음.
+*/
+function buildDashboardHtml(state, qrDataUrl) {
+	const tunnelStatus = state.tunnel.up ? "연결됨" : "끊어짐";
+	const tunnelClass = state.tunnel.up ? "status-up" : "status-down";
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	const pagesHtml = state.pages.length > 0 ? state.pages.map((p) => {
+		return `<li><span class="page-id">${p.id.replace(/[<>&"']/g, (c) => `&#${c.charCodeAt(0)};`)}</span> <span class="page-url">${p.url.slice(0, 120).replace(/[<>&"']/g, (c) => `&#${c.charCodeAt(0)};`)}</span></li>`;
+	}).join("\n") : "<li class=\"empty\">attach된 페이지 없음</li>";
+	let attachSection;
+	if (qrDataUrl && state.attachUrl) attachSection = `
+      <img class="qr" src="${qrDataUrl}" alt="attach QR" />
+      <p class="url-box">${state.attachUrl.replace(/[<>&"']/g, (c) => `&#${c.charCodeAt(0)};`)}</p>`;
+	else attachSection = "<p class=\"hint\">build_attach_url MCP tool을 호출하면 QR이 여기에 표시됩니다.</p>";
+	return `<!DOCTYPE html>
+<html lang="ko">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>AIT 디버그 Dashboard</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      background: #0d1117; color: #c9d1d9;
+      display: flex; flex-direction: column; align-items: center;
+      min-height: 100vh; margin: 0; padding: 2rem 1rem;
+      gap: 1.5rem;
+    }
+    h1 { font-size: 1.25rem; font-weight: 600; color: #e6edf3; margin: 0; text-align: center; }
+    .updated { font-size: 0.75rem; opacity: 0.4; font-family: monospace; margin: 0; }
+    section { width: 100%; max-width: 520px; }
+    h2 { font-size: 1rem; font-weight: 600; color: #e6edf3; margin: 0 0 0.5rem; }
+    .status { display: inline-block; padding: 0.25rem 0.75rem; border-radius: 999px; font-size: 0.8rem; font-weight: 600; }
+    .status-up { background: #238636; color: #fff; }
+    .status-down { background: #6e7681; color: #fff; }
+    img.qr {
+      width: min(80vw, 300px); height: auto;
+      image-rendering: pixelated;
+      background: #fff; padding: 0.75rem; border-radius: 10px;
+      display: block; margin: 0.5rem auto;
+    }
+    .url-box {
+      font-family: monospace; font-size: 0.7rem;
+      word-break: break-all; opacity: 0.45;
+      background: #161b22; padding: 0.6rem 0.85rem;
+      border-radius: 6px; border: 1px solid #30363d; margin: 0.5rem 0 0;
+    }
+    .hint { font-size: 0.85rem; opacity: 0.5; margin: 0.25rem 0 0; }
+    ul { margin: 0; padding-left: 1.25rem; }
+    li { margin-bottom: 0.35rem; font-size: 0.85rem; line-height: 1.5; }
+    li.empty { opacity: 0.4; list-style: none; padding-left: 0; }
+    .page-id { font-family: monospace; font-size: 0.75rem; opacity: 0.5; margin-right: 0.4rem; }
+    .page-url { word-break: break-all; }
+    hr { border: none; border-top: 1px solid #21262d; width: 100%; margin: 0; }
+  </style>
+</head>
+<body>
+  <h1>AIT 디버그 Dashboard</h1>
+  <p class="updated" id="updated">마지막 갱신: ${now}</p>
+
+  <section>
+    <h2>터널 상태</h2>
+    <span class="status ${tunnelClass}" id="tunnel-status">${tunnelStatus}</span>
+  </section>
+
+  <hr />
+
+  <section>
+    <h2>Attach QR</h2>
+    <div id="attach-section">${attachSection}</div>
+  </section>
+
+  <hr />
+
+  <section>
+    <h2>연결된 Pages</h2>
+    <ul id="pages-list">${pagesHtml}</ul>
+  </section>
+
+  <script>
+    // SSE — /events 구독해 상태 자동 갱신. 빌드 파이프라인 없는 인라인 스크립트.
+    (function () {
+      var src = new EventSource('/events');
+      src.onmessage = function (e) {
+        try {
+          var s = JSON.parse(e.data);
+          // 터널 상태 갱신
+          var el = document.getElementById('tunnel-status');
+          if (el) {
+            el.textContent = s.tunnel && s.tunnel.up ? '연결됨' : '끊어짐';
+            el.className = 'status ' + (s.tunnel && s.tunnel.up ? 'status-up' : 'status-down');
+          }
+          // page 목록 갱신
+          var ul = document.getElementById('pages-list');
+          if (ul) {
+            if (!s.pages || s.pages.length === 0) {
+              ul.innerHTML = '<li class="empty">attach된 페이지 없음</li>';
+            } else {
+              ul.innerHTML = s.pages.map(function (p) {
+                var sid = String(p.id || '').slice(0, 36).replace(/[<>&"']/g, function (c) { return '&#' + c.charCodeAt(0) + ';'; });
+                var su = String(p.url || '').slice(0, 120).replace(/[<>&"']/g, function (c) { return '&#' + c.charCodeAt(0) + ';'; });
+                return '<li><span class="page-id">' + sid + '</span> <span class="page-url">' + su + '</span></li>';
+              }).join('');
+            }
+          }
+          // attachUrl QR 갱신 — attachUrl이 없으면 hint 표시.
+          var sec = document.getElementById('attach-section');
+          if (sec) {
+            if (s.attachUrl) {
+              // QR은 서버에서 새로 렌더한 /qr.png?u= 로 img src 교체.
+              // TOTP at= 코드는 attachUrl 안에 캡슐화 — 별도 노출 없음.
+              var encoded = encodeURIComponent(s.attachUrl);
+              var safeUrl = String(s.attachUrl).slice(0, 2000).replace(/[<>&"']/g, function (c) { return '&#' + c.charCodeAt(0) + ';'; });
+              sec.innerHTML =
+                '<img class="qr" src="/qr.png?u=' + encoded + '" alt="attach QR" />' +
+                '<p class="url-box">' + safeUrl + '</p>';
+            } else {
+              sec.innerHTML = '<p class="hint">build_attach_url MCP tool을 호출하면 QR이 여기에 표시됩니다.</p>';
+            }
+          }
+          // 갱신 시각
+          var upd = document.getElementById('updated');
+          if (upd) upd.textContent = '마지막 갱신: ' + new Date().toISOString();
+        } catch (_) { /* 파싱 오류 무시 */ }
+      };
+      src.onerror = function () {
+        // 재연결은 EventSource가 자동 처리 (spec 기본 동작).
+      };
+    })();
+  <\/script>
+</body>
+</html>`;
+}
+/**
 * QR 스캔 페이지 HTML 본문.
 * dark theme, inline style, 외부 fetch 없음.
 */
@@ -1560,6 +1953,112 @@ function buildAttachHtml(qrDataUrl, safeLabel, safeAttachUrl) {
 </html>`;
 }
 //#endregion
+//#region src/mcp/relay-secret-store.ts
+/**
+* Project-local relay TOTP secret store (#394 first-run auto-mint, #396 moved to
+* a project-local single file `.ait_relay`).
+*
+* Two surfaces, intentionally split by who is allowed to write:
+*
+*   - {@link ensureRelaySecret} — WRITE path, called ONLY from the unplugin
+*     (env-2 relay boot). Mints a fresh secret on first run and persists it to
+*     `<projectRoot>/.ait_relay` (0600). A single file — no directory is created.
+*
+*   - {@link loadRelaySecretReadOnly} — READ-ONLY path, called from the MCP
+*     daemon when switching into a relay environment. It NEVER mints, chmods, or
+*     creates anything: it only reads an already-existing `.ait_relay` and injects
+*     its value into `env`. A daemon that minted would defeat the #250 fail-fast
+*     (the daemon is the verifier side — a self-minted secret would let a leaked
+*     tunnel URL attach unauthenticated), so the daemon stays read-only.
+*
+* Why a per-session `projectRoot` instead of `process.cwd()`: the daemon cannot
+* trust its own cwd — agent-plugin spawns it via `npx` without `cwd`, so cwd is
+* frozen at Claude Code launch and a cwd-walk stops at the monorepo workspace
+* root (which always has a package.json). So the project root is supplied
+* per-debug-session through `start_debug`.
+*
+* SECRET-HANDLING: this module handles AIT_DEBUG_TOTP_SECRET — the raw value and
+* its length MUST NOT appear in any log, error message, stdout, stderr, or
+* assertion output. Only boolean pass/fail signals are safe to surface, and the
+* discovered file path is never logged either. The persist file is written mode
+* 0600.
+*/
+/** Project-local secret file name (single file, not a directory). */
+const RELAY_SECRET_FILE_NAME = ".ait_relay";
+/**
+* Walks upward from `start` and returns the nearest directory that contains a
+* `package.json`. Falls back to `start` itself when none is found (so a write
+* still lands somewhere deterministic).
+*
+* The write (unplugin) and read (daemon) sides use the SAME anchor so a secret
+* minted by `pnpm dev` is found by the daemon: real mini-apps keep
+* `vite.config.ts` and `package.json` in the same directory, so
+* `server.config.root === package.json-dir`. In a monorepo subdir the anchor is
+* the package's own directory — the one the daemon can also reach via the
+* per-session projectRoot.
+*
+* @param start - Directory to start the upward walk from.
+* @param existsSyncFn - Injectable existence check (defaults to node:fs).
+*/
+function nearestPackageJsonDir(start, existsSyncFn) {
+	let dir = start;
+	while (true) {
+		if (existsSyncFn(join(dir, "package.json"))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return start;
+		dir = parent;
+	}
+}
+/**
+* Absolute path to the project-local `.ait_relay` file for a given start
+* directory (resolved against the nearest package.json directory).
+*
+* Exported so tests can compute the expected path without duplicating the
+* resolution logic.
+*/
+function relaySecretFilePath(start, existsSyncFn) {
+	return join(nearestPackageJsonDir(start, existsSyncFn), RELAY_SECRET_FILE_NAME);
+}
+/**
+* Reads an already-existing `<projectRoot>/.ait_relay` and, if its contents are a
+* valid relay TOTP secret, injects them into `env.AIT_DEBUG_TOTP_SECRET`.
+*
+* Strictly READ-ONLY: it uses only `existsSync` + `readFileSync` and NEVER mints,
+* chmods, or creates files/directories. The daemon must not mint because it is
+* the relay verifier side — a self-minted secret would defeat the #250 fail-fast
+* (a leaked tunnel URL could then attach unauthenticated). If no valid secret is
+* found the function leaves `env` untouched and returns without throwing, so the
+* downstream `assertRelayAuthConfigured()` stays the single fail-fast.
+*
+* Resolution order:
+*   1. `env.AIT_DEBUG_TOTP_SECRET` already valid → no-op (operator export wins).
+*   2. `projectRoot` given → read `<nearest package.json dir>/.ait_relay`; inject
+*      iff the contents pass {@link isValidRelayAuthSecret}.
+*   3. Otherwise (no projectRoot, file absent, or invalid) → silent no-op.
+*
+* SECRET-HANDLING: the read value is passed ONLY to the boolean predicate before
+* assignment; its value, length, and the discovered file path are never logged.
+*
+* @param deps - Optional dependency overrides for testing.
+*/
+async function loadRelaySecretReadOnly(deps) {
+	const { projectRoot, env = process.env, fs: fsDep, existsSync: existsSyncDep } = deps ?? {};
+	const { isValidRelayAuthSecret } = await import("../totp-CQFmgOhM.js");
+	if (isValidRelayAuthSecret(env.AIT_DEBUG_TOTP_SECRET)) return;
+	if (projectRoot === void 0) return;
+	const fs = fsDep ?? await import("node:fs");
+	const secretPath = relaySecretFilePath(projectRoot, existsSyncDep ?? fs.existsSync);
+	if (!fs.existsSync(secretPath)) return;
+	let stored;
+	try {
+		stored = fs.readFileSync(secretPath, "utf8").trim();
+	} catch {
+		return;
+	}
+	if (!isValidRelayAuthSecret(stored)) return;
+	env.AIT_DEBUG_TOTP_SECRET = stored;
+}
+//#endregion
 //#region src/mcp/server-lock.ts
 /**
 * Single debug session lock for the `devtools-mcp` debug server.
@@ -1722,138 +2221,26 @@ function acquireLock(options = {}) {
 		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,
-		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.
-*
-* `ait deploy --scheme-only` prints an `intoss-private://…?_deploymentId=<uuid>`
-* URL that opens a dogfood bundle on a phone. The in-app debug gate
-* (`src/in-app/gate.ts`) auto-attaches when the entry URL also carries
-* `debug=1` and `relay=<wss-url>`. This helper splices those params (plus
-* `at=<code>` when TOTP is enabled) into the scheme URL; rendering the result
-* as a QR code and scanning it with the phone camera opens the mini-app and
-* attaches it to the live Chii relay. QR is the single entry path — it needs
-* no USB cable, platform CLI, or driver, and works the same on iOS/Android.
-*
-* The Toss app propagates extra query params from the entry deep link into the
-* mini-app WebView's `location.search` (confirmed behavior), so the gate reads
-* them at attach time.
-*
-* TOTP `at=` param:
-*   When a TOTP secret is active, `buildDeepLinkAttachUrl` accepts an optional
-*   `totpCode` argument and splices `at=<code>` alongside `debug` and `relay`.
-*   The code must be computed by the caller at call time — do NOT pre-compute
-*   and cache it, because the 30-second window expires quickly. The in-app gate
-*   (`src/in-app/gate.ts` Layer C) validates this code against the baked secret.
-*
-* Why not `URL`/`URLSearchParams`: `intoss-private:` is a non-special scheme.
-* The WHATWG `URL` parser treats such schemes opaquely (no host/path/query
-* decomposition you can rely on across runtimes), so query manipulation via
-* `url.searchParams` is not portable here. We splice the query string directly
-* on the raw string instead, which keeps the scheme, authority, path, and any
-* pre-existing params (notably `_deploymentId`) byte-for-byte intact.
-*/
-/**
-* Suspicious/generic authority values that indicate a malformed or placeholder
-* scheme URL. These are host strings that will almost certainly cause the Toss
-* app to fail with "bundle not found" silently.
-*
-* The expected form from `ait deploy --scheme-only` is:
-*   intoss-private://<appName>?_deploymentId=<uuid>
-* where `<appName>` is a non-generic string like `aitc-sdk-example`.
-*/
-const SUSPICIOUS_AUTHORITIES = new Set([
-	"",
-	"web",
-	"localhost",
-	"127.0.0.1",
-	"app"
-]);
-/**
-* Validates the authority (host) portion of a scheme URL.
-*
-* Returns a warning message if the authority is missing or looks like a
-* placeholder, or `null` if the authority looks valid.
-*
-* Expected form: `intoss-private://<appName>?_deploymentId=<uuid>`
-* The authority must be a non-empty, non-generic app name (e.g. `aitc-sdk-example`).
-*/
-function validateSchemeAuthority(schemeUrl) {
-	const afterScheme = schemeUrl.replace(/^[a-zA-Z][a-zA-Z0-9+\-.]*:\/\//, "");
-	if (afterScheme === schemeUrl) return "scheme_url does not look like a scheme URL (expected `intoss-private://<appName>?_deploymentId=<uuid>`). Use the URL printed by `ait deploy --scheme-only`.";
-	const authorityEnd = afterScheme.search(/[/?#]/);
-	const authority = authorityEnd === -1 ? afterScheme : afterScheme.slice(0, authorityEnd);
-	if (SUSPICIOUS_AUTHORITIES.has(authority.toLowerCase())) return `scheme_url authority ${authority === "" ? "(empty)" : `"${authority}"`} looks like a placeholder. Expected an app name like \`intoss-private://aitc-sdk-example?_deploymentId=<uuid>\`. Use the URL printed by \`ait deploy --scheme-only\` — it includes the correct app name as the host.`;
-	return null;
-}
-function stripExisting(query, key) {
-	if (query === "") return "";
-	return query.split("&").filter((pair) => pair !== "" && pair.split("=")[0] !== key).join("&");
-}
-/**
-* Splices `debug=1`, `relay=<wssUrl>`, and (optionally) `at=<totpCode>` into a
-* scheme URL's query string, preserving everything else (scheme, authority,
-* path, hash, and the existing `_deploymentId` param). If any of the spliced
-* params is already present it is replaced so the helper is idempotent.
-*
-* @param schemeUrl - The `intoss-private://…?_deploymentId=<uuid>` URL printed
-*   by `ait deploy --scheme-only`. Must already carry `_deploymentId` (Layer B
-*   of the gate); this helper does not invent one.
-* @param wssUrl - The live relay URL (`wss://…trycloudflare.com`) from the
-*   running debug MCP server's quick tunnel.
-* @param totpCode - Optional current TOTP code (6 digits). When provided, it
-*   is spliced as `at=<totpCode>`. Must be computed at call time — it rotates
-*   every 30 s. Pass `undefined` or omit when TOTP is disabled.
-* @returns The same URL with `debug=1&relay=<encoded wssUrl>[&at=<totpCode>]`
-*   appended.
-* @throws If `wssUrl` is not a `wss:` URL (the gate rejects anything else, so
-*   producing such a link would be a silent dead end).
-*/
-function buildDeepLinkAttachUrl(schemeUrl, wssUrl, totpCode) {
-	let relay;
-	try {
-		relay = new URL(wssUrl);
-	} catch {
-		throw new Error(`relay URL is not a valid URL: ${wssUrl}`);
-	}
-	if (relay.protocol !== "wss:") throw new Error(`relay URL must use the wss: scheme, got ${relay.protocol} (${wssUrl})`);
-	const hashIndex = schemeUrl.indexOf("#");
-	const hash = hashIndex === -1 ? "" : schemeUrl.slice(hashIndex);
-	const beforeHash = hashIndex === -1 ? schemeUrl : schemeUrl.slice(0, hashIndex);
-	const queryIndex = beforeHash.indexOf("?");
-	const base = queryIndex === -1 ? beforeHash : beforeHash.slice(0, queryIndex);
-	let query = queryIndex === -1 ? "" : beforeHash.slice(queryIndex + 1);
-	const appended = [["debug", "1"], ["relay", wssUrl]];
-	if (totpCode !== void 0 && totpCode !== "") appended.push(["at", totpCode]);
-	query = stripExisting(query, "at");
-	for (const [key] of appended) query = stripExisting(query, key);
-	for (const [key, value] of appended) {
-		const pair = `${key}=${encodeURIComponent(value)}`;
-		query = query === "" ? pair : `${query}&${pair}`;
-	}
-	return `${base}?${query}${hash}`;
+	else 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/sdk-signatures.ts
@@ -2012,83 +2399,6 @@ 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 = [
@@ -2124,13 +2434,13 @@ 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. 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.",
+		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. Builds a self-attaching deep link for the active relay environment and returns a QR code. 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). Call list_pages first to confirm the relay/tunnel is up. If the tunnel is not up, restart: `npx @ait-co/devtools devtools-mcp`.\n\nEnvironment-specific behaviour:\n  • env 3 / relay-staging (start_debug mode=\"relay-staging\"): requires scheme_url — the intoss-private://…?_deploymentId=<uuid> URL from `ait deploy --scheme-only`. Splices debug=1 + relay URL into the scheme URL to produce a self-attach deep link.\n  • env 2 / relay-sandbox (start_debug mode=\"relay-sandbox\"): scheme_url is NOT used. Instead, reads AIT_TUNNEL_BASE_URL (the https://*.trycloudflare.com app tunnel from `tunnel:{cdp:true}`) and builds a launcher PWA deep-link (https://devtools.aitc.dev/launcher/?url=…&debug=1&relay=…). Scan the QR with the phone to open the launcher, which frames the tunnel URL and attaches CDP.\n\nSet wait_for_attach=true to block until a page attaches (polls up to 30 s). 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). \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: {
 				scheme_url: {
 					type: "string",
-					description: "The intoss-private:// scheme URL from `ait deploy --scheme-only` (must carry _deploymentId). The authority (host) must be the app name (e.g. intoss-private://aitc-sdk-example?_deploymentId=…). Generic values like \"web\" or an empty host indicate a malformed URL."
+					description: "The intoss-private:// scheme URL from `ait deploy --scheme-only` (must carry _deploymentId). Required for env 3/relay-staging mode. Not used in env 2/relay-sandbox mode (use AIT_TUNNEL_BASE_URL instead). The authority (host) must be the app name (e.g. intoss-private://aitc-sdk-example?_deploymentId=…). Generic values like \"web\" or an empty host indicate a malformed URL."
 				},
 				wait_for_attach: {
 					type: "boolean",
@@ -2141,7 +2451,7 @@ const DEBUG_TOOL_DEFINITIONS = [
 					description: "If true (default), render the QR as a PNG and open it in the OS default browser. Only works when the MCP server is running on a local GUI machine — headless or remote container environments should set this to false to use the text QR fallback."
 				}
 			},
-			required: ["scheme_url"]
+			required: []
 		},
 		availableIn: "relay"
 	},
@@ -2219,7 +2529,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 3/4 (real device relay) this hits the real SDK; on env 1 (local mock) it hits the mock SDK. (env 2 PWA does not inject the SDK — call_sdk is not available there.) 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\", [])",
+		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 3/4 (real device relay) this hits the real SDK; on env 1 (local mock) and env 2 (PWA relay — real WebKit, mock SDK) 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 — on relay (env 3/4) that means a non-dogfood bundle (redeploy via `ait build && aitcc app deploy`); on local (--target=local, env 1) it means the dev bridge is not installed (start the dev server with `pnpm dev`).\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: {
@@ -2273,23 +2583,27 @@ const DEBUG_TOOL_DEFINITIONS = [
 	},
 	{
 		name: "start_debug",
-		description: "Switches the active debug environment in-place (issue #348) — no Claude Code restart and no MCP re-handshake. One daemon holds both a local (env 1, mock SDK in a Chromium) and a relay (env 3/4, real-device Toss WebView over the Chii relay + cloudflared tunnel) connection at once; this tool flips which one every other tool reads from, lazily booting the requested family's infra on first use and keeping the inactive one warm so an existing attach survives the switch. After switching it emits notifications/tools/list_changed — call tools/list again to see the updated tool surface for the new environment.\n\nmodes:\n  local-browser-dev / local-browser-cdp — local Chromium CDP attach (env 1, mock). Both route to the local connection; the names preserve dev-vs-cdp intent.\n  relay-dev  — real-device dogfood relay (env 3). Side-effect tools run unguarded.\n  relay-live — real-device live/production relay (env 4, read-only debugging). Arms the LIVE guard: call_sdk/evaluate then require confirm: true. Entering relay-live ALSO requires confirm: true on this call to acknowledge LIVE intent.\n\nSwitching back to a local mode automatically disarms the LIVE guard.",
+		description: "Switches the active debug environment in-place (issue #348) — no Claude Code restart and no MCP re-handshake. One daemon holds both a local (env 1, mock SDK in a Chromium) and a relay (env 3/4, real-device Toss WebView over the Chii relay + cloudflared tunnel) connection at once; this tool flips which one every other tool reads from, lazily booting the requested family's infra on first use and keeping the inactive one warm so an existing attach survives the switch. After switching it emits notifications/tools/list_changed — call tools/list again to see the updated tool surface for the new environment.\n\nmodes:\n  local-browser — env 1: desktop Chromium with the MOCK SDK and a local CDP attach. Side-effect tools (call_sdk/evaluate) run unguarded against the mock; nothing touches a real device or real users. No prerequisites — the default, always-available environment for state/contract and visual-layout work.\n  relay-sandbox — env 2: a real-device PWA (real WebKit engine, MOCK SDK) over an external Chii relay that the unplugin already started with tunnel:{cdp:true}. CDP covers real-device WebKit DOM, console, exceptions, and safe-area observation; call_sdk still hits the mock (SDK fidelity needs relay-staging). liveIntent off — dev-intent, LIVE guard inactive, side-effect tools run unguarded against the mock. Prerequisites: AIT_RELAY_BASE_URL env var set + unplugin running with tunnel:{cdp:true} so the relay tunnel is already up.\n  relay-staging — env 3: a real-device Toss WebView dogfood build with the REAL SDK over the intoss-private relay. The first environment where call_sdk exercises the genuine native bridge. Side-effect tools run unguarded (dogfood, not released to real users). Prerequisite: a deployed dogfood candidate bundle + the device cold-loaded via the intoss-private deep-link/QR relay injection.\n  relay-live — env 4: the REVIEW-PASSED, released production runtime with the REAL SDK over the intoss relay — real end users are on the other side. Read-only debugging is the intent: the LIVE guard is armed, so call_sdk/evaluate require confirm:true per call, and ENTERING relay-live ALSO requires confirm:true on this call. Use it only to observe a shipped regression; verify fixes in relay-staging first.\n\nSwitching back to local-browser automatically disarms the LIVE guard.\n\nFor a relay mode (relay-sandbox/relay-staging/relay-live), also pass projectRoot — the absolute mini-app project root — so the daemon can read the relay auth secret from <projectRoot>/.ait_relay (read-only; the daemon never mints it). Omit it for local-browser.",
 		inputSchema: {
 			type: "object",
 			properties: {
 				mode: {
 					type: "string",
 					enum: [
-						"local-browser-dev",
-						"local-browser-cdp",
-						"relay-dev",
+						"local-browser",
+						"relay-sandbox",
+						"relay-staging",
 						"relay-live"
 					],
-					description: "Target environment to switch to. relay-live additionally requires confirm: true."
+					description: "Target environment to switch to. mode=relay-live additionally requires confirm: true (and arms the read-only LIVE guard)."
 				},
 				confirm: {
 					type: "boolean",
 					description: "Required when mode=relay-live — set true to acknowledge entering LIVE (env 4) debugging that can affect real users. Ignored for the other modes."
+				},
+				projectRoot: {
+					type: "string",
+					description: "Absolute path to the mini-app project root (the directory containing its package.json and .ait_relay). The daemon reads the relay auth secret from <projectRoot>/.ait_relay (read-only) when switching to a relay environment (relay-staging/relay-live/relay-sandbox). Pass this because the daemon's own cwd is fixed at launch and may not be the project being debugged. Omit for mode=local-browser (no secret needed)."
 				}
 			},
 			required: ["mode"]
@@ -2298,7 +2612,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 (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; in local-target mode tunnel.up=false is normal so \"restart\" is never recommended). 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.",
+		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|relay-mobile, 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; in local-target mode tunnel.up=false is normal so \"restart\" is never recommended). 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: {
@@ -2328,8 +2642,8 @@ function getToolAvailability(name) {
 * 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.
+* Relay variants (`relay-dev`, `relay-live`, `relay-mobile`) all satisfy the
+* `'relay'` availability tier — `isRelayEnv()` is used for the check.
 */
 function isToolAvailableIn(name, env) {
 	const availability = getToolAvailability(name);
@@ -2343,7 +2657,8 @@ function isToolAvailableIn(name, env) {
 * 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.
+* Relay variants (`relay-dev`, `relay-live`, `relay-mobile`) all satisfy the
+* `'relay'` tier.
 */
 function filterToolsByEnvironment(tools, env) {
 	return tools.filter((t) => t.availableIn === "both" || t.availableIn === "relay" && isRelayEnv(env) || t.availableIn === env);
@@ -2962,8 +3277,8 @@ function findRecentException(connection, windowStart, windowEnd) {
 * Calls a dogfood SDK method via `window.__sdkCall` on the attached page.
 * NOT read-only — SDK calls may have side effects.
 *
-* On env 2/3 (real device relay) this hits the real SDK; on env 1 (local
-* mock) it hits the mock SDK.
+* On env 3/4 (toss WebView relay) this hits the real SDK. On env 1 (local
+* mock) and env 2 (PWA relay — real WebKit, mock SDK) it hits the mock SDK.
 *
 * 인자 시그니처 검증: 등록된 메서드는 bridge 호출 전에 인자를 검증하고, mismatch면
 * `{ok:false, error}` MCP 오류 결과를 반환한다(bridge에 도달하지 않음).
@@ -3117,7 +3432,7 @@ async function readMcpSdkVersion() {
 * some test environments that skip the build step).
 */
 function readDevtoolsVersion() {
-	return "0.1.55";
+	return "0.1.57";
 }
 /**
 * Derives the next recommended action from a completed diagnostics snapshot.
@@ -3534,9 +3849,14 @@ function extractDeploymentId(schemeUrl) {
 		return null;
 	}
 }
-/** Returns `true` when the mode routes to a relay connection. */
+/**
+* Returns `true` when the mode routes to a relay connection (`relay-sandbox`,
+* `relay-staging`, or `relay-live`). `relay-sandbox` is an external-PWA relay;
+* `relay-staging`/`relay-live` are intoss-private relays — but all three surface
+* the Tier B / relay-only tool set.
+*/
 function isRelayMode(mode) {
-	return mode === "relay-dev" || mode === "relay-live";
+	return mode === "relay-sandbox" || mode === "relay-staging" || mode === "relay-live";
 }
 /**
 * Waits for the first target matching `filterFn` to attach, using the
@@ -3592,14 +3912,15 @@ function waitForAttachWithEvents(connection, filterFn, timeoutMs, pollIntervalMs
 * naturally via `enableDomains`). The tier only controls visibility.
 */
 function createDebugServer(deps) {
-	const { connection, router: routerDep, aitSource, getTunnelStatus, waitForAttachTimeoutMs = 9e4, qrHttpServer, getEnvironment: getEnvDep, getEnvironmentReason: getEnvReasonDep, diagnosticsCollector: collectorDep, totpSecret } = deps;
+	const { connection, router: routerDep, aitSource, getTunnelStatus, waitForAttachTimeoutMs = 9e4, qrHttpServer, getEnvironment: getEnvDep, getEnvironmentReason: getEnvReasonDep, diagnosticsCollector: collectorDep, totpSecret, onAttachUrlBuilt } = deps;
+	const getTotpSecret = deps.getTotpSecret ?? (() => totpSecret);
 	const router = routerDep ?? makeSingleConnectionRouter(connection);
-	const resolveEnvironment = getEnvDep ?? (() => deriveEnvironment(router.active.kind, getLiveIntent()));
+	const resolveEnvironment = getEnvDep ?? (() => deriveEnvironment(router.active.kind, getLiveIntent(), router.activeRelayOrigin));
 	const resolveEnvironmentReason = getEnvReasonDep ?? (() => `derived:kind=${router.active.kind},liveIntent=${getLiveIntent()}`);
 	const collector = collectorDep ?? new InMemoryDiagnosticsCollector();
 	const server = new Server({
 		name: "ait-debug",
-		version: "0.1.55"
+		version: "0.1.57"
 	}, { capabilities: { tools: { listChanged: true } } });
 	server.setRequestHandler(ListToolsRequestSchema, () => {
 		const conn = router.active;
@@ -3621,10 +3942,12 @@ function createDebugServer(deps) {
 		if (name === "start_debug") {
 			const rawMode = request.params.arguments?.mode;
 			const mode = normalizeStartDebugMode(rawMode);
-			if (mode === null) return mcpError("start_debug: mode가 올바르지 않습니다. 'local-browser-dev' | 'local-browser-cdp' | 'relay-dev' | 'relay-live' 중 하나를 전달하세요.");
+			if (mode === null) return mcpError("start_debug: mode가 올바르지 않습니다. 'local-browser' | 'relay-sandbox' | 'relay-staging' | 'relay-live' 중 하나를 전달하세요.");
 			const confirm = request.params.arguments?.confirm === true;
+			const rawProjectRoot = request.params.arguments?.projectRoot;
+			const projectRoot = typeof rawProjectRoot === "string" ? rawProjectRoot : void 0;
 			try {
-				return jsonResult$1(await router.switchMode(mode, confirm));
+				return jsonResult$1(await router.switchMode(mode, confirm, projectRoot));
 			} catch (err) {
 				return errorResult(err, name);
 			}
@@ -3669,10 +3992,179 @@ function createDebugServer(deps) {
 			return errorResult(err, name);
 		}
 		if (name === "build_attach_url") {
-			const schemeUrl = request.params.arguments?.scheme_url;
-			if (typeof schemeUrl !== "string" || schemeUrl === "") return mcpError("build_attach_url: scheme_url이 비어 있습니다. `ait deploy --scheme-only`가 출력하는 intoss-private:// URL을 인자로 전달하세요.");
 			const waitForAttach = request.params.arguments?.wait_for_attach === true;
 			const openInBrowser = request.params.arguments?.open_in_browser !== false;
+			if (env === "relay-mobile") {
+				const tunnelHttpUrl = process.env.AIT_TUNNEL_BASE_URL?.trim() ?? "";
+				if (tunnelHttpUrl === "") return mcpError("build_attach_url(mobile): AIT_TUNNEL_BASE_URL이 설정되지 않았습니다. unplugin tunnel:{cdp:true} 배너에 출력되는 앱 HTTP 터널 URL을 AIT_TUNNEL_BASE_URL 환경변수로 전달하세요.");
+				const tunnelStatus = getTunnelStatus();
+				if (!tunnelStatus.up || tunnelStatus.wssUrl === null) return mcpError("build_attach_url(mobile): relay wssUrl이 아직 설정되지 않았습니다. unplugin tunnel:{cdp:true}가 relay를 완전히 기동할 때까지 잠시 후 다시 시도하세요.");
+				const secret = getTotpSecret();
+				let totpCode;
+				let totpMeta;
+				if (secret !== void 0 && secret !== "") {
+					const now = Date.now();
+					totpCode = generateTotp(secret, now);
+					const STEP_SECONDS = 30;
+					const currentStep = Math.floor(now / 1e3 / STEP_SECONDS);
+					totpMeta = {
+						enabled: true,
+						ttlSeconds: STEP_SECONDS,
+						expiresAt: (/* @__PURE__ */ new Date((currentStep + 1) * STEP_SECONDS * 1e3)).toISOString()
+					};
+				}
+				const attachUrl = buildLauncherAttachUrl(tunnelHttpUrl, tunnelStatus.wssUrl, totpCode);
+				onAttachUrlBuilt?.(attachUrl);
+				const relayUrl = tunnelStatus.wssUrl;
+				const totp = totpMeta;
+				const isMatchingPage = (pages) => pages.length > 0;
+				const buildTimeoutError = (baseText, timeoutSec, observed) => {
+					const observedUrls = observed.slice(0, 3).map((p) => p.url.slice(0, 80)).join(", ");
+					return `${baseText}\n\nNo page attached within ${timeoutSec}s${observed.length > 0 ? ` — previously attached pages: [${observedUrls}]` : ""} — launcher QR을 폰 카메라로 스캔한 뒤 call list_pages를 다시 호출하세요.`;
+				};
+				return await (async () => {
+					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 warningPrefix = "";
+					const guiAvailable = canOpenBrowser();
+					if (openInBrowser && !guiAvailable) {
+						const headlessNote = "[open_in_browser] GUI 환경이 감지되지 않았습니다 (headless/remote 환경). open_in_browser=false로 자동 폴백합니다. 텍스트 QR을 폰 카메라로 스캔하거나, 로컬 GUI 환경에서 실행하세요.\n\n";
+						const qrHeadless = await renderQr(attachUrl);
+						const headlessText = `${warningPrefix}${headlessNote}${header}\n${JSON.stringify({
+							attachUrl,
+							relayUrl,
+							...totp ? { totp } : {}
+						}, null, 2)}\n\n${qrHeadless}`;
+						if (!waitForAttach) return { content: [{
+							type: "text",
+							text: headlessText
+						}] };
+						let attachedPagesHl = [];
+						try {
+							attachedPagesHl = await waitForAttachWithEvents(conn, isMatchingPage, waitForAttachTimeoutMs);
+						} catch {
+							attachedPagesHl = conn.listTargets();
+							return {
+								content: [{
+									type: "text",
+									text: buildTimeoutError(headlessText, waitForAttachTimeoutMs / 1e3, attachedPagesHl)
+								}],
+								isError: true
+							};
+						}
+						const pagesResultHl = listPages(conn, getTunnelStatus());
+						return { content: [{
+							type: "text",
+							text: `${headlessText}\n\n${JSON.stringify(pagesResultHl, null, 2)}`
+						}] };
+					}
+					if (openInBrowser && guiAvailable && qrHttpServer) {
+						const browserResult = await openQrInBrowser(qrHttpServer.buildAttachPageUrl(attachUrl), `http://127.0.0.1:${qrHttpServer.port}/qr.png?u=${encodeURIComponent(attachUrl)}`);
+						if (browserResult.opened) {
+							const retriedNote = browserResult.retried ? " (1회 retry 후 성공)" : "";
+							const openResult = {
+								attempted: true,
+								succeeded: true,
+								...browserResult.retried ? { retried: true } : {}
+							};
+							const shortText = `${warningPrefix}${header}\n${JSON.stringify({
+								relayUrl,
+								openResult,
+								...totp ? { totp } : {}
+							}, null, 2)}\n\n브라우저에서 QR을 열었습니다${retriedNote}. 폰 카메라로 스캔하세요.\nURL: ${browserResult.httpUrl}`;
+							if (!waitForAttach) return { content: [{
+								type: "text",
+								text: shortText
+							}] };
+							let attachedPages = [];
+							try {
+								attachedPages = await waitForAttachWithEvents(conn, isMatchingPage, waitForAttachTimeoutMs);
+							} catch {
+								attachedPages = conn.listTargets();
+								return {
+									content: [{
+										type: "text",
+										text: buildTimeoutError(shortText, waitForAttachTimeoutMs / 1e3, attachedPages)
+									}],
+									isError: true
+								};
+							}
+							const pagesResult = listPages(conn, getTunnelStatus());
+							return { content: [{
+								type: "text",
+								text: `${shortText}\n\n${JSON.stringify(pagesResult, null, 2)}`
+							}] };
+						}
+						const openResult = {
+							attempted: true,
+							succeeded: false,
+							failureReason: browserResult.error ?? "브라우저 실행 후보 모두 실패",
+							pngUrl: browserResult.pngUrl,
+							...browserResult.stderrSummary ? { stderrSummary: browserResult.stderrSummary } : {}
+						};
+						const stderrNote = browserResult.stderrSummary ? `\nstderr: ${browserResult.stderrSummary}` : "";
+						const fallbackNote = `[open_in_browser] 브라우저 자동 열기에 실패했습니다. 다음 URL을 직접 브라우저에서 여세요:\n${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stderrNote + "\n\n";
+						const qr = await renderQr(attachUrl);
+						const baseText = `${warningPrefix}${fallbackNote}${header}\n${JSON.stringify({
+							attachUrl,
+							relayUrl,
+							openResult,
+							...totp ? { totp } : {}
+						}, null, 2)}\n\n${qr}`;
+						if (!waitForAttach) return { content: [{
+							type: "text",
+							text: baseText
+						}] };
+						let attachedPagesFb = [];
+						try {
+							attachedPagesFb = await waitForAttachWithEvents(conn, isMatchingPage, waitForAttachTimeoutMs);
+						} catch {
+							attachedPagesFb = conn.listTargets();
+							return {
+								content: [{
+									type: "text",
+									text: buildTimeoutError(baseText, waitForAttachTimeoutMs / 1e3, attachedPagesFb)
+								}],
+								isError: true
+							};
+						}
+						const pagesResultFb = listPages(conn, getTunnelStatus());
+						return { content: [{
+							type: "text",
+							text: `${baseText}\n\n${JSON.stringify(pagesResultFb, null, 2)}`
+						}] };
+					}
+					const qr = await renderQr(attachUrl);
+					const baseText = `${warningPrefix}${header}\n${JSON.stringify({
+						attachUrl,
+						relayUrl,
+						...totp ? { totp } : {}
+					}, null, 2)}\n\n${qr}`;
+					if (!waitForAttach) return { content: [{
+						type: "text",
+						text: baseText
+					}] };
+					let attachedPages = [];
+					try {
+						attachedPages = await waitForAttachWithEvents(conn, isMatchingPage, waitForAttachTimeoutMs);
+					} catch {
+						attachedPages = conn.listTargets();
+						return {
+							content: [{
+								type: "text",
+								text: buildTimeoutError(baseText, waitForAttachTimeoutMs / 1e3, attachedPages)
+							}],
+							isError: true
+						};
+					}
+					const pagesResult = listPages(conn, getTunnelStatus());
+					return { content: [{
+						type: "text",
+						text: `${baseText}\n\n${JSON.stringify(pagesResult, null, 2)}`
+					}] };
+				})();
+			}
+			const schemeUrl = request.params.arguments?.scheme_url;
+			if (typeof schemeUrl !== "string" || schemeUrl === "") return mcpError("build_attach_url: scheme_url이 비어 있습니다. `ait deploy --scheme-only`가 출력하는 intoss-private:// URL을 인자로 전달하세요. 환경 2(mobile)라면 scheme_url 대신 AIT_TUNNEL_BASE_URL을 설정하세요.");
 			const deploymentId = extractDeploymentId(schemeUrl);
 			if (!deploymentId) logInfo("tool.call", {
 				tool: "build_attach_url",
@@ -3691,7 +4183,8 @@ 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, totp } = buildAttachUrl(schemeUrl, getTunnelStatus(), totpSecret);
+				const { attachUrl, relayUrl, authorityWarning, totp } = buildAttachUrl(schemeUrl, getTunnelStatus(), getTotpSecret());
+				onAttachUrlBuilt?.(attachUrl);
 				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();
@@ -3883,26 +4376,27 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 					const sdkArgs = Array.isArray(rawArgs) ? rawArgs : [];
 					if (conn.kind === "relay" && getLiveIntent() && request.params.arguments?.confirm !== true) return liveGuardError("call_sdk");
 					const sdkResult = await callSdk(conn, sdkName, sdkArgs);
-					if (!sdkResult.ok && typeof sdkResult.error === "string" && sdkResult.error.startsWith("sdk-absent:")) return sdkAbsentError("call_sdk");
+					if (!sdkResult.ok && typeof sdkResult.error === "string" && sdkResult.error.startsWith("sdk-absent:")) return sdkAbsentError("call_sdk", conn.kind === "local");
 					return envelopeResult$1(sdkResult, name, env, conn.listTargets().length > 0);
 				}
 				default: return unknownTool(name);
 			}
 		} catch (err) {
-			return errorResult(err, name);
+			return errorResult(err, name, conn.kind === "local");
 		}
 	});
 	return server;
 }
 /**
 * Normalizes a raw `start_debug` `mode` argument to a `StartDebugMode`, or
-* `null` when the value is not one of the four accepted modes.
+* `null` when the value is not one of the four accepted modes:
+*   'local-browser' | 'relay-sandbox' | 'relay-staging' | 'relay-live'
+*
+* Hard rename (issue #398): the older `local`/`mobile`/`staging`/`live` names
+* and their aliases are no longer accepted — pre-1.0, no back-compat.
 */
 function normalizeStartDebugMode(raw) {
-	if (raw === "local-browser-dev") return "local-browser-dev";
-	if (raw === "local-browser-cdp") return "local-browser-cdp";
-	if (raw === "relay-dev") return "relay-dev";
-	if (raw === "relay-live") return "relay-live";
+	if (raw === "local-browser" || raw === "relay-sandbox" || raw === "relay-staging" || raw === "relay-live") return raw;
 	return null;
 }
 /**
@@ -3919,7 +4413,9 @@ function makeSingleConnectionRouter(connection) {
 		get active() {
 			return connection;
 		},
-		switchMode(mode, confirm) {
+		activeRelayOrigin: void 0,
+		switchMode(mode, confirm, _projectRoot) {
+			if (mode === "relay-sandbox") return Promise.reject(/* @__PURE__ */ new Error("start_debug: 이 세션은 단일 연결만 보유합니다 — 'relay-sandbox'(환경 2 PWA, 외부 relay)로 동적 전환할 수 없습니다 (dual-connection 데몬에서만 지원). MCP 서버를 relay-sandbox 모드로 재시작하세요."));
 			if (isRelayMode(mode) !== (connection.kind === "relay")) return Promise.reject(/* @__PURE__ */ new Error(`start_debug: 이 세션은 단일 ${connection.kind} 연결만 보유합니다 — '${mode}'로 동적 전환할 수 없습니다 (dual-connection 데몬에서만 지원). MCP 서버를 원하는 모드로 재시작하세요.`));
 			if (mode === "relay-live" && !confirm) return Promise.reject(/* @__PURE__ */ new Error("start_debug: relay-live(실서비스 LIVE)는 confirm: true가 필요합니다 — 실유저에게 영향이 갈 수 있는 LIVE 디버깅 진입을 명시적으로 승인하세요."));
 			setLiveIntent(mode === "relay-live");
@@ -3978,8 +4474,8 @@ function classifyEnableDomainError(err, toolName) {
 * CDP/AIT 명령 실행 중 catch된 에러를 4상태로 분류해 tool 결과로 반환한다.
 * debug-server 내부 try/catch 블록에서 공통으로 사용한다.
 */
-function errorResult(err, name) {
-	return classifyToolError(err, name);
+function errorResult(err, name, isLocal = false) {
+	return classifyToolError(err, name, isLocal);
 }
 /**
 * Starts a polling watcher that detects the first 0→N target transition on
@@ -4059,34 +4555,12 @@ function startParentWatcher(onOrphaned, opts) {
 	} };
 }
 /**
-* Reads `AIT_DEBUG_TOTP_SECRET` from `process.env` at runtime and builds a
-* `verifyAuth` predicate for the Chii relay's WebSocket upgrade gate.
-*
-* The predicate checks the `at` query parameter against the current and
-* adjacent TOTP time steps (±1 skew) using `verifyTotp`.
-*
-* Returns `undefined` when the env var is not set — callers treat that as
-* "auth disabled" (no predicate registered on the relay).
-*
-* SECRET-HANDLING: The secret value read from env is captured in a closure and
-* is NEVER written to any log, error message, or process output.
-*/
-function buildRelayVerifyAuth() {
-	const secret = process.env.AIT_DEBUG_TOTP_SECRET;
-	if (!secret) return void 0;
-	return (req) => {
-		const rawUrl = req.url ?? "";
-		const qIndex = rawUrl.indexOf("?");
-		const queryStr = qIndex === -1 ? "" : rawUrl.slice(qIndex + 1);
-		return verifyTotp(secret, new URLSearchParams(queryStr).get("at") ?? "");
-	};
-}
-/**
 * Factory that constructs a `ChiiCdpConnection` for the given relay base URL.
 *
 * Introduced as a named seam so PR-2 (dual-connection, #348) can defer
-* construction to first-activation time by moving or replacing this call —
-* without changing the current eager construction order at startup.
+* construction to first-activation time by moving or replacing this call. Since
+* #396 every family (relay included) is constructed lazily on its first
+* `start_debug`, so this is always called from the lazy boot path.
 *
 * The relay base URL is only available after `startChiiRelay()` resolves, so
 * the factory is called right after that point (same as before this refactor).
@@ -4114,11 +4588,9 @@ var RoutingAitSource = class extends ChiiAitSource {
 * `--remote-debugging-port` and returns a `LocalCdpConnection` attached to it,
 * plus a `stop()` that kills both.
 *
-* Used two ways:
-*   - `runDebugServer` (relay-eager): the dual router's lazy callback, booted at
-*     most once on the first `start_debug({ mode: 'local-*' })`.
-*   - `runLocalDebugServer` (local-eager, #356): the eager family booted at
-*     startup.
+* Booted lazily via the dual router's `bootLazyFor('local-browser')` callback,
+* at most once on the first `start_debug({ mode: 'local-browser' })` (all-lazy,
+* #396 — no run function boots a family at startup anymore).
 */
 async function bootLocalFamily() {
 	const chromium = await launchChromium({
@@ -4143,10 +4615,10 @@ async function bootLocalFamily() {
 * `getTunnelStatus()` reflects the live tunnel (it flips up once the background
 * tunnel resolves and follows reissues).
 *
-* Used two ways (symmetry with {@link bootLocalFamily}):
-*   - `runDebugServer` (relay-eager): booted at startup.
-*   - `runLocalDebugServer` (local-eager, #356): the dual router's lazy
-*     callback, booted at most once on the first `start_debug({ mode: 'relay-*' })`.
+* Booted lazily via the dual router's `bootLazyFor('relay-intoss')` callback
+* (symmetry with {@link bootLocalFamily}), at most once on the first
+* `start_debug({ mode: 'relay-staging' | 'relay-live' })` (all-lazy, #396 — every
+* relay boot now flows through `switchMode` after the project-local secret load).
 *
 * The relay base URL is only known after `startChiiRelay()` resolves, so the
 * `ChiiCdpConnection` (via {@link createRelayConnection}) is constructed inside
@@ -4156,6 +4628,7 @@ async function bootLocalFamily() {
 * (relay host) is never logged here directly.
 */
 async function bootRelayFamily(options = {}) {
+	assertRelayAuthConfigured();
 	const relayPort = options.relayPort ?? 0;
 	const totpEnabled = options.verifyAuth !== void 0;
 	const relay = await startChiiRelay({
@@ -4205,6 +4678,7 @@ async function bootRelayFamily(options = {}) {
 	const connection = createRelayConnection(relay.baseUrl);
 	return {
 		connection,
+		relayOrigin: "intoss-webview",
 		getTunnelStatus: () => tunnelStatus,
 		stop() {
 			tunnelProbe?.stop();
@@ -4215,21 +4689,119 @@ async function bootRelayFamily(options = {}) {
 	};
 }
 /**
-* Production `ConnectionRouter` (issues #348, #356 — DUAL-CONNECTION-COEXIST).
-*
-* Holds two families — one booted eagerly at startup, the other lazily on the
-* first cross-family switch — an `active` pointer, and the single attach watcher
-* armed on the active connection. The router is **direction-neutral** (#356):
-* either family kind can be the eager one, so a `--target=local` session can
-* hot-switch into relay (and vice versa) without restarting the MCP server.
+* Boots the EXTERNAL relay family for env 2 (real-device PWA, issue #378).
+*
+* Unlike {@link bootRelayFamily}, this does NOT start a relay or a tunnel —
+* the unplugin (`tunnel: { cdp: true }`) already brought up a Chii relay for
+* the env-2 PWA and exposed its public base URL via `AIT_RELAY_BASE_URL`. Here
+* the MCP only opens a CDP client (`createRelayConnection`) against that
+* external relay. The relay's lifecycle is owned by the unplugin, so `stop()`
+* closes ONLY the CDP client — it must never tear down the relay or a tunnel
+* we did not start.
+*
+* `getTunnelStatus()` reports `up: true` with a `wssUrl` derived from
+* `relayBaseUrl` (http→ws, https→wss) so the `build_attach_url` gate
+* (`up: true && wssUrl !== null`) is satisfied even though we never opened a
+* cloudflared tunnel ourselves.
+*
+* SECRET-HANDLING: `relayBaseUrl` carries the relay host (same sensitivity as a
+* wss URL) — it is NEVER logged here. The caller validates presence and passes
+* the value straight to the CDP client.
+*/
+async function bootExternalRelayFamily(relayBaseUrl) {
+	assertRelayAuthConfigured();
+	const connection = createRelayConnection(relayBaseUrl);
+	const tunnelStatus = makeTunnelStatus(true, relayBaseUrl.replace(/^http/, "ws"));
+	return {
+		connection,
+		relayOrigin: "external-pwa",
+		getTunnelStatus: () => tunnelStatus,
+		stop() {
+			connection.close();
+		}
+	};
+}
+/**
+* Maps a `StartDebugMode` to the {@link FamilyKey} that serves it (issue #378).
+*   local-browser → 'local-browser'; relay-sandbox → 'relay-sandbox';
+*   relay-staging/relay-live → 'relay-intoss' (the shared physical slot).
+*/
+function familyKeyForMode(mode) {
+	switch (mode) {
+		case "local-browser": return "local-browser";
+		case "relay-sandbox": return "relay-sandbox";
+		case "relay-staging":
+		case "relay-live": return "relay-intoss";
+	}
+}
+/** The error thrown / surfaced when entering `mobile` without AIT_RELAY_BASE_URL. */
+const MOBILE_RELAY_BASE_URL_MISSING_MESSAGE = "start_debug(mobile): AIT_RELAY_BASE_URL이 설정되지 않았습니다 — unplugin이 tunnel:{cdp:true}로 띄운 relay base URL을 AIT_RELAY_BASE_URL 환경변수로 전달하세요. 환경 2(실기기 PWA) 진입은 외부 relay base가 필요합니다.";
+/**
+* Reads `AIT_RELAY_BASE_URL` from the environment for the env-2 (`mobile`) boot
+* site (issue #378). Returns the trimmed value, or throws the precise
+* {@link MOBILE_RELAY_BASE_URL_MISSING_MESSAGE} when unset/empty.
+*
+* SECRET-HANDLING: `AIT_RELAY_BASE_URL` carries the relay host (same class as a
+* wss URL). On the missing path the thrown message describes the env var name
+* and how to obtain it — it NEVER echoes any partial/garbled URL value. The
+* present value is returned to the caller (the CDP client) but never logged.
+*/
+function readMobileRelayBaseUrl(env = process.env) {
+	const raw = env.AIT_RELAY_BASE_URL;
+	const value = typeof raw === "string" ? raw.trim() : "";
+	if (value === "") throw new Error(MOBILE_RELAY_BASE_URL_MISSING_MESSAGE);
+	return value;
+}
+/**
+* Sentinel connection returned by {@link DualConnectionRouter.active} before the
+* first `start_debug` boots a family (all-lazy, issue #396). It satisfies the
+* full {@link CdpConnection} interface but holds nothing: `listTargets()` is
+* empty, every command rejects with a clear "call start_debug first" message,
+* and all event/teardown members are safe no-ops. Callers that read tools before
+* any switchMode therefore get an honest empty/down state instead of an NPE.
+*/
+const NULL_CDP_CONNECTION = {
+	kind: "local",
+	enableDomains: () => Promise.resolve(),
+	listTargets: () => [],
+	getBufferedEvents: () => [],
+	on: () => () => {},
+	send: () => Promise.reject(/* @__PURE__ */ new Error("no family booted yet — call start_debug first")),
+	close: () => {}
+};
+/**
+* Production `ConnectionRouter` (issues #348, #356, #378 — DUAL-CONNECTION-COEXIST).
+*
+* Holds a keyed set of lazily-booted families ({@link FamilyKey} →
+* `BootedFamily`, issue #378) with NO family active at startup (issue #396); the
+* first `start_debug` boots and activates one. Plus an `active` pointer and the
+* single attach watcher armed on the active connection. The router is
+* **direction-neutral** (#356): any family can be the first one booted, so a
+* `--target=local` session can hot-switch into relay (and vice versa) without
+* restarting the MCP server.
+*
+* Why a KEYED map and not a single lazy slot (#378): `relay-sandbox` (env-2
+* external relay) and `relay-staging`/`relay-live` (intoss relay) are BOTH
+* `kind: 'relay'`. A single "opposite-kind" slot could not warm-keep both at
+* once — they would collide. The three `FamilyKey`s
+* (`local-browser` / `relay-intoss` / `relay-sandbox`) give each its own warm
+* slot — `relay-staging` and `relay-live` deliberately share the one
+* `relay-intoss` slot (wire-identical, distinguished only by `liveIntent`).
+*
+* Why all-lazy (#396): the relay TOTP secret now lives in a project-local
+* `.ait_relay` file loaded read-only by `switchMode` BEFORE a relay family boots.
+* Booting any family eagerly at startup would bypass that load. With NO eager
+* boot every relay boot flows through `switchMode → loadRelaySecretReadOnly`, so
+* the secret is always populated before `assertRelayAuthConfigured()` /
+* `buildRelayVerifyAuth()` run at the boot site.
 *
 * `switchMode`:
-*   1. rejects re-entrant swaps (`swapInFlight`) and an unconfirmed relay-live;
-*   2. routes by the requested mode's family kind: same kind as `eager` → reuse
-*      eager; different kind → lazily boot (once) and keep warm;
+*   1. rejects re-entrant swaps (`swapInFlight`) and an unconfirmed `relay-live`;
+*   2. resolves the requested mode's `FamilyKey`:
+*      `lazyFamilies.get(key) ?? (boot via bootLazyFor(key), store)`;
 *   3. flips `active` (the MCP `Server` never re-handshakes — it reads through
 *      `active` per request);
-*   4. sets `liveIntent` (true only for relay-live);
+*   4. sets `liveIntent` (true only for `relay-live`; `relay-sandbox` is dev-intent → false);
 *   5. stops the old attach watcher and re-arms one on the new connection
 *      (the watcher self-clears, so re-arm is mandatory);
 *   6. emits `tools/list_changed`.
@@ -4240,30 +4812,37 @@ async function bootRelayFamily(options = {}) {
 */
 var DualConnectionRouter = class {
 	deps;
-	/** The opposite-kind family, booted lazily on the first cross-family switch. */
-	lazyFamily = null;
-	activeFamily;
+	/** Families, booted lazily and warm-kept per {@link FamilyKey} (#378, #396). */
+	lazyFamilies = /* @__PURE__ */ new Map();
+	/** `null` until the first `start_debug` boots a family (all-lazy, #396). */
+	activeFamily = null;
 	server = null;
 	attachWatcher = null;
 	swapInFlight = false;
 	constructor(deps) {
 		this.deps = deps;
-		this.activeFamily = deps.eager;
 	}
 	get active() {
-		return this.activeFamily.connection;
+		return this.activeFamily ? this.activeFamily.connection : NULL_CDP_CONNECTION;
 	}
-	/** Every booted family (for unified shutdown). */
+	/** Relay origin of the currently-active family (issue #378). */
+	get activeRelayOrigin() {
+		return this.activeFamily?.relayOrigin;
+	}
+	/** Every booted family (for unified shutdown). All families are lazy (#396). */
 	bootedFamilies() {
-		return this.lazyFamily ? [this.deps.eager, this.lazyFamily] : [this.deps.eager];
+		return [...this.lazyFamilies.values()];
 	}
 	/**
-	* Live tunnel status of the relay family, regardless of whether relay is the
-	* eager or lazy family (#356). Returns "down" until the relay family has been
-	* booted (local-eager sessions before the first relay switch) — which is the
-	* correct signal for `build_attach_url` (no tunnel exists yet).
+	* Live tunnel status of the active relay family (issues #356, #378). Reads
+	* the ACTIVE family's tunnel when it has one (so `relay-sandbox` surfaces the
+	* external relay wss and `relay-staging`/`relay-live` the intoss relay wss); otherwise
+	* falls back to the first booted family that has a tunnel. Returns "down"
+	* until any relay family is booted (any session before the first relay
+	* start_debug) — the correct signal for `build_attach_url` (no tunnel yet).
 	*/
 	relayTunnelStatus() {
+		if (this.activeFamily?.getTunnelStatus) return this.activeFamily.getTunnelStatus();
 		for (const family of this.bootedFamilies()) if (family.getTunnelStatus) return family.getTunnelStatus();
 		return {
 			up: false,
@@ -4271,8 +4850,9 @@ var DualConnectionRouter = class {
 		};
 	}
 	/**
-	* Binds the MCP `Server` and arms the initial attach watcher on the active
-	* connection. Called once after `createDebugServer` + `connect`.
+	* Binds the MCP `Server`; the attach watcher is armed by the first
+	* `start_debug` since no family is active at startup (all-lazy, #396). Called
+	* once after `createDebugServer` + `connect`.
 	*/
 	start(server) {
 		this.server = server;
@@ -4287,32 +4867,43 @@ var DualConnectionRouter = class {
 	armWatcher() {
 		const server = this.server;
 		if (!server) return;
-		this.attachWatcher = startAttachWatcher(this.activeFamily.connection, server, this.deps.attachWatcherIntervalMs ?? 1e3, () => {
+		const activeFamily = this.activeFamily;
+		if (!activeFamily) return;
+		this.attachWatcher = startAttachWatcher(activeFamily.connection, server, this.deps.attachWatcherIntervalMs ?? 1e3, () => {
 			this.deps.diagnosticsCollector.recordAttach();
-			if (this.activeFamily.connection.kind === "relay") this.deps.devtoolsOpener.open(this.relayTunnelStatus().wssUrl, deriveEnvironment(this.activeFamily.connection.kind, getLiveIntent()));
+			this.deps.onPageAttach?.();
+			if (activeFamily.connection.kind === "relay") this.deps.devtoolsOpener.open(this.relayTunnelStatus().wssUrl, deriveEnvironment(activeFamily.connection.kind, getLiveIntent(), activeFamily.relayOrigin));
 		});
 	}
-	async switchMode(mode, confirm) {
+	/**
+	* Resolves the `BootedFamily` for `key`: the warm family if already booted,
+	* otherwise boots it via `bootLazyFor(key)` and stores it (once per key).
+	* Since #396 every family is lazy, so this is the single boot path for all
+	* three keys.
+	*/
+	async familyFor(key) {
+		const warm = this.lazyFamilies.get(key);
+		if (warm) return warm;
+		const booted = await this.deps.bootLazyFor(key);
+		this.lazyFamilies.set(key, booted);
+		return booted;
+	}
+	async switchMode(mode, confirm, projectRoot) {
 		if (this.swapInFlight) throw new Error("start_debug: 이전 전환이 아직 진행 중입니다 — 잠시 후 다시 호출하세요.");
 		if (mode === "relay-live" && !confirm) throw new Error("start_debug: relay-live(실서비스 LIVE)는 confirm: true가 필요합니다 — 실유저에게 영향이 갈 수 있는 LIVE 디버깅 진입을 명시적으로 승인하세요.");
 		this.swapInFlight = true;
 		try {
-			const wantRelay = isRelayMode(mode);
-			const wantKind = wantRelay ? "relay" : "local";
-			let target;
-			if (wantKind === this.deps.eager.connection.kind) target = this.deps.eager;
-			else {
-				if (this.lazyFamily === null) this.lazyFamily = await this.deps.bootLazy();
-				target = this.lazyFamily;
-			}
+			if (isRelayMode(mode)) await loadRelaySecretReadOnly({ projectRoot });
+			const target = await this.familyFor(familyKeyForMode(mode));
 			this.activeFamily = target;
 			setLiveIntent(mode === "relay-live");
 			this.stopWatcher();
 			this.armWatcher();
 			this.server?.sendToolListChanged();
+			const wantRelay = isRelayMode(mode);
 			return {
 				mode,
-				environment: deriveEnvironment(target.connection.kind, getLiveIntent()),
+				environment: deriveEnvironment(target.connection.kind, getLiveIntent(), target.relayOrigin),
 				kind: target.connection.kind,
 				liveGuardActive: target.connection.kind === "relay" && getLiveIntent(),
 				nextStep: wantRelay ? "build_attach_url로 attach QR을 생성하세요 (relay 세션)." : "list_pages로 로컬 Chromium 페이지 attach를 확인하세요."
@@ -4332,26 +4923,39 @@ var DualConnectionRouter = class {
 */
 async function runDebugServer(options = {}) {
 	const lockHandle = acquireLock({ force: options.force ?? false });
-	const verifyAuth = buildRelayVerifyAuth();
-	const relayFamily = await bootRelayFamily({
-		relayPort: options.relayPort,
-		verifyAuth,
-		onWssUrl: (wssUrl) => lockHandle.updateWssUrl(wssUrl)
-	});
 	const devtoolsOpener = new AutoDevtoolsOpener();
 	const diagnosticsCollector = new InMemoryDiagnosticsCollector();
 	const router = new DualConnectionRouter({
-		eager: relayFamily,
-		bootLazy: bootLocalFamily,
+		bootLazyFor: (key) => key === "relay-sandbox" ? bootExternalRelayFamily(readMobileRelayBaseUrl()) : key === "local-browser" ? bootLocalFamily() : bootRelayFamily({
+			relayPort: options.relayPort,
+			verifyAuth: buildRelayVerifyAuth(),
+			onWssUrl: (wssUrl) => {
+				lockHandle.updateWssUrl(wssUrl);
+				qrServer?.notifyStateChange();
+			}
+		}),
 		diagnosticsCollector,
-		devtoolsOpener
+		devtoolsOpener,
+		onPageAttach: () => qrServer?.notifyStateChange()
 	});
 	const aitSource = new RoutingAitSource(() => {
 		return router.active;
 	});
+	let lastAttachUrl = null;
+	const getDashboardState = () => ({
+		tunnel: {
+			up: router.relayTunnelStatus().up,
+			wssUrl: router.relayTunnelStatus().wssUrl
+		},
+		pages: router.active.listTargets().map((t) => ({
+			id: t.id,
+			url: t.url
+		})),
+		attachUrl: lastAttachUrl
+	});
 	let qrServer;
 	try {
-		qrServer = await startQrHttpServer();
+		qrServer = await startQrHttpServer(getDashboardState);
 	} catch (err) {
 		logWarn("server.start", { msg: `QR HTTP 서버 시작 실패 (text QR fallback 사용): ${err instanceof Error ? err.message : String(err)}` });
 	}
@@ -4364,7 +4968,11 @@ async function runDebugServer(options = {}) {
 			return qrServer;
 		},
 		diagnosticsCollector,
-		...process.env.AIT_DEBUG_TOTP_SECRET ? { totpSecret: process.env.AIT_DEBUG_TOTP_SECRET } : {}
+		getTotpSecret: () => process.env.AIT_DEBUG_TOTP_SECRET,
+		onAttachUrlBuilt: (url) => {
+			lastAttachUrl = url;
+			qrServer?.notifyStateChange();
+		}
 	});
 	const transport = new StdioServerTransport();
 	let closed = false;
@@ -4425,13 +5033,15 @@ async function runDebugServer(options = {}) {
 	}
 }
 /**
-* Boots the local-browser debug stack and serves it over stdio:
-*   1. launch a local Chromium with `--remote-debugging-port=<port>`,
-*   2. attach a `LocalCdpConnection` to the first non-blank page target,
-*   3. expose the debug tools through the SAME direction-neutral
-*      `DualConnectionRouter` that `runDebugServer` uses (issue #356) — the
-*      local family is eager, the relay family is lazy-booted on the first
-*      `start_debug({ mode: 'relay-*' })`.
+* Serves the debug stack over stdio with the local browser as the default
+* target. Since #396 NOTHING boots at startup — every family (including the
+* local Chromium) is lazy-booted on its first `start_debug`:
+*   1. `start_debug({ mode: 'local-browser' })` launches a local Chromium with
+*      `--remote-debugging-port=<port>` and attaches a `LocalCdpConnection`;
+*   2. the intoss/external relay families lazy-boot on the first
+*      `start_debug({ mode: 'relay-staging' | 'relay-live' | 'relay-sandbox' })`;
+*   3. all of this runs through the SAME direction-neutral
+*      `DualConnectionRouter` that `runDebugServer` uses (issue #356).
 *
 * Symmetry with `runDebugServer` (#356): starting with `--target=local` no
 * longer pins a single-connection router. A `--target=local` session can
@@ -4453,37 +5063,195 @@ async function runDebugServer(options = {}) {
 */
 async function runLocalDebugServer(options = {}) {
 	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"
+	const cdpPort = options.cdpPort ?? 0;
+	const devUrl = options.devUrl ?? process.env.AIT_DEVTOOLS_URL ?? "http://localhost:5173";
+	const bootLocalFamilyForEntry = async () => {
+		const chromium = await launchChromium({
+			port: cdpPort,
+			devUrl
+		});
+		await new Promise((r) => setTimeout(r, 800));
+		const localConnection = new LocalCdpConnection({ devtoolsHttpUrl: chromium.devtoolsUrl });
+		return {
+			connection: localConnection,
+			stop() {
+				localConnection.close();
+				chromium.stop();
+			}
+		};
+	};
+	const devtoolsOpener = new AutoDevtoolsOpener();
+	const diagnosticsCollector = new InMemoryDiagnosticsCollector();
+	const router = new DualConnectionRouter({
+		bootLazyFor: (key) => key === "relay-sandbox" ? bootExternalRelayFamily(readMobileRelayBaseUrl()) : key === "local-browser" ? bootLocalFamilyForEntry() : bootRelayFamily({
+			verifyAuth: buildRelayVerifyAuth(),
+			onWssUrl: (wssUrl) => {
+				lockHandle.updateWssUrl(wssUrl);
+				qrServer?.notifyStateChange();
+			}
+		}),
+		diagnosticsCollector,
+		devtoolsOpener,
+		onPageAttach: () => qrServer?.notifyStateChange()
 	});
-	await new Promise((r) => setTimeout(r, 800));
-	const localConnection = new LocalCdpConnection({ devtoolsHttpUrl: chromium.devtoolsUrl });
-	const localFamily = {
-		connection: localConnection,
-		stop() {
-			localConnection.close();
-			chromium.stop();
+	const aitSource = new RoutingAitSource(() => {
+		return router.active;
+	});
+	let lastAttachUrl = null;
+	const getDashboardState = () => ({
+		tunnel: {
+			up: router.relayTunnelStatus().up,
+			wssUrl: router.relayTunnelStatus().wssUrl
+		},
+		pages: router.active.listTargets().map((t) => ({
+			id: t.id,
+			url: t.url
+		})),
+		attachUrl: lastAttachUrl
+	});
+	let qrServer;
+	try {
+		qrServer = await startQrHttpServer(getDashboardState);
+	} catch (err) {
+		logWarn("server.start", { msg: `QR HTTP 서버 시작 실패 (text QR fallback 사용): ${err instanceof Error ? err.message : String(err)}` });
+	}
+	const server = createDebugServer({
+		connection: router.active,
+		router,
+		aitSource,
+		getTunnelStatus: () => router.relayTunnelStatus(),
+		get qrHttpServer() {
+			return qrServer;
+		},
+		diagnosticsCollector,
+		getTotpSecret: () => process.env.AIT_DEBUG_TOTP_SECRET,
+		onAttachUrlBuilt: (url) => {
+			lastAttachUrl = url;
+			qrServer?.notifyStateChange();
 		}
+	});
+	const transport = new StdioServerTransport();
+	let closed = false;
+	let parentWatcher = null;
+	const shutdown = () => {
+		if (closed) return;
+		closed = true;
+		parentWatcher?.stop();
+		router.stopWatcher();
+		for (const family of router.bootedFamilies()) family.stop();
+		server.close();
+		qrServer?.close();
+		lockHandle.release();
 	};
-	const verifyAuth = buildRelayVerifyAuth();
+	process.once("SIGINT", shutdown);
+	process.once("SIGTERM", shutdown);
+	process.once("SIGHUP", shutdown);
+	process.on("exit", () => {
+		if (!closed) {
+			closed = true;
+			parentWatcher?.stop();
+			router.stopWatcher();
+			for (const family of router.bootedFamilies()) family.stop();
+			lockHandle.release();
+		}
+	});
+	process.on("uncaughtException", (err) => {
+		logError("tool.error", {
+			msg: `uncaughtException: ${String(err)}`,
+			errorKind: "uncaught",
+			mode: "local-browser"
+		});
+		shutdown();
+		process.exit(1);
+	});
+	process.on("unhandledRejection", (reason) => {
+		logError("tool.error", {
+			msg: `unhandledRejection: ${String(reason)}`,
+			errorKind: "unhandled-rejection",
+			mode: "local-browser"
+		});
+		shutdown();
+		process.exit(1);
+	});
+	await server.connect(transport);
+	router.start(server);
+	if (process.env.AIT_DEBUG_NO_PARENT_WATCH !== "1") {
+		parentWatcher = startParentWatcher(() => {
+			shutdown();
+			process.exit(0);
+		}, { intervalMs: 5e3 });
+		process.stdin.once("end", () => {
+			shutdown();
+			process.exit(0);
+		});
+		process.stdin.once("close", () => {
+			shutdown();
+			process.exit(0);
+		});
+	}
+}
+/**
+* Serves the env-2 (real-device PWA) debug stack over stdio with the external
+* Chii relay as the default target (issue #378). Since #396 NOTHING boots at
+* startup — the external relay family is lazy-booted on the first
+* `start_debug({ mode: 'relay-sandbox' })`.
+*
+* Unlike `runDebugServer` (which starts its own relay + cloudflared tunnel),
+* `runMobileDebugServer` attaches to a relay the unplugin ALREADY brought up
+* (`tunnel: { cdp: true }`) and exposed via `AIT_RELAY_BASE_URL`. The MCP only
+* opens a CDP client against that external relay — it never starts or tears down
+* a relay or a tunnel it did not own (see {@link bootExternalRelayFamily}).
+*
+* Symmetry with `runDebugServer` / `runLocalDebugServer` (#356, #378, #396): all
+* three families are lazy-booted — the env-2 external relay on the first
+* `start_debug({ mode: 'relay-sandbox' })`, the local family on `local-browser`,
+* the intoss relay on `relay-staging`/`relay-live` — so a `--target=mobile`
+* session can hot-switch
+* without a restart. The active env derives to `relay-mobile` (external-PWA
+* origin, liveIntent off).
+*
+* SECRET-HANDLING: `AIT_RELAY_BASE_URL` is read once here via
+* {@link readMobileRelayBaseUrl}; when unset it throws
+* {@link MOBILE_RELAY_BASE_URL_MISSING_MESSAGE} — a message that names the env
+* var and how to obtain it, never echoing any URL value. The error propagates to
+* the bin entry's fatal handler (the missing-URL path prints the guidance, not a
+* value). The present value is passed straight to the CDP client, never logged.
+*/
+async function runMobileDebugServer(options = {}) {
+	const relayBaseUrl = readMobileRelayBaseUrl();
+	const lockHandle = acquireLock({ force: options.force ?? false });
 	const devtoolsOpener = new AutoDevtoolsOpener();
 	const diagnosticsCollector = new InMemoryDiagnosticsCollector();
 	const router = new DualConnectionRouter({
-		eager: localFamily,
-		bootLazy: () => bootRelayFamily({
-			verifyAuth,
-			onWssUrl: (wssUrl) => lockHandle.updateWssUrl(wssUrl)
+		bootLazyFor: (key) => key === "relay-sandbox" ? bootExternalRelayFamily(relayBaseUrl) : key === "local-browser" ? bootLocalFamily() : bootRelayFamily({
+			verifyAuth: buildRelayVerifyAuth(),
+			onWssUrl: (wssUrl) => {
+				lockHandle.updateWssUrl(wssUrl);
+				qrServer?.notifyStateChange();
+			}
 		}),
 		diagnosticsCollector,
-		devtoolsOpener
+		devtoolsOpener,
+		onPageAttach: () => qrServer?.notifyStateChange()
 	});
 	const aitSource = new RoutingAitSource(() => {
 		return router.active;
 	});
+	let lastAttachUrl = null;
+	const getDashboardState = () => ({
+		tunnel: {
+			up: router.relayTunnelStatus().up,
+			wssUrl: router.relayTunnelStatus().wssUrl
+		},
+		pages: router.active.listTargets().map((t) => ({
+			id: t.id,
+			url: t.url
+		})),
+		attachUrl: lastAttachUrl
+	});
 	let qrServer;
 	try {
-		qrServer = await startQrHttpServer();
+		qrServer = await startQrHttpServer(getDashboardState);
 	} catch (err) {
 		logWarn("server.start", { msg: `QR HTTP 서버 시작 실패 (text QR fallback 사용): ${err instanceof Error ? err.message : String(err)}` });
 	}
@@ -4496,7 +5264,11 @@ async function runLocalDebugServer(options = {}) {
 			return qrServer;
 		},
 		diagnosticsCollector,
-		...process.env.AIT_DEBUG_TOTP_SECRET ? { totpSecret: process.env.AIT_DEBUG_TOTP_SECRET } : {}
+		getTotpSecret: () => process.env.AIT_DEBUG_TOTP_SECRET,
+		onAttachUrlBuilt: (url) => {
+			lastAttachUrl = url;
+			qrServer?.notifyStateChange();
+		}
 	});
 	const transport = new StdioServerTransport();
 	let closed = false;
@@ -4527,7 +5299,7 @@ async function runLocalDebugServer(options = {}) {
 		logError("tool.error", {
 			msg: `uncaughtException: ${String(err)}`,
 			errorKind: "uncaught",
-			mode: "local"
+			mode: "relay-sandbox"
 		});
 		shutdown();
 		process.exit(1);
@@ -4536,7 +5308,7 @@ async function runLocalDebugServer(options = {}) {
 		logError("tool.error", {
 			msg: `unhandledRejection: ${String(reason)}`,
 			errorKind: "unhandled-rejection",
-			mode: "local"
+			mode: "relay-sandbox"
 		});
 		shutdown();
 		process.exit(1);
@@ -4986,7 +5758,7 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.55"
+		version: "0.1.57"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -5061,11 +5833,15 @@ async function runDevServer() {
 *
 *   --mode=debug (default)
 *     --target=relay (default) — CDP/Chii relay + cloudflared quick tunnel.
-*       Attach a running mini-app (real Toss WebView, env 2/3) and read its
+*       Attach a running mini-app (real Toss WebView, env 3/4) and read its
 *       console + network over CDP without a human watching a phone.
 *     --target=local — CDP direct-attach to a local Chromium launched by the
 *       MCP server (env 1). No relay or tunnel; the browser is launched
 *       pointing at AIT_DEVTOOLS_URL (default http://localhost:5173).
+*     --target=mobile — CDP attach to an EXTERNAL Chii relay the unplugin
+*       already brought up for the env-2 real-device PWA (`tunnel: { cdp: true }`),
+*       exposed via AIT_RELAY_BASE_URL. The MCP starts no relay or tunnel; it
+*       only opens a CDP client against that external relay (issue #378).
 *
 *   --mode=dev — dev mode — reads the live browser mock state from a running
 *     Vite dev server (the devtools#130 `devtools_get_mock_state` surface).
@@ -5119,8 +5895,9 @@ function parseMode(argv) {
 * Parses `--target=<value>` / `--target <value>` from argv; default `relay`.
 *
 * Only meaningful when `--mode=debug`:
-*   - `relay`  — phone/WebView attach over Chii relay + cloudflared tunnel (env 2/3).
+*   - `relay`  — phone/WebView attach over Chii relay + cloudflared tunnel (env 3/4).
 *   - `local`  — local Chromium CDP attach (env 1, no relay needed).
+*   - `mobile` — CDP attach to an EXTERNAL relay (env 2 PWA, AIT_RELAY_BASE_URL).
 */
 function parseTarget(argv) {
 	for (let i = 0; i < argv.length; i++) {
@@ -5129,7 +5906,7 @@ function parseTarget(argv) {
 		if (arg.startsWith("--target=")) return normalizeTarget(arg.slice(9));
 		if (arg === "--target") {
 			const next = argv[i + 1];
-			if (next === void 0) throw new Error("--target requires a value: 'relay' (default) or 'local'.");
+			if (next === void 0) throw new Error("--target requires a value: 'relay' (default), 'local', or 'mobile'.");
 			return normalizeTarget(next);
 		}
 	}
@@ -5143,7 +5920,8 @@ function normalizeMode(value) {
 function normalizeTarget(value) {
 	if (value === "relay") return "relay";
 	if (value === "local") return "local";
-	throw new Error(`Unknown --target '${value}'. Expected 'relay' (default) or 'local'.`);
+	if (value === "mobile") return "mobile";
+	throw new Error(`Unknown --target '${value}'. Expected 'relay' (default), 'local', or 'mobile'.`);
 }
 async function main() {
 	const args = process.argv.slice(2);
@@ -5153,6 +5931,7 @@ async function main() {
 		const target = parseTarget(args);
 		const force = parseForce(args);
 		if (target === "local") await runLocalDebugServer({ force });
+		else if (target === "mobile") await runMobileDebugServer({ force });
 		else await runDebugServer({ force });
 	}
 }