docs(runtime): document websocket timeout triage

Author: masterkain

README.md

@@ -1512,9 +1512,6 @@ web, worker, scheduler, and migration roles. For a real install, pin the chart
 👉 [codex-action](https://github.com/icoretech/codex-action) runs OpenAI Codex
 CLI non-interactively in GitHub Actions workflows
 
-👉 [codex-docker](https://github.com/icoretech/codex-docker) provides a
-multi-arch OpenAI Codex CLI Docker image built from official upstream releases
-
 ## Local Development
 
 Local development runs Phoenix on the host and Postgres through the dev compose

docs-site/src/content/docs/getting-started/configuration.mdx

@@ -109,6 +109,8 @@ After the app boots, manage operational settings from the admin UI instead of ed
 
 Secret settings stay write-only in the UI. For example, metrics bearer material is stored as a keyed digest and SMTP credentials are stored encrypted for mail delivery and credential checks.
 
+Gateway websocket upgrades use the admin-managed `websocket_idle_timeout_ms` setting for downstream idle close behavior. The default is `1_800_000` ms, and accepted values are `60_000..3_600_000` ms. This setting applies to new websocket upgrades on the backend Codex route and the narrow public `/v1/responses` websocket route; it is separate from upstream receive timeouts.
+
 ## Runtime URLs
 
 Use only the surface that matches your client.

docs-site/src/content/docs/operators/request-logs.mdx

@@ -132,6 +132,14 @@ Common causes to inspect are:
 
 The Errors column should stay safe to copy into operator tickets. It should not include raw prompts, responses, uploaded file contents, credentials, or provider payloads.
 
+### Websocket Close Triage
+
+Websocket request rows are created after gateway admission and reservation. If a websocket closes before a request row exists, inspect application logs for sanitized websocket close metadata instead of looking for prompt or frame content.
+
+Safe close metadata can include route family, endpoint, transport, route class, phase, `reason_class`, elapsed milliseconds, safe session id prefixes, owner or proxy instance ids, and downstream epoch. Typical `reason_class` values include `max_frame_size_exceeded` for an oversized inbound websocket frame, `timeout` for downstream websocket idle close, and `closed` for a normal client close.
+
+For downstream idle closes on backend Codex websockets and narrow public `/v1/responses` websockets, check the admin-managed `websocket_idle_timeout_ms` setting. Its default is `1_800_000` ms and the accepted range is `60_000..3_600_000` ms. This setting does not change upstream receive timeout classification.
+
 ## Usage Metadata
 
 Usage lines summarize request accounting, including request count context, token totals, cached input tokens, and estimated cost when pricing is available. Treat these as operational attribution and capacity evidence. They are not a replacement for provider billing records.

docs-site/src/content/docs/reference/runtime-routes.mdx

@@ -125,7 +125,7 @@ These endpoints keep Codex backend semantics and do not translate through the pu
       <td>Persistent upstream Codex websocket response session</td>
       <td>No HTTP adapter translation</td>
       <td>Supported</td>
-      <td>Narrow backend websocket route. It preserves websocket session continuity and uses <code>x-codex-turn-state</code>.</td>
+      <td>Narrow backend websocket route. It preserves websocket session continuity, uses <code>x-codex-turn-state</code>, and applies the admin-managed <code>websocket_idle_timeout_ms</code> downstream idle window.</td>
     </tr>
     <tr>
       <td><code>POST /backend-api/codex/responses/compact</code></td>
@@ -185,7 +185,7 @@ Some Codex clients use `/backend-api/codex/v1` as their base URL. Codex Pooler e
       <td>Backend websocket response session</td>
       <td>No</td>
       <td>Supported</td>
-      <td>Alias for the backend websocket route. Prompt-cache routing locality is excluded.</td>
+      <td>Alias for the backend websocket route. Prompt-cache routing locality is excluded, and the same <code>websocket_idle_timeout_ms</code> downstream idle window applies.</td>
     </tr>
     <tr>
       <td><code>POST /backend-api/codex/v1/responses/compact</code></td>
@@ -317,7 +317,7 @@ Supported work is translated into Codex-compatible requests and then routed thro
       <td>Backend Codex websocket response session</td>
       <td>Partial</td>
       <td>Partial</td>
-      <td>Narrow Responses websocket compatibility only. It is not OpenAI Realtime SDK support.</td>
+      <td>Narrow Responses websocket compatibility only. It is not OpenAI Realtime SDK support. It uses the same downstream idle and frame guardrails as backend Codex websockets.</td>
     </tr>
     <tr>
       <td><code>POST /v1/chat/completions</code></td>
@@ -533,6 +533,12 @@ The root `/mcp` operator endpoint is not a bridge for `/v1/responses` remote MCP
 
 Prompt-cache routing locality is a local routing hint. It can apply on `POST /backend-api/codex/responses`, `POST /backend-api/codex/v1/responses`, `POST /backend-api/codex/v1/chat/completions`, `POST /v1/responses`, and `POST /v1/chat/completions`. It is excluded from websocket, compact, file, audio, image, usage, and app-server helper routes.
 
+## Websocket Guardrails
+
+Backend Codex websocket routes and the narrow public `GET /v1/responses` websocket route use bounded downstream guardrails. `websocket_idle_timeout_ms` controls the downstream websocket idle close window for new upgrades. Its default is `1_800_000` ms, and accepted values are `60_000..3_600_000` ms.
+
+Inbound websocket frames are also bounded by the configured gateway request body limit. Operators should treat `reason_class=max_frame_size_exceeded` as an oversized client frame, `reason_class=timeout` as downstream websocket idle close, and upstream receive timeout errors as separate upstream-side failures. These classifications are metadata-only and must not include raw websocket frames or request bodies.
+
 ## Request compression boundaries
 
 Request compression is a per-Pool routing option named `request_compression_enabled`. It is disabled by default. When enabled, Codex Pooler may compress upstream-bound Responses tool-output content before dispatch. This is request-side only: raw outputs and upstream response bodies are not stored, and CCR/retrieval is not implemented.