## 1. Package Foundation

- [x] 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.
- [x] 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.
- [x] 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.
- [x] 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

- [x] 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.
- [x] 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.
- [x] 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.
- [x] 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.
- [x] 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.
- [x] 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

- [x] 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.
- [x] 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.
- [x] 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

- [x] 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.
- [x] 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.
- [x] 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.
- [x] 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

- [x] 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.
- [x] 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.
- [x] 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.
- [x] 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

- [x] 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.
- [x] 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.
- [x] 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.
- [x] 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.
- [x] 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

- [x] 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.
- [x] 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.
- [x] 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.