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.

.cursor/skills/playwright-cli/SKILL.md

@@ -1,11 +1,24 @@
 ---
 name: playwright-cli
 description: Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, or extract information from web pages.
-allowed-tools: Bash(playwright-cli:*)
+allowed-tools: Bash(playwright-cli:*), Bash(./scripts/pw-session.sh:*)
 ---
 
 # Browser Automation with playwright-cli
 
+## Resource Budget (MUST)
+
+One Playwright browser session may be active at a time, machine-wide. The budget is shared by every worktree and by any other checkout that ships this wrapper, because the contended resource is machine RAM and CPU rather than the repository. Playwright disables normal background throttling, so hidden 5chan pages keep P2P and rendering work active after a check.
+
+- During iteration, use Chrome/Blink only. Run the full cross-browser matrix once the change is ready for final verification.
+- Open every fresh session through `./scripts/pw-session.sh open <session> ...`; it acquires the shared browser slot.
+- Reuse the same engine session for desktop and mobile by resizing it.
+- Close it with `./scripts/pw-session.sh close <session>` in a finally-style cleanup before opening another engine. `close` stops the browser even when the lock was already lost, so it is always the right cleanup call.
+- Run browser engines and profiler batches sequentially. Never spawn browser-driving agents in parallel.
+- Exit code 75 means the slot is busy. Finish non-browser work and retry, or block on `./scripts/pw-session.sh open --wait[=SECONDS] <session> ...` (default 300s). Do not bypass the lock.
+- Never use `playwright-cli close-all` or `kill-all` while concurrent agents may own sessions.
+- A lock left behind by an interrupted workflow clears itself: the next `open` reclaims any slot whose browser is no longer running. Inspect the holder with `./scripts/pw-session.sh status`, which reports whether that browser is still alive. `release <session>` is a last resort for the rare case where `status` cannot verify the browser state.
+
 ## Cross-Browser UI Verification
 
 When using `playwright-cli` to verify rendering, styling, layout, or interactions in this repo, run the relevant flow in all three major browser engines:
@@ -14,12 +27,20 @@ When using `playwright-cli` to verify rendering, styling, layout, or interaction
 - `firefox` for Gecko
 - `webkit` for Safari/WebKit coverage
 
-Use separate named sessions per engine, compare the results, and record any engine-specific differences instead of treating Chromium output as sufficient.
+Use separate short named sessions per engine, compare the results, and record any engine-specific differences instead of treating Chromium output as sufficient. Run them sequentially:
 
 ```bash
-playwright-cli -s=verify-chrome open http://example.com --browser=chrome
-playwright-cli -s=verify-firefox open http://example.com --browser=firefox
-playwright-cli -s=verify-webkit open http://example.com --browser=webkit
+./scripts/pw-session.sh open verify-chrome http://example.com --browser=chrome
+# Run the desktop and mobile flow, then release the slot.
+./scripts/pw-session.sh close verify-chrome
+
+./scripts/pw-session.sh open verify-firefox http://example.com --browser=firefox
+# Run the desktop and mobile flow, then release the slot.
+./scripts/pw-session.sh close verify-firefox
+
+./scripts/pw-session.sh open verify-webkit http://example.com --browser=webkit
+# Run the desktop and mobile flow, then release the slot.
+./scripts/pw-session.sh close verify-webkit
 ```
 
 ## Quick start
@@ -242,6 +263,7 @@ playwright-cli -s=mysession close  # stop a named browser
 playwright-cli -s=mysession delete-data  # delete user data for persistent session
 
 playwright-cli list
+# Never use these during concurrent agent work; they affect unrelated sessions.
 # Close all browsers
 playwright-cli close-all
 # Forcefully kill all browser processes

.cursor/skills/playwright-cli/references/session-management.md

@@ -1,6 +1,12 @@
 # Browser Session Management
 
-Run multiple isolated browser sessions concurrently with state persistence.
+Manage isolated browser sessions with state persistence. In 5chan, keep only one session active machine-wide and use the shared wrapper for the open/close lifecycle.
+
+```bash
+./scripts/pw-session.sh open verify-chrome https://5chan.localhost --browser=chrome
+playwright-cli -s=verify-chrome snapshot
+./scripts/pw-session.sh close verify-chrome
+```
 
 ## Named Browser Sessions
 
@@ -60,25 +66,18 @@ playwright-cli open example.com  # Uses "mysession" automatically
 
 ## Common Patterns
 
-### Concurrent Scraping
+### Sequential Cross-Browser Verification
 
 ```bash
 #!/bin/bash
-# Scrape multiple sites concurrently
+# Keep one browser active at a time, machine-wide.
 
-# Start all browsers
-playwright-cli -s=site1 open https://site1.com &
-playwright-cli -s=site2 open https://site2.com &
-playwright-cli -s=site3 open https://site3.com &
-wait
-
-# Take snapshots from each
-playwright-cli -s=site1 snapshot
-playwright-cli -s=site2 snapshot
-playwright-cli -s=site3 snapshot
-
-# Cleanup
-playwright-cli close-all
+for engine in chrome firefox webkit; do
+  session="verify-$engine"
+  ./scripts/pw-session.sh open "$session" https://5chan.localhost --browser="$engine"
+  playwright-cli -s="$session" snapshot
+  ./scripts/pw-session.sh close "$session"
+done
 ```
 
 ### A/B Testing Sessions
@@ -154,7 +153,8 @@ playwright-cli -s=s1 open https://github.com
 playwright-cli -s=auth close
 playwright-cli -s=scrape close
 
-# Or stop all at once
+# Do not use these global commands while concurrent agents may own sessions.
+# Stop all at once
 playwright-cli close-all
 
 # If browsers become unresponsive or zombie processes remain