react-native-ai-debugger 1.1.4 → 1.4.21

package/build/index.js

@@ -3,14 +3,21 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { createServer as createHttpServer } from "node:http";
+import { existsSync, unlinkSync } from "fs";
 import { z } from "zod";
 import { getGuideOverview, getGuideByTopic, getAvailableTopics } from "./core/guides.js";
-import { tap } from "./core/tap.js";
-import { logBuffer, networkBuffer, bundleErrorBuffer, connectedApps, getActiveSimulatorUdid, scanMetroPorts, fetchDevices, selectMainDevice, connectToDevice, getConnectedApps, executeInApp, listDebugGlobals, inspectGlobal, reloadApp, 
+import { getLicenseStatus, getDashboardUrl, getUsageInfo } from "./core/license.js";
+import { API_BASE_URL } from "./core/config.js";
+import { getPostHogClient, identifyIfDevMode, shutdownPostHog } from "./core/posthog.js";
+import { getInstallationId, getPackageName, getServerVersion, isDevMode, TELEMETRY_JSONL_PATH } from "./core/telemetry.js";
+import { isSDKInstalled, querySDKNetwork, getSDKNetworkEntry, getSDKNetworkStats, clearSDKNetwork, querySDKConsole, getSDKConsoleStats, clearSDKConsole } from "./core/sdkBridge.js";
+import { tap } from "./pro/tap.js";
+import { getActivateLicenseConfig, handleActivateLicense, getDeleteAccountConfig, handleDeleteAccount, } from "./tools/accountTools.js";
+import { logBuffers, networkBuffers, getLogBuffer, getNetworkBuffer, getTotalLogCount, getConnectedAppByDevice, LogBuffer, NetworkBuffer, bundleErrorBuffer, imageBuffer, connectedApps, scanMetroPorts, fetchDevices, filterDebuggableDevices, connectToDevice, getConnectedApps, executeInApp, listDebugGlobals, inspectGlobal, reloadApp, 
 // React Component Inspection
 getComponentTree, getScreenLayout, inspectComponent, findComponents, inspectAtPoint, toggleElementInspector, isInspectorActive, getInspectorSelection, getFirstConnectedApp, getLogs, searchLogs, getLogSummary, getNetworkRequests, searchNetworkRequests, getNetworkStats, formatRequestDetails, 
 // Connection state
-getAllConnectionStates, getAllConnectionMetadata, getRecentGaps, formatDuration, cancelAllReconnectionTimers, clearAllConnectionState, suppressReconnection, clearReconnectionSuppression, 
+getAllConnectionStates, getAllConnectionMetadata, getRecentGaps, formatDuration, cancelAllReconnectionTimers, cancelReconnectionTimer, clearAllConnectionState, clearAllCDPMessageTimes, suppressReconnection, suppressReconnectionForKey, clearReconnectionSuppression, purgeStaleConnectionsForPorts, 
 // Context health tracking
 getContextHealth, 
 // Connection resilience
@@ -20,7 +27,7 @@ connectMetroBuildEvents, disconnectMetroBuildEvents, getBundleErrors, getBundleS
 // Error screen parsing (OCR fallback)
 parseErrorScreenText, formatParsedError, 
 // OCR
-recognizeText, inferIOSDevicePixelRatio, 
+recognizeText, inferIOSDevicePixelRatio, enrichScreenshotWithLayout, 
 // Android
 listAndroidDevices, androidScreenshot, androidInstallApp, androidLaunchApp, androidListPackages, 
 // Android UI Input (Phase 2)
@@ -35,15 +42,69 @@ listIOSSimulators, iosScreenshot, iosInstallApp, iosLaunchApp, iosOpenUrl, iosTe
 iosTap, iosSwipe, iosInputText, iosButton, iosKeyEvent, iosKeySequence, iosDescribeAll, iosDescribePoint, IOS_BUTTON_TYPES, 
 // iOS Element Finding (no screenshots)
 iosFindElement, iosWaitForElement, 
-// Debug HTTP Server
-startDebugHttpServer, getDebugServerPort, 
 // Telemetry
-initTelemetry, trackToolInvocation, 
+initTelemetry, trackToolInvocation, getTargetPlatform, 
 // Format utilities (TONL)
-formatLogsAsTonl, formatNetworkAsTonl } from "./core/index.js";
+formatLogsAsTonl, formatNetworkAsTonl, 
+// LogBox detection & control
+detectLogBox, formatLogBoxWarning, dismissLogBox, formatDismissedEntries, pushLogBox, addLogBoxIgnorePatterns, verifyLogPipeline } from "./core/index.js";
+// Legacy package migration: notify once per session via LogBox
+const LEGACY_PACKAGE_NAME = "react-native-ai-debugger";
+let legacyMigrationNotified = false;
+async function notifyLegacyPackageMigration() {
+    if (legacyMigrationNotified)
+        return;
+    if (getPackageName() !== LEGACY_PACKAGE_NAME)
+        return;
+    legacyMigrationNotified = true;
+    try {
+        await pushLogBox("You are using the deprecated 'react-native-ai-debugger' package. " +
+            "Please update your MCP settings to use 'react-native-ai-devtools' instead. " +
+            "See: https://www.npmjs.com/package/react-native-ai-devtools", "warning", true);
+    }
+    catch {
+        // Best-effort — don't break the connection flow
+    }
+}
+// Helper: resolve log buffer for a device (or create a merged buffer from all devices)
+function resolveLogBuffer(device) {
+    if (device) {
+        const app = getConnectedAppByDevice(device);
+        if (!app)
+            throw new Error(`No connected device matches "${device}"`);
+        const deviceName = app.deviceInfo.deviceName || app.deviceInfo.title || "unknown";
+        return getLogBuffer(deviceName);
+    }
+    // Merge all logs into a temporary buffer for read operations
+    const merged = new LogBuffer(5000);
+    for (const buffer of logBuffers.values()) {
+        for (const entry of buffer.getAll()) {
+            merged.add(entry);
+        }
+    }
+    return merged;
+}
+// Helper: resolve network buffer for a device (or create a merged buffer from all devices)
+function resolveNetworkBuffer(device) {
+    if (device) {
+        const app = getConnectedAppByDevice(device);
+        if (!app)
+            throw new Error(`No connected device matches "${device}"`);
+        const deviceName = app.deviceInfo.deviceName || app.deviceInfo.title || "unknown";
+        return getNetworkBuffer(deviceName);
+    }
+    // Merge all network requests into a temporary buffer for read operations
+    const merged = new NetworkBuffer(5000);
+    for (const buffer of networkBuffers.values()) {
+        for (const req of buffer.getAll({})) {
+            merged.set(`${Math.random()}`, req);
+        }
+    }
+    return merged;
+}
 // Create MCP server
 const server = new McpServer({
-    name: "react-native-ai-debugger",
+    name: "react-native-ai-devtools",
     version: "1.0.0"
 }, {
     instructions: "React Native debugging MCP server. Call get_usage_guide to learn recommended workflows for all tools. Quick start: scan_metro → get_logs / search_logs (console debugging) → ios_screenshot → tap(text=\"Submit\") or tap(x, y) (interact with UI)."
@@ -115,15 +176,32 @@ function estimateImageTokens(base64Data) {
 // Registry for dev meta-tool — stores handlers and configs for dynamic dispatch
 /* eslint-disable @typescript-eslint/no-explicit-any */
 const toolRegistry = new Map();
-function registerToolWithTelemetry(toolName, config, handler) {
+function registerToolWithTelemetry(toolName, config, handler, emptyResultDetector) {
     toolRegistry.set(toolName, { config, handler });
     server.registerTool(toolName, config, async (args) => {
+        // --- Usage limit check (runs on every tool call) ---
+        const usageInfo = getUsageInfo();
+        if (usageInfo && !usageInfo.canUse) {
+            const isCredits = usageInfo.creditsRemaining !== null;
+            const dashboardUrl = `${API_BASE_URL}/dashboard/usage`;
+            const message = isCredits
+                ? `Credits depleted. Purchase more at ${dashboardUrl}`
+                : `Monthly free limit reached (${usageInfo.used}/${usageInfo.limit}). Purchase a credits pack for unlimited usage at ${dashboardUrl}`;
+            return { content: [{ type: "text", text: message }] };
+        }
         const startTime = Date.now();
         let success = true;
         let errorMessage;
         let errorContext;
         let inputTokens;
         let outputTokens;
+        let emptyResult;
+        let meaningful;
+        let changeRate;
+        let tapStrategy;
+        let iosDriver;
+        let responsePreview;
+        let emptyReason;
         try {
             inputTokens = Math.ceil(JSON.stringify(args).length / 4);
         }
@@ -135,10 +213,31 @@ function registerToolWithTelemetry(toolName, config, handler) {
             // Check if result indicates an error
             if (result?.isError) {
                 success = false;
-                errorMessage = result.content?.[0]?.text || "Unknown error";
+                // Prefer concise _errorMessage over full response text (which may be large JSON)
+                errorMessage = result._errorMessage || result.content?.[0]?.text || "Unknown error";
                 // Extract error context if provided (e.g., the expression that caused a syntax error)
                 errorContext = result._errorContext;
             }
+            // Check for empty result (only on success, only if detector provided)
+            if (success && emptyResultDetector) {
+                try {
+                    emptyResult = emptyResultDetector(result);
+                }
+                catch {
+                    // Detector failure should never affect tool execution
+                }
+            }
+            // Extract meaningfulness data if provided (tap tool verification)
+            if (result?._meaningful !== undefined)
+                meaningful = result._meaningful;
+            if (result?._changeRate !== undefined)
+                changeRate = result._changeRate;
+            if (result?._tapStrategy)
+                tapStrategy = result._tapStrategy;
+            if (result?._iosDriver)
+                iosDriver = result._iosDriver;
+            if (result?._emptyReason)
+                emptyReason = result._emptyReason;
             if (Array.isArray(result?.content)) {
                 let totalTokens = 0;
                 for (const item of result.content) {
@@ -152,16 +251,37 @@ function registerToolWithTelemetry(toolName, config, handler) {
                 if (totalTokens > 0)
                     outputTokens = totalTokens;
             }
+            // Capture response text preview for local dev dashboard
+            if (Array.isArray(result?.content)) {
+                const textParts = result.content
+                    .filter((item) => item.type === "text")
+                    .map((item) => item.text);
+                if (textParts.length > 0) {
+                    responsePreview = textParts.join("\n").substring(0, 2000);
+                }
+            }
             return result;
         }
         catch (error) {
             success = false;
             errorMessage = error instanceof Error ? error.message : String(error);
+            getPostHogClient()?.captureException(error, getInstallationId(), { tool: toolName, server_version: getServerVersion() });
             throw error;
         }
         finally {
             const duration = Date.now() - startTime;
-            trackToolInvocation(toolName, success, duration, errorMessage, errorContext, inputTokens, outputTokens);
+            trackToolInvocation(toolName, success, duration, errorMessage, errorContext, inputTokens, outputTokens, getTargetPlatform(), emptyResult, meaningful, changeRate, tapStrategy, iosDriver, responsePreview, emptyReason);
+            getPostHogClient()?.capture({
+                distinctId: getInstallationId(),
+                event: toolName,
+                properties: {
+                    success,
+                    duration,
+                    server_version: getServerVersion(),
+                    ...(errorMessage && { error: errorMessage.substring(0, 200) }),
+                    ...(getTargetPlatform() && { platform: getTargetPlatform() }),
+                },
+            });
         }
     });
 }
@@ -219,33 +339,90 @@ registerToolWithTelemetry("scan_metro", {
             ]
         };
     }
-    // Fetch devices from each port and connect
-    const results = [];
+    // Phase 1: Fetch devices from all ports first
+    const portDevices = new Map();
     for (const port of openPorts) {
         const devices = await fetchDevices(port);
-        if (devices.length === 0) {
-            results.push(`Port ${port}: No devices found`);
+        const debuggable = filterDebuggableDevices(devices);
+        if (debuggable.length > 0) {
+            portDevices.set(port, debuggable);
+        }
+    }
+    // Phase 1.5: Purge stale connections for scanned ports
+    // When Metro restarts with a different app, device IDs change.
+    // Old connections remain in connectedApps — remove them before connecting new devices.
+    const purged = purgeStaleConnectionsForPorts(portDevices);
+    // Phase 2: Assign each device to the best port
+    // If a device appears on multiple ports, prefer the port where it has
+    // the fewest OTHER unique devices (i.e. its dedicated Metro server)
+    const devicePortAssignment = new Map(); // deviceName -> best port
+    const allDeviceNames = new Map();
+    for (const [port, devices] of portDevices) {
+        for (const device of devices) {
+            const name = device.deviceName || device.title;
+            const entry = allDeviceNames.get(name);
+            if (entry) {
+                entry.ports.push(port);
+            }
+            else {
+                allDeviceNames.set(name, { device, ports: [port] });
+            }
+        }
+    }
+    for (const [name, { ports }] of allDeviceNames) {
+        if (ports.length === 1) {
+            devicePortAssignment.set(name, ports[0]);
+        }
+        else {
+            // Prefer the port with fewer OTHER unique devices (the dedicated Metro)
+            let bestPort = ports[0];
+            let fewestOthers = Infinity;
+            for (const port of ports) {
+                const othersOnPort = (portDevices.get(port) || [])
+                    .filter(d => (d.deviceName || d.title) !== name).length;
+                if (othersOnPort < fewestOthers) {
+                    fewestOthers = othersOnPort;
+                    bestPort = port;
+                }
+            }
+            devicePortAssignment.set(name, bestPort);
+        }
+    }
+    // Phase 3: Connect devices to their assigned ports
+    const results = [];
+    if (purged.length > 0) {
+        results.push(`Purged ${purged.length} stale connection(s): ${purged.join(", ")}`);
+    }
+    for (const port of openPorts) {
+        const devices = portDevices.get(port);
+        if (!devices) {
+            results.push(`Port ${port}: No debuggable devices found`);
             continue;
         }
         results.push(`Port ${port}: Found ${devices.length} device(s)`);
-        const mainDevice = selectMainDevice(devices);
-        if (mainDevice) {
+        for (const device of devices) {
+            const name = device.deviceName || device.title;
+            const assignedPort = devicePortAssignment.get(name);
+            if (assignedPort !== port) {
+                results.push(`  - ${name}: Skipped (assigned to port ${assignedPort})`);
+                continue;
+            }
             try {
-                const connectionResult = await connectToDevice(mainDevice, port);
+                const connectionResult = await connectToDevice(device, port);
                 results.push(`  - ${connectionResult}`);
-                // Also connect to Metro build events for this port
-                try {
-                    await connectMetroBuildEvents(port);
-                    results.push(`  - Connected to Metro build events`);
-                }
-                catch {
-                    // Build events connection is optional, don't fail the scan
-                }
             }
             catch (error) {
-                results.push(`  - Failed: ${error}`);
+                results.push(`  - ${name}: Failed - ${error}`);
             }
         }
+        // Connect to Metro build events for this port
+        try {
+            await connectMetroBuildEvents(port);
+            results.push(`  - Connected to Metro build events`);
+        }
+        catch {
+            // Build events connection is optional
+        }
     }
     return {
         content: [
@@ -261,33 +438,34 @@ registerToolWithTelemetry("get_apps", {
     description: "List currently connected React Native apps and their connection status. If no apps are connected, run scan_metro first to establish a connection.",
     inputSchema: {}
 }, async () => {
-    const connections = getConnectedApps();
-    if (connections.length === 0) {
+    const apps = getConnectedApps();
+    if (apps.length === 0) {
         return {
             content: [
                 {
                     type: "text",
-                    text: 'No apps connected. Run "scan_metro" first to discover and connect to running apps.'
+                    text: "No connected devices. Run scan_metro to discover and connect to Metro servers."
                 }
             ]
         };
     }
-    const status = connections.map(({ app, isConnected }) => {
-        const state = isConnected ? "Connected" : "Disconnected";
-        return `${app.deviceInfo.title} (${app.deviceInfo.deviceName}): ${state}`;
+    const deviceLines = apps
+        .filter(({ isConnected }) => isConnected)
+        .map(({ app }, i) => {
+        const name = app.deviceInfo.deviceName || app.deviceInfo.title;
+        const appId = app.deviceInfo.appId || app.deviceInfo.title.split(" (")[0] || "unknown";
+        return `  ${i + 1}. ${name} — ${appId} (${app.platform}, port ${app.port})`;
     });
-    // Include active iOS simulator info if available
-    const activeSimulatorUdid = getActiveSimulatorUdid();
-    const simulatorInfo = activeSimulatorUdid
-        ? `\nActive iOS Simulator (auto-scoped): ${activeSimulatorUdid}`
-        : "\nNo iOS simulator linked (iOS tools will use first booted simulator)";
+    const text = [
+        `Connected devices:`,
+        ...deviceLines,
+        ``,
+        `Use device="${apps[0].app.deviceInfo.deviceName}" to target a specific device.`,
+        ``,
+        `Total logs in buffer: ${getTotalLogCount()}`
+    ].join("\n");
     return {
-        content: [
-            {
-                type: "text",
-                text: `Connected apps:\n${status.join("\n")}${simulatorInfo}\n\nTotal logs in buffer: ${logBuffer.size}`
-            }
-        ]
+        content: [{ type: "text", text }]
     };
 });
 // Tool: Get connection status (detailed health and gap tracking)
@@ -370,6 +548,53 @@ registerToolWithTelemetry("get_connection_status", {
         content: [{ type: "text", text: lines.join("\n") }]
     };
 });
+// Tool: License status
+registerToolWithTelemetry("get_license_status", {
+    description: "Get your installation ID and license status. Shows your unique Installation ID (needed to activate Pro in the dashboard), current license tier, and cache validity.",
+    inputSchema: {},
+}, async () => {
+    const status = getLicenseStatus();
+    const lines = [];
+    lines.push(`Installation ID: ${status.installationId}`);
+    lines.push(`License: ${status.tier.charAt(0).toUpperCase() + status.tier.slice(1)}`);
+    if (status.plan) {
+        lines.push(`Plan expires: ${status.plan.expiresAt}`);
+    }
+    lines.push(`Cache valid until: ${status.cacheExpiresAt}`);
+    // Usage limits
+    const usage = getUsageInfo();
+    if (usage) {
+        lines.push("");
+        lines.push("--- Usage ---");
+        if (usage.creditsRemaining !== null) {
+            lines.push(`Credits remaining: ${usage.creditsRemaining.toLocaleString()}`);
+            lines.push(`Used this month: ${usage.used.toLocaleString()}`);
+        }
+        else {
+            lines.push(`Monthly usage: ${usage.used} / ${usage.limit}`);
+        }
+        lines.push(`Month: ${usage.monthKey}`);
+        if (usage.promotionalPeriod) {
+            const endsAt = usage.promotionalPeriodEndsAt
+                ? new Date(usage.promotionalPeriodEndsAt).toLocaleDateString("en-GB", { day: "2-digit", month: "2-digit", year: "numeric" })
+                : "unknown";
+            lines.push(`Status: Active (promotional period — no limits until ${endsAt})`);
+        }
+        else {
+            lines.push(`Status: ${usage.canUse ? "Active" : "Limit reached"}`);
+        }
+    }
+    if (status.tier === "free") {
+        const dashboardUrl = getDashboardUrl();
+        lines.push("");
+        if (dashboardUrl) {
+            lines.push(`Link your account: ${dashboardUrl}/link?id=${status.installationId}`);
+        }
+    }
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+    };
+});
 // Tool: Ensure connection health
 registerToolWithTelemetry("ensure_connection", {
     description: "Verify or establish a healthy connection to a React Native app. Use before running commands if connection may be stale, or after navigation/reload. This tool runs a health check and will auto-reconnect if needed.",
@@ -393,12 +618,14 @@ registerToolWithTelemetry("ensure_connection", {
             content: [
                 {
                     type: "text",
-                    text: result.error || "Connection failed: Unknown error"
+                    text: result.error || "Connection failed: No error details available. Try running scan_metro to check if Metro is running, then ensure_connection with forceRefresh=true."
                 }
             ],
             isError: true
         };
     }
+    // Notify legacy package users (fire-and-forget, once per session)
+    notifyLegacyPackageMigration();
     const lines = [];
     lines.push("=== Connection Ensured ===\n");
     if (result.connectionInfo) {
@@ -455,16 +682,71 @@ registerToolWithTelemetry("get_logs", {
             .boolean()
             .optional()
             .default(false)
-            .describe("Return summary statistics instead of full logs (count by level + last 5 messages). Use for quick overview.")
+            .describe("Return summary statistics instead of full logs (count by level + last 5 messages). Use for quick overview."),
+        device: z.string().optional().describe("Target device name (substring match). Omit for all devices. Run get_apps to see connected devices.")
+    }
+}, async ({ maxLogs, level, startFromText, maxMessageLength, verbose, format, summary, device }) => {
+    // Check if SDK is installed — prefer SDK data for richer logs
+    const sdkAvailable = await isSDKInstalled();
+    if (sdkAvailable) {
+        if (summary) {
+            const sdkStats = await getSDKConsoleStats();
+            if (sdkStats.success) {
+                const s = sdkStats.data;
+                const lines = [];
+                lines.push(`Total logs: ${s.total}`);
+                if (s.byLevel && Object.keys(s.byLevel).length > 0) {
+                    lines.push("\nBy Level:");
+                    for (const [lvl, cnt] of Object.entries(s.byLevel))
+                        lines.push(`  ${lvl}: ${cnt}`);
+                }
+                return { content: [{ type: "text", text: `Log Summary (SDK):\n\n${lines.join("\n")}` }] };
+            }
+        }
+        const sdkResult = await querySDKConsole({ count: maxLogs, level, text: startFromText });
+        if (sdkResult.success) {
+            const entries = sdkResult.data;
+            if (entries.length === 0) {
+                return { content: [{ type: "text", text: "No console logs captured yet." }] };
+            }
+            if (format === "tonl") {
+                const tonlLines = entries.map((e) => {
+                    const time = new Date(e.timestamp).toLocaleTimeString();
+                    let msg = e.message;
+                    if (!verbose && maxMessageLength > 0 && msg.length > maxMessageLength) {
+                        msg = msg.slice(0, maxMessageLength) + "...";
+                    }
+                    return `${time} [${e.level}] ${msg}`;
+                });
+                return { content: [{ type: "text", text: `Console Logs (${entries.length} entries, SDK):\n\n${tonlLines.join("\n")}` }] };
+            }
+            const lines = entries.map((e) => {
+                const time = new Date(e.timestamp).toLocaleTimeString();
+                let msg = e.message;
+                if (!verbose && maxMessageLength > 0 && msg.length > maxMessageLength) {
+                    msg = msg.slice(0, maxMessageLength) + "...";
+                }
+                return `[${time}] [${e.level.toUpperCase()}] ${msg}`;
+            });
+            return { content: [{ type: "text", text: `Console Logs (${entries.length} entries, SDK):\n\n${lines.join("\n")}` }] };
+        }
     }
-}, async ({ maxLogs, level, startFromText, maxMessageLength, verbose, format, summary }) => {
     // Return summary if requested
     if (summary) {
-        const summaryText = getLogSummary(logBuffer, { lastN: 5, maxMessageLength: 100 });
+        const summaryText = getLogSummary(resolveLogBuffer(device), { lastN: 5, maxMessageLength: 100 });
         let connectionWarning = "";
-        if (logBuffer.size === 0) {
-            const status = await checkAndEnsureConnection();
+        if (getTotalLogCount() === 0) {
+            const status = await checkAndEnsureConnection(device);
             connectionWarning = status.message ? `\n\n${status.message}` : "";
+            if (status.connected) {
+                const targetApp = device ? getConnectedAppByDevice(device) : getFirstConnectedApp();
+                if (targetApp) {
+                    const pipeline = await verifyLogPipeline(targetApp);
+                    if (pipeline.message) {
+                        connectionWarning += `\n\n${pipeline.message}`;
+                    }
+                }
+            }
         }
         return {
             content: [
@@ -475,7 +757,7 @@ registerToolWithTelemetry("get_logs", {
             ]
         };
     }
-    const { logs, count, formatted } = getLogs(logBuffer, {
+    const { logs, count, formatted } = getLogs(resolveLogBuffer(device), {
         maxLogs,
         level,
         startFromText,
@@ -484,9 +766,60 @@ registerToolWithTelemetry("get_logs", {
     });
     // Check connection health
     let connectionWarning = "";
+    let emptyReason;
     if (count === 0) {
-        const status = await checkAndEnsureConnection();
+        const status = await checkAndEnsureConnection(device);
         connectionWarning = status.message ? `\n\n${status.message}` : "";
+        // Track empty reason for telemetry
+        emptyReason = "no_logs";
+        if (!status.connected) {
+            emptyReason = "disconnected";
+        }
+        else if (status.wasReconnected) {
+            emptyReason = "post_reconnect";
+        }
+        // End-to-end log pipeline verification (with automatic recovery)
+        if (status.connected) {
+            const targetApp = device ? getConnectedAppByDevice(device) : getFirstConnectedApp();
+            if (targetApp) {
+                const pipeline = await verifyLogPipeline(targetApp);
+                if (pipeline.message) {
+                    connectionWarning += `\n\n${pipeline.message}`;
+                }
+                if (!pipeline.ok) {
+                    emptyReason = "pipeline_failed";
+                }
+                else if (pipeline.recovered) {
+                    emptyReason = "pipeline_recovered";
+                }
+                // If pipeline recovered, re-read the buffer — new logs may have arrived
+                if (pipeline.recovered && pipeline.ok) {
+                    const retryResult = getLogs(resolveLogBuffer(device), {
+                        maxLogs, level, startFromText, maxMessageLength, verbose
+                    });
+                    if (retryResult.count > 0) {
+                        // Return the recovered logs instead of empty
+                        return {
+                            _emptyReason: "pipeline_recovered",
+                            content: [{
+                                    type: "text",
+                                    text: `React Native Console Logs (${retryResult.count} entries):\n\n${retryResult.formatted}${connectionWarning}`
+                                }]
+                        };
+                    }
+                }
+            }
+        }
+        // Add diagnostic metadata for empty results (captured by telemetry via responsePreview)
+        if (count === 0) {
+            const diagParts = [
+                `empty_reason=${status?.wasReconnected ? "post_reconnect" : "no_logs"}`,
+                `connection=${getPassiveConnectionStatus().reason}`,
+                `device_count=${connectedApps.size}`,
+                `buffer_sizes=${JSON.stringify(Object.fromEntries([...logBuffers.entries()].map(([k, v]) => [k, v.size])))}`,
+            ];
+            connectionWarning += `\n\n[DIAG] ${diagParts.join(", ")}`;
+        }
     }
     else {
         const passive = getPassiveConnectionStatus();
@@ -514,6 +847,7 @@ registerToolWithTelemetry("get_logs", {
     if (format === "tonl") {
         const tonlOutput = formatLogsAsTonl(logs, { maxMessageLength: verbose ? 0 : maxMessageLength });
         return {
+            ...(emptyReason && { _emptyReason: emptyReason }),
             content: [
                 {
                     type: "text",
@@ -523,6 +857,7 @@ registerToolWithTelemetry("get_logs", {
         };
     }
     return {
+        ...(emptyReason && { _emptyReason: emptyReason }),
         content: [
             {
                 type: "text",
@@ -530,7 +865,9 @@ registerToolWithTelemetry("get_logs", {
             }
         ]
     };
-});
+}, 
+// Empty result detector: buffer has no entries at all
+() => getTotalLogCount() === 0);
 // Tool: Search logs
 registerToolWithTelemetry("search_logs", {
     description: "Search console logs for text (case-insensitive)",
@@ -551,14 +888,46 @@ registerToolWithTelemetry("search_logs", {
             .enum(["text", "tonl"])
             .optional()
             .default("tonl")
-            .describe("Output format: 'text' or 'tonl' (default, compact token-optimized format)")
+            .describe("Output format: 'text' or 'tonl' (default, compact token-optimized format)"),
+        device: z.string().optional().describe("Target device name (substring match). Omit for all devices. Run get_apps to see connected devices.")
+    }
+}, async ({ text, maxResults, maxMessageLength, verbose, format, device }) => {
+    // Check if SDK is installed — prefer SDK data
+    const sdkAvailable = await isSDKInstalled();
+    if (sdkAvailable) {
+        const sdkResult = await querySDKConsole({ count: maxResults, text });
+        if (sdkResult.success) {
+            const entries = sdkResult.data;
+            if (entries.length === 0) {
+                return { content: [{ type: "text", text: `No logs matching "${text}" found.` }] };
+            }
+            if (format === "tonl") {
+                const tonlLines = entries.map((e) => {
+                    const time = new Date(e.timestamp).toLocaleTimeString();
+                    let msg = e.message;
+                    if (!verbose && maxMessageLength > 0 && msg.length > maxMessageLength) {
+                        msg = msg.slice(0, maxMessageLength) + "...";
+                    }
+                    return `${time} [${e.level}] ${msg}`;
+                });
+                return { content: [{ type: "text", text: `Search results for "${text}" (${entries.length} matches, SDK):\n\n${tonlLines.join("\n")}` }] };
+            }
+            const lines = entries.map((e) => {
+                const time = new Date(e.timestamp).toLocaleTimeString();
+                let msg = e.message;
+                if (!verbose && maxMessageLength > 0 && msg.length > maxMessageLength) {
+                    msg = msg.slice(0, maxMessageLength) + "...";
+                }
+                return `[${time}] [${e.level.toUpperCase()}] ${msg}`;
+            });
+            return { content: [{ type: "text", text: `Search results for "${text}" (${entries.length} matches, SDK):\n\n${lines.join("\n")}` }] };
+        }
     }
-}, async ({ text, maxResults, maxMessageLength, verbose, format }) => {
-    const { logs, count, formatted } = searchLogs(logBuffer, text, { maxResults, maxMessageLength, verbose });
+    const { logs, count, formatted } = searchLogs(resolveLogBuffer(device), text, { maxResults, maxMessageLength, verbose });
     // Check connection health
     let connectionWarning = "";
     if (count === 0) {
-        const status = await checkAndEnsureConnection();
+        const status = await checkAndEnsureConnection(device);
         connectionWarning = status.message ? `\n\n${status.message}` : "";
     }
     else {
@@ -591,17 +960,32 @@ registerToolWithTelemetry("search_logs", {
 // Tool: Clear logs
 registerToolWithTelemetry("clear_logs", {
     description: "Clear the log buffer",
-    inputSchema: {}
-}, async () => {
-    const count = logBuffer.clear();
-    return {
-        content: [
-            {
-                type: "text",
-                text: `Cleared ${count} log entries from buffer.`
-            }
-        ]
-    };
+    inputSchema: {
+        device: z.string().optional().describe("Target device name (substring match). Omit to clear all devices. Run get_apps to see connected devices.")
+    }
+}, async ({ device }) => {
+    if (device) {
+        const app = getConnectedAppByDevice(device);
+        if (!app)
+            throw new Error(`No connected device matches "${device}"`);
+        const deviceName = app.deviceInfo.deviceName || app.deviceInfo.title || "unknown";
+        const count = getLogBuffer(deviceName).clear();
+        return { content: [{ type: "text", text: `Cleared ${count} log entries from ${deviceName}.` }] };
+    }
+    // Clear all
+    let total = 0;
+    for (const buffer of logBuffers.values()) {
+        total += buffer.clear();
+    }
+    // Also clear SDK buffer if available
+    const sdkAvailable = await isSDKInstalled();
+    if (sdkAvailable) {
+        const sdkResult = await clearSDKConsole();
+        if (sdkResult.success && sdkResult.count) {
+            total += sdkResult.count;
+        }
+    }
+    return { content: [{ type: "text", text: `Cleared ${total} log entries from all devices.` }] };
 });
 // Tool: Connect to specific Metro port
 registerToolWithTelemetry("connect_metro", {
@@ -662,9 +1046,11 @@ registerToolWithTelemetry("connect_metro", {
 });
 // Tool: Disconnect from Metro
 registerToolWithTelemetry("disconnect_metro", {
-    description: "Disconnect from all Metro servers and stop auto-reconnection. Use this when you want to switch to the built-in React Native debugger (which requires the CDP slot to be free). Log and network buffers are preserved. Reconnect later with scan_metro.",
-    inputSchema: {}
-}, async () => {
+    description: "Disconnect from Metro servers and stop auto-reconnection. Without device param: disconnects ALL devices. With device param: disconnects only the matching device. Use this to remove stale connections or free the CDP slot for the built-in debugger. Log and network buffers are preserved. Reconnect later with scan_metro.",
+    inputSchema: {
+        device: z.string().optional().describe("Target device name (substring match) to disconnect. Omit to disconnect all devices. Run get_apps to see connected devices.")
+    }
+}, async ({ device }) => {
     const connections = getConnectedApps();
     if (connections.length === 0) {
         return {
@@ -676,6 +1062,36 @@ registerToolWithTelemetry("disconnect_metro", {
             ]
         };
     }
+    // Targeted disconnect: only disconnect a specific device
+    if (device) {
+        const app = getConnectedAppByDevice(device);
+        if (!app) {
+            return {
+                content: [{ type: "text", text: `No connected device matches "${device}". Run get_apps to see connected devices.` }],
+                isError: true
+            };
+        }
+        // Find and close the matching connection
+        for (const [key, connectedApp] of connectedApps.entries()) {
+            if (connectedApp.ws === app.ws) {
+                // Suppress reconnection for this specific device
+                suppressReconnectionForKey(key);
+                cancelReconnectionTimer(key);
+                try {
+                    connectedApp.ws.close();
+                }
+                catch {
+                    // Ignore close errors
+                }
+                connectedApps.delete(key);
+                const name = connectedApp.deviceInfo.deviceName || connectedApp.deviceInfo.title;
+                return {
+                    content: [{ type: "text", text: `Disconnected from ${name} (port ${connectedApp.port}). Buffers preserved. Use scan_metro to reconnect.` }]
+                };
+            }
+        }
+    }
+    // Disconnect all
     const disconnected = [];
     // Suppress reconnection BEFORE closing sockets
     // (close handlers fire async and would re-schedule reconnection)
@@ -696,6 +1112,7 @@ registerToolWithTelemetry("disconnect_metro", {
     disconnectMetroBuildEvents();
     // Clear connection state (but NOT log/network buffers)
     clearAllConnectionState();
+    clearAllCDPMessageTimes();
     const lines = [
         `Disconnected from ${disconnected.length} app(s):`,
         ...disconnected.map((d) => `  - ${d}`),
@@ -737,10 +1154,11 @@ registerToolWithTelemetry("execute_in_app", {
             .boolean()
             .optional()
             .default(false)
-            .describe("Disable result truncation. Tip: Be cautious - Redux stores or large state can return 10KB+.")
+            .describe("Disable result truncation. Tip: Be cautious - Redux stores or large state can return 10KB+."),
+        device: z.string().optional().describe("Target device name (substring match). Omit for default device. Run get_apps to see connected devices.")
     }
-}, async ({ expression, awaitPromise, maxResultLength, verbose }) => {
-    const result = await executeInApp(expression, awaitPromise);
+}, async ({ expression, awaitPromise, maxResultLength, verbose, device }) => {
+    const result = await executeInApp(expression, awaitPromise, {}, device);
     if (!result.success) {
         let errorText = `Error: ${result.error}`;
         // If the error is a ReferenceError (accessing a global that doesn't exist),
@@ -775,13 +1193,22 @@ registerToolWithTelemetry("execute_in_app", {
             }
         ]
     };
+}, 
+// Empty result detector: successful execution but no meaningful output
+(result) => {
+    if (result?.isError)
+        return false;
+    const text = result?.content?.[0]?.text;
+    return text === undefined || text === "" || text === "undefined" || text === "null";
 });
 // Tool: List debug globals available in the app
 registerToolWithTelemetry("list_debug_globals", {
     description: "List globally available debugging objects in the connected React Native app (Apollo Client, Redux store, React DevTools, etc.). Use this to discover what state management and debugging tools are available.",
-    inputSchema: {}
-}, async () => {
-    const result = await listDebugGlobals();
+    inputSchema: {
+        device: z.string().optional().describe("Target device name (substring match). Omit for default device. Run get_apps to see connected devices.")
+    }
+}, async ({ device }) => {
+    const result = await listDebugGlobals(device);
     if (!result.success) {
         return {
             content: [
@@ -808,10 +1235,11 @@ registerToolWithTelemetry("inspect_global", {
     inputSchema: {
         objectName: z
             .string()
-            .describe("Name of the global object to inspect (e.g., '__EXPO_ROUTER__', '__APOLLO_CLIENT__')")
+            .describe("Name of the global object to inspect (e.g., '__EXPO_ROUTER__', '__APOLLO_CLIENT__')"),
+        device: z.string().optional().describe("Target device name (substring match). Omit for default device. Run get_apps to see connected devices.")
     }
-}, async ({ objectName }) => {
-    const result = await inspectGlobal(objectName);
+}, async ({ objectName, device }) => {
+    const result = await inspectGlobal(objectName, device);
     if (!result.success) {
         let errorText = `Error: ${result.error}`;
         // If the error is a ReferenceError (accessing a global that doesn't exist),
@@ -843,13 +1271,8 @@ registerToolWithTelemetry("inspect_global", {
 // ============================================================================
 // Tool: Get the React component tree
 registerToolWithTelemetry("get_component_tree", {
-    description: "Get the React component tree from the running app. **RECOMMENDED**: Use focusedOnly=true with structureOnly=true for a token-efficient overview of just the active screen (~1-2KB). This skips navigation wrappers and global overlays, showing only what's actually visible.",
+    description: "Get the full React component tree from the running app. Shows the complete fiber hierarchy including providers, navigation wrappers, and internal components. For a screen overview with positions and text, use get_screen_layout instead. Use structureOnly=true for compact names-only output.",
     inputSchema: {
-        focusedOnly: z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("Return only the focused/active screen subtree, skipping navigation wrappers and overlays. Dramatically reduces output size. (Recommended: true)"),
         structureOnly: z
             .boolean()
             .optional()
@@ -858,7 +1281,7 @@ registerToolWithTelemetry("get_component_tree", {
         maxDepth: z
             .number()
             .optional()
-            .describe("Maximum tree depth (default: 25 for focusedOnly+structureOnly, 40 for structureOnly, 100 for full mode)"),
+            .describe("Maximum tree depth (default: 5000)"),
         includeProps: z
             .boolean()
             .optional()
@@ -878,17 +1301,18 @@ registerToolWithTelemetry("get_component_tree", {
             .enum(["json", "tonl"])
             .optional()
             .default("tonl")
-            .describe("Output format: 'json' or 'tonl' (default, compact indented tree). Ignored if structureOnly=true.")
+            .describe("Output format: 'json' or 'tonl' (default, compact indented tree). Ignored if structureOnly=true."),
+        device: z.string().optional().describe("Target device name (substring match). Omit for default device. Run get_apps to see connected devices.")
     }
-}, async ({ focusedOnly, structureOnly, maxDepth, includeProps, includeStyles, hideInternals, format }) => {
+}, async ({ structureOnly, maxDepth, includeProps, includeStyles, hideInternals, format, device }) => {
     const result = await getComponentTree({
-        focusedOnly,
         structureOnly,
         maxDepth,
         includeProps,
         includeStyles,
         hideInternals,
-        format
+        format,
+        device
     });
     if (!result.success) {
         return {
@@ -912,36 +1336,22 @@ registerToolWithTelemetry("get_component_tree", {
 });
 // Tool: Get full screen layout (all components with layout styles)
 registerToolWithTelemetry("get_screen_layout", {
-    description: "Get layout information for all components on screen. **USE AFTER get_component_tree**: First use get_component_tree(structureOnly=true) to understand structure, then use this tool OR find_components with includeLayout=true to get layout details for specific areas. This tool returns full layout data which can be large for complex screens.",
+    description: "Get a screen map showing visible components as an indented tree with actual screen positions. Uses measureInWindow for real coordinates and filters out off-screen components. Returns meaningful component names with text content and frame data (x,y width x height). Coordinates are in **points** (iOS) or **dp** (Android) — NOT screenshot pixels. Use tap(text=...) or tap(testID=...) to interact with discovered components. Use extended=true to include layout styles (padding, margin, flex, backgroundColor, etc.).",
     inputSchema: {
-        maxDepth: z
-            .number()
-            .optional()
-            .default(65)
-            .describe("Maximum tree depth to traverse (default: 65, balanced for most screens)"),
-        componentsOnly: z
+        extended: z
             .boolean()
             .optional()
             .default(false)
-            .describe("Only show custom components, hide host components (View, Text, etc.)"),
-        shortPath: z
-            .boolean()
-            .optional()
-            .default(true)
-            .describe("Show only last 3 path segments instead of full path (default: true)"),
+            .describe("Include layout styles (padding, margin, flex, backgroundColor, borderRadius, etc.) for each component. Default: false for compact output."),
         summary: z
             .boolean()
             .optional()
             .default(false)
-            .describe("Return only component counts by name instead of full element list (default: false)"),
-        format: z
-            .enum(["json", "tonl"])
-            .optional()
-            .default("tonl")
-            .describe("Output format: 'json' or 'tonl' (default, pipe-delimited rows, ~40% smaller)")
+            .describe("Return only component counts by name instead of full tree (default: false)"),
+        device: z.string().optional().describe("Target device name (substring match). Omit for default device. Run get_apps to see connected devices.")
     }
-}, async ({ maxDepth, componentsOnly, shortPath, summary, format }) => {
-    const result = await getScreenLayout({ maxDepth, componentsOnly, shortPath, summary, format });
+}, async ({ extended, summary, device }) => {
+    const result = await getScreenLayout({ extended, summary, device });
     if (!result.success) {
         return {
             content: [
@@ -964,7 +1374,7 @@ registerToolWithTelemetry("get_screen_layout", {
 });
 // Tool: Inspect a specific component by name
 registerToolWithTelemetry("inspect_component", {
-    description: "Inspect a specific React component by name. **DRILL-DOWN TOOL**: Use after get_component_tree(structureOnly=true) to inspect specific components. Returns props, style, state (hooks), and optionally children tree. Use childrenDepth to control how deep nested children go.",
+    description: "Inspect a specific React component by name. **DRILL-DOWN TOOL**: Use after get_screen_layout or find_components to identify which component to inspect. Returns props, style, state (hooks), and optionally children tree. Use childrenDepth to control how deep nested children go.",
     inputSchema: {
         componentName: z
             .string()
@@ -990,16 +1400,18 @@ registerToolWithTelemetry("inspect_component", {
             .boolean()
             .optional()
             .default(true)
-            .describe("Simplify hooks output by hiding effects and reducing depth (default: true)")
+            .describe("Simplify hooks output by hiding effects and reducing depth (default: true)"),
+        device: z.string().optional().describe("Target device name (substring match). Omit for default device. Run get_apps to see connected devices.")
     }
-}, async ({ componentName, index, includeState, includeChildren, childrenDepth, shortPath, simplifyHooks }) => {
+}, async ({ componentName, index, includeState, includeChildren, childrenDepth, shortPath, simplifyHooks, device }) => {
     const result = await inspectComponent(componentName, {
         index,
         includeState,
         includeChildren,
         childrenDepth,
         shortPath,
-        simplifyHooks
+        simplifyHooks,
+        device
     });
     if (!result.success) {
         return {
@@ -1023,7 +1435,7 @@ registerToolWithTelemetry("inspect_component", {
 });
 // Tool: Find components matching a pattern
 registerToolWithTelemetry("find_components", {
-    description: "Find components matching a name pattern. **TARGETED SEARCH**: Use after get_component_tree(structureOnly=true) to find specific components by pattern and get their layout info. More efficient than get_screen_layout for targeted queries. Use includeLayout=true to get padding/margin/flex styles.",
+    description: "Find components matching a name pattern. **TARGETED SEARCH**: Use after get_screen_layout or get_component_tree(structureOnly=true) to find specific components by pattern. Use includeLayout=true to get padding/margin/flex styles.",
     inputSchema: {
         pattern: z
             .string()
@@ -1044,10 +1456,11 @@ registerToolWithTelemetry("find_components", {
             .enum(["json", "tonl"])
             .optional()
             .default("tonl")
-            .describe("Output format: 'json' or 'tonl' (default, pipe-delimited rows, ~40% smaller)")
+            .describe("Output format: 'json' or 'tonl' (default, pipe-delimited rows, ~40% smaller)"),
+        device: z.string().optional().describe("Target device name (substring match). Omit for default device. Run get_apps to see connected devices.")
     }
-}, async ({ pattern, maxResults, includeLayout, shortPath, summary, format }) => {
-    const result = await findComponents(pattern, { maxResults, includeLayout, shortPath, summary, format });
+}, async ({ pattern, maxResults, includeLayout, shortPath, summary, format, device }) => {
+    const result = await findComponents(pattern, { maxResults, includeLayout, shortPath, summary, format, device });
     if (!result.success) {
         return {
             content: [
@@ -1071,13 +1484,17 @@ registerToolWithTelemetry("find_components", {
 // Tool: Unified tap — tries fiber, accessibility, OCR, coordinate strategies
 registerToolWithTelemetry("tap", {
     description: "Tap a UI element. Automatically tries multiple strategies: fiber tree (React), accessibility tree (native), and OCR (visual). " +
-        "Auto-detects platform (iOS/Android). For coordinates, accepts pixels from screenshot and converts internally.\n\n" +
+        "Auto-detects platform (iOS/Android). For coordinates, pass raw pixel values from screenshot — tap handles all coordinate conversion internally (iOS pixel-to-point, scale factor adjustments).\n\n" +
+        "IMPORTANT: When both iOS and Android devices are connected, specify platform explicitly to avoid tapping on the wrong device.\n\n" +
         "Examples:\n" +
         "- tap(text=\"Submit\") — finds and taps element with matching text\n" +
         "- tap(testID=\"login-btn\") — finds by testID\n" +
         "- tap(component=\"HamburgerIcon\") — finds by React component name\n" +
-        "- tap(x=300, y=600) — taps at pixel coordinates from screenshot\n" +
-        "- tap(text=\"Menu\", strategy=\"ocr\") — forces OCR strategy only",
+        "- tap(x=300, y=600) — taps at pixel coordinates (LAST RESORT — only use if text/testID/component strategies all fail)\n" +
+        "- tap(text=\"Menu\", strategy=\"ocr\") — forces OCR strategy only\n" +
+        "- tap(x=300, y=600, native=true, platform=\"android\") — taps directly via ADB/simctl without React Native connection\n\n" +
+        "Returns a post-tap screenshot by default (set screenshot=false to disable). " +
+        "For coordinate/accessibility/OCR taps, automatically verifies the tap had a visual effect via before/after screenshot diff (set verify=false to disable).",
     inputSchema: {
         text: z
             .string()
@@ -1113,6 +1530,35 @@ registerToolWithTelemetry("tap", {
             .optional()
             .describe("Max parent levels to traverse when searching by component name (default: 15). " +
             "Increase if your component is deeply wrapped (e.g. inside multiple HOCs/animation wrappers)."),
+        native: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("When true, tap coordinates directly via ADB/simctl without requiring a React Native connection. " +
+            "Useful for interacting with native UI, system dialogs, or non-RN apps. Requires x/y coordinates."),
+        platform: z
+            .enum(["ios", "android"])
+            .optional()
+            .describe("Target platform. Required when both iOS and Android devices are connected. Auto-detected if only one platform is available."),
+        screenshot: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Capture and return a post-tap screenshot. Enabled by default. Set to false for fastest execution (no screenshots)."),
+        verify: z
+            .boolean()
+            .optional()
+            .describe("Run before/after screenshot diff to detect if the tap had a meaningful visual effect. " +
+            "Default: true for coordinate/accessibility/ocr strategies, false for fiber. Requires screenshot=true."),
+        burst: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Enable burst screenshot capture for enhanced verification. " +
+            "Captures 4 rapid screenshots (~150ms intervals) after the tap to detect transient visual feedback " +
+            "(press animations, highlights, ripples) that may settle before a standard after-screenshot. " +
+            "Results are stored in the image buffer (use get_images to inspect individual frames). " +
+            "Default: false."),
     },
 }, async (args) => {
     const result = await tap({
@@ -1124,19 +1570,51 @@ registerToolWithTelemetry("tap", {
         y: args.y,
         strategy: args.strategy,
         maxTraversalDepth: args.maxTraversalDepth,
+        native: args.native,
+        platform: args.platform,
+        screenshot: args.screenshot,
+        verify: args.verify,
+        burst: args.burst,
     });
-    const text = JSON.stringify(result, null, 2);
+    const { screenshot: screenshotData, ...resultWithoutScreenshot } = result;
+    const text = JSON.stringify(resultWithoutScreenshot, null, 2);
+    // Pack strategy mode + attempted strategies into errorContext for telemetry
+    // e.g. "s=ocr|fiber:no_pressable|ocr:no_match" or "s=auto|fiber:no_pressable|accessibility:not_found|ocr:no_match"
+    const stratPrefix = args.strategy && args.strategy !== "auto" ? `s=${args.strategy}|` : "";
+    const errorContext = result.attempted?.length
+        ? stratPrefix + result.attempted.map(a => `${a.strategy}:${a.reason.slice(0, 40)}`).join("|")
+        : undefined;
+    const content = [
+        { type: "text", text },
+    ];
+    if (screenshotData) {
+        content.push({
+            type: "image",
+            data: screenshotData.image,
+            mimeType: "image/jpeg",
+        });
+    }
     return {
-        content: [{ type: "text", text }],
+        content,
         isError: !result.success,
+        _errorMessage: !result.success
+            ? `${JSON.stringify(result.query)}|${result.error || ""}`
+            : undefined,
+        _errorContext: errorContext,
+        _meaningful: result.verification?.meaningful,
+        _changeRate: result.verification?.changeRate,
+        _tapStrategy: result.method,
+        _iosDriver: result.platform === "ios" ? (process.env.IOS_DRIVER?.toLowerCase() || "idb") : undefined,
     };
 });
 // Tool: Toggle Element Inspector programmatically
 registerToolWithTelemetry("toggle_element_inspector", {
     description: "Toggle React Native's Element Inspector overlay on/off. Rarely needed directly — get_inspector_selection auto-enables the inspector when called with coordinates. Use this only when you need manual control over the overlay visibility.",
-    inputSchema: {}
-}, async () => {
-    const result = await toggleElementInspector();
+    inputSchema: {
+        device: z.string().optional().describe("Target device name (substring match). Omit for default device. Run get_apps to see connected devices.")
+    }
+}, async ({ device }) => {
+    const result = await toggleElementInspector(device);
     if (!result.success) {
         return {
             content: [
@@ -1192,21 +1670,22 @@ registerToolWithTelemetry("get_inspector_selection", {
         y: z
             .number()
             .optional()
-            .describe("Y coordinate (in points). If provided with x, auto-taps at this location.")
+            .describe("Y coordinate (in points). If provided with x, auto-taps at this location."),
+        device: z.string().optional().describe("Target device name (substring match). Omit for default device. Run get_apps to see connected devices.")
     }
-}, async ({ x, y }) => {
+}, async ({ x, y, device }) => {
     // If coordinates provided, do the full flow: enable inspector -> tap -> read
     if (x !== undefined && y !== undefined) {
         // Check if inspector is active
-        const inspectorActive = await isInspectorActive();
+        const inspectorActive = await isInspectorActive(device);
         // Enable inspector if not active
         if (!inspectorActive) {
-            await toggleElementInspector();
+            await toggleElementInspector(device);
             // Wait for inspector to initialize
             await new Promise((resolve) => setTimeout(resolve, 300));
         }
         // Detect platform from connected app
-        const app = getFirstConnectedApp();
+        const app = device ? getConnectedAppByDevice(device) : getFirstConnectedApp();
         if (!app) {
             return {
                 content: [{ type: "text", text: "No app connected. Run scan_metro first." }],
@@ -1241,7 +1720,7 @@ registerToolWithTelemetry("get_inspector_selection", {
         await new Promise((resolve) => setTimeout(resolve, 200));
     }
     // Read the current selection
-    const result = await getInspectorSelection();
+    const result = await getInspectorSelection(device);
     if (!result.success) {
         return {
             content: [{ type: "text", text: `Error: ${result.error}` }],
@@ -1295,10 +1774,11 @@ registerToolWithTelemetry("inspect_at_point", {
             .boolean()
             .optional()
             .default(true)
-            .describe("Include position/dimensions (frame) in the output (default: true)")
+            .describe("Include position/dimensions (frame) in the output (default: true)"),
+        device: z.string().optional().describe("Target device name (substring match). Omit for default device. Run get_apps to see connected devices.")
     }
-}, async ({ x, y, includeProps, includeFrame }) => {
-    const result = await inspectAtPoint(x, y, { includeProps, includeFrame });
+}, async ({ x, y, includeProps, includeFrame, device }) => {
+    const result = await inspectAtPoint(x, y, { includeProps, includeFrame, device });
     if (!result.success) {
         return {
             content: [
@@ -1343,7 +1823,7 @@ registerToolWithTelemetry("inspect_at_point", {
 });
 // Tool: Get network requests
 registerToolWithTelemetry("get_network_requests", {
-    description: "Retrieve captured network requests from connected React Native app. Shows URL, method, status, and timing. Tip: Use summary=true first for stats overview (counts by method, status, domain), then fetch specific requests as needed.",
+    description: "Retrieve captured network requests from connected React Native app. Shows URL, method, status, and timing. Note: On Bridgeless targets (Expo SDK 52+) without the SDK, capture may miss early startup requests. Install react-native-ai-devtools-sdk for full capture with headers and response bodies. Tip: Use summary=true first for stats overview.",
     inputSchema: {
         maxRequests: z
             .number()
@@ -1362,16 +1842,67 @@ registerToolWithTelemetry("get_network_requests", {
             .boolean()
             .optional()
             .default(false)
-            .describe("Return statistics only (count, methods, domains, status codes). Use for quick overview.")
+            .describe("Return statistics only (count, methods, domains, status codes). Use for quick overview."),
+        device: z.string().optional().describe("Target device name (substring match). Omit for all devices. Run get_apps to see connected devices.")
+    }
+}, async ({ maxRequests, method, urlPattern, status, format, summary, device }) => {
+    // Check if SDK is installed — prefer SDK data over CDP/interceptor buffer
+    const sdkAvailable = await isSDKInstalled();
+    if (sdkAvailable) {
+        if (summary) {
+            const sdkStats = await getSDKNetworkStats();
+            if (sdkStats.success) {
+                const s = sdkStats.data;
+                const lines = [];
+                lines.push(`Total requests: ${s.total}`);
+                lines.push(`Completed: ${s.completed}`);
+                lines.push(`Errors: ${s.errors}`);
+                if (s.avgDuration != null)
+                    lines.push(`Avg duration: ${s.avgDuration}ms`);
+                if (s.byMethod && Object.keys(s.byMethod).length > 0) {
+                    lines.push("\nBy Method:");
+                    for (const [m, c] of Object.entries(s.byMethod))
+                        lines.push(`  ${m}: ${c}`);
+                }
+                if (s.byStatus && Object.keys(s.byStatus).length > 0) {
+                    lines.push("\nBy Status:");
+                    for (const [st, c] of Object.entries(s.byStatus))
+                        lines.push(`  ${st}: ${c}`);
+                }
+                if (s.byDomain && Object.keys(s.byDomain).length > 0) {
+                    lines.push("\nBy Domain:");
+                    for (const [d, c] of Object.entries(s.byDomain).sort((a, b) => b[1] - a[1]).slice(0, 10))
+                        lines.push(`  ${d}: ${c}`);
+                }
+                return { content: [{ type: "text", text: `Network Summary (SDK):\n\n${lines.join("\n")}` }] };
+            }
+        }
+        const sdkResult = await querySDKNetwork({ count: maxRequests, method, urlPattern, status });
+        if (sdkResult.success) {
+            const entries = sdkResult.data;
+            if (entries.length === 0) {
+                return { content: [{ type: "text", text: "No network requests captured yet." }] };
+            }
+            const lines = entries.map((r) => {
+                const time = new Date(r.timestamp).toLocaleTimeString();
+                const st = r.status ?? "pending";
+                const dur = r.duration != null ? `${r.duration}ms` : "-";
+                return `[${r.id}] ${time} ${r.method} ${st} ${dur} ${r.url}`;
+            });
+            return { content: [{ type: "text", text: `Network Requests (${entries.length} entries, SDK):\n\n${lines.join("\n")}` }] };
+        }
     }
-}, async ({ maxRequests, method, urlPattern, status, format, summary }) => {
+    // Fallback: read from in-process buffer (CDP/interceptor)
     // Return summary if requested
     if (summary) {
-        const stats = getNetworkStats(networkBuffer);
+        const stats = getNetworkStats(resolveNetworkBuffer(device));
         let connectionWarning = "";
-        if (networkBuffer.size === 0) {
-            const connStatus = await checkAndEnsureConnection();
+        if (resolveNetworkBuffer(device).size === 0) {
+            const connStatus = await checkAndEnsureConnection(device);
             connectionWarning = connStatus.message ? `\n\n${connStatus.message}` : "";
+            if (!sdkAvailable) {
+                connectionWarning += "\n\n[TIP] For full network capture including startup requests and response bodies, install the SDK: npm install react-native-ai-devtools-sdk";
+            }
         }
         return {
             content: [
@@ -1382,7 +1913,7 @@ registerToolWithTelemetry("get_network_requests", {
             ]
         };
     }
-    const { requests, count, formatted } = getNetworkRequests(networkBuffer, {
+    const { requests, count, formatted } = getNetworkRequests(resolveNetworkBuffer(device), {
         maxRequests,
         method,
         urlPattern,
@@ -1391,8 +1922,11 @@ registerToolWithTelemetry("get_network_requests", {
     // Check connection health
     let connectionWarning = "";
     if (count === 0) {
-        const connStatus = await checkAndEnsureConnection();
+        const connStatus = await checkAndEnsureConnection(device);
         connectionWarning = connStatus.message ? `\n\n${connStatus.message}` : "";
+        if (!sdkAvailable) {
+            connectionWarning += "\n\n[TIP] For full network capture including startup requests and response bodies, install the SDK: npm install react-native-ai-devtools-sdk";
+        }
     }
     else {
         const passive = getPassiveConnectionStatus();
@@ -1435,7 +1969,10 @@ registerToolWithTelemetry("get_network_requests", {
             }
         ]
     };
-});
+}, 
+// Empty result detector: buffer has no entries at all
+() => { let total = 0; for (const b of networkBuffers.values())
+    total += b.size; return total === 0; });
 // Tool: Search network requests
 registerToolWithTelemetry("search_network", {
     description: "Search network requests by URL pattern (case-insensitive)",
@@ -1446,14 +1983,36 @@ registerToolWithTelemetry("search_network", {
             .enum(["text", "tonl"])
             .optional()
             .default("tonl")
-            .describe("Output format: 'text' or 'tonl' (default, compact token-optimized format)")
+            .describe("Output format: 'text' or 'tonl' (default, compact token-optimized format)"),
+        device: z.string().optional().describe("Target device name (substring match). Omit for all devices. Run get_apps to see connected devices.")
+    }
+}, async ({ urlPattern, maxResults, format, device }) => {
+    // Check if SDK is installed — prefer SDK data
+    const sdkAvailable = await isSDKInstalled();
+    if (sdkAvailable) {
+        const sdkResult = await querySDKNetwork({ count: maxResults, urlPattern });
+        if (sdkResult.success) {
+            const entries = sdkResult.data;
+            if (entries.length === 0) {
+                return { content: [{ type: "text", text: `No network requests matching "${urlPattern}" found.` }] };
+            }
+            const lines = entries.map((r) => {
+                const time = new Date(r.timestamp).toLocaleTimeString();
+                const st = r.status ?? "pending";
+                const dur = r.duration != null ? `${r.duration}ms` : "-";
+                return `[${r.id}] ${time} ${r.method} ${st} ${dur} ${r.url}`;
+            });
+            if (format === "tonl") {
+                return { content: [{ type: "text", text: `Network search results for "${urlPattern}" (${entries.length} matches, SDK):\n\n${lines.join("\n")}` }] };
+            }
+            return { content: [{ type: "text", text: `Network search results for "${urlPattern}" (${entries.length} matches, SDK):\n\n${lines.join("\n")}` }] };
+        }
     }
-}, async ({ urlPattern, maxResults, format }) => {
-    const { requests, count, formatted } = searchNetworkRequests(networkBuffer, urlPattern, maxResults);
+    const { requests, count, formatted } = searchNetworkRequests(resolveNetworkBuffer(device), urlPattern, maxResults);
     // Check connection health
     let connectionWarning = "";
     if (count === 0) {
-        const status = await checkAndEnsureConnection();
+        const status = await checkAndEnsureConnection(device);
         connectionWarning = status.message ? `\n\n${status.message}` : "";
     }
     else {
@@ -1485,7 +2044,7 @@ registerToolWithTelemetry("search_network", {
 });
 // Tool: Get request details
 registerToolWithTelemetry("get_request_details", {
-    description: "Get full details of a specific network request including headers, body, and timing. Use get_network_requests first to find the request ID.",
+    description: "Get full details of a specific network request including headers, body, and timing. With the SDK installed, includes full request/response bodies. Without SDK, bodies are not available on most targets. Use get_network_requests first to find the request ID.",
     inputSchema: {
         requestId: z.string().describe("The request ID to get details for"),
         maxBodyLength: z.coerce
@@ -1497,12 +2056,60 @@ registerToolWithTelemetry("get_request_details", {
             .boolean()
             .optional()
             .default(false)
-            .describe("Disable body truncation. Tip: Use when you need to inspect full JSON payloads.")
+            .describe("Disable body truncation. Tip: Use when you need to inspect full JSON payloads."),
+        device: z.string().optional().describe("Target device name (substring match). Omit for all devices. Run get_apps to see connected devices.")
+    }
+}, async ({ requestId, maxBodyLength, verbose, device }) => {
+    // Check SDK first — it has full headers and body
+    const sdkAvailable = await isSDKInstalled();
+    if (sdkAvailable) {
+        const sdkResult = await getSDKNetworkEntry(requestId);
+        if (sdkResult.success && sdkResult.data) {
+            const r = sdkResult.data;
+            const lines = [];
+            lines.push(`=== ${r.method} ${r.url} ===`);
+            lines.push(`Request ID: ${r.id}`);
+            lines.push(`Time: ${new Date(r.timestamp).toISOString()}`);
+            lines.push(`Status: ${r.status ?? "pending"} ${r.statusText ?? ""}`);
+            if (r.duration != null)
+                lines.push(`Duration: ${r.duration}ms`);
+            if (r.mimeType)
+                lines.push(`Content-Type: ${r.mimeType}`);
+            if (r.error)
+                lines.push(`Error: ${r.error}`);
+            if (r.requestHeaders && Object.keys(r.requestHeaders).length > 0) {
+                lines.push("\n--- Request Headers ---");
+                for (const [k, v] of Object.entries(r.requestHeaders))
+                    lines.push(`${k}: ${v}`);
+            }
+            if (r.requestBody) {
+                lines.push("\n--- Request Body ---");
+                let body = r.requestBody;
+                if (!verbose && maxBodyLength > 0 && body.length > maxBodyLength) {
+                    body = body.slice(0, maxBodyLength) + `... [truncated: ${r.requestBody.length} chars]`;
+                }
+                lines.push(body);
+            }
+            if (r.responseHeaders && Object.keys(r.responseHeaders).length > 0) {
+                lines.push("\n--- Response Headers ---");
+                for (const [k, v] of Object.entries(r.responseHeaders))
+                    lines.push(`${k}: ${v}`);
+            }
+            if (r.responseBody) {
+                lines.push("\n--- Response Body ---");
+                let body = r.responseBody;
+                if (!verbose && maxBodyLength > 0 && body.length > maxBodyLength) {
+                    body = body.slice(0, maxBodyLength) + `... [truncated: ${r.responseBody.length} chars]`;
+                }
+                lines.push(body);
+            }
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
     }
-}, async ({ requestId, maxBodyLength, verbose }) => {
-    const request = networkBuffer.get(requestId);
+    // Fallback: read from in-process buffer
+    const request = resolveNetworkBuffer(device).get(requestId);
     if (!request) {
-        const status = await checkAndEnsureConnection();
+        const status = await checkAndEnsureConnection(device);
         const connectionNote = status.message ? `\n\n${status.message}` : "";
         return {
             content: [
@@ -1526,13 +2133,45 @@ registerToolWithTelemetry("get_request_details", {
 // Tool: Get network stats
 registerToolWithTelemetry("get_network_stats", {
     description: "Get statistics about captured network requests: counts by method, status code, and domain.",
-    inputSchema: {}
-}, async () => {
-    const stats = getNetworkStats(networkBuffer);
+    inputSchema: {
+        device: z.string().optional().describe("Target device name (substring match). Omit for all devices. Run get_apps to see connected devices.")
+    }
+}, async ({ device }) => {
+    // Check if SDK is installed — prefer SDK data
+    const sdkAvailable = await isSDKInstalled();
+    if (sdkAvailable) {
+        const sdkStats = await getSDKNetworkStats();
+        if (sdkStats.success) {
+            const s = sdkStats.data;
+            const lines = [];
+            lines.push(`Total requests: ${s.total}`);
+            lines.push(`Completed: ${s.completed}`);
+            lines.push(`Errors: ${s.errors}`);
+            if (s.avgDuration != null)
+                lines.push(`Avg duration: ${s.avgDuration}ms`);
+            if (s.byMethod && Object.keys(s.byMethod).length > 0) {
+                lines.push("\nBy Method:");
+                for (const [m, c] of Object.entries(s.byMethod))
+                    lines.push(`  ${m}: ${c}`);
+            }
+            if (s.byStatus && Object.keys(s.byStatus).length > 0) {
+                lines.push("\nBy Status:");
+                for (const [st, c] of Object.entries(s.byStatus))
+                    lines.push(`  ${st}: ${c}`);
+            }
+            if (s.byDomain && Object.keys(s.byDomain).length > 0) {
+                lines.push("\nBy Domain:");
+                for (const [d, c] of Object.entries(s.byDomain).sort((a, b) => b[1] - a[1]).slice(0, 10))
+                    lines.push(`  ${d}: ${c}`);
+            }
+            return { content: [{ type: "text", text: `Network Statistics (SDK):\n\n${lines.join("\n")}` }] };
+        }
+    }
+    const stats = getNetworkStats(resolveNetworkBuffer(device));
     // Check connection health
     let connectionWarning = "";
-    if (networkBuffer.size === 0) {
-        const status = await checkAndEnsureConnection();
+    if (resolveNetworkBuffer(device).size === 0) {
+        const status = await checkAndEnsureConnection(device);
         connectionWarning = status.message ? `\n\n${status.message}` : "";
     }
     else {
@@ -1549,18 +2188,105 @@ registerToolWithTelemetry("get_network_stats", {
             }
         ]
     };
-});
+}, 
+// Empty result detector: buffer has no entries at all
+() => { let total = 0; for (const b of networkBuffers.values())
+    total += b.size; return total === 0; });
 // Tool: Clear network requests
 registerToolWithTelemetry("clear_network", {
     description: "Clear the network request buffer",
-    inputSchema: {}
-}, async () => {
-    const count = networkBuffer.clear();
+    inputSchema: {
+        device: z.string().optional().describe("Target device name (substring match). Omit to clear all devices. Run get_apps to see connected devices.")
+    }
+}, async ({ device }) => {
+    let totalCleared = 0;
+    if (device) {
+        const app = getConnectedAppByDevice(device);
+        if (!app)
+            throw new Error(`No connected device matches "${device}"`);
+        const deviceName = app.deviceInfo.deviceName || app.deviceInfo.title || "unknown";
+        totalCleared = getNetworkBuffer(deviceName).clear();
+    }
+    else {
+        for (const buffer of networkBuffers.values()) {
+            totalCleared += buffer.clear();
+        }
+    }
+    // Also clear SDK buffer if available
+    const sdkAvailable = await isSDKInstalled();
+    if (sdkAvailable) {
+        const sdkResult = await clearSDKNetwork();
+        if (sdkResult.success && sdkResult.count) {
+            totalCleared += sdkResult.count;
+        }
+    }
     return {
         content: [
             {
                 type: "text",
-                text: `Cleared ${count} network requests from buffer.`
+                text: `Cleared ${totalCleared} network requests from buffer.`
+            }
+        ]
+    };
+});
+// Tool: Get images from shared image buffer
+registerToolWithTelemetry("get_images", {
+    description: "Access the shared image buffer containing screenshots from all tools (ios_screenshot, android_screenshot, ocr_screenshot, tap verification). Returns metadata only by default — use id or groupId+frameIndex to retrieve actual image data. Tap burst verification stores frame groups here when burst=true is used.",
+    inputSchema: {
+        list: z.boolean().optional().describe("List all entries and groups (metadata only, no image data)"),
+        id: z.string().optional().describe("Retrieve a specific image by ID (returns image data)"),
+        groupId: z.string().optional().describe("List frames in a group (metadata only), or combine with frameIndex to retrieve a specific frame"),
+        frameIndex: z.coerce.number().optional().describe("Retrieve a specific frame from a group (requires groupId)"),
+        last: z.coerce.number().optional().describe("Return the N most recent entries (metadata only)"),
+        source: z.string().optional().describe("Filter entries by source"),
+        clear: z.boolean().optional().describe("Clear the buffer")
+    }
+}, async ({ id, groupId, frameIndex, last, source, clear }) => {
+    if (clear) {
+        const count = imageBuffer.clear();
+        return {
+            content: [{ type: "text", text: `Cleared ${count} images from buffer.` }]
+        };
+    }
+    if (id) {
+        const entry = imageBuffer.getById(id);
+        if (!entry) {
+            return {
+                content: [{ type: "text", text: `No image found with id "${id}".` }],
+                isError: true
+            };
+        }
+        const { image, ...meta } = entry;
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(meta, null, 2) },
+                { type: "image", data: image.toString("base64"), mimeType: "image/png" }
+            ]
+        };
+    }
+    if (groupId !== undefined && frameIndex !== undefined) {
+        const entry = imageBuffer.getByGroupFrame(groupId, frameIndex);
+        if (!entry) {
+            return {
+                content: [{ type: "text", text: `No frame ${frameIndex} found in group "${groupId}".` }],
+                isError: true
+            };
+        }
+        const { image, ...meta } = entry;
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(meta, null, 2) },
+                { type: "image", data: image.toString("base64"), mimeType: "image/png" }
+            ]
+        };
+    }
+    const entries = imageBuffer.listEntries({ source, groupId, last });
+    const groups = imageBuffer.listGroups();
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ entries, groups, total: imageBuffer.size }, null, 2)
             }
         ]
     };
@@ -1568,9 +2294,11 @@ registerToolWithTelemetry("clear_network", {
 // Tool: Reload the app
 registerToolWithTelemetry("reload_app", {
     description: "Reload the React Native app (triggers JavaScript bundle reload like pressing 'r' in Metro). Will auto-connect to Metro if no connection exists. Note: After reload, the app may take a few seconds to fully restart and become responsive — wait before running other tools. IMPORTANT: React Native has Fast Refresh enabled by default - code changes are automatically applied without needing reload. Only use when: (1) logs/behavior don't reflect code changes after a few seconds, (2) app is in broken/error state, or (3) need to reset app state completely (navigation stack, context, etc.).",
-    inputSchema: {}
-}, async () => {
-    const result = await reloadApp();
+    inputSchema: {
+        device: z.string().optional().describe("Target device name (substring match). Omit for default device. Run get_apps to see connected devices.")
+    }
+}, async ({ device }) => {
+    const result = await reloadApp(device);
     if (!result.success) {
         return {
             content: [
@@ -1591,6 +2319,170 @@ registerToolWithTelemetry("reload_app", {
         ]
     };
 });
+// Tool: LogBox control (replaces dismiss_logbox)
+registerToolWithTelemetry("logbox", {
+    description: "Interact with React Native's LogBox overlay (dev mode only). " +
+        'Actions: "dismiss" clears all entries and returns their content. ' +
+        '"push" displays a message in the LogBox error banner (visible to the developer watching the device). ' +
+        '"ignore" adds patterns to suppress future LogBox entries for this session. ' +
+        '"detect" reads current LogBox state without modifying it. ' +
+        "Only works in __DEV__ mode — LogBox does not exist in production builds.",
+    inputSchema: {
+        action: z.enum(["dismiss", "push", "ignore", "detect"]).describe('Action to perform: "dismiss", "push", "ignore", or "detect"'),
+        message: z.string().optional().describe('Message to push into LogBox (required when action="push")'),
+        level: z.enum(["error", "warning"]).optional().describe('LogBox level for push (default: "error"). Only "error" shows a visible bottom banner; "warning" is stored but not visually shown unless LogBox is already open'),
+        expanded: z.boolean().optional().describe('When true, opens the full-screen LogBox detail view instead of the minimized bottom banner. Useful for important messages with clickable URLs (default: false)'),
+        subtitle: z.string().optional().describe('Additional info shown in the call stack area when expanded=true (default: "MCP Server"). Use for context like "License Check", "Usage Limit", etc.'),
+        target: z.enum(["logbox", "metro"]).optional().describe('Where to push the message (default: "logbox"). "logbox" shows on device screen, "metro" outputs to Metro terminal via console.log'),
+        patterns: z.array(z.string()).optional().describe('Patterns to ignore (required when action="ignore"), e.g. ["[APOLLO]", "deprecated"]'),
+        device: z.string().optional().describe("Target device name (substring match). Omit for default device. Run get_apps to see connected devices.")
+    }
+}, async ({ action, message, level, expanded, subtitle, target, patterns, device }) => {
+    if (action === "dismiss") {
+        const result = await dismissLogBox(device);
+        if (result === null) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "LogBox not available. This can happen if: (1) the app is a production build (__DEV__ is false), (2) no React Native app is connected, or (3) the Metro module registry is not accessible."
+                    }
+                ]
+            };
+        }
+        if (result.totalDismissed === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "No LogBox entries to dismiss."
+                    }
+                ]
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: formatDismissedEntries(result)
+                }
+            ]
+        };
+    }
+    if (action === "push") {
+        if (!message) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: 'Error: "message" parameter is required when action is "push".'
+                    }
+                ],
+                isError: true
+            };
+        }
+        const success = await pushLogBox(message, level || "error", expanded || false, target || "logbox", subtitle, device);
+        if (!success) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Failed to push message to LogBox. This can happen if: (1) the app is a production build, (2) no React Native app is connected, or (3) the Metro module registry is not accessible."
+                    }
+                ]
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: target === "metro"
+                        ? `Message pushed to Metro terminal: "${message}"`
+                        : `Message pushed to LogBox as ${level || "error"}: "${message}"`
+                }
+            ]
+        };
+    }
+    if (action === "ignore") {
+        if (!patterns || patterns.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: 'Error: "patterns" parameter is required when action is "ignore" (non-empty array of strings).'
+                    }
+                ],
+                isError: true
+            };
+        }
+        const activePatterns = await addLogBoxIgnorePatterns(patterns, device);
+        if (activePatterns === null) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Failed to add ignore patterns. This can happen if: (1) the app is a production build, (2) no React Native app is connected, or (3) the Metro module registry is not accessible."
+                    }
+                ]
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Added ignore patterns: ${patterns.map((p) => `"${p}"`).join(", ")}\n\nAll active ignore patterns: ${activePatterns.map((p) => `"${p}"`).join(", ")}`
+                }
+            ]
+        };
+    }
+    if (action === "detect") {
+        const state = await detectLogBox(device);
+        if (state === null) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "LogBox not available. This can happen if: (1) the app is a production build (__DEV__ is false), (2) no React Native app is connected, or (3) the Metro module registry is not accessible."
+                    }
+                ]
+            };
+        }
+        if (state.total === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "No LogBox entries detected."
+                    }
+                ]
+            };
+        }
+        const MAX_MSG_LENGTH = 150;
+        let output = `LogBox state: ${state.total} entr${state.total === 1 ? "y" : "ies"} (${state.errors} error${state.errors !== 1 ? "s" : ""}, ${state.warnings} warning${state.warnings !== 1 ? "s" : ""}, ${state.fatals} fatal${state.fatals !== 1 ? "s" : ""})\n`;
+        for (const entry of state.entries) {
+            const truncated = entry.message.length > MAX_MSG_LENGTH ? entry.message.substring(0, MAX_MSG_LENGTH) + "..." : entry.message;
+            const countStr = entry.count > 1 ? ` (x${entry.count})` : "";
+            output += `\n[${entry.level}] ${truncated}${countStr}`;
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: output
+                }
+            ]
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Unknown action: "${action}". Use "dismiss", "push", "ignore", or "detect".`
+            }
+        ],
+        isError: true
+    };
+});
 // ============================================================================
 // Bundle/Build Error Tools
 // ============================================================================
@@ -1776,7 +2668,7 @@ registerToolWithTelemetry("list_android_devices", {
 });
 // Tool: Android screenshot
 registerToolWithTelemetry("android_screenshot", {
-    description: "Take a screenshot from an Android device/emulator. Returns the image data that can be displayed.",
+    description: "Take a screenshot from an Android device/emulator. Returns the image and a screen layout overlay showing visible React components with names, text content, hierarchy, and tap-ready pixel coordinates. Use component names for inspect_component/find_components. Use tap(text=...) for interaction — only fall back to tap(x,y) coordinates from the layout if all tap strategies fail.",
     inputSchema: {
         outputPath: z
             .string()
@@ -1833,16 +2725,64 @@ registerToolWithTelemetry("android_screenshot", {
         catch {
             // Use defaults
         }
-        infoText += `\n📱 Android uses PIXELS for tap coordinates (same as screenshot)`;
+        // Enrich with screen layout data (component names + tap coordinates)
+        // Android: density ratio = densityDpi / 160 (160dpi = 1dp = 1px baseline)
+        const androidPixelRatio = densityDpi / 160;
+        let layoutText = null;
+        try {
+            layoutText = await enrichScreenshotWithLayout(androidPixelRatio, result.scaleFactor || 1);
+        }
+        catch {
+            // Non-fatal: screenshot works without layout enrichment
+        }
+        infoText += `\n📱 Android uses PIXELS for all coordinates`;
         if (result.scaleFactor && result.scaleFactor > 1) {
-            infoText += `\n⚠️ Image was scaled down to fit API limits. Scale factor: ${result.scaleFactor.toFixed(3)}`;
-            infoText += `\n📐 To convert image coords to tap coords: multiply by ${result.scaleFactor.toFixed(3)}`;
+            infoText += `\n🖼️ Image was scaled down to fit API limits (scale: ${result.scaleFactor.toFixed(3)})`;
+            infoText += `\n📐 tap() handles coordinate conversion automatically — pass pixel coords from this image directly`;
         }
         else {
             infoText += `\n📐 Screenshot coords = tap coords (no conversion needed)`;
         }
         infoText += `\n⚠️ Status bar: ${statusBarPixels}px (${statusBarDp}dp) from top - app content starts below this`;
         infoText += `\n📊 Display density: ${densityDpi}dpi`;
+        if (layoutText) {
+            infoText += `\n\n📋 Screen Layout (components with tap coordinates in pixels):`;
+            infoText += `\n${layoutText}`;
+            infoText += `\n\n💡 Next steps:`;
+            infoText += `\n  • tap(text="Button Label") — tap element by visible text (preferred)`;
+            infoText += `\n  • tap(testID="id") or tap(component="Name") — tap by testID or component name`;
+            infoText += `\n  • tap(x=<px>, y=<px>) — use tap coordinates from layout above ONLY if text/testID/component tap fails`;
+            infoText += `\n  • inspect_component("ComponentName") — inspect a component from the layout above`;
+        }
+        else {
+            infoText += `\n\n💡 Next steps:`;
+            infoText += `\n  • tap(text="Button Label") — tap element by visible text`;
+            infoText += `\n  • tap(x=<px>, y=<px>) — tap at coordinates from this screenshot`;
+            infoText += `\n  • android_describe_all — get full UI tree with exact tap coordinates`;
+            infoText += `\n  • android_find_element(text="...") — find element coordinates without tapping`;
+        }
+        // Check for LogBox overlay (uses default CDP device — native deviceId cannot be mapped to CDP device name)
+        try {
+            const logBoxState = await detectLogBox();
+            if (logBoxState && logBoxState.total > 0) {
+                infoText += formatLogBoxWarning(logBoxState);
+            }
+        }
+        catch {
+            // Non-fatal: LogBox detection failure should not break screenshot
+        }
+        imageBuffer.add({
+            id: `android-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+            image: result.data,
+            timestamp: Date.now(),
+            source: "android_screenshot",
+            metadata: {
+                width: result.originalWidth || 0,
+                height: result.originalHeight || 0,
+                scaleFactor: result.scaleFactor || 1,
+                platform: "android",
+            },
+        });
         return {
             content: [
                 {
@@ -2090,11 +3030,24 @@ server.registerTool("android_describe_all", {
     }
 }, async ({ deviceId }) => {
     const result = await androidDescribeAll(deviceId);
+    let text = result.success ? result.formatted : `Error: ${result.error}`;
+    // Check for LogBox overlay
+    if (result.success) {
+        try {
+            const logBoxState = await detectLogBox();
+            if (logBoxState && logBoxState.total > 0) {
+                text += formatLogBoxWarning(logBoxState);
+            }
+        }
+        catch {
+            // Non-fatal: LogBox detection failure should not break describe_all
+        }
+    }
     return {
         content: [
             {
                 type: "text",
-                text: result.success ? result.formatted : `Error: ${result.error}`
+                text
             }
         ],
         isError: !result.success
@@ -2277,7 +3230,7 @@ registerToolWithTelemetry("list_ios_simulators", {
 });
 // Tool: iOS screenshot
 registerToolWithTelemetry("ios_screenshot", {
-    description: "Take a screenshot from an iOS simulator. Returns the image data that can be displayed.",
+    description: "Take a screenshot from an iOS simulator. Returns the image and a screen layout overlay showing visible React components with names, text content, hierarchy, and tap-ready pixel coordinates. Use component names for inspect_component/find_components. Use tap(text=...) for interaction — only fall back to tap(x,y) coordinates from the layout if all tap strategies fail.",
     inputSchema: {
         outputPath: z
             .string()
@@ -2361,16 +3314,59 @@ registerToolWithTelemetry("ios_screenshot", {
             pointHeight = Math.round(pixelHeight / scaleFactor);
         }
         const safeAreaOffsetPixels = safeAreaTop * scaleFactor;
+        // Enrich with screen layout data (component names + tap coordinates)
+        let layoutText = null;
+        try {
+            layoutText = await enrichScreenshotWithLayout(scaleFactor, result.scaleFactor || 1);
+        }
+        catch {
+            // Non-fatal: screenshot works without layout enrichment
+        }
         let infoText = `Screenshot captured (${pixelWidth}x${pixelHeight} pixels)`;
-        infoText += `\n📱 iOS tap coordinates use POINTS: ${pointWidth}x${pointHeight}`;
-        infoText += `\n📐 To convert screenshot coords to tap points:`;
-        infoText += `\n   tap_x = pixel_x / ${scaleFactor}`;
-        infoText += `\n   tap_y = pixel_y / ${scaleFactor}`;
+        infoText += `\n📱 iOS screen: ${pointWidth}x${pointHeight} points (${scaleFactor}x scale)`;
+        infoText += `\n📐 tap() handles pixel-to-point conversion automatically — pass pixel coords from this image directly`;
         infoText += `\n⚠️ Status bar + safe area: ${safeAreaTop} points (${safeAreaOffsetPixels} pixels) from top`;
         if (result.scaleFactor && result.scaleFactor > 1) {
             infoText += `\n🖼️ Image was scaled down to fit API limits (scale: ${result.scaleFactor.toFixed(3)})`;
         }
-        infoText += `\n💡 Use ios_describe_all to get exact element coordinates`;
+        if (layoutText) {
+            infoText += `\n\n📋 Screen Layout (components with tap coordinates in pixels):`;
+            infoText += `\n${layoutText}`;
+            infoText += `\n\n💡 Next steps:`;
+            infoText += `\n  • tap(text="Button Label") — tap element by visible text (preferred)`;
+            infoText += `\n  • tap(testID="id") or tap(component="Name") — tap by testID or component name`;
+            infoText += `\n  • tap(x=<px>, y=<px>) — use tap coordinates from layout above ONLY if text/testID/component tap fails`;
+            infoText += `\n  • inspect_component("ComponentName") — inspect a component from the layout above`;
+        }
+        else {
+            infoText += `\n\n💡 Next steps:`;
+            infoText += `\n  • tap(text="Button Label") — tap element by visible text`;
+            infoText += `\n  • tap(x=<px>, y=<px>) — tap at coordinates from this screenshot`;
+            infoText += `\n  • ios_describe_all — get full UI tree with exact tap coordinates`;
+            infoText += `\n  • ios_find_element(label="...") — find element coordinates without tapping`;
+        }
+        // Check for LogBox overlay (uses default CDP device — native UDID cannot be mapped to CDP device name)
+        try {
+            const logBoxState = await detectLogBox();
+            if (logBoxState && logBoxState.total > 0) {
+                infoText += formatLogBoxWarning(logBoxState);
+            }
+        }
+        catch {
+            // Non-fatal: LogBox detection failure should not break screenshot
+        }
+        imageBuffer.add({
+            id: `ios-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+            image: result.data,
+            timestamp: Date.now(),
+            source: "ios_screenshot",
+            metadata: {
+                width: result.originalWidth || 0,
+                height: result.originalHeight || 0,
+                scaleFactor: result.scaleFactor || 1,
+                platform: "ios",
+            },
+        });
         return {
             content: [
                 {
@@ -2407,32 +3403,39 @@ registerToolWithTelemetry("ocr_screenshot", {
             .describe("Optional device ID (Android) or UDID (iOS). Uses first available device if not specified.")
     }
 }, async ({ platform, deviceId }) => {
-    // Call the HTTP endpoint for OCR (allows hot-reload without session restart)
-    // Prefer child process port, fall back to in-process port
-    const port = getDebugServerPort();
-    if (!port) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: "Debug HTTP server not running"
-                }
-            ],
-            isError: true
-        };
-    }
     try {
-        const params = new URLSearchParams({ platform, engine: "auto" });
-        if (deviceId)
-            params.set("deviceId", deviceId);
-        const response = await fetch(`http://localhost:${port}/api/ocr?${params}`);
-        const ocrResult = await response.json();
+        // Take screenshot
+        const screenshotResult = platform === "android"
+            ? await androidScreenshot(undefined, deviceId)
+            : await iosScreenshot(undefined, deviceId);
+        if (!screenshotResult.success || !screenshotResult.data) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Screenshot failed: ${screenshotResult.error || "No image data"}`
+                    }
+                ],
+                isError: true
+            };
+        }
+        // Calculate device pixel ratio for iOS
+        const devicePixelRatio = platform === "ios" && screenshotResult.originalWidth && screenshotResult.originalHeight
+            ? inferIOSDevicePixelRatio(screenshotResult.originalWidth, screenshotResult.originalHeight)
+            : 1;
+        // Run OCR on the screenshot
+        const scaleFactor = screenshotResult.scaleFactor || 1;
+        const ocrResult = await recognizeText(screenshotResult.data, {
+            scaleFactor,
+            platform,
+            devicePixelRatio
+        });
         if (!ocrResult.success) {
             return {
                 content: [
                     {
                         type: "text",
-                        text: `OCR failed: ${ocrResult.error || "Unknown error"}`
+                        text: `OCR failed: no text recognized`
                     }
                 ],
                 isError: true
@@ -2455,8 +3458,36 @@ registerToolWithTelemetry("ocr_screenshot", {
             confidence: Math.round(ocrResult.confidence || 0),
             elementCount: elements.length,
             elements,
-            note: "tapX/tapY are ready to use with tap commands (already converted for platform)"
+            note: "tapX/tapY are in device pixels — pass directly to tap(x, y) for automatic platform conversion"
         };
+        // Check for LogBox overlay (uses default CDP device — native deviceId cannot be mapped to CDP device name)
+        try {
+            const logBoxState = await detectLogBox();
+            if (logBoxState && logBoxState.total > 0) {
+                result.logBoxWarning = formatLogBoxWarning(logBoxState).trim();
+            }
+        }
+        catch {
+            // Non-fatal: LogBox detection failure should not break OCR
+        }
+        // Store screenshot in image buffer
+        try {
+            imageBuffer.add({
+                id: `ocr-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+                image: screenshotResult.data,
+                timestamp: Date.now(),
+                source: "ocr_screenshot",
+                metadata: {
+                    width: screenshotResult.originalWidth || 0,
+                    height: screenshotResult.originalHeight || 0,
+                    scaleFactor,
+                    platform,
+                },
+            });
+        }
+        catch {
+            // Non-fatal: image buffer write failure should not break OCR response
+        }
         return {
             content: [
                 {
@@ -2471,7 +3502,7 @@ registerToolWithTelemetry("ocr_screenshot", {
             content: [
                 {
                     type: "text",
-                    text: `OCR request failed: ${error instanceof Error ? error.message : String(error)}`
+                    text: `OCR failed: ${error instanceof Error ? error.message : String(error)}`
                 }
             ],
             isError: true
@@ -2688,11 +3719,24 @@ server.registerTool("ios_describe_all", {
     }
 }, async ({ udid }) => {
     const result = await iosDescribeAll(udid);
+    let text = result.success ? result.result : `Error: ${result.error}`;
+    // Check for LogBox overlay
+    if (result.success) {
+        try {
+            const logBoxState = await detectLogBox();
+            if (logBoxState && logBoxState.total > 0) {
+                text += formatLogBoxWarning(logBoxState);
+            }
+        }
+        catch {
+            // Non-fatal: LogBox detection failure should not break describe_all
+        }
+    }
     return {
         content: [
             {
                 type: "text",
-                text: result.success ? result.result : `Error: ${result.error}`
+                text
             }
         ],
         isError: !result.success
@@ -2758,7 +3802,7 @@ server.registerTool("ios_find_element", {
         `  Value: "${el.value}"`,
         `  Type: ${el.type}`,
         `  Frame: {x: ${el.frame.x}, y: ${el.frame.y}, w: ${el.frame.width}, h: ${el.frame.height}}`,
-        `  Center (tap coords): (${el.center.x}, ${el.center.y})`,
+        `  Center (tap coords): (${el.center.x}, ${el.center.y}) — iOS points. Use tap(text="...") or tap(testID="...") for reliable targeting.`,
         `  Enabled: ${el.enabled}`
     ].join("\n");
     return {
@@ -2825,109 +3869,43 @@ server.registerTool("ios_wait_for_element", {
         `  Label: "${el.label}"`,
         `  Value: "${el.value}"`,
         `  Type: ${el.type}`,
-        `  Center (tap coords): (${el.center.x}, ${el.center.y})`,
+        `  Center (tap coords): (${el.center.x}, ${el.center.y}) — iOS points. Use tap(text="...") or tap(testID="...") for reliable targeting.`,
         `  Enabled: ${el.enabled}`
     ].join("\n");
     return {
         content: [{ type: "text", text: info }]
     };
 });
-// Tool: Get debug server info
-registerToolWithTelemetry("get_debug_server", {
-    description: "Get the debug HTTP server URL. Use this to find where you can access logs, network requests, and other debug data via HTTP.",
-    inputSchema: {}
-}, async () => {
-    const port = getDebugServerPort();
-    if (!port) {
+// Tool: Activate Pro license
+registerToolWithTelemetry("activate_license", getActivateLicenseConfig(), handleActivateLicense);
+// Tool: Delete account
+registerToolWithTelemetry("delete_account", getDeleteAccountConfig(), handleDeleteAccount);
+// Dev-only tool: reset local telemetry data
+if (isDevMode()) {
+    registerToolWithTelemetry("reset_telemetry", {
+        description: "Clear local telemetry data file (/tmp/rn-devtools-telemetry.jsonl). Only available in development mode.",
+        inputSchema: {},
+    }, async () => {
+        if (existsSync(TELEMETRY_JSONL_PATH)) {
+            unlinkSync(TELEMETRY_JSONL_PATH);
+            return {
+                content: [{ type: "text", text: "Local telemetry data cleared." }],
+            };
+        }
         return {
-            content: [
-                {
-                    type: "text",
-                    text: "Debug HTTP server is not running."
-                }
-            ],
-            isError: true
+            content: [{ type: "text", text: "No local telemetry data file found." }],
         };
-    }
-    const info = {
-        url: `http://localhost:${port}`,
-        endpoints: {
-            status: `http://localhost:${port}/api/status`,
-            logs: `http://localhost:${port}/api/logs`,
-            network: `http://localhost:${port}/api/network`,
-            bundleErrors: `http://localhost:${port}/api/bundle-errors`,
-            apps: `http://localhost:${port}/api/apps`
-        }
-    };
-    return {
-        content: [
-            {
-                type: "text",
-                text: `Debug HTTP server running at:\n\n${JSON.stringify(info, null, 2)}`
-            }
-        ]
-    };
-});
-// Tool: Restart HTTP server (hot-reload)
-registerToolWithTelemetry("restart_http_server", {
-    description: "Note: HTTP server now runs in-process to share state. To apply code changes, restart the MCP session.",
-    inputSchema: {}
-}, async () => {
-    const port = getDebugServerPort();
-    return {
-        content: [
-            {
-                type: "text",
-                text: `HTTP server is running in-process on port ${port}. To apply code changes, rebuild with 'npm run build' and restart the MCP session. The in-process mode is required for the dashboard to show logs, network requests, and connected apps.`
-            }
-        ]
-    };
-});
-/**
- * Auto-connect to Metro bundler on startup
- * Scans common ports and connects to any running Metro servers
- */
-async function autoConnectToMetro() {
-    console.error("[rn-ai-debugger] Auto-scanning for Metro servers...");
-    try {
-        const openPorts = await scanMetroPorts();
-        if (openPorts.length === 0) {
-            console.error("[rn-ai-debugger] No Metro servers found on startup. Use scan_metro to connect later.");
-            return;
-        }
-        for (const port of openPorts) {
-            try {
-                const devices = await fetchDevices(port);
-                const mainDevice = selectMainDevice(devices);
-                if (mainDevice) {
-                    await connectToDevice(mainDevice, port);
-                    console.error(`[rn-ai-debugger] Auto-connected to ${mainDevice.title} on port ${port}`);
-                    // Also connect to Metro build events
-                    try {
-                        await connectMetroBuildEvents(port);
-                    }
-                    catch {
-                        // Build events connection is optional
-                    }
-                }
-            }
-            catch (error) {
-                console.error(`[rn-ai-debugger] Failed to auto-connect on port ${port}: ${error}`);
-            }
-        }
-    }
-    catch (error) {
-        console.error(`[rn-ai-debugger] Auto-connect error: ${error}`);
-    }
+    });
 }
 // Main function
 async function main() {
     // Initialize telemetry (checks opt-out env var, loads/creates installation ID)
+    // License validation is lazy — runs on first tool use via ensureLicense()
     initTelemetry();
-    // Start debug HTTP server in-process (shares state with MCP server)
-    // Note: Child process mode doesn't work because state (logs, network, apps) isn't shared
-    await startDebugHttpServer();
-    console.error("[rn-ai-debugger] HTTP server started in-process");
+    identifyIfDevMode(getInstallationId());
+    // --- Eager usage check (pre-loads usage cache for tool-level gate) ---
+    const { ensureLicense } = await import("./core/license.js");
+    await ensureLicense();
     const useHttp = process.argv.includes("--http");
     const httpPort = parseInt(process.env.MCP_HTTP_PORT || "8600", 10);
     if (useHttp) {
@@ -2988,25 +3966,47 @@ async function main() {
             res.end("Not found");
         });
         httpServer.listen(httpPort, () => {
-            console.error(`[rn-ai-debugger] MCP HTTP server listening on http://localhost:${httpPort}/mcp`);
+            console.error(`[rn-ai-devtools] MCP HTTP server listening on http://localhost:${httpPort}/mcp`);
         });
     }
     else {
         // Stdio transport mode — default for production
         const transport = new StdioServerTransport();
         await server.connect(transport);
-        console.error("[rn-ai-debugger] Server started on stdio");
+        console.error("[rn-ai-devtools] Server started on stdio");
     }
-    // Auto-connect to Metro in background (non-blocking)
-    // Use setImmediate to ensure MCP server is fully ready first
-    setImmediate(() => {
-        autoConnectToMetro().catch((err) => {
-            console.error("[rn-ai-debugger] Auto-connect failed:", err);
-        });
-    });
 }
 main().catch((error) => {
-    console.error("[rn-ai-debugger] Fatal error:", error);
+    console.error("[rn-ai-devtools] Fatal error:", error);
     process.exit(1);
 });
+// Graceful shutdown: close CDP connections so the slot is freed for other sessions
+function gracefulShutdown() {
+    suppressReconnection();
+    cancelAllReconnectionTimers();
+    for (const [key, app] of connectedApps.entries()) {
+        try {
+            app.ws.close();
+        }
+        catch {
+            // Ignore close errors during shutdown
+        }
+        connectedApps.delete(key);
+    }
+    disconnectMetroBuildEvents();
+    clearAllConnectionState();
+    clearAllCDPMessageTimes();
+    shutdownPostHog().catch(() => { });
+}
+process.on("beforeExit", () => {
+    shutdownPostHog().catch(() => { });
+});
+process.on("SIGINT", () => {
+    gracefulShutdown();
+    process.exit(0);
+});
+process.on("SIGTERM", () => {
+    gracefulShutdown();
+    process.exit(0);
+});
 //# sourceMappingURL=index.js.map