fix(codex): recover interrupted state DB backfills

[brennanb2025]

Fixes #11830. Related: #11828 and upstream openai/codex#37003.

Summary

• Detect incomplete state-DB backfills in managed Codex homes without mutating Codex-owned SQLite.
• Supervise a durable codex app-server claimant behind an exact process-incarnation lock, recovering dead or PID-reused Orca owners while leaving live owners and concurrent Orca instances untouched.
• Cover native macOS/Linux/Windows and WSL homes, defer short trust/rate-limit app-server probes that could refresh the stale lease, and reap owned recovery children on app quit.
• Surface Codex's backfill timeout in the pane as an actionable recovery message instead of silently dropping to a shell.

This branch was implemented fresh from current main; it does not reuse or cherry-pick the closed release-lineage PR #11981.

Screenshots

Electron QA through CDP, showing the recovery message in a Codex-launched pane:

Testing

• pnpm lint
• pnpm typecheck
• pnpm test
• pnpm build
• Added or updated high-quality tests that would catch regressions, or explained why tests were not needed

Focused validation after the final rebase:

• 73/73 tests across state inspection/recovery, dead and PID-reused owner recovery, live-owner non-interference, Windows creation-time identity, install locking, trust deferral, rate-limit deferral, WSL routing, and renderer detection.
• Main PTY Codex owner-arbitration integration: 1 passed / 446 skipped.
• Renderer PTY actionable-error integration: 1 passed / 544 skipped.
• Electron dev build booted successfully and the exact Codex-pane error path displayed the screenshot above.

The full local src/main/ipc/pty.test.ts file reached 438 passing tests; nine unrelated MiMo/Pi/WSL harness cases failed in this environment. None exercises a Codex launch or the new recovery mock, and the change-owned Codex integration test is green.

AI Review Report

Reviewed the complete delta against origin/main, including recovery lifecycle, lock stealing, child-process exit races, read-only DB inspection, shutdown, and all short-lived Codex app-server call sites. The review explicitly checked native macOS, Linux, and Windows process identity, WSL distro/PID-namespace scoping and shell quoting, SSH/folder-workspace behavior, path normalization, and Electron renderer behavior; no shortcut or label behavior changed.

The central integration risk is that Codex 0.146's backfill_state does not record a verifiable owner. The implementation therefore never guesses from CPU activity or age and never writes Codex schema: Orca arbitrates only its own supervisor with host + PID + process-start identity, while Codex's existing lease/claim transaction arbitrates the actual backfill. The missing upstream owner/repair contract is tracked in openai/codex#37003.

Security Audit

• SQLite access is read-only with fileMustExist; Orca never updates, deletes, or recreates Codex-owned state.
• Recovery commands use fixed arguments, existing Windows spawn handling, existing WSL login-shell quoting, and an absolute system PowerShell path. No user-controlled command fragments are introduced.
• Lock paths hash normalized Codex-home paths under Orca user data, and the existing atomic hard-link claim protocol prevents concurrent ownership or unsafe replacement.
• Windows liveness uses MachineGuid plus CIM process creation time, not PID alone; Linux includes PID namespace, boot ID, and start ticks; macOS includes boot identity and process start data.
• No auth material, secrets, dependencies, or new IPC surface are introduced.

Caveats

• Recovery-only churn can launch roughly one losing app-server every 32 seconds while a foreign Codex backfill lease remains live.
• Recovery checks Codex's SQLite state read-only every five seconds.
• The recovery supervisor stops after one hour; tighten that cap if real histories materially exceed the reported six-minute recovery.

Notes

Orca keeps the sanctioned app-server claimant alive until Codex marks the backfill complete, but intentionally does not hold pane startup for the full potentially long index. Pane startup waits only for exact Orca supervisor-owner arbitration; Codex remains the sole authority for its backfill claim.

On quit, Orca terminates and joins only recovery children it owns. Crash recovery remains required and covered because no shutdown path can make an abrupt host/process loss impossible.

[coderabbitai]

📝 Walkthrough

Walkthrough

The change adds Codex state-database inspection and backfill recovery. Recovery supports native and WSL execution, polling, retries, cancellation, shutdown, and supervisor locking. Codex PTY spawning, rate-limit fetching, trust grants, and application lifecycle now coordinate with recovery. Renderer PTY connections detect backfill-timeout output and report a recovery notice. Windows host and process identity detection now use registry and PowerShell probes. Configuration includes the new CLI sources.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 34.78% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main change: recovering interrupted Codex state DB backfills.
Description check	✅ Passed	The description includes all required sections, detailed testing, review, security, platform notes, and explains why the full test checkbox remains unchecked.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[brennanb2025]

Managed-home recovery: a stale running backfill with a dead supervisor owner recovered to complete, and the Codex pane launched with the recovered session-history index ready.

Actionable failure state: when recovery could not proceed, the Codex pane rendered the background-recovery guidance and retry instructions.