Files
pipelines/docs/notes/codex-pending-interactions-restart.md

3.5 KiB

Codex pending interactions across Pipelines restarts

The App Server's pending approval/question callback IDs belong to the connection that received them. Its current official schema exposes no pending-request listing/replay method. Saving JSON in the Pipelines database cannot make an old callback answerable on a new upstream connection.

Added pipelines-codex-host: a detached, private local WebSocket bridge that owns the existing App Server connection. It does not launch Codex. The installed server scopes hosts by database and upstream socket, finds/reuses the helper, and initializes only its downstream connection after a restart. The host caches the one upstream initialization and replays exactly the still-unanswered server requests. Responses or matching serverRequest/resolved notifications remove pending entries. Client call IDs are translated to unique host IDs and routed only to the originating client; replacing a client discards old routes. Client and callback RPC IDs are capped at 256 bytes.

Unix sockets are mode 0600 under an owner-verified mode-0700 directory. Per-scope file locks prevent simultaneous helpers. The existing daemon connection, not a PID or a model statement, owns pending callbacks. Pending memory is capped at 128 requests / 8 MiB; calls at 256; incoming frames at 16 MiB. Overflow closes rather than answering an interaction. With no Pipelines client, helpers expire after 20 minutes with no pending callbacks, or after 24 hours even when pending. Ordinary notifications are not spooled; current thread readback repairs gaps.

Native installation, tester packages and Docker include the helper; Go-bin uninstallation verifies and removes its executable. Missing helper or explicit PIPELINES_CODEX_HOST=off retains direct mode and logs its restart limitation. Direct-mode fixtures still pass. Hosts run independently of a launching request's context and are not killed by installing a replacement binary.

Verification:

  • go test -race ./internal/codexhost ./internal/codex ./internal/installation ./cmd/pipelines-server passes. Real Unix-socket fixtures cover pending approval and question responses across client replacement, duplicate response rejection, resolved callbacks, matching thread ownership, old/new RPC-ID collision isolation, detached arrival/replay, bounded pending state, singleton ownership, private permissions, shutdown cleanup, and actual helper process spawning/reuse.
  • The actual Codex adapter's Open -> Detach -> Open integration retains both permission and question maps, answers their original IDs, initializes upstream once, and does not replay resolved requests on a third client.
  • Existing direct Codex tests pass; go build ./..., go vet ./..., and all 53 native-installer Python tests pass. Full Go integration is the manager's check.

No live service, conversation, daemon, credential or deployment was changed. The initial deployment cannot rescue callbacks already owned by the old direct connection; pending interactions must settle before that first replacement. A helper crash, upstream App Server restart, or expiry breaks callback identity and remains an explicit limitation. No disk reconstruction is claimed.

Handshake follow-up: the bridge now sends the upstream initialized notification once after a successful initialize response and before declaring readiness. Downstream initialized notifications remain suppressed on every attach. A real socket fixture verifies initialize -> initialized ordering and exactly one of each across client replacement, and the adapter integration checks both counts.