coderouter-cli 2.14.0__py3-none-any.whl → 2.15.1__py3-none-any.whl

coderouter/adapters/anthropic_native.py

@@ -44,9 +44,14 @@ from coderouter.adapters.base import (
     ChatResponse,
     ProviderCallOverrides,
     StreamChunk,
+    StreamTruncatedError,
 )
 from coderouter.credentials import resolve_provider_credential
-from coderouter.logging import get_logger, log_output_filter_applied
+from coderouter.logging import (
+    get_logger,
+    log_output_filter_applied,
+    log_stream_truncation_detected,
+)
 from coderouter.output_filters import OutputFilterChain
 from coderouter.translation.anthropic import (
     AnthropicRequest,
@@ -74,6 +79,74 @@ _RETRYABLE_STATUSES = {404, 408, 425, 429, 500, 502, 503, 504}
 _DEFAULT_ANTHROPIC_VERSION = "2023-06-01"
 
 
+class _AnthropicTerminatorTracker:
+    """v2.15.0: watch an Anthropic SSE event stream for its terminator.
+
+    The parse loop in :meth:`AnthropicAdapter.stream_anthropic` used to be
+    stateless across events — ``current_event`` was reset on every blank
+    line and nothing remembered whether the stream had ended *properly*.
+    That made "upstream sent 30 deltas and hung up" indistinguishable from
+    "upstream sent the whole message". This tracker is the missing memory.
+
+    What counts as a terminator (deliberately generous, to keep the false
+    positive rate down — see ``stream_truncation_action`` in
+    ``config/schemas.py``):
+
+    * ``message_stop`` — the canonical Anthropic terminator.
+    * ``message_delta`` carrying a non-null ``stop_reason`` — the message is
+      semantically complete even if the provider omits ``message_stop``.
+      Some Anthropic-compatible local servers do exactly that, and their
+      content is *not* truncated, so flagging them would be a false positive.
+    * a top-level ``error`` event — the upstream ended the stream on purpose
+      and the frame is forwarded to the client verbatim (current behavior).
+      Reporting truncation on top would double-report one failure.
+
+    ``open_block_type`` tracks the currently-open content block so a stream
+    cut in the middle of a ``tool_use`` block's ``input_json_delta`` can be
+    reported as such: that is the case where the translation layer's
+    terminator synthesis closes a block whose argument JSON is provably
+    incomplete.
+    """
+
+    __slots__ = ("events", "open_block_type", "saw_start", "saw_terminator")
+
+    def __init__(self) -> None:
+        """Start with nothing observed."""
+        self.saw_terminator: bool = False
+        self.saw_start: bool = False
+        self.events: int = 0
+        self.open_block_type: str | None = None
+
+    def observe(self, event_type: str, data: Any) -> None:
+        """Fold one parsed SSE event into the tracked state.
+
+        ``data`` is whatever ``json.loads`` produced for the block, so it is
+        not guaranteed to be a mapping; non-dict payloads are treated as
+        empty rather than raising inside a streaming hot path.
+        """
+        self.events += 1
+        if not isinstance(data, dict):
+            data = {}
+        if event_type == "message_start":
+            self.saw_start = True
+        elif event_type == "content_block_start":
+            block = data.get("content_block")
+            self.open_block_type = block.get("type") if isinstance(block, dict) else None
+        elif event_type == "content_block_stop":
+            self.open_block_type = None
+        elif event_type == "message_delta":
+            delta = data.get("delta")
+            if isinstance(delta, dict) and delta.get("stop_reason"):
+                self.saw_terminator = True
+        elif event_type in {"message_stop", "error"}:
+            self.saw_terminator = True
+
+    @property
+    def tool_call_in_flight(self) -> bool:
+        """True when a ``tool_use`` block was still open at end-of-stream."""
+        return self.open_block_type == "tool_use"
+
+
 def anthropic_messages_url(base_url: str) -> str:
     """Resolve the ``/v1/messages`` endpoint URL from a ``base_url``.
 
@@ -475,6 +548,12 @@ class AnthropicAdapter(BaseAdapter):
         filter_chains: dict[int, OutputFilterChain] = {}
         logged_flag: list[bool] = [False]
 
+        # v2.15.0 (stream-truncation): remember whether the upstream ever
+        # terminated its message. Resolved once per call — the knob is a
+        # profile-level setting threaded in through ProviderCallOverrides.
+        truncation_action = self.effective_stream_truncation_action(overrides)
+        terminator = _AnthropicTerminatorTracker()
+
         try:
             # H3: stream over the shared client (pool / keep-alive / TLS
             # reuse). Only the ``stream(...)`` context is scoped here; the
@@ -514,6 +593,7 @@ class AnthropicAdapter(BaseAdapter):
                                 current_event = None
                                 data_lines = []
                                 continue
+                            terminator.observe(current_event, data_obj)
                             for out_event in self._process_stream_event_for_filters(
                                 AnthropicStreamEvent(type=current_event, data=data_obj),
                                 chains=filter_chains,
@@ -542,12 +622,37 @@ class AnthropicAdapter(BaseAdapter):
                     except json.JSONDecodeError:
                         data_obj = None
                     if data_obj is not None:
+                        terminator.observe(current_event, data_obj)
                         for out_event in self._process_stream_event_for_filters(
                             AnthropicStreamEvent(type=current_event, data=data_obj),
                             chains=filter_chains,
                             logged_flag=logged_flag,
                         ):
                             yield out_event
+
+            # v2.15.0 (stream-truncation): the upstream line iterator is
+            # exhausted. Reaching here with no terminator observed means the
+            # HTTP body ended cleanly while the Anthropic message was still
+            # open — the exact case transport-level error handling below
+            # cannot see (``httpx.RemoteProtocolError`` and timeouts already
+            # raise). Under ``off`` this block is inert, which is what keeps
+            # the default byte-for-byte identical to v2.14.0.
+            if truncation_action != "off" and not terminator.saw_terminator:
+                log_stream_truncation_detected(
+                    logger,
+                    self.name,
+                    action=truncation_action,
+                    wire="anthropic",
+                    events_forwarded=terminator.events,
+                    saw_stream_start=terminator.saw_start,
+                    tool_call_in_flight=terminator.tool_call_in_flight,
+                )
+                if truncation_action == "error":
+                    raise StreamTruncatedError(
+                        "upstream stream truncated (no message_stop terminator)",
+                        provider=self.name,
+                        tool_call_in_flight=terminator.tool_call_in_flight,
+                    )
         except httpx.TimeoutException as exc:
             raise AdapterError(
                 f"timeout streaming from {url}", provider=self.name, retryable=True

coderouter/adapters/base.py

@@ -137,6 +137,49 @@ class AdapterError(CodeRouterError):
         return f"[{self.provider}{sc}] {super().__str__()}"
 
 
+# v2.15.0 (stream-truncation): raised by an adapter when the upstream SSE
+# stream ended *without* its protocol terminator (``message_stop`` on the
+# Anthropic wire, ``data: [DONE]`` / a ``finish_reason`` on the OpenAI wire).
+#
+# HTTP-level breakage (timeout, ``httpx.RemoteProtocolError``) already became a
+# plain ``AdapterError`` in both adapters. This subclass covers the layer
+# mismatch the transport cannot see: the HTTP body ended cleanly, but the *LLM
+# protocol* carried inside it was still mid-message.
+#
+# It subclasses ``AdapterError`` on purpose — every existing engine branch
+# (``except AdapterError``) keeps working untouched, and the L2/L4/L5/L6 guards
+# learn from the failure automatically. The subclass only adds identity, so
+# ``classify_adapter_error`` can label the hop ``stream-truncated`` instead of
+# the generic ``upstream-error``.
+#
+# Raised only when the active profile sets ``stream_truncation_action: error``.
+# Under ``off`` (the default) and ``warn`` the adapter returns normally and the
+# legacy terminator-synthesis path in ``coderouter.translation.convert`` (H6 /
+# M9) runs byte-for-byte as before.
+class StreamTruncatedError(AdapterError):
+    """Upstream SSE stream ended without its protocol terminator event."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        provider: str,
+        tool_call_in_flight: bool = False,
+    ) -> None:
+        """Construct a truncation error.
+
+        Args:
+            message: Human-readable reason. Never contains upstream body text.
+            provider: The ``ProviderConfig.name`` whose stream was cut.
+            tool_call_in_flight: True when the stream was cut while a
+                ``tool_use`` / ``tool_calls`` block was still open, i.e. the
+                accumulated argument JSON is certainly incomplete. Carried for
+                observability only — it never changes control flow.
+        """
+        super().__init__(message, provider=provider, status_code=None, retryable=True)
+        self.tool_call_in_flight = tool_call_in_flight
+
+
 # v0.6-B: per-call overrides resolved from the active profile. The engine
 # builds one instance per request (since a profile is invariant across its
 # chain) and threads it through every adapter call on that chain. Adapters
@@ -150,6 +193,13 @@ class AdapterError(CodeRouterError):
 #   - ``append_system_prompt=""`` is a meaningful explicit value: "for
 #     this profile, clear the provider's directive". The adapter must
 #     distinguish ``None`` (no override) from ``""`` (override-to-empty).
+#
+# v2.15.0 (stream-truncation): ``stream_truncation_action`` rides the same
+# channel. It is a *profile*-level knob but has to be read inside the adapter's
+# SSE parse loop, and ``ProviderCallOverrides`` is the only object the engine
+# already threads into every adapter call. Its default of ``"off"`` keeps
+# ``ProviderCallOverrides()`` (and every legacy call site that passes nothing)
+# on the pre-v2.15.0 behavior.
 class ProviderCallOverrides(BaseModel):
     """Per-call provider overrides, resolved from the active profile."""
 
@@ -157,6 +207,7 @@ class ProviderCallOverrides(BaseModel):
 
     timeout_s: float | None = None
     append_system_prompt: str | None = None
+    stream_truncation_action: Literal["off", "warn", "error"] = "off"
 
 
 class BaseAdapter(ABC):
@@ -236,6 +287,20 @@ class BaseAdapter(ABC):
             return overrides.append_system_prompt or None
         return self.config.append_system_prompt
 
+    def effective_stream_truncation_action(
+        self, overrides: ProviderCallOverrides | None
+    ) -> str:
+        """v2.15.0: resolve ``stream_truncation_action`` for this call.
+
+        There is no per-provider counterpart — the knob lives on the profile
+        only — so this is just a null-safe read. ``None`` overrides (legacy
+        call sites, unit tests constructing adapters directly) resolve to
+        ``"off"``, which is the pre-v2.15.0 behavior.
+        """
+        if overrides is None:
+            return "off"
+        return overrides.stream_truncation_action
+
     @abstractmethod
     async def healthcheck(self) -> bool:
         """Lightweight check that the upstream is reachable. Return True if healthy."""

coderouter/adapters/openai_compat.py

@@ -28,12 +28,14 @@ from coderouter.adapters.base import (
     ChatResponse,
     ProviderCallOverrides,
     StreamChunk,
+    StreamTruncatedError,
 )
 from coderouter.credentials import resolve_provider_credential
 from coderouter.logging import (
     get_logger,
     log_capability_degraded,
     log_output_filter_applied,
+    log_stream_truncation_detected,
 )
 from coderouter.output_filters import OutputFilterChain
 
@@ -347,6 +349,20 @@ class OpenAICompatAdapter(BaseAdapter):
         # Captured for the closing flush chunk (if any): reuse the last
         # seen chunk's id/model so the flush emission looks native.
         last_chunk_template: dict[str, Any] | None = None
+
+        # v2.15.0 (stream-truncation): the loop below used to treat "saw
+        # [DONE]" and "the line iterator ran out" as the same event. These
+        # three flags are the memory that tells them apart.
+        #
+        # A terminator is EITHER ``data: [DONE]`` OR a ``finish_reason`` on
+        # any choice. Accepting ``finish_reason`` matters: a provider that
+        # emits a complete message and then closes without the ``[DONE]``
+        # sentinel is not truncated, and flagging it would be a false
+        # positive. See ``stream_truncation_action`` in ``config/schemas.py``.
+        truncation_action = self.effective_stream_truncation_action(overrides)
+        saw_terminator = False
+        chunks_seen = 0
+        tool_call_in_flight = False
         try:
             # H3: stream over the shared client so the connection pool /
             # keep-alive / TLS session are reused. Only the ``stream(...)``
@@ -376,11 +392,31 @@ class OpenAICompatAdapter(BaseAdapter):
                         continue
                     data_str = line[len("data:") :].strip()
                     if data_str == "[DONE]":
+                        # v2.15.0: the sentinel — this stream ended on purpose.
+                        saw_terminator = True
                         break
                     try:
                         payload_obj = json.loads(data_str)
                     except json.JSONDecodeError:
                         continue  # skip malformed chunks rather than abort
+                    # v2.15.0 (stream-truncation): fold this chunk into the
+                    # terminator state before any filtering / validation, so a
+                    # chunk that is later dropped as malformed still counts as
+                    # "the upstream got this far".
+                    chunks_seen += 1
+                    for _choice in payload_obj.get("choices") or []:
+                        if not isinstance(_choice, dict):
+                            continue
+                        if _choice.get("finish_reason"):
+                            # A finish_reason means the message is complete
+                            # even if the [DONE] sentinel never arrives, and
+                            # it also closes any tool call that was open.
+                            saw_terminator = True
+                            tool_call_in_flight = False
+                        elif isinstance(_choice.get("delta"), dict) and _choice[
+                            "delta"
+                        ].get("tool_calls"):
+                            tool_call_in_flight = True
                     if strip_reasoning:
                         stripped = _strip_reasoning_field(
                             payload_obj.get("choices"), delta_key=True
@@ -446,6 +482,30 @@ class OpenAICompatAdapter(BaseAdapter):
                         streaming=True,
                     )
                     output_filter_logged = True
+
+            # v2.15.0 (stream-truncation): decided AFTER the filter flush on
+            # purpose — the flush is the last chance to hand the caller every
+            # safe byte the filter chain was still holding, and under
+            # ``partial_stitch_action: surface`` those bytes end up in the
+            # partial content the client receives. Under ``off`` this block is
+            # inert, keeping the default byte-for-byte identical to v2.14.0.
+            if truncation_action != "off" and not saw_terminator:
+                log_stream_truncation_detected(
+                    logger,
+                    self.name,
+                    action=truncation_action,
+                    wire="openai",
+                    events_forwarded=chunks_seen,
+                    saw_stream_start=chunks_seen > 0,
+                    tool_call_in_flight=tool_call_in_flight,
+                )
+                if truncation_action == "error":
+                    raise StreamTruncatedError(
+                        "upstream stream truncated "
+                        "(no [DONE] sentinel and no finish_reason)",
+                        provider=self.name,
+                        tool_call_in_flight=tool_call_in_flight,
+                    )
         except httpx.TimeoutException as exc:
             raise AdapterError(
                 f"timeout streaming from {url}", provider=self.name, retryable=True

coderouter/config/schemas.py

@@ -1232,6 +1232,71 @@ class FallbackChain(BaseModel):
         ),
     )
 
+    # --- v2.15.0 (stream-truncation): upstream SSE cut without a terminator --
+    #
+    # A streaming upstream can end its HTTP body *cleanly* while the LLM
+    # protocol carried inside it is still mid-message: no ``message_stop`` on
+    # the Anthropic wire, no ``data: [DONE]`` and no ``finish_reason`` on the
+    # OpenAI wire. llama.cpp slot preemption, an ``--n-predict`` cut-off, a
+    # front proxy closing an EOF-delimited body, or an OOM'd local server all
+    # produce exactly this shape. Transport-level breakage (timeout,
+    # ``httpx.RemoteProtocolError``) was already caught; this is the layer the
+    # transport cannot see.
+    #
+    # Before v2.15.0 that stream was indistinguishable from a complete one:
+    # the adapters never recorded whether a terminator arrived, and the
+    # translation layer's terminator-synthesis guards (H6 / M9 in
+    # ``coderouter.translation.convert``) then fabricated a ``stop_reason:
+    # end_turn`` / ``finish_reason: "stop"`` so the client would not hang. The
+    # synthesis is correct and stays; what was missing is telling the *engine*
+    # that it happened.
+    #
+    #   * ``off``   — no detection, no log, no metric. Backward-compatible
+    #                 default: byte-for-byte identical to v2.14.0 on every path.
+    #   * ``warn``  — emit a ``stream-truncation-detected`` log line (and the
+    #                 ``stream_truncated_total`` metric); the stream still
+    #                 terminates through the legacy synthesis path, so the
+    #                 client sees exactly what it saw before.
+    #   * ``error`` — the adapter raises ``StreamTruncatedError`` (a retryable
+    #                 ``AdapterError``) at the point the terminator should have
+    #                 arrived. The engine's existing branches take over: no
+    #                 bytes forwarded yet → fall back to the next provider with
+    #                 reason ``stream-truncated``; bytes already forwarded →
+    #                 ``MidStreamError``, which ``partial_stitch_action:
+    #                 surface`` renders as a graceful close carrying a
+    #                 ``coderouter_partial`` event with reason
+    #                 ``stream_truncated``.
+    #
+    # Caveats for ``error``:
+    #   * False positives are possible against an upstream that legitimately
+    #     omits the terminator. A ``message_delta`` carrying a ``stop_reason``
+    #     (Anthropic) and a ``finish_reason`` on any choice (OpenAI) are both
+    #     accepted as terminators to keep that risk low, but running ``warn``
+    #     first to measure the real rate is the recommended rollout.
+    #   * Falling back re-generates the answer on the next provider, so the
+    #     tokens the truncated attempt burned are paid twice.
+    #   * On the Anthropic streaming path the pre-content fallback requires
+    #     ``empty_response_action: fallback`` as well — that is the knob that
+    #     withholds the opening events from the client. Without it the opening
+    #     ``message_start`` has already shipped, so a truncation is by
+    #     definition mid-stream.
+    stream_truncation_action: Literal["off", "warn", "error"] = Field(
+        default="off",
+        description=(
+            "v2.15.0: action when an upstream SSE stream ends without its "
+            "protocol terminator (no ``message_stop`` / no ``[DONE]`` and no "
+            "``finish_reason``). ``off`` (default) does nothing — identical to "
+            "v2.14.0. ``warn`` emits a ``stream-truncation-detected`` log and "
+            "metric while the stream still ends through the legacy terminator "
+            "synthesis. ``error`` raises a retryable ``StreamTruncatedError`` "
+            "so the engine falls back to the next provider (reason "
+            "``stream-truncated``) when nothing has reached the client yet, or "
+            "raises ``MidStreamError`` when it has. Pair with "
+            "``empty_response_action: fallback`` for pre-content fallback on "
+            "the Anthropic streaming path."
+        ),
+    )
+
     # --- ⑧ (empty-response): per-request empty-response fallback ------------
     #
     # Some local backends (observed: gemma4:26b on ``no_tool_temptation``

coderouter/doctor.py

@@ -635,6 +635,49 @@ _PROBE_TOOL_SPEC_ANTHROPIC = {
 }
 
 
+# v2.15.1: llama.cpp changed ``llama-server``'s default listen port from
+# 8080 to 9931 (ggml-org/llama.cpp#30159, build b11521, 2026-10-09). A server
+# started without ``--port`` on a new build is invisible to a provider that
+# still points at :8080, and the reverse holds for configs written against
+# the new default. When the basic probe cannot connect to one of those two
+# ports on a loopback host, check the other one so the transport error can
+# name the likely cause instead of looking like "server not running".
+_LLAMACPP_PORT_PAIR: dict[int, int] = {8080: 9931, 9931: 8080}
+_LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+
+
+async def _llamacpp_port_hint(base_url: object) -> str | None:
+    """Return a hint when the other llama.cpp default port answers.
+
+    Only fires for loopback hosts on port 8080 or 9931. The alternate
+    port is probed at ``GET /health`` (llama-server's readiness route)
+    with a short timeout on the IPv4 literal — ``localhost`` can resolve
+    to ``::1`` first on macOS, where llama-server is not listening. The
+    config is never rewritten; the operator decides.
+    """
+    try:
+        parsed = httpx.URL(str(base_url))
+    except (httpx.InvalidURL, TypeError):
+        return None
+    if parsed.host not in _LOOPBACK_HOSTS or parsed.port not in _LLAMACPP_PORT_PAIR:
+        return None
+    other = _LLAMACPP_PORT_PAIR[parsed.port]
+    try:
+        async with httpx.AsyncClient(timeout=1.5) as client:
+            resp = await client.get(f"http://127.0.0.1:{other}/health")
+    except httpx.HTTPError:
+        return None
+    if resp.status_code >= 500:
+        return None
+    return (
+        f"Something is answering on port {other} instead. llama.cpp "
+        f"builds b11521+ listen on 9931 when started without --port "
+        f"(older builds: 8080). Either start llama-server with "
+        f"--port {parsed.port}, or change this provider's base_url to "
+        f"port {other}"
+    )
+
+
 async def _probe_auth_and_basic_chat(
     provider: ProviderConfig,
 ) -> ProbeResult:
@@ -670,10 +713,14 @@ async def _probe_auth_and_basic_chat(
     )
 
     if status is None:
+        detail = f"could not reach {url}: {raw}"
+        hint = await _llamacpp_port_hint(provider.base_url)
+        if hint:
+            detail = f"{detail}. {hint}"
         return ProbeResult(
             name="auth+basic-chat",
             verdict=ProbeVerdict.TRANSPORT_ERROR,
-            detail=f"could not reach {url}: {raw}",
+            detail=detail,
         )
 
     if status in (401, 403):

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.