Metadata-Version: 2.4
Name: agent-session-rescue
Version: 0.1.0
Summary: Offline integrity checks and non-destructive recovery bundles for Codex rollout JSONL
Author: Agent Session Rescue
License-Expression: LicenseRef-Proprietary
Project-URL: Source, https://github.com/haozhn/agent-session-rescue
Project-URL: Issues, https://github.com/haozhn/agent-session-rescue/issues
Keywords: codex,jsonl,session,recovery,diagnostics,offline
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# 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.

```sh
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.

```sh
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:

```sh
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](docs/findings.md). The recovery bundle and data-loss contract is in [docs/repair-contract.md](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](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

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