codex-runtime-recovery

Codex Runtime Recovery

Overview

Recover Codex when runtime ownership drifts across hosts or launch paths. Start read-only, identify the canonical store, and separate data-plane issues from extension-host or auth failures before touching live state.

Reference Map

• Read references/topology-checks.md to verify active CODEX_HOME, candidate stores, config paths, and lock-sensitive files.
• Read references/recovery-lanes.md to choose between lightweight recovery, canonicalization, and reset-only-as-last-resort flows.
• Run scripts/inspect_codex_topology.py before making any mutation. It inventories candidate stores, session counts, and state DB presence without editing them.

Required Discovery

1. Identify the active host and launch path: CLI, VS Code, Windows, WSL, or remote.
2. Determine the authoritative store to preserve before merging or resetting anything.
3. Separate data-plane failures from control-plane failures.
4. Inspect auth.json, config.toml, state_5.sqlite*, and session trees before rotating or deleting them.

Recovery Lanes

Lightweight lane

Use when the session exists and visibility is broken. Prefer targeted JSONL import, codex resume, or a path fix over broad resets.

Canonicalization lane

Use when Windows and WSL or CLI and VS Code have diverged. Converge on one canonical CODEX_HOME, archive mirrors, and update launch settings to stop re-divergence.

Reset lane

Stop Rules

Output Contract

Common Mistakes