Codex Session Governor

codex-session-governor compacts large Codex JSONL rollouts without changing their thread identity. It keeps the current session resumable under the same ID, stores an exact compressed reconstruction in cold storage, and removes local staging only after identity, readback, and acceptance checks pass.

This is an independent community project. It is not an official OpenAI product and it intentionally does not modify Codex SQLite databases, task state, or provider history.

Why this exists

Long-running agent sessions can accumulate large append-only rollout files. Ordinary archiving breaks active continuity, while deleting history loses the ability to reconstruct the original source. This controller separates those concerns:

large rollout
  -> verify native compacted checkpoint and quiescence
  -> archive exact prefix + hot tail as content-addressed zstd objects
  -> CAS-replace the hot rollout with same-ID compacted state
  -> verify through the selected Codex owner readback transport
  -> accept, adopt canonical pointer, and remove bounded local staging

Safety model

• Production execution is disabled by default.
• One transaction and one session may advance at a time.
• Source identity is bound by inode, size, mtime, and SHA-256.
• Active writer locks, mutation leases, running turns, and open handles block.
• Cold objects are bound to content SHA-256, zstd binary SHA-256, and level.
• Failed post-replacement readback restores the exact original bytes.
• GC can remove only transaction staging after acceptance.
• No private Codex database writes or process signals are implemented.

The preferred readback mode is external_command: a fixed, admission-bound adapter queries the already-running Codex/Desktop owner. standalone_stdio is available only as an explicit compatibility mode for isolated or fully quiescent profiles; it is never selected by default.

Install for development

Requirements: Python 3.11+, Git, and zstd.

git clone https://github.com/nokiyliao/codex-session-governor.git
cd codex-session-governor
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/python -m unittest discover -v

Read-only/default state is stored under ${XDG_STATE_HOME:-~/.local/state}/codex-session-governor/shadow, not inside the installed package. An additional shadow write root must be declared through CODEX_SESSION_GOVERNOR_EXTRA_WRITE_ROOTS.

Shadow configuration

Start with a non-production policy and exact test paths:

codex-session-govern auto enable \
  --profile shadow \
  --allow-target /absolute/path/to/rollout.jsonl \
  --cold-store-root /absolute/path/to/cold-store \
  --cold-store-id local-test

codex-session-govern auto status

This persists policy and renders a template. It does not load a LaunchAgent or activate compaction.

Production boundary

Production activation is deliberately separate from installation:

1. Create and verify a clean release manifest.
2. Configure exact session/cold-store roots and a readback transport.
3. Publish the cold-store identity.
4. Issue an admission bound to release and policy digests.
5. Activate the single LaunchAgent.
6. Verify status and run only an admitted tick.

For an existing-owner adapter, configure a fixed argv (never a shell string):

codex-session-govern --root ~/.codex/session_auto_compaction/v1 auto configure \
  --profile ordinary_children \
  --session-root ~/.codex/sessions \
  --allow-target-root ~/.codex/sessions \
  --cold-store-root /Volumes/COLD/codex-sessions \
  --cold-store-id cold-volume-1 \
  --app-readback-transport external_command \
  --app-readback-command /absolute/path/to/readback-adapter

The adapter receives one JSON request on stdin and must return either a Codex thread object or {"thread": <thread object>} on stdout. The controller independently checks thread ID, lineage session ID, exact rollout path, and quiescent status.

See Architecture, Security, and the public-readiness review before enabling production behavior.

Scope and limitations

• The LaunchAgent installer currently targets macOS.
• App Server and rollout formats are upstream implementation surfaces and may change; unsupported shapes fail closed.
• Candidate construction is bounded to 160 MiB but is not yet streaming.
• This repository governs raw rollout compaction. It does not prune unrelated application caches or user files.

License

MIT. See LICENSE.