[Epic] Codex as a first-class structured engine (parity with Claude)

[serge-ivo]

Make Codex (and, later, other CLIs) a first-class coding engine on par with Claude: driven through its own structured event stream instead of scraped raw stdout, with the same clarity Claude already has about how it's invoked and who pays. Today Claude is the only structured engine (mode = clientType === "claude" ? "stream-json" : "raw" in headless.ts); every other engine is spawned raw, so its output is noisy/truncated, its spend is unmetered, and its acts are unattributed.

The work

Dependency chain (runner):

• [design] Structured engine adapters — parse each CLI's own JSON event stream, not a claude-or-raw switch #728 — [design] Structured engine adapters: per-engine JSON event parsing, not a claude-or-raw switch (the enabler)
• First-class Codex engine via codex exec --json (structured), not raw stdout capture #729 — Codex via codex exec --json (structured) — fixture-spike first; --json is an unverified premise + unstable with active tools
• [spike] Codex session continuity — verify resume-by-id is viable before building it #730 — [spike] Codex session continuity — verify resume-by-id is even viable before building it (upstream-risky; in tension with [design] The platform owns the conversation — an engine's own memory is an optimisation, not the source of truth #693)

Independent (UX / config clarity):

• Engine invocation mode as read-only transparency (status chip + fallback warning), not a user control #731 — Invocation mode as read-only transparency (status chip + fallback warning), not a user control
• Codex sign-in parity: expose + explain ChatGPT-subscription vs OpenAI-API-key, the way Claude already does #732 — Codex sign-in parity: ChatGPT-subscription vs OpenAI-API-key, made explicit + explained (verify the strip-key mechanic)

Downstream — consequences fixed once the chain lands (not to be worked directly):

• A Codex coding session is completely invisible — unmetered like a tmux drive, but unlike a tmux drive the absence is never recorded, and classifyEngineMetering has zero production callers #556 (Codex unmetered) — closed; its --json track lives in [design] Structured engine adapters — parse each CLI's own JSON event stream, not a claude-or-raw switch #728/First-class Codex engine via codex exec --json (structured), not raw stdout capture #729
• coding_timeline records no per-step token, cost, files-changed or test-result summary — the ordering half of this is fixed #674 (coding_timeline has no per-step tokens/cost), acts[].ok is documented in two supervision legends and absent from the payload; delegation budgets can enter 'exhausted' with no exit #594 (acts[].ok absent for raw engines), The handoff prompt a user answers is scraped from prose, because no structured field exists to prefer #621 (handoff scraped from prose) — all become tractable once raw engines emit structured usage/acts.

Cross-cutting obligations (don't let these fall through)

• docs/coding-engines.md must be updated by First-class Codex engine via codex exec --json (structured), not raw stdout capture #729/[spike] Codex session continuity — verify resume-by-id is viable before building it #730 — its "why no shipped preset resumes" and "what one-shot costs" sections go stale for Codex.
• Grok / Gemini adapters are explicitly out of scope for now (each needs its own --json-equivalent investigation) — recorded here so "Codex only" is a decision, not a forgotten gap. File a P3: later adapter issue if/when demand appears.

Open strategic question

#730 (engine-side resume) vs #693 ("platform owns the conversation" — seed continuity from coding_timeline, demote the engine's own memory). #730 is a deferred-#693 stopgap; if its spike fails, route Codex continuity through #693 instead. Resolve before scheduling #730's follow-up.

Provenance: decomposition + this framing came out of an adversarial 3-lens review (technical accuracy, scope/duplication, UX) on 2026-08-22.

[serge-ivo]

Labelled by the backlog audit, 2026-08-23 — the reasoning, so it can be argued with

Nine open issues carried no priority label. Labels applied against the vocabulary's own definitions (P0 = wrong in production right now · P1 = must be true before a non-owner can run an agent (#68) · P2 = real defect, no live harm today · P3 = design/strategy/deferred pending a decision or demand).

Issue	Priority	Why that one
#716 subscribe not idempotent	P2: correctness + mcp	It produced a real duplicate instance in production, but only inside a deploy window, and nothing was lost. Not P0 — no ongoing wrong result. Not P1 — nobody is blocked. mcp because subscribe_agent is the observed caller.
#725 Gmail fence	P2: correctness + bug backend connectors	The two high-volume tools are now fenced; what remains is find_confirmation_link, which is permission-gated. Real defect, no live harm measured.
#726 direct invoke writes no trace row	P2: correctness + bug backend observability mcp	observability by its own definition — a surface that means something other than its label (agent_trace promises "every meaningful thing an agent DOES"). Not P0: nothing computes a wrong value, a row is simply absent.
#729 Codex via codex exec --json	P2: correctness	Matches its enabler #728 (already P2). A Codex session today is unmetered (#556) and unattributed (#594) — those are real defects, and this is the work that closes them.
#731 invocation-mode transparency	P3: later	Depends on #728 + #729 for the "structured" state to exist. Today every non-Claude engine is raw and nothing claims otherwise, so there is no wrong value to fix — this ships visibility, not a correction.
#732 Codex sign-in parity	P2: correctness	Independent of the chain and wrong today: a ChatGPT subscriber is forced into "Machine login", which the platform itself records as unattributed spend, or into per-token API billing. The one distinction the product exists to make is missing for Codex.
#733 [Epic] Codex first-class	P3: later + coordination	It is a plan, not a defect, and it carries an unresolved strategic question (#730 engine-side resume vs #693 platform-owned conversation) that must be answered before its own children can be scheduled. That is P3's definition exactly.
#739 per-instance operator manual	P3: later + enhancement mcp backend	Not a defect, and it carries three open owner questions (size-cap behaviour, creator defaults, context opt-in). Demand is measured (43 instances, 19 of them coder-repo), so this is P3 on "pending a decision", not on "pending demand".
#741 operator skill in no gate's input set	P2: correctness + contracts mcp documentation	contracts is the exact label — "a declaration nothing compares to its implementation". It hand-lists 33 of 145 tools and three copies nothing checks are identical. Misleads an operator; harms no user.

Codex cluster consistency (#733's structure): the two dependency-chain build items are P2 (#728 enabler, #729 adapter), the speculative and UI items are P3 (#730 spike, #731 chip), the one genuinely independent gap is P2 (#732), and the epic itself is P3. That reads as intended: the epic is scheduling, the chain is work.

One correction to the brief that produced this pass: #722 was listed as unlabelled. It already carries P2: correctness (plus catalog, connectors, security) and I have not changed it.