app
Pup - the AI's own browser
Public Made by Adomby adom
pup gives your AI a real browser on your desktop that it drives completely, in the background, signed in as you: windows that never jump in front of your work, one shared profile that learns your logins, and every window labeled on the taskbar with its AI thread's name.
← 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
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.