@sidshaytay/heal-codex-session0.1.3
Bounded automatic recovery from rejected Codex encrypted reasoning.
Untested on omp
This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.
Reports 0
No reports yet.
Readme
heal-codex-session
Automatically recover from Codex encrypted-reasoning verification errors without rewriting the original session or replaying completed tools.
Quick start
Requires pi 1.2.x and Node.js 22.19 or later. The declared peer range excludes pi 1.3 and later. The production adapter is tested on pi 1.2.0 with synthetic providers and real CLI sessions.
pi install npm:@sidshaytay/heal-codex-session
Start pi, or run /reload in an existing session to load it. No settings are required. When a matching error occurs, recovery notifications show quarantine, compaction when needed, and continuation.
To install from this repository's root instead:
pi install ./packages/heal-codex-session
Update or remove
Run pi update --extensions to update unpinned installations, then /reload when recovery is idle. To stop loading this extension:
pi remove npm:@sidshaytay/heal-codex-session
Run /reload afterward. Existing recovery records and context edits remain in saved sessions; removing the extension does not undo them.
Understand automatic recovery
Only finalized assistant errors from the openai-codex-responses API trigger recovery. Compatible provider aliases work; user messages and tool output cannot trigger it.
| Context usage before failure | Automatic recovery |
|---|---|
| Below 60% | Quarantine the exact rejected reasoning block; continue once. |
| 60% or above, or unknown | Quarantine, wait for sanitized compaction, then continue once. |
| Repair, compaction, or resumed request fails | Start one fresh session with a sanitized handoff. |
Append-only, branch-local context edits remove the offending block from effective input. Other reasoning, visible text, and tool calls stay intact. Empty failed assistant responses are omitted from effective input so Pi can continue. Source JSONL entries are never rewritten. Normal requests and Pi's built-in compaction both use the edited projection.
The fresh session links to its source and receives bounded user requirements, existing summaries, visible history, and tool evidence. Handoff generation is deterministic so recovery does not require another successful summary request. Omitted middle history is marked explicitly. Images are not transferred; their source is identified. Model and thinking settings are recorded in the replacement session.
When a subagent cannot recover
When this extension is loaded in the parent, failed subagent/bg_wait results receive a recovery suggestion. Its separate completion-event integration was verified against pi-subagents 0.76.1; compatibility with later event formats has not been established. Matching events show a separate notice. The original error and structured result remain unchanged. The notice uses only an actual run ID and saved-conversation path when supplied; missing identifiers are omitted. It does not start a replacement or trigger a model request.
This works without loading the healer inside the failed child. It does not add automatic child replacement or modify pi-subagents. Child recovery itself still requires the healer to be loaded inside that child.
Rescue a conversation that failed before installation
If it has working subagents, leave its Pi process open. Restarting or reloading it can stop in-process children.
Open another terminal in the same project and run:
pi --fork "SESSION_ID"
Replace SESSION_ID with the saved conversation's ID from pi's session picker (/resume).
The fork loads the installed healer and leaves the source conversation untouched. Ask it to review the saved progress and continue without duplicating completed work or restarting running subagents. If the old rejected reasoning is still present, the next matching failed request triggers healing. A fork does not transfer ownership of the old process's subagents; collect their results there. Do not open the same live session file in two processes with --session.
Stop recovery and understand its limits
- User aborts, pending input, session switches, and competing boundary continuations take priority. Recovery does not drain or reorder queued input.
- Reload stops an unfinished recovery rather than silently repeating a request or side effect. Submit the pending work again to resume.
- A destination failure stops the chain. Completed tools are not executed by this extension; new model-requested tools still pass Pi's ordinary hooks.
- Jobs, subagents, extension state, and permissions do not migrate. The handoff tells the agent to verify and reattach rather than restart them.
- Quarantine can increase reasoning work. Compaction and continuation use provider tokens. Cache hits are not guaranteed.
Troubleshooting
Recovery notifications identify the phase without printing encrypted blobs or prompts. In print/JSON mode, provider failures and persisted recovery records remain available even when notifications have no UI.
CLI print/JSON replacement and compaction have runtime tests. TUI/RPC use the same replacement API but are not end-to-end tested. Bare SDK hosts must bind session-replacement commands. If replacement throws or the host never calls the fresh-session callback, the extension reports a private temporary handoff.md path; it never spawns another Pi process.
Pi's boundary continuation and pending-message APIs prevent competing attempts at those boundaries. Compatibility with independent recovery extensions that schedule private timers or account changes is not guaranteed; disable their overlapping recovery behavior. Custom compaction extensions must use the effective preparation messages, not raw branch entries.
No live Codex request or account change was used for verification. Transport tests exercise Pi 1.2.0's actual WebSocket continuation functions: editing the prefix clears cached continuation and sends full input. This is not a live server/cache-reuse test.