mac-lock (cross-track RAM mutex)
A vm_stat-gated, mkdir-atomic mutex that serialises memory-heavy work across two tracks on a single 128GB Mac, with a 40GB headroom self-check and stale-lock auto-reclaim.
Description
Born from a real OOM/watchdog crash: it prevents two memory-heavy tracks from colliding on one machine by gating on live memory pressure and reclaiming stale locks automatically.
Highlights
- Serialises memory-heavy work across two independent tracks on one Mac
- Gated on live memory pressure read from vm_stat
- Atomic acquisition via mkdir, a POSIX-atomic operation
- Headroom self-check (~40GB) before granting the lock
- Auto-reclaims stale locks left by a dead process
mac-lock is a small mutex for a specific failure: two heavy jobs on one large-memory Mac, each fine on its own, that crash the machine when their memory spikes happen to overlap. It was born from exactly that event — an out-of-memory / watchdog crash where two memory-heavy tracks collided on a single 128GB machine. Rather than cap either job, mac-lock simply makes them take turns through the memory-critical section.
How it works
The lock is acquired by creating a directory with mkdir, which is atomic on POSIX filesystems: if two tracks race, exactly one succeeds, so neither can falsely believe it holds the lock. Before granting, it runs a headroom self-check — reading live memory pressure from vm_stat and confirming there is roughly 40GB of headroom — so the lock reflects the machine's actual state, not just who asked first. Because a crashed holder would otherwise leave the lock wedged forever, it also detects and auto-reclaims stale locks abandoned by a dead process.
Why it matters
The scope is deliberately narrow and honest: it is single-machine and macOS-specific, because it depends on vm_stat. That constraint is the point — it solves the concrete problem it was built for without pretending to be a distributed scheduler. Within the wider work on governed agent systems, it is a minimal, evidence-led example of the same idea: read the real state of a shared resource, gate access on it, and fail safely rather than confidently. Licensed Apache-2.0.
Limitations
- Single-machine, macOS-specific (vm_stat).
- Repository is migrating off the retiring Octoryn Research domain.