Skip to content

fix(open-gstack-browser): disable parent watchdog on connect#963

Open
marksalmon wants to merge 1 commit intogarrytan:mainfrom
marksalmon:fix/open-gstack-browser-watchdog
Open

fix(open-gstack-browser): disable parent watchdog on connect#963
marksalmon wants to merge 1 commit intogarrytan:mainfrom
marksalmon:fix/open-gstack-browser-watchdog

Conversation

@marksalmon
Copy link
Copy Markdown

Summary

The open-gstack-browser skill currently fails its first-run experience inside Claude Code: the headed Chromium window appears for a few seconds then vanishes, and the user has no idea why. Root cause is the v0.15.15.0+ parent-process watchdog killing the browse server because the bash process that spawned $B connect has already exited.

Repro

  1. In Claude Code, invoke /open-gstack-browser on a clean machine (no prior browse session)
  2. The skill runs $B connect inside a Bash tool call
  3. Chromium launches in headed mode, user starts looking for the extension
  4. ~15 seconds later, the window disappears. $B focus reports focus requires headed mode. Run $B connect first.

Hit this today upgrading from v0.15.15.0 → v0.16.2.0 in a real Claude Code session. Had to reverse-engineer the fix live with the user watching the browser keep disappearing. Not a great first-run.

Root cause

  • browse/src/server.ts:740-751 implements the parent-process watchdog that exits the server when its recorded parent PID dies.
  • browse/src/cli.ts:235 records the CLI's own PID as BROWSE_PARENT_PID when spawning the server.
  • When Claude Code runs $B connect via a Bash tool call, the bash subprocess is the CLI's parent. Bash exits immediately after connect returns (which it does as soon as Chromium finishes launching), so the watchdog sees its parent gone and kills everything ~15s later.
  • This is the same issue v0.15.15.1 fixed for pair-agent (see changelog), but open-gstack-browser was never updated to use the same escape hatch.

The escape hatch already exists: browse/src/cli.ts:847-848 explicitly honors BROWSE_PARENT_PID=0 from the parent environment as a "disable watchdog" signal. /pair-agent uses this in browse/src/cli.ts:988.

Fix

Two tiny updates to open-gstack-browser/SKILL.md.tmpl:

  1. Step 1 (Connect): prefix $B connect with BROWSE_PARENT_PID=0 and add a critical-warning paragraph explaining why, so future skill maintainers don't accidentally remove it.
  2. Step 2 (Verify) + Step 3 Option C (troubleshooting): swap $B status for $B focus as the verification command. $B status is not read-only — if no server is running, it silently spawns a new one in default launched (headless) mode and reports healthy, which completely masks the failure this PR is trying to diagnose. $B focus fails loudly when the headed window is gone and never auto-spawns anything, so it's a strictly better diagnostic.

Only the template (SKILL.md.tmpl) is touched. The generated SKILL.md will be regenerated from the template on next ./setup run.

Test plan

  • Applied the fix locally, re-ran /open-gstack-browser from a clean state. Headed Chromium stayed alive past the 15s window, survived a long session, $B focus and $B snapshot -i worked against the live page.
  • Verified BROWSE_PARENT_PID=0 is the documented escape hatch in browse/src/cli.ts:847-848.
  • (For maintainer) Verify the ./setup regen pipeline produces a SKILL.md that matches the new template.

🤖 Generated with Claude Code

When Claude Code spawns `$B connect` via a Bash tool call, the bash
subprocess exits immediately after connect returns (connect itself
doesn't block). The v0.15.15.0+ parent-process watchdog in
browse/src/server.ts:740-751 then sees "parent gone" and kills the
headed Chromium ~15 seconds later.

Symptom: the Chromium window appears for a few seconds then vanishes,
and subsequent `$B focus` calls fail with "requires headed mode".

Fix: prefix the connect command with `BROWSE_PARENT_PID=0`, which the
CLI already honors as "disable watchdog" (browse/src/cli.ts:847). This
is the same escape hatch /pair-agent uses for its tunneled sessions.

Also swap the verification step from `$B status` to `$B focus`:
`status` is not read-only — if no server is running, it silently
spawns a new one in default `launched` (headless) mode and reports
`healthy`, which masks the exact failure this patch is trying to
diagnose. `focus` fails loudly when the headed window is gone and
never auto-spawns anything.

The Step 3 "Something went wrong" troubleshooting flow is updated
for the same reason: check `focus` first, not `status`.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant