agent-session-rescue

Agent Session Rescue

Agent Session Rescue is an offline, non-destructive CLI for inspecting one explicitly selected Codex rollout JSONL file and creating a separate, hash-audited recovery bundle.

Version 0.1.0 is a narrow beta. It does not modify Codex files, indexes, SQLite databases, configuration, or application state, and it does not promise that every damaged thread can be made resumable.

Install

Python 3.11 or newer is required. The package has no runtime dependencies.

python3 -m pip install agent-session-rescue
session-rescue --help

To install from a source checkout instead, run python3 -m pip install . in the repository root.

Read-only scan

Choose the rollout file yourself. v0 never crawls ~/.codex or chooses a session on your behalf.

session-rescue scan /path/to/rollout.jsonl
session-rescue scan /path/to/rollout.jsonl --format json

The report includes only structural metadata: the displayed input path, SHA-256, byte and record counts, finding codes, locations, sizes, and recovery limitations. It does not echo prompts, tool output, encrypted reasoning, inline images, or environment values.

Explicit salvage

Salvage is a second, explicit command and requires a new or empty output directory:

session-rescue salvage /path/to/rollout.jsonl --output ./recovery-bundle

Depending on the findings, the bundle can contain:

• manifest.json: input/output hashes, transformations, byte counts, and loss warnings.
• report.json: the same metadata-only structural report.
• resume.md: bounded user/assistant text plus tool names/statuses; no raw tool output or binary data.
• quarantine/: exact malformed fragments that could not be parsed.
• attachments/: safely decoded oversized data payloads addressed by SHA-256.
• repaired.jsonl: only when all transformations are supported and the candidate passes the same validator.

The original input hash and byte length are checked again after salvage. The product never installs repaired.jsonl into Codex; reintegration is outside the v0 support boundary.

Records over the 8 MiB parser cap are never decoded or parsed. Salvage can stream their exact bytes into quarantine, but it will not emit a repaired copy.

Exit codes

• 0: supported file is structurally clean.
• 1: findings exist and every blocking finding has a supported salvage transformation.
• 2: only partial recovery/export is safe; no loadable repaired JSONL is promised.
• 3: invalid invocation, unreadable input, unsafe output, or unsupported schema.
• 4: unexpected internal failure; the original remains unchanged.

The stable finding catalog is in docs/findings.md. The recovery bundle and data-loss contract is in docs/repair-contract.md.

Privacy and safety

• No network access, account, cloud storage, background process, or CLI telemetry.
• Default scan performs no writes.
• salvage writes only under the explicitly selected new/empty output directory.
• The input rollout, Codex indexes, SQLite, and configuration are never modified.
• Recovery outputs can contain sensitive session text or raw fragments. Protect, review, and delete the bundle like the original session.

See SECURITY.md before using salvage on a real session.

v0 non-goals

No Claude Code/OpenClaw/Cursor/Copilot/Gemini formats, live tracing, observability dashboard, model calls, semantic replay, AI summarization, GUI, cloud sync, automatic Codex-state repair, licensing system, workflow engine, scheduler, or management UI.

Local verification

PYTHONPATH=src python3 -m unittest discover -s tests -v
python3 scripts/dry_run.py
python3 -m compileall -q src tests scripts