diff --git a/docs/guides/concurrent-execution.md b/docs/guides/concurrent-execution.md index fe92ed0d52..b776866011 100644 --- a/docs/guides/concurrent-execution.md +++ b/docs/guides/concurrent-execution.md @@ -34,7 +34,7 @@ Relevant `PipelineConfig` fields: | `max_concurrent_agents` | `6` | Maximum agents per phase | | `message_poll_hint_seconds` | `30` | Suggested polling interval for agents | | `consensus_timeout_minutes` | `30` | Consensus timeout before escalation or auto-advance | -| `brc_consensus_progress_gate_seconds` | `300` | Defer the consensus-timeout HITL decision while BRC bus activity (proposals, ACKs/NACKs) or container heartbeats have fired within this window. Set to `0` to disable. | +| `brc_consensus_progress_gate_seconds` | `300` | Defer the consensus-timeout OVERSEER_ALERT while BRC bus activity (proposals, ACKs/NACKs) or container heartbeats have fired within this window. Set to `0` to disable. | | `post_consensus_iteration_budget_seconds` | `3600` | Per-iteration wait budget in the post-timeout poll loop. Resets each time a producer issues a new `CONSENSUS_PROPOSE` (initial or NACK→re-propose), giving each iteration a clean clock. | | `post_consensus_max_total_seconds` | `14400` | Hard ceiling on the total post-timeout wait, regardless of how often the per-iteration budget rebaselines. Must be ≥ `post_consensus_iteration_budget_seconds`. | | `agent_idle_timeout_minutes` | `60` | Idle agent timeout before termination | @@ -722,7 +722,7 @@ If any agent is in the `OBJECTING` readiness state (separate from BRC phase), th ### Timeout Handling -If consensus is not reached within `consensus_timeout_minutes`, the orchestrator first checks the **BRC progress gate** before opening a HITL decision. While any of the following have fired within `brc_consensus_progress_gate_seconds` (default 300 s), the orchestrator continues polling rather than escalating immediately: +If consensus is not reached within `consensus_timeout_minutes`, the orchestrator first checks the **BRC progress gate** before publishing the consensus-timeout `OVERSEER_ALERT` ([issue #2264](https://github.com/jwbron/egg/issues/2264)). While any of the following have fired within `brc_consensus_progress_gate_seconds` (default 300 s), the orchestrator continues polling rather than escalating immediately: - A `CONSENSUS_PROPOSE` or ACK/NACK on the BRC bus - A container heartbeat from any active role in the current phase @@ -853,7 +853,7 @@ Both are also available as MCP tools (`restart_agent`, `restart_phase`) and CLI | Agent stall (restarts exhausted) | Restart agent, Abort phase, Continue without | | Multiple agent stalls (2+ restarts exhausted) | Restart phase, Cancel pipeline | | Multiple failures (2+ / 60s) | Retry phase, Cancel pipeline | -| Consensus timeout (critical blockers) | Continue waiting, Accept current state, Abort phase | +| Consensus timeout (critical blockers) | *(no HITL — publishes high-priority `OVERSEER_ALERT`, see Timeout Handling)* | | Consensus timeout (advisory only) | *(no HITL — proceeds automatically)* | | Consensus timeout fires, consensus reached during wait | *(no HITL — recovered automatically via timeout recheck)* | | Agent objection | Resolve then advance, Override, Abort | diff --git a/docs/guides/sdlc-pipeline.md b/docs/guides/sdlc-pipeline.md index 99b7eee966..9e6c4ff8c9 100644 --- a/docs/guides/sdlc-pipeline.md +++ b/docs/guides/sdlc-pipeline.md @@ -1249,8 +1249,8 @@ Or pass it in the pipeline config JSON (e.g. via the API): | `start_phase` | str | `null` | Skip earlier phases and start execution from `"plan"` or `"implement"`. When set to `"implement"`, pass top-level `analysis`/`plan` fields to seed the contract (see Short-flow pipelines above). | | `max_concurrent_agents` | int | `6` | Maximum agents running simultaneously | | `message_poll_hint_seconds` | int | `30` | Suggested polling interval for agents | -| `consensus_timeout_minutes` | int | `30` | Timeout before HITL escalation | -| `brc_consensus_progress_gate_seconds` | int | `300` | Defer consensus-timeout HITL while BRC bus or container heartbeats are active. Set to `0` to disable. | +| `consensus_timeout_minutes` | int | `30` | Timeout before publishing an OVERSEER_ALERT (#2264) | +| `brc_consensus_progress_gate_seconds` | int | `300` | Defer consensus-timeout OVERSEER_ALERT while BRC bus or container heartbeats are active. Set to `0` to disable. | | `post_consensus_iteration_budget_seconds` | int | `3600` | Per-iteration wait budget after consensus timeout. Resets on each new `CONSENSUS_PROPOSE` from a producer. | | `post_consensus_max_total_seconds` | int | `14400` | Hard ceiling on total post-timeout wait. Must be ≥ `post_consensus_iteration_budget_seconds`. | | `agent_idle_timeout_minutes` | int | `60` | Agent idle timeout | @@ -1318,9 +1318,7 @@ Phase completion in concurrent mode uses a consensus-based approach: - The orchestrator polls every 5 seconds and stops containers immediately on consensus 4. Any agent can object (signal `OBJECTING`) to block completion - A HITL decision is created with options: **Override objections**, **Wait for resolution**, **Abort phase** -5. Timeout (`consensus_timeout_minutes`, default 30) triggers HITL escalation - - Options: **Continue waiting**, **Accept current state**, **Abort phase** - - Phase falls back to exit-code-based completion while awaiting the decision +5. Timeout (`consensus_timeout_minutes`, default 30) publishes an `OVERSEER_ALERT` (non-blocking; subject `consensus-timeout: []`) — the pipeline continues polling; intervene with `cancel_task` or `restart_phase` if needed (#2264) 6. If a container exits cleanly without signaling `READY`, the consensus wrapper restarts it with a recovery prompt (up to `MAX_CONSENSUS_RESTARTS`, default 2). After exhausting restarts, the wrapper performs a final consensus check — if consensus has already been reached (`is_complete=True`), it exits with code 0 (success). Only if consensus is genuinely incomplete does it exit with code 1, triggering the single-agent failure path (HITL decision: retry, abort, or continue without). See [Concurrent Execution: Consensus Wrapper](concurrent-execution.md#consensus-wrapper). 7. **Consensus gates phase advancement unconditionally.** When all containers have exited — whether with failures or cleanly — the orchestrator performs a final consensus recheck before returning success. If BRC consensus is incomplete, the phase fails (exit code 1) regardless of individual container exit codes. This prevents a PR from being opened when agents exit code 0 without completing the full BRC lifecycle. See [Concurrent Execution: All-Container-Exit Consensus Recovery](concurrent-execution.md#all-container-exit-consensus-recovery).