jwbron · jwbron · Apr 25, 2026 · Apr 25, 2026 · Apr 25, 2026 · Apr 25, 2026
diff --git a/docs/guides/concurrent-execution.md b/docs/guides/concurrent-execution.md
@@ -96,7 +96,7 @@ Agents communicate with each other during concurrent execution via the orchestra
 
 ### How to Wait
 
-Agents wait for BRC messages with a single canonical command — `egg-orch message wait-loop` — which long-polls the bus server-side and exits only on a terminal match or a permanent error. The full contract (the one-liner for producers and reviewers, the four anti-patterns to avoid, the `egg-orch message wait` exit codes, the `HEARTBEAT` schema, and the `EGG_MESSAGE_POLL_MAX_WAIT` ↔ gateway-Squid coupling) is in [Agent Wait Patterns](../reference/agent-wait-patterns.md) — read it before writing an outer `for`-loop, a `sleep`, or a multi-call poll sequence.
+Agents wait for BRC messages with a single canonical command — `egg-orch message wait-loop` — which long-polls the bus server-side and exits only on a terminal match or a permanent error. The full contract (the one-liner for producers and reviewers, the five anti-patterns to avoid, the `egg-orch message wait` exit codes, the `HEARTBEAT` schema, and the `EGG_MESSAGE_POLL_MAX_WAIT` ↔ gateway-Squid coupling) is in [Agent Wait Patterns](../reference/agent-wait-patterns.md) — read it before writing an outer `for`-loop, a `sleep`, or a multi-call poll sequence.
 
 ```bash
 # Producer STAY ALIVE — exits on consensus, re-review, or overseer alert
@@ -341,7 +341,7 @@ Each agent tracks two state machines (producer and reviewer) independently:
 
    > **Note — `CONSENSUS_RE_REVIEW` handling:** Agents that receive a `CONSENSUS_RE_REVIEW` while staying alive **must** act on it immediately: reviewers of the re-proposing producer must re-review and ACK/NACK; all other agents must re-confirm via `egg-orch consensus confirmed`. Ignoring this message stalls the pipeline.
 
-> **Note — `pending_acks` (exit code 2):** After a re-proposal, previously-confirmed reviewers are un-confirmed and must re-ACK. If the producer calls `confirmed` before those re-ACKs arrive, the command returns exit code **2** (`pending_acks`) — this is transient, not an error. The producer should poll for messages and retry `confirmed` until it exits 0. Via `mcp__brc__confirm`, the equivalent is `ok=False` with `status="pending_acks"`; retry until `ok=True`.
+> **Note — `pending_acks` (exit code 2):** After a re-proposal, previously-confirmed reviewers are un-confirmed and must re-ACK. If the producer calls `confirmed` before those re-ACKs arrive, the command returns exit code **2** (`pending_acks`) — this is transient, not an error. The producer must wait on the prerequisite event (`CONSENSUS_ACK`/`CONSENSUS_NACK` from reviewers, `CONSENSUS_PROPOSE` from missing producers, or `CONSENSUS_RE_REVIEW`) and retry `confirmed` when that arrives. Via `mcp__brc__confirm`, the equivalent is `ok=False` with `status="pending_acks"`; retry until `ok=True`. **Do not** enter the STAY ALIVE `wait_loop --for CONSENSUS_CONFIRMED` as a recovery path — a producer whose own confirm hasn't succeeded yet deadlocks the pipeline (see [Anti-pattern 5](../reference/agent-wait-patterns.md#anti-pattern-5--producer-waits-on-consensus_confirmed-before-its-own-confirm-has-succeeded-2064)).
 >
 > **Note — Reviewer `pending_acks`:** Reviewers can also receive exit code 2 from `confirmed` when they have stale ACKs (e.g., an ACK recorded before the producer proposed) **or unresolved NACKs** (a NACK issued against a producer that has not yet re-proposed). In the stale-ACK case, the reviewer must re-ACK the listed producers at their current proposal version before confirming. In the unresolved-NACK case, the reviewer must wait for the NACKed producer to re-propose, then re-review and ACK/NACK the new version before confirming.
 

diff --git a/docs/index.md b/docs/index.md
@@ -79,7 +79,7 @@ This index helps both humans and LLMs navigate the documentation efficiently.
 | [SDLC Contract](reference/sdlc-contract.md) | Full `egg-contract` command reference for tracking tasks, commits, decisions |
 | [MCP Deployment Tools](reference/mcp-deployment-tools.md) | Six k8s-facing MCP tools: `get_deployment_context`, `validate_deployment_manifests`, `prune_stale_worktrees`, `validate_network_isolation`, `rebuild_and_rollout`, `get_service_logs` |
 | [Agent MCP Tools](reference/agent-tools.md) | In-process SDK MCP tools sandbox agents call on the `tool_use` stream (30 verbs across 6 namespaces: `mcp__sdlc__*`, `mcp__brc__*`, `mcp__phase__*`, `mcp__progress__*`, `mcp__task__*`, `mcp__checkpoint__*`); on by default — set `EGG_MCP_TOOLS=false` to opt out |
-| [Agent Wait Patterns](reference/agent-wait-patterns.md) | Canonical `egg-orch message wait-loop` idiom for BRC STAY ALIVE, the four anti-patterns to avoid, the `egg-orch message wait` exit-code contract, the `HEARTBEAT` metadata schema, the `EGG_MESSAGE_POLL_MAX_WAIT` / `EGG_ORCH_WAITRESS_THREADS` env-var couplings, and §7 host-side `wait_for_status_change` for event-driven pipeline monitoring |
+| [Agent Wait Patterns](reference/agent-wait-patterns.md) | Canonical `egg-orch message wait-loop` idiom for BRC STAY ALIVE, the five anti-patterns to avoid, the `egg-orch message wait` exit-code contract, the `HEARTBEAT` metadata schema, the `EGG_MESSAGE_POLL_MAX_WAIT` / `EGG_ORCH_WAITRESS_THREADS` env-var couplings, and §7 host-side `wait_for_status_change` for event-driven pipeline monitoring |
 | [Jira Wrapper](reference/jira-wrapper.md) | `/api/v1/jira/*` read-only gateway endpoints (ticket read, JQL search with static project-scope extraction, ticket comments, GET-only execute passthrough); private-mode only; project allowlist via `config/context-filters.yaml`; `not_found` envelope; future write-verb extension points |
 | [Conditional ACK](reference/conditional-ack.md) | Reviewer verdict variant: ACK + `--pre-merge-condition "..."` attaches a merge-time human obligation (e.g. `git mv`) that surfaces in `egg-orch consensus status` and in a "Pre-merge Obligations" section on the auto-created PR body |
 

diff --git a/docs/reference/agent-wait-patterns.md b/docs/reference/agent-wait-patterns.md
@@ -1,7 +1,7 @@
 # Agent Wait Patterns
 
 > Canonical reference for how concurrent agents wait for BRC messages — the
-> single one-liner you should copy, the four anti-patterns to avoid, the
+> single one-liner you should copy, the five anti-patterns to avoid, the
 > exit-code contract for `egg-orch message wait`, the `HEARTBEAT` metadata
 > schema, and the operator-facing env vars that couple the client-side wait
 > cap to the gateway and Waitress thread pool.

diff --git a/docs/reference/orchestrator-cli.md b/docs/reference/orchestrator-cli.md
@@ -134,7 +134,7 @@ egg-orch message wait-loop \
 egg-orch message wait --for CONSENSUS_PROPOSE --from coder --timeout 60
 ```
 
-Do not wrap `wait-loop` in an outer shell `for`-loop or `sleep` — it is already the outer loop, server-side. See [Agent Wait Patterns](agent-wait-patterns.md) for the full contract, the four anti-patterns to avoid, and the exit-code table.
+Do not wrap `wait-loop` in an outer shell `for`-loop or `sleep` — it is already the outer loop, server-side. See [Agent Wait Patterns](agent-wait-patterns.md) for the full contract, the five anti-patterns to avoid, and the exit-code table.
 
 **Emit a structured heartbeat (state transitions only):**
 ```bash

diff --git a/orchestrator/routes/pipelines.py b/orchestrator/routes/pipelines.py
@@ -8729,7 +8729,7 @@ def _build_agent_prompt(
                 "across a send→wait boundary, capture the ID of your "
                 "send and pass `--since <id>`.  See "
                 "`docs/reference/agent-wait-patterns.md` for the full "
-                "exit-code contract and the four anti-patterns to avoid.",
+                "exit-code contract and the five anti-patterns to avoid.",
                 "4. If `wait-loop` returns with a message that affects your work, "
                 "transition back to WORKING, address it, then signal READY again. "
                 "**In particular, if you receive a `CONSENSUS_RE_REVIEW` message, "