beads-coordinator

Beads Coordinator

Allocate bounded outcomes to persistent implementation owners and recover their delivery. This controller handles lifecycle writes for dispatched workers; implementation, diagnosis and routine corrections remain with the same owner. For a session doing its own delivery use beads-looper. For a supplied package use beads-worker.

Use for “keep N workers finishing the backlog”, “finish started outcomes first”, or “coordinate several owners on this tracker”. Backlog authoring routes to beads-writer, recovery-only to beads-cleanup.

Contract and reading order

1. Shared delivery model: units, persistent owners, branch tradeoffs, packets, claim journal, evidence and acceptance.
2. Coordinator loop: allocation, review wiring, corrections, landing, per-member reconciliation and reports. Start here after the shared model; load other references only for the step that needs them.
3. Runtime and safety: actor/lease, capacity, guarded adoption, model selection and bounded waits.
4. Epic coordination: shared prerequisites and finite programme ownership; no extra mini-coordinator tier.
5. Commands: CLI lookup and session completion.

Claim with atomic --claim, use a unique actor and never mutate another live actor's claims. Multi-bead packages use the shared helper and journal. Dispatch native runtime sessions with absolute skill paths and concise current packet locators. Require worker bootstrap proof before editing. Never commit Dolt-managed .beads/ files, run production actions without authority, or bypass a repo gate.

Executable consumers

• rank_ready_work.py ranks finite outcomes and prerequisites and review-first admission. Pass the Step 0 normalization file; queue is executable order, candidates diagnostic only. Missing review evidence dispatches nothing; parked owners keep claims without consuming execution slots.
• coordinator_registry.py is the registry writer and shared liveness reader; do not hand-write registry expiries.
• normalize_pr_review_state.py reports canonical anchor/review associations and terminal-state recommendations.
• review_relation_graph.py validates relations without I/O; partial relation/inventory evidence permits no mutation.

Target trackers using bd -C /absolute/repo on every command when outside that repo. A bead prefix does not route across databases. Search known errors for unexpected errors, append confirmed new fixes there, and apply decision autonomy when a blocker is actually an engineering choice. Use token efficiency for projected output and reuse of evidence rather than repeated full scans.