@pa1nd/horse-browser 0.4.0

package/bin/horse-browser

@@ -0,0 +1,419 @@
+#!/usr/bin/env bash
+# horse-browser — start the dedicated agent browser, and optionally drive it.
+#
+# Two modes, chosen automatically from stdin:
+#   • bare    `horse-browser`             → ensure the browser is up (+ self-heal), exit.
+#   • driver  `horse-browser <<'PY' … PY` → ensure it's up, then run the script through
+#             browser-harness against it. A drop-in for `browser-harness` that always
+#             pre-flights the browser first. Args forward too, e.g. `horse-browser --doctor`.
+#
+# Driver mode sets BU_CDP_URL itself, so the CDP port is owned entirely by this tool —
+# callers never hardcode it. Change PORT in the config and the whole fleet follows.
+#
+# Subcommands:
+#   horse-browser status   versions (chrome / browser-harness / horse-browser) + state
+#   horse-browser update   fetch the latest Chrome for Testing and restart onto it
+#
+# Idempotent. Config is written by install.sh to ~/.config/horse-browser/config.
+# Env vars override it: HORSE_BROWSER_BIN, HORSE_BROWSER_PORT, HORSE_BROWSER_PROFILE.
+set -euo pipefail
+
+CONFIG="$HOME/.config/horse-browser/config"
+# shellcheck disable=SC1090
+[ -f "$CONFIG" ] && . "$CONFIG"
+
+PORT="${HORSE_BROWSER_PORT:-${PORT:-9223}}"
+PROFILE="${HORSE_BROWSER_PROFILE:-${PROFILE:-$HOME/.config/horse-browser/profile}}"
+BIN="${HORSE_BROWSER_BIN:-${BROWSER_BIN:-}}"
+EXT="${EXTENSION_DIR:-}"
+CACHE="${HORSE_BROWSER_CACHE:-$HOME/.cache/horse-browser}"
+
+# Capture a script ONLY when stdin is a heredoc / file / pipe (a regular file or a
+# FIFO) — those always reach EOF, so the read can't block. A bare invocation's stdin
+# is a tty, /dev/null, or the caller's open socket (none of which is -f/-p), so we
+# never read — and so never hang — when there's no script to run.
+script=""
+if [ -f /dev/fd/0 ] || [ -p /dev/fd/0 ]; then script="$(cat)"; fi
+# Driver mode = a script on stdin OR args to forward to browser-harness.
+PASSTHROUGH=
+if [ -n "$script" ] || [ "$#" -gt 0 ]; then PASSTHROUGH=1; fi
+
+# Pre-flight info goes to stdout in bare mode, but to stderr in driver mode so the
+# script's stdout stays pure browser-harness output.
+say() { if [ -n "$PASSTHROUGH" ]; then echo "$@" >&2; else echo "$@"; fi; }
+
+cdp_up() { curl -sf "http://127.0.0.1:$PORT/json/version" >/dev/null 2>&1; }
+
+# ── self-heal: GPU-process wedge after macOS sleep/wake ──────────────────────
+# After the machine or an external display sleeps, Chrome for Testing's GPU process
+# can get stuck in the frame-present path and never re-acquire its window-server
+# surface on wake. The renderer keeps running — JS, timers, non-render CDP all work —
+# but NOTHING paints: the window is frozen and Page.captureScreenshot hangs forever.
+# Stable Chrome/Brave auto-recover via a Finch seed + GPU watchdog; Chrome for Testing
+# (Null variations seed) does not, so the wedge is permanent until the GPU process is
+# restarted. RECOVERY (proven, non-destructive — no tabs/data lost): kill ONLY this
+# profile's GPU child; Chrome respawns it and the compositor rebuilds. So every
+# `horse-browser` invocation probes paint and heals a frozen browser automatically.
+
+# gpu_healthy [timeout]: 0 = paints fine, 1 = wedged (screenshot hangs), 2 = can't
+# tell. Probes with a 1x1 Page.captureScreenshot — it needs a composited frame, so
+# it hangs exactly when the GPU is wedged — over a dependency-free stdlib websocket.
+gpu_healthy() {
+  python3 - "$PORT" "${1:-5}" <<'PY'
+import sys, os, json, socket, base64, struct, urllib.request
+port, timeout = sys.argv[1], float(sys.argv[2])
+def http_json(p):
+    return json.load(urllib.request.urlopen(f"http://127.0.0.1:{port}{p}", timeout=4))
+def ws_connect(path):
+    s = socket.create_connection(("127.0.0.1", int(port)), timeout=5)
+    key = base64.b64encode(os.urandom(16)).decode()
+    s.sendall((f"GET {path} HTTP/1.1\r\nHost: 127.0.0.1:{port}\r\n"
+               "Upgrade: websocket\r\nConnection: Upgrade\r\n"
+               f"Sec-WebSocket-Key: {key}\r\nSec-WebSocket-Version: 13\r\n\r\n").encode())
+    buf = b""
+    while b"\r\n\r\n" not in buf:
+        c = s.recv(1024)
+        if not c: raise ConnectionError("handshake closed")
+        buf += c
+    if b" 101 " not in buf.split(b"\r\n", 1)[0]: raise ConnectionError("no upgrade")
+    return s
+def ws_send_text(s, payload):
+    d = payload.encode(); n = len(d); m = os.urandom(4); h = bytearray([0x81])
+    if n < 126: h.append(0x80 | n)
+    elif n < 65536: h.append(0x80 | 126); h += struct.pack(">H", n)
+    else: h.append(0x80 | 127); h += struct.pack(">Q", n)
+    h += m; s.sendall(bytes(h) + bytes(b ^ m[i % 4] for i, b in enumerate(d)))
+def ws_recv_frame(s):
+    def rd(n):
+        b = b""
+        while len(b) < n:
+            c = s.recv(n - len(b))
+            if not c: raise ConnectionError("closed")
+            b += c
+        return b
+    ln = rd(2)[1] & 0x7f
+    if ln == 126: ln = struct.unpack(">H", rd(2))[0]
+    elif ln == 127: ln = struct.unpack(">Q", rd(8))[0]
+    return rd(ln)
+try:
+    pages = [t for t in http_json("/json/list")
+             if t.get("type") == "page" and t.get("webSocketDebuggerUrl")]
+    if not pages: sys.exit(2)
+    s = ws_connect("/devtools/" + pages[0]["webSocketDebuggerUrl"].split("/devtools/", 1)[1])
+except Exception:
+    sys.exit(2)
+req = json.dumps({"id": 1, "method": "Page.captureScreenshot",
+                  "params": {"format": "png",
+                             "clip": {"x": 0, "y": 0, "width": 1, "height": 1, "scale": 1}}})
+try:
+    ws_send_text(s, req); s.settimeout(timeout)
+    while True:
+        if json.loads(ws_recv_frame(s)).get("id") == 1: sys.exit(0)  # any reply = GPU alive
+except (socket.timeout, TimeoutError):
+    sys.exit(1)   # no frame within timeout = wedged
+except Exception:
+    sys.exit(2)
+PY
+}
+
+# heal_gpu: restart ONLY this profile's wedged GPU process; Chrome respawns it.
+heal_gpu() {
+  local pids
+  pids=$(ps -ww -o pid,command -ax | grep -- "--type=gpu-process" \
+           | grep -F -- "--user-data-dir=$PROFILE" | grep -v grep | awk '{print $1}') || true
+  if [ -z "$pids" ]; then
+    echo "horse-browser: GPU wedged but no matching GPU process found — quit the browser and re-run." >&2
+    return 1
+  fi
+  echo "horse-browser: GPU wedged after sleep — restarting GPU process ($pids); Chrome will respawn it." >&2
+
+  # One-line record of each heal, so leaving the browser running quietly tracks how
+  # often the wedge actually fires. No polling daemon.
+  HEAL_LOG="${HORSE_BROWSER_HEAL_LOG:-$HOME/.config/horse-browser/heal.log}"
+  mkdir -p "$(dirname "$HEAL_LOG")" 2>/dev/null || true
+  printf '%s\twedge-healed\tgpu_pid=%s\n' \
+    "$(date '+%Y-%m-%dT%H:%M:%S%z')" "${pids//$'\n'/,}" >> "$HEAL_LOG" 2>/dev/null || true
+
+  # shellcheck disable=SC2086
+  kill $pids 2>/dev/null || true
+  for _ in $(seq 1 15); do
+    sleep 1
+    cdp_up || continue
+    if gpu_healthy 6; then echo "horse-browser: GPU recovered on :$PORT" >&2; return 0; fi
+  done
+  echo "horse-browser: GPU did not recover — quit the browser and re-run horse-browser." >&2
+  return 1
+}
+
+# reap_orphan_daemons: stop per-session browser-harness daemons (BU_NAME cc-*) whose
+# anchoring Claude session has exited. Conservative by design: it only touches daemons
+# whose env carries BOTH a cc-* BU_NAME (i.e. one WE named, in driver mode below) and a
+# BH_ANCHOR_PID, and only when that anchor PID is gone — so it never reaps the shared
+# "default" daemon, an explicit BU_NAME lane, or any live session. A browser-harness with
+# the self-reap patch already cleans up its own daemons; this covers a stock one, which
+# otherwise leaks one daemon per ended session. HORSE_BROWSER_REAP_DRYRUN=1 logs only.
+reap_orphan_daemons() {
+  command -v python3 >/dev/null 2>&1 || return 0
+  python3 - <<'PY' || true
+import os, sys, signal, subprocess
+def main():
+    dry = bool(os.environ.get("HORSE_BROWSER_REAP_DRYRUN"))
+    def envof(pid):
+        try:
+            out = subprocess.run(["ps", "eww", "-o", "command=", "-p", str(pid)],
+                                 capture_output=True, text=True, timeout=3).stdout
+        except Exception:
+            return {}
+        e = {}
+        for tok in out.split():
+            if "=" in tok:
+                k, v = tok.split("=", 1)
+                if k.isupper():
+                    e[k] = v
+        return e
+    def alive(pid):
+        try:
+            os.kill(int(pid), 0); return True
+        except Exception:
+            return False
+    try:
+        pids = subprocess.run(["pgrep", "-f", "browser_harness.daemon"],
+                              capture_output=True, text=True, timeout=3).stdout.split()
+    except Exception:
+        return
+    for pid in pids:
+        e = envof(pid)
+        if not e.get("BU_NAME", "").startswith("cc-"):  # only daemons we per-session-named
+            continue
+        anchor = e.get("BH_ANCHOR_PID")
+        if not anchor or alive(anchor):                  # unverifiable or session live -> keep
+            continue
+        if not dry:
+            try: os.kill(int(pid), signal.SIGTERM)
+            except Exception: continue
+        # log on stderr so it's visible but never pollutes a driver script's stdout
+        print(f"horse-browser: {'would reap' if dry else 'reaped'} orphan daemon "
+              f"pid={pid} {e['BU_NAME']} (anchor {anchor} gone)", file=sys.stderr, flush=True)
+try: main()
+except Exception: pass
+PY
+}
+
+# maybe_reap: run reap_orphan_daemons at most once per interval (cheap stamp-file throttle),
+# so it costs nothing on the hot path. HORSE_BROWSER_NO_REAP=1 disables it entirely.
+maybe_reap() {
+  [ -n "${HORSE_BROWSER_NO_REAP:-}" ] && return 0
+  local stamp="${HORSE_BROWSER_REAP_STAMP:-$HOME/.config/horse-browser/.last-reap}"
+  local interval="${HORSE_BROWSER_REAP_INTERVAL:-600}" now last
+  now=$(date +%s); last=$(cat "$stamp" 2>/dev/null || echo 0)
+  [ $(( now - last )) -lt "$interval" ] && return 0
+  mkdir -p "$(dirname "$stamp")" 2>/dev/null || true
+  echo "$now" > "$stamp" 2>/dev/null || true
+  reap_orphan_daemons
+}
+
+# ── status / update ──────────────────────────────────────────────────────────
+_chrome_ver() { echo "${1:-}" | grep -oE '[0-9]+(\.[0-9]+){3}' | head -1; }
+
+hb_status() {
+  local self repo ver running
+  self="$0"; [ -L "$self" ] && self="$(readlink "$self")"
+  repo="$(cd "$(dirname "$self")/.." 2>/dev/null && pwd || true)"
+  ver="$(git -C "$repo" describe --tags 2>/dev/null || true)"
+  # No git checkout (e.g. an `npm i -g` install)? Fall back to package.json's version.
+  if [ -z "$ver" ]; then
+    ver="$(python3 - "$0" <<'PY' 2>/dev/null || true
+import json, os, sys
+root = os.path.dirname(os.path.dirname(os.path.realpath(sys.argv[1])))
+try: print("v" + json.load(open(os.path.join(root, "package.json")))["version"])
+except Exception: pass
+PY
+)"
+  fi
+  ver="${ver:-?}"
+  running="$(curl -s "http://127.0.0.1:$PORT/json/version" 2>/dev/null \
+             | grep -oE '"Browser": *"[^"]*"' | grep -oE '[0-9]+(\.[0-9]+){3}' | head -1)"
+  echo "horse-browser $ver"
+  printf '  %-18s %s\n' "chrome (pinned)"  "$(_chrome_ver "$BIN")"
+  if cdp_up; then printf '  %-18s %s  (live on :%s)\n' "chrome (running)" "${running:-?}" "$PORT"
+  else            printf '  %-18s %s\n'               "chrome (running)" "down"; fi
+  printf '  %-18s %s\n' "browser-harness"  "$(browser-harness --version 2>/dev/null || echo '?')"
+  printf '  %-18s %s\n' "profile"  "$PROFILE"
+  printf '  %-18s %s\n' "config"   "$CONFIG"
+}
+
+hb_update() {
+  command -v npx >/dev/null 2>&1 || { echo "horse-browser: npx (Node) not found — needed to fetch Chrome." >&2; return 1; }
+  local oldver out newbin newver
+  oldver="$(_chrome_ver "$BIN")"
+  echo "horse-browser: resolving the latest Chrome for Testing (chrome@stable)…"
+  out="$(npx -y @puppeteer/browsers install chrome@stable --path "$CACHE")" \
+    || { echo "horse-browser: fetch failed." >&2; return 1; }
+  newbin="$(printf '%s\n' "$out" | grep '^chrome@' | tail -1 | sed 's/^[^ ]* //')"
+  [ -n "$newbin" ] && [ -x "$newbin" ] || { echo "horse-browser: couldn't resolve the new binary." >&2; return 1; }
+  newver="$(_chrome_ver "$newbin")"
+  if [ "$newbin" != "$BIN" ]; then
+    python3 - "$CONFIG" "$newbin" <<'PY'
+import os, sys
+cfg, newbin = sys.argv[1], sys.argv[2]
+lines = open(cfg).read().splitlines() if os.path.exists(cfg) else []
+out, seen = [], False
+for l in lines:
+    if l.startswith("BROWSER_BIN="): out.append(f'BROWSER_BIN="{newbin}"'); seen = True
+    else: out.append(l)
+if not seen: out.append(f'BROWSER_BIN="{newbin}"')
+open(cfg, "w").write("\n".join(out) + "\n")
+PY
+    echo "horse-browser: Chrome ${oldver:-?} → $newver  (updated $CONFIG)"
+  else
+    echo "horse-browser: latest stable is $newver."
+  fi
+  # Apply it: restart onto the latest, unless the browser is already running that version.
+  local running
+  running="$(curl -s "http://127.0.0.1:$PORT/json/version" 2>/dev/null \
+             | grep -oE '"Browser": *"[^"]*"' | grep -oE '[0-9]+(\.[0-9]+){3}' | head -1)"
+  if [ "$running" = "$newver" ]; then echo "horse-browser: already running $newver — nothing to apply."; return 0; fi
+  echo "horse-browser: restarting onto ${newver}…"
+  osascript -e 'quit app "Google Chrome for Testing"' >/dev/null 2>&1 || true
+  for _ in $(seq 1 20); do cdp_up || break; sleep 0.5; done
+  exec "$0"   # bare relaunch → re-sources config (new BIN) → launches $newver
+}
+
+# ensure_browser: bring the browser up (launching if needed) and self-heal a GPU
+# wedge. Returns 0 when CDP is live and painting; non-zero if it can't recover.
+ensure_browser() {
+  if cdp_up; then
+    say "horse-browser: already up on :$PORT"
+    local rc=0
+    gpu_healthy 6 || rc=$?
+    if [ "$rc" = 1 ]; then heal_gpu || return 1; fi   # wedged — restart the GPU process
+    return 0                                          # 0 = paints fine, 2 = no page to probe
+  fi
+
+  if [ -z "$BIN" ] || [ ! -x "$BIN" ]; then
+    echo "horse-browser: no browser configured (BROWSER_BIN missing or not executable)." >&2
+    echo "  Fetch Chrome for Testing with 'horse-browser update', run the repo's ./install.sh," >&2
+    echo "  or point HORSE_BROWSER_BIN at your own Chromium." >&2
+    return 1
+  fi
+
+  # Seed profile defaults that make this feel like a dedicated agent browser: pin the
+  # extension's toolbar button (extensions.pinned_extensions), switch on the vertical
+  # (left) tab strip (vertical_tabs), turn off "save password?" popups (they steal focus
+  # and aren't gated by focus emulation), and skip the confirm dialog when closing/
+  # removing/deleting a tab group (it would block an agent mid-cleanup). All live in the
+  # profile's Preferences, which Chrome owns — so we only touch it here, while the browser
+  # is stopped. The unpacked extension's id is a hash of its absolute path, so we compute
+  # it. Creates Preferences if absent, so a fresh install gets them all. (Pin is re-asserted
+  # each launch; the rest are set-if-absent, so a user who changes them keeps their choice.)
+  if [ -n "$EXT" ] && command -v python3 >/dev/null 2>&1; then
+    python3 - "$PROFILE/Default/Preferences" "$EXT" <<'PY' || true
+import hashlib, json, os, sys
+pref, ext = sys.argv[1], sys.argv[2]
+eid = "".join(chr(ord("a") + int(c, 16)) for c in hashlib.sha256(ext.encode()).hexdigest()[:32])
+os.makedirs(os.path.dirname(pref), exist_ok=True)
+d = {}
+if os.path.exists(pref):
+    try: d = json.load(open(pref))
+    except Exception: d = {}
+tb = d.setdefault("extensions", {}).get("pinned_extensions")
+if not isinstance(tb, list): tb = []
+if eid not in tb: tb.append(eid)
+d["extensions"]["pinned_extensions"] = tb
+# Default a fresh profile to the vertical (left) tab strip — the dedicated "agent
+# browser" feel. Set-if-absent, so a user who turns it off keeps it off.
+if "vertical_tabs" not in d:
+    d["vertical_tabs"] = {"enabled": True, "collapsed_state": False,
+                          "uncollapsed_width": 240, "enabled_first_time": True}
+# Agent-browser defaults (set-if-absent, so a user can re-enable them):
+d.setdefault("credentials_enable_service", False)   # no "save password?" popups
+_tg = d.setdefault("tab_groups", {}).setdefault("deletion", {})
+for _k in ("skip_dialog_on_close_tab", "skip_dialog_on_delete", "skip_dialog_on_remove_tab"):
+    _tg.setdefault(_k, True)                         # no confirm dialog closing a tab group
+json.dump(d, open(pref, "w"))
+PY
+  fi
+
+  # NB: the post-sleep freeze is the GPU-process wedge healed above, NOT occlusion
+  # throttling — the old keep-alive flags (--disable-backgrounding-occluded-windows,
+  # --disable-renderer-backgrounding, --disable-background-timer-throttling,
+  # --disable-features=CalculateNativeWinOcclusion) do NOT prevent it (verified), and
+  # Page.captureScreenshot forces a frame on demand regardless, so they're not set.
+  args=( --remote-debugging-port="$PORT" --user-data-dir="$PROFILE"
+         --test-type             # suppresses the "unsupported command-line flag" infobar
+         --disable-infobars      # hides the Chrome-for-Testing infobar (per Playwright's chromiumSwitches)
+         --remote-allow-origins=* # lets the in-browser Monitor page open the CDP socket (:9223)
+         --no-first-run --no-default-browser-check )
+  [ -n "$EXT" ] && args+=( --load-extension="$EXT" )
+
+  # Launch WITHOUT stealing focus. `open -g` starts the app in the background, so
+  # the window appears but your current app keeps keyboard focus. Falls back to a
+  # direct exec if the binary isn't inside a .app bundle.
+  APP="${BIN%/Contents/MacOS/*}"
+  if [ "$APP" != "$BIN" ] && [ -d "$APP" ]; then
+    open -g -a "$APP" --args "${args[@]}"
+  else
+    "$BIN" "${args[@]}" >/dev/null 2>&1 &
+  fi
+
+  say "horse-browser: launching… (waiting for CDP :$PORT)"
+  for _ in $(seq 1 30); do
+    cdp_up && { say "horse-browser: ready on :$PORT"; return 0; }
+    sleep 1
+  done
+  echo "horse-browser: timed out waiting for CDP :$PORT — check the browser window." >&2
+  return 1
+}
+
+# horse-browser's own subcommands — handled here, never forwarded to browser-harness.
+case "${1:-}" in
+  status) hb_status; exit 0 ;;
+  update) hb_update && exit 0 || exit 1 ;;
+esac
+
+ensure_browser || exit 1
+maybe_reap   # opportunistically clean up daemons from ended sessions (throttled)
+
+# Driver mode: run the captured script (and/or forwarded args) through browser-harness
+# against our browser. exec replaces this process, so browser-harness inherits the
+# here-string as its stdin exactly as if it had been called directly.
+if [ -n "$PASSTHROUGH" ]; then
+  if ! command -v browser-harness >/dev/null 2>&1; then
+    echo "horse-browser: browser-harness not found on PATH — needed to run a script." >&2
+    echo "  Install browser-harness, or run bare 'horse-browser' just to start the browser." >&2
+    exit 1
+  fi
+  export BU_CDP_URL="http://127.0.0.1:$PORT"
+
+  # Per-Claude-session daemon, so concurrent agents never share one daemon and clobber
+  # each other's current tab. browser-harness keys the daemon off BU_NAME; we derive a
+  # per-session one (the same scheme browser-harness uses internally). An explicit
+  # BU_NAME — e.g. a subagent lane — always wins.
+  if [ -z "${BU_NAME:-}" ] && [ -n "${CLAUDE_CODE_SESSION_ID:-}" ]; then
+    export BU_NAME="cc-${CLAUDE_CODE_SESSION_ID##*-}"
+  fi
+  # Anchor that daemon to this Claude session's process: a self-reaping browser-harness
+  # exits with the session, and reap_orphan_daemons can clean it up on a stock one. Walk
+  # up to the nearest `claude` ancestor; if not found, leave it unset (reaper skips it).
+  if [ -z "${BH_ANCHOR_PID:-}" ]; then
+    _ap=$$
+    for _ in $(seq 1 12); do
+      _comm=$(ps -o comm= -p "$_ap" 2>/dev/null) || break
+      case "$_comm" in
+        *claude*) export BH_ANCHOR_PID="$_ap"
+                  export BH_ANCHOR_START="$(ps -o lstart= -p "$_ap" 2>/dev/null)"; break ;;
+      esac
+      _pp=$(ps -o ppid= -p "$_ap" 2>/dev/null | tr -d ' ')
+      if [ -z "$_pp" ] || [ "$_pp" -le 1 ]; then break; fi
+      _ap="$_pp"
+    done
+  fi
+
+  if [ -n "$script" ]; then
+    exec browser-harness "$@" <<<"$script"   # feed the captured heredoc as stdin
+  else
+    exec browser-harness "$@"                # args only (e.g. --doctor) — inherit stdin
+  fi
+fi
+
+exit 0

package/claude-md.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# claude-md.sh — manage horse-browser's entry in your global ~/.claude/CLAUDE.md.
+#
+# Why a script: Claude Code loads CLAUDE.md verbatim, so its @-imports must be LITERAL
+# paths — they can't run a command to resolve anything. But the packaged browser-harness
+# SKILL.md lives under a Python-version-specific dir (…/lib/python3.12/site-packages/…)
+# that moves whenever browser-harness is reinstalled on a different Python. So instead of
+# hardcoding that brittle path, we point CLAUDE.md at a STABLE symlink we keep aimed at the
+# current SKILL, and manage a marked block so updates stay idempotent and checkable.
+#
+# Usage:
+#   ./claude-md.sh print      print the canonical block to stdout (compare / copy by hand)
+#   ./claude-md.sh check      is CLAUDE.md's block + the symlink current? (exit 0=yes, 1=drifted)
+#   ./claude-md.sh apply      (re)point the symlink + write the block into ~/.claude/CLAUDE.md
+#   ./claude-md.sh symlink    only (re)point the stable symlink at the current SKILL
+#
+# Env overrides: CLAUDE_MD, HORSE_BROWSER_BH_SKILL_LINK.
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLAUDE_MD="${CLAUDE_MD:-$HOME/.claude/CLAUDE.md}"
+LINK="${HORSE_BROWSER_BH_SKILL_LINK:-$HOME/.config/horse-browser/browser-harness-skill.md}"
+BEGIN="<!-- horse-browser:begin (managed by claude-md.sh — edits between markers are overwritten) -->"
+END="<!-- horse-browser:end -->"
+
+_tilde() { echo "$1" | sed "s|^$HOME|~|"; }
+
+# Echo the current packaged browser-harness SKILL.md path by ASKING browser-harness itself
+# (its own interpreter, via the CLI shebang) — version- and install-agnostic. Empty if absent.
+resolve_bh_skill() {
+  command -v browser-harness >/dev/null 2>&1 || return 0
+  local py; py="$(head -1 "$(command -v browser-harness)" 2>/dev/null | sed 's/^#!//;s/ .*//')"
+  [ -n "$py" ] && [ -x "$py" ] || return 0
+  "$py" -c 'import browser_harness, os; print(os.path.join(os.path.dirname(browser_harness.__file__), "SKILL.md"))' 2>/dev/null
+}
+
+ensure_symlink() {
+  local target; target="$(resolve_bh_skill)"
+  if [ -z "$target" ] || [ ! -f "$target" ]; then
+    echo "claude-md: couldn't resolve the browser-harness SKILL — is browser-harness installed?" >&2
+    return 1
+  fi
+  mkdir -p "$(dirname "$LINK")"
+  ln -sfn "$target" "$LINK"
+}
+
+# The canonical block. Kept tiny on purpose — it's loaded into every session's context; the
+# @-imports pull the full SKILLs on demand.
+block() {
+  cat <<EOF
+$BEGIN
+# Browsing
+
+A dedicated, persistent CDP browser + tab-grouper extension (per-session colour groups, no
+focus steal). Drive it with \`horse-browser <<'PY' … PY\` — a drop-in for browser-harness;
+open tabs with \`bh_open(url)\`, then navigate, scrape, render, screenshot.
+
+@$(_tilde "$LINK")
+@$(_tilde "$HERE")/SKILL.md
+$END
+EOF
+}
+
+# Extract the current managed block (BEGIN..END inclusive) from CLAUDE.md, or empty.
+_current_block() {
+  [ -f "$CLAUDE_MD" ] || return 0
+  awk -v b="$BEGIN" -v e="$END" '$0==b{f=1} f{print} $0==e{f=0; exit}' "$CLAUDE_MD"
+}
+
+apply() {
+  ensure_symlink
+  mkdir -p "$(dirname "$CLAUDE_MD")"; [ -f "$CLAUDE_MD" ] || : > "$CLAUDE_MD"
+  local tmp; tmp="$(mktemp)"
+  # drop any existing managed block, then trim trailing blank lines
+  awk -v b="$BEGIN" -v e="$END" '$0==b{skip=1} !skip{print} $0==e{skip=0}' "$CLAUDE_MD" \
+    | awk 'NF{last=NR} {buf[NR]=$0} END{for(i=1;i<=last;i++)print buf[i]}' > "$tmp"
+  { [ -s "$tmp" ] && printf '\n'; block; } >> "$tmp"
+  mv "$tmp" "$CLAUDE_MD"
+  echo "claude-md: wrote block + symlink → $CLAUDE_MD"
+}
+
+check() {
+  local rc=0
+  if [ "$(_current_block)" != "$(block)" ]; then
+    echo "claude-md: block in $CLAUDE_MD is DRIFTED (or missing)" >&2; rc=1
+  fi
+  local want have; want="$(resolve_bh_skill)"; have="$(readlink "$LINK" 2>/dev/null || true)"
+  if [ -z "$want" ]; then
+    echo "claude-md: cannot resolve browser-harness SKILL (not installed?)" >&2; rc=1
+  elif [ "$have" != "$want" ]; then
+    echo "claude-md: symlink stale — points at '${have:-<none>}', should be '$want'" >&2; rc=1
+  fi
+  [ "$rc" = 0 ] && echo "claude-md: up to date" || echo "claude-md: run './claude-md.sh apply' to fix" >&2
+  return $rc
+}
+
+case "${1:-print}" in
+  print)   block ;;
+  apply)   apply ;;
+  check)   check ;;
+  symlink) ensure_symlink && echo "claude-md: symlink $(_tilde "$LINK") → $(readlink "$LINK")" ;;
+  *) echo "usage: $(basename "$0") [print|apply|check|symlink]" >&2; exit 2 ;;
+esac

package/extension/background.js

@@ -0,0 +1,139 @@
+// Agent Tab Grouper — CDP-driven.
+//
+// A CDP client attaches to this service worker and calls self.groupTab /
+// self.activateTab / self.listTabs with Runtime.evaluate (awaitPromise: true).
+// chrome.debugger.getTargets() bridges CDP targetIds to chrome.tabs.Tab ids.
+// Nothing here is specific to any one driver — it's a plain tab grouper.
+
+// MV3 service workers sleep when idle and then vanish from Target.getTargets
+// until something wakes them — so a dormant SW would make groupTab/listTabs
+// (and the install smoke test) silently miss us. Two keepalives:
+//   • a 30s no-op alarm resets the idle timer so we stay warm once running;
+//   • waking on tab creation covers the gap before the first alarm tick — a
+//     tab is created right before we're asked to group it, and at launch.
+chrome.runtime.onInstalled.addListener(() => chrome.alarms.create("keepalive", { periodInMinutes: 0.5 }));
+chrome.runtime.onStartup.addListener(() => chrome.alarms.create("keepalive", { periodInMinutes: 0.5 }));
+chrome.alarms.onAlarm.addListener(() => {});
+chrome.tabs.onCreated.addListener(() => {});
+
+const COLORS = ["blue", "cyan", "green", "yellow", "orange", "red", "pink", "purple"];
+
+function colorForName(name) {
+  let h = 0;
+  for (let i = 0; i < name.length; i++) h = (h * 31 + name.charCodeAt(i)) >>> 0;
+  return COLORS[h % COLORS.length];
+}
+
+// ── Session codename ── a stable identity (emoji + colour + last-4) derived from the
+// session id, so any companion tool that renders the same code — a terminal statusline,
+// a dashboard — matches this tab group. 48 emoji grouped 6-per-colour; colour group =
+// slot / 6. The colours are Chrome's 8 tab-group colours (the binding constraint).
+// Hash = FNV-1a + a murmur3 finalizer over the FULL session id; mirror this exact
+// function if you render the codename in another tool, so they stay identical.
+const CODE_EMOJI = ["🔥","🍎","🍓","🍒","🌹","🐞","🦊","🍊","🦁","🐯","🥕","🏀","🍋","🌻","⭐","🐝","🍌","🐥","🐸","🍀","🌵","🐢","🌲","🐍","🐬","🌊","💎","🧊","🐳","💧","🐧","🫐","🦋","🌀","🌐","🐟","🦄","🍇","🔮","🐙","🍆","👾","🌸","🐷","🦩","🍑","🌷","🌺"];
+const CODE_ORDER = ["red", "orange", "yellow", "green", "cyan", "blue", "purple", "pink"];
+
+function hash32(s) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193); }
+  h ^= h >>> 16; h = Math.imul(h, 0x7feb352d); h ^= h >>> 15; h = Math.imul(h, 0x846ca68b); h ^= h >>> 16;
+  return h >>> 0;
+}
+
+// id → { title: "🐍 0FDA", color: "green" }. A bare ≤4-char label (no session id)
+// falls back to the old plain-label group, so nothing breaks if the caller is older.
+function codename(id) {
+  id = id || "";
+  if (id.length <= 4) return { title: id, color: colorForName(id) };
+  const slot = hash32(id) % CODE_EMOJI.length;
+  return { title: CODE_EMOJI[slot] + " " + id.slice(-4).toUpperCase(), color: CODE_ORDER[Math.floor(slot / 6)] };
+}
+
+async function tabIdForTargetId(targetId) {
+  const targets = await chrome.debugger.getTargets();
+  const t = targets.find(x => x.id === targetId);
+  if (!t || !t.tabId) throw new Error(`no tab for CDP target ${targetId}`);
+  return t.tabId;
+}
+
+// `session` is the FULL session id (the caller passes CLAUDE_CODE_SESSION_ID); the
+// codename (emoji + colour + last-4) is derived here so the browser owns its render.
+self.groupTab = async (targetId, session) => {
+  const tabId = await tabIdForTargetId(targetId);
+  const tab = await chrome.tabs.get(tabId);
+  const { title, color } = codename(session);
+  const existing = await chrome.tabGroups.query({ windowId: tab.windowId, title });
+  if (existing.length) {
+    await chrome.tabs.group({ tabIds: [tabId], groupId: existing[0].id });
+  } else {
+    const gid = await chrome.tabs.group({
+      tabIds: [tabId],
+      createProperties: { windowId: tab.windowId },
+    });
+    await chrome.tabGroups.update(gid, { title, color, collapsed: false });
+  }
+  return tabId;
+};
+
+// chrome.tabs.update({active:true}) swaps the browser's visible tab without raising
+// the app — replaces CDP Target.activateTarget, which calls [NSApp activate]
+// and steals macOS focus while the agent works.
+self.activateTab = async (targetId) => {
+  const tabId = await tabIdForTargetId(targetId);
+  await chrome.tabs.update(tabId, { active: true });
+  return tabId;
+};
+
+self.listTabs = async (session) => {
+  const { title } = codename(session);
+  const groups = await chrome.tabGroups.query({ title });
+  if (!groups.length) return [];
+  const groupIds = new Set(groups.map(g => g.id));
+  const tabs = await chrome.tabs.query({});
+  const targets = await chrome.debugger.getTargets();
+  const targetByTabId = new Map(targets.filter(t => t.tabId).map(t => [t.tabId, t.id]));
+  return tabs
+    .filter(t => groupIds.has(t.groupId))
+    .map(t => ({
+      targetId: targetByTabId.get(t.id) ?? null,
+      tabId: t.id,
+      url: t.url,
+      title: t.title,
+      lastAccessed: t.lastAccessed ?? null,
+      discarded: !!t.discarded,
+      audible: !!t.audible,
+      active: !!t.active,
+    }));
+};
+
+// The Agent Monitor — a CCTV grid of every session's live tabs. It's a normal extension
+// page that does its own CDP work as a second client on :9223. We keep exactly one, pinned
+// as the first tab, "permanently": Chrome already shields pinned tabs from "Close other
+// tabs", and showMonitor() reopens it if it's closed any other way. Defined as a const arrow
+// (not a function declaration) right after MONITOR_URL — both bind reliably in the worker.
+const MONITOR_URL = chrome.runtime.getURL("monitor.html");
+const showMonitor = async (focus) => {
+  const tabs = await chrome.tabs.query({ url: MONITOR_URL });
+  if (tabs.length === 0) {
+    await chrome.tabs.create({ url: MONITOR_URL, pinned: true, active: !!focus, index: 0 });
+    return;
+  }
+  if (!tabs[0].pinned) await chrome.tabs.update(tabs[0].id, { pinned: true });
+  if (focus) {
+    await chrome.tabs.update(tabs[0].id, { active: true });
+    await chrome.windows.update(tabs[0].windowId, { focused: true });
+  }
+  // de-dup: keep one Monitor (a closure burst can briefly mint two before either query returns)
+  for (const t of tabs.slice(1)) { try { await chrome.tabs.remove(t.id); } catch (e) {} }
+};
+
+chrome.action.onClicked.addListener(() => showMonitor(true));     // toolbar button → focus it
+chrome.runtime.onStartup.addListener(() => showMonitor(false));   // profile start → ensure pinned
+// Closed any other way (explicit close, etc.) → reopen, unless the window itself is going away.
+// Called directly (no setTimeout): chrome.tabs.* keeps the MV3 worker alive to finish; a timer wouldn't.
+chrome.tabs.onRemoved.addListener((_id, info) => { if (!info.isWindowClosing) showMonitor(false); });
+chrome.runtime.onInstalled.addListener((details) => {
+  showMonitor(false);                                             // install/update → ensure pinned
+  // First run on a fresh profile only: open the welcome page (not on updates/restarts).
+  if (details.reason === "install") chrome.tabs.create({ url: chrome.runtime.getURL("hello.html"), active: true });
+});