@ait-co/devtools 0.1.117 → 0.1.119

package/dist/attach-orchestrator-CFotueL3.js

@@ -0,0 +1,1749 @@
+import { r as generateTotp } from "./totp-DfekTBk3.js";
+import { randomBytes } from "node:crypto";
+import { Tunnel, bin, install } from "cloudflared";
+//#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}).
+*
+* When `opts.name` is given (non-blank), it is added as `&name=` so the
+* launcher partner bar shows the app name instead of the generic default (#498).
+* When `opts.icon` is an absolute https:// URL, it is added as `&icon=` so the
+* launcher can render an icon next to the title (#498).
+*
+* 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.
+* @param opts - Optional app identity hints: `name`, `icon`, and `selfdebug`
+*   (#498, #543).
+* @returns The launcher deep-link URL with `?url=<enc>&debug=1&relay=<enc>
+*   [&at=<code>][&name=<enc>][&icon=<enc>][&selfdebug=1]` params.
+*/
+function buildLauncherAttachUrl(tunnelUrl, wssUrl, totpCode, opts) {
+	let url = `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}&debug=1&relay=${encodeURIComponent(wssUrl)}`;
+	if (totpCode !== void 0 && totpCode !== "") url += `&at=${encodeURIComponent(totpCode)}`;
+	if (opts?.name !== void 0 && opts.name.trim() !== "") url += `&name=${encodeURIComponent(opts.name.trim())}`;
+	if (opts?.icon !== void 0) {
+		let iconParsed;
+		try {
+			iconParsed = new URL(opts.icon);
+		} catch {
+			iconParsed = null;
+		}
+		if (iconParsed?.protocol === "https:") url += `&icon=${encodeURIComponent(opts.icon)}`;
+	}
+	if (opts?.selfdebug === true) url += "&selfdebug=1";
+	return url;
+}
+/**
+* Build a self-attaching dog-food deep-link.
+*
+* `ait deploy --scheme-only` prints an `intoss-private://…?_deploymentId=<uuid>`
+* URL that opens a dog-food 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/errors.ts
+/**
+* 한국어 한 줄 "원인 + 다음 행동" 포맷으로 에러 결과를 빌드한다.
+*
+* @param message - 사용자에게 보여줄 에러 본문 (원인 + 다음 행동 포함).
+*/
+function mcpError(message) {
+	return {
+		content: [{
+			type: "text",
+			text: message
+		}],
+		isError: true
+	};
+}
+/**
+* 상태 1: tunnel 미가동 — cloudflared 터널이 아직 뜨지 않았다.
+*
+* `start_attach` 호출 시 tunnel.up === false 인 경우.
+*/
+function tunnelDownError() {
+	return mcpError("cloudflared 터널이 안 떠 있습니다. MCP 서버를 재시작하거나 잠시 후 list_pages로 터널 상태를 다시 확인하세요.");
+}
+/**
+* 상태 3: page crash — 연결됐던 페이지가 crash/destroy됐다.
+*
+* chii-connection 이 'replaced-by-new-attach' / 'targetCrashed' / 'targetDestroyed' 를
+* 던질 때 이 메시지를 사용한다.
+*/
+function pageCrashError(toolName) {
+	return mcpError(`${toolName ? `${toolName}: ` : ""}페이지가 crash됐습니다. 토스 앱을 재실행한 뒤 start_attach → QR 스캔으로 재attach하세요.`);
+}
+/**
+* 상태 4: SDK 부재 — window.__sdkCall이 주입되지 않았다.
+*
+* call_sdk 호출 시 브리지가 없을 때. 같은 "브리지 부재"라도 다음 행동은
+* connection 종류에 따라 정반대다 (issue #360):
+*   - relay(`--target` 없는 intoss / env-2): dog-food 빌드가 아니다 → dog-food
+*     채널로 재배포 후 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, 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이 주입되지 않았습니다 (dog-food 빌드가 아닙니다). dog-food 채널(intoss-private)로 재배포 후 QR을 다시 스캔하세요: \`ait build && aitcc app deploy\`.`);
+}
+/**
+* relay WebSocket 연결이 끊겼을 때 — 크래시가 아닌 네트워크/프로세스 종료.
+*/
+function relayDisconnectError(toolName) {
+	return mcpError(`${toolName ? `${toolName}: ` : ""}relay 연결이 끊겼습니다. list_pages로 상태를 확인하고, 필요하면 앱을 재실행 후 재attach하세요.`);
+}
+/**
+* CDP/AIT 명령 중 발생한 예외를 4상태로 분류해 적절한 에러 결과를 반환한다.
+*
+* - SDK 부재 패턴 (`window.__sdkCall is not available`) → sdkAbsentError
+* - crash 패턴 (`replaced-by-new-attach`, `targetCrashed`, `targetDestroyed`) → pageCrashError
+* - 연결 끊김 패턴 (`relay에 연결되어 있지 않습니다`, `relay WebSocket`) → relayDisconnectError
+* - 그 외 (일반 에러) → 원본 메시지를 포함한 mcpError
+*/
+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, 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됐는지 확인하세요.`);
+}
+//#endregion
+//#region src/mcp/log.ts
+/**
+* Allowed field keys that may pass through to a log line.
+* Unknown keys are dropped. Values are still redact-scanned.
+*/
+const ALLOWED_KEYS = new Set([
+	"ts",
+	"level",
+	"event",
+	"msg",
+	"port",
+	"totpEnabled",
+	"env",
+	"tool",
+	"deploymentId",
+	"errorKind",
+	"reason",
+	"prevTargetId",
+	"mode",
+	"fileCount",
+	"passed",
+	"failed",
+	"skipped"
+]);
+/**
+* Patterns that match secret values.
+* Match order matters — more-specific patterns first.
+*
+* #268 redact script covers: relay=wss://…, at=<TOTP>, _deploymentId=<uuid>.
+* Here we extend to in-process value-level patterns used in server logs.
+*/
+const SECRET_PATTERNS = [
+	/^\d{6}$/,
+	/^(aitcc_|AITCC_)/i,
+	/^[A-Za-z0-9_-]+=.{4,}/,
+	/^wss:\/\//,
+	/(?:^|[?&])at=[A-Z0-9]{6}/i
+];
+/**
+* Returns `true` when the string value matches any known-secret pattern.
+* Only string values are tested — numbers/booleans are always safe.
+*/
+function isSecretValue(value) {
+	return SECRET_PATTERNS.some((re) => re.test(value));
+}
+/**
+* Redacts a single scalar value.
+* - strings: return "***" if the value matches a secret pattern.
+* - other: return as-is.
+*/
+function redactValue(value) {
+	if (typeof value === "string" && isSecretValue(value)) return "***";
+	return value;
+}
+/**
+* Builds a safe log payload from raw fields.
+*
+* - Only keys in `ALLOWED_KEYS` are included.
+* - String values are scanned for secret patterns and replaced with "***".
+* - `ts` and `level` and `event` are always included (they are injected by the
+*   logger functions below, not by callers).
+*/
+function buildPayload(level, event, fields) {
+	const out = {
+		ts: (/* @__PURE__ */ new Date()).toISOString(),
+		level,
+		event
+	};
+	for (const [key, value] of Object.entries(fields)) {
+		if (!ALLOWED_KEYS.has(key)) continue;
+		if (key === "ts" || key === "level" || key === "event") continue;
+		out[key] = redactValue(value);
+	}
+	return out;
+}
+/**
+* Writes a single JSON log line to stderr.
+* MCP stdio transport uses stdout; all diagnostics go to stderr.
+*/
+function writeLog(level, event, fields = {}) {
+	const payload = buildPayload(level, event, fields);
+	process.stderr.write(`${JSON.stringify(payload)}\n`);
+}
+/** Log an informational structured event. */
+function logInfo(event, fields = {}) {
+	writeLog("info", event, fields);
+}
+/** Log an error structured event. */
+function logError(event, fields = {}) {
+	writeLog("error", event, fields);
+}
+//#endregion
+//#region src/mcp/sdk-signatures.ts
+function isObject(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function describeArgs(args) {
+	try {
+		return JSON.stringify(args);
+	} catch {
+		return String(args);
+	}
+}
+/**
+* 등록된 메서드 목록.
+*
+* 시그니처 출처 확인:
+*   - 함수가 인자를 받지 않으면 args[0] 없음 → `args.length === 0`을 체크하지 않고
+*     그냥 통과시킨다(args 무시하는 stub가 많아서 noArgs 체크가 noise).
+*   - 실 SDK 시그니처는 `src/__typecheck.ts`의 `Assert<Mock, Original>` 줄로 보장.
+*/
+const SIGNATURES = [
+	{
+		name: "setDeviceOrientation",
+		validateArgs(args) {
+			const arg = args[0];
+			if (!isObject(arg)) return {
+				ok: false,
+				expected: "{ type: 'portrait' | 'landscape' }",
+				received: describeArgs(args)
+			};
+			const type = arg.type;
+			if (type !== "portrait" && type !== "landscape") return {
+				ok: false,
+				expected: "{ type: 'portrait' | 'landscape' }",
+				received: describeArgs(args)
+			};
+			return { ok: true };
+		},
+		example: "call_sdk('setDeviceOrientation', [{ type: 'landscape' }])"
+	},
+	{
+		name: "setIosSwipeGestureEnabled",
+		validateArgs(args) {
+			const arg = args[0];
+			if (!isObject(arg) || typeof arg.isEnabled !== "boolean") return {
+				ok: false,
+				expected: "{ isEnabled: boolean }",
+				received: describeArgs(args)
+			};
+			return { ok: true };
+		},
+		example: "call_sdk('setIosSwipeGestureEnabled', [{ isEnabled: false }])"
+	},
+	{
+		name: "setSecureScreen",
+		validateArgs(args) {
+			const arg = args[0];
+			if (!isObject(arg) || typeof arg.enabled !== "boolean") return {
+				ok: false,
+				expected: "{ enabled: boolean }",
+				received: describeArgs(args)
+			};
+			return { ok: true };
+		},
+		example: "call_sdk('setSecureScreen', [{ enabled: true }])"
+	},
+	{
+		name: "setScreenAwakeMode",
+		validateArgs(args) {
+			const arg = args[0];
+			if (!isObject(arg) || typeof arg.enabled !== "boolean") return {
+				ok: false,
+				expected: "{ enabled: boolean }",
+				received: describeArgs(args)
+			};
+			return { ok: true };
+		},
+		example: "call_sdk('setScreenAwakeMode', [{ enabled: true }])"
+	},
+	{
+		name: "getOperationalEnvironment",
+		validateArgs(_args) {
+			return { ok: true };
+		},
+		example: "call_sdk('getOperationalEnvironment', [])"
+	},
+	{
+		name: "getPlatformOS",
+		validateArgs(_args) {
+			return { ok: true };
+		},
+		example: "call_sdk('getPlatformOS', [])"
+	},
+	{
+		name: "getDeviceId",
+		validateArgs(_args) {
+			return { ok: true };
+		},
+		example: "call_sdk('getDeviceId', [])"
+	},
+	{
+		name: "getLocale",
+		validateArgs(_args) {
+			return { ok: true };
+		},
+		example: "call_sdk('getLocale', [])"
+	},
+	{
+		name: "getNetworkStatus",
+		validateArgs(_args) {
+			return { ok: true };
+		},
+		example: "call_sdk('getNetworkStatus', [])"
+	},
+	{
+		name: "getSchemeUri",
+		validateArgs(_args) {
+			return { ok: true };
+		},
+		example: "call_sdk('getSchemeUri', [])"
+	},
+	{
+		name: "requestReview",
+		validateArgs(_args) {
+			return { ok: true };
+		},
+		example: "call_sdk('requestReview', [])"
+	},
+	{
+		name: "closeView",
+		validateArgs(_args) {
+			return { ok: true };
+		},
+		example: "call_sdk('closeView', [])"
+	}
+];
+new Map(SIGNATURES.map((s) => [s.name, s]));
+SIGNATURES.map((s) => s.name);
+new Set([
+	{
+		name: "list_console_messages",
+		description: "Lists recent console messages (console.log/warn/error/info) captured from the attached mini-app page over CDP (Runtime.consoleAPICalled). Read-only. Returns level, text, timestamp, and stringified args, oldest-first.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "list_network_requests",
+		description: "Lists recent network requests (XHR/fetch) captured from the attached mini-app page over CDP (Network.requestWillBeSent + Network.responseReceived). Read-only. Returns url, method, status, and timing, oldest-first.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "list_pages",
+		description: "Returns the single active page (at most one) the relay sees attached. When a second page attaches, the previous one is evicted (last-attach wins — single-attach model). The result includes `singleAttachModel: true` so the agent knows the array is always 0 or 1 entries. Also returns whether the cloudflared tunnel is up and the public wss relay URL. The `tunnel` field includes `droppedAt` (ISO timestamp or null/undefined): when non-null the tunnel has permanently dropped after 3 failed reissue attempts — restart the debug server with `npx @ait-co/devtools devtools-mcp`. Each page entry includes a `lastSeenAt` ISO timestamp (last inbound CDP message from that target — useful to detect stale entries when the phone app backgrounded). The result also includes `crashDetectedAt` (ISO timestamp or null): when non-null, a page crash was detected via Inspector.targetCrashed / Target.targetDestroyed since the last attach, the pages list will be empty, and `crashWarning` shows a Korean hint to re-attach. Call this first to confirm a page is attached before reading console/network. When a page attaches or detaches the server emits notifications/tools/list_changed — call tools/list again to get the full updated tool surface.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "start_attach",
+		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. Single entry point to attach a real device: switches the debug mode (if `mode` is given), builds the self-attaching deep-link QR for the active relay environment, and waits for the phone to attach — all in one call (replaces the old attach-URL + start_debug two-step). 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).\n\nmode (optional): pass \"relay-sandbox\" (env 2) or \"relay-staging\" (env 3) to switch the active environment first. When omitted, the current relay environment is used as-is (no switch). Passing \"local-browser\" returns an error — start_attach is relay-only (env 2/3). When the session is already in the requested mode, the switch is skipped.\n\nEnvironment-specific behaviour:\n  • env 3 / 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.\n  • env 2 / 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=…). When projectRoot is given, the app name from <projectRoot>/package.json is added as name= so the launcher partner bar shows it.\n\nWaits for a page to attach by default (up to wait_timeout_seconds, default 60 s). The server automatically opens the QR dashboard in the OS default browser when running on a local GUI machine — headless/remote environments fall back to the text QR in the tool output.\n\nTOTP auto re-mint: when AIT_DEBUG_TOTP_SECRET is set on the MCP server, the attachUrl carries a one-time code (at=<code>) valid for ~3 minutes (the relay gate accepts ±6 TOTP steps). While waiting, start_attach AUTOMATICALLY re-mints a fresh code before the current one expires and refreshes the dashboard QR in place (no browser re-open). You do NOT need to re-call start_attach every time the code would expire — a single call covers the whole wait window. The response includes a `totp` field with `expiresAt` and a `reminted` count of how many fresh codes were issued during the wait. Without AIT_DEBUG_TOTP_SECRET, the attachUrl has no expiry.\n\nselfdebug (env 2 / relay-sandbox only): pass selfdebug=true to add &selfdebug=1 to the launcher deep-link. The launcher PWA then registers its own document as the CDP target instead of the framed mini-app. SINGLE-ATTACH MODEL: attaching the launcher self-target evicts any currently-attached mini-app target — use this mode exclusively for diagnosing the launcher document itself (DOM, safe-area, console). Not applicable in env 3 (relay-staging) — passing selfdebug=true there returns an error.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				mode: {
+					type: "string",
+					enum: [
+						"local-browser",
+						"relay-sandbox",
+						"relay-staging"
+					],
+					description: "Optional debug mode to switch into before attaching. \"relay-sandbox\" = env 2 (launcher PWA), \"relay-staging\" = env 3 (intoss-private dog-food). \"local-browser\" returns an error (start_attach is relay-only). Omit to keep the current relay environment."
+				},
+				scheme_url: {
+					type: "string",
+					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_timeout_seconds: {
+					type: "number",
+					description: "Maximum seconds to wait for a page to attach (default 60, range 1–600). Values outside the range or invalid inputs (0, negative, NaN) fall back to the default silently. During the wait the TOTP code is auto re-minted as needed, so a single call covers the whole window."
+				},
+				projectRoot: {
+					type: "string",
+					description: "Absolute path to the mini-app project root (the directory containing its package.json and .ait_urls). When AIT_TUNNEL_BASE_URL is unset (env 2 / relay-mobile only), the daemon reads the app tunnel URL from <projectRoot>/.ait_urls written by the dev server (tunnel:{cdp:true}). Pass this because the daemon's own cwd is fixed at launch. Omit when AIT_TUNNEL_BASE_URL is set explicitly."
+				},
+				selfdebug: {
+					type: "boolean",
+					description: "Env 2 / relay-sandbox only. When true, adds &selfdebug=1 to the launcher deep-link so the launcher PWA registers its own document as the CDP target (launcher diagnostics mode). SINGLE-ATTACH MODEL: self-target attach evicts any currently-attached mini-app target. Use only when you need to inspect the launcher itself (DOM, safe-area, console). Passing selfdebug=true in env 3 (relay-staging) returns an error. Default: false (omitted)."
+				}
+			},
+			required: []
+		},
+		availableIn: "relay"
+	},
+	{
+		name: "get_dom_document",
+		description: "Returns the DOM tree of the attached mini-app page over CDP (DOM.getDocument). Read-only. Use for structural/layout regression diagnosis (e.g. confirming an element exists, inspecting attributes). Returns the document root node with children.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "take_snapshot",
+		description: "Captures a serialized snapshot of the attached page over CDP (DOMSnapshot.captureSnapshot). Read-only. Returns the documents + interned strings table for visual-regression diagnosis (e.g. checking computed CSS custom properties like --sat against the live layout).",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "take_screenshot",
+		description: "Captures a PNG screenshot of the attached mini-app page over CDP (Page.captureScreenshot) so the agent can see the phone screen directly. Read-only. Returns an image content block — this is the only debug tool that returns an image; all other debug tools return text (JSON).",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "measure_safe_area",
+		description: "Runs a safe-area probe on the attached mini-app page via Runtime.evaluate and returns normalized safe-area insets, viewport geometry, device pixel ratio, and User-Agent. Read-only — does not modify page state. Tier C per RFC #277: the same Runtime.evaluate probe runs in both `mock` (devtools panel page with window.__ait state) and `relay` (real-device WebView with window.__sdk). The result includes a `source: \"mock\" | \"relay-dev\" | \"relay-mobile\"` field so consumers can identify provenance without inspecting payload values. (`relay-mobile` = env 2 real-device PWA over an external relay; `relay-dev` = env 3 dog-food WebView; relay-live/env 4 removed #665.) Use in a relay session (phone attached) to get ground-truth values for upgrading a viewport preset from extrapolated/placeholder to measured. Requires a page to be attached — call list_pages first.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "evaluate",
+		description: "Evaluates an arbitrary JavaScript expression on the attached mini-app page via CDP Runtime.evaluate (returnByValue: true) and returns the result. NOT read-only — the expression can have side effects (DOM mutations, SDK calls, state changes). Requires the relay to be attached — call list_pages first. Throws if the evaluation throws an exception on the page.\n\nSECURITY: expression and result are not redacted — never include secrets or auth tokens in the expression.\n\nPositive-allowlist kill-switch (#665): this tool is blocked when the attached page is on a non-debug host (apps.tossmini.com / env 4). Only localhost, *.trycloudflare.com, and *.private-apps.tossmini.com are allowed. relay-live (env 4) and the LIVE confirm guard are removed.",
+		inputSchema: {
+			type: "object",
+			properties: { expression: {
+				type: "string",
+				description: "JavaScript expression to evaluate in the page context."
+			} },
+			required: ["expression"]
+		},
+		availableIn: "both"
+	},
+	{
+		name: "list_exceptions",
+		description: "Lists JS-level exceptions captured via `Runtime.exceptionThrown` from the relay attached page. Includes timestamp, exception text, source URL/line, and stack trace. Use to root-cause SDK throws that may precede a Toss app crash (#265 / #267). The buffer holds up to 50 most recent exceptions and survives target replaced/crashed/destroyed events so an exception just before a crash is preserved. Returns up to 50 most recent by default.",
+		inputSchema: {
+			type: "object",
+			properties: { limit: {
+				type: "number",
+				description: "Maximum number of exceptions to return (default 50, max 50)."
+			} },
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "call_sdk",
+		description: "Calls a dog-food 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-dog-food 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\nPositive-allowlist kill-switch (#665): blocked when the attached page is on a non-debug host (apps.tossmini.com / env 4). relay-live and the LIVE guard removed.\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: {
+				name: {
+					type: "string",
+					description: "SDK method name to call (e.g. \"getOperationalEnvironment\")."
+				},
+				args: {
+					type: "array",
+					description: "Arguments to pass to the SDK method (optional, default []).",
+					items: {}
+				}
+			},
+			required: ["name"]
+		},
+		availableIn: "both"
+	},
+	{
+		name: "AIT.getSdkCallHistory",
+		description: "Returns the recent Apps in Toss SDK call trace (method, args, result/error, timestamp) that raw CDP cannot observe. Read-only. Use to confirm an SDK call fired and how it resolved (e.g. a saveBase64Data permission regression).",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "AIT.getMockState",
+		description: "Returns the devtools mock state snapshot (window.__ait) — environment, permissions, location, auth, network, IAP, and more. Read-only. In dev mode this is the live browser mock state; in debug mode the in-app side reports it over the AIT domain.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "AIT.getOperationalEnvironment",
+		description: "Returns getOperationalEnvironment() plus the resolved SDK version — metadata raw CDP cannot observe. Read-only.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		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 2/3, real-device 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\nPositive-allowlist kill-switch (#665): relay sessions on apps.tossmini.com (env 4, released production) are silently blocked at both the in-app gate and this MCP layer — relay-live and the LIVE guard have been removed. Only localhost/loopback (env 1), *.trycloudflare.com (env 2), and *.private-apps.tossmini.com (env 3) are allowed.\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. CDP covers real-device WebKit DOM, console, exceptions, and safe-area observation; call_sdk still hits the mock (SDK fidelity needs relay-staging). Side-effect tools run unguarded against the mock. Only the dual-connection daemon can enter relay-sandbox in-place; a single-connection session rejects it with \"동적 전환할 수 없습니다 … relay-sandbox 모드로 재시작하세요\" — follow that hint and restart the MCP server in relay-sandbox mode rather than retrying. Prerequisites: both AIT_RELAY_BASE_URL (the relay base the unplugin emits when started with tunnel:{cdp:true}, used for the CDP attach) and AIT_TUNNEL_BASE_URL (the dev-server tunnel host, required by start_attach to render the launcher QR) must be set before the MCP server starts — the unplugin does not auto-forward either; set them explicitly. Both carry relay/tunnel hosts (secret-class) — keep them out of logs.\n  relay-staging — env 3: a real-device Toss WebView dog-food 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 (dog-food, not released to real users). Prerequisite: a dog-food candidate bundle built with `RELEASE_CHANNEL=dogfood ait build`, then uploaded with `ait deploy` (add `--scheme-only` to print the resulting intoss-private://…?_deploymentId=… deep-link); open that deep-link/QR on the device to cold-load the bundle with the relay injected. Unlike env 2, env 3 is NOT a dev-server tunnel — it is a deployed bundle reached via the intoss-private scheme, so `pnpm dev` plays no part here.\n\nFor a relay mode (relay-sandbox/relay-staging), also pass projectRoot — the absolute mini-app project root — so the daemon can read the relay auth secret from <projectRoot>/.ait_relay (read-only; the daemon never mints it). Omit it for local-browser.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				mode: {
+					type: "string",
+					enum: [
+						"local-browser",
+						"relay-sandbox",
+						"relay-staging"
+					],
+					description: "Target environment to switch to. relay-live (env 4) has been removed (#665) — use relay-staging (env 3) for dog-food debugging."
+				},
+				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-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"]
+		},
+		availableIn: "both"
+	},
+	{
+		name: "get_debug_status",
+		description: "Reports the current debug session state — which environment/mode is active, whether a page is attached, and a full diagnostic snapshot — in one call. Use this any time to answer \"what mode am I in right now?\" or \"why is this not working?\" without chaining 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), authRejects ({count, lastAt} — relay TOTP 401 rejections, secret-free; count > 0 with empty pages means the phone reached the relay but its code was rejected), environment (kind: mock|relay-dev|relay-mobile, env: mock|relay backward-compat, reason, liveGuardActive: always false — relay-live and LIVE guard removed (#665); start_debug mode→kind mapping: relay-sandbox→relay-mobile, relay-staging→relay-dev, local-browser→mock), 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).",
+		inputSchema: {
+			type: "object",
+			properties: { recent_errors_limit: {
+				type: "number",
+				description: "Maximum number of recent server-side errors to include (default 10, max 50)."
+			} },
+			required: []
+		},
+		availableIn: "both"
+	},
+	{
+		name: "run_tests",
+		description: "Runs mini-app test files on the attached page over CDP (Runtime.evaluate). Each matched file is bundled with esbuild (SDK imports redirected to the live mock/SDK), injected into the attached WebView, and executed; returns per-file results plus flattened totals (passed/failed/skipped/total). When there is no attached page and the current environment is relay (env 3), this tool automatically shows the QR dashboard and waits for a phone to connect before running (scheme_url required for env 3 relay-dev). Files run SEQUENTIALLY (single-attach model: the relay/local target serves one page), and one run_tests call runs at a time (a concurrent call is rejected). Test verification (assert/snapshot) is delegated to the in-page Vitest runtime; this tool is the transport + report. The per-file results array is the progress record — on partial failure you see exactly which files passed/failed/timed-out. Positive-allowlist kill-switch (#665): blocked when the attached page is on a non-debug host. debug-mode only — dev-mode (--mode=dev) has no CDP. Tier C (both mock/local and relay).",
+		inputSchema: {
+			type: "object",
+			properties: {
+				files: {
+					type: "array",
+					items: { type: "string" },
+					description: "Glob patterns or file paths to run (e.g. [\"src/**/*.ait.test.ts\"]). Resolved relative to projectRoot when given, else the daemon cwd. Required, non-empty."
+				},
+				projectRoot: {
+					type: "string",
+					description: "Absolute path to the mini-app project root used as the glob base. Pass this because the daemon's cwd is fixed at launch. Optional."
+				},
+				timeout_ms: {
+					type: "number",
+					description: "Per-file evaluate timeout in ms (default 30000, range 1000–600000). Out-of-range/invalid values fall back to the default."
+				},
+				scheme_url: {
+					type: "string",
+					description: "intoss-private:// deep-link URL from `ait deploy --scheme-only` (env 3 relay-dev only). Required when there is no attached page and the environment is relay-dev — the tool uses it to build the QR attach URL and wait for the phone to connect. Ignored when a page is already attached."
+				},
+				cell: {
+					type: "object",
+					description: "Optional cell object to inject into globalThis BEFORE running tests (e.g. { \"__AIT_CELL__\": { \"sdkLine\": \"2.x\", \"platform\": \"ios\" } }). Applied only on the auto-attach path (no-page → attach → inject → run). When a page is already attached the caller is responsible for any prior injection. Ignored when empty or absent. Values must be JSON-serialisable.",
+					additionalProperties: true
+				}
+			},
+			required: ["files"]
+		},
+		availableIn: "both"
+	}
+].map((t) => t.name));
+function isCrashAware(conn) {
+	return typeof conn.getLastCrashDetectedAt === "function" && typeof conn.getTargetLastSeenAt === "function";
+}
+function listPages(connection, tunnel) {
+	const pages = connection.listTargets().map((t) => {
+		const lastSeenMs = isCrashAware(connection) ? connection.getTargetLastSeenAt(t.id) : null;
+		return {
+			id: t.id,
+			title: t.title,
+			url: redactAtParam(t.url),
+			lastSeenAt: lastSeenMs !== null ? new Date(lastSeenMs).toISOString() : null
+		};
+	});
+	const crashMs = isCrashAware(connection) ? connection.getLastCrashDetectedAt() : null;
+	const crashDetectedAt = crashMs !== null ? new Date(crashMs).toISOString() : null;
+	return {
+		pages,
+		tunnel,
+		crashDetectedAt,
+		crashWarning: crashDetectedAt ? `[ait-debug] page crash 감지됨 — 새 attach 필요 (관측 시각: ${crashDetectedAt})` : null,
+		singleAttachModel: true
+	};
+}
+/**
+* Heuristic: can this process open a GUI browser?
+*
+* Returns `true` when we think a GUI is available:
+*   - On macOS (`darwin`) we assume yes (MCP normally runs on the user's Mac).
+*   - On Linux we check for `DISPLAY` or `WAYLAND_DISPLAY`.
+*   - On Windows we assume yes.
+*   - In a CI environment (`CI=true`) we assume no.
+*/
+function canOpenBrowser() {
+	if (process.env.CI === "true" || process.env.CI === "1") return false;
+	const platform = process.platform;
+	if (platform === "darwin" || platform === "win32") return true;
+	if (platform === "linux") return Boolean(process.env.DISPLAY ?? process.env.WAYLAND_DISPLAY);
+	return false;
+}
+/** platform별 browser open 명령 후보 목록 — 앞에서부터 순차 시도. */
+function getBrowserCandidates(httpUrl) {
+	const platform = process.platform;
+	if (platform === "darwin") return [
+		{
+			cmd: "open",
+			args: [httpUrl]
+		},
+		{
+			cmd: "open",
+			args: [
+				"-a",
+				"Safari",
+				httpUrl
+			]
+		},
+		{
+			cmd: "open",
+			args: [
+				"-a",
+				"Google Chrome",
+				httpUrl
+			]
+		},
+		{
+			cmd: "open",
+			args: [
+				"-a",
+				"Firefox",
+				httpUrl
+			]
+		}
+	];
+	if (platform === "win32") return [{
+		cmd: "cmd",
+		args: [
+			"/c",
+			"start",
+			"",
+			httpUrl
+		]
+	}, {
+		cmd: "rundll32",
+		args: ["url.dll,FileProtocolHandler", httpUrl]
+	}];
+	return [
+		{
+			cmd: "xdg-open",
+			args: [httpUrl]
+		},
+		{
+			cmd: "sensible-browser",
+			args: [httpUrl]
+		},
+		{
+			cmd: "x-www-browser",
+			args: [httpUrl]
+		},
+		{
+			cmd: "firefox",
+			args: [httpUrl]
+		},
+		{
+			cmd: "google-chrome",
+			args: [httpUrl]
+		},
+		{
+			cmd: "chromium",
+			args: [httpUrl]
+		}
+	];
+}
+/**
+* Redacts ONLY the `at=<value>` (TOTP) query param to `at=<redacted>`, leaving
+* every other query param (_deploymentId, debug, relay) intact. SECRET-HANDLING:
+* the TOTP code is the single short-lived secret carried in a CDP page url.
+*/
+function redactAtParam(text) {
+	return text.replace(/\bat=([^&\s"']+)/g, "at=<redacted>");
+}
+/** stderr에서 at= TOTP 코드 값을 redact한다. */
+function redactSecrets(text) {
+	return redactAtParam(text);
+}
+/** spawnSync exit 0이어도 stderr에 launch 실패 시그널이 있으면 실패로 판단한다. */
+const LAUNCH_FAILURE_PATTERNS = [
+	/LSOpenURLsWithRole\(\) failed/,
+	/kLSApplicationNotFoundErr/,
+	/No application/,
+	/Unable to find application/,
+	/xdg-open: not found/,
+	/command not found/
+];
+function isLaunchFailureStderr(stderr) {
+	return LAUNCH_FAILURE_PATTERNS.some((p) => p.test(stderr));
+}
+/**
+* 로컬 HTTP 서버 루트 URL(`http://127.0.0.1:<port>/`)을 OS 기본 브라우저로 연다 (#595).
+*
+* platform별 fallback chain으로 시도하며, 모두 실패하면 1회 retry를 수행한다
+* (ephemeral process launch 타이밍 문제 대응). retry까지 실패해도 `opened: false` +
+* `httpUrl`을 반환해 사용자가 직접 브라우저에 붙여넣을 수 있게 한다.
+*
+* SECRET-HANDLING:
+*   - tmp 파일을 만들지 않는다 (HTML/PNG는 HTTP 서버가 메모리에서 응답).
+*   - httpUrl은 `http://127.0.0.1:<port>/`(루트, 시크릿 없음). pngUrl은 127.0.0.1 로컬 전용.
+*   - stderr 캡처 결과에서 at= 코드 값을 redact한 후 stderrSummary에 포함.
+*   - attachUrl, deploymentId, TOTP 코드를 stdout/stderr/로그에 직접 출력 금지.
+*
+* @param httpUrl - `http://127.0.0.1:<port>/` 루트 URL (시크릿 없음, #595).
+* @param pngUrl  - `http://127.0.0.1:<port>/qr.png?u=<encoded>` PNG fallback URL.
+*/
+async function openQrInBrowser(httpUrl, pngUrl) {
+	const { spawnSync } = await import("node:child_process");
+	/**
+	* 한 번의 fallback chain 시도. 성공하면 열린 후보 cmd를 반환, 실패하면 null.
+	* stderrLines에 각 후보의 stderr를 누적한다.
+	*/
+	function tryOnce(stderrLines) {
+		const candidates = getBrowserCandidates(httpUrl);
+		for (const { cmd, args } of candidates) {
+			const result = spawnSync(cmd, args, {
+				encoding: "utf8",
+				timeout: 5e3
+			});
+			if (result.error) {
+				stderrLines.push(`${cmd}: ${result.error.message}`);
+				continue;
+			}
+			const stderr = typeof result.stderr === "string" ? result.stderr : "";
+			if (stderr) stderrLines.push(`${cmd}: ${redactSecrets(stderr.trim())}`);
+			if (result.status === 0 && !isLaunchFailureStderr(stderr)) return true;
+		}
+		return false;
+	}
+	const stderrLines = [];
+	if (tryOnce(stderrLines)) return {
+		opened: true,
+		httpUrl,
+		pngUrl
+	};
+	if (tryOnce(stderrLines)) return {
+		opened: true,
+		httpUrl,
+		pngUrl,
+		retried: true
+	};
+	return {
+		opened: false,
+		httpUrl,
+		pngUrl,
+		error: "모든 브라우저 실행 후보가 실패했습니다.",
+		stderrSummary: stderrLines.length > 0 ? stderrLines.join("\n") : void 0
+	};
+}
+`
+(function() {
+  var el = document.createElement('div');
+  el.style.cssText = 'position:fixed;top:0;left:0;width:0;height:0;visibility:hidden;' +
+    'padding-top:env(safe-area-inset-top,0px);' +
+    'padding-right:env(safe-area-inset-right,0px);' +
+    'padding-bottom:env(safe-area-inset-bottom,0px);' +
+    'padding-left:env(safe-area-inset-left,0px)';
+  document.documentElement.appendChild(el);
+  var cs = window.getComputedStyle(el);
+  var cssEnv = {
+    top: parseFloat(cs.paddingTop) || 0,
+    right: parseFloat(cs.paddingRight) || 0,
+    bottom: parseFloat(cs.paddingBottom) || 0,
+    left: parseFloat(cs.paddingLeft) || 0
+  };
+  document.documentElement.removeChild(el);
+  var sdkInsets = null;
+  var sdkInsetsSource = null;
+  var sdkInsetsError = undefined;
+  try {
+    var sdk = window.__sdk;
+    var ait = window.__ait;
+    if (sdk && sdk.SafeAreaInsets && typeof sdk.SafeAreaInsets.get === 'function') {
+      sdkInsets = sdk.SafeAreaInsets.get();
+      sdkInsetsSource = 'window.__sdk';
+    } else if (sdk && typeof sdk.getSafeAreaInsets === 'function') {
+      sdkInsets = sdk.getSafeAreaInsets();
+      sdkInsetsSource = 'window.__sdk';
+    } else if (ait && ait.state && ait.state.safeAreaInsets &&
+               typeof ait.state.safeAreaInsets.top === 'number') {
+      var s = ait.state.safeAreaInsets;
+      sdkInsets = { top: s.top, bottom: s.bottom, left: s.left, right: s.right };
+      sdkInsetsSource = 'window.__ait';
+    } else if (!sdk && !ait) {
+      sdkInsetsError = 'neither window.__sdk (relay) nor window.__ait (mock) available';
+    } else if (sdk) {
+      sdkInsetsError = 'neither SafeAreaInsets.get nor getSafeAreaInsets found on window.__sdk';
+    } else {
+      sdkInsetsError = 'window.__ait.state.safeAreaInsets is missing or malformed';
+    }
+  } catch(e) {
+    sdkInsetsError = String(e && e.message || e);
+  }
+  var navBarHeight = null;
+  var navBarHeightSource = 'not-exposed-by-sdk';
+  try {
+    var nb = document.querySelector('.ait-navbar');
+    if (nb) {
+      navBarHeight = nb.getBoundingClientRect().height;
+      navBarHeightSource = 'dom-.ait-navbar';
+    }
+  } catch(_) {}
+  var result = {
+    cssEnv: cssEnv,
+    sdkInsets: sdkInsets,
+    sdkInsetsSource: sdkInsetsSource,
+    navBarHeight: navBarHeight,
+    navBarHeightSource: navBarHeightSource,
+    innerWidth: window.innerWidth,
+    innerHeight: window.innerHeight,
+    devicePixelRatio: window.devicePixelRatio,
+    userAgent: navigator.userAgent
+  };
+  if (sdkInsetsError !== undefined) result.sdkInsetsError = sdkInsetsError;
+  return JSON.stringify(result);
+})()
+`.trim();
+//#endregion
+//#region src/mcp/tunnel.ts
+/**
+* cloudflared quick tunnel + attach banner for the debug-mode MCP server.
+*
+* On spawn, the debug server opens an accountless `*.trycloudflare.com` quick
+* tunnel to the local Chii relay so the phone can attach over a public wss URL,
+* then prints a unicode half-block QR + attach instructions. When TOTP auth is
+* enabled (`AIT_DEBUG_TOTP_SECRET` is set), the QR encodes only the base relay
+* URL — the TOTP code (`at=`) is NOT included because it rotates every 30 s
+* and would be stale by the time a human scans. The in-app deep-link builder
+* splices the live code at attach time.
+*
+* Tunnel health probe (`TunnelHealthProbe`):
+*   After the tunnel is up, a periodic HTTP HEAD probe hits the tunnel's
+*   `https://` URL every `probeIntervalMs` (default 60 s). Two consecutive
+*   failures trigger a reissue attempt (spawn a new cloudflared quick tunnel
+*   and redirect traffic). After `MAX_REISSUE_ATTEMPTS` (3) consecutive
+*   reissue failures, the probe gives up and marks the tunnel permanently
+*   dropped — `tunnelStatus.up` becomes false with `droppedAt` set. The caller
+*   should surface this to the agent so the user knows to restart the server.
+*
+* SECRET-HANDLING: The TOTP secret and computed code values MUST NOT appear
+* in any output from this module.
+*
+* Node-only: spawns the cloudflared binary and writes to stdout/stderr.
+*/
+/** Generates a 32-byte hex attach token shown as a pairing hint (relay-side validation is a later phase). */
+function generateAttachToken() {
+	return randomBytes(32).toString("hex");
+}
+/** Ensures the cloudflared binary is installed (downloads + caches on first run). */
+async function ensureCloudflaredBin() {
+	const { existsSync } = await import("node:fs");
+	if (!existsSync(bin)) await install(bin);
+}
+/**
+* Opens a cloudflared quick tunnel to the local relay port and resolves once
+* the public URL is assigned.
+*
+* FIX 1 (issue #571): after URL resolution the returned `QuickTunnel` object
+* watches the cloudflared child process for unexpected exits and calls any
+* registered `onUnexpectedExit` callback so the health probe can immediately
+* trigger reissue instead of waiting for the next poll interval.
+*/
+async function startQuickTunnel(localPort) {
+	await ensureCloudflaredBin();
+	const tunnel = Tunnel.quick(`http://127.0.0.1:${localPort}`);
+	const url = await new Promise((resolve, reject) => {
+		const onUrl = (assigned) => {
+			cleanup();
+			resolve(assigned);
+		};
+		const onError = (err) => {
+			cleanup();
+			reject(err);
+		};
+		const onExit = (code) => {
+			cleanup();
+			reject(/* @__PURE__ */ new Error(`cloudflared exited before assigning a URL (code ${code})`));
+		};
+		const cleanup = () => {
+			tunnel.off("url", onUrl);
+			tunnel.off("error", onError);
+			tunnel.off("exit", onExit);
+		};
+		tunnel.once("url", onUrl);
+		tunnel.once("error", onError);
+		tunnel.once("exit", onExit);
+	});
+	let intentionalStop = false;
+	let unexpectedExitCb = null;
+	tunnel.once("exit", (code) => {
+		if (!intentionalStop && unexpectedExitCb !== null) unexpectedExitCb(code);
+	});
+	return {
+		url,
+		wssUrl: url.replace(/^https/, "wss"),
+		childPid: tunnel.process?.pid,
+		onUnexpectedExit(cb) {
+			unexpectedExitCb = cb;
+		},
+		stop() {
+			intentionalStop = true;
+			tunnel.stop();
+		}
+	};
+}
+/**
+* Renders a pure unicode half-block QR string for the given text.
+*
+* Uses `qrcode` (Node full lib) to get the raw bit matrix, then encodes every
+* two vertical modules into a single half-block character:
+*   - both dark  → `█`
+*   - top only   → `▀`
+*   - bottom only → `▄`
+*   - both light → ` ` (space)
+*
+* The output contains **zero ANSI escape codes**, so it renders correctly in
+* every surface (terminal, VS Code, JetBrains, web) and can be scanned by a
+* phone camera when shown verbatim in an agent response.
+*
+* Shared by `renderAttachBanner` (relay wssUrl QR) and the `start_attach`
+* MCP tool response (attach deep-link QR).
+*/
+async function renderQr(text) {
+	const { default: QRCode } = await import("qrcode");
+	const qr = QRCode.create(text, { errorCorrectionLevel: "M" });
+	const size = qr.modules.size;
+	const data = qr.modules.data;
+	const isDark = (x, y) => {
+		if (x < 0 || y < 0 || x >= size || y >= size) return false;
+		return data[y * size + x] === 1;
+	};
+	const QUIET = 1;
+	const lines = [];
+	for (let y = -QUIET; y < size + QUIET; y += 2) {
+		let line = "";
+		for (let x = -QUIET; x < size + QUIET; x++) {
+			const top = isDark(x, y);
+			const bot = isDark(x, y + 1);
+			line += top && bot ? "█" : top ? "▀" : bot ? "▄" : " ";
+		}
+		lines.push(line);
+	}
+	return `${lines.join("\n")}\n`;
+}
+/**
+* Renders the attach banner (relay URL + unicode half-block QR) as a string.
+*
+* The QR is produced by `renderQr` (a half-block matrix, not the
+* `qrcode-terminal` ASCII art used by the unplugin banner) and encodes the
+* base `wssUrl` only. When `totpEnabled` is true, a note
+* is added that attach URLs generated by `start_attach` will include a
+* live TOTP code (`at=`) appended at call time.
+*
+* SECRET-HANDLING: no secret value, TOTP code, or intermediate value is
+* included in this output.
+*/
+async function renderAttachBanner(input) {
+	const qr = await renderQr(input.wssUrl);
+	const authNote = input.totpEnabled ? "  auth:          TOTP enabled — attach URLs include a rotating code (at=)." : "  auth:          none (set AIT_DEBUG_TOTP_SECRET to enable TOTP).";
+	return [
+		"",
+		"AIT debug — attach a mini-app to this session",
+		"",
+		`  relay (wss):   ${input.wssUrl}`,
+		authNote,
+		"",
+		"  Use start_attach to generate a deep link with the current TOTP code.",
+		"  Scan the QR to locate the relay (open the dog-food URL separately with",
+		"  ?debug=1&relay=<wss>&at=<code> or use the start_attach tool):",
+		"",
+		qr
+	].join("\n");
+}
+/** Prints the attach banner to stderr (stdout is the MCP stdio channel). */
+async function printAttachBanner(input) {
+	const banner = await renderAttachBanner(input);
+	process.stderr.write(`${banner}\n`);
+}
+/**
+* Probes `https://` URL with an HTTP HEAD request.
+* Returns `true` when the server responds (any HTTP status), `false` on
+* network error or timeout.
+*
+* We treat any HTTP response (including 4xx/5xx) as "tunnel alive" because
+* cloudflared itself responds to the HEAD — if the tunnel process died, the
+* request fails at the network level rather than returning a status code.
+*
+* @param httpsUrl - The `https://` tunnel URL to probe.
+* @param timeoutMs - Abort timeout in ms. Default 10 000.
+*/
+async function probeTunnel(httpsUrl, timeoutMs = 1e4) {
+	const { default: https } = await import("node:https");
+	return new Promise((resolve) => {
+		const url = new URL(httpsUrl);
+		const timer = setTimeout(() => {
+			req.destroy();
+			resolve(false);
+		}, timeoutMs);
+		const req = https.request({
+			hostname: url.hostname,
+			port: 443,
+			path: url.pathname || "/",
+			method: "HEAD"
+		}, (_res) => {
+			clearTimeout(timer);
+			_res.resume();
+			resolve(true);
+		});
+		req.on("error", () => {
+			clearTimeout(timer);
+			resolve(false);
+		});
+		req.end();
+	});
+}
+/**
+* Starts a periodic health probe for a cloudflared quick tunnel.
+*
+* Every `probeIntervalMs` the probe sends an HTTP HEAD request to the tunnel's
+* `https://` URL. When `failuresBeforeReissue` consecutive failures are
+* detected, it attempts to spawn a new tunnel (up to `MAX_REISSUE_ATTEMPTS`
+* times). On success the caller is notified via `onReissue`; on permanent
+* failure via `onPermanentDrop`.
+*
+* FIX 1 (issue #571): the probe also subscribes to each tunnel's
+* `onUnexpectedExit` callback to detect child death *immediately* instead of
+* waiting for the next probe interval (which could be 60 s away).
+*
+* @returns `stop` — call during server shutdown to clear the probe interval.
+*/
+function startTunnelHealthProbe(initialTunnel, localPort, options) {
+	const { probeIntervalMs = 6e4, failuresBeforeReissue = 2, onReissue, onPermanentDrop, log = (msg) => process.stderr.write(msg), probe = probeTunnel, spawnTunnel = startQuickTunnel } = options;
+	let currentTunnel = initialTunnel;
+	let consecutiveFailures = 0;
+	let reissueAttempts = 0;
+	let stopped = false;
+	const doReissueOrDrop = async () => {
+		if (stopped) return;
+		reissueAttempts += 1;
+		if (reissueAttempts > 3) return;
+		log(`[ait-debug] tunnel drop detected — reissuing (attempt ${reissueAttempts}/3)\n`);
+		try {
+			const newTunnel = await spawnTunnel(localPort);
+			try {
+				currentTunnel.stop();
+			} catch {}
+			currentTunnel = newTunnel;
+			consecutiveFailures = 0;
+			armChildExitWatch(newTunnel);
+			log(`[ait-debug] tunnel reissued — new relay: ${newTunnel.wssUrl}\n`);
+			onReissue(newTunnel);
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			log(`[ait-debug] tunnel reissue attempt ${reissueAttempts} failed: ${message}\n`);
+			if (reissueAttempts >= 3) {
+				clearInterval(handle);
+				stopped = true;
+				const droppedAt = (/* @__PURE__ */ new Date()).toISOString();
+				log(`[ait-debug] tunnel permanently dropped after 3 reissue attempts — restart the debug server to continue (npx @ait-co/devtools devtools-mcp).
+`);
+				onPermanentDrop(droppedAt);
+			}
+		}
+	};
+	const armChildExitWatch = (t) => {
+		t.onUnexpectedExit((code) => {
+			if (stopped) return;
+			log(`[ait-debug] cloudflared child exited unexpectedly (code=${code}) — triggering immediate reissue\n`);
+			consecutiveFailures = failuresBeforeReissue;
+			doReissueOrDrop();
+		});
+	};
+	armChildExitWatch(initialTunnel);
+	const handle = setInterval(() => {
+		(async () => {
+			if (stopped) return;
+			const httpsUrl = currentTunnel.url;
+			if (await probe(httpsUrl)) {
+				if (consecutiveFailures > 0) log("[ait-debug] tunnel health probe: tunnel recovered\n");
+				consecutiveFailures = 0;
+				reissueAttempts = 0;
+				return;
+			}
+			consecutiveFailures += 1;
+			log(`[ait-debug] tunnel health probe: failure ${consecutiveFailures}/${failuresBeforeReissue} (url=${httpsUrl})\n`);
+			if (consecutiveFailures < failuresBeforeReissue) return;
+			await doReissueOrDrop();
+		})();
+	}, probeIntervalMs);
+	return { stop() {
+		stopped = true;
+		clearInterval(handle);
+	} };
+}
+/**
+* Builds a `TunnelStatus` snapshot that includes drop state.
+*
+* Convenience helper for callers (debug-server) that maintain a mutable
+* `tunnelStatus` object — keeps the shape construction in one place.
+*/
+function makeTunnelStatus(up, wssUrl, droppedAt = null, reissueAttempts = 0) {
+	return {
+		up,
+		wssUrl,
+		droppedAt,
+		reissueAttempts
+	};
+}
+//#endregion
+//#region src/mcp/attach-orchestrator.ts
+/**
+* Maximum age (ms) of a page's `lastSeenAt` before it is treated as a ghost
+* and excluded from the `wait_for_attach` short-circuit in `start_attach`
+* (issue #610).
+*
+* Rationale: the env-2 relay is owned by the dev server (unplugin), so every
+* `dev:phone:cdp` restart produces a new quick-tunnel. The old relay goes
+* offline immediately, but the daemon's warm `ChiiCdpConnection` still lists
+* the last-seen target — its `lastSeenAt` freezes at the moment the old relay
+* died. A 5-minute threshold is large enough to be invisible in normal usage
+* (active CDP sessions see a message every few seconds) while being small
+* enough to catch a relay that went down before the daemon was re-entered.
+*
+* Injectable for tests via {@link AttachDeps.stalePageThresholdMs}.
+*/
+const RELAY_SANDBOX_STALE_PAGE_MS = 300 * 1e3;
+/**
+* Segment length (ms) of the `start_attach` wait loop (issue #626 — TOTP in-call
+* re-mint). The single-shot `wait_for_attach` of the old attach tool could
+* not re-mint a TOTP code mid-wait; `start_attach` decomposes the wait into
+* SEGMENT_MS slices so it can detect an aging code between slices and re-mint a
+* fresh one without the agent re-calling the tool. 30 s = one TOTP step.
+*/
+const START_ATTACH_SEGMENT_MS = 3e4;
+/**
+* Elapsed-since-mint threshold (ms) at which `start_attach` re-mints a fresh
+* TOTP code during its wait loop (issue #626). The relay gate accepts a code for
+* `RELAY_VERIFY_SKEW_STEPS` (6) × 30 s = 180 s backwards from issuance; we re-mint
+* at 150 s to leave a 30 s margin so a phone scan never lands on an expired code.
+*/
+const START_ATTACH_REMINT_THRESHOLD_MS = 15e4;
+/**
+* Predicate used by `start_attach`'s `wait_for_attach` loop to decide
+* whether the relay-sandbox connection has a genuinely fresh page attached.
+*
+* Stale-ghost gating (issue #610): when the dev server restarts with a new
+* quick-tunnel, the warm `ChiiCdpConnection` still lists the last-seen target
+* but its `lastSeenAt` is frozen. A page whose `lastSeenAt` exceeds
+* `stalePageThresholdMs` is a ghost from the dead relay — it must NOT
+* short-circuit `wait_for_attach`.
+*
+* Rules:
+* - `pages.length === 0` → false (nothing attached).
+* - Connection has no `getLastSeenAt` (test fakes, local-browser) → falls back
+*   to `pages.length > 0` (regression-safe).
+* - `seenMs === null` → treat as fresh (no CDP message received yet, first
+*   message pending — the connection is alive).
+* - Otherwise: at least one page must satisfy `nowMs - seenMs <=
+*   stalePageThresholdMs`.
+*
+* Exported for unit testing.
+*/
+function isSandboxPageFresh(pages, getLastSeenAt, nowMs, stalePageThresholdMs) {
+	if (pages.length === 0) return false;
+	if (getLastSeenAt === null) return true;
+	return pages.some((p) => {
+		const seenMs = getLastSeenAt(p.id);
+		if (seenMs === null) return true;
+		return nowMs - seenMs <= stalePageThresholdMs;
+	});
+}
+/**
+* Parses `_deploymentId` from the query string of a scheme URL.
+*
+* Returns `null` when the param is absent or empty — callers treat that as
+* "no deploymentId filter; match on presence only" and fall back to the
+* original `attachedPages.length > 0` condition.
+*
+* SECRET-HANDLING: deploymentId is a public identifier and may appear in
+* debug output. Never confuse it with TOTP secrets or relay tunnel URLs.
+*/
+function extractDeploymentId(schemeUrl) {
+	try {
+		const qIndex = schemeUrl.indexOf("?");
+		if (qIndex === -1) return null;
+		const id = new URLSearchParams(schemeUrl.slice(qIndex + 1)).get("_deploymentId");
+		return id && id.length > 0 ? id : null;
+	} catch {
+		return null;
+	}
+}
+/** Resolves `deps.stalePageThresholdMs` to its default. */
+function resolveStalePageThresholdMs(deps) {
+	return deps.stalePageThresholdMs ?? 3e5;
+}
+/** Resolves `deps.nowMs` to its default (`Date.now`). */
+function resolveNowMs(deps) {
+	return deps.nowMs ?? (() => Date.now());
+}
+/** Resolves `deps.canOpenBrowser` to the module default. */
+function resolveCanOpenBrowser(deps) {
+	return deps.canOpenBrowser ?? canOpenBrowser;
+}
+/**
+* Waits for the first target matching `filterFn` to attach, using the
+* event-driven `waitForFirstTarget()` when the connection supports it
+* (interface-optional member, present on `ChiiCdpConnection`), or falling
+* back to a polling loop for connections that don't implement it (test fakes,
+* `LocalCdpConnection`).
+*
+* This eliminates the polling-only race that previously caused `wait_for_attach`
+* to resolve before the relay had observed the first inbound CDP message from
+* the phone.
+*
+* Timeout note: callers (e.g. the `start_attach` path) always pass an
+* explicit `timeoutMs`, sourced from the factory's `waitForAttachTimeoutMs`
+* (default 60 000). That value is forwarded to `waitForFirstTarget`, so it
+* overrides that method's own 90 000 signature default — the effective
+* wait on the tool path is 60 s, not 90 s.
+*
+* @param connection - The CDP connection (production or fake).
+* @param filterFn   - Resolves when this predicate is satisfied.
+* @param timeoutMs  - Maximum wait time in ms.
+* @param pollIntervalMs - Fallback poll interval for connections without waitForFirstTarget.
+*/
+function waitForAttachWithEvents(connection, filterFn, timeoutMs, pollIntervalMs = 1e3) {
+	if (connection.waitForFirstTarget) return connection.waitForFirstTarget(filterFn, timeoutMs, pollIntervalMs);
+	return new Promise((resolve, reject) => {
+		const deadline = Date.now() + timeoutMs;
+		let settled = false;
+		const poll = setInterval(() => {
+			const targets = connection.listTargets();
+			if (filterFn(targets)) {
+				settled = true;
+				clearInterval(poll);
+				resolve(targets);
+			} else if (Date.now() >= deadline) {
+				settled = true;
+				clearInterval(poll);
+				reject(/* @__PURE__ */ new Error(`waitForAttachWithEvents: 타임아웃 (${timeoutMs}ms)`));
+			}
+		}, pollIntervalMs);
+		const targets = connection.listTargets();
+		if (!settled && filterFn(targets)) {
+			settled = true;
+			clearInterval(poll);
+			resolve(targets);
+		}
+	});
+}
+/**
+* Synthesizes an attach URL from stored components with a FRESHLY-minted TOTP
+* code (issue #626 §3/§4 — the single mint point). Reads the late-bound secret
+* via `deps.getTotpSecret()` so the project-local `.ait_relay` secret loaded by
+* `switchMode` is visible. SECRET-HANDLING: the minted code rides inside the
+* URL's `at=` param only — never logged or returned separately.
+*/
+function mintAttachUrl(deps, parts) {
+	const secret = deps.getTotpSecret();
+	const code = secret ? generateTotp(secret) : void 0;
+	return parts.kind === "launcher" ? buildLauncherAttachUrl(parts.tunnelHttpUrl, parts.wssUrl, code, {
+		name: parts.appName,
+		...parts.selfdebug ? { selfdebug: true } : {}
+	}) : buildDeepLinkAttachUrl(parts.schemeUrl, parts.wssUrl, code);
+}
+/** Builds the fresh TOTP metadata (expiresAt window) for a tool result. */
+function buildTotpMeta(deps) {
+	const secret = deps.getTotpSecret();
+	if (secret === void 0 || secret === "") return void 0;
+	const STEP_SECONDS = 30;
+	const expiresAtMs = resolveNowMs(deps)() + 6 * STEP_SECONDS * 1e3;
+	return {
+		enabled: true,
+		ttlSeconds: 6 * STEP_SECONDS,
+		expiresAt: new Date(expiresAtMs).toISOString()
+	};
+}
+/**
+* Env-specific validation + component bundle for `start_attach` (issue #626).
+* Branches on `env`: `relay-mobile` reads AIT_TUNNEL_BASE_URL + builds launcher
+* parts; `relay-dev` requires scheme_url + builds scheme parts. Returns
+* `{ ok: false, error }` with a ready McpResult on any failure.
+*/
+async function prepareAttach(deps, env, args, conn) {
+	const { getTunnelStatus, getTotpSecret } = deps;
+	const stalePageThresholdMs = resolveStalePageThresholdMs(deps);
+	const nowMs = resolveNowMs(deps);
+	const selfdebug = args?.selfdebug === true;
+	if (selfdebug && env !== "relay-mobile") return {
+		ok: false,
+		error: mcpError("start_attach: selfdebug=true는 env 2 / relay-sandbox 전용 기능입니다. 현재 환경(env 3)에서는 launcher가 없어 self-target 모드를 지원하지 않습니다. launcher self-target이 필요하다면 relay-sandbox 모드로 전환하세요.")
+	};
+	if (env === "relay-mobile") {
+		const rawProjectRoot = args?.projectRoot;
+		const buildProjectRoot = typeof rawProjectRoot === "string" ? rawProjectRoot : void 0;
+		let tunnelHttpUrl = process.env.AIT_TUNNEL_BASE_URL?.trim() ?? "";
+		if (tunnelHttpUrl === "" && buildProjectRoot !== void 0) {
+			const { readRelayUrls } = await import("./relay-url-store-CdA58fgw.js");
+			tunnelHttpUrl = (await readRelayUrls({ projectRoot: buildProjectRoot }))?.tunnelBaseUrl ?? "";
+		}
+		if (tunnelHttpUrl === "") return {
+			ok: false,
+			error: mcpError("start_attach(mobile): AIT_TUNNEL_BASE_URL이 설정되지 않았습니다. dev 서버가 tunnel:{cdp:true}로 기동 중이면 .ait_urls 파일이 자동 생성돼 있어야 합니다. 자동 발견이 되지 않을 경우 앱 HTTP 터널 URL을 AIT_TUNNEL_BASE_URL 환경변수로 직접 전달하세요.")
+		};
+		const tunnelStatus = getTunnelStatus();
+		if (!tunnelStatus.up || tunnelStatus.wssUrl === null) return {
+			ok: false,
+			error: mcpError("start_attach(mobile): relay wssUrl이 아직 설정되지 않았습니다. unplugin tunnel:{cdp:true}가 relay를 완전히 기동할 때까지 잠시 후 다시 시도하세요.")
+		};
+		const secret = getTotpSecret();
+		if (secret === void 0 || secret === "") return {
+			ok: false,
+			error: mcpError("start_attach(relay): TOTP secret(AIT_DEBUG_TOTP_SECRET)이 설정되지 않았습니다. relay 환경은 TOTP 인증이 필수입니다 — relay를 secret과 함께 재기동하세요.")
+		};
+		let launcherAppName;
+		if (buildProjectRoot !== void 0) try {
+			const { readFileSync } = await import("node:fs");
+			const pkgRaw = readFileSync(`${buildProjectRoot}/package.json`, "utf8");
+			const pkg = JSON.parse(pkgRaw);
+			const rawName = typeof pkg.name === "string" ? pkg.name : "";
+			launcherAppName = (rawName.includes("/") ? rawName.slice(rawName.indexOf("/") + 1) : rawName).trim() || void 0;
+		} catch {}
+		const parts = {
+			kind: "launcher",
+			tunnelHttpUrl,
+			wssUrl: tunnelStatus.wssUrl,
+			appName: launcherAppName,
+			...selfdebug ? { selfdebug: true } : {}
+		};
+		const connAsAny = conn;
+		const getLastSeenAt = typeof connAsAny.getTargetLastSeenAt === "function" ? (id) => connAsAny.getTargetLastSeenAt(id) : null;
+		const callNow = nowMs();
+		const isMatchingPage = (pages) => isSandboxPageFresh(pages, getLastSeenAt, callNow, stalePageThresholdMs);
+		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 {
+			ok: true,
+			parts,
+			isMatchingPage,
+			buildTimeoutError,
+			authorityWarning: void 0,
+			totpMeta: buildTotpMeta(deps)
+		};
+	}
+	const schemeUrl = args?.scheme_url;
+	if (typeof schemeUrl !== "string" || schemeUrl === "") return {
+		ok: false,
+		error: mcpError("start_attach: scheme_url이 비어 있습니다. `ait deploy --scheme-only`가 출력하는 intoss-private:// URL을 인자로 전달하세요. 환경 2(mobile)라면 scheme_url 대신 AIT_TUNNEL_BASE_URL을 설정하세요.")
+	};
+	{
+		const relaySecret = getTotpSecret();
+		if (relaySecret === void 0 || relaySecret === "") return {
+			ok: false,
+			error: mcpError("start_attach(relay): TOTP secret(AIT_DEBUG_TOTP_SECRET)이 설정되지 않았습니다. relay 환경은 TOTP 인증이 필수입니다 — relay를 secret과 함께 재기동하세요.")
+		};
+	}
+	const tunnelForBuild = getTunnelStatus();
+	if (!tunnelForBuild.up || tunnelForBuild.wssUrl === null) return {
+		ok: false,
+		error: classifyToolError(/* @__PURE__ */ new Error("tunnel-down:"), "start_attach")
+	};
+	const authorityWarning = validateSchemeAuthority(schemeUrl) ?? void 0;
+	const parts = {
+		kind: "scheme",
+		schemeUrl,
+		wssUrl: tunnelForBuild.wssUrl
+	};
+	const deploymentId = extractDeploymentId(schemeUrl);
+	if (!deploymentId) logInfo("tool.call", {
+		tool: "start_attach",
+		msg: "no _deploymentId in scheme_url; matching on presence only"
+	});
+	const isMatchingPage = (pages) => {
+		if (pages.length === 0) return false;
+		if (deploymentId === null) return true;
+		return pages.some((p) => p.url.includes(deploymentId));
+	};
+	const buildTimeoutError = (baseText, timeoutSec, observed) => {
+		const observedUrls = observed.slice(0, 3).map((p) => p.url.slice(0, 80)).join(", ");
+		const observedNote = observed.length > 0 ? ` — previously attached pages: [${observedUrls}]` : "";
+		return `${baseText}\n\nNo page${deploymentId ? ` matching deploymentId=${deploymentId}` : ""} attached within ${timeoutSec}s${observedNote} — call list_pages to retry.`;
+	};
+	return {
+		ok: true,
+		parts,
+		isMatchingPage,
+		buildTimeoutError,
+		authorityWarning,
+		totpMeta: buildTotpMeta(deps)
+	};
+}
+/**
+* QR render + browser open + segmented attach wait with in-call TOTP re-mint
+* (issue #626 §3). Shared by env-2 and env-3 (4 render paths:
+* headless / browser-opened / browser-open-failed / no-http-server).
+*
+* The wait is decomposed into `START_ATTACH_SEGMENT_MS` slices. Between slices,
+* if the current TOTP code has aged past `START_ATTACH_REMINT_THRESHOLD_MS`,
+* a fresh URL is minted via `mintAttachUrl` and pushed to the dashboard via
+* `onAttachUrlBuilt` (SSE refresh — NO browser re-open). The `reminted` count
+* rides in the success/timeout result.
+*
+* SECRET-HANDLING: attachUrl encodes tunnel/scheme host + the TOTP `at=` code
+* in the QR payload only. The browser is opened on a 127.0.0.1 URL only. The
+* tool result carries `totp.expiresAt` + `reminted` count — never the code.
+*/
+async function renderAndMaybeWait(deps, prep, waitForAttach, callTimeoutMs, conn) {
+	const { getTunnelStatus, qrHttpServer, onAttachUrlBuilt } = deps;
+	const nowMs = resolveNowMs(deps);
+	const canOpenBrowserFn = resolveCanOpenBrowser(deps);
+	const { parts, isMatchingPage, buildTimeoutError, authorityWarning, totpMeta } = prep;
+	let attachUrl = mintAttachUrl(deps, parts);
+	onAttachUrlBuilt?.(parts);
+	let totpIssuedAt = nowMs();
+	let reminted = 0;
+	const relayUrl = parts.wssUrl;
+	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 = authorityWarning ? `⚠️  scheme_url 경고: ${authorityWarning}\n\n` : "";
+	const guiAvailable = canOpenBrowserFn();
+	/** Builds the totp object surfaced in results (fresh expiresAt + reminted). */
+	const totpResult = () => {
+		if (!totpMeta) return void 0;
+		const expiresAtMs = totpIssuedAt + 180 * 1e3;
+		return {
+			enabled: true,
+			ttlSeconds: totpMeta.ttlSeconds,
+			expiresAt: new Date(expiresAtMs).toISOString(),
+			...reminted > 0 ? { reminted } : {}
+		};
+	};
+	/**
+	* Segmented wait with TOTP re-mint (issue #626 §3). Resolves with the
+	* attached page list, or rejects on timeout. Between SEGMENT_MS slices it
+	* re-mints when the code has aged past the threshold (max ~4 re-mints over
+	* 600 s). Returns immediately once a matching page attaches (no re-mint).
+	*/
+	async function waitWithRemint() {
+		const deadline = nowMs() + callTimeoutMs;
+		if (isMatchingPage(conn.listTargets())) return conn.listTargets();
+		for (;;) {
+			const remaining = deadline - nowMs();
+			if (remaining <= 0) throw new Error(`start_attach: 타임아웃 (${callTimeoutMs}ms)`);
+			const segmentMs = Math.min(START_ATTACH_SEGMENT_MS, remaining);
+			try {
+				return await waitForAttachWithEvents(conn, isMatchingPage, segmentMs);
+			} catch {
+				if (totpMeta && nowMs() - totpIssuedAt >= 15e4) {
+					attachUrl = mintAttachUrl(deps, parts);
+					onAttachUrlBuilt?.(parts);
+					totpIssuedAt = nowMs();
+					reminted += 1;
+				}
+			}
+		}
+	}
+	/**
+	* Assembles the success result after a page attaches. `baseText` carries the
+	* QR + pre-wait JSON block (the QR the user already scanned). The attach
+	* itself ends the wait, so the QR is moot — what matters now is the final
+	* TOTP state. If the segmented wait re-minted (issue #626 §3), surface the
+	* post-wait `totp` block (fresh `expiresAt` + `reminted` count) so the result
+	* reflects how many times the code rotated during the wait. SECRET-HANDLING:
+	* the totp block carries expiresAt + reminted only — never the code value.
+	*/
+	const successResult = (baseText) => {
+		const pagesResult = listPages(conn, getTunnelStatus());
+		const finalTotp = totpResult();
+		const remintNote = finalTotp && reminted > 0 ? `\n\n${JSON.stringify({ totp: finalTotp }, null, 2)}` : "";
+		return { content: [{
+			type: "text",
+			text: `${baseText}\n\n${JSON.stringify(pagesResult, null, 2)}${remintNote}`
+		}] };
+	};
+	/** Runs the wait (when requested) and returns success/timeout result. */
+	const runWait = async (baseText) => {
+		if (!waitForAttach) return { content: [{
+			type: "text",
+			text: baseText
+		}] };
+		try {
+			await waitWithRemint();
+		} catch {
+			const observed = conn.listTargets();
+			return {
+				content: [{
+					type: "text",
+					text: buildTimeoutError(baseText, callTimeoutMs / 1e3, observed)
+				}],
+				isError: true
+			};
+		}
+		return successResult(baseText);
+	};
+	if (!guiAvailable) {
+		const headlessNote = "GUI 환경이 감지되지 않았습니다 (headless/remote 환경). 텍스트 QR을 폰 카메라로 스캔하거나, 로컬 GUI 환경에서 실행하세요.\n\n";
+		const qr = await renderQr(attachUrl);
+		return runWait(`${warningPrefix}${headlessNote}${header}\n${JSON.stringify({
+			attachUrl,
+			relayUrl,
+			...totpResult() ? { totp: totpResult() } : {}
+		}, null, 2)}\n\n${qr}`);
+	}
+	if (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 } : {}
+			};
+			return runWait(`${warningPrefix}${header}\n${JSON.stringify({
+				relayUrl,
+				openResult,
+				...totpResult() ? { totp: totpResult() } : {}
+			}, null, 2)}\n\n브라우저에서 QR을 열었습니다${retriedNote}. 폰 카메라로 스캔하세요.\nURL: ${browserResult.httpUrl}`);
+		}
+		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 = `브라우저 자동 열기에 실패했습니다. 다음 URL을 직접 브라우저에서 여세요:\n${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stderrNote + "\n\n";
+		const qr = await renderQr(attachUrl);
+		return runWait(`${warningPrefix}${fallbackNote}${header}\n${JSON.stringify({
+			attachUrl,
+			relayUrl,
+			openResult,
+			...totpResult() ? { totp: totpResult() } : {}
+		}, null, 2)}\n\n${qr}`);
+	}
+	const qr = await renderQr(attachUrl);
+	return runWait(`${warningPrefix}${header}\n${JSON.stringify({
+		attachUrl,
+		relayUrl,
+		...totpResult() ? { totp: totpResult() } : {}
+	}, null, 2)}\n\n${qr}`);
+}
+/**
+* Builds a self-contained IIFE DOM expression that renders a dismissible
+* "Debugger Connected" badge on the bottom-left of the phone screen.
+*
+* **Pure function** — returns a JS expression string; does NOT inject it.
+* Injection is performed by {@link injectDebugIndicator} in `cell.ts`.
+*
+* The expression, when evaluated on the page, does the following:
+*   1. Early-returns if `#__ait_debug_indicator` already exists (idempotent —
+*      prevents duplicate badges on re-injection after page reload).
+*   2. Appends a fixed-position `<div id="__ait_debug_indicator">` at the
+*      bottom-left, accounting for safe-area insets.
+*   3. Attaches a `{ once: true }` `pointerdown` listener that removes the
+*      badge on first touch — one-tap dismiss.
+*
+* The expression intentionally contains NO relay URLs, wss addresses, TOTP
+* codes, or any other secrets. It is pure DOM UI text only.
+*
+* SECRET-HANDLING: this expression contains no secrets, relay URLs, wss
+* addresses, or TOTP codes whatsoever — DOM label text only.
+*
+* @param opts.label - Badge text (default: `'Debugger Connected'`).
+* @returns A JS expression string suitable for `Runtime.evaluate`.
+*/
+function buildIndicatorExpression(opts) {
+	const label = opts?.label ?? "Debugger Connected";
+	return `(() => {if (document.getElementById('__ait_debug_indicator')) return;const el = document.createElement('div');el.id = '__ait_debug_indicator';el.style.cssText = ['position:fixed','left:max(12px,calc(env(safe-area-inset-left,0px) + 8px))','bottom:max(12px,calc(env(safe-area-inset-bottom,0px) + 8px))','z-index:2147483647','background:#e5484d','color:#fff','font:bold 11px/1 system-ui,sans-serif','padding:5px 9px','border-radius:6px','pointer-events:auto','user-select:none',].join(';');el.textContent = ${JSON.stringify(label)};el.addEventListener('pointerdown', () => el.remove(), { once: true });document.body.appendChild(el);})()`;
+}
+//#endregion
+export { RELAY_SANDBOX_STALE_PAGE_MS, START_ATTACH_REMINT_THRESHOLD_MS, START_ATTACH_SEGMENT_MS, startTunnelHealthProbe as a, buildIndicatorExpression, extractDeploymentId, startQuickTunnel as i, isSandboxPageFresh, makeTunnelStatus as n, logError as o, prepareAttach, printAttachBanner as r, renderAndMaybeWait, logInfo as s, generateAttachToken as t };
+
+//# sourceMappingURL=attach-orchestrator-CFotueL3.js.map