coderouter-cli 2.11.2__tar.gz → 2.12.0__tar.gz

{coderouter_cli-2.11.2 → coderouter_cli-2.12.0}/CHANGELOG.md

@@ -9,6 +9,210 @@ are kept verbatim where the Japanese text itself is the subject).
 
 ---
 
+## [v2.12.0] — 2026-08-04 (the context-budget guard actually fires now)
+
+**This release changes behaviour you can observe.** The token estimator
+counted `tool_result`, `tool_use` and `thinking` blocks as zero
+characters, which meant the L1 context-budget guard stayed silent on
+exactly the sessions it exists to protect — agent conversations, where
+tool output is most of the context. Fixing the estimator makes the guard
+fire, the auto-router's `content_token_count_min` rules match earlier,
+and `POST /v1/messages/count_tokens` return larger numbers.
+
+Nothing was removed and no field changed meaning, so configs load
+unchanged. But if you set `context_budget_action: trim`, or wrote a
+`content_token_count_min` threshold, **read the migration note below
+before upgrading.** `token_estimation_include_tool_content: false`
+restores the v2.11.x estimate exactly.
+
+### Fixed
+
+- **The token estimator ignored tool blocks, so the context-budget guard
+  never fired for agent sessions.** `_extract_text_from_content` only
+  summed `type: "text"` blocks. A `tool_result` carrying 5,000 characters
+  of file content counted as 0, and so did a `tool_use` input. In a
+  Claude Code shaped session — short assistant text, large tool results —
+  that under-counted by 8x at 20 turns, 14x at 50 and **24x at 200**, so
+  a conversation genuinely at 96,311 tokens was reported as 4,011 and the
+  0.80 / 0.90 thresholds were never approached. `context_budget_action:
+  trim` was, in practice, inert for the workload it was written for. The
+  estimator now walks blocks by type: `text`, `tool_result` (recursing
+  into a list-shaped `content`), `tool_use` (name plus its serialised
+  input) and `thinking` are counted. **`image` blocks and
+  `redacted_thinking.data` stay at zero** and this is load-bearing — a
+  naive `json.dumps` over the whole block would have inflated a session
+  holding one 400 KB base64 PNG by 7.1x. Unknown block types are skipped
+  rather than raising, and a self-referential structure terminates
+  (`token_estimation.py`).
+- **Trimming could empty the conversation entirely.** `_normalize_head`
+  drops leading `assistant` messages and `user` messages that carry a
+  `tool_result`, because neither is a valid opening turn. When the
+  preserved tail was `[assistant(tool_use), user(tool_result), …]` — the
+  normal shape of an agent conversation — every message matched and the
+  trimmer returned an empty list. `AnthropicRequest.messages` has no
+  `min_length`, so pydantic accepted it and the upstream API answered
+  400. Measured on the shipped code: 81 messages in, 0 out. This was
+  reachable before this release too, but only for text-heavy sessions,
+  because tool blocks estimated as zero meant trimming rarely engaged.
+  Making the estimator honest would have made it routine. There is now
+  no path through the trimmer that returns an empty list for a non-empty
+  input (`guards/context_budget.py`).
+- **Restoring a head message could undo the entire trim.** When
+  normalisation left no valid opening turn, the trimmer restored the most
+  recent clean `user` message it had just dropped. If that message was
+  the reason the request was over budget — a pasted file, a log dump —
+  restoring it put the request straight back over the window while
+  reporting `status: "trimmed"`. On a 200 KB paste followed by 25 tool
+  turns: 67,066 tokens in, 67,060 out, against a 32,768 window. Across a
+  300-session sweep, **89% of the results that still exceeded the window
+  were caused by this restore**, none by the preserve floor. Restoration
+  now checks the budget: the most recent *affordable* dropped clean user
+  wins, and if none fits, a synthetic
+  `[earlier conversation trimmed to fit the context budget]` head is
+  used instead. Same fixture: 67,066 → 17,062, inside both the window and
+  the trim target. The sweep goes to 0% (`guards/context_budget.py`).
+- **The trim loop was quadratic.** It rebuilt the surviving message list
+  and re-scanned every character for each unit it considered dropping.
+  With the corrected estimator that is 217 ms of blocked event loop for
+  an 801-message conversation, and it is called synchronously from the
+  request path. Per-message character counts are now computed once and
+  decremented as units are dropped: 217 ms → 4 ms. Units that would free
+  nothing are skipped rather than dropped, so the trimmer no longer
+  destroys history without reducing the estimate. The set of dropped
+  messages is unchanged — verified against the old algorithm across 200
+  random conversations (`guards/context_budget.py`).
+- **The readiness probe now targets the `127.0.0.1` literal rather than
+  `localhost`.** Both copies of `_backend_ready` fetched
+  `http://localhost:<port>/health` while the backends they probe listen
+  on IPv4 only (`llama-server --host 127.0.0.1` by default), and the bare
+  TCP fallback in the same function already used the literal — so the
+  HTTP branch was the odd one out. On a host with no IPv6 stack at all,
+  where `localhost` resolves to `::1` and nothing else, this fails every
+  attempt with `Address family not supported` and a backend that is up
+  and serving never registers. Hardening rather than a reported bug: on a
+  host that has `::1`, the connect is refused immediately and the
+  resolver falls through to IPv4, so the old form worked. Applied to both
+  `ingress/launcher_routes.py` and `launcher_gui.py`, which carry
+  independent copies of this function.
+
+### Added
+
+- **`token_estimation_include_tool_content`** (top level, default
+  `true`). Set it to `false` to get the v2.11.x estimate back, byte for
+  byte — verified identical across 300 fuzzed request bodies on all three
+  estimator entry points. It is an escape hatch for operators who tuned
+  thresholds against the old numbers and need time to retune; expect it
+  to be removed in a future major. It is deliberately not per-profile:
+  the auto-router runs *before* a profile is chosen, and `count_tokens`
+  answers a client question that must not depend on which chain would
+  have served the request (`config/schemas.py`).
+- **`coderouter/py.typed`.** The package has advertised
+  `Typing :: Typed` in its classifiers without shipping a PEP 561
+  marker, so type checkers treated it as untyped. Verified present in the
+  built wheel (`pyproject.toml`).
+- **Release-time version and changelog checks.** `release.yml` now fails
+  the build if the pushed tag does not match `pyproject.toml`'s version,
+  or if `CHANGELOG.md` has no section for it — the awk that extracts
+  release notes silently falls back to a placeholder otherwise. Skipped
+  on `workflow_dispatch`, where `github.ref_name` is a branch.
+
+### Changed
+
+- **`examples/providers.yaml` and `examples/providers-multiagent.yaml`
+  now ship `context_budget_action: warn` instead of `trim`.** README
+  tells new users to `curl` the first of those, so shipping `trim`
+  together with a newly-working guard would have started deleting
+  history in conversations for people who never opted into it. Warn
+  first, read the logs, then decide. `docs/concepts/context-budget.md`
+  was updated to match.
+- **`thinking` blocks are now counted.** Extended-thinking content is
+  replayed to the model on the following turn — it has to be, or tool-use
+  signatures break — so it occupies the window exactly like text.
+  `redacted_thinking.data` is still not counted: it is opaque ciphertext,
+  the same category as base64 image data.
+- **Third-party GitHub Actions are pinned to commit SHAs**, with the
+  version in a trailing comment so dependabot still tracks them. The
+  publish job holds `id-token: write` for Trusted Publishing and the
+  release job holds `contents: write`; a moved tag on any action they
+  use is a direct path to the PyPI project.
+- **A macOS CI runner was added and then withdrawn again before this
+  release shipped.** It failed six launcher tests immediately, and the
+  failures turned out to belong to the test harness rather than the
+  product: every test that spawns a real stub process and requires its
+  `/health` to answer 200 within the harness's 5.0s
+  `readiness_timeout_s` failed, and no others. Spawning, argv
+  construction, crash detection, SIGTERM handling, TTL and registry
+  behaviour all passed on macOS. That 5.0s budget is 1/60th of the
+  shipped default of 300.0s, so it does not represent any real
+  deployment. Rather than ship six `xfail`s or a red CI, the runner is
+  deferred to a follow-up that raises the harness budget first. The
+  reasoning and the re-enable steps are recorded in `ci.yml` next to the
+  matrix.
+- **Corrected the note about tkinter on CI**, which v2.11.2 got wrong in
+  both directions. The GUI test modules originally said the uv-managed
+  Python on CI has no tkinter; v2.11.2 "fixed" that to say it does,
+  based on measuring `uv python install 3.12.11` in a Linux container.
+  The actual CI runs settle it: the ubuntu runner skips those four files
+  and the macOS runner ran them. Tk availability is a property of the
+  runner image, so the docstrings no longer assert it in either
+  direction — they just say to keep the `importorskip`.
+- **The CVE audit covers every extra.** `uv export` passed only
+  `--extra dev`, leaving `accuracy` (tokenizers) and `repair`
+  (json-repair) — both installable by users — outside pip-audit's view.
+  Now `--all-extras`.
+- **The sdist no longer allow-lists `docs` wholesale.** `only-include`
+  named the whole directory, so a local `uv build` swept in
+  `docs/inside/` and `docs/articles/` — private notes and article drafts
+  that `.gitignore` exists to keep out. A CI build from a clean checkout
+  was never affected, since those files are untracked, but a maintainer
+  building from a working tree would have shipped them. The list now
+  names the public subdirectories, and `release.yml` fails the build if
+  either directory reappears in the tarball. Every entry has to be
+  git-tracked: `docs/evidence` exists only in a maintainer's working tree
+  and made the allowlist claim to ship something a fresh checkout does
+  not have. `tests/test_packaging.py` now asserts each listed path
+  exists, which is how that was caught.
+
+### Migration
+
+Only two settings change meaning. If you set neither, upgrading is a
+no-op beyond larger `count_tokens` responses.
+
+**`context_budget_action: trim` or `warn`** — the guard was effectively
+inert for tool-heavy sessions and now works. Expect
+`context-budget-warning` in the logs, the
+`X-CodeRouter-Context-Budget` response header, and — under `trim` —
+conversation history actually being dropped, with a
+`[earlier conversation trimmed to fit the context budget]` message
+appearing at the head when nothing else fits. Measured against a 32 K
+window, a tool-driven session now warns around turn 32 and trims around
+turn 36; before, it never did either. Start with `warn` and read the
+logs before enabling `trim`.
+
+**`content_token_count_min`** — auto-router rules using it will match far
+earlier. A tool-driven session that reported 1,083 tokens after 200 turns
+under v2.11.x reports 93,183 now, so a `32000` threshold moves from never
+firing to firing around turn 69. Check where such a rule routes:
+`examples/providers.raspberrypi.yaml` sends matching traffic to a cloud
+free tier rather than the local model. Retune the threshold, or set
+`token_estimation_include_tool_content: false` while you do.
+
+### Tests
+
+- 3 new files, 48 new cases. Suite: 2393 passed, 1 skipped, ruff clean.
+- Each fix has a regression test confirmed to fail against the pre-fix
+  tree, including `test_trim_never_returns_empty_messages` (81 in, 0 out
+  on the old code) and `test_trim_lands_inside_the_window_across_budgets`,
+  which asserts that if a trimmed request is still over the window, the
+  preserve floor alone must account for it — structurally forbidding the
+  restore branch from being the cause.
+- The incremental trim loop is pinned against the old full-recompute
+  implementation across 200 random conversations (identical dropped
+  sets), and the opt-out is pinned against v2.11.2 across 300 fuzzed
+  bodies.
+
+---
+
 ## [v2.11.2] — 2026-08-04 (file-write safety and launcher event hygiene)
 
 Two fixes from the same review round as v2.11.1, split out because they

{coderouter_cli-2.11.2 → coderouter_cli-2.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coderouter-cli
-Version: 2.11.2
+Version: 2.12.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.11.2 → coderouter_cli-2.12.0}/coderouter/config/schemas.py

@@ -27,6 +27,7 @@ from pydantic import (
 )
 
 from coderouter.logging import get_logger
+from coderouter.token_estimation import set_include_tool_content
 
 logger = get_logger(__name__)
 
@@ -2306,6 +2307,36 @@ class CodeRouterConfig(BaseModel):
         ),
     )
 
+    # H-5 escape hatch: token-estimation scope.
+    #
+    # Deliberately top-level rather than per-``FallbackChain``, even
+    # though ``context_budget_action`` lives on the chain. The shared
+    # char/4 estimator has four consumers and three of them run with no
+    # profile in hand: the auto-router runs *before* a profile exists
+    # (it is what picks one), ``POST /v1/messages/count_tokens`` answers
+    # a client question that must not depend on which chain would have
+    # served it, and language-tax measurement is profile-agnostic. A
+    # per-profile switch would let the router and the guard disagree
+    # about the size of the very same request — exactly the class of bug
+    # this key exists to let operators back out of.
+    token_estimation_include_tool_content: bool = Field(
+        default=True,
+        description=(
+            "v2.12 (H-5): count ``tool_result`` / ``tool_use`` / "
+            "``thinking`` content blocks in the shared char/4 token "
+            "estimator. True (default) is the correct behavior — up to "
+            "v2.11.x these blocks estimated to 0 chars, under-counting a "
+            "Claude Code style session by 5x at 20 turns and ~29x at 200. "
+            "Image blocks stay at 0 either way. Set to false as an escape "
+            "hatch to restore v2.11.x-identical estimates (and therefore "
+            "v2.11.x context-budget firing, auto-router "
+            "``content_token_count_min`` matching and "
+            "``/v1/messages/count_tokens`` numbers) if the corrected "
+            "estimate disrupts a tuned deployment. Compatibility shim "
+            "only — scheduled for removal in a future release."
+        ),
+    )
+
     # v2.0-I: Continuous probing — background health checks for idle periods.
     continuous_probe: Literal["off", "active"] = Field(
         default="off",
@@ -2816,6 +2847,25 @@ class CodeRouterConfig(BaseModel):
             )
         return self
 
+    @model_validator(mode="after")
+    def _apply_token_estimation_scope(self) -> CodeRouterConfig:
+        """Publish ``token_estimation_include_tool_content`` process-wide.
+
+        The char/4 estimator is a dependency-free leaf module that every
+        consumer imports directly as a plain function; there is no
+        object graph to thread a flag through, and three of the four
+        consumers have no profile/config handle at their call site. So
+        the loaded config pushes the setting into the module once, here.
+
+        Idempotent and deterministic: the value always reflects the most
+        recently constructed config, which in a server process is the
+        single config that was loaded at startup. Declared last so a
+        config that fails any other validator never takes effect. Tests
+        that flip it should restore the default (True) afterwards.
+        """
+        set_include_tool_content(self.token_estimation_include_tool_content)
+        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:

{coderouter_cli-2.11.2 → coderouter_cli-2.12.0}/coderouter/guards/context_budget.py

@@ -38,6 +38,11 @@ Uses the shared :func:`~coderouter.token_estimation.estimate_tokens_from_anthrop
 (char/4 heuristic, 5-deps invariant). See that module's docstring
 for the CJK caveat and recommended threshold compensation.
 
+Since H-5 the estimator also counts ``tool_result`` / ``tool_use`` /
+``thinking`` blocks, so a Claude-Code-shaped session now reports a
+number 5-29x larger than it did in v2.11.x — i.e. the guard finally
+fires on the sessions it was written for.
+
 Trim algorithm
 ==============
 
@@ -49,6 +54,16 @@ Trim algorithm
      ``tool_use`` assistant message (and vice versa).
   5. After removal, re-estimate; if still over ``trim_target``,
      reduce ``preserve_last_n`` by 1 and retry (minimum floor: 2).
+  6. The result is **never** an empty message list — see
+     :func:`_normalize_head`.
+
+Cost
+====
+
+The incremental loop pre-computes each message's character count once
+and subtracts as units are dropped, so a trim is O(total chars) rather
+than O(messages x total chars). Before that change an 800-message trim
+blocked the event loop for ~0.2s.
 """
 
 from __future__ import annotations
@@ -57,6 +72,9 @@ from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any
 
 from coderouter.token_estimation import (
+    chars_to_tokens,
+    count_message_chars,
+    count_system_chars,
     estimate_tokens_from_anthropic_request,
 )
 
@@ -398,7 +416,37 @@ def _group_removable_units(
     return units
 
 
-def _normalize_head(messages: list[Any]) -> list[Any]:
+def _role_of(msg: Any) -> Any:
+    """Role of a message (Pydantic model or dict)."""
+    if hasattr(msg, "role"):
+        return msg.role
+    if isinstance(msg, dict):
+        return msg.get("role")
+    return None
+
+
+def _is_clean_user(msg: Any) -> bool:
+    """True for a ``user`` message that does not open with a tool_result."""
+    return _role_of(msg) == "user" and not _has_tool_result(msg)
+
+
+#: Content of the synthetic head inserted when no real clean ``user``
+#: message can be re-attached within budget. Short on purpose (~17
+#: tokens): its only job is to give Anthropic the valid opening turn the
+#: wire format demands while telling the model why history is missing.
+TRIM_PLACEHOLDER_HEAD_TEXT = "[earlier conversation trimmed to fit the context budget]"
+
+
+def _synthetic_head() -> dict[str, Any]:
+    """A minimal, always-affordable clean ``user`` message."""
+    return {"role": "user", "content": TRIM_PLACEHOLDER_HEAD_TEXT}
+
+
+def _normalize_head(
+    messages: list[Any],
+    *,
+    fallback_head: Any | None = None,
+) -> list[Any]:
     """Drop leading messages until the first is a clean ``user`` message.
 
     Anthropic requires the first message to be a ``user`` message, and a
@@ -407,18 +455,77 @@ def _normalize_head(messages: list[Any]) -> list[Any]:
     any assistant message and any user message that contains a
     tool_result, stopping at the first ``user`` message with no
     tool_result block.
+
+    **Never returns an empty list for a non-empty input.** In a
+    tool-heavy agent session the preserved tail can legitimately look
+    like ``[assistant(tool_use), user(tool_result), assistant(tool_use),
+    user(tool_result)]`` — every single message matches the drop
+    condition, and the naive loop returned ``[]``. ``AnthropicRequest``
+    declares no ``min_length`` on ``messages``, so pydantic happily
+    forwarded that and the upstream API answered 400, destroying the
+    session the guard exists to protect. (Latent before H-5 only
+    because ``tool_result`` blocks estimated to 0 chars, so trim never
+    fired on exactly those conversations.)
+
+    When no surviving message can serve as the head, ``fallback_head``
+    is prepended. The caller picks it under the token budget — see
+    :func:`_pick_fallback_head`; this function deliberately does no
+    budget arithmetic of its own.
     """
-    start = 0
-    n = len(messages)
-    while start < n:
-        msg = messages[start]
-        role = msg.role if hasattr(msg, "role") else (
-            msg.get("role") if isinstance(msg, dict) else None
-        )
-        if role == "user" and not _has_tool_result(msg):
-            break
-        start += 1
-    return messages[start:]
+    if not messages:
+        return list(messages)
+
+    for start, msg in enumerate(messages):
+        if _is_clean_user(msg):
+            return messages[start:]
+
+    # Every surviving message is an assistant turn or a tool_result-
+    # carrying user turn: normalizing by dropping would empty the list.
+    if fallback_head is not None:
+        return [fallback_head, *messages]
+    return list(messages)
+
+
+def _pick_fallback_head(
+    messages: list[Any],
+    msg_chars: list[int],
+    dropped: set[int],
+    *,
+    before: int,
+    kept_chars: int,
+    target_tokens: int,
+) -> Any:
+    """Choose a head message that keeps the result inside the budget.
+
+    Called only when nothing in the surviving window is a clean ``user``
+    message, so *something* has to be put in front or the request is a
+    guaranteed 400.
+
+    Selection order:
+
+    1. The **most recent** dropped clean ``user`` message that still
+       fits under ``target_tokens`` — recency matters because it is
+       usually the operator's latest standing instruction.
+    2. Failing that, a synthetic placeholder (:func:`_synthetic_head`).
+
+    The budget check is the whole point. Re-attaching the *newest*
+    candidate unconditionally is a trap: the most recent clean user
+    message in an agent session is very often a huge pasted file, and
+    restoring it undoes the entire trim. Measured on the canonical
+    "200 KB paste then 25 tool calls" shape, that path turned a
+    67,066-token request into a 67,061-token request against a 24,576
+    target — reported as ``status="trimmed"`` and then rejected
+    upstream. A budget-blind restore does not avoid the 400, it
+    guarantees it.
+    """
+    for idx in sorted(dropped, reverse=True):
+        if idx >= before:
+            continue
+        if not _is_clean_user(messages[idx]):
+            continue
+        if chars_to_tokens(kept_chars + msg_chars[idx]) <= target_tokens:
+            return messages[idx]
+    return _synthetic_head()
 
 
 def _do_trim(
@@ -437,12 +544,23 @@ def _do_trim(
     hard floor that is never removed. After trimming, the head is
     normalized so the first surviving message is a ``user`` message
     without a leading ``tool_result`` (avoids upstream 400s). Bug H5.
+
+    The loop is incremental in *characters*: every message's character
+    contribution is computed exactly once up front and subtracted as
+    units are dropped, instead of rebuilding the kept list and
+    re-walking the whole conversation on every iteration (the old
+    O(messages x chars) shape cost ~0.2s of event-loop time for an
+    800-message session). Because the char/4 heuristic floor-divides
+    the grand total exactly once, the running sum stays bit-identical
+    to a full recompute.
     """
     if not messages:
         return messages
 
-    already = estimate_tokens_from_anthropic_request(system=system, messages=messages)
-    if already <= target_tokens:
+    system_chars = count_system_chars(system)
+    msg_chars = [count_message_chars(m) for m in messages]
+    total_chars = system_chars + sum(msg_chars)
+    if chars_to_tokens(total_chars) <= target_tokens:
         # Nothing to do — return the input unchanged.
         return messages
 
@@ -453,14 +571,41 @@ def _do_trim(
     # Indices we have decided to drop; peel atomic units from the front.
     dropped: set[int] = set()
     for unit in units:
-        kept = [messages[i] for i in range(len(messages)) if i not in dropped]
-        estimated = estimate_tokens_from_anthropic_request(system=system, messages=kept)
-        if estimated <= target_tokens:
+        if chars_to_tokens(total_chars) <= target_tokens:
             break
+        unit_chars = sum(msg_chars[i] for i in unit)
+        if unit_chars <= 0:
+            # Dropping this unit would not move the estimate at all
+            # (e.g. an image-only turn, which counts as 0 chars by
+            # design). Destroying history for no budget gain is pure
+            # loss — skip it and try the next unit.
+            continue
         dropped.update(unit)
-
-    trimmed = [messages[i] for i in range(len(messages)) if i not in dropped]
-    return _normalize_head(trimmed)
+        total_chars -= unit_chars
+
+    kept_indices = [i for i in range(len(messages)) if i not in dropped]
+    trimmed = [messages[i] for i in kept_indices]
+    if not trimmed:
+        # Structural fail-safe: never hand back an empty history.
+        return list(messages[-max(preserve_last_n, 1) :])
+
+    if any(_is_clean_user(m) for m in trimmed):
+        # A real head survives — no fallback needed, and computing one
+        # would only cost time.
+        return _normalize_head(trimmed)
+
+    # Nothing in the surviving window can open the request. Pick a head
+    # that fits the remaining budget (``total_chars`` already reflects
+    # every drop above), falling back to a synthetic marker.
+    fallback_head = _pick_fallback_head(
+        messages,
+        msg_chars,
+        dropped,
+        before=kept_indices[0],
+        kept_chars=total_chars,
+        target_tokens=target_tokens,
+    )
+    return _normalize_head(trimmed, fallback_head=fallback_head)
 
 
 __all__ = [

{coderouter_cli-2.11.2 → coderouter_cli-2.12.0}/coderouter/ingress/launcher_routes.py

@@ -714,11 +714,21 @@ async def _backend_ready(backend: str, port: int, *, probe_timeout_s: float) ->
     Falling through to the bare TCP connect here would silently re-introduce
     the bug readiness gating was added to fix (provider registered before the
     model finished loading).
+
+    The probe targets ``127.0.0.1`` literally, never ``localhost``. On a host
+    where ``localhost`` resolves to ``::1`` first — the default on GitHub's
+    macOS runners, and common on Macs generally — an httpx request to
+    ``http://localhost:<port>`` fails with ``Address family not supported``
+    against a backend listening on IPv4 only, which is what ``llama-server``
+    does by default (``--host 127.0.0.1``). Readiness then never succeeds and
+    the spawn times out with ``status='loading'`` even though the backend is
+    up and serving. The bare TCP fallback below already used ``127.0.0.1``;
+    this branch was the odd one out.
     """
     if base_backend(backend) in ("llama.cpp", "vllm"):
         try:
             async with httpx.AsyncClient(timeout=probe_timeout_s) as client:
-                resp = await client.get(f"http://localhost:{port}/health")
+                resp = await client.get(f"http://127.0.0.1:{port}/health")
             return resp.status_code == 200
         except Exception:
             return False