Improve support for sub-agents on same branch

[pjbgf]

https://entire.io/gh/entireio/cli/trails/376

Multiple sessions sharing a shadow branch (same base commit + worktree) raced on the final SetReference at the end of WriteTemporary, and the race was silently lost to last-writer-wins. A stress test driving 8 concurrent sessions × 4 checkpoints each saw 75-94% of checkpoints orphaned per run.

Wrap WriteTemporary and WriteTemporaryTask in a per-shadow-branch flock under /entire-shadow-locks/ and replace the bare SetReference with git update-ref <ref> <new> <old> (CAS) plus a small retry budget. The flock serializes our own writers across goroutines and processes; the CAS catches external git update-ref callers as defense in depth.

After: 30/30 race iterations land all 32 checkpoints with no losses.

Before vs after

Test scenario	Before	After
20 race iterations, 8 sessions × 4 checkpoints	75–94% commits lost	0 commits lost
30 race iterations (final)	n/a	0 commits lost

---

Note

Medium Risk
Changes shadow-branch ref update semantics and introduces cross-process locking plus a CAS retry loop, which can affect checkpoint correctness and potentially block/hang if locking/backoff misbehaves. Scope is limited to checkpoint write paths and is covered by a new concurrency regression test.

Overview
Prevents concurrent checkpoint writers from clobbering shadow branches. Temporary checkpoint writes (WriteTemporary and WriteTemporaryTask) are now wrapped in a per-shadow-branch filesystem lock and update the branch ref using git update-ref compare-and-swap with bounded retries and jittered backoff.

Adds platform-specific flock implementations (Unix/Windows), stores lockfiles under <git-common-dir>/entire-shadow-locks/, and introduces a stress test that runs many concurrent SaveStep calls against the same shadow branch and validates the resulting commit chain/tree consistency.

^{Reviewed by Cursor Bugbot for commit 7350c3f. Configure here.}

[Copilot]

Pull request overview

Fixes a checkpoint-loss race where multiple AI-agent sessions sharing the same shadow branch (same base commit + worktree) raced on the final SetReference at the end of WriteTemporary/WriteTemporaryTask. The fix combines a per-shadow-branch cross-process flock with a CAS-style git update-ref <ref> <new> <old> and a small randomized-backoff retry loop, plus a stress test that catches regressions.

Changes:

• Introduce withShadowBranchFlock (file-based exclusive lock under <git-common-dir>/entire-shadow-locks/) and casUpdateShadowBranchRef (shell-out CAS via git update-ref), with retry budget and jittered backoff.
• Refactor WriteTemporary and WriteTemporaryTask to hold the flock around a retry loop that re-reads parent, re-builds the tree, creates the commit, and CASes the ref.
• Add a concurrent stress test (TestSaveStep_ConcurrentSessionsSameShadowBranch) driving 8 sessions × 4 checkpoints sharing a shadow branch and validating shadow-branch internal consistency and commit count.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
cmd/entire/cli/checkpoint/shadow_ref.go	New flock-path helper, withShadowBranchFlock, and casUpdateShadowBranchRef with jittered backoff.
cmd/entire/cli/checkpoint/temporary.go	Wrap shadow-branch writes in flock + CAS retry loop; restructure WriteTemporary/WriteTemporaryTask.
cmd/entire/cli/checkpoint/flock_unix.go	New Unix flock primitive (syscall.Flock) for the shadow lock.
cmd/entire/cli/checkpoint/flock_windows.go	New Windows flock primitive (LockFileEx) for the shadow lock.
cmd/entire/cli/strategy/manual_commit_concurrent_test.go	New concurrent stress test that reproduces the race and asserts shadow-branch consistency.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 7350c3f. Configure here.}