chore(agents): add a machine-wide Playwright browser resource budget

Playwright disables normal background throttling, so a hidden 5chan page keeps
doing P2P and rendering work after a check finishes. Agents verifying in
parallel across worktrees stacked whole browser engines on one machine.

Add scripts/pw-session.sh, a wrapper that permits one active Playwright browser
at a time and records who holds it:

- The lock is machine-wide, not per-repository, because the contended resource
  is RAM and CPU. Every worktree and checkout shares one slot.
- Acquisition is an atomic mkdir. Stale locks clear themselves: `open` reclaims
  any slot whose recorded browser is no longer `status: open` in
  `playwright-cli list --all`, so an interrupted workflow cannot strand the
  budget. When that list cannot be read the lock is left alone, so a broken CLI
  never silently disables the budget.
- `open` exits 75 when the slot is busy; `--wait[=SECONDS]` blocks instead.
- `close` always stops the browser, even when the lock was already lost, and
  never releases a slot held by a different session.
- `status` reports the holder and whether its browser is still alive.

Agent policy now runs browser engines and profiler batches sequentially, uses
Chrome/Blink during iteration and the full engine matrix only for final
verification, and never uses `close-all` or `kill-all` while other agents may
own sessions.

Covered by scripts/pw-session.test.js.
This commit is contained in:
Tommaso Casaburi
2026-08-01 19:21:01 +02:00
parent a67c66de0d
commit 1a33f7dc88
31 changed files with 835 additions and 169 deletions
@@ -30,7 +30,7 @@ Throttling is **Chromium-only** (CDP). It does not work on `firefox` or `webkit`
```bash
# open a Chromium session, throttle it to a mid-tier phone, then verify as usual
playwright-cli -s=lowspec open https://5chan.localhost --browser=chrome
./scripts/pw-session.sh open lowspec https://5chan.localhost --browser=chrome
./scripts/pw-throttle.sh lowspec mid
playwright-cli -s=lowspec snapshot
playwright-cli -s=lowspec screenshot --filename=lowspec-mid.png
@@ -43,7 +43,7 @@ playwright-cli -s=lowspec screenshot --filename=lowspec-mid.png
# reset and finish
./scripts/pw-throttle.sh lowspec off
playwright-cli -s=lowspec close
./scripts/pw-session.sh close lowspec
```
## Measuring, not guessing
@@ -59,5 +59,6 @@ playwright-cli -s=lowspec eval "() => Math.round(performance.getEntriesByType('n
## Caveats
- Chromium-only. Skip on Firefox/WebKit sessions; keep those checks unthrottled.
- Low-spec emulation is a measurement pass, not a machine-resource control. Hold the machine-wide browser slot for the whole pass and close it immediately afterward.
- The `low` latency is intentionally aggressive; if requests time out, fall back to `mid`.
- For render/rerender hotspots after a slow result, use the `profile-browsing` skill (it drives `playwright-cli` + react-scan) on the already-throttled session.