@generativereality/browser-automation 0.4.11 → 0.4.12

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.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "browser-automation",
3
3
  "description": "Daemonless, per-tab-isolated browser automation for Claude Code via the `browser-automation` CLI. Drives one shared headed Chrome (persistent profile + extensions) over per-target CDP — many parallel sessions, no focus stealing, nothing long-lived to crash.",
4
- "version": "0.4.11",
4
+ "version": "0.4.12",
5
5
  "author": {
6
6
  "name": "generativereality"
7
7
  },
package/dist/index.js CHANGED
@@ -4,12 +4,12 @@ import { cli, define } from "gunshi";
4
4
  import { consola } from "consola";
5
5
  import { homedir } from "node:os";
6
6
  import { basename, dirname, extname, join, resolve } from "node:path";
7
- import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
7
+ import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
8
8
  import { execFileSync, spawnSync } from "node:child_process";
9
9
  import { fileURLToPath } from "node:url";
10
10
  //#region package.json
11
11
  var name = "@generativereality/browser-automation";
12
- var version = "0.4.11";
12
+ var version = "0.4.12";
13
13
  var 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.";
14
14
  var package_default = {
15
15
  name,
@@ -388,6 +388,26 @@ async function createTab(url = "about:blank", { timeout } = {}) {
388
388
  }, timeout)).targetId;
389
389
  }, timeout);
390
390
  }
391
+ /**
392
+ * Bring a target to the front of its window.
393
+ *
394
+ * **This raises the Chrome window over whatever the operator is using** —
395
+ * measured on macOS 2026-09-11, with the terminal deliberately frontmost:
396
+ * Target.activateTarget, GET /json/activate/<id>, Page.bringToFront and
397
+ * createTarget(background:false) all moved the frontmost app from the terminal
398
+ * to Google Chrome. There is no quiet variant.
399
+ *
400
+ * It is here because a backgrounded target's renderer can take 12+ seconds to
401
+ * answer while an activated one answers in ~19ms (see core/renderer-wake.ts),
402
+ * and a brief flicker beats refusing to work. Nothing calls it casually:
403
+ * `ensureRenderer` spends it only after a grace period has expired, and hands
404
+ * the window straight back.
405
+ */
406
+ async function activateTab(targetId) {
407
+ return withBrowser(async (s) => {
408
+ await s.send("Target.activateTarget", { targetId });
409
+ });
410
+ }
391
411
  async function closeTab(targetId) {
392
412
  return withBrowser(async (s) => {
393
413
  return !!(await s.send("Target.closeTarget", { targetId })).success;
@@ -475,39 +495,303 @@ function normalizeUrl(input) {
475
495
  return `https://${input}`;
476
496
  }
477
497
  //#endregion
498
+ //#region src/core/renderer-wake.ts
499
+ /** How long a new tab gets to produce a renderer on its own before we wake it. */
500
+ const DEFAULT_GRACE = 2e3;
501
+ /** How long the woken tab then gets. Generous: waking is the expensive step. */
502
+ const DEFAULT_BUDGET = 1e4;
503
+ function envInt(name, fallback) {
504
+ const v = Number(process.env[name]);
505
+ return Number.isFinite(v) && v > 0 ? Math.floor(v) : fallback;
506
+ }
507
+ /**
508
+ * Ask ONE existing target's renderer to evaluate `1+1`.
509
+ *
510
+ * Deliberately not a navigation: the question is "can this renderer execute",
511
+ * which is the narrowest thing that separates a busy browser from a broken one
512
+ * without involving the network or the site.
513
+ */
514
+ async function askRenderer(targetId, timeout = 5e3) {
515
+ const started = Date.now();
516
+ const ms = () => Date.now() - started;
517
+ let ws;
518
+ try {
519
+ ws = await targetWsUrl(targetId);
520
+ } catch (e) {
521
+ return {
522
+ outcome: "error",
523
+ ms: ms(),
524
+ reason: String(e?.message ?? e)
525
+ };
526
+ }
527
+ if (!ws) return {
528
+ outcome: "gone",
529
+ ms: ms(),
530
+ reason: "the target vanished before we could attach to it"
531
+ };
532
+ let session;
533
+ try {
534
+ session = await connect(ws, { timeout });
535
+ } catch (e) {
536
+ const msg = String(e?.message ?? e);
537
+ return /timed out|timeout|WebSocket error/i.test(msg) ? {
538
+ outcome: "unattachable",
539
+ ms: ms(),
540
+ reason: `the target is listed, but its CDP connection would not open within ${timeout}ms (${msg})`
541
+ } : {
542
+ outcome: "error",
543
+ ms: ms(),
544
+ reason: msg
545
+ };
546
+ }
547
+ try {
548
+ const value = (await session.send("Runtime.evaluate", {
549
+ expression: "1+1",
550
+ returnByValue: true
551
+ }, timeout))?.result?.value;
552
+ if (value === 2) return {
553
+ outcome: "ok",
554
+ ms: ms()
555
+ };
556
+ return {
557
+ outcome: "wrong-answer",
558
+ ms: ms(),
559
+ reason: `the renderer answered with ${JSON.stringify(value)} instead of 2`
560
+ };
561
+ } catch (e) {
562
+ const msg = String(e?.message ?? e);
563
+ return /timed out|timeout/i.test(msg) ? {
564
+ outcome: "silent",
565
+ ms: ms(),
566
+ reason: `attached to the target, but its renderer did not answer within ${timeout}ms`
567
+ } : {
568
+ outcome: "error",
569
+ ms: ms(),
570
+ reason: msg
571
+ };
572
+ } finally {
573
+ session.close();
574
+ }
575
+ }
576
+ /**
577
+ * The macOS app currently in front, as a bundle path we can hand focus back to.
578
+ *
579
+ * `lsappinfo`, not AppleScript: `tell application "System Events" to get name
580
+ * of first application process whose frontmost is true` needs Accessibility
581
+ * permission, and a permission dialog appearing in the middle of an automated
582
+ * command is worse than the focus steal it is trying to undo. `lsappinfo` needs
583
+ * nothing and is present on every macOS.
584
+ */
585
+ function frontmostApp() {
586
+ if (process.platform !== "darwin") return null;
587
+ try {
588
+ const asn = execFileSync("lsappinfo", ["front"], {
589
+ encoding: "utf8",
590
+ stdio: [
591
+ "ignore",
592
+ "pipe",
593
+ "ignore"
594
+ ]
595
+ }).trim();
596
+ if (!asn) return null;
597
+ const info = execFileSync("lsappinfo", [
598
+ "info",
599
+ "-only",
600
+ "bundlepath",
601
+ asn
602
+ ], {
603
+ encoding: "utf8",
604
+ stdio: [
605
+ "ignore",
606
+ "pipe",
607
+ "ignore"
608
+ ]
609
+ });
610
+ return /"LSBundlePath"="([^"]+)"/.exec(info)?.[1] ?? null;
611
+ } catch {
612
+ return null;
613
+ }
614
+ }
615
+ /** Put the operator's app back in front. Best effort, and never fatal. */
616
+ function raiseApp(bundlePath) {
617
+ if (!bundlePath || process.platform !== "darwin") return;
618
+ if (/Google Chrome\.app|Chromium\.app/.test(bundlePath)) return;
619
+ try {
620
+ execFileSync("open", ["-a", bundlePath], { stdio: "ignore" });
621
+ } catch {}
622
+ }
623
+ /**
624
+ * Which tab the operator is looking at, so it can be put back afterwards.
625
+ *
626
+ * Chrome lists page targets most-recently-active first. That is an observation,
627
+ * not a documented guarantee — it held in every trial here, and when it is
628
+ * wrong the cost is that the window comes back to a different tab of the
629
+ * automation browser, not a failure.
630
+ */
631
+ async function activePageId() {
632
+ try {
633
+ return (await listPageTargets())[0]?.id;
634
+ } catch {
635
+ return;
636
+ }
637
+ }
638
+ /**
639
+ * Make sure `targetId` has a renderer that answers — cheaply if possible.
640
+ *
641
+ * Grace period first (the common case: no focus is taken at all), then one
642
+ * wake, then the verdict. `allowWake: false` (or BROWSER_AUTOMATION_NO_WAKE=1)
643
+ * keeps the window untouched for callers who would rather fail than flicker.
644
+ */
645
+ async function ensureRenderer(targetId, { grace, budget, allowWake = !process.env.BROWSER_AUTOMATION_NO_WAKE } = {}) {
646
+ const graceMs = grace ?? envInt("BROWSER_AUTOMATION_RENDERER_GRACE", DEFAULT_GRACE);
647
+ const budgetMs = budget ?? envInt("BROWSER_AUTOMATION_RENDERER_BUDGET", DEFAULT_BUDGET);
648
+ const started = Date.now();
649
+ const first = await askRenderer(targetId, graceMs);
650
+ if (first.outcome === "ok") return {
651
+ ...first,
652
+ ok: true,
653
+ woke: false,
654
+ ms: Date.now() - started
655
+ };
656
+ if (!allowWake || first.outcome !== "silent" && first.outcome !== "unattachable") return {
657
+ ...first,
658
+ ok: false,
659
+ woke: false,
660
+ ms: Date.now() - started
661
+ };
662
+ const previousApp = frontmostApp();
663
+ const previousTab = await activePageId();
664
+ try {
665
+ await activateTab(targetId);
666
+ } catch (e) {
667
+ return {
668
+ ...first,
669
+ ok: false,
670
+ woke: false,
671
+ ms: Date.now() - started,
672
+ reason: `${first.reason}; and it could not be activated either (${e?.message ?? e})`
673
+ };
674
+ }
675
+ const second = await askRenderer(targetId, budgetMs);
676
+ if (previousTab && previousTab !== targetId) await activateTab(previousTab).catch(() => {});
677
+ raiseApp(previousApp);
678
+ return {
679
+ ...second,
680
+ ok: second.outcome === "ok",
681
+ woke: true,
682
+ ms: Date.now() - started
683
+ };
684
+ }
685
+ //#endregion
478
686
  //#region src/core/renderer-health.ts
687
+ /** First attempt's budget. Later attempts double it. */
688
+ const DEFAULT_TIMEOUT = 5e3;
689
+ /** How many times we ask before we are willing to call a browser broken. */
690
+ const DEFAULT_ATTEMPTS = 3;
691
+ /** Breathing room between attempts — a browser mid-GC deserves a second look. */
692
+ const RETRY_PAUSE = 400;
693
+ /**
694
+ * The verdict, from the probe and the corroborations — and from nothing else.
695
+ *
696
+ * Pure, and separate from the probing, because this is the decision that was
697
+ * wrong: every failure used to become 'wedged' by default. Now 'wedged'
698
+ * requires `rendezvous === false`, which is the only thing that has ever
699
+ * actually meant it.
700
+ */
701
+ function rendererVerdict(outcome, e) {
702
+ if (outcome === "ok") return "healthy";
703
+ if (e?.rendezvous === false) return "wedged";
704
+ if (e?.rendezvous === true && (e.renderers ?? 0) > 0) return "busy";
705
+ return "unknown";
706
+ }
479
707
  /**
480
708
  * Create a throwaway tab, make its renderer prove it is alive, close it.
481
709
  *
482
- * Deliberately uses `about:blank` and `Runtime.evaluate`, not a navigation:
483
- * we are asking "can a new renderer exist and execute", which is the narrowest
484
- * question that separates a wedged browser from a slow network or a hostile
485
- * site. Nothing here touches the caller's tabs.
710
+ * Three things changed after 2026-09-11, and each of them is load-bearing:
711
+ *
712
+ * 1. It goes through `ensureRenderer`, so the probe opens its tab the way the
713
+ * tool opens tabs AND gets the same wake treatment. A probe that is harsher
714
+ * on itself than `goto` is on a real tab reports failures `goto` would not
715
+ * have had.
716
+ * 2. It retries with a doubling budget. One 5s timeout is not evidence of a
717
+ * permanent condition; it is evidence of 5 seconds.
718
+ * 3. It stops early when the Mach name is ABSENT — the one state where more
719
+ * waiting is genuinely pointless — so the real failure is still reported
720
+ * fast while a slow browser gets the benefit of the doubt.
486
721
  */
487
- async function probeRenderer({ timeout = 5e3 } = {}) {
722
+ async function probeRenderer({ timeout, attempts } = {}) {
723
+ const base = timeout ?? envInt("BROWSER_AUTOMATION_PROBE_TIMEOUT", DEFAULT_TIMEOUT);
724
+ const maxAttempts = Math.max(1, attempts ?? envInt("BROWSER_AUTOMATION_PROBE_ATTEMPTS", DEFAULT_ATTEMPTS));
488
725
  const started = Date.now();
489
726
  let pageTargets = 0;
490
727
  try {
491
728
  pageTargets = (await listPageTargets()).length;
492
729
  } catch {}
730
+ const tries = [];
731
+ let evidence;
732
+ for (let i = 0; i < maxAttempts; i++) {
733
+ const budget = base * 2 ** i;
734
+ tries.push(await probeOnce(budget));
735
+ if (tries[tries.length - 1].outcome === "ok") return finish({
736
+ ok: true,
737
+ started,
738
+ pageTargets,
739
+ tries,
740
+ evidence
741
+ });
742
+ evidence ??= gatherEvidence();
743
+ if (evidence.rendezvous === false) break;
744
+ if (i + 1 < maxAttempts) await new Promise((r) => setTimeout(r, RETRY_PAUSE));
745
+ }
746
+ return finish({
747
+ ok: false,
748
+ started,
749
+ pageTargets,
750
+ tries,
751
+ evidence
752
+ });
753
+ }
754
+ function finish({ ok, started, pageTargets, tries, evidence }) {
755
+ const last = tries[tries.length - 1];
756
+ const health = {
757
+ ok,
758
+ ms: Date.now() - started,
759
+ pageTargets,
760
+ reason: last?.reason,
761
+ outcome: last?.outcome ?? "error",
762
+ verdict: rendererVerdict(last?.outcome ?? "error", evidence),
763
+ attempts: tries,
764
+ evidence
765
+ };
766
+ recordProbe(health);
767
+ return health;
768
+ }
769
+ /** One create -> ensure -> close cycle. */
770
+ async function probeOnce(budget) {
771
+ const started = Date.now();
493
772
  let targetId;
494
773
  try {
495
- targetId = await createTab("about:blank", { timeout });
774
+ targetId = await createTab("about:blank", { timeout: budget });
496
775
  } catch (e) {
497
776
  return {
498
- ok: false,
777
+ outcome: "error",
778
+ budget,
499
779
  ms: Date.now() - started,
500
- pageTargets,
780
+ woke: false,
501
781
  reason: `could not create a target at all: ${e?.message ?? e}`
502
782
  };
503
783
  }
504
784
  try {
505
- const reason = await renderersAnswer(targetId, timeout);
785
+ const r = await ensureRenderer(targetId, {
786
+ grace: budget,
787
+ budget
788
+ });
506
789
  return {
507
- ok: reason === null,
790
+ outcome: r.outcome,
791
+ budget,
508
792
  ms: Date.now() - started,
509
- pageTargets,
510
- reason: reason ?? void 0
793
+ woke: r.woke,
794
+ reason: r.reason
511
795
  };
512
796
  } finally {
513
797
  if (targetId) await closeTab(targetId).catch(() => {});
@@ -516,68 +800,83 @@ async function probeRenderer({ timeout = 5e3 } = {}) {
516
800
  /**
517
801
  * Ask an EXISTING target's renderer to prove it is alive.
518
802
  *
519
- * Returns null when it answers correctly, or a human-readable reason when it
520
- * does not. Used both by the throwaway probe and by `new`, which has just
521
- * created a tab and should check that one rather than manufacture a second.
803
+ * Kept returning `string | null` because that is what `gc` wants (a reason to
804
+ * print beside a tab it is about to close). New callers should prefer
805
+ * `askRenderer`, which says WHICH failure it was.
522
806
  */
523
- async function renderersAnswer(targetId, timeout = 5e3) {
524
- try {
525
- const ws = await targetWsUrl(targetId);
526
- if (!ws) return "the target vanished immediately";
527
- const s = await connect(ws, { timeout });
528
- try {
529
- const value = (await s.send("Runtime.evaluate", {
530
- expression: "1+1",
531
- returnByValue: true
532
- }, timeout))?.result?.value;
533
- return value === 2 ? null : `the renderer answered with ${JSON.stringify(value)} instead of 2`;
534
- } finally {
535
- s.close();
536
- }
537
- } catch (e) {
538
- const msg = String(e?.message ?? e);
539
- return /timed out|timeout/i.test(msg) ? "the target exists, but no renderer ever answered it" : msg;
540
- }
807
+ async function renderersAnswer(targetId, timeout = DEFAULT_TIMEOUT) {
808
+ const r = await askRenderer(targetId, timeout);
809
+ return r.outcome === "ok" ? null : r.reason ?? r.outcome;
541
810
  }
542
811
  /**
543
812
  * The port we are actually talking to.
544
813
  *
545
814
  * NOT always `cdpPort()`: `BROWSER_AUTOMATION_CDP` points the CLI at an
546
- * arbitrary host:port, and everything here that shells out to `pgrep` or
547
- * `launchctl` has to ask about THAT browser. Using the uid-derived port
548
- * instead finds the user's default Chrome and cheerfully reports its health
549
- * as if it were the one being driven — caught while testing this module
550
- * against a second Chrome, where a perfectly healthy browser was accused of
551
- * having lost the bootstrap name that in fact belonged to a different pid.
815
+ * arbitrary host:port, and everything here that shells out to `ps` or
816
+ * `launchctl` has to ask about THAT browser. Using the uid-derived port instead
817
+ * finds the user's default Chrome and cheerfully reports its health as if it
818
+ * were the one being driven — caught while testing this module against a second
819
+ * Chrome, where a perfectly healthy browser was accused of having lost a
820
+ * bootstrap name that in fact belonged to a different pid.
552
821
  */
553
822
  function targetPort() {
554
823
  const explicit = process.env.BROWSER_AUTOMATION_CDP;
555
- if (explicit) {
824
+ if (explicit) try {
556
825
  const p = Number(new URL(explicit).port);
557
826
  if (Number.isInteger(p) && p > 0) return p;
558
- }
827
+ } catch {}
559
828
  return cdpPort();
560
829
  }
561
- /** The pid of the browser process serving the port we are driving, if visible. */
562
- function browserPid() {
830
+ /**
831
+ * The browser process serving our port, and how many renderers it has.
832
+ *
833
+ * One `ps`, not one `pgrep` plus one `ps` per hit: on a Chrome with 40 children
834
+ * that was 41 forks to answer two questions, and it ran on the error path of a
835
+ * browser already thought to be struggling.
836
+ *
837
+ * The executable check is not decoration. Matching on the command line alone
838
+ * (as `pgrep -f` does) hits any process that merely CONTAINS the debugging-port
839
+ * flag — the `grep` looking for it, or a shell running `browser-automation`
840
+ * with the flag as an argument. One of those, having no `--type=`, would have
841
+ * been reported as the browser pid, and its absent Mach name read as the
842
+ * permanent failure. Seen while writing this: a `ugrep` for the flag sat in
843
+ * `ps` output alongside the real Chrome.
844
+ */
845
+ function chromeProcesses() {
846
+ const flag = `--remote-debugging-port=${targetPort()}`;
847
+ const uid = String(process.getuid?.() ?? -1);
848
+ let out;
563
849
  try {
564
- const out = execFileSync("pgrep", [
565
- "-u",
566
- String(process.getuid?.() ?? -1),
567
- "-f",
568
- "--",
569
- `--remote-debugging-port=${targetPort()}`
570
- ], { encoding: "utf8" });
571
- for (const pid of out.split("\n").map((s) => s.trim()).filter(Boolean)) try {
572
- if (!execFileSync("ps", [
573
- "-o",
574
- "command=",
575
- "-p",
576
- pid
577
- ], { encoding: "utf8" }).includes("--type=")) return Number(pid);
578
- } catch {}
579
- } catch {}
580
- return null;
850
+ out = execFileSync("ps", ["-Ao", "pid=,uid=,command="], {
851
+ encoding: "utf8",
852
+ maxBuffer: 64 * 1024 * 1024,
853
+ stdio: [
854
+ "ignore",
855
+ "pipe",
856
+ "ignore"
857
+ ]
858
+ });
859
+ } catch {
860
+ return {
861
+ browser: null,
862
+ renderers: null
863
+ };
864
+ }
865
+ let browser = null;
866
+ let renderers = 0;
867
+ for (const line of out.split("\n")) {
868
+ const m = /^\s*(\d+)\s+(\d+)\s+(.*)$/.exec(line);
869
+ if (!m) continue;
870
+ const [, pid, u, cmd] = m;
871
+ if (u !== uid || !cmd.includes(flag)) continue;
872
+ if (!/chrome|chromium|brave|msedge|thorium/i.test(cmd.split(" --")[0])) continue;
873
+ if (/--type=renderer\b/.test(cmd)) renderers++;
874
+ else if (!cmd.includes("--type=")) browser = Number(pid);
875
+ }
876
+ return {
877
+ browser,
878
+ renderers
879
+ };
581
880
  }
582
881
  /**
583
882
  * macOS only: is the browser's Mach port rendezvous service still registered?
@@ -585,7 +884,7 @@ function browserPid() {
585
884
  * This is the ROOT CAUSE signal, not a symptom — when it is missing, every
586
885
  * child process Chrome launches kills itself on startup. Returns null when we
587
886
  * cannot tell (not macOS, `launchctl` unavailable, pid unknown), which is
588
- * different from `false` and must not be reported as a fault.
887
+ * different from `false` and must never be reported as a fault.
589
888
  */
590
889
  function rendezvousRegistered(pid) {
591
890
  if (process.platform !== "darwin" || !pid) return null;
@@ -603,51 +902,143 @@ function rendezvousRegistered(pid) {
603
902
  return null;
604
903
  }
605
904
  }
905
+ /** Both corroborations, in one pass. Cheap enough to run on every failure. */
906
+ function gatherEvidence() {
907
+ const { browser, renderers } = chromeProcesses();
908
+ return {
909
+ pid: browser,
910
+ renderers: browser === null ? null : renderers,
911
+ rendezvous: rendezvousRegistered(browser)
912
+ };
913
+ }
606
914
  /** Where `launch` writes Chrome's stdout/stderr — Chrome logs the real reason there. */
607
915
  function chromeLogPath() {
608
916
  const tmp = process.env.TMPDIR?.replace(/\/$/, "") || "/tmp";
609
917
  return process.env.BROWSER_AUTOMATION_LOG || `${tmp}/chrome-${targetPort()}.log`;
610
918
  }
919
+ function probeLogPath() {
920
+ return process.env.BROWSER_AUTOMATION_PROBE_LOG || join(homedir(), ".browser-automation", "renderer-probes.jsonl");
921
+ }
922
+ function recordProbe(h) {
923
+ const line = JSON.stringify({
924
+ t: (/* @__PURE__ */ new Date()).toISOString(),
925
+ ok: h.ok,
926
+ verdict: h.verdict,
927
+ outcome: h.outcome,
928
+ ms: h.ms,
929
+ attempts: h.attempts.map((a) => ({
930
+ outcome: a.outcome,
931
+ ms: a.ms,
932
+ budget: a.budget,
933
+ woke: a.woke
934
+ })),
935
+ pageTargets: h.pageTargets,
936
+ evidence: h.evidence
937
+ });
938
+ try {
939
+ const path = probeLogPath();
940
+ mkdirSync(join(path, ".."), { recursive: true });
941
+ try {
942
+ if (statSync(path).size > 256 * 1024) {
943
+ const kept = readFileSync(path, "utf8").split("\n").slice(-500).join("\n");
944
+ writeFileSync(path, kept.endsWith("\n") ? kept : kept + "\n");
945
+ }
946
+ } catch {}
947
+ appendFileSync(path, line + "\n");
948
+ } catch {}
949
+ }
950
+ /** Recent probe timings, for `doctor`. Returns null when there is no history. */
951
+ function recentProbeStats(limit = 50) {
952
+ try {
953
+ const rows = readFileSync(probeLogPath(), "utf8").trim().split("\n").slice(-limit).map((l) => {
954
+ try {
955
+ return JSON.parse(l);
956
+ } catch {
957
+ return null;
958
+ }
959
+ }).filter(Boolean);
960
+ if (!rows.length) return null;
961
+ const okMs = rows.filter((r) => r.ok).map((r) => r.ms).sort((a, b) => a - b);
962
+ return {
963
+ n: rows.length,
964
+ failures: rows.filter((r) => !r.ok).length,
965
+ median: okMs.length ? okMs[Math.floor(okMs.length / 2)] : -1,
966
+ worst: okMs.length ? okMs[okMs.length - 1] : -1
967
+ };
968
+ } catch {
969
+ return null;
970
+ }
971
+ }
972
+ function evidenceLines(e) {
973
+ if (!e) return [];
974
+ const mach = e.rendezvous === true ? `registered for pid ${e.pid} — the permanent failure's signature is ABSENT` : e.rendezvous === false ? `NOT REGISTERED for pid ${e.pid} — this is the permanent failure` : `could not check (${e.pid ? `pid ${e.pid}, ` : "browser pid unknown, "}not macOS or launchctl unavailable)`;
975
+ const rend = e.renderers === null ? `could not count` : `${e.renderers} live renderer process(es) for this browser`;
976
+ return [` mach service: ${mach}`, ` renderers: ${rend}`];
977
+ }
978
+ /** The cheap recovery. Always printed, always before anything expensive. */
979
+ function cheapRecovery() {
980
+ return [
981
+ `Try these first, cheapest first:`,
982
+ ``,
983
+ ` 1. Run the command again. A new tab's renderer has been measured taking`,
984
+ ` 12s and more on a loaded machine, and it is not broken, only late.`,
985
+ ` 2. Use a tab that already works. An existing tab navigates same-origin`,
986
+ ` without needing a new renderer, so it keeps working throughout:`,
987
+ ` browser-automation list`,
988
+ ` browser-automation eval -t <id> "location.href='<url>'"`,
989
+ ` 3. browser-automation doctor — re-measures, and prints recent probe times.`
990
+ ];
991
+ }
611
992
  /**
612
993
  * A ready-to-print explanation of a renderer failure, with the recovery.
613
994
  *
614
995
  * Written to be read by somebody who has just been told a site blocks them, so
615
- * it says what is and is not true before it says what to do.
996
+ * it says what is and is not true before it says what to do — and it says only
997
+ * what was actually established. The four verdicts get four different endings
998
+ * because they need four different actions, and exactly one of them is worth
999
+ * anybody's tabs.
616
1000
  */
617
1001
  function explainRendererFailure(h) {
618
- const pid = browserPid();
619
- const rendezvous = rendezvousRegistered(pid);
1002
+ const e = h.evidence ?? gatherEvidence();
1003
+ const verdict = h.verdict ?? rendererVerdict(h.outcome, e);
1004
+ const tried = h.attempts?.length ?? 1;
1005
+ const longest = h.attempts?.length ? Math.max(...h.attempts.map((a) => a.budget)) : 0;
1006
+ const woke = h.attempts?.some((a) => a.woke);
620
1007
  const lines = [
621
- `Chrome cannot give a new tab a working renderer.`,
1008
+ `Chrome did not give a new tab a working renderer.`,
622
1009
  ``,
623
- ` probe: created a target, ${h.reason ?? "no renderer answered"} (${h.ms}ms)`,
624
- ` page targets: ${h.pageTargets} (context only — this is NOT the cause; a healthy`,
625
- ` Chrome has been driven to 421 tabs with every renderer alive)`
1010
+ ` probe: ${tried} attempt(s), longest budget ${longest}ms, ${h.ms}ms total`,
1011
+ ` ${h.reason ?? "no renderer answered"}`,
1012
+ ...woke ? [` (it was also activated to force a renderer, and still did not answer)`] : [],
1013
+ ` page targets: ${h.pageTargets} (context only — NOT the cause; a healthy Chrome has`,
1014
+ ` been driven to 421 tabs with every renderer alive)`,
1015
+ ...evidenceLines(e),
1016
+ ``
626
1017
  ];
627
- if (rendezvous === false) lines.push(` root cause: the browser process (pid ${pid}) has lost its Mach bootstrap`, ` service "com.google.Chrome.MachPortRendezvousServer.${pid}".`, ` Chrome registers that name once, at startup; every child`, ` process looks it up to receive its shared memory. With the`, ` name gone, every renderer Chrome launches immediately exits.`, ` This is permanent for this browser process.`);
628
- else if (rendezvous === true) lines.push(` note: the Mach rendezvous service for pid ${pid} IS still registered,`, ` so this is a different renderer failure from the one seen on`, ` 2026-08-22. Chrome's own log will say why:`, ` tail -50 ${chromeLogPath()}`);
629
- lines.push(``, `This is a browser-level failure. It is NOT the site blocking automation, and`, `retrying, changing the URL, or adding a user agent will not help. Two tells:`, `same-origin navigations in tabs that already work keep working (they reuse a`, `renderer that already exists), and cross-origin ones fail with ERR_ABORTED`, `(site isolation needs a new renderer, which is the thing Chrome can't do).`, ``, `Recovery: restart Chrome. Nothing else clears it — closing tabs does not,`, `and plain \`launch\` will not either: it now DETECTS this (it runs this same`, `probe and fails), but it will never restart a browser other sessions may be`, `using without being told to. Restarting is always something you type.`, ``, ` browser-automation launch --restart # closes ALL tabs, then relaunches`, ``, `If other sessions are driving this Chrome, agree on the restart first — their`, `open tabs go with it. \`browser-automation list\` shows who holds what.`);
1018
+ if (verdict === "wedged") lines.push(`VERDICT: this browser process can never make a renderer again.`, ``, `Chrome registers "com.google.Chrome.MachPortRendezvousServer.${e.pid}" once, at`, `startup, and every child process looks that name up to receive its shared`, `memory. The name is gone, so every renderer Chrome launches from now on exits`, `within milliseconds. Nothing re-registers it, and closing tabs does not help.`, ``, `This is NOT the site blocking automation. Two tells: same-origin navigations in`, `tabs that already work keep working (they reuse a renderer that exists), and`, `cross-origin ones fail with ERR_ABORTED (site isolation needs a new renderer).`, ``, ...cheapRecovery(), ``, `Only then, and only because the signature above is confirmed present, a restart`, `is the real fix:`, ``, ` browser-automation launch --restart # closes ALL tabs, for EVERY session`, ``, `Other sessions are driving this Chrome. Their open tabs go with it, and they`, `will not be told why — agree on it first. \`browser-automation list\` shows who`, `holds what.`);
1019
+ else if (verdict === "busy") lines.push(`VERDICT: Chrome is NOT in the permanent, restart-only state.`, ``, `Its Mach rendezvous service is registered and ${e.renderers} renderer processes are`, `alive. Both are absent in that failure, so whatever this is, a restart is not`, `the fix for it — the probe asked ${tried} times, waited up to ${longest}ms, and did not`, `get an answer. That happens on a loaded machine and it usually clears by itself.`, ``, ...cheapRecovery(), ``, `Do NOT restart Chrome on the strength of this message. \`launch --restart\` closes`, `every tab of every session sharing this browser, and the evidence above says`, `this is not the failure a restart fixes.`);
1020
+ else lines.push(`VERDICT: undiagnosed — and specifically, NOT confirmed as the permanent failure.`, ``, `The probe failed, but the signature of the restart-only condition (an ABSENT`, `Mach rendezvous service) could not be confirmed, so this may equally be a slow`, `or heavily loaded browser. Those need opposite responses, and guessing wrong`, `costs every session on this browser its tabs.`, ``, ...cheapRecovery(), ``, `If it keeps failing, get the corroboration before doing anything drastic:`, ``, ` browser-automation doctor`, ` tail -50 ${chromeLogPath()}`, ``, `A \`doctor\` that reports the Mach service ABSENT is the permanent failure, and`, `only that justifies \`launch --restart\` — which closes every tab for every`, `session sharing this Chrome.`);
630
1021
  return lines.join("\n");
631
1022
  }
632
1023
  /**
633
- * Does this error look like it could be the renderer wedge rather than the site?
1024
+ * Does this error look like it could be a renderer failure rather than the site?
634
1025
  *
635
- * Kept deliberately narrow. These three are the ONLY shapes the failure takes
636
- * through the CLI, and each of them has an innocent explanation too — so a hit
637
- * here buys a probe, never a conclusion.
1026
+ * Kept deliberately narrow. These are the ONLY shapes the failure takes through
1027
+ * the CLI, and each of them has an innocent explanation too — so a hit here
1028
+ * buys a probe, never a conclusion.
638
1029
  */
639
1030
  function mayBeRendererFailure(err) {
640
1031
  const m = String(err?.message ?? err);
641
- return /Page\.enable timed out/i.test(m) || /net::ERR_ABORTED/i.test(m) || /Runtime\.evaluate timed out/i.test(m) || /Render process gone/i.test(m) || /CDP connect timeout/i.test(m);
1032
+ return /Page\.enable timed out/i.test(m) || /Target\.createTarget timed out/i.test(m) || /net::ERR_ABORTED/i.test(m) || /Runtime\.evaluate timed out/i.test(m) || /Render process gone/i.test(m) || /CDP connect timeout/i.test(m);
642
1033
  }
643
1034
  /**
644
- * Run `fn`; if it fails in a way the renderer wedge could explain, spend one
1035
+ * Run `fn`; if it fails in a way a renderer failure could explain, spend one
645
1036
  * probe finding out, and re-throw with the diagnosis attached.
646
1037
  *
647
1038
  * The probe only ever runs on the error path, so the happy path pays nothing.
648
1039
  * If the probe comes back healthy the original error is re-thrown untouched —
649
- * the point is to stop misattributing a browser fault to a site, not to blame
650
- * the browser for every timeout.
1040
+ * and since the probe now retries and can wake a late renderer, "healthy" is
1041
+ * the answer a loaded browser gets, which is the September bug not happening.
651
1042
  */
652
1043
  async function withRendererDiagnosis(fn) {
653
1044
  try {
@@ -683,21 +1074,22 @@ const newCommand = define({
683
1074
  const name = ctx.values.session || defaultSessionName();
684
1075
  const url = ctx.positionals[1] ? normalizeUrl(ctx.positionals[1]) : "about:blank";
685
1076
  if (loadSession(name) && !ctx.values.force) consola.warn(`Session "${name}" already maps to a tab. Use --force to open another, or just \`browser-automation goto -s ${name} <url>\`.`);
686
- const targetId = await createTab(url);
1077
+ const targetId = await withRendererDiagnosis(() => createTab(url));
687
1078
  saveSession({
688
1079
  name,
689
1080
  targetId,
690
1081
  url,
691
1082
  createdAt: (/* @__PURE__ */ new Date()).toISOString()
692
1083
  });
693
- const dead = await renderersAnswer(targetId).catch(() => null);
694
- if (dead) {
1084
+ const r = await ensureRenderer(targetId);
1085
+ if (r.woke) consola.warn(`[${name}] the new tab's renderer did not start on its own, so the tab was activated briefly to force one. The Chrome window was raised and handed straight back.`);
1086
+ if (!r.ok) {
695
1087
  const health = await probeRenderer().catch(() => null);
696
1088
  if (health && !health.ok) {
697
1089
  consola.error(`[${name}] tab ${targetId.slice(0, 12)}… was created but has no working renderer.\n\n${explainRendererFailure(health)}`);
698
1090
  process.exit(1);
699
1091
  }
700
- consola.warn(`[${name}] tab ${targetId.slice(0, 12)}… did not answer yet (${dead}). Chrome can still create renderers, so this is likely transient — retry the next command.`);
1092
+ consola.warn(`[${name}] tab ${targetId.slice(0, 12)}… did not answer yet (${r.reason ?? r.outcome}). Chrome can still create renderers, so this is likely transient — retry the next command.`);
701
1093
  }
702
1094
  consola.success(`[${name}] opened background tab ${targetId.slice(0, 12)}… → ${url}`);
703
1095
  }
@@ -815,6 +1207,9 @@ const gotoCommand = define({
815
1207
  const target = normalizeUrl(url);
816
1208
  const opts = targetOpts(ctx.values);
817
1209
  const { targetId, created } = await withRendererDiagnosis(() => resolveOrCreateTargetId(opts));
1210
+ if (created) {
1211
+ if ((await ensureRenderer(targetId)).woke) consola.warn("The new tab's renderer did not start on its own, so the tab was activated briefly to force one. The Chrome window was raised and handed straight back.");
1212
+ }
818
1213
  await withRendererDiagnosis(() => navigate(targetId, target));
819
1214
  if (!opts.match && !opts.target) {
820
1215
  const name = opts.session || defaultSessionName();
@@ -2014,6 +2409,10 @@ const listCommand = define({
2014
2409
  type: "boolean",
2015
2410
  description: "Output raw JSON"
2016
2411
  },
2412
+ all: {
2413
+ type: "boolean",
2414
+ description: "Also list stale session bookmarks (tabs that no longer exist), instead of just counting them"
2415
+ },
2017
2416
  frames: {
2018
2417
  type: "boolean",
2019
2418
  description: "Also list cross-origin child iframes (OOPIFs) — their targetIds/URLs let you drive Stripe Elements, embedded SSO widgets, etc. via -F <substr> or -t <id>."
@@ -2032,11 +2431,15 @@ const listCommand = define({
2032
2431
  return;
2033
2432
  }
2034
2433
  const liveIds = new Set(targets.map((t) => t.id));
2035
- if (sessions.length) {
2036
- consola.log(`# sessions (${sessions.length})`);
2037
- for (const s of sessions) consola.log(` ${s.name.padEnd(16)} [${liveIds.has(s.targetId) ? "live" : "stale"}] ${s.url ?? ""}`);
2038
- consola.log("");
2039
- }
2434
+ const live = sessions.filter((s) => liveIds.has(s.targetId));
2435
+ const stale = sessions.filter((s) => !liveIds.has(s.targetId));
2436
+ const shown = ctx.values.all ? sessions : live;
2437
+ if (shown.length) {
2438
+ consola.log(`# sessions (${shown.length}${ctx.values.all ? "" : " live"})`);
2439
+ for (const s of shown) consola.log(` ${s.name.padEnd(16)} [${liveIds.has(s.targetId) ? "live" : "stale"}] ${s.url ?? ""}`);
2440
+ } else if (sessions.length) consola.log(`# sessions (0 live)`);
2441
+ if (stale.length && !ctx.values.all) consola.log(` + ${stale.length} stale bookmark(s) whose tab is gone — \`list --all\` to see them, \`gc --sessions\` to clear them`);
2442
+ if (sessions.length) consola.log("");
2040
2443
  consola.log(`# open tabs (${targets.length}) — address with -t <id> or -m <substr>`);
2041
2444
  for (const t of targets) {
2042
2445
  const owner = sessions.find((s) => s.targetId === t.id);
@@ -2167,13 +2570,17 @@ const launchCommand = define({
2167
2570
  ok: false,
2168
2571
  ms: 0,
2169
2572
  pageTargets: 0,
2170
- reason: String(e?.message ?? e)
2573
+ reason: String(e?.message ?? e),
2574
+ outcome: "error",
2575
+ verdict: "unknown",
2576
+ attempts: []
2171
2577
  }));
2172
2578
  if (health.ok) {
2173
- consola.success(`Renderer capacity: a new tab got a live renderer in ${health.ms}ms — this Chrome works.`);
2579
+ const woke = health.attempts.some((a) => a.woke);
2580
+ consola.success(`Renderer capacity: a new tab got a live renderer in ${health.ms}ms — this Chrome works.` + (woke ? " (It had to be activated to get there — this browser is slow to give background tabs a renderer.)" : ""));
2174
2581
  return;
2175
2582
  }
2176
- consola.error("Chrome is up, but it cannot make renderers — this browser is unusable.\n");
2583
+ consola.error(health.verdict === "wedged" ? "Chrome is up, but it can never make a renderer again — this browser is unusable.\n" : "Chrome is up, but a new tab did not get a working renderer in time.\n");
2177
2584
  for (const line of explainRendererFailure(health).split("\n")) consola.log(line);
2178
2585
  consola.log(`\nChrome's own log: ${chromeLogPath()}`);
2179
2586
  process.exit(1);
@@ -2244,21 +2651,32 @@ const doctorCommand = define({
2244
2651
  ok: false,
2245
2652
  ms: 0,
2246
2653
  pageTargets: 0,
2247
- reason: String(e?.message ?? e)
2654
+ reason: String(e?.message ?? e),
2655
+ outcome: "error",
2656
+ verdict: "unknown",
2657
+ attempts: []
2248
2658
  }));
2249
2659
  if (health.ok) {
2660
+ const woke = health.attempts.some((a) => a.woke);
2250
2661
  ok(`Renderer capacity: a new tab got a live renderer in ${health.ms}ms`);
2251
- const pid = browserPid();
2252
- if (rendezvousRegistered(pid) === false) {
2253
- consola.log(` ⚠ but the Mach rendezvous service for pid ${pid} is NOT registered —`);
2662
+ if (woke) {
2663
+ consola.log(` ⚠ it only answered after being activated — this Chrome is slow to give`);
2664
+ consola.log(` BACKGROUND tabs a renderer (measured: median 367ms, tail past 30s).`);
2665
+ consola.log(` Commands will work; new tabs may briefly raise the Chrome window.`);
2666
+ }
2667
+ const ev = gatherEvidence();
2668
+ if (ev.rendezvous === false) {
2669
+ consola.log(` ⚠ but the Mach rendezvous service for pid ${ev.pid} is NOT registered —`);
2254
2670
  consola.log(` new renderers are expected to start failing. Restart Chrome soon:`);
2255
2671
  consola.log(` browser-automation launch --restart`);
2256
2672
  }
2257
2673
  } else {
2258
- bad(`Renderer capacity: FAILED`);
2674
+ bad(`Renderer capacity: FAILED (${health.verdict})`);
2259
2675
  for (const line of explainRendererFailure(health).split("\n")) consola.log(` ${line}`);
2260
2676
  consola.log(` Chrome's own log: ${chromeLogPath()}`);
2261
2677
  }
2678
+ const stats = recentProbeStats();
2679
+ if (stats) consola.log(` • last ${stats.n} renderer probe(s): ${stats.failures} failed` + (stats.median >= 0 ? `, median ${stats.median}ms, slowest success ${stats.worst}ms` : ""));
2262
2680
  const sessions = listSessions();
2263
2681
  let live = 0;
2264
2682
  try {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@generativereality/browser-automation",
3
- "version": "0.4.11",
3
+ "version": "0.4.12",
4
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.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -11,10 +11,19 @@
11
11
  # A browser process can permanently lose the ability to launch renderers (see
12
12
  # src/core/renderer-health.ts for the mechanism). Every existing tab keeps
13
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.
14
+ # navigation ever will again. Restarting is the only recovery FROM THAT ONE
15
+ # CONDITION — and plain `launch` cannot do it, because it is idempotent by
16
+ # design and correctly reports "already running". Without an explicit flag the
17
+ # only way out was to go and kill Chrome by hand, which is how a diagnosis
18
+ # ends up unactionable.
19
+ #
20
+ # It is a flag and not an automatic step because it closes every tab of every
21
+ # session sharing this browser. That condition is confirmed by ONE thing: the
22
+ # Mach bootstrap name being absent from `launchctl print gui/$UID`. A new tab
23
+ # whose renderer is merely slow to answer looks identical and is not it — for
24
+ # three weeks it was reported as it, and restarting for it twice destroyed
25
+ # another session's unrecoverable work. `browser-automation doctor` now prints
26
+ # which of the two it is; nothing here can tell them apart.
18
27
  #
19
28
  # Why this script exists:
20
29
  # The `browser-automation` skill prefers to drive a real, persistent Chrome
@@ -104,7 +104,7 @@ Page commands take a tab selector — `-s <session>` (default `$BAC_SESSION`, el
104
104
  | Inspect network (find the API, headers, bodies) | `browser-automation network -m bank --reload --filter api --headers --body` |
105
105
  | Screenshot a tab | `browser-automation screenshot -m op.fi --full -o shot.png` |
106
106
  | Prune stale session bookmarks + dead tabs | `browser-automation gc --dry` (then without `--dry`) |
107
- | Restart Chrome (only fix for the renderer wedge — closes ALL tabs) | `browser-automation launch --restart` |
107
+ | Restart Chrome (LAST resort — closes ALL tabs, for EVERY session; only once `doctor` confirms the Mach name is absent) | `browser-automation launch --restart` |
108
108
  | Forget a session (tab stays open) | `browser-automation close -s work` |
109
109
  | Forget **and** close the browser tab | `browser-automation close -s work --tab` |
110
110
 
@@ -287,11 +287,49 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
287
287
  isn't snapshot-interactive. After the drop, `read`/`screenshot`/`network` to
288
288
  confirm processing started, then grab the result (often a download endpoint you
289
289
  can pull with `download --url`).
290
+ - **A NEW tab's renderer can be slow rather than broken — do not restart Chrome for it.**
291
+ ⚠️ **Read this before acting on the wedge diagnosis below.** Measured 2026-09-11 on
292
+ Chrome 152.0.7977.83, time from `Target.createTarget` to the first `Runtime.evaluate`
293
+ returning, 8 trials each:
294
+
295
+ | how the target was created | median | worst |
296
+ |---|---|---|
297
+ | `background: true` (how this tool opens every tab) | 367ms | 12517ms, and >30s once |
298
+ | `background: true` + `Target.activateTarget` | 19ms | 65ms |
299
+ | `background: false` | 18ms | 22ms |
300
+
301
+ The renderer **process exists** in every arm — `ps` gains a `--type=renderer` child either
302
+ way. A background target is simply not given a renderer that answers promptly, and on a
303
+ loaded machine (this one was at load average 38) the tail runs past any budget worth
304
+ waiting. **This is not the wedge**, and a restart does nothing for it.
305
+
306
+ It cost real work to learn: for three weeks `goto` reported this as the permanent,
307
+ restart-only condition below, and `launch --restart` closes every tab of every session
308
+ sharing this Chrome. It twice destroyed unrecoverable work belonging to another session —
309
+ a finished AlternativeTo submission with hand edits, and an Azure signup flow mid-form.
310
+
311
+ **Since fixed (v0.4.12+):** `new`/`goto` wait for a late renderer and, if it still has not
312
+ answered, briefly activate the tab to force one and hand the window straight back (you get
313
+ a `WARN` saying so). The probe retries with a doubling budget, and the verdict now names
314
+ the permanent failure **only when its own signature is present**. On an older CLI, the
315
+ cheap move is to retry, or to drive a tab that already works.
316
+
317
+ **Whatever the version: before restarting anything, check the two corroborations.** Both
318
+ were decisive and neither used to be consulted:
319
+ ```bash
320
+ launchctl print "gui/$(id -u)" | grep MachPortRendezvousServer.<browser-pid>
321
+ ps -Ao command= | grep -c -- '--type=renderer'
322
+ ```
323
+ Mach name **present** + renderers **alive** ⇒ this is slowness, not the wedge. Retry, or use
324
+ a live tab. Mach name **absent** ⇒ it is the wedge, and only then is a restart the answer.
325
+
290
326
  - **"The site is blocking us" — when it is really Chrome that cannot make renderers.**
291
327
  A browser process can permanently lose the ability to launch **renderer processes** while
292
328
  looking perfectly healthy. Every tab that already exists keeps working, so nothing seems wrong
293
329
  until you open a tab or navigate somewhere new, and then the errors read as the remote site's
294
330
  doing. Diagnosed 2026-08-22; it cost an hour of blaming ferry-operator bot protection.
331
+ ⚠️ **This is a real condition and a rare one.** Confirm the Mach name is absent (above)
332
+ before you believe it — a slow background renderer produces every symptom in this list.
295
333
 
296
334
  How it shows up:
297
335
  - `browser-automation new` + `goto` → `CDP Page.enable timed out after 30000ms`, **even for
@@ -366,18 +404,34 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
366
404
  `Page.enable timed out` now arrives with the diagnosis attached instead of sending you to the
367
405
  site's bot-protection docs.
368
406
 
369
- **Recovery — only a Chrome restart clears it.** The bootstrap name is registered at startup and
370
- never re-registered, so nothing short of a new browser process helps. Closing tabs does not, and
371
- plain `launch` will not either (idempotent by design — it sees a live browser and exits happy):
372
- ```bash
373
- browser-automation launch --restart # SIGTERM (profile flushes cleanly), wait, relaunch
374
- ```
375
- It reports how many tabs it is about to close. **Those tabs belong to every parallel Claude Code
376
- session sharing this Chrome — ask Fred first, never restart unilaterally.**
407
+ **Recovery — cheapest first, and a restart only once the Mach name is confirmed absent.**
408
+
409
+ 1. **Retry.** A new tab's renderer has been measured taking 12s and more on a loaded
410
+ machine, and late is not broken.
411
+ 2. **Drive a tab that already works.** An existing tab navigates same-origin without
412
+ needing a new renderer, so it keeps working throughout even during a genuine wedge:
413
+ ```bash
414
+ browser-automation list
415
+ browser-automation eval -t <id> "location.href='<url>'"
416
+ ```
417
+ 3. **`browser-automation doctor`** — re-measures, prints the two corroborations, and shows
418
+ the recent probe-time distribution from `~/.browser-automation/renderer-probes.jsonl`.
419
+ 4. **Only if `doctor` reports the Mach rendezvous service ABSENT**, restart. The bootstrap
420
+ name is registered at startup and never re-registered, so nothing short of a new browser
421
+ process helps; closing tabs does not, and plain `launch` will not either (idempotent by
422
+ design — it sees a live browser and exits happy):
423
+ ```bash
424
+ browser-automation launch --restart # SIGTERM (profile flushes cleanly), wait, relaunch
425
+ ```
426
+ It reports how many tabs it is about to close. **Those tabs belong to every parallel
427
+ Claude Code session sharing this Chrome — ask Fred first, never restart unilaterally.**
377
428
 
378
429
  **Housekeeping is a different problem** — `browser-automation gc` prunes stale session bookmarks
379
430
  (they are never cleaned up otherwise; this machine had accumulated 234, only 5 of them live) and
380
- closes tabs whose renderer does not answer. Use `--dry` first. It is genuinely useful, but it is
431
+ closes tabs whose renderer does not answer. Use `--dry` first. `list` now counts stale
432
+ bookmarks instead of printing them (`list --all` to see them) — 105 stale lines above a
433
+ 24-tab Chrome is how "there are a hundred tabs open" became the leading theory for a
434
+ renderer failure that has nothing to do with tab count. It is genuinely useful, but it is
381
435
  **not** a fix for the wedge above, and it never closes a working tab unless you pass `--orphans`
382
436
  — tabs get addressed by `-m` and opened by hand, so "no session claims it" is not evidence that
383
437
  nobody wants it.