@shawnowen/comet-mcp 2.3.0 → 2.4.1

package/dist/cdp-client.js

@@ -1,19 +1,22 @@
 // CDP Client wrapper for Comet browser control
 // Supports macOS, Windows, and WSL
 import CDP from "chrome-remote-interface";
-import { spawn, execSync } from "child_process";
-import { platform } from "os";
-import { existsSync } from "fs";
+import { spawn, execSync, execFileSync } from "child_process";
+import { platform, homedir } from "os";
+import { existsSync, appendFileSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join, dirname } from "path";
+import { loadBridgeConfig } from "./bridge-config.js";
+import { dispatchAlert } from "./alert-dispatcher.js";
 // ============ PLATFORM DETECTION ============
 /**
  * Detect if running in WSL (Windows Subsystem for Linux)
  */
 function isWSL() {
-    if (platform() !== 'linux')
+    if (platform() !== "linux")
         return false;
     try {
-        const release = execSync('uname -r', { encoding: 'utf8' }).toLowerCase();
-        return release.includes('microsoft') || release.includes('wsl');
+        const release = execSync("uname -r", { encoding: "utf8" }).toLowerCase();
+        return release.includes("microsoft") || release.includes("wsl");
     }
     catch {
         return false;
@@ -54,6 +57,58 @@ function getCometPath() {
 }
 const COMET_PATH = getCometPath();
 const DEFAULT_PORT = 9222;
+const CRASH_LOG_PATH = join(homedir(), ".local", "log", "comet-crashes.log");
+const EXTENSION_PATH = join(homedir(), "Documents", "repos", "Comet-Bridge", "comet-mcp", "extension");
+function canonicalCometSessionTargetUrl(url) {
+    return url.startsWith("about:blank#comet-session-") ? url.toLowerCase() : url;
+}
+/**
+ * CDP windowState="normal" does not reliably exit native macOS fullscreen Spaces.
+ * Managed top-display Comet windows must stay windowed so control-left/right can
+ * switch normal Spaces and browser chrome remains visible.
+ */
+function enforceWindowedTopDisplayOnMac() {
+    if (platform() !== "darwin")
+        return;
+    const script = `
+tell application "System Events"
+  if exists process "Comet" then
+    tell process "Comet"
+      repeat with managedWindow in windows
+        try
+          set {xPos, yPos} to position of managedWindow
+          set {wWidth, wHeight} to size of managedWindow
+          if yPos < 0 and wWidth is greater than or equal to 800 then
+            if value of attribute "AXFullScreen" of managedWindow is true then
+              set value of attribute "AXFullScreen" of managedWindow to false
+              delay 0.5
+            end if
+            set position of managedWindow to {0, -1440}
+            set size of managedWindow to {2560, 1440}
+          end if
+        end try
+      end repeat
+    end tell
+  end if
+end tell
+`;
+    try {
+        execFileSync("osascript", ["-e", script], { stdio: "ignore", timeout: 5000 });
+    }
+    catch {
+        // Best-effort only; CDP bounds still keep the session usable if accessibility is unavailable.
+    }
+}
+function logCrashEvent(reason) {
+    try {
+        mkdirSync(join(homedir(), ".local", "log"), { recursive: true });
+        const ts = new Date().toISOString();
+        appendFileSync(CRASH_LOG_PATH, `${ts} ${reason}\n`);
+    }
+    catch {
+        /* best-effort logging */
+    }
+}
 // ============ WSL NETWORK HELPERS ============
 /**
  * Check if WSL can directly connect to Windows localhost (mirrored networking)
@@ -61,13 +116,13 @@ const DEFAULT_PORT = 9222;
 async function canConnectToWindowsLocalhost(port) {
     if (!IS_WSL)
         return true;
-    const net = await import('net');
+    const net = await import("net");
     return new Promise((resolve) => {
-        const client = net.createConnection({ port, host: '127.0.0.1' }, () => {
+        const client = net.createConnection({ port, host: "127.0.0.1" }, () => {
             client.destroy();
             resolve(true);
         });
-        client.on('error', () => {
+        client.on("error", () => {
             resolve(false);
         });
         client.setTimeout(2000, () => {
@@ -100,33 +155,35 @@ async function getWSLConnectPort(targetPort) {
  * Windows/WSL-compatible fetch using PowerShell
  * On WSL, native fetch connects to WSL's localhost, not Windows where Comet runs
  */
-async function windowsFetch(url, method = 'GET') {
+async function windowsFetch(url, method = "GET") {
     // Use native fetch on macOS/Linux (non-WSL)
-    if (platform() !== 'win32' && !IS_WSL) {
+    if (platform() !== "win32" && !IS_WSL) {
         const response = await fetch(url, { method });
         return response;
     }
     // On Windows or WSL, use PowerShell to reach Windows localhost
     try {
-        const psCommand = method === 'PUT'
+        const psCommand = method === "PUT"
             ? `Invoke-WebRequest -Uri '${url}' -Method PUT -UseBasicParsing | Select-Object -ExpandProperty Content`
             : `Invoke-WebRequest -Uri '${url}' -UseBasicParsing | Select-Object -ExpandProperty Content`;
         const result = execSync(`powershell.exe -NoProfile -Command "${psCommand}"`, {
-            encoding: 'utf8',
+            encoding: "utf8",
             timeout: 10000,
             windowsHide: true,
         });
         return {
             ok: true,
             status: 200,
-            json: async () => JSON.parse(result.trim())
+            json: async () => JSON.parse(result.trim()),
         };
     }
     catch (error) {
         return {
             ok: false,
             status: 0,
-            json: async () => { throw error; }
+            json: async () => {
+                throw error;
+            },
         };
     }
 }
@@ -136,6 +193,8 @@ export class CometCDPClient {
     state = {
         connected: false,
         port: DEFAULT_PORT,
+        profileId: "agent",
+        profileOwner: "agent",
     };
     lastTargetId;
     reconnectAttempts = 0;
@@ -144,6 +203,17 @@ export class CometCDPClient {
     get isConnected() {
         return this.state.connected && this.client !== null;
     }
+    /**
+     * Access the raw CDP protocol client for direct domain calls
+     * (e.g., Page.printToPDF, Network.enable, Input.dispatchKeyEvent).
+     * Throws if not connected — always check isConnected or call connect() first.
+     */
+    get protocol() {
+        if (!this.client) {
+            throw new Error("CDP client not connected. Call connect() first.");
+        }
+        return this.client;
+    }
     /**
      * Health check - verify connection is actually alive (not just "connected" in state)
      * This catches cases where WebSocket died silently
@@ -154,8 +224,8 @@ export class CometCDPClient {
         try {
             // Simple evaluation that should always work if connected
             const result = await Promise.race([
-                this.client.Runtime.evaluate({ expression: '1+1', returnByValue: true }),
-                new Promise((_, reject) => setTimeout(() => reject(new Error('Health check timeout')), 3000))
+                this.client.Runtime.evaluate({ expression: "1+1", returnByValue: true }),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("Health check timeout")), 3000)),
             ]);
             return result?.result?.value === 2;
         }
@@ -183,7 +253,7 @@ export class CometCDPClient {
      */
     async withAutoReconnect(operation) {
         if (this.isReconnecting) {
-            await new Promise(resolve => setTimeout(resolve, 1000));
+            await new Promise((resolve) => setTimeout(resolve, 1000));
         }
         try {
             const result = await operation();
@@ -193,16 +263,23 @@ export class CometCDPClient {
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
             const connectionErrors = [
-                'WebSocket', 'CLOSED', 'not open', 'disconnected',
-                'ECONNREFUSED', 'ECONNRESET', 'Protocol error', 'Target closed', 'Session closed'
+                "WebSocket",
+                "CLOSED",
+                "not open",
+                "disconnected",
+                "ECONNREFUSED",
+                "ECONNRESET",
+                "Protocol error",
+                "Target closed",
+                "Session closed",
             ];
-            if (connectionErrors.some(e => errorMessage.includes(e)) &&
+            if (connectionErrors.some((e) => errorMessage.includes(e)) &&
                 this.reconnectAttempts < this.maxReconnectAttempts) {
                 this.reconnectAttempts++;
                 this.isReconnecting = true;
                 try {
                     const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts - 1), 5000);
-                    await new Promise(resolve => setTimeout(resolve, delay));
+                    await new Promise((resolve) => setTimeout(resolve, delay));
                     await this.reconnect();
                     this.isReconnecting = false;
                     return await operation();
@@ -223,7 +300,9 @@ export class CometCDPClient {
             try {
                 await this.client.close();
             }
-            catch { /* ignore */ }
+            catch {
+                /* ignore */
+            }
         }
         this.state.connected = false;
         this.client = null;
@@ -232,32 +311,46 @@ export class CometCDPClient {
             await this.getVersion();
         }
         catch {
+            // Comet process is dead — log crash event and restart
+            logCrashEvent(`RECONNECT_RESTART: Comet not responding on port ${this.state.port}, attempting restart`);
             try {
                 await this.startComet(this.state.port);
-                await new Promise(resolve => setTimeout(resolve, 2000));
+                await new Promise((resolve) => setTimeout(resolve, 2000));
             }
             catch {
-                throw new Error('Cannot connect to Comet. Ensure Comet is running with --remote-debugging-port=9222');
+                logCrashEvent("RECONNECT_FAILED: Could not restart Comet");
+                throw new Error("Cannot connect to Comet. Ensure Comet is running with --remote-debugging-port=9222");
             }
         }
-        // Try to reconnect to last target
+        // Try to reconnect to last target (session-specific — never grab another agent's tab)
         if (this.lastTargetId) {
             try {
                 const targets = await this.listTargets();
-                if (targets.find(t => t.id === this.lastTargetId)) {
+                if (targets.find((t) => t.id === this.lastTargetId)) {
                     return await this.connect(this.lastTargetId);
                 }
             }
-            catch { /* target gone */ }
+            catch {
+                /* target gone */
+            }
         }
-        // Find best target
+        // Spec 034: Do NOT fall back to grabbing any Perplexity tab.
+        // In multi-agent mode, picking a random tab would hijack another agent's session.
+        // If we had a lastTargetId and it's gone, fail explicitly so the caller
+        // can re-register via comet_connect.
+        if (this.lastTargetId) {
+            throw new Error(`Session target ${this.lastTargetId} no longer exists. ` +
+                `Call comet_connect to establish a new session.`);
+        }
+        // No lastTargetId means this is a legacy/global client without session isolation.
+        // Fall back to finding a tab (backward compat for non-session usage).
         const targets = await this.listTargets();
-        const target = targets.find(t => t.type === 'page' && t.url.includes('perplexity.ai')) ||
-            targets.find(t => t.type === 'page' && t.url !== 'about:blank');
+        const target = targets.find((t) => t.type === "page" && t.url.includes("perplexity.ai")) ||
+            targets.find((t) => t.type === "page" && t.url !== "about:blank");
         if (target) {
             return await this.connect(target.id);
         }
-        throw new Error('No suitable tab found for reconnection');
+        throw new Error("No suitable tab found for reconnection. Call comet_connect first.");
     }
     /**
      * List tabs with categorization
@@ -265,17 +358,18 @@ export class CometCDPClient {
     async listTabsCategorized() {
         const targets = await this.listTargets();
         return {
-            main: targets.find(t => t.type === 'page' && t.url.includes('perplexity.ai') && !t.url.includes('sidecar')) || null,
-            sidecar: targets.find(t => t.type === 'page' && t.url.includes('sidecar')) || null,
-            agentBrowsing: targets.find(t => t.type === 'page' &&
-                !t.url.includes('perplexity.ai') &&
-                !t.url.includes('chrome-extension') &&
-                !t.url.includes('chrome://') &&
-                t.url !== 'about:blank') || null,
-            overlay: targets.find(t => t.url.includes('chrome-extension') && t.url.includes('overlay')) || null,
-            others: targets.filter(t => t.type === 'page' &&
-                !t.url.includes('perplexity.ai') &&
-                !t.url.includes('chrome-extension')),
+            main: targets.find((t) => t.type === "page" && t.url.includes("perplexity.ai") && !t.url.includes("sidecar")) || null,
+            sidecar: targets.find((t) => t.type === "page" && t.url.includes("sidecar")) || null,
+            agentBrowsing: targets.find((t) => t.type === "page" &&
+                !t.url.includes("perplexity.ai") &&
+                !t.url.includes("chrome-extension") &&
+                !t.url.includes("chrome://") &&
+                t.url !== "about:blank") || null,
+            overlay: targets.find((t) => t.url.includes("chrome-extension") && t.url.includes("overlay")) ||
+                null,
+            others: targets.filter((t) => t.type === "page" &&
+                !t.url.includes("perplexity.ai") &&
+                !t.url.includes("chrome-extension")),
         };
     }
     /**
@@ -285,46 +379,93 @@ export class CometCDPClient {
         return new Promise((resolve) => {
             if (IS_WINDOWS) {
                 // Windows: use tasklist to check for comet.exe
-                const check = spawn('tasklist', ['/FI', 'IMAGENAME eq comet.exe', '/NH']);
-                let output = '';
-                check.stdout?.on('data', (data) => { output += data.toString(); });
-                check.on('close', () => {
-                    resolve(output.toLowerCase().includes('comet.exe'));
+                const check = spawn("tasklist", ["/FI", "IMAGENAME eq comet.exe", "/NH"]);
+                let output = "";
+                check.stdout?.on("data", (data) => {
+                    output += data.toString();
+                });
+                check.on("close", () => {
+                    resolve(output.toLowerCase().includes("comet.exe"));
                 });
-                check.on('error', () => resolve(false));
+                check.on("error", () => resolve(false));
             }
             else {
                 // macOS/Linux: use pgrep
-                const check = spawn('pgrep', ['-f', 'Comet.app']);
-                check.on('close', (code) => resolve(code === 0));
-                check.on('error', () => resolve(false));
+                const check = spawn("pgrep", ["-f", "Comet.app"]);
+                check.on("close", (code) => resolve(code === 0));
+                check.on("error", () => resolve(false));
             }
         });
     }
-    /**
-     * Kill any running Comet process
-     */
-    async killComet() {
-        return new Promise((resolve) => {
-            if (IS_WINDOWS) {
-                // Windows: use taskkill to kill comet.exe
-                const kill = spawn('taskkill', ['/F', '/IM', 'comet.exe']);
-                kill.on('close', () => setTimeout(resolve, 1000));
-                kill.on('error', () => setTimeout(resolve, 1000));
+    // ---- Crash Loop Protection (Spec 016, FR-005, T032-T033) ----
+    readCrashHistory() {
+        try {
+            const config = loadBridgeConfig();
+            const data = readFileSync(config.crashRecovery.crashHistoryPath, "utf-8");
+            return JSON.parse(data);
+        }
+        catch (err) {
+            // ENOENT is expected on first run — only log actual errors
+            if (err?.code !== "ENOENT") {
+                console.warn(`[comet-bridge] Crash history read failed: ${err instanceof Error ? err.message : err}`);
             }
-            else {
-                // macOS/Linux: use pkill
-                const kill = spawn('pkill', ['-f', 'Comet.app']);
-                kill.on('close', () => setTimeout(resolve, 1000));
-                kill.on('error', () => setTimeout(resolve, 1000));
+            return [];
+        }
+    }
+    writeCrashHistory(timestamps) {
+        try {
+            const config = loadBridgeConfig();
+            mkdirSync(dirname(config.crashRecovery.crashHistoryPath), { recursive: true });
+            writeFileSync(config.crashRecovery.crashHistoryPath, JSON.stringify(timestamps));
+        }
+        catch (err) {
+            console.error(`[comet-bridge] Crash history write failed: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    recordCrash() {
+        const timestamps = this.readCrashHistory();
+        timestamps.push(new Date().toISOString());
+        this.writeCrashHistory(timestamps);
+    }
+    checkCrashLoopCap() {
+        try {
+            const config = loadBridgeConfig();
+            const maxRestarts = config.crashRecovery.maxRestarts;
+            const windowMs = config.crashRecovery.windowMinutes * 60 * 1000;
+            const cutoff = Date.now() - windowMs;
+            const history = this.readCrashHistory();
+            const recent = history.filter((ts) => new Date(ts).getTime() > cutoff);
+            // Clean up old entries
+            if (recent.length !== history.length) {
+                this.writeCrashHistory(recent);
             }
-        });
+            return {
+                blocked: recent.length >= maxRestarts,
+                count: recent.length,
+                windowMinutes: config.crashRecovery.windowMinutes,
+            };
+        }
+        catch (err) {
+            console.error(`[comet-bridge] Crash loop cap check failed: ${err instanceof Error ? err.message : err}. Failing closed (blocking restart).`);
+            return { blocked: true, count: -1, windowMinutes: 10 };
+        }
     }
     /**
      * Start Comet browser with remote debugging enabled
      * Handles macOS, Windows, and WSL environments
      */
     async startComet(port = DEFAULT_PORT) {
+        // Crash loop guard (Spec 016, FR-005, T033)
+        const crashCheck = this.checkCrashLoopCap();
+        if (crashCheck.blocked) {
+            dispatchAlert({
+                type: "CRASH_LOOP_CAP",
+                message: `Browser restart blocked: ${crashCheck.count} crashes in ${crashCheck.windowMinutes} minutes. Manual intervention required.`,
+                context: { crashCount: crashCheck.count, windowMinutes: crashCheck.windowMinutes },
+            });
+            throw new Error(`Crash loop detected: ${crashCheck.count} crashes in ${crashCheck.windowMinutes} minutes. ` +
+                `Automatic restart halted. Manual intervention required.`);
+        }
         this.state.port = port;
         // ========== WSL: Use PowerShell to communicate with Windows ==========
         if (IS_WSL) {
@@ -332,7 +473,7 @@ export class CometCDPClient {
             try {
                 const response = await windowsFetch(`http://127.0.0.1:${port}/json/version`);
                 if (response.ok) {
-                    const version = await response.json();
+                    const version = (await response.json());
                     return `Comet already running on Windows host, port: ${port} (${version.Browser})`;
                 }
             }
@@ -340,22 +481,25 @@ export class CometCDPClient {
                 // Comet not accessible, need to launch
             }
             // Get Windows LOCALAPPDATA path and construct Comet path
-            let cometPath = '';
+            let cometPath = "";
             try {
-                const localAppData = execSync('cmd.exe /c echo %LOCALAPPDATA%', { encoding: 'utf8' })
-                    .trim().replace(/\r?\n/g, '');
+                const localAppData = execSync("cmd.exe /c echo %LOCALAPPDATA%", { encoding: "utf8" })
+                    .trim()
+                    .replace(/\r?\n/g, "");
                 cometPath = `${localAppData}\\Perplexity\\Comet\\Application\\Comet.exe`;
             }
             catch {
-                cometPath = 'C:\\Users\\' + (process.env.USER || 'user') +
-                    '\\AppData\\Local\\Perplexity\\Comet\\Application\\Comet.exe';
+                cometPath =
+                    "C:\\Users\\" +
+                        (process.env.USER || "user") +
+                        "\\AppData\\Local\\Perplexity\\Comet\\Application\\Comet.exe";
             }
             try {
                 // Launch Comet via PowerShell (Set-Location avoids UNC path issues)
                 const psCommand = `Set-Location C:\\; Start-Process -FilePath '${cometPath}' -ArgumentList '--remote-debugging-port=${port}'`;
-                spawn('powershell.exe', ['-NoProfile', '-Command', psCommand], {
+                spawn("powershell.exe", ["-NoProfile", "-Command", psCommand], {
                     detached: true,
-                    stdio: 'ignore',
+                    stdio: "ignore",
                 }).unref();
                 // Wait for Comet to start
                 return new Promise((resolve, reject) => {
@@ -370,7 +514,9 @@ export class CometCDPClient {
                                 return;
                             }
                         }
-                        catch { /* keep trying */ }
+                        catch {
+                            /* keep trying */
+                        }
                         if (attempts < maxAttempts) {
                             setTimeout(checkReady, 500);
                         }
@@ -388,22 +534,31 @@ export class CometCDPClient {
                     `Error: ${launchError instanceof Error ? launchError.message : String(launchError)}`);
             }
         }
-        // ========== Native Windows: Use windowsFetch for HTTP ==========
-        if (platform() === 'win32') {
-            try {
-                const response = await windowsFetch(`http://127.0.0.1:${port}/json/version`);
-                if (response.ok) {
-                    const version = await response.json();
-                    return `Comet already running with debug port: ${version.Browser}`;
+        // ========== Native Windows: Retry with exponential backoff (Spec 034, FR-005) ==========
+        if (platform() === "win32") {
+            const WIN_RETRY_DELAYS = [1000, 2000, 4000, 8000, 16000];
+            for (let attempt = 0; attempt <= WIN_RETRY_DELAYS.length; attempt++) {
+                try {
+                    const response = await windowsFetch(`http://127.0.0.1:${port}/json/version`);
+                    if (response.ok) {
+                        const version = (await response.json());
+                        return `Comet already running with debug port: ${version.Browser}`;
+                    }
                 }
-            }
-            catch {
-                const isRunning = await this.isCometProcessRunning();
-                if (isRunning) {
-                    await this.killComet();
+                catch {
+                    if (attempt < WIN_RETRY_DELAYS.length) {
+                        console.warn(`[comet-bridge] CDP health check failed (attempt ${attempt + 1}/${WIN_RETRY_DELAYS.length + 1}), retrying in ${WIN_RETRY_DELAYS[attempt]}ms...`);
+                        await new Promise((resolve) => setTimeout(resolve, WIN_RETRY_DELAYS[attempt]));
+                    }
                 }
             }
-            // Start Comet on Windows
+            // All retries exhausted — check if Comet process exists (FR-006, FR-007)
+            const winIsRunning = await this.isCometProcessRunning();
+            if (winIsRunning) {
+                throw new Error(`Comet is running but CDP port ${port} is unreachable after retries.\n` +
+                    `Restart Comet with: "${COMET_PATH}" --remote-debugging-port=${port}`);
+            }
+            // No Comet process — safe to start
             return new Promise((resolve, reject) => {
                 this.cometProcess = spawn(COMET_PATH, [`--remote-debugging-port=${port}`], {
                     detached: true,
@@ -421,7 +576,9 @@ export class CometCDPClient {
                             return;
                         }
                     }
-                    catch { /* keep trying */ }
+                    catch {
+                        /* keep trying */
+                    }
                     if (attempts < maxAttempts) {
                         setTimeout(checkReady, 500);
                     }
@@ -432,28 +589,54 @@ export class CometCDPClient {
                 setTimeout(checkReady, 1500);
             });
         }
-        // ========== macOS/Linux: Original approach ==========
-        try {
-            const controller = new AbortController();
-            const timeoutId = setTimeout(() => controller.abort(), 2000);
-            const response = await fetch(`http://localhost:${port}/json/version`, { signal: controller.signal });
-            clearTimeout(timeoutId);
-            if (response.ok) {
-                const version = await response.json();
-                return `Comet already running with debug port: ${version.Browser}`;
+        // ========== macOS/Linux: Retry with exponential backoff (Spec 034, FR-005) ==========
+        const RETRY_DELAYS = [1000, 2000, 4000, 8000, 16000]; // ~31s total
+        for (let attempt = 0; attempt <= RETRY_DELAYS.length; attempt++) {
+            try {
+                const controller = new AbortController();
+                const timeoutId = setTimeout(() => controller.abort(), 2000);
+                const response = await fetch(`http://localhost:${port}/json/version`, {
+                    signal: controller.signal,
+                });
+                clearTimeout(timeoutId);
+                if (response.ok) {
+                    const version = (await response.json());
+                    return `Comet already running with debug port: ${version.Browser}`;
+                }
             }
-        }
-        catch {
-            const isRunning = await this.isCometProcessRunning();
-            if (isRunning) {
-                await this.killComet();
+            catch {
+                if (attempt < RETRY_DELAYS.length) {
+                    console.warn(`[comet-bridge] CDP health check failed (attempt ${attempt + 1}/${RETRY_DELAYS.length + 1}), retrying in ${RETRY_DELAYS[attempt]}ms...`);
+                    await new Promise((resolve) => setTimeout(resolve, RETRY_DELAYS[attempt]));
+                }
             }
         }
-        // Start Comet on macOS/Linux
+        // All retries exhausted — check if Comet process exists (FR-006, FR-007)
+        const isRunning = await this.isCometProcessRunning();
+        if (isRunning) {
+            // NEVER kill — report diagnostic error instead (FR-001)
+            throw new Error(`Comet is running but CDP port ${port} is unreachable after ${RETRY_DELAYS.length + 1} attempts (~31s).\n` +
+                `Restart Comet with: ${COMET_PATH} --remote-debugging-port=${port}\n` +
+                `Or check if another process is using port ${port}.`);
+        }
+        // No Comet process at all — safe to start a new one (FR-007)
         return new Promise((resolve, reject) => {
-            this.cometProcess = spawn(COMET_PATH, [`--remote-debugging-port=${port}`], {
+            const args = [
+                `--remote-debugging-port=${port}`,
+                "--no-first-run",
+                "--no-default-browser-check",
+                "--disable-background-timer-throttling",
+                "--disable-backgrounding-occluded-windows",
+                "--disable-renderer-backgrounding",
+            ];
+            // Load tab groups extension if available
+            if (existsSync(EXTENSION_PATH)) {
+                args.push(`--load-extension=${EXTENSION_PATH}`);
+            }
+            this.cometProcess = spawn(COMET_PATH, args, {
                 detached: true,
                 stdio: "ignore",
+                env: { ...process.env, CHROME_HEADLESS: "1" },
             });
             this.cometProcess.unref();
             const maxAttempts = 40;
@@ -463,15 +646,19 @@ export class CometCDPClient {
                 try {
                     const controller = new AbortController();
                     const timeoutId = setTimeout(() => controller.abort(), 2000);
-                    const response = await fetch(`http://localhost:${port}/json/version`, { signal: controller.signal });
+                    const response = await fetch(`http://localhost:${port}/json/version`, {
+                        signal: controller.signal,
+                    });
                     clearTimeout(timeoutId);
                     if (response.ok) {
-                        const version = await response.json();
+                        const version = (await response.json());
                         resolve(`Comet started with debug port ${port}: ${version.Browser}`);
                         return;
                     }
                 }
-                catch { /* keep trying */ }
+                catch {
+                    /* keep trying */
+                }
                 if (attempts < maxAttempts) {
                     setTimeout(checkReady, 500);
                 }
@@ -482,6 +669,65 @@ export class CometCDPClient {
             setTimeout(checkReady, 1500);
         });
     }
+    /**
+     * Position the Comet browser window on the top display using full-screen bounds.
+     * Top display staging bounds: origin (0, -1440), size 2560x1440.
+     * Keep the native window state normal so browser tabs and toolbar remain visible.
+     * Uses CDP Browser.getWindowForTarget + Browser.setWindowBounds.
+     */
+    async positionOnTopDisplay(targetId) {
+        if (platform() !== "darwin")
+            return; // Only applies to this Mac Studio setup
+        try {
+            // Use targetId if provided, otherwise find any page target
+            let pageTarget;
+            if (targetId) {
+                pageTarget = { id: targetId };
+            }
+            else {
+                let targets = await this.listTargets();
+                pageTarget = targets.find((t) => t.type === "page");
+                // Retry once if no targets (Comet 145.x quirk where /json/list returns empty)
+                if (!pageTarget) {
+                    await new Promise((r) => setTimeout(r, 500));
+                    targets = await this.listTargets();
+                    pageTarget = targets.find((t) => t.type === "page");
+                    if (!pageTarget)
+                        return;
+                }
+            }
+            // Temporarily connect to get the window ID
+            const tempClient = await CDP({
+                host: "127.0.0.1",
+                port: this.state.port,
+                target: pageTarget.webSocketDebuggerUrl || pageTarget.id,
+            });
+            try {
+                const { windowId } = await tempClient.Browser.getWindowForTarget();
+                // First set to normal state (can't set bounds while maximized/fullscreen)
+                await tempClient.Browser.setWindowBounds({
+                    windowId,
+                    bounds: { windowState: "normal" },
+                });
+                await tempClient.Browser.setWindowBounds({
+                    windowId,
+                    bounds: { left: 0, top: -1440, width: 2560, height: 1440 },
+                });
+                enforceWindowedTopDisplayOnMac();
+            }
+            finally {
+                try {
+                    await tempClient.close();
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }
+        catch {
+            // Best-effort positioning — browser still works without it
+        }
+    }
     /**
      * Get CDP version info
      */
@@ -499,7 +745,7 @@ export class CometCDPClient {
         // so fall back to /json which is equivalent but more reliable.
         const response = await windowsFetch(`http://127.0.0.1:${this.state.port}/json/list`);
         if (response.ok) {
-            const targets = await response.json();
+            const targets = (await response.json());
             if (targets.length > 0)
                 return targets;
         }
@@ -508,6 +754,51 @@ export class CometCDPClient {
             throw new Error(`Failed to list targets: ${fallback.status}`);
         return fallback.json();
     }
+    async waitForTargetUrl(url, timeoutMs = 10_000) {
+        const startedAt = Date.now();
+        const canonicalTargetUrl = canonicalCometSessionTargetUrl(url);
+        while (Date.now() - startedAt < timeoutMs) {
+            const targets = await this.listTargets();
+            const target = targets.find((t) => t.type === "page" &&
+                (t.url === url || canonicalCometSessionTargetUrl(t.url) === canonicalTargetUrl));
+            if (target)
+                return target;
+            await new Promise((resolve) => setTimeout(resolve, 250));
+        }
+        throw new Error(`Timed out waiting for Comet target URL: ${url}`);
+    }
+    async getWindowIdForTarget(target) {
+        const tempClient = await CDP({
+            host: "127.0.0.1",
+            port: this.state.port,
+            target: target.webSocketDebuggerUrl || target.id,
+        });
+        try {
+            const { windowId } = await tempClient.Browser.getWindowForTarget();
+            return typeof windowId === "number" ? windowId : null;
+        }
+        finally {
+            try {
+                await tempClient.close();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    async findSidecarTargetForWindow(windowId) {
+        const sidecarTargets = (await this.listTargets()).filter((target) => target.type === "page" && target.url.includes("sidecar"));
+        for (const target of sidecarTargets) {
+            try {
+                if ((await this.getWindowIdForTarget(target)) === windowId)
+                    return target;
+            }
+            catch {
+                /* target may have disappeared between /json/list and attach */
+            }
+        }
+        return null;
+    }
     /**
      * Connect to a specific tab
      */
@@ -517,10 +808,42 @@ export class CometCDPClient {
         }
         // On WSL, verify mirrored networking is available for WebSocket connection
         const connectPort = await getWSLConnectPort(this.state.port);
-        const options = { port: connectPort, host: '127.0.0.1' };
+        const options = { port: connectPort, host: "127.0.0.1" };
         if (targetId)
             options.target = targetId;
         this.client = await CDP(options);
+        // Proactive crash detection: listen for WebSocket disconnects
+        this.client.on("disconnect", () => {
+            const wasConnected = this.state.connected;
+            this.state.connected = false;
+            this.client = null;
+            if (wasConnected) {
+                // Crash error classification (Spec 016, FR-004, T034)
+                this.isCometProcessRunning()
+                    .then((running) => {
+                    if (running) {
+                        logCrashEvent("CDP_DISCONNECT: WebSocket connection lost — browser still running");
+                        dispatchAlert({
+                            type: "CDP_DISCONNECT",
+                            message: "CDP WebSocket connection lost, but browser process is still running.",
+                        });
+                    }
+                    else {
+                        logCrashEvent("BROWSER_CRASH: Browser process terminated unexpectedly");
+                        this.recordCrash();
+                        dispatchAlert({
+                            type: "BROWSER_CRASH",
+                            message: "Browser process terminated unexpectedly. Automatic restart will be attempted on next connect.",
+                            severity: "critical",
+                        });
+                    }
+                })
+                    .catch(() => {
+                    logCrashEvent("CDP_DISCONNECT: WebSocket connection lost — could not check process");
+                });
+                console.error("[comet-bridge] CDP connection lost");
+            }
+        });
         await Promise.all([
             this.client.Page.enable(),
             this.client.Runtime.enable(),
@@ -528,23 +851,6 @@ export class CometCDPClient {
             this.client.Network.enable(),
             this.client.Accessibility.enable(),
         ]);
-        // Position window fullscreen on top display (agents workspace)
-        // See: ~/.claude/workflows/display-browser-config.md
-        try {
-            const { windowId } = await this.client.Browser.getWindowForTarget({ targetId });
-            await this.client.Browser.setWindowBounds({
-                windowId,
-                bounds: { left: 0, top: -1080, width: 1920, height: 1080, windowState: 'normal' },
-            });
-        }
-        catch {
-            try {
-                await this.client.Emulation.setDeviceMetricsOverride({
-                    width: 1920, height: 1080, deviceScaleFactor: 1, mobile: false,
-                });
-            }
-            catch { /* continue */ }
-        }
         this.state.connected = true;
         this.state.activeTabId = targetId;
         this.lastTargetId = targetId;
@@ -621,11 +927,38 @@ export class CometCDPClient {
         await this.client.Input.dispatchKeyEvent({ type: "keyDown", key });
         await this.client.Input.dispatchKeyEvent({ type: "keyUp", key });
     }
+    /**
+     * Return the existing Perplexity sidecar CDP target without activating Comet
+     * or sending OS-level keyboard shortcuts.
+     */
+    async ensureSidecarOpen(options = {}) {
+        if (options.windowId !== undefined) {
+            const existingBoundSidecar = await this.findSidecarTargetForWindow(options.windowId);
+            if (existingBoundSidecar)
+                return existingBoundSidecar;
+        }
+        // Check if sidecar is already open
+        const tabs = await this.listTabsCategorized();
+        if (tabs.sidecar && options.windowId === undefined)
+            return tabs.sidecar;
+        return null;
+    }
+    /**
+     * Connect a separate CDP client to the sidecar target for isolated interaction.
+     */
+    async connectToSidecar(options = {}) {
+        const sidecarTarget = await this.ensureSidecarOpen(options);
+        if (!sidecarTarget)
+            return null;
+        const sidecarClient = new CometCDPClient();
+        await sidecarClient.connect(sidecarTarget.id);
+        return sidecarClient;
+    }
     /**
      * Create a new tab
      */
     async newTab(url) {
-        const response = await windowsFetch(`http://127.0.0.1:${this.state.port}/json/new${url ? `?${url}` : ""}`, 'PUT');
+        const response = await windowsFetch(`http://127.0.0.1:${this.state.port}/json/new${url ? `?${url}` : ""}`, "PUT");
         if (!response.ok)
             throw new Error(`Failed to create new tab: ${response.status}`);
         return response.json();
@@ -640,7 +973,9 @@ export class CometCDPClient {
                 return result.success;
             }
         }
-        catch { /* fallback to HTTP */ }
+        catch {
+            /* fallback to HTTP */
+        }
         try {
             const response = await windowsFetch(`http://127.0.0.1:${this.state.port}/json/close/${targetId}`);
             return response.ok;
@@ -661,12 +996,12 @@ export class CometCDPClient {
             const node = nodes[i];
             if (node.ignored)
                 continue;
-            const role = node.role?.value || '';
-            if (role === 'none' || role === 'generic' || role === 'InlineTextBox')
+            const role = node.role?.value || "";
+            if (role === "none" || role === "generic" || role === "InlineTextBox")
                 continue;
-            const name = node.name?.value || '';
-            const value = node.value?.value || '';
-            const description = node.description?.value || '';
+            const name = node.name?.value || "";
+            const value = node.value?.value || "";
+            const description = node.description?.value || "";
             // Calculate depth from parent chain
             let depth = 0;
             let parentId = node.parentId;
@@ -679,14 +1014,24 @@ export class CometCDPClient {
                 depth++;
                 parentId = parent.parentId;
             }
-            const indent = '  '.repeat(Math.min(depth, 10));
+            const indent = "  ".repeat(Math.min(depth, 10));
             let line = `${indent}[${role}`;
             // Add ref for interactive elements
-            const interactiveRoles = ['button', 'link', 'textbox', 'checkbox', 'radio', 'combobox', 'menuitem', 'tab', 'switch'];
+            const interactiveRoles = [
+                "button",
+                "link",
+                "textbox",
+                "checkbox",
+                "radio",
+                "combobox",
+                "menuitem",
+                "tab",
+                "switch",
+            ];
             if (interactiveRoles.includes(role)) {
                 line += ` ref_${i}`;
             }
-            line += ']';
+            line += "]";
             if (name)
                 line += ` "${name}"`;
             if (value)
@@ -696,26 +1041,26 @@ export class CometCDPClient {
             // Add relevant properties
             if (node.properties) {
                 for (const prop of node.properties) {
-                    if (prop.name === 'checked' && prop.value?.value)
+                    if (prop.name === "checked" && prop.value?.value)
                         line += ` (checked)`;
-                    if (prop.name === 'expanded' && prop.value?.value === false)
+                    if (prop.name === "expanded" && prop.value?.value === false)
                         line += ` (collapsed)`;
-                    if (prop.name === 'disabled' && prop.value?.value)
+                    if (prop.name === "disabled" && prop.value?.value)
                         line += ` (disabled)`;
-                    if (prop.name === 'required' && prop.value?.value)
+                    if (prop.name === "required" && prop.value?.value)
                         line += ` (required)`;
-                    if (prop.name === 'selected' && prop.value?.value)
+                    if (prop.name === "selected" && prop.value?.value)
                         line += ` (selected)`;
                 }
             }
             totalLength += line.length + 1;
             if (totalLength > maxLength) {
-                lines.push('... (truncated)');
+                lines.push("... (truncated)");
                 break;
             }
             lines.push(line);
         }
-        return lines.join('\n');
+        return lines.join("\n");
     }
     /**
      * Extract clean readable text from the current page
@@ -772,9 +1117,9 @@ export class CometCDPClient {
         return cleaned;
       })()
     `);
-        let text = result.result.value || '';
+        let text = result.result.value || "";
         if (text.length > maxLength) {
-            text = text.substring(0, maxLength) + '\n... (truncated)';
+            text = text.substring(0, maxLength) + "\n... (truncated)";
         }
         return text;
     }
@@ -800,11 +1145,13 @@ export class CometCDPClient {
                 if (timeoutTimer)
                     clearTimeout(timeoutTimer);
                 try {
-                    this.client.removeListener('Network.requestWillBeSent', onRequest);
-                    this.client.removeListener('Network.loadingFinished', onFinished);
-                    this.client.removeListener('Network.loadingFailed', onFailed);
+                    this.client.removeListener("Network.requestWillBeSent", onRequest);
+                    this.client.removeListener("Network.loadingFinished", onFinished);
+                    this.client.removeListener("Network.loadingFailed", onFailed);
+                }
+                catch {
+                    /* ignore listener removal errors */
                 }
-                catch { /* ignore listener removal errors */ }
             };
             const finish = (idle) => {
                 if (resolved)
@@ -848,9 +1195,9 @@ export class CometCDPClient {
                     resetIdleTimer();
                 }
             };
-            this.client.on('Network.requestWillBeSent', onRequest);
-            this.client.on('Network.loadingFinished', onFinished);
-            this.client.on('Network.loadingFailed', onFailed);
+            this.client.on("Network.requestWillBeSent", onRequest);
+            this.client.on("Network.loadingFinished", onFinished);
+            this.client.on("Network.loadingFailed", onFailed);
             // Start idle timer immediately (page may already be idle)
             resetIdleTimer();
             // Overall timeout