Watchdog kills browse server mid-workflow when invoked from skills

[Jud]

Problem

The parent-process watchdog (#808, 5bd05c9e) kills the browse server mid-workflow when the browse tool is invoked from skill scripts (e.g., automating League Lobster or GameChanger schedule updates).

How we use browse

We run a sports league (320 games). After editing the master schedule CSV, we sync changes to League Lobster and GameChanger via browser automation:

1. /setup-browser-cookies — imports authenticated cookies from the real browser
2. $B goto — navigates to the schedule page
3. $B js — finds games, opens edit modals, reads CSRF tokens, submits changes via fetch
4. $B snapshot — verifies edits persisted

This is a multi-step workflow with individual $B commands issued sequentially from a Claude Code skill. Each $B invocation goes through the CLI binary.

What breaks

The browse server is spawned with BROWSE_PARENT_PID: String(process.pid), where process.pid is the CLI invocation that first starts the server. The watchdog polls every 15s and calls shutdown() if that PID is gone.

Two failure modes:

1. Cookie picker dies mid-import. $B cookie-import-browser starts the cookie picker HTTP server (same port as browse). The CLI process that opened it exits. 15 seconds later, the watchdog kills the server. The user is still selecting cookies in their browser but the picker is dead.

2. Browse server dies between commands. Between $B js calls in a skill workflow, the original CLI process can exit. The next $B command finds a dead server and has to restart it (losing the browser session, cookies, and page state).

The pair-agent fix was scoped too narrowly

Commit 05d1a50e fixed this for pair-agent by setting BROWSE_PARENT_PID: '0' in the connect subprocess env. But the startServer() function still passes String(process.pid), so any non-pair-agent invocation still has the watchdog active.

The problem isn't specific to pair-agent. It's any scenario where the browse server needs to outlive the CLI invocation that spawned it. Skill-driven browser automation is a common case.

Our local fix

We patched startServer() in browse/src/cli.ts (two lines) to always pass BROWSE_PARENT_PID: '0':

-    const extraEnvStr = JSON.stringify({ BROWSE_STATE_FILE: config.stateFile, BROWSE_PARENT_PID: String(process.pid), ...(extraEnv || {}) });
+    const extraEnvStr = JSON.stringify({ BROWSE_STATE_FILE: config.stateFile, BROWSE_PARENT_PID: '0', ...(extraEnv || {}) });

-      env: { ...process.env, BROWSE_STATE_FILE: config.stateFile, BROWSE_PARENT_PID: String(process.pid), ...extraEnv },
+      env: { ...process.env, BROWSE_STATE_FILE: config.stateFile, BROWSE_PARENT_PID: '0', ...extraEnv },

This disables the watchdog entirely, which brings back the orphan risk from #808. But the 30-minute idle timeout (BROWSE_IDLE_TIMEOUT) already handles orphans for headless sessions, so in practice the watchdog is redundant for our use case.

Possible upstream fixes

1. Remove the PPID watchdog entirely. The idle timeout already prevents orphans. The watchdog adds a second, stricter lifecycle check that conflicts with legitimate long-running sessions.

2. Track "last attached CLI" instead of "spawning CLI." When a new CLI connects to an existing server, update the monitored PID. The server dies only when no CLI has connected for N seconds.

3. Opt-in watchdog. Default to BROWSE_PARENT_PID: '0' (no watchdog), let users or specific code paths enable it via env var when they know the server should die with the parent.

4. Activity-aware watchdog. Before self-terminating, check lastActivity. If there was recent activity (e.g., within the last 60s), skip the shutdown even if the parent is gone — something is still using the server.

Option 4 feels like the best balance: it prevents orphans (no activity = shutdown) without killing active sessions.

Environment

• macOS (Darwin 24.6.0)
• gstack browse invoked from Claude Code skills
• Workflow: cookie-import + multi-step JS automation on authenticated sites

[haorui]

Confirming this on a different setup — same root cause, same symptoms.

Environment

• macOS Darwin 25.4.0 (arm64)
• gstack 0.16.2.0 (just upgraded from 0.15.15.1, watchdog code at browse/src/server.ts:740-755 is unchanged in both versions)
• Invoked from Claude Code via $B in Bash tool calls (each tool call = fresh zsh child + fresh browse CLI invocation)

Observed behavior
Across a normal multi-step session, every $B <cmd> prints [browse] Starting server... and yields a new server PID:
call 1: PID 78800
call 2: PID 81722 ← starting server again
call 3: PID 11989 ← starting server again
State file <project>/.gstack/browse.json is missing between calls, and pgrep -fl 'bun run.*server\.ts' returns empty. The server is being gracefully shut down (not crashing) — emergency cleanup didn't fire, Chromium SingletonLock is clean.

Root cause confirmation
Added a console.log before shutdown() in the watchdog branch at server.ts:750. It fires every time with Parent process <pid> exited, shutting down, where <pid> matches the just-exited browse CLI process. So the chain in agent environments is:

1. Agent calls Bash tool → new shell → new $B CLI invocation (CLI PID = N)
2. CLI calls startServer() → spawns bun server with BROWSE_PARENT_PID=N
3. CLI finishes its single command and exits (~ms later)
4. Server runs normally for ~15 seconds
5. Watchdog tick sees parent N is gone → graceful shutdown() → deletes state file → exits
6. Next $B call → no state file → spawns fresh server → repeat

This means the advertised "state persists between calls" in the browse skill docs is effectively broken for any caller where the CLI is short-lived — which is every agent harness I know of (Claude Code, Codex CLI, OpenClaw, Cursor).

Why the existing fixes don't cover it

• 05d1a50e only sets BROWSE_PARENT_PID: '0' for the pair-agent subprocess.
• #857 / #869 only skip the watchdog when browserManager.getConnectionMode() === 'headed'.
• Default launched mode via normal $B <cmd> invocation is left vulnerable — which is the most common case.

Suggested fix direction
The activity-aware approach from the original report makes sense. A minimal version:

setInterval(() => {
  // If any command touched the server recently, assume something's still driving it,
  // regardless of who the original spawning CLI was.
  if (Date.now() - lastActivity < 60_000) return;
  try { process.kill(BROWSE_PARENT_PID, 0); }
  catch { shutdown(); }
}, 15_000);
A simpler alternative: don't set BROWSE_PARENT_PID at all by default. Rely on the existing IDLE_TIMEOUT_MS idle timer for orphan cleanup. That already exists at server.ts:727-737 and is already tuned for this exact purpose.

[mkyed]

Confirmation comment for #943

Also affected by #931 (compiled binary PATH lookup)

---

Confirming: browse server dies mid-workflow in skill-driven automation

Hit both #943 and #931 today while building a manual smoke test suite that
browses a running dev site. The browse tool simulates real user flows: login,
fill forms, submit via requestSubmit(), verify page content with $B js.

Environment

• macOS Apple Silicon (Darwin 25.3.0)
• gstack v0.16.3.0
• bun 1.3.11 (mise)
• Claude Code CLI (Opus 4.6)

What we were doing

A smoke test with ~80 sequential $B commands in a single Bash tool call.
Mix of goto, fill, select, wait --networkidle, js (form value
setting and requestSubmit()), and js (content assertions).

Failure pattern

The server survives ~25-40 commands reliably. Somewhere around command 40-50,
the server dies. All subsequent $B calls print:

[browse] Starting server...
[browse] Executable not found in $PATH: "bun"

The server cannot restart because of #931 (compiled binary can't find bun in
PATH even though which bun works in the parent shell).

Evidence that it's the watchdog

• Server PID stays stable through 30 rapid goto calls in isolation
• Server PID stays stable through 10 form submissions in isolation
• BROWSE_IDLE_TIMEOUT is 30 minutes, plenty of headroom
• Failure happens mid-workflow, not after idle time
• Pattern matches Watchdog kills browse server mid-workflow when invoked from skills #943 exactly: the CLI process that started the server
  exits (Bash tool starts a new shell per invocation), and the watchdog
  kills the server

Evidence that #931 compounds #943

Once the watchdog kills the server, recovery fails because the compiled binary
can't find bun to restart. Since the compiled binary IS bun, it should use
process.execPath instead of searching PATH. Until then, the server can never
self-recover mid-script.

Workaround

1. Start each Bash call with $B stop; sleep 1; $B status to force a fresh
   server from the parent shell (where bun IS findable)
2. Keep individual runs under ~40 commands
3. For longer workflows, split into multiple Bash calls with server pre-warm

Suggested fix

Agree with the original reporter: remove the PPID watchdog. The idle timeout
already prevents orphans. The watchdog is actively harmful for skill-driven
workflows where the CLI process is ephemeral.

For #931: the compiled binary should resolve bun using process.execPath
(itself) rather than searching PATH, since the compiled binary IS bun.

[steve-seungjun-lee]

Also hitting this on macOS (Darwin 25.4.0, gstack v0.16.4.0). Every $B invocation from Claude Code returns exit 137 with 0 bytes output — the CLI spawns the server, the CLI exits, watchdog kills server within 15s, next CLI call finds it gone and restarts the cycle.

The local patch from this issue (BROWSE_PARENT_PID: '0') works for us too. An upstream fix would really help skill-based workflows.

[garrytan]

Closing — fixed on main. The browse server now skips idle timeout in headed mode and only activates the parent-process watchdog when BROWSE_PARENT_PID > 0. Landed via PR #847.