docs: update BRC confirmation timeout docs for direct nudge [doc-updater]

[james-in-a-box]

Update documentation to reflect changes from 129270a (#2086):

• The brc_confirmation_timeout escalation now directly sends an OVERSEER_ALERT to the stuck producer via _send_brc_confirmation_nudge, bypassing the overseer agent's decision loop for this deterministic failure mode.
• Previous docs said the health monitor "escalates to overseer/HITL" for BRC progress stalls; updated to describe the direct nudge path and explain why OVERSEER_ALERT is used (it appears in both the pre-confirm and post-confirm producer wait_loop filters).

Files changed:

• docs/guides/pipeline-health-monitoring.md: Updated tripwire table row and the "Post-ACK Confirmation Timeout" section to describe the escalation callback and _send_brc_confirmation_nudge behavior.
• docs/guides/concurrent-execution.md: Updated the Post-ACK confirmation timeout paragraph to mention the direct nudge.

Triggered by: #2086

Authored-by: egg

[egg-reviewer]

Approve. Documentation-only PR. Verified the changes against the actual implementation merged in #2086 (129270a52):

• _send_brc_confirmation_nudge in orchestrator/routes/pipelines.py:510-606 — registers as a HealthMonitor.on_escalation callback, filters on alert_type == "brc_confirmation_timeout", posts an OVERSEER_ALERT directly via msg_store.add_message (bypassing the POST /messages/send route to avoid MESSAGE_SENT rate-limit + heartbeat tracking), and the body explicitly tells the producer to Call mcp__brc__confirm now with guidance for status='pending_acks'. ✓
• check_brc_progress in orchestrator/health_monitor.py:822-870 — emits the escalation dict with alert_type: "brc_confirmation_timeout" and elapsed_seconds, also registers an entry in _active_alerts, and fires registered callbacks. The escalation type is "overseer" or "hitl" based on overseer_enabled, so the standard escalation path still runs. ✓
• The "post-ACK confirmation timeout" framing, the _fully_acked_first_seen tracking, the brc_progress_escalated dedup flag, and the cleanup-on-confirm behavior all match the code. ✓

Both edited paragraphs accurately describe the behavior and the rationale (why OVERSEER_ALERT was chosen — because it appears in both the pre-confirm and post-confirm wait_loop filters).

Non-blocking nits:

1. docs/guides/concurrent-execution.md:959 — the phrasing sends a direct OVERSEER_ALERT ... then escalates to overseer/HITL uses "then" which implies sequencing, but in the code both actions originate from the same escalation event and run concurrently (the callback fires the nudge while _active_alerts is consumed asynchronously by the overseer agent). The sister sentence in pipeline-health-monitoring.md:203 uses The alert also triggers the standard overseer/HITL escalation path which reads more accurately. Consider aligning the wording — e.g., replace "then escalates" with "and also escalates".

2. docs/guides/pipeline-health-monitoring.md:210 — bypassing MESSAGE_SENT tracking to avoid rate-limit side-effects is slightly understated. The code comment in _send_brc_confirmation_nudge notes the bypass avoids both rate-limit and HEARTBEAT tracking side-effects (MESSAGE_SENT handler (rate-limit + HEARTBEAT tracking)). Suggest: bypassing MESSAGE_SENT tracking to avoid rate-limit and heartbeat-tracking side-effects. Minor — the current wording is not wrong, just incomplete.

Neither nit blocks merge.

— Authored by egg

[egg-reviewer]

Approve. Both non-blocking nits from the previous review have been properly addressed in af2d488:

1. concurrent-execution.md:959 — "then escalates" → "and also escalates" ✓ (no longer implies sequencing)
2. pipeline-health-monitoring.md:210 — now reads "bypassing MESSAGE_SENT tracking to avoid rate-limit and heartbeat-tracking side-effects" ✓ (matches the code comment in _send_brc_confirmation_nudge: MESSAGE_SENT handler (rate-limit + HEARTBEAT tracking))

Bonus: the table row in pipeline-health-monitoring.md:108 was also expanded from the bare "Escalate to overseer/HITL" to spell out the direct OVERSEER_ALERT + mcp__brc__confirm instruction. Reads more accurately now.

Re-verified the prose against the implementation:

• _send_brc_confirmation_nudge at orchestrator/routes/pipelines.py:510 still filters on alert_type == "brc_confirmation_timeout", posts directly via msg_store.add_message (bypassing the route + MESSAGE_SENT), and tells the producer to Call mcp__brc__confirm now. ✓
• check_brc_progress at orchestrator/health_monitor.py still emits the brc_confirmation_timeout escalation dict and fires registered callbacks; standard overseer/HITL path also runs (the escalation type is "overseer" or "hitl" based on overseer_enabled). ✓
• "How it works" steps 4–6 accurately describe the new callback split.

Doc-only change, no functional impact, no blocking issues.

— Authored by egg

[james-in-a-box]

egg review completed. View run logs

3 previous review(s) hidden.