diff --git a/docs/development/STRUCTURE.md b/docs/development/STRUCTURE.md index 23ab9e520d..ec4b1a3785 100644 --- a/docs/development/STRUCTURE.md +++ b/docs/development/STRUCTURE.md @@ -112,7 +112,7 @@ orchestrator/ ├── action_guards.py # Formal BRC state machine action guards (preconditions for propose/ack/nack/confirm/withdraw) ├── approval_matrix.py # Per-reviewer ACK/NACK matrix for BRC consensus ├── attestation_schemas.py # Attestation payload validation for BRC proposals -├── consensus_wrapper.py # Shell wrapper template: deterministic event-pump loop (sole path since slice-4; legacy capped-restart template and EGG_BRC_EVENT_PUMP flag deleted) +├── consensus_wrapper.py # Shell wrapper template: deterministic event-pump loop (sole path since slice-4; legacy capped-restart template and EGG_BRC_EVENT_PUMP flag deleted); contains dormant one-shot arm (#3064 slice-1) spliced in when EGG_EVENT_LOOP_OWNER=orchestrator ├── dag_visualizer.py # ASCII DAG visualization for pipeline status ├── decision_queue.py # HITL decision queue ├── events.py # Event bus for pipeline events diff --git a/docs/reference/orchestrator-cli.md b/docs/reference/orchestrator-cli.md index 85d2ee4349..bc45daa4c4 100644 --- a/docs/reference/orchestrator-cli.md +++ b/docs/reference/orchestrator-cli.md @@ -79,6 +79,7 @@ Agent role can be omitted when `EGG_AGENT_ROLE` is set. | `GATEWAY_URL` | Gateway URL (default: `http://egg-gateway:9848`) | | `EGG_CONCURRENT_MODE` | `true` when running in concurrent execution mode | | `EGG_BRC_MEMORY` | BRC memory writer mode for reviewers. `full` (default since slice-4) — handlers write and the event-pump reads the file on re-entry; `write-only` — handlers populate the per-role memory file but the reader stays inert; `off` — writes are no-ops (one-release rollback escape hatch). See [BRC Memory Artifact](../architecture/brc-memory.md). | +| `EGG_EVENT_LOOP_OWNER` | BRC event-loop ownership mode (#3064). `pod` (default) — today's behavior: each agent container runs the in-pod event-pump wait-loop in `consensus_wrapper.py`. `orchestrator` — the orchestrator owns the loop and spawns a one-shot pod per actionable BRC event (slice-2+). Values are matched case-insensitively (e.g. `Orchestrator`, `POD` are accepted). Unset/empty defaults to `pod`; any unrecognised value raises `ValueError` at read time (no silent fallback — see the #3023 post-mortem). The one-shot arm in the wrapper is dormant until `orchestrator` mode is selected AND the slice-2 spawner exists. | | `EGG_MESSAGE_POLL_INTERVAL` | Suggested message polling interval in seconds (default: 30) | | `EGG_MESSAGE_POLL_MAX_WAIT` | Server-side cap (seconds) on `message wait --timeout`. Default `60`, minimum `1`. Values `> 90` trigger a startup `warnings.warn` + WARNING log because the gateway's baked-in Squid `read_timeout` / `request_timeout` directives cap backend long-polls at ~60s — raising the cap above that requires a gateway image rebuild, not a ConfigMap edit. See [Agent Wait Patterns §6](agent-wait-patterns.md#6-egg_message_poll_max_wait--long-poll-cap-coupling). | | `EGG_SLICE_ID` | Set by `kubernetes_spawner` for every slice-scoped agent. When set, `message wait` / `message wait-loop` only match messages whose `metadata.slice_id` equals this value OR is null (pipeline-level passthrough — OVERSEER_ALERT and global phase signals continue to wake every waiter). Override with `--slice`. See [Agent Wait Patterns — Auto-scoping](agent-wait-patterns.md#auto-scoping-by-slice-and-producer-allowlist-2725). |