feat(codex): env-mcp subcommand of codex-app-gateway - #78

…ead codex app-server subprocess

Adds 2026-05-10-codex-app-gateway-subprocess.md, which replaces
Subsystem 2 of the MCP-rewrite spec with a design that spawns one
upstream `codex app-server --listen ws://...` subprocess per thread
and proxies ws frames between the user's TUI and the subprocess. Cuts
~1100 LOC of Go (no 17-RPC handler reimplementation, no Postgres
schema, no event mapper) at the cost of a per-thread subprocess
supervisor + S3 CODEX_HOME round-trip.

Validated against codex-cli 0.130.0:
- PoC #3: full initialize → thread/start → turn/start → ServerNotification
  stream end-to-end on a loopback ws.
- PoC #3b: two concurrent subprocesses with isolated CODEX_HOMEs run
  in independent threads with no sqlite contention.

Subsystems 1 (no fork patches), 3 (codex-exec-gateway), and 4 (env-mcp,
PR #78) are unchanged. Cross-references added to the MCP-rewrite spec
header.

…tion plan

Marks the 2026-05-05 codex-app-gateway-and-exec-gateway design spec
SUPERSEDED by the 2026-05-10 MCP-rewrite spec (and now further refined
by the codex-app-gateway-subprocess spec). Marks the four 2026-05-05
plan files OBSOLETE with pointers to their successors.

Adds 2026-05-10-codex-env-mcp.md, the implementation plan executed
in PR #78 that delivered Subsystem 4 of the MCP-rewrite spec
(env-mcp subcommand of codex-app-gateway).

… app-server (Subsystem 2)

Implements Subsystem 2 of the codex-gateway design as a thin auth-proxy + per-thread \`codex app-server\` subprocess manager + transparent ws frame proxy. Replaces the originally-planned 17-RPC handwritten Go RPC layer.

- New: \`internal/codexappgateway/{auth,codexhome,supervisor,proxy}/\` packages + \`server.go\` + \`s3_store.go\`.
- Modified: \`cmd/codex-app-gateway/main.go\` (wires the \`serve\` subcommand previously stubbed in #78).
- 63 tests + 1 integration test against real codex 0.130.0 — all PASS, race-clean.
- Spec: \`docs/superpowers/specs/2026-05-10-codex-app-gateway-subprocess.md\`
- Plan: \`docs/superpowers/plans/2026-05-11-codex-app-gateway-subprocess.md\`

**Final round of post-review fixes (after holistic 5-reviewer audit):**

- Runtime correctness: Touch-on-frame, race-loser unlock, stale-handle health-check on \`EnsureSubprocess\`, \`ChildHandle.Cmd\` → unexported.
- Hardening: \`os.Environ()\` inheritance for subprocess, \`filepath.Rel\` tmpdir guard, \`ConfigInput\` cross-field validation, \`*slog.Logger\` fields on Supervisor/IdleReaper/BridgeClient/MCPServer, S3 endpoint scheme validation.

Near-verbatim refresh of the 2026-05-05 plan with three contextual
updates aligned to the 2026-05-10 MCP-rewrite spec:
- Spec reference now points to 2026-05-10-codex-gateway-mcp-rewrite.md § Subsystem 3
- /bridge/{exe_id} consumer is the env-mcp child binary (PR #78), not
  the spawned codex itself (wire protocol + auth model unchanged)
- Cap-token allow-list is single-exe-id per the 2026-05-10 refinement
  (verification logic unchanged; minting is stricter, happens in
  codex-app-gateway)

Old 2026-05-05 plan file's banner updated to point at this reissue.

…uracy

Six interlinked fixes from the holistic PR self-review:
- C1: Config.Validate() rejects empty HMAC/internal secrets; NewServer now
  returns (*Server, error) and refuses zero-value config. Closes a path
  where empty CapTokenHMACSecret silently accepted forged tokens.
- C2: inbound + bridge ws now SetReadLimit(-1). nhooyr's 32KB default
  would silently close large process/read responses — codex exec-server
  streams them. (Same fix env-mcp PR #78 already had.)
- C3: RevokedSet.Add returns evictedLive bool; RevokeTurn handler logs
  at Warn when a still-live revocation is evicted at capacity. Closes a
  silent security regression where evicted-but-live tokens worked again.
- C4: bridge pump context now derived from r.Context() so graceful
  shutdown drains active sessions instead of leaking pump goroutines.
- I7: migrate() wraps each error with the migration name so operators
  can tell which migration failed.
- I8: corrects 3 wrong comments (bridge.go step-3 rationale, server.go
  nil-fields claim, forwarder.go shutdown semantics).

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

…egistry (Subsystem 3)

Implements **Subsystem 3** of the codex-gateway design — completes the gateway service trio (env-mcp #78, codex-app-gateway #79, codex-exec-gateway here).

- New service \`cmd/codex-exec-gateway\` + \`internal/codexexecgateway/\`:
  - chi router + lifecycle, embedded Postgres migrations.
  - Inbound \`/codex-exec/{exe_id}\` ws acceptor (bcrypt tunnel-token verify, single-conn-per-exe eviction).
  - Bridge \`/bridge/{exe_id}\` ws acceptor (HMAC cap-token verify with single-exe-id allow-list, revocation check, per-exe-id bridge mutex via \`AcquireBridge\`/\`ReleaseBridge\` to prevent concurrent-pump data races).
  - In-memory \`ConnRegistry\` (concurrent-safe, identity-guarded \`Unregister\`).
  - Bounded \`RevokedSet\` (cap 10000, FIFO eviction, periodic exp pruning, \`Add\` returns \`evictedLive bool\` for security alerting).
  - HTTP endpoints: \`POST /api/codex-exec/register\`, \`POST/GET/DELETE /api/codex-exec/workspaces/{wid}/executors\`, internal \`GET /api/exec-gateway/connected\`, \`POST /api/exec-gateway/revoke-turn\` (shared-secret-protected).
- Cross-package factor-out: \`internal/codexappgateway/proxy/\` (from PR #79) moved to shared \`internal/wsbridge/\`, consumed by both gateways.
- Shared DTOs in \`internal/codexexecgateway/execmodel\` (eliminates parent↔handlers import-cycle adapters).

**Self-review** (5 specialized reviewers in parallel) flagged 4 Critical + 11 Important + 7 Minor; 3 fix batches landed (\`10fd4a1\`, \`f1c7f3e\`, \`1a52358\`):
- C1: \`Config.Validate()\` rejects empty HMAC; \`NewServer\` returns error on zero-value config.
- C2: inbound + bridge \`SetReadLimit(-1)\` (closes silent 32KB-frame truncation).
- C3: revoked-set eviction logs Warn when dropping a still-live revocation.
- C4: bridge pump derives ctx from \`r.Context()\` (graceful shutdown drains active sessions).
- I3: per-exe-id bridge mutex prevents concurrent-pump data race.
- Plus observability (auth failure logs, pump-error log levels, close-error logs), comment accuracy, dead-config removal, \`Store\` encapsulation tightening.

Final: 35 PASS / 15 SKIP (DB-gated) / 0 FAIL, \`-race\` clean, vet clean, build clean.

**Spec / Plan**
- Spec: \`docs/superpowers/specs/2026-05-10-codex-gateway-mcp-rewrite.md\` § Subsystem 3
- Plan: \`docs/superpowers/plans/2026-05-12-codex-exec-gateway.md\` (14 TDD tasks, all complete)