coderouter-cli 2.6.1__tar.gz → 2.7.0__tar.gz

{coderouter_cli-2.6.1 → coderouter_cli-2.7.0}/CHANGELOG.md

@@ -6,6 +6,143 @@ versioning follows [SemVer](https://semver.org/).
 
 ---
 
+## [v2.7.0] — 2026-07-02 (Reliability & security: full-source review fixes)
+
+22 reliability and security fixes from a full-source review (26,600 lines),
+landed as two sequential PRs: high-priority **PR #34** (H1–H8) and
+medium-priority **PR #35** (M1–M14), both merged to `main`. No API or
+config-schema breaking changes. Backward compatibility highlights: the new
+launcher token auth is **opt-in** (`CODEROUTER_LAUNCHER_TOKEN` unset ⇒
+unchanged behavior + a startup warning), and the Host-validation middleware
+allows loopback by default with `CODEROUTER_ALLOWED_HOSTS` to extend it.
+
+### Fixed
+
+- **`/metrics` 500 when drift counters are non-zero** — three malformed
+  Prometheus label tuples (`(((),), v)` → `((), v)`) (`coderouter/metrics/prometheus.py`, PR #34/H1).
+- **`tool_repair` deleted unrelated fenced code blocks** while stripping
+  tool-call-shaped ones, losing user content
+  (`coderouter/translation/tool_repair.py`, PR #34/H2).
+- **Probe URL mismatch (`/v1/v1` duplication)** between the continuous probe
+  and the adapters caused healthy backends to be wrongly demoted; URL
+  normalization is now shared
+  (`coderouter/adapters/anthropic_native.py`, `coderouter/guards/continuous_probe.py`, PR #34/H4).
+- **`context_budget` dropped entire history at once** on threshold breach;
+  trimming is now sequential per tool-pair with re-estimation after each
+  step, and the new head turn is renormalized to a plain user turn
+  (`coderouter/guards/context_budget.py`, PR #34/H5).
+- **Empty-stream termination violated the SSE protocol** by sending a
+  terminator with no preceding `message_start`; one is now synthesized
+  first (`coderouter/translation/convert.py`, PR #34/H6).
+- **Excluded providers never recovered after a restart** — restored
+  self-healing state didn't re-arm recovery probes (only the live
+  UNHEALTHY-transition path did); probes are now re-spawned after state
+  restore, queued if the event loop isn't running yet
+  (`coderouter/routing/fallback.py`, `coderouter/guards/self_healing.py`, PR #34/H7).
+- **Malformed upstream responses bypassed retry/fallback** — an uncaught
+  pydantic `ValidationError` on missing/misshaped fields now converts to a
+  retryable `AdapterError` on non-stream paths, and stream paths skip the
+  malformed chunk with a once-per-stream warning
+  (`coderouter/adapters/anthropic_native.py`, `coderouter/adapters/openai_compat.py`, PR #35/M6).
+- **`"oom"` substring matched inside `"room"` / `"zoom"` / `"bloom"`** in
+  upstream error bodies, cooling down healthy providers; the memory-pressure
+  guard now matches the token on word boundaries
+  (`coderouter/guards/memory_pressure.py`, PR #35/M10).
+- **Interleaved text/tool-call deltas sent `input_json_delta` to
+  already-closed block indices** — blocks are now reopened at a fresh index
+  with their original `id`/`name` preserved
+  (`coderouter/translation/convert.py`, PR #35/M7).
+- **`tool_result.is_error` was dropped in both translation directions** — an
+  `"Error: "` content marker now round-trips the flag without
+  double-prefixing (`coderouter/translation/convert.py`, PR #35/M8).
+- **Streams ending without `message_stop` sent no terminal chunk**, hanging
+  OpenAI-compatible clients; a `finish_reason` + usage chunk is now
+  synthesized on abnormal termination (mirrors the H6 fix in the other
+  direction) (`coderouter/translation/convert.py`, PR #35/M9).
+- **`configure_logging` permanently detached the metrics collector** on a
+  second `create_app()` call by removing every root handler;
+  `install_collector` now re-attaches when missing, and
+  `configure_logging` removes only its own marked handlers
+  (`coderouter/logging.py`, PR #35/M4).
+- **Metrics persistence save/load asymmetry** zeroed language-tax
+  accounting on every restart — `save_state` was missing
+  `language_tax_usd` / `language_tax_usd_aggregate`, which `load_state`
+  expects (`coderouter/metrics/collector.py`, PR #35/M5).
+
+### Changed
+
+- **Config validation now fails fast at load time.** Previously-silent
+  misconfiguration is now rejected: profile chains referencing unknown
+  provider names, duplicate provider/profile names, inverted thresholds
+  (e.g. `context_budget` warn > trim, `trim_target` ≥ `trim_threshold`,
+  `recovery_probe_initial_s` > `recovery_probe_max_s`), and
+  `has_tools: false` / `has_image: false` matchers (which could never
+  match) (`coderouter/config/schemas.py`, PR #35/M13).
+- **Drift-based chain demotion now applies regardless of the `adaptive`
+  flag.** A dedicated cooldown-based demotion map is applied in
+  `_resolve_anthropic_chain` unconditionally; previously demotion only
+  affected ordering when `profile.adaptive` was true (and did nothing
+  under five samples) (`coderouter/routing/fallback.py`, PR #35/M3).
+- **Adaptive routing now observes streaming paths.** `record_attempt` was
+  only called from `generate_anthropic`; all four entry points
+  (`stream_anthropic` / `stream` / `generate` and non-stream) now record
+  first-event latency and outcomes, including Claude Code's default
+  streaming path (`coderouter/routing/fallback.py`, PR #35/M2).
+- **Drift verdicts are now request-scoped (`ContextVar`)** instead of
+  stored on the shared engine, eliminating a race where concurrent
+  requests could read another request's drift header or a stale verdict
+  during cooldown; the engine attribute remains as a deprecated mirror
+  (`coderouter/routing/fallback.py`, PR #35/M1).
+- **Chain resolution and context estimation no longer run twice per
+  request** — the resolved dispatch is cached per request and reused when
+  the request object is unchanged (`coderouter/routing/fallback.py`, PR #35/M11).
+- **Request/audit logs are now buffered** (20 records or 2 seconds,
+  flushed on close/`atexit`; `flush_every_n=1` restores write-through)
+  instead of synchronous per-request writes
+  (`coderouter/state/audit_log.py`, `coderouter/state/request_log.py`, PR #35/M12).
+- **The metrics collector hot path exits early** for unrecognized events
+  before acquiring the lock, and known events are dispatched via a dict
+  table instead of a ~30-branch `if`/`elif` chain
+  (`coderouter/metrics/collector.py`, PR #35/M12).
+- **Adapters now share a single `httpx.AsyncClient`** (lazily created,
+  per-call timeout override, closed on shutdown) instead of creating one
+  per request, enabling keep-alive/TLS session reuse
+  (`coderouter/adapters/base.py`, `coderouter/adapters/openai_compat.py`,
+  `coderouter/adapters/anthropic_native.py`, `coderouter/ingress/app.py`, PR #34/H3).
+
+### Security
+
+- **Host-validation middleware** on all routes rejects non-loopback `Host`
+  headers as a DNS-rebinding defense; loopback
+  (`localhost` / `127.0.0.1` / `[::1]`) is allowed by default and
+  `CODEROUTER_ALLOWED_HOSTS` (comma-separated) extends the allowlist
+  (`coderouter/ingress/app.py`, PR #34/H8).
+- **Opt-in launcher token authentication.** `launcher start/stop/delete`
+  require the `X-CodeRouter-Token` header (constant-time compare) when
+  `CODEROUTER_LAUNCHER_TOKEN` is set; unset behaves exactly as before, with
+  a one-time startup warning (`coderouter/ingress/launcher_routes.py`, PR #34/H8).
+- **`-m`/`--model` re-specification rejected** in launcher `extra_args`/
+  `options` to block arbitrary model-path injection
+  (`coderouter/ingress/launcher_routes.py`, PR #34/H8).
+- **Request body size cap** (64 MB default, `CODEROUTER_MAX_BODY_BYTES`
+  override) returns 413; SSE responses are unaffected
+  (`coderouter/ingress/app.py`, PR #35/M14).
+- **`/api/launcher/suggest` path confinement** — resolved paths must now
+  fall inside the configured `model_dirs`, closing an arbitrary-path
+  existence/size probe (`coderouter/ingress/launcher_routes.py`, PR #35/M14).
+
+### Tests
+
+- Full suite grew from **1263 → 1401 passed** (1 skipped, environment-only)
+  across the two PRs: 139 new regression tests in 12 new test files
+  (`tests/test_fix_h*.py` ×6, `tests/test_fix_m*.py` ×6). One existing test,
+  `tests/test_auto_router.py::test_has_tools_false_rejected_at_load`, was
+  flipped to expect `ValidationError` — its own docstring had anticipated
+  this once the new config validator (M13) landed; it is the only existing
+  test changed by either PR.
+
+---
+
 ## [v2.6.1] — 2026-06-28 (Token-savings accounting)
 
 Patch release: surfaces **token-savings accounting** in the metrics layer

{coderouter_cli-2.6.1 → coderouter_cli-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coderouter-cli
-Version: 2.6.1
+Version: 2.7.0
 Summary: Local-first, free-first, fallback-built-in LLM router. Claude Code / OpenAI compatible.
 Project-URL: Homepage, https://github.com/zephel01/CodeRouter
 Project-URL: Repository, https://github.com/zephel01/CodeRouter

{coderouter_cli-2.6.1 → coderouter_cli-2.7.0}/coderouter/adapters/anthropic_native.py

@@ -35,6 +35,7 @@ from collections.abc import AsyncIterator
 from typing import Any
 
 import httpx
+from pydantic import ValidationError
 
 from coderouter.adapters.base import (
     AdapterError,
@@ -68,6 +69,26 @@ _RETRYABLE_STATUSES = {404, 408, 425, 429, 500, 502, 503, 504}
 _DEFAULT_ANTHROPIC_VERSION = "2023-06-01"
 
 
+def anthropic_messages_url(base_url: str) -> str:
+    """Resolve the ``/v1/messages`` endpoint URL from a ``base_url``.
+
+    ``base_url`` may be given with or without a trailing ``/v1`` — users
+    may point it at either ``https://api.anthropic.com`` or
+    ``https://api.anthropic.com/v1`` (LM Studio and similar servers
+    commonly advertise the latter). We normalize by stripping a trailing
+    ``/v1`` so appending ``/v1/messages`` always yields a valid,
+    non-duplicated URL.
+
+    Shared by :class:`AnthropicAdapter` and the continuous-probe guard so
+    both hit the exact same endpoint (see bug H4: a mismatch made the
+    probe target ``/v1/v1/messages`` and 404 on healthy backends).
+    """
+    base = base_url.rstrip("/")
+    if base.endswith("/v1"):
+        base = base[: -len("/v1")]
+    return f"{base}/v1/messages"
+
+
 class AnthropicAdapter(BaseAdapter):
     """Native Anthropic Messages API adapter (passthrough).
 
@@ -87,15 +108,10 @@ class AnthropicAdapter(BaseAdapter):
 
         ``base_url`` may be given with or without a trailing ``/v1`` —
         we normalize by stripping it so appending ``/v1/messages``
-        always yields a valid URL.
+        always yields a valid URL. Delegates to the shared
+        :func:`anthropic_messages_url` helper.
         """
-        base = str(self.config.base_url).rstrip("/")
-        # Users may point base_url at either `https://api.anthropic.com`
-        # or `https://api.anthropic.com/v1`. We normalize to the former so
-        # we can always append /v1/messages.
-        if base.endswith("/v1"):
-            base = base[: -len("/v1")]
-        return f"{base}/v1/messages"
+        return anthropic_messages_url(str(self.config.base_url))
 
     def _headers(self, request: AnthropicRequest | None = None) -> dict[str, str]:
         """Build Anthropic-native HTTP headers, including beta-header forwarding.
@@ -161,21 +177,21 @@ class AnthropicAdapter(BaseAdapter):
         that auth works and the endpoint is reachable.
         """
         try:
-            async with httpx.AsyncClient(timeout=5.0) as client:
-                resp = await client.post(
-                    self._url(),
-                    headers=self._headers(),
-                    json={
-                        "model": self.config.model,
-                        "max_tokens": 1,
-                        "messages": [{"role": "user", "content": "ping"}],
-                    },
-                )
-                # 200 is clearly healthy. 4xx auth errors indicate the
-                # endpoint is reachable even if the key is bad — still a
-                # "the server answered" signal for healthcheck purposes.
-                # 5xx is upstream trouble.
-                return resp.status_code < 500
+            resp = await self.client().post(
+                self._url(),
+                headers=self._headers(),
+                json={
+                    "model": self.config.model,
+                    "max_tokens": 1,
+                    "messages": [{"role": "user", "content": "ping"}],
+                },
+                timeout=5.0,
+            )
+            # 200 is clearly healthy. 4xx auth errors indicate the
+            # endpoint is reachable even if the key is bad — still a
+            # "the server answered" signal for healthcheck purposes.
+            # 5xx is upstream trouble.
+            return resp.status_code < 500
         except httpx.HTTPError:
             return False
 
@@ -331,8 +347,9 @@ class AnthropicAdapter(BaseAdapter):
         timeout = self.effective_timeout(overrides)
 
         try:
-            async with httpx.AsyncClient(timeout=timeout) as client:
-                resp = await client.post(url, json=payload, headers=self._headers(request))
+            resp = await self.client().post(
+                url, json=payload, headers=self._headers(request), timeout=timeout
+            )
         except httpx.TimeoutException as exc:
             raise AdapterError(
                 f"timeout contacting {url}", provider=self.name, retryable=True
@@ -394,7 +411,22 @@ class AnthropicAdapter(BaseAdapter):
         # (future additions like thinking blocks) pass through via
         # extra="allow" on AnthropicResponse.
         data["coderouter_provider"] = self.name
-        return AnthropicResponse.model_validate(data)
+        # M6: guard the model validation. A 200 body that isn't a valid
+        # Anthropic Messages response (missing ``content``/``id``, an
+        # error envelope returned with a 200, etc.) would otherwise raise
+        # a bare pydantic ValidationError that escapes the engine's
+        # AdapterError-based retry/fallback path. Convert to a retryable
+        # AdapterError so the chain can fall through (mirrors the
+        # invalid-JSON branch above, but retryable — a malformed shape is
+        # usually transient upstream noise rather than a config fault).
+        try:
+            return AnthropicResponse.model_validate(data)
+        except ValidationError as exc:
+            raise AdapterError(
+                f"malformed response shape from upstream: {exc}",
+                provider=self.name,
+                retryable=True,
+            ) from exc
 
     async def stream_anthropic(
         self,
@@ -424,10 +456,14 @@ class AnthropicAdapter(BaseAdapter):
         logged_flag: list[bool] = [False]
 
         try:
-            async with (
-                httpx.AsyncClient(timeout=timeout) as client,
-                client.stream("POST", url, json=payload, headers=self._headers(request)) as resp,
-            ):
+            # H3: stream over the shared client (pool / keep-alive / TLS
+            # reuse). Only the ``stream(...)`` context is scoped here; the
+            # client persists and is closed via ``aclose`` on shutdown. The
+            # ``async with`` releases the response's borrowed connection even
+            # if the caller abandons this generator mid-stream — no GC leak.
+            async with self.client().stream(
+                "POST", url, json=payload, headers=self._headers(request), timeout=timeout
+            ) as resp:
                 if resp.status_code >= 400:
                     body = await resp.aread()
                     raise AdapterError(

{coderouter_cli-2.6.1 → coderouter_cli-2.7.0}/coderouter/adapters/base.py

@@ -11,6 +11,7 @@ from abc import ABC, abstractmethod
 from collections.abc import AsyncIterator
 from typing import Any, Literal
 
+import httpx
 from pydantic import BaseModel, ConfigDict, Field
 
 from coderouter.config.schemas import ProviderConfig
@@ -164,17 +165,59 @@ class BaseAdapter(ABC):
     def __init__(self, config: ProviderConfig) -> None:
         """Bind the adapter to a :class:`ProviderConfig`.
 
-        Subclasses do not need to override this; HTTP clients are
-        constructed lazily inside :meth:`generate` / :meth:`stream` so
-        each call can honor a per-call timeout override.
+        Subclasses do not need to override this. A single shared
+        :class:`httpx.AsyncClient` is created lazily on first use (see
+        :meth:`client`) and reused across every call on this adapter so
+        the connection pool, HTTP keep-alive, and TLS session are all
+        reused. Per-call timeouts are still honored by passing
+        ``timeout=`` to ``client.post`` / ``client.stream`` — they do
+        NOT require a fresh client.
         """
         self.config = config
+        # Shared client, created lazily inside the running event loop the
+        # first time an adapter method needs it (see ``client``). Kept as
+        # ``None`` until then so constructing an adapter has no I/O cost and
+        # is safe outside an event loop (e.g. at import / config time).
+        self._client: httpx.AsyncClient | None = None
 
     @property
     def name(self) -> str:
         """Shortcut for ``self.config.name`` — used in log trails and errors."""
         return self.config.name
 
+    # ---- H3: shared HTTP client (connection-pool / keep-alive reuse) ----
+    def client(self) -> httpx.AsyncClient:
+        """Return the shared :class:`httpx.AsyncClient`, creating it lazily.
+
+        The client is created on first use so construction happens inside
+        the running event loop and carries no I/O cost at adapter-build
+        time. Subsequent calls return the same instance, which is what
+        lets httpx reuse pooled connections, keep-alive, and the TLS
+        session across requests.
+
+        No default timeout is baked in here: every call site passes an
+        explicit per-call ``timeout=`` (resolved from the active profile
+        via :meth:`effective_timeout`), so leaving the client timeout
+        unset avoids a surprising default clamping long-running calls.
+        """
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=None)
+        return self._client
+
+    async def aclose(self) -> None:
+        """Close the shared HTTP client and drop the reference.
+
+        Idempotent: safe to call when no client was ever created, and
+        safe to call more than once. Invoked from the app lifespan
+        shutdown path so pooled connections are released cleanly rather
+        than left to garbage collection. After ``aclose`` a later call
+        re-creates the client on demand via :meth:`client`.
+        """
+        client = self._client
+        self._client = None
+        if client is not None:
+            await client.aclose()
+
     # ---- v0.6-B override resolution helpers -----------------------------
     def effective_timeout(self, overrides: ProviderCallOverrides | None) -> float:
         """Profile override wins when set; else provider default."""

{coderouter_cli-2.6.1 → coderouter_cli-2.7.0}/coderouter/adapters/openai_compat.py

@@ -19,6 +19,7 @@ from collections.abc import AsyncIterator
 from typing import Any
 
 import httpx
+from pydantic import ValidationError
 
 from coderouter.adapters.base import (
     AdapterError,
@@ -197,9 +198,8 @@ class OpenAICompatAdapter(BaseAdapter):
         base = str(self.config.base_url).rstrip("/")
         url = f"{base}/models"
         try:
-            async with httpx.AsyncClient(timeout=5.0) as client:
-                resp = await client.get(url, headers=self._headers())
-                return resp.status_code < 500
+            resp = await self.client().get(url, headers=self._headers(), timeout=5.0)
+            return resp.status_code < 500
         except httpx.HTTPError:
             return False
 
@@ -221,8 +221,9 @@ class OpenAICompatAdapter(BaseAdapter):
         payload = self._payload(request, stream=False, overrides=overrides)
         timeout = self.effective_timeout(overrides)
         try:
-            async with httpx.AsyncClient(timeout=timeout) as client:
-                resp = await client.post(url, json=payload, headers=self._headers())
+            resp = await self.client().post(
+                url, json=payload, headers=self._headers(), timeout=timeout
+            )
         except httpx.TimeoutException as exc:
             raise AdapterError(
                 f"timeout contacting {url}", provider=self.name, retryable=True
@@ -287,7 +288,22 @@ class OpenAICompatAdapter(BaseAdapter):
 
         # Tag the response with which provider answered
         data.setdefault("object", "chat.completion")
-        return ChatResponse(coderouter_provider=self.name, **data)
+        # M6: a syntactically valid JSON body may still not be a valid
+        # Chat Completions response (e.g. an OpenAI-compat server that
+        # returns ``{"error": ...}`` with a 200, or omits ``choices``).
+        # pydantic raises ValidationError here; if left uncaught it would
+        # propagate past the engine's AdapterError-based retry/fallback
+        # logic. Convert to a retryable AdapterError so the chain can fall
+        # through to the next provider (mirrors the invalid-JSON branch,
+        # but retryable since a malformed shape is often transient).
+        try:
+            return ChatResponse(coderouter_provider=self.name, **data)
+        except ValidationError as exc:
+            raise AdapterError(
+                f"malformed response shape from upstream: {exc}",
+                provider=self.name,
+                retryable=True,
+            ) from exc
 
     async def stream(
         self,
@@ -312,6 +328,10 @@ class OpenAICompatAdapter(BaseAdapter):
         # produce dozens of duplicate log lines.
         strip_reasoning = not self.config.capabilities.reasoning_passthrough
         reasoning_logged = False
+        # M6: one-shot dedupe flag for the malformed-chunk warning. A single
+        # broken stream can emit many non-conforming chunks; we skip each one
+        # but log only on the first to avoid a log flood.
+        malformed_chunk_logged = False
 
         # v1.0-A: stateful output_filters chain for the duration of this
         # stream. Handles `<think>...</think>` / stop markers that split
@@ -325,10 +345,16 @@ class OpenAICompatAdapter(BaseAdapter):
         # seen chunk's id/model so the flush emission looks native.
         last_chunk_template: dict[str, Any] | None = None
         try:
-            async with (
-                httpx.AsyncClient(timeout=timeout) as client,
-                client.stream("POST", url, json=payload, headers=self._headers()) as resp,
-            ):
+            # H3: stream over the shared client so the connection pool /
+            # keep-alive / TLS session are reused. Only the ``stream(...)``
+            # context is entered here — the client itself outlives the
+            # stream and is closed via ``aclose`` on app shutdown. The
+            # ``async with`` guarantees the response (and its borrowed
+            # connection) is released even if the consumer abandons this
+            # generator mid-stream, so no connection leaks on GC.
+            async with self.client().stream(
+                "POST", url, json=payload, headers=self._headers(), timeout=timeout
+            ) as resp:
                 if resp.status_code >= 400:
                     body = await resp.aread()
                     raise AdapterError(
@@ -375,7 +401,23 @@ class OpenAICompatAdapter(BaseAdapter):
                             if isinstance(content, str) and content:
                                 delta["content"] = filter_chain.feed(content)
                         last_chunk_template = payload_obj
-                    yield StreamChunk(**payload_obj)
+                    # M6: a chunk may be valid JSON yet not a valid
+                    # StreamChunk (e.g. a mid-stream ``{"error": ...}``
+                    # frame, or a chunk missing required fields). Rather
+                    # than let the ValidationError abort the whole stream
+                    # (bypassing the engine's AdapterError handling), skip
+                    # the bad chunk and keep consuming. Warn once per stream.
+                    try:
+                        chunk = StreamChunk(**payload_obj)
+                    except ValidationError as exc:
+                        if not malformed_chunk_logged:
+                            logger.warning(
+                                "malformed-stream-chunk",
+                                extra={"provider": self.name, "error": str(exc)},
+                            )
+                            malformed_chunk_logged = True
+                        continue
+                    yield chunk
 
             # v1.0-A: flush the chain at end-of-stream. If filters held
             # back a partial-tag suffix that turned out NOT to be a tag,

{coderouter_cli-2.6.1 → coderouter_cli-2.7.0}/coderouter/config/schemas.py

@@ -706,6 +706,63 @@ class FallbackChain(BaseModel):
         ),
     )
 
+    @model_validator(mode="after")
+    def _check_context_budget_thresholds_ordered(self) -> FallbackChain:
+        """v2.0-F (mE): cross-field sanity of the context-budget ratios.
+
+        The three ratios describe a strict staircase: a warning fires
+        first, then trimming kicks in at a higher usage, and trimming
+        reclaims space down to a target below the trim point. If they are
+        mis-ordered the guard is either a dead knob (warn above trim never
+        fires) or an infinite trim loop (target >= trim never converges).
+        Same fast-fail philosophy as ``_check_default_profile_exists`` —
+        surface the mistake at load with a concrete pointer to the fix
+        rather than at the first request that trips the guard.
+
+        Required invariants:
+          * ``context_budget_warn_threshold`` <= ``context_budget_trim_threshold``
+          * ``context_budget_trim_target``    <  ``context_budget_trim_threshold``
+        """
+        if self.context_budget_warn_threshold > self.context_budget_trim_threshold:
+            raise ValueError(
+                f"profile {self.name!r}: context_budget_warn_threshold "
+                f"({self.context_budget_warn_threshold}) must be <= "
+                f"context_budget_trim_threshold "
+                f"({self.context_budget_trim_threshold}) — the warning has to "
+                f"fire at or before trimming, otherwise it can never fire. "
+                f"Lower warn_threshold or raise trim_threshold."
+            )
+        if self.context_budget_trim_target >= self.context_budget_trim_threshold:
+            raise ValueError(
+                f"profile {self.name!r}: context_budget_trim_target "
+                f"({self.context_budget_trim_target}) must be < "
+                f"context_budget_trim_threshold "
+                f"({self.context_budget_trim_threshold}) — trimming must "
+                f"reclaim space *below* the trigger point, otherwise trim "
+                f"never converges. Lower trim_target below trim_threshold."
+            )
+        return self
+
+    @model_validator(mode="after")
+    def _check_recovery_probe_interval_ordered(self) -> FallbackChain:
+        """v2.0-J (mE): the recovery-probe backoff floor must not exceed its cap.
+
+        ``recovery_probe_initial_s`` is the first probe interval and each
+        failed probe doubles it up to ``recovery_probe_max_s``. When the
+        initial interval already exceeds the max, the exponential-backoff
+        ceiling is below its own floor — a nonsensical configuration that
+        the backoff loop would silently clamp. Surface it at load instead.
+        """
+        if self.recovery_probe_initial_s > self.recovery_probe_max_s:
+            raise ValueError(
+                f"profile {self.name!r}: recovery_probe_initial_s "
+                f"({self.recovery_probe_initial_s}) must be <= "
+                f"recovery_probe_max_s ({self.recovery_probe_max_s}) — the "
+                f"initial probe interval cannot exceed the backoff ceiling. "
+                f"Lower recovery_probe_initial_s or raise recovery_probe_max_s."
+            )
+        return self
+
 
 # ---------------------------------------------------------------------------
 # v1.6-A: auto_router — declarative request-body classifier
@@ -720,6 +777,14 @@ class RuleMatcher(BaseModel):
     adding a new optional field — the single-field invariant enforces
     discriminated-union semantics without pydantic's tagged-union syntax.
 
+    Boolean matchers (``has_image`` / ``has_tools``) only carry meaning at
+    ``True``: the runtime evaluator matches with ``is True`` (see
+    ``coderouter.routing.auto_router._match_rule``), so a ``False`` value
+    would construct without error yet never match anything — a dead rule
+    that silently shadows nothing and confuses operators. ``_exactly_one``
+    therefore rejects ``False`` for these fields at load (``None`` remains
+    the "unset" sentinel).
+
     Variants (v1.6-A):
 
     - ``has_image: True`` — any ``image_url`` / ``image`` /
@@ -822,8 +887,29 @@ class RuleMatcher(BaseModel):
         "cjk_ratio_min",
     )
 
+    # Boolean matcher fields carry meaning only at ``True`` — the runtime
+    # evaluator uses ``is True`` — so a ``False`` value is a dead rule that
+    # never matches. ``_exactly_one`` rejects it explicitly (see below).
+    _BOOL_MATCHER_FIELDS: tuple[str, ...] = ("has_image", "has_tools")
+
     @model_validator(mode="after")
     def _exactly_one(self) -> Self:
+        # Reject the dead-rule shape first so the error names the specific
+        # field the operator got wrong, rather than the generic
+        # "exactly one" message (``False`` counts as "set" below).
+        false_bools = [
+            name
+            for name in self._BOOL_MATCHER_FIELDS
+            if getattr(self, name) is False
+        ]
+        if false_bools:
+            raise ValueError(
+                f"RuleMatcher boolean matcher(s) set to False: {false_bools}. "
+                f"These matchers are evaluated with ``is True``, so a False "
+                f"value is a dead rule that never matches (it would silently "
+                f"shadow nothing). Use True to match, or omit the field "
+                f"(leave it None) to not use this matcher."
+            )
         set_fields = [
             name for name in self._MATCHER_FIELDS if getattr(self, name) is not None
         ]
@@ -1391,6 +1477,74 @@ class CodeRouterConfig(BaseModel):
             )
         return self
 
+    @model_validator(mode="after")
+    def _check_names_unique(self) -> CodeRouterConfig:
+        """mE: provider and profile names must each be unique.
+
+        ``provider_by_name`` / ``profile_by_name`` return the *first*
+        match, so a duplicate name silently shadows every later entry with
+        the same key — the operator's second ``local:`` block is loaded,
+        validated, and then never reachable. Reject duplicates at load with
+        the offending names, matching the fast-fail philosophy of the other
+        ``_check_*`` validators.
+        """
+        seen_p: set[str] = set()
+        dup_p: list[str] = []
+        for p in self.providers:
+            if p.name in seen_p and p.name not in dup_p:
+                dup_p.append(p.name)
+            seen_p.add(p.name)
+        if dup_p:
+            raise ValueError(
+                f"duplicate provider name(s): {sorted(dup_p)}. Provider names "
+                f"must be unique — a duplicate silently shadows the later "
+                f"entry (provider_by_name returns the first match). Rename or "
+                f"remove the duplicate(s)."
+            )
+
+        seen_f: set[str] = set()
+        dup_f: list[str] = []
+        for prof in self.profiles:
+            if prof.name in seen_f and prof.name not in dup_f:
+                dup_f.append(prof.name)
+            seen_f.add(prof.name)
+        if dup_f:
+            raise ValueError(
+                f"duplicate profile name(s): {sorted(dup_f)}. Profile names "
+                f"must be unique — a duplicate silently shadows the later "
+                f"entry (profile_by_name returns the first match). Rename or "
+                f"remove the duplicate(s)."
+            )
+        return self
+
+    @model_validator(mode="after")
+    def _check_profile_providers_exist(self) -> CodeRouterConfig:
+        """mE: every provider named in a profile chain must be declared.
+
+        Previously a typo in ``profiles[].providers`` was tolerated at load
+        and only surfaced at runtime as a ``skip-unknown-provider`` warning;
+        if *every* entry in a chain was typo'd the profile silently had no
+        usable providers and only failed once fully drained. Rejecting at
+        load — same philosophy as ``_check_default_profile_exists`` and
+        ``_check_mode_alias_targets_exist`` — turns a silent-until-drained
+        misconfig into a startup error naming the profile and the bad
+        provider(s).
+        """
+        names = {p.name for p in self.providers}
+        errors: list[str] = []
+        for prof in self.profiles:
+            missing = [name for name in prof.providers if name not in names]
+            if missing:
+                errors.append(f"{prof.name!r} -> {missing}")
+        if errors:
+            raise ValueError(
+                f"profile(s) reference undeclared provider(s): "
+                f"{'; '.join(errors)}. known providers={sorted(names)}. "
+                f"Fix the typo in profiles[].providers or add the missing "
+                f"provider(s)."
+            )
+        return self
+
     def provider_by_name(self, name: str) -> ProviderConfig:
         """Look up a provider config by name. Raises KeyError if not found."""
         for p in self.providers: