@ait-co/devtools 0.1.80 → 0.1.84

package/dist/machine-state-DOUweFsJ.cjs

@@ -0,0 +1,216 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+let node_os = require("node:os");
+let node_path = require("node:path");
+//#region src/telemetry/machine-state.ts
+/**
+* Machine-level telemetry consent store — #542
+*
+* Persists consent to `~/.ait-devtools/telemetry.json` (Node.js side only).
+* This eliminates repeated consent prompts when the dev origin rotates
+* (quick-tunnel host changes per session, localhost port varies).
+*
+* Design invariants:
+*  - localStorage keys in src/telemetry/state.ts are LOCKED — this module does
+*    NOT replace them. It adds a machine-level overlay that takes precedence
+*    when a dev server is running.
+*  - Tier 0 / Tier 1 consent semantics are unchanged — only the storage
+*    location and lifetime change.
+*  - No PII. The file stores: consent enum + decided_at ISO timestamp +
+*    policy_version + anon_id (pseudonymous UUID).
+*  - anon_id is promoted to machine level so the same identity is used across
+*    all dev origins (prevents counting the same developer multiple times).
+*
+* Node.js-only: imported exclusively from the unplugin (server-side).
+* Never imported from panel/browser code.
+*/
+var machine_state_exports = /* @__PURE__ */ __exportAll({
+	ensureMachineConsent: () => ensureMachineConsent,
+	machineStateDir: () => machineStateDir,
+	machineStateFile: () => machineStateFile,
+	promptTtyConsent: () => promptTtyConsent,
+	readMachineState: () => readMachineState,
+	writeMachineState: () => writeMachineState
+});
+/** Resolved directory: `~/.ait-devtools`. */
+function machineStateDir(homeOverride) {
+	return (0, node_path.join)(homeOverride ?? (0, node_os.homedir)(), ".ait-devtools");
+}
+/** Resolved file: `~/.ait-devtools/telemetry.json`. */
+function machineStateFile(homeOverride) {
+	return (0, node_path.join)(machineStateDir(homeOverride), "telemetry.json");
+}
+function isoNow() {
+	return (/* @__PURE__ */ new Date()).toISOString();
+}
+function newUUID() {
+	return crypto.randomUUID();
+}
+/**
+* Returns a minimal MachineStateFsDep using real `node:fs` synchronous APIs.
+* Resolved lazily to avoid pulling node:fs into non-Node environments.
+*/
+async function realFs() {
+	const { existsSync, mkdirSync, readFileSync, writeFileSync } = await import("node:fs");
+	return {
+		existsSync,
+		mkdirSync,
+		readFileSync,
+		writeFileSync
+	};
+}
+/**
+* Reads the machine-level telemetry state.
+* Returns `null` when the file is absent or cannot be parsed.
+*
+* NODE-ONLY. Never call from browser/panel code.
+*/
+async function readMachineState(deps) {
+	const fs = deps?.fs ?? await realFs();
+	const filePath = machineStateFile(deps?.homeDir);
+	if (!fs.existsSync(filePath)) return null;
+	let raw;
+	try {
+		raw = fs.readFileSync(filePath, "utf8");
+	} catch {
+		return null;
+	}
+	try {
+		const parsed = JSON.parse(raw);
+		if (parsed !== null && typeof parsed === "object" && "consent" in parsed && typeof parsed.consent === "string" && [
+			"granted",
+			"denied",
+			"undecided"
+		].includes(parsed.consent)) return parsed;
+		return null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Writes (or patches) the machine-level telemetry state file.
+* Creates `~/.ait-devtools/` if it does not yet exist.
+*
+* NODE-ONLY. Never call from browser/panel code.
+*/
+async function writeMachineState(patch, deps) {
+	const fs = deps?.fs ?? await realFs();
+	const dir = machineStateDir(deps?.homeDir);
+	const filePath = machineStateFile(deps?.homeDir);
+	const now = deps?.now ?? isoNow;
+	const uuid = deps?.randomUUID ?? newUUID;
+	if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+	let existing = null;
+	if (fs.existsSync(filePath)) try {
+		const raw = fs.readFileSync(filePath, "utf8");
+		existing = JSON.parse(raw);
+	} catch {}
+	const next = {
+		...existing ?? {
+			consent: "undecided",
+			decided_at: now(),
+			policy_version: "",
+			anon_id: null
+		},
+		...patch,
+		anon_id: existing?.anon_id ?? patch.anon_id ?? uuid(),
+		decided_at: now()
+	};
+	fs.writeFileSync(filePath, JSON.stringify(next, null, 2), { mode: 384 });
+}
+/**
+* Prompts the user in the terminal (stdin/stdout TTY) to accept or deny
+* telemetry consent — called once per machine on the first `pnpm dev` run.
+*
+* Returns the chosen `ConsentState`, or `'undecided'` when:
+*  - The TTY is not interactive (CI, headless, piped stdin).
+*  - The prompt times out.
+*  - An error occurs.
+*
+* NODE-ONLY. Called from the unplugin `configureServer` hook.
+*/
+async function promptTtyConsent() {
+	if (!process.stdin.isTTY || !process.stdout.isTTY) return "undecided";
+	const { createInterface } = await import("node:readline");
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	const question = (q) => new Promise((resolve) => rl.question(q, resolve));
+	process.stdout.write("\n[@ait-co/devtools] 익명 사용 통계를 보내도 될까요?\n  버전·날짜만 수집하고 PII는 없습니다. 언제든 Environment 탭에서 끌 수 있어요.\n  자세히: https://docs.aitc.dev/privacy\n  (y) 네, 보낼게요  (n) 아니요  (무응답 시 보류 — 다음 기동 때 다시 물어요)\n");
+	let answer = "";
+	try {
+		answer = await Promise.race([question("  > "), new Promise((resolve) => setTimeout(() => resolve(""), 3e4))]);
+	} catch {} finally {
+		rl.close();
+	}
+	const normalized = answer.trim().toLowerCase();
+	if (normalized === "y" || normalized === "yes" || normalized === "네" || normalized === "ㅇ") return "granted";
+	if (normalized === "n" || normalized === "no" || normalized === "아니요" || normalized === "ㄴ") return "denied";
+	return "undecided";
+}
+/**
+* Ensures the machine-level consent state is resolved.
+*
+* Algorithm:
+*  1. Read the machine file.
+*  2. If already decided (granted/denied) → return as-is (no re-prompt).
+*     Exception: granted + stale policy_version → revert to undecided (mirrors
+*     browser-side resolveEffectiveConsent).
+*  3. If undecided or absent → TTY-prompt once. Persist the answer (including
+*     'undecided' — the directory is guaranteed to exist for subsequent writes,
+*     and decided_at is set for potential future reprompt-window logic).
+*
+* Returns the resolved `MachineTelemetryState`. Callers decide what to do with it.
+*
+* NODE-ONLY.
+*/
+async function ensureMachineConsent(policyVersion, deps) {
+	const existing = await readMachineState(deps);
+	if (existing?.consent === "granted" || existing?.consent === "denied") {
+		if (existing.consent === "granted" && existing.policy_version !== policyVersion) {
+			await writeMachineState({
+				consent: "undecided",
+				policy_version: policyVersion
+			}, deps);
+			return ensureMachineConsent(policyVersion, deps);
+		}
+		return existing;
+	}
+	await writeMachineState({
+		consent: await (deps?.promptConsent ?? promptTtyConsent)(),
+		policy_version: policyVersion
+	}, deps);
+	return await readMachineState(deps);
+}
+//#endregion
+Object.defineProperty(exports, "ensureMachineConsent", {
+	enumerable: true,
+	get: function() {
+		return ensureMachineConsent;
+	}
+});
+Object.defineProperty(exports, "machine_state_exports", {
+	enumerable: true,
+	get: function() {
+		return machine_state_exports;
+	}
+});
+Object.defineProperty(exports, "writeMachineState", {
+	enumerable: true,
+	get: function() {
+		return writeMachineState;
+	}
+});
+
+//# sourceMappingURL=machine-state-DOUweFsJ.cjs.map

package/dist/machine-state-DOUweFsJ.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine-state-DOUweFsJ.cjs","names":[],"sources":["../src/telemetry/machine-state.ts"],"sourcesContent":["/**\n * Machine-level telemetry consent store — #542\n *\n * Persists consent to `~/.ait-devtools/telemetry.json` (Node.js side only).\n * This eliminates repeated consent prompts when the dev origin rotates\n * (quick-tunnel host changes per session, localhost port varies).\n *\n * Design invariants:\n *  - localStorage keys in src/telemetry/state.ts are LOCKED — this module does\n *    NOT replace them. It adds a machine-level overlay that takes precedence\n *    when a dev server is running.\n *  - Tier 0 / Tier 1 consent semantics are unchanged — only the storage\n *    location and lifetime change.\n *  - No PII. The file stores: consent enum + decided_at ISO timestamp +\n *    policy_version + anon_id (pseudonymous UUID).\n *  - anon_id is promoted to machine level so the same identity is used across\n *    all dev origins (prevents counting the same developer multiple times).\n *\n * Node.js-only: imported exclusively from the unplugin (server-side).\n * Never imported from panel/browser code.\n */\n\nimport { homedir } from 'node:os';\nimport { join } from 'node:path';\n\nimport type { ConsentState } from './state.js';\n\n// ---------------------------------------------------------------------------\n// Schema\n// ---------------------------------------------------------------------------\n\nexport interface MachineTelemetryState {\n  consent: ConsentState;\n  /** ISO 8601 timestamp of the decision (or first-write). */\n  decided_at: string;\n  /** Policy version string at decision time. */\n  policy_version: string;\n  /**\n   * Machine-level anon_id (UUID v4). Created once and never overwritten.\n   * Promoted from per-origin localStorage to here so all dev origins share\n   * a single pseudonymous identity.\n   */\n  anon_id: string | null;\n}\n\n// ---------------------------------------------------------------------------\n// File path helpers\n// ---------------------------------------------------------------------------\n\n/** Resolved directory: `~/.ait-devtools`. */\nexport function machineStateDir(homeOverride?: string): string {\n  return join(homeOverride ?? homedir(), '.ait-devtools');\n}\n\n/** Resolved file: `~/.ait-devtools/telemetry.json`. */\nexport function machineStateFile(homeOverride?: string): string {\n  return join(machineStateDir(homeOverride), 'telemetry.json');\n}\n\n// ---------------------------------------------------------------------------\n// Dependency injection surface (injectable for tests)\n// ---------------------------------------------------------------------------\n\nexport interface MachineStateFsDep {\n  existsSync(path: string): boolean;\n  mkdirSync(path: string, options?: { recursive?: boolean }): void;\n  readFileSync(path: string, encoding: BufferEncoding): string;\n  writeFileSync(path: string, data: string, options?: { mode?: number }): void;\n}\n\nexport interface MachineStateDeps {\n  fs?: MachineStateFsDep;\n  homeDir?: string;\n  now?: () => string;\n  randomUUID?: () => string;\n  /**\n   * Override for the TTY consent prompt. When provided, `ensureMachineConsent`\n   * calls this instead of the real `promptTtyConsent` — useful in tests where\n   * `process.stdin.isTTY` cannot be spied on.\n   */\n  promptConsent?: () => Promise<ConsentState>;\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\nfunction isoNow(): string {\n  return new Date().toISOString();\n}\n\nfunction newUUID(): string {\n  return crypto.randomUUID();\n}\n\n/**\n * Returns a minimal MachineStateFsDep using real `node:fs` synchronous APIs.\n * Resolved lazily to avoid pulling node:fs into non-Node environments.\n */\nasync function realFs(): Promise<MachineStateFsDep> {\n  const { existsSync, mkdirSync, readFileSync, writeFileSync } = await import('node:fs');\n  return { existsSync, mkdirSync, readFileSync, writeFileSync };\n}\n\n// ---------------------------------------------------------------------------\n// Read\n// ---------------------------------------------------------------------------\n\n/**\n * Reads the machine-level telemetry state.\n * Returns `null` when the file is absent or cannot be parsed.\n *\n * NODE-ONLY. Never call from browser/panel code.\n */\nexport async function readMachineState(\n  deps?: MachineStateDeps,\n): Promise<MachineTelemetryState | null> {\n  const fs = deps?.fs ?? (await realFs());\n  const filePath = machineStateFile(deps?.homeDir);\n\n  if (!fs.existsSync(filePath)) return null;\n\n  let raw: string;\n  try {\n    raw = fs.readFileSync(filePath, 'utf8');\n  } catch {\n    return null;\n  }\n\n  try {\n    const parsed = JSON.parse(raw) as unknown;\n    if (\n      parsed !== null &&\n      typeof parsed === 'object' &&\n      'consent' in parsed &&\n      typeof (parsed as { consent: unknown }).consent === 'string' &&\n      ['granted', 'denied', 'undecided'].includes((parsed as { consent: string }).consent)\n    ) {\n      return parsed as MachineTelemetryState;\n    }\n    return null;\n  } catch {\n    return null;\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Write\n// ---------------------------------------------------------------------------\n\n/**\n * Writes (or patches) the machine-level telemetry state file.\n * Creates `~/.ait-devtools/` if it does not yet exist.\n *\n * NODE-ONLY. Never call from browser/panel code.\n */\nexport async function writeMachineState(\n  patch: Partial<MachineTelemetryState>,\n  deps?: MachineStateDeps,\n): Promise<void> {\n  const fs = deps?.fs ?? (await realFs());\n  const dir = machineStateDir(deps?.homeDir);\n  const filePath = machineStateFile(deps?.homeDir);\n  const now = deps?.now ?? isoNow;\n  const uuid = deps?.randomUUID ?? newUUID;\n\n  // Ensure directory exists.\n  if (!fs.existsSync(dir)) {\n    fs.mkdirSync(dir, { recursive: true });\n  }\n\n  // Merge with existing state (if any).\n  let existing: MachineTelemetryState | null = null;\n  if (fs.existsSync(filePath)) {\n    try {\n      const raw = fs.readFileSync(filePath, 'utf8');\n      existing = JSON.parse(raw) as MachineTelemetryState;\n    } catch {\n      // Corrupt file — overwrite.\n    }\n  }\n\n  const base: MachineTelemetryState = existing ?? {\n    consent: 'undecided',\n    decided_at: now(),\n    policy_version: '',\n    anon_id: null,\n  };\n\n  const next: MachineTelemetryState = {\n    ...base,\n    ...patch,\n    // Never overwrite an existing anon_id — generate one if creating fresh.\n    anon_id: existing?.anon_id ?? patch.anon_id ?? uuid(),\n    decided_at: now(),\n  };\n\n  fs.writeFileSync(filePath, JSON.stringify(next, null, 2), { mode: 0o600 });\n}\n\n// ---------------------------------------------------------------------------\n// TTY consent prompt (dev server only)\n// ---------------------------------------------------------------------------\n\n/**\n * Prompts the user in the terminal (stdin/stdout TTY) to accept or deny\n * telemetry consent — called once per machine on the first `pnpm dev` run.\n *\n * Returns the chosen `ConsentState`, or `'undecided'` when:\n *  - The TTY is not interactive (CI, headless, piped stdin).\n *  - The prompt times out.\n *  - An error occurs.\n *\n * NODE-ONLY. Called from the unplugin `configureServer` hook.\n */\nexport async function promptTtyConsent(): Promise<ConsentState> {\n  // Guard: require an interactive terminal on both ends.\n  if (!process.stdin.isTTY || !process.stdout.isTTY) {\n    return 'undecided';\n  }\n\n  const { createInterface } = await import('node:readline');\n  const rl = createInterface({ input: process.stdin, output: process.stdout });\n\n  const question = (q: string): Promise<string> =>\n    new Promise((resolve) => rl.question(q, resolve));\n\n  process.stdout.write(\n    '\\n[@ait-co/devtools] 익명 사용 통계를 보내도 될까요?\\n' +\n      '  버전·날짜만 수집하고 PII는 없습니다. 언제든 Environment 탭에서 끌 수 있어요.\\n' +\n      '  자세히: https://docs.aitc.dev/privacy\\n' +\n      '  (y) 네, 보낼게요  (n) 아니요  (무응답 시 보류 — 다음 기동 때 다시 물어요)\\n',\n  );\n\n  let answer = '';\n  try {\n    // 30-second timeout — if the user ignores the prompt, default to 'undecided'.\n    answer = await Promise.race([\n      question('  > '),\n      new Promise<string>((resolve) => setTimeout(() => resolve(''), 30_000)),\n    ]);\n  } catch {\n    // readline error — stay undecided.\n  } finally {\n    rl.close();\n  }\n\n  const normalized = answer.trim().toLowerCase();\n  if (normalized === 'y' || normalized === 'yes' || normalized === '네' || normalized === 'ㅇ') {\n    return 'granted';\n  }\n  if (normalized === 'n' || normalized === 'no' || normalized === '아니요' || normalized === 'ㄴ') {\n    return 'denied';\n  }\n  // Empty / timeout / unrecognised → undecided (will be asked again next session).\n  return 'undecided';\n}\n\n// ---------------------------------------------------------------------------\n// Bootstrap helper — called from configureServer once dev server is ready\n// ---------------------------------------------------------------------------\n\n/**\n * Ensures the machine-level consent state is resolved.\n *\n * Algorithm:\n *  1. Read the machine file.\n *  2. If already decided (granted/denied) → return as-is (no re-prompt).\n *     Exception: granted + stale policy_version → revert to undecided (mirrors\n *     browser-side resolveEffectiveConsent).\n *  3. If undecided or absent → TTY-prompt once. Persist the answer (including\n *     'undecided' — the directory is guaranteed to exist for subsequent writes,\n *     and decided_at is set for potential future reprompt-window logic).\n *\n * Returns the resolved `MachineTelemetryState`. Callers decide what to do with it.\n *\n * NODE-ONLY.\n */\nexport async function ensureMachineConsent(\n  policyVersion: string,\n  deps?: MachineStateDeps,\n): Promise<MachineTelemetryState> {\n  const existing = await readMachineState(deps);\n\n  if (existing?.consent === 'granted' || existing?.consent === 'denied') {\n    // Policy-version bump: re-prompt only when previously granted (same logic as\n    // browser-side resolveEffectiveConsent — denied stays denied on version change).\n    if (existing.consent === 'granted' && existing.policy_version !== policyVersion) {\n      await writeMachineState({ consent: 'undecided', policy_version: policyVersion }, deps);\n      // Recurse: will now prompt the user.\n      return ensureMachineConsent(policyVersion, deps);\n    }\n    return existing;\n  }\n\n  // Undecided or absent → prompt (use injected override in tests).\n  const prompt = deps?.promptConsent ?? promptTtyConsent;\n  const answer = await prompt();\n  await writeMachineState({ consent: answer, policy_version: policyVersion }, deps);\n\n  // Re-read to get the full written state (includes newly generated anon_id).\n  return (await readMachineState(deps)) as MachineTelemetryState;\n}\n"],"mappings":"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"}

package/dist/mcp/cli.js

@@ -1031,9 +1031,10 @@ const LAUNCHER_URL = "https://devtools.aitc.dev/launcher/";
 * @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` and `icon` (#498).
+* @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>]` params.
+*   [&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)}`;
@@ -1048,6 +1049,7 @@ function buildLauncherAttachUrl(tunnelUrl, wssUrl, totpCode, opts) {
 		}
 		if (iconParsed?.protocol === "https:") url += `&icon=${encodeURIComponent(opts.icon)}`;
 	}
+	if (opts?.selfdebug === true) url += "&selfdebug=1";
 	return url;
 }
 /**
@@ -1233,12 +1235,18 @@ function buildChiiInspectorUrl(relayHttpBaseUrl, targetId, mintTotp, panel = "co
 	return `${relayHttpBaseUrl.replace(/\/$/, "")}/front_end/chii_app.html?${params.toString()}`;
 }
 /**
-* Returns `true` when auto-open is **disabled** via the `AIT_AUTO_DEVTOOLS`
-* env var. Only the explicit `"0"` value disables it; anything else (including
-* absent) leaves auto-open enabled.
+* Returns `true` when auto-open is **disabled**.
+*
+* Default (env var absent or any value other than `"1"`) is **disabled** —
+* the developer uses the "디버그 툴 열기" button on the /attach or dashboard
+* page instead. Set `AIT_AUTO_DEVTOOLS=1` to restore the old automatic
+* browser-open behaviour on device attach.
+*
+* `AIT_AUTO_DEVTOOLS=0` retains its explicit opt-out meaning for backward
+* compatibility (same effect as absent).
 */
 function isAutoDevtoolsDisabled() {
-	return process.env.AIT_AUTO_DEVTOOLS === "0";
+	return process.env.AIT_AUTO_DEVTOOLS !== "1";
 }
 /**
 * Opens the given URL in the OS default browser using a platform-appropriate
@@ -1341,8 +1349,8 @@ var AutoDevtoolsOpener = class {
 		if (options.inspectorStableUrl) {
 			this._openedTargets.add(targetId);
 			const stableUrl = options.inspectorStableUrl;
-			process.stderr.write(`[ait-debug] 기기가 연결됐습니다 — Chii DevTools를 자동으로 엽니다.
-[ait-debug] 인스펙터 URL: ${stableUrl}\n[ait-debug] (AIT_AUTO_DEVTOOLS=0 으로 자동 열기를 끌 수 있습니다)
+			process.stderr.write(`[ait-debug] 기기가 연결됐습니다.
+[ait-debug] QR 페이지 또는 대시보드(${stableUrl.replace("/inspector", "")})의 "디버그 툴 열기" 버튼을 눌러 DevTools를 여세요.\n[ait-debug] (AIT_AUTO_DEVTOOLS=1 로 설정하면 연결 시 자동으로 열립니다)
 `);
 			if (!openUrlInBrowser(stableUrl)) process.stderr.write(`[ait-debug] 브라우저 자동 열기 실패 — ${stableUrl} 을 브라우저에서 직접 여세요.\n`);
 			return;
@@ -1354,8 +1362,8 @@ var AutoDevtoolsOpener = class {
 			process.stderr.write("[ait-debug] 기기가 연결됐습니다 — TOTP secret 미설정으로 인스펙터 URL을 생성할 수 없습니다.\n[ait-debug] relay 세션은 AIT_DEBUG_TOTP_SECRET 설정이 필요합니다.\n");
 			return;
 		}
-		process.stderr.write(`[ait-debug] 기기가 연결됐습니다 — Chii DevTools를 자동으로 엽니다.
-[ait-debug] DevTools URL: ${inspectorUrl}\n[ait-debug] (AIT_AUTO_DEVTOOLS=0 으로 자동 열기를 끌 수 있습니다)
+		process.stderr.write(`[ait-debug] 기기가 연결됐습니다.
+[ait-debug] DevTools URL: ${inspectorUrl}\n[ait-debug] (AIT_AUTO_DEVTOOLS=1 로 설정하면 연결 시 자동으로 열립니다)
 [ait-debug] 주의: URL의 at= 코드는 ~3분 안에서만 유효합니다.
 `);
 		if (!openUrlInBrowser(inspectorUrl)) process.stderr.write("[ait-debug] 브라우저 자동 열기 실패 — 위 URL을 브라우저에서 직접 여세요.\n");
@@ -2134,8 +2142,8 @@ const en = {
 	"dashboard.url.copy": "Copy",
 	"dashboard.url.copied": "Copied",
 	"dashboard.inspector.section": "Inspector",
-	"dashboard.inspector.open": "Open inspector",
-	"dashboard.inspector.waiting": "Inspector URL pending — appears after a page attaches",
+	"dashboard.inspector.open": "Open DevTools",
+	"dashboard.inspector.waiting": "Attach a page to enable the \"Open DevTools\" button",
 	"inspector.error.noTarget": "No page attached. Attach a device and try again.",
 	"inspector.error.relayDown": "Relay is not active. Start a relay session first.",
 	"attach.title": "AIT Debug Session — QR Scan",
@@ -2388,8 +2396,8 @@ const tables = {
 		"dashboard.url.copy": "복사",
 		"dashboard.url.copied": "복사됨",
 		"dashboard.inspector.section": "인스펙터",
-		"dashboard.inspector.open": "인스펙터 열기",
-		"dashboard.inspector.waiting": "인스펙터 URL 대기 중 (페이지 attach 후 표시됩니다)",
+		"dashboard.inspector.open": "디버그 툴 열기",
+		"dashboard.inspector.waiting": "페이지를 attach하면 \"디버그 툴 열기\" 버튼이 표시됩니다",
 		"inspector.error.noTarget": "연결된 페이지가 없습니다. 기기를 attach한 후 다시 시도하세요.",
 		"inspector.error.relayDown": "relay가 활성화되지 않았습니다. start_debug로 relay를 기동하세요.",
 		"attach.title": "AIT 디버그 세션 — QR 스캔",
@@ -2595,7 +2603,15 @@ hr { border: none; border-top: 1px solid #21262d; width: 100%; margin: 0.5rem 0;
 .lang-switcher { display: flex; gap: 0.5rem; font-size: 0.75rem; }
 .lang-switcher a { color: #58a6ff; text-decoration: none; opacity: 0.6; }
 .lang-switcher a.active { font-weight: 700; text-decoration: underline; opacity: 1; }
-</style></head><body><h1>AIT 디버그 세션 — QR 스캔</h1>__MODE_LABEL____LANG_SWITCHER__<div id="attach-section"><img class="qr" src="__QR_DATA_URL__" alt="attach QR"/></div><section><h2>스캔 절차</h2><ol><li>홈 화면의 launcher PWA 아이콘으로 실행하세요 (Safari 주소창이 보이면 standalone이 아닙니다).</li><li>launcher 안의 <strong>"QR 카메라로 스캔"</strong>으로 이 QR 코드를 스캔하세요.</li><li>미니앱이 풀스크린으로 열리고 디버그 세션이 자동으로 attach됩니다.</li></ol></section><hr/><section><h2>진단 체크리스트</h2><ul><li><strong>launcher가 설치돼 있지 않은 경우</strong> — <code>devtools.aitc.dev/launcher/</code>를 한 번 열어 홈 화면에 추가하세요</li><li><strong>카메라 앱으로 스캔하면 Safari 탭으로 열립니다 (하단 탭 바 노출)</strong> — launcher 아이콘으로 다시 실행해 인앱 스캔을 사용하세요</li><li><strong>QR이 만료된 경우 (TOTP — 코드 1개는 30초 창, 만료 후 ~3분(±6 step) 이내 소급 허용)</strong> — 새 QR을 다시 스캔하세요</li><li><strong>Chii 주입 실패 / 콘솔이 비어 있는 경우</strong> — 미니앱 번들에 <code>in-app</code> debug import가 있는지 확인</li></ul></section><hr/><section id="url-section"><h2>URL (fallback)</h2><div class="url-row"><p class="url-box" id="url-box">__SAFE_ATTACH_URL__</p><button class="copy-btn" id="copy-btn" type="button" aria-label="복사">복사</button></div></section></body></html>`;
+.inspector-link {
+  display: inline-block; margin-top: 0.5rem;
+  padding: 0.45rem 1rem; border-radius: 6px;
+  background: #1f6feb; color: #fff; font-size: 0.85rem; font-weight: 600;
+  text-decoration: none; text-align: center;
+}
+.inspector-link:hover { background: #388bfd; }
+.inspector-hint { display: inline-block; margin-top: 0.5rem; font-size: 0.8rem; opacity: 0.45; }
+</style></head><body><h1>AIT 디버그 세션 — QR 스캔</h1>__MODE_LABEL____LANG_SWITCHER__<div id="attach-section"><img class="qr" src="__QR_DATA_URL__" alt="attach QR"/></div><section><h2>스캔 절차</h2><ol><li>홈 화면의 launcher PWA 아이콘으로 실행하세요 (Safari 주소창이 보이면 standalone이 아닙니다).</li><li>launcher 안의 <strong>"QR 카메라로 스캔"</strong>으로 이 QR 코드를 스캔하세요.</li><li>미니앱이 풀스크린으로 열리고 디버그 세션이 자동으로 attach됩니다.</li></ol></section><hr/><section><h2>진단 체크리스트</h2><ul><li><strong>launcher가 설치돼 있지 않은 경우</strong> — <code>devtools.aitc.dev/launcher/</code>를 한 번 열어 홈 화면에 추가하세요</li><li><strong>카메라 앱으로 스캔하면 Safari 탭으로 열립니다 (하단 탭 바 노출)</strong> — launcher 아이콘으로 다시 실행해 인앱 스캔을 사용하세요</li><li><strong>QR이 만료된 경우 (TOTP — 코드 1개는 30초 창, 만료 후 ~3분(±6 step) 이내 소급 허용)</strong> — 새 QR을 다시 스캔하세요</li><li><strong>Chii 주입 실패 / 콘솔이 비어 있는 경우</strong> — 미니앱 번들에 <code>in-app</code> debug import가 있는지 확인</li></ul></section><hr/><section id="url-section"><h2>URL (fallback)</h2><div class="url-row"><p class="url-box" id="url-box">__SAFE_ATTACH_URL__</p><button class="copy-btn" id="copy-btn" type="button" aria-label="복사">복사</button></div></section><hr/><section id="inspector-section"><h2>인스펙터</h2>__INSPECTOR_SECTION__</section></body></html>`;
 const attachChromeHtmlKoIntoss = `<!DOCTYPE html>
 <html lang="ko"><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="preload" as="image" href="__QR_DATA_URL__"/><title>AIT 디버그 세션 — QR 스캔</title><style>
 *, *::before, *::after { box-sizing: border-box; }
@@ -2645,7 +2661,15 @@ hr { border: none; border-top: 1px solid #21262d; width: 100%; margin: 0.5rem 0;
 .lang-switcher { display: flex; gap: 0.5rem; font-size: 0.75rem; }
 .lang-switcher a { color: #58a6ff; text-decoration: none; opacity: 0.6; }
 .lang-switcher a.active { font-weight: 700; text-decoration: underline; opacity: 1; }
-</style></head><body><h1>AIT 디버그 세션 — QR 스캔</h1>__MODE_LABEL____LANG_SWITCHER__<p class="label">deployment: __SAFE_LABEL__</p><div id="attach-section"><img class="qr" src="__QR_DATA_URL__" alt="attach QR"/></div><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>__LIVE_FAQ__</ul></section><hr/><section id="url-section"><h2>URL (fallback)</h2><div class="url-row"><p class="url-box" id="url-box">__SAFE_ATTACH_URL__</p><button class="copy-btn" id="copy-btn" type="button" aria-label="복사">복사</button></div></section></body></html>`;
+.inspector-link {
+  display: inline-block; margin-top: 0.5rem;
+  padding: 0.45rem 1rem; border-radius: 6px;
+  background: #1f6feb; color: #fff; font-size: 0.85rem; font-weight: 600;
+  text-decoration: none; text-align: center;
+}
+.inspector-link:hover { background: #388bfd; }
+.inspector-hint { display: inline-block; margin-top: 0.5rem; font-size: 0.8rem; opacity: 0.45; }
+</style></head><body><h1>AIT 디버그 세션 — QR 스캔</h1>__MODE_LABEL____LANG_SWITCHER__<p class="label">deployment: __SAFE_LABEL__</p><div id="attach-section"><img class="qr" src="__QR_DATA_URL__" alt="attach QR"/></div><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>__LIVE_FAQ__</ul></section><hr/><section id="url-section"><h2>URL (fallback)</h2><div class="url-row"><p class="url-box" id="url-box">__SAFE_ATTACH_URL__</p><button class="copy-btn" id="copy-btn" type="button" aria-label="복사">복사</button></div></section><hr/><section id="inspector-section"><h2>인스펙터</h2>__INSPECTOR_SECTION__</section></body></html>`;
 const dashboardChromeHtmlEn = `<!DOCTYPE html>
 <html lang="en"><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><title>AIT Debug Dashboard</title><style>
 *, *::before, *::after { box-sizing: border-box; }
@@ -2755,7 +2779,15 @@ hr { border: none; border-top: 1px solid #21262d; width: 100%; margin: 0.5rem 0;
 .lang-switcher { display: flex; gap: 0.5rem; font-size: 0.75rem; }
 .lang-switcher a { color: #58a6ff; text-decoration: none; opacity: 0.6; }
 .lang-switcher a.active { font-weight: 700; text-decoration: underline; opacity: 1; }
-</style></head><body><h1>AIT Debug Session — QR Scan</h1>__MODE_LABEL____LANG_SWITCHER__<div id="attach-section"><img class="qr" src="__QR_DATA_URL__" alt="attach QR"/></div><section><h2>How to scan</h2><ol><li>Launch the launcher PWA icon on your home screen (if the Safari address bar is visible, it is not standalone).</li><li>Scan this QR code with <strong>"Scan QR with camera"</strong> inside the launcher.</li><li>The mini-app opens fullscreen and the debug session attaches automatically.</li></ol></section><hr/><section><h2>Troubleshooting checklist</h2><ul><li><strong>Launcher is not installed</strong> — open <code>devtools.aitc.dev/launcher/</code> once and add it to your home screen</li><li><strong>Scanning with the camera app opens a Safari tab (bottom tab bar visible)</strong> — relaunch from the launcher icon and use the in-app scanner</li><li><strong>QR expired (TOTP — 30-second step, ±6 steps (~3 min) accepted)</strong> — scan a fresh QR code</li><li><strong>Chii injection failure / console is empty</strong> — verify the mini-app bundle has an <code>in-app</code> debug import</li></ul></section><hr/><section id="url-section"><h2>URL (fallback)</h2><div class="url-row"><p class="url-box" id="url-box">__SAFE_ATTACH_URL__</p><button class="copy-btn" id="copy-btn" type="button" aria-label="Copy">Copy</button></div></section></body></html>`;
+.inspector-link {
+  display: inline-block; margin-top: 0.5rem;
+  padding: 0.45rem 1rem; border-radius: 6px;
+  background: #1f6feb; color: #fff; font-size: 0.85rem; font-weight: 600;
+  text-decoration: none; text-align: center;
+}
+.inspector-link:hover { background: #388bfd; }
+.inspector-hint { display: inline-block; margin-top: 0.5rem; font-size: 0.8rem; opacity: 0.45; }
+</style></head><body><h1>AIT Debug Session — QR Scan</h1>__MODE_LABEL____LANG_SWITCHER__<div id="attach-section"><img class="qr" src="__QR_DATA_URL__" alt="attach QR"/></div><section><h2>How to scan</h2><ol><li>Launch the launcher PWA icon on your home screen (if the Safari address bar is visible, it is not standalone).</li><li>Scan this QR code with <strong>"Scan QR with camera"</strong> inside the launcher.</li><li>The mini-app opens fullscreen and the debug session attaches automatically.</li></ol></section><hr/><section><h2>Troubleshooting checklist</h2><ul><li><strong>Launcher is not installed</strong> — open <code>devtools.aitc.dev/launcher/</code> once and add it to your home screen</li><li><strong>Scanning with the camera app opens a Safari tab (bottom tab bar visible)</strong> — relaunch from the launcher icon and use the in-app scanner</li><li><strong>QR expired (TOTP — 30-second step, ±6 steps (~3 min) accepted)</strong> — scan a fresh QR code</li><li><strong>Chii injection failure / console is empty</strong> — verify the mini-app bundle has an <code>in-app</code> debug import</li></ul></section><hr/><section id="url-section"><h2>URL (fallback)</h2><div class="url-row"><p class="url-box" id="url-box">__SAFE_ATTACH_URL__</p><button class="copy-btn" id="copy-btn" type="button" aria-label="Copy">Copy</button></div></section><hr/><section id="inspector-section"><h2>Inspector</h2>__INSPECTOR_SECTION__</section></body></html>`;
 const attachChromeHtmlEnIntoss = `<!DOCTYPE html>
 <html lang="en"><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="preload" as="image" href="__QR_DATA_URL__"/><title>AIT Debug Session — QR Scan</title><style>
 *, *::before, *::after { box-sizing: border-box; }
@@ -2805,7 +2837,15 @@ hr { border: none; border-top: 1px solid #21262d; width: 100%; margin: 0.5rem 0;
 .lang-switcher { display: flex; gap: 0.5rem; font-size: 0.75rem; }
 .lang-switcher a { color: #58a6ff; text-decoration: none; opacity: 0.6; }
 .lang-switcher a.active { font-weight: 700; text-decoration: underline; opacity: 1; }
-</style></head><body><h1>AIT Debug Session — QR Scan</h1>__MODE_LABEL____LANG_SWITCHER__<p class="label">deployment: __SAFE_LABEL__</p><div id="attach-section"><img class="qr" src="__QR_DATA_URL__" alt="attach QR"/></div><section><h2>How to scan</h2><ol><li>Open the Toss app.</li><li>Scan the QR code with your phone camera app.</li><li>Tap <strong>"Open in Toss"</strong> when the popup appears.</li><li>The mini-app opens and the debug session attaches automatically.</li></ol></section><hr/><section><h2>Troubleshooting checklist</h2><ul><li><strong>Toss app does not open</strong> — check app version; scan with the system camera app (not the Toss in-app QR reader)</li><li><strong>Mini-app stuck in PREPARE state</strong> — verify the deep-link has a <code>_deploymentId</code> parameter</li><li><strong>Chii injection failure / console is empty</strong> — verify the mini-app bundle has an <code>in-app</code> debug import</li><li><strong>TOTP gate Layer C is inactive</strong> — check that <code>AIT_DEBUG_TOTP_SECRET</code> is set on the relay server</li>__LIVE_FAQ__</ul></section><hr/><section id="url-section"><h2>URL (fallback)</h2><div class="url-row"><p class="url-box" id="url-box">__SAFE_ATTACH_URL__</p><button class="copy-btn" id="copy-btn" type="button" aria-label="Copy">Copy</button></div></section></body></html>`;
+.inspector-link {
+  display: inline-block; margin-top: 0.5rem;
+  padding: 0.45rem 1rem; border-radius: 6px;
+  background: #1f6feb; color: #fff; font-size: 0.85rem; font-weight: 600;
+  text-decoration: none; text-align: center;
+}
+.inspector-link:hover { background: #388bfd; }
+.inspector-hint { display: inline-block; margin-top: 0.5rem; font-size: 0.8rem; opacity: 0.45; }
+</style></head><body><h1>AIT Debug Session — QR Scan</h1>__MODE_LABEL____LANG_SWITCHER__<p class="label">deployment: __SAFE_LABEL__</p><div id="attach-section"><img class="qr" src="__QR_DATA_URL__" alt="attach QR"/></div><section><h2>How to scan</h2><ol><li>Open the Toss app.</li><li>Scan the QR code with your phone camera app.</li><li>Tap <strong>"Open in Toss"</strong> when the popup appears.</li><li>The mini-app opens and the debug session attaches automatically.</li></ol></section><hr/><section><h2>Troubleshooting checklist</h2><ul><li><strong>Toss app does not open</strong> — check app version; scan with the system camera app (not the Toss in-app QR reader)</li><li><strong>Mini-app stuck in PREPARE state</strong> — verify the deep-link has a <code>_deploymentId</code> parameter</li><li><strong>Chii injection failure / console is empty</strong> — verify the mini-app bundle has an <code>in-app</code> debug import</li><li><strong>TOTP gate Layer C is inactive</strong> — check that <code>AIT_DEBUG_TOTP_SECRET</code> is set on the relay server</li>__LIVE_FAQ__</ul></section><hr/><section id="url-section"><h2>URL (fallback)</h2><div class="url-row"><p class="url-box" id="url-box">__SAFE_ATTACH_URL__</p><button class="copy-btn" id="copy-btn" type="button" aria-label="Copy">Copy</button></div></section><hr/><section id="inspector-section"><h2>Inspector</h2>__INSPECTOR_SECTION__</section></body></html>`;
 /** Map from Locale to the precompiled dashboard chrome string. */
 const dashboardChromeByLocale = {
 	ko: dashboardChromeHtmlKo,
@@ -2905,8 +2945,9 @@ function buildDashboardHtml(state, qrDataUrl, locale, path = "/", params = new U
 		const copyLabel = escapeHtml(s("dashboard.url.copy"));
 		attachSection = `<img class="qr" src="${qrDataUrl}" alt="attach QR" /><div class="url-row"><p class="url-box" id="url-box">${safeAttachUrl}</p><button class="copy-btn" id="copy-btn" type="button" aria-label="${copyLabel}">${copyLabel}</button></div>`;
 	} else attachSection = `<p class="hint">${escapeHtml(s("dashboard.attach.hint"))}</p>`;
+	const pagesAttached = Array.isArray(state.pages) && state.pages.length > 0;
 	let inspectorSection;
-	if (state.inspectorUrl) inspectorSection = `<a class="inspector-link" id="inspector-link" href="${escapeHtml(state.inspectorUrl)}" target="_blank" rel="noopener noreferrer">${escapeHtml(s("dashboard.inspector.open"))}</a>`;
+	if (pagesAttached && state.inspectorUrl) inspectorSection = `<a class="inspector-link" id="inspector-link" href="${escapeHtml(state.inspectorUrl)}" target="_blank" rel="noopener noreferrer">${escapeHtml(s("dashboard.inspector.open"))}</a>`;
 	else inspectorSection = `<span class="inspector-hint" id="inspector-link">${escapeHtml(s("dashboard.inspector.waiting"))}</span>`;
 	const pagesSection = state.pages === null ? "" : `<hr /><section id="pages-section"><h2>${escapeHtml(s("dashboard.pages.section"))}</h2><ul id="pages-list">${state.pages.length > 0 ? state.pages.map((p) => {
 		return `<li><span class="page-id">${escapeHtml(p.id)}</span> <span class="page-url">${escapeHtml(p.url.slice(0, 120))}</span></li>`;
@@ -3076,11 +3117,15 @@ function buildSseScript(strings) {
               sec.innerHTML = '<p class=\\"hint\\">' + ATTACH_HINT + '</p>';`}
             }
           }
-          // 인스펙터 링크 갱신 — #inspector-link (#503).
+          // 인스펙터 링크 갱신 — #inspector-link (#503, gate 보정 #544).
+          // 게이트: pages.length > 0 (페이지 attach 여부) — inspectorUrl 존재 여부가 아님.
+          // #530 이후 inspectorUrl은 항상 안정 URL이므로 null 게이트는 사실상 항상 활성이었다.
+          // pages.length > 0 으로 바꿔 미attach 시 대기 힌트를 보여주도록 수정.
           // SECRET-HANDLING: inspectorUrl을 console.log 등으로 출력하지 않는다.
           var insp = document.getElementById('inspector-link');
           if (insp) {
-            if (s.inspectorUrl) {
+            var pagesAttachedSse = Array.isArray(s.pages) && s.pages.length > 0;
+            if (pagesAttachedSse && s.inspectorUrl) {
               var safeInspUrl = String(s.inspectorUrl).slice(0, 2000).replace(/[<>&"']/g, function (c) { return '&#' + c.charCodeAt(0) + ';'; });
               insp.outerHTML = '<a class=\\"inspector-link\\" id=\\"inspector-link\\" href=\\"' + safeInspUrl + '\\" target=\\"_blank\\" rel=\\"noopener noreferrer\\">' + INSPECTOR_OPEN_LABEL + '</a>';
             } else {
@@ -3102,28 +3147,33 @@ function buildSseScript(strings) {
 * Attach 페이지 HTML — precompiled chrome에 per-request 동적 값을 채워 완성한다.
 *
 * 동적 파트:
-*   - __QR_DATA_URL__     : base64 data URL (QR 이미지)
-*   - __SAFE_LABEL__      : HTML-escaped deploymentId label (intoss family에만 존재)
-*   - __SAFE_ATTACH_URL__ : HTML-escaped attach URL (TOTP at= 코드 포함 — 의도된 전달)
-*   - __MODE_LABEL__      : 환경 배지 (`<p class="mode-label">…</p>` 또는 빈 문자열, #468)
-*   - __LIVE_FAQ__        : 환경 4 LIVE read-only `<li>` 또는 빈 문자열 (intoss family에만 존재)
+*   - __QR_DATA_URL__       : base64 data URL (QR 이미지)
+*   - __SAFE_LABEL__        : HTML-escaped deploymentId label (intoss family에만 존재)
+*   - __SAFE_ATTACH_URL__   : HTML-escaped attach URL (TOTP at= 코드 포함 — 의도된 전달)
+*   - __MODE_LABEL__        : 환경 배지 (`<p class="mode-label">…</p>` 또는 빈 문자열, #468)
+*   - __LIVE_FAQ__          : 환경 4 LIVE read-only `<li>` 또는 빈 문자열 (intoss family에만 존재)
+*   - __INSPECTOR_SECTION__ : "디버그 툴 열기" 버튼 또는 대기 힌트 (#544)
 *
 * mode-aware 분기 (#468): mode가 `relay-mobile`이면 sandbox family chrome(launcher
 * PWA 절차), 그 외는 intoss family chrome(토스 앱 절차)을 선택한다. `relay-live`는
 * intoss chrome에 LIVE read-only 라인을 추가한다.
 *
 * SSE 스크립트도 주입 — `#attach-section` hook이 있으면 `/events` push 때 QR이
-* `/qr.png?u=<fresh attachUrl>`로 자동 갱신된다. `#tunnel-status`·`#pages-list` 등
-* 나머지 selector는 /attach 페이지에 없으므로 null-guard로 no-op.
+* `/qr.png?u=<fresh attachUrl>`로 자동 갱신된다. `#inspector-link`도 SSE push로
+* pages.length > 0 게이트에 따라 활성/비활성 전환된다 (#544).
 *
 * SECRET-HANDLING: TOTP at= 코드는 attachUrl 캡슐 안에서만 노출 — 의도된 transport.
+* inspectorStableUrl은 /inspector 안정 URL (127.0.0.1, 시크릿 없음) — 노출 가능.
 */
-function buildAttachHtml(qrDataUrl, safeLabel, safeAttachUrl, locale, path = "/attach", params = new URLSearchParams(), mode) {
+function buildAttachHtml(qrDataUrl, safeLabel, safeAttachUrl, locale, path = "/attach", params = new URLSearchParams(), mode, pagesAttached = false, inspectorStableUrl = null) {
 	const s = resolveLocaleStrings(locale);
 	const langSwitcher = buildLangSwitcher(path, params, locale, s);
 	const family = attachFamilyForMode(mode);
 	const liveFaq = mode === "relay-live" ? `<li>${s("attach.intoss.faq.liveReadOnly")}</li>` : "";
-	const filled = attachChromeByLocale[locale][family].replaceAll("__LANG_SWITCHER__", langSwitcher).replaceAll("__MODE_LABEL__", buildModeLabel(mode, s)).replaceAll("__LIVE_FAQ__", liveFaq).replaceAll("__QR_DATA_URL__", qrDataUrl).replaceAll("__SAFE_LABEL__", safeLabel).replaceAll("__SAFE_ATTACH_URL__", safeAttachUrl);
+	let inspectorSection;
+	if (pagesAttached && inspectorStableUrl) inspectorSection = `<a class="inspector-link" id="inspector-link" href="${escapeHtml(inspectorStableUrl)}" target="_blank" rel="noopener noreferrer">${escapeHtml(s("dashboard.inspector.open"))}</a>`;
+	else inspectorSection = `<span class="inspector-hint" id="inspector-link">${escapeHtml(s("dashboard.inspector.waiting"))}</span>`;
+	const filled = attachChromeByLocale[locale][family].replaceAll("__LANG_SWITCHER__", langSwitcher).replaceAll("__MODE_LABEL__", buildModeLabel(mode, s)).replaceAll("__LIVE_FAQ__", liveFaq).replaceAll("__QR_DATA_URL__", qrDataUrl).replaceAll("__SAFE_LABEL__", safeLabel).replaceAll("__SAFE_ATTACH_URL__", safeAttachUrl).replaceAll("__INSPECTOR_SECTION__", inspectorSection);
 	const sseScript = buildSseScript({
 		tunnelUp: JSON.stringify(s("dashboard.tunnel.up")),
 		tunnelDown: JSON.stringify(s("dashboard.tunnel.down")),
@@ -3225,12 +3275,20 @@ async function startQrHttpServer(getDashboardState, options) {
 				const dpMatch = attachUrl.match(/[?&]_deploymentId=([^&]+)/);
 				if (dpMatch?.[1]) deploymentIdLabel = decodeURIComponent(dpMatch[1]).slice(0, 36);
 			} catch {}
-			const mode = getDashboardState?.().mode;
+			const currentState = getDashboardState?.();
+			const mode = currentState?.mode;
+			const pagesAttached = Array.isArray(currentState?.pages) && (currentState?.pages.length ?? 0) > 0;
+			const inspectorStableUrlForAttach = (() => {
+				if (!options?.getDirectInspectorUrl) return null;
+				const addr = server.address();
+				if (!addr || typeof addr === "string") return null;
+				return `http://127.0.0.1:${addr.port}/inspector`;
+			})();
 			QRCode.toDataURL(attachUrl, {
 				type: "image/png",
 				errorCorrectionLevel: "M"
 			}).then((dataUrl) => {
-				const html = buildAttachHtml(dataUrl, escapeHtml(deploymentIdLabel), escapeHtml(attachUrl), locale, path, params, mode);
+				const html = buildAttachHtml(dataUrl, escapeHtml(deploymentIdLabel), escapeHtml(attachUrl), locale, path, params, mode, pagesAttached, inspectorStableUrlForAttach);
 				res.writeHead(200, {
 					"Content-Type": "text/html; charset=utf-8",
 					"Cache-Control": "no-store"
@@ -3703,7 +3761,7 @@ const DEBUG_TOOL_DEFINITIONS = [
 	},
 	{
 		name: "build_attach_url",
-		description: "The tool result already shows the QR to the user directly (Claude Code renders MCP tool output to the user's screen; they press Ctrl+O to expand if it's collapsed). Do NOT re-print or re-render the QR in your reply — that just wastes output tokens. Simply tell the user to scan the QR shown in this tool's output with their phone camera. Builds a self-attaching deep-link for the active relay environment and returns a QR code. Scan the QR with the phone camera to open the mini-app and attach it to this debug session (QR is the single entry path — no USB cable or platform CLI needed). Call list_pages first to confirm the relay/tunnel is up. If the tunnel is not up, restart: `npx @ait-co/devtools devtools-mcp`.\n\nEnvironment-specific behaviour:\n  • env 3 / relay-staging (start_debug mode=\"relay-staging\"): requires scheme_url — the intoss-private://…?_deploymentId=<uuid> URL from `ait deploy --scheme-only`. Splices debug=1 + relay URL into the scheme URL to produce a self-attach deep-link.\n  • env 2 / relay-sandbox (start_debug mode=\"relay-sandbox\"): scheme_url is NOT used. Instead, reads AIT_TUNNEL_BASE_URL (the https://*.trycloudflare.com app tunnel from `tunnel:{cdp:true}`) and builds a launcher PWA deep-link (https://devtools.aitc.dev/launcher/?url=…&debug=1&relay=…). When projectRoot is given, the app name from <projectRoot>/package.json is automatically added as name= so the launcher partner bar shows it. Scan the QR with the phone to open the launcher, which frames the tunnel URL and attaches CDP.\n\nSet wait_for_attach=true to block until a page attaches (polls up to 30 s). On timeout, call build_attach_url again to resume polling. When open_in_browser=true (default), saves the QR as a PNG and opens it in the OS default browser — only works when the MCP server runs on a local GUI machine (not headless/remote containers). \n\nTOTP auth: when AIT_DEBUG_TOTP_SECRET is set on the MCP server, the returned attachUrl automatically includes the current one-time code (at=<code>). The code is valid for ~3 minutes (the relay gate accepts ±6 TOTP steps = 180–210 s of backwards acceptance). The response includes a `totp` field with `expiresAt` (ISO timestamp, ~3 min from issuance). If the phone scan happens after expiresAt, the relay will reject the code — just call build_attach_url again to get a fresh URL. Without AIT_DEBUG_TOTP_SECRET, the attachUrl has no expiry.",
+		description: "The tool result already shows the QR to the user directly (Claude Code renders MCP tool output to the user's screen; they press Ctrl+O to expand if it's collapsed). Do NOT re-print or re-render the QR in your reply — that just wastes output tokens. Simply tell the user to scan the QR shown in this tool's output with their phone camera. Builds a self-attaching deep-link for the active relay environment and returns a QR code. Scan the QR with the phone camera to open the mini-app and attach it to this debug session (QR is the single entry path — no USB cable or platform CLI needed). Call list_pages first to confirm the relay/tunnel is up. If the tunnel is not up, restart: `npx @ait-co/devtools devtools-mcp`.\n\nEnvironment-specific behaviour:\n  • env 3 / relay-staging (start_debug mode=\"relay-staging\"): requires scheme_url — the intoss-private://…?_deploymentId=<uuid> URL from `ait deploy --scheme-only`. Splices debug=1 + relay URL into the scheme URL to produce a self-attach deep-link.\n  • env 2 / relay-sandbox (start_debug mode=\"relay-sandbox\"): scheme_url is NOT used. Instead, reads AIT_TUNNEL_BASE_URL (the https://*.trycloudflare.com app tunnel from `tunnel:{cdp:true}`) and builds a launcher PWA deep-link (https://devtools.aitc.dev/launcher/?url=…&debug=1&relay=…). When projectRoot is given, the app name from <projectRoot>/package.json is automatically added as name= so the launcher partner bar shows it. Scan the QR with the phone to open the launcher, which frames the tunnel URL and attaches CDP.\n\nSet wait_for_attach=true to block until a page attaches (polls up to 30 s). On timeout, call build_attach_url again to resume polling. When open_in_browser=true (default), saves the QR as a PNG and opens it in the OS default browser — only works when the MCP server runs on a local GUI machine (not headless/remote containers). \n\nTOTP auth: when AIT_DEBUG_TOTP_SECRET is set on the MCP server, the returned attachUrl automatically includes the current one-time code (at=<code>). The code is valid for ~3 minutes (the relay gate accepts ±6 TOTP steps = 180–210 s of backwards acceptance). The response includes a `totp` field with `expiresAt` (ISO timestamp, ~3 min from issuance). If the phone scan happens after expiresAt, the relay will reject the code — just call build_attach_url again to get a fresh URL. 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/4 (relay-staging/relay-live) — passing selfdebug=true there returns an error.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -3722,6 +3780,10 @@ const DEBUG_TOOL_DEFINITIONS = [
 				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/4 (relay-staging/relay-live) returns an error. Default: false (omitted — output is byte-identical to previous behaviour)."
 				}
 			},
 			required: []
@@ -4717,7 +4779,7 @@ async function readMcpSdkVersion() {
 * some test environments that skip the build step).
 */
 function readDevtoolsVersion() {
-	return "0.1.80";
+	return "0.1.84";
 }
 /**
 * Derives the next recommended action from a completed diagnostics snapshot.
@@ -5221,7 +5283,7 @@ function createDebugServer(deps) {
 	const collector = collectorDep ?? new InMemoryDiagnosticsCollector();
 	const server = new Server({
 		name: "ait-debug",
-		version: "0.1.80"
+		version: "0.1.84"
 	}, { capabilities: { tools: { listChanged: true } } });
 	server.setRequestHandler(ListToolsRequestSchema, () => {
 		const conn = router.active;
@@ -5295,6 +5357,8 @@ function createDebugServer(deps) {
 		if (name === "build_attach_url") {
 			const waitForAttach = request.params.arguments?.wait_for_attach === true;
 			const openInBrowser = request.params.arguments?.open_in_browser !== false;
+			const selfdebug = request.params.arguments?.selfdebug === true;
+			if (selfdebug && env !== "relay-mobile") return mcpError("build_attach_url: selfdebug=true는 env 2 / relay-sandbox 전용 기능입니다. 현재 환경(env 3/4)에서는 launcher가 없어 self-target 모드를 지원하지 않습니다. launcher self-target이 필요하다면 relay-sandbox 모드로 재시작하세요.");
 			if (env === "relay-mobile") {
 				const rawBuildProjectRoot = request.params.arguments?.projectRoot;
 				const buildProjectRoot = typeof rawBuildProjectRoot === "string" ? rawBuildProjectRoot : void 0;
@@ -5329,7 +5393,10 @@ function createDebugServer(deps) {
 					const rawName = typeof pkg.name === "string" ? pkg.name : "";
 					launcherAppName = (rawName.includes("/") ? rawName.slice(rawName.indexOf("/") + 1) : rawName).trim() || void 0;
 				} catch {}
-				const attachUrl = buildLauncherAttachUrl(tunnelHttpUrl, tunnelStatus.wssUrl, totpCode, { name: launcherAppName });
+				const attachUrl = buildLauncherAttachUrl(tunnelHttpUrl, tunnelStatus.wssUrl, totpCode, {
+					name: launcherAppName,
+					...selfdebug ? { selfdebug: true } : {}
+				});
 				onAttachUrlBuilt?.({
 					kind: "launcher",
 					tunnelHttpUrl,
@@ -7264,7 +7331,7 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.80"
+		version: "0.1.84"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {