docs: Document BRC pending_acks exit code 2 [doc-updater]

[james-in-a-box]

Update concurrent-execution.md to reflect the new egg-orch consensus confirmed exit code 2 behavior introduced in #1179.

When a producer calls egg-orch consensus confirmed before all reviewer re-ACKs have arrived (e.g., immediately after a re-proposal), the command now returns exit code 2 (pending_acks) instead of raising an error. Agents need to know this is a transient state — they should poll for messages and retry confirmed until it exits 0.

Changes:

• BRC Protocol Flow step 3 (Converge): added explanation of exit code 2 and retry behavior
• Command example for egg-orch consensus confirmed: added inline comment documenting exit codes 0 and 2

Triggered by: #1179

Issue: none

Test plan:

• Verify the command examples read correctly in context of the surrounding workflow steps

Authored-by: egg

[egg-reviewer]

Accurate documentation of the pending_acks exit code 2 behavior. Verified against the implementation in sandbox/egg_lib/orch_cli.py:1250-1262 — the three exit paths (0=confirmed, 1=error, 2=pending_acks) match what's documented.

No blocking issues. Two non-blocking suggestions:

1. Inline comment could include exit code 1 for completeness (concurrent-execution.md:219)

The comment documents exit 0 and exit 2 but omits exit 1 (error). Agents encountering an unexpected exit 1 won't find it here. Suggest:

# Exit 0 = confirmed. Exit 1 = error. Exit 2 = waiting for reviewer re-ACKs (retry after polling).

2. Step 3 (Converge) now contains retry guidance for a scenario that occurs after step 4 (Re-propose) (concurrent-execution.md:200)

The pending_acks case only applies after a re-proposal when previously-confirmed reviewers have been un-confirmed and haven't re-ACKed yet. Documenting it in the Converge step (before Re-propose is introduced) makes the reader encounter the concept before they have the context to understand it. This isn't incorrect — the confirmed command is the convergence mechanism — but a reader hitting this for the first time may find the ordering confusing. Moving the note to step 4 or adding it as a separate callout after the steps would read more naturally, but this is minor.

Other docs (CLAUDE.md, docs/reference/integrator-agent.md) mention consensus confirmed but in workflow-step contexts that already say "confirm after all reviewers ACK." Since those instructions guide agents to call confirmed only after receiving ACKs, agents following them correctly shouldn't encounter exit code 2. The detailed behavior is appropriately placed in this guide. No updates needed elsewhere.

— Authored by egg

[egg-reviewer]

Both suggestions from the previous review have been addressed:

1. Exit code 1 added to inline comment — The comment now documents all three exit paths (Exit 0 = confirmed. Exit 1 = error. Exit 2 = waiting for reviewer re-ACKs), matching the implementation at sandbox/egg_lib/orch_cli.py:1250-1262.

2. pending_acks detail moved after step 4 (Re-propose) — The callout is now positioned after the Re-propose step where re-proposal context exists, rather than in the Converge step where the reader lacks that context. The blockquote format is a clear visual break that makes the note easy to find without disrupting the numbered flow.

Verified the documentation against the implementation — exit codes 0, 1, and 2 all match. No issues.

— Authored by egg

[james-in-a-box]

egg review completed. View run logs

3 previous review(s) hidden.