Rudimar Ronsoni dec60de976 fix(codex): preserve wrapped sessions and recover state (#2160) ... ## Description Closes #2159. Codex wrappers currently launch against a disposable `CODEX_HOME`, so session state created during a wrapped run can disappear when that temporary directory is removed. This change launches Codex against its durable home, keeps proxy routing process-local, and adds recovery for retained temporary homes and pinned recovery sources. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [x] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Launch Codex against its durable `CODEX_HOME` and apply routing through process-local config overrides after the actual proxy port is resolved. - Preserve custom provider identity and reject providers that cannot be redirected safely. - Detect dangling temporary Codex homes before interactive wraps and offer recovery. - Add `headroom recover codex` with automatic discovery, repeatable `--source`, preview, confirmation, retained backups, and rollback on failure. - Search Python's temp root, `$TMPDIR`, `/tmp`, `/private/tmp`, and macOS `/private/var/folders/*/*/T` for retained `headroom-codex-home-*` directories. - Reuse `source-pinned/` copies left by interrupted or failed recovery attempts after the original temporary home has disappeared. - Report deleted temporary homes still referenced by SQLite rollout paths without treating paths pasted into prompts or errors as filesystem evidence. - Audit the durable thread index, rollout files, and history when no source remains, including indexed chat counts and history-only orphan records. - Normalize legacy localhost `headroom` providers in both SQLite thread rows and rollout `session_meta`, including retries after an earlier broken recovery, while preserving user-defined remote providers named `headroom`. - Merge compatible config, JSONL, rollout, SQLite, credential, and regular-file state without propagating deletions or runtime artifacts. - Rewrite recovered thread rollout paths to the durable home and restore legacy Headroom thread providers to the active provider. - Validate SQLite schemas, SQLx migration checksums, integrity, and foreign keys, and quarantine malformed JSONL. - Preserve failed targets with an atomic rename before rollback, avoiding recursive-deletion races with live SQLite runtime files. - Document discovery, migration, retained backups, rollback behavior, and the limits of deleted-source recovery. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check`) - [x] Type checking passes (`mypy`) - [x] New tests added for new functionality - [x] Manual testing performed in isolated Docker containers ### Test Output ```text $ uv run pytest tests/test_cli/test_wrap_codex.py tests/test_cli/test_recover_codex.py -q 122 passed $ uv run ruff check headroom/cli/recover.py headroom/providers/codex/recovery.py tests/test_cli/test_recover_codex.py All checks passed! $ uv run ruff format --check headroom/cli/recover.py headroom/providers/codex/recovery.py tests/test_cli/test_recover_codex.py 3 files already formatted $ uv run mypy headroom/cli/recover.py headroom/providers/codex/recovery.py Success: no issues found in 2 source files ``` All validation ran in `ghcr.io/astral-sh/uv:python3.12-bookworm` against a writable disposable copy of a read-only source mount. Codex was not installed or launched, and no real user Codex state was read or modified. The tests cover multi-root discovery, deleted-reference reporting, retained pinned-source recovery, durable SQLite path relocation, SQLite and rollout provider normalization, idempotent repair after an earlier broken recovery, remote provider preservation, unrelated dangling target rows, backup retention, atomic rollback, malformed-state quarantine, SQLite validation, and Windows-safe handle closure. The repository shim E2E was not launched locally because this recovery work intentionally avoids launching Codex. Upstream CI exercises wrapper E2E in isolated environments. ## Real Behavior Proof - Environment: `ghcr.io/astral-sh/uv:python3.12-bookworm`, Python 3.12, a writable disposable checkout copied from a read-only source mount, at head `2d89ecec`. - Exact command / steps: Run `pytest -q tests/test_cli/test_wrap_codex.py tests/test_cli/test_recover_codex.py`, then run `ruff check` and `ruff format --check` against `headroom/cli/wrap.py`, `headroom/cli/recover.py`, `headroom/providers/codex/recovery.py`, `tests/test_cli/test_wrap_codex.py`, and `tests/test_cli/test_recover_codex.py`. - Observed result: `122 passed in 10.08s`; Ruff reported `All checks passed!` and `5 files already formatted`. - Not tested: Launching a real Codex process or modifying a real user `CODEX_HOME`; these were intentionally excluded to protect live user state. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code where the behavior is hard to understand - [x] I have made corresponding documentation changes - [x] My changes generate no new warnings - [x] I have added tests that prove the fix is effective - [x] New and existing focused unit tests pass with my changes - [x] I have updated `CHANGELOG.md` if applicable ## Additional Notes The temporary-home behavior was introduced by #1507 in `ad9d086f43`. Related context: #730, #731, #961, #1034, #1050, #1349, #1853, #1889, #2103, and #2104. A temporary home that macOS or `TemporaryDirectory` already deleted cannot be reconstructed unless a retained `source-pinned/` copy exists. Recovery identifies genuine dangling SQLite paths, audits surviving durable history, and recovers any retained pinned source it can find. Prompt text without a rollout cannot reconstruct a full transcript. The unchecked changelog item is not applicable because this repository does not require a changelog entry for this fix. --------- Co-authored-by: JerrettDavis <mxjerrett@gmail.com>		2026-07-15 19:58:21 +00:00
..
_lib	test(init): extend Docker e2e with bare/shim/per-subcommand cases	2026-04-23 16:12:27 -05:00
init	fix(mcp): register managed installs with a resolvable headroom command (#1386)	2026-06-26 23:39:00 -05:00
wrap	fix(codex): preserve wrapped sessions and recover state (#2160)	2026-07-15 19:58:21 +00:00
__init__.py	test(init): extend Docker e2e with bare/shim/per-subcommand cases	2026-04-23 16:12:27 -05:00
docker-native-install.sh	test(e2e): assert HEADROOM_WORKSPACE_DIR / HEADROOM_CONFIG_DIR reach container at runtime	2026-04-16 19:59:56 -05:00