pi-browser-harness 0.4.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/console.ts

@@ -0,0 +1,173 @@
+import { Type } from "typebox";
+import { Markdown, Text } from "@mariozechner/pi-tui";
+import { getMarkdownTheme, keyHint } from "@mariozechner/pi-coding-agent";
+import { type Result, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { applyTruncation } from "../util/truncate";
+import type { ConsoleRecord, ConsoleLevel } from "../cdp/console-buffer";
+
+const ConsoleArgs = Type.Object({
+  levels: Type.Optional(
+    Type.Array(
+      Type.Union(
+        [
+          Type.Literal("log"),
+          Type.Literal("info"),
+          Type.Literal("warn"),
+          Type.Literal("error"),
+          Type.Literal("debug"),
+        ],
+      ),
+      { description: 'Filter to these levels only, e.g. ["error","warn"]. Default: all levels.' },
+    ),
+  ),
+  textPattern: Type.Optional(
+    Type.String({ description: "Substring match by default. Wrap in slashes (e.g. /TypeError/) for regex." }),
+  ),
+  sinceSeq: Type.Optional(
+    Type.Integer({ minimum: 0, description: "Only records with seq strictly greater than this. Use the previous call's nextCursor to see only what's new." }),
+  ),
+  sinceMs: Type.Optional(
+    Type.Integer({ minimum: 0, description: "Only records from the last N ms." }),
+  ),
+  limit: Type.Optional(
+    Type.Integer({ default: 50, minimum: 1, maximum: 500, description: "Max records to return." }),
+  ),
+});
+
+const levelTag = (lvl: ConsoleLevel): string => {
+  switch (lvl) {
+    case "error": return "[error]";
+    case "warn":  return "[warn] ";
+    case "info":  return "[info] ";
+    case "debug": return "[debug]";
+    default:      return "[log]  ";
+  }
+};
+
+const formatLocation = (r: ConsoleRecord): string => {
+  if (r.url === undefined || r.url === "") return "";
+  const short = r.url.length > 60 ? "…" + r.url.slice(-59) : r.url;
+  return r.lineNumber !== undefined ? `${short}:${r.lineNumber}` : short;
+};
+
+const renderConsoleMarkdown = (
+  records: ReadonlyArray<ConsoleRecord>,
+  opts: { total: number; bufferOverflowed: boolean; expanded: boolean; nextCursor: number | undefined },
+): string => {
+  if (records.length === 0) {
+    if (opts.bufferOverflowed) return "_No matching console records. (Buffer overflowed since last drain — some events were dropped.)_";
+    return "_No matching console records captured yet._";
+  }
+
+  const counts = records.reduce<Record<ConsoleLevel, number>>(
+    (acc, r) => { acc[r.level]++; return acc; },
+    { log: 0, info: 0, warn: 0, error: 0, debug: 0 },
+  );
+
+  const summaryParts: string[] = [];
+  if (counts.error > 0) summaryParts.push(`${counts.error} error${counts.error === 1 ? "" : "s"}`);
+  if (counts.warn  > 0) summaryParts.push(`${counts.warn} warning${counts.warn === 1 ? "" : "s"}`);
+  if (counts.info  > 0) summaryParts.push(`${counts.info} info`);
+  if (counts.log   > 0) summaryParts.push(`${counts.log} log${counts.log === 1 ? "" : "s"}`);
+  if (counts.debug > 0) summaryParts.push(`${counts.debug} debug`);
+
+  const headerLines: string[] = [`**${summaryParts.join(" · ")}**`];
+  if (opts.bufferOverflowed) headerLines.push("⚠ buffer overflowed since last drain — older entries dropped");
+  if (opts.total > records.length) headerLines.push(`(${records.length} of ${opts.total} matches shown — increase \`limit\` for more)`);
+
+  const renderRow = (r: ConsoleRecord, compact: boolean): string => {
+    const tag = levelTag(r.level);
+    const loc = formatLocation(r);
+    const maxText = compact ? 80 : 200;
+    const text = r.text.length > maxText ? r.text.slice(0, maxText - 1) + "…" : r.text;
+    const locSuffix = loc !== "" ? `  _at ${loc}_` : "";
+    const main = `\`${tag}\` ${text}${locSuffix}`;
+    if (!compact && r.stackTrace !== undefined) return `${main}\n\`\`\`\n${r.stackTrace}\n\`\`\``;
+    return main;
+  };
+
+  const visible = !opts.expanded && records.length > 5 ? records.slice(-5) : records;
+  const rows = visible.map((r) => renderRow(r, !opts.expanded)).join(opts.expanded ? "\n\n" : "\n");
+
+  const more = !opts.expanded && records.length > 5 ? `\n  … ${records.length - 5} earlier (expand to see all)` : "";
+  const cursor = opts.nextCursor !== undefined ? `\n\n_nextCursor=${opts.nextCursor}_` : "";
+
+  return `${headerLines.join("\n")}\n\n${rows}${more}${cursor}`;
+};
+
+type ConsoleDetails = {
+  total: number;
+  returned: number;
+  bufferOverflowed: boolean;
+  truncated: boolean;
+  fullOutputPath?: string;
+  records: ReadonlyArray<ConsoleRecord>;
+  nextCursor?: number;
+};
+
+export const consoleTool = defineBrowserTool({
+  name: "browser_console",
+  label: "Browser Console",
+  description:
+    "Read JS errors and console messages from the active tab. Diagnostic — use when an action looks broken or silent.",
+  promptSnippet: "Read JS errors / console output on the current tab",
+  promptGuidelines: [
+    "Use after a click, submit, or navigate produced no visible change — errors often explain it.",
+    "Pass `sinceSeq` from the previous call's `nextCursor` to see only new messages after an action.",
+    "Buffer is reset on tab switch (capacity 500 records). bufferOverflowed:true means older entries were dropped.",
+    "Don't use as a default observation tool — prefer browser_snapshot for page structure.",
+  ],
+  parameters: ConsoleArgs,
+
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const session = client.session();
+    const drained = session.drainConsoleBuffer({
+      ...(args.levels !== undefined ? { levels: args.levels } : {}),
+      ...(args.textPattern !== undefined ? { textPattern: args.textPattern } : {}),
+      ...(args.sinceSeq !== undefined ? { sinceSeq: args.sinceSeq } : {}),
+      ...(args.sinceMs !== undefined ? { sinceMs: args.sinceMs } : {}),
+      limit: args.limit ?? 50,
+    });
+
+    const last = drained.records.at(-1);
+    const nextCursor = last?.seq;
+
+    const text = renderConsoleMarkdown(drained.records, {
+      total: drained.total,
+      bufferOverflowed: drained.bufferOverflowed,
+      expanded: true, // full text always returned to the LLM; renderResult handles compact view for humans
+      nextCursor,
+    });
+    const trunc = await applyTruncation(text, "console");
+
+    const details: ConsoleDetails = {
+      total: drained.total,
+      returned: drained.records.length,
+      bufferOverflowed: drained.bufferOverflowed,
+      truncated: trunc.wasTruncated,
+      records: drained.records,
+      ...(nextCursor !== undefined ? { nextCursor } : {}),
+    };
+    if (trunc.fullOutputPath !== undefined) details.fullOutputPath = trunc.fullOutputPath;
+
+    return ok({ text: trunc.text, details });
+  },
+
+  renderResult(result, expanded, theme) {
+    const details = result.details as ConsoleDetails | undefined;
+    if (!details) return new Text(theme.fg("error", "console: no details"), 0, 0);
+
+    const md = renderConsoleMarkdown(details.records, {
+      total: details.total,
+      bufferOverflowed: details.bufferOverflowed,
+      expanded,
+      nextCursor: details.nextCursor,
+    });
+    const tail = expanded
+      ? `\n\n${keyHint("app.tools.expand", "to collapse")}${details.fullOutputPath ? ` · full payload at \`${details.fullOutputPath}\`` : ""}`
+      : `\n\n${keyHint("app.tools.expand", "to expand")}`;
+
+    return new Markdown(md + tail, 0, 0, getMarkdownTheme());
+  },
+});

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();
   });