## Purpose

Defines how Emacs agent-shell launches every Codex ACP session against the common externally managed Codex App Server through the installed transport bridge.

## Requirements

### Requirement: Codex agent-shell uses the shared server exclusively
Every Codex agent-shell launch SHALL use stock `codex-acp` with `CODEX_PATH` set to the absolute path of `codex-app-server-bridge` and `CODEX_APP_SERVER_URL` set to `ws://127.0.0.1:4500`. The integration MUST NOT provide a path that starts or falls back to a private App Server.

#### Scenario: Codex agent-shell starts successfully
- **WHEN** the bridge executable is installed and the configured shared App Server is available
- **THEN** agent-shell starts stock `codex-acp`, which invokes `<resolved-bridge-path> app-server` and connects through the bridge to the shared server

#### Scenario: bridge executable is missing
- **WHEN** Emacs cannot resolve `codex-app-server-bridge` with `executable-find`
- **THEN** the Codex launcher reports a clear error before starting `codex-acp`

#### Scenario: shared server is unavailable
- **WHEN** agent-shell launches Codex while the configured shared App Server is unavailable
- **THEN** the launch fails clearly without starting a private App Server

### Requirement: Endpoint settings remain separate
The agent-shell bridge endpoint and the shared App Server launcher endpoint SHALL remain independently configured in version 1. The agent-shell environment SHALL explicitly inject its bridge endpoint rather than depend on the environment inherited when Emacs started.

#### Scenario: agent-shell environment is constructed
- **WHEN** Emacs prepares the environment for a Codex ACP process
- **THEN** it adds `CODEX_APP_SERVER_URL=ws://127.0.0.1:4500` directly to that process environment

#### Scenario: shared server launcher is retained
- **WHEN** the user launches the common App Server through the existing CLI helper
- **THEN** that helper continues to use its own endpoint configuration without reading the agent-shell bridge setting

### Requirement: Codex launcher has one authentication scope
The Emacs agent-shell configuration SHALL expose only the normal Codex launcher and SHALL remove the capital `C-c p X` binding and the agent-shell-specific privileged Codex launcher path. The tool-auth CLI helper used to launch the shared App Server MUST remain available. This requirement applies only to Codex and MUST NOT alter Pi or Claude launcher behavior.

#### Scenario: normal Codex binding is used
- **WHEN** the user invokes `C-c p x`
- **THEN** Emacs launches a Codex ACP session through the shared-server bridge

#### Scenario: removed capital binding is inspected
- **WHEN** the user checks `C-c p X`
- **THEN** it is not bound to the former privileged Codex agent-shell launcher

#### Scenario: shared server needs tool authentication
- **WHEN** the user launches the common App Server with the existing tool-auth CLI helper
- **THEN** the helper remains available and defines the authentication environment inherited by the shared server

#### Scenario: another agent provider is launched
- **WHEN** the user starts Pi or Claude from agent-shell
- **THEN** its existing authentication and launcher behavior is unchanged

### Requirement: Agent sessions are distinct shared-server threads
Each stock `codex-acp` process SHALL use one bridge process and one shared-server WebSocket connection. Starting a new Codex agent-shell session SHALL create its own Emacs-owned Codex thread on the shared App Server rather than live-peer into or resume an existing Codex TUI thread.

#### Scenario: multiple agent-shell sessions run concurrently
- **WHEN** the user starts two Codex agent-shell sessions
- **THEN** each session has its own `codex-acp` and bridge process and both connect independently to the same shared App Server

#### Scenario: a TUI thread already exists
- **WHEN** the user starts an agent-shell Codex session while a Codex TUI thread is active on the shared server
- **THEN** agent-shell creates a distinct thread instead of attaching to the active TUI thread

### Requirement: Agent-shell does not manage server lifecycle
Starting, restarting, or stopping a Codex agent-shell session SHALL affect only its `codex-acp` and bridge processes. It MUST NOT start, restart, stop, or supervise the common App Server.

#### Scenario: agent-shell buffer is restarted
- **WHEN** the user invokes the existing agent-shell restart command
- **THEN** Emacs replaces the session's adapter and bridge connection while the shared App Server continues running

#### Scenario: agent-shell buffer is closed
- **WHEN** the user closes a Codex agent-shell buffer
- **THEN** its bridge connection ends without terminating the shared App Server

### Requirement: Shared authentication effects are explicit
Authentication state SHALL be owned by the shared App Server. Documentation for the agent-shell integration MUST state that logout requests are global to that shared server and therefore affect all clients connected to it.

#### Scenario: account logout is requested from agent-shell
- **WHEN** the user invokes the `codex-acp` logout behavior from an agent-shell session
- **THEN** the request reaches the shared App Server and the documented shared authentication scope applies to every client