gatelock

Overview ¶

Command gatelock is the machine-wide gate lock: a Playwright sweep needs the machine to itself (two sweeps in two worktrees, or a sweep beside `make test-race`, go red — kb:lesson/concurrent-e2e-across-worktrees-goes-red), while Go unit-test runs may overlap each other. So every Playwright run holds it exclusive (web/playwright.config.ts globalSetup), `make test` / `make test-race` hold it shared, and `gates.sh` holds it once around a whole gate run.

go build -o bin/gatelock ./tools/gatelock   # never `go run`: it exits 1 for any non-zero
                                            # program exit, masking the child's code and 75
bin/gatelock run  (--exclusive|--shared) [--wait <dur>] -- <cmd> [args…]
bin/gatelock hold (--exclusive|--shared) [--wait <dur>]
bin/gatelock status

`run` execs cmd as a child with the lock held and exits with its code. `hold` prints `acquired` once it has the lock, then blocks until stdin closes — a Node parent that ends (or is SIGKILLed) closes the pipe and so releases the lock. `status` prints `free` or one holder per line.

Exit codes: 0 ok; 1 error (including the exclusive-under-shared self-deadlock refusal); 2 usage; 75 (EX_TEMPFAIL) the wait expired — rerun when free, nothing failed. GNU make exits 2 on any failed recipe, so 75 reaches a caller only from a direct invocation (gates.sh re-execs itself under `run`); elsewhere the stderr message is the contract.

Re-entrancy: `run` and `hold` export MUSTER_GATELOCK=<mode> to the child. A nested call no-ops when an ancestor's mode covers it (exclusive covers all; shared covers shared), and refuses (exit 1) when it would need exclusive under a shared ancestor.