pi-browser-harness 0.5.0 → 0.8.0

package/CHANGELOG.md

@@ -2,7 +2,18 @@
 
 All notable changes to pi-browser-harness will be documented in this file.
 
-## 0.5.0 — 2026-05-07
+## 0.6.0 — 2026-06-21
+
+### Added
+
+- **Per-tab isolation for multi-agent safety.** Each agent's browser session now operates in a dedicated Chrome window with tab ownership tracking. Tabs opened via `browser_open_urls` and `browser_new_tab` are automatically registered in the ownership registry and tagged with a 🟢 prefix in the document title for user visibility. `browser_list_tabs` scoped to `"owned"` (default) only shows the current session's tabs.
+- **Unix socket daemon with auto-reconnect.** The browser daemon now binds to a Unix-domain socket (`pi-browser.sock`) in the harness temp directory instead of a TCP port. The transport layer reconnects automatically when Chrome restarts — no manual `/browser-reload-daemon` needed.
+- **On-demand browser initialization.** Chrome is no longer launched eagerly at harness startup. The harness attaches lazily on the first browser tool call, reducing resource usage when the agent isn't using the browser.
+- **`browser_setup` as agent-callable tool.** The setup tool can now be called programmatically by agents, not just via slash command. Idempotent — safe to call when already connected.
+
+### Fixed
+
+- **Chrome detection on macOS** now matches by process-name substring instead of exact binary path comparison, fixing false negatives when Chrome is running from different installation paths (e.g. `/Applications/Google Chrome.app/` vs user-local copies).
 
 ### Added
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-browser-harness",
-  "version": "0.5.0",
+  "version": "0.8.0",
   "description": "Browser control extension for pi — navigate, click, type, screenshot, and extract data from real Chrome via CDP",
   "keywords": [
     "pi-package",
@@ -52,6 +52,7 @@
     "@mariozechner/pi-coding-agent": "*",
     "@mariozechner/pi-tui": "*",
     "@types/ws": "^8.18.1",
+    "tsx": "^4.22.4",
     "typebox": "*",
     "typescript": "^5.0.0"
   },

package/skills/pi-browser-harness/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pi-browser-harness
-description: Direct browser control via CDP. Use when the user wants to automate, scrape, test, or interact with web pages. Connects to the user's already-running Chrome. Default to browser_snapshot for understanding pages and browser_execute_js for surgical reads — browser_screenshot is for visual verification only.
+description: Direct browser control via CDP. Use when the user wants to automate, scrape, test, or interact with web pages. Connects to the user's already-running Chrome. Default to browser_snapshot for understanding pages and browser_execute_js for surgical reads — browser_screenshot is for visual verification only.
 ---
 
 # pi-browser-harness
@@ -30,6 +30,22 @@ What do you need to know?
 
 Pass `@(x,y)` from `browser_snapshot` straight to `browser_click`. No screenshot round-trip.
 
+## Connection Setup
+
+Browser control is **on-demand** — the daemon does NOT start automatically.
+If you try a browser tool and get a `not_connected` error, tell the user to
+run `/browser-setup` first. This opens the daemon and connects to Chrome.
+Once initialized, all subsequent sessions reuse the same connection silently.
+
+**Before calling any browser tool**, the runtime checks for the daemon socket
+at `/tmp/pi-browser-daemon.sock`. If the socket is missing (user hasn't run
+`/browser-setup`), you get: `"Browser harness not initialized. Run /browser-setup first"`.
+
+**Do not ask the user.** Call `browser_setup` directly — it spawns the daemon,
+connects to Chrome, and opens a test tab. The user sees a single "Allow Remote
+Debugging" prompt the first time. After that, all sessions reuse the same connection.
+`browser_setup` is idempotent — safe to call even when already connected.
+
 ## Connection
 
 You're attached to the user's real Chrome — never launch your own. If auth is required, stop and ask the user. If `browser_page_info` returns a dialog, handle it first with `browser_handle_dialog`.

package/src/cdp/daemon-transport.ts

@@ -0,0 +1,211 @@
+/**
+ * DaemonTransport — CdpTransport backed by a Unix socket to the browser daemon.
+ *
+ * Satisfies the exact CdpTransport interface so BrowserClient, CdpSession, and
+ * all domain tools work without changes. Internally uses newline-delimited JSON
+ * over a Unix domain socket instead of a WebSocket to Chrome.
+ *
+ * References:
+ *   - CdpTransport interface: src/cdp/transport.ts
+ *   - net.createConnection IPC: https://nodejs.org/docs/latest-v22.x/api/net.html#netcreateconnection
+ *   - readline.createInterface: https://nodejs.org/docs/latest-v22.x/api/readline.html#readlinecreateinterfaceoptions
+ */
+
+import { createConnection, type Socket } from "node:net";
+import { createInterface } from "node:readline";
+import { type Result, err, ok } from "../util/result";
+import { type CdpError, cdpError } from "../cdp/errors";
+import type { CdpTransport } from "../cdp/transport";
+import type { CdpEvent } from "../cdp/types";
+import { type Pending, makeEventQueue, makeOnClose, rejectAllPending, sendWithTimeout } from "./event-queue";
+import {
+  DAEMON_SOCKET_PATH,
+  type WireRequest,
+  type WireControl,
+  deserialize,
+  serialize,
+} from "../daemon/protocol";
+
+// ── Implementation ─────────────────────────────────────────────────────────────
+
+export const createDaemonTransport = (clientId: string): CdpTransport => {
+  let socket: Socket | null = null;
+  let rl: ReturnType<typeof createInterface> | null = null;
+  let queue = makeEventQueue();
+  const closeListeners = new Set<() => void>();
+  const pending = new Map<number, Pending>();
+  let registered = false;
+  let nextRequestId = 1;
+
+  const cleanup = (reason: string): void => {
+    rejectAllPending(pending, reason);
+    queue.end();
+    queue = makeEventQueue();
+    registered = false;
+
+    if (rl) { rl.close(); rl = null; }
+    if (socket) { try { socket.destroy(); } catch {} socket = null; }
+
+    for (const cb of closeListeners) cb();
+  };
+
+  // ── Connect ────────────────────────────────────────────────────────────
+
+  const connect = (_url: string, opts?: { timeoutMs?: number }): Promise<Result<void, CdpError>> => {
+    // url is ignored — we always connect to the daemon socket
+    const timeoutMs = opts?.timeoutMs ?? 10_000;
+
+    if (socket && !socket.destroyed && registered) {
+      return Promise.resolve(ok(undefined));
+    }
+
+    return new Promise((resolve) => {
+      let settled = false;
+      const settle = (r: Result<void, CdpError>): void => {
+        if (settled) return;
+        settled = true;
+        resolve(r);
+      };
+
+      try {
+        socket = createConnection(DAEMON_SOCKET_PATH);
+      } catch (e) {
+        settle(err(cdpError("transport_closed", e instanceof Error ? e.message : String(e))));
+        return;
+      }
+
+      const connectTimer = setTimeout(() => {
+        cleanup("Connection timeout");
+        settle(err(cdpError("timeout", `Daemon connection timed out after ${timeoutMs}ms`)));
+      }, timeoutMs);
+
+      socket.on("connect", () => {
+        clearTimeout(connectTimer);
+        rl = createInterface({ input: socket!, crlfDelay: Infinity });
+
+        rl.on("line", (line: string) => {
+          const msg = deserialize(line);
+          if (!msg) return;
+
+          if (msg.type === "control" && msg.action === "registered" && msg.clientId === clientId) {
+            registered = true;
+            settle(ok(undefined));
+            return;
+          }
+
+          if (msg.type === "control" && msg.action === "shutdown") {
+            cleanup(`Daemon shutting down: ${msg.reason ?? "unknown"}`);
+            return;
+          }
+
+          if (!registered) return;
+
+          if (msg.type === "response") {
+            const p = pending.get(msg.id);
+            if (!p) return;
+            pending.delete(msg.id);
+            clearTimeout(p.timer);
+
+            if (msg.error) {
+              p.resolve(err(cdpError(
+                msg.error.message.includes("Session with given id not found")
+                  ? "session_not_found"
+                  : "remote_error",
+                msg.error.message,
+                p.method,
+              )));
+            } else {
+              p.resolve(ok(msg.result));
+            }
+            return;
+          }
+
+          if (msg.type === "event") {
+            queue.push({
+              method: msg.method,
+              params: msg.params,
+              ...(msg.sessionId !== undefined ? { sessionId: msg.sessionId } : {}),
+            });
+            return;
+          }
+        });
+
+        socket!.on("error", () => {
+          // Errors are surfaced via 'close'
+        });
+
+        socket!.on("close", () => {
+          clearTimeout(connectTimer);
+          cleanup("Daemon socket closed");
+          // If connect hasn't settled yet, settle with error
+          settle(err(cdpError("transport_closed", "Daemon socket closed before registration")));
+        });
+
+        // Send registration
+        const regMsg: WireControl = { type: "control", action: "register", clientId };
+        socket!.write(serialize(regMsg) + "\n");
+      });
+
+      socket.on("error", (e: NodeJS.ErrnoException) => {
+        clearTimeout(connectTimer);
+        const msg = e.code === "ENOENT"
+          ? "Daemon not running — socket not found"
+          : e.message;
+        settle(err(cdpError("transport_closed", msg)));
+      });
+    });
+  };
+
+  // ── Close ──────────────────────────────────────────────────────────────
+
+  const close = async (): Promise<void> => {
+    if (registered && socket && !socket.destroyed) {
+      const dereg: WireControl = { type: "control", action: "deregister", clientId };
+      try { socket.write(serialize(dereg) + "\n"); } catch {}
+    }
+    cleanup("close() called");
+  };
+
+  // ── Request ────────────────────────────────────────────────────────────
+
+  const request = (
+    method: string,
+    params: Record<string, unknown>,
+    opts?: { sessionId?: string | null; timeoutMs?: number },
+  ): Promise<Result<unknown, CdpError>> => {
+    const timeoutMs = opts?.timeoutMs ?? 15_000;
+    const sessionId = opts?.sessionId ?? null;
+
+    if (!socket || socket.destroyed || !registered) {
+      return Promise.resolve(err(cdpError("transport_closed", "Daemon not connected", method)));
+    }
+
+    const id = nextRequestId++;
+    const req: WireRequest = {
+      type: "request",
+      id,
+      method,
+      params,
+      ...(sessionId !== null && sessionId !== undefined ? { sessionId } : {}),
+    };
+
+    return sendWithTimeout(pending, id, method, timeoutMs, "Daemon", () => socket!.write(serialize(req) + "\n"));
+  };
+
+  // ── Events ─────────────────────────────────────────────────────────────
+
+  const events = (): AsyncIterable<CdpEvent> => queue.iter;
+
+  // ── State ──────────────────────────────────────────────────────────────
+
+  const state = (): "open" | "closed" | "connecting" => {
+    if (!socket) return "closed";
+    if (!registered) return "connecting";
+    if (socket.destroyed) return "closed";
+    return "open";
+  };
+
+  const onClose = makeOnClose(closeListeners);
+
+  return { connect, close, request, events, state, onClose };
+};

package/src/cdp/event-queue.ts

@@ -0,0 +1,128 @@
+/**
+ * Shared transport primitives for CdpTransport implementations.
+ *
+ * Both the WebSocket transport (transport.ts, talking to Chrome directly) and
+ * the daemon transport (daemon-transport.ts, talking to the daemon over a Unix
+ * socket) need an identical single-consumer async event queue plus the same
+ * pending-request bookkeeping. This module is the single source of truth for
+ * that shared machinery.
+ */
+
+import { type Result, err } from "../util/result";
+import { type CdpError, cdpError } from "./errors";
+import type { CdpEvent } from "./types";
+
+export type CdpResult = Result<unknown, CdpError>;
+
+/**
+ * A single-consumer async queue of CDP events.
+ *
+ * `push` enqueues an event (dropped silently after `end`). `end` terminates the
+ * stream — any pending and future iterator `next()` calls resolve `done:true`.
+ * `iter` is the AsyncIterable consumed by one for-await loop; a second consumer
+ * would silently steal events from the first.
+ */
+export type EventQueue = {
+  readonly push: (e: CdpEvent) => void;
+  readonly end: () => void;
+  readonly iter: AsyncIterable<CdpEvent>;
+};
+
+export const makeEventQueue = (): EventQueue => {
+  const buf: CdpEvent[] = [];
+  const waiters: Array<(v: IteratorResult<CdpEvent>) => void> = [];
+  let ended = false;
+  return {
+    push(e) {
+      if (ended) return;
+      const w = waiters.shift();
+      if (w) w({ value: e, done: false });
+      else buf.push(e);
+    },
+    end() {
+      ended = true;
+      // value: undefined as unknown as CdpEvent is the correct iterator-protocol
+      // pattern: when done=true the value field is conventionally undefined but
+      // the TS type still requires CdpEvent.
+      for (const w of waiters.splice(0)) w({ value: undefined as unknown as CdpEvent, done: true });
+    },
+    iter: {
+      [Symbol.asyncIterator]() {
+        return {
+          next: (): Promise<IteratorResult<CdpEvent>> =>
+            new Promise((resolve) => {
+              const next = buf.shift();
+              if (next) resolve({ value: next, done: false });
+              else if (ended) resolve({ value: undefined as unknown as CdpEvent, done: true });
+              else waiters.push(resolve);
+            }),
+        };
+      },
+    },
+  };
+};
+
+/** An in-flight CDP request awaiting its response or timeout. */
+export type Pending = {
+  readonly resolve: (v: Result<unknown, CdpError>) => void;
+  readonly timer: ReturnType<typeof setTimeout>;
+  readonly method: string;
+};
+
+/**
+ * Reject every in-flight request with a transport_closed error and clear the
+ * map. Called from each transport's cleanup path when the underlying connection
+ * goes away.
+ */
+export const rejectAllPending = (pending: Map<number, Pending>, reason: string): void => {
+  for (const [, p] of pending) {
+    clearTimeout(p.timer);
+    p.resolve(err(cdpError("transport_closed", reason, p.method)));
+  }
+  pending.clear();
+};
+
+/**
+ * Send a CDP request and return a promise that settles when the matching
+ * response arrives, the request times out, or the send throws.
+ *
+ * The transport supplies a `send` callback that puts the already-serialized
+ * payload onto its wire (WebSocket frame or Unix-socket line); everything else
+ * — registering the pending entry, the timeout timer, and synchronous send
+ * failure handling — is identical across transports and lives here.
+ *
+ * `timeoutLabel` is the transport's prefix for the timeout error message
+ * (e.g. "CDP" or "Daemon").
+ */
+export const sendWithTimeout = (
+  pending: Map<number, Pending>,
+  id: number,
+  method: string,
+  timeoutMs: number,
+  timeoutLabel: string,
+  send: () => void,
+): Promise<CdpResult> =>
+  new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      pending.delete(id);
+      resolve(err(cdpError("timeout", `${timeoutLabel} timeout after ${timeoutMs}ms: ${method}`, method)));
+    }, timeoutMs);
+    pending.set(id, { resolve, timer, method });
+    try {
+      send();
+    } catch (e) {
+      clearTimeout(timer);
+      pending.delete(id);
+      resolve(err(cdpError("transport_closed", e instanceof Error ? e.message : String(e), method)));
+    }
+  });
+
+/**
+ * Register a close listener, returning an unsubscribe function. Identical
+ * across transports, so it lives here.
+ */
+export const makeOnClose = (closeListeners: Set<() => void>) =>
+  (cb: () => void): (() => void) => {
+    closeListeners.add(cb);
+    return () => closeListeners.delete(cb);
+  };

package/src/cdp/session.ts

@@ -17,12 +17,25 @@ type TabSession = {
   pageInfoDirty: boolean;
   networkBuffer: ReturnType<typeof createNetworkBuffer>;
   consoleBuffer: ReturnType<typeof createConsoleBuffer>;
+  // Stable element refs (e1, e2, …) → CDP backendNodeId, from the latest
+  // snapshot of this tab. Replaced wholesale on every snapshot — old refs are
+  // stale anyway, so this stays bounded (~50–60 KB worst case).
+  refMap: Map<string, number>;
+  // Per-ref signature ("role|name|value") from the latest snapshot, used as the
+  // baseline for the post-mutation auto-diff. Replaced alongside refMap.
+  refSig: Map<string, string>;
 };
 
 export type CdpSession = {
   attachFirstPage(): Promise<Result<{ readonly targetId: string; readonly sessionId: string }, CdpError>>;
   switchTo(targetId: string): Promise<Result<void, CdpError>>;
   current(): { readonly sessionId: string; readonly targetId: string } | null;
+  /** Replace the active tab's ref map and ref signatures (from a fresh snapshot). */
+  setRefMap(refMap: Map<string, number>, refSig: Map<string, string>): void;
+  /** Resolve a ref (e.g. "e12") to its backendNodeId on the active tab, or undefined if unknown/stale. */
+  resolveRef(ref: string): number | undefined;
+  /** The active tab's prior ref signatures — baseline for the post-mutation diff. */
+  refSignatures(): ReadonlyMap<string, string>;
   call(method: string, params?: Record<string, unknown>, opts?: { timeoutMs?: number }): Promise<Result<unknown, CdpError>>;
   callOnTarget(method: string, params: Record<string, unknown>, sessionId: string, opts?: { timeoutMs?: number }): Promise<Result<unknown, CdpError>>;
   callBrowser(method: string, params?: Record<string, unknown>, opts?: { timeoutMs?: number }): Promise<Result<unknown, CdpError>>;
@@ -211,6 +224,8 @@ export const createCdpSession = (
         pageInfoDirty: false,
         networkBuffer: createNetworkBuffer(),
         consoleBuffer: createConsoleBuffer(),
+        refMap: new Map(),
+        refSig: new Map(),
       });
       sessionIdToTargetId.set(a.sessionId, pickTargetId);
       return ok({ targetId: pickTargetId, sessionId: a.sessionId });
@@ -230,6 +245,8 @@ export const createCdpSession = (
         pageInfoDirty: true,
         networkBuffer: createNetworkBuffer(),
         consoleBuffer: createConsoleBuffer(),
+        refMap: new Map(),
+        refSig: new Map(),
       };
       if (existing) {
         // Each Target.attachToTarget produces a new sessionId — update it.
@@ -249,6 +266,20 @@ export const createCdpSession = (
     current() {
       return sessionId && targetId ? { sessionId, targetId } : null;
     },
+    setRefMap(refMap, refSig) {
+      const tab = targetId ? tabs.get(targetId) : undefined;
+      if (!tab) return;
+      tab.refMap = refMap;
+      tab.refSig = refSig;
+    },
+    resolveRef(ref) {
+      const tab = targetId ? tabs.get(targetId) : undefined;
+      return tab?.refMap.get(ref);
+    },
+    refSignatures() {
+      const tab = targetId ? tabs.get(targetId) : undefined;
+      return tab?.refSig ?? new Map();
+    },
     call(method, params = {}, opts = {}) {
       return transport.request(method, params, { sessionId, ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}) });
     },

package/src/cdp/transport.ts

@@ -3,15 +3,10 @@ import { type Result, err, ok } from "../util/result";
 import { type CdpError, cdpError } from "./errors";
 import { isCdpRawMessage } from "./types";
 import type { CdpEvent, CdpRawMessage } from "./types";
+import { type Pending, makeEventQueue, makeOnClose, rejectAllPending, sendWithTimeout } from "./event-queue";
 
 const DEFAULT_TIMEOUT_MS = 15_000;
 
-type Pending = {
-  readonly resolve: (v: Result<unknown, CdpError>) => void;
-  readonly timer: ReturnType<typeof setTimeout>;
-  readonly method: string;
-};
-
 export type CdpTransport = {
   connect(url: string, opts?: { timeoutMs?: number }): Promise<Result<void, CdpError>>;
   close(): Promise<void>;
@@ -33,46 +28,6 @@ export const createCdpTransport = (): CdpTransport => {
   const pending = new Map<number, Pending>();
   const closeListeners = new Set<() => void>();
 
-  type EventQueue = {
-    readonly push: (e: CdpEvent) => void;
-    readonly end: () => void;
-    readonly iter: AsyncIterable<CdpEvent>;
-  };
-
-  const makeEventQueue = (): EventQueue => {
-    const buf: CdpEvent[] = [];
-    const waiters: Array<(v: IteratorResult<CdpEvent>) => void> = [];
-    let ended = false;
-    return {
-      push(e) {
-        if (ended) return;
-        const w = waiters.shift();
-        if (w) w({ value: e, done: false });
-        else buf.push(e);
-      },
-      end() {
-        ended = true;
-        // value: undefined as unknown as CdpEvent is the correct iterator-protocol
-        // pattern: when done=true the value field is conventionally undefined but
-        // the TS type still requires CdpEvent.
-        for (const w of waiters.splice(0)) w({ value: undefined as unknown as CdpEvent, done: true });
-      },
-      iter: {
-        [Symbol.asyncIterator]() {
-          return {
-            next: (): Promise<IteratorResult<CdpEvent>> =>
-              new Promise((resolve) => {
-                const next = buf.shift();
-                if (next) resolve({ value: next, done: false });
-                else if (ended) resolve({ value: undefined as unknown as CdpEvent, done: true });
-                else waiters.push(resolve);
-              }),
-          };
-        },
-      },
-    };
-  };
-
   let queue = makeEventQueue();
 
   const handleMessage = (raw: string): void => {
@@ -109,11 +64,7 @@ export const createCdpTransport = (): CdpTransport => {
   };
 
   const cleanup = (reason: string): void => {
-    for (const [, p] of pending) {
-      clearTimeout(p.timer);
-      p.resolve(err(cdpError("transport_closed", reason, p.method)));
-    }
-    pending.clear();
+    rejectAllPending(pending, reason);
     queue.end();
     queue = makeEventQueue();
     for (const cb of closeListeners) cb();
@@ -184,20 +135,7 @@ export const createCdpTransport = (): CdpTransport => {
       const payload: Record<string, unknown> = { id, method, params };
       if (sessionId) payload["sessionId"] = sessionId;
       const json = JSON.stringify(payload);
-      return new Promise((resolve) => {
-        const timer = setTimeout(() => {
-          pending.delete(id);
-          resolve(err(cdpError("timeout", `CDP timeout after ${timeoutMs}ms: ${method}`, method)));
-        }, timeoutMs);
-        pending.set(id, { resolve, timer, method });
-        try {
-          sock.send(json);
-        } catch (e) {
-          clearTimeout(timer);
-          pending.delete(id);
-          resolve(err(cdpError("transport_closed", e instanceof Error ? e.message : String(e), method)));
-        }
-      });
+      return sendWithTimeout(pending, id, method, timeoutMs, "CDP", () => sock.send(json));
     },
     events(): AsyncIterable<CdpEvent> {
       // Single-consumer: each connection's event stream may be iterated by
@@ -213,9 +151,6 @@ export const createCdpTransport = (): CdpTransport => {
       if (ws.readyState === WebSocket.OPEN) return "open";
       return "closed";
     },
-    onClose(cb): () => void {
-      closeListeners.add(cb);
-      return () => closeListeners.delete(cb);
-    },
+    onClose: makeOnClose(closeListeners),
   };
 };

package/src/client.ts

@@ -11,6 +11,7 @@ import type { DaemonStatus, DialogInfo, PageInfo, TabInfo } from "./cdp/types";
 
 export type BrowserClientOptions = {
   readonly namespace: string;
+  readonly transport?: CdpTransport;
   readonly remote?: { readonly cdpUrl: string; readonly browserId: string };
   readonly initialOwnership?: {
     readonly ownedTargetIds?: ReadonlyArray<string>;
@@ -28,6 +29,9 @@ export type BrowserClient = {
   status(): DaemonStatus;
   start(): Promise<Result<void, CdpError>>;
   stop(): Promise<void>;
+  /** Detach from the current page target (removes the "Chrome is being controlled" banner)
+   *  while keeping the transport connection alive. Call on session shutdown. */
+  detach(): Promise<void>;
   evaluateJs(expression: string, sessionId?: string): Promise<Result<unknown, CdpError>>;
   pageInfo(): Promise<Result<PageInfo | { readonly dialog: DialogInfo }, CdpError>>;
   takeDialog(): DialogInfo | null;
@@ -77,7 +81,7 @@ const parsePageInfoPayload = (v: unknown): Result<PageInfo, CdpError> => {
 };
 
 export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient => {
-  const transport = createCdpTransport();
+  const transport = opts.transport ?? createCdpTransport();
   const ownershipInit: { ownedTargetIds?: ReadonlyArray<string>; harnessWindowTargetId?: string } = {};
   if (opts.initialOwnership?.ownedTargetIds !== undefined) {
     ownershipInit.ownedTargetIds = opts.initialOwnership.ownedTargetIds;
@@ -298,9 +302,19 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     ...(remote?.browserId !== undefined ? { remoteBrowserId: remote.browserId } : {}),
   });
 
+  const detach = async (): Promise<void> => {
+    const cur = session.current();
+    if (!cur) return;
+    // Target.detachFromTarget removes the "Chrome is being controlled" banner
+    // and releases the page session. The transport (WebSocket/Unix socket)
+    // stays alive for reuse by the next session.
+    // Reference: https://chromedevtools.github.io/devtools-protocol/tot/Target/#method-detachFromTarget
+    await transport.request("Target.detachFromTarget", { sessionId: cur.sessionId }, { sessionId: null });
+  };
+
   return {
     namespace: opts.namespace,
-    ensureAlive, status, start, stop,
+    ensureAlive, status, start, stop, detach,
     evaluateJs, pageInfo,
     takeDialog: () => session.takeDialog(),
     listTabs, switchTab, newTab, closeTab,