codex-session-recovery

Diagnose, privately back up, compact, verify, and hand off stalled or extremely slow Codex CLI sessions through the official app-server protocol. Use when a Codex resume/thread appears frozen, cold-lo

SKILL.md

GitHub

Codex Session Recovery

Recover the existing thread conservatively. Treat the rollout as private append-only evidence, not as a file to repair manually.

Non-negotiable safety rules

  • Read every applicable AGENTS.md before inspecting the project named by the thread.
  • Never truncate, replace, reformat, or open a rollout JSONL for writing.
  • Never update, copy, restore, or vacuum the live shared state_*.sqlite database.
  • Never kill a Codex, tmux, IDE, or app-server process that already owns the rollout.
  • Never bypass an unknown ownership result, missing backup, checksum failure, schema mismatch, or invalid JSON tail.
  • Keep raw rollouts, backups, database files, prompts, tokens, and generated images outside Git repositories and skill folders.
  • Change model or reasoning effort only when the user explicitly requests that exact change.
  • Do not retry authentication, quota, or failed-compaction errors automatically.

Use the bundled tool

Set the skill path once:

SKILL_DIR="${CODEX_HOME:-$HOME/.codex}/skills/codex-session-recovery"
RECOVERY="$SKILL_DIR/scripts/codex_session_recovery.py"

Run global options before the subcommand.

1. Check protocol compatibility

python3 "$RECOVERY" --json doctor

Require the generated app-server schema contract to pass. Treat the app-server as version-sensitive and fail closed when required methods or fields change.

2. Inspect without reading prompt text

python3 "$RECOVERY" --json inspect THREAD_UUID
python3 "$RECOVERY" --json inspect THREAD_UUID --scan

Use --scan only when aggregate rollout counts are useful; it streams the file without loading giant image lines into memory. Check:

  • exact rollout path and size;
  • newline and tail-JSON validity;
  • active file owners;
  • model, effort, and numeric token counters;
  • generated-image footprint;
  • optional compaction, abort, and inline-image counts.

If ownership.owners is non-empty, stop. Ask the user to finish, interrupt, close, or detach that session themselves, then inspect again.

3. Preview the mutation plan

python3 "$RECOVERY" --json recover THREAD_UUID --dry-run

The tool must resolve one active, regular, non-symlink, non-hardlinked rollout whose filename exactly matches the UUID under $CODEX_HOME/sessions.

4. Recover through supported APIs

python3 "$RECOVERY" --json recover THREAD_UUID --yes

This guarded sequence:

  1. locks the recovery helper for that UUID;
  2. proves that no external process owns the rollout;
  3. creates a new private 0700 backup directory outside Git;
  4. compresses the rollout and verifies both compressed and decompressed SHA-256 evidence;
  5. re-attests device, inode, size, mtime, and SHA-256 immediately before resume;
  6. resumes with excludeTurns: true through codex app-server --disable hooks --stdio and verifies the returned thread ID;
  7. rechecks that only the tool-owned process group opened the rollout;
  8. requests thread/compact/start;
  9. requires the matching contextCompaction item start/completion and completed turn;
  10. interrupts a known in-flight turn on timeout or protocol failure;
  11. always proves the original file prefix is unchanged and only append-only data was added, including after an operation failure.

Backups default to:

$CODEX_HOME/session-recovery-backups/THREAD_UUID/TIMESTAMP/

Do not put --backup-dir inside a repository.

5. Change effort only explicitly

When the user chooses a lower sticky effort to reduce subsequent latency:

python3 "$RECOVERY" --json recover THREAD_UUID --yes --effort medium

Report that the setting persists. If a later phase fails, report the partial setting change rather than pretending it rolled back.

JSON failures include a structured partial object with the verified backup, observed effort change, lifecycle result, interruption evidence, and postflight result when available.

6. Verify responsiveness

Cold-load without adding a model turn:

python3 "$RECOVERY" --json probe THREAD_UUID

Append a model canary only with explicit mutation consent:

python3 "$RECOVERY" --json canary THREAD_UUID --yes --expected SESSION_OK

Or add --canary to recover. A canary consumes quota and appends a user/assistant turn. Prompt instructions reduce tool risk but cannot make a model turn equivalent to a read-only operation.

7. Recheck a backup later

python3 "$RECOVERY" --json verify-backup \
  "$CODEX_HOME/session-recovery-backups/THREAD_UUID/TIMESTAMP/manifest.json"

Verify against the manifest, not against the now-appended live rollout.

Interpret the result correctly

Supported compaction reduces model-visible history. It does not shrink the append-only rollout file. A recovered multi-gigabyte thread can answer normally after loading yet still take minutes to cold-open.

When cold-start latency remains unacceptable:

  1. preserve the original thread as the archive;
  2. write a curated handoff that contains only current tasks, verified facts, paths, and next actions;
  3. keep raw private history in ignored/private storage;
  4. continue in a fresh thread using the handoff.

Use aginti-agentlink conventions when multiple sessions or machines share the handoff.

Stop conditions

Stop and report evidence when:

  • the rollout is active, ambiguous, archived, symlinked, hardlinked, outside the active session root, or has an invalid tail;
  • private backup creation or decompressed SHA verification fails;
  • disk space is insufficient;
  • the generated app-server schema is incompatible;
  • resume, compaction lifecycle, or append-only verification fails;
  • Codex returns authentication, authorization, quota, rate-limit, interrupted, or failed status.

Do not convert these failures into manual JSONL or SQLite surgery.

Detailed reference

Read references/recovery-playbook.md when diagnosing a failure, reviewing protocol events, handling version drift, or preparing a safe handoff. Run the isolated fixture suite after changing the tool:

python3 -m py_compile "$SKILL_DIR/scripts/"*.py
python3 "$SKILL_DIR/scripts/test_codex_session_recovery.py"