Proposal: opt-in JSONL run tracing for codex-cli (CODEX_TRACE_PATH)

[OS-DevSource]

What feature would you like to see?

Summary
Add an opt-in JSONL run trace for codex-cli when CODEX_TRACE_PATH is set. The trace is best-effort (never fails the CLI if trace IO fails) and writes one JSON object per line.

Motivation / use cases

• Debugging: correlate a run with its working directory and outcome (success/failure).
• Automation/CI: a stable machine-readable signal to detect failed runs and collect context.
• Tooling: easy to tail, grep, parse, and ingest (JSONL).

Proposed behavior (no default behavior change)

• Default: no tracing unless explicitly enabled via env var.
• When enabled: append to the trace file:
  • run_started: { ts_ms, run_id, mode: "cli", cwd }
  • run_finished: { ts_ms, run_id, ok, exit_code, error }
• run_id should be unique per run (e.g. run_<ts_ms>_<pid>).
• Error strings should be redacted/sanitized if configured.

Prototype
I implemented a working prototype in PR #8017:
#8017

If this aligns with the roadmap, I can rework it to match any preferred schema/tests/placement.

Additional information

Manual test
export CODEX_TRACE_PATH=/tmp/codex-trace.jsonl
rm -f /tmp/codex-trace.jsonl
codex # run any short session, then quit
tail -n 5 /tmp/codex-trace.jsonl

Notes

• Best-effort: if the file cannot be opened/written, tracing is silently disabled and the CLI runs normally.
• JSONL format is intended for streaming/grepping/ingestion (1 JSON object per line).