CLI: add checkpointed continuation at context boundaries

What variant of Codex are you using?

Codex CLI. Proposed native scope: Linux, macOS, and Windows, including native Windows. The user interface is the terminal. Shared runtime changes should preserve other clients' current behavior.

What feature would you like to see?

Add checkpointed continuation: an opt-in native context strategy that starts a fresh model-facing context from a durable execution checkpoint while retaining the visible thread and its recoverable history.

Codex has changed how I work. I built CompactVeteran to preserve the current objective, execution cursor, and next action when a context window ends. I am contributing the behavior and reference implementation for integration into the CLI binary.

The essential rule is simple: a pending request remains pending across the boundary; a handled request stays handled. The next context should continue the current work.

Reference implementation

At commit db6adf35a95dd0a8663304fb2bad005829648fbf, CompactVeteran records the latest user objective, last assistant result, pending/completed markers, Git state, and transcript recovery pointers. Its handoff capsule is capped at 16 KiB. Objective and cursor text have separate clipping limits, with pointers to retained source material. See the state model and capsule writer.

The prototype checkpoints local Git changes, intercepts pre-compaction, and starts another Codex process with the capsule. Its system fixture exercises both a completed objective and a new request that remains pending at the next boundary. The native version should own this transition inside the existing CLI runtime.

Proposed native contract

Durable ownership. Persist a versioned checkpoint keyed by thread, context generation, and individual user-input IDs. Include the objective, current execution boundary, explicit unresolved action, request handling state, workspace reference, and links to supporting events. A turn can contain multiple steered inputs; turn ID alone must not mark all of them handled.

Safe transition. Commit the checkpoint before switching model-facing context. Keep the visible thread, effective model/provider settings, permissions, current instructions, attachments, queued input, and recoverable transcript. Transition at a tool-safe boundary. Retain durable handles for work that is still running.

Fresh context. Assemble the next context from current instructions and bounded checkpoint data. Recover source material for a specific ambiguity. Keep checkpoint data separate from instruction authority. This strategy should have an explicit integration path alongside the existing local, remote, remote-v2, and token-budget compaction paths.

Execution truth. Store runtime outcomes separately from assistant claims. A terminal turn can still leave unresolved work. Admit each input once within the continuation state machine. After a crash, reconcile uncertain external effects before retrying them; request deduplication alone cannot guarantee exactly-once external operations.

Workspace checkpoints. Preserve the prototype's local recovery goal. Make file snapshots an explicit policy with clear scope and retention. Preserve the user's Git index, branch, and untracked-file choices. A metadata checkpoint should also work in a non-Git directory. Existing sandbox and approval rules remain authoritative.

Bounded recovery. Budget checkpoint data by encoded bytes and tokens. Record truncation explicitly and retain source references. Keep transcript hashing or scans off the interactive hot path. Retention and deletion should follow the owning thread's lifecycle.

Source integration points

The compaction task dispatcher selects multiple implementations. The local compaction code distinguishes standalone and mid-turn context injection. The shared Session::replace_compacted_history boundary and thread-store replay are candidate integration points for durable state and recovery.

These are proposed ownership points. Provider-specific context ordering and compatibility still require native integration tests. The prototype's process supervision, model-specific overrides, and installation paths should become platform-neutral runtime behavior.

Acceptance criteria

1. A handled request remains historical after repeated boundaries. A newly accepted request remains actionable. Two steered inputs in one turn retain separate handling state.
2. Recovery preserves current permissions, input attachments, workspace identity, and queued messages. Concurrent threads in one repository retain separate checkpoints.
3. Faults before and after checkpoint persistence produce a recoverable state. Tool calls with unknown outcomes enter reconciliation.
4. Manual and automatic boundaries work across all supported CLI platforms. Legacy histories remain readable.
5. Local recovery works with a dirty worktree, detached HEAD, and non-Git directories under the selected snapshot policy.
6. Record checkpoint cost, recovery latency, repeated-tool count, and task completion quality in controlled comparisons.

Verification already completed

The pinned prototype's fixture-based system proof was run on Linux with Rust 1.96.0:

bash scripts/prove-system.sh

Result: CompactVeteran system proof: PASS, exit status 0.

The fixture covers local checkpoint persistence, pending/completed handoff state, transcript recovery pointers, manual and automatic boundaries, offline-remote behavior, and installation recovery. It uses a simulated stock Codex process. Live-model continuation quality and native Windows/macOS behavior remain evaluation work.

Additional information

Related reports include #29356 on operational continuity and #30859 on handled steering instructions. Those reports describe Desktop symptoms. This proposal scopes a native CLI continuation strategy and brings an executable reference fixture.

Requested maintainer decision: accept the checkpointed-continuation direction and identify the runtime owner for a staged implementation. A first stage can establish durable request ownership and recovery tests; a second can enable deterministic fresh-context continuation.

Reference proof entry point: scripts/prove-system.sh. This proposal follows the current issue-based contribution route.

Start by reading codex-rs/core/src/tasks/compact.rs, codex-rs/core/src/compact.rs, and Session::replace_compacted_history in codex-rs/core/src/session/mod.rs. Run the referenced scripts/prove-system.sh fixture to understand the existing checkpoint behavior before reviewing thread-store replay and native integration tests. Done means staged continuation preserves per-input handling state, recovery data, permissions, queued input, and workspace state across supported boundaries without breaking legacy histories.