Speculative prewarm (generate:false) for the Codex WebSocket transport

[amondnet]

Summary

Evaluate and (if worthwhile) implement speculative prewarm (generate:false) on the Codex WebSocket transport — opening/priming the socket and server-side context before the first real turn, to shave first-token latency. Currently explicitly out of scope.

Why

Real Codex uses a generate:false prewarm to keep a connection warm and the context primed so the first billable turn starts faster. shunt already pools connections per session, so the remaining latency is the handshake + initial context upload on the first turn of a conversation. Prewarm targets exactly that. This is a pure latency optimization — no correctness impact — so it's lower priority than the correctness/robustness WS items, and should follow the live-probe work (so we trust continuation before adding speculative turns).

See docs/comparison.md §6 item D.

Tasks

• Confirm the generate:false frame semantics against real Codex WS traffic (what it returns, whether it establishes a reusable previous_response_id).
• Decide the trigger: on session start? on first /v1/messages for a new session id? (avoid prewarming sessions that never send a turn).
• Measure first-token latency with vs without prewarm before committing.
• Gate behind the existing websocket opt-in (and possibly a separate prewarm flag); keep it inert on non-Codex backends.

Evidence

• docs/m7-codex-websocket.md:53-58 (prewarm listed as out of scope)
• src/adapters/codex_ws.rs (pooling, response.create framing)

Related

• Comparison: docs/comparison.md
• Prerequisite: live-probe the continuation normalization first

[amondnet]

Flagging for a maintainer decision before any implementation.

docs/m7-codex-websocket.md §7 ("prewarm vs continuation — a deliberate omission", added in PR #39) already argues against this: a stateless proxy has no "user typing" phase, so forcing a generate:false prewarm would mean two round-trips per turn (worse latency), and it is currently omitted by design. This is the same "investigated, decided against" shape as #31.

Recommendation: either (a) close as won't-do referencing §7, or (b) keep open only if a real latency measurement overturns that reasoning. Priority set Low / Effort Medium pending that decision.