@ait-co/devtools 0.1.108 → 0.1.110

package/README.en.md

@@ -60,31 +60,16 @@ Load a dog-food bundle in the real Toss app WebView and debug it via the MCP rel
 ```bash
 devtools-mcp              # start MCP server → QR printed in terminal
 # ait build && ait deploy --scheme-only
-# call build_attach_url → scan QR → Toss app loads bundle + relay attaches
+# one start_attach(scheme_url) call generates the QR and waits for the phone to attach — scan it and the Toss app loads the bundle + relay attaches
 ```
 
 No HMR (Toss WebView cold-load only). Details: [`docs/scenarios/env-3.md`](./docs/scenarios/env-3.md)
 
 ---
 
-**Environment 4 — Live deployed app** (passed review, HMR off, read-only debug)
-
-Attach a relay to a live OPENED app to observe runtime behavior.
-
-```bash
-devtools-mcp   # start MCP server
-# In Claude Code: start_debug({mode: 'relay-live', confirm: true})  ← arms LIVE guard
-# call build_attach_url → scan QR → live app loads + relay attaches
-# call_sdk / evaluate: confirm: true required (LIVE guard — real users affected)
-```
-
-`start_debug({mode: 'relay-live', confirm: true})` arms the LIVE guard in-session. Details: [`docs/scenarios/env-4.md`](./docs/scenarios/env-4.md)
-
----
-
 ## On-device debugging in one line
 
-To enable on-device CDP debugging in environments 2, 3, and 4, add **one line** to your mini-app entry (`main.tsx` or equivalent):
+To enable on-device CDP debugging in environments 2 and 3, add **one line** to your mini-app entry (`main.tsx` or equivalent):
 
 ```ts
 // main.tsx (or the top of your mini-app entry)
@@ -106,11 +91,11 @@ For environments 3 and 4 (intoss-private relay), the relay QR deep-link carries
 
 **"QR window doesn't open"**
 
-Either `build_attach_url` wasn't called first, or the MCP server is running in a headless environment where no browser can be opened. The tool result always includes a text QR — scan it directly with your phone camera. On a local GUI machine, the dashboard opens automatically in the browser.
+Either `start_attach` wasn't called first, or the MCP server is running in a headless environment where no browser can be opened. The tool result always includes a text QR — scan it directly with your phone camera. On a local GUI machine, the dashboard opens automatically in the browser.
 
 **"Page not attached" — list_pages returns an empty array**
 
-No page has joined the relay yet. Re-enter via `build_attach_url` → QR scan on your phone. When the MCP error message reads "page not attached — run build_attach_url then scan QR", this is the case.
+No page has joined the relay yet. Re-enter via `start_attach` → QR scan on your phone. When the MCP error message reads "page not attached — run start_attach then scan QR", this is the case.
 
 **"Tunnel down" — no response or timeout**
 
@@ -118,7 +103,7 @@ A cloudflared quick tunnel can drop after a few hours. Restart the `devtools-mcp
 
 **"Page crash" — list_pages shows a non-null crashDetectedAt**
 
-The page on the phone died (OOM, JS exception, or native bridge crash). Relaunch the app, then re-attach via `build_attach_url` → QR scan. (Related: [#265](https://github.com/apps-in-toss-community/devtools/issues/265))
+The page on the phone died (OOM, JS exception, or native bridge crash). Relaunch the app, then re-attach via `start_attach` → QR scan. (Related: [#265](https://github.com/apps-in-toss-community/devtools/issues/265))
 
 **"SDK not available" — window.__sdkCall not injected**
 
@@ -126,7 +111,7 @@ When `call_sdk` returns `ok: false, error: "window.__sdkCall is not available"`,
 
 **"QR scanned but auth rejected" — TOTP code expired**
 
-When `AIT_DEBUG_TOTP_SECRET` is set, `build_attach_url` automatically splices the current one-time TOTP code (`at=`) into the returned `attachUrl`. Each code covers a 30-second step, and the relay accepts ±6 steps (~3 min) of backwards skew. Scanning more than ~3 minutes after `totp.expiresAt` causes the relay to reject the request. Fix: call `build_attach_url` again to get a fresh URL and QR.
+When `AIT_DEBUG_TOTP_SECRET` is set, `start_attach` automatically splices the current one-time TOTP code (`at=`) into the returned `attachUrl`. Each code covers a 30-second step, and the relay accepts ±6 steps (~3 min) of backwards skew. While waiting for the phone to attach, `start_attach` re-mints the code in-call as it nears its expiry window (the re-mint count is surfaced as `totp.reminted`), so you usually do not need to re-call during the wait. If you do scan an expired QR and the relay rejects it, call `start_attach` again to get a fresh URL and QR.
 
 ---
 
@@ -979,15 +964,14 @@ A local browser (env 1) and a phone Toss WebView (env 2/3) both speak CDP, so ev
 |---|---|---|---|---|
 | `--target=mobile` (env 2) | `devtools-mcp` → `start_debug({mode:'relay-sandbox'})` | `AIT_RELAY_BASE_URL`, `AIT_TUNNEL_BASE_URL` | Real-device Safari/WebKit PWA (external Chii relay + cloudflared tunnel, env 2) | console/network/page + DOM/snapshot/screenshot |
 | `--mode=debug --target=relay` (default, env 3) | `devtools-mcp` → `start_debug({mode: 'relay-staging'})` | — | Dog-food bundle on a phone (CDP/Chii relay + cloudflared tunnel, env 3) | same + `AIT.*` |
-| `--mode=debug --target=relay` LIVE (env 4) | `devtools-mcp` → `start_debug({mode: 'relay-live', confirm: true})` | — (env 4 LIVE guard) | Live deployed app (env 4) — `call_sdk`/`evaluate` require `confirm: true` | same |
 | `--mode=debug --target=local` (env 1) | `devtools-mcp --target=local` | `MCP_ENV=mock` (auto) | Local Chromium launched by the MCP server (CDP direct-attach, no relay needed, env 1) | same |
 | `--mode=dev` | `devtools-mcp --mode=dev` | `MCP_ENV=mock` (auto) | Mock state from a running Vite dev server (AIT.* only, no CDP) | `AIT.*` (+ `devtools_get_mock_state` alias) |
 
-`--target=local` opens `AIT_DEVTOOLS_URL` (default `http://localhost:5173`) and attaches directly to a local Chromium — no relay or tunnel required. `--mode=dev` reads the mock-state HTTP endpoint of the Vite dev server and does not provide CDP tools. Switch environments in-session with `start_debug(mode)`: `relay-sandbox` (env 2 PWA), `relay-staging` (env 3 dogfood), `relay-live` (env 4, arms LIVE guard — `confirm: true` required), `local-browser` (env 1).
+`--target=local` opens `AIT_DEVTOOLS_URL` (default `http://localhost:5173`) and attaches directly to a local Chromium — no relay or tunnel required. `--mode=dev` reads the mock-state HTTP endpoint of the Vite dev server and does not provide CDP tools. Switch environments in-session with `start_debug(mode)`: `relay-sandbox` (env 2 PWA), `relay-staging` (env 3 dogfood), `local-browser` (env 1).
 
 #### Environment 2 (real-device PWA CDP) — `--target=mobile`
 
-Debug on a real phone using Safari/WebKit without Toss review. The Vite dev server with [`tunnel:{cdp:true}`](#tunnel-option) brings up both an app HTTP tunnel and a Chii relay tunnel. The MCP server attaches to that relay and provides `build_attach_url` → launcher QR.
+Debug on a real phone using Safari/WebKit without Toss review. The Vite dev server with [`tunnel:{cdp:true}`](#tunnel-option) brings up both an app HTTP tunnel and a Chii relay tunnel. The MCP server attaches to that relay and provides `start_attach` → launcher QR.
 
 **Setup procedure:**
 
@@ -1018,7 +1002,7 @@ Debug on a real phone using Safari/WebKit without Toss review. The Vite dev serv
 3. In a Claude Code session:
    ```
    start_debug({mode: 'relay-sandbox'})
-   build_attach_url()
+   start_attach()
    ```
    Scan the QR with your phone camera. The launcher PWA opens the app in a frame and injects Chii target.js.
 
@@ -1032,7 +1016,7 @@ Debug on a real phone using Safari/WebKit without Toss review. The Vite dev serv
 
 For a step-by-step walkthrough of the on-device relay debug loop (dog-food build → QR scan → relay attach) including common failure recovery, see **[`docs/dogfood-relay-loop.md`](./docs/dogfood-relay-loop.md)** (Korean). For crash triage — `list_pages.crashDetectedAt`, iOS Console.app `.ips` analysis, and the redact procedure — see **[`docs/crash-triage.md`](./docs/crash-triage.md)** (Korean).
 
-Read-only tools only. Tools are registered in two tiers based on attach state — before attach, only the bootstrap tools (`build_attach_url`, `list_pages`) are visible; once a relay/local page attaches, the attach-dependent tools are registered dynamically in the same session via `notifications/tools/list_changed` (no session restart needed). The phone attach roundtrip is fully wired; all that remains is a single on-device acceptance run. The tool layer is CI-verified via a mockable injectable CDP connection / AIT source.
+Read-only tools only. Tools are registered in two tiers based on attach state — before attach, only the bootstrap tools (`start_attach`, `list_pages`) are visible; once a relay/local page attaches, the attach-dependent tools are registered dynamically in the same session via `notifications/tools/list_changed` (no session restart needed). The phone attach roundtrip is fully wired; all that remains is a single on-device acceptance run. The tool layer is CI-verified via a mockable injectable CDP connection / AIT source.
 
 Running `devtools-mcp` as a stdio server starts a local Chii relay on an OS-assigned port and opens a cloudflared quick tunnel, printing a public `wss://*.trycloudflare.com` URL and a QR code in the terminal (secrets/auth codes are never printed). When the phone enters the dog-food entry point, the in-app attach UI connects to the relay with that URL, and the agent reads console/network/page state via `chrome-devtools-mcp`-compatible tools — diagnosing regressions without anyone watching the phone.
 
@@ -1050,22 +1034,20 @@ Environments 3 and 4 (intoss-private relay) — start `devtools-mcp` as-is, then
 ```
 
 - Environment 3 (dog-food relay): `start_debug({mode: 'relay-staging'})`
-- Environment 4 (LIVE relay, LIVE guard enabled): `start_debug({mode: 'relay-live', confirm: true})`
-
-**`start_debug(mode)` is the single in-session entry path.** `MCP_ENV=relay-live` remains only as a deprecated alias that seeds `liveIntent` at boot — in a new session, enter via `start_debug({mode: 'relay-live', confirm: true})`.
+**`start_debug(mode)` is the single in-session entry path.**
 
 | Tool | CDP / AIT backing | Description |
 |---|---|---|
 | `list_console_messages` | `Runtime.consoleAPICalled` | Recent console.log/warn/error messages (level, text, timestamp, args) |
 | `list_network_requests` | `Network.requestWillBeSent` + `responseReceived` | Recent XHR/fetch requests (url, method, status, timing) |
 | `list_pages` | Chii relay target list | Attached pages + tunnel status + wss URL |
-| `build_attach_url` | (pure synthesis) | Splices `debug=1` + the relay URL into an `ait deploy --scheme-only` URL, prints a QR. Scanning the QR with the phone camera is the single entry path for env 2/3 (requires `list_pages` first) |
+| `start_attach` | (pure synthesis + attach wait) | Splices `debug=1` + the relay URL into an `ait deploy --scheme-only` URL, prints a QR, then waits in the same call until the phone attaches (QR generation and attach in one call). A `mode` arg can switch the session environment too, and the TOTP code is re-minted automatically during the wait. Entry tool for env 2 and 3 (bootstrap) — no `list_pages` needed first |
 | `get_dom_document` | `DOM.getDocument` | DOM tree read (structural/layout regression diagnosis) |
 | `take_snapshot` | `DOMSnapshot.captureSnapshot` | Page snapshot (documents + interned strings, visual regression) |
 | `take_screenshot` | `Page.captureScreenshot` | Page PNG screenshot (returned as an MCP image content block) |
 | `measure_safe_area` | `Runtime.evaluate` | Runs a safe-area probe on the attached page → returns normalized safe-area insets, viewport geometry, DPR, and User-Agent. Read-only. Use in a relay session to get ground-truth values for upgrading a viewport preset from extrapolated/placeholder to measured. Requires attach (`list_pages` first) |
 | `evaluate` | `Runtime.evaluate` | Evaluates an arbitrary JS expression on the attached page (returnByValue) and returns the result. **Not read-only** — the expression can have side effects (DOM mutations, SDK calls, state changes). Requires attach |
-| `call_sdk` | `window.__sdkCall` bridge (via `Runtime.evaluate`) | Calls a dog-food SDK method via the `window.__sdkCall` bridge (exported by `@apps-in-toss/web-framework` in `__DEBUG_BUILD__` bundles only). **Not read-only** — SDK calls have side effects (navigation, payments, permissions, etc.). Hits the real SDK on env 3/4, mock SDK on env 1. Env 2 (PWA) does not inject the SDK — not available there. On env 4, `confirm: true` is required (LIVE guard). Requires attach. Returns `{ok,value}` / `{ok,error}` |
+| `call_sdk` | `window.__sdkCall` bridge (via `Runtime.evaluate`) | Calls a dog-food SDK method via the `window.__sdkCall` bridge (exported by `@apps-in-toss/web-framework` in `__DEBUG_BUILD__` bundles only). **Not read-only** — SDK calls have side effects (navigation, payments, permissions, etc.). Hits the real SDK on env 3, mock SDK on env 1. Env 2 (PWA) does not inject the SDK — not available there. Requires attach. Returns `{ok,value}` / `{ok,error}` |
 | `AIT.getSdkCallHistory` | AIT domain | SDK call trace (method, args, result/error, timestamp) |
 | `AIT.getMockState` | AIT domain | Mock state snapshot (`window.__ait`) |
 | `AIT.getOperationalEnvironment` | AIT domain | `getOperationalEnvironment()` + SDK version |

package/README.md

@@ -60,31 +60,16 @@ pnpm dev:phone          # AIT_TUNNEL=1 pnpm dev 와 동일
 ```bash
 devtools-mcp              # MCP 서버 시작 → QR 출력
 # ait build && ait deploy --scheme-only
-# build_attach_url 호출 → QR 스캔 → 토스 앱 로드 + relay attach
+# start_attach(scheme_url) 호출 한 번으로 QR 생성 + 폰 attach까지 — QR 스캔하면 토스 앱 로드 + relay attach
 ```
 
 HMR 없음(토스 WebView cold-load만). 상세: [`docs/scenarios/env-3.md`](./docs/scenarios/env-3.md)
 
 ---
 
-**환경 4 — 배포된 앱 (LIVE)** (검수 통과 앱, HMR X, read-only debug)
-
-검수를 통과하고 OPENED 상태인 실 출시 앱에 relay를 붙여 런타임을 관측합니다.
-
-```bash
-devtools-mcp   # MCP 서버 시작
-# Claude Code에서: start_debug({mode: 'relay-live', confirm: true})  ← LIVE guard 활성화
-# build_attach_url 호출 → QR 스캔 → LIVE 앱 로드 + relay attach
-# call_sdk / evaluate 는 confirm: true 필수 (LIVE guard — 실유저 영향)
-```
-
-`start_debug({mode: 'relay-live', confirm: true})`가 LIVE guard를 활성화합니다. 상세: [`docs/scenarios/env-4.md`](./docs/scenarios/env-4.md)
-
----
-
 ## on-device 디버깅 한 줄 설정
 
-환경 2·3·4에서 on-device CDP 디버깅을 활성화하려면 미니앱 entry(`main.tsx` 등)에 **한 줄**을 추가하세요:
+환경 2·3에서 on-device CDP 디버깅을 활성화하려면 미니앱 entry(`main.tsx` 등)에 **한 줄**을 추가하세요:
 
 ```ts
 // main.tsx (또는 미니앱 entry 최상단)
@@ -106,11 +91,11 @@ import '@ait-co/devtools/in-app/auto';
 
 **"QR 창이 안 열림"**
 
-`build_attach_url`을 먼저 호출하지 않았거나, GUI 없는 headless 환경이라 대시보드를 열 수 없는 경우입니다. 도구 결과에 텍스트 QR이 출력되므로 폰 카메라로 직접 스캔하세요. 로컬 GUI 환경에서는 대시보드가 자동으로 브라우저에 열립니다.
+`start_attach`을 먼저 호출하지 않았거나, GUI 없는 headless 환경이라 대시보드를 열 수 없는 경우입니다. 도구 결과에 텍스트 QR이 출력되므로 폰 카메라로 직접 스캔하세요. 로컬 GUI 환경에서는 대시보드가 자동으로 브라우저에 열립니다.
 
 **"page 미attach" — list_pages가 빈 배열 반환**
 
-relay에 붙은 페이지가 없는 상태입니다. `build_attach_url` → QR 스캔 순서로 폰을 다시 진입시키세요. MCP 에러 메시지가 "페이지가 attach 안 됨. build_attach_url → QR 스캔."으로 뜨면 이 케이스입니다.
+relay에 붙은 페이지가 없는 상태입니다. `start_attach` → QR 스캔 순서로 폰을 다시 진입시키세요. MCP 에러 메시지가 "페이지가 attach 안 됨. start_attach → QR 스캔."으로 뜨면 이 케이스입니다.
 
 **"tunnel down" — 터널 응답 없음 또는 timeout**
 
@@ -118,7 +103,7 @@ cloudflared quick tunnel은 수 시간 후 drop될 수 있습니다. `devtools-m
 
 **"page crash" — list_pages에 crashDetectedAt이 찍힘**
 
-폰 측 페이지가 OOM·JS exception·native bridge crash로 죽은 상태입니다. 앱을 재실행 후 `build_attach_url` → QR 스캔으로 다시 attach하세요. (관련: [#265](https://github.com/apps-in-toss-community/devtools/issues/265))
+폰 측 페이지가 OOM·JS exception·native bridge crash로 죽은 상태입니다. 앱을 재실행 후 `start_attach` → QR 스캔으로 다시 attach하세요. (관련: [#265](https://github.com/apps-in-toss-community/devtools/issues/265))
 
 **"SDK 부재" — window.__sdkCall 미주입**
 
@@ -126,7 +111,7 @@ cloudflared quick tunnel은 수 시간 후 drop될 수 있습니다. `devtools-m
 
 **"QR 스캔했는데 인증 실패" — TOTP 만료**
 
-`AIT_DEBUG_TOTP_SECRET` 설정 시 `build_attach_url`이 반환하는 attachUrl에는 TOTP 코드(`at=`)가 자동으로 포함됩니다. 코드 1개는 30초 창이고, relay는 만료 후 ~3분(±6 step) 이내 소급을 허용합니다. 응답의 `totp.expiresAt`로부터 ~3분 이상 지난 뒤 스캔하면 relay가 인증을 거부합니다. 해결: `build_attach_url`을 재호출해 새 URL과 QR을 발급받으세요.
+`AIT_DEBUG_TOTP_SECRET` 설정 시 `start_attach`이 반환하는 attachUrl에는 TOTP 코드(`at=`)가 자동으로 포함됩니다. 코드 1개는 30초 창이고, relay는 만료 후 ~3분(±6 step) 이내 소급을 허용합니다. `start_attach`은 attach를 기다리는 동안 코드가 만료 창에 가까워지면 호출 안에서 코드를 자동 재발행하므로(재발행 횟수는 응답의 `totp.reminted`로 노출), 대기 중에는 보통 재호출이 필요 없습니다. 그래도 만료된 QR을 스캔해 relay가 인증을 거부하면 `start_attach`을 재호출해 새 URL과 QR을 발급받으세요.
 
 ---
 
@@ -1009,15 +994,14 @@ AI 코딩 에이전트(Claude Code, Cursor 등)가 [MCP(Model Context Protocol)]
 |---|---|---|---|---|
 | `--target=mobile` (env 2) | `devtools-mcp` → `start_debug({mode:'relay-sandbox'})` | `AIT_RELAY_BASE_URL`, `AIT_TUNNEL_BASE_URL` | 실기기 Safari/WebKit PWA (외부 Chii relay + cloudflared 터널, 환경 2) | console/network/page + DOM/snapshot/screenshot |
 | `--mode=debug --target=relay` (기본값, env 3) | `devtools-mcp` → `start_debug({mode: 'relay-staging'})` | — | 폰 안 dog-food 번들 (CDP/Chii relay + cloudflared 터널, 환경 3) | 동일 + `AIT.*` |
-| `--mode=debug --target=relay` LIVE (env 4) | `devtools-mcp` → `start_debug({mode: 'relay-live', confirm: true})` | — (**환경 4 LIVE guard**) | LIVE 배포 앱 (환경 4) — `call_sdk`/`evaluate`에 `confirm: true` 필요 | 동일 |
 | `--mode=debug --target=local` (env 1) | `devtools-mcp --target=local` | `MCP_ENV=mock` (자동) | MCP가 직접 기동한 로컬 Chromium (CDP direct-attach, relay 불필요, 환경 1) | 동일 |
 | `--mode=dev` | `devtools-mcp --mode=dev` | `MCP_ENV=mock` (자동) | 실행 중인 Vite dev server의 mock state (AIT.* 전용, CDP 없음) | `AIT.*` (+ `devtools_get_mock_state` alias) |
 
-`--target=local`은 `AIT_DEVTOOLS_URL`(기본 `http://localhost:5173`)을 열고 로컬 Chromium에 CDP direct-attach합니다 — relay나 터널이 필요하지 않습니다. `--mode=dev`는 Vite dev server의 mock-state HTTP endpoint를 읽으며 CDP tool은 제공하지 않습니다. 세션 내 환경 전환은 `start_debug(mode)` 한 번으로 처리됩니다: `relay-sandbox`(env 2 PWA), `relay-staging`(env 3 dogfood), `relay-live`(env 4 LIVE guard 활성화, `confirm: true` 필수), `local-browser`(env 1).
+`--target=local`은 `AIT_DEVTOOLS_URL`(기본 `http://localhost:5173`)을 열고 로컬 Chromium에 CDP direct-attach합니다 — relay나 터널이 필요하지 않습니다. `--mode=dev`는 Vite dev server의 mock-state HTTP endpoint를 읽으며 CDP tool은 제공하지 않습니다. 세션 내 환경 전환은 `start_debug(mode)` 한 번으로 처리됩니다: `relay-sandbox`(env 2 PWA), `relay-staging`(env 3 dogfood), `local-browser`(env 1).
 
 #### 환경 2 (실기기 PWA CDP) — `--target=mobile`
 
-토스 검수 없이 실기기 WebKit 엔진에서 CDP 디버깅이 가능한 모드입니다. [`tunnel:{cdp:true}`](#tunnel-옵션)를 켠 Vite dev server가 앱 HTTP 터널과 Chii relay 터널을 두 개 띄우고, MCP는 그 relay에 붙어 `build_attach_url` → launcher QR을 제공합니다.
+토스 검수 없이 실기기 WebKit 엔진에서 CDP 디버깅이 가능한 모드입니다. [`tunnel:{cdp:true}`](#tunnel-옵션)를 켠 Vite dev server가 앱 HTTP 터널과 Chii relay 터널을 두 개 띄우고, MCP는 그 relay에 붙어 `start_attach` → launcher QR을 제공합니다.
 
 **진입 절차:**
 
@@ -1048,7 +1032,7 @@ AI 코딩 에이전트(Claude Code, Cursor 등)가 [MCP(Model Context Protocol)]
 3. Claude Code 세션에서 진입:
    ```
    start_debug({mode: 'relay-sandbox'})
-   build_attach_url()
+   start_attach()
    ```
    QR을 폰 카메라로 스캔하면 launcher PWA가 앱을 프레임에 열고 Chii target.js를 주입합니다.
 
@@ -1063,7 +1047,7 @@ AI 코딩 에이전트(Claude Code, Cursor 등)가 [MCP(Model Context Protocol)]
 실기기 relay 디버깅 루프(dog-food 빌드 → QR 스캔 → relay attach)의 단계별 절차와 복구 방법은 **[`docs/dogfood-relay-loop.md`](./docs/dogfood-relay-loop.md)** 를 참고하세요. crash가 발생한 경우 — `list_pages.crashDetectedAt`, iOS Console.app `.ips` 분석, redact 절차를 포함한 원인 추적 절차는 **[`docs/crash-triage.md`](./docs/crash-triage.md)** 를 참고하세요.
 
 read-only tool만 노출합니다. 도구는 attach 상태에 따라 2단계로 등록됩니다 — attach 전에는 bootstrap
-도구(`build_attach_url`·`list_pages`)만 보이고, 릴레이/로컬 페이지가 attach되면 `notifications/tools/list_changed`로
+도구(`start_attach`·`list_pages`)만 보이고, 릴레이/로컬 페이지가 attach되면 `notifications/tools/list_changed`로
 attach 의존 도구가 같은 세션에서 동적 등록됩니다(세션 재시작 불필요). 폰 attach 라운드트립은 fully wired
 상태이며 남은 것은 실기기 acceptance 한 번뿐입니다. tool 계층은 주입 가능한 CDP 연결 / AIT 소스를 mock해
 CI에서 검증됩니다.
@@ -1088,22 +1072,20 @@ tunnel로 공개 `wss://*.trycloudflare.com` URL을 발급한 뒤 QR을 터미
 ```
 
 - 환경 3 (dog-food relay): `start_debug({mode: 'relay-staging'})`
-- 환경 4 (LIVE relay, LIVE guard 활성화): `start_debug({mode: 'relay-live', confirm: true})`
-
-**세션 내 환경 전환은 `start_debug(mode)`가 단일 진입 경로**입니다. `MCP_ENV=relay-live`는 부팅 시 `liveIntent`를 미리 시드하는 deprecated 별칭으로만 남아 있습니다 — 새 세션에서는 `start_debug({mode: 'relay-live', confirm: true})`로 진입하세요.
+**세션 내 환경 전환은 `start_debug(mode)`가 단일 진입 경로**입니다.
 
 | Tool | CDP / AIT 백킹 | 설명 |
 |---|---|---|
 | `list_console_messages` | `Runtime.consoleAPICalled` | 최근 console.log/warn/error 메시지 (level, text, timestamp, args) |
 | `list_network_requests` | `Network.requestWillBeSent` + `responseReceived` | 최근 XHR/fetch 요청 (url, method, status, timing) |
 | `list_pages` | Chii 릴레이 target 목록 | attach된 페이지 + tunnel 상태 + wss URL |
-| `build_attach_url` | (순수 합성) | `ait deploy --scheme-only` URL에 `debug=1`+릴레이 URL을 끼워 self-attach deep-link 합성 → QR을 터미널 출력. QR을 폰 카메라로 스캔하는 것이 환경 2·3의 단일 진입 경로 (`list_pages` 먼저 필요) |
+| `start_attach` | (순수 합성 + attach 대기) | `ait deploy --scheme-only` URL에 `debug=1`+릴레이 URL을 끼워 self-attach deep-link를 합성하고 QR을 출력한 뒤, 폰이 attach될 때까지 같은 호출 안에서 대기한다(QR 생성·attach가 한 호출). `mode`로 세션 환경을 함께 전환할 수 있고, 대기 중 TOTP 코드를 자동 재발행한다. 환경 2·3 진입 도구(bootstrap) — `list_pages` 선행 불필요 |
 | `get_dom_document` | `DOM.getDocument` | DOM 트리 read (구조/레이아웃 회귀 진단) |
 | `take_snapshot` | `DOMSnapshot.captureSnapshot` | 페이지 스냅샷 (documents + interned strings, 시각 회귀 진단) |
 | `take_screenshot` | `Page.captureScreenshot` | 페이지 PNG 스크린샷 (MCP image content block 반환) |
 | `measure_safe_area` | `Runtime.evaluate` | attach된 페이지에서 safe-area 프로브 실행 → 정규화된 safe-area inset·뷰포트 geometry·DPR·User-Agent 반환. read-only. relay 세션(폰 attach)에서 viewport preset을 extrapolated/placeholder→measured로 승급할 ground truth 수집용. attach 필요 (`list_pages` 먼저) |
 | `evaluate` | `Runtime.evaluate` | attach된 페이지에서 임의 JS 표현식 평가(returnByValue) → 결과 반환. **read-only 아님** — 표현식이 부작용(DOM 변경·SDK 호출·상태 변경)을 일으킬 수 있음. attach 필요 |
-| `call_sdk` | `window.__sdkCall` 브리지 (`Runtime.evaluate` 경유) | dog-food SDK 메서드를 `window.__sdkCall` 브리지로 호출 (`@apps-in-toss/web-framework`가 `__DEBUG_BUILD__` 번들에서만 export). **read-only 아님** — SDK 호출은 부작용(내비게이션·결제·권한 등). 환경 3·4(실기기 relay)에선 실 SDK, 환경 1(로컬 mock)에선 mock SDK. 환경 2(PWA)는 SDK 미주입으로 사용 불가. 환경 4에서는 `confirm: true` 필수(LIVE guard). attach 필요. `{ok,value}` / `{ok,error}` 반환 |
+| `call_sdk` | `window.__sdkCall` 브리지 (`Runtime.evaluate` 경유) | dog-food SDK 메서드를 `window.__sdkCall` 브리지로 호출 (`@apps-in-toss/web-framework`가 `__DEBUG_BUILD__` 번들에서만 export). **read-only 아님** — SDK 호출은 부작용(내비게이션·결제·권한 등). 환경 3(실기기 relay)에선 실 SDK, 환경 1(로컬 mock)에선 mock SDK. 환경 2(PWA)는 SDK 미주입으로 사용 불가. attach 필요. `{ok,value}` / `{ok,error}` 반환 |
 | `AIT.getSdkCallHistory` | AIT 도메인 | SDK 호출 trace (method, args, result/error, timestamp) |
 | `AIT.getMockState` | AIT 도메인 | mock state 스냅샷 (`window.__ait`) |
 | `AIT.getOperationalEnvironment` | AIT 도메인 | `getOperationalEnvironment()` + SDK 버전 |

package/dist/bundle-KFs4t-wc.d.ts

@@ -0,0 +1,96 @@
+//#region src/test-runner/bundle.d.ts
+/**
+ * esbuild-based bundler for user test files.
+ *
+ * Bundles a single test file into a self-contained IIFE string that can be
+ * injected into a WebView via `Runtime.evaluate`. The bundle includes the
+ * test runtime (`runtime.ts`), which provides `describe/it/test/expect` and
+ * the `runTestModule(factory)` entry point.
+ *
+ * ## How the wiring works
+ *
+ * The bundle exposes two exports on `globalThis.__testBundle`:
+ *   - `runTestModule` — the runtime's entry function.
+ *   - `__userFactory`  — an async function whose body is the user's top-level
+ *     test registration code (describe/it/test calls).
+ *
+ * The Node-side RPC (`rpc.ts`) calls:
+ *   `globalThis.__testBundle.runTestModule(globalThis.__testBundle.__userFactory)`
+ *
+ * `runTestModule` then installs `describe/it/test/expect` as globals, invokes
+ * the factory (which registers all tests), runs them, and returns a `RunReport`.
+ *
+ * ## Why a factory wrapper is needed
+ *
+ * Naively adding the runtime to `entryPoints` and bundling the user file would
+ * fail for two reasons:
+ *   1. `describe/it/test/expect` from the runtime are module-local in the IIFE
+ *      scope. The user's top-level `describe(...)` calls expect them as globals —
+ *      they are not globals until `runTestModule` installs them.
+ *   2. Even with globals pre-installed, the user file runs at IIFE-evaluation
+ *      time, before the RPC layer calls `runTestModule` to reset state and start
+ *      the test clock.
+ *
+ * The factory approach solves both: the user's registration code is deferred
+ * into a function that `runTestModule` calls AFTER installing the globals.
+ *
+ * ## Factory extraction algorithm
+ *
+ * The `userFactoryPlugin` reads the user file and splits lines into:
+ *   - **top-level**: `import …` and re-export lines — kept at module scope
+ *     (the only valid position for static `import` in ESM).
+ *   - **body**: all other statements — moved into the body of the exported
+ *     `__userFactory` async function.
+ *
+ * esbuild processes the re-generated module, following each static import
+ * through the normal dependency graph (including the SDK-redirect plugin).
+ *
+ * ## SDK redirect
+ *
+ * Imports of `@apps-in-toss/web-framework` (and sub-paths) are intercepted via
+ * the `sdkRedirectPlugin` and replaced with a virtual `window.__sdk` proxy that
+ * `src/in-app/auto.ts` installs at runtime. This works for both 2.x and 3.x SDK.
+ *
+ * SECRET-HANDLING: the returned bundle code is caller-managed; never log it.
+ */
+/** Options accepted by `bundleTestFile`. */
+interface BundleOptions {
+  /**
+   * Additional esbuild `external` patterns. The SDK package
+   * (`@apps-in-toss/web-framework` and `@apps-in-toss/web-framework/*`) is
+   * always handled by the SDK redirect plugin — callers may add more patterns
+   * to be left as globals.
+   */
+  extraExternals?: string[];
+  /**
+   * Global name for the IIFE output object. Defaults to `__testBundle`.
+   * The runtime entry uses this to call `__testBundle.runTestModule(__userFactory)`.
+   */
+  globalName?: string;
+}
+/**
+ * The result of bundling a test file.
+ * `code` is a self-contained IIFE string ready for `Runtime.evaluate`.
+ */
+interface BundleResult {
+  code: string;
+  warnings: string[];
+}
+/**
+ * Bundles `absPath` into a single IIFE string suitable for `Runtime.evaluate`.
+ *
+ * The IIFE installs `window.__testBundle` (or the custom `globalName`) with:
+ *   - `runTestModule` — the runtime entry (from `runtime.ts`).
+ *   - `__userFactory` — an async function wrapping the user's test registration
+ *     code so it runs AFTER `runTestModule` installs the globals.
+ *
+ * Callers (rpc.ts) invoke:
+ *   `globalThis.__testBundle.runTestModule(globalThis.__testBundle.__userFactory)`
+ *
+ * @param absPath - Absolute path to the user test file.
+ * @param opts    - Optional bundling overrides.
+ */
+declare function bundleTestFile(absPath: string, opts?: BundleOptions): Promise<BundleResult>;
+//#endregion
+export { BundleResult as n, bundleTestFile as r, BundleOptions as t };
+//# sourceMappingURL=bundle-KFs4t-wc.d.ts.map

package/dist/bundle-KFs4t-wc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle-KFs4t-wc.d.ts","names":[],"sources":["../src/test-runner/bundle.ts"],"mappings":";;AAqEA;;;;;AAmBA;;;;;AA2LA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA9MiB,aAAA;;;;;;;EAOf,cAAA;;;;;EAKA,UAAA;AAAA;;;;;UAOe,YAAA;EACf,IAAA;EACA,QAAA;AAAA;;;;;;;;;;;;;;;iBAyLoB,cAAA,CAAe,OAAA,UAAiB,IAAA,GAAO,aAAA,GAAgB,OAAA,CAAQ,YAAA"}

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

@@ -1 +1 @@
-{"version":3,"file":"auto.d.ts","names":[],"sources":["../../src/in-app/auto.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;AA6IA;;;;;AAkCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAhGQ,MAAA;EAAA,UACI,MAAA;;;;;;;;;;IAUR,KAAA,GAAQ,MAAA;;;;;;;;;IAUR,SAAA,IACE,IAAA,aACG,IAAA,gBACA,OAAA;MAAU,EAAA;MAAa,KAAA;MAAiB,KAAA;IAAA;EAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;iBAsCjC,eAAA,CAAA;;;;;;;;;;;;;;iBAkCA,cAAA,CACd,KAAA,YACA,SAAA"}
+{"version":3,"file":"auto.d.ts","names":[],"sources":["../../src/in-app/auto.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;AA8IA;;;;;AAkCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAhGQ,MAAA;EAAA,UACI,MAAA;;;;;;;;;;IAUR,KAAA,GAAQ,MAAA;;;;;;;;;IAUR,SAAA,IACE,IAAA,aACG,IAAA,gBACA,OAAA;MAAU,EAAA;MAAa,KAAA;MAAiB,KAAA;IAAA;EAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;iBAsCjC,eAAA,CAAA;;;;;;;;;;;;;;iBAkCA,cAAA,CACd,KAAA,YACA,SAAA"}

package/dist/in-app/auto.js

@@ -151,6 +151,42 @@ function isTrycloudflareHost(hostname) {
 	return hostname.endsWith(TRYCLOUDFLARE_HOST_SUFFIX);
 }
 /**
+* Returns true when the hostname is a localhost/loopback address.
+* Allowed: `localhost`, `127.x.x.x` (full RFC 5735 loopback block), `[::1]`,
+* `0.0.0.0`, `*.localhost`.
+*
+* Security note: `hostname.startsWith('127.')` is intentionally NOT used —
+* that pattern would accept `127.evil.com`, which starts with "127." but is an
+* attacker-controlled hostname, not a loopback address. Instead, the 127/8
+* loopback block is matched with a strict numeric-quad regex so only valid
+* dotted-decimal IPv4 in the 127.x.x.x range pass (#665 작업 A fix).
+*/
+function isLocalhostHost(hostname) {
+	if (hostname === "localhost" || hostname === "0.0.0.0") return true;
+	if (hostname === "[::1]") return true;
+	if (/^127\.\d+\.\d+\.\d+$/.test(hostname)) return true;
+	if (hostname.endsWith(".localhost")) return true;
+	return false;
+}
+/**
+* Positive-allowlist kill-switch (#665): returns true when the hostname is a
+* known debug-allowed host. The debug surface is ONLY active on:
+*   - localhost / loopback (env 1 desktop dev)
+*   - *.trycloudflare.com (env 2 PWA tunnel)
+*   - *.private-apps.tossmini.com (env 3 dog-food)
+*
+* Any other host (including apps.tossmini.com — the former env 4 LIVE host)
+* is silently blocked. This is a positive allowlist — unlisted hosts never
+* had debug surface regardless, but this function makes it explicit and
+* auditable in a single place.
+*
+* SECRET-HANDLING: the hostname value MUST NOT be logged or included in any
+* error reason string — only benign labels ('host not in allowlist') are safe.
+*/
+function isDebugAllowedHost(hostname) {
+	return isLocalhostHost(hostname) || isTrycloudflareHost(hostname) || isPrivateAppsHost(hostname);
+}
+/**
 * Pure function that evaluates the runtime debug activation layers (B and C).
 *
 * Has no side effects. The input is explicit. Returns a discriminated union
@@ -173,12 +209,13 @@ function isTrycloudflareHost(hostname) {
 */
 function evaluateDebugGate(input) {
 	const isTunnel = isTrycloudflareHost(input.hostname);
-	if (!isPrivateAppsHost(input.hostname) && !isTunnel) return {
+	const isLocal = isLocalhostHost(input.hostname);
+	if (!isDebugAllowedHost(input.hostname)) return {
 		attach: false,
 		reason: "host"
 	};
 	let deploymentId = "";
-	if (!isTunnel) {
+	if (!isTunnel && !isLocal) {
 		deploymentId = input.searchParams.get("_deploymentId") ?? "";
 		if (deploymentId === "") return {
 			attach: false,
@@ -688,7 +725,7 @@ function shouldActivate(isDev = detectDevSignal(), searchStr = typeof window !==
 	const params = new URLSearchParams(searchStr);
 	return params.get("debug") === "1" || params.has("relay");
 }
-if (!shouldActivate()) {} else {
+if (!shouldActivate()) {} else if (typeof window === "undefined" || !isDebugAllowedHost(window.location.hostname)) {} else {
 	maybeAttach();
 	import("@apps-in-toss/web-framework").then((sdk) => {
 		if (typeof window === "undefined") return;