cmux: make large Subrouter session restores reliable

DA
16d ago
+7970-383

Summary

Restored cmux sessions can lose their Subrouter routing evidence or start too many Ghostty surfaces at once. That left Codex restores at the missing SUBROUTER_CODEX_DUMMY_API_KEY screen, produced account/read bootstrap failures, and could drive the app into the CPU and WindowServer failure mode described in https://github.com/manaflow-ai/cmux/issues/21352.

This change:

  • detects and preserves Subrouter provider evidence from captured launch data;
  • injects the local SUBROUTER_CODEX_DUMMY_API_KEY sentinel for restored Codex sessions;
  • resumes routed sessions with sr codex resume <checkpoint> --cd <directory>;
  • honors persisted autoResume bindings, including legacy binding-only records;
  • spreads routed startup and serializes restored native surface admission.

Validation

On Apple silicon M3 using the preserved 41-workspace/138-panel session manifest:

  • all 41 workspaces and 138 panels restored;
  • all 41 persisted auto-resume states reached autoResumeCommandRunning;
  • no account/read, missing-environment, or Subrouter exit errors;
  • settled tagged app resource sample: about 1% CPU and 920 MB RSS;
  • focused tests passed: 17/17 restore scheduler tests and 26/26 resume argument tests;
  • Swift syntax verification passed.

Changelog

Fixed restored Subrouter Codex sessions and paced large session restores.

Refs: #21352

View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith-bot with what you need.

Summary by cubic

Makes large Subrouter session restores reliable, recovers Codex sessions killed with the app, and bounds feed startup recovery so damaged or oversized history cannot hang startup. Restored Codex and Claude sessions previously lost Subrouter routing evidence, spawned too many Ghostty surfaces at once, or stalled at missing credential prompts with high CPU and WindowServer load.

Session restore

  • Preserves Subrouter provider evidence from captured launch data, injects the local SUBROUTER_CODEX_DUMMY_API_KEY sentinel, and fails closed on missing, conflicting, ambiguous, cross-source, or custom-path declarations; legacy Codex and Claude records are rebuilt only from trusted markers and only through bounded restore admission.
  • Resumes routed sessions with sr codex resume <checkpoint> or sr claude proxy --resume, preserves validated outer Codex launcher prefixes including custom launchers, and rejects records whose executable identity contradicts captured evidence; restored panes are joined to live process evidence in cmux sessions list diagnostics.
  • Caps admission retries by wall-clock and attempt budgets, admits process-detected bindings only after policy review, and fails closed when a saved working directory is missing or unmounted.
  • Recovers Codex sessions after an unclean app exit through the structured restore verb; cmux records its own panel-close boundary so intentional closes are not resurrected, and duplicate agent checkpoints restore once while staying manually recoverable.
  • Serializes cmux-cua helper launches across processes with a kernel lease, paces restored native surface spawns at one second, defers native surfaces until the restored pane is presented, deduplicates window manifests a crash can leave written twice, and keeps bootstrap restore callbacks inert.

Feed startup

  • Bounds workstream startup recovery for large or damaged history with a hard time budget, keeps feed revisions ordered past 2 GiB with a durable revision floor preserved across startup and feed clear, skips oversized rows per page, restores recent items and paging state, and flushes persistence before orderly quit.

Summary by CodeRabbit

  • New Features

    • Eligible Codex sessions using the Subrouter provider can resume from saved checkpoints, including sessions that were not running when the app closed. Eligible Claude sessions can also resume through Subrouter.
    • Codex sessions can be recovered after an unexpected process exit.
    • Terminal startup restores recent workstream items and paging state, even when history contains large, malformed, or incomplete sections.
    • Feed history can be cleared through the existing confirmation flow.

  • Bug Fixes

    • Reduced duplicate terminal creation and spaced out restored terminal launches.
    • Sessions with unavailable volume-based working directories use a usable startup location while preserving the saved workspace path.
    • Ambiguous provider details and mismatched launch information no longer trigger Subrouter resumes.
    • Improved persistence recovery and revision tracking when history files are missing, damaged, or cleared.