npm - @ait-co/devtools - Versions diffs - 0.1.38 → 0.1.40 - Mend

@ait-co/devtools 0.1.38 → 0.1.40

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/dist/mcp/cli.js CHANGED Viewed

@@ -649,6 +649,173 @@ async function launchChromium(options = {}) {
 	};
 }
 //#endregion
+//#region src/mcp/qr-http-server.ts
+/**
+* 로컬 HTTP 서버를 127.0.0.1 random port(또는 `AIT_DEBUG_HTTP_PORT` env)로 시작한다.
+* MCP debug server 생애주기에 묶어 사용 — `runDebugServer` shutdown 시 `close()`로 정리.
+*/
+async function startQrHttpServer() {
+	const { default: QRCode } = await import("qrcode");
+	const server = createServer((req, res) => {
+		const [path, query = ""] = (req.url ?? "/").split("?", 2);
+		const params = new URLSearchParams(query ?? "");
+		if (path === "/attach") {
+			const encodedU = params.get("u") ?? "";
+			let attachUrl;
+			try {
+				attachUrl = decodeURIComponent(encodedU);
+			} catch {
+				res.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
+				res.end("잘못된 u 파라미터입니다.");
+				return;
+			}
+			let deploymentIdLabel = "attach";
+			try {
+				const dpMatch = attachUrl.match(/[?&]_deploymentId=([^&]+)/);
+				if (dpMatch?.[1]) deploymentIdLabel = decodeURIComponent(dpMatch[1]).slice(0, 36);
+			} catch {}
+			QRCode.toDataURL(attachUrl, {
+				type: "image/png",
+				errorCorrectionLevel: "M"
+			}).then((dataUrl) => {
+				const html = buildAttachHtml(dataUrl, deploymentIdLabel.replace(/[<>&"']/g, (c) => `&#${c.charCodeAt(0)};`), attachUrl.replace(/[<>&"']/g, (c) => `&#${c.charCodeAt(0)};`));
+				res.writeHead(200, {
+					"Content-Type": "text/html; charset=utf-8",
+					"Cache-Control": "no-store"
+				});
+				res.end(html);
+			}).catch(() => {
+				res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+				res.end("QR 생성에 실패했습니다.");
+			});
+			return;
+		}
+		if (path === "/qr.png") {
+			const encodedU = params.get("u") ?? "";
+			let attachUrl;
+			try {
+				attachUrl = decodeURIComponent(encodedU);
+			} catch {
+				res.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
+				res.end("잘못된 u 파라미터입니다.");
+				return;
+			}
+			QRCode.toBuffer(attachUrl, {
+				type: "png",
+				errorCorrectionLevel: "M"
+			}).then((buf) => {
+				res.writeHead(200, {
+					"Content-Type": "image/png",
+					"Cache-Control": "no-store",
+					"Content-Length": String(buf.length)
+				});
+				res.end(buf);
+			}).catch(() => {
+				res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+				res.end("QR PNG 생성에 실패했습니다.");
+			});
+			return;
+		}
+		res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+		res.end("Not Found");
+	});
+	const listenPort = Number(process.env.AIT_DEBUG_HTTP_PORT ?? 0);
+	await new Promise((resolve, reject) => {
+		server.listen(listenPort, "127.0.0.1", () => resolve());
+		server.once("error", reject);
+	});
+	const address = server.address();
+	if (!address || typeof address === "string") throw new Error("qr-http-server: server.address()가 예상하지 못한 형태입니다.");
+	const port = address.port;
+	return {
+		port,
+		buildAttachPageUrl(attachUrl) {
+			return `http://127.0.0.1:${port}/attach?u=${encodeURIComponent(attachUrl)}`;
+		},
+		close() {
+			return new Promise((resolve, reject) => {
+				server.close((err) => err ? reject(err) : resolve());
+			});
+		}
+	};
+}
+/**
+* QR 스캔 페이지 HTML 본문.
+* dark theme, inline style, 외부 fetch 없음.
+*/
+function buildAttachHtml(qrDataUrl, safeLabel, safeAttachUrl) {
+	return `<!DOCTYPE html>
+<html lang="ko">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>AIT 디버그 세션 — QR 스캔</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      background: #0d1117; color: #c9d1d9;
+      display: flex; flex-direction: column; align-items: center;
+      min-height: 100vh; margin: 0; padding: 2rem 1rem;
+      gap: 1.5rem;
+    }
+    h1 { font-size: 1.25rem; font-weight: 600; color: #e6edf3; margin: 0; text-align: center; }
+    .label { font-size: 0.8rem; opacity: 0.5; font-family: monospace; margin: 0; }
+    img.qr {
+      width: min(90vw, 360px); height: auto;
+      image-rendering: pixelated;
+      background: #fff; padding: 1rem; border-radius: 12px;
+    }
+    section { width: 100%; max-width: 480px; }
+    h2 { font-size: 1rem; font-weight: 600; color: #e6edf3; margin: 0 0 0.5rem; }
+    ol, ul { margin: 0; padding-left: 1.25rem; }
+    li { margin-bottom: 0.4rem; font-size: 0.9rem; line-height: 1.5; }
+    .url-box {
+      font-family: monospace; font-size: 0.72rem;
+      word-break: break-all; opacity: 0.4;
+      background: #161b22; padding: 0.75rem 1rem;
+      border-radius: 6px; border: 1px solid #30363d;
+    }
+    hr { border: none; border-top: 1px solid #21262d; width: 100%; margin: 0.5rem 0; }
+  </style>
+</head>
+<body>
+  <h1>AIT 디버그 세션 — QR 스캔</h1>
+  <p class="label">deployment: ${safeLabel}</p>
+  <img class="qr" src="${qrDataUrl}" alt="attach QR" />
+  <section>
+    <h2>스캔 절차</h2>
+    <ol>
+      <li>토스 앱을 실행하세요.</li>
+      <li>폰 카메라 앱으로 QR 코드를 스캔하세요.</li>
+      <li>팝업이 뜨면 <strong>"토스로 열기"</strong>를 탭하세요.</li>
+      <li>미니앱이 열리고 디버그 세션이 자동으로 attach됩니다.</li>
+    </ol>
+  </section>
+  <hr />
+  <section>
+    <h2>진단 체크리스트</h2>
+    <ul>
+      <li><strong>토스 앱이 안 열리는 경우</strong> — 앱 버전 확인, 카메라 앱으로 스캔 (토스 앱 내 QR 리더 X)</li>
+      <li><strong>미니앱이 PREPARE 상태에서 멈추는 경우</strong> — deep-link에 <code>_deploymentId</code> 파라미터가 있는지 확인</li>
+      <li><strong>Chii 주입 실패 / 콘솔이 비어 있는 경우</strong> — 미니앱 번들에 <code>in-app</code> debug import가 있는지 확인</li>
+      <li><strong>TOTP gate Layer C가 비활성인 경우</strong> — relay 서버에 <code>AIT_DEBUG_TOTP_SECRET</code>이 설정돼 있는지 확인</li>
+    </ul>
+  </section>
+  <hr />
+  <section>
+    <h2>URL (fallback)</h2>
+    <p class="url-box">${safeAttachUrl}</p>
+  </section>
+</body>
+</html>`;
+}
+//#endregion
 //#region src/mcp/deeplink.ts
 /**
 * Build a self-attaching dogfood deep link.
@@ -1009,102 +1176,136 @@ function canOpenBrowser() {
 	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]
+		}
+	];
+}
+/** stderr에서 at= TOTP 코드 값을 redact한다. */
+function redactSecrets(text) {
+	return text.replace(/\bat=([^&\s"']+)/g, "at=<redacted>");
+}
+/** 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));
+}
 /**
-* Writes the attach URL as a QR PNG + a wrapper HTML page to the OS temp
-* directory, then opens the HTML in the OS default browser.
+* 로컬 HTTP 서버 URL(`http://127.0.0.1:<port>/attach?u=...`)을 OS 기본 브라우저로 연다.
+*
+* platform별 fallback chain으로 시도하며, 모두 실패해도 `opened: false` + `httpUrl`을
+* 반환해 사용자가 직접 브라우저에 붙여넣을 수 있게 한다.
 *
 * SECRET-HANDLING:
-*   - File names are derived from a short timestamp, NOT from the attach URL or
-*     any token/code value. The `at=` code is NOT in the file name.
-*   - The attach URL (which may carry `at=`) is embedded inside the HTML page
-*     body — that is the intended delivery channel for the QR.
-*   - This function must NOT write the attach URL, deploymentId, or any
-*     TOTP code to stdout, stderr, or any log.
-*
-* @param attachUrl - The deep link to encode as a QR. May contain `at=<code>`.
-* @param deploymentId - Optional human-readable label for the HTML page (e.g. UUID substring).
-*   Must NOT be derived from the `at=` code value.
-* @returns `OpenQrInBrowserResult` — never throws (errors are returned in `.error`).
+*   - tmp 파일을 만들지 않는다 (HTML/PNG는 HTTP 서버가 메모리에서 응답).
+*   - httpUrl/pngUrl은 127.0.0.1 로컬 전용.
+*   - stderr 캡처 결과에서 at= 코드 값을 redact한 후 stderrSummary에 포함.
+*   - attachUrl, deploymentId, TOTP 코드를 stdout/stderr/로그에 직접 출력 금지.
+*
+* @param httpUrl - `http://127.0.0.1:<port>/attach?u=<encoded>` HTTP URL.
+* @param pngUrl  - `http://127.0.0.1:<port>/qr.png?u=<encoded>` PNG fallback URL.
 */
-async function openQrInBrowser(attachUrl, deploymentId) {
-	const { tmpdir } = await import("node:os");
-	const { writeFileSync } = await import("node:fs");
-	const { join } = await import("node:path");
+async function openQrInBrowser(httpUrl, pngUrl) {
 	const { spawnSync } = await import("node:child_process");
-	const { default: QRCode } = await import("qrcode");
-	const stamp = Date.now();
-	const pngPath = join(tmpdir(), `ait-qr-${stamp}.png`);
-	const htmlPath = join(tmpdir(), `ait-qr-${stamp}.html`);
-	try {
-		await QRCode.toFile(pngPath, attachUrl, {
-			type: "png",
-			errorCorrectionLevel: "M"
+	const candidates = getBrowserCandidates(httpUrl);
+	const stderrLines = [];
+	for (const { cmd, args } of candidates) {
+		const result = spawnSync(cmd, args, {
+			encoding: "utf8",
+			timeout: 5e3
 		});
-	} catch (err) {
-		return {
-			opened: false,
-			htmlPath,
-			pngPath,
-			error: `QR PNG write failed: ${err instanceof Error ? err.message : String(err)}`
-		};
-	}
-	const htmlContent = `<!DOCTYPE html>
-<html lang="ko">
-<head>
-  <meta charset="utf-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>AIT Debug — QR</title>
-  <style>
-    body { font-family: monospace; background: #111; color: #eee; display: flex; flex-direction: column; align-items: center; justify-content: center; min-height: 100vh; margin: 0; gap: 1.5rem; padding: 2rem; box-sizing: border-box; }
-    img { width: min(90vw, 400px); height: auto; image-rendering: pixelated; background: #fff; padding: 1rem; border-radius: 8px; }
-    .label { font-size: 0.85rem; opacity: 0.6; }
-    .url { font-size: 0.75rem; word-break: break-all; max-width: 60ch; opacity: 0.5; }
-  </style>
-</head>
-<body>
-  <img src="${pngPath}" alt="QR code" />
-  <p class="label">deployment: ${deploymentId ? deploymentId.replace(/[<>&"']/g, (c) => `&#${c.charCodeAt(0)};`) : "attach"}</p>
-</body>
-</html>`;
-	try {
-		writeFileSync(htmlPath, htmlContent, "utf8");
-	} catch (err) {
-		return {
-			opened: false,
-			htmlPath,
-			pngPath,
-			error: `HTML write failed: ${err instanceof Error ? err.message : String(err)}`
+		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 {
+			opened: true,
+			httpUrl,
+			pngUrl
 		};
 	}
-	const platform = process.platform;
-	let openCmd;
-	let openArgs;
-	if (platform === "darwin") {
-		openCmd = "open";
-		openArgs = [htmlPath];
-	} else if (platform === "win32") {
-		openCmd = "cmd";
-		openArgs = [
-			"/c",
-			"start",
-			"",
-			htmlPath
-		];
-	} else {
-		openCmd = "xdg-open";
-		openArgs = [htmlPath];
-	}
-	const spawnResult = spawnSync(openCmd, openArgs, { timeout: 5e3 });
-	if (spawnResult.error) return {
-		opened: false,
-		htmlPath,
-		pngPath,
-		error: `Browser open failed (${openCmd}): ${spawnResult.error.message}`
-	};
 	return {
-		opened: true,
-		htmlPath,
-		pngPath
+		opened: false,
+		httpUrl,
+		pngUrl,
+		error: "모든 브라우저 실행 후보가 실패했습니다.",
+		stderrSummary: stderrLines.length > 0 ? stderrLines.join("\n") : void 0
 	};
 }
 /** Returns the DOM tree of the attached page (`DOM.getDocument`). */
@@ -1131,8 +1332,14 @@ async function takeScreenshot(connection) {
 * The JS probe injected via `Runtime.evaluate`. It reads:
 *   1. `env(safe-area-inset-*)` via a temporary element with padding set to
 *      those CSS env vars, then `getComputedStyle`.
-*   2. `SafeAreaInsets.get()` if the native SDK object is available.
-*   3. nav bar geometry (first `.ait-navbar` element height, if present).
+*   2. `window.__sdk.SafeAreaInsets.get()` (1st priority) or
+*      `window.__sdk.getSafeAreaInsets()` (2nd priority) — both surfaces
+*      confirmed live on iPhone 15 Pro relay. `window.__sdk` is only present
+*      in dogfood (__DEBUG_BUILD__) bundles; outside those it is undefined.
+*      If both paths fail the result carries `sdkInsetsError` explaining why.
+*   3. nav bar geometry: the SDK does not expose navBar height as a standalone
+*      API — `.ait-navbar` DOM height is read as a cross-check, and
+*      `navBarHeightSource` records where it came from.
 *   4. `innerWidth`, `innerHeight`, `devicePixelRatio`, `navigator.userAgent`.
 *
 * Returns a plain JSON-serialisable object so `returnByValue: true` works.
@@ -1159,25 +1366,42 @@ const SAFE_AREA_PROBE_EXPRESSION = `
   };
   document.documentElement.removeChild(el);
   var sdkInsets = null;
+  var sdkInsetsError = undefined;
   try {
-    if (typeof SafeAreaInsets !== 'undefined' && SafeAreaInsets && typeof SafeAreaInsets.get === 'function') {
-      sdkInsets = SafeAreaInsets.get();
+    var sdk = window.__sdk;
+    if (sdk && sdk.SafeAreaInsets && typeof sdk.SafeAreaInsets.get === 'function') {
+      sdkInsets = sdk.SafeAreaInsets.get();
+    } else if (sdk && typeof sdk.getSafeAreaInsets === 'function') {
+      sdkInsets = sdk.getSafeAreaInsets();
+    } else if (!sdk) {
+      sdkInsetsError = 'window.__sdk not available (non-dogfood bundle)';
+    } else {
+      sdkInsetsError = 'neither SafeAreaInsets.get nor getSafeAreaInsets found on window.__sdk';
     }
-  } catch(_) {}
+  } 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;
+    if (nb) {
+      navBarHeight = nb.getBoundingClientRect().height;
+      navBarHeightSource = 'dom-.ait-navbar';
+    }
   } catch(_) {}
-  return JSON.stringify({
+  var result = {
     cssEnv: cssEnv,
     sdkInsets: sdkInsets,
     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();
 /**
@@ -1209,19 +1433,30 @@ function normalizeSafeAreaResult(rawValue) {
 			left: typeof r.left === "number" ? r.left : 0
 		};
 	}
+	const cssEnv = requireInsets("cssEnv") ?? {
+		top: 0,
+		right: 0,
+		bottom: 0,
+		left: 0
+	};
+	const sdkInsets = requireInsets("sdkInsets");
+	const sdkInsetsError = typeof obj.sdkInsetsError === "string" ? obj.sdkInsetsError : void 0;
+	const navBarHeight = typeof obj.navBarHeight === "number" ? obj.navBarHeight : null;
+	const navBarHeightSource = typeof obj.navBarHeightSource === "string" ? obj.navBarHeightSource : "not-exposed-by-sdk";
+	const innerWidth = typeof obj.innerWidth === "number" ? obj.innerWidth : 0;
+	const innerHeight = typeof obj.innerHeight === "number" ? obj.innerHeight : 0;
+	const devicePixelRatio = typeof obj.devicePixelRatio === "number" ? obj.devicePixelRatio : 1;
+	const userAgent = typeof obj.userAgent === "string" ? obj.userAgent : "";
 	return {
-		cssEnv: requireInsets("cssEnv") ?? {
-			top: 0,
-			right: 0,
-			bottom: 0,
-			left: 0
-		},
-		sdkInsets: requireInsets("sdkInsets"),
-		navBarHeight: typeof obj.navBarHeight === "number" ? obj.navBarHeight : null,
-		innerWidth: typeof obj.innerWidth === "number" ? obj.innerWidth : 0,
-		innerHeight: typeof obj.innerHeight === "number" ? obj.innerHeight : 0,
-		devicePixelRatio: typeof obj.devicePixelRatio === "number" ? obj.devicePixelRatio : 1,
-		userAgent: typeof obj.userAgent === "string" ? obj.userAgent : ""
+		cssEnv,
+		sdkInsets,
+		...sdkInsetsError !== void 0 ? { sdkInsetsError } : {},
+		navBarHeight,
+		navBarHeightSource,
+		innerWidth,
+		innerHeight,
+		devicePixelRatio,
+		userAgent
 	};
 }
 /**
@@ -1623,10 +1858,10 @@ async function printAttachBanner(input) {
 * naturally via `enableDomains`). The tier only controls visibility.
 */
 function createDebugServer(deps) {
-	const { connection, aitSource, getTunnelStatus, waitForAttachTimeoutMs = 9e4 } = deps;
+	const { connection, aitSource, getTunnelStatus, waitForAttachTimeoutMs = 9e4, qrHttpServer } = deps;
 	const server = new Server({
 		name: "ait-debug",
-		version: "0.1.38"
+		version: "0.1.40"
 	}, { capabilities: { tools: { listChanged: true } } });
 	server.setRequestHandler(ListToolsRequestSchema, () => {
 		return { tools: connection.listTargets().length > 0 ? DEBUG_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) : DEBUG_TOOL_DEFINITIONS.filter((tool) => BOOTSTRAP_TOOL_NAMES.has(tool.name)).map((tool) => ({ ...tool })) };
@@ -1666,15 +1901,10 @@ function createDebugServer(deps) {
 				const { attachUrl, relayUrl, authorityWarning } = buildAttachUrl(schemeUrl, getTunnelStatus());
 				const warningPrefix = authorityWarning ? `⚠️  scheme_url 경고: ${authorityWarning}\n\n` : "";
 				const header = "This tool result is shown to the user directly — do NOT re-print the QR below in your reply (it wastes output tokens). Just tell the user to scan the QR in this output (Ctrl+O to expand if collapsed).";
-				if (openInBrowser && canOpenBrowser()) {
-					let deploymentIdLabel;
-					try {
-						const dpMatch = attachUrl.match(/[?&]_deploymentId=([^&]+)/);
-						if (dpMatch?.[1]) deploymentIdLabel = decodeURIComponent(dpMatch[1]).slice(0, 36);
-					} catch {}
-					const browserResult = await openQrInBrowser(attachUrl, deploymentIdLabel);
+				if (openInBrowser && canOpenBrowser() && qrHttpServer) {
+					const browserResult = await openQrInBrowser(qrHttpServer.buildAttachPageUrl(attachUrl), `http://127.0.0.1:${qrHttpServer.port}/qr.png?u=${encodeURIComponent(attachUrl)}`);
 					if (browserResult.opened) {
-						const shortText = `${warningPrefix}${header}\n${JSON.stringify({ relayUrl }, null, 2)}\n\nブラウザにQRを表示しました。\nQR画像: ${browserResult.pngPath}\nHTMLページ: ${browserResult.htmlPath}\n\n브라우저에 QR을 띄웠습니다. 스마트폰 카메라로 스캔하세요.\nPNG: ${browserResult.pngPath}`;
+						const shortText = `${warningPrefix}${header}\n${JSON.stringify({ relayUrl }, null, 2)}\n\n브라우저에서 QR을 열었습니다. 폰 카메라로 스캔하세요.\nURL: ${browserResult.httpUrl}`;
 						if (!waitForAttach) return { content: [{
 							type: "text",
 							text: shortText
@@ -1701,7 +1931,8 @@ function createDebugServer(deps) {
 							text: `${shortText}\n\n${JSON.stringify(pagesResult, null, 2)}`
 						}] };
 					}
-					const fallbackNote = `(브라우저 열기 실패: ${browserResult.error ?? "unknown"} — 텍스트 QR로 대체)\n`;
+					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);
 					const baseText = `${warningPrefix}${fallbackNote}${header}\n${JSON.stringify({
 						attachUrl,
@@ -1941,10 +2172,21 @@ async function runDebugServer(options = {}) {
 `);
 	});
 	const connection = new ChiiCdpConnection({ relayBaseUrl: relay.baseUrl });
+	const aitSource = new ChiiAitSource(connection);
+	let qrServer;
+	startQrHttpServer().then((s) => {
+		qrServer = s;
+	}, (err) => {
+		const message = err instanceof Error ? err.message : String(err);
+		process.stderr.write(`[ait-debug] QR HTTP 서버 시작 실패 (text QR fallback 사용): ${message}\n`);
+	});
 	const server = createDebugServer({
 		connection,
-		aitSource: new ChiiAitSource(connection),
-		getTunnelStatus: () => tunnelStatus
+		aitSource,
+		getTunnelStatus: () => tunnelStatus,
+		get qrHttpServer() {
+			return qrServer;
+		}
 	});
 	const transport = new StdioServerTransport();
 	let closed = false;
@@ -1957,6 +2199,7 @@ async function runDebugServer(options = {}) {
 		tunnel?.stop();
 		relay.close();
 		server.close();
+		qrServer?.close();
 	};
 	process.once("SIGINT", shutdown);
 	process.once("SIGTERM", shutdown);
@@ -2169,7 +2412,7 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.38"
+		version: "0.1.40"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {