@ait-co/devtools 0.1.56 → 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);
@@ -1582,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;
@@ -1661,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());
@@ -1669,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 없음.
 */
@@ -1745,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.
@@ -2085,186 +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;
-}
-/**
-* Minimum length (in hex characters) accepted for `AIT_DEBUG_TOTP_SECRET`.
-*
-* The secret is hex-encoded (see {@link generateTotp} — `Buffer.from(secret,
-* 'hex')`). 32 hex chars = 16 bytes = 128 bits, the floor for an HMAC-SHA1 key
-* we are willing to gate a public relay behind. `generateAttachToken()` emits
-* 64 hex chars (32 bytes), comfortably above this bar.
-*/
-const MIN_SECRET_HEX_CHARS = 32;
-/** Hex string: one or more hex digits, case-insensitive (RFC 4648 base16). */
-const HEX_RE = /^[0-9a-fA-F]+$/;
-/**
-* Human-facing guidance printed when {@link assertRelayAuthConfigured} fails.
-*
-* SECRET-HANDLING: this message states only the REQUIREMENT (≥32 hex chars) and
-* how to mint one. It NEVER echoes the configured value, its length, or any
-* fragment derived from it — see {@link assertRelayAuthConfigured}.
-*
-* Note on encoding: the secret is hex (base16), not base32 — `generateTotp`
-* decodes it with `Buffer.from(secret, 'hex')`. A base32 string would be
-* silently mis-decoded and every TOTP code would fail to match, so the minting
-* command emits hex.
-*/
-const RELAY_AUTH_SECRET_MISSING_MESSAGE = [
-	"[ait-debug] AIT_DEBUG_TOTP_SECRET이 필수입니다. 32자 이상 16진수(hex) 문자열을 설정하세요.",
-	"발급: openssl rand -hex 32",
-	"자세히: https://docs.aitc.dev/guides/relay-auth-totp"
-].join("\n");
-/**
-* Whether `secret` is a well-formed relay-auth TOTP secret: a hex string of at
-* least {@link MIN_SECRET_HEX_CHARS} characters with an even length (an odd
-* length would have its trailing nibble silently dropped by `Buffer.from(...,
-* 'hex')`, weakening the key without warning).
-*
-* Pure predicate so callers can test the validation independently of the
-* fail-fast side effect in {@link assertRelayAuthConfigured}.
-*
-* SECRET-HANDLING: returns only a boolean — the input value is never returned,
-* logged, or echoed.
-*/
-function isValidRelayAuthSecret(secret) {
-	if (secret === void 0 || secret === "") return false;
-	if (secret.length < MIN_SECRET_HEX_CHARS) return false;
-	if (secret.length % 2 !== 0) return false;
-	return HEX_RE.test(secret);
-}
-/**
-* Fail-fast guard enforcing that a relay-auth TOTP secret is configured before
-* a public-internet-exposed relay is booted (issue #250).
-*
-* Relay-auth (the §4 Layer C TOTP gate) is the only fail-fast layer that closes
-* the real gap: a leaked `wss://…trycloudflare.com` URL otherwise lets a third
-* party attach a debugger to a dogfood/live mini-app. Without a secret the relay
-* comes up unauthenticated, so this guard is called at every relay-boot site —
-* `bootRelayFamily` (intoss env 3/4) and `bootExternalRelayFamily` (env-2 PWA),
-* both eager and lazy. Local-only sessions never boot a relay and so never reach
-* this guard, matching the issue's exemption for non-relay debugging.
-*
-* Throws when the secret is unset, empty, too short, or not a valid hex string.
-* The thrown message is the bin entry's fatal stderr (see `cli.ts` `main().catch`)
-* — the same fatal model as the missing-`AIT_RELAY_BASE_URL` path.
-*
-* SECRET-HANDLING: the env value is read once, passed ONLY to the boolean
-* predicate, and never logged. The thrown message names the requirement, never
-* the value, its length, or any derived fragment.
-*
-* @param env - Environment to read from. Defaults to `process.env`; injectable
-*   for tests so they never mutate the real process environment.
-*/
-function assertRelayAuthConfigured(env = process.env) {
-	if (!isValidRelayAuthSecret(env.AIT_DEBUG_TOTP_SECRET)) throw new Error(RELAY_AUTH_SECRET_MISSING_MESSAGE);
-}
-/**
-* 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 {@link verifyTotp}.
-*
-* Returns `undefined` when the env var is not set — callers treat that as
-* "auth disabled" (no predicate registered on the relay). Note that since
-* issue #250 the secret is MANDATORY at every relay-boot site (enforced by
-* {@link assertRelayAuthConfigured} BEFORE the relay starts), so in production
-* this never returns `undefined` for a relay that actually boots; the
-* `undefined` branch only matters for the no-relay local path and tests.
-*
-* Lives here (not in the MCP server) so the unplugin's env-2 relay can wire the
-* same gate without importing the heavy MCP server module graph. Re-exported
-* from `debug-server.ts` for back-compat.
-*
-* 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(env = process.env) {
-	const secret = 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") ?? "");
-	};
-}
-//#endregion
 //#region src/mcp/tools.ts
 /** Static MCP tool descriptors (name + JSONSchema) for the full debug tool surface. */
 const DEBUG_TOOL_DEFINITIONS = [
@@ -2300,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. 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 / staging (start_debug mode=\"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 / mobile (start_debug mode=\"mobile\"): 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.",
+		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). Required for env 3/staging mode. Not used in env 2/mobile 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."
+					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",
@@ -2449,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 — 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  mobile — 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 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  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  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 live ALSO requires confirm:true on this call. Use it only to observe a shipped regression; verify fixes in staging first.\n\nSwitching back to local 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",
-						"mobile",
-						"staging",
-						"live"
+						"local-browser",
+						"relay-sandbox",
+						"relay-staging",
+						"relay-live"
 					],
-					description: "Target environment to switch to. mode=live additionally requires confirm: true (and arms the read-only LIVE guard)."
+					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=live — set true to acknowledge entering LIVE (env 4) debugging that can affect real users. Ignored for the other modes."
+					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"]
@@ -3294,7 +3432,7 @@ async function readMcpSdkVersion() {
 * some test environments that skip the build step).
 */
 function readDevtoolsVersion() {
-	return "0.1.56";
+	return "0.1.57";
 }
 /**
 * Derives the next recommended action from a completed diagnostics snapshot.
@@ -3712,13 +3850,13 @@ function extractDeploymentId(schemeUrl) {
 	}
 }
 /**
-* Returns `true` when the mode routes to a relay connection (`mobile`,
-* `staging`, or `live`). `mobile` is an external-PWA relay; `staging`/`live`
-* are intoss-private relays — but all three surface the Tier B / relay-only
-* tool set.
+* 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 === "mobile" || mode === "staging" || mode === "live";
+	return mode === "relay-sandbox" || mode === "relay-staging" || mode === "relay-live";
 }
 /**
 * Waits for the first target matching `filterFn` to attach, using the
@@ -3774,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(), 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.56"
+		version: "0.1.57"
 	}, { capabilities: { tools: { listChanged: true } } });
 	server.setRequestHandler(ListToolsRequestSchema, () => {
 		const conn = router.active;
@@ -3803,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' | 'mobile' | 'staging' | 'live' 중 하나를 전달하세요 (deprecated 별칭 'local-browser-dev'/'local-browser-cdp'/'relay-mobile'/'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);
 			}
@@ -3858,11 +3999,12 @@ function createDebugServer(deps) {
 				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 (totpSecret !== void 0 && totpSecret !== "") {
+				if (secret !== void 0 && secret !== "") {
 					const now = Date.now();
-					totpCode = generateTotp(totpSecret, now);
+					totpCode = generateTotp(secret, now);
 					const STEP_SECONDS = 30;
 					const currentStep = Math.floor(now / 1e3 / STEP_SECONDS);
 					totpMeta = {
@@ -3872,6 +4014,7 @@ function createDebugServer(deps) {
 					};
 				}
 				const attachUrl = buildLauncherAttachUrl(tunnelHttpUrl, tunnelStatus.wssUrl, totpCode);
+				onAttachUrlBuilt?.(attachUrl);
 				const relayUrl = tunnelStatus.wssUrl;
 				const totp = totpMeta;
 				const isMatchingPage = (pages) => pages.length > 0;
@@ -4040,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();
@@ -4245,26 +4389,14 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 }
 /**
 * Normalizes a raw `start_debug` `mode` argument to a `StartDebugMode`, or
-* `null` when the value is not one of the accepted modes.
-*
-* Accepts the 4 canonical modes + 5 deprecated aliases (back-compat for
-* pinned .mcp.json / docs / QA runbooks that still emit old strings):
-*   'local'           → 'local'   (canonical)
-*   'mobile'          → 'mobile'  (canonical)
-*   'staging'         → 'staging' (canonical)
-*   'live'            → 'live'    (canonical)
-*   'local-browser-dev'  → 'local'   (deprecated alias)
-*   'local-browser-cdp'  → 'local'   (deprecated alias)
-*   'relay-mobile'       → 'mobile'  (deprecated alias)
-*   'relay-dev'          → 'staging' (deprecated alias)
-*   'relay-live'         → 'live'    (deprecated alias)
+* `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" || raw === "mobile" || raw === "staging" || raw === "live") return raw;
-	if (raw === "local-browser-dev" || raw === "local-browser-cdp") return "local";
-	if (raw === "relay-mobile") return "mobile";
-	if (raw === "relay-dev") return "staging";
-	if (raw === "relay-live") return "live";
+	if (raw === "local-browser" || raw === "relay-sandbox" || raw === "relay-staging" || raw === "relay-live") return raw;
 	return null;
 }
 /**
@@ -4282,11 +4414,11 @@ function makeSingleConnectionRouter(connection) {
 			return connection;
 		},
 		activeRelayOrigin: void 0,
-		switchMode(mode, confirm) {
-			if (mode === "mobile") return Promise.reject(/* @__PURE__ */ new Error("start_debug: 이 세션은 단일 연결만 보유합니다 — 'mobile'(환경 2 PWA, 외부 relay)로 동적 전환할 수 없습니다 (dual-connection 데몬에서만 지원). MCP 서버를 mobile 모드로 재시작하세요."));
+		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 === "live" && !confirm) return Promise.reject(/* @__PURE__ */ new Error("start_debug: live(실서비스 LIVE)는 confirm: true가 필요합니다 — 실유저에게 영향이 갈 수 있는 LIVE 디버깅 진입을 명시적으로 승인하세요."));
-			setLiveIntent(mode === "live");
+			if (mode === "relay-live" && !confirm) return Promise.reject(/* @__PURE__ */ new Error("start_debug: relay-live(실서비스 LIVE)는 confirm: true가 필요합니다 — 실유저에게 영향이 갈 수 있는 LIVE 디버깅 진입을 명시적으로 승인하세요."));
+			setLiveIntent(mode === "relay-live");
 			const environment = deriveEnvironment(connection.kind, getLiveIntent());
 			return Promise.resolve({
 				mode,
@@ -4426,8 +4558,9 @@ function startParentWatcher(onOrphaned, opts) {
 * 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).
@@ -4455,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({
@@ -4484,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
@@ -4592,14 +4723,15 @@ async function bootExternalRelayFamily(relayBaseUrl) {
 }
 /**
 * Maps a `StartDebugMode` to the {@link FamilyKey} that serves it (issue #378).
-*   local → 'local'; mobile → 'relay-external'; staging/live → 'relay-intoss'.
+*   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": return "local";
-		case "mobile": return "relay-external";
-		case "staging":
-		case "live": return "relay-intoss";
+		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. */
@@ -4621,28 +4753,55 @@ function readMobileRelayBaseUrl(env = process.env) {
 	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 one eagerly-booted family plus a keyed set of lazily-booted families
-* ({@link FamilyKey} → `BootedFamily`, issue #378), an `active` pointer, and the
+* 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 eager one, so a
+* **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): `mobile` (env-2 external
-* relay) and `staging`/`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` / `relay-intoss` / `relay-external`) give each
-* its own warm slot.
+* 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 `live`;
-*   2. resolves the requested mode's `FamilyKey`: equals `eagerKey` → reuse
-*      eager; else `lazyFamilies.get(key) ?? (boot via bootLazyFor(key), store)`;
+*   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 `live`; `mobile` is dev-intent → false);
+*   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`.
@@ -4653,37 +4812,37 @@ function readMobileRelayBaseUrl(env = process.env) {
 */
 var DualConnectionRouter = class {
 	deps;
-	/** Non-eager families, booted lazily and warm-kept per {@link FamilyKey} (#378). */
+	/** Families, booted lazily and warm-kept per {@link FamilyKey} (#378, #396). */
 	lazyFamilies = /* @__PURE__ */ new Map();
-	activeFamily;
+	/** `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;
 	}
 	/** Relay origin of the currently-active family (issue #378). */
 	get activeRelayOrigin() {
-		return this.activeFamily.relayOrigin;
+		return this.activeFamily?.relayOrigin;
 	}
-	/** Every booted family (for unified shutdown). */
+	/** Every booted family (for unified shutdown). All families are lazy (#396). */
 	bootedFamilies() {
-		return [this.deps.eager, ...this.lazyFamilies.values()];
+		return [...this.lazyFamilies.values()];
 	}
 	/**
 	* Live tunnel status of the active relay family (issues #356, #378). Reads
-	* the ACTIVE family's tunnel when it has one (so `mobile` surfaces the
-	* external relay wss and `staging`/`live` the intoss relay wss); otherwise
+	* 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 (local-eager sessions before the first
-	* relay switch) — the correct signal for `build_attach_url` (no tunnel yet).
+	* 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();
+		if (this.activeFamily?.getTunnelStatus) return this.activeFamily.getTunnelStatus();
 		for (const family of this.bootedFamilies()) if (family.getTunnelStatus) return family.getTunnelStatus();
 		return {
 			up: false,
@@ -4691,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;
@@ -4707,32 +4867,36 @@ 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.activeFamily.relayOrigin));
+			this.deps.onPageAttach?.();
+			if (activeFamily.connection.kind === "relay") this.deps.devtoolsOpener.open(this.relayTunnelStatus().wssUrl, deriveEnvironment(activeFamily.connection.kind, getLiveIntent(), activeFamily.relayOrigin));
 		});
 	}
 	/**
-	* Resolves the `BootedFamily` for `key`: the eager family when `key` matches
-	* `eagerKey`, otherwise the warm lazy family (booting + storing it once on
-	* first use). Only ever asks `bootLazyFor` for non-eager keys.
+	* 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) {
-		if (key === this.deps.eagerKey) return this.deps.eager;
 		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) {
+	async switchMode(mode, confirm, projectRoot) {
 		if (this.swapInFlight) throw new Error("start_debug: 이전 전환이 아직 진행 중입니다 — 잠시 후 다시 호출하세요.");
-		if (mode === "live" && !confirm) throw new Error("start_debug: live(실서비스 LIVE)는 confirm: true가 필요합니다 — 실유저에게 영향이 갈 수 있는 LIVE 디버깅 진입을 명시적으로 승인하세요.");
+		if (mode === "relay-live" && !confirm) throw new Error("start_debug: relay-live(실서비스 LIVE)는 confirm: true가 필요합니다 — 실유저에게 영향이 갈 수 있는 LIVE 디버깅 진입을 명시적으로 승인하세요.");
 		this.swapInFlight = true;
 		try {
+			if (isRelayMode(mode)) await loadRelaySecretReadOnly({ projectRoot });
 			const target = await this.familyFor(familyKeyForMode(mode));
 			this.activeFamily = target;
-			setLiveIntent(mode === "live");
+			setLiveIntent(mode === "relay-live");
 			this.stopWatcher();
 			this.armWatcher();
 			this.server?.sendToolListChanged();
@@ -4759,27 +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,
-		eagerKey: "relay-intoss",
-		bootLazyFor: (key) => key === "relay-external" ? bootExternalRelayFamily(readMobileRelayBaseUrl()) : 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)}` });
 	}
@@ -4792,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;
@@ -4853,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
@@ -4881,38 +5063,55 @@ 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"
-	});
-	await new Promise((r) => setTimeout(r, 800));
-	const localConnection = new LocalCdpConnection({ devtoolsHttpUrl: chromium.devtoolsUrl });
-	const localFamily = {
-		connection: localConnection,
-		stop() {
-			localConnection.close();
-			chromium.stop();
-		}
+	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 verifyAuth = buildRelayVerifyAuth();
 	const devtoolsOpener = new AutoDevtoolsOpener();
 	const diagnosticsCollector = new InMemoryDiagnosticsCollector();
 	const router = new DualConnectionRouter({
-		eager: localFamily,
-		eagerKey: "local",
-		bootLazyFor: (key) => key === "relay-external" ? bootExternalRelayFamily(readMobileRelayBaseUrl()) : bootRelayFamily({
-			verifyAuth,
-			onWssUrl: (wssUrl) => lockHandle.updateWssUrl(wssUrl)
+		bootLazyFor: (key) => key === "relay-sandbox" ? bootExternalRelayFamily(readMobileRelayBaseUrl()) : key === "local-browser" ? bootLocalFamilyForEntry() : 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)}` });
 	}
@@ -4925,7 +5124,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;
@@ -4956,7 +5159,7 @@ async function runLocalDebugServer(options = {}) {
 		logError("tool.error", {
 			msg: `uncaughtException: ${String(err)}`,
 			errorKind: "uncaught",
-			mode: "local"
+			mode: "local-browser"
 		});
 		shutdown();
 		process.exit(1);
@@ -4965,7 +5168,7 @@ async function runLocalDebugServer(options = {}) {
 		logError("tool.error", {
 			msg: `unhandledRejection: ${String(reason)}`,
 			errorKind: "unhandled-rejection",
-			mode: "local"
+			mode: "local-browser"
 		});
 		shutdown();
 		process.exit(1);
@@ -4988,8 +5191,10 @@ async function runLocalDebugServer(options = {}) {
 	}
 }
 /**
-* Boots the env-2 (real-device PWA) debug stack and serves it over stdio
-* (issue #378). The external Chii relay is the EAGER family here.
+* 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
@@ -4997,11 +5202,13 @@ async function runLocalDebugServer(options = {}) {
 * 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): the env-2
-* external relay is eager; the local family and the intoss relay family are
-* lazy-booted on the first `start_debug({ mode: 'local' | 'staging' | 'live' })`,
-* so a `--target=mobile` session can hot-switch without a restart. The active
-* env derives to `relay-mobile` (external-PWA origin, liveIntent off).
+* 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
@@ -5013,26 +5220,38 @@ async function runLocalDebugServer(options = {}) {
 async function runMobileDebugServer(options = {}) {
 	const relayBaseUrl = readMobileRelayBaseUrl();
 	const lockHandle = acquireLock({ force: options.force ?? false });
-	const externalRelayFamily = await bootExternalRelayFamily(relayBaseUrl);
-	const verifyAuth = buildRelayVerifyAuth();
 	const devtoolsOpener = new AutoDevtoolsOpener();
 	const diagnosticsCollector = new InMemoryDiagnosticsCollector();
 	const router = new DualConnectionRouter({
-		eager: externalRelayFamily,
-		eagerKey: "relay-external",
-		bootLazyFor: (key) => key === "local" ? bootLocalFamily() : 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)}` });
 	}
@@ -5045,7 +5264,11 @@ async function runMobileDebugServer(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;
@@ -5076,7 +5299,7 @@ async function runMobileDebugServer(options = {}) {
 		logError("tool.error", {
 			msg: `uncaughtException: ${String(err)}`,
 			errorKind: "uncaught",
-			mode: "mobile"
+			mode: "relay-sandbox"
 		});
 		shutdown();
 		process.exit(1);
@@ -5085,7 +5308,7 @@ async function runMobileDebugServer(options = {}) {
 		logError("tool.error", {
 			msg: `unhandledRejection: ${String(reason)}`,
 			errorKind: "unhandled-rejection",
-			mode: "mobile"
+			mode: "relay-sandbox"
 		});
 		shutdown();
 		process.exit(1);
@@ -5535,7 +5758,7 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.56"
+		version: "0.1.57"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {