coderouter-cli 2.13.0__py3-none-any.whl → 2.15.0__py3-none-any.whl

coderouter/ingress/anthropic_routes.py

@@ -30,6 +30,7 @@ from typing import Any
 from fastapi import APIRouter, Header, HTTPException, Request
 from fastapi.responses import JSONResponse, StreamingResponse
 
+from coderouter.adapters.base import StreamTruncatedError
 from coderouter.guards.tool_loop import ToolCountExceededError, ToolLoopBreakError
 from coderouter.logging import get_logger
 from coderouter.routing import (
@@ -38,6 +39,10 @@ from coderouter.routing import (
     NoProvidersAvailableError,
 )
 from coderouter.routing.auto_router import RESERVED_PROFILE_NAME, classify
+from coderouter.routing.fallback_trace import (
+    SSE_FALLBACK_EVENT,
+    current_fallback_trace,
+)
 from coderouter.token_estimation import extract_text_from_anthropic_request
 from coderouter.token_estimation_accurate import count_tokens, is_accuracy_available
 from coderouter.translation import (
@@ -54,6 +59,11 @@ _ANTHROPIC_VERSION_HEADER = "anthropic-version"
 _ANTHROPIC_BETA_HEADER = "anthropic-beta"
 _CTX_BUDGET_HEADER = "X-CodeRouter-Context-Budget"
 _DRIFT_HEADER = "X-CodeRouter-Drift"
+# v2.15.0: the ``X-CodeRouter-Fallback-*`` family is built by
+# ``FallbackTrace.header_values()`` rather than named here, because the set
+# of headers varies with the trace (``-To`` is absent when the whole chain
+# was exhausted). The names themselves live next to the trace so the
+# engine, the ingress and the tests all read one definition.
 
 # M14: overall SSE stream ceiling. A single streamed request can legitimately
 # run much longer than one provider call (long generations, tool turns), so we
@@ -258,6 +268,20 @@ async def messages(
         drift_severity = engine.last_drift_severity
         if drift_severity:
             stream_headers[_DRIFT_HEADER] = drift_severity
+        # v2.15.0: fallback headers on the streaming path carry what is
+        # already known when the response commits — i.e. the pre-attempt
+        # hops (paid gate / budget / backend health / self-healing) that
+        # ``apply_context_budget`` recorded while resolving the chain just
+        # above. Runtime attempt failures happen *after* the HTTP headers
+        # have shipped and are therefore physically unreachable here; they
+        # are delivered instead as the trailing ``coderouter_fallback`` SSE
+        # metadata event emitted by ``_anthropic_sse_iterator`` (the same
+        # trailer mechanism v2.0-H uses for ``coderouter_partial``), and as
+        # ``fallback-occurred`` log lines. Same commit-order constraint the
+        # drift header comment above describes.
+        pre_dispatch_trace = current_fallback_trace()
+        if pre_dispatch_trace is not None:
+            stream_headers.update(pre_dispatch_trace.header_values())
         # M14: wrap the SSE iterator with an overall timeout + client
         # disconnect cleanup so a wedged upstream cannot pin the client
         # (or the upstream socket) open forever.
@@ -309,6 +333,15 @@ async def messages(
         resp_headers[_CTX_BUDGET_HEADER] = ctx_budget_status
     if drift_severity:
         resp_headers[_DRIFT_HEADER] = drift_severity
+    # v2.15.0: fallback reason headers. The engine wrote its hops onto the
+    # request-scoped trace while ``generate_anthropic`` was awaited above,
+    # so by here the trail is complete — ``header_values()`` returns an
+    # empty dict (and this whole block is inert) when the first provider
+    # served the request, which keeps the healthy path byte-identical to
+    # v2.14.0.
+    fallback_trace = current_fallback_trace()
+    if fallback_trace is not None:
+        resp_headers.update(fallback_trace.header_values())
 
     if resp_headers:
         return JSONResponse(
@@ -511,6 +544,17 @@ async def _anthropic_sse_iterator(
         except (KeyError, ValueError):
             pass
 
+        # v2.15.0 (stream-truncation): name the specific failure on the
+        # metadata event. ``mid_stream_failure`` stays the default so every
+        # pre-v2.15.0 case is byte-identical; ``stream_truncated`` tells the
+        # client the difference between "the provider errored out" and "the
+        # provider went quiet with the message still open".
+        partial_reason = (
+            "stream_truncated"
+            if isinstance(exc.original, StreamTruncatedError)
+            else "mid_stream_failure"
+        )
+
         if partial_action == "surface" and exc.partial_content:
             # Emit message_delta with accumulated usage (signals stream end).
             yield _format_anthropic_sse(AnthropicStreamEvent(
@@ -533,21 +577,32 @@ async def _anthropic_sse_iterator(
                     "type": "coderouter_partial",
                     "partial_content": exc.partial_content,
                     "provider": exc.provider,
-                    "reason": "mid_stream_failure",
+                    "reason": partial_reason,
                     "original_error": str(exc.original)[:200],
                 },
             ))
-            logger.info(
-                "partial-stitch-surfaced",
-                extra={
-                    "provider": exc.provider,
-                    "profile": profile_name,
-                    "text_blocks": len(exc.partial_content),
-                    "text_length": sum(
-                        len(b.get("text", "")) for b in exc.partial_content
-                    ),
-                },
-            )
+            # v2.15.0: keep the pre-v2.15.0 key set (and order) intact for
+            # every failure that is not a truncation. The JSON formatter
+            # walks ``record.__dict__`` and emits whatever ``extra`` carries,
+            # so an unconditional ``reason`` would change the shape of this
+            # log line even under the default ``stream_truncation_action:
+            # off`` — where no truncation can be detected in the first place
+            # and the release claims byte-for-byte compatibility with
+            # v2.14.0. The key is therefore appended only when it says
+            # something new.
+            _stitch_extra: dict[str, Any] = {
+                "provider": exc.provider,
+                "profile": profile_name,
+                "text_blocks": len(exc.partial_content),
+                "text_length": sum(
+                    len(b.get("text", "")) for b in exc.partial_content
+                ),
+            }
+            if partial_reason != "mid_stream_failure":
+                # Lets a dashboard split "provider errored" from "provider
+                # went quiet" without re-parsing the SSE.
+                _stitch_extra["reason"] = partial_reason
+            logger.info("partial-stitch-surfaced", extra=_stitch_extra)
         else:
             err_event = AnthropicStreamEvent(
                 type="error",
@@ -561,6 +616,21 @@ async def _anthropic_sse_iterator(
             )
             yield _format_anthropic_sse(err_event)
 
+    # v2.15.0: trailing fallback metadata. Emitted after the stream has
+    # terminated (normally or with an in-stream error frame), so it never
+    # interleaves with the Anthropic event sequence a client is parsing —
+    # exactly the position ``coderouter_partial`` occupies. Client-optional:
+    # spec-compliant Anthropic SDKs ignore unknown event types, and the
+    # frame is only produced when a fallback actually happened.
+    trace = current_fallback_trace()
+    if trace is not None and trace.occurred:
+        yield _format_anthropic_sse(
+            AnthropicStreamEvent(
+                type=SSE_FALLBACK_EVENT,
+                data=trace.as_event_payload(),
+            )
+        )
+
 
 def _format_anthropic_sse(ev: AnthropicStreamEvent) -> str:
     """Serialize an :class:`AnthropicStreamEvent` onto the SSE wire.

coderouter/ingress/dashboard_routes.py

@@ -34,9 +34,11 @@ Why inline JS / CSS
 
 from __future__ import annotations
 
-from fastapi import APIRouter
+from fastapi import APIRouter, Request
 from fastapi.responses import HTMLResponse
 
+from coderouter.ingress.ui_auth import auth_required, require_ui_token
+
 router = APIRouter()
 
 
@@ -219,6 +221,17 @@ _DASHBOARD_HTML = r"""<!doctype html>
   // Poll interval — 2s matches plan.md §12.3.5. Short enough to feel
   // live on a local dev machine, long enough that HTTP overhead is noise.
   const POLL_MS = 2000;
+  // v2.14.0: the token is entered by the operator and kept in
+  // sessionStorage (cleared when the tab closes). The page is told only
+  // whether auth is on, never what the token is.
+  const AUTH_REQUIRED = __METRICS_AUTH_REQUIRED__;
+  const TOKEN_KEY = "coderouter-metrics-token";
+  let metricsToken = sessionStorage.getItem(TOKEN_KEY) || "";
+  if (AUTH_REQUIRED && !metricsToken) {
+    const v = window.prompt("CODEROUTER_METRICS_TOKEN を入力してください", "");
+    if (v) { metricsToken = v.trim(); sessionStorage.setItem(TOKEN_KEY, metricsToken); }
+  }
+  const authHeaders = () => metricsToken ? {"X-CodeRouter-Token": metricsToken} : {};
   // Sparkline ring — 60 samples at 2s/sample → 2 minutes of history.
   const SPARK_POINTS = 60;
   const sparkBuffer = [];
@@ -524,7 +537,7 @@ _DASHBOARD_HTML = r"""<!doctype html>
 
   const poll = async () => {
     try {
-      const resp = await fetch("/metrics.json", {cache: "no-store"});
+      const resp = await fetch("/metrics.json", {cache: "no-store", headers: authHeaders()});
       if (!resp.ok) {
         renderError("HTTP " + resp.status);
         return;
@@ -547,7 +560,7 @@ _DASHBOARD_HTML = r"""<!doctype html>
 
 
 @router.get("/dashboard", response_class=HTMLResponse)
-async def dashboard() -> HTMLResponse:
+async def dashboard(request: Request) -> HTMLResponse:
     """Serve the single-page dashboard HTML.
 
     The page is entirely static — all data comes from polling
@@ -556,4 +569,11 @@ async def dashboard() -> HTMLResponse:
     the template lives in this module as a string, keeping the shipping
     unit a single Python file with no template dir to configure.
     """
-    return HTMLResponse(content=_DASHBOARD_HTML)
+    require_ui_token(request)
+    # Only the boolean reaches the page — never the token. Same split the
+    # v2.13.0 launcher fix introduced after ``curl /launcher | grep``
+    # recovered the shared secret straight out of the HTML.
+    html = _DASHBOARD_HTML.replace(
+        "__METRICS_AUTH_REQUIRED__", "true" if auth_required() else "false"
+    )
+    return HTMLResponse(content=html)

coderouter/ingress/metrics_routes.py

@@ -28,7 +28,9 @@ from typing import Any
 from fastapi import APIRouter, Request
 from fastapi.responses import PlainTextResponse
 
+from coderouter.ingress.ui_auth import require_ui_token
 from coderouter.metrics import format_prometheus, get_collector
+from coderouter.secret_redaction import redact
 
 router = APIRouter()
 
@@ -48,6 +50,11 @@ async def metrics_json(request: Request) -> dict[str, Any]:
     dashboard uses it to classify providers into local / free / paid
     for the usage-mix bar without a second endpoint round-trip.
     """
+    # v2.14.0: opt-in token first, before anything is computed. The
+    # ordering is the point — codex-router's /health answers before its
+    # own auth check and leaks the live session name to any local caller.
+    require_ui_token(request)
+
     snapshot = get_collector().snapshot()
 
     config = getattr(request.app.state, "config", None)
@@ -66,7 +73,10 @@ async def metrics_json(request: Request) -> dict[str, Any]:
                     "paid": p.paid,
                     # ``HttpUrl`` is not JSON-serializable directly in Pydantic v2;
                     # the cast also makes the shape stable if Pydantic switches types.
-                    "base_url": str(p.base_url),
+                    # v2.14.0: run it through the scrubber. A base_url is the
+                    # one config field an operator can paste a credential into
+                    # (``?api_key=…``), and this endpoint hands it to a browser.
+                    "base_url": redact(str(p.base_url)),
                 }
                 for p in config.providers
             ],
@@ -79,7 +89,7 @@ async def metrics_json(request: Request) -> dict[str, Any]:
 
 
 @router.get("/metrics", response_class=PlainTextResponse)
-async def metrics_prometheus() -> PlainTextResponse:
+async def metrics_prometheus(request: Request) -> PlainTextResponse:
     """Prometheus text exposition format (v1.5-B).
 
     Convention-compliant endpoint path for Prometheus scrapers. Returns
@@ -88,5 +98,6 @@ async def metrics_prometheus() -> PlainTextResponse:
     Sits alongside :func:`metrics_json` (not a replacement) — JSON is
     for internal UI, Prometheus is for external time-series DBs.
     """
+    require_ui_token(request)
     body = format_prometheus(get_collector().snapshot())
     return PlainTextResponse(content=body, media_type=_PROM_CONTENT_TYPE)

coderouter/ingress/openai_routes.py

@@ -29,12 +29,13 @@ from collections.abc import AsyncIterator
 from typing import Any
 
 from fastapi import APIRouter, Header, HTTPException, Request
-from fastapi.responses import StreamingResponse
+from fastapi.responses import JSONResponse, StreamingResponse
 
 from coderouter.adapters.base import ChatRequest
 from coderouter.logging import get_logger
 from coderouter.routing import FallbackEngine, NoProvidersAvailableError
 from coderouter.routing.auto_router import RESERVED_PROFILE_NAME, classify
+from coderouter.routing.fallback_trace import current_fallback_trace
 
 router = APIRouter()
 logger = get_logger(__name__)
@@ -179,7 +180,7 @@ async def chat_completions(
     request: Request,
     x_coderouter_profile: str | None = Header(default=None, alias=_PROFILE_HEADER),
     x_coderouter_mode: str | None = Header(default=None, alias=_MODE_HEADER),
-) -> StreamingResponse | dict[str, Any]:
+) -> StreamingResponse | JSONResponse | dict[str, Any]:
     """OpenAI Chat Completions endpoint.
 
     Validates the body into :class:`ChatRequest`, resolves the profile
@@ -252,6 +253,34 @@ async def chat_completions(
     except NoProvidersAvailableError as exc:
         raise HTTPException(status_code=502, detail=str(exc)) from exc
 
+    # v2.15.0: fallback reason headers, same shape and same construction as
+    # ``anthropic_routes.messages`` — the engine filled the request-scoped
+    # trace while ``generate`` was awaited, and ``header_values()`` is empty
+    # unless the chain actually moved. A request served by its first
+    # provider therefore still returns the bare dict, byte-identical to
+    # v2.14.0.
+    #
+    # Only the non-streaming half exists here, and that is deliberate. The
+    # Anthropic streaming path can carry the trail two ways: chain-resolve
+    # hops ride the HTTP headers (``apply_context_budget`` resolves the
+    # chain before the response commits) and runtime hops ride the trailing
+    # ``coderouter_fallback`` SSE event (Anthropic's wire is typed, so an
+    # unknown event type is ignored by spec-compliant SDKs). Neither is
+    # available on the OpenAI wire: this route has no pre-dispatch chain
+    # resolution, and OpenAI SSE frames are untyped — every ``data:`` line
+    # is parsed as a ChatCompletionChunk, so injecting a metadata frame
+    # would hand strict clients an object they cannot deserialize. That is
+    # a breaking change, so the streaming OpenAI path stays untouched and
+    # its reasons are available via the ``fallback-occurred`` log lines.
+    fallback_trace = current_fallback_trace()
+    if fallback_trace is not None:
+        resp_headers = fallback_trace.header_values()
+        if resp_headers:
+            return JSONResponse(
+                content=response.model_dump(exclude_none=True),
+                headers=resp_headers,
+            )
+
     return response.model_dump(exclude_none=True)
 
 

coderouter/ingress/ui_auth.py

@@ -0,0 +1,94 @@
+"""Opt-in token auth for the read-only UI surfaces (v2.14.0).
+
+``/dashboard``, ``/metrics.json`` and ``/metrics`` were the last endpoints
+with no authentication story at all. They change nothing, so they were
+never part of the H-8 state-changing-endpoint work — but "read-only" is
+not "harmless". ``/metrics.json`` returns every provider's name, kind,
+paid flag and ``base_url``, plus the profile graph: the full topology of
+which models an operator runs and which vendors they pay. On a laptop
+that is fine. On a box where the port is reachable by anything else, it
+is a free reconnaissance endpoint.
+
+The failure we are deliberately not repeating is codex-router's: its
+``/health`` answers *before* the caller-key check and includes the live
+session name, so any local process can read what the operator is working
+on. Cheap to avoid, easy to ship by accident — the check just has to come
+first.
+
+Contract
+--------
+Identical in shape to :func:`coderouter.ingress.launcher_routes._require_launcher_token`,
+so an operator learns it once:
+
+* ``CODEROUTER_METRICS_TOKEN`` unset → the endpoints stay open exactly as
+  they were, and a one-time warning is logged. Backwards compatible by
+  construction; nobody's Prometheus scrape breaks on upgrade.
+* Set → every request must carry a matching ``X-CodeRouter-Token`` header,
+  compared with :func:`secrets.compare_digest`.
+
+The token is deliberately **not** accepted as a query parameter. A token
+in a URL lands in access logs, in ``Referer`` headers, and in the browser
+history — and this codebase now has a log scrubber precisely because
+credentials end up in places nobody predicted.
+"""
+
+from __future__ import annotations
+
+import os
+import secrets
+
+from fastapi import HTTPException, Request
+
+from coderouter.logging import get_logger
+
+__all__ = ["METRICS_TOKEN_ENV", "METRICS_TOKEN_HEADER", "require_ui_token"]
+
+logger = get_logger(__name__)
+
+METRICS_TOKEN_ENV = "CODEROUTER_METRICS_TOKEN"
+METRICS_TOKEN_HEADER = "X-CodeRouter-Token"
+
+# One warning per process, not per request — a 2-second dashboard poll
+# would otherwise bury every other log line.
+_warning_emitted = False
+
+
+def require_ui_token(request: Request) -> None:
+    """Enforce the metrics/dashboard token when one is configured.
+
+    Raises ``401`` on mismatch. Returns silently when the env var is
+    unset, after logging a single ``metrics-auth-disabled`` line.
+    """
+    global _warning_emitted
+    expected = os.environ.get(METRICS_TOKEN_ENV, "")
+    if not expected:
+        if not _warning_emitted:
+            logger.warning(
+                "metrics-auth-disabled",
+                extra={
+                    "hint": (
+                        f"{METRICS_TOKEN_ENV} is not set; /dashboard, "
+                        "/metrics.json and /metrics are unauthenticated and "
+                        "expose provider names, base_urls and the profile "
+                        "graph. Set it when binding to anything but loopback."
+                    ),
+                },
+            )
+            _warning_emitted = True
+        return
+    provided = request.headers.get(METRICS_TOKEN_HEADER, "")
+    if not secrets.compare_digest(provided, expected):
+        raise HTTPException(
+            status_code=401, detail="Invalid or missing metrics token."
+        )
+
+
+def auth_required() -> bool:
+    """Whether a token is configured — safe to embed in the page.
+
+    The dashboard needs to know *that* auth is on so it can prompt; it
+    must never receive the token itself. Same split as the v2.13.0 fix
+    that stopped ``GET /launcher`` embedding ``CODEROUTER_LAUNCHER_TOKEN``
+    straight into the HTML, where ``curl | grep`` recovered it.
+    """
+    return bool(os.environ.get(METRICS_TOKEN_ENV, ""))

coderouter/logging.py

@@ -23,6 +23,8 @@ import logging
 import sys
 from typing import Any, Literal, TypedDict
 
+from coderouter.secret_redaction import install_secret_filter
+
 
 class JsonLineFormatter(logging.Formatter):
     """Emit each record as a single JSON line."""
@@ -105,6 +107,11 @@ def configure_logging(level: str = "INFO") -> None:
             root.removeHandler(h)
     handler = logging.StreamHandler(sys.stderr)
     handler.setFormatter(JsonLineFormatter())
+    # v2.14.0: scrub registered credentials before the formatter runs. The
+    # filter is attached per-handler (not to the root logger) because logger
+    # filters do not apply to records propagated up from child loggers —
+    # every emitting module in this codebase uses its own module logger.
+    install_secret_filter(handler)
     setattr(handler, _CODEROUTER_LOG_HANDLER_MARKER, True)
     root.addHandler(handler)
 
@@ -1472,6 +1479,63 @@ def log_empty_response_detected(
     )
 
 
+# ---------------------------------------------------------------------------
+# v2.15.0 (stream-truncation): upstream SSE ended without a terminator
+#
+# Fired from the adapter's SSE parse loop when ``stream_truncation_action``
+# is ``warn`` or ``error`` and the upstream line iterator was exhausted
+# without a ``message_stop`` (Anthropic wire) / ``[DONE]`` or a
+# ``finish_reason`` (OpenAI wire).
+#
+# ``action`` records which knob value produced the line, so a dashboard can
+# separate "we only measured it" (``warn``) from "we acted on it" (``error``).
+# ``events_forwarded`` is how many events/chunks the adapter had already
+# yielded — 0 means nothing reached the engine and a clean fallback is still
+# possible. ``tool_call_in_flight`` is the sharp edge: True means a
+# ``tool_use`` / ``tool_calls`` block was still open, so whatever the
+# translation layer synthesizes closes a block whose argument JSON is
+# provably incomplete.
+# ---------------------------------------------------------------------------
+
+
+def log_stream_truncation_detected(
+    logger: logging.Logger,
+    provider: str,
+    *,
+    action: str,
+    wire: str,
+    events_forwarded: int,
+    saw_stream_start: bool,
+    tool_call_in_flight: bool = False,
+) -> None:
+    """Emit a ``stream-truncation-detected`` warn line.
+
+    Args:
+        logger: Target logger.
+        provider: ``ProviderConfig.name`` whose stream was cut.
+        action: The ``stream_truncation_action`` value in effect (``warn``
+            or ``error`` — ``off`` never reaches here).
+        wire: ``anthropic`` or ``openai`` — which SSE dialect was being
+            parsed, i.e. which terminator went missing.
+        events_forwarded: Count of events/chunks already yielded downstream.
+        saw_stream_start: Whether the opening event (``message_start`` /
+            first data chunk) had arrived at all. False means the upstream
+            produced nothing before closing.
+        tool_call_in_flight: Whether a tool-call block was still open.
+    """
+    logger.warning(
+        "stream-truncation-detected",
+        extra={
+            "provider": provider,
+            "action": action,
+            "wire": wire,
+            "events_forwarded": events_forwarded,
+            "saw_stream_start": saw_stream_start,
+            "tool_call_in_flight": tool_call_in_flight,
+        },
+    )
+
+
 # ---------------------------------------------------------------------------
 # v2.0-I: Continuous probe log shapes
 #
@@ -1605,3 +1669,89 @@ def log_probe_capabilities_drift(
         "in_registry": in_registry,
     }
     logger.warning("probe-capabilities-drift", extra=payload)
+
+
+# ---------------------------------------------------------------------------
+# v2.15.0: fallback reason logging
+#
+# One ``fallback-occurred`` line per hop. Fires only when the chain
+# actually moves — a request served by its first provider produces no
+# line at all, so this adds zero volume to the healthy path.
+#
+# The vocabulary of ``reason`` is defined in
+# :mod:`coderouter.routing.fallback_trace` (a single canonical set that
+# also names the pre-existing ``provider-does-not-support`` /
+# ``translation-lossy`` degrade reasons, which never appear here — a
+# degrade keeps the request on the same provider).
+#
+# ``to_provider`` is ``None`` when the hop is the chain's last one and no
+# successor was ever attempted (chain exhausted). The line is still
+# emitted: "we left A because of R and had nowhere to go" is the single
+# most diagnostic event in the whole engine.
+# ---------------------------------------------------------------------------
+
+
+class FallbackOccurredPayload(TypedDict):
+    """Structured shape of the ``fallback-occurred`` log record.
+
+    Fields
+        provider: the provider being left. Duplicated from
+            ``from_provider`` under the field name every other engine
+            event uses, so existing per-provider log queries keep working
+            without learning a new key.
+        from_provider: the provider being left.
+        to_provider: the provider taking over, or None if the chain was
+            exhausted with no successor.
+        reason: canonical fallback reason (see ``fallback_trace``).
+        detail: short human-readable context (HTTP status, truncated
+            error text), or None.
+        profile: the resolved profile name, when known.
+        stream: True when the hop happened on a streaming request.
+        pre_attempt: True when the provider was filtered out during chain
+            resolution (budget / health / paid gate) and therefore never
+            actually called; False when it was called and failed.
+        hop_index: 0-based position of this hop within the request.
+    """
+
+    provider: str
+    from_provider: str
+    to_provider: str | None
+    reason: str
+    detail: str | None
+    profile: str | None
+    stream: bool
+    pre_attempt: bool
+    hop_index: int
+
+
+def log_fallback_occurred(
+    logger: logging.Logger,
+    *,
+    from_provider: str,
+    to_provider: str | None,
+    reason: str,
+    detail: str | None = None,
+    profile: str | None = None,
+    stream: bool = False,
+    pre_attempt: bool = False,
+    hop_index: int = 0,
+) -> None:
+    """Emit a ``fallback-occurred`` warning line for one chain transition.
+
+    Warn level, matching ``provider-failed`` — a fallback is a
+    degradation of the intended routing even when the request ultimately
+    succeeds, and operators grep for it when a profile's primary provider
+    stops earning its place at the front of the chain.
+    """
+    payload: FallbackOccurredPayload = {
+        "provider": from_provider,
+        "from_provider": from_provider,
+        "to_provider": to_provider,
+        "reason": reason,
+        "detail": detail,
+        "profile": profile,
+        "stream": stream,
+        "pre_attempt": pre_attempt,
+        "hop_index": hop_index,
+    }
+    logger.warning("fallback-occurred", extra=payload)

coderouter/metrics/collector.py

@@ -53,6 +53,8 @@ Event inventory (dispatch table in :meth:`MetricsCollector._dispatch`)
     ``drift-reload-attempted``   → ``drift_reload_total`` / success
     ``partial-stitch-surfaced``  → ``partial_stitch_surfaced_total`` (v2.0-H)
     ``empty-response-detected``  → ``empty_responses_total`` + per-provider (⑧)
+    ``stream-truncation-detected`` → ``stream_truncated_total`` + per-provider
+                                   + per-action (v2.15.0)
     ``probe-completed`` (v2.0-I) → ``probe_total`` / ``probe_success`` / ``probe_failure``
                                    + per-provider latency gauge
     ``probe-round-completed``    → ``probe_rounds_total`` (v2.0-I)
@@ -111,6 +113,7 @@ _KNOWN_EVENTS: Final[frozenset[str]] = frozenset(
         "drift-reload-attempted",
         "partial-stitch-surfaced",
         "empty-response-detected",
+        "stream-truncation-detected",
         "probe-completed",
         "probe-round-completed",
         "probe-capabilities-drift",
@@ -281,6 +284,16 @@ class MetricsCollector(logging.Handler):
         self._empty_responses_total: int = 0
         self._empty_responses_by_provider: Counter[str] = Counter()
 
+        # v2.15.0 (stream-truncation): count of upstream SSE streams that
+        # ended without a protocol terminator, under either ``warn`` or
+        # ``error``. Per-provider answers "which backend goes quiet"; the
+        # per-action split separates measurement from enforcement so a
+        # dashboard can show the ``warn``-phase rate before an operator
+        # commits to ``error``.
+        self._stream_truncated_total: int = 0
+        self._stream_truncated_by_provider: Counter[str] = Counter()
+        self._stream_truncated_by_action: Counter[str] = Counter()
+
         # v2.0-I: continuous probe counters. Per-provider probe attempts
         # and outcomes, plus a round counter for the dashboard's
         # "probes/min" panel.
@@ -339,6 +352,7 @@ class MetricsCollector(logging.Handler):
             "drift-reload-attempted": self._on_drift_reload_attempted,
             "partial-stitch-surfaced": self._on_partial_stitch_surfaced,
             "empty-response-detected": self._on_empty_response_detected,
+            "stream-truncation-detected": self._on_stream_truncation_detected,
             "probe-completed": self._on_probe_completed,
             "probe-round-completed": self._on_probe_round_completed,
             "probe-capabilities-drift": self._on_probe_capabilities_drift,
@@ -691,6 +705,20 @@ class MetricsCollector(logging.Handler):
             self._empty_responses_by_provider[provider] += 1
         self._push_recent("empty-response-detected", extras, record)
 
+    def _on_stream_truncation_detected(
+        self, extras: dict[str, Any], record: logging.LogRecord
+    ) -> None:
+        # v2.15.0 (stream-truncation): an upstream SSE stream ended without
+        # its terminator under a ``warn`` / ``error`` action.
+        self._stream_truncated_total += 1
+        provider = _str(extras.get("provider"))
+        if provider:
+            self._stream_truncated_by_provider[provider] += 1
+        action = _str(extras.get("action"))
+        if action:
+            self._stream_truncated_by_action[action] += 1
+        self._push_recent("stream-truncation-detected", extras, record)
+
     def _on_probe_completed(
         self, extras: dict[str, Any], record: logging.LogRecord
     ) -> None:
@@ -914,6 +942,14 @@ class MetricsCollector(logging.Handler):
                     "empty_responses_by_provider": dict(
                         self._empty_responses_by_provider
                     ),
+                    # v2.15.0 (stream-truncation).
+                    "stream_truncated_total": self._stream_truncated_total,
+                    "stream_truncated_by_provider": dict(
+                        self._stream_truncated_by_provider
+                    ),
+                    "stream_truncated_by_action": dict(
+                        self._stream_truncated_by_action
+                    ),
                     # v2.0-I: continuous probe counters.
                     "probe_total": dict(self._probe_total),
                     "probe_success": dict(self._probe_success),
@@ -1071,6 +1107,10 @@ class MetricsCollector(logging.Handler):
             # ⑧ (empty-response)
             self._empty_responses_total = 0
             self._empty_responses_by_provider.clear()
+            # v2.15.0 (stream-truncation)
+            self._stream_truncated_total = 0
+            self._stream_truncated_by_provider.clear()
+            self._stream_truncated_by_action.clear()
             # v2.0-I
             self._probe_total.clear()
             self._probe_success.clear()