Inject EGG_REAL_BACKEND_WINDOW into agent event pods (#3316)

[jwbron]

Summary

Fixes #3316. The #3249 context-discipline measurement's window_utilization (peak-utilization-under-resume) and real_backend_window (working-set-vs-window, the #3200 §6 recursion-escalation signal) were permanently null on every production event because no producer wired the EGG_REAL_BACKEND_WINDOW cross-boundary env into agent event pods.

shared/egg_agent/measurement.py resolves the real backend window from $EGG_REAL_BACKEND_WINDOW first, then falls back to importing orchestrator.agent_model_resolution.real_backend_window. But orchestrator is off the pod's PYTHONPATH, so the fallback always fails in-pod — leaving both window-relative metrics null (confirmed live on issue-3288: all 24 captured events null for both).

Fix

The symmetric counterpart to the #3279 EGG_RESEED_THRESHOLD injection:

• _build_event_spawn_params now also resolves real_backend_window(decision.claude_code_alias) from the same model decision it already computes, returning it in the tuple (4 → 5 elements).
• spawn_event exports env["EGG_REAL_BACKEND_WINDOW"] = str(real_window) alongside the existing EGG_RESEED_THRESHOLD export.

The real window is returned separately rather than recovered from the reseed threshold, because the threshold is min(FLOOR, MARGIN * real_window) and so is not invertible once the floor binds.

Tests

New TestEventSpawnRealBackendWindow mirrors the three reseed cases:

• default Claude (opus) → 1000000
• sub-1M LiteLLM (kimi-k2.7-code) → 262144 (not the [1m]-implied 1M)
• unregistered LiteLLM (qwen3-coder-30b) → conservative 200000

Plus the existing _build_event_spawn_params test now asserts the 5th tuple element. Stale "no producer wires it yet" docstrings in measurement.py updated.

Notes

• Inert on a default pod — only the Measure + monitor + tune the BRC context-discipline knobs (route-aware reseed cap/threshold) — consumes #3200 measurement surfaces #3249 measurement (and any flag-gated consumer) reads the var.
• Relates to BRC context discipline: protected directive root + queryable environment, bounded by a deterministic threshold reseed #3200 (measurement substrate) and Compute + inject EGG_RESEED_THRESHOLD per event spawn (feed the #3200 threshold-reseed gate) #3279 (the parallel EGG_RESEED_THRESHOLD injection).

🤖 Generated with Claude Code

[james-in-a-box]

Autofix tracking

{"Test/Unit Tests": 1}

[egg-reviewer]

Review: Inject EGG_REAL_BACKEND_WINDOW into agent event pods (#3316)

Verdict: Approve. This is a clean, correctly-scoped fix for a genuine cross-module silent no-op. I traced the full producer→consumer data flow and verified every resolved value against the registry. No blocking issues. One non-blocking note on scope.

What I verified

The bug is real and the fix addresses it end-to-end. This is the canonical cross-module dead-end the review rules call out, fixed: measurement.py:_resolve_real_window reads $EGG_REAL_BACKEND_WINDOW first (line 229) and only then falls back to importing orchestrator.agent_model_resolution, which always fails in-pod because orchestrator is off the sandbox PYTHONPATH. With no producer exporting the env, both real_backend_window and window_utilization were permanently null (consistent with the live evidence cited from issue-3288). The PR wires the producer side in spawn_event, closing the gap. Consumer constant REAL_BACKEND_WINDOW_ENV = "EGG_REAL_BACKEND_WINDOW" (measurement.py:101) matches the exported key exactly.

Resolution chain is correct for all three branches (traced classify_model → claude_code_alias → real_backend_window):

• Default opus → claude_code_alias="opus" → _is_claude_alias → 1_000_000 ✓
• kimi-k2.7-code → in _SUB_1M_CONTEXT_MODELS, so claude_code_alias stays bare → registry lookup → 262_144 (not the [1m]-implied 1M) ✓
• qwen3-coder-30b → unregistered, claude_code_alias="qwen3-coder-30b[1m]" → real_backend_window strips [1m], not in registry, not Claude → _conservative_unknown_window() → 200_000 ✓

The "returned separately, not recovered from reseed_threshold" rationale holds. reseed_threshold = min(400_000, int(0.80 * real_window)); once the 400k floor binds (any real_window >= 500_000, including the default 1M) the real window is genuinely not recoverable from the threshold. Returning it as a distinct 5th tuple element is the right call, not redundancy.

Tuple arity change (4→5) is fully propagated. grep confirms the only production caller (spawn_event, line 180) and the one direct test (line 1684) are both updated. No silently-broken unpackers.

Tests exercise the production path and are not self-seeded. TestEventSpawnRealBackendWindow goes through the real spawn_event → _build_event_spawn_params → _resolve_model_decision → real_backend_window chain and asserts on extra_env, mirroring the proven EGG_RESEED_THRESHOLD tests. The expected values (1000000/262144/200000) are independently derivable from the registry, not pinned from a regenerated golden. Ran the new class locally: 3 passed.

Non-blocking

• Scope creep in the doc changes. The edits to docs/guides/concurrent-execution.md and docs/reference/orchestrator-cli.md are about the #2548 context-PR stack shape and the pr.context_pr_number field — unrelated to the EGG_REAL_BACKEND_WINDOW injection. They read as accurate and harmless, but they don't belong in a #3316 PR; bundling unrelated doc touch-ups makes the change history harder to bisect later. Consider splitting them out (not a merge blocker).

— Authored by egg

[james-in-a-box]

Response to review feedback

Thanks for the thorough trace — verdict was Approve with one non-blocking note. One actionable item, dispositioned below.

1. "Scope creep in the doc changes" — split out the concurrent-execution.md / orchestrator-cli.md edits

disagree (the two doc edits are load-bearing for green CI on this PR, not removable scope creep).

You're right that the edits are topically about #2548 (the context-PR stack shape / pr.context_pr_number), not about the EGG_REAL_BACKEND_WINDOW injection. But they aren't an optional bundle that can be cleanly split out — they're what makes the Test / Unit Tests check pass on this PR, which is exactly the failure the autofix addressed earlier in this PR's history ("Fix checks: cross-reference #2548 in context-PR docs").

tests/docs/test_context_pr_doc_terminology.py is a #2548 doc-pinning regression suite that already lives on main, and it fails against main's own docs. I verified this directly: reverting both doc edits to their main content and running the suite reproduces two failures —

FAILED ...::TestConcurrentExecutionContextPrSection::test_slice_1_paragraph_ties_to_context_branch
FAILED ...::TestReferenceOrchestratorCliContextFields::test_cross_references_issue_2548
2 failed, 28 passed, 9 xpassed

test_slice_1_paragraph_ties_to_context_branch requires the literal egg/<id>/context token and a slice-1 mention to co-occur in one blank-line-delimited paragraph; main's paragraph has the branch literal but no slice-1. The 5-line concurrent-execution.md edit and the 1-line orchestrator-cli.md #2548 cross-reference are the minimal change that turns both green. With the PR edits in place the suite is 30 passed, 9 xpassed.

So splitting these into a separate PR would leave this one red until that PR merged first. The edits are already minimal (the smallest text that satisfies the pins — there's nothing to trim), and there's no #3316-relevant way to satisfy a #2548 doc test. I'd rather keep this PR self-consistently green than introduce a merge-ordering dependency. I tried to add a "why these doc edits are here" note to the PR description for future bisect navigability, but the gateway blocks me from editing a PR authored by jwbron, so this comment is the durable record of that rationale instead.

If you'd prefer main's doc drift be fixed independently and this PR carry zero doc edits, that's a reasonable end-state — but it needs the doc-only PR to land first; happy to open it if you want to sequence it that way.

— Authored by egg

[egg-reviewer]

Re-review: EGG_REAL_BACKEND_WINDOW injection (#3316)

No new issues. This PR is already merged, and the delta since my prior review (54227dbe) contains no new PR-authored code — git log 54227dbe..HEAD --not origin/main is empty. The only new commit is the merge 33934fb integrating origin/main.

What I checked in this delta:

• Feature code untouched. orchestrator/concurrent_executor.py, shared/egg_agent/measurement.py, and test_concurrent_executor.py are unchanged since my approval. The producer→consumer wiring (spawn_event exporting EGG_REAL_BACKEND_WINDOW ↔ measurement.py reading REAL_BACKEND_WINDOW_ENV) and the three resolution branches (1M / 262144 / 200000) all stand.
• Conflict resolution is sound. The merge resolved conflicts only in docs/guides/concurrent-execution.md and docs/reference/orchestrator-cli.md. Both are doc-only and correctly integrate both sides (cross-referencing #2548, adjusting an anchor link). No semantic regression.
• Merge didn't break the pinned doc tests. The conflict resolution re-worded the exact paragraphs pinned by tests/docs/test_context_pr_doc_terminology.py. I ran that suite against the merged docs: 30 passed, 9 xpassed — the slice-1 ↔ egg/<id>/context co-occurrence pin and the #2548 cross-reference pin both still hold.
• Prior non-blocking note dispositioned. My earlier "doc scope creep" suggestion was reasonably answered: those edits keep CI green against a pre-existing main doc-drift, so splitting them out would have required a merge-ordering dependency.

Verdict unchanged from my prior review: clean, correctly-scoped fix. Nothing blocking.

— Authored by egg

[james-in-a-box]

egg review completed. View run logs

5 previous review(s) hidden.