# Codex compatibility

Production builds use an installed official Codex CLI or an administrator-pinned release artifact. They do not depend on upstream `main`, private Codex Rust types, or provider wire types in the domain layer.

## Runtime transport

The default worker transport is `codex exec --json`, with prompt content delivered on stdin. Request construction includes only capabilities discovered by the non-inference probe; unsupported model, effort, schema, resume, or sandbox options are omitted or fail closed.

`codex-compat` also contains stable App Server message builders/parsers and capability/schema probes. The provider runtime can drive the App Server stdio lifecycle when an explicit adapter policy selects it. A protocol failure may fall back once to a capability-verified exec invocation only before the App Server has crossed a mutating turn boundary; otherwise it fails closed. The CLI retains the documented exec-first priority. `codex_app_server_adapter` and `codex_exec_fallback` are independent runtime gates, and disabling both leaves Codex with no executable transport.

## Capability and event contracts

The probe allowlist contains only `--version`, public `--help` surfaces, and `app-server generate-json-schema`. It never submits a prompt. Version selection order is exact fixture, tested compatible range (none currently registered), generic untested adapter, then safe mode.

Unknown optional item/event payloads are retained as opaque values. Unknown `thread.*` or `turn.*` lifecycle events, missing/changed required fields, and malformed JSON fail closed. Quota errors are normalized without treating a transient rate limit as confirmed quota exhaustion.

## Supported Codex releases

Exact fixture-backed compatibility is limited to Codex `0.144.6` and `0.144.5`; `0.144.6` is the recommended release. The committed registry pins the recommended release to revision `5d1fbf26c43abc65a203928b2e31561cb039e06d`. The version registry and generated matrix are the authoritative records: [`compatibility/codex-version.toml`](../compatibility/codex-version.toml) and [`compatibility/codex-matrix.json`](../compatibility/codex-matrix.json). A numerically nearby or otherwise unknown version is not treated as exact compatibility.

Contract tests require the committed machine-readable matrix to match the version registry and every per-version manifest. The two exact-version fixtures cover capability output, successful/tool/error/quota/resume streams, malformed JSON, unknown optional items, and an unknown lifecycle event. A third version is added only after a real release has fixture evidence and an explicit maintenance decision.

## Fixture provenance

Version/help output and stable generated schemas can be captured without inference. JSONL turn fixtures are curated, redacted contract samples and are never generated by CI through a real model turn. Adding support for a release requires human review of fixture provenance and an updated manifest/matrix; a passing help probe alone never enables writable work.

## Upstream tracking CI

Daily stable-release and weekly exact-main workflows build the selected upstream source without provider credentials. They capture only allowlisted metadata, compare help options/schema fingerprints with the recommended fixture, run compatibility/migration/fake-provider tests, and upload JSON/Markdown reports. Each report lists existing support, the candidate revision, command/option changes, JSONL review status, App Server schema status, broken contracts, adapter/migration assessment, risk, and recommended action.

Optional publishing creates a draft compatibility PR. Nothing is auto-merged. Upstream-main results never change the production pin.