Clarify app-server turn lifecycle semantics for external clients

What feature would you like to see?

Expose a stable, machine-readable lifecycle for Codex task execution so external clients can reliably monitor progress and decide when human review is needed.

This is intended for open-source integrations (CLI wrappers, dashboards, mobile/web review surfaces), without changing Codex model behavior.

Problem

Today, external tooling can observe Codex outcomes, but lifecycle signals are not consistently exposed as a stable contract. Integrators need to infer state transitions from mixed output/log patterns, which is brittle across versions.

Desired outcome

Provide a minimal, versioned lifecycle contract with:

1. Run state transitions
2. Review-required signal
3. Diff/artifact summary metadata
4. Final disposition

Proposed API shape (minimal)

A structured envelope emitted for each run:

• run.created
• run.queued
• run.executing
• run.review_required
• run.completed
• run.failed
• run.canceled

Each event includes stable identifiers and timestamps, plus optional artifact summary fields.

Why this matters

• Enables reliable supervision UX for Codex runs
• Reduces parser fragility for community tooling
• Preserves Codex as source of truth while allowing ecosystem clients

Backward compatibility

• Additive only
• Existing human-readable output remains unchanged
• Version field in payload to support future extension

Acceptance criteria

1. A documented event/state contract exists in docs.
2. At least one output surface exposes the contract (stdout JSON mode, log stream, or dedicated command output).
3. Contract includes explicit review_required signal.
4. Contract includes file-change summary metadata (files_changed, insertions, deletions) when available.
5. Tests cover state transition ordering and terminal states.

Minimal schema example

{
  "version": "1.0",
  "event": "run.executing",
  "run": {
    "id": "run_123",
    "session_id": "sess_456",
    "task_id": "task_789",
    "state": "executing",
    "created_at": "2026-05-04T18:10:00Z",
    "updated_at": "2026-05-04T18:10:12Z",
    "review_required": false
  },
  "artifact": {
    "diff_available": true,
    "files_changed": 3,
    "insertions": 42,
    "deletions": 9,
    "paths": [
      "codex-rs/tui/src/app.rs",
      "codex-rs/core/src/task.rs"
    ]
  },
  "terminal": {
    "reason": null,
    "exit_code": null
  }
}

Enum values

• state: created | queued | executing | review_required | completed | failed | canceled
• terminal.reason: success | error | user_canceled | policy_blocked | timeout

Additional information

I can help with:

• Repro cases
• Edge-case matrix (failed tool call, partial write, canceled run)
• Draft tests for transition validity