@ait-co/devtools 0.1.49 → 0.1.51

package/dist/in-app/index.d.ts

@@ -205,6 +205,13 @@ declare function deriveTargetScriptUrl(relayUrl: string): string;
  * Safe to call even if `document` is somehow unavailable (defensive boundary
  * guard — in practice this always runs in a real WebView).
  *
+ * **keepAwake side effect**: on a successful attach, `setScreenAwakeMode({
+ * enabled: true })` is called so the phone screen stays awake during the debug
+ * session. A `beforeunload` handler restores normal sleep on page unload.
+ * Opt out by adding `noKeepAwake=1` to the page URL query string — the check
+ * reads `window.location.search` directly, consistent with other guards in
+ * this file.
+ *
  * @param gateResult - Optional pre-evaluated gate result for testability.
  *   Defaults to `checkDebugGate()` which reads the current page URL. Passing a
  *   custom value avoids the need to manipulate `window.location` in tests.

package/dist/in-app/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/in-app/gate.ts","../../src/in-app/attach.ts","../../src/in-app/index.ts"],"mappings":";;AA+DA;;;;;;;;;AASA;;;;;AAmBA;;;;;AAQA;;;;;;;;;;;AAwEA;;;;;AAyBA;;;;;;;;;;;;ACvKA;;;;;AA4BA;;;;;;;;ACbA;AAAA,UFmBiB,gBAAA;EAAA,SACN,MAAA;EEpBuB;EAAA,SFsBvB,QAAA;;WAEA,YAAA;AAAA;;UAIM,iBAAA;EAAA,SACN,MAAA;;;;;;;;;;;;;;;WAeA,MAAA;AAAA;AAAA,KAGC,UAAA,GAAa,gBAAA,GAAmB,iBAAA;;;;;;;UAQ3B,SAAA;;;;;;;;;;;;;WAaN,QAAA;;;;;;;WAQA,YAAA,EAAc,eAAA;;;;;;;;;;;;;;;;;;;;;;;;;WA0Bd,cAAA,IAAkB,IAAA;AAAA;;;;;;;;;;;;iBAyBb,iBAAA,CAAkB,QAAA;;;;;;;;;;;;;;;;;;;;;;iBAyBlB,iBAAA,CAAkB,KAAA,EAAO,SAAA,GAAY,UAAA;;;;;;AAzGrD;;;;;AAQA;;;;;;;iBCtEgB,qBAAA,CAAsB,QAAA;;;;AD8ItC;;;;;AAyBA;;;;;;;;iBC3IgB,WAAA,CAAY,UAAA,GAAY,UAAA;;;;;;;ADkHxC;;;;;AAyBA;;;;;iBExJgB,cAAA,CAAA,GAAkB,UAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/in-app/gate.ts","../../src/in-app/attach.ts","../../src/in-app/index.ts"],"mappings":";;AA+DA;;;;;;;;;AASA;;;;;AAmBA;;;;;AAQA;;;;;;;;;;;AAwEA;;;;;AAyBA;;;;;;;;;;;;ACtKA;;;;;AAmCA;;;;;;;;ACrBA;AAAA,UFmBiB,gBAAA;EAAA,SACN,MAAA;EEpBuB;EAAA,SFsBvB,QAAA;;WAEA,YAAA;AAAA;;UAIM,iBAAA;EAAA,SACN,MAAA;;;;;;;;;;;;;;;WAeA,MAAA;AAAA;AAAA,KAGC,UAAA,GAAa,gBAAA,GAAmB,iBAAA;;;;;;;UAQ3B,SAAA;;;;;;;;;;;;;WAaN,QAAA;;;;;;;WAQA,YAAA,EAAc,eAAA;;;;;;;;;;;;;;;;;;;;;;;;;WA0Bd,cAAA,IAAkB,IAAA;AAAA;;;;;;;;;;;;iBAyBb,iBAAA,CAAkB,QAAA;;;;;;;;;;;;;;;;;;;;;;iBAyBlB,iBAAA,CAAkB,KAAA,EAAO,SAAA,GAAY,UAAA;;;;;;AAzGrD;;;;;AAQA;;;;;;;iBCrEgB,qBAAA,CAAsB,QAAA;;;;AD6ItC;;;;;AAyBA;;;;;;;;;;;;ACtKA;;;iBAmCgB,WAAA,CAAY,UAAA,GAAY,UAAA;;;;;;;AD0GxC;;;;;AAyBA;;;;;iBExJgB,cAAA,CAAA,GAAkB,UAAA"}

package/dist/in-app/index.js

@@ -1,3 +1,4 @@
+import { setScreenAwakeMode } from "@apps-in-toss/web-framework";
 //#region src/in-app/gate.ts
 /**
 * The host suffix the Toss app uses to serve dogfood / private mini-apps.
@@ -139,6 +140,13 @@ let attached = false;
 * Safe to call even if `document` is somehow unavailable (defensive boundary
 * guard — in practice this always runs in a real WebView).
 *
+* **keepAwake side effect**: on a successful attach, `setScreenAwakeMode({
+* enabled: true })` is called so the phone screen stays awake during the debug
+* session. A `beforeunload` handler restores normal sleep on page unload.
+* Opt out by adding `noKeepAwake=1` to the page URL query string — the check
+* reads `window.location.search` directly, consistent with other guards in
+* this file.
+*
 * @param gateResult - Optional pre-evaluated gate result for testability.
 *   Defaults to `checkDebugGate()` which reads the current page URL. Passing a
 *   custom value avoids the need to manipulate `window.location` in tests.
@@ -160,6 +168,14 @@ function maybeAttach(gateResult = checkDebugGate()) {
 	script.async = true;
 	(document.head ?? document.documentElement).appendChild(script);
 	attached = true;
+	if (typeof window !== "undefined" && new URLSearchParams(window.location.search).get("noKeepAwake") === "1") return;
+	setScreenAwakeMode({ enabled: true }).then(() => {
+		window.addEventListener("beforeunload", () => {
+			setScreenAwakeMode({ enabled: false }).catch(() => {});
+		}, { once: true });
+	}).catch((err) => {
+		console.debug("[@ait-co/devtools] setScreenAwakeMode failed:", err);
+	});
 }
 //#endregion
 //#region src/in-app/index.ts

package/dist/in-app/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/in-app/gate.ts","../../src/in-app/attach.ts","../../src/in-app/index.ts"],"sourcesContent":["/**\n * Runtime activation gate for the in-app debug surface.\n *\n * Spec: docs/superpowers/specs/2026-05-18-in-app-debug-mcp.md\n * \"3-layer activation gate\". This is the pure gate decision; the Chii client,\n * WebSocket transport, MCP server, and CLI that consume it live in src/mcp/.\n *\n * This function evaluates the two RUNTIME layers, B and C. Layer A — the\n * build-time gate — is NOT evaluated here, and deliberately so: it is enforced\n * entirely by the consumer's `if (__DEBUG_BUILD__) { … }` guard around the\n * import site (see sdk-example `src/main.tsx`). `__DEBUG_BUILD__` is a\n * consumer-build-time constant; a release consumer build folds it to `false`\n * and dead-code-eliminates the whole import of `@ait-co/devtools/in-app`, so\n * this code is simply absent from release bundles. A pre-built npm package\n * cannot re-check that flag — it was already baked at devtools' own publish\n * time — so any `isDebugBuild` check inside this function would be permanently\n * `false` and could never pass. Layer A is the consumer guard; B and C are\n * here.\n *\n * Layer B has two parts. Both must pass:\n *   B1 — host allowlist: `hostname` must be a `*.private-apps.tossmini.com`\n *        subdomain. The Toss app serves dogfood / private mini-apps from a\n *        separate `private-apps` host; a production (`intoss://`) entry is\n *        served from `*.apps.tossmini.com` WITHOUT the `private-apps` segment.\n *        This is the security gate against a dogfood build that somehow lands\n *        on a production entry — see the comment on {@link isPrivateAppsHost}.\n *   B2 — entry query: `_deploymentId` must be present and non-empty.\n *\n * Layer C — opt-in + relay + optional TOTP auth:\n *   C1 — opt-in:       `debug=1` must be present.\n *   C2 — relay URL:    `relay=<wss-url>` must be a valid `wss:` URL.\n *   C3 — TOTP auth:    When `verifyTotpCode` is provided (consumer injected the\n *                      baked secret at build time via `__DEBUG_TOTP_SECRET__`),\n *                      `at=<code>` is checked. Invalid or absent code → BLOCKED.\n *                      When no verifier is provided (TOTP disabled), `at` is\n *                      ignored (backward compatible).\n *\n * Security note on baked secrets:\n *   The TOTP secret baked in via `__DEBUG_TOTP_SECRET__` is present in the\n *   dogfood bundle and is extractable by a determined reverse engineer.\n *   The practical bar raised is: \"URL leak\" (Slack paste, QR screenshot) →\n *   blocked; \"URL + bundle extraction + live TOTP code\" → not blocked.\n *   This is the intended threat model. Do not overpromise on this guarantee.\n *\n * SECRET-HANDLING: `verifyTotpCode` is a black-box predicate. This module\n *   does NOT log the secret, any code value, or pass/fail details beyond the\n *   `'auth'` reason enum.\n *\n * Decision matrix (gate only runs in a debug build — Layer A already passed):\n *\n *   host ok | _deploymentId | debug=1 | relay ok | TOTP ok* | result\n *   no      | (any)         | (any)   | (any)    | (any)    | BLOCKED (host)\n *   yes     | absent        | (any)   | (any)    | (any)    | BLOCKED (entry)\n *   yes     | present       | absent  | (any)    | (any)    | BLOCKED (opt-in)\n *   yes     | present       | present | invalid  | (any)    | BLOCKED (invalid-relay)\n *   yes     | present       | present | valid    | fail*    | BLOCKED (auth)\n *   yes     | present       | present | valid    | pass/n/a | ATTACH\n *\n *   * \"TOTP ok\" column only applies when `verifyTotpCode` is provided.\n *     When no verifier is injected, TOTP check is skipped entirely.\n */\n\n/** Shape returned when the gate allows attachment. */\nexport interface GateResultAttach {\n  readonly attach: true;\n  /** The validated `wss:` relay URL from the `relay` query param. */\n  readonly relayUrl: string;\n  /** The deployment ID extracted from the `_deploymentId` query param. */\n  readonly deploymentId: string;\n}\n\n/** Shape returned when the gate blocks attachment, with a reason code. */\nexport interface GateResultBlocked {\n  readonly attach: false;\n  /**\n   * - `'host'`          Layer B1: `hostname` is not a `*.private-apps.tossmini.com` host.\n   * - `'entry'`         Layer B2: `_deploymentId` param is absent or empty.\n   * - `'opt-in'`        Layer C1: `debug=1` param is absent.\n   * - `'invalid-relay'` Layer C2: `relay` param is absent, empty, or not a `wss:` URL.\n   * - `'auth'`          Layer C3: TOTP `at=` code is absent, invalid, or expired\n   *                     (only when a `verifyTotpCode` predicate is injected).\n   *\n   * There is no `'build'` reason: Layer A is enforced by the consumer's\n   * `if (__DEBUG_BUILD__)` guard, not by this function.\n   *\n   * SECRET-HANDLING: `'auth'` is the only value surfaced for auth failures —\n   * no code value, expected value, or secret fragment is ever exposed.\n   */\n  readonly reason: 'host' | 'entry' | 'opt-in' | 'invalid-relay' | 'auth';\n}\n\nexport type GateResult = GateResultAttach | GateResultBlocked;\n\n/**\n * Input for {@link evaluateDebugGate}.\n *\n * All fields are explicit so the function is trivially testable without\n * touching `window`.\n */\nexport interface GateInput {\n  /**\n   * The host the page is served from — `window.location.hostname`.\n   *\n   * This is the Layer B1 security signal. Why hostname and not the entry\n   * scheme: the Toss SDK normalises `intoss-private://` to `intoss://` in\n   * `getSchemeUri()`, and `getOperationalEnvironment()` / `getWebViewType()`\n   * return the same value (`\"toss\"` / `\"partner\"`) for both dogfood and\n   * production entries — none of them distinguish a dogfood entry. The host\n   * does: a dogfood / private-apps entry is served from\n   * `*.private-apps.tossmini.com`, a production entry is not. This was\n   * confirmed live over CDP against mini-app 31146 (see spec open question 2).\n   */\n  readonly hostname: string;\n\n  /**\n   * The URL search params to inspect for gate signals (Layers B2 and C).\n   *\n   * Prefer `URLSearchParams` so callers can pass `new URLSearchParams(location.search)`\n   * without coupling the pure function to `window`.\n   */\n  readonly searchParams: URLSearchParams;\n\n  /**\n   * Optional TOTP code verifier for Layer C3 auth gate.\n   *\n   * When provided, `evaluateDebugGate` reads the `at` query param and passes\n   * it to this predicate. Return `true` to allow, `false` to block with\n   * `reason: 'auth'`.\n   *\n   * Inject via the consumer's build define, e.g.:\n   * ```ts\n   * // dogfood build entry — consumer's build injects __DEBUG_TOTP_SECRET__\n   * declare const __DEBUG_TOTP_SECRET__: string | undefined;\n   * const verifyTotpCode = typeof __DEBUG_TOTP_SECRET__ !== 'undefined'\n   *   ? (code: string) => verifyTotp(__DEBUG_TOTP_SECRET__, code)\n   *   : undefined;\n   * maybeAttach(evaluateDebugGate({ ...params, verifyTotpCode }));\n   * ```\n   *\n   * Security note: this predicate is a black-box from the gate's perspective.\n   * The gate only surfaces pass/fail and the `'auth'` reason code — no code\n   * value or secret fragment is ever logged or returned.\n   *\n   * When `undefined` (TOTP disabled), `at=` is silently ignored and the gate\n   * proceeds to ATTACH if all other layers pass.\n   */\n  readonly verifyTotpCode?: (code: string) => boolean;\n}\n\n/**\n * The host suffix the Toss app uses to serve dogfood / private mini-apps.\n *\n * A `intoss-private://` (dogfood) entry maps to a host such as\n * `aitc-sdk-example.private-apps.tossmini.com`. A production `intoss://`\n * entry is served from `*.apps.tossmini.com` — the `.private-apps.` segment\n * is absent. Confirmed live over CDP for mini-app 31146; the exact production\n * host is to be re-confirmed once 31146 passes review (spec open question 2).\n */\nconst PRIVATE_APPS_HOST_SUFFIX = '.private-apps.tossmini.com';\n\n/**\n * Returns whether `hostname` is a `*.private-apps.tossmini.com` subdomain —\n * the host the Toss app reserves for dogfood / private mini-app entries.\n *\n * The match is an exact suffix check, not a substring `.includes()`: a\n * substring test would also accept an attacker-controlled host like\n * `private-apps.tossmini.com.evil.example`, which ends in `.example`, not in\n * `.tossmini.com`. Requiring the string to END with the suffix closes that.\n * The leading `.` in the suffix also forces a real subdomain label, so a\n * bare `private-apps.tossmini.com` (no mini-app subdomain) does not match.\n */\nexport function isPrivateAppsHost(hostname: string): boolean {\n  return hostname.endsWith(PRIVATE_APPS_HOST_SUFFIX);\n}\n\n/**\n * Pure function that evaluates the runtime debug activation layers (B and C).\n *\n * Has no side effects. The input is explicit. Returns a discriminated union\n * so callers can pattern-match on `result.attach`.\n *\n * Layer A (build-time) is intentionally not evaluated here — see the file-level\n * comment. By the time this function runs, the consumer's `if (__DEBUG_BUILD__)`\n * guard has already passed; this function only decides B and C.\n *\n * @example\n * ```ts\n * const result = evaluateDebugGate({\n *   hostname: window.location.hostname,\n *   searchParams: new URLSearchParams(window.location.search),\n * });\n * if (result.attach) {\n *   // Proceed to load Chii client\n * }\n * ```\n */\nexport function evaluateDebugGate(input: GateInput): GateResult {\n  // Layer B1 — host allowlist (the security gate).\n  // The page must be served from a `*.private-apps.tossmini.com` host. A\n  // production `intoss://` entry is served from `*.apps.tossmini.com` and is\n  // rejected here. This is what stops a dogfood build that somehow reaches a\n  // production entry from attaching: Layer A keeps debug code out of release\n  // bundles, and this layer keeps a dogfood bundle that lands on a production\n  // host from attaching even though its code is present.\n  if (!isPrivateAppsHost(input.hostname)) {\n    return { attach: false, reason: 'host' };\n  }\n\n  // Layer B2 — runtime entry query gate.\n  // `_deploymentId` must be present and non-empty. The `intoss-private://`\n  // scheme used for dogfood entries includes this param; general user entry\n  // paths do not.\n  const deploymentId = input.searchParams.get('_deploymentId') ?? '';\n  if (deploymentId === '') {\n    return { attach: false, reason: 'entry' };\n  }\n\n  // Layer C — explicit opt-in gate.\n  // Require `debug=1` so that an operator who opens a dogfood URL by accident\n  // does not inadvertently trigger the debug surface.\n  const debugParam = input.searchParams.get('debug');\n  if (debugParam !== '1') {\n    return { attach: false, reason: 'opt-in' };\n  }\n\n  // Layer C continued — relay URL validation.\n  // `relay=<wss-url>` must be present and must use the `wss:` scheme.\n  // Plain `ws:` is rejected (no TLS). `http:`/`https:` are rejected.\n  const relayRaw = input.searchParams.get('relay') ?? '';\n  if (relayRaw === '') {\n    return { attach: false, reason: 'invalid-relay' };\n  }\n\n  let relayUrl: URL;\n  try {\n    relayUrl = new URL(relayRaw);\n  } catch {\n    return { attach: false, reason: 'invalid-relay' };\n  }\n\n  if (relayUrl.protocol !== 'wss:') {\n    return { attach: false, reason: 'invalid-relay' };\n  }\n\n  // Layer C3 — TOTP auth gate (fail-fast, only when a verifier is injected).\n  // The `at` query param carries the current TOTP code. Absent or invalid code\n  // → BLOCKED. When no verifier is provided (TOTP disabled), this check is\n  // skipped entirely for backward compatibility.\n  //\n  // SECRET-HANDLING: we do NOT log `code`, the verifier's result, or anything\n  // derived from the secret. Only the `'auth'` enum is surfaced on failure.\n  if (input.verifyTotpCode !== undefined) {\n    const code = input.searchParams.get('at') ?? '';\n    if (!input.verifyTotpCode(code)) {\n      return { attach: false, reason: 'auth' };\n    }\n  }\n\n  return { attach: true, relayUrl: relayUrl.href, deploymentId };\n}\n","/**\n * In-app Chii target injection for the debug attach flow.\n *\n * Spec: docs/superpowers/specs/2026-05-18-in-app-debug-mcp.md\n * \"MCP attach\" topology section — Phase 1 browser-side implementation.\n *\n * This module bridges the 3-layer gate result to a Chii `target.js` script\n * injection. The Chii npm package is the relay SERVER — the in-app side is\n * a plain `<script src=\"…/target.js\">` pointing at the relay host. No chii\n * npm dependency is needed here.\n */\n\nimport { checkDebugGate, type GateResult } from './index.js';\n\n/**\n * Converts a validated `wss:` relay URL into the Chii `target.js` script URL.\n *\n * Scheme is mapped `wss:` → `https:`. Host and port are preserved.\n * Pathname is set to `/target.js` regardless of the relay path.\n * Query params and hash from the relay URL are dropped — the target script\n * URL is a static asset path on the same host.\n *\n * @example\n * deriveTargetScriptUrl('wss://abc.trycloudflare.com/relay')\n * // → 'https://abc.trycloudflare.com/target.js'\n *\n * deriveTargetScriptUrl('wss://h.example.com:9100/')\n * // → 'https://h.example.com:9100/target.js'\n */\nexport function deriveTargetScriptUrl(relayUrl: string): string {\n  const u = new URL(relayUrl);\n  u.protocol = 'https:';\n  u.pathname = '/target.js';\n  u.search = '';\n  u.hash = '';\n  return u.toString();\n}\n\n/** Module-level guard against double-injection within a page lifecycle. */\nlet attached = false;\n\n/**\n * Evaluates the 3-layer debug gate and, if the gate passes, injects the Chii\n * `target.js` script into `document.head`.\n *\n * Idempotent — calling more than once is safe. The second call is a no-op if\n * a script with the same `src` is already present in the document, and the\n * module-level `attached` flag prevents redundant DOM queries after the first\n * successful injection.\n *\n * Safe to call even if `document` is somehow unavailable (defensive boundary\n * guard — in practice this always runs in a real WebView).\n *\n * @param gateResult - Optional pre-evaluated gate result for testability.\n *   Defaults to `checkDebugGate()` which reads the current page URL. Passing a\n *   custom value avoids the need to manipulate `window.location` in tests.\n */\nexport function maybeAttach(gateResult: GateResult = checkDebugGate()): void {\n  if (!gateResult.attach) {\n    console.debug(\n      `[@ait-co/devtools] debug attach skipped — gate blocked (reason: ${gateResult.reason})`,\n    );\n    return;\n  }\n\n  // Guard against double-injection across repeated calls.\n  if (attached) {\n    return;\n  }\n\n  // Defensive: if document is not available (unusual, but possible in some\n  // SSR-adjacent edge cases), bail silently rather than throwing.\n  if (typeof document === 'undefined') {\n    return;\n  }\n\n  const src = deriveTargetScriptUrl(gateResult.relayUrl);\n\n  // Also guard against a script with the same src already in the DOM\n  // (e.g. injected by a different code path or a page reload within SPA).\n  const existing = document.querySelector<HTMLScriptElement>(`script[src=\"${src}\"]`);\n  if (existing !== null) {\n    attached = true;\n    return;\n  }\n\n  const script = document.createElement('script');\n  script.src = src;\n  script.async = true;\n  (document.head ?? document.documentElement).appendChild(script);\n\n  attached = true;\n}\n","/**\n * @ait-co/devtools/in-app entry point.\n *\n * Spec: docs/superpowers/specs/2026-05-18-in-app-debug-mcp.md\n *\n * Phase 1 — gate + browser-side Chii target injection.\n * WebSocket relay, QR/paste UI, and AI-host MCP bin are later phases that\n * require real-device validation and are not included here.\n *\n * This thin entry reads `window.location` and calls the pure\n * {@link evaluateDebugGate} function. All testable logic lives in `./gate.ts`\n * and `./attach.ts`, not here.\n *\n * Layer A of the activation gate (build-time) is NOT enforced in this module.\n * It is the consumer's responsibility: the consumer wraps its\n * `import('@ait-co/devtools/in-app')` call site in `if (__DEBUG_BUILD__) { … }`\n * (see sdk-example `src/main.tsx`), where `__DEBUG_BUILD__` is a\n * consumer-build-time constant. A release consumer build folds that constant\n * to `false` and dead-code-eliminates this whole module. This package is\n * pre-built and ships with `__DEBUG_BUILD__` already resolved at devtools'\n * publish time, so it could never re-evaluate the consumer's build channel —\n * which is exactly why Layer A lives at the consumer guard, not here.\n */\n\nimport { evaluateDebugGate, type GateResult } from './gate.js';\n\nexport { deriveTargetScriptUrl, maybeAttach } from './attach.js';\nexport type { GateInput, GateResult, GateResultAttach, GateResultBlocked } from './gate.js';\nexport { evaluateDebugGate, isPrivateAppsHost } from './gate.js';\n\n/**\n * Evaluates the runtime debug activation layers (B and C) against the current\n * page URL.\n *\n * Returns the gate result. Callers can check `result.attach` to decide whether\n * to proceed with debug surface attachment.\n *\n * This function reads `window.location` only — both the hostname (Layer B1\n * host allowlist) and the search params (Layers B2 and C). Layer A\n * (build-time) is enforced by the consumer's `if (__DEBUG_BUILD__)` guard\n * around the import site, not here — see the file-level comment. Consumers\n * call this with no arguments, so the Layer B1 host check is picked up with\n * no change at the call site.\n */\nexport function checkDebugGate(): GateResult {\n  return evaluateDebugGate({\n    hostname: window.location.hostname,\n    searchParams: new URLSearchParams(window.location.search),\n  });\n}\n"],"mappings":";;;;;;;;;;AA8JA,MAAM,2BAA2B;;;;;;;;;;;;AAajC,SAAgB,kBAAkB,UAA2B;AAC3D,QAAO,SAAS,SAAS,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;AAwBpD,SAAgB,kBAAkB,OAA8B;AAQ9D,KAAI,CAAC,kBAAkB,MAAM,SAAS,CACpC,QAAO;EAAE,QAAQ;EAAO,QAAQ;EAAQ;CAO1C,MAAM,eAAe,MAAM,aAAa,IAAI,gBAAgB,IAAI;AAChE,KAAI,iBAAiB,GACnB,QAAO;EAAE,QAAQ;EAAO,QAAQ;EAAS;AAO3C,KADmB,MAAM,aAAa,IAAI,QAAQ,KAC/B,IACjB,QAAO;EAAE,QAAQ;EAAO,QAAQ;EAAU;CAM5C,MAAM,WAAW,MAAM,aAAa,IAAI,QAAQ,IAAI;AACpD,KAAI,aAAa,GACf,QAAO;EAAE,QAAQ;EAAO,QAAQ;EAAiB;CAGnD,IAAI;AACJ,KAAI;AACF,aAAW,IAAI,IAAI,SAAS;SACtB;AACN,SAAO;GAAE,QAAQ;GAAO,QAAQ;GAAiB;;AAGnD,KAAI,SAAS,aAAa,OACxB,QAAO;EAAE,QAAQ;EAAO,QAAQ;EAAiB;AAUnD,KAAI,MAAM,mBAAmB,KAAA,GAAW;EACtC,MAAM,OAAO,MAAM,aAAa,IAAI,KAAK,IAAI;AAC7C,MAAI,CAAC,MAAM,eAAe,KAAK,CAC7B,QAAO;GAAE,QAAQ;GAAO,QAAQ;GAAQ;;AAI5C,QAAO;EAAE,QAAQ;EAAM,UAAU,SAAS;EAAM;EAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACrOhE,SAAgB,sBAAsB,UAA0B;CAC9D,MAAM,IAAI,IAAI,IAAI,SAAS;AAC3B,GAAE,WAAW;AACb,GAAE,WAAW;AACb,GAAE,SAAS;AACX,GAAE,OAAO;AACT,QAAO,EAAE,UAAU;;;AAIrB,IAAI,WAAW;;;;;;;;;;;;;;;;;AAkBf,SAAgB,YAAY,aAAyB,gBAAgB,EAAQ;AAC3E,KAAI,CAAC,WAAW,QAAQ;AACtB,UAAQ,MACN,mEAAmE,WAAW,OAAO,GACtF;AACD;;AAIF,KAAI,SACF;AAKF,KAAI,OAAO,aAAa,YACtB;CAGF,MAAM,MAAM,sBAAsB,WAAW,SAAS;AAKtD,KADiB,SAAS,cAAiC,eAAe,IAAI,IAAI,KACjE,MAAM;AACrB,aAAW;AACX;;CAGF,MAAM,SAAS,SAAS,cAAc,SAAS;AAC/C,QAAO,MAAM;AACb,QAAO,QAAQ;AACf,EAAC,SAAS,QAAQ,SAAS,iBAAiB,YAAY,OAAO;AAE/D,YAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC/Cb,SAAgB,iBAA6B;AAC3C,QAAO,kBAAkB;EACvB,UAAU,OAAO,SAAS;EAC1B,cAAc,IAAI,gBAAgB,OAAO,SAAS,OAAO;EAC1D,CAAC"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/in-app/gate.ts","../../src/in-app/attach.ts","../../src/in-app/index.ts"],"sourcesContent":["/**\n * Runtime activation gate for the in-app debug surface.\n *\n * Spec: docs/superpowers/specs/2026-05-18-in-app-debug-mcp.md\n * \"3-layer activation gate\". This is the pure gate decision; the Chii client,\n * WebSocket transport, MCP server, and CLI that consume it live in src/mcp/.\n *\n * This function evaluates the two RUNTIME layers, B and C. Layer A — the\n * build-time gate — is NOT evaluated here, and deliberately so: it is enforced\n * entirely by the consumer's `if (__DEBUG_BUILD__) { … }` guard around the\n * import site (see sdk-example `src/main.tsx`). `__DEBUG_BUILD__` is a\n * consumer-build-time constant; a release consumer build folds it to `false`\n * and dead-code-eliminates the whole import of `@ait-co/devtools/in-app`, so\n * this code is simply absent from release bundles. A pre-built npm package\n * cannot re-check that flag — it was already baked at devtools' own publish\n * time — so any `isDebugBuild` check inside this function would be permanently\n * `false` and could never pass. Layer A is the consumer guard; B and C are\n * here.\n *\n * Layer B has two parts. Both must pass:\n *   B1 — host allowlist: `hostname` must be a `*.private-apps.tossmini.com`\n *        subdomain. The Toss app serves dogfood / private mini-apps from a\n *        separate `private-apps` host; a production (`intoss://`) entry is\n *        served from `*.apps.tossmini.com` WITHOUT the `private-apps` segment.\n *        This is the security gate against a dogfood build that somehow lands\n *        on a production entry — see the comment on {@link isPrivateAppsHost}.\n *   B2 — entry query: `_deploymentId` must be present and non-empty.\n *\n * Layer C — opt-in + relay + optional TOTP auth:\n *   C1 — opt-in:       `debug=1` must be present.\n *   C2 — relay URL:    `relay=<wss-url>` must be a valid `wss:` URL.\n *   C3 — TOTP auth:    When `verifyTotpCode` is provided (consumer injected the\n *                      baked secret at build time via `__DEBUG_TOTP_SECRET__`),\n *                      `at=<code>` is checked. Invalid or absent code → BLOCKED.\n *                      When no verifier is provided (TOTP disabled), `at` is\n *                      ignored (backward compatible).\n *\n * Security note on baked secrets:\n *   The TOTP secret baked in via `__DEBUG_TOTP_SECRET__` is present in the\n *   dogfood bundle and is extractable by a determined reverse engineer.\n *   The practical bar raised is: \"URL leak\" (Slack paste, QR screenshot) →\n *   blocked; \"URL + bundle extraction + live TOTP code\" → not blocked.\n *   This is the intended threat model. Do not overpromise on this guarantee.\n *\n * SECRET-HANDLING: `verifyTotpCode` is a black-box predicate. This module\n *   does NOT log the secret, any code value, or pass/fail details beyond the\n *   `'auth'` reason enum.\n *\n * Decision matrix (gate only runs in a debug build — Layer A already passed):\n *\n *   host ok | _deploymentId | debug=1 | relay ok | TOTP ok* | result\n *   no      | (any)         | (any)   | (any)    | (any)    | BLOCKED (host)\n *   yes     | absent        | (any)   | (any)    | (any)    | BLOCKED (entry)\n *   yes     | present       | absent  | (any)    | (any)    | BLOCKED (opt-in)\n *   yes     | present       | present | invalid  | (any)    | BLOCKED (invalid-relay)\n *   yes     | present       | present | valid    | fail*    | BLOCKED (auth)\n *   yes     | present       | present | valid    | pass/n/a | ATTACH\n *\n *   * \"TOTP ok\" column only applies when `verifyTotpCode` is provided.\n *     When no verifier is injected, TOTP check is skipped entirely.\n */\n\n/** Shape returned when the gate allows attachment. */\nexport interface GateResultAttach {\n  readonly attach: true;\n  /** The validated `wss:` relay URL from the `relay` query param. */\n  readonly relayUrl: string;\n  /** The deployment ID extracted from the `_deploymentId` query param. */\n  readonly deploymentId: string;\n}\n\n/** Shape returned when the gate blocks attachment, with a reason code. */\nexport interface GateResultBlocked {\n  readonly attach: false;\n  /**\n   * - `'host'`          Layer B1: `hostname` is not a `*.private-apps.tossmini.com` host.\n   * - `'entry'`         Layer B2: `_deploymentId` param is absent or empty.\n   * - `'opt-in'`        Layer C1: `debug=1` param is absent.\n   * - `'invalid-relay'` Layer C2: `relay` param is absent, empty, or not a `wss:` URL.\n   * - `'auth'`          Layer C3: TOTP `at=` code is absent, invalid, or expired\n   *                     (only when a `verifyTotpCode` predicate is injected).\n   *\n   * There is no `'build'` reason: Layer A is enforced by the consumer's\n   * `if (__DEBUG_BUILD__)` guard, not by this function.\n   *\n   * SECRET-HANDLING: `'auth'` is the only value surfaced for auth failures —\n   * no code value, expected value, or secret fragment is ever exposed.\n   */\n  readonly reason: 'host' | 'entry' | 'opt-in' | 'invalid-relay' | 'auth';\n}\n\nexport type GateResult = GateResultAttach | GateResultBlocked;\n\n/**\n * Input for {@link evaluateDebugGate}.\n *\n * All fields are explicit so the function is trivially testable without\n * touching `window`.\n */\nexport interface GateInput {\n  /**\n   * The host the page is served from — `window.location.hostname`.\n   *\n   * This is the Layer B1 security signal. Why hostname and not the entry\n   * scheme: the Toss SDK normalises `intoss-private://` to `intoss://` in\n   * `getSchemeUri()`, and `getOperationalEnvironment()` / `getWebViewType()`\n   * return the same value (`\"toss\"` / `\"partner\"`) for both dogfood and\n   * production entries — none of them distinguish a dogfood entry. The host\n   * does: a dogfood / private-apps entry is served from\n   * `*.private-apps.tossmini.com`, a production entry is not. This was\n   * confirmed live over CDP against mini-app 31146 (see spec open question 2).\n   */\n  readonly hostname: string;\n\n  /**\n   * The URL search params to inspect for gate signals (Layers B2 and C).\n   *\n   * Prefer `URLSearchParams` so callers can pass `new URLSearchParams(location.search)`\n   * without coupling the pure function to `window`.\n   */\n  readonly searchParams: URLSearchParams;\n\n  /**\n   * Optional TOTP code verifier for Layer C3 auth gate.\n   *\n   * When provided, `evaluateDebugGate` reads the `at` query param and passes\n   * it to this predicate. Return `true` to allow, `false` to block with\n   * `reason: 'auth'`.\n   *\n   * Inject via the consumer's build define, e.g.:\n   * ```ts\n   * // dogfood build entry — consumer's build injects __DEBUG_TOTP_SECRET__\n   * declare const __DEBUG_TOTP_SECRET__: string | undefined;\n   * const verifyTotpCode = typeof __DEBUG_TOTP_SECRET__ !== 'undefined'\n   *   ? (code: string) => verifyTotp(__DEBUG_TOTP_SECRET__, code)\n   *   : undefined;\n   * maybeAttach(evaluateDebugGate({ ...params, verifyTotpCode }));\n   * ```\n   *\n   * Security note: this predicate is a black-box from the gate's perspective.\n   * The gate only surfaces pass/fail and the `'auth'` reason code — no code\n   * value or secret fragment is ever logged or returned.\n   *\n   * When `undefined` (TOTP disabled), `at=` is silently ignored and the gate\n   * proceeds to ATTACH if all other layers pass.\n   */\n  readonly verifyTotpCode?: (code: string) => boolean;\n}\n\n/**\n * The host suffix the Toss app uses to serve dogfood / private mini-apps.\n *\n * A `intoss-private://` (dogfood) entry maps to a host such as\n * `aitc-sdk-example.private-apps.tossmini.com`. A production `intoss://`\n * entry is served from `*.apps.tossmini.com` — the `.private-apps.` segment\n * is absent. Confirmed live over CDP for mini-app 31146; the exact production\n * host is to be re-confirmed once 31146 passes review (spec open question 2).\n */\nconst PRIVATE_APPS_HOST_SUFFIX = '.private-apps.tossmini.com';\n\n/**\n * Returns whether `hostname` is a `*.private-apps.tossmini.com` subdomain —\n * the host the Toss app reserves for dogfood / private mini-app entries.\n *\n * The match is an exact suffix check, not a substring `.includes()`: a\n * substring test would also accept an attacker-controlled host like\n * `private-apps.tossmini.com.evil.example`, which ends in `.example`, not in\n * `.tossmini.com`. Requiring the string to END with the suffix closes that.\n * The leading `.` in the suffix also forces a real subdomain label, so a\n * bare `private-apps.tossmini.com` (no mini-app subdomain) does not match.\n */\nexport function isPrivateAppsHost(hostname: string): boolean {\n  return hostname.endsWith(PRIVATE_APPS_HOST_SUFFIX);\n}\n\n/**\n * Pure function that evaluates the runtime debug activation layers (B and C).\n *\n * Has no side effects. The input is explicit. Returns a discriminated union\n * so callers can pattern-match on `result.attach`.\n *\n * Layer A (build-time) is intentionally not evaluated here — see the file-level\n * comment. By the time this function runs, the consumer's `if (__DEBUG_BUILD__)`\n * guard has already passed; this function only decides B and C.\n *\n * @example\n * ```ts\n * const result = evaluateDebugGate({\n *   hostname: window.location.hostname,\n *   searchParams: new URLSearchParams(window.location.search),\n * });\n * if (result.attach) {\n *   // Proceed to load Chii client\n * }\n * ```\n */\nexport function evaluateDebugGate(input: GateInput): GateResult {\n  // Layer B1 — host allowlist (the security gate).\n  // The page must be served from a `*.private-apps.tossmini.com` host. A\n  // production `intoss://` entry is served from `*.apps.tossmini.com` and is\n  // rejected here. This is what stops a dogfood build that somehow reaches a\n  // production entry from attaching: Layer A keeps debug code out of release\n  // bundles, and this layer keeps a dogfood bundle that lands on a production\n  // host from attaching even though its code is present.\n  if (!isPrivateAppsHost(input.hostname)) {\n    return { attach: false, reason: 'host' };\n  }\n\n  // Layer B2 — runtime entry query gate.\n  // `_deploymentId` must be present and non-empty. The `intoss-private://`\n  // scheme used for dogfood entries includes this param; general user entry\n  // paths do not.\n  const deploymentId = input.searchParams.get('_deploymentId') ?? '';\n  if (deploymentId === '') {\n    return { attach: false, reason: 'entry' };\n  }\n\n  // Layer C — explicit opt-in gate.\n  // Require `debug=1` so that an operator who opens a dogfood URL by accident\n  // does not inadvertently trigger the debug surface.\n  const debugParam = input.searchParams.get('debug');\n  if (debugParam !== '1') {\n    return { attach: false, reason: 'opt-in' };\n  }\n\n  // Layer C continued — relay URL validation.\n  // `relay=<wss-url>` must be present and must use the `wss:` scheme.\n  // Plain `ws:` is rejected (no TLS). `http:`/`https:` are rejected.\n  const relayRaw = input.searchParams.get('relay') ?? '';\n  if (relayRaw === '') {\n    return { attach: false, reason: 'invalid-relay' };\n  }\n\n  let relayUrl: URL;\n  try {\n    relayUrl = new URL(relayRaw);\n  } catch {\n    return { attach: false, reason: 'invalid-relay' };\n  }\n\n  if (relayUrl.protocol !== 'wss:') {\n    return { attach: false, reason: 'invalid-relay' };\n  }\n\n  // Layer C3 — TOTP auth gate (fail-fast, only when a verifier is injected).\n  // The `at` query param carries the current TOTP code. Absent or invalid code\n  // → BLOCKED. When no verifier is provided (TOTP disabled), this check is\n  // skipped entirely for backward compatibility.\n  //\n  // SECRET-HANDLING: we do NOT log `code`, the verifier's result, or anything\n  // derived from the secret. Only the `'auth'` enum is surfaced on failure.\n  if (input.verifyTotpCode !== undefined) {\n    const code = input.searchParams.get('at') ?? '';\n    if (!input.verifyTotpCode(code)) {\n      return { attach: false, reason: 'auth' };\n    }\n  }\n\n  return { attach: true, relayUrl: relayUrl.href, deploymentId };\n}\n","/**\n * In-app Chii target injection for the debug attach flow.\n *\n * Spec: docs/superpowers/specs/2026-05-18-in-app-debug-mcp.md\n * \"MCP attach\" topology section — Phase 1 browser-side implementation.\n *\n * This module bridges the 3-layer gate result to a Chii `target.js` script\n * injection. The Chii npm package is the relay SERVER — the in-app side is\n * a plain `<script src=\"…/target.js\">` pointing at the relay host. No chii\n * npm dependency is needed here.\n */\n\nimport { setScreenAwakeMode } from '@apps-in-toss/web-framework';\nimport { checkDebugGate, type GateResult } from './index.js';\n\n/**\n * Converts a validated `wss:` relay URL into the Chii `target.js` script URL.\n *\n * Scheme is mapped `wss:` → `https:`. Host and port are preserved.\n * Pathname is set to `/target.js` regardless of the relay path.\n * Query params and hash from the relay URL are dropped — the target script\n * URL is a static asset path on the same host.\n *\n * @example\n * deriveTargetScriptUrl('wss://abc.trycloudflare.com/relay')\n * // → 'https://abc.trycloudflare.com/target.js'\n *\n * deriveTargetScriptUrl('wss://h.example.com:9100/')\n * // → 'https://h.example.com:9100/target.js'\n */\nexport function deriveTargetScriptUrl(relayUrl: string): string {\n  const u = new URL(relayUrl);\n  u.protocol = 'https:';\n  u.pathname = '/target.js';\n  u.search = '';\n  u.hash = '';\n  return u.toString();\n}\n\n/** Module-level guard against double-injection within a page lifecycle. */\nlet attached = false;\n\n/**\n * Evaluates the 3-layer debug gate and, if the gate passes, injects the Chii\n * `target.js` script into `document.head`.\n *\n * Idempotent — calling more than once is safe. The second call is a no-op if\n * a script with the same `src` is already present in the document, and the\n * module-level `attached` flag prevents redundant DOM queries after the first\n * successful injection.\n *\n * Safe to call even if `document` is somehow unavailable (defensive boundary\n * guard — in practice this always runs in a real WebView).\n *\n * **keepAwake side effect**: on a successful attach, `setScreenAwakeMode({\n * enabled: true })` is called so the phone screen stays awake during the debug\n * session. A `beforeunload` handler restores normal sleep on page unload.\n * Opt out by adding `noKeepAwake=1` to the page URL query string — the check\n * reads `window.location.search` directly, consistent with other guards in\n * this file.\n *\n * @param gateResult - Optional pre-evaluated gate result for testability.\n *   Defaults to `checkDebugGate()` which reads the current page URL. Passing a\n *   custom value avoids the need to manipulate `window.location` in tests.\n */\nexport function maybeAttach(gateResult: GateResult = checkDebugGate()): void {\n  if (!gateResult.attach) {\n    console.debug(\n      `[@ait-co/devtools] debug attach skipped — gate blocked (reason: ${gateResult.reason})`,\n    );\n    return;\n  }\n\n  // Guard against double-injection across repeated calls.\n  if (attached) {\n    return;\n  }\n\n  // Defensive: if document is not available (unusual, but possible in some\n  // SSR-adjacent edge cases), bail silently rather than throwing.\n  if (typeof document === 'undefined') {\n    return;\n  }\n\n  const src = deriveTargetScriptUrl(gateResult.relayUrl);\n\n  // Also guard against a script with the same src already in the DOM\n  // (e.g. injected by a different code path or a page reload within SPA).\n  const existing = document.querySelector<HTMLScriptElement>(`script[src=\"${src}\"]`);\n  if (existing !== null) {\n    attached = true;\n    return;\n  }\n\n  const script = document.createElement('script');\n  script.src = src;\n  script.async = true;\n  (document.head ?? document.documentElement).appendChild(script);\n\n  attached = true;\n\n  // keepAwake — keep phone screen on during the debug session.\n  // Opt out via noKeepAwake=1 in the URL (consistent with direct window reads\n  // used throughout this file).\n  if (\n    typeof window !== 'undefined' &&\n    new URLSearchParams(window.location.search).get('noKeepAwake') === '1'\n  ) {\n    return;\n  }\n\n  setScreenAwakeMode({ enabled: true })\n    .then(() => {\n      // Restore normal sleep on page unload — only if the enable call succeeded\n      // (nothing to restore if it failed).\n      window.addEventListener(\n        'beforeunload',\n        () => {\n          setScreenAwakeMode({ enabled: false }).catch(() => {});\n        },\n        { once: true },\n      );\n    })\n    .catch((err) => {\n      // Swallow rejection so attach never breaks — some platforms/mock reject.\n      console.debug('[@ait-co/devtools] setScreenAwakeMode failed:', err);\n    });\n}\n","/**\n * @ait-co/devtools/in-app entry point.\n *\n * Spec: docs/superpowers/specs/2026-05-18-in-app-debug-mcp.md\n *\n * Phase 1 — gate + browser-side Chii target injection.\n * WebSocket relay, QR/paste UI, and AI-host MCP bin are later phases that\n * require real-device validation and are not included here.\n *\n * This thin entry reads `window.location` and calls the pure\n * {@link evaluateDebugGate} function. All testable logic lives in `./gate.ts`\n * and `./attach.ts`, not here.\n *\n * Layer A of the activation gate (build-time) is NOT enforced in this module.\n * It is the consumer's responsibility: the consumer wraps its\n * `import('@ait-co/devtools/in-app')` call site in `if (__DEBUG_BUILD__) { … }`\n * (see sdk-example `src/main.tsx`), where `__DEBUG_BUILD__` is a\n * consumer-build-time constant. A release consumer build folds that constant\n * to `false` and dead-code-eliminates this whole module. This package is\n * pre-built and ships with `__DEBUG_BUILD__` already resolved at devtools'\n * publish time, so it could never re-evaluate the consumer's build channel —\n * which is exactly why Layer A lives at the consumer guard, not here.\n */\n\nimport { evaluateDebugGate, type GateResult } from './gate.js';\n\nexport { deriveTargetScriptUrl, maybeAttach } from './attach.js';\nexport type { GateInput, GateResult, GateResultAttach, GateResultBlocked } from './gate.js';\nexport { evaluateDebugGate, isPrivateAppsHost } from './gate.js';\n\n/**\n * Evaluates the runtime debug activation layers (B and C) against the current\n * page URL.\n *\n * Returns the gate result. Callers can check `result.attach` to decide whether\n * to proceed with debug surface attachment.\n *\n * This function reads `window.location` only — both the hostname (Layer B1\n * host allowlist) and the search params (Layers B2 and C). Layer A\n * (build-time) is enforced by the consumer's `if (__DEBUG_BUILD__)` guard\n * around the import site, not here — see the file-level comment. Consumers\n * call this with no arguments, so the Layer B1 host check is picked up with\n * no change at the call site.\n */\nexport function checkDebugGate(): GateResult {\n  return evaluateDebugGate({\n    hostname: window.location.hostname,\n    searchParams: new URLSearchParams(window.location.search),\n  });\n}\n"],"mappings":";;;;;;;;;;;AA8JA,MAAM,2BAA2B;;;;;;;;;;;;AAajC,SAAgB,kBAAkB,UAA2B;AAC3D,QAAO,SAAS,SAAS,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;AAwBpD,SAAgB,kBAAkB,OAA8B;AAQ9D,KAAI,CAAC,kBAAkB,MAAM,SAAS,CACpC,QAAO;EAAE,QAAQ;EAAO,QAAQ;EAAQ;CAO1C,MAAM,eAAe,MAAM,aAAa,IAAI,gBAAgB,IAAI;AAChE,KAAI,iBAAiB,GACnB,QAAO;EAAE,QAAQ;EAAO,QAAQ;EAAS;AAO3C,KADmB,MAAM,aAAa,IAAI,QAAQ,KAC/B,IACjB,QAAO;EAAE,QAAQ;EAAO,QAAQ;EAAU;CAM5C,MAAM,WAAW,MAAM,aAAa,IAAI,QAAQ,IAAI;AACpD,KAAI,aAAa,GACf,QAAO;EAAE,QAAQ;EAAO,QAAQ;EAAiB;CAGnD,IAAI;AACJ,KAAI;AACF,aAAW,IAAI,IAAI,SAAS;SACtB;AACN,SAAO;GAAE,QAAQ;GAAO,QAAQ;GAAiB;;AAGnD,KAAI,SAAS,aAAa,OACxB,QAAO;EAAE,QAAQ;EAAO,QAAQ;EAAiB;AAUnD,KAAI,MAAM,mBAAmB,KAAA,GAAW;EACtC,MAAM,OAAO,MAAM,aAAa,IAAI,KAAK,IAAI;AAC7C,MAAI,CAAC,MAAM,eAAe,KAAK,CAC7B,QAAO;GAAE,QAAQ;GAAO,QAAQ;GAAQ;;AAI5C,QAAO;EAAE,QAAQ;EAAM,UAAU,SAAS;EAAM;EAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACpOhE,SAAgB,sBAAsB,UAA0B;CAC9D,MAAM,IAAI,IAAI,IAAI,SAAS;AAC3B,GAAE,WAAW;AACb,GAAE,WAAW;AACb,GAAE,SAAS;AACX,GAAE,OAAO;AACT,QAAO,EAAE,UAAU;;;AAIrB,IAAI,WAAW;;;;;;;;;;;;;;;;;;;;;;;;AAyBf,SAAgB,YAAY,aAAyB,gBAAgB,EAAQ;AAC3E,KAAI,CAAC,WAAW,QAAQ;AACtB,UAAQ,MACN,mEAAmE,WAAW,OAAO,GACtF;AACD;;AAIF,KAAI,SACF;AAKF,KAAI,OAAO,aAAa,YACtB;CAGF,MAAM,MAAM,sBAAsB,WAAW,SAAS;AAKtD,KADiB,SAAS,cAAiC,eAAe,IAAI,IAAI,KACjE,MAAM;AACrB,aAAW;AACX;;CAGF,MAAM,SAAS,SAAS,cAAc,SAAS;AAC/C,QAAO,MAAM;AACb,QAAO,QAAQ;AACf,EAAC,SAAS,QAAQ,SAAS,iBAAiB,YAAY,OAAO;AAE/D,YAAW;AAKX,KACE,OAAO,WAAW,eAClB,IAAI,gBAAgB,OAAO,SAAS,OAAO,CAAC,IAAI,cAAc,KAAK,IAEnE;AAGF,oBAAmB,EAAE,SAAS,MAAM,CAAC,CAClC,WAAW;AAGV,SAAO,iBACL,sBACM;AACJ,sBAAmB,EAAE,SAAS,OAAO,CAAC,CAAC,YAAY,GAAG;KAExD,EAAE,MAAM,MAAM,CACf;GACD,CACD,OAAO,QAAQ;AAEd,UAAQ,MAAM,iDAAiD,IAAI;GACnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AClFN,SAAgB,iBAA6B;AAC3C,QAAO,kBAAkB;EACvB,UAAU,OAAO,SAAS;EAC1B,cAAc,IAAI,gBAAgB,OAAO,SAAS,OAAO;EAC1D,CAAC"}

package/dist/mcp/cli.js

@@ -3148,6 +3148,7 @@ function readDevtoolsVersion() {
 * Derives the next recommended action from a completed diagnostics snapshot.
 *
 * Branch rules (evaluated in priority order):
+*   0. tunnel.droppedAt non-null                  → restart (permanent tunnel drop — highest priority)
 *   1. tunnel.up === false AND env is relay       → restart (relay needs a live tunnel)
 *   1b. tunnel.up === false AND env is mock       → wait_for_page (local target: tunnel-less is normal)
 *   2. tunnel.up, pages empty, env === relay      → build_attach_url (start attach)
@@ -3157,6 +3158,10 @@ function readDevtoolsVersion() {
 * Pure — does not throw; receives the final assembled snapshot fields.
 */
 function computeNextRecommendedAction(tunnel, pages, env) {
+	if (tunnel.droppedAt != null) return {
+		tool: "restart",
+		reason: `tunnel permanently dropped at ${tunnel.droppedAt} after ${tunnel.reissueAttempts} reissue attempt(s) — restart the MCP server (npx @ait-co/devtools devtools-mcp)`
+	};
 	if (!tunnel.up) if (!isRelayEnv(env)) {
 		if (pages !== null && pages.pages.length === 0 && !pages.crashDetectedAt) return {
 			tool: "wait_for_page",
@@ -3187,7 +3192,7 @@ function computeNextRecommendedAction(tunnel, pages, env) {
 *   - Lock file data contains only pid + startedAt + wssUrl — no secrets.
 */
 async function getDiagnostics(input) {
-	const { tunnel, connection, env, envReason, collector, readLock: readLockFn, recentErrorsLimit = 10, getMcpVersion = readMcpSdkVersion } = input;
+	const { tunnel, connection, env, envReason, collector, readLock: readLockFn, recentErrorsLimit = 10, getMcpVersion = readMcpSdkVersion, checkParentAlive = () => isPidAlive(process.ppid) } = input;
 	const [mcpVersion, devtoolsVersion] = await Promise.all([getMcpVersion(), Promise.resolve(readDevtoolsVersion())]);
 	const lockData = readLockFn();
 	const serverLockHolder = lockData ? {
@@ -3199,7 +3204,9 @@ async function getDiagnostics(input) {
 		up: tunnel.up,
 		wssUrl: tunnel.wssUrl,
 		pid: lockData?.pid ?? null,
-		startedAt: lockData?.startedAt ?? null
+		startedAt: lockData?.startedAt ?? null,
+		droppedAt: tunnel.droppedAt ?? null,
+		reissueAttempts: tunnel.reissueAttempts ?? 0
 	};
 	let pages = null;
 	if (connection !== void 0) try {
@@ -3223,6 +3230,11 @@ async function getDiagnostics(input) {
 			liveGuardActive: isLiveRelayEnv(env)
 		},
 		serverLockHolder,
+		process: {
+			pid: process.pid,
+			ppid: process.ppid,
+			parentAlive: checkParentAlive()
+		},
 		nextRecommendedAction
 	};
 }
@@ -3549,8 +3561,10 @@ function extractDeploymentId(schemeUrl) {
 }
 /**
 * Waits for the first target matching `filterFn` to attach, using the
-* event-driven `waitForFirstTarget()` on `ChiiCdpConnection` instances, or
-* falling back to a polling loop for generic `CdpConnection` fakes (tests).
+* 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
@@ -3559,10 +3573,10 @@ function extractDeploymentId(schemeUrl) {
 * @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 non-ChiiCdpConnection.
+* @param pollIntervalMs - Fallback poll interval for connections without waitForFirstTarget.
 */
 function waitForAttachWithEvents(connection, filterFn, timeoutMs, pollIntervalMs = 1e3) {
-	if (connection instanceof ChiiCdpConnection) return connection.waitForFirstTarget(filterFn, timeoutMs, pollIntervalMs);
+	if (connection.waitForFirstTarget) return connection.waitForFirstTarget(filterFn, timeoutMs, pollIntervalMs);
 	return new Promise((resolve, reject) => {
 		const deadline = Date.now() + timeoutMs;
 		let settled = false;
@@ -3611,7 +3625,7 @@ function createDebugServer(deps) {
 	const collector = collectorDep ?? new InMemoryDiagnosticsCollector();
 	const server = new Server({
 		name: "ait-debug",
-		version: "0.1.49"
+		version: "0.1.51"
 	}, { capabilities: { tools: { listChanged: true } } });
 	server.setRequestHandler(ListToolsRequestSchema, () => {
 		const env = resolveEnvironment();
@@ -3840,8 +3854,8 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 			await connection.enableDomains();
 		} catch (err) {
 			if (name === "list_pages") {
-				if (connection instanceof ChiiCdpConnection) try {
-					await connection.refreshTargets();
+				try {
+					await connection.refreshTargets?.();
 				} catch {}
 				const pagesData = listPages(connection, getTunnelStatus());
 				const attached = connection.listTargets().length > 0;
@@ -3858,8 +3872,8 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 				}
 				case "list_network_requests": return jsonResult$1(listNetworkRequests(connection));
 				case "list_pages": {
-					if (connection instanceof ChiiCdpConnection) try {
-						await connection.refreshTargets();
+					try {
+						await connection.refreshTargets?.();
 					} catch {}
 					const listPagesData = listPages(connection, getTunnelStatus());
 					const listPagesAttached = connection.listTargets().length > 0;
@@ -3991,6 +4005,45 @@ function startAttachWatcher(connection, server, intervalMs = 1e3, onFirstAttach)
 	} };
 }
 /**
+* Starts a periodic watcher that detects when the parent process (e.g. Claude
+* Code) has died without sending SIGTERM/SIGHUP, and calls `onOrphaned` so the
+* daemon can self-terminate rather than running as a zombie.
+*
+* Mirrors the `startAttachWatcher` pattern: `setInterval`-based, returns
+* `{ stop(): void }`, injectable deps for testability.
+*
+* @param onOrphaned - Called once when the parent is gone.
+* @param opts.intervalMs   - Poll interval in milliseconds (default 5 000).
+* @param opts.initialPpid  - Parent PID to watch (default `process.ppid`).
+* @param opts.isAlive      - Predicate to test if a PID is running (default `isPidAlive`).
+* @param opts.getPpid      - Supplier of current ppid (default `() => process.ppid`).
+*                            Detects ppid changes as well as death.
+* @param opts.log          - Logger (default `process.stderr.write`).
+*
+* @returns `stop` — call during shutdown to clear the interval.
+*/
+function startParentWatcher(onOrphaned, opts) {
+	const { intervalMs = 5e3, initialPpid = process.ppid, isAlive = isPidAlive, getPpid = () => process.ppid, log = (msg) => process.stderr.write(msg) } = opts ?? {};
+	if (initialPpid <= 1) {
+		log("[ait-debug] parent-pid watcher: no parent to watch (ppid<=1), skipping\n");
+		return { stop() {} };
+	}
+	let fired = false;
+	const handle = setInterval(() => {
+		if (fired) return;
+		const currentPpid = getPpid();
+		if (currentPpid !== initialPpid || !isAlive(initialPpid)) {
+			fired = true;
+			clearInterval(handle);
+			log(`[ait-debug] parent-pid watcher: parent PID ${initialPpid} is gone (currentPpid=${currentPpid}) — shutting down\n`);
+			onOrphaned();
+		}
+	}, intervalMs);
+	return { stop() {
+		clearInterval(handle);
+	} };
+}
+/**
 * Reads `AIT_DEBUG_TOTP_SECRET` from `process.env` at runtime and builds a
 * `verifyAuth` predicate for the Chii relay's WebSocket upgrade gate.
 *
@@ -4014,6 +4067,19 @@ function buildRelayVerifyAuth() {
 	};
 }
 /**
+* Factory that constructs a `ChiiCdpConnection` for the given relay base URL.
+*
+* Introduced as a named seam so PR-2 (dual-connection, #348) can defer
+* construction to first-activation time by moving or replacing this call —
+* without changing the current eager construction order at startup.
+*
+* The relay base URL is only available after `startChiiRelay()` resolves, so
+* the factory is called right after that point (same as before this refactor).
+*/
+function createRelayConnection(relayBaseUrl) {
+	return new ChiiCdpConnection({ relayBaseUrl });
+}
+/**
 * Boots the live debug stack and serves it over stdio:
 *   1. start the Chii relay on an OS-assigned port (with TOTP auth if
 *      AIT_DEBUG_TOTP_SECRET is set),
@@ -4070,7 +4136,7 @@ async function runDebugServer(options = {}) {
 	}, (err) => {
 		logError("tunnel.down", { msg: `Failed to open cloudflared quick tunnel: ${err instanceof Error ? err.message : String(err)}. The relay is up locally; attach over the public URL is unavailable until the tunnel starts.` });
 	});
-	const connection = new ChiiCdpConnection({ relayBaseUrl: relay.baseUrl });
+	const connection = createRelayConnection(relay.baseUrl);
 	const aitSource = new ChiiAitSource(connection);
 	let qrServer;
 	try {
@@ -4094,9 +4160,11 @@ async function runDebugServer(options = {}) {
 	const transport = new StdioServerTransport();
 	let closed = false;
 	let attachWatcher = null;
+	let parentWatcher = null;
 	const shutdown = () => {
 		if (closed) return;
 		closed = true;
+		parentWatcher?.stop();
 		attachWatcher?.stop();
 		tunnelProbe?.stop();
 		connection.close();
@@ -4112,6 +4180,7 @@ async function runDebugServer(options = {}) {
 	process.on("exit", () => {
 		if (!closed) {
 			closed = true;
+			parentWatcher?.stop();
 			attachWatcher?.stop();
 			tunnelProbe?.stop();
 			tunnel?.stop();
@@ -4142,6 +4211,20 @@ async function runDebugServer(options = {}) {
 			defaultEnv: "relay-dev"
 		}));
 	});
+	if (process.env.AIT_DEBUG_NO_PARENT_WATCH !== "1") {
+		parentWatcher = startParentWatcher(() => {
+			shutdown();
+			process.exit(0);
+		}, { intervalMs: 5e3 });
+		process.stdin.once("end", () => {
+			shutdown();
+			process.exit(0);
+		});
+		process.stdin.once("close", () => {
+			shutdown();
+			process.exit(0);
+		});
+	}
 }
 /**
 * Boots the local-browser debug stack and serves it over stdio:
@@ -4183,9 +4266,11 @@ async function runLocalDebugServer(options = {}) {
 	const transport = new StdioServerTransport();
 	let closed = false;
 	let attachWatcher = null;
+	let parentWatcher = null;
 	const shutdown = () => {
 		if (closed) return;
 		closed = true;
+		parentWatcher?.stop();
 		attachWatcher?.stop();
 		connection.close();
 		chromium.stop();
@@ -4198,6 +4283,7 @@ async function runLocalDebugServer(options = {}) {
 	process.on("exit", () => {
 		if (!closed) {
 			closed = true;
+			parentWatcher?.stop();
 			attachWatcher?.stop();
 			chromium.stop();
 			lockHandle.release();
@@ -4223,6 +4309,20 @@ async function runLocalDebugServer(options = {}) {
 	});
 	await server.connect(transport);
 	attachWatcher = startAttachWatcher(connection, server);
+	if (process.env.AIT_DEBUG_NO_PARENT_WATCH !== "1") {
+		parentWatcher = startParentWatcher(() => {
+			shutdown();
+			process.exit(0);
+		}, { intervalMs: 5e3 });
+		process.stdin.once("end", () => {
+			shutdown();
+			process.exit(0);
+		});
+		process.stdin.once("close", () => {
+			shutdown();
+			process.exit(0);
+		});
+	}
 }
 //#endregion
 //#region src/mcp/ait-http-source.ts
@@ -4635,16 +4735,10 @@ async function buildDevMeasureSafeArea(aitSource) {
 */
 async function buildDevCallSdk(methodName, aitSource) {
 	switch (methodName) {
-		case "getOperationalEnvironment": {
-			const env = await aitSource.get("AIT.getOperationalEnvironment");
-			return {
-				ok: true,
-				value: {
-					environment: env.environment,
-					sdkVersion: env.sdkVersion
-				}
-			};
-		}
+		case "getOperationalEnvironment": return {
+			ok: true,
+			value: (await aitSource.get("AIT.getOperationalEnvironment")).environment
+		};
 		default: return {
 			ok: false,
 			error: `dev-mode-unsupported: "${methodName}"은 dev-mode에서 직접 호출할 수 없습니다. CDP bridge(window.__sdkCall)가 없으므로 실제 SDK 호출은 \`--mode=local\` 또는 debug 모드에서만 가능합니다. 지원 메서드: getOperationalEnvironment (mock state에서 읽음).`
@@ -4658,7 +4752,7 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.49"
+		version: "0.1.51"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {