field guidemain · attested greentoolchain pins ↗shippeddirectionproposed
05 Fleet

A fleet of hives, one Head Office

One team working this way is a demo. This page is what it looks like when every repo is a hive and you read the whole fleet from one seat.

Each hive owns its issues; the workspace owns the view. bh sync aggregates every registered hive — cloned ones by local path, uncloned ones via a blobless minimal-clone cache — so bh hub bd ready answers "what's actionable anywhere?" even on a machine with no code checked out. The hub is that read-only aggregate; HQ is a different, authoritative store — fleet membership, host manifests, leases, and the escalations filed with bh escalate.

$GIT_WORKSPACE — EACH REPO IS A HIVEhivegithub/acme/api.beads/ (Dolt) + codehivegithub/acme/webprefix: acme-web-Nhivegitea/lab/protonot even cloned herebd dolt pushrepo's own git remoterefs/heads/* · code, PRsrefs/dolt/data · issue historyrepo's own git remoterefs/heads/* · code, PRsrefs/dolt/data · issue historyrepo's own git remoterefs/heads/* · code, PRsrefs/dolt/data · issue historyno central server — issue data rides the repo's own remote,in a ref namespace branches and PRs never seebh synccloned → by local pathuncloned → blobless cache + bd bootstraphub~/.beadhive/hubone aggregated beads DBread cache — hives stay authoritativebh hub bd readyactionable work, anywherebh hub intakethe fleet-wide inboxHead Office + HQ~/.beadhive/config.yaml (partitioned registry) · ~/.beadhive/hq (hosts, leases, escalations)supervisor → policy · director → fleet membershipcustodian → hive config + secrets · controller → read-only
The hub is the read side; HQ is the write side (a git repo with its own bead store, cloned to ~/.beadhive/hq). The prefix is permanent and derived from org + repo; the provider — the thing most likely to change — lives in a label, so a host migration is a label edit, not data surgery.

Keeping the fleet in sync

bh hive sync-remote pushes and pulls one hive's git and Dolt state — or every hive's — and its dry run classifies each as clean, dirty, unpushed, remote-only or blocked. Where local and remote disagree it surfaces the disagreement as datarather than picking a winner quietly — a conflict is something you read and decide, not something a sync resolves silently while you're not looking. bh sync is the fleet-wide read pass: it adds every registered hive to the hub, clone-caching the ones that aren't checked out locally; bh hq push / bh hq status do the same ahead/behind accounting for HQ.

Fielding what comes in

Work also arrives from outside the plan. bh report files a bug or request into any hive you own — including from a different hive entirely, which is how one repo tells another that something it depends on is broken. bh escalate is the lighter move: name a tool problem, hand it up, and keep working rather than stopping to route it yourself.

Both land in one queue. bh work intake is the per-hive view andbh hub intake the fleet-wide inbox (bh hq intake now shows only HQ's own escalations), and the queue is source-agnostic — a cross-hive report, an imported GitHub issue, and a legacy import all triage the same way, with duplicate detection running on entry and again at triage so a colliding request doesn't bury the queue. Four verbs dispose of anything in it:

  • bh work accept — real work: set type and priority, clear it into the backlog, where it flows through the ordinary ready/dispatch loop.
  • bh work reject — not a bug, or won't do: close it with a reason the reporter can actually read.
  • bh work reroute — filed against the wrong hive: re-file it into the right one, or bounce it up when it's genuinely ambiguous.
  • bh work promote — too big to simply accept: hand it to the planner, which adopts it into a gated molecule instead of letting it sit as an oversized ticket.
SOURCESQUEUES — intake:untriaged · origin:<channel>DISPOSITION — typed verbs, never ad-hoc labelsbh report <hive> "<title>"target is KNOWN: a hive you own — including from anotherhive, how one repo tells another it is broken · origin:reportGitHub issue importchannel derived from source_system · origin:githublegacy importorigin:import · same queue, same triagebh escalate "<what> with <tool>"target is UNKNOWN: a bh / bd / tool bug mid-work.One line, fire-and-forget, keep working —the developer never routes or investigates · origin:escalationdirectionauto-routing by report channela tool declares where its issues go:<tool> report-target --json/.well-known/report-channel.jsonMCP serverInfo._metadescriptor spec ships; nothing reads it yet.resolved → file as a report into that hive;unresolved → escalate to HQ as todayper-hive queue · bh work intakethe dispatcher fields its own hive's queuebd find-duplicates runs on entry and again at triage,so a colliding request surfaces instead of burying itbh work intake --source report|github|importbh sync aggregates every hive (read side)fleet-wide inbox · bh hub intakethe director's view across all hives — the hub is derivedand rebuildable; it holds no truth of its ownHQ's own queue · bh hq intakeescalations land as hq- beads in the authoritative store;the director is the terminal router — no auto-routing yetprints a pointer to the fleet inbox so nobody is strandeddispatcherdirectordirectorbh work accept <id> [--type T] [--priority P]real work: intake cleared → backlog → the ordinaryready / dispatch loop · intake:acceptedbh work reject <id> --reason "…"closed with a reason the reporter can read · intake:rejectedbh work reroute <id> --to <hive>mis-filed: lands in that hive's queue · intake:reroutedbh work reroute <id> --super <seat>genuinely ambiguous: stays in the fleet inbox for a second lookbh work promote <id>too big to accept as a ticket · intake:promoted — the adoptqueue key. The planner runs bh plan adopt <id> and seedsa molecule frame; the report rides the epic as its childthree facets, kept orthogonalintakethe queue state: untriaged → accepted | rejected | rerouted | promoted (closed dimension, bd set-state)originthe channel it entered through: report · github · import · escalation — a durable provenance tagsource_system+ external_ref — the native system-of-record coupling, set only at import, never overloaded by a native reportreporter identity is bd --actor, never a label. One queue for every channel means one triage, one duplicate scan,one set of verbs — a cross-hive report, an imported GitHub issue and an escalation all look the same to the seatdisposing of them; only the queue they sit in, and therefore who sees them first, differs.
report path — target knownescalation path — target unknownhand-off to planningdirection
The split is by what the filer knows. A report names its hive, so it lands in that hive's queue and the hive's own dispatcher triages it; the fleet inbox is only an aggregate read of every such queue. An escalation names nothing but the symptom — it goes to HQ's own store and waits for the director, who is the one terminal router and resolves it with the same four verbs. Nothing routes itself today. The report-channel descriptor is the piece that would let a tool say where its issues belong, so that a known target files directly and only the genuinely unknown case climbs to HQ; the descriptor is specified and validated, and the consumer that would read it is deliberately a later bead.
Hosts

Who runs a hive

A fleet is read from one seat; it is run by hosts. A host takes a hive's lease through HQ — one primary host per hive, everything else read-only — and its dispatcher loops start kicked-off epics in ready order. The host roles, the lease rules, the two loop scopes, the runtime tiers, and the proposed Frame contract for provisioning and failover are all on the Frames page, each with its shipped / proposed status.

Go deeper

Where the source of truth lives

DocCovers
docs/AGF.mdThe tenets, naming, container branches, dispatch depth, role modes — the process overview.
docs/DESIGN.mdHives, prefixes, labels, identity-over-time, git-native hosting — the why.
docs/WORK.mdEvery bh work verb, refine plans, validation modes, conflict ladder, batches, PR-governed landing.
docs/PLANNING-PLANE.mdThe two gates, fidelity tiers, spike loop, replan vs groom.
docs/CONTROL-PLANE.mdThe four control seats, Head Office partitions, the commissioning loop.
docs/ASSURANCE.mdThe warden, the security:* gate, the verifier lens.
docs/HUB.md · docs/HQ.md · docs/HIVES.mdThe cross-hive aggregate, HQ as the authoritative fleet store, onboarding, hive kinds and identity.
docs/ATTEST-KEYS.md · docs/DOLT.mdGraph-derived attest keys and evidence reuse; the shared Dolt server and the optional central one.