Swarm Runtime Atlas
The complete architecture of the autonomous coding swarm on one page — master map, loops over loops, run lifecycle, Turn-Stop handshake, git flow, admission funnel, leg lifecycle, context anatomy, harness loop, delegation, toolbox, robustness matrix, invariants.
The complete architecture of the autonomous coding swarm, as shipped 2026-08 — every component, three kinds of traffic (solid = dispatch, dashed = feedback, dotted = observe/notify), reviewed adversarially against the source code. Companion to “Lessons of an Autonomous Swarm”.
Master map
One door in · one queue · one pod per run · one durable store · GitHub re-read on every wake.
Loops over loops
Each loop runs inside the next and escalates outward when it can't finish; every ring has a hard bound, so no loop is infinite.
Planes
Control — Gateway · Receiver · Reaper
- clarity gate (LLM, fail-open)
- allowlist · dedup · breaker
- HMAC fail-closed webhooks
- actor = user.type (bot ≠ human)
- orphans · caps · park TTL
Spine — Redis · Postgres
- PEL + heartbeat = exactly-once
- poison-pill delivery cap
- blob = conversation · bundle = edits
- branch = committed code
- durable streaks · budgets
Data — KEDA · Pod
- scales on gateway lag metric
- warm probe / cold clone+blob
- goal judge · guard floor
- fold sidecar → one trace
- litellm → tiered providers
Run lifecycle
Teal-edged states are resumable — no run with a live PR is unreachable.
- QUEUED — token published · no pod yet
- RUNNING — a pod is driving the agent
- AWAITING_CI — PR open, pod idle — wakes re-drive it
- NEEDS_INPUT — parked on a question · answer or TTL proceed-without
- HALTED — machine stopped (cap / dead end) but an OPEN PR exists · human-only revival
- CONCLUDED — agent chose to stop, reason recorded · resumable
- COMPLETED — PR merged · done
- FAILED — nothing to keep reachable — no OPEN PR (or ledger unreadable, fail-closed) · terminal
- CANCELLED — operator stop · terminal
- CANCELLING — cancel requested, pod still winding down · transitional
- CLOSED — PR closed without merge · terminal
- PARTIAL — multi-repo: some PRs merged, some not · terminal
Turn-Stop handshake
Ack-after-durable: every crash is a resume, never a loss or double-apply.
Git flow — three lanes, one working tree
Lanes 1–2 mint ordinary commits from the real index; lane 3 fingerprints the tree each Turn-Stop and bundles only the uncommitted delta. Shadow objects are reused by the eventual real commit; the shadow ref never reaches origin.
Admission funnel — every input, one spec
Inputs differ only in how the spec gets filled — verbatim, derived, or fetched-and-organized. After the spec, one identical path: gate → write-ahead → token. A new ingress costs a resolver, never a pipeline.
A leg, end to end — signal → prepare → loop → tail
Three entries, one loop, one tail. goals.md is rewritten from the durable spec on every lane; the tail runs whether the agent pushed or not — the backstop and checkpoint make delivery and durability independent of agent discipline.
Context anatomy — what the agent actually sees
Bottom-up: the fixed floor (contract + tool schemas), the growing conversation, and the per-leg/per-turn dynamic layers. Teal callouts are the budget-aware controls — the floor is gated down, the preamble tells the agent its own spend, feedback is capped, and the compact valve is pinned to the real window, not the model's belief.
Inside the agent turn — the harness loop
Hooks are the harness: persona forced at prompt, deterministic guards before every tool, goal judge before every stop. Turn loops until the judge allows.
goal judge · inputs — file, not context
- goals.md read from run cwd (marker-written)
- state = git log --oneline + diff --stat vs base
- never the transcript — agent can't argue with it
- file absent → nothing to enforce → allow
goal judge · call — small model, forced schema
- small-fast model tier (haiku-class)
- forced tool report_verdict → {met, unmet[]}
- thinking off · max_tokens 256 · SDK retry ×2
- skipped while no deliverable + budget left
goal judge · verdict — block, allow, or surface
- unmet or no PR/commit → block + reason injected
- cap: MAX_BLOCKS (3) → allow + surface gap
- judge down → indeterminate, fail-open (never met=true)
- park always wins · one-time verify nudge on clean delivery
Delegation — skill vs subagent
Skill = same context, knowledge flows in. Subagent = fresh context on its own model tier, one report flows back. Guards apply to both; the goal judge only to the parent.
Toolbox — by agent type
agent_type: implementer — ships a PR
skills
- deliver · cycle · ground-spec
- commit-push-pr · consolidate
- + the cloned repo's own .claude/skills
subagents
- code-reviewer · test-runner /verify
- cycle: architecture-review · quality-bars · live-e2e · docs-updater · grill-repo · grill-industry
- general-purpose (owned definition)
mcp
- codegraph (7 tools pinned) · context7 docs
- chrome-devtools — browser-gated
- vision — key-gated (the proxied model lane is image-blind)
- runtime verbs: park · conclude · file issue
agent_type: investigator — ships an RCA — read-only
skills
- investigate — hypothesis tree · RCA schema
- skeptical observed-vs-read Stop gate
subagents
- investigation-hypothesis-tester
- general-purpose (read work only)
mcp
- keeps codegraph · context7 · vision
- drops chrome-devtools
- + env-gated reads: Slack · Logfire · Datadog · Linear · gateway
- read-only PreToolUse containment · external servers stay under the mutation-verb guard
Robustness — who recovers what
pod crash mid-turn — queue, not exception handlers
- OOM/SIGKILL runs zero code — by design
- heartbeat stops → PEL idle > reclaim window
- KEDA orphaned-pending → replacement pod
- XAUTOCLAIM → cold resume: branch + blob + bundle
- lost turn re-runs · poison-pill cap bounds retries
reaper sweeps — 3 orphan classes + parks
- RUNNING + no pod + no PEL → reap + finalize
- idle-deadline expiry → ack, run stays AWAITING_CI
- NEEDS_INPUT past TTL → proceed-without re-drive
- zero-check stuck PR → update-branch nudge
- dead consumers → drain-then-delete (never drop)
status reconcile — pod-independent truth
- receiver: PR merged/closed webhook → terminal status
- operator cancel intent never clobbered
- stuck CANCELLING (no pod) → direct CAS to CANCELLED
- PR title/draft repaired on adoption
- CI-poll fallback when GitHub emits no event
wake loss — notification + fetch
- wakes carry reasons only — GitHub re-read on re-drive
- lost webhook costs latency, never correctness
- cold re-dispatch: status + inflight + CAS triple gate
- duplicate-pod gate reads queue's own undelivered set
infra blips — transient ≠ terminal
- Redis: backoff retry + idle-socket health check
- mid-scan fault → retry next tick, never false-empty
- token-mint blip → bounded backoff, stale file kept
- bare gh 404 stays transient (private repo ≠ gone)
provider outage — breakers + retry
- silent-noop turn detected (0 tokens + "success")
- in-leg bounded retry, same SDK session
- per-run breaker · fleet-wide dispatch pause
- no-op push skipped — human branch tip never clobbered
runaway bounds — durable, crash-proof caps
- delivery cap · redispatch streak · lifetime leg cap
- counters live in Postgres — a crash refunds nothing
- convergence guard on identical CI failures
- breach → HALTED (resumable), never a silent loop
last resort — humans stay in reach
- HALTED/CONCLUDED revive: PR comment (one-shot) · resume verb
- park questions answered via Slack thread
- fleet-down alert reads the control plane, not workers
- every swallow has a gauge — silence is alertable
Invariants
- ack-after-durable — commit first, ACK second
- exactly-once — PEL + heartbeat + poison-pill cap
- notification + fetch — wakes carry reasons, GitHub carries truth
- guard floor — deterministic hooks under any classifier
- bot identity — self-feedback impossible by type
- single writer — GitOps owns state · secrets · image tag
- never stuck — park → TTL → HALTED → human revival
- fail by blast radius — auth closed · scoring open · guards warn