pi-browser-harness 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to pi-browser-harness will be documented in this file.
 
+## 0.9.0 — 2026-07-24
+
+### Added
+
+- **`browser_web_search`** — new tool. Query → ranked links by scraping a real Google SERP in the user's own Chrome, so no API key or search subscription is involved. Runs in an isolated tab whose lifecycle mirrors `browser_open_urls` (never touches the user's current tab). The SERP parser is pure and fixture-tested (9 scenarios), extracts results semantically (`a h3`) and unwraps redirect URLs. CAPTCHA walls and empty result sets surface as `invalid_state` with `details.reason` rather than an empty list.
+- **`browser_read_page`** — new tool. URL (or an owned `targetId`) → clean main-article text with nav/ad/footer boilerplate stripped, via a dependency-free readability heuristic. The DOM walk runs as an in-page capture expression; scoring and selection are a pure, fixture-tested function (link-density plus boilerplate-ancestor filtering, with a body-text fallback for pages that have no article structure). Registered unserialized, so concurrent reads are safe.
+- **`deep-research` skill and `/deep-research` command.** Fans out to isolated `web-search-researcher` subagents, runs a coverage-driven loop with a hard iteration ceiling, and synthesizes a cited Markdown report. The researcher agent now uses `browser_web_search` + `browser_read_page`; it previously referenced `web_search`/`web_fetch` tools that do not exist in this harness.
+- **Forms domain with a universal field setter.** `browser_fill`, `browser_fill_form`, `browser_select_option`, and `browser_set_checked` now live in `src/domains/forms.ts` behind one setter that auto-detects the element type and fires framework-compatible input events (the React native-setter trick), so controlled inputs register the change instead of silently reverting.
+- **Durable window binding.** Every new-window code path now captures the real Chrome `windowId` and binds it as the session's window identity, so per-session tab ownership survives navigation and tab churn instead of being inferred fresh each time.
+- **Brave support and additional Chrome channels.** `checkChromeRunning()` recognizes Brave (macOS `brave browser`, Linux `brave`/`brave-browser`, Windows `brave.exe`) alongside Chrome/Chromium/Edge, and now excludes `gpu`/`updater` sub-processes that linger after a browser quits. Profile discovery covers Brave Stable/Beta/Nightly/Dev and Chrome Beta/Dev/Canary/Chromium across macOS, Linux, and Windows.
+- **Expand/collapse (Ctrl+O) rendering for `browser_web_search` and `browser_read_page`,** via a shared `renderExpandableText` helper (`src/domains/render.ts`) mirroring `browser_execute_js`. Compact preview by default, full body on expand; the complete text still reaches the model regardless of render state. The `web_search` summary line surfaces engine and result count.
+
+### Fixed
+
+- **Daemon setup now works on Windows.** The Unix-socket daemon introduced in 0.6.0 carried several POSIX-only assumptions that broke setup entirely on Windows: `DAEMON_SOCKET_PATH` is now a named pipe (`\\.\pipe\pi-browser-daemon`) on win32, since a `/tmp` path is not a valid `net` listen/connect target there; `spawnDaemon()` resolves `tsx.cmd`/`npx.cmd` and runs them through a shell with per-token quoting (paths with spaces) and `windowsVerbatimArguments`, because npm's `.cmd` shims fail with EINVAL/ENOENT when spawned directly; `isDaemonRunning()` skips the `fs.access` pre-check and probes the pipe directly, as named pipes are not filesystem entries and `access()` always fails on them; and stale-socket `unlink()` is a no-op on Windows, where pipes self-clean. (#7)
+- **Stale `DevToolsActivePort` files no longer break CDP discovery.** Discovery previously trusted the first readable port file — a browser that has quit leaves its file behind, so when another browser later bound the same port (e.g. 9222), discovery returned a WS URL carrying the dead browser's UUID against the live browser's server and the connection failed. `discoverWsUrl()` now collects all readable candidates, keeps the most recently written file when candidates share a port, skips ports that aren't live via a fast single-shot probe (no 30s `waitForPort` block on stale files), and asks each live browser for its canonical `webSocketDebuggerUrl` via `/json/version`, falling back to the file's WS path when that endpoint is disabled. Well-known ports (9222, plus `BU_CDP_PORTS`) are probed both when no profile file is readable — covering sandboxed harnesses hitting EPERM/EACCES and non-default install locations — and after all discovered candidates prove stale. Ports parsed from a truncated or corrupt file are validated before use, since `net.connect` throws `ERR_SOCKET_BAD_PORT` synchronously for `NaN`/out-of-range values, which previously escaped as an unhandled rejection. (#4)
+- **Footer browser status indicator removed.** The chip set during `session_start` went stale: a successful `/browser-setup` only called `ctx.ui.notify()` and never updated `ctx.ui.setStatus("browser", …)`, so the red "Browser — run /browser-setup" nudge persisted while the browser was in fact connected. Browser control is on-demand and setup already reports its own outcome, so the persistent chip was removed rather than resynced. (#10)
+
+### Changed
+
+- **Setup guidance** now mentions `brave://inspect` / `edge://inspect` and the `--remote-debugging-port` launch flag.
+
+## 0.8.3 — 2026-07-08
+
+### Fixed
+
+- **Stale socket detection no longer blocks daemon spawn after a crash.** `isDaemonRunning()` only checked that the Unix socket file existed; a dead daemon leaves a stale socket behind, so `ensureDaemon()` skipped spawning and `client.start()` failed with "Chrome not connected". It now runs a liveness probe — connect, register, verify the ack, disconnect — and cleans up the stale socket on failure. The bridge's `handleRequest` is also async, polling for a Chrome connection for up to 15s before rejecting.
+
 ## 0.8.1 — 2026-07-05
 
 ### Fixed

package/README.md

@@ -85,6 +85,13 @@ Pass `@(x,y)` from `browser_snapshot` straight to `browser_click`. **No screensh
 | `browser_page_info` | URL, title, viewport, scroll position, or pending dialog. |
 | `browser_http_get` | Direct HTTP GET outside the browser — 10-50× faster for APIs. |
 
+### Research & reading
+
+| Tool | Purpose |
+|------|---------|
+| `browser_web_search` | Search the web — scrapes a Google results page in the real Chrome (no API key), returns ranked `{title, url, snippet, rank}`. **Links only** — follow up with `browser_read_page`. Runs in its own isolated tab. |
+| `browser_read_page` | Reader mode — a `url` (opened + closed in an isolated tab) or an owned `targetId` → clean main-article text with nav/ads/boilerplate stripped. Use over snapshot/execute_js when you want an article's content. |
+
 ### Visual (last resort)
 
 | Tool | Purpose |
@@ -173,16 +180,29 @@ browser_network_requests({
 
 ### Research workflow
 
+Search → read, with each tool running in its own isolated tab (your current tab is never disturbed):
+
 ```
-browser_navigate({ url: "https://google.com/search?q=..." })
-browser_open_urls({ urls: ["url1", "url2", "url3"] })
-browser_list_tabs()
-browser_switch_tab({ targetId: "..." })
-browser_wait_for_load()
-browser_snapshot()
-browser_execute_js({ expression: "document.querySelector('.content').innerText" })
+browser_web_search({ query: "chrome devtools protocol overview", limit: 5 })
+# → ranked {title, url, snippet, rank} — links only
+browser_read_page({ url: "<the best result's url>" })
+# → clean main-article text, boilerplate stripped
 ```
 
+### Deep research
+
+For a question that needs multiple sources synthesized into a cited report, run:
+
+```
+/deep-research <your question>
+```
+
+This triggers the **deep-research skill**: it decomposes the question into sub-questions, fans out
+one isolated `web-search-researcher` subagent per sub-question (each using `browser_web_search` +
+`browser_read_page`), loops for coverage under a hard ceiling, and writes a **cited Markdown report**
+file where every claim carries a source link. The skill also auto-triggers on research-shaped
+requests ("research X and cite sources", "compare X and Y with sources") without the command.
+
 ### Visual verification (only when pixels matter)
 
 ```
@@ -271,6 +291,7 @@ Scripts are written to disk — auditable and re-runnable.
 | `/browser-setup` | Connect pi to Chrome (run once) |
 | `/browser-status` | Show daemon health and current page |
 | `/browser-reload-daemon` | Restart the connection |
+| `/deep-research <q>` | Research a question on the web and write a cited Markdown report |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-browser-harness",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Browser control extension for pi — navigate, click, type, screenshot, and extract data from real Chrome via CDP",
   "keywords": [
     "pi-package",

package/skills/deep-research/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: deep-research
+description: Use when the user asks you to research a topic on the web, do deep research, investigate something across multiple sources, or produce a cited report / literature review from the live web. Decomposes the question, fans out isolated web-search-researcher subagents (one per sub-question) that scrape the real browser, then synthesizes a source-cited Markdown report. Trigger phrases include "research", "deep research", "look this up and cite sources", "investigate", "compare X and Y with sources".
+---
+
+# Deep Research
+
+Turn a research question into a **cited Markdown report** by fanning out to isolated `web-search-researcher` subagents that use the real browser, then synthesizing their distilled findings. Every claim in the final report carries a source link.
+
+This runs on two browser tools — `browser_web_search` (ranked SERP, links only) and `browser_read_page` (URL → clean article text) — used *inside the subagents*, not by you directly. Both tools open their own isolated tabs, so **the fan-out never disturbs the user's tabs or current page.** You do not need `/browser-setup` to have been run by you; if the browser isn't connected the subagents' first tool call will report `not_connected` — relay that and ask the user to run `/browser-setup`.
+
+## Workflow
+
+### 1. Decompose
+
+Break the question into **3–6 focused sub-questions**, each independently answerable from the web. Cover the distinct facets — definitions, current state, competing options, trade-offs, recent changes — not slight rewordings of the same thing. Aim for coverage: if you synthesized perfect answers to all sub-questions, the original question should be fully answered.
+
+State the sub-questions to the user before dispatching (a short numbered list) so the plan is visible.
+
+### 2. Fan out
+
+Dispatch **one `web-search-researcher` subagent per sub-question**, in parallel where the runtime allows. Each subagent runs in isolated context and returns a distilled, source-linked finding (claims + urls) — not raw pages. Give each subagent exactly one sub-question plus any constraints (recency, specific ecosystem, authoritative sources to prefer).
+
+Do not do the searching yourself — that is the subagents' job, and their isolation is what keeps your context clean enough to synthesize well.
+
+### 3. Assess coverage — loop with a hard ceiling
+
+After each round of findings, self-assess: **is every sub-question answered, or did findings surface new gaps worth a follow-up search?**
+
+- If gaps remain and you are under the ceiling, dispatch a second round of researchers targeting only the gaps (rephrased or newly discovered sub-questions).
+- **Hard ceiling:** at most **2 rounds** and **8 researcher subagents total**. When you hit either limit, stop searching, synthesize with what you have, and list the unresolved gaps explicitly in the report. Never loop indefinitely chasing completeness.
+
+Handle subagent-reported tool failures:
+- A subagent reporting a `browser_web_search` `invalid_state` with `reason: "captcha"` means a bot wall. **Surface this to the user immediately** and do not spawn a tight retry loop — ask whether to continue, wait, or narrow scope.
+- `reason: "no_results"` is already handled inside the subagent (one rephrase); if it still comes back empty, treat that sub-question as a gap.
+
+### 4. Synthesize a cited report
+
+Merge the distilled findings into a **Markdown report written to a file** (e.g. `research-<topic-slug>.md` in the working directory — tell the user the path). Structure:
+
+```
+# {The research question}
+
+## Summary
+{A few paragraphs answering the question, synthesized across sources.}
+
+## {Sub-topic / sub-question 1}
+{Findings, in prose. Every claim carries a source link inline: … as shown in [Title](url).}
+
+## {Sub-topic 2}
+...
+
+## Open questions / gaps
+{Anything the ceiling left unresolved, or where sources conflicted.}
+
+## Sources
+{Deduplicated list of every URL cited, with titles.}
+```
+
+Rules for the report:
+- **Every factual claim carries a source link** — inline `[title](url)`. No unsourced assertions.
+- **Attribute conflicts.** Where sources disagree, present both and cite each.
+- **Distinguish synthesis from quotation.** Don't fabricate precision the sources didn't provide.
+- **Be honest about gaps.** The gaps section is mandatory when the ceiling cut off coverage — an incomplete-but-honest report beats a complete-looking-but-padded one.
+
+After writing the file, give the user a short chat summary and the file path — don't paste the whole report into the conversation.

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

@@ -21,6 +21,12 @@ What do you need to know?
   ├─ Network behavior on the current page?
   │     → browser_network_requests
   │
+  ├─ Find pages on the web about a topic?
+  │     → browser_web_search    (ranked SERP — links only; follow up with browser_read_page)
+  │
+  ├─ An article's main content as clean text?
+  │     → browser_read_page     (reader mode — a url or an owned targetId → boilerplate stripped)
+  │
   ├─ JS errors / why did nothing happen after an action?
   │     → browser_console     (DIAGNOSTIC — only when something looks broken)
   │
@@ -30,6 +36,8 @@ What do you need to know?
 
 Pass `@(x,y)` from `browser_snapshot` straight to `browser_click`. No screenshot round-trip.
 
+`browser_web_search` and `browser_read_page` each run in their own isolated tab and never touch the user's current tab. For a multi-source question that needs a synthesized, cited report, use the **deep-research** skill (or `/deep-research <question>`): it fans out isolated `web-search-researcher` subagents over both tools and writes a source-cited Markdown report.
+
 ## Connection Setup
 
 Browser control is **on-demand** — the daemon does NOT start automatically.

package/src/cdp/discovery.ts

@@ -1,7 +1,8 @@
-import { readFile } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { connect as netConnect } from "node:net";
+import { request as httpRequest } from "node:http";
 import { type Result, err, ok } from "../util/result";
 import { type CdpError, cdpError } from "./errors";
 
@@ -11,23 +12,45 @@ const PORT_PROBE_INTERVAL_MS = 1_000;
 const profileDirs = (): ReadonlyArray<string> => {
   const home = homedir();
   return [
+    // macOS — Chrome (all channels), Chromium, Brave, Edge
     join(home, "Library/Application Support/Google/Chrome"),
+    join(home, "Library/Application Support/Google/Chrome Beta"),
+    join(home, "Library/Application Support/Google/Chrome Dev"),
+    join(home, "Library/Application Support/Google/Chrome Canary"),
+    join(home, "Library/Application Support/Chromium"),
+    join(home, "Library/Application Support/BraveSoftware/Brave-Browser"),
+    join(home, "Library/Application Support/BraveSoftware/Brave-Browser-Beta"),
+    join(home, "Library/Application Support/BraveSoftware/Brave-Browser-Nightly"),
+    join(home, "Library/Application Support/BraveSoftware/Brave-Browser-Dev"),
     join(home, "Library/Application Support/Microsoft Edge"),
     join(home, "Library/Application Support/Microsoft Edge Beta"),
     join(home, "Library/Application Support/Microsoft Edge Dev"),
     join(home, "Library/Application Support/Microsoft Edge Canary"),
+    // Linux — Chrome (all channels), Chromium, Brave, Edge
     join(home, ".config/google-chrome"),
+    join(home, ".config/google-chrome-beta"),
+    join(home, ".config/google-chrome-unstable"),
     join(home, ".config/chromium"),
     join(home, ".config/chromium-browser"),
+    join(home, ".config/BraveSoftware/Brave-Browser"),
+    join(home, ".config/BraveSoftware/Brave-Browser-Beta"),
+    join(home, ".config/BraveSoftware/Brave-Browser-Nightly"),
     join(home, ".config/microsoft-edge"),
     join(home, ".config/microsoft-edge-beta"),
     join(home, ".config/microsoft-edge-dev"),
+    // Linux flatpak
     join(home, ".var/app/org.chromium.Chromium/config/chromium"),
     join(home, ".var/app/com.google.Chrome/config/google-chrome"),
     join(home, ".var/app/com.brave.Browser/config/BraveSoftware/Brave-Browser"),
     join(home, ".var/app/com.microsoft.Edge/config/microsoft-edge"),
+    // Windows — Chrome, Chromium, Brave, Edge
     join(home, "AppData/Local/Google/Chrome/User Data"),
+    join(home, "AppData/Local/Google/Chrome Beta/User Data"),
+    join(home, "AppData/Local/Google/Chrome Dev/User Data"),
+    join(home, "AppData/Local/Google/Chrome SxS/User Data"),
     join(home, "AppData/Local/Chromium/User Data"),
+    join(home, "AppData/Local/BraveSoftware/Brave-Browser/User Data"),
+    join(home, "AppData/Local/BraveSoftware/Brave-Browser-Beta/User Data"),
     join(home, "AppData/Local/Microsoft/Edge/User Data"),
     join(home, "AppData/Local/Microsoft/Edge Beta/User Data"),
     join(home, "AppData/Local/Microsoft/Edge Dev/User Data"),
@@ -66,17 +89,94 @@ const waitForPort = async (port: number): Promise<Result<void, CdpError>> => {
   ));
 };
 
+// Fast, single-shot TCP check (no retry loop). Used to skip stale
+// DevToolsActivePort files left behind by a browser that has since quit —
+// unlike waitForPort, this returns immediately instead of blocking ~30s.
+const isPortLive = async (port: number): Promise<boolean> => (await probePort(port)).success;
+
+// Ask the live browser for its canonical webSocketDebuggerUrl via
+// http://127.0.0.1:<port>/json/version. This is authoritative: it avoids
+// trusting a path from a stale DevToolsActivePort file that may belong to a
+// different browser which has since exited (e.g. Chrome's stale file pointing
+// at 9222 while Brave actually owns the port now). Returns null if the endpoint
+// is unreachable, non-200, or doesn't expose a WS URL.
+const queryLiveWsUrl = (port: number, timeoutMs = 1_500): Promise<string | null> =>
+  new Promise<string | null>((resolve) => {
+    const req = httpRequest(
+      { host: "127.0.0.1", port, path: "/json/version", method: "GET", timeout: timeoutMs },
+      (res) => {
+        if (res.statusCode !== 200) {
+          res.resume();
+          resolve(null);
+          return;
+        }
+        const chunks: Buffer[] = [];
+        res.on("data", (c: Buffer) => chunks.push(c));
+        res.on("end", () => {
+          try {
+            const json = JSON.parse(Buffer.concat(chunks).toString("utf8")) as Record<string, unknown>;
+            const ws = json["webSocketDebuggerUrl"];
+            resolve(typeof ws === "string" ? ws : null);
+          } catch {
+            resolve(null);
+          }
+        });
+      },
+    );
+    req.on("timeout", () => { req.destroy(); resolve(null); });
+    req.on("error", () => resolve(null));
+    req.end();
+  });
+
+// Well-known CDP ports to probe when no DevToolsActivePort file is readable
+// (sandboxed harness, restricted filesystem permissions, or an unusual profile
+// location not on the profileDirs list). The default Chromium remote-debugging
+// port is 9222; users can extend via BU_CDP_PORTS="9222,9333".
+const fallbackPorts = (): ReadonlyArray<number> => {
+  const ports = new Set<number>([9222]);
+  const fromEnv = process.env["BU_CDP_PORTS"];
+  if (fromEnv) {
+    for (const tok of fromEnv.split(",")) {
+      const n = Number(tok.trim());
+      if (Number.isInteger(n) && n > 0 && n < 65536) ports.add(n);
+    }
+  }
+  return Array.from(ports);
+};
+
+type Candidate = { readonly port: number; readonly path: string; readonly mtimeMs: number };
+
 export const discoverWsUrl = async (): Promise<Result<string, CdpError>> => {
   const dirs = profileDirs();
+
+  // Phase 1: collect every readable DevToolsActivePort candidate up front,
+  // rather than committing to the first one found. A single browser writes one
+  // such file, but stale files from quit browsers linger, so we must
+  // disambiguate below instead of trusting discovery order.
+  const candidates: Candidate[] = [];
+  const readErrors: string[] = [];
   for (const base of dirs) {
     const portFile = join(base, "DevToolsActivePort");
     let raw: string;
+    let mtimeMs = 0;
     try {
       raw = await readFile(portFile, "utf8");
+      try {
+        mtimeMs = (await stat(portFile)).mtimeMs;
+      } catch {
+        // mtime is only a tiebreaker; a stat failure just leaves it at 0.
+      }
     } catch (e) {
-      // Node fs errors carry .code; see ErrnoException
+      // Node fs errors carry .code; see ErrnoException. ENOENT is normal — the
+      // dir is on our list but the user hasn't installed that browser. EPERM/
+      // EACCES is common under sandboxes; remember it and fall back to network
+      // probing rather than failing the whole discovery.
       const code = (e as NodeJS.ErrnoException).code;
       if (code === "ENOENT" || code === undefined) continue;
+      if (code === "EPERM" || code === "EACCES") {
+        readErrors.push(`${portFile}: ${code}`);
+        continue;
+      }
       return err(cdpError("discovery_failed", `failed to read ${portFile}: ${e instanceof Error ? e.message : String(e)}`));
     }
     const lines = raw.trim().split("\n");
@@ -84,12 +184,74 @@ export const discoverWsUrl = async (): Promise<Result<string, CdpError>> => {
     const port = lines[0]?.trim();
     const path = lines[1]?.trim();
     if (!port || !path) continue;
-    const ready = await waitForPort(Number(port));
-    if (!ready.success) return ready;
-    return ok(`ws://127.0.0.1:${port}${path}`);
+    // Guard against a truncated/corrupt port file (e.g. a non-numeric first
+    // line): an out-of-range port makes net.connect throw ERR_SOCKET_BAD_PORT
+    // synchronously, which would escape discoverWsUrl instead of surfacing as
+    // a Result error. Skip such entries.
+    const portNum = Number(port);
+    if (!Number.isInteger(portNum) || portNum <= 0 || portNum >= 65536) continue;
+    candidates.push({ port: portNum, path, mtimeMs });
   }
-  return err(cdpError(
-    "discovery_failed",
-    `DevToolsActivePort not found in ${dirs.join(", ")} — open chrome://inspect/#remote-debugging in your browser, tick the checkbox, click Allow, then retry. Or set BU_CDP_WS to a remote browser endpoint.`,
-  ));
+
+  // Phase 2: no readable candidate — probe well-known ports directly. Covers
+  // sandboxed harnesses that can't read profile dirs and non-default install
+  // locations. Requires the browser to have been launched with
+  // --remote-debugging-port so /json/version is served.
+  if (candidates.length === 0) {
+    for (const port of fallbackPorts()) {
+      if (!(await isPortLive(port))) continue;
+      const live = await queryLiveWsUrl(port);
+      if (live) return ok(live);
+    }
+    const permHint = readErrors.length > 0
+      ? `\n\nDevToolsActivePort reads were denied (${readErrors.join(", ")}); if you're running in a sandbox, grant read access to those files or set BU_CDP_WS / BU_CDP_PORTS to bypass file discovery.`
+      : "";
+    return err(cdpError(
+      "discovery_failed",
+      `DevToolsActivePort not found in ${dirs.join(", ")} — open chrome://inspect/#remote-debugging (or brave://inspect, edge://inspect) in your browser, tick the checkbox, click Allow, then retry. Or set BU_CDP_WS to a remote browser endpoint.${permHint}`,
+    ));
+  }
+
+  // Phase 3: disambiguate candidates sharing a port (one browser running, and
+  // another's file left behind on the default 9222): keep the most-recently-
+  // written file — that's the currently-running browser.
+  const byPort = new Map<number, Candidate>();
+  for (const c of candidates) {
+    const prev = byPort.get(c.port);
+    if (!prev || c.mtimeMs > prev.mtimeMs) byPort.set(c.port, c);
+  }
+  const unique = Array.from(byPort.values());
+
+  // Prefer candidates whose port is actually accepting connections; this skips
+  // stale files whose browser has quit (avoiding a ~30s waitForPort block).
+  const liveChecks = await Promise.all(unique.map((c) => isPortLive(c.port)));
+  const liveCandidates = unique.filter((_, i) => liveChecks[i]);
+  const ordered = liveCandidates.length > 0 ? liveCandidates : unique;
+
+  // Phase 4: for each candidate, prefer the browser's own canonical WS URL from
+  // /json/version. Some browsers disable that HTTP endpoint when remote
+  // debugging is toggled only via chrome://inspect (rather than a launch flag),
+  // so fall back to the WS path written in DevToolsActivePort.
+  let lastErr: Result<string, CdpError> | null = null;
+  for (const c of ordered) {
+    const ready = await waitForPort(c.port);
+    if (!ready.success) {
+      lastErr = err(ready.error);
+      continue;
+    }
+    const liveUrl = await queryLiveWsUrl(c.port);
+    return ok(liveUrl ?? `ws://127.0.0.1:${c.port}${c.path}`);
+  }
+
+  // Every discovered candidate was stale/unreachable. Before giving up, try the
+  // well-known fallback ports — a user with a leftover DevToolsActivePort file
+  // may still have a live browser reachable via 9222 / BU_CDP_PORTS. (Skip ports
+  // already covered by a candidate above so we don't re-probe them.)
+  for (const port of fallbackPorts()) {
+    if (byPort.has(port) || !(await isPortLive(port))) continue;
+    const liveUrl = await queryLiveWsUrl(port);
+    if (liveUrl) return ok(liveUrl);
+  }
+
+  return lastErr ?? err(cdpError("discovery_failed", "no live DevTools endpoint among discovered candidates"));
 };

package/src/cdp/ownership.ts

@@ -20,14 +20,24 @@ export type OwnershipRegistry = {
   replaceAll(ids: ReadonlyArray<string>): void;
   setHarnessWindow(targetId: string | undefined): void;
   harnessWindow(): string | undefined;
+  /** The real Chrome windowId of the dedicated harness window — the durable
+   *  identity of "the window this session initialized", surviving seed-tab
+   *  closure. Undefined until the window is created (or after teardown). */
+  setHarnessWindowId(windowId: number | undefined): void;
+  harnessWindowId(): number | undefined;
   onChange(cb: () => void): void;
 };
 
 export const createOwnershipRegistry = (
-  initial?: { readonly ownedTargetIds?: ReadonlyArray<string>; readonly harnessWindowTargetId?: string },
+  initial?: {
+    readonly ownedTargetIds?: ReadonlyArray<string>;
+    readonly harnessWindowTargetId?: string;
+    readonly harnessWindowId?: number;
+  },
 ): OwnershipRegistry => {
   const owned = new Set<string>(initial?.ownedTargetIds ?? []);
   let harnessWindow: string | undefined = initial?.harnessWindowTargetId;
+  let harnessWindowId: number | undefined = initial?.harnessWindowId;
   let listener: (() => void) | null = null;
 
   const notify = (): void => {
@@ -65,6 +75,14 @@ export const createOwnershipRegistry = (
     harnessWindow() {
       return harnessWindow;
     },
+    setHarnessWindowId(windowId) {
+      if (harnessWindowId === windowId) return;
+      harnessWindowId = windowId;
+      notify();
+    },
+    harnessWindowId() {
+      return harnessWindowId;
+    },
     onChange(cb) {
       listener = cb;
     },

package/src/cdp/session.ts

@@ -92,6 +92,17 @@ export const createCdpSession = (
         const tab = targetId ? tabs.get(targetId) : undefined;
         if (tab) tab.pageInfoDirty = true;
       }
+      if (ev.method === "Target.targetCreated" && ownership) {
+        // Adopt tabs opened BY a tab we already own (window.open, target=_blank,
+        // popups). Chrome sets openerId to the opener target; if that opener is
+        // owned, the child belongs to this session's window and must be
+        // controllable + cleaned up. Targets the user opens themselves have no
+        // owned opener, so they are never adopted.
+        const info = (ev.params as { targetInfo?: { targetId?: string; type?: string; openerId?: string } } | undefined)?.targetInfo;
+        if (info?.type === "page" && info.targetId && info.openerId && ownership.has(info.openerId)) {
+          ownership.add(info.targetId);
+        }
+      }
       if (ev.method === "Target.targetDestroyed" && ownership) {
         const params = ev.params as { targetId?: string } | undefined;
         if (params?.targetId) {
@@ -179,6 +190,43 @@ export const createCdpSession = (
         if (survivors.length !== ownership.list().length) ownership.replaceAll(survivors);
         const hw = ownership.harnessWindow();
         if (hw && !live.has(hw)) ownership.setHarnessWindow(undefined);
+
+        if (survivors.length === 0) {
+          // No owned tab survived — the harness window is gone (user closed it,
+          // or Chrome restarted and reassigned all ids). The persisted windowId
+          // is now meaningless and could even collide with one of the user's
+          // windows, so drop it. attachFirstPage will mint a fresh window below.
+          ownership.setHarnessWindowId(undefined);
+        } else {
+          // Self-heal ownership from the window itself. We anchor on a tab we
+          // KNOW we own (a survivor) and re-adopt only its live window-mates —
+          // popups/children from last session, tabs reopened in our window.
+          // Ownership is thus DERIVED from the real window, never from the bare
+          // persisted integer (which Chrome may reassign to a user window on
+          // restart — anchoring on a survivor makes that misfire impossible).
+          const anchorId = survivors[0]!;
+          const anchorWin = await transport.request("Browser.getWindowForTarget", { targetId: anchorId }, { sessionId: null });
+          if (anchorWin.success) {
+            const anchorWindowId = (anchorWin.data as { windowId?: number }).windowId;
+            if (typeof anchorWindowId === "number") {
+              ownership.setHarnessWindowId(anchorWindowId); // refresh to the live id
+              const windows = await Promise.all(
+                allPages.map((p) =>
+                  p.targetId === anchorId
+                    ? Promise.resolve(anchorWin)
+                    : transport.request("Browser.getWindowForTarget", { targetId: p.targetId }, { sessionId: null }),
+                ),
+              );
+              allPages.forEach((p, i) => {
+                const r = windows[i];
+                if (r?.success && (r.data as { windowId?: number }).windowId === anchorWindowId) {
+                  ownership.add(p.targetId);
+                }
+              });
+            }
+          }
+          if (!ownership.harnessWindow()) ownership.setHarnessWindow(anchorId);
+        }
       }
       // Prune per-tab state for pages that no longer exist
       const liveTargetIds = new Set(allPages.map((p) => p.targetId));
@@ -208,6 +256,13 @@ export const createCdpSession = (
         if (ownership) {
           ownership.setHarnessWindow(c.targetId);
           ownership.add(c.targetId);
+          // Capture the real Chrome windowId — the durable identity of the
+          // window this session initialized (survives seed-tab closure).
+          const win = await transport.request("Browser.getWindowForTarget", { targetId: c.targetId }, { sessionId: null });
+          if (win.success) {
+            const wid = (win.data as { windowId?: number }).windowId;
+            if (typeof wid === "number") ownership.setHarnessWindowId(wid);
+          }
         }
       }
 

package/src/cdp/window-binding.ts

@@ -0,0 +1,15 @@
+import type { BrowserClient } from "../client";
+
+/**
+ * Capture the real Chrome windowId of a freshly-created harness window and bind
+ * it as the session's durable window identity. Best-effort: a failed CDP call
+ * leaves the previous binding untouched. Call this on every code path that
+ * spawns a NEW dedicated window (newWindow:true), so the windowId never points
+ * at a window that has since been replaced.
+ */
+export const bindHarnessWindowId = async (client: BrowserClient, targetId: string): Promise<void> => {
+  const r = await client.session().callBrowser("Browser.getWindowForTarget", { targetId });
+  if (!r.success) return;
+  const wid = (r.data as { windowId?: number }).windowId;
+  if (typeof wid === "number") client.ownership().setHarnessWindowId(wid);
+};