@generativereality/browser-automation 0.4.5 → 0.4.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@generativereality/browser-automation",
3
- "version": "0.4.5",
4
- "description": "Daemonless, per-tab-isolated browser automation CLI for Claude Code. Drives one shared headed Chrome (persistent profile + extensions) over per-target CDP — many parallel sessions, no focus stealing, nothing long-lived to crash.",
3
+ "version": "0.4.7",
4
+ "description": "Daemonless, per-tab-isolated browser automation CLI for Claude Code. Drives one shared headed Chrome (persistent profile + extensions) over per-target CDP \u2014 many parallel sessions, no focus stealing, nothing long-lived to crash.",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "browser-automation": "dist/index.js"
@@ -16,7 +16,7 @@
16
16
  "dev": "bun run ./src/index.ts",
17
17
  "build": "tsdown",
18
18
  "typecheck": "tsc --noEmit",
19
- "check": "npm run typecheck && npm run build",
19
+ "check": "npm run typecheck && bash scripts/check-one-port.sh && npm run build",
20
20
  "release": "bumpp && npm publish",
21
21
  "sync-plugin": "bash scripts/sync-plugin.sh",
22
22
  "prepack": "npm run build"
@@ -0,0 +1,70 @@
1
+ #!/usr/bin/env bash
2
+ #
3
+ # One place decides the CDP port. This fails the build if a second one appears.
4
+ #
5
+ # The formula (base + uid offset) has now been copied out of `cdpPort()` twice:
6
+ # into the launch script within an hour of being written, and into a downstream
7
+ # app the same day. Both copies carried a comment promising to keep them in
8
+ # step, which is the tell rather than the plan — and the second time, the
9
+ # comment outlived the fix that removed the duplication and sat there inviting a
10
+ # third copy in good faith.
11
+ #
12
+ # A comment cannot enforce this. A grep can, and it costs nothing: there is no
13
+ # test runner in this package and this needs none.
14
+ #
15
+ # What is allowed to name the number:
16
+ # - src/core/cdp.ts the definition
17
+ # - src/commands/doctor.ts a historical note about the bug, in a comment
18
+ # Everything else asks: `browser-automation port`, or `--port` from the CLI.
19
+ set -euo pipefail
20
+
21
+ cd "$(dirname "${BASH_SOURCE[0]}")/.."
22
+
23
+ fail=0
24
+
25
+ # The base port, anywhere it could be executed.
26
+ while IFS= read -r hit; do
27
+ echo "✗ $hit" >&2
28
+ fail=1
29
+ done < <(
30
+ grep -rn --include='*.ts' --include='*.sh' -- '9223' src scripts 2>/dev/null \
31
+ | grep -v '^src/core/cdp.ts:' \
32
+ | grep -v '^src/commands/doctor.ts:.*\*' \
33
+ | grep -v '^scripts/check-one-port.sh:' \
34
+ | grep -vE '^[^:]+:[0-9]+:[[:space:]]*(//|#)' || true
35
+ )
36
+
37
+ # Shell ARITHMETIC on the uid — the shape a re-derivation takes when somebody
38
+ # does not want to shell out to node.
39
+ #
40
+ # Deliberately narrow: `$(( … ))` or `expr`, not "a line mentioning id -u".
41
+ # The first version matched `pgrep -u "$(id -u)" -f -- "--remote-debugging-port=…"`
42
+ # — the ownership probe, which uses the port it was GIVEN — and a checker whose
43
+ # first run cries wolf is how the one real finding gets skimmed past.
44
+ while IFS= read -r hit; do
45
+ echo "✗ $hit" >&2
46
+ fail=1
47
+ done < <(
48
+ grep -rnE --include='*.sh' '\$\(\([^)]*id -u|expr[^|]*id -u' scripts 2>/dev/null \
49
+ | grep -v '^scripts/check-one-port.sh:' || true
50
+ )
51
+
52
+ if [ "$fail" -ne 0 ]; then
53
+ cat >&2 <<'MSG'
54
+
55
+ The CDP port is decided in exactly one place: cdpPort() in src/core/cdp.ts.
56
+ Ask for it instead of recomputing it:
57
+
58
+ TypeScript import { cdpPort } from '../core/cdp.js'
59
+ shell browser-automation port
60
+ a subprocess pass --port, as `launch` does
61
+
62
+ Why this is enforced rather than requested: 127.0.0.1 is machine-wide and the
63
+ DevTools protocol has no authentication, so two answers to "which port" means
64
+ one account silently driving another account's browser — which on a real task
65
+ is somebody's signed-in bank session. Found 2026-08-08; not a hypothetical.
66
+ MSG
67
+ exit 1
68
+ fi
69
+
70
+ echo "✓ one place decides the port"
@@ -2,25 +2,89 @@
2
2
  # Launch the canonical long-running headed Chrome that the browser-automation CLI drives via per-target CDP.
3
3
  #
4
4
  # Usage:
5
- # ./scripts/launch-chrome.sh # launch if not already running
6
- # ./scripts/launch-chrome.sh --status # exit 0 if a CDP browser is listening on :9223, else 1
5
+ # ./scripts/launch-chrome.sh # launch if not already running
6
+ # ./scripts/launch-chrome.sh --status # exit 0 if a CDP browser is listening, else 1
7
+ # ./scripts/launch-chrome.sh --port 9224 # explicit port (the CLI always passes this)
8
+ # ./scripts/launch-chrome.sh --restart # quit a running Chrome first, then launch
9
+ #
10
+ # Why --restart exists:
11
+ # A browser process can permanently lose the ability to launch renderers (see
12
+ # src/core/renderer-health.ts for the mechanism). Every existing tab keeps
13
+ # working, so the browser looks fine, but no new tab or cross-origin
14
+ # navigation ever will again. Restarting is the ONLY recovery — and plain
15
+ # `launch` cannot do it, because it is idempotent by design and correctly
16
+ # reports "already running". Without an explicit flag the only way out was to
17
+ # go and kill Chrome by hand, which is how a diagnosis ends up unactionable.
7
18
  #
8
19
  # Why this script exists:
9
20
  # The `browser-automation` skill prefers to drive a real, persistent Chrome
10
21
  # profile (so logins survive reboots) over a Playwright-managed one. The
11
- # convention is: one Chrome listening on --remote-debugging-port=9223 with
12
- # a dedicated user-data-dir. The browser-automation CLI then drives it over per-target CDP. This script is the single source of truth for how
13
- # to start that Chrome.
22
+ # convention is: one Chrome per user listening on --remote-debugging-port with
23
+ # a dedicated user-data-dir. The browser-automation CLI then drives it over
24
+ # per-target CDP. This script is the single source of truth for how to start
25
+ # that Chrome.
26
+ #
27
+ # ONE CHROME PER USER, NOT PER MACHINE:
28
+ # 127.0.0.1 is machine-wide and CDP has no authentication, so a single
29
+ # hardcoded port means the first macOS account to launch owns it and every
30
+ # other account's automation silently drives that account's browser. The port
31
+ # is therefore derived from the uid, by `cdpPort()` in src/core/cdp.ts — the
32
+ # one place that decides it. This script is told, or asks.
14
33
  set -euo pipefail
15
34
 
16
- PORT=9223
35
+ # --- port ------------------------------------------------------------------
36
+ # **Asked for, never recomputed.** `cdpPort()` in src/core/cdp.ts is the only
37
+ # place the port is decided; the CLI passes it here with --port, and a person
38
+ # running this script by hand gets the same number by asking the CLI that ships
39
+ # beside it. A second copy of the formula is a second answer waiting to happen.
40
+ ask_cli_for_port() {
41
+ local dist="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/dist/index.js"
42
+ if [ -f "$dist" ] && command -v node >/dev/null 2>&1; then
43
+ node "$dist" port 2>/dev/null && return 0
44
+ fi
45
+ command -v browser-automation >/dev/null 2>&1 && browser-automation port 2>/dev/null
46
+ }
47
+
48
+ PORT=""
49
+ RESTART=0
50
+ ARGS=()
51
+ while [ $# -gt 0 ]; do
52
+ case "$1" in
53
+ --port) PORT="${2:-}"; shift 2 ;;
54
+ --restart) RESTART=1; shift ;;
55
+ *) ARGS+=("$1"); shift ;;
56
+ esac
57
+ done
58
+ set -- "${ARGS[@]+"${ARGS[@]}"}"
59
+ PORT="${PORT:-$(ask_cli_for_port || true)}"
60
+ if [ -z "${PORT}" ]; then
61
+ echo "Error: could not work out which port to use — pass --port, or set" >&2
62
+ echo " BROWSER_AUTOMATION_PORT. (This script asks the CLI beside it;" >&2
63
+ echo " see cdpPort() in src/core/cdp.ts, the only place it is decided.)" >&2
64
+ exit 1
65
+ fi
66
+
17
67
  PROFILE="${BROWSER_AUTOMATION_PROFILE:-$HOME/Library/Application Support/Google/Chrome/browser-automation}"
18
- LOG="${BROWSER_AUTOMATION_LOG:-/tmp/chrome-9223.log}"
68
+ # Under the caller's OWN temp dir: /tmp is shared and sticky, so with a
69
+ # machine-global name the second user cannot write the first user's log.
70
+ LOG="${BROWSER_AUTOMATION_LOG:-${TMPDIR:-/tmp}/chrome-${PORT}.log}"
19
71
 
20
72
  is_up() {
21
73
  curl -fs -o /dev/null "http://localhost:${PORT}/json/version"
22
74
  }
23
75
 
76
+ # Is the browser answering on this port OURS?
77
+ #
78
+ # Note the question is "is it mine", not "whose is it". `lsof` tells a
79
+ # non-root user NOTHING about another user's socket — it prints an empty
80
+ # result and exits 0, which reads exactly like a free port. Measured
81
+ # 2026-08-08: as the second account, `lsof -iTCP:9223 -sTCP:LISTEN` returned
82
+ # nothing while the first account's Chrome was plainly listening. You can
83
+ # always see your OWN processes, so ask that instead.
84
+ port_is_ours() {
85
+ pgrep -u "$(id -u)" -f -- "--remote-debugging-port=${PORT}" >/dev/null 2>&1
86
+ }
87
+
24
88
  if [ "${1:-}" = "--status" ]; then
25
89
  if is_up; then
26
90
  echo "Chrome CDP on :${PORT} is up"
@@ -30,9 +94,50 @@ if [ "${1:-}" = "--status" ]; then
30
94
  exit 1
31
95
  fi
32
96
 
97
+ # Something is answering on our port and it is not ours. Refuse loudly rather
98
+ # than drive it: "already running" here used to mean "another macOS account's
99
+ # browser, and you will never be told".
100
+ if is_up && ! port_is_ours; then
101
+ echo "Error: something else on this Mac is already serving CDP on port ${PORT}," >&2
102
+ echo " and it is not a Chrome this account started. Driving it would act in" >&2
103
+ echo " ANOTHER user's browser — quit Chrome in that account, or set" >&2
104
+ echo " BROWSER_AUTOMATION_PORT to a free port for this one." >&2
105
+ exit 1
106
+ fi
107
+
108
+ # Restart: quit the Chrome we own, wait for the port to go quiet, fall through
109
+ # to the normal launch. Deliberately SIGTERM, not SIGKILL — Chrome flushes its
110
+ # profile (cookies, extension state, session) on a clean quit, and that profile
111
+ # is the whole reason this browser is long-lived. Only escalate if it will not
112
+ # go, and say so when it happens.
113
+ if [ "$RESTART" = "1" ] && is_up; then
114
+ if ! port_is_ours; then
115
+ echo "Error: refusing to restart a Chrome this account did not start." >&2
116
+ exit 1
117
+ fi
118
+ TABS="$(curl -fs "http://localhost:${PORT}/json/list" 2>/dev/null | grep -c '"type": "page"' || true)"
119
+ echo "Restarting Chrome on :${PORT} — closing ${TABS:-?} open tab(s)."
120
+ pkill -u "$(id -u)" -f -- "--remote-debugging-port=${PORT}" 2>/dev/null || true
121
+ for _ in $(seq 1 40); do
122
+ is_up || break
123
+ sleep 0.25
124
+ done
125
+ if is_up; then
126
+ echo "Chrome did not quit on SIGTERM after 10s; sending SIGKILL." >&2
127
+ pkill -9 -u "$(id -u)" -f -- "--remote-debugging-port=${PORT}" 2>/dev/null || true
128
+ sleep 2
129
+ fi
130
+ # Chrome unregisters its bootstrap names and releases the port on the way out;
131
+ # relaunching before that finishes produces a second browser that cannot serve
132
+ # CDP. A short settle beats a confusing race.
133
+ sleep 1
134
+ fi
135
+
33
136
  if is_up; then
34
137
  echo "Already running on :${PORT} — nothing to do."
35
138
  echo "Drive it with: browser-automation goto -s <session> <url>"
139
+ echo "(To force a fresh browser process — the only fix for a Chrome that can no"
140
+ echo " longer launch renderers — use: browser-automation launch --restart)"
36
141
  exit 0
37
142
  fi
38
143
 
@@ -57,6 +162,16 @@ fi
57
162
 
58
163
  mkdir -p "$(dirname "$PROFILE")"
59
164
 
165
+ # Keep one generation of the previous log. Chrome's stdout is the only place
166
+ # the reason for a renderer failure is ever written, and truncating it on
167
+ # relaunch destroys the evidence at exactly the moment somebody restarted
168
+ # BECAUSE of that failure. (Done during this fix, to this author's own
169
+ # evidence.) One generation, not a rotation scheme: the interesting log is
170
+ # always the one from the browser that just misbehaved.
171
+ if [ -s "$LOG" ]; then
172
+ mv -f "$LOG" "${LOG}.prev" 2>/dev/null || true
173
+ fi
174
+
60
175
  nohup "$CHROME" \
61
176
  --remote-debugging-port="$PORT" \
62
177
  --user-data-dir="$PROFILE" \
@@ -14,7 +14,8 @@ file under `~/.browser-automation/sessions/`.
14
14
 
15
15
  ## The model — read this first
16
16
 
17
- - **One shared headed Chrome** on `--remote-debugging-port=9223` with a
17
+ - **One shared headed Chrome per USER** on a uid-derived
18
+ `--remote-debugging-port` (`9223` for the first account on the machine) with a
18
19
  persistent profile (`browser-automation`). Cookies, logins, and **browser
19
20
  extensions (password managers, etc.) all persist** across runs and across
20
21
  Claude Code restarts. The user can watch and complete interactive auth in the
@@ -55,7 +56,7 @@ file under `~/.browser-automation/sessions/`.
55
56
 
56
57
  ```bash
57
58
  npm install -g @generativereality/browser-automation
58
- browser-automation launch # start the canonical Chrome on :9223 (idempotent)
59
+ browser-automation launch # start this user's Chrome (idempotent)
59
60
  browser-automation doctor # verify Node, Chrome, targets, sessions
60
61
  ```
61
62
 
@@ -71,7 +72,7 @@ Page commands take a tab selector — `-s <session>` (default `$BAC_SESSION`, el
71
72
  | Need | Command |
72
73
  |---|---|
73
74
  | Start/refresh the Chrome | `browser-automation launch` |
74
- | Diagnose setup | `browser-automation doctor` |
75
+ | Diagnose setup (incl. renderer capacity) | `browser-automation doctor` |
75
76
  | List sessions + every open tab (id, title, url) | `browser-automation list` |
76
77
  | Open a background tab | `browser-automation new -s work [url]` |
77
78
  | Navigate (session tab created if needed) | `browser-automation goto -s work https://example.com` |
@@ -85,8 +86,11 @@ Page commands take a tab selector — `-s <session>` (default `$BAC_SESSION`, el
85
86
  | Download a file / CSV export | `browser-automation download -m bank --click e42` (or `--url <href>`) |
86
87
  | Set files on a known `<input type=file>` | `browser-automation setfiles -m app e7 ~/Desktop/clip.mp4` |
87
88
  | Upload via a button that opens a file chooser | `browser-automation upload -m app --click e9 ~/Desktop/clip.mp4` |
89
+ | Drop file(s) onto a drag-and-drop zone | `browser-automation drop -m app e7 ~/Desktop/clip.mp4` (add `--js` for a synthetic drop) |
88
90
  | Inspect network (find the API, headers, bodies) | `browser-automation network -m bank --reload --filter api --headers --body` |
89
91
  | Screenshot a tab | `browser-automation screenshot -m op.fi --full -o shot.png` |
92
+ | Prune stale session bookmarks + dead tabs | `browser-automation gc --dry` (then without `--dry`) |
93
+ | Restart Chrome (only fix for the renderer wedge — closes ALL tabs) | `browser-automation launch --restart` |
90
94
  | Forget a session (tab stays open) | `browser-automation close -s work` |
91
95
  | Forget **and** close the browser tab | `browser-automation close -s work --tab` |
92
96
 
@@ -186,7 +190,7 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
186
190
  whose JS handler builds a client-side **blob** and clicks it via a *nested*
187
191
  synthetic click won't fire (Chrome activation quirk) — for those, grab the
188
192
  underlying export URL/endpoint and use `--url`, or the site's API.
189
- - **File upload.** Two paths, mirroring Playwright. For a static, snapshot-able
193
+ - **File upload.** Three paths. The first two mirror Playwright. For a static, snapshot-able
190
194
  `<input type=file>`, use `setfiles <ref> <path…>` — it resolves the ref and
191
195
  calls `DOM.setFileInputFiles` (a file input's `.files` is read-only to page JS,
192
196
  so a value-setter/`eval` can't populate it; CDP can, and fires trusted
@@ -207,11 +211,113 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
207
211
  successful run **adds another attachment** — retrying a "did it work?" upload a
208
212
  few times silently produces duplicates (this cost us a dozen copies on a live ASC
209
213
  reply). Upload once, verify, and only re-run if verification shows nothing staged.
214
+ The **third path is drag-and-drop**, for zones with NO `<input type=file>` at
215
+ all — a `drop` listener reading `e.dataTransfer.files` (vocalremover-style audio
216
+ tools, many image/video drop zones). Neither `setfiles` nor `upload` applies;
217
+ use `drop <ref> <path…>`. By default it fires a genuinely-**trusted** CDP drag
218
+ (`Input.dispatchDragEvent`) carrying the real files from disk: it force-fronts
219
+ the tab (bringToFront + focus emulation + active lifecycle — so the tab reports
220
+ focused+visible even when the Chrome window isn't the frontmost OS window),
221
+ waits for the zone to be actionable, then dragEnter→dragOver→drop. The
222
+ force-front matters: drop-zone uploaders commonly do their work only inside a
223
+ **user activation**, and CDP input grants no activation on a tab the renderer
224
+ considers `hidden` — which it is whenever the window is occluded (the usual
225
+ case while you work in the terminal). vocalremover.org is the canonical example:
226
+ the file reaches its `change`/`drop` handler either way, but it only uploads +
227
+ separates once activation is present. `--js` instead dispatches a synthetic
228
+ (isTrusted=false) `DataTransfer` drop **without** force-fronting/stealing focus,
229
+ for zones that accept synthetic events. The `<ref>` can be any snapshot element
230
+ sitting over the drop region (a heading/button inside the zone) — the drop
231
+ bubbles to the zone/document handler, so it works even when the drop div itself
232
+ isn't snapshot-interactive. After the drop, `read`/`screenshot`/`network` to
233
+ confirm processing started, then grab the result (often a download endpoint you
234
+ can pull with `download --url`).
235
+ - **"The site is blocking us" — when it is really Chrome that cannot make renderers.**
236
+ A browser process can permanently lose the ability to launch **renderer processes** while
237
+ looking perfectly healthy. Every tab that already exists keeps working, so nothing seems wrong
238
+ until you open a tab or navigate somewhere new, and then the errors read as the remote site's
239
+ doing. Diagnosed 2026-08-22; it cost an hour of blaming ferry-operator bot protection.
240
+
241
+ How it shows up:
242
+ - `browser-automation new` + `goto` → `CDP Page.enable timed out after 30000ms`, **even for
243
+ `example.com`**.
244
+ - **Cross-origin** navigation of an existing, working tab → `navigate failed: net::ERR_ABORTED`.
245
+ Site isolation puts a new origin in a new renderer — the exact thing Chrome can no longer do.
246
+ - **Same-origin** navigation on that same tab keeps working perfectly (Skyscanner → Skyscanner
247
+ with new query params was fine throughout). That asymmetry is what makes it masquerade as
248
+ "only site X blocks us": the tab you were already using still behaves.
249
+ - A target created at the browser level (`PUT /json/new?<url>`) appears in `/json/list` with the
250
+ right URL but an **empty title forever**; every `Runtime.evaluate` against it times out.
251
+ `Page.captureScreenshot` returns `Internal error`. The target shell exists; the renderer does not.
252
+
253
+ **The mechanism** (macOS, from Chrome's own log at `$TMPDIR/chrome-<port>.log` — `launch --restart`
254
+ keeps the previous browser's log as `chrome-<port>.log.prev`, which is the one you want after a
255
+ restart):
256
+ ```
257
+ ERROR:base/apple/mach_port_rendezvous_mac.cc:256]
258
+ bootstrap_look_up com.google.Chrome.MachPortRendezvousServer.<pid>: (ipc/send) invalid destination port
259
+ ERROR:base/memory/shared_memory_switch.cc:261]
260
+ No rendezvous client, terminating process (parent died?)
261
+ ```
262
+ A Chrome child process gets its shared-memory handles by looking up a Mach bootstrap service the
263
+ browser registers **once, at startup**, named `com.google.Chrome.MachPortRendezvousServer.<browser-pid>`.
264
+ That registration had vanished from the user's launchd namespace — confirmed absent via
265
+ `launchctl print gui/$UID | grep MachPortRendezvousServer.<pid>`, while two healthy Chromes on the
266
+ same machine were both listed. From then on **every renderer Chrome launches kills itself within
267
+ milliseconds**, which is why none ever appears in `ps` and why the browser only reports
268
+ `Render process gone.` **What made the name vanish is not established.** Two things
269
+ correlated and neither is proven: the binary on disk had moved to 151.0.7922.170 while the live
270
+ browser was still running .138, and `GoogleUpdater` was FATAL-ing on its own `bootstrap_check_in`
271
+ with error 141. But the first renderer failure (18:53) *preceded* the first updater FATAL (19:42)
272
+ by ~50 minutes, so the update churn is at best a fellow symptom of a sick launchd bootstrap
273
+ namespace, not the cause. Treat the trigger as unknown; the diagnosis and the recovery do not
274
+ depend on it.
275
+
276
+ **It is NOT about how many tabs are open.** That was the first theory and it is wrong: a freshly
277
+ launched Chrome on the same machine was driven to **421 page targets / 435 live renderer
278
+ processes, every one responsive**, and a 256-fd `ulimit` made no difference either (205 renderers,
279
+ all fine). The broken browser had 66 tabs. The count was a coincidence — so do not treat a big
280
+ tab count as evidence of this, and do not expect closing tabs to fix it.
281
+
282
+ **Diagnose it:**
283
+ ```bash
284
+ browser-automation doctor # measures renderer capacity, not just reachability
285
+ ```
286
+ `doctor` now creates a throwaway tab, makes its renderer evaluate `1+1`, and closes it — the one
287
+ round-trip that separates a wedged browser from a slow network or a hostile site. On failure it
288
+ names the root cause (including the missing bootstrap service and the pid) and points at Chrome's
289
+ log. On a healthy browser it reports e.g. `✓ Renderer capacity: a new tab got a live renderer in
290
+ 73ms`. `goto` and `new` run the same probe automatically **on the error path only**, so a bare
291
+ `Page.enable timed out` now arrives with the diagnosis attached instead of sending you to the
292
+ site's bot-protection docs.
293
+
294
+ **Recovery — only a Chrome restart clears it.** The bootstrap name is registered at startup and
295
+ never re-registered, so nothing short of a new browser process helps. Closing tabs does not, and
296
+ plain `launch` will not either (idempotent by design — it sees a live browser and exits happy):
297
+ ```bash
298
+ browser-automation launch --restart # SIGTERM (profile flushes cleanly), wait, relaunch
299
+ ```
300
+ It reports how many tabs it is about to close. **Those tabs belong to every parallel Claude Code
301
+ session sharing this Chrome — ask Fred first, never restart unilaterally.**
302
+
303
+ **Housekeeping is a different problem** — `browser-automation gc` prunes stale session bookmarks
304
+ (they are never cleaned up otherwise; this machine had accumulated 234, only 5 of them live) and
305
+ closes tabs whose renderer does not answer. Use `--dry` first. It is genuinely useful, but it is
306
+ **not** a fix for the wedge above, and it never closes a working tab unless you pass `--orphans`
307
+ — tabs get addressed by `-m` and opened by hand, so "no session claims it" is not evidence that
308
+ nobody wants it.
309
+
310
+ **The false lead to resist:** a bare `curl` to a suspicious site may genuinely return a bot wall
311
+ (vikingline.fi serves an Imperva "Pardon Our Interruption" page, HTTP 200), which feels like
312
+ confirmation. It confirms nothing about the browser path — the persistent, cookie-bearing profile
313
+ is a completely different client. Check the browser first: if `doctor` says renderer capacity is
314
+ fine and a boring cross-origin URL loads, *then* start suspecting the site.
315
+
210
316
  - **Page still loading.** `goto` waits for the load event, but SPAs render after.
211
317
  If a `read`/`snapshot` looks empty, re-run after a moment, or snapshot again
212
318
  once a known element should be present.
213
319
  - **`launch` is macOS/Linux only** (resolves the Chrome binary per-OS). On other
214
- setups, start Chrome manually with `--remote-debugging-port=9223
320
+ setups, start Chrome manually with `--remote-debugging-port=<doctor's port>
215
321
  --user-data-dir="<profile>"`.
216
322
 
217
323
  ## Network insights — find the API behind a page
@@ -275,7 +381,10 @@ working around it forever**:
275
381
 
276
382
  ## Troubleshooting
277
383
 
278
- - **`No CDP browser on http://localhost:9223`** → `browser-automation launch`.
384
+ - **`No CDP browser on http://localhost:<port>`** → `browser-automation launch`.
385
+ If it says the port is held by ANOTHER user, that is not your Chrome and
386
+ driving it would act in their session — quit Chrome in that account, or set
387
+ `BROWSER_AUTOMATION_PORT`.
279
388
  - **`command not found: browser-automation`** → `npm install -g @generativereality/browser-automation`.
280
389
  - **Chrome was restarted** → nothing to do; the next `goto` recreates the
281
390
  session's tab automatically (sessions self-heal; `list` shows `stale`).