pi-browser-harness 0.5.0 → 0.8.0

package/src/domains/snapshot.ts

@@ -2,6 +2,7 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { Type } from "typebox";
 import { Container, Image, type ImageTheme, Markdown, Text, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
 import { getMarkdownTheme, keyHint } from "@mariozechner/pi-coding-agent";
+import type { CdpSession } from "../cdp/session";
 import { type Result, err, ok } from "../util/result";
 import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
 import { applyTruncation } from "../util/truncate";
@@ -27,7 +28,7 @@ const SnapshotArgs = Type.Object({
 
 // Raw shapes from CDP Accessibility.getFullAXTree. Cast at this boundary only.
 type AxValue = { value?: unknown };
-type RawAxNode = {
+export type RawAxNode = {
   nodeId: string;
   parentId?: string;
   childIds?: ReadonlyArray<string>;
@@ -42,7 +43,7 @@ type RawAxNode = {
 
 type Box = { x: number; y: number; width: number; height: number; cx: number; cy: number };
 
-type SlimNode = {
+export type SlimNode = {
   role: string;
   name?: string;
   value?: string;
@@ -51,6 +52,8 @@ type SlimNode = {
   children: SlimNode[];
   /** Internal: kept for the post-build box fetch. Stripped before returning to the LLM. */
   _backendId?: number;
+  /** Stable handle (e.g. "e12") for interaction tools. Survives re-renders via backendNodeId. */
+  ref?: string;
   /** Click target — center of the element's bounding box, in viewport CSS pixels. */
   box?: Box;
 };
@@ -70,6 +73,20 @@ const INTERACTIVE_ROLES = new Set([
   "spinbutton",
 ]);
 
+// Roles whose live DOM value/checked state should override the (often stale)
+// AX-tree value. The AX `value` is unreliable for freshly-typed or controlled
+// inputs, so for these we read the real DOM property at snapshot time.
+const VALUE_ROLES = new Set([
+  "textbox",
+  "searchbox",
+  "spinbutton",
+  "combobox",
+  "checkbox",
+  "radio",
+  "switch",
+  "slider",
+]);
+
 const stringOf = (v: AxValue | undefined): string | undefined => {
   const x = v?.value;
   if (typeof x === "string" && x !== "") return x;
@@ -93,7 +110,7 @@ const collectState = (props: RawAxNode["properties"]): string | undefined => {
   return flags.length > 0 ? flags.join(", ") : undefined;
 };
 
-const buildTree = (
+export const buildTree = (
   rawNodes: ReadonlyArray<RawAxNode>,
   opts: { interestingOnly: boolean; maxNodes: number },
 ): SlimNode[] => {
@@ -204,8 +221,9 @@ const renderOutline = (nodes: ReadonlyArray<SlimNode>): string => {
       if (n.name) line += ` "${n.name}"`;
       if (n.value && n.value !== n.name) line += ` = ${JSON.stringify(n.value)}`;
       if (n.state) line += ` (${n.state})`;
-      // Surface click coordinates for interactive nodes — agents can pass these
-      // straight to browser_click without a screenshot round-trip.
+      // Surface the stable ref + click coordinates for interactive nodes. Agents
+      // pass `ref` to interaction tools (survives re-renders); @(x,y) is a fallback.
+      if (n.ref) line += ` [${n.ref}]`;
       if (n.box && INTERACTIVE_ROLES.has(n.role)) {
         line += ` @(${n.box.cx},${n.box.cy})`;
       }
@@ -229,7 +247,7 @@ const stripInternals = (nodes: ReadonlyArray<SlimNode>): SlimNode[] =>
  * roles. Caller fetches DOM.getBoxModel for each and writes box back into the
  * slim node by reference.
  */
-const collectInteractiveTargets = (
+export const collectInteractiveTargets = (
   nodes: ReadonlyArray<SlimNode>,
 ): Array<{ node: SlimNode; backendId: number }> => {
   const out: Array<{ node: SlimNode; backendId: number }> = [];
@@ -245,6 +263,33 @@ const collectInteractiveTargets = (
   return out;
 };
 
+/**
+ * Read the live DOM value for a form control by backend node id. Resolves the
+ * node to a JS object then reads the property that matters for its type:
+ * `.value` for inputs/selects/textareas, `.checked` (→ "checked"/"unchecked")
+ * for checkboxes/radios. Returns undefined on any failure so the caller falls
+ * back to the AX value. Mirrors the box-fetch error handling: never throws.
+ */
+const liveValue = async (session: CdpSession, backendId: number): Promise<string | undefined> => {
+  const resolved = await session.call("DOM.resolveNode", { backendNodeId: backendId });
+  if (!resolved.success) return undefined;
+  const objectId = (resolved.data as { object?: { objectId?: string } }).object?.objectId;
+  if (!objectId) return undefined;
+  const fn = `function () {
+    if (this.type === "checkbox" || this.type === "radio") return this.checked ? "checked" : "unchecked";
+    if (typeof this.value === "string") return this.value;
+    return null;
+  }`;
+  const r = await session.call("Runtime.callFunctionOn", {
+    objectId,
+    functionDeclaration: fn,
+    returnByValue: true,
+  });
+  if (!r.success) return undefined;
+  const value = (r.data as { result?: { value?: unknown } }).result?.value;
+  return typeof value === "string" ? value : undefined;
+};
+
 type SnapshotDetails = {
   nodeCount: number;
   truncated: boolean;
@@ -258,14 +303,15 @@ export const snapshotTool = defineBrowserTool({
   name: "browser_snapshot",
   label: "Browser Snapshot",
   description:
-    "DEFAULT tool for understanding what is on the page. Returns the structured accessibility tree (roles, names, states, hierarchy) plus click coordinates for every interactive element as @(x,y). Use this BEFORE deciding whether you need a screenshot — almost always sufficient on its own and far cheaper. Pair with browser_execute_js for surgical reads of specific element values.",
-  promptSnippet: "Get accessibility-tree snapshot of the current page (default for page inspection)",
+    "DEFAULT tool for understanding what is on the page. Returns the structured accessibility tree (roles, names, states, hierarchy). Every interactive element gets a stable ref shown as [eN] plus click coordinates @(x,y). Pass the ref to browser_click/browser_fill/etc. — refs survive re-renders, coordinates don't. Use this BEFORE deciding whether you need a screenshot. Pair with browser_execute_js for surgical reads of specific element values.",
+  promptSnippet: "Get accessibility-tree snapshot with stable element refs (default for page inspection)",
   promptGuidelines: [
     "DEFAULT — use this whenever you need to know what's on a page, what's clickable, or how the page is structured.",
-    "Click coordinates come for free: every interactive element shows '@(x,y)' in the outline. Pass these straight to browser_click. NO screenshot round-trip needed.",
-    "DO NOT call browser_screenshot just to understand the page. This tool already gives you structure, labels, states, and click targets.",
+    "Refs come for free: every interactive element shows '[eN]' in the outline. Pass eN as `ref` to browser_click/browser_fill/browser_select_option/browser_focus/browser_upload_file — refs survive re-renders, so prefer them over the '@(x,y)' coordinates (a fallback).",
+    "DO NOT call browser_screenshot just to understand the page. This tool already gives you structure, labels, states, refs, and click targets.",
+    "Re-run after a navigation or a major re-render to get fresh refs; a 'ref is stale' error from an interaction tool means you need a new snapshot.",
     "Pass includeScreenshot:true ONLY if you also need to verify visual rendering (rare).",
-    "format:'json' returns the raw slim structure (with `box` per node) for programmatic use; default 'outline' is human/LLM-readable.",
+    "format:'json' returns the raw slim structure (with `ref` and `box` per node) for programmatic use; default 'outline' is human/LLM-readable.",
   ],
   parameters: SnapshotArgs,
 
@@ -293,6 +339,19 @@ export const snapshotTool = defineBrowserTool({
     //    without a screenshot round-trip. Capped budget so a slow page can't
     //    wedge the call.
     const targets = collectInteractiveTargets(slim);
+
+    // Assign stable refs (e1, e2, …) to every interactive target. Interaction
+    // tools resolve these refs to backendNodeIds at call time, so they stay
+    // valid across re-renders. The ref → backendNodeId map (and the per-ref
+    // signature baseline for the post-mutation diff) is published below, after
+    // the box/live-value fetch so the signature reflects the live DOM value.
+    const refMap = new Map<string, number>();
+    targets.forEach(({ node, backendId }, i) => {
+      const ref = `e${i + 1}`;
+      node.ref = ref;
+      refMap.set(ref, backendId);
+    });
+
     if (targets.length > 0) {
       const ac = new AbortController();
       const timer = setTimeout(() => ac.abort(), 1_500);
@@ -320,11 +379,28 @@ export const snapshotTool = defineBrowserTool({
             cx: Math.round(x + width / 2),
             cy: Math.round(y + height / 2),
           };
+          // Override the AX value with the live DOM property for form controls.
+          // The AX `value` is stale for freshly-typed / controlled inputs, so the
+          // agent can't trust it as a read-back signal. Reading .value/.checked
+          // from the actual element fixes that.
+          if (ac.signal.aborted || !VALUE_ROLES.has(node.role)) return;
+          const live = await liveValue(session, backendId);
+          if (live !== undefined) node.value = live;
         }),
       );
       clearTimeout(timer);
     }
 
+    // Publish refs to the active tab. The signature (role|name|value|state) is
+    // the baseline the post-mutation auto-diff compares against, so it must use
+    // the live values resolved above.
+    const refSig = new Map<string, string>();
+    for (const { node } of targets) {
+      if (node.ref === undefined) continue;
+      refSig.set(node.ref, `${node.role}|${node.name ?? ""}|${node.value ?? ""}|${node.state ?? ""}`);
+    }
+    session.setRefMap(refMap, refSig);
+
     const stripped = stripInternals(slim);
     const text = (args.format ?? "outline") === "outline" ? renderOutline(slim) : JSON.stringify(stripped, null, 2);
     const trunc = await applyTruncation(text, "snapshot");

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/prompt.ts

@@ -21,9 +21,13 @@ to interact with pages visually, and other tools alongside them.
 
 | Tool | Purpose |
 |------|---------|
+| browser_snapshot | Accessibility-tree snapshot. Assigns every interactive element a stable **ref** (\`[eN]\`) plus \`@(x,y)\`. Refs are the primary handle for interaction tools — they survive re-renders, coordinates don't. |
 | browser_screenshot | Capture a PNG or JPEG screenshot of the current page (rendered inline in the TUI; the LLM reads the image via the saved file path) |
-| browser_click | Click at viewport coordinates |
-| browser_type | Type text into the focused element |
+| browser_click | Click an element by **ref** (preferred — re-resolves position, survives re-renders) or viewport x/y. Appends a compact diff of page changes. |
+| browser_type | Type text into the focused element (real keystrokes; requires a focused field) |
+| browser_fill | Fill an input/textarea by **ref** (preferred) or selector — updates React/Vue controlled components, verifies the value, appends a page-changes diff |
+| browser_select_option | Select an option in a native <select> by **ref** (preferred) or selector, choosing by value/label/index (fires change) |
+| browser_focus | Focus an element by **ref** (preferred) or selector (deterministic; use before browser_type) |
 | browser_press_key | Press a keyboard key (Enter, Tab, Escape, arrows, etc.) |
 | browser_scroll | Scroll the page at coordinates |
 | browser_navigate | Navigate to a URL (result details.outcome.kind is "in_place" or "new_tab_created") |
@@ -38,6 +42,7 @@ to interact with pages visually, and other tools alongside them.
 | browser_http_get | Direct HTTP GET (outside browser, for APIs) |
 | browser_console | Read JS errors / console output on the current tab (diagnostic — use when an action looks broken; pass sinceSeq from the previous nextCursor to see only new messages) |
 | browser_wait | Wait N seconds |
+| browser_wait_for | Wait until a selector/text appears (or a selector disappears) — use for SPA content before interacting |
 | browser_wait_for_load | Wait for document.readyState === 'complete' (returns a typed timeout error if the page doesn't reach readyState=complete in N seconds, default 15) |
 | browser_handle_dialog | Accept or dismiss a JS dialog |
 | browser_run_script | Execute a temporary script file with daemon access (write script to disk, then run) |
@@ -83,11 +88,25 @@ browser_http_get("https://api.example.com/data") + browser_click(x, y)
 browser_new_tab("https://example.com") → browser_wait_for_load() → browser_screenshot()
 \`\`\`
 
-**Form filling:**
+**Form filling (ref-first — this is the reliable path on React/SPA forms):**
 \`\`\`
-browser_screenshot() → find input coordinates → browser_click(x, y)
-→ browser_type("text") → browser_press_key("Tab") → browser_screenshot()
+browser_wait_for({ selector: "#email" })                    // ensure SPA field is rendered
+browser_snapshot()                                          // each interactive element gets a [eN] ref
+→ browser_fill({ ref: "e7", value: "a@b.com" })            // target by ref, not a guessed selector
+→ browser_select_option({ ref: "e9", label: "India" })     // native <select> by ref
+→ browser_click({ ref: "e12" })                            // e.g. Save — re-resolves position even if the form reflowed
+// each mutating call appends a compact "Page changes" diff — read it to confirm
+// the change landed (e.g. a save closed the form, a new field appeared as *[eN]).
 \`\`\`
+**Why ref over selector/coordinates:** refs are keyed to the element's identity, so
+they survive the re-renders that React/Vue forms trigger on every edit and save —
+coordinates go stale and selectors you guess often don't match. If a call returns
+"ref is stale", the page changed: re-run browser_snapshot for fresh refs.
+
+Prefer browser_fill for text inputs/textareas — it fires input/change so controlled
+components update, and returns the field's value for verification. Use browser_click +
+browser_type only for keystroke-sensitive widgets (autocomplete, masked inputs);
+browser_type requires an already-focused field and errors if none is focused.
 
 **Data extraction:**
 \`\`\`
@@ -121,8 +140,8 @@ write("/tmp/extract.js", "...script with daemon access...") → browser_run_scri
 
 | Tool | Purpose |
 |------|---------|
-| browser_upload_file | Upload a file to a file input (bypasses file picker) |
-| browser_dispatch_key | Dispatch a DOM KeyboardEvent on a specific element (for React/Vue inputs); returns details.matched (number of elements) |
+| browser_upload_file | Upload a file to a file input by **ref** (preferred) or selector (bypasses file picker) |
+| browser_dispatch_key | Dispatch a DOM KeyboardEvent on an element by **ref** (preferred) or selector (for React/Vue inputs); returns details.matched |
 | browser_download | Configure download directory and disable save-as prompts |
 | browser_viewport_resize | Resize the viewport for responsive testing |
 | browser_drag_and_drop | Perform drag-and-drop from one coordinate to another |

package/src/registry.ts

@@ -3,7 +3,8 @@ import type { BrowserClient } from "./client";
 import { type AnyBrowserToolDefinition, registerBrowserTool } from "./util/tool";
 import { clickTool } from "./domains/click";
 import { typeTool, pressKeyTool, dispatchKeyTool } from "./domains/keyboard";
-import { pageInfoTool, waitTool, waitForLoadTool } from "./domains/page";
+import { fillTool, selectOptionTool, focusTool } from "./domains/form";
+import { pageInfoTool, waitTool, waitForLoadTool, waitForTool } from "./domains/page";
 import { scrollTool } from "./domains/scroll";
 import { handleDialogTool } from "./domains/dialog";
 import { screenshotTool } from "./domains/screenshot";
@@ -17,18 +18,25 @@ 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 },
+  { ...fillTool, serialized: true },
+  { ...selectOptionTool, serialized: true },
+  { ...focusTool, serialized: true },
   { ...pressKeyTool, serialized: true },
   { ...dispatchKeyTool, serialized: true },
   { ...scrollTool, serialized: true },
   pageInfoTool,
   waitTool,
+  waitForTool,
   { ...waitForLoadTool, serialized: true },
   { ...handleDialogTool, serialized: true },
   screenshotTool,

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"];

package/src/util/tool.ts

@@ -9,6 +9,8 @@ import type {
   ToolRenderResultOptions,
 } from "@mariozechner/pi-coding-agent";
 import type { Component } from "@mariozechner/pi-tui";
+import { access } from "node:fs/promises";
+import { DAEMON_SOCKET_PATH } from "../daemon/protocol";
 import type { BrowserClient } from "../client";
 import type { Result } from "./result";
 
@@ -142,6 +144,23 @@ export const registerBrowserTool = (
       : {}),
     async execute(_toolCallId, args, signal, onUpdate, extensionCtx) {
       if (def.ensureAlive !== false) {
+        // Check daemon socket exists before attempting browser control.
+        // If missing, the user hasn't run /browser-setup yet. Return a clear
+        // error so the agent knows to direct the user to initialize.
+        try {
+          await access(DAEMON_SOCKET_PATH);
+        } catch {
+          return toToolResult(
+            {
+              success: false,
+              error: {
+                kind: "not_connected",
+                message: "Browser harness not initialized. Run /browser-setup first",
+              },
+            },
+            def.name,
+          );
+        }
         const alive = await client.ensureAlive();
         if (!alive.success) {
           return toToolResult(