@ait-co/devtools 0.1.51 → 0.1.53

package/dist/mcp/cli.js

@@ -213,6 +213,8 @@ const DEFAULT_COMMAND_TIMEOUT_MS = 3e4;
 * opens a client websocket to it, enables Phase 1 domains, and buffers events.
 */
 var ChiiCdpConnection = class {
+	/** Authoritative connection kind (issue #348) — relay-backed. */
+	kind = "relay";
 	relayBaseUrl;
 	bufferSize;
 	commandTimeoutMs;
@@ -909,7 +911,7 @@ function isLiveRelayEnv(env) {
 	return env === "relay-live";
 }
 /**
-* Maps the new `McpEnvironment` union to the legacy two-value union
+* Maps the `McpEnvironment` union to the legacy two-value union
 * (`'mock' | 'relay'`) for backward-compatible fields in diagnostics output.
 */
 function toLegacyEnv(env) {
@@ -917,93 +919,42 @@ function toLegacyEnv(env) {
 	return "relay";
 }
 /**
-* URL patterns that mark a CDP target as a real-device WebView relay.
+* Reconstructs the three-value `McpEnvironment` output string from the two
+* orthogonal signals (issue #348):
 *
-* - `intoss-private://` is the Toss in-app private scheme — only ever observed
-*   inside the real Toss app WebView.
-* - `*.trycloudflare.com` (host suffix) is the cloudflared quick tunnel used as
-*   the relay transport. A target whose URL is on that host is, by construction,
-*   reached over the relay.
+*   - `kind === 'local'`                 → `'mock'`
+*   - `kind === 'relay'` &&  liveIntent  → `'relay-live'`
+*   - `kind === 'relay'` && !liveIntent  → `'relay-dev'`
 *
-* Pattern-only matches — no specific tunnel host or deploymentId is hard-coded.
+* Pure — used at every output boundary (envelope `meta.env`, `get_diagnostics`,
+* `measure_safe_area` provenance) so the surface never sniffs a URL again.
 */
-const RELAY_URL_PATTERNS = [/^intoss-private:\/\//i, /:\/\/[a-z0-9-]+\.trycloudflare\.com(\/|$|:|\?)/i];
-/**
-* Returns true when the URL string looks like a real-device WebView attached
-* over the Chii relay. Used for `getEnvironment()` precedence step 2.
-*/
-function isRelayUrl(url) {
-	if (typeof url !== "string" || url.length === 0) return false;
-	return RELAY_URL_PATTERNS.some((p) => p.test(url));
+function deriveEnvironment(kind, liveIntent) {
+	if (kind === "local") return "mock";
+	return liveIntent ? "relay-live" : "relay-dev";
 }
 /**
-* Test/override hook — when non-null, `getEnvironment()` returns this value
-* regardless of env vars or connection state. Cleared with `null`.
-*/
-let envOverride = null;
-/**
-* Parses the `MCP_ENV` env var into a `McpEnvironment` if valid.
+* Module-level `relay-dev` vs `relay-live` intent bit (issue #348).
 *
-* Accepted values:
-*   - `mock`        → `mock`
-*   - `relay-dev`   → `relay-dev`
-*   - `relay-live`  → `relay-live`
-*   - `relay`       → `relay-dev`  (backward-compat alias — resolves to relay-dev)
+* Armed by `start_debug({ mode: 'relay-live' })` (and seeded at boot by the
+* deprecated `MCP_ENV=relay-live` alias). Disarming is implicit: when the
+* active connection becomes local, the LIVE guard reads
+* `connection.kind === 'relay' && liveIntent`, so a stale `true` bit is inert.
 *
-* Any other value is ignored and falls through to the next precedence step.
+* SECRET-HANDLING: this is a boolean — never a secret. Safe to read in logs.
 */
-function readEnvVar() {
-	const raw = process.env.MCP_ENV;
-	if (raw === "mock") return "mock";
-	if (raw === "relay-dev") return "relay-dev";
-	if (raw === "relay-live") return "relay-live";
-	if (raw === "relay") return "relay-dev";
-}
-/**
-* Returns the current MCP environment, applying the precedence rules:
-*   1. test override (if set)
-*   2. `MCP_ENV` env var
-*   3. CDP target URL pattern match → `relay-dev` (conservative — LIVE
-*      requires explicit MCP_ENV=relay-live opt-in)
-*   4. caller-stated `defaultEnv` (intent hint from the CLI mode)
-*   5. baked-in default `mock`
-*/
-function getEnvironment(input = {}) {
-	if (envOverride !== null) return envOverride;
-	const fromEnv = readEnvVar();
-	if (fromEnv !== void 0) return fromEnv;
-	const { connection, defaultEnv } = input;
-	if (connection !== void 0) {
-		const targets = connection.listTargets();
-		for (const t of targets) if (isRelayUrl(t.url)) return "relay-dev";
-	}
-	return defaultEnv ?? "mock";
+let liveIntent = false;
+/** Returns the current `liveIntent` bit. */
+function getLiveIntent() {
+	return liveIntent;
 }
 /**
-* Returns the `EnvironmentReason` that drove the current `getEnvironment()`
-* result. Used by stderr logs and the rejection-reason payload on Tier A/B
-* mismatch errors. SECRET-HANDLING: only stable enum strings — no URL or
-* secret value is ever returned.
+* Sets the `liveIntent` bit. Called by `start_debug` (true for `relay-live`,
+* false for every other mode) and once at boot by the `MCP_ENV=relay-live`
+* deprecated alias.
 */
-function getEnvironmentReason(input = {}) {
-	if (envOverride !== null) {
-		if (envOverride === "mock") return "env-var-mock";
-		if (envOverride === "relay-live") return "env-var-relay-live";
-		return "env-var-relay-dev";
-	}
-	const rawVar = process.env.MCP_ENV;
-	const fromEnv = readEnvVar();
-	if (fromEnv === "mock") return "env-var-mock";
-	if (fromEnv === "relay-live") return "env-var-relay-live";
-	if (fromEnv === "relay-dev") return rawVar === "relay" ? "env-var-relay-compat" : "env-var-relay-dev";
-	const { connection, defaultEnv } = input;
-	if (connection !== void 0) {
-		const targets = connection.listTargets();
-		for (const t of targets) if (isRelayUrl(t.url)) return "cdp-target-url-relay-pattern";
-	}
-	if (defaultEnv === "relay-live") return "default-relay-live";
-	if (defaultEnv === "relay-dev") return "default-relay-dev";
-	return "default-mock";
+function setLiveIntent(value) {
+	liveIntent = value;
 }
 //#endregion
 //#region src/mcp/errors.ts
@@ -1027,7 +978,8 @@ function mcpError(message) {
 * @param toolName    - 거부된 tool 이름.
 * @param requiredEnv - 해당 tool이 요구하는 환경 ('mock' | 'relay').
 * @param currentEnv  - 현재 세션 환경.
-* @param reason      - 환경이 결정된 근거 (EnvironmentReason 문자열).
+* @param reason      - 환경이 결정된 근거를 나타내는 파생 문자열
+*                      (예: `derived:kind=relay,liveIntent=true`).
 */
 function tierRejectionError(toolName, requiredEnv, currentEnv, reason) {
 	return mcpError(`${`${toolName}은 ${requiredEnv === "relay" ? "relay (실기기 연결)" : "mock (로컬 브라우저)"} 환경에서만 사용할 수 있습니다. 현재 환경: ${currentEnv === "relay" ? "relay" : "mock"} (${reason}). ${requiredEnv === "relay" ? "relay로 전환하려면 MCP_ENV=relay 설정 후 서버를 재시작하고 build_attach_url → QR 스캔으로 실기기를 attach하세요." : "mock으로 전환하려면 MCP_ENV=mock 설정 후 서버를 재시작하세요."}`}\n\n${`tool ${toolName} is available only in ${requiredEnv}. Current environment is ${currentEnv} (${reason}).`}`);
@@ -1162,6 +1114,8 @@ const PHASE_1_EVENTS = [
 * `about:blank`, `about:newtab`, or a devtools:// URL.
 */
 var LocalCdpConnection = class {
+	/** Authoritative connection kind (issue #348) — local Chromium CDP. */
+	kind = "local";
 	devtoolsHttpUrl;
 	bufferSize;
 	emitter = new EventEmitter();
@@ -2317,6 +2271,31 @@ const DEBUG_TOOL_DEFINITIONS = [
 		},
 		availableIn: "both"
 	},
+	{
+		name: "start_debug",
+		description: "Switches the active debug environment in-place (issue #348) — no Claude Code restart and no MCP re-handshake. One daemon holds both a local (env 1, mock SDK in a Chromium) and a relay (env 3/4, real-device Toss WebView over the Chii relay + cloudflared tunnel) connection at once; this tool flips which one every other tool reads from, lazily booting the requested family's infra on first use and keeping the inactive one warm so an existing attach survives the switch. After switching it emits notifications/tools/list_changed — call tools/list again to see the updated tool surface for the new environment.\n\nmodes:\n  local-browser-dev / local-browser-cdp — local Chromium CDP attach (env 1, mock). Both route to the local connection; the names preserve dev-vs-cdp intent.\n  relay-dev  — real-device dogfood relay (env 3). Side-effect tools run unguarded.\n  relay-live — real-device live/production relay (env 4, read-only debugging). Arms the LIVE guard: call_sdk/evaluate then require confirm: true. Entering relay-live ALSO requires confirm: true on this call to acknowledge LIVE intent.\n\nSwitching back to a local mode automatically disarms the LIVE guard.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				mode: {
+					type: "string",
+					enum: [
+						"local-browser-dev",
+						"local-browser-cdp",
+						"relay-dev",
+						"relay-live"
+					],
+					description: "Target environment to switch to. relay-live additionally requires confirm: true."
+				},
+				confirm: {
+					type: "boolean",
+					description: "Required when mode=relay-live — set true to acknowledge entering LIVE (env 4) debugging that can affect real users. Ignored for the other modes."
+				}
+			},
+			required: ["mode"]
+		},
+		availableIn: "both"
+	},
 	{
 		name: "get_diagnostics",
 		description: "Returns a single-call server status snapshot so the agent can diagnose \"why is this not working?\" without calling multiple tools. Fields: mcpVersion (MCP SDK version), devtoolsVersion (@ait-co/devtools package version), tunnel (up/wssUrl/pid/startedAt), pages (list_pages result + lastSeenAt stats), lastAttachAt, lastDetachAt, recentErrors (last N server-side errors, PII/secret redacted), environment (kind: mock|relay-dev|relay-live, env: mock|relay backward-compat, reason, liveGuardActive: true when relay-live LIVE guard is active), serverLockHolder (pid + startedAt from the lock file, or null), nextRecommendedAction ({tool, reason} or null — the single next tool to call; in local-target mode tunnel.up=false is normal so \"restart\" is never recommended). All fields are nullable — missing data is null, not an error. debug-mode only — dev-mode (--mode=dev) does not support relay diagnostics. Tier C (both mock and relay). Call this first when debugging session state.",
@@ -2381,7 +2360,8 @@ function filterToolsByEnvironment(tools, env) {
 const BOOTSTRAP_TOOL_NAMES = new Set([
 	"build_attach_url",
 	"get_diagnostics",
-	"list_pages"
+	"list_pages",
+	"start_debug"
 ]);
 /** Renders a CDP `RemoteObject` console arg to a stable display string. */
 function renderRemoteObject(arg) {
@@ -3112,19 +3092,26 @@ var InMemoryDiagnosticsCollector = class {
 	}
 };
 /**
-* Reads the `@modelcontextprotocol/sdk` package version from the installed
-* package's `package.json`. Returns `null` on any error (missing file, JSON
-* parse failure, etc.) — diagnostics must never throw.
-*
-* Node-only — uses dynamic `import()` so it does not pollute the browser
-* module graph.
+* Returns the `@modelcontextprotocol/sdk` version baked in at build time via
+* the `__MCP_SDK_VERSION__` define (see `tsdown.config.ts`). Returns `null`
+* when the define is absent (unbundled test runs) and the runtime fallback
+* below also fails — diagnostics must never throw.
+*
+* The old implementation resolved `@modelcontextprotocol/sdk/package.json` at
+* runtime, but that subpath is NOT in the SDK's `exports` map, so the resolve
+* threw `ERR_PACKAGE_PATH_NOT_EXPORTED` and this always returned `null` in a
+* real bundle (issue #361). The build-time define sidesteps the exports gate.
+*
+* Kept `async` for call-site compatibility (`Promise.all` at the caller); the
+* body is synchronous apart from the best-effort fallback.
 */
 async function readMcpSdkVersion() {
 	try {
 		const { createRequire } = await import("node:module");
-		const pkgPath = createRequire(import.meta.url).resolve("@modelcontextprotocol/sdk/package.json");
+		const entry = createRequire(import.meta.url).resolve("@modelcontextprotocol/sdk");
+		const root = entry.slice(0, entry.indexOf("@modelcontextprotocol/sdk") + 25);
 		const { readFileSync } = await import("node:fs");
-		const raw = readFileSync(pkgPath, "utf8");
+		const raw = readFileSync(`${root}/package.json`, "utf8");
 		const parsed = JSON.parse(raw);
 		return typeof parsed.version === "string" ? parsed.version : null;
 	} catch {
@@ -3137,12 +3124,7 @@ async function readMcpSdkVersion() {
 * some test environments that skip the build step).
 */
 function readDevtoolsVersion() {
-	try {
-		const v = globalThis.__VERSION__;
-		return typeof v === "string" && v.length > 0 ? v : null;
-	} catch {
-		return null;
-	}
+	return "0.1.53";
 }
 /**
 * Derives the next recommended action from a completed diagnostics snapshot.
@@ -3559,6 +3541,10 @@ function extractDeploymentId(schemeUrl) {
 		return null;
 	}
 }
+/** Returns `true` when the mode routes to a relay connection. */
+function isRelayMode(mode) {
+	return mode === "relay-dev" || mode === "relay-live";
+}
 /**
 * Waits for the first target matching `filterFn` to attach, using the
 * event-driven `waitForFirstTarget()` when the connection supports it
@@ -3613,23 +3599,19 @@ function waitForAttachWithEvents(connection, filterFn, timeoutMs, pollIntervalMs
 * naturally via `enableDomains`). The tier only controls visibility.
 */
 function createDebugServer(deps) {
-	const { connection, aitSource, getTunnelStatus, waitForAttachTimeoutMs = 9e4, qrHttpServer, getEnvironment: getEnvDep, getEnvironmentReason: getEnvReasonDep, diagnosticsCollector: collectorDep, defaultEnv, totpSecret } = deps;
-	const resolveEnvironment = getEnvDep ?? (() => getEnvironment({
-		connection,
-		defaultEnv
-	}));
-	const resolveEnvironmentReason = getEnvReasonDep ?? (() => getEnvironmentReason({
-		connection,
-		defaultEnv
-	}));
+	const { connection, router: routerDep, aitSource, getTunnelStatus, waitForAttachTimeoutMs = 9e4, qrHttpServer, getEnvironment: getEnvDep, getEnvironmentReason: getEnvReasonDep, diagnosticsCollector: collectorDep, totpSecret } = deps;
+	const router = routerDep ?? makeSingleConnectionRouter(connection);
+	const resolveEnvironment = getEnvDep ?? (() => deriveEnvironment(router.active.kind, getLiveIntent()));
+	const resolveEnvironmentReason = getEnvReasonDep ?? (() => `derived:kind=${router.active.kind},liveIntent=${getLiveIntent()}`);
 	const collector = collectorDep ?? new InMemoryDiagnosticsCollector();
 	const server = new Server({
 		name: "ait-debug",
-		version: "0.1.51"
+		version: "0.1.53"
 	}, { capabilities: { tools: { listChanged: true } } });
 	server.setRequestHandler(ListToolsRequestSchema, () => {
+		const conn = router.active;
 		const env = resolveEnvironment();
-		const attached = connection.listTargets().length > 0;
+		const attached = conn.listTargets().length > 0;
 		const envFiltered = filterToolsByEnvironment(DEBUG_TOOL_DEFINITIONS, env);
 		return { tools: attached ? envFiltered.map((tool) => ({ ...tool })) : envFiltered.filter((tool) => BOOTSTRAP_TOOL_NAMES.has(tool.name)).map((tool) => ({ ...tool })) };
 	});
@@ -3642,10 +3624,22 @@ function createDebugServer(deps) {
 			}],
 			isError: true
 		};
+		const conn = router.active;
+		if (name === "start_debug") {
+			const rawMode = request.params.arguments?.mode;
+			const mode = normalizeStartDebugMode(rawMode);
+			if (mode === null) return mcpError("start_debug: mode가 올바르지 않습니다. 'local-browser-dev' | 'local-browser-cdp' | 'relay-dev' | 'relay-live' 중 하나를 전달하세요.");
+			const confirm = request.params.arguments?.confirm === true;
+			try {
+				return jsonResult$1(await router.switchMode(mode, confirm));
+			} catch (err) {
+				return errorResult(err, name);
+			}
+		}
 		const env = resolveEnvironment();
+		const envReason = resolveEnvironmentReason();
 		if (!isToolAvailableIn(name, env)) {
 			const requiredEnv = getToolAvailability(name) ?? "unknown";
-			const envReason = resolveEnvironmentReason();
 			logWarn("tool.error", {
 				tool: name,
 				errorKind: "tier-filter",
@@ -3656,7 +3650,7 @@ function createDebugServer(deps) {
 			return tierRejectionError(name, requiredEnv, env, envReason);
 		}
 		if (isAitToolName(name)) try {
-			await connection.enableDomains();
+			await conn.enableDomains();
 			switch (name) {
 				case "AIT.getSdkCallHistory": return jsonResult$1(await getSdkCallHistory(aitSource));
 				case "AIT.getMockState": return jsonResult$1(await getMockState(aitSource));
@@ -3669,17 +3663,15 @@ function createDebugServer(deps) {
 		if (name === "get_diagnostics") try {
 			const rawLimit = request.params.arguments?.recent_errors_limit;
 			const recentErrorsLimit = typeof rawLimit === "number" && rawLimit > 0 ? rawLimit : 10;
-			const result = await getDiagnostics({
+			return envelopeResult$1(await getDiagnostics({
 				tunnel: getTunnelStatus(),
-				connection,
-				env: resolveEnvironment(),
-				envReason: resolveEnvironmentReason(),
+				connection: conn,
+				env,
+				envReason,
 				collector,
 				readLock: readServerLock,
 				recentErrorsLimit
-			});
-			const attached = connection.listTargets().length > 0;
-			return envelopeResult$1(result, name, resolveEnvironment(), attached);
+			}), name, env, conn.listTargets().length > 0);
 		} catch (err) {
 			return errorResult(err, name);
 		}
@@ -3724,9 +3716,9 @@ function createDebugServer(deps) {
 					}] };
 					let attachedPagesHl = [];
 					try {
-						attachedPagesHl = await waitForAttachWithEvents(connection, isMatchingPage, waitForAttachTimeoutMs);
+						attachedPagesHl = await waitForAttachWithEvents(conn, isMatchingPage, waitForAttachTimeoutMs);
 					} catch {
-						attachedPagesHl = connection.listTargets();
+						attachedPagesHl = conn.listTargets();
 						return {
 							content: [{
 								type: "text",
@@ -3735,7 +3727,7 @@ function createDebugServer(deps) {
 							isError: true
 						};
 					}
-					const pagesResultHl = listPages(connection, getTunnelStatus());
+					const pagesResultHl = listPages(conn, getTunnelStatus());
 					return { content: [{
 						type: "text",
 						text: `${headlessText}\n\n${JSON.stringify(pagesResultHl, null, 2)}`
@@ -3761,9 +3753,9 @@ function createDebugServer(deps) {
 						}] };
 						let attachedPages = [];
 						try {
-							attachedPages = await waitForAttachWithEvents(connection, isMatchingPage, waitForAttachTimeoutMs);
+							attachedPages = await waitForAttachWithEvents(conn, isMatchingPage, waitForAttachTimeoutMs);
 						} catch {
-							attachedPages = connection.listTargets();
+							attachedPages = conn.listTargets();
 							return {
 								content: [{
 									type: "text",
@@ -3772,7 +3764,7 @@ function createDebugServer(deps) {
 								isError: true
 							};
 						}
-						const pagesResult = listPages(connection, getTunnelStatus());
+						const pagesResult = listPages(conn, getTunnelStatus());
 						return { content: [{
 							type: "text",
 							text: `${shortText}\n\n${JSON.stringify(pagesResult, null, 2)}`
@@ -3801,9 +3793,9 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 					}] };
 					let attachedPagesFb = [];
 					try {
-						attachedPagesFb = await waitForAttachWithEvents(connection, isMatchingPage, waitForAttachTimeoutMs);
+						attachedPagesFb = await waitForAttachWithEvents(conn, isMatchingPage, waitForAttachTimeoutMs);
 					} catch {
-						attachedPagesFb = connection.listTargets();
+						attachedPagesFb = conn.listTargets();
 						return {
 							content: [{
 								type: "text",
@@ -3812,7 +3804,7 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 							isError: true
 						};
 					}
-					const pagesResultFb = listPages(connection, getTunnelStatus());
+					const pagesResultFb = listPages(conn, getTunnelStatus());
 					return { content: [{
 						type: "text",
 						text: `${baseText}\n\n${JSON.stringify(pagesResultFb, null, 2)}`
@@ -3830,9 +3822,9 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 				}] };
 				let attachedPages = [];
 				try {
-					attachedPages = await waitForAttachWithEvents(connection, isMatchingPage, waitForAttachTimeoutMs);
+					attachedPages = await waitForAttachWithEvents(conn, isMatchingPage, waitForAttachTimeoutMs);
 				} catch {
-					attachedPages = connection.listTargets();
+					attachedPages = conn.listTargets();
 					return {
 						content: [{
 							type: "text",
@@ -3841,7 +3833,7 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 						isError: true
 					};
 				}
-				const pagesResult = listPages(connection, getTunnelStatus());
+				const pagesResult = listPages(conn, getTunnelStatus());
 				return { content: [{
 					type: "text",
 					text: `${baseText}\n\n${JSON.stringify(pagesResult, null, 2)}`
@@ -3851,65 +3843,55 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 			}
 		}
 		try {
-			await connection.enableDomains();
+			await conn.enableDomains();
 		} catch (err) {
 			if (name === "list_pages") {
 				try {
-					await connection.refreshTargets?.();
+					await conn.refreshTargets?.();
 				} catch {}
-				const pagesData = listPages(connection, getTunnelStatus());
-				const attached = connection.listTargets().length > 0;
-				return envelopeResult$1(pagesData, name, resolveEnvironment(), attached);
+				return envelopeResult$1(listPages(conn, getTunnelStatus()), name, env, conn.listTargets().length > 0);
 			}
 			return classifyEnableDomainError(err, name);
 		}
 		try {
 			switch (name) {
-				case "list_console_messages": return jsonResult$1(listConsoleMessages(connection));
+				case "list_console_messages": return jsonResult$1(listConsoleMessages(conn));
 				case "list_exceptions": {
 					const rawLimit = request.params.arguments?.limit;
-					return jsonResult$1({ exceptions: listExceptions(connection, typeof rawLimit === "number" && rawLimit > 0 ? rawLimit : 50) });
+					return jsonResult$1({ exceptions: listExceptions(conn, typeof rawLimit === "number" && rawLimit > 0 ? rawLimit : 50) });
 				}
-				case "list_network_requests": return jsonResult$1(listNetworkRequests(connection));
-				case "list_pages": {
+				case "list_network_requests": return jsonResult$1(listNetworkRequests(conn));
+				case "list_pages":
 					try {
-						await connection.refreshTargets?.();
+						await conn.refreshTargets?.();
 					} catch {}
-					const listPagesData = listPages(connection, getTunnelStatus());
-					const listPagesAttached = connection.listTargets().length > 0;
-					return envelopeResult$1(listPagesData, name, resolveEnvironment(), listPagesAttached);
-				}
-				case "get_dom_document": return jsonResult$1(await getDomDocument(connection));
-				case "take_snapshot": return jsonResult$1(await takeSnapshot(connection));
+					return envelopeResult$1(listPages(conn, getTunnelStatus()), name, env, conn.listTargets().length > 0);
+				case "get_dom_document": return jsonResult$1(await getDomDocument(conn));
+				case "take_snapshot": return jsonResult$1(await takeSnapshot(conn));
 				case "take_screenshot": {
-					const shot = await takeScreenshot(connection);
+					const shot = await takeScreenshot(conn);
 					return { content: [{
 						type: "image",
 						data: shot.data,
 						mimeType: shot.mimeType
 					}] };
 				}
-				case "measure_safe_area": {
-					const safeAreaData = await measureSafeArea(connection, resolveEnvironment());
-					const safeAreaAttached = connection.listTargets().length > 0;
-					return envelopeResult$1(safeAreaData, name, resolveEnvironment(), safeAreaAttached);
-				}
+				case "measure_safe_area": return envelopeResult$1(await measureSafeArea(conn, env), name, env, conn.listTargets().length > 0);
 				case "evaluate": {
 					const expression = request.params.arguments?.expression;
 					if (typeof expression !== "string" || expression === "") return mcpError("evaluate: expression 인자가 비어 있습니다. 평가할 JavaScript 표현식을 전달하세요.");
-					if (isLiveRelayEnv(env) && request.params.arguments?.confirm !== true) return liveGuardError("evaluate");
-					return jsonResult$1(await evaluate(connection, expression));
+					if (conn.kind === "relay" && getLiveIntent() && request.params.arguments?.confirm !== true) return liveGuardError("evaluate");
+					return jsonResult$1(await evaluate(conn, expression));
 				}
 				case "call_sdk": {
 					const sdkName = request.params.arguments?.name;
 					if (typeof sdkName !== "string" || sdkName === "") return mcpError("call_sdk: name 인자가 비어 있습니다. 호출할 SDK 메서드 이름을 전달하세요.");
 					const rawArgs = request.params.arguments?.args;
 					const sdkArgs = Array.isArray(rawArgs) ? rawArgs : [];
-					if (isLiveRelayEnv(env) && request.params.arguments?.confirm !== true) return liveGuardError("call_sdk");
-					const sdkResult = await callSdk(connection, sdkName, sdkArgs);
+					if (conn.kind === "relay" && getLiveIntent() && request.params.arguments?.confirm !== true) return liveGuardError("call_sdk");
+					const sdkResult = await callSdk(conn, sdkName, sdkArgs);
 					if (!sdkResult.ok && typeof sdkResult.error === "string" && sdkResult.error.startsWith("sdk-absent:")) return sdkAbsentError("call_sdk");
-					const callSdkAttached = connection.listTargets().length > 0;
-					return envelopeResult$1(sdkResult, name, resolveEnvironment(), callSdkAttached);
+					return envelopeResult$1(sdkResult, name, env, conn.listTargets().length > 0);
 				}
 				default: return unknownTool(name);
 			}
@@ -3919,6 +3901,46 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 	});
 	return server;
 }
+/**
+* Normalizes a raw `start_debug` `mode` argument to a `StartDebugMode`, or
+* `null` when the value is not one of the four accepted modes.
+*/
+function normalizeStartDebugMode(raw) {
+	if (raw === "local-browser-dev") return "local-browser-dev";
+	if (raw === "local-browser-cdp") return "local-browser-cdp";
+	if (raw === "relay-dev") return "relay-dev";
+	if (raw === "relay-live") return "relay-live";
+	return null;
+}
+/**
+* Builds a trivial `ConnectionRouter` pinned to a single connection (issue
+* #348). Used by `createDebugServer` when no real dual router is injected —
+* every existing single-connection test and the `local`-only / `relay`-only
+* boot path. `switchMode` here cannot lazily boot another family, so it only
+* honors a request that matches the connection's own kind (and arms/disarms
+* `liveIntent` accordingly for relay-live); any cross-family request is
+* rejected with a clear "dynamic switch unavailable in this session" error.
+*/
+function makeSingleConnectionRouter(connection) {
+	return {
+		get active() {
+			return connection;
+		},
+		switchMode(mode, confirm) {
+			if (isRelayMode(mode) !== (connection.kind === "relay")) return Promise.reject(/* @__PURE__ */ new Error(`start_debug: 이 세션은 단일 ${connection.kind} 연결만 보유합니다 — '${mode}'로 동적 전환할 수 없습니다 (dual-connection 데몬에서만 지원). MCP 서버를 원하는 모드로 재시작하세요.`));
+			if (mode === "relay-live" && !confirm) return Promise.reject(/* @__PURE__ */ new Error("start_debug: relay-live(실서비스 LIVE)는 confirm: true가 필요합니다 — 실유저에게 영향이 갈 수 있는 LIVE 디버깅 진입을 명시적으로 승인하세요."));
+			setLiveIntent(mode === "relay-live");
+			const environment = deriveEnvironment(connection.kind, getLiveIntent());
+			return Promise.resolve({
+				mode,
+				environment,
+				kind: connection.kind,
+				liveGuardActive: connection.kind === "relay" && getLiveIntent(),
+				nextStep: connection.kind === "relay" ? "build_attach_url로 attach QR을 생성하세요." : "list_pages로 로컬 페이지 attach를 확인하세요."
+			});
+		}
+	};
+}
 function jsonResult$1(value) {
 	return { content: [{
 		type: "text",
@@ -4080,21 +4102,72 @@ 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),
-*   2. open a cloudflared quick tunnel to the relay's confirmed port,
-*   3. print relay URL + attach instructions,
-*   4. expose the debug tools backed by a `ChiiCdpConnection` + `ChiiAitSource`.
+* AIT source that always forwards over the *currently active* connection
+* (issue #348). The single-connection `ChiiAitSource` binds one sender at
+* construction; in the dual-connection daemon the AIT.* domain must follow the
+* active connection across `start_debug` swaps, so this indirection reads
+* `getActive()` on every call.
+*
+* Both `ChiiCdpConnection` and `LocalCdpConnection` expose `sendCommand`, so
+* the active connection is a valid `AitCommandSender`.
 */
-async function runDebugServer(options = {}) {
-	const lockHandle = acquireLock({ force: options.force ?? false });
+var RoutingAitSource = class extends ChiiAitSource {
+	constructor(getActive) {
+		super({ sendCommand: (method, params) => getActive().sendCommand(method, params) });
+	}
+};
+/**
+* Boots the local-browser family (issues #348, #356). Launches a Chromium with
+* `--remote-debugging-port` and returns a `LocalCdpConnection` attached to it,
+* plus a `stop()` that kills both.
+*
+* Used two ways:
+*   - `runDebugServer` (relay-eager): the dual router's lazy callback, booted at
+*     most once on the first `start_debug({ mode: 'local-*' })`.
+*   - `runLocalDebugServer` (local-eager, #356): the eager family booted at
+*     startup.
+*/
+async function bootLocalFamily() {
+	const chromium = await launchChromium({
+		port: 0,
+		devUrl: process.env.AIT_DEVTOOLS_URL ?? "http://localhost:5173"
+	});
+	await new Promise((r) => setTimeout(r, 800));
+	const connection = new LocalCdpConnection({ devtoolsHttpUrl: chromium.devtoolsUrl });
+	return {
+		connection,
+		stop() {
+			connection.close();
+			chromium.stop();
+		}
+	};
+}
+/**
+* Boots the relay family (issues #348, #356): starts the Chii relay on an
+* OS-assigned port (with optional TOTP gate), opens a cloudflared quick tunnel
+* to the relay's confirmed port in the background, prints the attach banner,
+* and arms the tunnel health probe. Returns a {@link BootedFamily} whose
+* `getTunnelStatus()` reflects the live tunnel (it flips up once the background
+* tunnel resolves and follows reissues).
+*
+* Used two ways (symmetry with {@link bootLocalFamily}):
+*   - `runDebugServer` (relay-eager): booted at startup.
+*   - `runLocalDebugServer` (local-eager, #356): the dual router's lazy
+*     callback, booted at most once on the first `start_debug({ mode: 'relay-*' })`.
+*
+* The relay base URL is only known after `startChiiRelay()` resolves, so the
+* `ChiiCdpConnection` (via {@link createRelayConnection}) is constructed inside
+* this function, after the relay port is confirmed.
+*
+* SECRET-HANDLING: the TOTP secret rides only inside `verifyAuth`; the wssUrl
+* (relay host) is never logged here directly.
+*/
+async function bootRelayFamily(options = {}) {
 	const relayPort = options.relayPort ?? 0;
-	const verifyAuth = buildRelayVerifyAuth();
-	const totpEnabled = verifyAuth !== void 0;
+	const totpEnabled = options.verifyAuth !== void 0;
 	const relay = await startChiiRelay({
 		port: relayPort,
-		verifyAuth
+		verifyAuth: options.verifyAuth
 	});
 	logInfo("server.start", {
 		port: relay.port,
@@ -4102,18 +4175,18 @@ async function runDebugServer(options = {}) {
 	});
 	let tunnel = null;
 	let tunnelStatus = makeTunnelStatus(false, null);
-	generateAttachToken();
 	let tunnelProbe = null;
+	generateAttachToken();
 	startQuickTunnel(relay.port).then((t) => {
 		tunnel = t;
 		tunnelStatus = makeTunnelStatus(true, t.wssUrl);
-		lockHandle.updateWssUrl(t.wssUrl);
+		options.onWssUrl?.(t.wssUrl);
 		logInfo("tunnel.up", { totpEnabled });
 		tunnelProbe = startTunnelHealthProbe(t, relay.port, {
 			onReissue: (newTunnel) => {
 				tunnel = newTunnel;
 				tunnelStatus = makeTunnelStatus(true, newTunnel.wssUrl, null, 0);
-				lockHandle.updateWssUrl(newTunnel.wssUrl);
+				options.onWssUrl?.(newTunnel.wssUrl);
 				printAttachBanner({
 					wssUrl: newTunnel.wssUrl,
 					totpEnabled
@@ -4137,39 +4210,178 @@ async function runDebugServer(options = {}) {
 		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 = createRelayConnection(relay.baseUrl);
-	const aitSource = new ChiiAitSource(connection);
+	return {
+		connection,
+		getTunnelStatus: () => tunnelStatus,
+		stop() {
+			tunnelProbe?.stop();
+			tunnel?.stop();
+			connection.close();
+			relay.close();
+		}
+	};
+}
+/**
+* Production `ConnectionRouter` (issues #348, #356 — DUAL-CONNECTION-COEXIST).
+*
+* Holds two families — one booted eagerly at startup, the other lazily on the
+* first cross-family switch — an `active` pointer, and the single attach watcher
+* armed on the active connection. The router is **direction-neutral** (#356):
+* either family kind can be the eager one, so a `--target=local` session can
+* hot-switch into relay (and vice versa) without restarting the MCP server.
+*
+* `switchMode`:
+*   1. rejects re-entrant swaps (`swapInFlight`) and an unconfirmed relay-live;
+*   2. routes by the requested mode's family kind: same kind as `eager` → reuse
+*      eager; different kind → lazily boot (once) and keep warm;
+*   3. flips `active` (the MCP `Server` never re-handshakes — it reads through
+*      `active` per request);
+*   4. sets `liveIntent` (true only for relay-live);
+*   5. stops the old attach watcher and re-arms one on the new connection
+*      (the watcher self-clears, so re-arm is mandatory);
+*   6. emits `tools/list_changed`.
+*
+* Inactive infra is left WARM — teardown happens only at process exit (the
+* unified shutdown in the run functions), which is what keeps a phone attach
+* alive across a local→relay→local round trip.
+*/
+var DualConnectionRouter = class {
+	deps;
+	/** The opposite-kind family, booted lazily on the first cross-family switch. */
+	lazyFamily = null;
+	activeFamily;
+	server = null;
+	attachWatcher = null;
+	swapInFlight = false;
+	constructor(deps) {
+		this.deps = deps;
+		this.activeFamily = deps.eager;
+	}
+	get active() {
+		return this.activeFamily.connection;
+	}
+	/** Every booted family (for unified shutdown). */
+	bootedFamilies() {
+		return this.lazyFamily ? [this.deps.eager, this.lazyFamily] : [this.deps.eager];
+	}
+	/**
+	* Live tunnel status of the relay family, regardless of whether relay is the
+	* eager or lazy family (#356). Returns "down" until the relay family has been
+	* booted (local-eager sessions before the first relay switch) — which is the
+	* correct signal for `build_attach_url` (no tunnel exists yet).
+	*/
+	relayTunnelStatus() {
+		for (const family of this.bootedFamilies()) if (family.getTunnelStatus) return family.getTunnelStatus();
+		return {
+			up: false,
+			wssUrl: null
+		};
+	}
+	/**
+	* Binds the MCP `Server` and arms the initial attach watcher on the active
+	* connection. Called once after `createDebugServer` + `connect`.
+	*/
+	start(server) {
+		this.server = server;
+		this.armWatcher();
+	}
+	/** Stops the current attach watcher (for shutdown). */
+	stopWatcher() {
+		this.attachWatcher?.stop();
+		this.attachWatcher = null;
+	}
+	/** Arms a fresh attach watcher on the current active connection. */
+	armWatcher() {
+		const server = this.server;
+		if (!server) return;
+		this.attachWatcher = startAttachWatcher(this.activeFamily.connection, server, this.deps.attachWatcherIntervalMs ?? 1e3, () => {
+			this.deps.diagnosticsCollector.recordAttach();
+			if (this.activeFamily.connection.kind === "relay") this.deps.devtoolsOpener.open(this.relayTunnelStatus().wssUrl, deriveEnvironment(this.activeFamily.connection.kind, getLiveIntent()));
+		});
+	}
+	async switchMode(mode, confirm) {
+		if (this.swapInFlight) throw new Error("start_debug: 이전 전환이 아직 진행 중입니다 — 잠시 후 다시 호출하세요.");
+		if (mode === "relay-live" && !confirm) throw new Error("start_debug: relay-live(실서비스 LIVE)는 confirm: true가 필요합니다 — 실유저에게 영향이 갈 수 있는 LIVE 디버깅 진입을 명시적으로 승인하세요.");
+		this.swapInFlight = true;
+		try {
+			const wantRelay = isRelayMode(mode);
+			const wantKind = wantRelay ? "relay" : "local";
+			let target;
+			if (wantKind === this.deps.eager.connection.kind) target = this.deps.eager;
+			else {
+				if (this.lazyFamily === null) this.lazyFamily = await this.deps.bootLazy();
+				target = this.lazyFamily;
+			}
+			this.activeFamily = target;
+			setLiveIntent(mode === "relay-live");
+			this.stopWatcher();
+			this.armWatcher();
+			this.server?.sendToolListChanged();
+			return {
+				mode,
+				environment: deriveEnvironment(target.connection.kind, getLiveIntent()),
+				kind: target.connection.kind,
+				liveGuardActive: target.connection.kind === "relay" && getLiveIntent(),
+				nextStep: wantRelay ? "build_attach_url로 attach QR을 생성하세요 (relay 세션)." : "list_pages로 로컬 Chromium 페이지 attach를 확인하세요."
+			};
+		} finally {
+			this.swapInFlight = false;
+		}
+	}
+};
+/**
+* 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),
+*   2. open a cloudflared quick tunnel to the relay's confirmed port,
+*   3. print relay URL + attach instructions,
+*   4. expose the debug tools backed by a `ChiiCdpConnection` + `ChiiAitSource`.
+*/
+async function runDebugServer(options = {}) {
+	const lockHandle = acquireLock({ force: options.force ?? false });
+	const verifyAuth = buildRelayVerifyAuth();
+	const relayFamily = await bootRelayFamily({
+		relayPort: options.relayPort,
+		verifyAuth,
+		onWssUrl: (wssUrl) => lockHandle.updateWssUrl(wssUrl)
+	});
+	const devtoolsOpener = new AutoDevtoolsOpener();
+	const diagnosticsCollector = new InMemoryDiagnosticsCollector();
+	const router = new DualConnectionRouter({
+		eager: relayFamily,
+		bootLazy: bootLocalFamily,
+		diagnosticsCollector,
+		devtoolsOpener
+	});
+	const aitSource = new RoutingAitSource(() => {
+		return router.active;
+	});
 	let qrServer;
 	try {
 		qrServer = await startQrHttpServer();
 	} catch (err) {
 		logWarn("server.start", { msg: `QR HTTP 서버 시작 실패 (text QR fallback 사용): ${err instanceof Error ? err.message : String(err)}` });
 	}
-	const devtoolsOpener = new AutoDevtoolsOpener();
-	const diagnosticsCollector = new InMemoryDiagnosticsCollector();
 	const server = createDebugServer({
-		connection,
+		connection: router.active,
+		router,
 		aitSource,
-		getTunnelStatus: () => tunnelStatus,
+		getTunnelStatus: () => router.relayTunnelStatus(),
 		get qrHttpServer() {
 			return qrServer;
 		},
 		diagnosticsCollector,
-		defaultEnv: "relay-dev",
 		...process.env.AIT_DEBUG_TOTP_SECRET ? { totpSecret: process.env.AIT_DEBUG_TOTP_SECRET } : {}
 	});
 	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();
-		tunnel?.stop();
-		relay.close();
+		router.stopWatcher();
+		for (const family of router.bootedFamilies()) family.stop();
 		server.close();
 		qrServer?.close();
 		lockHandle.release();
@@ -4181,9 +4393,8 @@ async function runDebugServer(options = {}) {
 		if (!closed) {
 			closed = true;
 			parentWatcher?.stop();
-			attachWatcher?.stop();
-			tunnelProbe?.stop();
-			tunnel?.stop();
+			router.stopWatcher();
+			for (const family of router.bootedFamilies()) family.stop();
 			lockHandle.release();
 		}
 	});
@@ -4204,13 +4415,7 @@ async function runDebugServer(options = {}) {
 		process.exit(1);
 	});
 	await server.connect(transport);
-	attachWatcher = startAttachWatcher(connection, server, 1e3, () => {
-		diagnosticsCollector.recordAttach();
-		devtoolsOpener.open(tunnelStatus.wssUrl, getEnvironment({
-			connection,
-			defaultEnv: "relay-dev"
-		}));
-	});
+	router.start(server);
 	if (process.env.AIT_DEBUG_NO_PARENT_WATCH !== "1") {
 		parentWatcher = startParentWatcher(() => {
 			shutdown();
@@ -4230,19 +4435,28 @@ async function runDebugServer(options = {}) {
 * Boots the local-browser debug stack and serves it over stdio:
 *   1. launch a local Chromium with `--remote-debugging-port=<port>`,
 *   2. attach a `LocalCdpConnection` to the first non-blank page target,
-*   3. expose the debug tools backed by that connection + a `ChiiAitSource`.
-*
-* `build_attach_url` (relay-specific, generates a deep-link + QR for the phone)
-* is not applicable in local mode because there is no relay or tunnel. The tool
-* is still listed (it is part of `DEBUG_TOOL_DEFINITIONS`) but will return a
-* clear "not applicable" message via the tunnel-down path (wssUrl is null).
+*   3. expose the debug tools through the SAME direction-neutral
+*      `DualConnectionRouter` that `runDebugServer` uses (issue #356) — the
+*      local family is eager, the relay family is lazy-booted on the first
+*      `start_debug({ mode: 'relay-*' })`.
+*
+* Symmetry with `runDebugServer` (#356): starting with `--target=local` no
+* longer pins a single-connection router. A `--target=local` session can
+* hot-switch into relay (env 1 → env 3) without restarting the MCP server,
+* closing the asymmetry where only the default (relay-target) entry point had
+* bidirectional hot-switch. The intended fidelity-ladder flow — "validate in
+* env 1 (local), then env 3 (intoss-private) in ONE session, no restart" — now
+* works from either entry point.
+*
+* `build_attach_url` (relay-specific) stays effectively hidden / non-applicable
+* until the relay family is booted: before the first relay switch the env
+* derives to `mock` and `relayTunnelStatus()` reports "down", so the tool fails
+* with a clear "tunnel not up" message. After a relay switch the relay tunnel
+* is live and the tool works.
 *
 * The AIT.* tools (`AIT.getSdkCallHistory`, `AIT.getMockState`,
-* `AIT.getOperationalEnvironment`) ride the same CDP channel via
-* `ChiiAitSource` → `LocalCdpConnection.sendCommand`. They will succeed once
-* the sdk-example dev-bridge (`window.__sdkCall` install) lands in sdk-example;
-* until then they return the sdk-example "bridge absent" message — which is
-* expected and noted in the PR as an explicit out-of-scope follow-up.
+* `AIT.getOperationalEnvironment`) ride the *active* connection's CDP channel
+* via `RoutingAitSource`, so they follow `start_debug` swaps.
 */
 async function runLocalDebugServer(options = {}) {
 	const lockHandle = acquireLock({ force: options.force ?? false });
@@ -4251,30 +4465,57 @@ async function runLocalDebugServer(options = {}) {
 		devUrl: options.devUrl ?? process.env.AIT_DEVTOOLS_URL ?? "http://localhost:5173"
 	});
 	await new Promise((r) => setTimeout(r, 800));
-	const connection = new LocalCdpConnection({ devtoolsHttpUrl: chromium.devtoolsUrl });
-	const aitSource = new ChiiAitSource(connection);
-	const tunnelStatus = {
-		up: false,
-		wssUrl: null
+	const localConnection = new LocalCdpConnection({ devtoolsHttpUrl: chromium.devtoolsUrl });
+	const localFamily = {
+		connection: localConnection,
+		stop() {
+			localConnection.close();
+			chromium.stop();
+		}
 	};
+	const verifyAuth = buildRelayVerifyAuth();
+	const devtoolsOpener = new AutoDevtoolsOpener();
+	const diagnosticsCollector = new InMemoryDiagnosticsCollector();
+	const router = new DualConnectionRouter({
+		eager: localFamily,
+		bootLazy: () => bootRelayFamily({
+			verifyAuth,
+			onWssUrl: (wssUrl) => lockHandle.updateWssUrl(wssUrl)
+		}),
+		diagnosticsCollector,
+		devtoolsOpener
+	});
+	const aitSource = new RoutingAitSource(() => {
+		return router.active;
+	});
+	let qrServer;
+	try {
+		qrServer = await startQrHttpServer();
+	} catch (err) {
+		logWarn("server.start", { msg: `QR HTTP 서버 시작 실패 (text QR fallback 사용): ${err instanceof Error ? err.message : String(err)}` });
+	}
 	const server = createDebugServer({
-		connection,
+		connection: router.active,
+		router,
 		aitSource,
-		getTunnelStatus: () => tunnelStatus,
-		defaultEnv: "mock"
+		getTunnelStatus: () => router.relayTunnelStatus(),
+		get qrHttpServer() {
+			return qrServer;
+		},
+		diagnosticsCollector,
+		...process.env.AIT_DEBUG_TOTP_SECRET ? { totpSecret: process.env.AIT_DEBUG_TOTP_SECRET } : {}
 	});
 	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();
+		router.stopWatcher();
+		for (const family of router.bootedFamilies()) family.stop();
 		server.close();
+		qrServer?.close();
 		lockHandle.release();
 	};
 	process.once("SIGINT", shutdown);
@@ -4284,8 +4525,8 @@ async function runLocalDebugServer(options = {}) {
 		if (!closed) {
 			closed = true;
 			parentWatcher?.stop();
-			attachWatcher?.stop();
-			chromium.stop();
+			router.stopWatcher();
+			for (const family of router.bootedFamilies()) family.stop();
 			lockHandle.release();
 		}
 	});
@@ -4308,7 +4549,7 @@ async function runLocalDebugServer(options = {}) {
 		process.exit(1);
 	});
 	await server.connect(transport);
-	attachWatcher = startAttachWatcher(connection, server);
+	router.start(server);
 	if (process.env.AIT_DEBUG_NO_PARENT_WATCH !== "1") {
 		parentWatcher = startParentWatcher(() => {
 			shutdown();
@@ -4752,7 +4993,7 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.51"
+		version: "0.1.53"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -4836,9 +5077,29 @@ async function runDevServer() {
 *   --mode=dev — dev mode — reads the live browser mock state from a running
 *     Vite dev server (the devtools#130 `devtools_get_mock_state` surface).
 *
+* Back-compat (issue #348): the legacy `--mode`/`--target` flags and `MCP_ENV`
+* still work. `--target=relay`/`local` select the initial active connection;
+* the in-session `start_debug(mode)` MCP tool can then flip between them with no
+* restart. `MCP_ENV=relay-live` seeds LIVE intent at boot (deprecated alias);
+* `MCP_ENV=mock|relay|relay-dev` are accepted and ignored for env derivation
+* (the active connection's `kind` is authoritative).
+*
 * Node-only stdio process.
 */
 /**
+* Seeds the module-level `liveIntent` bit from the deprecated `MCP_ENV` alias
+* (issue #348). `MCP_ENV=relay-live` is the only value that matters now — it
+* arms LIVE intent at boot so a session launched straight into env 4 has the
+* guard active without a `start_debug({ mode: 'relay-live' })` round-trip. All
+* other `MCP_ENV` values (`mock`, `relay`, `relay-dev`) are accepted-and-ignored
+* for env derivation — the active connection's `kind` is authoritative.
+*
+* SECRET-HANDLING: reads only the env-var string; never logs a secret.
+*/
+function seedLiveIntentFromEnv(env = process.env) {
+	if (env.MCP_ENV === "relay-live") setLiveIntent(true);
+}
+/**
 * Returns `true` when `--force` or `--takeover` is present in argv.
 *
 * Both flags are accepted as aliases — `--force` is the short form listed in
@@ -4893,6 +5154,7 @@ function normalizeTarget(value) {
 }
 async function main() {
 	const args = process.argv.slice(2);
+	seedLiveIntentFromEnv();
 	if (parseMode(args) === "dev") await runDevServer();
 	else {
 		const target = parseTarget(args);
@@ -4926,6 +5188,6 @@ if (isEntrypoint()) main().catch((err) => {
 	process.exitCode = 1;
 });
 //#endregion
-export { parseForce, parseMode, parseTarget };
+export { parseForce, parseMode, parseTarget, seedLiveIntentFromEnv };
 
 //# sourceMappingURL=cli.js.map