codeaf-suite-lock

Overview ¶

codeaf-suite-lock holds the machine-wide heavy-suite lock while a command runs.

The lock is an advisory file lock held on an open descriptor through internal/filelock, so it works on every platform the release ships (build-cross covers Windows too).

THE LOCK'S LIFETIME IS THE SUITE'S. Not this wrapper's: a wrapper killed mid-run must not unlock a box that is still running a suite. And not any descendant's: an advisory lock lives on the open file description, so a descriptor handed to the suite is kept alive by every process the suite leaves behind, and a test's orphaned shell held this box for eight minutes past a green run on 2026-09-19. So the descriptor goes to a HOLDER beside the suite instead (lock_unix.go): a process of ours that execs nothing, watches the suite's pid, and exits when the suite does. The suite never sees the descriptor, and nothing can inherit it.

If the holder is killed, the lock frees while the suite may still run. That is the failure we choose. The holder waits and does nothing else, so it dies only to a deliberate kill, an out-of-memory sweep or the box going down; it lives in its own session, so a signal aimed at the suite or at this wrapper misses it; the lock file names both pids so a free lock under a running suite can still be read back; and a lock nothing can release stops the box, where a lock freed early costs one concurrent suite.

The lock file carries the suite's pid, when it started, and the holder's pid, only so a refused contender can name who holds it.