First-class Codex engine via `codex exec --json` (structured), not raw stdout capture

[serge-ivo]

Depends on #728 (structured engine adapters).

Problem

Codex sessions run through runOneShot() in packages/browser-runner/src/coding/headless.ts with mode = "raw": we spawn codex exec --sandbox danger-full-access "<turn>" and capture stdout raw. Consequences, all structural:

• Noisy, truncated readback. The assistant's actual answer is interleaved with every exec/curl/tool line in the transcript, then clipped by the transcript-line cap → 8000-char snapshot → 400-char coding_timeline tail. Asking the agent to "be concise" cannot fix it — the loss is at the capture layer, and even a 3-line answer arrives buried in command chrome. (Observed live on the FIS coder session.)
• Unmetered. takeUsage() returns [] for raw engines, so Codex spend never reaches the ledger — this is 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.
• Unattributed acts. takeActs() returns [], so a Codex gh pr merge/push is invisible to supervision (acts[].ok is documented in two supervision legends and absent from the payload; delegation budgets can enter 'exhausted' with no exit #594).

Codex supports structured output

codex exec (the non-interactive form we already invoke — no TTY, no tmux) supports --json, which streams a JSONL event feed on stdout: thread/turn/item events including agent messages, reasoning, command executions, and token usage on turn completion. This is the direct analogue of Claude's --output-format stream-json. (--output-last-message <file> is also available for just the final message.)

Proposed fix

Implement a Codex adapter on the #728 abstraction:

• Launch argv: add --json to the Codex exec command (update the codex entry in handlers.ts cliCommand and the cloud DEFAULT_ENGINES preset in workers/api/src/lib/coding-engines.ts).
• Parse each JSONL line → the normalized event set: agent message → assistant text; command/tool item → tool_use/tool_result; turn-completed → turnEnd + a usage record; error/turn-failed → error + turn report.
• Feed the SAME pendingUsage/pendingActs/turnReport pipeline Claude uses, so metering (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), acts (acts[].ok is documented in two supervision legends and absent from the payload; delegation budgets can enter 'exhausted' with no exit #594) and the turn report ([bug] Every Codex turn exited 1 and the session still reported alive/ready/idle — a non-zero engine exit is a line of prose in the pane and nothing else #545) light up for Codex with no further work.

Acceptance

• Codex adapter parses codex exec --json output; the transcript shows the assistant's message isolated from command execution lines.
• A Codex turn produces a non-empty takeUsage() record (verify Engine spend appears on the Usage page — closes the Codex half of 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).
• A Codex gh pr/push is attributed via takeActs().
• Adapter is written against the observed Codex JSONL schema and pinned to a tested Codex CLI version (schema is --json/experimental — assert with a captured fixture, don't assume field names).
• Older runners with no --json support fall back to the generic raw adapter, unchanged.

Refs: #728, #556, #594, #545, #674

[serge-ivo]

Review corrections (adversarial BA assessment, 2026-08-22)

The direction holds, but three claims were overstated or wrong. Tightening before this is scheduled:

1. codex exec --json is an UNVERIFIED premise — spike it first. The monorepo has zero references to codex exec --json / thread.started / --output-last-message; docs/coding-engines.md (which discusses Codex at length, codex-cli 0.146.0) never mentions a JSON mode. First deliverable is a captured JSONL fixture proving the flag exists on a pinned codex-cli version and the schema matches, BEFORE any adapter code. If it doesn't emit turn-complete events with token counts, this issue collapses to "the generic raw fallback already exists, nothing to build."

2. --json is unstable with active tools — our exact config. openai/codex#15451: --json output is malformed when tools/MCP servers are active. Our Codex runs write-enabled and executes shell/gh tools, so this is the tested scenario, not an edge case. Add to acceptance: the adapter must tolerate non-JSON / corrupt lines without wedging the turn (the Claude handle() already does this at headless.ts:656 — same guarantee required here), and the fixture must be captured with tools firing, not a minimal call.

3. Event schema is NOT Claude-parallel — name the real field paths. Codex --json uses type: "turn.completed" carrying usage.input_tokens / output_tokens / cached_input_tokens, and type: "item.*" (e.g. item.command_execution) for tool events — not Claude's type: "assistant" + content[].type / type: "result" + result.usage. The pipeline target (pendingUsage/pendingActs/turnReport) is the same; the mapping must be written to the Codex paths, not assumed from Claude's.

4. Wording fix: "older runners with no --json support" → it's the codex-cli version on the user's machine, which the PAGS runner cannot version-check before spawn. Reframe as "machines with an older codex-cli" and specify the minimum version that reliably emits thread.started+turn.completed, or degrade gracefully on parse failure.

Refs: upstream openai/codex#15451, #3817. Ref cheatsheet for the schema: takopi.dev codex exec-json.

[serge-ivo]

Shipped the #729 spike and implementation.\n\nCommits:\n- 032b543 docs(browser-runner): record codex json spike\n- 50ec826 feat(browser-runner): structure codex exec output\n\nWhat landed:\n- Captured and committed Codex 0.151.0 JSON-mode evidence and schema map.\n- Added a Codex engine adapter for plain codex exec that injects --json once and keeps one-shot prompt-last argv semantics.\n- Parsed thread.started, item.command_execution, item.agent_message, turn.completed, and turn.failed into the normalized engine event pipeline.\n- Codex command executions now flow through existing transcript rendering and consequential-act attribution via stable item.id.\n- Codex token usage now drains as provider openai / model codex; no dollar cost is invented when the CLI reports no cost.\n- codex exec resume / fork / review / help remain on raw fallback pending #730. Codex thread ids are not persisted as resume state.\n- Default Codex preset is now codex exec --json --sandbox danger-full-access.\n\nVerification:\n- pnpm vitest run packages/browser-runner/src/coding/engine-adapter.test.ts packages/browser-runner/src/coding/engine-usage.test.ts packages/browser-runner/src/coding/engine-acts.test.ts packages/browser-runner/src/coding/headless.test.ts packages/browser-runner/src/coding/runtime.test.ts workers/api/src/lib/engine-usage.test.ts workers/api/src/lib/usage.test.ts workers/api/src/lib/coding-timeline.test.ts workers/api/src/lib/engine-metering.test.ts workers/api/src/lib/coding-engines.test.ts\n- pnpm --filter @proagentstore/browser-runner typecheck\n- pnpm exec biome check touched TS/doc paths\n- git diff --check\n\nKnown unrelated verification gap: pnpm --filter proagentstore-api typecheck still fails in existing src/lib/pdf-form.ts / missing pdf-lib typing issues, outside this change.