A mutex made of mkdir: the cheap fix for agent fleets fighting over one resource

The sample log is the strongest evidence in the post, and also the most revealing. Eight agents, first acquire at 23:05:52Z, last release at 23:06:35Z, every hold either zero or one second ^[1]. That is a 43 second window in which the lock was actually held for seven seconds, about 16 per cent of the wall clock ^[14]. The gaps between one release and the next acquire run five to six seconds ^[1], which is shorter than the 15 second default poll interval ^[9], so whatever produced that log was not running the shipped defaults ^[13].

Run the defaults and the shape gets worse. A waiter that misses sleeps 15 seconds ^[9], so each handoff costs roughly seven and a half seconds on average, and the post's own guidance adds a one-off 60 second sleep for every agent that is not first in the batch ^[12]. For the twelve subagents the piece opens with ^[6], each holding the resource for a second, that works out at about 155 seconds of wall clock to buy 12 seconds of work at the resource ^[15]. This is not an argument against the lock. It is an argument for setting `--poll` to the length of the critical section, and for the instruction to release immediately after the last resource command rather than after the thinking and the file writes ^[12].

The 1800 second default timeout draws a harder line ^[9]. Queue twelve agents on one resource and the last one in line gives up unless every holder stays under about 164 seconds ^[16]. So the defaults encode an assumption that nobody states: small fleets, short sections. A dozen agents each driving a five minute job through this lock will simply shed its tail.

Stale breaking is where the design trades safety for liveness, and the trade is worth naming. The next agent removes a lock older than `--stale`, 600 seconds by default, logs the break and proceeds ^[8]. That test is the directory's age, not whether the holder is still alive, so a command that outruns ten minutes has its lock deleted underneath it and gains a co-tenant ^[17]. The break lands in the log ^[7], which is how you find out, afterwards.

What makes the primitive worth the trouble is the thing it does not do. There is no lock file content to write and then read back as two separate operations: `mkdir` either creates the directory or fails because it exists, and release is `rmdir` ^[3][4]. The failure the post is guarding against is the interleaved command corrupting another agent's work mid-flight with no record of who held the resource ^[6], and a filesystem primitive settles that without asking twelve prompts to be polite to each other. The startup check closes the adjacent hole: if the lock directory is missing or not writable, the script fails loudly at second zero rather than running as a mutex that never locks anything ^[11].

One caveat on sourcing. The portability claim, that this holds on macOS, Linux, WSL, the BSDs and a NAS in a cupboard, and that there is no NFS weirdness, is the author's own ^[18]. Zero dependencies beyond the Python 3 standard library ^[10] makes it cheap to test that claim yourself on whatever shared storage your fleet actually mounts, which is where an atomic-looking `mkdir` stops being atomic.