@ait-co/devtools 0.1.54 → 0.1.56

package/dist/mcp/cli.js

@@ -718,6 +718,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 +1048,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 +1074,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 +1184,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 +1233,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됐는지 확인하세요.`);
@@ -1744,118 +1929,6 @@ function acquireLock(options = {}) {
 	};
 }
 //#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}`;
-}
-//#endregion
 //#region src/mcp/sdk-signatures.ts
 function isObject$1(v) {
 	return typeof v === "object" && v !== null && !Array.isArray(v);
@@ -2088,6 +2161,109 @@ function verifyTotp(secret, code, when = Date.now(), skew = 1) {
 	}
 	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. */
@@ -2124,13 +2300,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 / 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.",
 		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/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."
 				},
 				wait_for_attach: {
 					type: "boolean",
@@ -2141,7 +2317,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 +2395,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 +2449,23 @@ 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 — 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.",
 		inputSchema: {
 			type: "object",
 			properties: {
 				mode: {
 					type: "string",
 					enum: [
-						"local-browser-dev",
-						"local-browser-cdp",
-						"relay-dev",
-						"relay-live"
+						"local",
+						"mobile",
+						"staging",
+						"live"
 					],
-					description: "Target environment to switch to. relay-live additionally requires confirm: true."
+					description: "Target environment to switch to. mode=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."
+					description: "Required when mode=live — set true to acknowledge entering LIVE (env 4) debugging that can affect real users. Ignored for the other modes."
 				}
 			},
 			required: ["mode"]
@@ -2298,7 +2474,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 +2504,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 +2519,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 +3139,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 +3294,7 @@ async function readMcpSdkVersion() {
 * some test environments that skip the build step).
 */
 function readDevtoolsVersion() {
-	return "0.1.54";
+	return "0.1.56";
 }
 /**
 * Derives the next recommended action from a completed diagnostics snapshot.
@@ -3534,9 +3711,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 (`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.
+*/
 function isRelayMode(mode) {
-	return mode === "relay-dev" || mode === "relay-live";
+	return mode === "mobile" || mode === "staging" || mode === "live";
 }
 /**
 * Waits for the first target matching `filterFn` to attach, using the
@@ -3594,12 +3776,12 @@ function waitForAttachWithEvents(connection, filterFn, timeoutMs, pollIntervalMs
 function createDebugServer(deps) {
 	const { connection, router: routerDep, aitSource, getTunnelStatus, waitForAttachTimeoutMs = 9e4, qrHttpServer, getEnvironment: getEnvDep, getEnvironmentReason: getEnvReasonDep, diagnosticsCollector: collectorDep, totpSecret } = deps;
 	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.54"
+		version: "0.1.56"
 	}, { capabilities: { tools: { listChanged: true } } });
 	server.setRequestHandler(ListToolsRequestSchema, () => {
 		const conn = router.active;
@@ -3621,7 +3803,7 @@ 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' | 'mobile' | 'staging' | 'live' 중 하나를 전달하세요 (deprecated 별칭 'local-browser-dev'/'local-browser-cdp'/'relay-mobile'/'relay-dev'/'relay-live'도 수용).");
 			const confirm = request.params.arguments?.confirm === true;
 			try {
 				return jsonResult$1(await router.switchMode(mode, confirm));
@@ -3669,10 +3851,177 @@ 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를 완전히 기동할 때까지 잠시 후 다시 시도하세요.");
+				let totpCode;
+				let totpMeta;
+				if (totpSecret !== void 0 && totpSecret !== "") {
+					const now = Date.now();
+					totpCode = generateTotp(totpSecret, 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);
+				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",
@@ -3883,26 +4232,39 @@ ${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 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)
 */
 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" || 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";
 	return null;
 }
 /**
@@ -3919,10 +4281,12 @@ function makeSingleConnectionRouter(connection) {
 		get active() {
 			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 모드로 재시작하세요."));
 			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");
+			if (mode === "live" && !confirm) return Promise.reject(/* @__PURE__ */ new Error("start_debug: live(실서비스 LIVE)는 confirm: true가 필요합니다 — 실유저에게 영향이 갈 수 있는 LIVE 디버깅 진입을 명시적으로 승인하세요."));
+			setLiveIntent(mode === "live");
 			const environment = deriveEnvironment(connection.kind, getLiveIntent());
 			return Promise.resolve({
 				mode,
@@ -3978,8 +4342,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,29 +4423,6 @@ 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
@@ -4156,6 +4497,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 +4547,7 @@ async function bootRelayFamily(options = {}) {
 	const connection = createRelayConnection(relay.baseUrl);
 	return {
 		connection,
+		relayOrigin: "intoss-webview",
 		getTunnelStatus: () => tunnelStatus,
 		stop() {
 			tunnelProbe?.stop();
@@ -4215,21 +4558,91 @@ async function bootRelayFamily(options = {}) {
 	};
 }
 /**
-* Production `ConnectionRouter` (issues #348, #356 — DUAL-CONNECTION-COEXIST).
+* 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 → 'local'; mobile → 'relay-external'; staging/live → 'relay-intoss'.
+*/
+function familyKeyForMode(mode) {
+	switch (mode) {
+		case "local": return "local";
+		case "mobile": return "relay-external";
+		case "staging":
+		case "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;
+}
+/**
+* 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
+* single attach watcher armed on the active connection. The router is
+* **direction-neutral** (#356): any family can be the eager one, so a
+* `--target=local` session can hot-switch into relay (and vice versa) without
+* restarting the MCP server.
 *
-* 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.
+* 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.
 *
 * `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 `live`;
+*   2. resolves the requested mode's `FamilyKey`: equals `eagerKey` → reuse
+*      eager; else `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 `live`; `mobile` 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,8 +4653,8 @@ async function bootRelayFamily(options = {}) {
 */
 var DualConnectionRouter = class {
 	deps;
-	/** The opposite-kind family, booted lazily on the first cross-family switch. */
-	lazyFamily = null;
+	/** Non-eager families, booted lazily and warm-kept per {@link FamilyKey} (#378). */
+	lazyFamilies = /* @__PURE__ */ new Map();
 	activeFamily;
 	server = null;
 	attachWatcher = null;
@@ -4253,17 +4666,24 @@ var DualConnectionRouter = class {
 	get active() {
 		return this.activeFamily.connection;
 	}
+	/** Relay origin of the currently-active family (issue #378). */
+	get activeRelayOrigin() {
+		return this.activeFamily.relayOrigin;
+	}
 	/** Every booted family (for unified shutdown). */
 	bootedFamilies() {
-		return this.lazyFamily ? [this.deps.eager, this.lazyFamily] : [this.deps.eager];
+		return [this.deps.eager, ...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 `mobile` surfaces the
+	* external relay wss and `staging`/`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).
 	*/
 	relayTunnelStatus() {
+		if (this.activeFamily.getTunnelStatus) return this.activeFamily.getTunnelStatus();
 		for (const family of this.bootedFamilies()) if (family.getTunnelStatus) return family.getTunnelStatus();
 		return {
 			up: false,
@@ -4289,30 +4709,37 @@ var DualConnectionRouter = class {
 		if (!server) return;
 		this.attachWatcher = startAttachWatcher(this.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()));
+			if (this.activeFamily.connection.kind === "relay") this.deps.devtoolsOpener.open(this.relayTunnelStatus().wssUrl, deriveEnvironment(this.activeFamily.connection.kind, getLiveIntent(), this.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.
+	*/
+	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) {
 		if (this.swapInFlight) throw new Error("start_debug: 이전 전환이 아직 진행 중입니다 — 잠시 후 다시 호출하세요.");
-		if (mode === "relay-live" && !confirm) throw new Error("start_debug: relay-live(실서비스 LIVE)는 confirm: true가 필요합니다 — 실유저에게 영향이 갈 수 있는 LIVE 디버깅 진입을 명시적으로 승인하세요.");
+		if (mode === "live" && !confirm) throw new Error("start_debug: 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;
-			}
+			const target = await this.familyFor(familyKeyForMode(mode));
 			this.activeFamily = target;
-			setLiveIntent(mode === "relay-live");
+			setLiveIntent(mode === "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를 확인하세요."
@@ -4342,7 +4769,8 @@ async function runDebugServer(options = {}) {
 	const diagnosticsCollector = new InMemoryDiagnosticsCollector();
 	const router = new DualConnectionRouter({
 		eager: relayFamily,
-		bootLazy: bootLocalFamily,
+		eagerKey: "relay-intoss",
+		bootLazyFor: (key) => key === "relay-external" ? bootExternalRelayFamily(readMobileRelayBaseUrl()) : bootLocalFamily(),
 		diagnosticsCollector,
 		devtoolsOpener
 	});
@@ -4471,7 +4899,8 @@ async function runLocalDebugServer(options = {}) {
 	const diagnosticsCollector = new InMemoryDiagnosticsCollector();
 	const router = new DualConnectionRouter({
 		eager: localFamily,
-		bootLazy: () => bootRelayFamily({
+		eagerKey: "local",
+		bootLazyFor: (key) => key === "relay-external" ? bootExternalRelayFamily(readMobileRelayBaseUrl()) : bootRelayFamily({
 			verifyAuth,
 			onWssUrl: (wssUrl) => lockHandle.updateWssUrl(wssUrl)
 		}),
@@ -4558,6 +4987,126 @@ 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.
+*
+* 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): 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).
+*
+* 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 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)
+		}),
+		diagnosticsCollector,
+		devtoolsOpener
+	});
+	const aitSource = new RoutingAitSource(() => {
+		return router.active;
+	});
+	let qrServer;
+	try {
+		qrServer = await startQrHttpServer();
+	} 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,
+		...process.env.AIT_DEBUG_TOTP_SECRET ? { totpSecret: process.env.AIT_DEBUG_TOTP_SECRET } : {}
+	});
+	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();
+	};
+	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: "mobile"
+		});
+		shutdown();
+		process.exit(1);
+	});
+	process.on("unhandledRejection", (reason) => {
+		logError("tool.error", {
+			msg: `unhandledRejection: ${String(reason)}`,
+			errorKind: "unhandled-rejection",
+			mode: "mobile"
+		});
+		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);
+		});
+	}
+}
 //#endregion
 //#region src/mcp/ait-http-source.ts
 function isObject(value) {
@@ -4986,7 +5535,7 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.54"
+		version: "0.1.56"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -5061,11 +5610,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 +5672,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 +5683,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 +5697,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 +5708,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 });
 	}
 }