← Commit history

Document the frozen-event-loop bridge restart: never run synchronous exec on a verb or close path, and how to burst-test for it

John Lauer ·c9b30ce8b7 ·3mo ago ·parent 702c0b5
1 file changed +24
dev-skills/pup-bridge-debug/SKILL.md+24
@@ -743,3 +743,27 @@ dropping to an interactive banner here; `cmd /c` and AD's `process_list` verb ar **Test gotcha:** do NOT recover a crashed tab with `browser_reload` if you crashed it by navigating to `chrome://crash` — reload re-loads `chrome://crash` and re-crashes. Use `browser_navigate` to a real URL, or reload only when the tab's real URL is benign.++## The bridge "crashed" toast after closing several windows (v1.9.81) — never run sync exec on a hot path++AD toasted "restarting the pup browser bridge (it crashed earlier)" right after a run of test-window+closes. The bridge had not thrown — it was FROZEN. The v1.9.78 orphan-renderer reap ran a PowerShell+CIM query via `execFileSync` (timeout 8s) ON THE CLOSE PATH. A synchronous exec blocks Node's entire+event loop for its full duration, and PowerShell on this box is flaky (a broken profile drops `-File`+invocations to an interactive banner; CIM can just be slow), so each close could freeze the bridge+for up to 8s. Close five windows in a row and AD's health check reads the bridge as unresponsive and+respawns it. Self-inflicted: the "fix" for issue #16 caused the next incident.++Rules:+- **NEVER `execSync`/`execFileSync` inside a verb handler, close path, or timer callback.** Use the+  async `execFile` (or the runPsHidden*Async helpers) and treat the result as best-effort. The only+  acceptable sync execs run at startup, before the server accepts requests.+- A frozen event loop and a crash are indistinguishable from the outside (both = missed health+  pings = watchdog respawn). If AD reports a "crash" but there's no stack in the log, hunt for a+  BLOCKING call first.+- Verification that catches this: after any change to close/launch paths, do a burst test — N rapid+  `browser_close_window` calls each immediately followed by `ping`, asserting round-trip stays+  sub-second (measured ~600ms healthy; the sync version stalls multi-second).+- PowerShell reliability on user boxes is NOT a given. `powershell -File` can drop to an interactive+  banner (profile damage) and burn its whole timeout. For process queries prefer AD's `process_list`+  verb or `cmd /c` one-liners; keep PS for things only PS can do, always async, always with a timeout.