codex-app-server-bridge/openspec/changes/connect-agent-shell-to-shared-codex-app-server/proposal.md

Why

Emacs agent-shell currently reaches Codex through codex-acp, which starts a private codex app-server process for each adapter. This prevents those sessions from participating in the already-running shared Codex App Server and fragments thread visibility and authentication across separate server processes.

What Changes

• Add a standalone codex-app-server-bridge executable that satisfies the narrow Codex executable contract expected by stock codex-acp: it accepts exactly the app-server subcommand and translates stdio JSONL messages to WebSocket text frames connected to an existing Codex App Server.
• Require a loopback-only WebSocket endpoint in CODEX_APP_SERVER_URL; the bridge never discovers, starts, stops, supervises, or falls back from the shared server.
• Author the bridge in strict TypeScript, compile it to Node 24 ESM JavaScript, keep the generated output uncommitted, and package only that runtime build with no dependencies as private package version 0.1.0 installable from an npm pack tarball.
• Define deterministic connection, framing, logging, signal, and failure behavior, including a five-second startup timeout, no reconnect, no JSON-RPC payload logging, and one WebSocket connection per bridge process.
• BREAKING Change both Codex agent-shell launch paths to shared-server-only operation by resolving the bridge into CODEX_PATH and injecting CODEX_APP_SERVER_URL=ws://127.0.0.1:4500; no private App Server fallback remains.
• BREAKING Remove the capital C-c p X Codex agent-shell binding and its privileged/unprivileged agent-shell distinction. Preserve the separate tool-auth CLI helper used to launch the shared App Server.
• Keep stock codex-acp unchanged and preserve transparent shared-server behavior, including the global effect of account/logout.

Capabilities

New Capabilities

• codex-app-server-bridge: A Node 24 executable and npm package that adapts codex-acp stdio JSONL transport to a pre-existing loopback Codex App Server WebSocket endpoint with explicit lifecycle and failure semantics.
• agent-shell-shared-codex-connection: Emacs agent-shell configuration that routes all Codex ACP sessions through the installed bridge and the common App Server while preserving the server-launch authentication helper.

Modified Capabilities

None.

Impact

• Adds the standalone /Users/dnabracz/Work/scm/codex-app-server-bridge repository as the source and OpenSpec owner for the bridge package.
• Later implementation will update the user-managed Emacs configuration in /Users/dnabracz/.config/emacs/init.el; that home-directory change remains governed by the dotgit workflow.
• Integrates with stock codex-acp through its existing CODEX_PATH environment contract and with the Codex App Server through its WebSocket JSON-RPC transport. Neither upstream project is forked or patched.
• Requires Node.js 24 or newer. Runtime dependencies remain empty; development dependencies are limited to pinned typescript and @types/node packages.
• Distribution uses reproducible, uncommitted JavaScript build output in the .tgz generated by npm pack and installed globally with npm; no package registry or server lifecycle manager is introduced.