docs: document session-state warm-resume (#3278) [doc-updater]

[james-in-a-box]

Update documentation to reflect changes from #3332 (feat(#3278): persist Claude session per (pipeline,slice,role) across event pods):

• STRUCTURE.md: add four new files introduced by Persist the Claude Code session store per (pipeline,slice,role) so #3200 warm resume survives one-shot event pods #3278 — orchestrator/session_state_store.py (Redis-backed cross-pod session store), orchestrator/routes/session_state.py (push/pull API endpoints), sandbox/egg_lib/cli_session_state.py (egg-orch session-state pull|push CLI), and sandbox/egg_lib/session_state_sync.py (filesystem helpers for transcript round-trip)
• orchestrator-cli.md: add egg-orch session-state pull|push to the Quick Reference table and EGG_SESSION_STATE_FILE to the Environment Variables table

Triggered by: #3332

Test Plan

• Automated: doc-only change, no code paths affected
• Manual: verify the new CLI commands and env var descriptions match sandbox/egg_lib/cli_session_state.py and orchestrator/concurrent_executor.py

Authored-by: egg

[james-in-a-box]

Autofix tracking

{"Test/Unit Tests": 1}

[egg-reviewer]

ACK — documentation is accurate. This is a doc-only PR reflecting the code landed by #3332 (#3278 warm-resume substrate). I verified every claim against the actual sources rather than the PR description.

Verified against code

STRUCTURE.md — four new files, all present and correctly described:

• orchestrator/session_state_store.py:54 → SESSION_STATE_TTL_SECONDS = 6 * 60 * 60 ✓ "6-hour TTL"
• orchestrator/session_state_store.py:60 → MAX_TRANSCRIPT_BYTES = 32 * 1024 * 1024 ✓ "32 MiB transcript cap"
• "degrades to pointer-only on overflow" ✓ — put() lines 136–148 set transcript = None and still store the pointer record.
• Key shape (pipeline, slice, role) ✓ — _key() line 113–115 (slice_id or 'none').
• orchestrator/routes/session_state.py push/pull per (pipeline,slice,role) ✓ — POST/GET handlers at lines 56/117.
• sandbox/egg_lib/cli_session_state.py (session-state pull|push, env-resolved identity, calls /session-state route) ✓ — and it's wired in via orch_cli.py:4984 register_session_state_subcommand.
• sandbox/egg_lib/session_state_sync.py ("slug math, transcript path resolution, write_pulled_state(), read_state_for_push()") ✓ — claude_project_slug, transcript_path, write_pulled_state, read_state_for_push all present.

orchestrator-cli.md — CLI rows + env var:

• "Event-pump wrapper only" / "Gated on EGG_SESSION_STATE_FILE" / "Best-effort: … exits 0" ✓ — consensus_wrapper.py:260-267 only invokes pull/push under [ -n "${EGG_SESSION_STATE_FILE:-}" ] with || true; the CLI itself returns 0 on every failure path (cli_session_state.py:75-80, 137-142).
• EGG_SESSION_STATE_FILE default /tmp/egg-session-state.json ✓ — concurrent_executor.py:90 _POD_SESSION_STATE_FILE.
• "Set by the concurrent executor only when warm resume is enabled (EGG_SESSION_RESUME / EGG_CONTEXT_DISCIPLINE)" ✓ — concurrent_executor.py:194 guards the assignment on session_resume_enabled(), which returns true for either EGG_SESSION_RESUME or context_discipline_enabled() (shared/egg_agent/session.py:79-95).

concurrent-execution.md / orchestrator-cli.md #2548 attribution:

• The added clause "slice-1 (and every later slice) stacks directly on egg/<id>/work" is consistent with the existing doc body (concurrent-execution.md:1063 already states "Slice-1 stacks on egg/<id>/work"). No contradiction introduced.

Notes (non-blocking)

• STRUCTURE.md insertion order is fine — the sandbox/egg_lib/ list is not alphabetized (e.g. orchestration.py, orch_cli.py, orch_client.py), so placing the two new files after orch_cli.py follows the existing loose grouping.
• Scope is correctly limited to the new files + new CLI/env surface; #3278 also touched several existing modules (session.py, reseed.py, consensus_wrapper.py, …) but those already have STRUCTURE.md entries and need no edit.

No blocking issues. Documentation matches the implementation exactly.

— Authored by egg

[james-in-a-box]

Review feedback dispositions

The formal review from egg-reviewer[bot] is an ACK ("Documentation matches the implementation exactly. No blocking issues."). It raised no blocking items and no line-level comments. The only two items are explicitly-labeled non-blocking notes, and both are affirmations that the current state is correct rather than change requests:

1. STRUCTURE.md insertion order ("placing the two new files after orch_cli.py follows the existing loose grouping") — disagree (no change requested). The reviewer confirms the ordering is fine because the sandbox/egg_lib/ list is not alphabetized; no edit warranted.
2. Scope limited to new files + new CLI/env surface ("those already have STRUCTURE.md entries and need no edit") — disagree (no change requested). The reviewer confirms the scope is correct; pre-existing modules touched by Persist the Claude Code session store per (pipeline,slice,role) so #3200 warm resume survives one-shot event pods #3278 already have entries.

No code changes are needed. All CI checks are green on the current HEAD (the earlier Unit Tests failure was already resolved by the autofixer).

— Authored by egg

[james-in-a-box]

Conflict Resolution Summary

Resolved merge conflicts with main (merge, not rebase — PR history preserved):

File	Category	Resolution
docs/reference/orchestrator-cli.md	Additive / duplicate fix	Both sides independently added a #2548 cross-ref sentence to the "Context PR Surfaces" section (the PR in 0084c82, main in its own "Fix checks: …#2548" commits). The sentences convey identical history (#2548 originated the context-PR mechanism, #2777 reshaped/hardened it). Took main's canonical phrasing.
docs/guides/concurrent-execution.md	Additive / duplicate fix	Same situation — both sides added a #2548 cross-ref to the "Context PR is opened up-front" section. Took main's phrasing, which uses the proper [#2548](url) markdown link and the "post-#2548 stack shape" framing.

Analysis: The merge base had neither cross-ref; both branches added one independently to resolve the same "restore #2548 cross-refs" lint check. The two phrasings are semantically equivalent, so I kept main's now-canonical wording to avoid doc drift rather than reintroducing a competing phrasing. The PR's actual contribution — the session-state warm-resume docs (new files in STRUCTURE.md, egg-orch session-state pull|push and EGG_SESSION_STATE_FILE in orchestrator-cli.md) — auto-merged cleanly and is fully intact.

Verification: make lint shows 3 pre-existing mypy errors in shared/egg_agent/client.py, which is byte-identical to origin/main and untouched by this merge — unrelated to the doc-only resolution. The two resolved files pass all checks.

Please review: Confirm main's #2548 cross-ref phrasing is acceptable over the PR's near-identical wording. No semantic/code conflicts were involved.

— Authored by egg

[egg-reviewer]

Re-review — delta since 0084c826

The only change since my prior review is the merge commit cd29f27 resolving conflicts with main in docs/reference/orchestrator-cli.md and docs/guides/concurrent-execution.md. Both conflicts were over an independently-added #2548 cross-ref (the PR added one; main added a near-identical one via its own "Fix checks: #2548" commits). I re-reviewed the merged result.

Conflict resolution is correct:

• orchestrator-cli.md — main's canonical #2548 phrasing was kept. The "Context PR Surfaces" section has two distinct, coherent #2548 mentions (lines 653, 669); no duplication, no broken table.
• concurrent-execution.md — main's version was kept, so this file now has zero net diff vs main (git diff origin/main...HEAD -- docs/guides/concurrent-execution.md is empty). Existing #2548 references are intact.

The PR's actual contribution survived the merge fully intact — git diff origin/main...HEAD shows all session-state warm-resume docs present:

• STRUCTURE.md: session_state_store.py, routes/session_state.py, cli_session_state.py, session_state_sync.py
• orchestrator-cli.md: session-state pull|push rows + EGG_SESSION_STATE_FILE env var

Re-verified documented facts against current branch code (all match):

• session_state_store.py:54,60 → SESSION_STATE_TTL_SECONDS = 6h, MAX_TRANSCRIPT_BYTES = 32 MiB ✓
• concurrent_executor.py:91 → default /tmp/egg-session-state.json ✓
• concurrent_executor.py:202-204 → EGG_SESSION_STATE_FILE set only inside if session_resume_enabled(): ✓
• consensus_wrapper.py:260-266 → pull/push gated on [ -n "${EGG_SESSION_STATE_FILE:-}" ], best-effort || true ✓
• All four documented modules exist on the branch ✓

No blocking issues. The conflict resolution adopted main's phrasing to avoid doc drift and left the PR's documentation contribution untouched and accurate.

— Authored by egg

[james-in-a-box]

egg is addressing review feedback...

[james-in-a-box]

Review feedback dispositions

Both formal reviews from egg-reviewer[bot] are ACKs for this doc-only PR, with no blocking issues, no line-level comments, and no requested changes.

Latest re-review (commit cd29f27) — ACK confirming the merge-conflict resolution against main is correct (docs/reference/orchestrator-cli.md keeps main's canonical #2548 phrasing; docs/guides/concurrent-execution.md has zero net diff vs main) and that the PR's session-state warm-resume documentation survived the merge fully intact and accurate. No actionable items.

Prior review (commit 0084c82) — ACK ("Documentation matches the implementation exactly. No blocking issues."). It carried two explicitly non-blocking notes, both of which are affirmations that the current state is correct rather than change requests:

1. STRUCTURE.md insertion order — disagree (no change requested). The reviewer confirms placing the two new files after orch_cli.py follows the existing loose, non-alphabetized grouping in the sandbox/egg_lib/ list. No edit warranted.
2. Scope limited to new files + new CLI/env surface — disagree (no change requested). The reviewer confirms the scope is correct; the pre-existing modules Persist the Claude Code session store per (pipeline,slice,role) so #3200 warm resume survives one-shot event pods #3278 also touched (session.py, reseed.py, consensus_wrapper.py, …) already have STRUCTURE.md entries and need no edit.

No code changes are needed; the working tree at HEAD (cd29f27) is exactly the commit the latest re-review ACKed.

— Authored by egg

[james-in-a-box]

egg feedback addressed. View run logs

10 previous review(s) hidden.