Docs / Observability / Coordination deadlock

coordination_deadlock

Two or more agents are waiting on each other to release control — Coffman's circular-wait condition expressed in agent handoffs. Mesedi's SDK semantics make three of Coffman's four classic deadlock conditions implicit (mutual exclusion, hold-and-wait, no-preemption), so the detector only needs to find the fourth: circular wait. It scans the handoff graph for cycles A→B→A (2-cycles via a fast path) and longer A→B→C→A (N≥3 cycles via Tarjan's strongly-connected-components algorithm).

What this detector catches

Two-cycle fast path: when agent_handoff events show agent A handing off to agent B and B handing off back to A within the same execution chain, the detector fires under signature coordination_deadlock:<A>:<B> (members sorted alphabetically for determinism). N≥3 cycles (Tarjan SCC): when a cycle of length 3+ exists in the handoff graph (e.g. A→B→C→A), the detector fires under coordination_deadlock:<m1>:<m2>:<m3>... (members sorted, cycle length recoverable by colon-count). When both a 2-cycle and a N≥3 cycle exist in the same topology, the 2-cycle wins to preserve alerting for existing customer dashboards. Self-loops (an agent handing off to itself) are explicitly excluded — that's not a deadlock, that's a single-agent recursion pattern caught by other detectors.

Example failures it groups

A planner agent hands off to a critique agent for review; the critique agent hands back to the planner for a revision; the planner hands back again. 2-cycle deadlock — neither agent has a termination condition that overrides the handoff.
A multi-tool agent chain A→B→C where C decides the input needs more planning and hands back to A. The 3-cycle fires under coordination_deadlock:A:B:C.
A supervisor-worker pattern where the supervisor and worker both invoke each other to verify state. 2-cycle.

What to do when it fires

Open the failure-group detail page. The Playbook walks through cycle-breaking strategies: add a hop-count cap (every handoff increments a counter; refuse to hand off when the counter exceeds a threshold), introduce a terminating verdict (one of the cycle members can decide "good enough" without requiring another hop), or restructure the handoff topology so it becomes a DAG (the most reliable fix — replace cyclic critique-and-revise with a bounded N-pass loop). For N≥3 cycles, the signature lists the members in alphabetical order; reading them in execution order may require checking the execution timeline.

When NOT to investigate

Intentional bounded critique-and-revise loops where you've already added a hop-count cap in code. The detector still sees the cycle; if the cap is firing reliably, the detector is informational rather than actionable. Use severity routing to downgrade to info-tier.
Single-agent recursive patterns (an agent handing off to itself). The detector explicitly excludes self-loops; if you see one surfacing here, that's a bug — file it.

Tunable thresholds + allowlist

No per-project tunable thresholds. The detector fires on any qualifying cycle. The allowlist primitive does not yet support this detector; use severity routing to downgrade the failure class if you have intentional bounded cycles you'd rather monitor than alert on.

Related docs

cascading_failure — the multi-agent sibling that catches linear failure chains (parent → child crash). coordination_deadlock catches cyclic stalls; cascading_failure catches linear cascades.
Multi-agent topology + handoffs — the overview doc.