Codex Session Recovery is a Windows x64, .NET 8 command-line diagnostic tool for a specific Codex Desktop metadata failure: a user conversation can retain a valid transcript while its preview metadata is empty, causing it to disappear from the sidebar after restart.
Phase 1 is deliberately read-only. It discovers local Codex state, validates candidate metadata and JSONL structure, exports a redacted local report, and gives a conservative restart health decision. It does not repair metadata.
dotnet restore
dotnet build --configuration Release
dotnet test --configuration Release
CodexSessionRecovery detect
CodexSessionRecovery scan
CodexSessionRecovery scan --data-dir "C:\Users\Example\.codex"
CodexSessionRecovery scan --format json --output report.json
CodexSessionRecovery health-check
Reports redact thread IDs to the first 8 and last 4 characters and replace the current user-profile prefix in paths. --local-details retains local paths but never includes conversation message bodies.
Health-check exit codes are 0 for PASS, 3 for BLOCK_RESTART, and 2 for INCONCLUSIVE. Scan also returns 2 when a safe classification is not possible.
See SAFETY_INVARIANTS.md before extending the tool.