codex-rescue 0.1.0a1__tar.gz

codex_rescue-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to Codex Rescue will be documented in this file.
+
+## v0.1.0-alpha
+
+Initial experimental alpha release.
+
+### Included
+
+- Recent Codex session discovery (`sessions` command)
+- Interrupted and damaged session diagnosis (`doctor` command)
+- Immutable evidence-backed recovery salvage (`salvage` command)
+- Git repository state verification (`verify` command)
+- Confidence-labeled recovery handoff (VERIFIED / RECONSTRUCTED / UNKNOWN)
+- Sanitized synthetic regression corpus (5 fixture types)
+- Sanitized real-origin regression corpus (3 cases)
+- Crash-safe append-only journal
+- Bounded recovery brief generation
+- Secret redaction in handoff artifacts
+
+### Known limitations
+
+- Broad real compaction recovery not yet validated
+- Interactive continuation depends on terminal/TTY environment
+- Previous Codex version recovery coverage is limited
+- Not every arbitrary corruption type is supported

codex_rescue-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shleder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codex_rescue-0.1.0a1/MANIFEST.in

@@ -0,0 +1,21 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include pyproject.toml
+
+prune fixtures
+prune real-corpus
+prune tests
+prune .github
+prune .validation-output
+prune .pypi-release-venv
+prune .release-venv
+prune .validation-baseline
+prune .validation-runtime
+prune .cli-smoke
+prune .codex-rescue-poc
+prune .codex-rescue-final
+prune .codex-rescue-final-3
+prune .review-output
+
+global-exclude *.pyc *.pyo __pycache__

codex_rescue-0.1.0a1/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: codex-rescue
+Version: 0.1.0a1
+Summary: Local-first recovery tool for interrupted and damaged OpenAI Codex sessions
+Author: shleder
+License: MIT
+Project-URL: Homepage, https://github.com/shleder/codex-rescue
+Project-URL: Repository, https://github.com/shleder/codex-rescue
+Project-URL: Issues, https://github.com/shleder/codex-rescue/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: System :: Recovery Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<p align="center">
+  <a href="https://github.com/shleder/codex-rescue/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/shleder/codex-rescue/ci.yml?branch=main&style=flat-square&label=CI&logo=github" alt="CI Status"></a>
+  <a href="https://github.com/shleder/codex-rescue/releases/tag/v0.1.0-alpha"><img src="https://img.shields.io/badge/version-v0.1.0--alpha-3fb950?style=flat-square" alt="Version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License"></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-1f6feb?style=flat-square&logo=python&logoColor=white" alt="Python"></a>
+  <a href="#privacy"><img src="https://img.shields.io/badge/privacy-100%25%20local--first-238636?style=flat-square" alt="Privacy"></a>
+</p>
+
+---
+
+## Overview
+
+When **OpenAI Codex CLI** can't resume safely, **Rescue** tells you what actually happened and gets you back to work.
+
+Codex Rescue is a local-first fsck and crash-recovery tool for OpenAI Codex sessions. It diagnoses interrupted or damaged sessions, verifies repository working tree state, and reconstructs a bounded evidence-backed continuation **without modifying the original Codex rollout**.
+
+> [!WARNING]
+> **Codex Rescue is experimental alpha software.**
+> It is an evidence-gathering release designed to collect real failure cases.
+> See [Alpha Limitations](#alpha-limitations) below.
+
+---
+
+## Core Commands
+
+Rescue provides four narrow, read-only diagnostic and recovery entry points:
+
+| Command | Usage | Description |
+|---|---|---|
+| **`sessions`** | `codex-rescue sessions` | Discover and list recent local Codex rollout sessions |
+| **`doctor`** | `codex-rescue doctor --latest` | Inspect and diagnose a damaged session (**read-only**) |
+| **`salvage`** | `codex-rescue salvage --latest --fork` | Create an immutable, content-addressed recovery handoff |
+| **`verify`** | `codex-rescue verify <rescue-id>` | Detect repository divergence before executing continuation |
+
+---
+
+## Confidence Model
+
+Rescue reconstructs facts with explicit, uncompromised confidence levels. Model prose alone is **never** accepted as source of truth.
+
+| Level | Badge | Meaning & Source of Truth |
+|---|---|---|
+| **VERIFIED** | `VERIFIED` | Directly proven by durable evidence: Git HEAD SHA, working tree diff, tool execution exit code, or durable output record |
+| **RECONSTRUCTED** | `RECONSTRUCTED` | Strongly inferred from available evidence with no unresolved contradictions |
+| **UNKNOWN** | `UNKNOWN` | Cannot be proven safely. **UNKNOWN is deliberate.** Rescue refuses to guess when execution state is uncertain |
+
+> [!NOTE]
+> **Safety Invariants:**
+> 1. Source rollouts are **immutable** (`doctor`, `salvage`, and `verify` never write to the original `.jsonl` file).
+> 2. **No automatic replay** — an action whose execution status is `UNKNOWN` is never automatically re-executed.
+
+---
+
+## Quick Start
+
+### 1. Installation
+
+Install directly from the GitHub release tag:
+
+```bash
+# Recommended global installation via pipx
+pipx install git+https://github.com/shleder/codex-rescue.git@v0.1.0-alpha
+
+# Or via standard pip
+pip install git+https://github.com/shleder/codex-rescue.git@v0.1.0-alpha
+```
+
+### 2. Workflow Example
+
+```bash
+# 1. Discover recent Codex sessions
+codex-rescue sessions
+
+# 2. Diagnose the latest session
+codex-rescue doctor --latest
+
+# 3. Generate an immutable recovery handoff
+codex-rescue salvage --latest --fork
+
+# 4. Verify repository state before continuing
+codex-rescue verify <rescue-id>
+```
+
+### Sample Output
+
+```text
+$ codex-rescue doctor --latest
+
+Doctor: UNFINISHED_TOOL_CALL
+Findings: UNFINISHED_TOOL_CALL
+Repository: /path/to/repo (HEAD a6cfe48)
+
+$ codex-rescue salvage --latest --fork
+
+Salvage: 8f8f4e822c9ce353ed584c5f
+Original session untouched: yes
+Rescue directory: .codex-rescue/rescues/8f8f4e822c9ce353ed584c5f
+
+$ codex-rescue verify 8f8f4e822c9ce353ed584c5f
+
+Verify: REVIEW_REQUIRED
+Review: unfinished action requires inspection before replay
+Review: handoff contains load-bearing unknowns
+```
+
+---
+
+## Proven Compatibility & Evidence
+
+| Version / Scope | Status | Proven Real-World Evidence |
+|---|---|---|
+| **Codex CLI 0.147.0** | **Validated** | Genuine interrupted session diagnosed (`UNFINISHED_TOOL_CALL`), source rollout preserved, repo state verified |
+| **Codex CLI 0.146.1** | **Smoke-tested** | Isolated authentication & basic rollout parser validation |
+| **Codex 0.145.0-alpha.18** | **Observed** | Legacy envelope format compatibility observed |
+| **Synthetic Fixtures** | **5/5 PASS** | `kill_apply_patch`, `kill_shell_before_result`, `lost_tail_after_compaction`, `malformed_jsonl`, `oversized_payload` |
+
+---
+
+## Alpha Limitations
+
+> [!IMPORTANT]
+> The following limitations are documented honestly. Do not claim recovery guarantees that have not been validated.
+
+- **Compaction recovery** — broad real compaction-related recovery is not yet validated; only synthetic fixtures exist.
+- **Interactive continuation** — automatic fresh continuation depends on terminal/TTY environment (Windows ConPTY limitations noted).
+- **Previous versions** — validation is focused on Codex CLI 0.147.0; earlier versions are smoke-tested or observed.
+- **Side-effect replay** — Rescue does not automatically replay unknown side effects; it reports them as `REVIEW_REQUIRED`.
+
+---
+
+## Privacy & Security
+
+- **100% Local-First** — zero telemetry, zero analytics, zero network uploads, zero cloud dependencies.
+- **No private DB mutation** — Rescue never modifies `state_*.sqlite` or internal Codex databases.
+- **Secret Redaction** — built-in secret redaction automatically filters common API key patterns (`sk-*`, `ghp_*`, `AKIA*`, Bearer tokens).
+- **Sanitization Notice** — Codex rollouts can contain secrets; sanitize all session files before attaching to public issues.
+
+---
+
+## Development & Verification
+
+```bash
+# Clone the repository
+git clone https://github.com/shleder/codex-rescue.git
+cd codex-rescue
+
+# Install in editable mode
+pip install -e .
+
+# Run full unit test suite (43 passed, 1 skipped)
+python -m unittest discover -s tests -v
+
+# Run synthetic fixture harness (5/5 PASS)
+python -m codex_rescue.harness fixtures --output .validation-output/test
+
+# Run deterministic alpha demo
+python scripts/demo_alpha.py
+```
+
+---
+
+## Submit a Recovery Report
+
+The primary goal of this public alpha is collecting real broken Codex sessions to expand our sanitized regression corpus.
+
+[**Open a Recovery Report →**](https://github.com/shleder/codex-rescue/issues/new?template=recovery-report.yml)
+
+> [!CAUTION]
+> **Do NOT upload raw rollout files containing secrets or credentials.** Always sanitize session data before attaching.
+
+---
+
+## License
+
+Distributed under the [MIT License](LICENSE). Copyright (c) 2026 shleder.

codex_rescue-0.1.0a1/README.md

@@ -0,0 +1,175 @@
+<p align="center">
+  <a href="https://github.com/shleder/codex-rescue/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/shleder/codex-rescue/ci.yml?branch=main&style=flat-square&label=CI&logo=github" alt="CI Status"></a>
+  <a href="https://github.com/shleder/codex-rescue/releases/tag/v0.1.0-alpha"><img src="https://img.shields.io/badge/version-v0.1.0--alpha-3fb950?style=flat-square" alt="Version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License"></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-1f6feb?style=flat-square&logo=python&logoColor=white" alt="Python"></a>
+  <a href="#privacy"><img src="https://img.shields.io/badge/privacy-100%25%20local--first-238636?style=flat-square" alt="Privacy"></a>
+</p>
+
+---
+
+## Overview
+
+When **OpenAI Codex CLI** can't resume safely, **Rescue** tells you what actually happened and gets you back to work.
+
+Codex Rescue is a local-first fsck and crash-recovery tool for OpenAI Codex sessions. It diagnoses interrupted or damaged sessions, verifies repository working tree state, and reconstructs a bounded evidence-backed continuation **without modifying the original Codex rollout**.
+
+> [!WARNING]
+> **Codex Rescue is experimental alpha software.**
+> It is an evidence-gathering release designed to collect real failure cases.
+> See [Alpha Limitations](#alpha-limitations) below.
+
+---
+
+## Core Commands
+
+Rescue provides four narrow, read-only diagnostic and recovery entry points:
+
+| Command | Usage | Description |
+|---|---|---|
+| **`sessions`** | `codex-rescue sessions` | Discover and list recent local Codex rollout sessions |
+| **`doctor`** | `codex-rescue doctor --latest` | Inspect and diagnose a damaged session (**read-only**) |
+| **`salvage`** | `codex-rescue salvage --latest --fork` | Create an immutable, content-addressed recovery handoff |
+| **`verify`** | `codex-rescue verify <rescue-id>` | Detect repository divergence before executing continuation |
+
+---
+
+## Confidence Model
+
+Rescue reconstructs facts with explicit, uncompromised confidence levels. Model prose alone is **never** accepted as source of truth.
+
+| Level | Badge | Meaning & Source of Truth |
+|---|---|---|
+| **VERIFIED** | `VERIFIED` | Directly proven by durable evidence: Git HEAD SHA, working tree diff, tool execution exit code, or durable output record |
+| **RECONSTRUCTED** | `RECONSTRUCTED` | Strongly inferred from available evidence with no unresolved contradictions |
+| **UNKNOWN** | `UNKNOWN` | Cannot be proven safely. **UNKNOWN is deliberate.** Rescue refuses to guess when execution state is uncertain |
+
+> [!NOTE]
+> **Safety Invariants:**
+> 1. Source rollouts are **immutable** (`doctor`, `salvage`, and `verify` never write to the original `.jsonl` file).
+> 2. **No automatic replay** — an action whose execution status is `UNKNOWN` is never automatically re-executed.
+
+---
+
+## Quick Start
+
+### 1. Installation
+
+Install directly from the GitHub release tag:
+
+```bash
+# Recommended global installation via pipx
+pipx install git+https://github.com/shleder/codex-rescue.git@v0.1.0-alpha
+
+# Or via standard pip
+pip install git+https://github.com/shleder/codex-rescue.git@v0.1.0-alpha
+```
+
+### 2. Workflow Example
+
+```bash
+# 1. Discover recent Codex sessions
+codex-rescue sessions
+
+# 2. Diagnose the latest session
+codex-rescue doctor --latest
+
+# 3. Generate an immutable recovery handoff
+codex-rescue salvage --latest --fork
+
+# 4. Verify repository state before continuing
+codex-rescue verify <rescue-id>
+```
+
+### Sample Output
+
+```text
+$ codex-rescue doctor --latest
+
+Doctor: UNFINISHED_TOOL_CALL
+Findings: UNFINISHED_TOOL_CALL
+Repository: /path/to/repo (HEAD a6cfe48)
+
+$ codex-rescue salvage --latest --fork
+
+Salvage: 8f8f4e822c9ce353ed584c5f
+Original session untouched: yes
+Rescue directory: .codex-rescue/rescues/8f8f4e822c9ce353ed584c5f
+
+$ codex-rescue verify 8f8f4e822c9ce353ed584c5f
+
+Verify: REVIEW_REQUIRED
+Review: unfinished action requires inspection before replay
+Review: handoff contains load-bearing unknowns
+```
+
+---
+
+## Proven Compatibility & Evidence
+
+| Version / Scope | Status | Proven Real-World Evidence |
+|---|---|---|
+| **Codex CLI 0.147.0** | **Validated** | Genuine interrupted session diagnosed (`UNFINISHED_TOOL_CALL`), source rollout preserved, repo state verified |
+| **Codex CLI 0.146.1** | **Smoke-tested** | Isolated authentication & basic rollout parser validation |
+| **Codex 0.145.0-alpha.18** | **Observed** | Legacy envelope format compatibility observed |
+| **Synthetic Fixtures** | **5/5 PASS** | `kill_apply_patch`, `kill_shell_before_result`, `lost_tail_after_compaction`, `malformed_jsonl`, `oversized_payload` |
+
+---
+
+## Alpha Limitations
+
+> [!IMPORTANT]
+> The following limitations are documented honestly. Do not claim recovery guarantees that have not been validated.
+
+- **Compaction recovery** — broad real compaction-related recovery is not yet validated; only synthetic fixtures exist.
+- **Interactive continuation** — automatic fresh continuation depends on terminal/TTY environment (Windows ConPTY limitations noted).
+- **Previous versions** — validation is focused on Codex CLI 0.147.0; earlier versions are smoke-tested or observed.
+- **Side-effect replay** — Rescue does not automatically replay unknown side effects; it reports them as `REVIEW_REQUIRED`.
+
+---
+
+## Privacy & Security
+
+- **100% Local-First** — zero telemetry, zero analytics, zero network uploads, zero cloud dependencies.
+- **No private DB mutation** — Rescue never modifies `state_*.sqlite` or internal Codex databases.
+- **Secret Redaction** — built-in secret redaction automatically filters common API key patterns (`sk-*`, `ghp_*`, `AKIA*`, Bearer tokens).
+- **Sanitization Notice** — Codex rollouts can contain secrets; sanitize all session files before attaching to public issues.
+
+---
+
+## Development & Verification
+
+```bash
+# Clone the repository
+git clone https://github.com/shleder/codex-rescue.git
+cd codex-rescue
+
+# Install in editable mode
+pip install -e .
+
+# Run full unit test suite (43 passed, 1 skipped)
+python -m unittest discover -s tests -v
+
+# Run synthetic fixture harness (5/5 PASS)
+python -m codex_rescue.harness fixtures --output .validation-output/test
+
+# Run deterministic alpha demo
+python scripts/demo_alpha.py
+```
+
+---
+
+## Submit a Recovery Report
+
+The primary goal of this public alpha is collecting real broken Codex sessions to expand our sanitized regression corpus.
+
+[**Open a Recovery Report →**](https://github.com/shleder/codex-rescue/issues/new?template=recovery-report.yml)
+
+> [!CAUTION]
+> **Do NOT upload raw rollout files containing secrets or credentials.** Always sanitize session data before attaching.
+
+---
+
+## License
+
+Distributed under the [MIT License](LICENSE). Copyright (c) 2026 shleder.

codex_rescue-0.1.0a1/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "codex-rescue"
+dynamic = ["version"]
+description = "Local-first recovery tool for interrupted and damaged OpenAI Codex sessions"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.11"
+dependencies = []
+authors = [
+    {name = "shleder"},
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: System :: Recovery Tools",
+]
+
+[project.urls]
+Homepage = "https://github.com/shleder/codex-rescue"
+Repository = "https://github.com/shleder/codex-rescue"
+Issues = "https://github.com/shleder/codex-rescue/issues"
+
+[project.scripts]
+codex-rescue = "codex_rescue.cli:main"
+
+[tool.setuptools.dynamic]
+version = {attr = "codex_rescue.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

codex_rescue-0.1.0a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

codex_rescue-0.1.0a1/src/codex_rescue/__init__.py

@@ -0,0 +1,3 @@
+"""Codex Rescue — local-first recovery for OpenAI Codex sessions."""
+
+__version__ = "0.1.0a1"

codex_rescue-0.1.0a1/src/codex_rescue/artifacts.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+
+def canonical_json(data: Any) -> bytes:
+    return json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+def atomic_write(path: Path, data: bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temp = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    fd = os.open(temp, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    try:
+        offset = 0
+        while offset < len(data):
+            offset += os.write(fd, data[offset:])
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+    os.replace(temp, path)
+    if os.name != "nt":
+        dir_fd = os.open(path.parent, os.O_RDONLY)
+        try:
+            os.fsync(dir_fd)
+        finally:
+            os.close(dir_fd)
+
+
+def write_rescue(root: Path, handoff: dict[str, Any], brief: str, continuation: str) -> tuple[str, Path]:
+    handoff_bytes = canonical_json(handoff)
+    rescue_id = hashlib.sha256(handoff_bytes).hexdigest()[:24]
+    rescue_dir = root / "rescues" / rescue_id
+    atomic_write(rescue_dir / "handoff.v1.json", handoff_bytes + b"\n")
+    atomic_write(rescue_dir / "RECOVERY_BRIEF.md", brief.encode("utf-8"))
+    atomic_write(rescue_dir / "CONTINUATION_PROMPT.md", continuation.encode("utf-8"))
+    return rescue_id, rescue_dir
+
+
+def load_handoff(root: Path, rescue_id: str) -> dict[str, Any]:
+    path = root / "rescues" / rescue_id / "handoff.v1.json"
+    data = json.loads(path.read_text(encoding="utf-8"))
+    actual_id = hashlib.sha256(canonical_json(data)).hexdigest()[:24]
+    if actual_id != rescue_id:
+        raise ValueError(f"handoff hash mismatch: expected {rescue_id}, actual {actual_id}")
+    return data
+