S0-01: Prove signed-in Codex ACP and bounded cleanup

[dkritarth]

Closes #25

User outcome

Vellum can open a real codex-acp session through Kritarth's existing ChatGPT sign-in, stream a useful response, terminate with done, and clean the adapter process tree without leaving an orphan.

Scope

• Add an explicit VELLUM_CODEX_MODEL compatibility override passed to the first-party adapter without a shell.
• Make ACP disposal idempotent, bounded, and process-tree-aware on POSIX; preserve bounded direct-child cleanup on Windows.
• Make smoke failures return nonzero and keep smoke evidence compact/sanitized.
• Document current adapter/CLI contract and signed-in live evidence.

Non-goals: no paper UI, custom authentication, raw API keys, RAG, alternate harness, renderer, or Electron UI change.

Acceptance criteria

• Real StdioAcpClient.newSession("codex") succeeds through first-party adapter.
• Prompt emits useful streaming output and terminates with done.
• No raw API key or third-party OAuth bridge exists.
• Failure paths remain bounded and clean up adapter processes.
• ACP integration documentation matches observed behavior.

Automated verification

• Failing baseline: dispose() resolved while adapter child remained alive (expected null not to be null).
• Focused: npm test -- core/acp/stdio-client.test.ts — 18/18 passed.
• npm test — 24 files, 147 tests passed. Existing jsdom canvas warnings remain in Reader tests; all Reader tests passed.
• npm run typecheck
• npm run build
• git diff --check

Live Electron verification

Not applicable: no src/, electron/, preload, IPC, or visible UI files changed. Issue #25 requires the real headless signed-in ACP path, exercised below. No screenshots required.

Visual and console evidence

No visible UI change. Legacy adapter stderr logs nonfatal model-metadata decode errors for newer max reasoning metadata. These are disclosed in docs/verification/codex-acp-2026-08-12.md; successful turns still end in done/end_turn.

Real-paper / ACP evidence

Environment: codex-cli 0.147.0; codex login status reported Logged in using ChatGPT; PATH adapter is deprecated @zed-industries/codex-acp 0.16.0 with embedded Codex 0.137.0; ACP SDK 1.2.1. No credential files or tokens were read.

Baseline npm run smoke:acp -- codex opened a session but failed because service selected gpt-5.6-sol, newer than embedded runtime, and left an orphan native adapter.

Final independent verification on commit 71ab478 ran VELLUM_CODEX_MODEL=gpt-5.5 npm run smoke:acp -- codex twice:

• Run 1: 2026-08-12T01:40:16.747Z to 01:40:30.602Z; text pong; kinds tool_result,text,tool_result,done; stopReason: end_turn; exit 0; immediate orphan query empty.
• Run 2: 2026-08-12T01:40:39.384Z to 01:40:46.766Z; same text/kinds/stop reason; exit 0; immediate orphan query empty.

Exact cleanup query: ps -axo pid,ppid,state,lstart,command | rg '[c]odex-acp|[c]odex app-server'.

Limitations and follow-ups

• Installed @zed-industries/codex-acp 0.16.0 is deprecated and noisy against current model metadata. Maintained prerequisite is @agentclientprotocol/codex-acp 1.1.14; local migration remains recommended.
• Current live proof needs VELLUM_CODEX_MODEL=gpt-5.5 until maintained adapter/current runtime replaces the legacy package.
• Windows cleanup is bounded direct-child termination; POSIX receives full process-group cleanup.

Independent review

• Standards/security/lifecycle review: final re-review passed with no actionable findings.
• Issue-contract/spec review: final re-review passed with no actionable findings.
• Independent verifier repeated applicable live procedure twice and confirmed clean worktree/no orphan processes.
• Linked issue had status:in-progress, never status:blocked.