`lock_root` dereferenced `$HOME` unconditionally, so under `set -u` the script
died with "HOME: unbound variable" in any environment that starts without it —
even when `PLAYWRIGHT_RESOURCE_LOCK_DIR` made HOME irrelevant. Surfaced by
running the suite under vitest's node environment, where `process.env` is
patched and spreading it does not carry HOME through to the child.
Resolve the lock path in order (explicit override, XDG_CACHE_HOME, HOME) and
fail with a clear message only when none of them is set. The test now names
PATH and HOME explicitly instead of spreading process.env.
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.
Tommaso Casaburi