pi-browser-harness 0.5.0 → 0.6.0

package/src/daemon/server.ts

@@ -0,0 +1,245 @@
+/**
+ * IpcServer — Unix socket server for daemon ↔ pi client communication.
+ *
+ * Accepts multiple concurrent pi client connections over a Unix domain
+ * stream socket. Uses newline-delimited JSON framing (one WireMessage per
+ * line). Clients are anonymous until they send a control.register message.
+ *
+ * References:
+ *   - net.createServer: https://nodejs.org/docs/latest-v22.x/api/net.html#netcreateserveroptions-connectionlistener
+ *   - server.listen(path): https://nodejs.org/docs/latest-v22.x/api/net.html#serverlistenpath-backlog-callback
+ *   - readline.createInterface: https://nodejs.org/docs/latest-v22.x/api/readline.html#readlinecreateinterfaceoptions
+ */
+
+import { createServer, type Server, type Socket } from "node:net";
+import { createInterface, type Interface } from "node:readline";
+import { unlinkSync } from "node:fs";
+import {
+  type WireMessage,
+  type WireControl,
+  isWireMessage,
+  DAEMON_SOCKET_PATH,
+  DAEMON_MAX_CLIENTS,
+  DAEMON_STALE_SOCKET_CLEANUP,
+} from "./protocol";
+
+// ── Types ──────────────────────────────────────────────────────────────────────
+
+/** A connected pi client with its socket and readline interface. */
+export type ClientSocket = {
+  /** Client namespace (set after registration). */
+  id: string;
+  readonly socket: Socket;
+  readonly rl: Interface;
+  /** True once a valid control.register message has been received. */
+  registered: boolean;
+};
+
+/** Handler called for every valid WireMessage from any client. */
+export type MessageHandler = (msg: WireMessage, client: ClientSocket) => void;
+
+/** Handler called when a client connects or disconnects. */
+export type ConnectionHandler = (client: ClientSocket) => void;
+
+export type IpcServer = {
+  /** Start listening on the Unix socket. Resolves when the server is ready. */
+  start(): Promise<void>;
+  /** Close the server and all client connections. Resolves when cleaned up. */
+  stop(): Promise<void>;
+  /** Register a handler for incoming WireMessages from any client. */
+  onMessage(handler: MessageHandler): void;
+  /** Register a handler for client connect events. */
+  onConnect(handler: ConnectionHandler): void;
+  /** Register a handler for client disconnect events. */
+  onDisconnect(handler: ConnectionHandler): void;
+  /** Send a WireMessage to a specific client by clientId. No-op if client not found. */
+  send(clientId: string, msg: WireMessage): void;
+  /** Send a WireMessage to all connected (registered) clients. */
+  broadcast(msg: WireMessage): void;
+  /** Force-disconnect a client by clientId. */
+  disconnectClient(clientId: string): void;
+  /** All currently connected clients (by clientId). */
+  clients(): ReadonlyMap<string, ClientSocket>;
+  /** Number of connected clients. */
+  clientCount(): number;
+};
+
+// ── Implementation ─────────────────────────────────────────────────────────────
+
+export const createIpcServer = (): IpcServer => {
+  let server: Server | null = null;
+  // Anonymous temp-id → ClientSocket. Temp ids are assigned before registration.
+  const sockets = new Map<string, ClientSocket>();
+  // clientId → ClientSocket (only registered clients).
+  const clients = new Map<string, ClientSocket>();
+  let messageHandler: MessageHandler | null = null;
+  let connectHandler: ConnectionHandler | null = null;
+  let disconnectHandler: ConnectionHandler | null = null;
+  let nextTempId = 1;
+
+  const start = (): Promise<void> =>
+    new Promise((resolve, reject) => {
+      // Clean up stale socket file from a previous crashed daemon.
+      if (DAEMON_STALE_SOCKET_CLEANUP) {
+        try {
+          unlinkSync(DAEMON_SOCKET_PATH);
+        } catch {
+          // ENOENT is expected — no stale socket to clean.
+        }
+      }
+
+      server = createServer({ pauseOnConnect: false }, (socket: Socket) => {
+        // Reject if at capacity (check registered clients only).
+        if (clients.size >= DAEMON_MAX_CLIENTS) {
+          socket.destroy();
+          return;
+        }
+
+        const tempId = `anon-${nextTempId++}`;
+        const rl = createInterface({ input: socket, crlfDelay: Infinity });
+        let currentClient: ClientSocket = { id: tempId, socket, rl, registered: false };
+
+        sockets.set(tempId, currentClient);
+
+        // Buffer for partial lines. readline handles line splitting, but
+        // we store a reference in case we need it for diagnostics.
+        let lineCount = 0;
+
+        rl.on("line", (line: string) => {
+          lineCount++;
+          let msg: WireMessage | null;
+          try {
+            const parsed: unknown = JSON.parse(line);
+            if (!isWireMessage(parsed)) return;
+            msg = parsed;
+          } catch {
+            // Malformed JSON — ignore silently, don't crash the daemon.
+            return;
+          }
+
+          // Handle registration before forwarding to the general handler.
+          if (msg.type === "control" && msg.action === "register" && !currentClient.registered) {
+            const clientId = msg.clientId;
+            if (!clientId) return;
+
+            // If a client with this id is already connected, reject.
+            if (clients.has(clientId)) {
+              const reply: WireControl = {
+                type: "control",
+                action: "shutdown",
+                reason: `clientId ${clientId} is already connected`,
+              };
+              socket.write(JSON.stringify(reply) + "\n");
+              socket.destroy();
+              return;
+            }
+
+            // Promote from anonymous to registered — mutate in place so the
+            // closure captures the updated client reference.
+            sockets.delete(tempId);
+            currentClient.id = clientId;
+            currentClient.registered = true;
+            clients.set(clientId, currentClient);
+
+            // Acknowledge registration.
+            const ack: WireControl = { type: "control", action: "registered", clientId };
+            socket.write(JSON.stringify(ack) + "\n");
+
+            connectHandler?.(currentClient);
+            return;
+          }
+
+          // Require registration for non-control messages.
+          if (!currentClient.registered) return;
+
+          // Forward to the general handler.
+          messageHandler?.(msg, currentClient);
+        });
+
+        socket.on("error", () => {
+          // Socket errors (ECONNRESET, etc.) are handled by the 'close' event.
+        });
+
+        socket.on("close", () => {
+          // Clean up whichever map the client is in.
+          const found = clients.get(currentClient.id) ?? sockets.get(tempId);
+          if (found) {
+            clients.delete(found.id);
+            sockets.delete(tempId);
+            // Notify if this was a registered client.
+            if (found.registered) {
+              disconnectHandler?.(found);
+            }
+          }
+          // Clean up readline to prevent memory leaks.
+          rl.close();
+        });
+      });
+
+      server.on("error", (err: NodeJS.ErrnoException) => {
+        reject(err);
+      });
+
+      server.listen(DAEMON_SOCKET_PATH, () => {
+        resolve();
+      });
+    });
+
+  const stop = (): Promise<void> =>
+    new Promise((resolve) => {
+      // Close all client sockets.
+      for (const [, client] of clients) {
+        try { client.socket.destroy(); } catch { /* best-effort */ }
+      }
+      for (const [, client] of sockets) {
+        try { client.socket.destroy(); } catch { /* best-effort */ }
+      }
+      clients.clear();
+      sockets.clear();
+
+      if (server) {
+        server.close(() => {
+          // Clean up the socket file.
+          try { unlinkSync(DAEMON_SOCKET_PATH); } catch { /* ENOENT ok */ }
+          resolve();
+        });
+      } else {
+        resolve();
+      }
+    });
+
+  return {
+    start,
+    stop,
+    onMessage(handler) {
+      messageHandler = handler;
+    },
+    onConnect(handler) {
+      connectHandler = handler;
+    },
+    onDisconnect(handler) {
+      disconnectHandler = handler;
+    },
+    send(clientId, msg) {
+      const client = clients.get(clientId);
+      if (!client) return;
+      try {
+        client.socket.write(JSON.stringify(msg) + "\n");
+      } catch {
+        // Socket write error — the close handler will clean up.
+      }
+    },
+    broadcast(msg) {
+      for (const [clientId] of clients) {
+        this.send(clientId, msg);
+      }
+    },
+    disconnectClient(clientId) {
+      const client = clients.get(clientId);
+      if (!client) return;
+      client.socket.destroy();
+    },
+    clients: (): ReadonlyMap<string, ClientSocket> => clients,
+    clientCount: (): number => clients.size,
+  };
+};

package/src/daemon/spawn.ts

@@ -0,0 +1,85 @@
+/**
+ * Daemon lifecycle helpers — spawn detection and lazy launch.
+ *
+ * The daemon is a standalone long-lived process that owns the single WebSocket
+ * to Chrome. pi instances connect to it via a Unix domain socket. This module
+ * provides the plumbing to detect a running daemon and spawn one if needed.
+ *
+ * Reference:
+ *   - child_process.spawn detached: https://nodejs.org/docs/latest-v22.x/api/child_process.html#optionsdetached
+ */
+
+import { spawn, type ChildProcess } from "node:child_process";
+import { access } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { DAEMON_SOCKET_PATH } from "./protocol";
+
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Check whether the daemon is running by testing if its Unix socket exists.
+ * The socket file is created by the daemon on startup and removed on shutdown.
+ */
+export const isDaemonRunning = async (): Promise<boolean> => {
+  try {
+    await access(DAEMON_SOCKET_PATH);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Spawn the daemon as a detached child process. The daemon will continue
+ * running after the parent pi process exits.
+ *
+ * The daemon entry point is resolved relative to this module. When running
+ * from source (tsx), the entry is src/daemon/index.ts. When running compiled,
+ * it's dist/daemon/index.js.
+ *
+ * Returns the child process handle (caller should call child.unref()).
+ */
+export const spawnDaemon = (): ChildProcess | null => {
+  // Resolve the daemon entry point and tsx binary.
+  const daemonScript = join(moduleDir, "index.ts");
+  const tsxBin = join(moduleDir, "..", "..", "node_modules", ".bin", "tsx");
+
+  // Use tsx to run the daemon TypeScript source directly.
+  // The spawed process inherits the parent's env so module resolution works.
+  // Fall back to `npx tsx` if the local binary isn't available.
+  const cmd = existsSync(tsxBin) ? tsxBin : "npx";
+  const args = existsSync(tsxBin) ? [daemonScript] : ["tsx", daemonScript];
+
+  const child = spawn(cmd, args, {
+    detached: true,
+    stdio: "ignore",
+    env: { ...process.env },
+  });
+
+  child.unref();
+  return child;
+};
+
+/**
+ * Ensure the daemon is running. If not, spawn it and wait (up to timeoutMs)
+ * for the socket file to appear.
+ *
+ * Returns true if the daemon is running (or was successfully spawned).
+ */
+export const ensureDaemon = async (timeoutMs = 10_000): Promise<boolean> => {
+  if (await isDaemonRunning()) return true;
+
+  const child = spawnDaemon();
+  if (!child) return false;
+
+  // Poll for the socket file to appear
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await isDaemonRunning()) return true;
+    await new Promise((r) => setTimeout(r, 200));
+  }
+
+  return false;
+};

package/src/domains/navigate.ts

@@ -3,6 +3,7 @@ import { Text } from "@mariozechner/pi-tui";
 import { type Result, err, ok } from "../util/result";
 import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
 import { applyTruncation } from "../util/truncate";
+import { safeJs } from "../util/js-template";
 
 const NavigateArgs = Type.Object({
   url: Type.String({ description: "Full URL to navigate to (e.g. https://github.com)" }),
@@ -82,11 +83,18 @@ export const openUrlsTool = defineBrowserTool({
   renderCall: (a) => new Text(`🌐 Opening ${a.urls.length} URL${a.urls.length !== 1 ? "s" : ""}…`, 0, 0),
   async handler(args, { client, onUpdate }): Promise<Result<ToolOk, ToolErr>> {
     const total = args.urls.length;
-    // Phase 1: create tabs in parallel.
+    // Phase 1: create tabs in parallel.  Own them so they appear in
+    // browser_list_tabs scope:'owned' and group in the harness window.
+    const hw = client.ownership().harnessWindow();
     const created = await Promise.all(args.urls.map(async (url): Promise<TabResult> => {
-      const r = await client.session().callBrowser("Target.createTarget", { url: "about:blank" });
+      const params: Record<string, unknown> = { url: "about:blank" };
+      if (hw) params["openerId"] = hw;
+      else params["newWindow"] = true;
+      const r = await client.session().callBrowser("Target.createTarget", params);
       if (!r.success) return { url, targetId: "", ok: false, error: r.error.message };
-      const c = r.data as { targetId: string }; // CDP boundary cast: Target.createTarget returns { targetId: string }
+      const c = r.data as { targetId: string };
+      if (params["newWindow"]) client.ownership().setHarnessWindow(c.targetId);
+      client.ownership().add(c.targetId);
       return { url, targetId: c.targetId, ok: true };
     }));
     // Phase 2: attach + navigate each created tab in parallel.
@@ -101,6 +109,12 @@ export const openUrlsTool = defineBrowserTool({
           if (!enabled.success) return { ...tab, ok: false, error: enabled.error.message };
           const nav = await client.session().callOnTarget("Page.navigate", { url: tab.url }, sid);
           if (!nav.success) return { ...tab, ok: false, error: nav.error.message };
+          // Mark the tab with a green circle so the user can see which
+          // tabs the agent opened. Best-effort; don't fail on CSP blocks.
+          client.evaluateJs(
+            safeJs`if(!document.title.startsWith('🟢'))document.title='🟢 '+document.title`,
+            sid
+          ).catch(() => {});
           return tab;
         } finally {
           completed++;

package/src/domains/setup.ts

@@ -0,0 +1,41 @@
+/**
+ * browser_setup tool — agent-callable browser initialization.
+ *
+ * The agent can call this directly when browser tools fail with
+ * "not initialized" instead of asking the user. Idempotent: safe
+ * to call even when already connected.
+ */
+
+import { Type } from "typebox";
+import { Text } from "@mariozechner/pi-tui";
+import type { Result } from "../util/result";
+import { err, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { performSetup } from "../setup";
+
+const SetupArgs = Type.Object({});
+
+export const setupTool = defineBrowserTool({
+  name: "browser_setup",
+  label: "Browser Setup",
+  description:
+    "Initialize browser control. Spawns the daemon, connects to Chrome, opens a test tab. " +
+    "Call when browser tools fail with 'Browser harness not initialized'. Idempotent.",
+  promptSnippet: "Initialize browser connection",
+  promptGuidelines: [
+    "Call browser_setup when you get a 'Browser harness not initialized' error from any browser tool.",
+    "This tool is idempotent — calling it when already connected is harmless.",
+    "After browser_setup succeeds, retry the browser tool that failed.",
+  ],
+  parameters: SetupArgs,
+  // ensureAlive:false — this tool IS the setup; it must bypass the socket guard
+  ensureAlive: false,
+  renderCall: () => new Text("🔧 Initializing browser...", 0, 0),
+  async handler(_args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const result = await performSetup(client);
+    if (result.success) {
+      return ok({ text: result.data });
+    }
+    return err({ kind: "internal", message: result.error });
+  },
+});

package/src/index.ts

@@ -27,6 +27,7 @@ import { registerSetupCommand } from "./setup";
 import { type BrowserState, defaultState, persistState, restoreState } from "./state";
 import { registerAllTools } from "./registry";
 import { cleanupTempDirs } from "./util/truncate";
+import { createDaemonTransport } from "./cdp/daemon-transport";
 
 export default function browserHarnessExtension(pi: ExtensionAPI): void {
   const flagNs = pi.getFlag("browser-namespace") as string | undefined;
@@ -98,25 +99,43 @@ export default function browserHarnessExtension(pi: ExtensionAPI): void {
 
   pi.on("session_start", async (_event, ctx) => {
     state = restoreState(ctx, state.namespace);
-    const initialOwnership: { ownedTargetIds?: ReadonlyArray<string>; harnessWindowTargetId?: string } = {};
-    if (state.ownedTargetIds !== undefined) initialOwnership.ownedTargetIds = state.ownedTargetIds;
-    if (state.harnessWindowTargetId !== undefined) initialOwnership.harnessWindowTargetId = state.harnessWindowTargetId;
-    client = createBrowserClient({
-      namespace: state.namespace,
-      ...(Object.keys(initialOwnership).length > 0 ? { initialOwnership } : {}),
-      onOwnershipChange: (snap) => {
-        state = {
-          ...state,
-          ownedTargetIds: snap.ownedTargetIds,
-          ...(snap.harnessWindowTargetId !== undefined
-            ? { harnessWindowTargetId: snap.harnessWindowTargetId }
-            : {}),
-        };
-        persistState(pi, state);
-      },
-    });
-    // failure is fine — surfaced via tool errors when the agent first tries to use the browser
-    await client.start();
+
+    // Create the client lazily on first session. The daemon transport
+    // is created but NOT connected — that only happens when the user
+    // runs /browser-setup or a browser tool call finds an existing socket.
+    // This means zero Chrome prompts for non-browser pi sessions.
+    if (!client) {
+      const transport = createDaemonTransport(state.namespace);
+
+      const initialOwnership: { ownedTargetIds?: ReadonlyArray<string>; harnessWindowTargetId?: string } = {};
+      if (state.ownedTargetIds !== undefined) initialOwnership.ownedTargetIds = state.ownedTargetIds;
+      if (state.harnessWindowTargetId !== undefined) initialOwnership.harnessWindowTargetId = state.harnessWindowTargetId;
+
+      client = createBrowserClient({
+        namespace: state.namespace,
+        transport,
+        ...(Object.keys(initialOwnership).length > 0 ? { initialOwnership } : {}),
+        onOwnershipChange: (snap) => {
+          state = {
+            ...state,
+            ownedTargetIds: snap.ownedTargetIds,
+            ...(snap.harnessWindowTargetId !== undefined
+              ? { harnessWindowTargetId: snap.harnessWindowTargetId }
+              : {}),
+          };
+          // Ownership changes can fire from CDP events at any time,
+          // including after session replacement when pi's ctx is stale.
+          // Persistence is best-effort — failure must not crash the event consumer.
+          // ponytail: try/catch is the simplest guard against stale-ctx.
+          try { persistState(pi, state); } catch { /* stale ctx — safe to ignore */ }
+        },
+      });
+    }
+
+    // Do NOT call client.start() here — browser control is on-demand.
+    // The first browser tool call or /browser-setup triggers the actual
+    // daemon socket connection and Chrome prompt.
+
     if (!toolsRegistered) {
       registerAllTools(pi, client);
       toolsRegistered = true;
@@ -132,15 +151,17 @@ export default function browserHarnessExtension(pi: ExtensionAPI): void {
     persistState(pi, state);
     if (client) {
       try {
-        await client.stop();
+        // Detach from the page target (removes the "Chrome is being controlled"
+        // banner) but keep the transport alive for the next session.
+        await client.detach();
       } catch (e) {
-        // Shutdown is best-effort, but a stuck stop() points at a transport
-        // bug worth surfacing for debugging.
-        console.warn("[pi-browser-harness] client.stop() failed during shutdown:", e);
+        console.warn("[pi-browser-harness] client.detach() failed during shutdown:", e);
       }
-      client = null;
+      // ponytail: keep the transport alive across sessions.
+      // Do NOT call client.stop() or null out client — the daemon connection
+      // persists and eliminates the per-session "Allow Remote Debugging" prompt.
+      // Only Chrome restart or daemon death triggers a new prompt.
     }
-    toolsRegistered = false;
     await cleanupTempDirs();
   });
 

package/src/registry.ts

@@ -17,11 +17,14 @@ import { httpGetTool, networkRequestsTool } from "./domains/network";
 import { consoleTool } from "./domains/console";
 import { snapshotTool } from "./domains/snapshot";
 import { executeJsTool, runScriptTool } from "./domains/js";
+import { setupTool } from "./domains/setup";
 
 // Mutation tools that modify page / browser state are marked `serialized: true`
 // so they run through a shared async mutex.  Observation / read-only tools are
 // left unmarked and can execute in parallel.
 const TOOLS: ReadonlyArray<AnyBrowserToolDefinition> = [
+  // setup comes first — the agent calls this to self-recover from not-initialized
+  setupTool,
   { ...clickTool, serialized: true },
   { ...typeTool, serialized: true },
   { ...pressKeyTool, serialized: true },

package/src/setup.ts

@@ -1,37 +1,50 @@
 /**
- * Setup command — verifies Chrome is running with remote debugging
- * and connects the pi agent to it.
+ * Setup — verifies Chrome is running with remote debugging and connects
+ * the pi agent to it. Exposed as both a slash command (/browser-setup) for
+ * users and a tool (browser_setup) for the agent to self-recover.
  */
 
-import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { execSync } from "node:child_process";
 import type { BrowserClient } from "./client";
+import { ensureDaemon } from "./daemon/spawn";
+
+// ── Public: register the /browser-setup slash command ──────────────────────
 
 export function registerSetupCommand(pi: ExtensionAPI, client: BrowserClient): void {
   pi.registerCommand("browser-setup", {
     description: "Connect pi to your Chrome browser",
     handler: async (_args, ctx) => {
-      await runSetup(ctx, client);
+      const result = await performSetup(client);
+      if (result.success) {
+        ctx.ui.notify(result.data, "info");
+      } else {
+        ctx.ui.notify(result.error, "error");
+      }
     },
   });
 }
 
-async function runSetup(ctx: ExtensionContext, client: BrowserClient): Promise<void> {
-  ctx.ui.notify("browser setup: checking Chrome...", "info");
+// ── Shared setup result ────────────────────────────────────────────────────
+
+export type SetupResult = { success: true; data: string } | { success: false; error: string };
+
+// ── Shared setup logic (used by both the command and the tool) ─────────────
 
+export async function performSetup(client: BrowserClient): Promise<SetupResult> {
   // Step 1: Check Chrome is running
   const chromeRunning = checkChromeRunning();
   if (!chromeRunning) {
-    ctx.ui.notify(
-      "No browser instance running. Please open your browser and then run /browser-setup.",
-      "error",
-    );
-    return;
+    return { success: false, error: "No browser instance running. Please open your browser and then run /browser-setup." };
   }
-  ctx.ui.notify("Chrome is running ✓", "info");
 
-  // Step 2: Try to connect to Chrome DevTools
-  ctx.ui.notify("Connecting to Chrome DevTools...", "info");
+  // Step 2: Start the browser daemon (spawns if not running, silently reuses if alive)
+  const daemonReady = await ensureDaemon();
+  if (!daemonReady) {
+    return { success: false, error: "Could not start the browser daemon. Check /tmp/pi-browser-daemon.sock." };
+  }
+
+  // Step 3: Connect to Chrome DevTools
   const startResult = await client.start();
   if (!startResult.success) {
     const msg = startResult.error.message;
@@ -43,30 +56,23 @@ async function runSetup(ctx: ExtensionContext, client: BrowserClient): Promise<v
       lower.includes("econnrefused") ||
       lower.includes("cannot reach chrome devtools")
     ) {
-      ctx.ui.notify(
-        "Chrome remote debugging needs to be enabled.\n\n" +
-          "Open chrome://inspect/#remote-debugging in your browser, tick the\n" +
-          "\"Discover network targets\" / Allow checkbox, then run /browser-setup again.\n\n" +
+      return {
+        success: false,
+        error:
+          "Chrome remote debugging needs to be enabled.\n\n" +
+          'Open chrome://inspect/#remote-debugging in your browser, tick the\n' +
+          '"Discover network targets" / Allow checkbox, then retry.\n\n' +
           "Or set BU_CDP_WS to a remote browser WebSocket URL.",
-        "warning",
-      );
-      return;
+      };
     }
 
-    ctx.ui.notify(`Connection failed: ${msg}`, "error");
-    return;
+    return { success: false, error: `Connection failed: ${msg}` };
   }
-  ctx.ui.notify("Connected to Chrome ✓", "info");
 
-  // Step 3: Verify with test navigation
-  ctx.ui.notify("Testing browser control...", "info");
+  // Step 4: Verify with test navigation
   const tabResult = await client.newTab("https://github.com");
   if (!tabResult.success) {
-    ctx.ui.notify(
-      `Browser connected but test navigation failed: ${tabResult.error.message}`,
-      "warning",
-    );
-    return;
+    return { success: false, error: `Browser connected but test navigation failed: ${tabResult.error.message}` };
   }
 
   const info = await client.pageInfo();
@@ -75,24 +81,24 @@ async function runSetup(ctx: ExtensionContext, client: BrowserClient): Promise<v
   }
 
   const pageUrl = info.success && !("dialog" in info.data) ? info.data.url : "github.com";
-  ctx.ui.notify(`Browser control verified ✓\nNavigated to: ${pageUrl}`, "info");
+  return { success: true, data: `Browser connected ✓\nNavigated to: ${pageUrl}` };
 }
 
+// ── Chrome process detection ───────────────────────────────────────────────
+
 function checkChromeRunning(): boolean {
   try {
     if (process.platform === "darwin") {
-      // Exact line matching — excludes "Google Chrome Helper" etc.
-      // that linger after the user quits the browser.
+      // ps -o comm= returns the full executable path on modern macOS.
+      // We check for "Google Chrome" anywhere in the path (case-insensitive),
+      // excluding helper/renderer subprocesses.
       const out = execSync("ps -A -o comm=", { timeout: 5000 }).toString().toLowerCase();
       const lines = out.split("\n").map((l) => l.trim()).filter(Boolean);
-      const browserProcesses = ["google chrome", "chromium", "microsoft edge"];
       return lines.some((l) => {
-        if (l.includes("helper") || l.includes("renderer")) return false;
-        return browserProcesses.includes(l);
+        if (l.includes("helper") || l.includes("renderer") || l.includes("crashpad")) return false;
+        return l.includes("google chrome") || l.includes("chromium") || l.includes("microsoft edge");
       });
     } else if (process.platform === "linux") {
-      // Use args to distinguish the main browser process from sub-processes
-      // (GPU, renderer, utility, etc.) which carry --type= flags.
       const out = execSync("ps -A -o comm=,args=", { timeout: 5000 }).toString().toLowerCase();
       const lines = out.split("\n").map((l) => l.trim()).filter(Boolean);
       const browserComms = ["chrome", "chromium", "chromium-browser", "msedge", "microsoft-edge", "google-chrome"];