Codex Thread Repair
Repair a specific local task without rewriting its message bodies or replacing the whole Codex state directory.
Dependencies
- macOS with the Codex desktop app installed as
/Applications/ChatGPT.app.
- Python 3.10 or newer. The repair script uses only the Python standard library.
- A local Codex state directory containing
state_5.sqlite, sqlite/codex-dev.db, and the selected task's JSONL rollout. It defaults to $CODEX_HOME when set, otherwise ~/.codex.
- Local read/write access to the selected rollout and Codex state. No network access or third-party Python package is required.
Workflow
Resolve <skill-dir> as the directory containing this SKILL.md; never assume that the current working directory is the skill directory. Resolve and diagnose the user-supplied title or ID while Codex may remain open:
python3 "<skill-dir>/scripts/thread_repair.py" diagnose "<title-or-id>"
Exact UI-title matches come from local_thread_catalog; canonical rows and rollout paths come from state_5.sqlite. If a title is ambiguous, show the candidates and ask the user for an exact ID. Never choose by recency alone.
Read references/repair-patterns.md when diagnosis is not healthy or supported_ordinal_orphan. Do not auto-repair an unrecognized structure.
For supported_ordinal_orphan, explain the detected boundary and prepare one offline launcher:
python3 "<skill-dir>/scripts/thread_repair.py" prepare "<title-or-id>"
Tell the user to press Cmd+Q and then double-click the returned .command file. The launcher creates a targeted recovery set, applies the patch atomically, verifies it, and reopens Codex.
After Codex restarts, verify both layers:
python3 "<skill-dir>/scripts/thread_repair.py" verify "<title-or-id>"
Also use the Codex task-reading tool to confirm that the formerly hidden recent turns are separate and readable.
Keep the backup until the user confirms the UI. If rollback is required, have the user quit Codex and run:
python3 "<skill-dir>/scripts/thread_repair.py" rollback "<backup-directory>" --reopen
Safety boundaries
- Diagnosis and launcher preparation are read-only with respect to Codex state.
- Mutation requires Codex Desktop, its renderer/services, and its app-server to be stopped.
- Resolve the selected rollout to an absolute path under the selected Codex home's
sessions/ directory. Refuse relative paths, symlink escapes, and database paths outside that directory.
- Back up the target rollout plus consistent snapshots of
state_5.sqlite, codex-dev.db, and .codex-global-state.json before replacement.
- Preserve the original rollout byte-for-byte in the backup.
- Auto-repair only the narrowly validated ordinal-regression/orphan-turn pattern. Refuse multiple regressions, ambiguous open turns, missing rollouts, malformed JSON, non-contiguous segments, active latest turns, or session-ID mismatches.
- Preserve every original line except the top-level
ordinal value after the repair boundary; insert exactly one turn_aborted event. Verify a normalized content hash before replacement.
- Do not edit SQLite rows for this repair type. For provider mismatches, missing assignments, moved paths, or missing database rows, use
recover-codex-project-chats instead.
- On any post-replacement verification failure, restore the backed-up rollout automatically.
Commands
python3 "<skill-dir>/scripts/thread_repair.py" resolve "<title-or-id>"
python3 "<skill-dir>/scripts/thread_repair.py" diagnose "<title-or-id>"
python3 "<skill-dir>/scripts/thread_repair.py" prepare "<title-or-id>"
python3 "<skill-dir>/scripts/thread_repair.py" apply "<exact-thread-id>" --reopen
python3 "<skill-dir>/scripts/thread_repair.py" verify "<title-or-id>"
python3 "<skill-dir>/scripts/thread_repair.py" rollback "<backup-directory>" --reopen
--codex-home <path> is a global option and must appear before the subcommand. prepare --output <path> selects a new launcher path and refuses to overwrite an existing file. apply --reopen and rollback --reopen request reopening Codex; failure to reopen is reported as a warning without undoing a successful file operation.
Exit codes are 0 for success or no repair needed, 1 for an operational/safety error, 2 for an ambiguous selector or invalid CLI use, and 3 for an unsupported diagnosis or failed verification.
Report the resolved ID, UI title, rollout path, diagnosis, changed metadata, backup directory, integrity results, and UI verification outcome.
See CHANGELOG.md for release history.
1---2name: codex-thread-repair3description: Diagnose and safely repair one local Codex Desktop task selected by its UI title or thread ID when recent turns are missing, truncated, merged into an interrupted turn, or hidden by damaged rollout ordering. Do not use for broad project/provider restoration or ordinary task continuation.4---56# Codex Thread Repair78- **Version**: 1.0.19- **License**: MIT10- **Author**: Evan Song · [github.com/Songhonglei](https://github.com/Songhonglei)11- **Repository**: https://github.com/Songhonglei/better-agent-skills/tree/main/skills/codex-thread-repair1213Repair a specific local task without rewriting its message bodies or replacing the whole Codex state directory.1415## Dependencies1617- macOS with the Codex desktop app installed as `/Applications/ChatGPT.app`.18- Python 3.10 or newer. The repair script uses only the Python standard library.19- A local Codex state directory containing `state_5.sqlite`, `sqlite/codex-dev.db`, and the selected task's JSONL rollout. It defaults to `$CODEX_HOME` when set, otherwise `~/.codex`.20- Local read/write access to the selected rollout and Codex state. No network access or third-party Python package is required.2122## Workflow23241. Resolve `<skill-dir>` as the directory containing this `SKILL.md`; never assume that the current working directory is the skill directory. Resolve and diagnose the user-supplied title or ID while Codex may remain open:2526 ```bash27 python3 "<skill-dir>/scripts/thread_repair.py" diagnose "<title-or-id>"28 ```2930 Exact UI-title matches come from `local_thread_catalog`; canonical rows and rollout paths come from `state_5.sqlite`. If a title is ambiguous, show the candidates and ask the user for an exact ID. Never choose by recency alone.31322. Read [references/repair-patterns.md](references/repair-patterns.md) when diagnosis is not `healthy` or `supported_ordinal_orphan`. Do not auto-repair an unrecognized structure.33343. For `supported_ordinal_orphan`, explain the detected boundary and prepare one offline launcher:3536 ```bash37 python3 "<skill-dir>/scripts/thread_repair.py" prepare "<title-or-id>"38 ```3940 Tell the user to press Cmd+Q and then double-click the returned `.command` file. The launcher creates a targeted recovery set, applies the patch atomically, verifies it, and reopens Codex.41424. After Codex restarts, verify both layers:4344 ```bash45 python3 "<skill-dir>/scripts/thread_repair.py" verify "<title-or-id>"46 ```4748 Also use the Codex task-reading tool to confirm that the formerly hidden recent turns are separate and readable.49505. Keep the backup until the user confirms the UI. If rollback is required, have the user quit Codex and run:5152 ```bash53 python3 "<skill-dir>/scripts/thread_repair.py" rollback "<backup-directory>" --reopen54 ```5556## Safety boundaries5758- Diagnosis and launcher preparation are read-only with respect to Codex state.59- Mutation requires Codex Desktop, its renderer/services, and its app-server to be stopped.60- Resolve the selected rollout to an absolute path under the selected Codex home's `sessions/` directory. Refuse relative paths, symlink escapes, and database paths outside that directory.61- Back up the target rollout plus consistent snapshots of `state_5.sqlite`, `codex-dev.db`, and `.codex-global-state.json` before replacement.62- Preserve the original rollout byte-for-byte in the backup.63- Auto-repair only the narrowly validated ordinal-regression/orphan-turn pattern. Refuse multiple regressions, ambiguous open turns, missing rollouts, malformed JSON, non-contiguous segments, active latest turns, or session-ID mismatches.64- Preserve every original line except the top-level `ordinal` value after the repair boundary; insert exactly one `turn_aborted` event. Verify a normalized content hash before replacement.65- Do not edit SQLite rows for this repair type. For provider mismatches, missing assignments, moved paths, or missing database rows, use `recover-codex-project-chats` instead.66- On any post-replacement verification failure, restore the backed-up rollout automatically.6768## Commands6970```bash71python3 "<skill-dir>/scripts/thread_repair.py" resolve "<title-or-id>"72python3 "<skill-dir>/scripts/thread_repair.py" diagnose "<title-or-id>"73python3 "<skill-dir>/scripts/thread_repair.py" prepare "<title-or-id>"74python3 "<skill-dir>/scripts/thread_repair.py" apply "<exact-thread-id>" --reopen75python3 "<skill-dir>/scripts/thread_repair.py" verify "<title-or-id>"76python3 "<skill-dir>/scripts/thread_repair.py" rollback "<backup-directory>" --reopen77```7879`--codex-home <path>` is a global option and must appear before the subcommand. `prepare --output <path>` selects a new launcher path and refuses to overwrite an existing file. `apply --reopen` and `rollback --reopen` request reopening Codex; failure to reopen is reported as a warning without undoing a successful file operation.8081Exit codes are `0` for success or no repair needed, `1` for an operational/safety error, `2` for an ambiguous selector or invalid CLI use, and `3` for an unsupported diagnosis or failed verification.8283Report the resolved ID, UI title, rollout path, diagnosis, changed metadata, backup directory, integrity results, and UI verification outcome.8485See [CHANGELOG.md](./CHANGELOG.md) for release history.
Songhonglei