Codex Context Repair

Codex Context Repair

Safety Rules

• Treat Codex local state as user data. Never delete or truncate session history.
• Always run diagnosis first unless the user explicitly asked for repair.
• Before repair, back up the target rollout JSONL to C:\Users\Administrator\.codex\migration_backups.
• Prefer repairing one explicit thread id. If several threads match a title/path, show candidates and ask the user to choose.
• Do not paste large JSONL/session contents into chat. Report ids, paths, counts, and concise findings.

Workflow

1. Identify the affected thread:
   • Use a user-provided thread id when available.
   • Otherwise list likely threads by title, cwd, updated time, token count, and rollout path.
2. Diagnose:
   • Check state_5.sqlite for threads, jobs, and stage1_outputs.
   • Inspect the target sessions/**/*.jsonl tail for task_started, task_complete, turn_aborted, compacted, and context_compacted.
   • Measure large JSONL lines and recent token_count events.
3. Decide whether repair is appropriate:
   • Good candidate: a compact/task turn started but no completion event follows, or token count is near the model context window and no recent context_compacted was written.
   • Bad candidate: active current thread still running, missing rollout file, or multiple ambiguous matches.
4. Repair only with explicit intent:
   • Run scripts/repair_codex_context.py --thread-id <id> --repair.
   • The script appends a manual turn_aborted for an unfinished last task when needed.
   • The script appends a small compacted checkpoint containing a recovery summary and next-step prompt.
   • The script appends context_compacted after the checkpoint and refreshes threads.updated_at.
5. Verify:
   • Re-read the JSONL tail and confirm the final events are the manual compact checkpoint and context_compacted.
   • Tell the user to restart Codex if the UI still shows cached old state.

Script

Use:

python C:\Users\Administrator\.codex\skills\codex-context-repair\scripts\repair_codex_context.py --list
python C:\Users\Administrator\.codex\skills\codex-context-repair\scripts\repair_codex_context.py --thread-id <thread-id> --diagnose
python C:\Users\Administrator\.codex\skills\codex-context-repair\scripts\repair_codex_context.py --thread-id <thread-id> --repair

Useful filters:

python C:\Users\Administrator\.codex\skills\codex-context-repair\scripts\repair_codex_context.py --list --cwd-like "D:\Desktop"
python C:\Users\Administrator\.codex\skills\codex-context-repair\scripts\repair_codex_context.py --list --title-like "重构"

On Windows PowerShell, if Chinese filter text gets mangled, use thread id, cwd fragments without Chinese, or Unicode escapes through Python.