patch-codex-app-server-observability

name	patch-codex-app-server-observability
description	This skill should be used when ensuring Codex emits centralized observability logs (sse_lines.jsonl) while running in app-server mode, especially when used by the VS Code extension.

Patch Codex App Server Observability

[Created by Codex: 019be564-39d9-7b12-a4cf-fb7a7f1af223 2026-01-22]

Purpose

Enable or restore centralized observability (writes sse_lines.jsonl) for the long-lived codex app-server process used by VS Code.

When to Use

• VS Code Codex “New Thread” works but subsequent turns stop producing events in ~/centralized-logs/codex/sse_lines.jsonl.
• codex app-server runs fine but the process never opens sse_lines.jsonl.
• A regression between Codex versions removed app-server logging.
• The user sets "chatgpt.cliExecutable" to a custom codex binary and expects the same observability behavior as terminal runs.

Workflow

1. Confirm which codex binary VS Code is running:
   • Check settings for "chatgpt.cliExecutable" in:
     • ~/Library/Application Support/Code/User/settings.json
     • <repo>/.vscode/settings.json
   • Record the resolved path and codex --version.
   • If the path points to a local repo build, ask the user to confirm the intended repo/branch/commit.
2. Confirm the running app-server process and whether it is logging:
   • Find the VS Code-started PID (search for codex app-server).
   • Check whether the process has the log file open:
     • lsof -p <pid> | rg 'sse_lines\\.jsonl|centralized-logs/codex'
3. Choose the patch location (prefer least invasive):
   • Preferred (matches codex-cli 0.77.0 behavior): initialize observability in the root CLI when launching codex app-server (no sub-subcommand).
   • Alternative: initialize observability inside the codex-app-server crate (requires a decision on how to choose/configure log dir).
4. Implement the root CLI patch:
   • In codex-rs/cli/src/main.rs, before launching the server:
     • resolve the effective log dir (root --log-dir if set, otherwise default via observability::resolve_log_dir)
     • call observability::init(log_dir)
   • Keep failure non-fatal (print a warning and continue).
   • Keep SIGTERM handler behavior consistent.
5. Build and validate:
   • cargo build -p codex-cli --release
   • Ensure VS Code points at the rebuilt binary if "chatgpt.cliExecutable" is set.
6. Restart VS Code to pick up the new binary:
   • VS Code keeps codex app-server alive; reload the window (or kill the app-server PID and let the extension respawn it).
7. Re-test:
   • Confirm lsof shows sse_lines.jsonl opened by the app-server process.
   • Run multiple turns in one thread; confirm the JSONL file continues to append across turns.

Evidence to Include in RCA

• The exact codex path VS Code ran (bundled binary vs "chatgpt.cliExecutable" override).
• The codex app-server command line and PID.
• Whether lsof shows sse_lines.jsonl open.
• Any stderr warnings emitted when observability initialization fails.