@ait-co/devtools 0.1.103 → 0.1.105

package/README.en.md

@@ -4,7 +4,7 @@
 
 [![npm](https://img.shields.io/npm/v/@ait-co/devtools)](https://www.npmjs.com/package/@ait-co/devtools) [![license](https://img.shields.io/badge/license-BSD--3--Clause-blue)](./LICENSE)
 
-![@ait-co/devtools — SDK mock + DevTools panel for Apps In Toss mini-apps](./assets/og/image.png)
+![@ait-co/devtools — mock SDK + DevTools panel for Apps in Toss mini-apps](./assets/og/image.png)
 
 A mock library for the `@apps-in-toss/web-framework` SDK. Imports of `@apps-in-toss/webview-bridge` are intercepted by the unplugin too (only the high-level SDK functions are exposed — bridge primitives are not). (2.x packages `@apps-in-toss/web-bridge` and `@apps-in-toss/web-analytics` are supported for back-compat.)
 
@@ -55,7 +55,7 @@ One-time prerequisite: add `https://devtools.aitc.dev/launcher/` to your phone's
 
 **Environment 3 — intoss-private** (Toss WebView, HMR off, debug only)
 
-Load a dogfood bundle in the real Toss app WebView and debug it via the MCP relay.
+Load a dog-food bundle in the real Toss app WebView and debug it via the MCP relay.
 
 ```bash
 devtools-mcp              # start MCP server → QR printed in terminal
@@ -100,7 +100,7 @@ What this single line does:
 
 For environments 3 and 4 (intoss-private relay), the relay QR deep-link carries `?debug=1&relay=<wss>` query params, so this one line is all the wiring you need. Environment 2 (PWA, `tunnel: { cdp: true }`) works the same way.
 
-> For dogfood builds with TOTP authentication, inject `__DEBUG_TOTP_SECRET__` via your build define and use `@ait-co/devtools/in-app` directly with `evaluateDebugGate({ verifyTotpCode })` + `maybeAttach()`. `in-app/auto` does not inject a TOTP verifier, so Layer C3 is disabled.
+> For dog-food builds with TOTP authentication, inject `__DEBUG_TOTP_SECRET__` via your build define and use `@ait-co/devtools/in-app` directly with `evaluateDebugGate({ verifyTotpCode })` + `maybeAttach()`. `in-app/auto` does not inject a TOTP verifier, so Layer C3 is disabled.
 
 ## Five common problems
 
@@ -144,7 +144,7 @@ devtools runs two npm dist-tags off the same code at once. Pick the channel that
 
 | Channel | Install | web-framework peer |
 |---|---|---|
-| **stable** (`latest`, default) | `pnpm add -D @ait-co/devtools` | `>=2.6.0 <2.7.0` (2.x) |
+| **stable** (`latest`, default) | `pnpm add -D @ait-co/devtools` | `>=2.6.0 <3.0.0` (2.x) |
 | **beta** | `pnpm add -D @ait-co/devtools@beta` | `>=3.0.0-beta <4.0.0` (3.0 line) |
 
 - On web-framework **2.x**, the default install (stable) is all you need.
@@ -978,7 +978,7 @@ A local browser (env 1) and a phone Toss WebView (env 2/3) both speak CDP, so ev
 | Mode + target | Invocation | Env vars | Target | Tools |
 |---|---|---|---|---|
 | `--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'})` | — | Dogfood bundle on a phone (CDP/Chii relay + cloudflared tunnel, env 3) | same + `AIT.*` |
+| `--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) |
@@ -1030,11 +1030,11 @@ Debug on a real phone using Safari/WebKit without Toss review. The Vite dev serv
 
 ### Debug mode (CDP via Chii)
 
-For a step-by-step walkthrough of the on-device relay debug loop (dogfood 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).
+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.
 
-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 dogfood 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.
+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.
 
 Environments 3 and 4 (intoss-private relay) — start `devtools-mcp` as-is, then enter via `start_debug(mode)`:
 
@@ -1049,7 +1049,7 @@ Environments 3 and 4 (intoss-private relay) — start `devtools-mcp` as-is, then
 }
 ```
 
-- Environment 3 (dogfood relay): `start_debug({mode: 'relay-staging'})`
+- 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})`.
@@ -1065,7 +1065,7 @@ Environments 3 and 4 (intoss-private relay) — start `devtools-mcp` as-is, then
 | `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 dogfood 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/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}` |
 | `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 |
@@ -1142,7 +1142,7 @@ Returns the full current mock state (permissions, location, auth, network, IAP,
 | `@ait-co/devtools/unplugin` | Bundler plugin (.vite, .webpack, .rspack, .esbuild, .rollup) |
 | `@ait-co/devtools/mcp/server` | Dev-mode MCP stdio server function (Node.js) |
 | `@ait-co/devtools/mcp/cli` | `devtools-mcp` bin entry point (debug / dev mode, Node.js) |
-| `@ait-co/devtools/in-app` | In-app debug attach — runtime gate (layers B/C) + Chii target.js injection. The consumer wraps the import in `if (__DEBUG_BUILD__)` so it is DCE'd from release builds — dogfood builds only |
+| `@ait-co/devtools/in-app` | In-app debug attach — runtime gate (layers B/C) + Chii target.js injection. The consumer wraps the import in `if (__DEBUG_BUILD__)` so it is DCE'd from release builds — dog-food builds only |
 | `@ait-co/devtools/in-app/auto` | Self-gating side-effect entry — a single `import '@ait-co/devtools/in-app/auto'` line wires attach + SDK bridge. Active only when `?debug=1` / `?relay=` are in the URL or it is a DEV build; stays dormant on normal production loads. See the [section above](#on-device-debugging-in-one-line) |
 
 ## License

package/README.md

@@ -4,7 +4,7 @@
 
 [![npm](https://img.shields.io/npm/v/@ait-co/devtools)](https://www.npmjs.com/package/@ait-co/devtools) [![license](https://img.shields.io/badge/license-BSD--3--Clause-blue)](./LICENSE)
 
-![@ait-co/devtools — SDK mock + DevTools panel for Apps In Toss mini-apps](./assets/og/image.png)
+![@ait-co/devtools — mock SDK + DevTools panel for Apps in Toss mini-apps](./assets/og/image.png)
 
 `@apps-in-toss/web-framework` SDK의 mock 라이브러리입니다. `@apps-in-toss/webview-bridge` import도 unplugin이 함께 인터셉트합니다(high-level SDK 함수만 노출 — bridge primitive는 미노출). (2.x의 `@apps-in-toss/web-bridge`, `@apps-in-toss/web-analytics`도 back-compat으로 지원.)
 
@@ -55,7 +55,7 @@ pnpm dev:phone          # AIT_TUNNEL=1 pnpm dev 와 동일
 
 **환경 3 — intoss-private** (토스 WebView, HMR X, debug 전용)
 
-실기기 토스 앱 WebView에서 dogfood 번들을 로드하고 MCP relay로 디버깅합니다.
+실기기 토스 앱 WebView에서 dog-food 번들을 로드하고 MCP relay로 디버깅합니다.
 
 ```bash
 devtools-mcp              # MCP 서버 시작 → QR 출력
@@ -100,7 +100,7 @@ import '@ait-co/devtools/in-app/auto';
 
 환경 3·4(intoss-private relay) 빌드는 relay QR deep-link가 `?debug=1&relay=<wss>` 파라미터를 실어 보내므로, 이 한 줄만 있으면 별도 게이트 코드가 필요 없습니다. 환경 2(PWA, `tunnel: { cdp: true }`)도 동일하게 동작합니다.
 
-> TOTP 인증이 필요한 dogfood 빌드는 빌드 define으로 `__DEBUG_TOTP_SECRET__`을 주입하고 `@ait-co/devtools/in-app`을 직접 import해 `evaluateDebugGate({ verifyTotpCode })` + `maybeAttach()`를 사용하세요. `in-app/auto`는 TOTP verifier를 주입하지 않으므로 C3 레이어가 비활성화됩니다.
+> TOTP 인증이 필요한 dog-food 빌드는 빌드 define으로 `__DEBUG_TOTP_SECRET__`을 주입하고 `@ait-co/devtools/in-app`을 직접 import해 `evaluateDebugGate({ verifyTotpCode })` + `maybeAttach()`를 사용하세요. `in-app/auto`는 TOTP verifier를 주입하지 않으므로 C3 레이어가 비활성화됩니다.
 
 ## 자주 겪는 문제 5가지
 
@@ -144,7 +144,7 @@ devtools는 같은 코드에서 두 개의 npm dist-tag를 동시에 운영합
 
 | 채널 | 설치 | web-framework peer |
 |---|---|---|
-| **stable** (`latest`, 기본) | `pnpm add -D @ait-co/devtools` | `>=2.6.0 <2.7.0` (2.x) |
+| **stable** (`latest`, 기본) | `pnpm add -D @ait-co/devtools` | `>=2.6.0 <3.0.0` (2.x) |
 | **beta** | `pnpm add -D @ait-co/devtools@beta` | `>=3.0.0-beta <4.0.0` (3.0 라인) |
 
 - web-framework **2.x**를 쓰면 위 기본 설치(stable)면 됩니다.
@@ -1008,7 +1008,7 @@ AI 코딩 에이전트(Claude Code, Cursor 등)가 [MCP(Model Context Protocol)]
 | 모드 + 타깃 | 호출 | 환경 변수 | 대상 | tool |
 |---|---|---|---|---|
 | `--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'})` | — | 폰 안 dogfood 번들 (CDP/Chii relay + cloudflared 터널, 환경 3) | 동일 + `AIT.*` |
+| `--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) |
@@ -1060,7 +1060,7 @@ AI 코딩 에이전트(Claude Code, Cursor 등)가 [MCP(Model Context Protocol)]
 
 ### Debug 모드 (CDP via Chii)
 
-실기기 relay 디버깅 루프(dogfood 빌드 → 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)** 를 참고하세요.
+실기기 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`로
@@ -1070,7 +1070,7 @@ CI에서 검증됩니다.
 
 `devtools-mcp`를 stdio로 실행하면 로컬 Chii 릴레이를 OS가 할당한 포트에 띄우고 cloudflared quick
 tunnel로 공개 `wss://*.trycloudflare.com` URL을 발급한 뒤 QR을 터미널에 출력합니다(시크릿/인증
-코드는 출력하지 않습니다). 폰이 dogfood 진입 시 in-app attach UI가 그 URL로 릴레이에 붙으면,
+코드는 출력하지 않습니다). 폰이 dog-food 진입 시 in-app attach UI가 그 URL로 릴레이에 붙으면,
 에이전트가 `chrome-devtools-mcp` 호환 tool로 console/network/page 상태를 read합니다. 사람이 폰을
 지켜볼 필요 없이 회귀를 단독 진단하는 것이 목표입니다.
 
@@ -1087,7 +1087,7 @@ tunnel로 공개 `wss://*.trycloudflare.com` URL을 발급한 뒤 QR을 터미
 }
 ```
 
-- 환경 3 (dogfood relay): `start_debug({mode: 'relay-staging'})`
+- 환경 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})`로 진입하세요.
@@ -1103,7 +1103,7 @@ tunnel로 공개 `wss://*.trycloudflare.com` URL을 발급한 뒤 QR을 터미
 | `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` 경유) | dogfood 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·4(실기기 relay)에선 실 SDK, 환경 1(로컬 mock)에선 mock SDK. 환경 2(PWA)는 SDK 미주입으로 사용 불가. 환경 4에서는 `confirm: true` 필수(LIVE guard). 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 버전 |
@@ -1182,7 +1182,7 @@ export default {
 | `@ait-co/devtools/unplugin` | 번들러 플러그인 (.vite, .webpack, .rspack, .esbuild, .rollup) |
 | `@ait-co/devtools/mcp/server` | dev-mode MCP stdio server 함수 (Node.js) |
 | `@ait-co/devtools/mcp/cli` | `devtools-mcp` bin 진입점 (debug / dev 모드, Node.js) |
-| `@ait-co/devtools/in-app` | In-app debug attach — 런타임 gate(layer B·C) + Chii target.js 주입. 소비자가 `if (__DEBUG_BUILD__)`로 import를 감싸 release 빌드에서 DCE — dogfood 빌드 전용 |
+| `@ait-co/devtools/in-app` | In-app debug attach — 런타임 gate(layer B·C) + Chii target.js 주입. 소비자가 `if (__DEBUG_BUILD__)`로 import를 감싸 release 빌드에서 DCE — dog-food 빌드 전용 |
 | `@ait-co/devtools/in-app/auto` | Self-gating side-effect entry — `import '@ait-co/devtools/in-app/auto'` 한 줄로 attach + SDK 브리지 설치. URL 파라미터(`?debug=1` / `?relay=`) 또는 DEV 빌드에서만 활성화, 일반 프로덕션 로드는 dormant. [위 섹션](#on-device-디버깅-한-줄-설정) 참고 |
 
 ## 라이센스

package/dist/mcp/cli.js

@@ -2164,6 +2164,7 @@ const en = {
 	"dashboard.tunnel.down": "Disconnected",
 	"dashboard.attach.section": "Attach QR",
 	"dashboard.attach.hint": "Call the build_attach_url MCP tool to show the QR here.",
+	"dashboard.attach.tunnelDown": "Relay disconnected — this QR is no longer valid. Restart the relay, then regenerate the QR.",
 	"dashboard.pages.section": "Connected Pages",
 	"dashboard.pages.empty": "No attached pages",
 	"dashboard.url.copy": "Copy",
@@ -2400,6 +2401,7 @@ const tables = {
 		"dashboard.tunnel.down": "끊어짐",
 		"dashboard.attach.section": "Attach QR",
 		"dashboard.attach.hint": "build_attach_url MCP tool을 호출하면 QR이 여기에 표시됩니다.",
+		"dashboard.attach.tunnelDown": "relay 연결이 끊겼습니다 — 이 QR은 더 이상 유효하지 않습니다. relay를 재시작한 뒤 QR을 다시 생성하세요.",
 		"dashboard.pages.section": "연결된 Pages",
 		"dashboard.pages.empty": "attach된 페이지 없음",
 		"dashboard.url.copy": "복사",
@@ -2553,6 +2555,7 @@ img.qr {
 }
 .copy-btn:hover { background: #30363d; }
 .hint { font-size: 0.85rem; opacity: 0.5; margin: 0.25rem 0 0; }
+.hint.error { color: #f85149; opacity: 1; font-weight: 600; }
 .inspector-link {
   display: inline-block; margin-top: 0.5rem;
   padding: 0.45rem 1rem; border-radius: 6px;
@@ -2595,6 +2598,8 @@ img.qr {
   display: block; margin: 0 auto;
 }
 section { width: 100%; max-width: 480px; }
+.hint { font-size: 0.85rem; opacity: 0.5; margin: 0.25rem 0 0; }
+.hint.error { color: #f85149; opacity: 1; font-weight: 600; }
 h2 { font-size: 1rem; font-weight: 600; color: #e6edf3; margin: 0 0 0.5rem; }
 ol, ul { margin: 0; padding-left: 1.25rem; }
 li { margin-bottom: 0.4rem; font-size: 0.9rem; line-height: 1.5; }
@@ -2653,6 +2658,8 @@ img.qr {
   display: block; margin: 0 auto;
 }
 section { width: 100%; max-width: 480px; }
+.hint { font-size: 0.85rem; opacity: 0.5; margin: 0.25rem 0 0; }
+.hint.error { color: #f85149; opacity: 1; font-weight: 600; }
 h2 { font-size: 1rem; font-weight: 600; color: #e6edf3; margin: 0 0 0.5rem; }
 ol, ul { margin: 0; padding-left: 1.25rem; }
 li { margin-bottom: 0.4rem; font-size: 0.9rem; line-height: 1.5; }
@@ -2729,6 +2736,7 @@ img.qr {
 }
 .copy-btn:hover { background: #30363d; }
 .hint { font-size: 0.85rem; opacity: 0.5; margin: 0.25rem 0 0; }
+.hint.error { color: #f85149; opacity: 1; font-weight: 600; }
 .inspector-link {
   display: inline-block; margin-top: 0.5rem;
   padding: 0.45rem 1rem; border-radius: 6px;
@@ -2771,6 +2779,8 @@ img.qr {
   display: block; margin: 0 auto;
 }
 section { width: 100%; max-width: 480px; }
+.hint { font-size: 0.85rem; opacity: 0.5; margin: 0.25rem 0 0; }
+.hint.error { color: #f85149; opacity: 1; font-weight: 600; }
 h2 { font-size: 1rem; font-weight: 600; color: #e6edf3; margin: 0 0 0.5rem; }
 ol, ul { margin: 0; padding-left: 1.25rem; }
 li { margin-bottom: 0.4rem; font-size: 0.9rem; line-height: 1.5; }
@@ -2829,6 +2839,8 @@ img.qr {
   display: block; margin: 0 auto;
 }
 section { width: 100%; max-width: 480px; }
+.hint { font-size: 0.85rem; opacity: 0.5; margin: 0.25rem 0 0; }
+.hint.error { color: #f85149; opacity: 1; font-weight: 600; }
 h2 { font-size: 1rem; font-weight: 600; color: #e6edf3; margin: 0 0 0.5rem; }
 ol, ul { margin: 0; padding-left: 1.25rem; }
 li { margin-bottom: 0.4rem; font-size: 0.9rem; line-height: 1.5; }
@@ -2957,7 +2969,8 @@ function buildDashboardHtml(state, qrDataUrl, locale, path = "/", params = new U
 	const tunnelStatus = state.tunnel.up ? s("dashboard.tunnel.up") : s("dashboard.tunnel.down");
 	const tunnelClass = state.tunnel.up ? "status-up" : "status-down";
 	let attachSection;
-	if (qrDataUrl && state.attachUrl) {
+	if (!state.tunnel.up) attachSection = `<p class="hint error">${escapeHtml(s("dashboard.attach.tunnelDown"))}</p>`;
+	else if (qrDataUrl && state.attachUrl) {
 		const safeAttachUrl = escapeHtml(state.attachUrl);
 		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>`;
@@ -2974,6 +2987,7 @@ function buildDashboardHtml(state, qrDataUrl, locale, path = "/", params = new U
 		tunnelDown: JSON.stringify(s("dashboard.tunnel.down")),
 		pagesEmpty: JSON.stringify(s("dashboard.pages.empty")),
 		attachHint: JSON.stringify(s("dashboard.attach.hint")),
+		attachTunnelDown: JSON.stringify(s("dashboard.attach.tunnelDown")),
 		copyLabel: JSON.stringify(s("dashboard.url.copy")),
 		copiedLabel: JSON.stringify(s("dashboard.url.copied")),
 		inspectorOpenLabel: JSON.stringify(s("dashboard.inspector.open")),
@@ -3017,6 +3031,7 @@ function buildSseScript(strings) {
       var TUNNEL_DOWN = ${strings.tunnelDown};
       var PAGES_EMPTY = ${strings.pagesEmpty};
       var ATTACH_HINT = ${strings.attachHint};
+      var ATTACH_TUNNEL_DOWN = ${strings.attachTunnelDown};
       var COPY_LABEL = ${strings.copyLabel};
       var COPIED_LABEL = ${strings.copiedLabel};
       var INSPECTOR_OPEN_LABEL = ${strings.inspectorOpenLabel};
@@ -3106,9 +3121,13 @@ function buildSseScript(strings) {
           }
           // attachUrl QR + url-box 갱신
           // SECRET-HANDLING: URL 값을 로그로 출력하지 않는다.
+          // 터널이 죽으면(s.tunnel.up=false) attachUrl이 남아 있어도 QR을
+          // 그리지 않고 에러 상태로 교체한다 — 죽은 QR이 스캔되는 것을 막는다(#631).
           var sec = document.getElementById('attach-section');
           if (sec) {
-            if (s.attachUrl) {
+            if (!(s.tunnel && s.tunnel.up)) {
+              sec.innerHTML = '<p class=\\"hint error\\">' + ATTACH_TUNNEL_DOWN + '</p>';
+            } else if (s.attachUrl) {
               var encoded = encodeURIComponent(s.attachUrl);
               var safeUrl = String(s.attachUrl).slice(0, 2000).replace(/[<>&"']/g, function (c) { return '&#' + c.charCodeAt(0) + ';'; });
               ${isDashboard ? `// dashboard: #attach-section innerHTML 전체 교체 (img + url-row).
@@ -3196,6 +3215,7 @@ function buildAttachHtml(qrDataUrl, safeLabel, safeAttachUrl, locale, path = "/a
 		tunnelDown: JSON.stringify(s("dashboard.tunnel.down")),
 		pagesEmpty: JSON.stringify(s("dashboard.pages.empty")),
 		attachHint: JSON.stringify(s("dashboard.attach.hint")),
+		attachTunnelDown: JSON.stringify(s("dashboard.attach.tunnelDown")),
 		copyLabel: JSON.stringify(s("dashboard.url.copy")),
 		copiedLabel: JSON.stringify(s("dashboard.url.copied")),
 		inspectorOpenLabel: JSON.stringify(s("dashboard.inspector.open")),
@@ -3540,6 +3560,24 @@ function killAndWait(pid, graceMs = 2e3) {
 	} catch {}
 }
 /**
+* Reaps an orphaned cloudflared tunnel child left behind by a previous session
+* (issue #628). The normal shutdown path TERM-cascades to the child, but a
+* SIGKILL'd or crashed Node process can't run cleanup — its cloudflared child
+* keeps the (now stale) quick tunnel alive. When `acquireLock` reclaims such a
+* lock, this kills the still-alive `tunnelChildPid` so the new session starts
+* from a clean slate (companion to the #347/#571 zombie-daemon defenses).
+*
+* No-op when the lock carries no `tunnelChildPid` (older lock files) or the
+* child is already gone. SECRET-HANDLING: logs the PID only — never the tunnel
+* host/wss (those never enter the lock file or this path).
+*/
+function reapOrphanTunnelChild(existing) {
+	const childPid = existing.tunnelChildPid;
+	if (typeof childPid !== "number" || !isPidAlive(childPid)) return;
+	process.stderr.write(`[ait-debug] reaping orphaned tunnel child PID=${childPid} from previous session.\n`);
+	killAndWait(childPid);
+}
+/**
 * Reads the current lock file without acquiring it. Returns the parsed
 * `LockData` when the file exists and is valid, otherwise `null`. Used by
 * `get_debug_status` to surface the `serverLockHolder` field without
@@ -3571,13 +3609,17 @@ function acquireLock(options = {}) {
 		else if (force) {
 			process.stderr.write(`[ait-debug] --force: terminating existing session PID=${existing.pid} …\n`);
 			killAndWait(existing.pid);
+			reapOrphanTunnelChild(existing);
 			process.stderr.write(`[ait-debug] --force: PID=${existing.pid} stopped, taking over.\n`);
 		} else {
 			const urlPart = existing.wssUrl != null ? `wssUrl=${existing.wssUrl}` : "wssUrl=(tunnel starting)";
 			process.stderr.write(`[ait-debug] 기존 debug-mode 세션이 이미 실행 중 — PID=${existing.pid}, started ${existing.startedAt}, ${urlPart}\n[ait-debug] 회복: \`kill ${existing.pid}\` 또는 \`npx @ait-co/devtools devtools-mcp --force\`\n`);
 			throw new ServerLockConflictError(existing.pid, existing.wssUrl, existing.startedAt);
 		}
-	} else process.stderr.write(`[ait-debug] stale lock from PID ${existing.pid} recovered — starting fresh.\n`);
+	} else {
+		process.stderr.write(`[ait-debug] stale lock from PID ${existing.pid} recovered — starting fresh.\n`);
+		reapOrphanTunnelChild(existing);
+	}
 	const data = {
 		pid: process.pid,
 		wssUrl: null,
@@ -3922,7 +3964,7 @@ const DEBUG_TOOL_DEFINITIONS = [
 	},
 	{
 		name: "AIT.getSdkCallHistory",
-		description: "Returns the recent Apps In Toss SDK call trace (method, args, result/error, timestamp) that raw CDP cannot observe. Read-only. Use to confirm an SDK call fired and how it resolved (e.g. a saveBase64Data permission regression).",
+		description: "Returns the recent Apps in Toss SDK call trace (method, args, result/error, timestamp) that raw CDP cannot observe. Read-only. Use to confirm an SDK call fired and how it resolved (e.g. a saveBase64Data permission regression).",
 		inputSchema: {
 			type: "object",
 			properties: {},
@@ -4813,7 +4855,7 @@ async function readMcpSdkVersion() {
 * some test environments that skip the build step).
 */
 function readDevtoolsVersion() {
-	return "0.1.103";
+	return "0.1.105";
 }
 /**
 * Derives the next recommended action from a completed diagnostics snapshot.
@@ -5405,7 +5447,7 @@ function createDebugServer(deps) {
 	const collector = collectorDep ?? new InMemoryDiagnosticsCollector();
 	const server = new Server({
 		name: "ait-debug",
-		version: "0.1.103"
+		version: "0.1.105"
 	}, { capabilities: { tools: { listChanged: true } } });
 	server.setRequestHandler(ListToolsRequestSchema, () => {
 		const conn = router.active;
@@ -6189,6 +6231,7 @@ async function bootRelayFamily(options = {}) {
 			onPermanentDrop: (droppedAt) => {
 				tunnelStatus = makeTunnelStatus(false, null, droppedAt, 3);
 				logError("tunnel.down", { msg: `tunnel permanently dropped (${droppedAt}). Restart: npx @ait-co/devtools devtools-mcp` });
+				options.onTunnelDown?.();
 			}
 		});
 		return printAttachBanner({
@@ -6550,7 +6593,8 @@ async function runDebugServer(options = {}) {
 				activeTunnelChildPid = pid;
 				lockHandle.updateTunnelChildPid(pid);
 			},
-			onAuthReject: () => diagnosticsCollector.recordAuthReject()
+			onAuthReject: () => diagnosticsCollector.recordAuthReject(),
+			onTunnelDown: () => qrServer?.notifyStateChange()
 		}),
 		diagnosticsCollector,
 		devtoolsOpener,
@@ -6763,7 +6807,8 @@ async function runLocalDebugServer(options = {}) {
 				activeTunnelChildPid = pid;
 				lockHandle.updateTunnelChildPid(pid);
 			},
-			onAuthReject: () => diagnosticsCollector.recordAuthReject()
+			onAuthReject: () => diagnosticsCollector.recordAuthReject(),
+			onTunnelDown: () => qrServer?.notifyStateChange()
 		}),
 		diagnosticsCollector,
 		devtoolsOpener,
@@ -6959,7 +7004,8 @@ async function runMobileDebugServer(options = {}) {
 				activeTunnelChildPid = pid;
 				lockHandle.updateTunnelChildPid(pid);
 			},
-			onAuthReject: () => diagnosticsCollector.recordAuthReject()
+			onAuthReject: () => diagnosticsCollector.recordAuthReject(),
+			onTunnelDown: () => qrServer?.notifyStateChange()
 		}),
 		diagnosticsCollector,
 		devtoolsOpener,
@@ -7539,7 +7585,7 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.103"
+		version: "0.1.105"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {