Files
gstack/browse/src/browser-manager.ts
T
Garry Tan 55f8151fbe v1.91.30.0 fix: honest eval failure reports, Bun floor with safe auto-update, make-pdf and /review on Codex (#3033)
* docs: approved reliability follow-ups plan (Oct 2026)

* D1: score overlay wrong answers as comparison results (contract v4)

A completed answer that fails the fixture's output check is now a valid
measurement with taskCorrect false and answerError set, in either arm.
Only execution, scope and metric failures invalidate a trial. ON
correctness still gates the case, so an OFF wrong answer stays in the
comparison. OVERLAY_CONTRACT moves to v4; v3 verdicts are not
reinterpreted. Replays the 37198445662 sonnet trials (OFF-0 wrong).

* C4: score auq-matrix substance with a 3-sample judge panel

Each skill keeps one native capture in the same execution; the
recommendation-substance grader now runs as a JUDGE_PANEL_SAMPLES panel on
that capture and gates on the mean against the unchanged minimum of 4. A
failed sample fails the panel without resampling. Approved at the gate
2026-10-04 for censuses after this change.

* E1: one Bun version source; setup refuses below the 1.3.3 floor, updater checks before advancing

bin/gstack-bun-version.sh holds the security floor (1.3.3) and the tested
version (1.4.0, the CI pin and engines.bun). setup refuses Bun below the
floor before writing anything, warns between floor and tested, warns and
continues on an unparseable version, and prints a 1.4.0 install hint.
Prereleases sort below their release (semver).

gstack-session-update now fetches, reads the incoming release's floor and
checks the bun setup will run before fast-forwarding to that exact
revision; below it the update is held with reason bun-too-old and a
resume command, leaving the revision and installs untouched.

Fixture copies of setup (team-mode, claude-code migration) now include the
sourced file; the slow-git lock test sleeps on fetch, the updater's
network step.

* E3: record the owned Chromium's PID over CDP so the #2709 reap runs on Playwright 1.62

Playwright 1.62's Browser has no process(), so chromiumProcInfo was always
null and browse stop never reaped a surviving headless Chromium. The owned
headless launch now reads the browser PID from CDP SystemInfo.getProcessInfo
(bounded at 2s; a hung or failed call logs once and records nothing). The
reaper's start-time and cmdline identity checks are unchanged, so a recycled
PID or an externally owned browser is never signalled.

* A1: ship docs gate records post-child hashes with gstack-docs-candidate, saves each record once

Stored transcripts (37198445662 gate-census-2) show the parent's reads of
release files take ~1 s; the parent's own model time dominates (completion
268 s of 392 s, store ~270 s of 387 s), and 45-78 s of it is retyping hash
maps, child output and records into several artifacts after the child
returns. The child contract is unchanged.

* A2: /plan-ceo-review sends the mode handoff line before any other tool call

plan-ceo-mode-routing's HOLD SCOPE session spends its 240 s post-selection
window on model work: 37176837432 skipped the handoff helper and paraphrased
the mode, 37198445662 ran it, then wrote the plan, loaded sections and probed
Codex for 114 s before the posture chat. The handoff line is the posture.

* B3: accept wrapped unchanged rows in the cropped Edit preview

PR run 37176835584 timed out with the floor's owned Edit menu on screen:
unchanged diff rows soft-wrap under their gutter with a blank marker
column, and a trimmed empty unchanged row keeps only its number. The
parser accepted wrapped +/- rows only, so it never verified the owned
edit. Both forms are now parsed and still compared with the exact source
lines; the captured viewport is replayed with negative controls.

* A3: record per-phase headroom diagnosis for docsync, plan-mode-no-op, mode-routing and gate slice 11

* E4: /review Step 1 keeps going when the base fetch fails and reports stale base coverage

Under Codex's read-only .git, 'git fetch && merge-base && diff --stat'
stopped at the fetch, so the empty output read as 'Nothing to review'.
The fetch is now separate, prints BASE_REFRESH fresh or stale with the
local base revision, and the review states stale coverage.

* D2: reword the format-approach question prompt

Both plan-ceo-review-format-approach refusals in census 37195203538
(Fable 5.1 model_refusal_no_fallback, category reasoning_extraction:
"duplicating model outputs") were anchored on the session prompt, whose
capture instruction asked for the "verbatim" question and "the exact
prose you would have shown" in a "format-capture test". The approach
case now asks for the same question in the same file as the step's
output, without that wording. The other three plan-format cases keep
their unchanged prompt (no refusals in 72 trials).

* C2: /qa defines its outcome filename fields; QA report templates name the measured timing fields

Low judge samples in failing panels named both: qa workflow (37186854666)
'an undefined {user} in the outcome filename', and qa-only workflow
(37198445662) 'template asks for Duration / durationMs totals while
reporting.md mandates Probe budget and Guarded command time'. The qa
union stays under its 1.11 size ratio (93292 of 93294 bytes).

* 0.1: session ledger written by the claude -p, Agent SDK, PTY and Codex runners

Each armed model session appends one best-effort line to
$GSTACK_EVAL_DIR/session-ledger.jsonl: a stable session key, the timeout it
armed, monotonic elapsed time, its end reason (completed, session_timeout,
observer_timeout, api_error, refusal, aborted, error), one sanitized evidence
line and, for stream-JSON runners, a compact liveness summary (longest
in-request silence with nothing outstanding, last event kind, tool open at
end). Partial messages now stream for every claude -p session and for SDK
sessions without a custom query provider (runSharedInteractive opts in); their
rows feed only the summary, so transcripts keep their size unless
publicStreamDiagnostics is set. Structured refusal and API-error signals win
over phrases, and tool results are never read for them.

* 0.2: failure_cause beside failure_class, from runner facts and the session ledger

One pure failureCauseOf() beside failureClassOf() sets failure_cause
(contract > pre_turn_infra > api_error > refusal > provider_stall >
session_timeout > observer_timeout > assertion > unknown; no machine-set
'detector') with one bounded evidence line, and failureDetailOf() keeps a
Bun matcher's Expected/Received or a judge's failing dimensions in
failure_detail. Both record builders (classifyTrialShard, junitCensus) call
them and attach the trial's ledger sessions. failure_class, error and
TRIAL_ERROR_MAX are computed exactly as before; the new fields are optional,
bounded and validated only when present, and a frozen copy of the v1 reader
accepts every new record. A provider stall needs partial messages and
STALL_WINDOW_MS (120 s, eval-budgets.ts beside HEADROOM_WARN/FAIL) of
in-request silence with nothing outstanding; it stays a failure under
EVAL_POLICY v1.

* E4: fingerprint under a read-only .git via a private object dir owned by review-log

Codex's sandbox mounts .git read-only, so gstack-wtree's git add -A could not
write blobs and /review lost its start capture. gstack-review-log now creates
a private 0700 object directory under TMPDIR, passes it to gstack-wtree (which
writes new objects there with the common-dir object store, resolved before
exporting, as an alternate, so linked worktrees work), exposes it to the
bindReview/checkSharedLibsReuse consumers that read the tree and blobs, and
removes it on EXIT/INT/TERM after they finish. gstack-wtree prints one stderr
line and exits 1 on a failed write or unwritable TMPDIR instead of printing a
partial hash; review-log no longer swallows that line. Standalone gstack-wtree
keeps writing to the repository store so git diff between saved snapshots
(/ship) still works.

* 0.3: red lines name their values, evidence and an after-a-repair command; one published-text sanitizer

Each red line in the census report keeps its stored error and adds the
machine cause with its evidence, the failure_detail values (Expected/Received,
or each failing judge dimension with its mean, sample count and the sample
sentence naming it), the slice artifact and shard directory that hold the
transcript, a fetch command (eval:pass-rates --run <id> --case <id>), and
'after a repair:' with a command that selects only that case (E2E ids via
--case, judges via their selection and an exact test-name filter). A
session that completed and failed a check says so instead of 'assertion
(success)'. Report text that reaches a PR comment, issue or committed file
goes through scripts/lib/published-text.ts: control and bidi characters
stripped, credential-scan patterns redacted, mentions neutralized, HTML and
link brackets escaped inline, blocks in a fence longer than any backtick run,
length capped. Verdicts and collector verdict objects are unchanged.

* E2: one make-pdf resolver for readiness and every $P block on env-var hosts

make-pdf exported $P from its readiness block, which Codex and the other
env-var hosts lose between blocks. binaryAssignment gains 'make-pdf': the
MAKE-PDF SETUP readiness check and the runtime prelude both use it, so every
block that runs $P derives the same make-pdf/dist/pdf binary, with
MAKE_PDF_BIN (dev builds) winning when it is executable. Claude output keeps
its repo-local-first probe; only the false 'subsequent blocks' comment
changed. Root plus P=... fits the 400-byte prelude budget; the fixed
MAKE_PDF_OVERRIDE segment is the one exemption, named in runtime-root.ts and
the conformance test.

* 0.1: eval:pass-rates --headroom, --reds and --run report views; 85% headroom alarm in --gate

A new pure module, scripts/lib/eval-history.ts, reports per case the slowest
armed session against the timeout it armed (censored when it timed out,
insufficient below 3 samples, unknown without a session ledger, with the
case wall shown separately as an upper bound), the census critical path from
the slice jobs' timings, the verdict red ledger per census by failure class
and machine cause with shrunk per-case rates, and the all-green probability
(an approximation: the product of 1 - p_i, with an interval). --run <id>
lists one census's reds with their values and history and downloads only the
slice artifacts those reds name, reporting any over 64 MB instead of skipping
them. eval-flake-rank.ts only routes flags: --help works offline, an unknown
flag or case id exits 2 before any fetch, --case narrows the JSON and the
alarms, every view prints its run/branch scope, and --gate also alarms on a
session above HEADROOM_FAIL (85%) of its budget.

* E5: GSTACK_DESIGN_IMAGE_MODEL override; the live model check always tests the defaults

The image_generation tool model gains an env override validated against a
conservative gpt-image-<version> pattern; a bad value fails before any
request and the error names the variable. Pairing and rejection hints name
the tool model actually requested. design/scripts/live-model-check.ts now
ignores GSTACK_DESIGN_MODEL and GSTACK_DESIGN_IMAGE_MODEL (and says so), so
an override cannot mask a retirement of a default, and its exit 2 (no key)
says nothing was checked.

* C3: /deslop-shared-libs names a concrete risk for each recommendation, never 'none'

Both shared-libs-opportunity-judgment reds (37193478719 t3, 37195203538 t1)
failed adoption_and_risk because the top recommendation said 'Main risk:
none found inside the repo' / 'none in behavior'. The skill asked to 'name
the main risk or uncertainty' without saying what counts.

* B4: --case selects loop-registered cases; an unknown id exits before any process

caseSelection() resolves the one paid file that registers a case and how a
trial selects it: by its literal Bun test name, by the id a registration loop
names its test at runtime (coverage audits, TPA, journeys), or by running the
whole file when it registers no other case (plan-mode-no-op, whose test names
are not the id, so the old name pattern ran nothing). A whole-file case runs
one file shard per trial and is judged by shard status, as CI judges it.
--list prints the selection. Every E2E_TIERS id now resolves except
carve-section-loading, which fifteen files register (CI runs each as its own
shard) and which still fails with the owning files named.

* 0.3: after-a-repair runs the shard file when --case cannot resolve a case

A case that several files register (carve-section-loading) cannot be selected
by --case; its red line now prints the bun test command for the shard file
that went red, so every printed command selects exactly one case.

* C1: pre-register workflow-judge control bundles for qa, qa-only, review and setup-deploy

Positive (production bundle), negative (headings only) and one targeted
execution-blocking defect per judge, one 3-sample panel each, built with the
eval's own reader, prompt builder, options and floors.

* F: cost_known: a trial whose harness captured no billing says so; totals never hide it

cost_usd stays a finite number. Trial and eval records gain an optional
cost_known boolean (absent means known, so old records still parse; the
validator accepts only a boolean). Session-ledger rows record whether the
session's terminal result carried total_cost_usd; PTY and Codex sessions
never do, and SDK captures without a terminal result do not. A trial is
cost-known only when it has eval records and every record and session
captured billing, so JUnit-only PTY cases (125 of 298 trials in run
37198445662 recorded 0) now read cost unknown. The census headline prints the
known sum plus the unknown count, never a bare total over unknown costs, and
no total when every cost is unknown; the history import keeps the flag.
PTY transcripts are not priced: test/helpers/pricing.ts estimates exclude
cache writes, so they cannot give the billed cost.

* B1: replay corpora for the five repeat-offender cases

shared-libs-plan-callers, plan-ceo-section-loading, auto-decide-preserved,
plan-design-review-plan-mode and ship-docsync-late-result each get an
inventory of every wave census in scope (all artifacts still available)
and minimal, redacted detector or actor inputs replayed through the real
detector in the free suite: census passes, every distinct census red, and
derived negative controls labelled as derived. Fixed false reds stay as
expected passes with their history; the two genuine auto-decide product
failures (37176837432, 37179171083) stay refused. A contract test bounds
each entry at 64 KB, scans it for HIGH credentials, requires a pass and a
refusal per case, and reports entries whose series identity is stale.

Building the auto-decide corpus exposed a latent native detector misread:
a bold 'Mode application and rationale.' heading was parsed as a
withdrawn Mode field (37186854666). A field status now ends at its
sentence.

* B2: read approved stale-fill decisions from more valid ledger records

The structured ledger reader is authoritative before the prose fallback,
but it missed two valid approved records in passing censuses
(37186854666: a camelCase writeProfile subject; 37195203538: a
slash-joined 'D1 / STALE-FILL' row id), which then rested on the prose
detector that caused both historical reds. Both forms are accepted; an
unresolved row, an unrelated decision, the copied fixture plan and
non-write camelCase words stay refused.

* C1: record workflow-judge control results (negatives separated; qa and review miss a removed step)

* C2: record every low workflow-judge sample in the wave censuses with its disposition

* 0.3: published lines cannot break a fixed fence

evals.yml wraps collector-outcomes failures in a fixed three-backtick fence
for the PR comment, so those lines (and eval:pass-rates output meant for the
tracking issue) go through sanitizeFixedFenceLine: cleaned like every
published line, with backticks turned into quotes. Inline published text
also neutralizes backticks.

* A1: fit the post-child record wording under ship's 1.428 parity size cap

* E4: inline the Step 1 base refresh to fit review's 1.199 parity size cap

* B2: inventory of gate and periodic phrase-only detector checks

docs/evals/detector-inventory.md lists every pass/fail decision in gate
and periodic E2E cases that rests on phrases in model free text, with
its structured source (if any), whether the contract is user-visible,
and a disposition: already structured-first, convert candidate, phrase
witness required, or no structured source. Convert candidates are
ordered by census red history.

* 0.2: failureCauseOf takes the stall window instead of importing it; the PTY ledger never throws

eval-store.ts imported STALL_WINDOW_MS from eval-budgets.ts, which free tests
replace with mock.module stubs (review-finalization-budget, office-hours,
qa-fix-loop, qa-only), so loading eval-store failed there. failureCauseOf is
now dependency-free: the record builders pass STALL_WINDOW_MS. A PTY session
whose handle cannot show its text (test doubles) records no panel instead of
throwing from runPtySession's cleanup. The 37186854666 replay also runs
through classifyTrialShard.

* A2/auto-decide: the CEO handoff chat repeats the helper's printed line verbatim

Claude Code 2.1.284 collapses the helper's Bash output ('Ran 1 shell
command'), so the 'Auto-decided review mode → …' line reaches the user only
through chat. In lane D's auto-decide-preserved corpus every passing capture's
chat starts with that line, and the reds paraphrased it ('HOLD SCOPE was
auto-selected…', 'Mode decision done…', "I'm defaulting to HOLD SCOPE…").
The template now says verbatim and why.

* C2: record the judge panels rerun on the final ship and review wording

* integrate: touchfiles and module-size ratchet entries for the wave's new modules

GLOBAL_TOUCHFILES gains session-ledger.ts, published-text.ts and
auq-substance-panel.ts; bin/gstack-bun-version.sh joins every entry that
lists setup or the updater; auq-matrix stays a rule case with its C4
evidence beside E2E_KINDS; eval-history, published-text and session-ledger
are registered new modules.

* E1: BROWSE SETUP install hint pins the tested Bun (1.4.0)

* E2: quote "$P" in make-pdf commands so install paths with spaces work

* E1: /gstack-upgrade checks the incoming Bun floor before pulling

gstack_bun_incoming_hold (bin/gstack-bun-version.sh) is now the one
pre-advance check: the auto-updater calls it before its fast-forward and
/gstack-upgrade's git path calls it after fetching. Below the incoming
release's floor the upgrade stops with BUN_TOO_OLD and the checkout,
VERSION and installs stay untouched. Vendored installs were already safe:
setup refuses before writing and the swap restores the previous install.

* 0.3: only main posts or closes tracking issues; reports carry alarms, red ledger, headroom and all-green

A branch-dispatched periodic or marathon run writes its report to the step
summary and a report artifact; the upsert and close steps run only on
refs/heads/main. The periodic body now keeps every pass-rate alarm line (the
old grep kept only the header), adds the red ledger and session headroom read
with an explicit --branch, the all-green estimate and the triage guide link,
and routes report text through scripts/lib/published-text.ts. The marathon
lane gains the matching close-on-green step.

Migrated: evals-workflow-wiring pinned report-summary.md in the upsert step;
the body is now written by 'Write the census report'.

* C3: prosons neutral-posture detector ignores a negated "taste call"

Both plan-review-prosons-neutral-neg reds (37179171083 t3, 37193478719 t3)
recommended A and closed with "a coverage call, not a taste call"; the
old /taste call/i matched the negation. The detector moves to a helper so
the two census captures replay free as negatives, with positive controls.

* B2: credit the CEO mode handoff only when the chat shows its line

Claude Code 2.1.284 collapses the gstack-ceo-mode-handoff Bash result, so
the printed AUTO_DECIDE line is user-visible only when a later chat message
of the session begins with it. The native detector now requires that
witness; the helper's tool result locates it but no longer replaces it, and
a generic mode statement cannot stand in once a handoff ran. Census
37182865432 is relabelled a genuine miss (expected: refused): the chat said
"I'm defaulting to HOLD SCOPE…" and "Mode decided: HOLD SCOPE". Corpus
replay: 5 credited, 3 refused. ceo-mode-handoff tests migrated to the
witness rule (deliberate behavior change).

* test: baseline the wave's approved detector and harness replay tests

B1 corpora, B3, C3, C4 and D2 replay captures through paid-case detectors,
actors or fixtures (test code by design); each entry carries its reason.

* E6: live Codex multi-block periodic case in the host-run Codex job

test/codex-e2e-multiblock-live.test.ts runs ./setup --host codex once from the
job's checkout into a fresh HOME and CODEX_HOME (auth.json copied from the CI
login home), asserts codex debug prompt-input lists the gstack router as a
real file, seeds one learning, and runs /learn's Show recent block through
codex exec: that later block must root itself through its prelude, run the
installed gstack-learnings-search and print the seeded learning; no block may
report a missing install or an unresolved gstack helper path.

The file joins CODEX_CI_FILES so the planner gives it to the host-run Codex
job. paid-test-durations.json carries a 180 s packing estimate (refreshed by
--write-durations after the first census) so the plan keeps every slice
within max-parallel. Oracles live in test/helpers/codex-multiblock.ts with
free replays in test/codex-multiblock.test.ts. Registration (E2E_TOUCHFILES,
E2E_TIERS periodic, E2E_KINDS rule) is the integrator's.

* E5: design live-model check as a periodic case

test/skill-e2e-design-model-smoke.test.ts runs design/scripts/live-model-check.ts
(default models only) under a temp HOME. Without OPENAI_API_KEY the case is a
Bun skip that the census lists as SKIPPED with no coverage credit; with a key,
exit 0 passes and any other exit fails with the script output (exit 2 under a
present key fails as 'nothing was checked'). paid-test-durations.json carries
a 90 s packing estimate. Registration (E2E_TOUCHFILES, E2E_TIERS periodic,
E2E_KINDS rule) is the integrator's.

* A1: docsync parent points children at a saved interface file

The /ship docsync fixture saved its observation interface only in the
parent prompt and told the parent to copy it into every child prompt,
about 30-40 s of parent generation per session (lane S, 37198445662).
docsSessionOptions now writes it to <home>/fixture-interface.md (0600) and
the parent tells each child to Read that file first. Fault-actor prompts,
which prepare already writes to a file, are unchanged. Fixture-only.

* A3: a JUnit case's recorded wall is capped by its shard's wall

junitCensus summed a case's JUnit test times as duration_ms; for
plan-mode-no-op's concurrent PTY tests that is 346 s inside a 176 s shard
(the "432-613 s" history). The case wall headroom shows is now
min(sum, shard elapsed), a true upper bound. Session headroom already
used the ledger's per-session clocks.

* A3: refresh paid-test durations from census 37198445662

Recorded 2026-09-29 estimates under-packed gate slice 11 (17 files
estimated 1078 s ran 1353 s; plan-review-report 76 s -> 198 s,
plan-ceo-plan-mode 37 s -> 112 s, safety-codex-consult 83 s -> 150 s).
Refreshed both tiers with --report --write-durations from the latest
census's slice walls. Old plan re-costed with observed walls: worst slice
~677 s (slice 11); refreshed plan: every slice estimated <= 539 s.

* C2: Browser Quick gets a feasible budget; QA loop names its directory and stop path

Judge rationales on the qa-only panels (2 of the last 3) cited the 30 s
Browser Quick budget: homepage + 5 targets, each a checkpoint write and a
guarded command, left ~5 s per probe. Quick is now 180 s (method text: 3
minutes); the qa-only-no-fix paid check expects the same native deadline.
PROBE_DIR points at its source line, a stopped loop goes to the final
report steps (annotations, materialize, Markdown), and /review and /ship
say that after smoke expiry only plan checks rerun in revalidation.

* C2: name the flows judges found implicit in review resolvers

Structured outside review: MISSING COVERAGE asks no fix question and is
never reported clean (was "preserve the existing user decision flow").
/review's HIGH-impact plan gate: spawned or non-interactive runs report
REQUIREMENTS MISSING and continue, writing no TODOs. Value cards: the byte
clamp applies to card lines; JSON records you write keep full values.

* C1: a free test catches a removed workflow step, which the judges missed

C1 controls showed the qa workflow judge passing /qa without Phase 10 and
the review judge passing /review without Step 3. The new test pins every
step/phase heading of qa, qa-only, review, ship, plan-ceo-review,
plan-eng-review and setup-deploy (derived from the templates' step
headings) and names any that goes missing or out of order; new step
headings must be pinned. The judge rubric is unchanged (EVAL_POLICY).

* size: fit the wave's wording under ship, review and qa parity caps

Measured after all lane merges: ship -79, review -210, qa -68 bytes over.
Trimmed the added wording first (post-expiry rule, MISSING COVERAGE,
plan-gate default, value-card JSON, stop line) and folded /review's
redundant INFORMATIONAL sentence and findings bullet. ship 268,036 (room
8), review 130,118 (room 1). qa needed 11 more bytes: cap 1.11 -> 1.1102
with the measured 93,305 / 84,049 = 1.11013 and its reason beside it.

* docs: troubleshooting sections for the wave's new messages

Bun floor (setup, auto-update, /gstack-upgrade), /review stale base and
fingerprint temp-dir errors, the design image model override, the
unrecorded Chromium PID, and a contributor section for census report
lines (pass-rates flags, failure causes, headroom, cost unknown, overlay
v4, stale corpora, auq substance). A free test checks every
troubleshooting.md#anchor printed by setup or bin scripts exists.

* TODOS: reliability follow-ups deferrals; close the Bun floor, make-pdf $P and #2709 reap

* 0.4: 'A census went red' guide; docs for causes, session ledger, headroom and new messages

docs/evals/census-red.md walks one red line to a diagnosis: prerequisites, the
report fields, eval:pass-rates --run/--reds/--headroom with expected output,
what unknown/insufficient/unrecorded data means, free replay, and the single
'after a repair' paid run allowed by TESTING_INTERNALS. Linked from
CONTRIBUTING, TESTING_INTERNALS and both census reports.

TESTING_INTERNALS documents the failure_cause glossary (one row per
FAILURE_CAUSES value, diagnostic only under EVAL_POLICY v1), failure_detail,
sessions[], cost_known, the session ledger, the pass-rates views and the 85%
headroom alarm, main-only tracking issues, overlay contract v4, auq-matrix's
3-sample substance panel and the E5/E6 periodic cases. troubleshooting.md
gains #bun-too-old and an anchor per new user-facing message from lanes P, D
and F. README names GSTACK_DESIGN_IMAGE_MODEL. test/census-red-docs.test.ts
pins the glossary to FAILURE_CAUSES, parses every guide command and checks the
links.

* v1.91.20.0: CHANGELOG and version for the reliability follow-ups

* regen: SKILL.md and sections for all hosts, digest, context-budget fixture

bun run gen:skill-docs --host all; goldens and llms.txt re-rendered
unchanged; bun test/helpers/capture-context-budget.ts.

* integrate: register codex-multiblock-live and design-model-smoke (periodic, rule)

* 0.4: census report and eval:pass-rates views link the census-red guide

* test: cookie approval fixture reverses the Bun install-hint pin (E1)

The historical approved cookie-workflow prompt carried BUN_VERSION=1.3.10;
the regenerated install hint now pins 1.4.0, so the fixture's reversal
list gains that edit like the earlier waves' entries.

* test: release floor counts the two new periodic cases (E5, E6)

* fix: /freeze, /guard, /unfreeze and /investigate work on Codex and other env-var hosts

Templates quoted "$HOME/.claude/skills/gstack/...", which the env-var hosts'
rewrites turned into "$HOME/.agents/skills/gstack/..." on Codex (a path a
global install never has; same class on the other hosts), and setup's
runtime roots had no freeze/bin. Quoted runtime paths now use
{{RUNTIME_ROOT}}: $GSTACK_ROOT on env-var hosts (the fence gets the
runtime prelude), the unchanged $HOME path on Claude. _link_runtime_dists
links freeze/bin and the careful/bin helper it sources into every
env-var host's root. Also fixes the same guess in /benchmark-models,
/retro and /diagram. test/env-host-runtime-assets.test.ts fails on the
previous code: no fence guesses a $HOME/<dir>/skills/gstack path, every
$GSTACK_ROOT path a fence uses is in the host's runtime root, and the
installed Codex /freeze and /unfreeze fences run from a fresh shell.
Template-reading tests now read the Claude render or expect the
placeholder (deliberate change).

* CHANGELOG/TODOS: lane W's workflow, cases and guide; the env-var host freeze fix

* E6: a block that reads a SKILL.md is not a missing install

The first live codex-multiblock-live run passed its real check (the /learn
block found the install and printed the seeded learning) but the oracle
flagged a sed of the learn SKILL.md, whose prelude source quotes the
'gstack: no install found (tried $_r)' text. Only an emitted line that
starts with the message and names a real root counts now; free replay
negative added.

* test: qa-only fixture keeps its caller-set 30 s deadline

The qa-only-no-fix fixture tells the model to start the guard with 30 s
(a caller limit), so its deadline assertion's default stays 30 000 ms; the
product's Browser Quick default (180 s) does not apply to it. Reverts the
helper and its test to their base.

* C2: keep PROBE_DIR 'owned' (qa-functional-prompt pins it); qa measured 93,311

* test: paid file count and periodic floor include the two new periodic cases

* test: ship docs freshness pin checks meaning after A1's wording trim

The snapshot still hashes selected release paths (--select narrows them),
generated outputs and docs; the pin now checks that instead of the
pre-trim sentence.

* E3: reap the recorded Chromium only after the daemon has exited

With the PID now recorded (E3), browse stop reaped Chromium while the
daemon was still shutting down; the daemon read that as a crash, exited 1
and left its state file (chromium-profile-isolation's headless stop test
failed 3/3 locally, passes on base). The CLI waits up to 5 s for the daemon
to exit before reaping a survivor.

* regen: qa and qa-only exploratory sections (PROBE_DIR wording)

* B1: batching counter reads a target declared mid-line; replay corpus

GSTA-23's census 37228573062 failed plan-eng-multi-finding-batching with
reviewCount=0 after 975 s although D1-D10 were asked one per finding,
each with its saved decision-ledger record. The report wrote 'Report
destination requested by the user. Review target (fixed): `PLAN.md` ...'
and the counter read target fields only at a line start, so no brief
inherited the plan identity. A target field may now open any sentence of
its line; a mid-sentence mention or another file still gives no identity.
Floor (3), budget and kind unchanged. Corpus: 9 earlier passing censuses,
the red (now credited at D5), and a derived batching refusal; 975 s noted
in the headroom diagnosis.

* B1: shared-libs corpus labels its git path and covers the supported shape

Every census entry was recorded in CI's eval image (git 2.43), where
gstack-safe-git falls back because --no-lazy-fetch is rejected; each entry
now says so (git_path: fallback). Two synthetic supported-path entries
(HEAD and a history citation in the brief, as git >= 2.44 produces) keep
the 37193478719 pass and the 37195203538 refusal, and a test asserts both
shapes are covered and the actor reads no git-path-specific text.

* v1.91.21.0: move off v1.91.20.0 (claimed by #3031)

* test: settle nav-guard commands before asserting; make two new tests Windows-safe

navigation-guard: Bun's expect(promise).rejects slows each Playwright round-trip
to ~1s while it waits (50 page.evaluate: 43ms plain vs 46.6s inside the matcher),
so the click's 5s timeout expired before the guard saw the link-local request
(CI: 'click: Timeout 5000ms exceeded ... waiting for scheduled navigations').
Settle the command first, then assert on the refusal; a source check keeps it so.

env-host-runtime-assets: PROBE_FILES now matches either path separator.
detector-corpus ship-docsync-late-result: JSON-escape the <ROOT> substitution so a
Windows temp path's backslashes do not break JSON.parse.

* fix: CI run/job ids are not phone numbers; context-recovery fixture gets the full runtime bin

pii.phone.e164 redacted the run id in the published eval report's fetch command
(--run 37235771700), breaking the command it prints. Digit-only spans in a run/job
flag, gh run argument, actions/runs/ or /job/ URL segment, or run_id/job_id key are
now exempt; the same digits elsewhere still report.

context-recovery-artifacts: the fixture's ./bin/ lacked gstack-skill-start and
gstack-context-recovery (the preamble's runtime scripts since v1.71), so the agent
spent its 10 turns hunting for them and hit error_max_turns with no final message
(run 37235771700, 11 turns). Link the whole runtime bin; diagnostic rerun passed
in 6 turns.

* test: replay run 37237194905's late-result capture through the docs authority detector

The only failure was call 20's write to a mistyped shard root (3GanyY for 3GanyU),
which the model disclosed; the detector is correct and the A1 post-snapshot
--out under the fixture home stays permitted. Named red recorded in TODOS.

* test: keep docsync-authority in the Windows profile

The replay test's literal helper path tripped the Windows curator's shebang-spawn
pattern, dropping the whole file from the Windows profile (test-free-shards
invariant). The snapshot --out case is already covered by docsync-command-grammar,
so it is removed here, and the Linux-path replay skips on win32.

* fix: gstack-docs-candidate --help works; docs gate red lines name the denying tool failure

PR run 37239016858 ship-docsync-completion: the parent ran
'gstack-docs-candidate --help' (the helper's usage error points at --help, which
failed). That undeclared command made docsToolFailures non-empty, which denied
the atomic-replacement proof of the child's legitimate native Edit, so the red
line blamed the Edit's temp file. A replay of the capture proves the atomic
replace once --help is declared.

- the helper prints its usage for --help/-h and exits 0
- the fixture interface and command grammar admit the helper's bare --help
- the atomic-proof denial names its check and the tool failures behind it
  (deny labels renumbered to their lines)
- replay with negative controls (undeclared command, temp left behind, renamed
  elsewhere); diagnostic rerun of ship-docsync-completion passed

* test: retro-base-branch fixture uses main and a shallow report path

PR run 37241493377: the agent wrote retro-output.md one directory above the
requested <tmp>/retro-base/retro-output.md (it dropped the retro-base segment),
so the report check found nothing. The fixture also ran plain git init, which
makes master on CI's git while the prompt says the repo is on main; the agent
logged that mismatch as a learning. Init on main and use the temp dir itself as
the repo. Diagnostic rerun passed (18 turns, 203s).

* test: qa-quick sets a caller probe limit and drains past its session budget

C2 raised Browser Quick's native budget to 180 s. qa-quick is the only gate case
on the native budget, and its wall went 194 s (main periodic, pre-C2) -> 254 s and
274 s (this PR's runs) -> 300 s session timeout (run 37242691913): the agent now
probes every navigation target with a checkpoint, then needs ~80 s to report.
Like qa-only-no-fix, the eval now sets a caller probe limit (30 s), scopes the
fixture, and gives bun's outer timeout the session drain margin instead of racing
the 300 s session. The product's 180 s budget and the session budget are unchanged.
Diagnostic rerun passed in 195 s.

* review/ship: use main's post-expiry smoke sentence; v1.91.24.0

GSTA-23's measurement on the review workflow judge: main's 'Post-expiry smoke
rechecks are not-run.' passed 10/10; the C2 wording passed 6/10 and the
'..., even in 4c.' variant failed in PR run 37248650879. qa-probe-gates pins
main's sentence before step 4c.

* test: record the plan-design corpus test in the test-of-test baseline

#3031's ratchet now counts tests that slice a paid test file's source; the B1
plan-design-review-plan-mode replay corpus reads test/skill-e2e-design.test.ts
like its sibling corpora already listed.

* fix: --case no longer deadlocks importing the running CLI

runCaseDiagnosis loaded runPaidShards with a dynamic import of
scripts/test-paid-shards.ts; when that file is the entry it is still in its
top-level await, so the import never resolved and `--case` hung after its
first line (on main since #3031, found by the per-case measurement runs). The
CLI now passes its runner in; library callers keep the lazy import.

* test: name the in-flight file and the native error when bun dies before its summary (#3037)

* Bun 1.4.2 everywhere CI and setup pin the tested version

Bun 1.4.0 on Windows aborts about 3% of free-suite shards with native
bad-handle errors (main too; #3037); the same head on 1.4.2 had none in 180
shard runs. Every current 1.4.0 pin moves together, as bun-version-drift
requires: setup-bun in every workflow (CSO orchestration included), the eval
image (sha256 from bun-v1.4.2's SHASUMS256.txt, re-hashed locally), GitLab,
the Ubicloud free-suite setup, gstack-bun-version.sh's tested version,
engines.bun and @types/bun, the install hint in generated skills, the Dia and
cookie native-qualification pins, and docs and tests that state the current
pin. Recorded 1.4.0 observations, fixtures, CHANGELOG history and the CSO
images' oven/bun:1.3.10 base stay.

* fix: --case runs a single-case file whole

A session option naming the case (testName: 'office-hours-section-loading')
made caseSelection pick test-name mode, whose filter matched no Bun test, so
every trial would run hollow. A file that registers only this case now runs
whole before any name match is tried.

* fix(office-hours): reviewer returns a hash-bound receipt instead of echoing its verdict

The spec reviewer now Writes its verdict once, seals it with
gstack-office-hours-review seal (validates the saved JSON and prints
OFFICE_HOURS_VERDICT round=N sha256=<hash> path=<verdict>), and returns
only that line. check --receipt recomputes the hash and fails closed on a
missing, malformed, stale-round, wrong-path or mismatched receipt. The
saved file stays the sole findings inventory; validators bind the receipt
to the saved bytes and the judge reads those bytes.

* fix(office-hours): only blocking findings send a design back for another review round

Review findings carry severity blocking|minor (verdict schema v2). PASS when
no blocking findings remain; minor findings are recorded in Reviewer
Concerns and the Spec Review table, never a reason for another round.
CONVERGENCE needs a persisting blocking prior. A persisting or unverified
blocking prior cannot be relabeled minor. The 3-round cap is unchanged.

* fix(office-hours): rounds 2 and 3 are delta re-reviews of the captured design diff

prepare saves each reviewed design as round-N.design.md and gives later
reviewers the exact line diff since the previous round. A new later-round
blocking finding must cite (changed_text) an excerpt of a changed line;
seal, check and the validators verify it against the snapshots and fail
closed when a citation or snapshot is missing. Other new observations are
minor. Severity, anti-downgrade and CONVERGENCE rules are unchanged.

* test(office-hours): preservation judge accepts COMPLETED with recorded minor findings

* fix(office-hours): parent fixes only blocking findings; callers may set --max-rounds

Between rounds the parent edits for blocking findings only; minor findings
stay recorded. gstack-office-hours-review takes --max-rounds 1|2|3 (default
3) on every command; reaching it stops at MAX_ITERATIONS. The marathon
fixture sets 2 rounds so round 1 (full) and round 2 (delta) run live.

* docs(changelog): office-hours review loop changes in v1.91.28.0

* fix(cso): helper JSON keeps run URLs only in the validated workflow slot

The shared redactor now treats GitHub Actions run ids as CI metadata
(c245d1bc2), so main's #3041 invariant that the same run digits stay
redacted outside qualification.workflow held only through the phone
false positive. Make it explicit in the CSO sanitizer.

* test(plan-ceo): split-overflow progress detector accepts the skill's candidate wording

Collection never ended when the model wrote 'E1 Slack:' / 'E1-SLACK:' or
labels like 'Include in this quarter' / 'Defer with flip trigger', so the
session ran the whole review (930-1464 s) and failed on its extra findings
or the case deadline (6 of 21 runs). The candidate check now accepts a
platform-bound E-id and the action is the bucket's leading verb, as the
skill names them (Include/Defer/Cut/Hold). The semantic judge, call floor
and include/defer/cut validation are unchanged. Replays the captured CI
37374526437, t2, t9 and t15 menus with negative controls.

* test(plan-ceo): split-overflow candidate identity is the one E1-E5 token

The skill fixes no header or question wording, and shape-matching kept
missing new forms (header 'D1.1 Slack' with 'SCOPE-E1:', 'D1.1 E1 Slack',
'E1 Slack DM bot ...:', a misspelled 'Mattermst'). Identity is now exactly
one E1-E5 token across the header and the question's first line, with no
other candidate's platform named. Options rules, judge, call floor and
include/defer/cut validation are unchanged. Replays all 31 measured runs;
the quoted-row controls now quote a second ledger id.

* v1.91.30.0: move past #3044's claimed 1.91.29.0

* test: register the split-overflow wording replay as a free fixture

* fix(skills): resolve judge-cited ambiguities in /qa and /plan-eng-review

- tasks JSONL keeps the raw branch as GIT_BRANCH instead of overwriting
  gstack-slug's sanitized BRANCH used for artifact names
- the Codex outside-voice block runs for ready or unverified, matching
  its routing rule
- plan-eng startup names the preamble's own setup prompts; the
  cross-project question waits for Step 0
- /qa 8c: a fix that applies but leaves the finding reproducing gets one
  revised fix, else it is reverted; browser verification names its before
  screenshot; the exploratory loop drops its duplicate 3-step summary

* fix(plan-eng): keep the startup steps in their pinned order

* fix(plan-eng): explicit spawned sessions follow the spawned rule at the scope gate; one announcement rule

A missing tool still sends the prose menu whatever the session type, but a
session the caller or host explicitly marks spawned selects the menu's
Recommendation without prose or BLOCKED. The pre-load announcement
sentence now states Step 0's single check.

* eval policy v3: judge panels gate on the per-dimension median of 3 samples

A judge dimension now passes when at least 2 of its 3 samples meet the
unchanged threshold (judgePanelMedian); any other sample count or a
non-numeric sample fails closed. Thresholds, sample count, judge model and
prompts are unchanged; panel logs show every sample and the mean, and name
the median as the gate. Applies to the skill-llm-eval panels, the
workflow-judge cache, the auq-matrix substance panel and the calibration
replicas. EVAL_POLICY 2 -> 3 and HARNESS_VERSION 1 -> 2 (verdicts change),
so every case starts a new pass-rate series. Replays the captured panels
from jobs 112032744416 and 112049856586 as replayed evidence.
2026-10-06 18:07:50 +00:00

2300 lines
98 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* Browser lifecycle manager
*
* Chromium crash handling:
* browser.on('disconnected') → log error → process.exit(1)
* CLI detects dead server → auto-restarts on next command
* We do NOT try to self-heal — don't hide failure.
*
* Dialog handling:
* page.on('dialog') → auto-accept by default → store in dialog buffer
* Prevents browser lockup from alert/confirm/prompt
*
* Context recreation (useragent):
* recreateContext() saves cookies/storage/URLs, creates new context,
* restores state. Falls back to clean slate on any failure.
*/
import type { ChildProcess } from 'node:child_process';
import { chromium, type Browser, type BrowserContext, type BrowserContextOptions, type Page, type Locator, type Cookie } from 'playwright';
import { writeSecureFile, mkdirSecure } from './file-permissions';
import { addConsoleEntry, addNetworkEntry, addDialogEntry, networkBuffer, type DialogEntry } from './buffers';
import { emitActivity } from './activity';
import { validateNavigationUrl, blockedNavigationReason } from './url-validation';
import { TabSession, type RefEntry } from './tab-session';
import { resolveChromiumProfile, cleanSingletonLocks, resolveConfig } from './config';
import { ensureProjectProfile } from './chromium-profiles';
import { launchWithXProtectHeal } from './xprotect-heal';
import { readPidStartTime, shouldSpawnXvfb, spawnFreeXvfb, xvfbInstallHint, type XvfbHandle } from './xvfb';
import { withCdpSession } from './cdp-bridge';
import type { MemorySnapshot, MemoryStructureStats, MemoryTabSnapshot, MemoryProcess } from './memory-snapshot';
/**
* Headless GPU flags (#2709): on macOS 26 / Apple Silicon the headless-shell
* GPU process can peg ~800% CPU indefinitely after real page work, and
* --disable-gpu alone is not enough — the software-compositing GPU process
* still spawns and still spins. The reporter validated this exact flag set
* drops it to 0.0% with screenshots still working. darwin-gated: on Linux CI
* and Windows the GPU process behaves, and the flags are a mild automation
* tell. GSTACK_DISABLE_GPU=off opts out. Pure function (platform + env
* injected) so the darwin behavior is unit-testable on any host. Deliberately
* NOT in buildGStackLaunchArgs: that feeds the headed/GBrowser paths too,
* where GPU-off is user-visibly wrong.
*/
export function headlessGpuArgs(platform: string, env: NodeJS.ProcessEnv): string[] {
if (platform !== 'darwin') return [];
if ((env.GSTACK_DISABLE_GPU || '').toLowerCase() === 'off') return [];
return [
'--disable-gpu',
'--disable-software-rasterizer',
'--disable-gpu-compositing',
'--disable-gpu-watchdog',
];
}
/**
* Detect whether GSTACK_CHROMIUM_PATH points at a custom Chromium build that
* already bakes the gstack extension in as a component extension (e.g.,
* GStack Browser.app / GBrowser). Passing --load-extension against such a
* binary triggers a ServiceWorkerState::SetWorkerId DCHECK because two
* copies of the same service worker try to register.
*
* Resolution:
* 1. GSTACK_CHROMIUM_KIND === 'custom-extension-baked' (preferred, explicit)
* 2. GSTACK_CHROMIUM_PATH path substring contains 'GBrowser' or 'gbrowser'
* (fallback for callers that only set the path)
*/
export function isCustomChromium(): boolean {
if (process.env.GSTACK_CHROMIUM_KIND === 'custom-extension-baked') return true;
const p = process.env.GSTACK_CHROMIUM_PATH || '';
return p.includes('GBrowser') || p.includes('gbrowser');
}
/**
* Decide whether Playwright should request Chromium's sandbox.
*
* Returns false on Windows (Bun→Node→Chromium chain breaks the sandbox,
* GitHub #276) and on Linux under root / CI / container (sandbox needs
* unprivileged user namespaces, which are missing for root and typically
* disabled in containers).
*
* When false, Playwright auto-adds --no-sandbox to the launch args — the
* desired behavior in those environments. When true, Playwright does NOT
* add --no-sandbox, which keeps Chromium's "unsupported command-line flag"
* yellow infobar from appearing on every headed launch.
*
* The headless launch path also pushes an explicit '--no-sandbox' into args
* when CI/CONTAINER/root is set; that push is now defensively redundant
* (Playwright will add it anyway when this returns false) and harmless.
*/
export function shouldEnableChromiumSandbox(): boolean {
if (process.platform === 'win32') return false;
// Explicit user override for Ubuntu/AppArmor and similar environments where
// unprivileged Chromium sandboxing is blocked even for normal users (the
// sandbox needs unprivileged user namespaces that the host policy denies,
// so /qa hangs without --no-sandbox). Setting GSTACK_CHROMIUM_NO_SANDBOX=1
// forces the sandbox off without changing the default for everyone else.
// See #1562.
if (process.env.GSTACK_CHROMIUM_NO_SANDBOX === '1') return false;
const isRoot = typeof process.getuid === 'function' && process.getuid() === 0;
return !(process.env.CI || process.env.CONTAINER || isRoot);
}
/**
* Thrown by probePoisonedChromiumBundle() when it finds — and removes — a
* Chromium bundle poisoned by the pre-v1.64 in-place rebrand (#2242).
* Call sites rethrow on `instanceof` (never message-string sniffing) so the
* actionable remediation reaches the user instead of being swallowed by the
* probe's fall-through-on-failure catch.
*/
export class PoisonedBundleError extends Error {
constructor(message: string) {
super(message);
this.name = 'PoisonedBundleError';
}
}
/**
* Self-heal probe for bundles the OLD (pre-v1.64) rebrand code already
* poisoned (#2242): the mutation lives in the SHARED Playwright cache, so
* deleting the rebrand code fixes fresh installs only, and the documented
* deploy paths never run upgrade migrations. Detect the mutated plist and
* remove the bundle so the next `playwright install chromium` (or the
* upgrade migration) re-fetches a clean one.
*
* Removal scope: when the .app sits in the standard Playwright cache layout
* (chromium-<rev>/chrome-mac/<name>.app), the WHOLE chromium-<rev> revision
* dir is removed — Playwright's INSTALLATION_COMPLETE marker lives there,
* and `playwright install chromium` treats its presence as "is already
* downloaded", so removing only the .app would turn our own remediation
* command into a no-op that leaves the user with no browser at all. Outside
* that layout, the .app plus any sibling INSTALLATION_COMPLETE /
* DEPENDENCIES_VALIDATED markers are removed.
*
* Caller contract: pass ONLY Playwright-cache executables
* (chromium.executablePath()). A bundle supplied via GSTACK_CHROMIUM_PATH
* belongs to the wrapper/embedder — its plist legitimately says "GStack
* Browser" — and must never be deleted. Both call sites (launchHeaded and
* handoff) honor this, and as a second belt the probe refuses to act on the
* GSTACK_CHROMIUM_PATH executable itself.
*
* @param chromiumExecutablePath the Chromium binary inside the .app
* (…/<name>.app/Contents/MacOS/<name>), as returned by
* chromium.executablePath().
* @throws PoisonedBundleError after removing a poisoned bundle — the
* message carries the re-fetch command for the user.
*/
export function probePoisonedChromiumBundle(chromiumExecutablePath: string): void {
const fs = require('fs');
const path = require('path');
// Belt to the caller contract: never act on the custom/embedder bundle.
const customPath = process.env.GSTACK_CHROMIUM_PATH;
if (customPath && path.resolve(chromiumExecutablePath) === path.resolve(customPath)) {
return;
}
const chromeContentsDir = path.resolve(path.dirname(chromiumExecutablePath), '..');
const chromePlist = path.join(chromeContentsDir, 'Info.plist');
if (!fs.existsSync(chromePlist)) return;
if (!fs.readFileSync(chromePlist, 'utf-8').includes('GStack Browser')) return;
const appDir = path.resolve(chromeContentsDir, '..');
const revisionDir = path.resolve(appDir, '..', '..');
if (/^chromium-\d+$/.test(path.basename(revisionDir))) {
fs.rmSync(revisionDir, { recursive: true, force: true });
} else {
fs.rmSync(appDir, { recursive: true, force: true });
for (const marker of ['INSTALLATION_COMPLETE', 'DEPENDENCIES_VALIDATED']) {
fs.rmSync(path.join(path.dirname(appDir), marker), { force: true });
}
}
throw new PoisonedBundleError(
'Chromium bundle was mutated by a previous gstack version (broken codesign seal — ' +
'GPU exit_code=5 on macOS 26). The poisoned bundle has been removed. ' +
'Re-fetch a clean one with: bunx playwright install chromium — then retry.',
);
}
/** Playwright's public Browser type omits `process()`, which only browsers we launched provide. */
function launchedProcess(browser: Browser | null | undefined): ChildProcess | null {
const withProcess = browser as (Browser & { process?: () => ChildProcess | null }) | null | undefined;
return typeof withProcess?.process === 'function' ? withProcess.process() : null;
}
/**
* #2709: PID of the Chromium browser process gstack launched, read over CDP
* (`SystemInfo.getProcessInfo`, type "browser") because Playwright 1.62's
* Browser has no `process()`. Call it only for a launch gstack owns; a
* connected browser belongs to someone else and must never be reaped. Bounded:
* a hung or failed CDP call logs once and returns null, which means no reap.
*/
export async function launchedChromiumPid(browser: Browser, timeoutMs = 2_000): Promise<number | null> {
let timer: ReturnType<typeof setTimeout> | undefined;
const query = async (): Promise<number | null> => {
const session = await browser.newBrowserCDPSession();
try {
const { processInfo } = await session.send('SystemInfo.getProcessInfo');
const pid = processInfo.find((p) => p.type === 'browser')?.id;
return Number.isInteger(pid) && pid! > 0 ? pid! : null;
} finally {
await session.detach().catch(() => {});
}
};
try {
return await Promise.race([
query(),
new Promise<never>((_, reject) => {
timer = setTimeout(() => reject(new Error(`timed out after ${timeoutMs}ms`)), timeoutMs);
}),
]);
} catch (err) {
const msg = err instanceof Error ? err.message : String(err);
console.warn(`[browse] Could not record the Chromium PID (CDP SystemInfo.getProcessInfo: ${msg}); browse stop cannot reap a surviving Chromium.`);
return null;
} finally {
clearTimeout(timer);
}
}
/**
* Resolve why the underlying Chromium ChildProcess is going away.
*
* The 'disconnected' Playwright event fires before the child process emits
* its own 'exit' in most cases, so .exitCode is null at that moment. Wait
* briefly (capped at 1s) for the exit then read .exitCode + .signalCode:
*
* exitCode === 0 && no signal → 'clean' (user Cmd+Q, normal shutdown)
* anything else → 'crash' (signal-kill, SIGSEGV, OOM, non-zero exit)
*
* Process supervisors (gbrowser's gbd HealthMonitor in cmd/gbd/health.go)
* read our exit code to decide whether to restart. The two callers in this
* file ride on top of this: a 'clean' result exits with code 0 (gbd skips
* restart, treats as user-intent); a 'crash' result keeps the existing
* per-path exit semantics (launch→1, launchHeaded→2, handoff→1) and gbd
* restarts on backoff.
*/
export async function resolveDisconnectCause(browser: Browser | null): Promise<'clean' | 'crash'> {
// `.process()` only exists on browsers we launched ourselves. A browser
// obtained via connectOverCDP() (or a stub in tests) has no such method —
// calling it blind throws inside the disconnect handler, which killed the
// whole daemon with "browser?.process is not a function".
const proc = launchedProcess(browser);
if (proc && proc.exitCode === null && proc.signalCode === null) {
await new Promise<void>((resolve) => {
const timer = setTimeout(resolve, 1000);
proc.once('exit', () => {
clearTimeout(timer);
resolve();
});
});
}
return proc?.exitCode === 0 && proc?.signalCode == null ? 'clean' : 'crash';
}
/**
* Exit-on-disconnect is DAEMON-ONLY semantics. The standalone server
* entrypoint opts in via markDaemonProcess() (under its import.meta.main
* gate, same contract as its signal handlers); embedders — gbrowser
* phoenix, and every test that launches a BrowserManager in-process —
* must never have a Chromium crash process.exit() their HOST. Observed
* live before this flag: a test-launched browser died mid-suite and the
* exit(1) killed the whole bun shard with no terminal summary (the
* truncation class the strict runner exists to catch).
*/
let daemonProcess = false;
export function markDaemonProcess(): void {
daemonProcess = true;
}
/**
* Headless `launch()` disconnect handler. In the standalone daemon: exits 0
* on clean user-quit, 1 on crash. Embedded contexts get the log line only.
* Inlined into the launch() body via a one-line dispatch so
* browser-manager's flow stays grep-friendly.
*/
export async function handleChromiumDisconnect(browser: Browser | null): Promise<void> {
const cause = await resolveDisconnectCause(browser);
if (!daemonProcess) {
console.error(`[browse] Chromium disconnected (${cause}) in an embedded context — host process continues.`);
return;
}
if (cause === 'clean') {
console.error('[browse] Chromium closed cleanly (user-initiated quit). Server exiting (0).');
process.exit(0);
}
console.error('[browse] FATAL: Chromium process crashed or was killed. Server exiting (1).');
console.error('[browse] Console/network logs flushed to .gstack/browse-*.log');
process.exit(1);
}
export type { RefEntry };
// Re-export TabSession for consumers
export { TabSession };
export interface BrowserState {
cookies: Cookie[];
pages: Array<{
url: string;
isActive: boolean;
storage: { localStorage: Record<string, string>; sessionStorage: Record<string, string> } | null;
/**
* HTML content loaded via load-html (setContent), replayed after context recreation.
* In-memory only — never persisted to disk (HTML may contain secrets or customer data).
*/
loadedHtml?: string;
loadedHtmlWaitUntil?: 'load' | 'domcontentloaded' | 'networkidle';
/**
* Tab owner clientId for multi-agent isolation. Survives context recreation so
* scoped agents don't get locked out of their own tabs after viewport --scale.
* In-memory only.
*/
owner?: string;
}>;
}
export class BrowserManager {
private browser: Browser | null = null;
private context: BrowserContext | null = null;
// Proxy config applied to chromium.launch() when set (D8). Set by server.ts
// at startup based on BROWSE_PROXY_URL. For SOCKS5 with auth, server.ts
// points this at the local bridge (socks5://127.0.0.1:<bridgePort>); for
// HTTP/HTTPS or unauth SOCKS5, it's the upstream URL directly.
private proxyConfig: { server: string; username?: string; password?: string } | null = null;
private pages: Map<number, Page> = new Map();
private tabSessions: Map<number, TabSession> = new Map();
private activeTabId: number = 0;
private nextTabId: number = 1;
private extraHeaders: Record<string, string> = {};
private customUserAgent: string | null = null;
// #2709: identity of the Chromium child WE launched (headless path). The
// headless launch has no userDataDir, so killOrphanChromium's SingletonLock
// walk is a structural no-op for it — `browse stop` reported success while
// the orphaned GPU process kept spinning. PID alone is not identity (reuse);
// start time makes the later reap safe (same contract as xvfbPid/xvfbStartTime).
private chromiumProcInfo: { pid: number; startTime: string } | null = null;
/** PID + start-time of the launched Chromium child, when we own one. */
getChromiumProcInfo(): { pid: number; startTime: string } | null {
return this.chromiumProcInfo;
}
// ─── Viewport + deviceScaleFactor (context options) ──────────
// Tracked at the manager level so recreateContext() preserves them.
// deviceScaleFactor is a *context* option, not a page-level setter — changes
// require recreateContext(). Viewport width/height can change on-page, but we
// track the latest so context recreation restores it instead of hardcoding 1280x720.
private deviceScaleFactor: number = 1;
private currentViewport: { width: number; height: number } = { width: 1280, height: 720 };
/** Server port — set after server starts, used by cookie-import-browser command */
public serverPort: number = 0;
// ─── Tab Ownership (multi-agent isolation) ──────────────
// Maps tabId → clientId. Unowned tabs (not in this map) are root-only for writes.
private tabOwnership: Map<number, string> = new Map();
/** Headless launch with BROWSE_EXTENSIONS_DIR: a persistent context (#2281). */
private extensionContext = false;
/** Pending and recorded navigation-guard verdicts per page (D2). */
private navigationGuards = new WeakMap<Page, { pending: Set<Promise<void>>; blocked: string | null }>();
// Our own 'disconnected' listeners per browser. Detach only these: removing
// every 'disconnected' listener also strips Playwright's internal one that
// resolves browser.close(), so each close waited the full race timeout (and
// Playwright 1.62 has no Browser.process() for the SIGKILL fallback).
private disconnectHandlers = new WeakMap<Browser, Array<() => void>>();
private onBrowserDisconnected(browser: Browser | null | undefined, handler: () => void): void {
if (!browser) return;
browser.on('disconnected', handler);
this.disconnectHandlers.set(browser, [...(this.disconnectHandlers.get(browser) ?? []), handler]);
}
private detachDisconnectHandlers(browser: Browser | null | undefined): void {
if (!browser) return;
for (const handler of this.disconnectHandlers.get(browser) ?? []) browser.off('disconnected', handler);
this.disconnectHandlers.delete(browser);
}
// ─── Dialog Handling (global, not per-tab) ──────────────────
private dialogAutoAccept: boolean = true;
private dialogPromptText: string | null = null;
// ─── Cookie Origin Tracking ────────────────────────────────
private cookieImportedDomains: Set<string> = new Set();
// ─── Handoff State ─────────────────────────────────────────
private isHeaded: boolean = false;
private consecutiveFailures: number = 0;
// ─── Watch Mode ─────────────────────────────────────────
private watching = false;
public watchInterval: ReturnType<typeof setInterval> | null = null;
private watchSnapshots: string[] = [];
private watchStartTime: number = 0;
// ─── Headed State ────────────────────────────────────────
private connectionMode: 'launched' | 'headed' = 'launched';
/**
* Fired when a RUNNING daemon is promoted to headed mode (see handoff()),
* as opposed to starting headed. The server uses it to cancel the
* parent-process watchdog, which was registered on the assumption that mode
* is fixed at boot and would otherwise kill the freshly handed-off browser
* the next time the spawning shell exits.
*/
onHeadedPromotion?: () => void;
private intentionalDisconnect = false;
private xvfb: XvfbHandle | null = null;
private displayAllocation: Promise<void> | null = null;
private handoffPending: Promise<string> | null = null;
private closing = false;
private handoffPrevious: { browser: Browser; pages: Map<number, Page>; tabSessions: Map<number, TabSession>; activeTabId: number } | null = null;
getXvfbHandle(): XvfbHandle | null { return this.xvfb; }
async ensureHeadedDisplay(): Promise<void> {
if (this.closing) throw new Error('Browser is shutting down');
if (this.xvfb) return;
if (this.displayAllocation) return this.displayAllocation;
if (!shouldSpawnXvfb({ ...process.env, BROWSE_HEADED: '1' }, process.platform).spawn) return;
this.displayAllocation = (async () => {
try {
const handle = await spawnFreeXvfb();
if (this.closing) {
handle.close();
throw new Error('Browser is shutting down');
}
this.xvfb = handle;
} catch (err) {
throw new Error(`${err instanceof Error ? err.message : String(err)}. ${xvfbInstallHint()}`);
}
})();
try { await this.displayAllocation; }
finally { this.displayAllocation = null; }
}
closeOwnedDisplay(): void {
this.xvfb?.close();
this.xvfb = null;
}
// ─── Tab Count Guardrail (D5 + Codex single-tab flag) ───────
// Idempotent threshold trackers: each guardrail fires exactly once per
// upward crossing of its threshold and re-arms when the tab count drops
// back below. Pre-guardrail, nothing tracked tab count growth and a
// user could accumulate hundreds of tabs (each holding 50–300 MB of
// Chromium-side RSS) without warning until the OS OOM-killer fired.
// The toast UX lives in the sidebar (extension/sidepanel.js); the
// server-side responsibility is the audit-trail activity entry that
// appears in the activity feed even when the sidebar is closed.
private static readonly TAB_GUARDRAIL_SOFT = 50;
private static readonly TAB_GUARDRAIL_HARD = 200;
private tabGuardrailSoftHit = false;
private tabGuardrailHardHit = false;
/**
* Called from context.on('page') after a new tab is tracked. Emits at
* most one activity entry per upward crossing of each threshold.
*/
private checkTabGuardrails(): void {
const total = this.pages.size;
if (!this.tabGuardrailSoftHit && total >= BrowserManager.TAB_GUARDRAIL_SOFT) {
this.tabGuardrailSoftHit = true;
const msg = `Tab count crossed ${BrowserManager.TAB_GUARDRAIL_SOFT} (now ${total}). Consider closing unused tabs — each Chromium tab holds 50–300 MB.`;
console.warn(`[browse] ${msg}`);
emitActivity({ type: 'error', command: 'tab-guardrail', error: msg, tabs: total });
}
if (!this.tabGuardrailHardHit && total >= BrowserManager.TAB_GUARDRAIL_HARD) {
this.tabGuardrailHardHit = true;
const msg = `Tab count crossed ${BrowserManager.TAB_GUARDRAIL_HARD} (now ${total}). OOM risk imminent. Open the sidebar to see top RAM consumers.`;
console.error(`[browse] ${msg}`);
emitActivity({ type: 'error', command: 'tab-guardrail', error: msg, tabs: total });
}
}
/** Called from page.on('close') so the guardrails re-arm. */
private recheckTabGuardrailsOnClose(): void {
const total = this.pages.size;
if (this.tabGuardrailSoftHit && total < BrowserManager.TAB_GUARDRAIL_SOFT) {
this.tabGuardrailSoftHit = false;
}
if (this.tabGuardrailHardHit && total < BrowserManager.TAB_GUARDRAIL_HARD) {
this.tabGuardrailHardHit = false;
}
}
// Called when the headed browser disconnects without intentional teardown
// (user closed the window). Wired up by server.ts to run full cleanup
// (terminal agent, state file, profile locks) before exiting with code 2.
// Returns void or a Promise; rejections are caught and fall back to exit(2).
// `exitCode` is the resolved process exit code from the disconnect cause:
// 0 on clean user-initiated quit (e.g., Cmd+Q on headed Chromium), 2 on
// crash/signal-kill. Callers (server.ts) forward it to their shutdown
// pipeline so process supervisors (gbrowser's gbd) read the right signal.
public onDisconnect: ((exitCode?: number) => void | Promise<void>) | null = null;
getConnectionMode(): 'launched' | 'headed' { return this.connectionMode; }
// ─── Watch Mode Methods ─────────────────────────────────
isWatching(): boolean { return this.watching; }
startWatch(): void {
this.watching = true;
this.watchSnapshots = [];
this.watchStartTime = Date.now();
}
stopWatch(): { snapshots: string[]; duration: number } {
this.watching = false;
if (this.watchInterval) {
clearInterval(this.watchInterval);
this.watchInterval = null;
}
const snapshots = this.watchSnapshots;
const duration = Date.now() - this.watchStartTime;
this.watchSnapshots = [];
this.watchStartTime = 0;
return { snapshots, duration };
}
addWatchSnapshot(snapshot: string): void {
this.watchSnapshots.push(snapshot);
}
/**
* Find the gstack Chrome extension directory.
* Checks: repo root /extension, global install, dev install.
*/
private findExtensionPath(): string | null {
const fs = require('fs');
const path = require('path');
const candidates = [
// Explicit override via env var (used by GStack Browser.app bundle)
process.env.BROWSE_EXTENSIONS_DIR || '',
// Relative to this source file (dev mode: browse/src/ -> ../../extension)
path.resolve(__dirname, '..', '..', 'extension'),
// Global gstack install
path.join(process.env.HOME || '', '.claude', 'skills', 'gstack', 'extension'),
// Git repo root (detected via BROWSE_STATE_FILE location)
(() => {
const stateFile = process.env.BROWSE_STATE_FILE || '';
if (stateFile) {
const repoRoot = path.resolve(path.dirname(stateFile), '..');
return path.join(repoRoot, '.claude', 'skills', 'gstack', 'extension');
}
return '';
})(),
].filter(Boolean);
for (const candidate of candidates) {
try {
if (fs.existsSync(path.join(candidate, 'manifest.json'))) {
return candidate;
}
} catch (err: any) {
if (err?.code !== 'ENOENT' && err?.code !== 'EACCES') throw err;
}
}
return null;
}
/**
* Set the proxy config applied to chromium.launch() in launch() and
* launchHeaded(). Called by server.ts at startup once the (optional) SOCKS5
* bridge is up.
*/
setProxyConfig(cfg: { server: string; username?: string; password?: string } | null): void {
this.proxyConfig = cfg;
}
/**
* Get the ref map for external consumers (e.g., /refs endpoint).
*/
getRefMap(): Array<{ ref: string; role: string; name: string }> {
try {
return this.getActiveSession().getRefEntries();
} catch {
return [];
}
}
async launch() {
this.closing = false;
// ─── Extension Support ────────────────────────────────────
// BROWSE_EXTENSIONS_DIR points to an unpacked Chrome extension directory.
// Extensions only run in a persistent context (launch() + newContext()
// isolates them), so that path uses launchPersistentContext with Chrome's
// new headless mode: no window, unlike the old off-screen window that
// macOS still showed (#2281, #432).
const extensionsDir = process.env.BROWSE_EXTENSIONS_DIR;
const { STEALTH_LAUNCH_ARGS, buildGStackLaunchArgs, STEALTH_IGNORE_DEFAULT_ARGS } = await import('./stealth');
const launchArgs: string[] = [...STEALTH_LAUNCH_ARGS, ...buildGStackLaunchArgs()];
// #2771/#1968: honor GSTACK_CHROMIUM_PATH headless too (NixOS, macOS 13).
// That bundle belongs to the user, so the XProtect heal never touches it,
// and a launch failure names it.
const executablePath = process.env.GSTACK_CHROMIUM_PATH || undefined;
const nameCustomChromium = (err: unknown): never => {
if (!executablePath) throw err;
const message = err instanceof Error ? err.message : String(err);
throw new Error(`Chromium at GSTACK_CHROMIUM_PATH=${executablePath} failed to launch: ${message}\nFix: point GSTACK_CHROMIUM_PATH at a working Chromium or Chrome binary, or unset it to use Playwright's bundled Chromium.`, { cause: err });
};
// Docker/CI/root: Chromium sandbox requires unprivileged user namespaces which
// are typically disabled in containers and are never available for the root
// user on Linux. Detect all three cases and add --no-sandbox automatically.
const isRoot = typeof process.getuid === 'function' && process.getuid() === 0;
if (process.env.CI || process.env.CONTAINER || isRoot) {
launchArgs.push('--no-sandbox');
}
if (extensionsDir) {
// Skip --load-extension when running against a custom Chromium build that
// already bakes the extension in (e.g., GBrowser / GStack Browser.app).
// Loading it twice causes a ServiceWorkerState::SetWorkerId DCHECK crash.
if (!isCustomChromium()) {
launchArgs.push(
`--disable-extensions-except=${extensionsDir}`,
`--load-extension=${extensionsDir}`,
);
}
launchArgs.push('--headless=new');
console.log(`[browse] Extensions loaded from: ${extensionsDir}`);
}
// #2709: headless-only GPU flags; headed/GBrowser sessions keep the GPU.
launchArgs.push(...headlessGpuArgs(process.platform, process.env));
const contextOptions: BrowserContextOptions = {
viewport: { width: this.currentViewport.width, height: this.currentViewport.height },
deviceScaleFactor: this.deviceScaleFactor,
};
if (this.customUserAgent) {
contextOptions.userAgent = this.customUserAgent;
}
if (extensionsDir) {
const profileDir = require('path').join(resolveConfig().stateDir, 'extensions', 'chromium-profile');
require('fs').mkdirSync(profileDir, { recursive: true, mode: 0o700 });
cleanSingletonLocks(profileDir);
this.context = await launchWithXProtectHeal(() => chromium.launchPersistentContext(profileDir, {
headless: false, // --headless=new in launchArgs: windowless, extensions run
handleSIGINT: false,
handleSIGTERM: false,
handleSIGHUP: false,
chromiumSandbox: shouldEnableChromiumSandbox(),
args: launchArgs,
ignoreDefaultArgs: STEALTH_IGNORE_DEFAULT_ARGS,
...contextOptions,
...(executablePath ? { executablePath } : {}),
...(this.proxyConfig ? { proxy: this.proxyConfig } : {}),
}), { usesCustomExecutable: Boolean(executablePath) }).catch(nameCustomChromium);
this.extensionContext = true;
this.browser = this.context.browser();
this.onBrowserDisconnected(this.browser, () => {
void handleChromiumDisconnect(this.browser);
});
for (const page of this.context.pages()) await page.close().catch(() => {});
if (Object.keys(this.extraHeaders).length > 0) {
await this.context.setExtraHTTPHeaders(this.extraHeaders);
}
const { applyStealth } = await import('./stealth');
await applyStealth(this.context);
await this.newTab();
return;
}
// XProtect self-heal wrapper (P0 #2554): a macOS definition update can
// start SIGKILLing the pinned Chromium at spawn. On the classified
// signature, clear quarantine on the Playwright cache + force-reinstall
// once, then retry this launch once. A GSTACK_CHROMIUM_PATH bundle is
// scoped out of the heal.
this.browser = await launchWithXProtectHeal(() => chromium.launch({
headless: true,
// #2220: the daemon owns signal policy, not Playwright. Playwright's
// default handlers close Chromium the moment THIS process receives
// SIGINT/SIGTERM/SIGHUP — which fights the deliberate headless
// SIGTERM-ignore in server.ts (the daemon survives the signal but
// loses its browser out from under it). All three are false; server.ts
// routes the signals it actually honors through activeShutdown, which
// closes Chromium itself.
handleSIGINT: false,
handleSIGTERM: false,
handleSIGHUP: false,
// On Windows, Chromium's sandbox fails when the server is spawned through
// the Bun→Node process chain (GitHub #276). Disable it — local daemon
// browsing user-specified URLs has marginal sandbox benefit. Also disabled
// on Linux root/CI/container, where the sandbox requires unprivileged user
// namespaces that aren't available.
chromiumSandbox: shouldEnableChromiumSandbox(),
...(launchArgs.length > 0 ? { args: launchArgs } : {}),
...(executablePath ? { executablePath } : {}),
...(this.proxyConfig ? { proxy: this.proxyConfig } : {}),
}), { usesCustomExecutable: Boolean(executablePath) }).catch(nameCustomChromium);
// Chromium disconnect → distinguish clean user-quit from crash. Both
// events look identical to Playwright (one 'disconnected' fires), but
// the underlying ChildProcess exit code separates them:
// exitCode === 0 → clean quit (user Cmd+Q on macOS, normal shutdown)
// exitCode !== 0 → crash, signal-kill, or OOM
// Process supervisors (gbrowser's gbd) consume our exit code: code 0
// means "user wanted this, don't restart"; non-zero means "crash, please
// bring me back." Without this distinction every Cmd+Q gets treated as
// a crash and the user-visible window keeps respawning.
this.onBrowserDisconnected(this.browser, () => {
void handleChromiumDisconnect(this.browser);
});
// #2709: record the child's identity so the CLI can reap a survivor after
// daemon shutdown. We launched this browser, so its PID is ours to record.
{
const pid = await launchedChromiumPid(this.browser);
this.chromiumProcInfo = pid ? { pid, startTime: readPidStartTime(pid) } : null;
}
this.context = await this.browser.newContext(contextOptions);
if (Object.keys(this.extraHeaders).length > 0) {
await this.context.setExtraHTTPHeaders(this.extraHeaders);
}
// Apply Layer C stealth (applyStealth): masks navigator.webdriver,
// restores window.chrome.* shape, aligns Notification.permission, sets
// per-install hardware, and strips automation globals + the Permissions
// notifications tell. We still do NOT fake navigator.plugins/languages —
// faking those to fixed values flags more bot-like, not less (D7).
const { applyStealth } = await import('./stealth');
await applyStealth(this.context);
// Create first tab
await this.newTab();
}
// ─── Headed Mode ─────────────────────────────────────────────
/**
* Launch Playwright's bundled Chromium in headed mode with the gstack
* Chrome extension auto-loaded. Uses launchPersistentContext() which
* is required for extension loading (launch() + newContext() can't
* load extensions).
*
* The browser launches headed with a visible window — the user sees
* every action Claude takes in real time.
*/
async launchHeaded(authToken?: string): Promise<void> {
this.closing = false;
await this.ensureHeadedDisplay();
// Clear old state before repopulating
this.pages.clear();
this.tabSessions.clear();
this.nextTabId = 1;
// Find the gstack extension directory for auto-loading
const extensionPath = this.findExtensionPath();
const { STEALTH_LAUNCH_ARGS, buildGStackLaunchArgs } = await import('./stealth');
const launchArgs = [
'--hide-crash-restore-bubble',
// Anti-bot-detection: --disable-blink-features=AutomationControlled (and any
// future blink-level tells) via the shared STEALTH_LAUNCH_ARGS constant — the
// same flag launch() and handoff() use, kept in one place instead of a literal.
...STEALTH_LAUNCH_ARGS,
// GStack Pack 1: per-install hardware/GPU/UA-CH overrides for the
// C++ patches in gbrowser's Chromium build. Each switch is a no-op
// on Chromium builds without the corresponding patch (the patch's
// empty-fallback returns native), so this is safe on stock Playwright
// Chromium too.
...buildGStackLaunchArgs(),
];
if (extensionPath) {
// Skip --load-extension when running against a custom Chromium build
// that already bakes the extension in as a component extension
// (gbrowser / GStack Browser.app). Loading it twice causes a
// ServiceWorkerState::SetWorkerId DCHECK crash.
if (!isCustomChromium()) {
launchArgs.push(`--disable-extensions-except=${extensionPath}`);
launchArgs.push(`--load-extension=${extensionPath}`);
}
// Write auth token for extension bootstrap (still required even when
// the extension is component-baked — it reads ~/.gstack/.auth.json at
// startup to learn how to call the daemon).
// Write to ~/.gstack/.auth.json (not the extension dir, which may be read-only
// in .app bundles and breaks codesigning).
if (authToken) {
const fs = require('fs');
const path = require('path');
const gstackDir = path.join(process.env.HOME || '/tmp', '.gstack');
mkdirSecure(gstackDir);
const authFile = path.join(gstackDir, '.auth.json');
try {
writeSecureFile(authFile, JSON.stringify({ token: authToken, port: this.serverPort || 34567 }));
} catch (err: any) {
console.warn(`[browse] Could not write .auth.json: ${err.message}`);
}
}
}
// Launch headed Chromium via Playwright's persistent context.
// Extensions REQUIRE launchPersistentContext (not launch + newContext).
// Real Chrome (executablePath/channel) silently blocks --load-extension,
// so we use Playwright's bundled Chromium which reliably loads extensions.
const fs = require('fs');
const path = require('path');
const userDataDir = resolveChromiumProfile();
ensureProjectProfile(userDataDir);
fs.mkdirSync(userDataDir, { recursive: true });
// Pre-launch cleanup of stale SingletonLock/Socket/Cookie. Chromium's
// ProcessSingleton refuses to start when these exist from a prior crash
// (SIGKILL, hard crash) — the lockfiles point at a PID that may no longer
// exist. Shutdown cleanup doesn't run on hard crashes, so we clean here
// too. Safe under external coordination: gbd.lock for gbrowser,
// single-instance CLI check for gstack.
cleanSingletonLocks(userDataDir);
// Support custom Chromium binary via GSTACK_CHROMIUM_PATH env var.
// Used by GStack Browser.app to point at the bundled Chromium.
const executablePath = process.env.GSTACK_CHROMIUM_PATH || undefined;
// NOTE (#2242): the in-place "rebrand" that patched the Chromium .app's
// Info.plist (global "Google Chrome for Testing" → "GStack Browser"
// replace) and overwrote its Resources/*.icns is deliberately GONE.
// Chrome for Testing is a code-signed bundle: the global replace renamed
// CFBundleExecutable to a binary that doesn't exist and the plist/icon
// writes broke the codesign seal — GPU process exit_code=5, headed mode
// dead on macOS 26 (#2242, #2138, #2139). Branding belongs in the
// GStack Browser.app wrapper (GSTACK_CHROMIUM_PATH), never in a mutation
// of the signed bundle. Do not reintroduce writes into the Chromium
// bundle here — browse/test/rebrand-signed-bundle.test.ts fails CI if
// you do.
//
// Self-heal for bundles the OLD code already poisoned: probe the
// Playwright-cache bundle and remove it when the mutated plist is
// present (see probePoisonedChromiumBundle for the removal-scope
// rationale). Scoped to the Playwright cache copy — a
// GSTACK_CHROMIUM_PATH bundle belongs to the wrapper/embedder and is
// never probed.
if (!executablePath) {
try {
probePoisonedChromiumBundle(chromium.executablePath());
} catch (err: unknown) {
if (err instanceof PoisonedBundleError) throw err;
// Probe failures (no bundle yet, EACCES) fall through to launch,
// which produces its own actionable error.
}
}
// Build custom user agent: report as stock Chrome with the version
// matching the underlying Chromium binary. D6 (codex #18 correction):
// the previous "GStackBrowser" branding suffix was itself a high-entropy
// classifier — sites grepping UA for known browser strings caught us
// immediately. Branding still lives in the wrapper .app name + Dock icon
// + tray; it does NOT need to be in the UA string for the product to be
// "GBrowser." Removing it resolves the "looks like Chrome but identifies
// as GStackBrowser" contradiction codex flagged.
let customUA: string | undefined;
if (!this.customUserAgent) {
// Detect Chrome version from the Chromium binary
const chromePath = executablePath || chromium.executablePath();
try {
const versionProc = Bun.spawnSync([chromePath, '--version'], {
stdout: 'pipe', stderr: 'pipe', timeout: 5000,
});
const versionOutput = versionProc.stdout.toString().trim();
// Output like: "Google Chrome for Testing 145.0.6422.0" or "Chromium 145.0.6422.0"
const versionMatch = versionOutput.match(/(\d+\.\d+\.\d+\.\d+)/);
const chromeVersion = versionMatch ? versionMatch[1] : '131.0.0.0';
customUA = `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${chromeVersion} Safari/537.36`;
} catch {
// Fallback: generic modern Chrome UA
customUA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36';
}
}
// T1: strip Playwright's automation-tell defaults. STEALTH_IGNORE_DEFAULT_ARGS
// covers the originals (extension-loading blockers) plus --enable-automation
// (kills the "Chrome is being controlled by automated test software" infobar
// and the chrome-runtime shape changes Playwright otherwise triggers) and
// three more (--disable-popup-blocking, --disable-component-update,
// --disable-default-apps — each a documented automation tell per Patchright).
const { STEALTH_IGNORE_DEFAULT_ARGS } = await import('./stealth');
// XProtect self-heal wrapper (P0 #2554). usesCustomExecutable scopes the
// heal out when GSTACK_CHROMIUM_PATH supplies the bundle — that bundle
// belongs to the wrapper/embedder and is never quarantine-cleared or
// reinstalled over (probePoisonedChromiumBundle's scope contract).
this.context = await launchWithXProtectHeal(() => chromium.launchPersistentContext(userDataDir, {
headless: false,
...(this.xvfb ? { env: { ...process.env, DISPLAY: this.xvfb.display } } : {}),
// #2220: daemon owns signal policy — see launch() for the rationale.
handleSIGINT: false,
handleSIGTERM: false,
handleSIGHUP: false,
// Match the sandbox policy used by launch() above. Without this,
// Playwright auto-adds --no-sandbox on every headed launch and the user
// sees Chromium's "unsupported command-line flag" yellow infobar.
chromiumSandbox: shouldEnableChromiumSandbox(),
args: launchArgs,
viewport: null, // Use browser's default viewport (real window size)
userAgent: this.customUserAgent || customUA,
...(executablePath ? { executablePath } : {}),
...(this.proxyConfig ? { proxy: this.proxyConfig } : {}),
ignoreDefaultArgs: STEALTH_IGNORE_DEFAULT_ARGS,
}), { usesCustomExecutable: Boolean(executablePath) });
this.browser = this.context.browser();
this.connectionMode = 'headed';
this.intentionalDisconnect = false;
// ─── Anti-bot-detection patches ───────────────────────────────
// Apply Layer C stealth (applyStealth): masks navigator.webdriver,
// restores window.chrome.* shape, aligns Notification.permission, sets
// per-install hardware, and strips automation runtime artifacts (cdc_/
// __webdriver globals + the Permissions notifications 'denied' tell).
// We still do NOT fake navigator.plugins/languages — faking those flags
// more bot-like, not less (D7). The cdc/Permissions cleanup moved into
// applyStealth so headless launch() and handoff() get it too, not just
// this headed path.
const { applyStealth } = await import('./stealth');
await applyStealth(this.context);
// Inject visual indicator — subtle top-edge amber gradient
// Extension's content script handles the floating pill
const indicatorScript = () => {
const injectIndicator = () => {
if (document.getElementById('gstack-ctrl')) return;
const topLine = document.createElement('div');
topLine.id = 'gstack-ctrl';
topLine.style.cssText = `
position: fixed; top: 0; left: 0; right: 0; height: 2px;
background: linear-gradient(90deg, #F59E0B, #FBBF24, #F59E0B);
background-size: 200% 100%;
animation: gstack-shimmer 3s linear infinite;
pointer-events: none; z-index: 2147483647;
opacity: 0.8;
`;
const style = document.createElement('style');
style.textContent = `
@keyframes gstack-shimmer {
0% { background-position: 200% 0; }
100% { background-position: -200% 0; }
}
@media (prefers-reduced-motion: reduce) {
#gstack-ctrl { animation: none !important; }
}
`;
document.documentElement.appendChild(style);
document.documentElement.appendChild(topLine);
};
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', injectIndicator);
} else {
injectIndicator();
}
};
await this.context.addInitScript(indicatorScript);
// Track user-created tabs automatically (Cmd+T, link opens in new tab, etc.)
this.context.on('page', (page) => {
const id = this.nextTabId++;
this.pages.set(id, page);
this.tabSessions.set(id, new TabSession(page));
this.activeTabId = id;
this.wirePageEvents(page);
// Inject indicator on the new tab
page.evaluate(indicatorScript).catch(() => {});
console.log(`[browse] New tab detected (id=${id}, total=${this.pages.size})`);
this.checkTabGuardrails();
});
// Persistent context opens a default page — adopt it instead of creating a new one
const existingPages = this.context.pages();
if (existingPages.length > 0) {
const page = existingPages[0];
const id = this.nextTabId++;
this.pages.set(id, page);
this.tabSessions.set(id, new TabSession(page));
this.activeTabId = id;
this.wirePageEvents(page);
// Inject indicator on restored page (addInitScript only fires on new navigations)
try {
await page.evaluate(indicatorScript);
} catch {}
} else {
await this.newTab();
}
// Browser disconnect handler — distinguish user Cmd+Q from real crash.
// Clean exit (Chromium exit code 0) → process.exit(0) so process
// supervisors (gbrowser's gbd) treat it as user intent and skip the
// restart loop. Crash → process.exit(2) preserves the legacy headed
// semantics that's distinct from launch()'s code 1.
// Always calls onDisconnect() first to trigger full shutdown (kill
// terminal agent, save session, clean profile locks + state file) so
// crashes don't strand resources either.
if (this.browser) {
this.onBrowserDisconnected(this.browser, () => {
if (this.intentionalDisconnect) return;
const browserRef = this.browser;
void (async () => {
const cause = await resolveDisconnectCause(browserRef);
const exitCode = cause === 'clean' ? 0 : 2;
if (cause === 'clean') {
console.error('[browse] Real browser closed cleanly (user-initiated quit). Server exiting (0).');
} else {
console.error('[browse] Real browser disconnected (crash or kill). Server exiting (2).');
console.error('[browse] Run `$B connect` to reconnect.');
}
if (!this.onDisconnect) {
process.exit(exitCode);
return;
}
try {
const result = this.onDisconnect(exitCode);
if (result && typeof (result as Promise<void>).catch === 'function') {
(result as Promise<void>).catch((err) => {
console.error('[browse] onDisconnect rejected:', err);
process.exit(exitCode);
});
}
// onDisconnect is responsible for exit on the success path.
} catch (err) {
console.error('[browse] onDisconnect threw:', err);
process.exit(exitCode);
}
})();
});
}
// Headed mode defaults
this.dialogAutoAccept = false; // Don't dismiss user's real dialogs
this.isHeaded = true;
this.consecutiveFailures = 0;
}
// How long close() waits for a graceful shutdown before falling back to
// SIGKILL (launched mode) or abandoning the context close (headed mode).
// A field, not a literal, so the SIGKILL fallback is unit-testable without
// a 5-second wait.
private closeRaceMs = 5000;
async close() {
this.closing = true;
const previousBrowser = this.handoffPrevious?.browser;
const currentBrowser = this.browser;
// unref'd race timer: without unref, every successful close still pins
// the caller's event loop for the full window.
const raceTimeout = (ms: number) => new Promise<false>((resolve) => {
const t = setTimeout(() => resolve(false), ms);
(t as { unref?: () => void }).unref?.();
});
if (this.browser || ((this.connectionMode === 'headed' || this.handoffPrevious) && this.context)) {
if (this.connectionMode === 'headed' || this.handoffPrevious || this.extensionContext) {
// Headed/persistent context mode: close the context (which closes the browser)
this.intentionalDisconnect = true;
this.detachDisconnectHandlers(this.browser);
await Promise.race([
this.context ? this.context.close() : Promise.resolve(),
raceTimeout(this.closeRaceMs),
]).catch(() => {});
} else if (this.browser) {
// Launched mode: close the browser we spawned.
this.detachDisconnectHandlers(this.browser);
// Grab the child handle BEFORE the race: nulling this.browser after a
// race-timeout used to ABANDON a live Chromium whose sockets kept the
// caller's event loop (and keep-alive connections into test servers)
// open forever — the intermittent whole-suite wedge. If graceful close
// doesn't finish in time, the child gets SIGKILL, not freedom.
const child = launchedProcess(this.browser);
const closed = await Promise.race([
this.browser.close().then(() => true as const),
raceTimeout(this.closeRaceMs),
]).catch(() => false as const);
if (closed === false && child && child.exitCode === null && !child.killed) {
try { child.kill('SIGKILL'); } catch { /* already gone */ }
}
}
this.browser = null;
}
if (previousBrowser && previousBrowser !== currentBrowser) {
this.detachDisconnectHandlers(previousBrowser);
const child = launchedProcess(previousBrowser);
const closed = await Promise.race([
previousBrowser.close().then(() => true), raceTimeout(this.closeRaceMs),
]).catch(() => false);
if (!closed && child && child.exitCode === null && !child.killed) {
try { child.kill('SIGKILL'); } catch {}
}
}
await this.displayAllocation?.catch(() => {});
this.closeOwnedDisplay();
}
/** Health check — verifies Chromium is connected AND responsive */
async isHealthy(): Promise<boolean> {
if (!this.browser || !this.browser.isConnected()) return false;
try {
const page = this.pages.get(this.activeTabId);
if (!page) return true; // connected but no pages — still healthy
await Promise.race([
page.evaluate('1'),
new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 2000)),
]);
return true;
} catch {
return false;
}
}
// ─── Tab Management ────────────────────────────────────────
async newTab(url?: string, clientId?: string): Promise<number> {
if (!this.context) throw new Error('Browser not launched');
// Validate URL before allocating page to avoid zombie tabs on rejection.
// Use the normalized return value for navigation — it handles file://./x and
// file://<segment> cwd-relative forms that the standard URL parser doesn't.
let normalizedUrl: string | undefined;
if (url) {
normalizedUrl = await validateNavigationUrl(url);
}
const page = await this.context.newPage();
const id = this.nextTabId++;
this.pages.set(id, page);
this.tabSessions.set(id, new TabSession(page));
this.activeTabId = id;
// Record tab ownership for multi-agent isolation
if (clientId) {
this.tabOwnership.set(id, clientId);
}
// Wire up console/network/dialog capture
this.wirePageEvents(page);
if (normalizedUrl) {
await page.goto(normalizedUrl, { waitUntil: 'domcontentloaded', timeout: 15000 });
}
return id;
}
async closeTab(id?: number): Promise<void> {
const tabId = id ?? this.activeTabId;
const page = this.pages.get(tabId);
if (!page) throw new Error(`Tab ${tabId} not found`);
// Capture BEFORE close(): the page 'close' event handler wired in
// wirePageEvents() can fire while page.close() is awaited. It removes
// the tab from the maps and reassigns activeTabId (to 0 when no tabs
// remain), so a post-close `tabId === this.activeTabId` check is
// order-dependent — whether the event dispatches before or after
// close() resolves varies across Playwright/Chromium versions and
// machines, and losing the race means the last-tab auto-create below
// never runs, leaving the manager with zero tabs.
const wasActive = tabId === this.activeTabId;
await page.close();
this.pages.delete(tabId);
this.tabSessions.delete(tabId);
this.tabOwnership.delete(tabId);
// Switch to another tab if we closed the active one
if (wasActive) {
const remaining = [...this.pages.keys()];
if (remaining.length === 0) {
// No tabs left — create a new blank one
await this.newTab();
} else if (!this.pages.has(this.activeTabId)) {
// The 'close' handler may have already switched to a valid tab;
// only reassign when activeTabId no longer points at a live tab.
this.activeTabId = remaining[remaining.length - 1];
}
}
}
switchTab(id: number, opts?: { bringToFront?: boolean }): void {
if (!this.tabSessions.has(id)) throw new Error(`Tab ${id} not found`);
this.activeTabId = id;
// Only bring to front when explicitly requested (user-initiated tab switch).
// Internal tab pinning (BROWSE_TAB) should NOT steal focus.
if (opts?.bringToFront !== false) {
const page = this.pages.get(id);
if (page) page.bringToFront().catch(() => {});
}
}
/**
* Sync activeTabId to match the tab whose URL matches the Chrome extension's
* active tab. Called on every /sidebar-tabs poll so manual tab switches in
* the browser are detected within ~2s.
*/
syncActiveTabByUrl(activeUrl: string): void {
if (!activeUrl || this.pages.size <= 1) return;
// Try exact match first, then fuzzy match (origin+pathname, ignoring query/fragment)
let fuzzyId: number | null = null;
let activeOriginPath = '';
try {
const u = new URL(activeUrl);
activeOriginPath = u.origin + u.pathname;
} catch (err: any) {
if (!(err instanceof TypeError)) throw err;
}
for (const [id, page] of this.pages) {
try {
const pageUrl = page.url();
// Exact match — best case
if (pageUrl === activeUrl && id !== this.activeTabId) {
this.activeTabId = id;
return;
}
// Fuzzy match — origin+pathname (handles query param / fragment differences)
if (activeOriginPath && fuzzyId === null && id !== this.activeTabId) {
try {
const pu = new URL(pageUrl);
if (pu.origin + pu.pathname === activeOriginPath) {
fuzzyId = id;
}
} catch (err: any) {
if (!(err instanceof TypeError)) throw err;
}
}
} catch {}
}
// Fall back to fuzzy match
if (fuzzyId !== null) {
this.activeTabId = fuzzyId;
}
}
getActiveTabId(): number {
return this.activeTabId;
}
getTabCount(): number {
return this.pages.size;
}
// ─── Tab Ownership (multi-agent isolation) ──────────────
/** Get the owner of a tab, or null if unowned (root-only for writes). */
getTabOwner(tabId: number): string | null {
return this.tabOwnership.get(tabId) || null;
}
/**
* Check if a client can access a tab.
*
* Two policies, distinguished by `options.ownOnly`:
*
* - **own-only (pair-agent over tunnel):** the strict mode. Token must own
* the target tab for any access (reads or writes). Unowned user tabs
* and tabs owned by other clients are off-limits. Remote agents must
* `newtab` first to get a tab they can drive.
*
* - **shared (local skill spawns, default scoped tokens):** permissive on
* tab access. The token can read/write any tab — capability is gated
* elsewhere (scope checks at /command, rate limits, the dual-listener
* allowlist for tunnel-bound traffic). Tab ownership is not a security
* boundary for shared tokens; it only matters for pair-agent isolation.
* This matches the contract documented in `skill-token.ts:79`
* ("skill scripts may switch tabs as needed").
*
* Root is unconstrained.
*
* `isWrite` is preserved in the signature for callers that want to log or
* branch on it elsewhere, but the access decision itself only depends on
* `ownOnly` + ownership map state.
*/
checkTabAccess(tabId: number, clientId: string, options: { isWrite?: boolean; ownOnly?: boolean } = {}): boolean {
if (clientId === 'root') return true;
if (options.ownOnly) {
const owner = this.tabOwnership.get(tabId);
return owner === clientId;
}
return true;
}
/** Transfer tab ownership to a different client. */
transferTab(tabId: number, toClientId: string): void {
if (!this.pages.has(tabId)) throw new Error(`Tab ${tabId} not found`);
this.tabOwnership.set(tabId, toClientId);
}
/**
* Release all tab ownership held by a client (called on revoke / reducing
* re-pair). Deletes the ownership entries so an own-only client re-pairing
* under the same name can no longer inherit the revoked agent's
* authenticated tabs (checkTabAccess gates own-only on owner === clientId).
* Tabs are NOT closed — leaving the page open is the local human's call, not
* the daemon's; the residual is a root-only tab. Returns the released ids.
*/
releaseClientTabs(clientId: string): number[] {
const released: number[] = [];
for (const [tabId, owner] of this.tabOwnership) {
if (owner === clientId) {
this.tabOwnership.delete(tabId);
released.push(tabId);
}
}
return released;
}
async getTabListWithTitles(): Promise<Array<{ id: number; url: string; title: string; active: boolean }>> {
const tabs: Array<{ id: number; url: string; title: string; active: boolean }> = [];
for (const [id, page] of this.pages) {
tabs.push({
id,
url: page.url(),
title: await page.title().catch(() => ''),
active: id === this.activeTabId,
});
}
return tabs;
}
// ─── Session Access ────────────────────────────────────────
/** Get the TabSession for the active tab. */
getActiveSession(): TabSession {
const session = this.tabSessions.get(this.activeTabId);
if (!session) throw new Error('No active page. Use "browse goto <url>" first.');
return session;
}
/** Get a TabSession by tab ID. Used by /batch for parallel tab execution. */
getSession(tabId: number): TabSession {
const session = this.tabSessions.get(tabId);
if (!session) throw new Error(`Tab ${tabId} not found`);
return session;
}
/** Get the underlying Page for a tab id. Returns null if the tab doesn't exist.
* Used by the CDP bridge (cdp-bridge.ts) to mint per-tab CDPSessions. */
getPageForTab(tabId: number): Page | null {
return this.pages.get(tabId) ?? null;
}
// ─── Two-tier mutex (Codex T7) ─────────────────────────────
// Per-tab and global locks for the CDP bridge. tab-scoped methods take the
// per-tab mutex; browser-scoped methods take the global lock that blocks all
// tab mutexes. Hard timeout on acquire so silent deadlock can't happen.
// Every caller MUST use try { ... } finally { release() }.
private tabLocks: Map<number, Promise<void>> = new Map();
private globalCdpLockTail: Promise<void> = Promise.resolve();
/**
* Acquire the per-tab CDP lock with a timeout. Returns a release fn.
* Locks chain: each acquire waits on the prior tail's resolution.
* Browser-scoped global lock takes precedence: while the global lock is
* held, no tab lock can be acquired (and vice versa).
*/
async acquireTabLock(tabId: number, timeoutMs: number): Promise<() => void> {
const existing = this.tabLocks.get(tabId) ?? Promise.resolve();
// Wait for any held global lock first (cross-tier serialization).
const tail = Promise.all([existing, this.globalCdpLockTail]).then(() => undefined);
let release!: () => void;
const next = new Promise<void>((resolve) => { release = resolve; });
this.tabLocks.set(tabId, tail.then(() => next));
const timeoutPromise = new Promise<never>((_, reject) =>
setTimeout(() => reject(new Error(
`CDPMutexAcquireTimeout: tab ${tabId} lock not acquired within ${timeoutMs}ms.\n` +
'Cause: a prior CDP or browser-scoped operation has held the lock too long.\n' +
'Action: retry; if this repeats, the prior operation may be hung — file a bug.'
)), timeoutMs),
);
try {
await Promise.race([tail, timeoutPromise]);
} catch (e) {
// Acquisition failed; release the slot we reserved so we don't deadlock the queue.
release();
throw e;
}
return release;
}
/**
* Acquire the global CDP lock. Blocks until all tab locks are released, and
* blocks new tab-lock acquisitions until released.
*/
async acquireGlobalCdpLock(timeoutMs: number): Promise<() => void> {
const allTabTails = Array.from(this.tabLocks.values());
const priorGlobal = this.globalCdpLockTail;
const allPrior = Promise.all([priorGlobal, ...allTabTails]).then(() => undefined);
let release!: () => void;
const next = new Promise<void>((resolve) => { release = resolve; });
this.globalCdpLockTail = allPrior.then(() => next);
const timeoutPromise = new Promise<never>((_, reject) =>
setTimeout(() => reject(new Error(
`CDPMutexAcquireTimeout: global CDP lock not acquired within ${timeoutMs}ms.\n` +
'Cause: in-flight tab operations have not completed.\n' +
'Action: retry; if this repeats, file a bug — a tab op may be hung.'
)), timeoutMs),
);
try {
await Promise.race([allPrior, timeoutPromise]);
} catch (e) {
release();
throw e;
}
return release;
}
// ─── Page Access (delegates to active session) ─────────────
getPage(): Page {
return this.getActiveSession().page;
}
getCurrentUrl(): string {
try {
return this.getPage().url();
} catch {
return 'about:blank';
}
}
/**
* Diagnostic for `$B memory` and the /memory endpoint.
*
* Collects:
* - Bun process memory (cross-platform, accurate, no shelling).
* - Per-tab JS heap via CDP Performance.getMetrics — the most portable
* per-tab signal CDP exposes. Misses native/GPU/Skia/cache memory
* (Codex flag on the eng-review; see follow-up TODO "native/GPU
* memory breakdown").
* - Chromium process tree via SystemInfo.getProcessInfo — PID + type
* + CPU time. Per-process RSS is NOT exposed via CDP and the eng
* review (D2 USE_CDP) explicitly chose CDP over shelling to `ps`,
* so RSS columns are absent and `notes[]` says why.
*
* `structures` is passed in by the caller (read-commands / server) so
* browser-manager doesn't take a hard dep on every buffer-owning module.
*/
async getMemorySnapshot(structures: MemoryStructureStats): Promise<MemorySnapshot> {
const bunMem = process.memoryUsage();
const notes: string[] = [];
// Per-tab JS heap. Lazy: only the pages we already track. A target
// that died mid-snapshot is omitted, never throws.
const tabs: MemoryTabSnapshot[] = [];
for (const [id, page] of this.pages) {
try {
const url = (() => { try { return page.url(); } catch { return ''; } })();
const title = await page.title().catch(() => '');
const metrics = await withCdpSession(page, async (session) => {
await session.send('Performance.enable').catch(() => undefined);
const result = await session.send('Performance.getMetrics');
return ((result as { metrics?: Array<{ name: string; value: number }> }).metrics) ?? [];
});
const mm: Record<string, number> = {};
for (const m of metrics) mm[m.name] = m.value;
tabs.push({
id,
url,
title,
jsHeapUsed: mm.JSHeapUsedSize ?? 0,
jsHeapTotal: mm.JSHeapTotalSize ?? 0,
documents: mm.Documents ?? 0,
nodes: mm.Nodes ?? 0,
listeners: mm.JSEventListeners ?? 0,
});
} catch {
// Target died or CDP unavailable mid-snapshot — skip this tab.
}
}
// Chromium process tree. Browser handle may be on the `browser` field
// (launched mode) or accessible via `context.browser()` (persistent
// context / headed mode); try both.
let processes: MemoryProcess[] | null = null;
const browser: Browser | null = this.browser ?? (this.context ? this.context.browser() : null);
if (browser) {
try {
// `newBrowserCDPSession` is browser-wide. Not exposed on every
// Playwright TypeScript surface, but present at runtime on the
// Browser instance — use a typed cast to avoid the @ts-expect-error.
type BrowserWithCDP = Browser & {
newBrowserCDPSession?: () => Promise<{
send: (method: string, params?: unknown) => Promise<unknown>;
detach: () => Promise<void>;
}>;
};
const maybeFactory = (browser as BrowserWithCDP).newBrowserCDPSession;
if (typeof maybeFactory === 'function') {
const browserSession = await maybeFactory.call(browser);
try {
const info = (await browserSession.send('SystemInfo.getProcessInfo')) as {
processInfo?: Array<{ id: number; type: string; cpuTime: number }>;
};
processes = (info.processInfo ?? []).map((p) => ({
id: p.id,
type: p.type,
cpuTime: p.cpuTime,
}));
notes.push(
'Per-Chromium-process RSS not collected — SystemInfo.getProcessInfo exposes PID+type+CPU only. ' +
'See follow-up TODO "native/GPU memory breakdown" for the deferred fix.',
);
} finally {
await browserSession.detach().catch(() => undefined);
}
} else {
notes.push('Playwright build does not expose newBrowserCDPSession; per-process info skipped.');
}
} catch (err: any) {
notes.push(`CDP browser session unavailable: ${err?.message ?? String(err)}`);
}
} else {
notes.push('Browser handle unavailable (server connection mode); per-process info skipped.');
}
return {
bunServer: {
rss: bunMem.rss,
heapUsed: bunMem.heapUsed,
heapTotal: bunMem.heapTotal,
external: bunMem.external,
},
tabs,
processes,
structures,
capturedAt: Date.now(),
notes,
};
}
// ─── Ref Map (delegates to active session) ──────────────────
setRefMap(refs: Map<string, RefEntry>) {
this.getActiveSession().setRefMap(refs);
}
clearRefs() {
this.getActiveSession().clearRefs();
}
async resolveRef(selector: string): Promise<{ locator: Locator } | { selector: string }> {
return this.getActiveSession().resolveRef(selector);
}
getRefRole(selector: string): string | null {
return this.getActiveSession().getRefRole(selector);
}
getRefCount(): number {
return this.getActiveSession().getRefCount();
}
// ─── Snapshot Diffing (delegates to active session) ─────────
setLastSnapshot(text: string | null) {
this.getActiveSession().setLastSnapshot(text);
}
getLastSnapshot(): string | null {
return this.getActiveSession().getLastSnapshot();
}
// ─── Dialog Control ───────────────────────────────────────
setDialogAutoAccept(accept: boolean) {
this.dialogAutoAccept = accept;
}
getDialogAutoAccept(): boolean {
return this.dialogAutoAccept;
}
setDialogPromptText(text: string | null) {
this.dialogPromptText = text;
}
getDialogPromptText(): string | null {
return this.dialogPromptText;
}
// ─── Cookie Origin Tracking ────────────────────────────────
trackCookieImportDomains(domains: string[]): void {
for (const d of domains) this.cookieImportedDomains.add(d);
}
getCookieImportedDomains(): ReadonlySet<string> {
return this.cookieImportedDomains;
}
hasCookieImports(): boolean {
return this.cookieImportedDomains.size > 0;
}
// ─── Viewport ──────────────────────────────────────────────
async setViewport(width: number, height: number) {
this.currentViewport = { width, height };
await this.getPage().setViewportSize({ width, height });
}
// ─── Extra Headers ─────────────────────────────────────────
async setExtraHeader(name: string, value: string) {
this.extraHeaders[name] = value;
if (this.context) {
await this.context.setExtraHTTPHeaders(this.extraHeaders);
}
}
// ─── User Agent ────────────────────────────────────────────
setUserAgent(ua: string) {
this.customUserAgent = ua;
}
getUserAgent(): string | null {
return this.customUserAgent;
}
// ─── Lifecycle helpers ───────────────────────────────
/**
* Close all open pages and clear the pages map.
* Used by state load to replace the current session.
*/
async closeAllPages(): Promise<void> {
for (const page of this.pages.values()) {
await page.close().catch(() => {});
}
this.pages.clear();
this.tabSessions.clear();
}
// ─── Frame context (delegates to active session) ────────────
setFrame(frame: import('playwright').Frame | null): void {
this.getActiveSession().setFrame(frame);
}
getFrame(): import('playwright').Frame | null {
return this.getActiveSession().getFrame();
}
getActiveFrameOrPage(): import('playwright').Page | import('playwright').Frame {
return this.getActiveSession().getActiveFrameOrPage();
}
// ─── State Save/Restore (shared by recreateContext + handoff) ─
/**
* Capture browser state: cookies, localStorage, sessionStorage, URLs, active tab.
* Skips pages that fail storage reads (e.g., already closed).
*/
async saveState(): Promise<BrowserState> {
if (!this.context) throw new Error('Browser not launched');
const cookies = await this.context.cookies();
const pages: BrowserState['pages'] = [];
for (const [id, page] of this.pages) {
const url = page.url();
let storage = null;
try {
storage = await page.evaluate(() => ({
localStorage: { ...localStorage },
sessionStorage: { ...sessionStorage },
}));
} catch {}
// Capture load-html content so a later context recreation (viewport --scale)
// can replay it via setTabContent. Never persisted to disk.
const session = this.tabSessions.get(id);
const loaded = session?.getLoadedHtml();
// Preserve tab ownership through recreation so scoped agents aren't locked out.
const owner = this.tabOwnership.get(id);
pages.push({
url: url === 'about:blank' ? '' : url,
isActive: id === this.activeTabId,
storage,
loadedHtml: loaded?.html,
loadedHtmlWaitUntil: loaded?.waitUntil,
owner,
});
}
return { cookies, pages };
}
/**
* Restore browser state into the current context: cookies, pages, storage.
* Navigates to saved URLs, restores storage, wires page events.
* Failures on individual pages are swallowed — partial restore is better than none.
*/
async restoreState(state: BrowserState): Promise<void> {
if (!this.context) throw new Error('Browser not launched');
// Restore cookies
if (state.cookies.length > 0) {
await this.context.addCookies(state.cookies);
}
// Clear stale ownership — the old tab IDs are gone. We'll re-add per-tab
// owners below as each saved tab gets a fresh ID. Without this reset, old
// tabId → clientId entries would linger and match new tabs with the same
// sequential IDs, silently granting ownership to the wrong clients.
this.tabOwnership.clear();
// Re-create pages
let activeId: number | null = null;
for (const saved of state.pages) {
const page = await this.context.newPage();
const id = this.nextTabId++;
this.pages.set(id, page);
const newSession = new TabSession(page);
this.tabSessions.set(id, newSession);
this.wirePageEvents(page);
// Restore tab ownership for the new ID — preserves scoped-agent isolation
// across context recreation (viewport --scale, user-agent change, handoff).
if (saved.owner) {
this.tabOwnership.set(id, saved.owner);
}
if (saved.loadedHtml) {
// Replay load-html content via setTabContent — this rehydrates
// TabSession.loadedHtml so the next saveState sees it. page.setContent()
// alone would restore the DOM but lose the replay metadata.
try {
await newSession.setTabContent(saved.loadedHtml, { waitUntil: saved.loadedHtmlWaitUntil });
} catch (err: any) {
console.warn(`[browse] Failed to replay loadedHtml for tab ${id}: ${err.message}`);
}
} else if (saved.url) {
// Validate the saved URL before navigating — the state file is user-writable and
// a tampered URL could navigate to cloud metadata endpoints. Use the normalized
// return value so file:// forms get consistent treatment with live goto.
let normalizedUrl: string;
try {
normalizedUrl = await validateNavigationUrl(saved.url);
} catch (err: any) {
console.warn(`[browse] Skipping invalid URL in state file: ${saved.url} — ${err.message}`);
continue;
}
await page.goto(normalizedUrl, { waitUntil: 'domcontentloaded', timeout: 15000 }).catch(() => {});
}
if (saved.storage) {
try {
await page.evaluate((s: { localStorage: Record<string, string>; sessionStorage: Record<string, string> }) => {
if (s.localStorage) {
for (const [k, v] of Object.entries(s.localStorage)) {
localStorage.setItem(k, v);
}
}
if (s.sessionStorage) {
for (const [k, v] of Object.entries(s.sessionStorage)) {
sessionStorage.setItem(k, v);
}
}
}, saved.storage);
} catch {}
}
if (saved.isActive) activeId = id;
}
// If no pages were saved, create a blank one
if (this.pages.size === 0) {
await this.newTab();
} else {
this.activeTabId = activeId ?? [...this.pages.keys()][0];
}
// Clear refs — pages are new, locators are stale
this.clearRefs();
}
/**
* Recreate the browser context to apply user agent changes.
* Saves and restores cookies, localStorage, sessionStorage, and open pages.
* Falls back to a clean slate on any failure.
*/
async recreateContext(): Promise<string | null> {
if (this.connectionMode === 'headed') {
throw new Error('Cannot recreate context in headed mode. Use disconnect first.');
}
if (this.extensionContext) {
throw new Error('Cannot recreate context while BROWSE_EXTENSIONS_DIR extensions are loaded (persistent context). Restart browse with the new settings instead.');
}
if (!this.browser || !this.context) {
throw new Error('Browser not launched');
}
try {
// 1. Save state
const state = await this.saveState();
// 2. Close old pages and context
for (const page of this.pages.values()) {
await page.close().catch(() => {});
}
this.pages.clear();
this.tabSessions.clear();
await this.context.close().catch(() => {});
// 3. Create new context with updated settings
const contextOptions: BrowserContextOptions = {
viewport: { width: this.currentViewport.width, height: this.currentViewport.height },
deviceScaleFactor: this.deviceScaleFactor,
};
if (this.customUserAgent) {
contextOptions.userAgent = this.customUserAgent;
}
this.context = await this.browser.newContext(contextOptions);
// Re-apply stealth: newContext() is a fresh context with no init scripts,
// so a useragent / viewport --scale rebuild would otherwise drop the
// webdriver mask, window.chrome.* shape, hardware spoof, and cdc/
// Permissions cleanup on every restored page. Must run before
// restoreState() navigates the restored tabs.
const { applyStealth } = await import('./stealth');
await applyStealth(this.context);
if (Object.keys(this.extraHeaders).length > 0) {
await this.context.setExtraHTTPHeaders(this.extraHeaders);
}
// 4. Restore state
await this.restoreState(state);
return null; // success
} catch (err: unknown) {
// Fallback: create a clean context + blank tab
try {
this.pages.clear();
this.tabSessions.clear();
if (this.context) await this.context.close().catch(() => {});
const contextOptions: BrowserContextOptions = {
viewport: { width: this.currentViewport.width, height: this.currentViewport.height },
deviceScaleFactor: this.deviceScaleFactor,
};
if (this.customUserAgent) {
contextOptions.userAgent = this.customUserAgent;
}
this.context = await this.browser!.newContext(contextOptions);
// Stealth applies to the fallback blank context too.
const { applyStealth } = await import('./stealth');
await applyStealth(this.context);
await this.newTab();
this.clearRefs();
} catch {
// If even the fallback fails, we're in trouble — but browser is still alive
}
return `Context recreation failed: ${err instanceof Error ? err.message : String(err)}. Browser reset to blank tab.`;
}
}
/**
* Change deviceScaleFactor + viewport size atomically.
*
* deviceScaleFactor is a context-level option, so Playwright requires a full context
* recreation. This method validates the input, stores the new values, calls
* recreateContext(), and rolls back the fields on failure so a bad call doesn't
* leave the manager in an inconsistent state.
*
* Returns null on success, or an error string if the new context couldn't be built
* (state may have been lost, per recreateContext's fallback behavior).
*/
async setDeviceScaleFactor(scale: number, width: number, height: number): Promise<string | null> {
if (!Number.isFinite(scale)) {
throw new Error(`viewport --scale: value must be a finite number, got ${scale}`);
}
if (scale < 1 || scale > 3) {
throw new Error(`viewport --scale: value must be between 1 and 3 (gstack policy cap), got ${scale}`);
}
if (this.connectionMode === 'headed') {
throw new Error('viewport --scale is not supported in headed mode — scale is controlled by the real browser window.');
}
const prevScale = this.deviceScaleFactor;
const prevViewport = { ...this.currentViewport };
this.deviceScaleFactor = scale;
this.currentViewport = { width, height };
const err = await this.recreateContext();
if (err !== null) {
// recreateContext's fallback path built a blank context using the NEW scale +
// viewport (the fields we just set). Rolling the fields back without a second
// recreate would leave the live context at new-scale while state says old-scale.
// Roll back fields FIRST, then force a second recreate against the old values
// so live state matches tracked state.
this.deviceScaleFactor = prevScale;
this.currentViewport = prevViewport;
const rollbackErr = await this.recreateContext();
if (rollbackErr !== null) {
// Second recreate also failed — we're in a clean blank slate via fallback, but
// with old scale. Return the original error so the caller sees the primary failure.
return `${err} (rollback also encountered: ${rollbackErr})`;
}
return err;
}
return null;
}
/** Read current deviceScaleFactor (for tests + debug). */
getDeviceScaleFactor(): number {
return this.deviceScaleFactor;
}
/** Read current tracked viewport (for tests + `viewport --scale` size fallback). */
getCurrentViewport(): { width: number; height: number } {
return { ...this.currentViewport };
}
// ─── Handoff: Headless → Headed ─────────────────────────────
/**
* Hand off browser control to the user by relaunching in headed mode.
*
* Flow (launch-first-close-second for safe rollback):
* 1. Save state from current headless browser
* 2. Launch NEW headed browser
* 3. Restore state into new browser
* 4. Close OLD headless browser
* If step 2 fails → return error, headless browser untouched
*/
async handoff(message: string): Promise<string> {
if (this.handoffPending) return this.handoffPending;
this.handoffPending = this.promoteToHeaded(message);
try { return await this.handoffPending; }
finally { this.handoffPending = null; }
}
private async promoteToHeaded(message: string): Promise<string> {
if (this.closing) return 'ERROR: Browser is shutting down';
if (this.connectionMode === 'headed' || this.isHeaded) {
return `HANDOFF: Already in headed mode at ${this.getCurrentUrl()}`;
}
if (!this.browser || !this.context) {
throw new Error('Browser not launched');
}
// 1. Save state from current browser
const state = await this.saveState();
if (this.closing) return 'ERROR: Browser is shutting down';
const currentUrl = this.getCurrentUrl();
const previousDisplay = this.xvfb;
// 2. Launch new headed browser with extension (same as launchHeaded)
// Uses launchPersistentContext so the extension auto-loads.
let newContext: BrowserContext;
try {
await this.ensureHeadedDisplay();
const fs = require('fs');
const path = require('path');
const extensionPath = this.findExtensionPath();
const { STEALTH_LAUNCH_ARGS, buildGStackLaunchArgs } = await import('./stealth');
// Same blink-level stealth flags as launch()/launchHeaded(). Without
// STEALTH_LAUNCH_ARGS the handed-off browser kept the AutomationControlled
// tell that the other two paths strip.
const launchArgs: string[] = ['--hide-crash-restore-bubble', ...STEALTH_LAUNCH_ARGS, ...buildGStackLaunchArgs()];
if (extensionPath) {
launchArgs.push(`--disable-extensions-except=${extensionPath}`);
launchArgs.push(`--load-extension=${extensionPath}`);
// Auth token is served via POST /extension-token (pinned-origin
// bootstrap, no file write needed). /health is liveness-only.
console.log(`[browse] Handoff: loading extension from ${extensionPath}`);
} else {
console.log('[browse] Handoff: extension not found — headed mode without side panel');
}
// Same profile resolution + singleton-lock cleanup as launchHeaded().
// This path previously hardcoded ~/.gstack/chromium-profile, silently
// ignoring $CHROMIUM_PROFILE / $GSTACK_HOME and skipping the lock
// cleanup — the third shipped drift between the three launch paths.
const userDataDir = resolveChromiumProfile();
ensureProjectProfile(userDataDir);
fs.mkdirSync(userDataDir, { recursive: true });
cleanSingletonLocks(userDataDir);
// Self-heal probe (#2242): handoff always launches the Playwright-cache
// bundle (this launchPersistentContext call passes no executablePath),
// so a bundle poisoned by the old in-place rebrand would GPU-crash here
// exactly like launchHeaded(). Same probe, same contract: a
// GSTACK_CHROMIUM_PATH bundle is never passed in. The rethrown typed
// error surfaces through the outer catch as the actionable
// "Cannot open headed browser" message, headless browser untouched.
try {
probePoisonedChromiumBundle(chromium.executablePath());
} catch (err: unknown) {
if (err instanceof PoisonedBundleError) throw err;
// Probe failures (no bundle yet, EACCES) fall through to launch.
}
// T1: same automation-tell-stripping defaults as launchHeaded().
// The handoff path (headless → headed re-launch) takes the same
// anti-detection posture.
const { STEALTH_IGNORE_DEFAULT_ARGS } = await import('./stealth');
// XProtect self-heal wrapper (P0 #2554): handoff always launches the
// Playwright-cache bundle (no executablePath), so the heal applies
// exactly as in launch()/launchHeaded().
newContext = await launchWithXProtectHeal(() => chromium.launchPersistentContext(userDataDir, {
headless: false,
...(this.xvfb ? { env: { ...process.env, DISPLAY: this.xvfb.display } } : {}),
// #2220: daemon owns signal policy — see launch() for the rationale.
handleSIGINT: false,
handleSIGTERM: false,
handleSIGHUP: false,
// Match the sandbox policy used by launchHeaded() / launch(). The
// handoff path is the headless→headed re-launch and shares the same
// anti-detection posture, including no spurious --no-sandbox infobar.
chromiumSandbox: shouldEnableChromiumSandbox(),
args: launchArgs,
viewport: null,
...(this.proxyConfig ? { proxy: this.proxyConfig } : {}),
ignoreDefaultArgs: STEALTH_IGNORE_DEFAULT_ARGS,
timeout: 15000,
}));
if (this.closing) {
await newContext.close().catch(() => {});
throw new Error('Browser is shutting down');
}
} catch (err: unknown) {
if (!previousDisplay) this.closeOwnedDisplay();
if (this.closing) return 'ERROR: Browser is shutting down';
const msg = err instanceof Error ? err.message : String(err);
return `ERROR: Cannot open headed browser — ${msg}. Headless browser still running.`;
}
const previous = {
browser: this.browser, context: this.context,
pages: this.pages, tabSessions: this.tabSessions, tabOwnership: this.tabOwnership,
activeTabId: this.activeTabId, nextTabId: this.nextTabId,
connectionMode: this.connectionMode, isHeaded: this.isHeaded,
dialogAutoAccept: this.dialogAutoAccept, intentionalDisconnect: this.intentionalDisconnect,
chromiumProcInfo: this.chromiumProcInfo,
tabGuardrailSoftHit: this.tabGuardrailSoftHit, tabGuardrailHardHit: this.tabGuardrailHardHit,
};
this.handoffPrevious = previous;
try {
this.context = newContext;
this.browser = newContext.browser();
this.pages = new Map();
this.tabSessions = new Map();
this.tabOwnership = new Map();
// Same Layer C stealth as launch()/launchHeaded(). Must run BEFORE
// restoreState() navigates so the init scripts apply to the restored
// pages — without this the handed-off browser had cmdline args but no
// JS stealth (no webdriver mask, no chrome.* shape, no toString proxy).
const { applyStealth } = await import('./stealth');
await applyStealth(newContext);
if (Object.keys(this.extraHeaders).length > 0) {
await newContext.setExtraHTTPHeaders(this.extraHeaders);
}
await this.restoreState(state);
if (this.closing) throw new Error('Browser is shutting down');
if (this.browser) {
const browserRef = this.browser;
this.onBrowserDisconnected(this.browser, () => {
if (this.intentionalDisconnect) return;
void handleChromiumDisconnect(browserRef);
});
}
this.connectionMode = 'headed';
this.isHeaded = true;
this.dialogAutoAccept = false; // User controls dialogs in headed mode
this.chromiumProcInfo = null;
try { this.onHeadedPromotion?.(); }
catch (err) { console.warn('[browse] Headed promotion callback failed:', err); }
// 4. Close old headless browser (fire-and-forget)
this.detachDisconnectHandlers(previous.browser);
previous.browser.close().catch(() => {});
return [
`HANDOFF: Browser opened at ${currentUrl}`,
...(this.xvfb ? ['DISPLAY: Off-screen Xvfb; a separate remote desktop is required for human interaction.'] : []),
`MESSAGE: ${message}`,
`STATUS: Waiting for user. Run 'resume' when done.`,
].join('\n');
} catch (err: unknown) {
await newContext.close().catch(() => {});
if (!this.closing) {
Object.assign(this, previous);
this.recheckTabGuardrailsOnClose();
}
if (!previousDisplay) this.closeOwnedDisplay();
if (this.closing) return 'ERROR: Browser is shutting down';
const msg = err instanceof Error ? err.message : String(err);
return `ERROR: Handoff failed during state restore — ${msg}. Headless browser still running.`;
} finally {
this.handoffPrevious = null;
}
}
/**
* Resume AI control after user handoff.
* Clears stale refs and resets failure counter.
* The meta-command handler calls handleSnapshot() after this.
*/
resume(): void {
// Clear refs and frame on the active session
try {
const session = this.getActiveSession();
session.clearRefs();
session.setFrame(null);
} catch {}
this.resetFailures();
}
getIsHeaded(): boolean {
return this.isHeaded;
}
// ─── Auto-handoff Hint (consecutive failure tracking) ───────
incrementFailures(): void {
this.consecutiveFailures++;
}
resetFailures(): void {
this.consecutiveFailures = 0;
}
getFailureHint(): string | null {
if (this.consecutiveFailures >= 3 && !this.isHeaded) {
return `HINT: ${this.consecutiveFailures} consecutive failures. Consider using 'handoff' to let the user help.`;
}
return null;
}
/**
* Run a command and surface any navigation the guard blocked while it ran.
* The block reason replaces the command's own result or error (often
* "navigation interrupted"), so the caller learns why the tab is blank.
*/
async failIfNavigationBlocked<T>(page: Page, work: Promise<T>): Promise<T> {
const outcome = await work.then((value) => ({ value }), (error) => ({ error }));
const guard = this.navigationGuards.get(page);
while (guard && guard.pending.size > 0) await Promise.all([...guard.pending]);
const blocked = guard?.blocked ?? null;
if (guard) guard.blocked = null;
if (blocked) throw new Error(blocked);
if ('error' in outcome) throw outcome.error;
return outcome.value;
}
/**
* D2: validateNavigationUrl only sees explicit navigations. Redirect hops and
* page-driven navigations (links, scripts, forms, frames) arrive here as
* navigation requests; one that targets a blocked address blanks the tab and
* is reported by failIfNavigationBlocked.
*/
private guardNavigations(page: Page): void {
if (this.navigationGuards.has(page)) return;
const guard = { pending: new Set<Promise<void>>(), blocked: null as string | null };
this.navigationGuards.set(page, guard);
page.on('request', (req) => {
if (!req.isNavigationRequest()) return;
const check: Promise<void> = blockedNavigationReason(req.url()).then(async (reason) => {
if (!reason || page.isClosed()) return;
guard.blocked = reason;
console.warn(`[browse] ${reason} (navigation from ${req.frame().url() || 'a new page'}; tab reset to about:blank)`);
// A target that fails fast commits its error page around the reset, so
// let it settle (bounded; a hanging target is cut off by the reset),
// then blank the tab until it stays blank (about:blank loads at once).
await Promise.race([req.response().catch(() => null), new Promise((resolve) => setTimeout(resolve, 1_000))]);
// Leaving an error page can commit a second about:blank after the reset
// resolves; wait for the main frame to stay quiet so the next command's
// navigation is not interrupted by it.
for (let attempt = 0; attempt < 3 && !page.isClosed(); attempt++) {
await page.goto('about:blank', { waitUntil: 'load', timeout: 5_000 }).catch(() => {});
const late = await page.waitForEvent('framenavigated', { predicate: (frame) => frame === page.mainFrame(), timeout: 250 })
.then(() => true, () => false);
if (!late && page.url() === 'about:blank') break;
}
}).finally(() => { guard.pending.delete(check); });
guard.pending.add(check);
});
}
// ─── Console/Network/Dialog/Ref Wiring ────────────────────
private wirePageEvents(page: Page) {
const pages = this.pages;
const tabSessions = this.tabSessions;
this.guardNavigations(page);
// Track tab close — remove from pages and sessions maps, switch to another tab
page.on('close', () => {
for (const [id, p] of pages) {
if (p === page) {
pages.delete(id);
tabSessions.delete(id);
console.log(`[browse] Tab closed (id=${id}, remaining=${pages.size})`);
// If the closed tab was active, switch to another
const remaining = [...pages.keys()];
const fallback = remaining.length > 0 ? remaining[remaining.length - 1]! : 0;
if (pages === this.pages) {
if (this.activeTabId === id) this.activeTabId = fallback;
} else if (this.handoffPrevious?.pages === pages && this.handoffPrevious.activeTabId === id) {
this.handoffPrevious.activeTabId = fallback;
}
break;
}
}
if (pages === this.pages) this.recheckTabGuardrailsOnClose();
});
// Clear ref map on navigation — refs point to stale elements after page change
// (lastSnapshot is NOT cleared — it's a text baseline for diffing)
page.on('framenavigated', (frame) => {
if (frame === page.mainFrame()) {
// Find the TabSession for this page and clear its per-tab state
for (const session of tabSessions.values()) {
if (session.page === page) {
session.onMainFrameNavigated();
break;
}
}
}
});
// ─── Dialog auto-handling (prevents browser lockup) ─────
page.on('dialog', async (dialog) => {
const entry: DialogEntry = {
timestamp: Date.now(),
type: dialog.type(),
message: dialog.message(),
defaultValue: dialog.defaultValue() || undefined,
action: this.dialogAutoAccept ? 'accepted' : 'dismissed',
response: this.dialogAutoAccept ? (this.dialogPromptText ?? undefined) : undefined,
};
addDialogEntry(entry);
try {
if (this.dialogAutoAccept) {
await dialog.accept(this.dialogPromptText ?? undefined);
} else {
await dialog.dismiss();
}
} catch {
// Dialog may have been dismissed by navigation
}
});
page.on('console', (msg) => {
addConsoleEntry({
timestamp: Date.now(),
level: msg.type(),
text: msg.text(),
});
});
page.on('request', (req) => {
addNetworkEntry({
timestamp: Date.now(),
method: req.method(),
url: req.url(),
});
});
page.on('response', (res) => {
// Find matching request entry and update it (backward scan)
const url = res.url();
const status = res.status();
for (let i = networkBuffer.length - 1; i >= 0; i--) {
const entry = networkBuffer.get(i);
if (entry && entry.url === url && !entry.status) {
networkBuffer.set(i, { ...entry, status, duration: Date.now() - entry.timestamp });
break;
}
}
});
// Capture response sizes via requestfinished — but DO NOT call
// response.body() here. Pre-fix, this listener materialized every
// response body across CDP just to read .length: multi-GB/hour of
// Buffer churn on long-lived headed Chromium with media-heavy
// pages, the primary Bun-side accelerant on the gbrowser-OOM
// investigation. req.sizes() pulls from the Network.loadingFinished
// event Chromium already emits — accurate for chunked transfer,
// gzip-compressed responses, and streaming media, all the cases
// where the previous Content-Length-header approach would have
// missed the size.
//
// The "single context-level CDP listener" architecture (D10's
// stretch goal — would reduce per-page listener count from N to 1
// via Target.setAutoAttach) is deferred. TODOS.md tracks it.
page.on('requestfinished', async (req) => {
try {
const sizes = await req.sizes().catch(() => null);
if (!sizes) return;
const url = req.url();
const size = sizes.responseBodySize ?? 0;
for (let i = networkBuffer.length - 1; i >= 0; i--) {
const entry = networkBuffer.get(i);
if (entry && entry.url === url && !entry.size) {
networkBuffer.set(i, { ...entry, size });
break;
}
}
} catch {
// Best-effort: requestfinished fires for aborted/cached requests too,
// where sizes() is unavailable. Missing size is acceptable; an
// unbounded throw would noise the console for every cache hit.
}
});
}
}