The deep dive · chapter 7 · 7 steps

Two people, one checkout

What actually collides when two sessions share a folder, why the lock isn't the answer, and the one-flag fix.

1. 1. The problem — somebody clobbered something

   Two people, or two assistant sessions, working in the same checked-out folder at the same time. Somewhere around the end of the day, work goes missing and nobody can say quite how.

   Everyone's first theory is that the two sessions overwrote each other's files. That theory is wrong, which matters, because it sends you looking for a locking mechanism when what you needed was a second folder.

2. 2. What actually breaks

   Two people, one folder

   aidlc — zsh

   $ aidlc claim price-alerts
   
   price-alerts is claimed by session sam-1130 (not stale)
     — release it first or wait for timeout

   .git/aidlc/claims/price-alerts.yaml

   session: sam-1130
   claimed_at: 2026-09-05T11:30:00Z
   renewed_at: 2026-09-05T12:05:00Z

   ← backstep 1 of 3next →

   The state files were never the problem. They're small, they're separated per piece of work, and two sessions on two different pieces of work barely touch the same bytes.

   Git is the problem. One checked-out folder has exactly one current branch. When the other session starts something and cuts a branch, your checkout moves too — you are now sitting on their branch with your half-finished changes still on disk. And the moment either session stages everything and commits, the other's work goes in under the wrong name, on the wrong branch, in the wrong change.

   There's a second casualty that's easier to miss. Two overlapping claims means usage records can't be assigned to either piece of work. On this project, two concurrent sessions in one folder lost all of their cost data — not some of it. Both pieces of work read as unknown, because every record had two equally plausible owners.

3. 3. What the lock is actually for

   There is a lock. It's the claim from the cost chapter, and it lives in a shared location so every folder of the same repository sees the same set.

   What it does: tells you somebody else is already inside this piece of work, before you start editing its documents. It also expires — sixty minutes by default — because a session that crashes must not lock work forever. A claim past its timeout counts as stale and can be taken over, and if you're in a long session you renew it:

   aidlc claim price-alerts --renew
   

   What it does not do: stop the git collision. It can't. Nothing about a lock on a piece of work prevents a branch switch in a shared folder.

   So a claim tells the tool who is working on what. It is not the answer to concurrency, and treating it as one is how people end up surprised.

4. 4. The fix, which is one flag

   A git worktree gives you a second folder that shares one history. Two branches checked out at once, no collision:

   aidlc start bugfix --name login-500 --worktree
   

   That creates the folder, creates the branch, and does all further work for that piece of work inside it. Both folders still see the same claims, because claims live in the shared git directory rather than in either checkout — which is exactly the property you want: separate branches, shared knowledge of who's doing what.

   One thing to know about worktrees: .aidlc/roadmap/ is written to the primary checkout, not the worktree's copy. Two worktrees each capturing ideas into their own copy would give you two idea lists that both look complete.

5. 5. When you can't have a branch

   Sometimes you want to work on something without touching code at all — writing requirements, reviewing a design, triaging ideas — while somebody else holds the checkout:

   aidlc start quick-feature --name pricing-rework --no-code
   

   That records no branch, and the implementation step stays blocked until one exists. It's not a workaround for the collision; it's an admission that this work doesn't need code yet, which is often true for the first two steps of anything.

6. 6. Checkpoint

   checkpoint

   Two sessions are working in the same folder at the same time. What breaks first?

   • The state files — both sessions write them.
   • Git — one folder has one current branch.
   • Nothing, as long as they work on different features.

   This checkpoint needs JavaScript.

7. 7. What you can do now

   You can start concurrent work without losing any of it, and you know which of the three options to reach for: a worktree when the second piece of work needs code, --no-code when it doesn't, and waiting when neither is true. And you know that a lock on the work is not a lock on the folder.

   Next, and last: making it yours — the lessons that come back, the chores that become skills, and the tool that repairs the repository.