docs: document EGG_EVENT_LOOP_OWNER flag (#3064 slice-1) [doc-updater]

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

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). |