codex-diagnostics.md

# Codex CLI integration diagnostics

## Current verification status (2026-10-03)

Native Codex Agent question answering **passed** in the final isolated Python-MCP run: exit 0, no timeout, **67.592 seconds**, **18 JSON events** and **six completed Book Agent tool calls**, each with `error: null`. Evidence: `.work/acceptance/codex-final-v2/codex-call.json` and UTF-8 `codex-answer.txt`.

The final command inherited the configured model, used `stdin=DEVNULL`, a separately registered F: runtime and isolated host home, and a per-run MCP override with startup timeout 90 seconds and tool timeout 120 seconds. Global host configuration was unchanged. Completed tools were `book_status`, `book_get_skill`, `book_search`, `book_locate_source`, `book_read_source` and `book_render_page`. The answer cited record `1`, its evidence ID and verified physical PDF page 2, correctly reported `lexical_fallback`, and stated that actual MCP image attachment does not prove visual understanding. Native Skill automatic triggering was not separately tested.

The answer and JSON contain normal UTF-8 Chinese. A cp936 console display issue in the supervisor log did not corrupt those saved artifacts. The latest Windows executable independently passed **44 checks, 0 failures**, run `0a3d5ab2` in `.work/smoke-release-final.json`, including SDK stdio/PNG transport; see [binary validation](windows-binary-validation.md). Complete release pytest passed 276 cases with 2 skips in 161.38 seconds. This successful native Agent run used the Python MCP command shown in its report, rather than the frozen EXE.

Separate actual default Skill bootstrap installed 46 wheels in 73.259 seconds, and the dedicated optional installer installed 67 packages offline with successful pip check in 233.145 seconds. Their receiving-runtime probes passed default search/source checks and Codex host dry-run; they did not repeat native Agent question answering or host UI verification. Optional bootstrap's 67-wheel plan was checked without an actual bootstrap install. See [acceptance](acceptance.md). The probes used the same code/dependency artifacts before this document update; their captured manifest identity is not the subsequently rebuilt final manifest.

The two earlier 160-second model attempts and later 15-second model-free probes remain historical diagnostic evidence. Multiple launch/environment details changed before the final successful run, so the results do not isolate a unique cause of those earlier delays.

## Historical observed failure

The initial isolated integration attempt in `.work/run_codex_acceptance.py` used native Codex CLI, the user's configured `gpt-6.1-sol`/`openai_http` provider, a per-run Book Agent MCP override, `--ephemeral --json --sandbox read-only`, and a dedicated project. It changed no global host configuration. The launcher timed out after 160 seconds with **zero JSON events, zero stderr and no MCP tool calls**; only its own process tree was terminated. `.work/acceptance/codex-call.json` records the failure.

The launcher passed a prompt argument but left child stdin inherited. Official OpenAI documentation says that when stdin is piped and a prompt is supplied, Codex also consumes the piped data as context. Local CLI help confirms this behavior. A still-open inherited pipe can therefore delay startup before events appear. This is an inference from the launcher and input contract, not a confirmed attribution of the timeout. [Non-interactive mode](https://learn.chatgpt.com/docs/non-interactive-mode).

## Historical bounded, model-free checks

`../.work/codex-diagnostics.py`（工程内部验收记录，不随发行包提供） invokes only version/help/list commands, with explicit `stdin=DEVNULL`, a 15-second limit per command and termination limited to that command's process tree. It does not read authentication files or change global configuration.

| Command | Result | Seconds |
| --- | --- | --- |
| `codex --version` | Exit 0; `codex-cli 0.153.4` | 6.530 |
| `codex exec --help` | Exit 0; confirms piped-stdin behavior and exec `--ignore-user-config` | 5.232 |
| `codex mcp list --help` | Exit 0; no `--ignore-user-config` option | 3.913 |
| `codex --ignore-user-config -c mcp_servers={} mcp list --json` | Exit 2; rejects `--ignore-user-config` | 5.141 |

No command timed out. The last result establishes a flag-scope limitation; it does not establish an MCP initialization failure. For this installed version, `--ignore-user-config` belongs to `exec`. The official command reference documents that the flag skips user configuration while authentication still uses `CODEX_HOME`. Skipping configuration would also omit a custom configured provider unless separately reconstructed; that is unnecessary for the first retry. [Developer commands](https://learn.chatgpt.com/docs/developer-commands).

## Historical input-handling retry

Keep the original acceptance command, selected model/provider, per-run MCP definition and read-only sandbox. Change only the launcher input handling:

```python
process = subprocess.Popen(
    command,
    stdin=subprocess.DEVNULL,
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE,
    # Keep the launcher's existing encoding and Windows creation flags.
)
```

Apply the existing 160-second deadline and bounded process-tree cleanup. The root agent owns this actual model call; the diagnostics script performs no model calls. If events and MCP tools then appear, the result supports the stdin explanation. If startup remains silent, record the timeout without claiming successful native-agent integration.

The root agent repeated the acceptance with `stdin=DEVNULL`. It still timed out after 160 seconds with zero events and zero stderr. Closing stdin alone therefore did not resolve that historical failure. This result preceded the final successful isolated run above. No additional model call was made by this diagnostics worker.

The initial timeout and failed input-handling retry alone did not identify a provider, sandbox or MCP cause. The final successful run inherited the configured model and used per-run MCP isolation; it did not require a global configuration change.

There is currently no observed sandbox error or evidence that sandbox initialization caused this failure. Official documentation distinguishes `elevated` and `unelevated` Windows sandbox modes, but this diagnostic does not justify changing the sandbox or bypassing it. [Windows sandbox](https://learn.chatgpt.com/docs/windows/windows-sandbox).

## Historical additional model-free isolation on F:

After relocation to `F:\workspace\book-agent`, bounded `mcp list --json` probes used `stdin=DEVNULL` and printed only output byte counts/JSON type. Inherited configuration outputs were suppressed. Temporary home/work directories remained on F: and were checked to remain within the workspace before cleanup.

| Isolation | Observation |
| --- | --- |
| Inherited config, empty MCP override | 15-second deadline; zero stdout/stderr; total 29.232 seconds including cleanup |
| Blank temporary `CODEX_HOME`, existing acceptance cwd, empty MCP override | 15-second deadline; zero stdout/stderr; total 15.285 seconds |
| Blank temporary `CODEX_HOME` and cwd outside the repository, no override | 15-second deadline; zero stdout/stderr; total 29.863 seconds |
| Blank temporary `CODEX_HOME` and cwd outside the repository, empty MCP override | 15-second deadline; zero stdout/stderr; total 15.293 seconds |
| Standard Windows environment only, blank home/outside cwd | 15-second deadline; zero stdout; helper-alias warning when home was also the temporary directory |
| Separate blank home/temp, minimal environment, per-run file credential stores and startup update check disabled | 15-second deadline; zero stdout/stderr; total 33.255 seconds |

The helper-alias warning said Codex refused to create helper binaries under its temporary directory and proceeded. The last probe separated those directories and did not emit that warning; it still exceeded the short deadline. No authentication file or literal was inspected by the diagnostics worker, and no model request was made.

The root agent also observed F: cold filesystem/native-library operations taking roughly 35 seconds. Therefore the 15-second list limits were insufficient to establish that these probes reproduced the original 160-second exec failure. They did not identify a specific config, provider, sandbox or MCP defect; further probes were stopped while the final build proceeded. The later native Agent success is recorded at the top of this document. The requested credential-store/update overrides are public configuration fields. [Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference).