codexLB-up 1.25.0b10__py3-none-any.whl

app/modules/proxy/_service/support.py

@@ -0,0 +1,2122 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+import re
+import time
+from collections import deque
+from collections.abc import Awaitable, Callable, Coroutine, Mapping
+from contextvars import ContextVar, Token
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Literal, NoReturn, Protocol, cast
+
+import anyio
+
+from app.core.auth.refresh import RefreshError, is_transient_refresh_contention, refresh_contention_kind
+from app.core.balancer.types import UpstreamError
+from app.core.clients.proxy import CodexControlRequestPrivacyPolicy, ProxyResponseError
+from app.core.clients.proxy_websocket import (
+    UPSTREAM_WEBSOCKET_TRANSPORT_FAILURE_DETAIL,
+    UpstreamWebSocket,
+)
+from app.core.clock import REAL_CLOCK, Clock, Scheduler
+from app.core.config.settings import get_settings
+from app.core.errors import OpenAIErrorEnvelope, OpenAIErrorParam, openai_error
+from app.core.openai.model_registry import get_model_registry
+from app.core.openai.models import OpenAIEvent
+from app.core.openai.parsing import classify_event_type
+from app.core.plan_types import account_plan_matches_allowed
+from app.core.resilience.network_recovery import PROCESS_NETWORK_UNAVAILABLE_CODE
+from app.core.resilience.overload import is_local_overload_error_code
+from app.core.types import JsonValue
+from app.core.upstream_proxy import ResolvedUpstreamRoute
+from app.core.utils.locks import fast_lock
+from app.core.utils.sse import sse_event_type_from_block
+from app.db.models import Account, StickySessionKind
+from app.modules.api_keys.service import (
+    ApiKeyData,
+    ApiKeyRequestUsageBudget,
+    ApiKeyUsageReservationData,
+)
+from app.modules.proxy.affinity import _AffinityPolicy
+from app.modules.proxy.affinity_observation import AffinityObservation
+from app.modules.proxy.helpers import _normalize_error_code, _parse_openai_error
+from app.modules.proxy.load_balancer import (
+    AccountLease,
+    AccountSelection,
+    CatalogOmissionQuotaAdmission,
+)
+from app.modules.proxy.tool_call_dedupe import ToolCallDedupeKey
+from app.modules.proxy.work_admission import AdmissionLease
+
+logger = logging.getLogger(__name__)
+
+
+_REQUEST_TRANSPORT_HTTP = "http"
+_REQUEST_TRANSPORT_WEBSOCKET = "websocket"
+_REASONING_SUMMARY_BLANK_HTML_COMMENT_RE = re.compile(r"(?m)^[ \t]*<!--\s*-->[ \t]*(?:\r?\n|\Z)")
+_TTFT_EVENT_TYPES = frozenset(
+    {
+        "response.output_text.delta",
+        "response.refusal.delta",
+        "response.reasoning_text.delta",
+    }
+)
+_TTFT_TOOL_DELTA_EVENT_TYPES = frozenset(
+    {
+        "response.function_call_arguments.delta",
+        "response.output_tool_call.delta",
+        "response.custom_tool_call_input.delta",
+    }
+)
+_TTFT_REASONING_EVENT_TYPES = frozenset(
+    {"response.reasoning_summary_text.delta", "response.reasoning_summary_text.done"}
+)
+_PENDING_TOOL_CALL_OUTPUT_ITEM_TYPE_BY_CALL_TYPE = {
+    "function_call": "function_call_output",
+    "custom_tool_call": "custom_tool_call_output",
+    "apply_patch_call": "apply_patch_call_output",
+}
+_PENDING_TOOL_CALL_ITEM_TYPES = frozenset(_PENDING_TOOL_CALL_OUTPUT_ITEM_TYPE_BY_CALL_TYPE)
+_PENDING_TOOL_CALL_OUTPUT_ITEM_TYPES = frozenset(_PENDING_TOOL_CALL_OUTPUT_ITEM_TYPE_BY_CALL_TYPE.values())
+_TTFT_OUTPUT_ITEM_TYPES = _PENDING_TOOL_CALL_ITEM_TYPES - {"function_call"}
+# Upstream ``response.*`` events that prove the model already ran for a turn.
+# Both relay surfaces flip ``upstream_model_output_seen`` on them; in the
+# Responses protocol the first one is always ``response.output_item.added``.
+_MODEL_OUTPUT_EVENT_TYPES = frozenset(
+    {
+        "response.output_item.added",
+        "response.output_item.done",
+        "response.output_text.delta",
+        "response.refusal.delta",
+        "response.reasoning_text.delta",
+        "response.reasoning_summary_text.delta",
+        "response.reasoning_summary_text.done",
+        "response.function_call_arguments.delta",
+        "response.output_tool_call.delta",
+    }
+)
+_WEBSOCKET_FULL_REPLAY_WAIT_MIN_ITEMS = 20
+_WEBSOCKET_FULL_REPLAY_WAIT_POLL_SECONDS = 0.05
+_HARD_HTTP_BRIDGE_AFFINITY_KINDS = frozenset(
+    {
+        "turn_state_header",
+        "session_header",
+        "thread_header",
+        "internal_unanchored_parallel",
+        "internal_model_parallel",
+        "internal_request_parallel",
+    }
+)
+_ACCOUNT_SELECTION_RECOVERY_MIN_SLEEP_SECONDS = 1.0
+_HARD_AFFINITY_RECOVERY_SLEEP_SECONDS = 2.0
+_ACCOUNT_SELECTION_RECOVERY_DEFAULT_SLEEP_SECONDS = 30.0
+_ACCOUNT_SELECTION_RECOVERY_MAX_SLEEP_SECONDS = 300.0
+_ACCOUNT_SELECTION_RECOVERY_HEARTBEAT_SECONDS = 10.0
+_ACCOUNT_SELECTION_RETRY_HINT_RE = re.compile(r"try again in\s+([0-9]+(?:\.[0-9]+)?)s", re.IGNORECASE)
+_LOCAL_ACCOUNT_CAP_ERROR_CODES = frozenset(
+    {"account_response_create_cap", "account_stream_cap", "api_key_stream_fair_share"}
+)
+_ACCOUNT_MODEL_UNSUPPORTED_ERROR_CODE = "account_model_unsupported"
+_PROPAGATED_CAPACITY_STARTUP_WAIT: ContextVar[asyncio.Event | None] = ContextVar(
+    "propagated_capacity_startup_wait",
+    default=None,
+)
+_PROPAGATED_CAPACITY_STARTUP_READY: ContextVar[asyncio.Event | None] = ContextVar(
+    "propagated_capacity_startup_ready",
+    default=None,
+)
+_PROPAGATED_RESPONSES_SERVICE_CLEANUP_READY: ContextVar[asyncio.Event | None] = ContextVar(
+    "propagated_responses_service_cleanup_ready",
+    default=None,
+)
+_PROPAGATED_RESPONSES_OWNER_FORWARD_DISPATCHED: ContextVar[asyncio.Event | None] = ContextVar(
+    "propagated_responses_owner_forward_dispatched",
+    default=None,
+)
+_PROPAGATED_RESPONSES_OWNER_FORWARD_REJECTED: ContextVar[asyncio.Event | None] = ContextVar(
+    "propagated_responses_owner_forward_rejected",
+    default=None,
+)
+
+
+def _strip_blank_html_comment_lines(text: str) -> str:
+    terminal_match = None
+    for match in _REASONING_SUMMARY_BLANK_HTML_COMMENT_RE.finditer(text):
+        if match.end() == len(text):
+            terminal_match = match
+    cleaned, count = _REASONING_SUMMARY_BLANK_HTML_COMMENT_RE.subn("", text)
+    if count == 0:
+        return text
+    if terminal_match is not None:
+        return cleaned.rstrip("\r\n")
+    return cleaned
+
+
+def _reasoning_summary_delta_key(payload: Mapping[str, JsonValue]) -> tuple[str | None, int | None, int | None]:
+    item_id = payload.get("item_id")
+    output_index = payload.get("output_index")
+    summary_index = payload.get("summary_index")
+    return (
+        item_id if isinstance(item_id, str) else None,
+        output_index if isinstance(output_index, int) else None,
+        summary_index if isinstance(summary_index, int) else None,
+    )
+
+
+def _could_be_blank_html_comment_line(text: str) -> bool:
+    candidate = text.rsplit("\n", 1)[-1].lstrip(" \t")
+    if not candidate:
+        return False
+    if not candidate.startswith("<!--"):
+        return "<!--".startswith(candidate)
+    remainder = candidate[4:].lstrip()
+    if not remainder.startswith("-->"):
+        return "-->".startswith(remainder)
+    return not remainder[3:].strip(" \t\r")
+
+
+def _is_reasoning_summary_interleavable_event(event_type: JsonValue | None) -> bool:
+    return isinstance(event_type, str) and (event_type == "response.in_progress" or event_type.startswith("codex."))
+
+
+@dataclass(slots=True)
+class _TTFTReasoningDeltaState:
+    text: str
+    visible_at: float | None = None
+
+
+def _visible_reasoning_prefix_before_blank_comment_candidate(text: str) -> str:
+    if "\n" not in text:
+        return ""
+    prefix, _candidate = text.rsplit("\n", 1)
+    return _strip_blank_html_comment_lines(prefix).strip()
+
+
+def _finalize_ttft_reasoning_deltas(
+    pending_reasoning_deltas: dict[tuple[str | None, int | None, int | None], _TTFTReasoningDeltaState],
+    *,
+    now: float,
+) -> float | None:
+    # ``now`` is the caller's owner-clock sample; it stamps every pending
+    # reasoning delta that became visible without a stamp of its own.
+    visible_at_values: list[float] = []
+    for pending in pending_reasoning_deltas.values():
+        if not _strip_blank_html_comment_lines(pending.text):
+            continue
+        if pending.visible_at is not None:
+            visible_at_values.append(pending.visible_at)
+            continue
+        visible_at_values.append(now)
+    pending_reasoning_deltas.clear()
+    return min(visible_at_values) if visible_at_values else None
+
+
+def _ttft_event_visible_at(
+    event_type: str | None,
+    payload: dict[str, JsonValue] | None,
+    pending_reasoning_deltas: dict[tuple[str | None, int | None, int | None], _TTFTReasoningDeltaState] | None = None,
+    *,
+    now: float,
+) -> float | None:
+    # ``now`` is the caller's owner-clock sample (``clock_for(owner).monotonic()``);
+    # it stamps every visible_at value this event makes visible.
+    pending = pending_reasoning_deltas if pending_reasoning_deltas is not None else {}
+    event_key = _reasoning_summary_delta_key(payload) if payload is not None else (None, None, None)
+    if (
+        pending
+        and not _is_reasoning_summary_interleavable_event(event_type)
+        and not (event_type in _TTFT_REASONING_EVENT_TYPES and event_key in pending)
+    ):
+        visible_at = _finalize_ttft_reasoning_deltas(pending, now=now)
+        if visible_at is not None:
+            return visible_at
+    if event_type == "response.reasoning_summary_text.delta":
+        delta = payload.get("delta") if payload is not None else None
+        if not isinstance(delta, str):
+            return None
+        previous = pending.pop(event_key, None)
+        combined = (previous.text if previous is not None else "") + delta
+        cleaned = _strip_blank_html_comment_lines(combined)
+        if cleaned != combined:
+            if not cleaned:
+                return None
+            return previous.visible_at if previous is not None and previous.visible_at is not None else now
+        if _could_be_blank_html_comment_line(combined):
+            visible_at = None if previous is None else previous.visible_at
+            if visible_at is None and _visible_reasoning_prefix_before_blank_comment_candidate(combined):
+                visible_at = now
+            pending[event_key] = _TTFTReasoningDeltaState(combined, visible_at=visible_at)
+            return None
+        if not combined:
+            return None
+        return previous.visible_at if previous is not None and previous.visible_at is not None else now
+    if event_type == "response.reasoning_summary_text.done" and event_key in pending:
+        visible_at = _finalize_ttft_reasoning_deltas({event_key: pending.pop(event_key)}, now=now)
+        return visible_at
+    if event_type in _TTFT_TOOL_DELTA_EVENT_TYPES:
+        if payload is None:
+            return None
+        has_visible_part = any(
+            isinstance(payload.get(key), str) and bool(payload[key]) for key in ("delta", "arguments")
+        )
+        return now if has_visible_part else None
+    if event_type in _TTFT_EVENT_TYPES:
+        delta = payload.get("delta") if payload is not None else None
+        return now if isinstance(delta, str) and bool(delta) else None
+    if event_type not in {"response.output_item.added", "response.output_item.done"} or not isinstance(payload, dict):
+        return None
+    item = payload.get("item")
+    if not isinstance(item, dict) or item.get("type") not in _TTFT_OUTPUT_ITEM_TYPES:
+        return None
+    if item.get("type") == "custom_tool_call":
+        meaningful = any(isinstance(item.get(key), str) and bool(item[key]) for key in ("input", "arguments"))
+    else:
+        meaningful = any(item.get(key) not in (None, "", {}) for key in ("operation", "patch", "input"))
+    return now if meaningful else None
+
+
+def _is_ttft_event(
+    event_type: str | None,
+    payload: dict[str, JsonValue] | None,
+    pending_reasoning_deltas: dict[tuple[str | None, int | None, int | None], _TTFTReasoningDeltaState] | None = None,
+    *,
+    now: float,
+) -> bool:
+    return _ttft_event_visible_at(event_type, payload, pending_reasoning_deltas, now=now) is not None
+
+
+def _ttft_latency_ms_from_visible_at(visible_at: float | None, started_at: float) -> int | None:
+    return None if visible_at is None else max(0, int((visible_at - started_at) * 1000))
+
+
+def _ttft_event_latency_ms(
+    event_type: str | None,
+    payload: dict[str, JsonValue] | None,
+    pending_reasoning_deltas: dict[tuple[str | None, int | None, int | None], _TTFTReasoningDeltaState],
+    started_at: float,
+    *,
+    now: float,
+) -> int | None:
+    return _ttft_latency_ms_from_visible_at(
+        _ttft_event_visible_at(event_type, payload, pending_reasoning_deltas, now=now), started_at
+    )
+
+
+def _finalize_ttft_latency_ms(
+    pending_reasoning_deltas: dict[tuple[str | None, int | None, int | None], _TTFTReasoningDeltaState],
+    started_at: float,
+    *,
+    now: float,
+) -> int | None:
+    return _ttft_latency_ms_from_visible_at(
+        _finalize_ttft_reasoning_deltas(pending_reasoning_deltas, now=now), started_at
+    )
+
+
+# Stream frames whose parsed payload feeds a real per-event consumer:
+# lifecycle/terminal handling and usage settlement (created/queued/in_progress/
+# completed/failed/incomplete/error), parallel tool-call rewrite + duplicate
+# side-effect suppression (response.output_item.*), and text-done suppression
+# (response.output_text.done / response.content_part.done). Canonically framed
+# frames of any other type can relay upstream bytes verbatim once the TTFT
+# window is settled and no service-tier snapshot is present.
+_MUST_PARSE_STREAM_EVENT_TYPES = frozenset(
+    {
+        "response.created",
+        "response.queued",
+        "response.in_progress",
+        "response.completed",
+        "response.failed",
+        "response.incomplete",
+        "error",
+        "response.output_item.added",
+        "response.output_item.done",
+        "response.output_text.done",
+        "response.content_part.done",
+    }
+)
+# Raw-line gate for service-tier attribution: response snapshots carry
+# `"service_tier"` in their JSON, and a false positive (the substring inside
+# delta text) merely takes the full-parse path.
+_SERVICE_TIER_MARKER = '"service_tier"'
+
+
+def _verbatim_relay_event_type(
+    line: str,
+    latency_first_token_ms: int | None,
+    pending_reasoning_deltas: dict[tuple[str | None, int | None, int | None], _TTFTReasoningDeltaState],
+) -> str | None:
+    """Return the cheap event type when a stream frame can relay verbatim.
+
+    Eligible frames are canonically framed (leading ``event: <type>`` line,
+    single JSON-object ``data:`` line — see ``sse_event_type_from_block``),
+    outside the must-parse set, past the TTFT first-token window (including a
+    pending reasoning-delta window), and free of the service-tier marker.
+    Everything else returns ``None`` and takes the full parse +
+    ``format_sse_event`` path, preserving the EventSource framing guarantee
+    for data-only blocks.
+    """
+    if latency_first_token_ms is None or pending_reasoning_deltas:
+        return None
+    if _SERVICE_TIER_MARKER in line:
+        return None
+    event_type = sse_event_type_from_block(line)
+    if event_type is None or event_type in _MUST_PARSE_STREAM_EVENT_TYPES:
+        return None
+    return event_type
+
+
+def _bind_propagated_capacity_startup_wait(event: asyncio.Event) -> Token[asyncio.Event | None]:
+    return _PROPAGATED_CAPACITY_STARTUP_WAIT.set(event)
+
+
+def _reset_propagated_capacity_startup_wait(token: Token[asyncio.Event | None]) -> None:
+    _PROPAGATED_CAPACITY_STARTUP_WAIT.reset(token)
+
+
+def _bind_propagated_capacity_startup_ready(event: asyncio.Event) -> Token[asyncio.Event | None]:
+    return _PROPAGATED_CAPACITY_STARTUP_READY.set(event)
+
+
+def _reset_propagated_capacity_startup_ready(token: Token[asyncio.Event | None]) -> None:
+    _PROPAGATED_CAPACITY_STARTUP_READY.reset(token)
+
+
+def _signal_propagated_capacity_startup_wait() -> None:
+    ready_event = _PROPAGATED_CAPACITY_STARTUP_READY.get()
+    if ready_event is not None:
+        ready_event.clear()
+    event = _PROPAGATED_CAPACITY_STARTUP_WAIT.get()
+    if event is not None:
+        event.set()
+
+
+def _signal_propagated_capacity_startup_ready() -> None:
+    wait_event = _PROPAGATED_CAPACITY_STARTUP_WAIT.get()
+    if wait_event is not None:
+        wait_event.clear()
+    event = _PROPAGATED_CAPACITY_STARTUP_READY.get()
+    if event is not None:
+        event.set()
+
+
+def _bind_propagated_responses_service_cleanup_ready(event: asyncio.Event) -> Token[asyncio.Event | None]:
+    return _PROPAGATED_RESPONSES_SERVICE_CLEANUP_READY.set(event)
+
+
+def _reset_propagated_responses_service_cleanup_ready(token: Token[asyncio.Event | None]) -> None:
+    _PROPAGATED_RESPONSES_SERVICE_CLEANUP_READY.reset(token)
+
+
+def _signal_propagated_responses_service_cleanup_ready() -> None:
+    event = _PROPAGATED_RESPONSES_SERVICE_CLEANUP_READY.get()
+    if event is not None:
+        event.set()
+
+
+def _bind_propagated_responses_owner_forward_dispatched(event: asyncio.Event) -> Token[asyncio.Event | None]:
+    return _PROPAGATED_RESPONSES_OWNER_FORWARD_DISPATCHED.set(event)
+
+
+def _reset_propagated_responses_owner_forward_dispatched(token: Token[asyncio.Event | None]) -> None:
+    _PROPAGATED_RESPONSES_OWNER_FORWARD_DISPATCHED.reset(token)
+
+
+def _signal_propagated_responses_owner_forward_dispatched() -> None:
+    event = _PROPAGATED_RESPONSES_OWNER_FORWARD_DISPATCHED.get()
+    if event is not None:
+        event.set()
+
+
+def _bind_propagated_responses_owner_forward_rejected(event: asyncio.Event) -> Token[asyncio.Event | None]:
+    return _PROPAGATED_RESPONSES_OWNER_FORWARD_REJECTED.set(event)
+
+
+def _reset_propagated_responses_owner_forward_rejected(token: Token[asyncio.Event | None]) -> None:
+    _PROPAGATED_RESPONSES_OWNER_FORWARD_REJECTED.reset(token)
+
+
+def _signal_propagated_responses_owner_forward_rejected() -> None:
+    event = _PROPAGATED_RESPONSES_OWNER_FORWARD_REJECTED.get()
+    if event is not None:
+        event.set()
+
+
+def _account_selection_recovery_sleep_seconds_from_message(
+    message: str | None,
+    *,
+    error_code: str | None = None,
+    suppress_uncoded_local_selector_hint: bool = False,
+) -> float | None:
+    message = (message or "").strip()
+    if not message:
+        return None
+
+    lowered = message.lower()
+    if (
+        "require re-authentication" in lowered
+        or "all accounts are paused" in lowered
+        or "no accounts with a plan" in lowered
+        or "no accounts with available additional quota" in lowered
+        or "no fresh additional quota data" in lowered
+        or (
+            (error_code == "no_accounts" or (suppress_uncoded_local_selector_hint and error_code is None))
+            and lowered.startswith("rate limit exceeded. try again in")
+        )
+    ):
+        return None
+
+    retry_hint = _ACCOUNT_SELECTION_RETRY_HINT_RE.search(message)
+    if retry_hint is not None:
+        try:
+            hinted_seconds = float(retry_hint.group(1))
+        except ValueError:
+            hinted_seconds = _ACCOUNT_SELECTION_RECOVERY_DEFAULT_SLEEP_SECONDS
+        return min(
+            max(hinted_seconds, _ACCOUNT_SELECTION_RECOVERY_MIN_SLEEP_SECONDS),
+            _ACCOUNT_SELECTION_RECOVERY_MAX_SLEEP_SECONDS,
+        )
+
+    if "hit your spend cap set by the owner of your workspace" in lowered:
+        return _ACCOUNT_SELECTION_RECOVERY_DEFAULT_SLEEP_SECONDS
+
+    # A hard affinity row is an ownership constraint, so it must not spill to
+    # another account. Capacity/health transitions can nevertheless make the
+    # owner briefly unavailable; give that owner a short recovery window before
+    # surfacing a 503 rather than rebinding the logical session.
+    if error_code == "hard_affinity_saturated":
+        return _HARD_AFFINITY_RECOVERY_SLEEP_SECONDS
+
+    if error_code in _LOCAL_ACCOUNT_CAP_ERROR_CODES:
+        return _ACCOUNT_SELECTION_RECOVERY_DEFAULT_SLEEP_SECONDS
+
+    return None
+
+
+def _account_selection_recovery_sleep_seconds(selection: AccountSelection) -> float | None:
+    """The wait this selection failure earns before the caller re-selects.
+
+    ``hard_affinity_owner_excluded`` is the selector's proof that the hard
+    ``CODEX_SESSION`` owner it resolved is one of the caller's own
+    ``exclude_account_ids``. The owner cannot become selectable while that
+    exclusion holds and a hard row never spills to another account, so the
+    short owner-recovery window earns nothing here: every re-selection would
+    report the same ``hard_affinity_saturated`` until the request budget is
+    spent (7200s on the HTTP bridge), long after the client gave up. Fail
+    closed at once instead -- the same fail-closed the bridge already applies
+    when the request excludes the account its hard session is bound to
+    (``_require_http_bridge_bound_account_not_excluded``) -- and let the
+    client's own retry reach the owner with no exclusion. A genuinely
+    unavailable owner the caller did NOT exclude keeps its recovery wait.
+    """
+    if selection.hard_affinity_owner_excluded:
+        return None
+    return _account_selection_recovery_sleep_seconds_from_message(
+        selection.error_message,
+        error_code=selection.error_code,
+        suppress_uncoded_local_selector_hint=selection.account is None,
+    )
+
+
+def _account_capacity_wait_payload(
+    request_state: "_WebSocketRequestState | None",
+    *,
+    request_id: str | None,
+    reason: str | None,
+    retry_after_seconds: float | None,
+    started_at: float | None = None,
+    now: float,
+) -> dict[str, JsonValue]:
+    wait_started_at = request_state.account_capacity_wait_started_at if request_state is not None else started_at
+    # ``now`` must come from the clock that stamped ``wait_started_at``;
+    # callers pass their owner clock sample.
+    waited_seconds = int(max(0.0, now - wait_started_at)) if wait_started_at is not None else 0
+    payload: dict[str, JsonValue] = {
+        "type": "codex.keepalive",
+        "status": "waiting_for_account_capacity",
+        "request_id": request_id or (request_state.request_id if request_state is not None else None),
+        "waited_seconds": waited_seconds,
+    }
+    if reason:
+        payload["reason"] = reason
+    if retry_after_seconds is not None:
+        payload["retry_after_seconds"] = int(max(0.0, retry_after_seconds))
+    return payload
+
+
+async def _sleep_for_account_selection_recovery(
+    selection: AccountSelection,
+    *,
+    request_id: str | None,
+    kind: str,
+    request_stage: str,
+    model: str | None,
+    max_sleep_seconds: float | None = None,
+    request_state: "_WebSocketRequestState | None" = None,
+    heartbeat: Callable[[float], Awaitable[None]] | None = None,
+    scheduler: Scheduler,
+    clock: Clock,
+) -> bool:
+    sleep_seconds = _account_selection_recovery_sleep_seconds(selection)
+    if sleep_seconds is None:
+        return False
+    if max_sleep_seconds is not None:
+        if max_sleep_seconds <= 0:
+            return False
+        sleep_seconds = min(sleep_seconds, max_sleep_seconds)
+
+    if request_state is not None:
+        request_state.account_capacity_waiting = True
+        request_state.account_capacity_wait_reason = selection.error_message
+        request_state.account_capacity_wait_started_at = (
+            request_state.account_capacity_wait_started_at or clock.monotonic()
+        )
+        request_state.account_capacity_wait_retry_after_seconds = sleep_seconds
+
+    logger.info(
+        "Waiting for an account to recover before retrying selection request_id=%s kind=%s "
+        "request_stage=%s model=%s sleep_seconds=%.1f error=%s",
+        request_id,
+        kind,
+        request_stage,
+        model,
+        sleep_seconds,
+        selection.error_message,
+    )
+    remaining = sleep_seconds
+    try:
+        while remaining > 0:
+            if heartbeat is not None:
+                await heartbeat(remaining)
+            chunk = min(remaining, _ACCOUNT_SELECTION_RECOVERY_HEARTBEAT_SECONDS)
+            await scheduler.sleep(chunk)
+            remaining -= chunk
+    finally:
+        if request_state is not None:
+            request_state.account_capacity_waiting = False
+            request_state.account_capacity_wait_reason = None
+            request_state.account_capacity_wait_retry_after_seconds = None
+    return True
+
+
+async def _call_with_supported_optional_kwargs(
+    func: Callable[..., Awaitable[Any]],
+    /,
+    *args: Any,
+    optional_kwargs: Mapping[str, Any],
+    **required_kwargs: Any,
+) -> Any:
+    return await func(*args, **_supported_optional_kwargs(func, optional_kwargs, required_kwargs))
+
+
+def _supported_optional_kwargs(
+    func: Callable[..., Any],
+    optional_kwargs: Mapping[str, Any],
+    required_kwargs: Mapping[str, Any],
+) -> dict[str, Any]:
+    kwargs = dict(required_kwargs)
+    kwargs.update(optional_kwargs)
+    if optional_kwargs:
+        try:
+            signature = inspect.signature(func)
+        except (TypeError, ValueError):
+            signature = None
+        accepts_var_keyword = signature is not None and any(
+            parameter.kind is inspect.Parameter.VAR_KEYWORD for parameter in signature.parameters.values()
+        )
+        if signature is not None and not accepts_var_keyword:
+            for name in optional_kwargs:
+                if name not in signature.parameters:
+                    kwargs.pop(name, None)
+    return kwargs
+
+
+_CONVERSATION_HEADERS_BY_USERAGENT_PREFIX = (
+    ("opencode", ("x-parent-session-id", "x-opencode-session", "x-session-id", "x-session-affinity")),
+    ("codex", ("thread-id",)),
+)
+
+
+def _request_log_useragent_fields(headers: Mapping[str, str]) -> tuple[str | None, str | None]:
+    raw_useragent = next((value for key, value in headers.items() if key.lower() == "user-agent"), None)
+    if raw_useragent is None:
+        return None, None
+    useragent = raw_useragent.strip()
+    if not useragent:
+        return None, None
+    first_token = useragent.split(maxsplit=1)[0]
+    useragent_group = first_token.split("/", 1)[0].strip() or None
+    if "/" in useragent:
+        useragent_group = useragent.split("/", 1)[0]
+    return useragent, useragent_group
+
+
+def _request_log_client_fields(
+    headers: Mapping[str, str],
+) -> tuple[str | None, str | None, str | None]:
+    useragent, useragent_group = _request_log_useragent_fields(headers)
+    normalized_useragent = (useragent or "").strip().casefold()
+    normalized_headers = {key.casefold(): value for key, value in headers.items()}
+    for prefix, header_names in _CONVERSATION_HEADERS_BY_USERAGENT_PREFIX:
+        if normalized_useragent.startswith(prefix):
+            for header_name in header_names:
+                value = normalized_headers.get(header_name)
+                if value and (conversation_id := value.strip()):
+                    return useragent, useragent_group, conversation_id
+            break
+    return useragent, useragent_group, None
+
+
+class _RetryableStreamError(Exception):
+    def __init__(self, code: str, error: UpstreamError, *, exclude_account: bool = False) -> None:
+        super().__init__(code)
+        self.code = code
+        self.error = error
+        self.exclude_account = exclude_account
+
+
+class _WebSocketConnectFailureEmitted(Exception):
+    pass
+
+
+class _WebSocketTransientRefreshFailover(Exception):
+    """Signals the WebSocket connect loop to fail over after a transient refresh.
+
+    Raised from the connect attempt when a non-permanent, transport-level
+    ``RefreshError`` (for example ``refresh_claim_timeout`` when another replica
+    holds the account's refresh claim) reaches the connect path and the request
+    is not bound to a preferred/required account. The loop releases the skipped
+    account's stream lease, excludes it, and reselects a healthy account instead
+    of surfacing a bogus 401 ``invalid_api_key``.
+    """
+
+    def __init__(self, account_id: str) -> None:
+        super().__init__(account_id)
+        self.account_id = account_id
+
+
+# ---- Refresh-claim contention failover helpers -----------------------------
+#
+# A transient cross-replica refresh contention (``is_transient_refresh_contention``:
+# ONLY the benign ``refresh_claim_timeout`` claim-contention code and the
+# post-exchange ``token_persist_conflict`` / ``status_downgrade_conflict`` CAS
+# codes, NOT the broad ``transport_error`` flag) means the account's credentials
+# are healthy and only its refresh claim/persist lost to a peer replica. These
+# helpers let the proxy previsible-unary failover surface a retryable
+# ``upstream_unavailable`` WITHOUT recording an account-health penalty, while a
+# genuine OAuth transport failure keeps its normal health accounting.
+
+_FAILED_ACCOUNT_ATTR = "_codex_lb_failed_account"
+_CLAIM_CONTENTION_UNPENALIZED_ATTR = "_codex_lb_claim_contention_unpenalized"
+
+
+class _RefreshFailoverProxy(Protocol):
+    async def _handle_stream_error(
+        self,
+        account: Account,
+        error: Any,
+        code: str,
+        http_status: int | None = None,
+        *,
+        privacy_policy: CodexControlRequestPrivacyPolicy = CodexControlRequestPrivacyPolicy.STANDARD,
+        retry_after_seconds: float | None = None,
+        burst_cooldown_recorded: bool = False,
+        upstream_http_status: int | None = None,
+    ) -> Any: ...
+
+
+def is_claim_contention_unpenalized(exc: object) -> bool:
+    """True when ``exc`` is a retryable ``upstream_unavailable`` from claim contention.
+
+    The account is healthy (a peer replica held its refresh claim), so callers
+    MUST NOT record an account-health penalty for it.
+    """
+    return bool(getattr(exc, _CLAIM_CONTENTION_UNPENALIZED_ATTR, False))
+
+
+def raise_proxy_unavailable_for_claim_contention(message: str, account: Account) -> NoReturn:
+    """Raise a retryable ``upstream_unavailable`` marked as (unpenalized) claim contention."""
+    exc = ProxyResponseError(502, openai_error("upstream_unavailable", message))
+    setattr(exc, _FAILED_ACCOUNT_ATTR, account)
+    setattr(exc, _CLAIM_CONTENTION_UNPENALIZED_ATTR, True)
+    raise exc
+
+
+def _raise_proxy_unavailable_for_account(message: str, account: Account) -> NoReturn:
+    exc = ProxyResponseError(502, openai_error("upstream_unavailable", message))
+    setattr(exc, _FAILED_ACCOUNT_ATTR, account)
+    raise exc
+
+
+async def failover_after_previsible_refresh_error(
+    proxy: _RefreshFailoverProxy,
+    exc: Exception,
+    current: Account,
+    *,
+    attempt: int,
+    max_account_attempts: int,
+    strict_account_id: str | None,
+    excluded_account_ids: set[str],
+    select_next_account: Callable[[set[str]], Awaitable[AccountSelection]],
+    request_id: str,
+    kind: str,
+    privacy_policy: CodexControlRequestPrivacyPolicy = CodexControlRequestPrivacyPolicy.STANDARD,
+) -> Account:
+    """Pick the next account after a previsible-unary freshness/connect failure.
+
+    Consolidates the transient ``RefreshError`` claim-contention and transport
+    paths plus raw aiohttp/connect errors into one decision:
+
+    * Transient refresh contention (``is_transient_refresh_contention``) is ALWAYS
+      retryable and NEVER penalizes the skipped account (its credentials are
+      healthy; only its refresh claim/persist lost to a peer). This covers BOTH
+      benign claim contention and a post-exchange persist/status CAS conflict; the
+      latter is logged distinctly (a rarer, more-serious internal race). On
+      strict-pin / attempt exhaustion or an empty selection it raises a
+      claim-contention-marked ``upstream_unavailable`` that the caller's terminal
+      ``_handle_proxy_error`` skips penalizing.
+    * A genuine OAuth ``transport_error`` refresh failure or a raw aiohttp/connect
+      failure keeps its health accounting: failover is gated on the message text
+      and the skipped account is penalized via ``_handle_stream_error`` so a
+      persistently broken account backs off.
+
+    Returns the next account to try; raises otherwise.
+    """
+    from app.modules.proxy._service.streaming.helpers import _should_retry_transient_stream_error
+
+    claim = isinstance(exc, RefreshError) and is_transient_refresh_contention(exc)
+    contention_kind = refresh_contention_kind(exc) if isinstance(exc, RefreshError) else None
+    message = getattr(exc, "message", None) or str(exc) or "Request to upstream timed out"
+    if contention_kind == "persist_conflict":
+        # Post-exchange guarded-write CAS conflict: rarer/more-serious than benign
+        # claim contention, so surface it distinctly (it still fails over with no
+        # penalty, identically to benign contention).
+        logger.warning(
+            "%s refresh post-exchange persist conflict code=%s request_id=%s account_id=%s",
+            kind,
+            getattr(exc, "code", None),
+            request_id,
+            "<redacted>" if privacy_policy.redacts_sensitive_details else current.id,
+            exc_info=None if privacy_policy.redacts_sensitive_details else True,
+        )
+    else:
+        logger.warning(
+            "%s refresh %s request_id=%s account_id=%s",
+            kind,
+            "claim contention" if claim else "failed",
+            request_id,
+            "<redacted>" if privacy_policy.redacts_sensitive_details else current.id,
+            exc_info=None if privacy_policy.redacts_sensitive_details else True,
+        )
+    if not claim and not _should_retry_transient_stream_error("upstream_unavailable", message):
+        _raise_proxy_unavailable_for_account(message, current)
+
+    def _give_up() -> NoReturn:
+        if claim:
+            raise_proxy_unavailable_for_claim_contention(message, current)
+        _raise_proxy_unavailable_for_account(message, current)
+
+    if (strict_account_id is not None and current.id == strict_account_id) or attempt >= max_account_attempts:
+        _give_up()
+    excluded_account_ids.add(current.id)
+    selection = await select_next_account(excluded_account_ids)
+    selected_account = selection.account
+    if selected_account is None:
+        _give_up()
+    assert selected_account is not None
+    if not claim:
+        # Genuine transport / connect failure: penalize the skipped account so a
+        # persistently broken account backs off. Claim contention never penalizes.
+        if privacy_policy.redacts_sensitive_details:
+            await proxy._handle_stream_error(
+                current,
+                {"message": message},
+                "upstream_unavailable",
+                privacy_policy=privacy_policy,
+            )
+        else:
+            await proxy._handle_stream_error(current, {"message": message}, "upstream_unavailable")
+    return selected_account
+
+
+class _TransientStreamError(Exception):
+    """Transient upstream error (e.g. 500 server_error) - retry on same account first."""
+
+    def __init__(
+        self,
+        code: str,
+        error: UpstreamError,
+        *,
+        preserve_on_selection_exhausted: bool = False,
+        account_health_error: bool = False,
+    ) -> None:
+        super().__init__(code)
+        self.code = code
+        self.error = error
+        self.preserve_on_selection_exhausted = preserve_on_selection_exhausted
+        self.account_health_error = account_health_error
+
+
+class _TerminalStreamError(Exception):
+    def __init__(self, code: str, error: UpstreamError) -> None:
+        super().__init__(code)
+        self.code = code
+        self.error = error
+
+
+@dataclass
+class _ApiKeyReservationTouchState:
+    last_touch_at: float
+
+
+@dataclass
+class _StreamSettlement:
+    """Populated by _stream_once(), consumed by _stream_with_retry() for reservation settlement."""
+
+    status: str = "success"
+    model: str = ""
+    service_tier: str | None = None
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    cached_input_tokens: int | None = None
+    error_code: str | None = None
+    error_message: str | None = None
+    error: UpstreamError | None = None
+    account_health_error: bool = False
+    settlement_order_required: bool = False
+    record_success: bool = True
+    downstream_visible: bool = False
+    downstream_text_visible: bool = False
+    response_id: str | None = None
+    usage_settlement_transferred: bool = False
+    # Monotonic instant the upstream terminal frame (``response.completed`` /
+    # ``response.failed`` / ``response.incomplete`` / ``error``) was parsed by
+    # ``_stream_once``, before it is yielded downstream. The throughput cohort
+    # sample ends its generation span here; the row's ``latency_ms`` keeps
+    # measuring to the generator's close (downstream flush, upstream EOF).
+    upstream_terminal_at: float | None = None
+
+    def reset(self) -> None:
+        fresh = type(self)()
+        self.__dict__.update(fresh.__dict__)
+
+
+def _stream_settlement_error_payload(settlement: _StreamSettlement) -> UpstreamError:
+    if settlement.error is not None:
+        return settlement.error
+    payload: UpstreamError = {}
+    if settlement.error_message:
+        payload["message"] = settlement.error_message
+    else:
+        payload["message"] = "Upstream error"
+    return payload
+
+
+def _consume_api_key_reservation_heartbeat_result(task: asyncio.Task[None]) -> None:
+    try:
+        task.result()
+    except asyncio.CancelledError:
+        pass
+    except Exception:
+        logger.warning("API key reservation heartbeat task failed during cancellation", exc_info=True)
+
+
+@dataclass(frozen=True, slots=True)
+class _RequestLogFailureMetadata:
+    failure_phase: str | None = None
+    failure_detail: str | None = None
+    failure_exception_type: str | None = None
+    upstream_status_code: int | None = None
+    upstream_error_code: str | None = None
+    bridge_stage: str | None = None
+
+
+@dataclass(slots=True)
+class _HTTPBridgeCompletedDeliveryScope:
+    active: bool = False
+    terminal_enqueued: bool = False
+
+
+@dataclass(slots=True)
+class _DeferredAccountBackoffLifecycle:
+    reservation: ApiKeyUsageReservationData | None
+    pending_backoffs: dict[str, Account] = field(default_factory=dict)
+    settlement_owned: bool = False
+    settlement_confirmed: bool = False
+
+
+@dataclass(slots=True)
+class _DeferredAccountBackoffTracker:
+    current_lifecycle: _DeferredAccountBackoffLifecycle | None = None
+
+
+@dataclass(slots=True)
+class _DeferredKeyedStreamHealthPenalty:
+    """Classified account-health write deferred until reservation settlement."""
+
+    account: Account
+    error: UpstreamError
+    code: str
+
+
+@dataclass(eq=False, slots=True)
+class _HTTPBridgeResponseCreateAttempt:
+    ordinal: int
+    disarmed: bool = False
+    response_observed: bool = False
+    # A non-terminal response event (a deferred-reasoning prelude, for
+    # example) proves the attempt was answered midstream even when ordinary
+    # event accounting was deliberately skipped. A later terminal failure
+    # frame must then not be charged as a pre-response strike.
+    non_terminal_response_observed: bool = False
+    retry_circuit_failure_recorded: bool = False
+    retry_circuit_failure_settled: anyio.Event | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class _HTTPBridgeRetryCircuitAttemptSelection:
+    kind: Literal["absent", "eligible", "recorded", "settled", "ineligible"]
+    attempts: tuple[_HTTPBridgeResponseCreateAttempt, ...] = ()
+
+    def __post_init__(self) -> None:
+        carries_attempts = self.kind in {"eligible", "recorded", "settled"}
+        if carries_attempts != bool(self.attempts):
+            raise ValueError(f"invalid retry-circuit attempt selection: {self.kind}")
+
+    @property
+    def attempt(self) -> _HTTPBridgeResponseCreateAttempt | None:
+        return self.attempts[0] if len(self.attempts) == 1 else None
+
+    @property
+    def ambiguous(self) -> bool:
+        return len(self.attempts) > 1
+
+
+@dataclass
+class _WebSocketRequestState:
+    request_id: str
+    model: str | None
+    service_tier: str | None
+    reasoning_effort: str | None
+    api_key_reservation: ApiKeyUsageReservationData | None
+    started_at: float
+    responses_lite_model: str | None = None
+    latency_first_token_ms: int | None = None
+    ttft_reasoning_deltas: dict[tuple[str | None, int | None, int | None], _TTFTReasoningDeltaState] = field(
+        default_factory=dict
+    )
+    latency_response_created_ms: int | None = None
+    latency_first_upstream_event_ms: int | None = None
+    latency_response_create_gate_wait_ms: int | None = None
+    latency_bridge_queue_wait_ms: int | None = None
+    # Monotonic instant the upstream terminal event (``response.completed`` /
+    # ``response.failed`` / ``response.incomplete`` / ``error``) was parsed for
+    # this turn, before terminal bookkeeping, API-key settlement and cleanup.
+    # The throughput cohort sample ends its generation span here; the row's
+    # ``latency_ms`` keeps measuring to the end of the finalizer.
+    upstream_terminal_at: float | None = None
+    response_create_gate_wait_started_at: float | None = None
+    # Monotonic time immediately before the current upstream response.create
+    # send. Retries replace this value so admission wait and prior attempts do
+    # not age a fresh send into the eventless owner deadline.
+    response_create_sent_at: float | None = None
+    response_create_attempt_count: int = 0
+    response_create_attempt: _HTTPBridgeResponseCreateAttempt | None = None
+    bridge_queue_wait_started_at: float | None = None
+    # Monotonic deadline of the original bridge request budget. Retry and
+    # recovery paths re-prepare request states with a fresh started_at, so
+    # budget clamps must use this instead of recomputing from started_at.
+    bridge_request_deadline: float | None = None
+    prewarm_status: str | None = None
+    prewarm_latency_ms: int | None = None
+    session_previous_gap_ms: int | None = None
+    request_log_id: str | None = None
+    archive_request_id: str | None = None
+    requested_service_tier: str | None = None
+    actual_service_tier: str | None = None
+    response_id: str | None = None
+    awaiting_response_created: bool = False
+    event_queue: asyncio.Queue[str | None] | None = None
+    transport: str = _REQUEST_TRANSPORT_WEBSOCKET
+    upstream_transport: str | None = _REQUEST_TRANSPORT_WEBSOCKET
+    enforce_openai_sdk_contract: bool = True
+    propagate_http_errors: bool = False
+    request_kind: str = "normal"
+    connection_request_kind: str | None = None
+    generate_false_prewarm: bool = False
+    api_key: ApiKeyData | None = None
+    # The client's requested model captured before api-key enforcement
+    # normalized aliases (``gpt-5-high`` -> ``gpt-5``), with the key's
+    # ``enforced_model`` substituted and the fast-mode correction applied,
+    # exactly like the HTTP path's ``raw_source_model``. Consumed only by the
+    # WebSocket source-ownership guards; it must never reach the upstream
+    # wire payload. ``None`` on request states that were not built by
+    # ``_prepare_websocket_response_create_request`` (replays, archives),
+    # which keeps those on the normalized-model check.
+    raw_source_model: str | None = None
+    # True when the Codex HTTP route structurally excludes this request from
+    # model-source routing: a terminal compaction trigger or ``input_file``
+    # references pinned to the uploading subscription account. Previous
+    # response ownership is recorded separately after continuity lookup.
+    source_route_excluded: bool = False
+    request_usage_budget: ApiKeyRequestUsageBudget | None = None
+    request_text: str | None = None
+    replay_count: int = 0
+    # Counts only the one extra replay permitted after the initial recovery
+    # replay when the replacement upstream socket also closes cleanly before
+    # producing any response event.
+    clean_close_replay_count: int = 0
+    clean_close_retry_in_progress: bool = False
+    clean_close_retry_result: bool | None = None
+    clean_close_retry_close_generation: int | None = None
+    auth_replay_count: int = 0
+    auth_replay_counts_by_account: dict[str, int] = field(default_factory=dict)
+    force_refresh_account_id: str | None = None
+    excluded_account_ids: set[str] = field(default_factory=set)
+    # A narrowly classified pre-acceptance account/model rejection may move
+    # once to another account. Keep the original upstream error until that
+    # replacement connection is established so an empty replacement pool does
+    # not turn the upstream 400 into a proxy-generated 5xx/no-accounts error.
+    precreated_replay_reason: str | None = None
+    precreated_replay_account_id: str | None = None
+    skip_request_log: bool = False
+    previous_response_id: str | None = None
+    session_id: str | None = None
+    # Session headers provide locality, but only a previous response or
+    # explicit turn-state header guarantees continuity for stale recovery.
+    hard_continuity_anchor: bool = False
+    proxy_injected_previous_response_id: bool = False
+    # The durable lookup carried an anchor, but its owner was already stale,
+    # ownerless, or lease-expired when this request arrived.  Such a request
+    # must not be presented to the client as a retryable upstream timeout.
+    durable_owner_dead: bool = False
+    # True only when the client's own incoming payload (before this anchor was
+    # injected or trimmed) already looked like a full conversation resend
+    # (``_http_bridge_payload_looks_like_full_resend``). Deliberately weaker
+    # than ``fresh_upstream_request_is_retry_safe``: it does not require the
+    # exact-manifest/retained-output proof that field needs for an in-place
+    # same-request replay, only that the client is a resend-capable client at
+    # all. Used to decide whether it is safe to invalidate a durable session's
+    # stored anchor after this request proves eventless -- a client that
+    # already resends full history on its own can recover unanchored; a
+    # genuine delta-only client has no other way to convey prior context and
+    # must stay anchored.
+    proxy_injected_anchor_had_full_resend_payload: bool = False
+    # Process-local denial generation captured before any canonical session
+    # exists. A detached predecessor can reject the anchor while the request
+    # is waiting for owner resolution; retain that generation through retries
+    # so the successor's final dispatch fence still fails closed.
+    denied_proxy_injected_anchor_fence_generation_at_prepare: int | None = None
+    # Generation equality alone cannot distinguish a request captured after a
+    # denial from one captured before it. Preserve the tombstone observation on
+    # the prepared request so a stale durable lookup cannot be redispatched.
+    denied_proxy_injected_anchor_fence_response_id: str | None = None
+    denied_proxy_injected_anchor_fence_request_id: str | None = None
+    denied_proxy_injected_anchor_fence_was_already_denied: bool = False
+    expose_stale_previous_response_classifier: bool = False
+    fresh_upstream_request_text: str | None = None
+    # True only when ``fresh_upstream_request_text`` contains a *safe* pre-
+    # injection form of this request that can be replayed as a fresh turn.
+    # Durable-anchor injection captures the original unanchored full-resend
+    # payload, so dropping the anchor and replaying is equivalent to the
+    # client's own retry. Session-level anchor injection does not set this:
+    # the original payload may have omitted history the conversation depended
+    # on, and dropping the anchor there would silently turn a continuation into
+    # a context-free fresh turn.
+    fresh_upstream_request_is_retry_safe: bool = False
+    # Memo for the account installation-id stamp applied to ``request_text`` /
+    # ``fresh_upstream_request_text`` on the HTTP bridge submit path. The stamp
+    # is re-applied at several submit and retry sites; these fields remember the
+    # exact ``str`` objects the last stamp returned for ``codex_installation_id``
+    # so an already-stamped object is recognised by identity instead of being
+    # decoded and re-encoded again. Every text rewrite yields a new ``str``
+    # object and an account swap changes the id, so both miss automatically.
+    installation_stamp_installation_id: str | None = None
+    installation_stamp_text: str | None = None
+    installation_stamp_fresh_text: str | None = None
+    # Set only on the internally constructed one-shot request that replaces an
+    # explicitly rejected stale anchor with a verified full-history payload.
+    # It may bypass an older hard-key retry circuit without deleting that
+    # circuit or weakening admission for ordinary client retries.
+    verified_stale_anchor_replay: bool = False
+    # Snapshot of the hard-key circuit observed when the stale-anchor replay
+    # was authorized. ``captured=True`` with ``generation=None`` proves that no
+    # circuit existed; a newer local/durable failure must suppress submit.
+    verified_stale_anchor_retry_circuit_generation_captured: bool = False
+    verified_stale_anchor_retry_circuit_key: _HTTPBridgeSessionKey | None = None
+    verified_stale_anchor_retry_circuit_generation: tuple[int, float, int, float, int, float, float] | None = None
+    verified_stale_anchor_quarantine_generation: int | None = None
+    # The exact half-open lease this request's admission claimed (0.0 when
+    # it claimed none); released by the submit finalizer whenever the probe
+    # was never dispatched, so no pre-dispatch exit can strand the lease.
+    claimed_half_open_until: float = 0.0
+    # True while the submit owns an admission-waiter registration taken at
+    # submit entry, before the retry-circuit gate, that the dispatch path has
+    # not yet taken over. It keeps the turn visible to a concurrent
+    # cooldown-suppressed sibling deciding whether the shared session is
+    # idle; every pre-dispatch exit releases it.
+    admission_waiter_preregistered: bool = False
+    # Stable fingerprint used by the durable recovery-attempt journal. It is
+    # populated only for a proof-gated fresh replay candidate.
+    recovery_attempt_fingerprint: str | None = None
+    recovery_attempt_session_id: str | None = None
+    recovery_attempt_owner_epoch: int | None = None
+    # True when recovery already atomically claimed the journal row as
+    # REPLAYED. Claimed replays must not be re-journaled at dispatch.
+    recovery_attempt_claimed: bool = False
+    # Set once the upstream send is attempted, including an ambiguous send
+    # failure. Pre-dispatch admission/setup failures may safely roll back a
+    # claimed recovery journal; an attempted send must remain consumed.
+    recovery_attempt_dispatched: bool = False
+    recovery_attempt_event_observed: bool = False
+    # Durable operation identity for a continuity-bound response.create. It is
+    # stable across client reconnects with the same parent response and body.
+    operation_id: str | None = None
+    operation_fingerprint: str | None = None
+    operation_parent_response_id: str | None = None
+    operation_registered: bool = False
+    # Account-neutral durable recovery keeps the original operation identity
+    # while asking request submission to rebind it to the replacement session.
+    operation_rebind_required: bool = False
+    # True after an existing UNKNOWN operation is claimed for this attempt.
+    # If admission fails before send, cleanup must restore UNKNOWN rather than
+    # treating the pre-existing row like a newly-created operation.
+    # True only when this request created the durable operation row. A
+    # pre-dispatch admission failure may remove that row; an existing row
+    # represents an ambiguous upstream attempt and must remain fenced.
+    operation_created: bool = False
+    operation_rebound: bool = False
+    operation_rebound_from_session_id: str | None = None
+    operation_rebound_from_account_id: str | None = None
+    operation_rebound_from_model: str | None = None
+    operation_rebound_from_parent_response_id: str | None = None
+    operation_replay: bool = False
+    operation_dispatched: bool = False
+    # Last response identity successfully written to the durable operation.
+    # Retry setup may clear the active response before a replacement is
+    # acknowledged, but fallback settlement must still fence against this ID.
+    operation_persisted_response_id: str | None = None
+    # Responses-Lite model advertised by ``fresh_upstream_request_text``. A
+    # fresh replay built from a trusted marker-only frame has the reserved
+    # marker stripped, so swapping to the fresh body must also swap this onto
+    # ``responses_lite_model``; otherwise the replay's ``response.created``
+    # would be recorded as a Lite acceptance for a non-Lite upstream request.
+    fresh_upstream_request_responses_lite_model: str | None = None
+    request_stage: str = "first_turn"
+    preferred_account_id: str | None = None
+    # Once an account-bound body has been dispatched, retries remain pinned to
+    # that owner even when stale-anchor recovery removes previous_response_id.
+    replay_required_account_id: str | None = None
+    require_security_work_authorized: bool = False
+    durable_capability_lineage_required: bool = False
+    file_required_preferred_account: bool = False
+    bridge_soft_capacity_reroute_allowed: bool = False
+    error_code_override: str | None = None
+    error_message_override: str | None = None
+    error_type_override: str | None = None
+    error_param_override: OpenAIErrorParam | JsonValue | None = None
+    failure_phase_override: str | None = None
+    failure_detail_override: str | None = None
+    upstream_error_code_override: str | None = None
+    error_http_status_override: int | None = None
+    response_event_count: int = 0
+    last_upstream_activity_at: float | None = None
+    upstream_model_output_seen: bool = False
+    # Terminal WebSocket error sanitization records continuity telemetry once;
+    # later serializers preserve the normalized fields without recording it a
+    # second time.
+    websocket_terminal_error_fields_sanitized: bool = False
+    previous_response_not_found_rewritten: bool = False
+    # A canonical stale-anchor code with malformed present ``param`` may be
+    # matched for masking, but must never authorize replay.
+    previous_response_not_found_recovery_blocked: bool = False
+    previous_response_owner_lookup_source: str | None = None
+    previous_response_owner_lookup_outcome: str | None = None
+    previous_response_owner_requested_at: datetime | None = None
+    previous_response_owner_session_id: str | None = None
+    # Subscription account proven to own ``previous_response_id`` by the
+    # continuity index/request-log lookup. Identifier syntax is never used as
+    # an ownership signal, so ``None`` leaves configured source routing intact.
+    previous_response_owner_account_id: str | None = None
+    response_create_gate_acquired: bool = False
+    response_create_gate: asyncio.Semaphore | None = None
+    response_create_admission: AdmissionLease | None = None
+    response_create_admission_reacquire_required: bool = False
+    account_response_create_lease: AccountLease | None = None
+    account_response_create_release: Callable[[AccountLease | None], Coroutine[Any, Any, None]] | None = None
+    websocket_stream_lease: AccountLease | None = None
+    affinity_policy: _AffinityPolicy = field(default_factory=_AffinityPolicy)
+    affinity_observation: AffinityObservation | None = None
+    thread_affinity_last_touch_at: float = field(default_factory=time.monotonic)
+    suppressed_duplicate_tool_call: bool = False
+    pending_function_call_ids: list[str] = field(default_factory=list)
+    pending_tool_call_types: dict[str, str] = field(default_factory=dict)
+    added_tool_call_types: dict[str, str] = field(default_factory=dict)
+    tool_call_manifest_invalid: bool = False
+    seen_tool_call_keys: dict[ToolCallDedupeKey, None] = field(default_factory=dict)
+    input_item_count: int = 0
+    input_full_fingerprint: str | None = None
+    api_key_reservation_last_touch_at: float = field(default_factory=time.monotonic)
+    api_key_reservation_heartbeat_stop: asyncio.Event | None = None
+    api_key_reservation_heartbeat_task: asyncio.Task[None] | None = None
+    upstream_proxy_route_mode: str | None = None
+    upstream_proxy_pool_id: str | None = None
+    upstream_proxy_endpoint_id: str | None = None
+    upstream_proxy_fallback_used: bool | None = None
+    upstream_proxy_fail_closed_reason: str | None = None
+    useragent: str | None = None
+    useragent_group: str | None = None
+    conversation_id: str | None = None
+    # The Responses payload's own ``conversation``, distinct from the client
+    # log's ``conversation_id`` above. It is account-scoped continuity with no
+    # dedicated owner index, so the raw path cannot prove the bridge session's
+    # owner for it.
+    payload_conversation_bound: bool = False
+    client_ip: str | None = None
+    downstream_visible: bool = False
+    last_downstream_sequence_number: int | None = None
+    # Confirmed pre-dispatch account-route failures must not mutate account
+    # health while this request's API-key reservation is still live. The
+    # account objects are keyed by id so repeated connect attempts cannot
+    # stack the same backoff floor more than once before settlement.
+    deferred_account_error_backoffs: dict[str, Account] = field(default_factory=dict)
+    deferred_account_backoff_tracker: _DeferredAccountBackoffTracker | None = None
+    deferred_account_backoff_lifecycle: _DeferredAccountBackoffLifecycle | None = None
+    # Classified health writes (mark_rate_limit / mark_quota_exceeded /
+    # record_error) deferred by keyed pre-created retry branches until this
+    # request's API-key reservation settles or its fallback release commits
+    # (settlement-ordering invariant). Entries drop unapplied when neither
+    # confirms.
+    deferred_keyed_stream_health: list[_DeferredKeyedStreamHealthPenalty] = field(default_factory=list)
+    deferred_reasoning_downstream_texts: list[str] = field(default_factory=list)
+    suppress_next_created_downstream: bool = False
+    # Armed together with the created suppression when the client already saw
+    # ``response.in_progress`` from the failed attempt, so the replay's
+    # duplicate prelude frame is dropped and the lifecycle stays single.
+    suppress_next_in_progress_downstream: bool = False
+    replay_downstream_response_id: str | None = None
+    draining_until_terminal: bool = False
+    completed_delivery_scope: _HTTPBridgeCompletedDeliveryScope | None = None
+    # Exactly-once reservation settlement for terminal HTTP bridge events
+    # (issue #1594). "claimed" marks a request popped from pending ownership
+    # whose in-flight terminal bookkeeping continuation exclusively owns
+    # settlement; "abandoned" marks a claim whose continuation aborted and
+    # whose shielded abort settlement also failed, allowing a later detach to
+    # reclaim settlement; None means unclaimed or settled.
+    terminal_settlement_phase: Literal["claimed", "abandoned"] | None = None
+    account_capacity_waiting: bool = False
+    account_capacity_wait_suppress_keepalive: bool = False
+    account_capacity_wait_reason: str | None = None
+    account_capacity_wait_started_at: float | None = None
+    account_capacity_wait_retry_after_seconds: float | None = None
+    capacity_startup_wait_event: asyncio.Event | None = None
+    capacity_startup_ready_event: asyncio.Event | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class _HTTPBridgeSessionKey:
+    affinity_kind: str
+    affinity_key: str
+    api_key_id: str | None
+    strength: Literal["hard", "soft"] | None = None
+
+    def __post_init__(self) -> None:
+        strength = self.strength
+        if strength is None:
+            strength = "hard" if self.affinity_kind in _HARD_HTTP_BRIDGE_AFFINITY_KINDS else "soft"
+        object.__setattr__(self, "strength", strength)
+
+
+@dataclass(frozen=True, slots=True)
+class _HTTPBridgeOwnerForward:
+    owner_instance: str
+    owner_endpoint: str
+    key: _HTTPBridgeSessionKey
+
+
+@dataclass(slots=True)
+class _HTTPBridgeSession:
+    key: _HTTPBridgeSessionKey
+    headers: dict[str, str]
+    affinity: _AffinityPolicy
+    request_model: str | None
+    account: Account
+    upstream: UpstreamWebSocket
+    upstream_control: _WebSocketUpstreamControl
+    pending_requests: deque[_WebSocketRequestState]
+    pending_lock: anyio.Lock
+    response_create_gate: asyncio.Semaphore
+    queued_request_count: int
+    last_used_at: float
+    idle_ttl_seconds: float
+    # Wakes a reader that began an unbounded receive before the first request
+    # was enqueued. The reader keeps one receive task alive across wakeups.
+    upstream_reader_wakeup: asyncio.Event = field(default_factory=asyncio.Event)
+    unanchored_reservation_id: str | None = None
+    admission_waiter_count: int = 0
+    request_service_tier: str | None = None
+    catalog_omission_quota_admission: CatalogOmissionQuotaAdmission | None = None
+    lifecycle_lock: anyio.Lock = field(default_factory=fast_lock)
+    recovery_alias_lock: anyio.Lock = field(default_factory=fast_lock)
+    api_key: ApiKeyData | None = None
+    codex_session: bool = False
+    prewarmed: bool = False
+    access_token_expires_at: float | None = None
+    prewarm_lock: anyio.Lock | None = None
+    upstream_turn_state: str | None = None
+    downstream_turn_state: str | None = None
+    downstream_turn_state_aliases: set[str] = field(default_factory=set)
+    previous_response_ids: set[str] = field(default_factory=set)
+    # The live session keeps only its current denial tombstone.  Historical
+    # ids remain in the process-local fence ledger while prepared requests pin
+    # them, so this carrier cannot grow with every denied sibling anchor.
+    denied_proxy_injected_anchor_ids: set[str] = field(default_factory=set)
+    # Denials whose durable or local alias cleanup still needs a retry.  This
+    # is separate from the current tombstone carrier: a sibling-advanced
+    # denial remains fenced for pinned requests, but is not unresolved cleanup
+    # and may be retired when the session closes.
+    denied_proxy_injected_anchor_cleanup_pending: set[str] = field(default_factory=set)
+    denied_proxy_injected_anchor_generation: int = 0
+    alias_registration_generation: int = 0
+    turn_state_alias_registration_generations: dict[str, int] = field(default_factory=dict)
+    previous_response_alias_registration_generations: dict[str, int] = field(default_factory=dict)
+    last_completed_input_count: int = 0
+    last_completed_response_id: str | None = None
+    # Account that owns ``last_completed_response_id``. A previous_response_id
+    # anchor is account-scoped upstream, so it may only be replayed on the same
+    # account; when the session fails over to a different account this diverges
+    # from ``account.id`` and the anchor must NOT be injected. Kept in sync with
+    # ``last_completed_response_id`` at every setter.
+    last_completed_response_account_id: str | None = None
+    last_completed_input_prefix_fingerprint: str | None = None
+    last_pending_tool_calls: dict[str, str] = field(default_factory=dict)
+    durable_session_id: str | None = None
+    durable_owner_epoch: int | None = None
+    upstream_reader: asyncio.Task[None] | None = None
+    last_upstream_event_generation: int = 0
+    last_upstream_close_code: int | None = None
+    last_upstream_close_generation: int = 0
+    closed: bool = False
+    # ``closed`` is only an admission fence. Resource teardown is single-flight
+    # through this task so invalidation and shutdown can distinguish a rejected
+    # session from one whose socket and leases actually have a close owner.
+    resource_close_task: asyncio.Task[None] | None = None
+    # ``closed`` rejects new admissions but is written by many unrelated
+    # retirement paths; it never proves that a sender owns pending settlement.
+    # Only the submitter may claim this, while holding ``lifecycle_lock``, when
+    # its own send reports a liveness timeout. The reader remains the default
+    # settlement owner for every other close, including an already-closed
+    # session whose still-running transport later loses heartbeat liveness.
+    liveness_settlement_owner: Literal["send"] | None = None
+    # Set when the session proved silent/wedged (reattached stream with
+    # response events but no ``response.created``, or repeated eventless
+    # timeouts). A quarantined session must never be selected for reuse or
+    # re-attach; later requests take the fresh session/no-anchor path.
+    quarantined: bool = False
+    # Set while a reader handoff is replacing the socket. Idle pruning must
+    # retain the registered session during this short transition even though
+    # ``closed`` is fail-closed for normal request reuse.
+    handoff_in_progress: bool = False
+    handoff_future: asyncio.Future["_HTTPBridgeSession"] | None = None
+    account_lease: AccountLease | None = None
+    upstream_close_attempted: bool = False
+    seen_tool_call_keys: dict[ToolCallDedupeKey, None] = field(default_factory=dict)
+    upstream_proxy_route_mode: str | None = None
+    upstream_proxy_pool_id: str | None = None
+    upstream_proxy_endpoint_id: str | None = None
+    upstream_proxy_fallback_used: bool | None = None
+    upstream_proxy_fail_closed_reason: str | None = None
+    # Upstream frames that proved transport liveness but matched no pending
+    # request. They are dropped from the downstream queues, so without this
+    # counter a pre-response bridge timeout cannot tell "upstream said nothing"
+    # apart from "upstream spoke and our matching lost the frame".
+    unmatched_upstream_liveness_count: int = 0
+
+    def replace_connection(
+        self,
+        account: Account,
+        headers: dict[str, str],
+        upstream: UpstreamWebSocket,
+        access_token_expires_at: float | None,
+    ) -> None:
+        """Replace account-bound transport state as one in-memory operation."""
+        self.account = account
+        self.headers = headers
+        self.upstream = upstream
+        self.access_token_expires_at = access_token_expires_at
+
+    def claim_liveness_settlement(self) -> bool:
+        """Claim whole-deque settlement for a liveness-failed submitter.
+
+        The caller must hold ``lifecycle_lock`` across the failing send and
+        this synchronous claim so the reader cannot settle the same deque.
+        """
+
+        if self.liveness_settlement_owner is None:
+            self.liveness_settlement_owner = "send"
+        return self.liveness_settlement_owner == "send"
+
+
+def _complete_http_bridge_handoff(
+    session: _HTTPBridgeSession,
+    inflight_sessions: dict[_HTTPBridgeSessionKey, asyncio.Future[_HTTPBridgeSession]],
+) -> None:
+    session.handoff_in_progress = False
+    future = session.handoff_future
+    session.handoff_future = None
+    if future is not None and not future.done():
+        future.set_result(session)
+    if inflight_sessions.get(session.key) is future:
+        inflight_sessions.pop(session.key, None)
+
+
+def _http_bridge_session_supports_service_tier(
+    session: _HTTPBridgeSession,
+    *,
+    request_model: str | None,
+    request_service_tier: str | None,
+) -> bool:
+    if request_model is None:
+        return True
+
+    registry = get_model_registry()
+    # Mirror select_account: only apply model-account filtering when the model has
+    # registry plan-presence. An operator-mapped but unadvertised slug yields an
+    # authoritative-empty account catalog, which must not deny bridge session reuse.
+    # Explicitly suppressed catalog slugs must, however, not allow reuse because
+    # they intentionally block account selection even when the catalog is empty.
+    plan_types_for_model = getattr(registry, "plan_types_for_model", None)
+    model_allowed_plans = plan_types_for_model(request_model) if callable(plan_types_for_model) else None
+    is_suppressed_model = getattr(registry, "is_suppressed_model", None)
+    if callable(plan_types_for_model) and not model_allowed_plans:
+        if callable(is_suppressed_model) and is_suppressed_model(request_model):
+            return False
+        return True
+    account_indexes_cover_owner = True
+    current_account_plan: str | None = None
+    current_account_plan_is_authoritative = False
+    get_snapshot = getattr(registry, "get_snapshot", None)
+    if callable(get_snapshot):
+        snapshot = get_snapshot()
+        current_account_plan_is_authoritative = snapshot is not None and session.account.id in snapshot.account_plans
+        account_indexes_cover_owner = current_account_plan_is_authoritative
+        if current_account_plan_is_authoritative:
+            current_account_plan = snapshot.account_plans[session.account.id]
+    account_ids_for_model = getattr(registry, "account_ids_for_model", None)
+    model_account_ids = (
+        account_ids_for_model(request_model)
+        if callable(account_ids_for_model) and account_indexes_cover_owner
+        else None
+    )
+    model_catalog_omits_account = model_account_ids is not None and session.account.id not in model_account_ids
+    quota_admission_matches = (
+        session.catalog_omission_quota_admission is not None
+        and session.catalog_omission_quota_admission.matches(
+            requested_model=request_model,
+            service_tier=request_service_tier,
+        )
+    )
+    if model_catalog_omits_account and not quota_admission_matches:
+        return False
+    # Keep bridge reuse aligned with account selection: clients commonly send
+    # these omit-equivalent values explicitly, but neither selects a specific
+    # service tier.
+    normalized_service_tier = request_service_tier.strip().lower() if request_service_tier is not None else None
+    if normalized_service_tier in {None, "auto", "default"}:
+        allowed_plans = model_allowed_plans
+    else:
+        allowed_account_ids = (
+            registry.account_ids_for_model_service_tier(request_model, request_service_tier)
+            if account_indexes_cover_owner
+            else None
+        )
+        if allowed_account_ids is not None and not model_catalog_omits_account:
+            return session.account.id in allowed_account_ids
+
+        allowed_plans = registry.plan_types_for_model_service_tier(request_model, request_service_tier)
+    if allowed_plans is None:
+        return True
+    if current_account_plan_is_authoritative:
+        account_plan = current_account_plan
+    elif session.catalog_omission_quota_admission is not None:
+        # Quota admission proves model support, not the owner's current plan eligibility.
+        return False
+    else:
+        account_plan = session.account.plan_type
+    return account_plan_matches_allowed(account_plan, allowed_plans)
+
+
+@dataclass(slots=True)
+class _WebSocketContinuityState:
+    last_completed_input_count: int = 0
+    last_completed_response_id: str | None = None
+    last_completed_input_prefix_fingerprint: str | None = None
+    last_pending_function_call_ids: list[str] = field(default_factory=list)
+    last_pending_tool_call_types: dict[str, str] = field(default_factory=dict)
+    responses_lite_model: str | None = None
+    responses_lite_response_id: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class _WebSocketContinuityAnchor:
+    previous_response_id: str
+    stored_input_item_count: int
+
+
+@dataclass(slots=True)
+class _WebSocketUpstreamControl:
+    reconnect_requested: bool = False
+    retire_after_drain: bool = False
+    suppress_downstream_event: bool = False
+    replay_request_state: _WebSocketRequestState | None = None
+    downstream_texts: list[str] | None = None
+    downstream_sequence_request_state: _WebSocketRequestState | None = None
+    downstream_sequence_number: int | None = None
+    seen_tool_call_keys: dict[ToolCallDedupeKey, None] = field(default_factory=dict)
+    terminal_message_task: asyncio.Task[bool] | None = None
+
+
+@dataclass(slots=True)
+class _DownstreamWebSocketActivity:
+    """Downstream websocket liveness stamps, read with the owner's clock.
+
+    ``clock`` is the owner's collaborator (``clock_for(proxy)``); the real
+    default keeps the previous ``time.monotonic`` stamps verbatim.
+    """
+
+    clock: Clock = field(default=REAL_CLOCK, kw_only=True)
+    last_activity_at: float = field(init=False)
+    disconnected: bool = False
+
+    def __post_init__(self) -> None:
+        self.last_activity_at = self.clock.monotonic()
+
+    def mark(self) -> None:
+        self.last_activity_at = self.clock.monotonic()
+
+    def mark_disconnected(self) -> None:
+        self.disconnected = True
+        self.mark()
+
+
+def _clear_websocket_request_error_overrides(request_state: _WebSocketRequestState) -> None:
+    request_state.error_code_override = None
+    request_state.error_message_override = None
+    request_state.error_type_override = None
+    request_state.error_param_override = None
+    request_state.failure_phase_override = None
+    request_state.failure_detail_override = None
+    request_state.upstream_error_code_override = None
+    request_state.error_http_status_override = None
+
+
+def _clear_websocket_precreated_replay_fallback(request_state: _WebSocketRequestState) -> None:
+    if request_state.precreated_replay_reason != _ACCOUNT_MODEL_UNSUPPORTED_ERROR_CODE:
+        return
+    request_state.precreated_replay_reason = None
+    request_state.precreated_replay_account_id = None
+    _clear_websocket_request_error_overrides(request_state)
+
+
+def _websocket_is_reasoning_output_item_event(event_type: str | None, payload: Mapping[str, JsonValue] | None) -> bool:
+    if event_type not in {"response.output_item.added", "response.output_item.done"} or payload is None:
+        return False
+    item = payload.get("item")
+    return isinstance(item, Mapping) and item.get("type") == "reasoning"
+
+
+def _websocket_should_defer_reasoning_prelude(
+    request_state: _WebSocketRequestState | None,
+    event_type: str | None,
+    payload: Mapping[str, JsonValue] | None,
+) -> bool:
+    if request_state is None:
+        return False
+    if request_state.downstream_visible:
+        return False
+    reasoning_output_item_event = _websocket_is_reasoning_output_item_event(event_type, payload)
+    # Once a reasoning prelude starts, keep the whole prelude buffered.  The
+    # first reasoning item marks upstream model output as seen so replay stays
+    # disabled; that marker must not make subsequent reasoning deltas visible.
+    if request_state.deferred_reasoning_downstream_texts and (
+        reasoning_output_item_event
+        or event_type
+        in {
+            "response.reasoning_text.delta",
+            "response.reasoning_text.done",
+            "response.reasoning_summary_text.delta",
+            "response.reasoning_summary_text.done",
+        }
+    ):
+        return True
+    if not reasoning_output_item_event:
+        return False
+    if request_state.upstream_model_output_seen:
+        return False
+    if request_state.pending_function_call_ids or request_state.pending_tool_call_types:
+        return False
+    return request_state.response_event_count <= 1
+
+
+def _pop_websocket_deferred_reasoning_downstream_texts(request_state: _WebSocketRequestState | None) -> list[str]:
+    if request_state is None or not request_state.deferred_reasoning_downstream_texts:
+        return []
+    deferred_texts = request_state.deferred_reasoning_downstream_texts
+    request_state.deferred_reasoning_downstream_texts = []
+    return deferred_texts
+
+
+def _clear_websocket_deferred_reasoning_downstream_texts(request_state: _WebSocketRequestState | None) -> None:
+    if request_state is not None:
+        request_state.deferred_reasoning_downstream_texts = []
+
+
+def _mark_response_create_attempt_observed(
+    request_state: _WebSocketRequestState | None,
+    event_type: str | None,
+) -> None:
+    if request_state is None or event_type is None or not event_type.startswith("response."):
+        return
+    attempt = request_state.response_create_attempt
+    if attempt is not None:
+        attempt.response_observed = True
+        if event_type not in {"response.failed", "response.incomplete"}:
+            attempt.non_terminal_response_observed = True
+
+
+def _record_response_event(
+    request_state: _WebSocketRequestState | None,
+    event_type: str | None,
+    *,
+    now: float,
+) -> None:
+    if request_state is None or event_type is None or not event_type.startswith("response."):
+        return
+    _mark_response_create_attempt_observed(request_state, event_type)
+    # ``now`` is the owner clock sample the bridge/websocket idle deadlines are
+    # later compared against; callers pass ``clock_for(owner).monotonic()``.
+    request_state.last_upstream_activity_at = now
+    if event_type in {"response.failed", "response.incomplete"}:
+        return
+    request_state.response_event_count += 1
+
+
+def _websocket_request_can_replay_before_visible_output(
+    request_state: _WebSocketRequestState,
+    *,
+    allow_clean_close_retry: bool = False,
+) -> bool:
+    if not request_state.request_text:
+        return False
+    if request_state.transport == _REQUEST_TRANSPORT_WEBSOCKET and request_state.response_create_sent_at is None:
+        return False
+    # The bounded clean-close retry is a pre-created affordance. An accepted
+    # lifecycle (``replay_downstream_response_id`` captured) is re-sent exactly
+    # once; a clean close of the replacement socket before its
+    # ``response.created`` surfaces one terminal under the visible id instead
+    # of a third send (openspec: retry-accepted-output-free-capacity-failures).
+    if request_state.replay_count >= 1 and not (
+        allow_clean_close_retry
+        and request_state.replay_count == 1
+        and request_state.response_event_count == 0
+        and request_state.clean_close_replay_count == 0
+        and request_state.replay_downstream_response_id is None
+    ):
+        return False
+    # A sequenced downstream frame pins the request to its socket: a fresh
+    # upstream generation restarts ``sequence_number`` from zero (openspec
+    # requirement "Direct WebSocket replay never mixes numeric response
+    # sequences"). The accepted-lifecycle replay does not widen this; the
+    # created-only ``generate: false`` prewarm keeps its watermark-0 exception.
+    sequenced_created_only_prewarm = (
+        request_state.generate_false_prewarm
+        and request_state.last_downstream_sequence_number == 0
+        and request_state.response_id is not None
+        and not request_state.awaiting_response_created
+        and request_state.response_event_count == 1
+        and not request_state.downstream_visible
+    )
+    if request_state.last_downstream_sequence_number is not None and not sequenced_created_only_prewarm:
+        return False
+    if request_state.downstream_visible:
+        return False
+    if request_state.upstream_model_output_seen:
+        return False
+    has_retry_safe_fresh_payload = (
+        request_state.fresh_upstream_request_is_retry_safe and request_state.fresh_upstream_request_text is not None
+    )
+    precreated_pending = request_state.response_id is None and request_state.awaiting_response_created
+    if precreated_pending and request_state.previous_response_id is not None and not has_retry_safe_fresh_payload:
+        return False
+    accepted_lifecycle_only_pending = _websocket_request_is_accepted_lifecycle_only(request_state) and (
+        request_state.previous_response_id is None or has_retry_safe_fresh_payload
+    )
+    if precreated_pending and request_state.response_event_count > 0:
+        return False
+    return precreated_pending or accepted_lifecycle_only_pending
+
+
+def _websocket_request_is_accepted_lifecycle_only(request_state: _WebSocketRequestState) -> bool:
+    """Return whether upstream accepted the request without producing any output.
+
+    True only while the accepted response consists of its lifecycle prelude:
+    ``response.created`` and optionally ``response.in_progress``. In the
+    Responses protocol every other counted ``response.*`` event follows
+    ``response.output_item.added``, which is a model-output event
+    (``_MODEL_OUTPUT_EVENT_TYPES``) that both the HTTP bridge and the direct
+    websocket relay record in ``upstream_model_output_seen``, so "at most two
+    counted events and no output marker" is equivalent to "lifecycle only"
+    even when upstream skips ``response.in_progress``. A buffered reasoning
+    prelude or a pending tool call disqualifies the request. Such a turn has
+    no client-observable or conversational side effect, which is what makes
+    its single-lifecycle replay safe.
+
+    This predicate describes the upstream lifecycle only. Downstream sequence
+    exposure (``last_downstream_sequence_number``) is judged by the callers:
+    ``_websocket_request_can_replay_before_visible_output`` and the accepted
+    capacity classifier both keep refusing a sequenced request, so the direct
+    websocket surface never replays after a finite ``sequence_number`` frame
+    was forwarded.
+    """
+    if request_state.response_id is None or request_state.awaiting_response_created:
+        return False
+    if not 1 <= request_state.response_event_count <= 2:
+        return False
+    if request_state.downstream_visible or request_state.upstream_model_output_seen:
+        return False
+    if request_state.deferred_reasoning_downstream_texts:
+        return False
+    return not (request_state.pending_function_call_ids or request_state.pending_tool_call_types)
+
+
+def _affinity_may_resolve_hard_owner(affinity_policy: _AffinityPolicy) -> bool:
+    """Return whether sticky selection may bind this affinity to one owner account.
+
+    A resolved hard ``CODEX_SESSION`` row narrows selection to its owner
+    (``hard_sticky`` in ``sticky_selection``): turn-state ownership, or the raw
+    compatibility row an old replica persisted for a bare session or thread
+    header, which every policy exposing ``legacy_selection_key`` consults and
+    which wins over the namespaced soft row. The owner is not a request-state
+    pin -- it is read from the database at selection time -- so neither the
+    direct websocket request nor the HTTP bridge session can tell whether its
+    affinity resolves to a hard owner. Any policy that may is treated as
+    owner-bound: excluding that owner would leave every re-selection at
+    ``hard_affinity_saturated`` until the connect budget runs out. Shared by
+    the direct websocket accepted-replay exclusion and the HTTP bridge one.
+    """
+    return (
+        affinity_policy.kind == StickySessionKind.CODEX_SESSION
+        or affinity_policy.legacy_selection_key is not None
+        or affinity_policy.legacy_continuity_source is not None
+    )
+
+
+def _record_websocket_route_metadata(
+    request_state: _WebSocketRequestState,
+    *,
+    upstream: UpstreamWebSocket | None = None,
+    route: ResolvedUpstreamRoute | None = None,
+    fallback_used: bool | None = None,
+) -> None:
+    request_state.upstream_proxy_route_mode = getattr(upstream, "upstream_proxy_route_mode", None) or (
+        route.mode if route is not None else None
+    )
+    request_state.upstream_proxy_pool_id = getattr(upstream, "upstream_proxy_pool_id", None) or (
+        route.pool_id if route is not None else None
+    )
+    request_state.upstream_proxy_endpoint_id = getattr(upstream, "upstream_proxy_endpoint_id", None) or (
+        route.endpoint_id if route is not None else None
+    )
+    upstream_fallback = getattr(upstream, "upstream_proxy_fallback_used", None)
+    request_state.upstream_proxy_fallback_used = upstream_fallback if upstream_fallback is not None else fallback_used
+    if request_state.upstream_proxy_endpoint_id is None:
+        request_state.upstream_proxy_fallback_used = None
+    request_state.upstream_proxy_fail_closed_reason = None
+
+
+def _copy_websocket_route_metadata_to_session(
+    session: _HTTPBridgeSession,
+    request_state: _WebSocketRequestState,
+) -> None:
+    session.upstream_proxy_route_mode = request_state.upstream_proxy_route_mode
+    session.upstream_proxy_pool_id = request_state.upstream_proxy_pool_id
+    session.upstream_proxy_endpoint_id = request_state.upstream_proxy_endpoint_id
+    session.upstream_proxy_fallback_used = request_state.upstream_proxy_fallback_used
+    session.upstream_proxy_fail_closed_reason = request_state.upstream_proxy_fail_closed_reason
+
+
+def _copy_websocket_route_metadata_from_session(
+    request_state: _WebSocketRequestState,
+    session: _HTTPBridgeSession,
+) -> None:
+    request_state.upstream_proxy_route_mode = session.upstream_proxy_route_mode
+    request_state.upstream_proxy_pool_id = session.upstream_proxy_pool_id
+    request_state.upstream_proxy_endpoint_id = session.upstream_proxy_endpoint_id
+    request_state.upstream_proxy_fallback_used = session.upstream_proxy_fallback_used
+    request_state.upstream_proxy_fail_closed_reason = session.upstream_proxy_fail_closed_reason
+
+
+def _websocket_route_log_kwargs(request_state: _WebSocketRequestState) -> dict[str, str | bool | None]:
+    return {
+        "upstream_proxy_route_mode": request_state.upstream_proxy_route_mode,
+        "upstream_proxy_pool_id": request_state.upstream_proxy_pool_id,
+        "upstream_proxy_endpoint_id": request_state.upstream_proxy_endpoint_id,
+        "upstream_proxy_fallback_used": (
+            request_state.upstream_proxy_fallback_used if request_state.upstream_proxy_endpoint_id else None
+        ),
+        "upstream_proxy_fail_closed_reason": request_state.upstream_proxy_fail_closed_reason,
+    }
+
+
+@dataclass(slots=True)
+class _PreparedWebSocketRequest:
+    text_data: str
+    request_state: _WebSocketRequestState
+    affinity_policy: _AffinityPolicy
+
+
+@dataclass(frozen=True, slots=True)
+class _WebSocketReceiveTimeout:
+    timeout_seconds: float
+    error_code: str
+    error_message: str
+    fail_all_pending: bool = False
+
+
+def _event_type_from_payload(event: OpenAIEvent | None, payload: dict[str, JsonValue] | None) -> str | None:
+    if event is not None:
+        return event.type
+    return classify_event_type(payload)
+
+
+async def _wait_for_websocket_continuity_gap(
+    pending_requests: deque[_WebSocketRequestState],
+    *,
+    pending_lock: anyio.Lock,
+    timeout_seconds: float,
+    scheduler: Scheduler,
+    clock: Clock,
+) -> bool:
+    deadline = clock.monotonic() + max(0.0, timeout_seconds)
+    while True:
+        async with pending_lock:
+            if not pending_requests:
+                return True
+        remaining = deadline - clock.monotonic()
+        if remaining <= 0:
+            return False
+        await scheduler.sleep(min(_WEBSOCKET_FULL_REPLAY_WAIT_POLL_SECONDS, remaining))
+
+
+async def _websocket_full_replay_should_wait_for_continuity(
+    request_state: _WebSocketRequestState,
+    pending_requests: deque[_WebSocketRequestState],
+    *,
+    pending_lock: anyio.Lock,
+    codex_session_affinity: bool,
+) -> bool:
+    if (
+        not codex_session_affinity
+        or request_state.previous_response_id is not None
+        or request_state.input_item_count < _WEBSOCKET_FULL_REPLAY_WAIT_MIN_ITEMS
+    ):
+        return False
+    async with pending_lock:
+        return bool(pending_requests)
+
+
+def _is_account_neutral_error_code(code: str | None) -> bool:
+    return is_local_overload_error_code(code) or code in {
+        PROCESS_NETWORK_UNAVAILABLE_CODE,
+        "proxy_unavailable",
+        "responses_compact_input_too_large",
+        "stream_idle_timeout",
+    }
+
+
+def _is_local_account_cap_code(code: str | None) -> bool:
+    return code in _LOCAL_ACCOUNT_CAP_ERROR_CODES
+
+
+def _api_key_fair_share_threshold_pct_from_settings(settings: object) -> int:
+    """Resolve the fair-share congestion threshold, tolerating stale snapshots.
+
+    Cached settings snapshots taken before the field existed lack it; fall
+    back to the live settings object the same way the stream recovery reserve
+    resolution in ``ProxyService`` does.
+    """
+    threshold = getattr(settings, "proxy_api_key_fair_share_congestion_threshold_pct", None)
+    if threshold is None:
+        return get_settings().proxy_api_key_fair_share_congestion_threshold_pct
+    return int(threshold)
+
+
+def _selection_api_key_fair_share_threshold_pct(
+    settings: object,
+    *,
+    lease_kind: str | None,
+    request_stage: str,
+) -> int:
+    """Fair-share threshold for one account selection; 0 disables the gate.
+
+    Only stream leases are fair-share gated. Reattach resumes an existing
+    in-flight response; denying it would strand running work, so it bypasses
+    the fair-share gate the same way it bypasses the recovery reserve.
+    """
+    if lease_kind != "stream" or request_stage == "reattach":
+        return 0
+    return _api_key_fair_share_threshold_pct_from_settings(settings)
+
+
+def opportunistic_admission_account_scope(settings: object, api_key: ApiKeyData | None) -> set[str] | None:
+    """Account ids an opportunistic admission check may consider; ``None`` is the whole pool.
+
+    The API key's account-assignment scope applies first. Single-account
+    routing then narrows the scope to the selected account, or to nothing when
+    no account is selected or the selected one lies outside the key's scope.
+    This is the exact scope ``ProxyService.check_opportunistic_admission`` has
+    always applied, hoisted so read-only callers (the pool-exhaustion probe)
+    share one definition with the admission gate.
+    """
+    scoped_account_ids = (
+        set(api_key.assigned_account_ids) if api_key is not None and api_key.account_assignment_scope_enabled else None
+    )
+    if getattr(settings, "routing_strategy", None) != "single_account":
+        return scoped_account_ids
+    selected_account_id = (getattr(settings, "single_account_id", None) or "").strip()
+    if not selected_account_id:
+        return set()
+    if scoped_account_ids is None or selected_account_id in scoped_account_ids:
+        return {selected_account_id}
+    return set()
+
+
+def _http_error_status_from_payload(payload: dict[str, JsonValue] | None) -> int | None:
+    if not isinstance(payload, dict):
+        return None
+    for status_field in ("status", "status_code"):
+        status = payload.get(status_field)
+        if isinstance(status, int) and not isinstance(status, bool):
+            return status
+    return None
+
+
+def _openai_error_envelope_from_response_failed_payload(
+    payload: dict[str, JsonValue] | None,
+) -> OpenAIErrorEnvelope:
+    default_envelope = openai_error("upstream_error", "Upstream error")
+    if not isinstance(payload, dict):
+        return default_envelope
+    response_payload = payload.get("response")
+    if not isinstance(response_payload, dict):
+        return default_envelope
+    error_payload = response_payload.get("error")
+    if not isinstance(error_payload, dict):
+        return default_envelope
+
+    message_value = error_payload.get("message")
+    if isinstance(message_value, str) and message_value.strip():
+        message = message_value.strip()
+    else:
+        message = "Upstream error"
+
+    code_value = error_payload.get("code")
+    code = code_value.strip() if isinstance(code_value, str) and code_value.strip() else "upstream_error"
+
+    type_value = error_payload.get("type")
+    error_type = type_value.strip() if isinstance(type_value, str) and type_value.strip() else "server_error"
+
+    envelope = openai_error(code, message, error_type)
+    if "param" in error_payload:
+        param_state = OpenAIErrorParam.from_mapping(cast(Mapping[str, JsonValue], error_payload))
+        envelope["error"]["param"] = param_state.raw
+    error_detail = envelope["error"]
+    plan_type = error_payload.get("plan_type")
+    if plan_type is not None:
+        error_detail["plan_type"] = str(plan_type)
+    resets_at = error_payload.get("resets_at")
+    if isinstance(resets_at, int | float):
+        error_detail["resets_at"] = resets_at
+    resets_in = error_payload.get("resets_in_seconds")
+    if isinstance(resets_in, int | float):
+        error_detail["resets_in_seconds"] = resets_in
+    return envelope
+
+
+# --- Upstream websocket transport health -----------------------------------
+#
+# Codex clients only switch to the HTTP transport when the websocket
+# handshake is rejected with HTTP 426 (codex-rs checks
+# ``StatusCode::UPGRADE_REQUIRED`` on connect; in-band error events never
+# trigger the transport fallback). This per-instance marker remembers a
+# recent connect-phase upstream websocket transport failure so the websocket
+# routes can deny the next handshake with 426 and the HTTP paths can pin the
+# upstream transport to HTTP until the websocket upstream proves healthy
+# again.
+
+UPSTREAM_WS_TRANSPORT_FAILURE_TTL_SECONDS = 60.0
+_upstream_ws_transport_failure_at: float | None = None
+
+
+def mark_upstream_websocket_transport_failure() -> None:
+    global _upstream_ws_transport_failure_at
+    _upstream_ws_transport_failure_at = time.monotonic()
+
+
+def clear_upstream_websocket_transport_failure() -> None:
+    global _upstream_ws_transport_failure_at
+    _upstream_ws_transport_failure_at = None
+
+
+def websocket_connect_transport_failure_code(
+    exc: ProxyResponseError,
+    *,
+    confirmed_pre_dispatch: bool,
+) -> str | None:
+    """Code of a host-scoped upstream websocket transport failure, else ``None``.
+
+    The discriminator is the provenance the direct upstream open stamps, not
+    the sanitized error code. Codes cannot carry it in either direction: the
+    responses policy preserves the upstream handshake body, so a direct 5xx
+    upgrade rejection surfaces as ``upstream_error`` or whatever the edge
+    returned, while OAuth refresh transport errors, routed-proxy handshakes,
+    TLS verification failures and host-wide network loss all share the
+    ``upstream_unavailable`` envelope and must keep their
+    classify-penalize-failover handling.
+    """
+
+    if confirmed_pre_dispatch or exc.failure_phase != "connect":
+        return None
+    if exc.failure_detail != UPSTREAM_WEBSOCKET_TRANSPORT_FAILURE_DETAIL:
+        return None
+    connect_error = _parse_openai_error(exc.payload)
+    return _normalize_error_code(
+        connect_error.code if connect_error else None,
+        connect_error.type if connect_error else None,
+    )
+
+
+UPSTREAM_STREAM_TRANSPORTS = frozenset({"auto", "http", "websocket"})
+_UPSTREAM_STREAM_TRANSPORT_DEFAULT = "auto"
+
+
+def configured_upstream_stream_transport(dashboard_settings: Any) -> str:
+    """Return the operator-configured upstream stream transport.
+
+    The dashboard row is the only source. The legacy ``"default"`` sentinel
+    (which used to defer to the removed ``CODEX_LB_UPSTREAM_STREAM_TRANSPORT``
+    env var) and any unknown value resolve to ``"auto"`` so a settings-cache
+    snapshot taken before the data migration ran behaves like the migrated row.
+    """
+    configured = getattr(dashboard_settings, "upstream_stream_transport", None)
+    if configured in UPSTREAM_STREAM_TRANSPORTS:
+        return cast(str, configured)
+    return _UPSTREAM_STREAM_TRANSPORT_DEFAULT
+
+
+def upstream_websocket_transport_recently_failed() -> bool:
+    marked_at = _upstream_ws_transport_failure_at
+    return marked_at is not None and time.monotonic() - marked_at < UPSTREAM_WS_TRANSPORT_FAILURE_TTL_SECONDS