Many sessions run at once on one machine, and they share a vault, a set of repositories, and a handful of jobs that must not be done twice. Concurrency is the goal here, not the enemy. The work is to let sessions run in parallel wherever they can, and to hold apart only the few places where two of them would genuinely collide. Four mechanisms do that. Two of them prevent overlap; two of them enable it.
It is tempting to think of concurrency control as one idea: stop things treading on each other. But the mechanisms here differ in kind. Some exist to stop two sessions doing the same thing at the same time. Others exist to let two sessions run at the same time without ever reaching for the same thing. Keeping the two apart is the key to reading the rest of this page.
A job that two sessions must never run together is held to one at a time, or an unsafe action on shared state is refused outright.
Work is handed to exactly one session, or split into private copies, so two sessions can run in parallel without contending at all.
Each mechanism has a job and a nature. Read the role badge on each: it says whether the mechanism is there to prevent an overlap that cannot be allowed, or to enable two sessions to proceed at once.
Some jobs genuinely cannot overlap. Sorting the inbox, trimming memory, and writing a handoff all rewrite shared vault state, and two of them at once would corrupt it. The lock serialises them: one at a time, across every session on the machine.
A session takes the lock before it starts one of these jobs. A second session that reaches for it while it is held is refused, and told which session holds it, rather than being allowed to proceed and clash. The lock is released the moment the job is done, and cannot be held forever: it lapses on the next turn, at session end, or after a timeout, so a session that dies mid-job never strands it. The skills that run under it are the vault-mutating ones: , , , and their siblings.
Deferred wrap-up work is left as a breadcrumb for a later session to finish. If several sessions start and all see the same breadcrumb, the finishing work must fall to exactly one of them, not all of them.
Each session tries to claim the job by renaming the breadcrumb to itself. The rename is atomic, so the first session wins and the rest find it already taken and move on. This does not hold anyone back: it hands different jobs to different sessions, so they proceed in parallel. If the session that claimed a job dies before finishing, the claim is recognised as stale and released, so the job is picked up rather than lost.
Two sessions editing code at once would tread on each other if they shared one checkout: the same files, the same branch, the same working tree.
Instead each session works in its own checkout of the repository, a worktree, with its own branch and its own files. Parallel edits never touch the same paths, so the contention is not resolved after the fact, it is designed out. The sessions converge only when their branches merge, on their own terms, which is where the usual review happens.
A few actions on shared state are unsafe no matter which session takes them: committing straight to the main branch, or writing into the primary checkout that other sessions read from.
These are refused at the point of the action, before they land. A commit aimed at the main branch is blocked; a write aimed at the primary checkout is redirected to the session's own worktree. The guard does not serialise anything, it simply stops a specific mistake, so a session cannot corrupt the state the others depend on.
Only two of the four mechanisms actually stop a session doing something: the lock, and the guards. The other two exist so that sessions never need stopping, because they were handed separate work or given separate files in the first place. A design that leans on partition and isolation needs to serialise far less than one that reaches for a lock at every turn.
A lock is the heaviest of the four: while it is held, every other session that wants it waits. So it is reserved for the jobs that genuinely cannot overlap, the ones that rewrite shared vault state, and nothing else runs through it. Everywhere else, the cheaper move is to remove the contention rather than to police it.
The four compose. Sessions run in their own worktrees, take separate jobs off the breadcrumb queue, serialise only the vault writes that must be serial, and are stopped at the guard from the handful of actions that are never safe. The result is many sessions at once on one machine, colliding almost nowhere.