Restore Codex Conversations

Restore Codex Conversations

Restore local conversation visibility with a backup-first, evidence-driven workflow. Treat database rows, rollout metadata, the session index, and project mappings as one consistency set.

Safety rules

1. Limit writes to the current computer's active Codex home, normally %USERPROFILE%\.codex or $CODEX_HOME.
2. Treat attached old system or project disks as read-only unless the user explicitly authorizes writes or path remapping on those disks.
3. Preserve archived threads, subagent threads, original timestamps, cwd values, sandbox boundaries, and rollout history unless a verified compatibility requirement says otherwise.
4. Back up the SQLite database consistently, the global state, the session index, and every target rollout before mutation.
5. Derive model_provider and cli_version from a currently visible official-account main thread. Never copy provider/version constants from examples.
6. Request the required filesystem approval before writing outside the workspace. Do not work around a denied write.
7. Never delete Electron Local Storage or Session Storage as a first-line recovery step.

Workflow

1. Establish scope

• Resolve the active Codex home and verify that state_5.sqlite, .codex-global-state.json, session_index.jsonl, and sessions/ belong to the current installation.
• If the user requested diagnosis or explanation only, remain read-only and report the consistency gaps. Execute repairs only when the request authorizes restoration.
• If old disks are attached, distinguish the current Codex home from historical copies before any mutation.

2. Inspect before changing

• Read references/restore-project-conversations.md completely before performing a migration. For a read-only diagnosis, read the sections covering scope, template selection, target selection, and validation.
• Locate a usable sqlite3 executable from --sqlite, $SQLITE3_PATH, or PATH rather than assuming one installation path.
• Count main, archived, and subagent threads separately.
• Verify every selected rollout_path exists on the current computer and begins with {, not a UTF-8 BOM.
• Compare database main-thread IDs with session_index.jsonl, thread-writable-roots, and thread-project-assignments.
• Select a current visible official main thread as the provider/version template.

3. Choose the repair path

Prefer scripts/restore_codex_conversations.js when the active schema matches the reference and the user requested restoration. Run it without --apply first; the default mode is a read-only preflight. Review the selected template and targets, then rerun with --apply only after the repair scope is confirmed.

Use the manual procedure in the reference when:

• the schema differs from the script's expected threads columns;
• the target is a small, explicitly named subset;
• rollout metadata is malformed beyond the first line;
• project-path migration is also requested;
• the script's preflight validation fails.

Do not run the script if no currently visible official main thread exists; first ask the user to create one so the compatibility template is observable.

4. Execute narrowly

• Migrate unarchived main threads whose provider is incompatible with the current template.
• Exclude guardian, reviewer, and other subagent rows.
• Keep source semantics, cwd, archived state, timestamps, and sandbox policy unless the current schema requires a documented change.
• Update only rollout line 1 when repairing session_meta; preserve the remaining bytes.
• Write JSON and JSONL as UTF-8 without BOM.
• Add missing session-index rows without replacing existing human-friendly thread names.
• Add or repair local-projects, thread-writable-roots, and thread-project-assignments using exact or longest-root matching.
• Never mechanically replace old drive letters with attached-disk drive letters.

5. Verify at every layer

• Run PRAGMA integrity_check; use wal_checkpoint(TRUNCATE) after the client exits or PASSIVE while it remains open.
• Recount official-compatible, archived, and subagent rows.
• Parse each changed rollout first line and confirm the first byte is 7B.
• Parse every session-index line and the entire global-state JSON.
• Confirm backup and manifest files exist.
• If Codex thread tools are available, search for and read an old thread. Do not send it a new task merely to test restoration.
• Fully restart Codex Desktop, then verify the old conversation appears under its project and opens with historical turns.

Bundled resources

• references/restore-project-conversations.md: detailed schema notes, SQL examples, backup requirements, project mappings, failure modes, and manual checklist.
• scripts/restore_codex_conversations.js: deterministic migration used successfully on the source machine. It resolves the active Codex home and sqlite3 portably, defaults to a read-only preflight, dynamically chooses a current-account template, creates backups on --apply, updates compatibility metadata and mappings, and performs integrity checks.

Treat the script as a migration tool, not a Codex runtime dependency. Review its default paths and arguments on every new machine or client schema.