From 424f46f7b091c1f426a434a29f800ad7daf2ce8c Mon Sep 17 00:00:00 2001 From: James Wiesebron Date: Wed, 29 Apr 2026 13:32:58 -0700 Subject: [PATCH 1/2] =?UTF-8?q?Fix=20#2275:=20docs=20follow-up=20=E2=80=94?= =?UTF-8?q?=20consensus-timeout=20HITL=20=E2=86=92=20OVERSEER=5FALERT?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Docs leftovers from #2269 (which replaced the consensus-timeout HITL choice with an OVERSEER_ALERT but didn't reach every reference). - concurrent-execution.md: brc_consensus_progress_gate_seconds row references OVERSEER_ALERT; Timeout Handling lead sentence updated to match (it contradicted the bullets that already described the alert flow). - sdlc-pipeline.md: consensus_timeout_minutes / brc_consensus_progress_gate_seconds rows reference OVERSEER_ALERT; BRC consensus-protocol step 5 rewritten as a non-blocking alert (post-timeout polling continues; cancel_task / restart_phase / provide_input replace the removed three-option HITL). --- docs/guides/concurrent-execution.md | 4 ++-- docs/guides/sdlc-pipeline.md | 10 +++++----- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/guides/concurrent-execution.md b/docs/guides/concurrent-execution.md index fe92ed0d52..647a2f5be0 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 `OVERSEER_ALERT`. 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 diff --git a/docs/guides/sdlc-pipeline.md b/docs/guides/sdlc-pipeline.md index 99b7eee966..a6ecde337e 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 a consensus-timeout `OVERSEER_ALERT` | +| `brc_consensus_progress_gate_seconds` | int | `300` | Defer the 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,9 @@ 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 a non-blocking `OVERSEER_ALERT` (subject `consensus-timeout: []`) rather than gating on a HITL decision — see [issue #2264](https://github.com/jwbron/egg/issues/2264) + - The `/sdlc` skill surfaces the alert (Check agent logs / Acknowledge / Cancel pipeline) + - The orchestrator continues polling for consensus under the post-timeout budget; operators can intervene with `cancel_task`, `restart_phase`, or `provide_input` 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). From 5e33e190811a46e6b300c753de7e162430ec91ef Mon Sep 17 00:00:00 2001 From: "egg-reviewer[bot]" <261018737+egg-reviewer[bot]@users.noreply.github.com> Date: Wed, 29 Apr 2026 21:32:22 +0000 Subject: [PATCH 2/2] Update concurrent-execution.md HITL/consensus-timeout rows to OVERSEER_ALERT Address PR #2277 review feedback: two stale rows in concurrent-execution.md contradicted the OVERSEER_ALERT flow established by #2269. - L36 (PipelineConfig table): consensus_timeout_minutes description now matches the parallel sdlc-pipeline.md row. - L856 (HITL Escalation Paths table): critical-blocker consensus timeout no longer lists the removed three-option HITL choice; matches the shape of the advisory-only row directly below it. --- docs/guides/concurrent-execution.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/concurrent-execution.md b/docs/guides/concurrent-execution.md index 647a2f5be0..e6704f84e9 100644 --- a/docs/guides/concurrent-execution.md +++ b/docs/guides/concurrent-execution.md @@ -33,7 +33,7 @@ Relevant `PipelineConfig` fields: | `start_phase` | `null` | Skip earlier phases and begin execution from `"plan"` or `"implement"` | | `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 | +| `consensus_timeout_minutes` | `30` | Timeout before publishing a consensus-timeout `OVERSEER_ALERT` | | `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`. | @@ -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 — `OVERSEER_ALERT` `priority=high`; orchestrator continues post-timeout polling)* | | 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 |