ADR-010: Shared Beads Branch with Optimistic Concurrency

Status

Accepted

Context

Swarm agents need to coordinate task assignment through beads. Each agent runs in its own git worktree on its own branch. The beads database (.beads/) must be accessible to all agents for claiming, closing, and querying tasks.

The question: how do agents share beads state when they're on different branches?

Decision

Use a shared beads branch (swarm/<session-id>/beads) that all agent worktrees can access. Beads operations use optimistic concurrency: agents read from the branch, make changes, and push. If a push fails (another agent pushed first), the agent rebases and retries.

Mechanism

1. At session start, create_beads_branch() creates swarm/<session>/beads from HEAD.
2. Each agent's prompt includes beads state read from this shared branch.
3. When an agent runs bd claim or bd close, beads writes to the local .beads/ directory and commits to the shared beads branch.
4. If two agents try to update beads simultaneously, one push will fail. The beads CLI handles the retry (pull-rebase-push).

Why not per-agent beads?

Per-agent beads would require a merge step and could lead to conflicting claims (two agents claiming the same bead). A shared branch with optimistic concurrency prevents double-claims at the git level.

Alternatives Considered

1. Beads in SQLite (alongside messages)

• Pro: No git contention, fast.
• Con: Beads is an external tool with its own storage. Duplicating its state in SQLite would require constant syncing. Beads' git-native design is a feature, not a limitation.

2. Per-agent beads with supervisor merge

• Pro: No contention between agents.
• Con: Double-claims are possible (two agents claim same bead before supervisor merges). Adds complexity to supervisor and delays visibility.

3. File-locking beads

• Pro: Simple mutual exclusion.
• Con: Worktrees are on different filesystem paths. File locks don't work across worktrees easily. Also fragile under crash scenarios.

Consequences

• Agents may occasionally see a brief retry delay when beads pushes conflict.
• The shared branch is created/deleted per session (no permanent branch pollution).
• The beads CLI must be pre-installed and support the shared branch workflow.
• The prompt builder reads beads state from the shared branch (Stage 4 of prompt pipeline).

Tradeoffs