Folder rules are not enough. Here is the 144-line lock we ship.

Two layers. Layer one is folder scope. The frontend agent owns components/, the backend agent owns api/, the test agent owns __tests__/. Most file edits never collide because the agents are working in different directories. Layer two is an atomic file-system lock for shared artifacts that do not live in any one folder (the build output, the running process, the append-only test log). Fazm uses a directory-based lock at /tmp/fazm-build.lock created with mkdir, which is atomic on every filesystem. The holder writes its PID into the directory so a second agent can detect a dead holder with kill -0 and reclaim a stale lock. CLAUDE.md tells each agent: do not delete the lock by hand, do not kill the app externally, always read the status file first.

It works for source files. It does not work for the artifacts that exist outside any folder. A native macOS app has one binary in build/, one bundle ID, one running process, one append-only log at /private/tmp/fazm-dev.log, and one status file. None of those belong to a subdirectory of src/. If two agents both call run.sh, one will compile while the other is mid-test; the test agent's logged-in app will get killed by the next pkill in line 75 of run.sh, mid-query. The folder partition cannot represent that. You need a real lock that serializes the actions on the shared singleton, plus a separate signal for whether the running app is currently busy.

Because mkdir is atomic on every filesystem and every macOS version that Fazm ships to. The classic 'echo $$ > /tmp/foo.lock' pattern is not atomic on its own. Two processes can both succeed in writing to it, and the last one wins; whichever process reads next sees a single PID and assumes it owns the lock, but actually two of them are running concurrently. mkdir cannot lose this race: only one mkdir call returns success, the rest return EEXIST. Inside /tmp/fazm-build.lock you will find a 'pid' file with the owner's process ID and a 'script' file with the name of the script that grabbed it (so the failure message can tell you which run.sh is holding things up).

Folder ownership and a binary lock together still are not enough. Consider this case: agent A finished its build, the app is running, and the user is mid-conversation with the app while a test runs. Agent B arrives, acquires the lock, runs run.sh, which kills the existing app at line 75 (pkill -f 'Fazm Dev.app'). The user's in-flight test dies mid-query. The fix is fazm_app_is_idle, which scans the last 2000 lines of /private/tmp/fazm-dev.log for activity patterns (Chat query started, Test query received, Control command received, floating_bar_query_sent, floating_bar_ptt_started, chat_agent_query_completed). If any of those landed in the last FAZM_IDLE_WINDOW_SEC seconds (default 30), agent B releases the lock it just acquired, sleeps 5 seconds, and retries. The app gets to finish its work before the next rebuild.

When mkdir on /tmp/fazm-build.lock fails, the script reads the holder PID from the lock directory and runs kill -0 $holder_pid. If that returns nonzero, the holding process is dead. The script logs 'Removing stale lock from dead process' along with the script name that grabbed it, deletes the lock directory, and retries the mkdir on the next loop iteration. This handles the common case where a previous Claude Code session was Ctrl-C'd at the wrong moment, or a SIGKILL came from somewhere unexpected. No human ever has to rm -rf the lock; the next agent that arrives sees the dead PID and cleans up.

/tmp/fazm-dev-status holds one line in the format '<state> <pid> <ts>'. State is one of 'building', 'running', 'exited', or 'failed'. The agent reads the file, parses the state, and acts: if 'running', it checks 'kill -0 $pid' to confirm the listed app is actually alive (the file can lie if the app was force-killed). If alive, the agent does not need to build; it can send a distributed notification straight to the running app (com.fazm.testQuery is the production hook). If the file shows 'building', the agent waits. If it says 'exited' or is missing, the agent is free to run run.sh. Crucially, the agent does not use pgrep or ps aux to figure this out; those answer a different question (is any process matching this name alive) than the one that matters (is the app I want to test currently in the state I expect).

Two lines in /Users/matthewdi/fazm/CLAUDE.md spell it out. The first tells every agent: just run ./run.sh, it handles everything; if another agent holds the lock, it waits up to 5 minutes. The second tells every agent: never manually delete /tmp/fazm-build.lock, never run rm -rf on it; the lock is a directory managed by the scripts and manually deleting it defeats the concurrency system. Combined with the Multiple Agents in Parallel section in the user's global ~/.claude/CLAUDE.md (build errors you didn't cause, wait 30 seconds and retry), this gives a complete contract: scoped files for source edits, atomic locks for shared artifacts, idle window for running processes, and explicit don'ts for the failure modes that look tempting in the moment.

It is not. The same shape applies to any project where the artifact under contention is not a file: a shared dev server, a Docker container, a port, a database, a queue. The folder partition handles source edits; the file-system lock handles the singleton artifact; the idle window handles the case where the singleton is currently being used by another agent's in-flight task. The specific binaries change (it is sips and pkill on macOS, it would be docker and curl on a server project) but the three-layer pattern is the same. Folder, lock, idle.

Yes. The repository is github.com/mediar-ai/fazm. The lock implementation is at scripts/fazm-lock.sh (144 lines, 5687 bytes). The status file logic is inside run.sh. The CLAUDE.md file at the repo root is the contract every Claude Code agent reads when it picks up work in that repo. You can clone the repo, point your own Claude Code session at it, and the rules apply automatically. Nothing here is theory or a stylized example; this is the working production setup that ships Fazm to thousands of macOS users.

Two builds run concurrently. They both write to build/Fazm.app, they both run pkill -f 'Fazm Dev.app' (so each kills the other's just-launched app), they both append to /private/tmp/fazm-dev.log (the log interleaves and stops being readable), and at some point Codemagic notarization fails because the bundle signature does not match the binary it expects. The cost is roughly a 15-minute rebuild plus a few minutes of confusion reading the interleaved log. That is why CLAUDE.md is explicit about never deleting the lock manually: the cost of doing so falls on whoever has to debug the resulting mess, not on the agent that took the shortcut.