execbro 2.3.0 → 2.5.0

package/build/core/connection.js

@@ -11,26 +11,13 @@ import { scheduleAppDetection } from "./appDetection.js";
 import { markConnectionEstablished } from "./jsExecute.js";
 import { startSdkMirrorPoller, stopSdkMirrorPoller } from "./sdkMirrorPoller.js";
 import { DEFAULT_RECONNECTION_CONFIG, MIN_STABLE_CONNECTION_MS, initConnectionState, updateConnectionState, getConnectionState, recordConnectionGap, closeConnectionGap, saveConnectionMetadata, clearConnectionMetadata, getConnectionMetadata, saveReconnectionTimer, cancelReconnectionTimer, calculateBackoffDelay, initContextHealth, markContextHealthy, markContextStale, getContextHealth, updateContextHealth, formatDuration, recordConnectionEvent, } from "./connectionState.js";
-// Connection locks to prevent concurrent connection attempts to the same device
 const connectionLocks = new Set();
-// Last CDP target id seen per device name, used to detect app relaunches.
 const lastTargetIdByDevice = new Map();
-// Track Network.enable message IDs to detect CDP network support
 const pendingNetworkEnableIds = new Set();
-// Track SDK-probe message IDs so we can decode their responses and set
-// app.sdkPresent. The probe runs on connect and then periodically because
-// the SDK's init() may execute after we attach.
-const pendingSdkProbeIds = new Map(); // msgId -> appKey
+const pendingSdkProbeIds = new Map();
 const SDK_PROBE_INITIAL_DELAY_MS = 200;
 const SDK_PROBE_INTERVAL_MS = 3000;
-// Consecutive SDK-absent probes required to flip sdkPresent true→false.
-// Hysteresis against the post-reload window where the JS context exists but
-// the SDK's init() hasn't re-run yet (see ConnectedApp.sdkMissCount).
 const SDK_ABSENCE_CONFIRM_COUNT = 2;
-// Fast re-probe schedule after a context is (re)created, so the SDK is
-// re-detected within a few hundred ms instead of waiting up to a full
-// SDK_PROBE_INTERVAL_MS tick. Covers reloads not driven by reload_app
-// (shake-to-reload, Metro "r").
 const SDK_REPROBE_DELAYS_MS = [200, 500, 1000, 2000];
 function sendSdkProbe(ws, appKey) {
     if (ws.readyState !== WebSocket.OPEN)
@@ -65,16 +52,11 @@ function startSdkProbeLoop(ws, appKey) {
     if (app) {
         app.sdkProbeTimer = interval;
     }
-    // Best-effort cleanup if the socket closes before the initial probe fires
     ws.once("close", () => {
         clearTimeout(initial);
         clearInterval(interval);
     });
 }
-// Fire a burst of SDK probes on the heels of a (re)created execution context.
-// After a reload the context is recreated but the SDK's init() re-runs slightly
-// later; without this, sdkPresent only recovers on the next 3s interval tick,
-// widening the window where get_network_requests falls off the SDK buffer.
 function scheduleFastSdkReprobe(ws, appKey) {
     for (const delay of SDK_REPROBE_DELAYS_MS) {
         const t = setTimeout(() => {
@@ -85,48 +67,24 @@ function scheduleFastSdkReprobe(ws, appKey) {
         ws.once("close", () => clearTimeout(t));
     }
 }
-// Suppress auto-reconnection for intentionally disconnected devices
 const reconnectionSuppressed = new Set();
-/**
- * Suppress auto-reconnection for all current connections.
- * Used by disconnect_metro to prevent close handlers from re-connecting.
- */
 export function suppressReconnection() {
     for (const key of connectedApps.keys()) {
         reconnectionSuppressed.add(key);
     }
 }
-/**
- * Suppress auto-reconnection for a specific connection key.
- * Used by disconnect_metro with device targeting.
- */
 export function suppressReconnectionForKey(appKey) {
     reconnectionSuppressed.add(appKey);
 }
-/**
- * Clear reconnection suppression (called when user explicitly reconnects via scan_metro).
- */
 export function clearReconnectionSuppression() {
     reconnectionSuppressed.clear();
 }
 const STALE_ACTIVITY_THRESHOLD_MS = 30_000;
-const PING_INTERVAL_MS = 1_000; // WebSocket ping/pong keepalive interval
-/**
- * Max time (ms) to wait for a Runtime.evaluate("1+1") reply during liveness probing.
- * Tight budget: live targets respond in under 50ms; zombie CDP targets never respond.
- */
+const PING_INTERVAL_MS = 1_000;
 const PROBE_TIMEOUT_MS = 1500;
 const RECONNECT_SETTLE_MS = 500;
-/**
- * Creates a WebSocket connection with Origin header fallback.
- * RN 0.85+ Metro requires the Origin header, but Expo SDK 55 Bridgeless
- * rejects connections that include one. The rejection can manifest as:
- *   - Connection refused before open (error/close before open event)
- *   - Immediate close after open (open fires, then close with code 1006)
- * Tries with Origin first, falls back to without on quick failure.
- */
 export function createWebSocketWithOriginFallback(url, timeoutMs = 5000) {
-    const STABILIZE_MS = 500; // Wait after open to detect immediate close
+    const STABILIZE_MS = 500;
     return new Promise((resolve, reject) => {
         const wsUrl = new URL(url);
         const origin = `http://${wsUrl.hostname}:${wsUrl.port}`;
@@ -138,7 +96,6 @@ export function createWebSocketWithOriginFallback(url, timeoutMs = 5000) {
             ws.on("open", () => {
                 opened = true;
                 if (withOrigin) {
-                    // Wait briefly to detect immediate close (Expo SDK 55 pattern)
                     setTimeout(() => {
                         if (settled)
                             return;
@@ -147,7 +104,6 @@ export function createWebSocketWithOriginFallback(url, timeoutMs = 5000) {
                             console.error("[execbro] WebSocket connected with Origin header");
                             resolve(ws);
                         }
-                        // If not OPEN, the close handler will trigger fallback
                     }, STABILIZE_MS);
                 }
                 else {
@@ -185,7 +141,6 @@ export function createWebSocketWithOriginFallback(url, timeoutMs = 5000) {
         }, timeoutMs);
     });
 }
-// Helper to find appKey from device info by searching connectedApps
 function findAppKeyForDevice(device) {
     for (const [key, app] of connectedApps.entries()) {
         if (app.deviceInfo.id === device.id) {
@@ -194,7 +149,6 @@ function findAppKeyForDevice(device) {
     }
     return null;
 }
-// Helper to convert WebSocket readyState to readable name
 export function getWebSocketStateName(state) {
     switch (state) {
         case WebSocket.CONNECTING: return "CONNECTING";
@@ -204,24 +158,13 @@ export function getWebSocketStateName(state) {
         default: return `UNKNOWN(${state})`;
     }
 }
-/**
- * Purge stale connections for scanned ports.
- * When Metro restarts with a different app, /json returns new device IDs.
- * Old connections keyed by the previous device IDs remain in connectedApps.
- * This function removes connections on scanned ports whose device IDs
- * are no longer present in the fresh device list from Metro.
- */
 export function purgeStaleConnectionsForPorts(freshDevicesByPort) {
     const purged = [];
     const scannedPorts = new Set(freshDevicesByPort.keys());
     for (const [appKey, app] of connectedApps.entries()) {
-        // Only check connections on ports we just scanned
         if (!scannedPorts.has(app.port))
             continue;
         const freshDevices = freshDevicesByPort.get(app.port) || [];
-        // Check both device ID and appId — device IDs are per-physical-device
-        // (stable across Metro restarts), so a different app on the same device
-        // would have the same ID but a different appId
         const matchingDevice = freshDevices.find(d => d.id === app.deviceInfo.id);
         const stillValid = matchingDevice && matchingDevice.appId === app.deviceInfo.appId;
         if (!stillValid) {
@@ -230,7 +173,6 @@ export function purgeStaleConnectionsForPorts(freshDevicesByPort) {
                 ? "device no longer in Metro /json"
                 : `appId changed: ${app.deviceInfo.appId} → ${matchingDevice.appId}`;
             console.error(`[execbro] Purging stale connection: ${name} (port ${app.port}, id ${app.deviceInfo.id}) — ${reason}`);
-            // Suppress reconnection so close handler doesn't try to reconnect
             reconnectionSuppressed.add(appKey);
             cancelReconnectionTimer(appKey);
             clearLastCDPMessageTime(appKey);
@@ -238,14 +180,13 @@ export function purgeStaleConnectionsForPorts(freshDevicesByPort) {
             try {
                 app.ws.close();
             }
-            catch { /* ignore */ }
+            catch { }
             connectedApps.delete(appKey);
             purged.push(name);
         }
     }
     return purged;
 }
-// Format CDP RemoteObject to readable string
 export function formatRemoteObject(result) {
     if (result.type === "undefined") {
         return "undefined";
@@ -253,44 +194,31 @@ export function formatRemoteObject(result) {
     if (result.subtype === "null") {
         return "null";
     }
-    // For objects/arrays with a value, stringify it
     if (result.value !== undefined) {
         if (typeof result.value === "object") {
             return JSON.stringify(result.value, null, 2);
         }
         return String(result.value);
     }
-    // Use description for complex objects
     if (result.description) {
         return result.description;
     }
-    // Handle unserializable values (NaN, Infinity, etc.)
     if (result.unserializableValue) {
         return result.unserializableValue;
     }
     return `[${result.type}${result.subtype ? ` ${result.subtype}` : ""}]`;
 }
-/**
- * Extract a clean, informative error message from CDP exception details
- * Handles various error formats from Hermes and other JS engines
- */
 function extractExceptionMessage(exceptionDetails) {
     const parts = [];
-    // Get the exception object if available
     const exc = exceptionDetails.exception;
     if (exc) {
-        // For error objects, className tells us the error type (ReferenceError, TypeError, etc.)
         const errorType = exc.className || (exc.subtype === 'error' ? 'Error' : '');
-        // The description usually contains "ErrorType: message" or full stack trace
-        // We want to extract just the first line (the actual error message)
         if (exc.description) {
             const firstLine = exc.description.split('\n')[0].trim();
-            // If description already includes the error type, use it directly
             if (firstLine.includes(':')) {
                 parts.push(firstLine);
             }
             else if (errorType) {
-                // Combine error type with description
                 parts.push(`${errorType}: ${firstLine}`);
             }
             else {
@@ -298,7 +226,6 @@ function extractExceptionMessage(exceptionDetails) {
             }
         }
         else if (exc.value !== undefined) {
-            // For primitive exceptions (throw "string" or throw 123)
             const valueStr = typeof exc.value === 'string' ? exc.value : JSON.stringify(exc.value);
             if (errorType) {
                 parts.push(`${errorType}: ${valueStr}`);
@@ -308,32 +235,25 @@ function extractExceptionMessage(exceptionDetails) {
             }
         }
         else if (errorType) {
-            // Just the error type, no message
             parts.push(errorType);
         }
     }
-    // Fall back to exceptionDetails.text if we couldn't extract from exception object
-    // But avoid just "Uncaught" which is not helpful
     if (parts.length === 0) {
         const text = exceptionDetails.text;
         if (text && text.toLowerCase() !== 'uncaught') {
             parts.push(text);
         }
     }
-    // Add location info for syntax/compilation errors (helps identify the problem)
     if (exceptionDetails.lineNumber !== undefined && exceptionDetails.columnNumber !== undefined) {
-        // Only add location if it's meaningful (not 0:0 which is often just wrapper)
         if (exceptionDetails.lineNumber > 0 || exceptionDetails.columnNumber > 0) {
             parts.push(`at line ${exceptionDetails.lineNumber}:${exceptionDetails.columnNumber}`);
         }
     }
-    // If we still have nothing, provide a generic message
     if (parts.length === 0) {
         return 'JavaScript execution failed (no error details available)';
     }
     return parts.join(' ');
 }
-// Format a CDP object preview recursively
 function formatPreview(preview) {
     const isArray = preview.subtype === "array";
     const props = preview.properties || [];
@@ -358,40 +278,32 @@ function formatPreview(preview) {
         ? `[${formatted.join(", ")}${overflow}]`
         : `{${formatted.join(", ")}${overflow}}`;
 }
-// Format a single CDP console argument (sync — without object resolution)
 function formatConsoleArg(arg) {
-    // Explicit undefined (matches browser: console.log(undefined) → "undefined")
     if (arg.type === "undefined") {
         return "undefined";
     }
-    // Primitives
     if (arg.type === "string" || arg.type === "number" || arg.type === "boolean") {
         return String(arg.value);
     }
-    // Objects/arrays with preview — expand inline
     if (arg.preview?.properties) {
         return formatPreview(arg.preview);
     }
-    // Raw value (e.g. null sent as value)
     if (arg.value !== undefined) {
         return JSON.stringify(arg.value);
     }
-    // Description fallback (functions, symbols, errors without preview)
     if (arg.description) {
         return arg.description;
     }
-    // Object without any resolved data
     if (arg.type === "object") {
         return "[Object]";
     }
     return `[${arg.type || "unknown"}]`;
 }
-// Fetch object properties via CDP Runtime.getProperties
 function fetchObjectProperties(ws, objectId, depth = 2) {
     return new Promise((resolve) => {
         const msgId = getNextMessageId();
         const timeout = setTimeout(() => {
-            resolve("Object"); // Fallback on timeout
+            resolve("Object");
         }, 3000);
         const handler = (data) => {
             try {
@@ -408,7 +320,6 @@ function fetchObjectProperties(ws, objectId, depth = 2) {
                 }
             }
             catch {
-                // Ignore parse errors
             }
         };
         ws.on("message", handler);
@@ -419,11 +330,9 @@ function fetchObjectProperties(ws, objectId, depth = 2) {
         }));
     });
 }
-// Format CDP property descriptors into a readable string
 async function formatCDPProperties(ws, properties, depth) {
     const parts = [];
     let isArrayLike = false;
-    // Detect arrays by checking for numeric keys and "length" property
     const propNames = properties.filter((p) => !p.isAccessor && p.name !== "__proto__").map((p) => p.name);
     const hasLength = propNames.includes("length");
     const numericKeys = propNames.filter((n) => /^\d+$/.test(n));
@@ -447,7 +356,6 @@ async function formatCDPProperties(ws, properties, depth) {
         ? `[${parts.join(", ")}]`
         : `{${parts.join(", ")}}`;
 }
-// Format a single property value
 async function formatPropertyValue(ws, val, remainingDepth) {
     const type = val.type;
     const subtype = val.subtype;
@@ -461,11 +369,9 @@ async function formatPropertyValue(ws, val, remainingDepth) {
         return String(val.value);
     if (type === "function")
         return "[Function]";
-    // Nested object — recurse if depth allows
     if (type === "object" && val.objectId && remainingDepth > 0) {
         return fetchObjectProperties(ws, val.objectId, remainingDepth);
     }
-    // Object but no depth left — use description
     if (type === "object") {
         return val.description || "[Object]";
     }
@@ -475,26 +381,20 @@ async function formatPropertyValue(ws, val, remainingDepth) {
         return val.description;
     return `[${type}]`;
 }
-// Resolve all object args in a console message, returning formatted text
 async function resolveConsoleArgs(ws, args) {
     const parts = await Promise.all(args.map(async (arg) => {
-        // Primitives — format synchronously
         if (arg.type === "string" || arg.type === "number" || arg.type === "boolean") {
             return String(arg.value);
         }
-        // Objects/arrays with preview — expand inline
         if (arg.preview?.properties) {
             return formatPreview(arg.preview);
         }
-        // Object with objectId — fetch properties via CDP
         if (arg.type === "object" && arg.objectId) {
             return fetchObjectProperties(ws, arg.objectId);
         }
-        // Raw value
         if (arg.value !== undefined) {
             return JSON.stringify(arg.value);
         }
-        // Description fallback
         if (arg.description) {
             return arg.description;
         }
@@ -502,24 +402,19 @@ async function resolveConsoleArgs(ws, args) {
     }));
     return parts.join(" ");
 }
-// Handle CDP messages
 export function handleCDPMessage(message, device, ws) {
-    // Track last CDP activity for connection liveness detection (per-device)
     const cdpAppKey = findAppKeyForDevice(device);
     if (cdpAppKey) {
         updateLastCDPMessageTime(cdpAppKey, new Date());
     }
     const deviceName = device.deviceName || device.title || "unknown";
-    // Handle responses to our requests (e.g., Runtime.evaluate)
     if (typeof message.id === "number") {
         const pending = pendingExecutions.get(message.id);
         if (pending) {
             clearTimeout(pending.timeoutId);
             pendingExecutions.delete(message.id);
-            // Check for CDP-level error (protocol error, not JS exception)
             if (message.error) {
                 const error = message.error;
-                // Build comprehensive error message including code and data if available
                 const parts = [];
                 if (error.message)
                     parts.push(error.message);
@@ -531,21 +426,18 @@ export function handleCDPMessage(message, device, ws) {
                 pending.resolve({ success: false, error: errorMessage });
                 return;
             }
-            // Check for JavaScript exception in result
             const result = message.result;
             if (result?.exceptionDetails) {
                 const errorMessage = extractExceptionMessage(result.exceptionDetails);
                 pending.resolve({ success: false, error: errorMessage });
                 return;
             }
-            // Success - format the result
             if (result?.result) {
                 pending.resolve({ success: true, result: formatRemoteObject(result.result) });
                 return;
             }
             pending.resolve({ success: true, result: "undefined" });
         }
-        // Track SDK-probe responses
         if (pendingSdkProbeIds.has(message.id)) {
             const appKey = pendingSdkProbeIds.get(message.id);
             pendingSdkProbeIds.delete(message.id);
@@ -554,15 +446,11 @@ export function handleCDPMessage(message, device, ws) {
                 const result = message.result?.result;
                 const present = result?.value === true;
                 const wasPresent = app.sdkPresent === true;
-                // Hysteresis on the true→false edge: tolerate transient SDK
-                // absence right after a reload (context recreated, init() not
-                // re-run yet) so we don't restore duplicate-prone CDP/interceptor
-                // writes and bounce get_network_requests off the SDK buffer.
                 let nextPresent = present;
                 if (!present && wasPresent) {
                     app.sdkMissCount = (app.sdkMissCount ?? 0) + 1;
                     if (app.sdkMissCount < SDK_ABSENCE_CONFIRM_COUNT) {
-                        nextPresent = true; // hold "present" until absence is confirmed
+                        nextPresent = true;
                     }
                     else {
                         app.sdkMissCount = 0;
@@ -574,9 +462,6 @@ export function handleCDPMessage(message, device, ws) {
                 app.sdkPresent = nextPresent;
                 if (nextPresent !== wasPresent) {
                     console.error(`[execbro] SDK ${present ? "detected" : "no longer detected"} on ${app.deviceInfo.title}; CDP/JS-interceptor buffer writes ${present ? "suppressed" : "restored"}`);
-                    // Toggle the in-app interceptor's emit flag so it stops
-                    // (or resumes) producing console.debug lines and CDP
-                    // traffic. Fire-and-forget — the flag is idempotent.
                     if (app.ws.readyState === WebSocket.OPEN) {
                         try {
                             app.ws.send(JSON.stringify({
@@ -589,14 +474,12 @@ export function handleCDPMessage(message, device, ws) {
                             }));
                         }
                         catch {
-                            // ignore — next probe will retry
                         }
                     }
                 }
             }
             return;
         }
-        // Track Network.enable responses to detect CDP network support
         if (pendingNetworkEnableIds.has(message.id)) {
             pendingNetworkEnableIds.delete(message.id);
             const nAppKey = findAppKeyForDevice(device);
@@ -617,29 +500,22 @@ export function handleCDPMessage(message, device, ws) {
         return;
     }
     const method = message.method;
-    // Handle Runtime.consoleAPICalled
     if (method === "Runtime.consoleAPICalled") {
         const params = message.params;
         const type = params.type || "log";
         const level = mapConsoleType(type);
         const args = params.args || [];
-        // Check for network interceptor events before processing as logs
         const interceptorJson = isInterceptorEvent(args);
         if (interceptorJson !== null) {
             const iAppKey = findAppKeyForDevice(device);
             const iApp = iAppKey ? connectedApps.get(iAppKey) : null;
-            // Skip when CDP Network domain is the source, OR when the in-app
-            // SDK is the source — both would otherwise produce duplicate
-            // entries for every request.
             if (!iApp?.cdpNetworkSupported && !iApp?.sdkPresent) {
                 applyInterceptedEvent(interceptorJson, getNetworkBuffer(deviceName), deviceName);
             }
             return;
         }
-        // Check if any args need async object resolution
         const hasObjectArgs = ws && args.some((a) => a.type === "object" && a.objectId && !a.preview?.properties);
         if (hasObjectArgs) {
-            // Resolve object args asynchronously via CDP
             resolveConsoleArgs(ws, args).then((messageText) => {
                 getLogBuffer(deviceName).add({
                     timestamp: new Date(),
@@ -648,7 +524,6 @@ export function handleCDPMessage(message, device, ws) {
                     args: args.map((a) => a.value)
                 });
             }).catch(() => {
-                // Fallback to sync formatting on error
                 const messageText = args.map(formatConsoleArg).join(" ");
                 getLogBuffer(deviceName).add({
                     timestamp: new Date(),
@@ -670,7 +545,6 @@ export function handleCDPMessage(message, device, ws) {
             }
         }
     }
-    // Handle Log.entryAdded
     if (method === "Log.entryAdded") {
         const params = message.params;
         if (params.entry) {
@@ -682,24 +556,12 @@ export function handleCDPMessage(message, device, ws) {
             });
         }
     }
-    // Handle Network.requestWillBeSent
     if (method === "Network.requestWillBeSent") {
-        // Skip CDP capture when the in-app SDK is the source of truth —
-        // otherwise every request lands in both buffers under different ids.
-        // The follow-up Network.responseReceived/loadingFinished/loadingFailed
-        // handlers below only mutate existing entries, so they self-skip.
         const nAppKey = findAppKeyForDevice(device);
         const nApp = nAppKey ? connectedApps.get(nAppKey) : null;
         if (nApp?.sdkPresent) {
             return;
         }
-        // An arriving Network.requestWillBeSent is proof the CDP Network domain
-        // is active. Some backends (e.g. RN 0.85 Bridgeless/Hermes) enable the
-        // domain but never send a response to Network.enable, so the
-        // response-based detection above never fires and cdpNetworkSupported
-        // stays undefined — leaving the JS interceptor un-suppressed and every
-        // request double-captured (CDP + interceptor). Mark support here so the
-        // interceptor dedup guard (see Runtime.consoleAPICalled handler) trips.
         if (nApp && !nApp.cdpNetworkSupported) {
             nApp.cdpNetworkSupported = true;
             console.error(`[execbro] CDP Network domain active (detected via requestWillBeSent on ${nApp.deviceInfo.title})`);
@@ -720,7 +582,6 @@ export function handleCDPMessage(message, device, ws) {
         };
         getNetworkBuffer(deviceName).set(params.requestId, request);
     }
-    // Handle Network.responseReceived
     if (method === "Network.responseReceived") {
         const params = message.params;
         const existing = getNetworkBuffer(deviceName).get(params.requestId);
@@ -735,7 +596,6 @@ export function handleCDPMessage(message, device, ws) {
             getNetworkBuffer(deviceName).set(params.requestId, existing);
         }
     }
-    // Handle Network.loadingFinished
     if (method === "Network.loadingFinished") {
         const params = message.params;
         const existing = getNetworkBuffer(deviceName).get(params.requestId);
@@ -748,7 +608,6 @@ export function handleCDPMessage(message, device, ws) {
             getNetworkBuffer(deviceName).set(params.requestId, existing);
         }
     }
-    // Handle Network.loadingFailed
     if (method === "Network.loadingFailed") {
         const params = message.params;
         const existing = getNetworkBuffer(deviceName).get(params.requestId);
@@ -758,54 +617,39 @@ export function handleCDPMessage(message, device, ws) {
             getNetworkBuffer(deviceName).set(params.requestId, existing);
         }
     }
-    // Handle Runtime context lifecycle events for health tracking
     const appKey = findAppKeyForDevice(device);
     if (appKey) {
-        // Handle Runtime.executionContextCreated
         if (method === "Runtime.executionContextCreated") {
             const params = message.params;
             markContextHealthy(appKey, params.context.id);
             console.error(`[execbro] Context created: ${params.context.id}`);
-            // Re-inject network interceptor and re-check CDP Network support
             const ctxApp = connectedApps.get(appKey);
             if (ctxApp?.ws?.readyState === WebSocket.OPEN) {
                 injectNetworkInterceptor(ctxApp.ws);
                 const nEnableId = sendNetworkEnable(ctxApp.ws);
                 pendingNetworkEnableIds.add(nEnableId);
-                // The context was just recreated (e.g. reload). Re-probe the SDK
-                // quickly so sdkPresent re-establishes within a few hundred ms
-                // instead of on the next 3s interval tick.
                 scheduleFastSdkReprobe(ctxApp.ws, appKey);
             }
         }
-        // Handle Runtime.executionContextDestroyed
         if (method === "Runtime.executionContextDestroyed") {
             markContextStale(appKey);
             console.error(`[execbro] Context destroyed`);
         }
-        // Handle Runtime.executionContextsCleared
         if (method === "Runtime.executionContextsCleared") {
             markContextStale(appKey);
-            // A replaced JS runtime starts a new app run. Bump so pre-restart
-            // entries stay addressable and readers can draw the boundary.
             const clearedDevice = device.deviceName || device.title || "unknown";
             const nextEpoch = bumpEpoch(clearedDevice);
             console.error(`[execbro] All contexts cleared — ${clearedDevice} now epoch ${nextEpoch}`);
         }
     }
 }
-// Connect to a device via CDP WebSocket
 export async function connectToDevice(device, port, options = {}) {
     const { isReconnection = false, reconnectionConfig = DEFAULT_RECONNECTION_CONFIG } = options;
     return new Promise(async (resolve, reject) => {
         const appKey = `${port}-${device.id}`;
-        // Check if already connected with a valid WebSocket
         const existingApp = connectedApps.get(appKey);
         if (existingApp) {
             if (existingApp.ws.readyState === WebSocket.OPEN) {
-                // Verify WebSocket is actually alive with a ping/pong check.
-                // readyState can show OPEN even when the remote end is gone
-                // (TCP hasn't timed out yet, especially after Metro restart).
                 const isAlive = await new Promise((pongResolve) => {
                     const timeout = setTimeout(() => pongResolve(false), 2000);
                     existingApp.ws.once("pong", () => {
@@ -824,26 +668,22 @@ export async function connectToDevice(device, port, options = {}) {
                     resolve(`Already connected to ${device.title}`);
                     return;
                 }
-                // Ping failed — connection is dead, clean up
                 console.error(`[execbro] Existing connection to ${device.title} failed liveness check (no pong), reconnecting`);
                 recordConnectionEvent("liveness-failed", appKey, device.title, "no pong within 2000ms");
                 reconnectionSuppressed.add(appKey);
                 try {
                     existingApp.ws.terminate();
                 }
-                catch { /* ignore */ }
+                catch { }
                 connectedApps.delete(appKey);
                 clearLastCDPMessageTime(appKey);
                 clearActiveSimulatorIfSource(appKey);
             }
             else {
-                // WebSocket exists but not OPEN - clean up stale entry
                 console.error(`[execbro] Cleaning up stale connection for ${device.title} (state: ${getWebSocketStateName(existingApp.ws.readyState)})`);
                 connectedApps.delete(appKey);
             }
         }
-        // Skip if this device is already connected on a different port
-        // (Metro's /json advertises all devices it can see, even ones built by other Metro servers)
         const deviceName = device.deviceName || device.title;
         for (const [existingKey, existingApp] of connectedApps.entries()) {
             if (existingKey !== appKey && existingApp.ws.readyState === WebSocket.OPEN) {
@@ -854,15 +694,12 @@ export async function connectToDevice(device, port, options = {}) {
                 }
             }
         }
-        // Prevent concurrent connection attempts to the same device
         if (connectionLocks.has(appKey)) {
             resolve(`Connection already in progress for ${device.title}`);
             return;
         }
         connectionLocks.add(appKey);
-        // Cancel any pending reconnection timer for this appKey
         cancelReconnectionTimer(appKey);
-        // Save connection metadata for potential reconnection
         saveConnectionMetadata(appKey, {
             port,
             deviceInfo: device,
@@ -870,53 +707,34 @@ export async function connectToDevice(device, port, options = {}) {
         });
         try {
             const ws = await createWebSocketWithOriginFallback(device.webSocketDebuggerUrl);
-            // Register close/error handlers IMMEDIATELY — before any async work
-            // below (probeCdpAlive, Runtime.enable, simctl/adb lookups). Previously
-            // they were attached only at the end of the setup block, so any close
-            // event during that window was silently swallowed: the entry stayed
-            // in connectedApps, readyState flipped to CLOSED, but no reconnect
-            // was scheduled and no `closed` event was recorded.
             let pingInterval = null;
             let staleRejected = false;
             const handleClose = () => {
                 if (staleRejected)
-                    return; // probe-fail path handles its own cleanup
+                    return;
                 if (pingInterval) {
                     clearInterval(pingInterval);
                     pingInterval = null;
                 }
-                // Fail anything still in flight on this socket. Otherwise each
-                // call parks until its own timeoutMs and then reports a generic
-                // "Expression took too long", which classifies as logical and
-                // never triggers auto-reconnect.
                 const failedCount = failPendingExecutionsForSocket(ws, "WebSocket connection is not open.");
                 if (failedCount > 0) {
                     console.error(`[execbro] Failed ${failedCount} in-flight call(s) on closed socket for ${device.title}`);
                 }
-                // Release connection lock if still held
                 connectionLocks.delete(appKey);
-                // Stop mirroring — the socket is gone, so every tick would just
-                // fail. No drain attempt here: there is nothing left to read.
                 stopSdkMirrorPoller(device.deviceName || device.title || "unknown");
                 connectedApps.delete(appKey);
                 clearLastCDPMessageTime(appKey);
-                // Clear active simulator UDID if this connection set it
                 clearActiveSimulatorIfSource(appKey);
-                // Keep log and network buffers across reconnections
-                // They are only cleared on demand via clear_logs / clear_network tools
-                // Check if connection was stable before resetting attempts
                 const state = getConnectionState(appKey);
                 let wasStable = false;
                 if (state?.lastConnectedTime) {
                     const connectionDuration = Date.now() - state.lastConnectedTime.getTime();
                     wasStable = connectionDuration >= MIN_STABLE_CONNECTION_MS;
                     if (wasStable) {
-                        // Connection was stable - reset attempts for fresh start
                         updateConnectionState(appKey, { reconnectionAttempts: 0 });
                         console.error(`[execbro] Connection was stable for ${Math.round(connectionDuration / 1000)}s, resetting reconnection attempts`);
                     }
                 }
-                // Record the gap and trigger reconnection
                 recordConnectionGap(appKey, "Connection closed");
                 if (state) {
                     updateConnectionState(appKey, {
@@ -928,11 +746,7 @@ export async function connectToDevice(device, port, options = {}) {
                 const earlyPhase = state ? "" : " (before state init)";
                 console.error(`[execbro] Disconnected from ${device.title}${earlyPhase}`);
                 recordConnectionEvent("closed", appKey, device.title, `uptime ${formatDuration(uptimeMs)}${wasStable ? " (stable)" : " (unstable)"}${earlyPhase}`);
-                // Schedule auto-reconnection if enabled (skip if intentionally disconnected)
                 if (reconnectionConfig.enabled && !reconnectionSuppressed.has(appKey)) {
-                    // If close fired before initConnectionState, scheduleReconnection
-                    // would early-return (it requires existing state). Init it now
-                    // so the reconnect loop can still run.
                     if (!state)
                         initConnectionState(appKey);
                     scheduleReconnection(appKey, reconnectionConfig);
@@ -950,10 +764,6 @@ export async function connectToDevice(device, port, options = {}) {
             ws.on("error", (error) => {
                 console.error(`[execbro] WebSocket error for ${device.title}: ${error?.message || error}`);
             });
-            // Verify the JS context is actually alive. Metro's /json can advertise
-            // zombie CDP pages that complete the WS handshake but no longer execute.
-            // A stale target here causes every downstream tool to time out or return
-            // degenerate state (e.g. __DEV__ === false on a debug bundle).
             const alive = await probeCdpAlive(ws, PROBE_TIMEOUT_MS);
             if (!alive) {
                 staleRejected = true;
@@ -962,41 +772,29 @@ export async function connectToDevice(device, port, options = {}) {
                 try {
                     ws.terminate();
                 }
-                catch { /* ignore */ }
+                catch { }
                 clearConnectionMetadata(appKey);
                 console.error(`[execbro] Rejecting stale CDP target for ${device.title} (no probe response)`);
                 recordConnectionEvent("stale-target", appKey, device.title, `no probe response within ${PROBE_TIMEOUT_MS}ms${isReconnection ? " (during reconnect)" : ""}`);
                 resolve(`Skipped ${device.deviceName || device.title} (stale CDP target — no response from JS context)`);
                 return;
             }
-            // Connection established — run setup
             connectionLocks.delete(appKey);
             connectedApps.set(appKey, { ws, deviceInfo: device, port, platform: "android" });
             markConnectionEstablished();
-            // A new CDP target id under a device name we have buffered before
-            // means the app process was replaced. Bump so pre-restart entries
-            // stay addressable and readers can draw the boundary.
             const bufferKey = device.deviceName || device.title || "unknown";
             const previousTargetId = lastTargetIdByDevice.get(bufferKey);
             if (previousTargetId && previousTargetId !== device.id) {
                 bumpEpoch(bufferKey);
             }
             lastTargetIdByDevice.set(bufferKey, device.id);
-            // Mirror the in-app SDK buffers into ours so a hard app restart
-            // does not take the only copy with it. No-op when the SDK is absent
-            // or EXECBRO_DISABLE_SDK_MIRROR=1.
             startSdkMirrorPoller(device.deviceName);
-            // Initialize or update connection state
-            // Note: We do NOT reset reconnectionAttempts here - that happens
-            // only when connection has been stable for MIN_STABLE_CONNECTION_MS
             if (isReconnection) {
                 closeConnectionGap(appKey);
                 updateConnectionState(appKey, {
                     status: "connected",
                     lastConnectedTime: new Date()
-                    // reconnectionAttempts NOT reset here - see ws.on("close") for stable connection check
                 });
-                // Reset context health for reconnection
                 initContextHealth(appKey);
                 console.error(`[execbro] Reconnected to ${device.title}`);
                 recordConnectionEvent("reconnect-success", appKey, device.title);
@@ -1007,26 +805,20 @@ export async function connectToDevice(device, port, options = {}) {
                 console.error(`[execbro] Connected to ${device.title}`);
                 recordConnectionEvent("connect-success", appKey, device.title);
             }
-            // Enable Runtime domain to receive console messages
             ws.send(JSON.stringify({
                 id: getNextMessageId(),
                 method: "Runtime.enable"
             }));
-            // Also enable Log domain
             ws.send(JSON.stringify({
                 id: getNextMessageId(),
                 method: "Log.enable"
             }));
-            // Inject JS network interceptor (immediate capture, may fail if context not ready)
             injectNetworkInterceptor(ws);
-            // Also try CDP Network.enable (takes priority if supported)
+            void import("./routeHistory.js")
+                .then((m) => m.installRouteHistory(device.deviceName))
+                .catch(() => { });
             const networkEnableId = sendNetworkEnable(ws);
             pendingNetworkEnableIds.add(networkEnableId);
-            // Resolve native identifiers from the device name in parallel:
-            //   - iOS: simulator UDID via findSimulatorByName
-            //   - Android: adb serial via getAdbIdForAvd (maps AVD name → emulator-NNNN)
-            // Both are best-effort; failures are swallowed. Identifiers enable
-            // automatic device scoping and power the registry-first resolver fast path.
             if (device.deviceName) {
                 const [simulatorUdid, adbSerial] = await Promise.all([
                     findSimulatorByName(device.deviceName).catch(() => null),
@@ -1047,19 +839,11 @@ export async function connectToDevice(device, port, options = {}) {
                     }
                 }
             }
-            // Fire-and-forget app detection (500ms delayed, non-blocking)
             const appForDetection = connectedApps.get(appKey);
             if (appForDetection) {
                 scheduleAppDetection(appForDetection);
             }
-            // Start periodic SDK probe. When __RN_AI_DEVTOOLS__ is detected,
-            // app.sdkPresent flips to true and CDP/JS-interceptor buffer
-            // writes are suppressed (SDK becomes the single source).
             startSdkProbeLoop(ws, appKey);
-            // Start WebSocket ping/pong keepalive to detect dead connections
-            // (especially important for physical devices over Wi-Fi).
-            // pingInterval was declared up-top so the early-registered close
-            // handler can clear it; close/error handlers are already attached.
             let pongReceived = true;
             pingInterval = setInterval(() => {
                 if (!pongReceived) {
@@ -1083,13 +867,11 @@ export async function connectToDevice(device, port, options = {}) {
                     handleCDPMessage(message, device, ws);
                 }
                 catch {
-                    // Ignore non-JSON messages
                 }
             });
             resolve(`Connected to ${device.title} (${device.deviceName})`);
         }
         catch (error) {
-            // Connection failed (both with and without Origin header)
             connectionLocks.delete(appKey);
             cancelReconnectionTimer(appKey);
             connectedApps.delete(appKey);
@@ -1105,9 +887,6 @@ export async function connectToDevice(device, port, options = {}) {
         }
     });
 }
-/**
- * Schedule a reconnection attempt with exponential backoff
- */
 function scheduleReconnection(appKey, config = DEFAULT_RECONNECTION_CONFIG) {
     const state = getConnectionState(appKey);
     if (!state)
@@ -1133,9 +912,6 @@ function scheduleReconnection(appKey, config = DEFAULT_RECONNECTION_CONFIG) {
     }, delay);
     saveReconnectionTimer(appKey, timer);
 }
-/**
- * Attempt to reconnect to a previously connected device
- */
 async function attemptReconnection(appKey, config = DEFAULT_RECONNECTION_CONFIG) {
     const metadata = getConnectionMetadata(appKey);
     if (!metadata) {
@@ -1145,7 +921,6 @@ async function attemptReconnection(appKey, config = DEFAULT_RECONNECTION_CONFIG)
     }
     const deviceTitle = metadata.deviceInfo.title;
     recordConnectionEvent("reconnect-attempt", appKey, deviceTitle);
-    // Quick check: is Metro even running on this port?
     const { scanMetroPorts } = await import("./metro.js");
     const openPorts = await scanMetroPorts(metadata.port, metadata.port);
     if (openPorts.length === 0) {
@@ -1155,15 +930,12 @@ async function attemptReconnection(appKey, config = DEFAULT_RECONNECTION_CONFIG)
         return false;
     }
     try {
-        // Re-fetch devices to get fresh WebSocket URL (may have changed)
         const devices = await fetchDevices(metadata.port);
-        // Try to find the same device first, otherwise select main device
         const device = devices.find(d => d.id === metadata.deviceInfo.id)
             || selectMainDevice(devices);
         if (!device) {
             console.error(`[execbro] Device no longer available for ${appKey}`);
             recordConnectionEvent("reconnect-failed", appKey, deviceTitle, "device no longer advertised by Metro");
-            // Schedule next attempt
             scheduleReconnection(appKey, config);
             return false;
         }
@@ -1174,12 +946,10 @@ async function attemptReconnection(appKey, config = DEFAULT_RECONNECTION_CONFIG)
         const msg = error instanceof Error ? error.message : String(error);
         console.error(`[execbro] Reconnection failed: ${msg}`);
         recordConnectionEvent("reconnect-failed", appKey, deviceTitle, msg);
-        // Schedule next attempt
         scheduleReconnection(appKey, config);
         return false;
     }
 }
-// Get list of connected apps
 export function getConnectedApps() {
     return Array.from(connectedApps.entries()).map(([key, app]) => ({
         key,
@@ -1187,24 +957,16 @@ export function getConnectedApps() {
         isConnected: app.ws.readyState === WebSocket.OPEN
     }));
 }
-// Get first connected app with an OPEN WebSocket (or null if none)
 export function getFirstConnectedApp() {
-    // Find first app with OPEN WebSocket, cleaning up stale entries
     for (const [key, app] of connectedApps.entries()) {
         if (app.ws.readyState === WebSocket.OPEN) {
             return app;
         }
-        // Clean up stale entry
         console.error(`[execbro] Cleaning up stale connection in getFirstConnectedApp: ${key} (state: ${getWebSocketStateName(app.ws.readyState)})`);
         connectedApps.delete(key);
     }
     return null;
 }
-/**
- * Find the connected RN app running on a specific iOS simulator (by UDID).
- * Returns null if no connected app matches — caller should skip any CDP-based
- * enrichment to avoid pulling data from a different simulator's app.
- */
 export function getConnectedAppBySimulatorUdid(udid) {
     for (const [key, app] of connectedApps.entries()) {
         if (app.ws.readyState !== WebSocket.OPEN) {
@@ -1217,13 +979,6 @@ export function getConnectedAppBySimulatorUdid(udid) {
     }
     return null;
 }
-/**
- * Find the connected RN app running on a specific Android device.
- * Falls back to the sole connected Android app when `deviceId` is not provided
- * or cannot be resolved via deviceName substring match — this keeps the common
- * single-device case working while preventing cross-device data leakage when
- * multiple Android apps are connected.
- */
 export function getConnectedAppByAndroidDeviceId(deviceId) {
     const androidApps = [];
     for (const [key, app] of connectedApps.entries()) {
@@ -1249,20 +1004,13 @@ export function getConnectedAppByAndroidDeviceId(deviceId) {
     }
     return null;
 }
-/**
- * Lowercase and strip separators (whitespace, `_`, `-`) so substring matches
- * survive punctuation drift between caller input and the device's reported
- * identifier (e.g. "SM_A356N" vs "SM-A356N - 15 - API 35").
- */
 function normalizeDeviceId(value) {
     if (!value)
         return "";
     return value.toLowerCase().replace(/[\s_\-]+/g, "");
 }
-/** Guess which platform a caller-supplied device string refers to. */
 function guessRequestedPlatform(device) {
     const lower = device.toLowerCase();
-    // Simulator UDIDs are uppercase UUIDs; adb serials are not.
     if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(lower))
         return "ios";
     if (/iphone|ipad|ipod|\bios\b|simulator/.test(lower))
@@ -1274,10 +1022,6 @@ function guessRequestedPlatform(device) {
 function deviceLabel(app) {
     return app.deviceInfo.deviceName || app.deviceInfo.title || "";
 }
-/**
- * Human-facing explanation for a `kind: "none"` / `kind: "ambiguous"` resolution.
- * Kept next to the matcher so the message always reflects the matching rules.
- */
 export function describeDeviceResolution(resolution) {
     if (resolution.kind === "ok")
         return "";
@@ -1293,9 +1037,6 @@ export function describeDeviceResolution(resolution) {
         return `No connected device matches "${device}". No devices are currently connected — run scan_metro to discover and connect to Metro servers.`;
     }
     const quoted = connected.map(a => `"${deviceLabel(a)}"`).join(", ");
-    // Cross-platform mismatch is the dominant shape of this failure: the agent
-    // passes a name from list_devices while only the other
-    // platform is attached to Metro. Saying so beats "retry with one of these".
     const requested = guessRequestedPlatform(device);
     const attachedPlatforms = new Set(connected.map(a => a.platform));
     if (requested && !attachedPlatforms.has(requested)) {
@@ -1311,10 +1052,6 @@ export function describeDeviceResolution(resolution) {
     }
     return `No connected device matches "${device}". Connected devices: ${quoted}. Retry with one of these names (substring match, case-insensitive), or run get_apps to list them.`;
 }
-/**
- * Non-throwing device matcher. Prefer this in call sites that can retry
- * (auto-connect, rescan); use getConnectedAppByDevice when a miss is terminal.
- */
 export function resolveConnectedAppByDevice(device) {
     const openApps = [];
     for (const [key, app] of connectedApps.entries()) {
@@ -1332,10 +1069,6 @@ export function resolveConnectedAppByDevice(device) {
     const normDevice = normalizeDeviceId(device);
     const matches = [];
     for (const app of openApps) {
-        // Match against deviceName + the underlying hardware identifiers, with
-        // separator-insensitive normalization so "SM_A356N" finds
-        // "SM-A356N - 15 - API 35" and "emulator-5554" finds the Android app
-        // attached to that serial.
         const haystacks = [
             normalizeDeviceId(deviceLabel(app)),
             normalizeDeviceId(app.simulatorUdid),
@@ -1345,8 +1078,6 @@ export function resolveConnectedAppByDevice(device) {
             matches.push(app);
         }
     }
-    // Prefer exact (case-insensitive) match when present — disambiguates
-    // "iPhone 17 Pro" from "iPhone 17 Pro Max" when both are connected.
     const exact = matches.find(a => deviceLabel(a).toLowerCase() === lowerDevice);
     if (exact)
         return { kind: "ok", app: exact };
@@ -1360,8 +1091,6 @@ export function getConnectedAppByDevice(device) {
     const resolution = resolveConnectedAppByDevice(device);
     if (resolution.kind === "ok")
         return resolution.app;
-    // No device argument: a miss just means "nothing connected" — callers
-    // handle null themselves (historically getFirstConnectedApp's contract).
     if (!device)
         return null;
     const context = resolution.kind === "ambiguous"
@@ -1369,7 +1098,6 @@ export function getConnectedAppByDevice(device) {
         : resolution.connected.length > 0 ? "device_mismatch" : "no_devices_connected";
     throw new UserInputError(describeDeviceResolution(resolution), context);
 }
-// Check if any app is connected with an OPEN WebSocket
 export function hasConnectedApp() {
     for (const [, app] of connectedApps.entries()) {
         if (app.ws.readyState === WebSocket.OPEN) {
@@ -1378,10 +1106,6 @@ export function hasConnectedApp() {
     }
     return false;
 }
-/**
- * Run a quick health check to verify the page context is responsive
- * Returns true if the context can execute code, false otherwise
- */
 export async function runQuickHealthCheck(app) {
     const HEALTH_CHECK_TIMEOUT = 2000;
     const messageId = getNextMessageId();
@@ -1394,7 +1118,6 @@ export async function runQuickHealthCheck(app) {
             resolve: (result) => {
                 clearTimeout(timeoutId);
                 pendingExecutions.delete(messageId);
-                // Update context health tracking
                 const appKey = findAppKeyForDevice(app.deviceInfo);
                 if (appKey) {
                     updateContextHealth(appKey, {
@@ -1422,10 +1145,6 @@ export async function runQuickHealthCheck(app) {
     });
 }
 const LOG_PIPELINE_MARKER_PREFIX = "__rn_devtools_health_";
-/**
- * Inject a sentinel console.log via CDP and wait for it to appear in the log buffer.
- * Returns true if the marker arrives within TIMEOUT_MS.
- */
 async function sendAndWaitForMarker(app, buffer) {
     const marker = `${LOG_PIPELINE_MARKER_PREFIX}${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
     const TIMEOUT_MS = 3000;
@@ -1439,7 +1158,6 @@ async function sendAndWaitForMarker(app, buffer) {
     catch {
         return false;
     }
-    // Poll the buffer for the marker (check every 50ms, up to TIMEOUT_MS)
     const startTime = Date.now();
     while (Date.now() - startTime < TIMEOUT_MS) {
         if (buffer.getAll().some(entry => entry.message.includes(marker))) {
@@ -1450,45 +1168,29 @@ async function sendAndWaitForMarker(app, buffer) {
     }
     return false;
 }
-/**
- * End-to-end log pipeline verification with automatic recovery.
- *
- * 1. Injects a sentinel console.log via CDP and verifies it appears in the buffer.
- * 2. If the marker doesn't arrive, attempts recovery:
- *    a. Re-sends Runtime.enable + Log.enable (fixes missing domain subscription)
- *    b. Retries the marker once
- * 3. If still broken, force-reconnects via ensureConnection and retries.
- *
- * Returns { ok, recovered, message } — the caller decides what to show.
- */
 export async function verifyLogPipeline(app) {
     const deviceName = app.deviceInfo.deviceName || app.deviceInfo.title || "unknown";
     const buffer = getLogBuffer(deviceName);
-    // --- Attempt 1: quick check ---
     if (await sendAndWaitForMarker(app, buffer)) {
         return { ok: true, recovered: false, message: null };
     }
-    // --- Attempt 2: re-enable Runtime/Log domains and retry ---
     try {
         app.ws.send(JSON.stringify({ id: getNextMessageId(), method: "Runtime.enable" }));
         app.ws.send(JSON.stringify({ id: getNextMessageId(), method: "Log.enable" }));
     }
     catch {
-        // WS send failed — fall through to reconnect
     }
-    // Brief pause for domain activation
     await new Promise(resolve => setTimeout(resolve, 300));
     if (await sendAndWaitForMarker(app, buffer)) {
         return { ok: true, recovered: true, message: "[CONNECTION] Log pipeline was stale — re-enabled CDP domains. Logs are flowing again." };
     }
-    // --- Attempt 3: force reconnect and retry ---
     const appKey = `${app.port}-${app.deviceInfo.id}`;
     const port = app.port;
     cancelReconnectionTimer(appKey);
     try {
         app.ws.close();
     }
-    catch { /* ignore */ }
+    catch { }
     connectedApps.delete(appKey);
     const result = await ensureConnection({ port, forceRefresh: false, healthCheck: true });
     if (!result.connected || !result.healthCheckPassed) {
@@ -1498,9 +1200,7 @@ export async function verifyLogPipeline(app) {
             message: "[CONNECTION] Log pipeline broken and reconnection failed. Ensure the app is running, then call scan_metro.",
         };
     }
-    // Wait for the new connection to settle
     await new Promise(resolve => setTimeout(resolve, 500));
-    // Get the fresh app reference after reconnection
     const freshApp = getFirstConnectedApp();
     if (!freshApp) {
         return {
@@ -1524,43 +1224,29 @@ export async function verifyLogPipeline(app) {
         message: "[WARNING] Log pipeline verification failed after reconnection. Console events are not reaching the buffer. Try reload_app or scan_metro.",
     };
 }
-/**
- * Check if a log message is a health check marker (for filtering from output).
- */
 export function isHealthCheckMarker(message) {
     return message.includes(LOG_PIPELINE_MARKER_PREFIX);
 }
-/**
- * Find the first available Metro port
- */
 async function findFirstMetroPort() {
     const ports = await scanMetroPorts();
     return ports.length > 0 ? ports[0] : null;
 }
-/**
- * Ensure a healthy connection to a React Native app
- * This will verify or establish a connection, optionally running a health check
- */
 export async function ensureConnection(options = {}) {
     const { port, healthCheck = true, forceRefresh = false } = options;
     let wasReconnected = false;
-    // forceRefresh: close every currently-connected app, then fall through to
-    // single-device fresh connect. Full multi-device re-discovery is scan_metro's
-    // job — ensureConnection only fresh-connects one when nothing is open.
     if (forceRefresh) {
         for (const { key, app } of getConnectedApps()) {
             cancelReconnectionTimer(key);
             try {
                 app.ws.close();
             }
-            catch { /* ignore */ }
+            catch { }
             connectedApps.delete(key);
         }
     }
     let openApps = getConnectedApps()
         .filter(a => a.isConnected)
         .map(a => a.app);
-    // Nothing connected — establish a single-device connection from scratch.
     if (openApps.length === 0) {
         const targetPort = port ?? await findFirstMetroPort();
         if (!targetPort) {
@@ -1584,10 +1270,6 @@ export async function ensureConnection(options = {}) {
             };
         }
         try {
-            // Clear any prior reconnection suppression — without this a stale
-            // suppression entry from a previous disconnect_metro keeps the
-            // close-handler from auto-recovering if Metro drops the WS just
-            // after probe.
             clearReconnectionSuppression();
             const connectResult = await connectToDevice(mainDevice, targetPort);
             wasReconnected = true;
@@ -1600,7 +1282,6 @@ export async function ensureConnection(options = {}) {
                     error: `${connectResult}. The CDP page advertised by Metro is no longer responsive — restart the React Native app, then retry.`,
                 };
             }
-            // Race window: settle briefly and retry getting the open app list.
             for (let i = 0; i < 5 && openApps.length === 0; i++) {
                 if (i > 0)
                     await new Promise(resolve => setTimeout(resolve, 100));
@@ -1636,8 +1317,6 @@ export async function ensureConnection(options = {}) {
             error: "Connection succeeded but app is not available",
         };
     }
-    // Per-device health-check; reconnect failed devices individually so a dead
-    // Android doesn't take down a healthy iOS report and vice versa.
     const perApp = [];
     for (const candidate of openApps) {
         let app = candidate;
@@ -1653,7 +1332,7 @@ export async function ensureConnection(options = {}) {
                 try {
                     app.ws.close();
                 }
-                catch { /* ignore */ }
+                catch { }
                 connectedApps.delete(appKey);
                 const devices = await fetchDevices(appPort);
                 const mainDevice = selectMainDevice(devices);
@@ -1716,7 +1395,6 @@ export async function ensureConnection(options = {}) {
 }
 export function getPassiveConnectionStatus(targetAppKey) {
     if (targetAppKey) {
-        // Check a specific device's connection
         const app = connectedApps.get(targetAppKey);
         if (!app || app.ws.readyState !== WebSocket.OPEN) {
             return { connected: false, needsPing: false, reason: "no_connection" };
@@ -1735,7 +1413,6 @@ export function getPassiveConnectionStatus(targetAppKey) {
         }
         return { connected: true, needsPing: false, reason: "ok" };
     }
-    // Default: check first connected app (backwards compatible)
     if (!hasConnectedApp()) {
         return { connected: false, needsPing: false, reason: "no_connection" };
     }
@@ -1758,7 +1435,6 @@ export function getPassiveConnectionStatus(targetAppKey) {
     return { connected: true, needsPing: false, reason: "ok" };
 }
 export async function checkAndEnsureConnection(device) {
-    // Resolve targeted device to appKey if specified
     let targetAppKey;
     let targetApp = null;
     if (device) {
@@ -1769,7 +1445,6 @@ export async function checkAndEnsureConnection(device) {
             }
         }
         catch {
-            // Device not found — fall through to reconnection
         }
     }
     const passive = getPassiveConnectionStatus(targetAppKey);