pi-browser-harness 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 All notable changes to pi-browser-harness will be documented in this file.
 
+## 0.14.0 — 2026-11-01
+
+### Added
+
+- **Browser recipes: journal and save.** Every page-changing browser call is journaled per session, and `browser_save_recipe` saves the agent's last browser task as a YAML recipe with `{{params}}`, after the user confirms it.
+- **Browser recipes: replay.** `browser_run_recipe` and `/browser-recipe NAME key=value` replay a saved recipe with no model calls, finding each element by role and name and checking each step's recorded outcome. Downloads and status/alert toasts are now recorded, so a step can expect them.
+- **Browser recipes: finish and repair.** A failed replay hands the agent the failed step and a snapshot; the agent finishes the task, then `browser_save_recipe` with `repair_step` rewrites the recipe from that step, keeping the previous version. An auth wall stops the replay without typing anything.
+- **Browser recipes: project recipes need approval.** A recipe from the project's `.pi/browser-recipes/` asks for confirmation, listing its URLs, uploads and downloads, before its first run and again whenever its file changes.
+- **Browser recipes: read steps return data.** `browser_http_get` and `browser_read_page` of a URL are kept as recipe steps, and a replay returns what they fetched: in `browser_run_recipe`'s result, and as a session message from `/browser-recipe` that starts no model turn. A read made with request headers or a tab id is left out.
+- **Browser recipes: bot checks.** A replay waits up to 30s while Cloudflare's "Just a moment..." check is showing; if it never clears, the replay stops and the agent asks the user to complete it.
+
+### Fixed
+
+- **`browser_execute_js` with a top-level `return` returns its value.** Any body with a top-level `return` runs inside an async function that is awaited, and scripts run in REPL mode, so a later call may declare the same `const` or `let` again.
+- **`browser_close_tab` is fast and confirms the close.** Closing the current tab no longer waits 10s, and a tab Chrome keeps open (one closed while still loading) is closed again, or reported as still open, instead of being reported closed.
+- **Every element gets a ref.** `browser_snapshot`'s `maxNodes` caps only what is shown, so a ref the agent read from a long page still resolves.
+- **`browser_page_info` reports the new page right after a navigation**, not the cached previous one.
+- **`browser_web_search` resolves Google `/goto` result links**, and treats every Google TLD as Google's own, not a result.
+- **The agent calls `browser_setup` before it has connected** instead of falling back to `curl`: the prompt now says the `browser_*` tools are available and the browser is just not connected yet.
+
+## 0.13.0 — 2026-10-20
+
+### Fixed
+
+- **A killed daemon no longer crashes pi with `read ECONNRESET`.** The daemon's liveness probe, the client transport and the IPC server read the wire protocol through `node:readline`, which re-emits the socket's errors on its own interface with no listener. They now share a small line reader in `src/daemon/lines.ts` that only emits lines.
+- **Waking from sleep no longer stacks up "Allow remote debugging" prompts.** Each dial to Chrome is one prompt, and the daemon abandoned a dial after 10s and started another on the next tool call, so an agent mid-task could open a dozen prompts before anyone was back at the keyboard. A dial now stays open for 5 minutes while callers get a "waiting for the Allow prompt" answer after 10s, every caller joins the dial in flight, and an outright failure starts a doubling cooldown (30s to 5min) during which no automatic dial happens. A dropped connection still re-dials once at the next demand. `/browser-setup` and `/browser-reload-daemon` send `Daemon.reconnect`, which bypasses the cooldown.
+- **Tool failures now reach the model as errors.** `defineBrowserTool` set `isError` on the returned result, but pi only flags a result as an error when `execute` rejects, so every failed browser tool read as a success. Failed handlers now throw with the rendered error text; replayed errors still render in the UI.
+- **The daemon transport no longer exits mid-handshake.** The connect timer was cleared on TCP connect, before the daemon's `registered` reply, and the socket was already unref'd, so a print-mode run could exit before registering. The timer now stays armed until the handshake settles; a daemon that accepts but never registers times out instead of hanging.
+- **Disconnected clients are cleaned up in the daemon.** The idle-timer registration overwrote the bridge's disconnect handler, so router ownership and armed timers leaked per client. The IPC server now keeps a handler list; `deregister` is handled.
+- **`--browser-namespace` works.** The flag was read before it was registered, so it was always undefined.
+- **CDP sessions are reused or detached.** Switching tabs re-attached every time and left the old session alive; destroying the current target left `current()` pointing at it for up to 30s. Sessions are now tracked per target, detached on re-attach, and cleared on `Target.targetDestroyed` / `Inspector.detached`.
+- **Connect timeouts no longer kick every client off the daemon**, overlapping `connect()` calls share one handshake, the detach release reads the session from `params`, and the duplicate-clientId reply is flushed before the socket closes.
+- **Time budgets in `browser_network_requests` and `browser_snapshot` actually bound the work** through a concurrency-limited runner that honours the abort signal.
+- **`browser_handle_dialog` clears the recorded dialog**, so the next `browser_page_info` no longer reports an already-handled dialog.
+- **`browser_press_key` sends virtual key codes for function and modifier keys.**
+- **`browser_open_urls` applies the tab-title marker after the page loads** instead of to the document being replaced.
+- **`browser_print_to_pdf`, screenshots and uploads return `io_error`** on unwritable or unreadable paths instead of throwing.
+- **Element refs are released** (`Runtime.releaseObject`) on every ref path; `browser_read_page` and `browser_open_urls` detach the sessions they attach.
+- sharp "missing" is classified correctly under ESM; `isPathWithin` accepts siblings starting with `..`; `BH_DEBUG_CLICKS=0` disables debug; Linux `chromium-browser` process names are matched after `ps` truncation; discovery probes stale `DevToolsActivePort` candidates concurrently under one deadline.
+
+### Changed
+
+- **Bad arguments return `invalid_args`** instead of `invalid_state`.
+- **`browser_switch_tab` resolves targetId prefixes against owned tabs only**, matching `browser_close_tab`.
+- **`browser_execute_js` details hold a bounded preview**; the full value lives in the text.
+- **CDP calls require params when the method needs them**, and `Input.*`, `Emulation.setDeviceMetricsOverride`, `Page.printToPDF` and `Page.captureScreenshot` have real schemas.
+- **Tool `details` are typed** via a TypeBox schema on the definition and validated on replay.
+- **Page-side JS is TypeScript** under `src/domains/page/*.page.ts`, type-checked against the DOM lib and injected via `fn.toString()`. `src/domains/fill-engine.ts` is removed.
+- The browser prompt's lane lists and the skill file's tool reference are generated from the registry (`npm run gen:skill`).
+
+### Added
+
+- **Other pi extensions can contribute browser tools** through `registerBrowserTools` (see README, Extending).
+- Type-aware ESLint (`npm run lint`) and `npm run check` running typecheck, boundaries, lint and tests. The boundary scanner gained a `raw-js-template` rule.
+- Injection seams on the daemon entry, extension factory, setup and profile binding; tests for every tool in `src/domains` and the previously untested util, profile and daemon modules (365 tests to 1017).
+
 ## 0.12.0 — 2026-10-19
 
 ### Changed

package/README.md

@@ -182,6 +182,8 @@ tabs or navigating the tab to another origin.
 | Tool | Purpose |
 |---|---|
 | `browser_run_script` | Run a temporary script with raw CDP and full Node access. See [Extending](#extending). |
+| `browser_save_recipe` | Save the browser task the agent just finished as a replayable recipe. See [Saved recipes](#saved-recipes). |
+| `browser_run_recipe` | Replay a saved recipe with no model calls, or list recipes when called with no name. |
 | `browser_setup` | Agent-callable setup. Idempotent — how the agent recovers from `not initialized` on its own. |
 
 `browser_snapshot`, `browser_network_requests`, `browser_console`, `browser_execute_js`,
@@ -257,6 +259,49 @@ browser_press_key({ key: "T", modifiers: 10 })   // Ctrl+Shift+T
 
 ---
 
+## Saved recipes
+
+Every page-changing browser call is journaled to `~/.pi/agent/browser-harness/journal/<session>.jsonl`
+(user-only permissions, pruned after 30 days). Password values are never written.
+
+After a multi-step task the agent offers to save it. `browser_save_recipe` turns that task into a YAML
+file under `~/.pi/agent/browser-recipes/<site>/<name>.yaml` (or `.pi/browser-recipes/` in the project
+with `project: true`), replacing the values you name as params with `{{param}}`. You confirm the recipe
+before it is written. Saving over a name bumps `version` and keeps the old file under `.history/`.
+
+Run one yourself with `/browser-recipe vendor-invoices-export month=2026-10` (no model involved), or ask
+the agent ("run the invoices recipe for October"), which calls `browser_run_recipe`. `/browser-recipe`
+with no name lists recipes; names tab-complete. Each step finds its element by role and name, waits up to
+5s for it, and checks that the page changed the way the recorded run did. A status or alert message the
+recorded run saw counts when its first words match, so "Exported 43 rows" satisfies "Exported 42 rows".
+
+When a step fails, the replay stops and hands the agent the step, what it expected and a fresh snapshot.
+The agent finishes your task from that step first, then calls `browser_save_recipe` with `repair_step`,
+which replaces that step onward with what it just did, bumps `version` and keeps the old file. A failed
+`/browser-recipe` goes to the agent the same way. If the page asks you to sign in, the replay stops and the
+agent asks you to sign in; it never types credentials.
+
+A recipe in the project's `.pi/browser-recipes/` comes from whoever wrote the repo, so it needs your
+approval before its first run: you see its file, site, the URLs it opens, the files it uploads and its
+downloads. The approval holds for those exact file bytes (kept in
+`~/.pi/agent/browser-harness/trusted-recipes.json`); if the file changes, you are asked again. Without a UI
+an unapproved project recipe does not run.
+
+Reads are kept too: a `browser_http_get`, or a `browser_read_page` of a URL, becomes a read step, and a
+replay returns what each one fetched (`browser_run_recipe` in its result, `/browser-recipe` as a message in
+the session that starts no model turn). A read made with request headers or a tab id is left out, since
+headers can carry credentials and a tab id means nothing next run. A `browser_execute_js` that changed
+nothing is left out as well, so a replay does not return what it read; read data with `browser_http_get`
+or `browser_read_page` when the recipe should hand it back.
+
+If the site shows Cloudflare's "Just a moment..." check, a replay waits up to 30s for it to clear; if it
+does not, the replay stops and the agent asks you to complete the check in the browser.
+
+A task that typed into a password field, or used a `browser_execute_js` that changed the page or
+`browser_run_script`, cannot be saved.
+
+---
+
 ## Concurrency and isolation
 
 **Parallel reads, serialized writes.** Observation tools run concurrently with each other and with
@@ -303,6 +348,91 @@ Scripts must live under the OS temp dir, the cwd, or `BH_SCRIPT_DIR`, and every
 mandatory timeout (60s default, 600s max). They land on disk first, so they're reviewable and
 re-runnable.
 
+### Contributing tools from another pi extension
+
+Another extension can add its own `browser_*` tools to this harness. Contributed tools share the
+same client, mutation mutex, tab ownership, and lane prompt as the built-ins, so a `serialized` tool
+you add queues behind `browser_click` exactly as `browser_fill` does.
+
+Define the tool with `defineBrowserTool` and hand it to `registerBrowserTools` at your extension's
+load time, before pi emits `session_start`. The harness registers it with pi on the next
+`session_start` alongside the built-ins.
+
+```ts
+// my-extension/src/index.ts
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "typebox";
+import { defineBrowserTool, registerBrowserTools, ok } from "pi-browser-harness/src/index.ts";
+import { evalJs } from "pi-browser-harness/src/domains/cdp-call.ts";
+
+const pageHeightTool = defineBrowserTool({
+  name: "browser_page_height",
+  label: "Browser Page Height",
+  description: "Report the document's full scroll height in CSS pixels.",
+  promptSnippet: "Measure the page's scroll height",
+  promptGuidelines: [],
+  parameters: Type.Object({}),
+  concurrency: "parallel",
+  handler: async (_args, { client }) => {
+    const height = await evalJs(client, "document.documentElement.scrollHeight");
+    if (!height.success) return height;
+    return ok({ text: `Scroll height: ${String(height.data)}px` });
+  },
+});
+
+export default function myExtension(_pi: ExtensionAPI): void {
+  const added = registerBrowserTools([pageHeightTool]);
+  if (!added.success) console.warn(added.error.message);
+}
+```
+
+`registerBrowserTools` returns a `Result`. The whole batch is rejected, and nothing is added, when any
+name is already taken by a built-in, an earlier contribution, or another tool in the same batch. Pick
+`concurrency: "serialized"` for anything that changes page or tab state; `"parallel"` for reads.
+`browserTools()` lists what the harness will register, built-ins plus contributions so far.
+
+A tool that wants a custom result view declares a `details` schema next to `parameters`. The handler
+then returns `details` of that shape, and `renderResult` receives them typed. pi stores details with
+the session and replays them later; the harness validates replayed details against the schema first,
+so a renderer never sees a stale shape from an older session (it falls back to the stored text instead).
+Details must be plain JSON: no `Map`s, and omit a key rather than setting it to `undefined`.
+
+```ts
+import { Text } from "@mariozechner/pi-tui";
+
+const PageHeightDetails = Type.Object({ height: Type.Number(), unit: Type.Literal("px") });
+
+const pageHeightTool = defineBrowserTool({
+  // ...name, label, description, promptSnippet, promptGuidelines, parameters, concurrency as above
+  details: PageHeightDetails,
+  handler: async (_args, { client }) => {
+    const height = await evalJs(client, "document.documentElement.scrollHeight");
+    if (!height.success) return height;
+    const px = typeof height.data === "number" ? height.data : 0;
+    return ok({ text: `Scroll height: ${px}px`, details: { height: px, unit: "px" } });
+  },
+  renderResult: (result, _expanded, theme) =>
+    new Text(theme.fg("muted", `${result.details.height}${result.details.unit}`), 0, 0),
+});
+```
+
+Tools without a `details` schema need nothing extra: they may still attach any JSON object for logs,
+and their `renderResult` (if any) sees it untyped.
+
+### Known limits
+
+Two extension points are documented but not implemented; the escape hatches that exist today are
+listed with each.
+
+- **No per-tab extension slot.** `TabSession` in `src/cdp/session.ts` carries only the harness's own
+  per-tab state (session id, dialog, page-info cache). A contributed tool cannot stash its own state
+  on a tab. Keep per-tab state in your extension keyed by `targetId` from `browser_current_tab` or
+  `browser_list_tabs`, or compute it on demand with `browser_run_script` through `daemon.session(targetId)`.
+- **Hardcoded browser list.** `src/profile/paths.ts` knows the user-data directories of a fixed set
+  of Chromium browsers, so `/browser-profile` cannot discover one that is not on that list. Point the
+  harness at any Chromium profile directory with `CHROME_USER_DATA_DIR`, or skip discovery entirely
+  by attaching to a running browser's DevTools endpoint with `BU_CDP_WS`.
+
 ---
 
 ## Commands, flags, and environment
@@ -313,6 +443,7 @@ re-runnable.
 | `/browser-profile` | Pick which browser profile the agent works in. Remembered across sessions. |
 | `/browser-status` | Connection state, selected profile, and current page. |
 | `/browser-reload-daemon` | Force a client restart. Rarely needed — the transport reconnects on its own. |
+| `/browser-recipe` | Replay a saved recipe: `/browser-recipe NAME key=value`. No name lists recipes. |
 
 | Flag / variable | Effect |
 |---|---|
@@ -393,6 +524,7 @@ path-restricted and timeout-bounded, but that is a blast-radius limit, not a san
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, conventions, and the PR process.
+`npm run check` runs the typecheck, the boundary scan, the type-aware ESLint pass and the test suite in that order; it is the one command a PR must pass.
 Release history lives in [CHANGELOG.md](CHANGELOG.md).
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-browser-harness",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Browser control extension for pi — navigate, click, type, screenshot, and extract data from real Chrome via CDP",
   "keywords": [
     "pi-package",
@@ -49,18 +49,24 @@
     "typebox": "*"
   },
   "devDependencies": {
+    "@eslint/js": "10.0.1",
     "@mariozechner/pi-coding-agent": "*",
     "@mariozechner/pi-tui": "*",
     "@types/ws": "^8.18.1",
+    "eslint": "10.11.0",
     "typebox": "*",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "typescript-eslint": "8.71.0"
   },
   "scripts": {
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
-    "test": "node --conditions=import --import tsx --test \"test/{profile,domains,cdp,daemon,util}/**/*-test.ts\"",
+    "typecheck": "tsc -b tsconfig.page.json && tsc --noEmit && tsc -p tsconfig.test.json",
+    "test": "node --conditions=import --import tsx --test \"test/{profile,domains,cdp,daemon,util,types,recipes}/**/*-test.ts\"",
     "boundaries": "tsx scripts/check-boundaries.ts",
-    "check": "npm run typecheck && npm run boundaries && npm test",
-    "prepublishOnly": "tsc --noEmit"
+    "gen:skill": "node --conditions=import --import tsx scripts/gen-skill.ts",
+    "check": "npm run typecheck && npm run boundaries && npm run lint && npm test",
+    "prepublishOnly": "npm run typecheck",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
   },
   "publishConfig": {
     "access": "public"
@@ -69,7 +75,9 @@
     "sharp": "^0.33.0"
   },
   "dependencies": {
+    "acorn": "^8.19.0",
     "tsx": "^4.22.4",
-    "ws": "^8.20.0"
+    "ws": "^8.20.0",
+    "yaml": "^2.8.3"
   }
 }

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

@@ -41,6 +41,63 @@ Pass `@(x,y)` from `browser_snapshot` straight to `browser_click`. No screenshot
 
 `browser_web_search` and `browser_read_page` each run in their own isolated tab and never touch the user's current tab. Pair them for a research question: search for candidate URLs, then read the promising ones.
 
+## Tool reference
+
+Every tool, its concurrency lane, and a one-line summary. `serialized` tools queue through one
+shared mutation lane; `parallel` tools may run alongside them. The decision tree above says which
+to reach for first; the tool descriptions and parameter schemas carry per-tool detail.
+
+<!-- tools:start -->
+Generated from `src/registry.ts` by `npm run gen:skill`; do not edit by hand.
+
+| Tool | Lane | Summary |
+|---|---|---|
+| `browser_clear_headers` | serialized | Clear extra request headers from the current owned tab |
+| `browser_click` | serialized | Click an element by ref (preferred) or pixel coordinates |
+| `browser_close_tab` | serialized | Close an owned tab |
+| `browser_console` | parallel | Read JS errors / console output on the current tab |
+| `browser_current_tab` | parallel | Get current tab info |
+| `browser_dispatch_key` | serialized | Dispatch a DOM KeyboardEvent on an element by ref (preferred) or selector |
+| `browser_download` | serialized | Configure download directory |
+| `browser_drag_and_drop` | serialized | Drag and drop between two coordinates |
+| `browser_execute_js` | parallel | Execute JS in the page — surgical DOM reads (preferred over screenshot) |
+| `browser_fill` | serialized | Fill a form field by ref (preferred) or selector (works with React/Vue controlled inputs) |
+| `browser_fill_form` | serialized | Fill many form fields at once by ref — React-safe, self-confirming |
+| `browser_focus` | serialized | Focus an element by ref (preferred) or selector |
+| `browser_go_back` | serialized | Go back one page |
+| `browser_go_forward` | serialized | Go forward one page |
+| `browser_handle_dialog` | serialized | Accept or dismiss a JS dialog |
+| `browser_http_get` | parallel | HTTP GET (outside browser; for APIs/static pages) |
+| `browser_list_tabs` | parallel | List browser tabs |
+| `browser_navigate` | serialized | Navigate to a URL |
+| `browser_network_requests` | parallel | Inspect recent network requests on the current page |
+| `browser_new_tab` | serialized | Open a new tab |
+| `browser_open_urls` | serialized | Open multiple URLs in new tabs (parallel) |
+| `browser_page_info` | parallel | Get current page URL, title, viewport, and scroll position |
+| `browser_press_key` | serialized | Press a key (Enter, Tab, Escape, arrows, or any character) |
+| `browser_print_to_pdf` | serialized | Print the current page to PDF |
+| `browser_read_page` | parallel | Read a page's main content as clean text |
+| `browser_reload` | serialized | Reload the page |
+| `browser_run_recipe` | parallel | Replay a saved browser recipe, or list recipes |
+| `browser_run_script` | parallel | Run a temporary script with daemon + Node access (security-bounded) |
+| `browser_save_recipe` | parallel | Save the last browser task as a replayable recipe |
+| `browser_screenshot` | parallel | Capture a screenshot — visual verification only |
+| `browser_scroll` | serialized | Scroll the page (deltaY positive=down, negative=up) |
+| `browser_select_option` | serialized | Select an option in a native <select> by ref (preferred) or selector |
+| `browser_set_checked` | serialized | Set a checkbox/radio checked state by ref |
+| `browser_set_headers` | serialized | Set extra request headers on the current owned tab |
+| `browser_setup` | parallel | Initialize browser connection |
+| `browser_snapshot` | parallel | Get accessibility-tree snapshot with stable element refs (default for page inspection) |
+| `browser_switch_tab` | serialized | Switch tabs |
+| `browser_type` | serialized | Type text into the focused element |
+| `browser_upload_file` | serialized | Upload a file to a file input by ref (preferred) or selector |
+| `browser_viewport_resize` | serialized | Resize the viewport (responsive testing) |
+| `browser_wait` | parallel | Wait N seconds |
+| `browser_wait_for` | parallel | Wait for an element or text to appear (or an element to disappear) |
+| `browser_wait_for_load` | serialized | Wait for the page to finish loading |
+| `browser_web_search` | serialized | Search the web for a query |
+<!-- tools:end -->
+
 ## Connection Setup
 
 Browser control is **on-demand** — the daemon does NOT start automatically.
@@ -76,6 +133,36 @@ it by opening tabs elsewhere — a different profile means different accounts.
 
 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`.
 
+## Saved recipes
+
+`browser_save_recipe` compiles your last browser task into a YAML recipe; `browser_run_recipe` replays one with no model calls. What a recipe keeps:
+
+- **Page actions**: navigate, new_tab, click, fill, select_option, type, press_key, scroll, wait_for, close_tab and the other replayable tools. Each step finds its element by role and name and checks the page changed as it did when recorded.
+- **Reads**: `browser_http_get` and `browser_read_page` with a `url`. A replay returns what each one fetched, so a recipe can hand back data, not only a page. A read with `headers` or a `targetId` is left out.
+- **Left out**: a `browser_execute_js` that changed nothing. A replay does not return what it read, so when the user wants data back, fetch it with `browser_http_get` (an API, a JSON endpoint) or `browser_read_page` before saving.
+- **Refused**: typing into a password field, a `browser_execute_js` that changed the page, `browser_run_script`.
+
+Params replace values you pass: each value must appear, as written, in a step's args or element name (a URL, typed text, a selected label). Its URL forms count too: `{{topic|url}}`, `{{topic|plus}}`, `{{topic|underscore}}`. A value that only appeared in a left-out call cannot be a param.
+
+The file format, for reading a recipe; repair it with `browser_save_recipe` `repair_step`, not by editing it, so the repair is replayed before it is written:
+
+```yaml
+name: npm-downloads
+site: api.npmjs.org
+version: 1
+params:
+  package: { type: string, example: pi-browser-harness }
+steps:
+  - navigate: { url: "https://www.npmjs.com/package/{{package}}" }
+    expect: { url: "https://www.npmjs.com/package/{{package}}" }   # origin and path only
+  - http_get: { url: "https://api.npmjs.org/downloads/range/last-month/{{package}}" }
+  - click: { role: button, name: Export CSV, nth: 0 }              # the element: role+name+nth, or { css: "#export" }
+    expect: { appeared: [{ role: status, name: Exported 42 rows }] }
+recorded: { at: "2026-11-01T15:14:25.918Z", session: 01a197ab }
+```
+
+At a sign-in page or a bot check (Cloudflare's "Just a moment...", waited out for 30s first) the replay stops: ask the user to sign in or complete the check; never do either yourself.
+
 ## Downloads land in the user's context
 
 `browser_download` calls `Browser.setDownloadBehavior` with no `browserContextId`, which Chrome applies to its **default browser context** — the same one the user's own tabs are in. The override redirects the user's manual downloads too, and it lives on the browser connection the daemon keeps open, so it outlives the tab and the pi session. Symptom the user reports: *"I download things in Chrome and nothing appears in Downloads."*
@@ -111,11 +198,11 @@ When a workflow repeats 3+ times or needs Node.js APIs, write a script to disk a
 
 ## Troubleshooting: "Could not start the browser daemon"
 
-`browser_setup` spawns the daemon as `node <tsx cli> <pkg>/src/daemon/index.ts` with `stdio: "ignore"` (tsx is resolved from the package directory upward, so in pi's hoisted install it sits beside the package rather than inside it). A crash before the socket binds is completely silent and all you see is `Could not start the browser daemon. Check /tmp/pi-browser-daemon.sock.`
+`browser_setup` spawns the daemon as `node <tsx cli> <pkg>/src/daemon/main.ts` with `stdio: "ignore"` (tsx is resolved from the package directory upward, so in pi's hoisted install it sits beside the package rather than inside it). A crash before the socket binds is completely silent and all you see is `Could not start the browser daemon. Check /tmp/pi-browser-daemon.sock.`
 
 Run it in the foreground to see the real error (it prints whether it reached Chrome):
 
-    cd <pkg> && node "$(node -p "require.resolve('tsx/cli')")" src/daemon/index.ts
+    cd <pkg> && node "$(node -p "require.resolve('tsx/cli')")" src/daemon/main.ts
 
 Known cause (package 0.11.1): `Error: Cannot find module 'typebox'` at `src/cdp/discovery.ts`. The package declares `typebox` in `peerDependencies` and `devDependencies`, and pi installs packages with dev and peer dependencies omitted, so the tree has no physical copy. It still resolves inside the pi extension host, which maps `typebox` to pi's bundled copy, but not in the spawned daemon process, which resolves modules from the package directory upward. The daemon dies, no socket appears, and every browser tool reports `not_connected`.