@pa1nd/horse-browser 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pa1nd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/pA1nD/pa1nd-media/main/horse-browser/banner-animated.svg" alt="Horse Browser — a dedicated browser for AI agents: colored per-session tab groups and a celestial navigation trail" width="100%" />
+</p>
+<!-- static fallback if the animated SVG ever fails to render:
+<p align="center">
+  <img src="https://raw.githubusercontent.com/pA1nD/pa1nd-media/main/horse-browser/banner.jpg" alt="Horse Browser" width="100%" />
+</p>
+-->
+
+# Horse Browser 🐴
+
+**A browser where your agents live.** Log in once; every agent you point at it inherits the session — and you watch them all on one live wall.
+
+<p align="center">
+  <a href="https://github.com/pA1nD/horse-browser/releases"><img src="https://img.shields.io/github/v/release/pA1nD/horse-browser?color=2f855a&label=release" alt="release" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-2f855a" alt="MIT" /></a>
+  <img src="https://img.shields.io/badge/platform-macOS-2f855a" alt="macOS" />
+</p>
+
+Every other tool hands each agent a *throwaway* browser. But you don't want throwaway — you want **your** browser, logged into your stuff, that agents quietly borrow. The catch: on macOS, every CDP command yanks the browser to the foreground ([a known open sore](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1254) across [the big tools](https://github.com/vercel-labs/agent-browser/issues/1247)). Horse Browser fixes that — agents open tabs **in the background**, each in their own **colored group**, in a **dedicated browser** that coexists with your daily one and never steals your focus.
+
+> Why "horse"? *Browse* meant a horse grazing — nibbling shoots — long before it meant clicking links. A horse that browses is the *original* browser. And it rides in [browser-harness](https://github.com/browser-use/browser-harness): you harness a horse. 🐴
+
+## Setup
+
+**Install (macOS, Node 18+):**
+
+```bash
+npm install -g @pa1nd/horse-browser
+```
+
+That fetches a dedicated **Chrome for Testing** (lives alongside your daily browser, never fights it for the dock), puts the `horse-browser` launcher on your PATH, and wires in the extension. Then start it and **sign into your apps once** — those logins persist for every agent:
+
+```bash
+horse-browser        # launches the dedicated browser, no focus steal
+```
+
+To *drive* it, you also need **browser-harness** (a small Python tool horse-browser wraps) — a one-time prereq:
+
+```bash
+uv tool install browser-harness      # or: pipx install browser-harness
+```
+
+Prefer your own Chromium? `export HORSE_BROWSER_BIN=/path/to/chromium` before installing.
+
+<details>
+<summary>Or hand the repo to your agent (clone + <code>./install.sh</code>)</summary>
+
+You don't have to install by hand. Paste into **Claude Code** or **Codex**:
+
+```text
+Set up https://github.com/pA1nD/horse-browser for me.
+
+Clone it, run ./install.sh, then add SKILL.md to my CLAUDE.md so you always use
+bh_open to open tabs from now on.
+```
+
+`install.sh` does the same setup as the npm install, and additionally wires `SKILL.md` into your `CLAUDE.md` (the npm install prints that import line for you to add — see below).
+</details>
+
+### Teaching agents the discipline
+
+`SKILL.md` isn't an optional skill — it's a guardrail (open tabs with `bh_open`, never bare `goto_url`) that must be in context *before* the first browser call. So you register it by importing it into a `CLAUDE.md`, not as a load-on-demand skill.
+
+**Recommended** — let `claude-md.sh` manage a small, marked block in your global `~/.claude/CLAUDE.md`:
+
+```bash
+./claude-md.sh apply     # write/refresh the block (idempotent)
+./claude-md.sh print     # just print it — to compare, or copy by hand
+./claude-md.sh check     # is CLAUDE.md up to date? (exit 1 if drifted — good for a cron)
+```
+
+It imports both playbooks — horse-browser's, and browser-harness's via a **stable symlink** it keeps aimed at the current install, so the `@`-import never rots when browser-harness is reinstalled on a different Python (`install.sh` refreshes that symlink too).
+
+**By hand** — or just add the import yourself (global `~/.claude/CLAUDE.md`, or a single repo's `CLAUDE.md`):
+
+```text
+@~/path/to/horse-browser/SKILL.md
+```
+
+(Codex users: `~/.codex/AGENTS.md` works the same way.) Either way, the agent loads the `bh_open` discipline automatically from then on.
+
+> **Installed via npm?** `SKILL.md` lives inside the global package — the installer prints the exact `@…/SKILL.md` line to paste, or find it with `echo "$(npm root -g)/@pa1nd/horse-browser/SKILL.md"`.
+
+## How it stays out of your way
+
+Sign into Gmail, GitHub, your dashboards, whatever — **once** — and every agent you point at `:9223` inherits those sessions. No re-auth dance, no cookie juggling, no "paste your token" on every run. The catch with one shared browser is everyone trips over everyone, so three things keep it civil:
+
+- **Coexists with your daily browser.** A *separate* browser (Chrome for Testing) — launching it never hijacks your everyday Chrome/Brave, and clicking yours never lands you in the agents' window.
+- **Focus-safe by construction.** Tabs open in the background and activate through the extension instead of `Target.activateTarget` (which calls `[NSApp activate]` and yanks the browser over whatever you're doing). The page is told it's foregrounded via focus emulation, so nothing misbehaves.
+- **Per-session tab groups.** Each agent's tabs live in their own colored group; you see whose-is-whose at a glance, humans and agents in one window.
+
+(Browserbase, Steel, Hyperbrowser & co. solve scale by giving each agent its *own throwaway* browser. Great for the cloud; useless when you want **one real browser, on your machine, that stays logged in**. That's this.)
+
+## Watch them all — the Agent Monitor
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/pA1nD/pa1nd-media/main/horse-browser/monitor.jpg" alt="The Agent Monitor — a live grid of every agent's tabs" width="100%" />
+</p>
+
+Click the 🐴 toolbar button for a live **2×2 / 3×3 wall** of screencasts — one tab per cell — so you can watch every agent browse at once on a big screen.
+
+Built around **stable slots**: a tab keeps its cell, so the picture never shuffles under you. Activity lights up *in place* (a green pulse on the tab an agent just acted on) instead of reordering everything; the wall only changes membership when a tab has gone idle and a busier one is waiting. A theme-aware sidebar **groups every tab by session** — coloured Chrome-style groups (emoji + code), favicon rows, and a slot number on each on-wall tab so a row maps straight to its preview. Click any pane to jump to that tab. Pure read-only over CDP (a *second* client alongside whatever's driving), so it costs the agents nothing.
+
+## How agents drive it
+
+`horse-browser` is a drop-in for [browser-harness](https://github.com/browser-use/browser-harness) that brings the dedicated browser up first (launching if down, self-healing a frozen GPU after sleep) and points the harness at it — so agents never touch a port:
+
+```bash
+horse-browser <<'PY'
+bh_open("https://example.com")   # own colored tab group, no focus steal
+print(page_info())
+PY
+```
+
+It owns the CDP endpoint, so the port lives in exactly one place (its config) — change it there and every agent follows. Under the hood it's just a dedicated browser speaking CDP, so any other CDP client can still attach the classic way:
+
+```bash
+horse-browser && export BU_CDP_URL=http://127.0.0.1:9223   # for an arbitrary CDP client
+```
+
+Agents open tabs with `bh_open(url)` (their own colored group, no focus steal) rather than bare `goto_url` (which clobbers whoever's focused). The discipline lives in [SKILL.md](SKILL.md) — import it into a `CLAUDE.md` ([see Setup](#teaching-agents-the-discipline)) and agents follow it automatically.
+
+## What's inside
+
+- **`extension/`** — MV3 extension: the tab grouper, the Agent Monitor (sidebar collapsed by default), and a first-run welcome page.
+- **`bin/horse-browser`** — the launcher *and* a browser-harness drop-in: ensures the browser is up (self-heals a GPU wedge after sleep), then runs your script against it. Also `horse-browser status` (versions + state) and `horse-browser update` (fetch the latest Chrome for Testing — it has no auto-updater — and restart onto it).
+- **`install.sh`** — one-time setup; fetches the browser, registers the launcher + helpers.
+- **`claude-md.sh`** — registers horse-browser's guidance in your `~/.claude/CLAUDE.md` (`apply`/`print`/`check`), via a version-proof symlink to the browser-harness SKILL.
+- **`SKILL.md`** — the agent's playbook (the `bh_open` discipline + a helper recipe it self-installs).
+
+A thin, self-contained setup — browser-harness (or anything else speaking CDP) is just a *consumer* on port 9223.
+
+## License
+
+MIT © pa1nd

package/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: horse-browser
+description: A dedicated, persistent CDP browser plus a tab-grouper extension that drops each agent's tabs into its own per-session group and opens them without stealing OS focus. Use whenever you drive a browser via horse-browser (a browser-harness drop-in) — opening tabs, navigating, scraping, rendering, screenshots.
+---
+
+# horse-browser
+
+**Rule:** when this skill is active, open tabs with `bh_open(url)` not `new_tab(url)`. If `bh_open` is undefined in your browser-harness call, install it from the [recipe](#extension) below *before* opening any tab. End-of-task: prune your group with `bh_list()` and `cdp("Target.closeTarget", ...)`.
+
+**Never reach for bare `goto_url`.** It navigates whichever tab is currently focused in the browser — disastrous for other agents (it hijacks their work) and humans (it clobbers the tab they're reading). Open with `bh_open(url)`; re-navigate within your own session-grouped tab via `bh_switch_tab(tid)` first, then `goto_url(url)`. The only legitimate place for bare `goto_url` is *inside* `bh_open` itself.
+
+## Driving the browser
+
+`horse-browser` is a drop-in for `browser-harness` that always brings the dedicated
+browser up first (launching it if down, **self-healing a frozen GPU after sleep**) and
+points the harness at it for you. **Anywhere the browser-harness skill says
+`browser-harness <<'PY'`, use `horse-browser <<'PY'` instead.** One command drives it:
+
+```bash
+horse-browser <<'PY'
+tid = bh_open("https://example.com")   # your own coloured tab group, no focus steal
+wait_for_load()
+print(page_info())
+PY
+```
+
+You never set `BU_CDP_URL` or name a port — **horse-browser owns the CDP endpoint** and
+wires it up internally (change the port once in its config and the whole fleet follows).
+Flags forward too (e.g. `horse-browser --doctor`). To *only* ensure the browser is up
+without running a script, call it bare:
+
+```bash
+horse-browser            # launch if down, heal if wedged, no-op if healthy; then exit
+```
+
+**Never launch a browser yourself** — don't `open` Chrome/Brave, don't spawn your own
+Chromium, and don't run `browser-harness` against some other Chrome. Only `horse-browser`.
+It runs a *dedicated* browser (Chrome for Testing, own profile) that won't collide with
+the user's daily browser; improvising would.
+
+If `horse-browser` isn't on your PATH, the one-time setup hasn't been run — tell the user
+to run the repo's `./install.sh` (fetches the browser, registers the launcher). Don't
+attempt setup yourself.
+
+## Extension
+
+Gives each Claude session its own coloured tab group (label = last 4 chars of `CLAUDE_CODE_SESSION_ID`; subagents inherit it and share the group). Keeps RAM and tab-strip clutter from bleeding across parallel sessions, and lets you reason about "my tabs" as a real set. `chrome.tabGroups` is extension-only — no CDP equivalent — which is why an extension exists at all.
+
+The service worker exposes three async functions on `self`:
+
+```js
+self.groupTab(targetId: string, label: string) -> Promise<number>
+//   Puts the tab into a group titled `label`. Creates the group if missing
+//   (colour deterministic from `label`).
+//   targetId: CDP target id (uppercase hex string, e.g. "3C39F0B4…").
+//   label:    string used as the group title.
+//   Returns:  chrome tab id (number).
+//   Throws:   Error("no tab for CDP target ...") if targetId has no live tab.
+
+self.activateTab(targetId: string) -> Promise<number>
+//   Makes this tab the visible tab in its browser window WITHOUT raising the
+//   browser over your current macOS app. Replaces CDP Target.activateTarget, which
+//   calls [NSApp activate] and steals focus while the agent works. Returns
+//   the chrome tab id.
+
+self.listTabs(label: string) -> Promise<Tab[]>
+//   Returns metadata for every tab whose group title equals `label`.
+//   Returns []  if no group with that title exists.
+//   Tab = {
+//     targetId:     string | null,   // CDP target id; null if no live target
+//     tabId:        number,          // chrome tab id
+//     url:          string,
+//     title:        string,
+//     lastAccessed: number | null,   // ms since epoch; chrome may omit
+//     discarded:    boolean,
+//     audible:      boolean,
+//     active:       boolean,
+//   }
+```
+
+**`bh_open` / `bh_list` / `bh_switch_tab` are pre-installed.** `install.sh` writes them into browser-harness's `agent-workspace/agent_helpers.py` (which auto-loads on every call), so they're available immediately — just call `bh_open(url)`.
+
+If `bh_open` is somehow undefined (a browser-harness checkout that never ran our `install.sh`), re-run `horse-browser`'s `install.sh` to install them — don't hand-roll your own; the focus-safe behaviour is subtle. You pass CDP `targetId`s only — the extension bridges to chrome `tabId`s internally.
+
+### Why this avoids stealing macOS focus
+
+Two ingredients:
+
+1. **`Target.createTarget(background=True)` + `chrome.tabs.update({active:true})` instead of `Target.activateTarget`.** The latter calls `[NSApp activate]` on macOS and pulls the browser over whatever app you're in. `chrome.tabs.update` is documented to "not affect whether the window is focused" — it only changes which tab is visible inside the browser.
+2. **`Emulation.setFocusEmulationEnabled` per attached session.** Makes the renderer treat the page as always focused — `document.hasFocus()` returns true, `requestAnimationFrame` runs at full rate, focus/blur events fire as if user-driven. The OS app focus state is independent of this; the emulation just stops sites and Chromium internals from misbehaving because the tab "looks" backgrounded.
+
+Native popovers (autofill, password save, translate) are *not* gated by focus emulation — they're triggered in the browser process per-form-field. If you see typing-time focus theft, those are the likely culprit; disable them at the profile level rather than chasing them through CDP.
+
+## Tab discipline
+
+Regularly (e.g. before opening many tabs), glance at `bh_list()` and close stale ones via raw CDP. Close the rest when a task ends. Chrome removes empty groups, so a disciplined session leaves zero clutter.

package/agent-helpers.py

@@ -0,0 +1,215 @@
+# horse-browser helpers for browser-harness.
+#
+# install.sh appends these into browser-harness's agent-workspace/agent_helpers.py
+# (which auto-loads on every browser-harness call), so bh_open() is available on
+# the first run — no agent has to install the recipe by hand.
+#
+# What they give you (pass CDP targetIds; the extension bridges to chrome tabIds):
+#   bh_open(url)         open a tab WITHOUT raising the browser over your macOS app,
+#                        drop it into this session's coloured group, return targetId.
+#   bh_switch_tab(tid)   focus-safe tab switch (no Target.activateTarget / NSApp).
+#   bh_list()            tabs in this session's group.
+#
+# Why bh_open instead of new_tab/goto_url: bare goto_url navigates whatever tab is
+# focused — clobbering other agents' and humans' work. bh_open never does that.
+
+import json
+import os
+from browser_harness.helpers import cdp as _real_cdp, _send, goto_url, wait_for_load, current_tab
+
+
+# ── auto-home: group-aware attach, from the helper side ──────────────────────────
+# A stock browser-harness daemon attaches to the FIRST real page in the whole (shared)
+# browser at startup — possibly another session's tab. And if its current tab later goes
+# away (closed) it can fall back onto a neighbour's tab again. So a raw cdp()/page_info()/
+# js()/capture_screenshot() could read, act on, or screenshot another session's page. We
+# can't patch the daemon, but browser-harness MERGES this file into its helpers namespace,
+# so defining cdp() here overrides it — and every helper that routes through cdp (page_info,
+# js, goto_url, new_tab, capture_screenshot, …) goes through ours. We use that to home onto
+# THIS session's own tab whenever the daemon's current tab is foreign — recreating
+# group-aware attach without forking browser-harness.
+_homed = False
+
+
+def cdp(*args, **kwargs):
+    global _homed
+    if not _homed:
+        _homed = True              # set BEFORE homing so re-entrant cdp() is a plain passthrough
+        try: _hb_home()
+        except Exception: pass     # a home failure must never break cdp()
+    return _real_cdp(*args, **kwargs)
+
+
+def _hb_home():
+    # Home the daemon onto one of THIS session's own tabs whenever its current tab is
+    # foreign — a neighbour's tab, or the visible one a stock daemon attached to at startup
+    # / fell back onto. Runs once per CLI process (the _homed gate). It's a NO-OP when we're
+    # already on an own tab, so it never clobbers the agent's own current-tab choice; it only
+    # acts when the current tab isn't ours (which is never a legitimate choice). This is what
+    # stops a raw cdp / page_info / js / capture_screenshot from touching a neighbour's page.
+    if not _session_id():
+        return
+    own = [t for t in bh_list() if t.get("targetId")]
+    own_ids = {t["targetId"] for t in own}
+    try:
+        cur = (current_tab() or {}).get("targetId")
+    except Exception:
+        cur = None
+    if cur and cur in own_ids:
+        return                              # already on one of my own tabs — leave it be
+    if not own:
+        bh_open("about:blank")             # no tab yet → create + home a blank in my group
+        return
+    # Foreign: restore the EXACT tab I last drove (persisted on every bh_switch_tab). agents
+    # drive tabs in the background, so lastAccessed doesn't track which tab is "current" — the
+    # persisted id does. Only if that tab is truly gone do we fall back to the newest own tab.
+    want = _hb_recall()
+    if want and want not in own_ids:
+        import sys
+        print("\U0001F434 horse-browser: the tab you were driving has closed — switched to "
+              "another of your tabs (bh_list() to see them)", file=sys.stderr)
+        want = None
+    if want not in own_ids:
+        want = max(own, key=lambda t: t.get("lastAccessed") or 0)["targetId"]
+    bh_switch_tab(want)
+
+
+def _hb_current_file():
+    return os.path.join(os.path.expanduser("~/.config/horse-browser/current"),
+                        os.environ.get("BU_NAME", "default"))
+
+
+def _hb_remember(target_id):
+    # Persist the tab this session is currently driving, so _hb_home can put us back on the
+    # SAME tab (not a guess) after the daemon drifts onto a foreign tab.
+    try:
+        f = _hb_current_file()
+        os.makedirs(os.path.dirname(f), exist_ok=True)
+        open(f, "w").write(target_id or "")
+    except Exception:
+        pass
+
+
+def _hb_recall():
+    try:
+        return (open(_hb_current_file()).read().strip() or None)
+    except Exception:
+        return None
+
+
+def ext_call(fn, *args):
+    """Call an extension SW function. Returns the deserialised JS value,
+    or None if the extension's service worker isn't registered."""
+    sw = next((t["targetId"] for t in cdp("Target.getTargets")["targetInfos"]
+               if t.get("type") == "service_worker"
+               and t.get("url", "").startswith("chrome-extension://")), None)
+    if sw is None:
+        return None
+    s = cdp("Target.attachToTarget", targetId=sw, flatten=True)["sessionId"]
+    a = ", ".join(json.dumps(x) for x in args)
+    try:
+        return cdp("Runtime.evaluate", session_id=s,
+                   expression=f"self.{fn}({a})",
+                   awaitPromise=True, returnByValue=True)["result"].get("value")
+    finally:
+        cdp("Target.detachFromTarget", sessionId=s)
+
+
+def _label():
+    return os.environ.get("CLAUDE_CODE_SESSION_ID", "")[-4:]
+
+
+def _session_id():
+    # The FULL session id — passed to the extension so the browser derives the tab
+    # group's codename (emoji + colour + last-4) itself. Passing the whole id (not just
+    # the last-4) lets any companion tool that renders the same codename — a terminal
+    # statusline, a dashboard — match this group byte-for-byte.
+    return os.environ.get("CLAUDE_CODE_SESSION_ID", "")
+
+
+def bh_switch_tab(target_id):
+    # Drop-in replacement for helpers.switch_tab that does NOT call
+    # Target.activateTarget (which fires [NSApp activate] on macOS and yanks
+    # the browser over your current app) AND does NOT change the window's visible
+    # tab: focus emulation lets us drive it fully in the background (navigate,
+    # click, screenshot), so concurrent agents never flip each other's view. The
+    # horse-browser monitor surfaces the busiest tabs for follow-along.
+    try: cdp("Runtime.evaluate", expression="if(document.title.startsWith('\U0001F434 '))document.title=document.title.slice(3)")
+    except Exception: pass
+    sid = cdp("Target.attachToTarget", targetId=target_id, flatten=True)["sessionId"]
+    _send({"meta": "set_session", "session_id": sid, "target_id": target_id})
+    _hb_remember(target_id)   # remember the tab I'm now driving, so a drift can restore THIS one
+    cdp("Emulation.setFocusEmulationEnabled", enabled=True)
+    try: cdp("Runtime.evaluate", expression="if(!document.title.startsWith('\U0001F434'))document.title='\U0001F434 '+document.title")
+    except Exception: pass
+    return sid
+
+
+_hb_reported = False  # surface the group's open tabs once per browser-harness process
+
+
+def _tab_report(tabs):
+    # Once per process, tell the agent which tabs its session group has open — on
+    # stderr, so it never pollutes a script's stdout. Always reports the count; when
+    # a lot have gone idle, adds a nudge to close what's no longer needed (agents
+    # accumulate tabs otherwise). Tune via HORSE_BROWSER_TAB_NUDGE (default 5) and
+    # HORSE_BROWSER_TAB_IDLE_MIN (default 10); set TAB_NUDGE to a huge number to mute.
+    global _hb_reported
+    if _hb_reported:
+        return
+    _hb_reported = True
+    try:
+        import time, sys
+        if not tabs:
+            return
+        idle_min = float(os.environ.get("HORSE_BROWSER_TAB_IDLE_MIN", "10"))
+        nudge_at = int(os.environ.get("HORSE_BROWSER_TAB_NUDGE", "5"))
+        now = time.time() * 1000
+        stale = sum(1 for t in tabs
+                    if t.get("lastAccessed") and (now - t["lastAccessed"]) >= idle_min * 60000)
+        line = (f"\U0001F434 horse-browser: {len(tabs)} tab(s) open in your group "
+                f"({stale} idle ≥{int(idle_min)}m)")
+        if stale > nudge_at:
+            line += (" — close what you don't need: "
+                     "cdp('Target.closeTarget', targetId=t['targetId']) per tab (ids via bh_list())")
+        print(line, file=sys.stderr)
+    except Exception:
+        pass
+
+
+def bh_open(url):
+    # Reuse a blank tab already in MY group (e.g. the one the daemon opened on
+    # attach, when this session had no tab yet) instead of leaving it stray; else
+    # mint a fresh background tab. background=True keeps [NSApp activate] from firing.
+    tid = None
+    if _session_id():
+        tabs = bh_list()
+        _tab_report(tabs)   # once per call: surface the group's tabs (+ nudge if hoarding)
+        for t in tabs:
+            if (t.get("url") or "") in ("", "about:blank") and t.get("targetId"):
+                tid = t["targetId"]
+                break
+    created = tid is None
+    if created:
+        tid = cdp("Target.createTarget", url="about:blank", background=True)["targetId"]
+    try:
+        # group BEFORE navigating: an open that fails (or a session killed
+        # mid-navigation) still lands in the session group, so bh_list()-based
+        # cleanup can see it instead of leaking an ungrouped about:blank tab.
+        if _session_id() and created:
+            ext_call("groupTab", tid, _session_id())
+        bh_switch_tab(tid)
+        if url != "about:blank":
+            goto_url(url)
+        wait_for_load()
+    except Exception:
+        # don't leak a tab WE created (never close a reused, pre-existing one)
+        if created:
+            try: cdp("Target.closeTarget", targetId=tid)
+            except Exception: pass
+        raise
+    return tid
+
+
+def bh_list():
+    return ext_call("listTabs", _session_id()) or [] if _session_id() else []