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

1. Package Foundation

• 1.1 Add package.json for private package version 0.1.0 with engines.node >=24, the codex-app-server-bridge bin, typecheck/build/test/prepack scripts, no runtime dependencies, and pinned typescript plus @types/node development dependencies; verify a clean npm ci succeeds from the generated lockfile.
• 1.2 Add strict no-emit TypeScript checking plus a reproducible Node 24 ESM build configuration; verify npm run typecheck rejects a non-erasable syntax fixture, accepts the project source, and npm run build emits runnable JavaScript with rewritten relative imports.
• 1.3 Add Git ignores for generated build output, npm tarballs, and other local outputs while retaining source and the lockfile; verify git status --short lists neither dist/ nor an .tgz produced by the release flow.
• 1.4 Add a minimal JavaScript bin bootstrap that reports the Node 24 minimum before importing the compiled entry point; verify the supported-runtime path reaches the compiled CLI and an injected unsupported-version test reaches the intentional error path.

2. Bridge Implementation

• 2.1 Implement the exact app-server invocation contract and concise usage failure for all other argument sequences; verify table-driven CLI tests cover missing, extra, and alternate arguments without opening a socket.
• 2.2 Implement required endpoint parsing for only root-path ws://127.0.0.1:<port> and ws://[::1]:<port> URLs; verify tests reject missing values, localhost, invalid or missing ports, other hosts and schemes, credentials, paths, queries, and fragments.
• 2.3 Implement a single native WebSocket connection with a five-second startup deadline and defer stdin consumption until open; verify tests preserve an immediately written initialize record and time out without spawning or discovering a server.
• 2.4 Implement ordered stdio-JSONL-to-WebSocket-text framing in both directions, ignoring blank input without parsing JSON-RPC; verify tests preserve request and response payload text, ordering, and account/logout while rejecting binary frames.
• 2.5 Implement graceful stdin-EOF, SIGINT, and SIGTERM shutdown plus nonzero exits for configuration, timeout, transport, protocol, and unexpected-close failures; verify child-process tests assert the corresponding close behavior and exit statuses with no reconnect.
• 2.6 Limit stderr output to sanitized configuration and lifecycle diagnostics and omit routine or payload logs; verify tests use secret-bearing sample payloads and assert they never appear in stderr.

3. Hermetic Test Infrastructure

• 3.1 Build a minimal loopback WebSocket test peer from Node core APIs for deterministic handshake and text/binary frame control; verify it runs entirely under node:test without Codex, credentials, external network access, or additional packages.
• 3.2 Cover normal duplex relay, startup backpressure, multiple records, local shutdown, remote closure, connection refusal, timeout, and binary-frame rejection through the compiled executable process boundary; verify npm test passes and leaves no child processes or listeners behind.
• 3.3 Add a concurrency test that starts two independent compiled bridge processes against one test peer; verify each process creates exactly one distinct WebSocket connection and neither process manages the peer's lifecycle.

4. Documentation and Package Validation

• 4.1 Document prerequisites, the exact CODEX_PATH and CODEX_APP_SERVER_URL contract, strict loopback URL grammar, shared-server-only failure behavior, no lifecycle management, compiled-runtime packaging, and global logout scope; verify every externally visible requirement has a corresponding README section or executable usage message.
• 4.2 Document the source-based release flow npm ci, npm run typecheck, npm run build, npm test, npm pack, and global installation from the resulting tarball, including the tested codex-acp and Codex versions; verify the commands are executable from a clean checkout without a registry publication step.
• 4.3 Run npm pack --dry-run and inspect the file list for only intended compiled runtime and documentation files; verify no TypeScript source, tests, local artifacts, credentials, or stale unrelated build output are included.
• 4.4 Produce the 0.1.0 tarball, install it globally, and invoke the installed bin; verify executable-find/command -v resolves it and unsupported arguments fail through the packed artifact as specified.

5. Emacs Dotfiles Integration

• 5.1 Update the dotgit-managed Codex agent-shell environment builder to resolve codex-app-server-bridge with executable-find, fail clearly when absent, and inject the absolute CODEX_PATH plus CODEX_APP_SERVER_URL=ws://127.0.0.1:4500; verify an Emacs batch or emacsclient evaluation returns the intended child environment.
• 5.2 Remove the capital C-c p X binding and agent-shell-specific privileged Codex launcher while retaining C-c p x, the Codex tool-auth CLI helper used for shared-server launch, and all Pi and Claude behavior; verify live keymap/function inspection and the dotgit diff show only the intended Codex agent-shell removal.
• 5.3 Keep the shared App Server launch endpoint independently configured from the agent-shell bridge endpoint; verify changing or inspecting one configuration does not source its value from the other.
• 5.4 Restart existing Codex agent-shell buffers after the configuration change; verify each replacement codex-acp process has the resolved bridge path and explicit loopback URL in its environment.

6. Live Shared-Server Acceptance

• 6.1 With the externally managed tool-auth App Server already listening on ws://127.0.0.1:4500, run a direct packed-bridge initialize/request smoke test; verify a valid response returns and closing the bridge leaves the original server process and listener alive.
• 6.2 Launch a Codex session through C-c p x; verify the process chain is agent-shell -> codex-acp -> codex-app-server-bridge, no private codex app-server child exists, and the Emacs-owned thread is visible through the shared server.
• 6.3 Launch two concurrent Codex agent-shell sessions while a TUI client is present; verify they create distinct shared-server threads/connections rather than attaching to the TUI thread.
• 6.4 Stop and restart one agent-shell session; verify only its adapter and bridge processes change and the shared server plus other clients remain connected.
• 6.5 Stop the shared server and attempt a fresh agent-shell launch; verify the bridge reports the sanitized loopback endpoint, exits nonzero within the startup deadline, and no private fallback server appears.

7. Final Validation

• 7.1 Run npm ci, npm run typecheck, npm run build, and npm test in the bridge repository; verify all local quality gates pass from lockfile state.
• 7.2 Run openspec validate connect-agent-shell-to-shared-codex-app-server --strict; verify the change passes strict validation with both capability deltas and all tasks traceable to the specs and design.
• 7.3 Review repository and dotgit status separately; verify source changes, generated artifacts, consumer configuration, and any uncommitted user changes are clearly distinguished before handoff.