From 71ab478278867667da0cb28215d00f3c8dac0556 Mon Sep 17 00:00:00 2001
From: Kritarth-Dandapat <dkritarth@gmail.com>
Date: Wed, 12 Aug 2026 07:04:19 +0530
Subject: [PATCH] fix(acp): prove signed-in Codex session cleanup

---
 core/acp/README.md                          |  26 ++++
 core/acp/smoke.ts                           |  15 +-
 core/acp/stdio-client.test.ts               |  70 ++++++++-
 core/acp/stdio-client.ts                    |  98 ++++++++++--
 docs/research/codex-acp-current-contract.md | 164 ++++++++++++++++++++
 docs/verification/codex-acp-2026-08-12.md   |  86 ++++++++++
 6 files changed, 446 insertions(+), 13 deletions(-)
 create mode 100644 docs/research/codex-acp-current-contract.md
 create mode 100644 docs/verification/codex-acp-2026-08-12.md

diff --git a/core/acp/README.md b/core/acp/README.md
index fe44c1a..e15231e 100644
--- a/core/acp/README.md
+++ b/core/acp/README.md
@@ -12,6 +12,13 @@ for the implementation ([P1-01] — done).
 
 Adding a backend later = spawn a different ACP server. No new client code.
 
+Install the maintained Codex adapter as
+`@agentclientprotocol/codex-acp`. The older
+`@zed-industries/codex-acp` package is deprecated and embeds an older Codex
+runtime even when a newer standalone `codex` CLI is on `PATH`. Record the
+adapter package and version during live verification; executable name alone
+does not distinguish them.
+
 ## Dependency
 
 `@agentclientprotocol/sdk` (npm, verified on the registry 2026-07-21). This is
@@ -64,6 +71,13 @@ child adapter process is killed and the caller gets a thrown error
 hanging forever — this is what protects against a stalled adapter (e.g. an
 errored codex-acp turn, or any other hang mid-session).
 
+On POSIX, adapters start in their own process group. Session disposal and
+handshake/turn failures terminate the complete adapter process tree, wait up
+to one second, then escalate to `SIGKILL` if required. This matters for npm
+launcher scripts that spawn a native adapter child: killing only the launcher
+can otherwise orphan the native process. Windows terminates the direct child,
+waits with the same bound, and escalates before reporting cleanup failure.
+
 The handshake default is deliberately generous, not tight: measured against
 a real cold-start `claude-code-acp` (`CLAUDECODE` stripped), `initialize`
 returns in ~226ms but `session/new` alone legitimately takes ~16.2s — it
@@ -83,6 +97,18 @@ Requires the adapter CLI(s) actually installed and signed in to your
 Claude Pro/Max or ChatGPT plan. This is **not** part of `npm test` / CI — it's
 a separate, honest check of the real sanctioned-plan path. See `smoke.ts`.
 
+Smoke output is sanitized and compact: UTC start/end times, streamed text,
+update kinds, and terminal stop reason. Adapter diagnostics remain on stderr.
+
+If a service rollout selects a model newer than the installed adapter runtime,
+set `VELLUM_CODEX_MODEL` to a model supported by that runtime while upgrading
+the adapter. The value goes directly to the first-party adapter as
+`-c model=<value>` without a shell or alternate authentication path:
+
+```bash
+VELLUM_CODEX_MODEL=gpt-5.5 npm run smoke:acp -- codex
+```
+
 Runs fine from inside a Claude Code terminal/agent now (the `CLAUDECODE`
 stripping above handles it automatically) and no longer hangs forever on a
 stalled adapter (the turn/handshake timeouts above make it fail loud
diff --git a/core/acp/smoke.ts b/core/acp/smoke.ts
index e7cc8d9..ecfaf36 100644
--- a/core/acp/smoke.ts
+++ b/core/acp/smoke.ts
@@ -40,6 +40,7 @@ const PROMPT = 'Reply with exactly the word "pong" and nothing else.'
 
 async function smoke(backend: AcpBackend): Promise<void> {
   console.log(`\n=== ${backend} (${backend === 'claude' ? 'claude-code-acp' : 'codex-acp'}) ===`)
+  console.log(`startedAt=${new Date().toISOString()}`)
   const client = new StdioAcpClient()
   let session
   try {
@@ -49,22 +50,34 @@ async function smoke(backend: AcpBackend): Promise<void> {
     console.log(
       `  -> install/sign in the adapter, confirm it's on PATH, then re-run: npm run smoke:acp -- ${backend}`,
     )
+    process.exitCode = 1
     return
   }
 
   try {
     let sawDone = false
+    const updateKinds: string[] = []
     for await (const update of session.prompt({ text: PROMPT })) {
-      console.log(JSON.stringify(update))
+      updateKinds.push(update.kind)
+      if (update.kind === 'text' && typeof update.data === 'object' && update.data !== null) {
+        const text = 'text' in update.data ? update.data.text : undefined
+        if (typeof text === 'string') console.log(`text=${JSON.stringify(text)}`)
+      }
+      if (update.kind === 'done') console.log(`done=${JSON.stringify(update.data)}`)
       if (update.kind === 'done') sawDone = true
       if (update.kind === 'error') {
+        console.log(`error=${JSON.stringify(update.data)}`)
         console.log(`UNVERIFIED — adapter reported an error mid-turn.`)
+        process.exitCode = 1
         return
       }
     }
+    console.log(`updateKinds=${updateKinds.join(',')}`)
     console.log(sawDone ? 'VERIFIED — stream ended in a done update.' : 'UNVERIFIED — stream ended without done.')
+    if (!sawDone) process.exitCode = 1
   } finally {
     await session.dispose()
+    console.log(`endedAt=${new Date().toISOString()}`)
   }
 }
 
diff --git a/core/acp/stdio-client.test.ts b/core/acp/stdio-client.test.ts
index d0a59cd..04acce6 100644
--- a/core/acp/stdio-client.test.ts
+++ b/core/acp/stdio-client.test.ts
@@ -13,7 +13,13 @@ import type { Readable, Writable } from 'node:stream'
 import { describe, expect, it } from 'vitest'
 
 import type { AcpBackend, AcpUpdate } from './client.js'
-import { StdioAcpClient, buildAdapterEnv, mapSessionUpdate, type SpawnAdapter } from './stdio-client.js'
+import {
+  StdioAcpClient,
+  buildAdapterArgs,
+  buildAdapterEnv,
+  mapSessionUpdate,
+  type SpawnAdapter,
+} from './stdio-client.js'
 
 type AdapterChildProcess = ChildProcessByStdio<Writable, Readable, null>
 
@@ -22,6 +28,7 @@ type AdapterChildProcess = ChildProcessByStdio<Writable, Readable, null>
 // Behavior is selected via argv so one script covers every test scenario.
 const FAKE_AGENT_SCRIPT = String.raw`
 const readline = require('node:readline')
+const { spawn } = require('node:child_process')
 // argv[0] is the node binary; with \`node -e <script> <extra>\`, the first
 // extra arg lands at argv[1] (there is no "eval" placeholder entry).
 const mode = process.argv[1]
@@ -30,6 +37,12 @@ if (mode === 'exit-immediately') {
   process.exit(7)
 }
 
+if (mode === 'term-resistant-descendant') {
+  spawn(process.execPath, ['-e', 'process.on("SIGTERM", () => {}); setInterval(() => {}, 1000)'], {
+    stdio: 'ignore',
+  })
+}
+
 const rl = readline.createInterface({ input: process.stdin, terminal: false })
 function send(msg) {
   process.stdout.write(JSON.stringify(msg) + '\n')
@@ -70,6 +83,7 @@ function spawnFakeAgent(mode: string): SpawnAdapter {
   return (_backend: AcpBackend): AdapterChildProcess =>
     spawn(process.execPath, ['-e', FAKE_AGENT_SCRIPT, mode], {
       stdio: ['pipe', 'pipe', 'inherit'],
+      detached: process.platform !== 'win32',
     }) as AdapterChildProcess
 }
 
@@ -163,6 +177,38 @@ describe('StdioAcpClient', () => {
     expect(updates).toEqual([{ kind: 'error', data: { message: 'session disposed' } }])
   })
 
+  it('dispose() does not resolve until the adapter subprocess exits', async () => {
+    let child: AdapterChildProcess | undefined
+    const captureChild: SpawnAdapter = (backend) => {
+      child = spawnFakeAgent('happy')(backend)
+      return child
+    }
+    const client = new StdioAcpClient(captureChild)
+    const session = await client.newSession('codex')
+
+    await session.dispose()
+
+    expect(child?.exitCode !== null || child?.signalCode !== null).toBe(true)
+  })
+
+  it.runIf(process.platform !== 'win32')(
+    'dispose() removes a TERM-resistant adapter descendant and remains idempotent',
+    async () => {
+      let child: AdapterChildProcess | undefined
+      const captureChild: SpawnAdapter = (backend) => {
+        child = spawnFakeAgent('term-resistant-descendant')(backend)
+        return child
+      }
+      const client = new StdioAcpClient(captureChild)
+      const session = await client.newSession('codex')
+      const groupId = child!.pid!
+
+      await Promise.all([session.dispose(), session.dispose()])
+
+      expect(() => process.kill(-groupId, 0)).toThrow()
+    },
+  )
+
   it('fails a stalled prompt() via the turn timeout instead of hanging forever', async () => {
     const client = new StdioAcpClient(spawnFakeAgent('stall'), { turnMs: 50 })
     const session = await client.newSession('claude')
@@ -176,8 +222,14 @@ describe('StdioAcpClient', () => {
   })
 
   it('fails newSession() via the handshake timeout when the adapter never answers initialize', async () => {
-    const client = new StdioAcpClient(spawnFakeAgent('stall-handshake'), { handshakeMs: 50 })
+    let child: AdapterChildProcess | undefined
+    const captureChild: SpawnAdapter = (backend) => {
+      child = spawnFakeAgent('stall-handshake')(backend)
+      return child
+    }
+    const client = new StdioAcpClient(captureChild, { handshakeMs: 50 })
     await expect(client.newSession('claude')).rejects.toThrow('ACP handshake timed out after 50ms')
+    expect(child?.exitCode !== null || child?.signalCode !== null).toBe(true)
   })
 })
 
@@ -200,3 +252,17 @@ describe('buildAdapterEnv', () => {
     expect(buildAdapterEnv(sourceEnv)).toEqual({ PATH: '/usr/bin' })
   })
 })
+
+describe('buildAdapterArgs', () => {
+  it('passes an explicit Codex model override through the first-party adapter config interface', () => {
+    expect(buildAdapterArgs('codex', { VELLUM_CODEX_MODEL: 'gpt-5.5' })).toEqual([
+      '-c',
+      'model="gpt-5.5"',
+    ])
+  })
+
+  it('uses normal adapter configuration when no Codex model override is set', () => {
+    expect(buildAdapterArgs('codex', {})).toEqual([])
+    expect(buildAdapterArgs('claude', { VELLUM_CODEX_MODEL: 'gpt-5.5' })).toEqual([])
+  })
+})
diff --git a/core/acp/stdio-client.ts b/core/acp/stdio-client.ts
index 18c3ef9..a769192 100644
--- a/core/acp/stdio-client.ts
+++ b/core/acp/stdio-client.ts
@@ -42,9 +42,20 @@ type AdapterChildProcess = ChildProcessByStdio<Writable, Readable, null>
 
 /** First-party adapter subprocess per backend. Do not add others here without
  * a card — this is the whole point of the "no OAuth bridge" guardrail. */
-const ADAPTERS: Record<AcpBackend, { command: string; args: string[] }> = {
-  claude: { command: 'claude-code-acp', args: [] },
-  codex: { command: 'codex-acp', args: [] },
+const ADAPTERS: Record<AcpBackend, { command: string }> = {
+  claude: { command: 'claude-code-acp' },
+  codex: { command: 'codex-acp' },
+}
+
+/** Optional compatibility override for Codex service/CLI rollout skew. The
+ * adapter owns config parsing; JSON string encoding is valid TOML and keeps
+ * the model value in one argv entry without invoking a shell. */
+export function buildAdapterArgs(
+  backend: AcpBackend,
+  sourceEnv: NodeJS.ProcessEnv = process.env,
+): string[] {
+  const model = sourceEnv.VELLUM_CODEX_MODEL?.trim()
+  return backend === 'codex' && model ? ['-c', `model=${JSON.stringify(model)}`] : []
 }
 
 /** Spawns the adapter subprocess for a backend. Overridable for tests so unit
@@ -72,13 +83,79 @@ export function buildAdapterEnv(sourceEnv: NodeJS.ProcessEnv = process.env): Nod
 }
 
 const defaultSpawnAdapter: SpawnAdapter = (backend) => {
-  const { command, args } = ADAPTERS[backend]
-  return spawn(command, args, {
+  const { command } = ADAPTERS[backend]
+  return spawn(command, buildAdapterArgs(backend), {
     stdio: ['pipe', 'pipe', 'inherit'],
     env: buildAdapterEnv(),
+    detached: process.platform !== 'win32',
   }) as AdapterChildProcess
 }
 
+const PROCESS_EXIT_GRACE_MS = 1_000
+
+function processGroupExists(pid: number): boolean {
+  try {
+    process.kill(-pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function waitForProcessGroupExit(pid: number, timeoutMs: number): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs
+  while (processGroupExists(pid) && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 10))
+  }
+  return !processGroupExists(pid)
+}
+
+async function waitForChildExit(child: AdapterChildProcess, timeoutMs: number): Promise<boolean> {
+  if (child.exitCode !== null || child.signalCode !== null) return true
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve(false), timeoutMs)
+    const finish = (): void => {
+      clearTimeout(timer)
+      resolve(true)
+    }
+    child.once('exit', finish)
+    child.once('error', finish)
+  })
+}
+
+async function terminateAdapter(child: AdapterChildProcess): Promise<void> {
+  // A spawn failure has no pid and no process tree to terminate. Its tracked
+  // ENOENT/permission diagnostic must remain the error returned to callers.
+  if (child.pid === undefined) return
+
+  if (process.platform === 'win32') {
+    if (child.exitCode !== null || child.signalCode !== null) return
+    child.kill()
+    if (await waitForChildExit(child, PROCESS_EXIT_GRACE_MS)) return
+    child.kill('SIGKILL')
+    if (await waitForChildExit(child, PROCESS_EXIT_GRACE_MS)) return
+    throw new Error('ACP adapter process did not exit after forced termination')
+  }
+
+  const pid = child.pid
+  if (!processGroupExists(pid)) return
+  try {
+    process.kill(-pid, 'SIGTERM')
+  } catch {
+    child.kill()
+  }
+  if (await waitForProcessGroupExit(pid, PROCESS_EXIT_GRACE_MS)) return
+
+  try {
+    process.kill(-pid, 'SIGKILL')
+  } catch {
+    child.kill('SIGKILL')
+  }
+  if (!(await waitForProcessGroupExit(pid, PROCESS_EXIT_GRACE_MS))) {
+    throw new Error(`ACP adapter process group ${pid} did not exit after forced termination`)
+  }
+}
+
 /** Maps a raw ACP `SessionUpdate` onto Vellum's `AcpUpdate` contract.
  * Exported standalone so the mapping can be unit-tested without a subprocess. */
 export function mapSessionUpdate(update: SessionUpdate): AcpUpdate {
@@ -223,6 +300,7 @@ class StdioAcpSession implements AcpSession {
   // session, mirroring the ACP protocol (a session has one active turn).
   private queue: UpdateQueue | undefined
   private disposed = false
+  private disposePromise: Promise<void> | undefined
   // Set only while a prompt() call is in flight; cleared by dispose() too so
   // an external dispose mid-turn doesn't leave a dangling timer.
   private turnTimeout: { cancel(): void } | undefined
@@ -280,8 +358,7 @@ class StdioAcpSession implements AcpSession {
       settled = true
       queue.push({ kind: 'error', data: { message: err.message } })
       queue.close()
-      this.disposed = true
-      this.child.kill()
+      void this.dispose().catch(() => undefined)
     })
 
     try {
@@ -293,13 +370,14 @@ class StdioAcpSession implements AcpSession {
   }
 
   async dispose(): Promise<void> {
-    if (this.disposed) return
+    if (this.disposePromise) return this.disposePromise
     this.disposed = true
     this.turnTimeout?.cancel()
     this.turnTimeout = undefined
     this.queue?.close()
     this.queue = undefined
-    this.child.kill()
+    this.disposePromise = terminateAdapter(this.child)
+    return this.disposePromise
   }
 }
 
@@ -372,7 +450,7 @@ export class StdioAcpClient implements AcpClient {
       return session
     } catch (err) {
       handshake.cancel()
-      child.kill()
+      await terminateAdapter(child)
       // Whether the transport's generic "connection closed" error or the
       // child's own exit/spawn diagnostic wins the race above is a timing
       // accident. `failure` settles once the child actually exits/errors
diff --git a/docs/research/codex-acp-current-contract.md b/docs/research/codex-acp-current-contract.md
new file mode 100644
index 0000000..fcfccd6
--- /dev/null
+++ b/docs/research/codex-acp-current-contract.md
@@ -0,0 +1,164 @@
+# Codex ACP current contract
+
+Research snapshot: 2026-08-12. Scope: Issue #25 contract research only. This
+note records executable, authentication, wire-protocol, and lifecycle facts; it
+does not claim a successful live Vellum smoke test.
+
+## Executive finding
+
+The machine has a usable-looking but legacy adapter installation:
+`@zed-industries/codex-acp` 0.16.0. That repository was archived on 2026-07-22;
+the maintained successor is `@agentclientprotocol/codex-acp`, currently
+published as 1.1.14. Both expose a `codex-acp` executable, so executable name
+alone does not identify implementation or compatibility. Vellum's proof must
+record adapter package/version and the `initialize` response, not only PATH.
+
+Installed legacy adapter 0.16.0 embeds Codex Rust crates pinned to Codex
+`rust-v0.137.0`; it does not delegate turns to the separately installed
+`codex-cli 0.147.0` executable. Therefore `codex --version` is useful auth and
+environment evidence, but does not report the engine version inside this
+adapter. [Legacy adapter manifest](https://github.com/zed-industries/codex-acp/blob/v0.16.0/Cargo.toml)
+
+## Observed local prerequisites
+
+Read-only commands and package metadata produced this snapshot:
+
+| Check | Observed result | Supported diagnostic |
+| --- | --- | --- |
+| `command -v codex` | `/opt/homebrew/bin/codex` | `codex --version` / `codex -V` |
+| Codex version | `codex-cli 0.147.0` | CLI help explicitly defines `-V, --version` |
+| `command -v codex-acp` | `/opt/homebrew/bin/codex-acp` | package-dependent |
+| Adapter package | `@zed-industries/codex-acp` 0.16.0 | Read installed `package.json` or `initialize.agentInfo` |
+| `codex-acp --version` | rejected as an unexpected argument | This legacy binary supports only `-c/--config` and `-h/--help` |
+| Vellum ACP SDK | `@agentclientprotocol/sdk` 1.2.1 | `package.json` / lockfile |
+
+Installed evidence paths:
+
+- `/opt/homebrew/Caskroom/codex/0.147.0/bin/codex`
+- `/opt/homebrew/lib/node_modules/@zed-industries/codex-acp/package.json`
+- `/opt/homebrew/lib/node_modules/@zed-industries/codex-acp/node_modules/@zed-industries/codex-acp-darwin-arm64/package.json`
+- `node_modules/@agentclientprotocol/sdk/package.json`
+- `node_modules/@agentclientprotocol/sdk/schema/schema.json`
+
+Current maintained adapter installation differs: its official README supports
+`codex-acp --version`, bundles a compatible `@openai/codex`, and allows
+`CODEX_PATH` only as an override. Its npm package is
+`@agentclientprotocol/codex-acp`, not the installed legacy Zed package.
+[Maintained adapter README](https://github.com/agentclientprotocol/codex-acp#installation)
+
+## Authentication contract
+
+Codex supports ChatGPT-managed OAuth, persists and refreshes those credentials,
+and exposes `codex login`, `codex login status`, and
+`codex login --device-auth`. Issue #25 must use that existing ChatGPT sign-in;
+no API-key login is needed or allowed by Vellum's guardrails.
+[OpenAI authentication documentation](https://learn.chatgpt.com/docs/auth)
+[OpenAI CLI login implementation](https://github.com/openai/codex/blob/main/codex-rs/cli/src/login.rs)
+
+Legacy adapter 0.16.0 uses Codex's shared auth manager and Codex home. It
+advertises ChatGPT authentication unless `NO_BROWSER` is set, reloads stored
+auth before rejecting a session or prompt as authentication-required, and can
+start Codex's browser login flow through ACP. Existing CLI authentication is
+therefore expected to be visible to the adapter, but only a live session proves
+that for this installation. Remote/headless behavior differs: `NO_BROWSER`
+suppresses the adapter's ChatGPT method, while official Codex CLI provides
+device authentication.
+[Legacy adapter source](https://github.com/zed-industries/codex-acp/blob/v0.16.0/src/codex_agent.rs)
+[Legacy adapter README](https://github.com/zed-industries/codex-acp/blob/v0.16.0/README.md)
+
+The maintained adapter also advertises ChatGPT, API-key, and optional custom
+gateway auth. Vellum should select or inherit ChatGPT auth and must not infer
+that every advertised method is permitted by project policy.
+[Maintained adapter authentication](https://github.com/agentclientprotocol/codex-acp#authentication)
+
+## ACP V1 request and stream semantics
+
+ACP wire messages use newline-delimited JSON-RPC over stdio. Client initializes
+before any session request. `initialize` carries an integer protocol major and
+client capabilities; agent returns its negotiated version, capabilities,
+optional authentication methods, and optional `agentInfo`. Missing capability
+means unsupported. Client should disconnect when returned version is not one it
+supports. [ACP initialization](https://agentclientprotocol.com/protocol/v1/initialization)
+[ACP transports](https://agentclientprotocol.com/protocol/v1/transports)
+
+Installed adapter 0.16.0 responds with ACP V1 and identifies itself as
+`codex-acp` with package version. Its declared dependency is ACP crate 0.14.0,
+while Vellum uses TypeScript SDK 1.2.1; those artifact versions are not wire
+protocol versions. Current stable wire protocol is V1.
+[ACP versioning](https://github.com/agentclientprotocol/agent-client-protocol#versioning)
+[Legacy adapter manifest](https://github.com/zed-industries/codex-acp/blob/v0.16.0/Cargo.toml)
+
+`session/new` requires an absolute `cwd` and `mcpServers`, then returns a
+`sessionId`. Installed 0.16.0 builds a Codex thread, forwards supported client
+MCP configuration, and returns that thread/session identity. The same ID must
+be used for subsequent prompt, update, cancel, and close operations.
+[ACP session setup](https://agentclientprotocol.com/protocol/v1/session-setup)
+[Legacy adapter source](https://github.com/zed-industries/codex-acp/blob/v0.16.0/src/codex_agent.rs)
+
+`session/prompt` represents one complete turn. During it, the agent sends zero
+or more `session/update` notifications. Relevant Vellum update variants include
+`agent_message_chunk`, `agent_thought_chunk`, `tool_call`, and
+`tool_call_update`; newer SDK schemas also include plan, command, mode, config,
+session-info, and usage updates. Completion is the `session/prompt` response,
+whose required `stopReason` may be `end_turn`, `max_tokens`, `max_turn_requests`,
+`refusal`, or `cancelled`. Silence, first text, or a tool result is not turn
+completion. [ACP prompt turn](https://agentclientprotocol.com/protocol/v1/prompt-turn)
+[Installed SDK schema](../../node_modules/@agentclientprotocol/sdk/schema/schema.json)
+
+This matches Vellum's basic flow: `initialize` -> `session/new` ->
+`session/prompt`; route updates by `sessionId`; emit Vellum `done` only after
+the prompt RPC resolves. A valid live proof should record sanitized update
+kinds, useful response text, and final `stopReason: end_turn` for two turns or
+sessions.
+
+## Cancellation and termination
+
+`session/cancel` is a notification for an active turn. Agent should stop model
+and tool work, flush pending updates, then resolve the original prompt with
+`stopReason: cancelled`. Cancellation does not itself close session or adapter
+process. [ACP cancellation](https://agentclientprotocol.com/protocol/v1/cancellation)
+
+`session/close`, when supported/advertised, cancels in-flight work and releases
+that session's resources. Legacy adapter 0.16.0 implements close and explicitly
+drains shutdown/abort events so prompt callers receive clean cancellation.
+Process shutdown remains separate from turn cancellation and session close.
+[ACP session-close RFD](https://agentclientprotocol.com/rfds/session-close)
+[Legacy adapter thread shutdown](https://github.com/zed-industries/codex-acp/blob/v0.16.0/src/thread.rs)
+
+Vellum currently kills the child on `dispose()` and timeout rather than sending
+`session/cancel` or negotiated `session/close`. Killing provides a final safety
+boundary, but live verification must explicitly check for no orphan process.
+A future lifecycle fix should prefer cancel/close and retain bounded forced
+termination as fallback; any such behavior change needs regression tests for
+stalled prompt and non-exiting child paths.
+
+## Compatibility constraints for Issue #25
+
+1. Identify which package owns `codex-acp` on PATH. Installed legacy 0.16.0 and
+   maintained 1.1.x have materially different internals and version flags.
+2. Capture `initialize.protocolVersion`, `agentInfo`, and advertised
+   capabilities. Do not infer compatibility from npm/SDK artifact versions.
+3. Treat installed CLI 0.147.0 and legacy adapter's embedded Codex 0.137.0 as
+   separate runtimes. CLI sign-in state may be shared; executable version is
+   not.
+4. Use ACP V1 semantics. Do not depend on draft/newer protocol features unless
+   negotiated.
+5. Keep consuming updates until prompt response resolves. Preserve unknown
+   update variants rather than treating them as fatal or completion.
+6. Bound initialize/session creation and each prompt. On timeout, cancel/close
+   when possible, terminate process as fallback, and verify no orphan remains.
+7. Existing ChatGPT authentication is the sanctioned path. Do not set or
+   solicit `OPENAI_API_KEY`, `CODEX_API_KEY`, or custom-gateway credentials.
+
+## Limits of this research
+
+- No credential files or tokens were read, changed, or copied.
+- No browser sign-in or authentication mutation was performed.
+- No prompt was sent and no live ACP session was created by this research task.
+- Package documentation and source establish intended contracts, not successful
+  use of Kritarth's current subscription. `npm run smoke:acp -- codex`, a
+  second prompt/session, timestamps, sanitized updates, and orphan-process
+  inspection remain required live evidence.
+- The installed legacy repository is archived. Current maintained adapter
+  behavior may continue changing; pin and report exact package versions in any
+  reproducible result.
diff --git a/docs/verification/codex-acp-2026-08-12.md b/docs/verification/codex-acp-2026-08-12.md
new file mode 100644
index 0000000..5d12bc5
--- /dev/null
+++ b/docs/verification/codex-acp-2026-08-12.md
@@ -0,0 +1,86 @@
+# Codex ACP live verification: 2026-08-12
+
+Issue: #25. All timestamps are UTC. Responses and diagnostics below are
+sanitized; no credentials or credential files were read.
+
+## Environment
+
+- Standalone CLI: `codex-cli 0.147.0`
+- Sign-in check: `codex login status` reported `Logged in using ChatGPT`
+- Adapter on `PATH`: deprecated `@zed-industries/codex-acp 0.16.0`
+- Adapter embedded Codex runtime: `rust-v0.137.0`
+- ACP SDK: `@agentclientprotocol/sdk 1.2.1`
+- Maintained adapter available from npm:
+  `@agentclientprotocol/codex-acp 1.1.14`
+
+## Reproducible baseline
+
+At `2026-08-11T18:04:48Z`, `npm run smoke:acp -- codex` opened a real ACP
+session but failed its prompt. The signed-in service selected `gpt-5.6-sol`;
+the legacy adapter reported that the model required a newer Codex version. It
+also failed to decode the newer `max` reasoning-effort model metadata. Vellum
+received a terminal ACP error rather than useful streamed text.
+
+The baseline also exposed an orphan native `codex-acp` process after the npm
+launcher exited. Regression tests now require `dispose()` and handshake
+failure to wait for adapter exit. POSIX cleanup terminates the complete adapter
+process group.
+
+## Signed-in live proof
+
+The stable standalone CLI completed the exact-response prompt with `gpt-5.5`,
+proving that model is available through the existing ChatGPT sign-in. Vellum
+then ran its real first-party ACP path twice with
+`VELLUM_CODEX_MODEL=gpt-5.5`.
+
+Both Vellum sessions:
+
+- completed `StdioAcpClient.newSession("codex")`;
+- streamed the useful text `pong`;
+- emitted update kinds including `text`, `tool_result`, and `done`;
+- terminated with `stopReason: end_turn`;
+- used no raw API key, custom gateway, or third-party OAuth bridge.
+
+Final post-fix runs:
+
+| Run | Start | End | Terminal result | Orphan query |
+| --- | --- | --- | --- | --- |
+| 1 | `2026-08-12T01:32:35.106Z` | `2026-08-12T01:32:47.333Z` | `done/end_turn` | empty |
+| 2 | `2026-08-12T01:32:58.702Z` | `2026-08-12T01:33:09.523Z` | `done/end_turn` | empty |
+
+The legacy adapter continued to log its model-metadata decode error on stderr,
+but the explicit supported-model override allowed both turns to complete. The
+maintained adapter should replace the deprecated package as a local
+prerequisite; executable-name compatibility alone is not enough evidence.
+
+## Cleanup evidence
+
+Before the lifecycle fix, native adapter processes survived under PID 1. After
+the fix, disposal targets the POSIX process group and waits for it to disappear,
+with bounded `SIGKILL` escalation. Final verification reran the smoke twice
+and recorded an empty `codex-acp` / `codex app-server` process query after each
+session.
+
+Exact post-session process check:
+
+```bash
+ps -axo pid,ppid,state,lstart,command | rg '[c]odex-acp|[c]odex app-server'
+```
+
+It produced no matching rows after either final run.
+
+## Automated verification
+
+- Failing regression baseline: disposal returned while its adapter child was
+  still alive (`expected null not to be null`).
+- Focused: `npm test -- core/acp/stdio-client.test.ts` passed 18 tests.
+- Full: `npm test` passed 24 files and 147 tests.
+- `npm run typecheck` passed.
+- `npm run build` passed all Electron Vite bundles.
+- `git diff --check` passed.
+
+The full suite emitted existing jsdom `HTMLCanvasElement.getContext` warnings
+from Reader tests; all Reader tests passed. Live Electron clicks, screenshots,
+and real-paper evidence are not applicable: issue #25 changes the headless ACP
+transport, smoke harness, and documentation, with no renderer or visible UI
+change. The real signed-in ACP sessions above are the required live path.