Codex session import

Codex session import

AIWG can import Codex App Server thread snapshots and, as a fallback, local rollout JSONL into the normalized session catalog. The adapter was characterized on 2026-07-27 against the schemas generated by `codex-cli 0.145.0`.

Evidence and acquisition order

The preferred acquisition surface is Codex App Server v2. Its `thread/list` method provides cursor-based listing, filters, timestamps, runtime status, and thread metadata. `thread/read` with `includeTurns: true` supplies stored turns and items without resuming the thread. The same protocol documents fork, status-change, compaction, archive, unarchive, and hard-delete operations and notifications.

AIWG consumes an explicitly captured JSONL sequence of those App Server responses and notifications. It does not start an App Server, mutate a thread, or invoke archive/delete while importing. Capture tooling should request every `thread/list` page and then `thread/read` each selected thread with turns included. Opaque pagination cursors are evidence of traversal state, not stable thread identifiers.

When App Server acquisition is unavailable, the adapter can read explicitly authorized rollout files below a Codex sessions root. The App Server documentation identifies these persisted rollouts as JSONL files and describes archive as moving them to the archived-sessions directory.

Preserved evidence

For App Server sources, the adapter preserves:

  • native thread and session-tree identifiers;
  • parent and fork-source thread identifiers;
  • runtime status and status-change evidence;
  • turns, item identifiers, compaction summaries, archive, unarchive, and

deletion notifications;

  • CLI/product version and model provider;
  • workspace and Git branch/commit metadata with raw paths and repository URLs

reduced to privacy-safe classes;

  • unknown fields as opaque provider extensions;
  • pagination completion evidence and source-method provenance.

For rollout fallback, `session_meta`, `turn_context`, `event_msg`, `response_item`, and `compacted` records are recognized. Unknown record types remain opaque. Only complete JSONL records are consumed; a truncated final record is ignored until a later import completes it.

Declared unknown major schema versions, malformed records, thread identity drift, symbolic-link traversal, and paths outside explicitly authorized roots fail before any catalog write.

Consistency and replay

An App Server capture containing an active thread is provisional. Rollout files are also provisional because Codex may append to them. Stable native item IDs, source ordering, and import checkpoints make an identical replay a no-op while allowing newly completed records to be appended on a later import.

App Server is the semantic authority when available. The rollout parser is version-tolerant fallback evidence and does not claim every internal record shape is a public compatibility contract.

Retention, archive, and deletion boundaries

Codex documents `thread/archive` as moving persisted rollout files into the archived sessions directory. It documents `thread/delete` as hard-deleting the selected active or archived thread and spawned descendants, requiring rollout files and associated metadata to be removed before success.

AIWG import never performs those provider mutations. `aiwg sessions delete` tombstones catalog data only and does not change Codex state.

Codex can maintain lightweight thread metadata or indexes separately from rollout payloads. An entry in a SQLite state database, a session index, or command/prompt history is not proof that canonical rollout content exists; an index limit is likewise not a rollout-retention guarantee. Conversely, deleting an index entry alone does not prove that rollout, archived rollout, backup, synchronized, exported, or remote copies were deleted. A purge procedure must enumerate and verify each storage system in scope.

Known limitations

  • Live App Server calls are intentionally outside this read-only adapter; the

adapter imports an authorized capture produced by a protocol client.

  • Ephemeral threads may never have rollout files, so App Server evidence can be

the only available source.

  • App Server and rollout internals evolve. Unknown minor fields are retained;

an explicitly declared unknown major schema fails closed.

  • Full content is subject to catalog redaction policy. Opaque provider

extensions must receive the same access controls as transcript data.

  • Discovery never scans `CODEX_HOME` or a home directory implicitly.