coderouter-cli 2.11.0__tar.gz → 2.11.1__tar.gz

{coderouter_cli-2.11.0 → coderouter_cli-2.11.1}/CHANGELOG.md

@@ -9,6 +9,191 @@ are kept verbatim where the Japanese text itself is the subject).
 
 ---
 
+## [v2.11.1] — 2026-08-04 (second-round review: correctness & hardening)
+
+Seven fixes from a full-source review of the 36k-line package, plus two
+deprecation warnings that pre-announce the behaviour changes queued for
+v2.12.0. **No breaking changes**: no config-schema field was removed or
+narrowed, no CLI flag changed meaning, and every default is unchanged.
+The two new warnings do not alter behaviour — they only tell you which
+of your settings will need editing before v2.12.0.
+
+### Fixed
+
+- **Brace scanning in `tool_repair` was quadratic and blocked the event
+  loop for minutes.** `_find_balanced_json_objects` and
+  `_find_candidate_object_spans` restarted a full scan to end-of-text at
+  every `{`, so an assistant reply carrying unclosed braces — the
+  ordinary shape of a deep nested JSON truncated by `max_tokens` — cost
+  O(k·n). Measured on the old code: 3.997 s for 8 KiB of `{`, 22.199 s
+  for a 48 KiB reply, 139.019 s for 48 KiB of bare `{`. Both scanners
+  are called synchronously from `to_anthropic_response`, which
+  `FallbackEngine._generate_anthropic_impl` / `._stream_anthropic_impl`
+  invoke from inside `async` handlers, so the whole server stalled for
+  the duration — every concurrent request, not just the offending one.
+  Replaced with a single right-to-left sweep that builds a depth-0
+  closing-brace table (`table[j]` = the first depth-0 `}` reached when
+  scanning from offset `j` outside any string); the answer for an
+  opening brace at `q` is `table[q+1]`, which is by definition the
+  fresh-restart semantics the old code had. Same inputs now take
+  0.004 s / 0.016 s / 0.024 s. The strict (`"` only) and lenient (`'`
+  too) quoting rules live in separate tables and cannot bleed into each
+  other. Scan output is unchanged — see Tests. Added
+  `_MAX_BARE_SCAN_CHARS` (256 KiB); above it the bare-JSON pass is
+  skipped with a `tool-repair-input-too-large` warning while the fenced
+  / XML / R4c passes still run. The two `to_anthropic_response` call
+  sites moved to `asyncio.to_thread`; the function itself stays
+  synchronous (`tool_repair.py`, `routing/fallback.py`).
+- **`doctor --apply` dropped `output_filters` a user had configured.**
+  The probe emitted only the filters that were *missing*, but
+  `deep_merge_dicts` replaces lists wholesale, so applying
+  `output_filters: [strip_thinking]` to a provider already carrying
+  `[strip_stop_markers, my_filter]` left it with `[strip_thinking]`
+  alone. `strip_tool_call_xml` and `repair_byte_fallback` were dropped
+  100% of the time, since no probe ever recommends them. The patch now
+  carries the union — existing chain first, missing filters appended.
+  Order is load-bearing (`OutputFilterChain.feed` applies left to
+  right), so the union never sorts; `deep_merge_dicts` semantics are
+  untouched (`doctor.py`).
+- **`doctor --check-model` could write `capabilities: tools: false` for
+  a model that supports tools.** The tool-call probe judged on
+  `content[:200]` — a display-oriented truncation — while the probe
+  budget is 256 tokens, or 1024 for thinking models (roughly 3–4 k
+  chars). A model that emits a preamble before its tool JSON, which is
+  exactly what thinking models do, fell through to the "nothing
+  tool-shaped at all" branch and got a `tools: false` patch that
+  `--apply` then wrote. This re-created, by a different route, the
+  false positive the v1.8.3 budget increase was meant to remove.
+  Detection now reads the full body up to `_TOOL_PROBE_SCAN_CHARS`
+  (16 KiB) and the 200-char slice is display-only; the detail line
+  reports how many chars were actually scanned (`doctor.py`).
+- **Stray `stop_reason` values from Anthropic were treated as malformed
+  responses.** `AnthropicResponse.stop_reason` was a closed `Literal`,
+  and `ConfigDict(extra="allow")` does not widen a declared field, so
+  `pause_turn` (server-tool turns), `refusal` and
+  `model_context_window_exceeded` raised `ValidationError`.
+  `AnthropicAdapter` converts that to a retryable `AdapterError`, so a
+  perfectly good — and already billed — reply was discarded and the
+  chain fell through to the next provider, or to
+  `NoProvidersAvailableError` if it was the last. Streaming was
+  unaffected (`AnthropicStreamEvent` keeps its payload as a plain
+  dict), so only non-streaming requests were hit. The field is now
+  `str | None`, deliberately open: Anthropic has added stop reasons
+  three times and a closed `Literal` reproduces this bug on the next
+  one. `_REVERSE_FINISH_REASON_MAP` gained `pause_turn` → `stop`,
+  `refusal` → `content_filter`, `model_context_window_exceeded` →
+  `length`. While here, `drift_detection._EXPECTED_STOP` gained
+  `stop_sequence` — it was counting a documented, ordinary stop reason
+  as an anomaly (`translation/anthropic.py`, `translation/convert.py`,
+  `guards/drift_detection.py`).
+- **`import coderouter.translation` failed on its own.** The package
+  reached `adapters` → `registry` → `anthropic_native`, which imported
+  `translation.convert` back at module scope. `pytest tests/` passed
+  only because alphabetical collection imports `test_adapter_anthropic`
+  first and primes `coderouter.adapters`; running
+  `pytest tests/test_tool_repair.py` on its own was a collection error.
+  The three `convert` symbols moved into the `generate()` / `stream()`
+  bodies that use them (`adapters/anthropic_native.py`).
+
+### Security
+
+- **`doctor --apply` silently rewrote `providers.yaml` while reporting
+  "already up to date", then destroyed the original in `.bak`.** The
+  write was gated on `diff_text` — "does a ruamel re-dump differ from
+  what is on disk" — not on whether a patch changed anything. ruamel
+  re-flows quoted scalars at 80 columns and renders an explicit `null`
+  as an empty scalar, so a fully idempotent re-run still produced a
+  diff and still wrote. The CLI meanwhile took the `is_no_op` early
+  return and printed `All N patch(es) already applied`, showing neither
+  the diff nor a backup line. The *next* `--apply` then copied that
+  already-reformatted text over `providers.yaml.bak`, which is
+  deliberately un-timestamped and single-slot — so the only copy of the
+  operator's original was gone. The shipped `examples/providers.yaml`
+  is affected (five `api_key_env: null` lines), as is
+  `examples/providers.llamacpp-vllm.yaml` (two `binary: null`). The
+  write is now gated on the merge result per target file; a target
+  whose merges were all no-ops reports an empty diff and parks the
+  cosmetic delta in `ApplyResult.reformat_only`, surfaced under
+  `--dry-run` only. The dumper also sets `width = 4096`, as defence in
+  depth. Every exit path of the apply command — including both
+  exception returns — now states how many files were written.
+  **If you ran `doctor --apply` on v2.11.0 or earlier, compare
+  `providers.yaml` against `providers.yaml.bak` once.** The
+  reformatting is semantically equivalent YAML, but the first `--apply`
+  after upgrading will show the un-wrapping alongside your intended
+  change; that is expected and happens once (`doctor_apply.py`,
+  `cli.py`).
+- **A malformed GGUF file could hang or crash the launcher, including
+  from the HTTP route.** `_skip_value` recursed once per array nesting
+  level at 12 bytes per level, so a ~12 KB file raised `RecursionError`
+  — which is not `GGUFParseError`, so it went straight through
+  `try_read_gguf_metadata`'s handler. Separately, array elements were
+  skipped with `fh.seek(size, 1)` per element with no end-of-file
+  check: a 49-byte file declaring `count = 1<<24` spun 16.7 M times,
+  took 7.94 s, and returned a `GGUFInfo` rather than raising. Both are
+  reachable from `POST /api/launcher/start`, and
+  `launcher_speculative.find_draft_companion` reads *every* `.gguf` in
+  the configured model directories, so one bad file poisons the scan.
+  `_skip_value` is now iterative over an explicit work stack —
+  `RecursionError` is structurally unreachable — with
+  `_MAX_ARRAY_DEPTH = 8` retained as an independent bound (real GGUF
+  arrays are depth 1; llama.cpp's writer emits nothing deeper). Every
+  skip validates against the file size before seeking, and fixed-width
+  scalar arrays are skipped in one bulk seek: a 150 k-element `u32`
+  array went from 0.0624 s to 0.000102 s, and the 49-byte case from
+  7.94 s to 0.000043 s with a `GGUFParseError`. `p.open()` is now
+  wrapped for the stat/open TOCTOU, and `try_read_gguf_metadata`
+  catches `OSError` / `RecursionError` / `MemoryError` as well
+  (`gguf_introspect.py`).
+
+### Changed
+
+- **Deprecation warning: `providers.yaml` discovered in the current
+  directory.** When neither `--config` nor `CODEROUTER_CONFIG` resolves
+  and the file actually loaded came from `./providers.yaml`, a
+  `cwd-config-loaded` warning is logged once per process naming the
+  path. In v2.12.0 this search step becomes opt-in behind
+  `CODEROUTER_ALLOW_CWD_CONFIG`, because starting the server in an
+  untrusted directory currently means loading that directory's
+  execution-bearing settings. Behaviour is unchanged in this release
+  (`config/loader.py`).
+- **Deprecation warning: shell syntax in `restart_command`.** A value
+  containing `&&`, `||`, `|`, `;`, `>`, `<`, `$(` or a backtick, or
+  starting with `~/` or `FOO=bar`, now logs
+  `restart-command-shell-syntax` at config load. In v2.12.0 the command
+  will be `shlex.split` and run with `shell=False`, so those forms
+  break — and `pkill x && x` breaks *silently*, with `&&` passed to
+  `pkill` as an argument. Wrap such commands in a script, or use an
+  explicit `/bin/sh -c "..."`. This is a warning only; nothing is
+  rejected and execution is unchanged (`config/schemas.py`).
+
+### Tests
+
+- 6 new files, 184 new cases (`test_tool_repair_differential.py`,
+  `test_tool_repair_scanners.py`, `test_examples_yaml_roundtrip.py`,
+  `test_import_hygiene.py`, `test_stop_reason_forward_compat.py`,
+  `test_config_cwd_warning.py`, plus additions to `test_doctor.py`,
+  `test_doctor_apply.py` and `test_gguf_introspect.py`). Suite: 2307
+  passed, 1 skipped, ruff clean.
+- The scanner rewrite is pinned by a differential test that carries the
+  old quadratic algorithm as a reference implementation and compares
+  both scanners across five random alphabets × 2500 inputs each, plus
+  the full `benchmarks/tool-repair` corpus end to end. A naive global
+  single-pass rewrite — the obvious way to linearise this, and the way
+  that looks correct — diverges on 6870 of 12500 strict cases and 6977
+  lenient, because an apostrophe in ordinary prose (`I'll`, `don't`)
+  opens a single-quoted string that swallows every following brace. The
+  differential test was verified to catch exactly that.
+- Each fix above has a regression test confirmed to fail against the
+  pre-fix tree, including
+  `test_cli_no_op_message_states_nothing_written` (the "up to date"
+  message printed while writing),
+  `test_no_op_apply_leaves_example_byte_identical` (the shipped
+  examples), `test_array_count_past_eof_raises_immediately` (raises,
+  and inside 0.5 s) and `test_lenient_survives_prose_apostrophe`.
+
+---
+
 ## [v2.11.0] — 2026-07-28 (launcher backend variants)
 
 ### Added
@@ -52,7 +237,11 @@ are kept verbatim where the Japanese text itself is the subject).
   exist in the chosen build with a 400 instead of letting
   `--device CUDA0` reach a Vulkan build and fail at startup. Skipped
   when `--list-devices` itself fails (best-effort, per the
-  `hardware.py` invariant). New `launcher_devices.unknown_device_ids`.
+  `hardware.py` invariant). New `launcher_devices.foreign_device_ids`,
+  which compares the backend *prefix* (`backend_of`) rather than the
+  exact id — the mismatch worth catching is the wrong build, not a
+  number gap, and prefix matching stays correct if a future
+  `--list-devices` format change makes `parse_list_devices` miss a line.
 
 ### Changed
 

{coderouter_cli-2.11.0 → coderouter_cli-2.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coderouter-cli
-Version: 2.11.0
+Version: 2.11.1
 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.0 → coderouter_cli-2.11.1}/coderouter/adapters/anthropic_native.py

@@ -53,11 +53,16 @@ from coderouter.translation.anthropic import (
     AnthropicResponse,
     AnthropicStreamEvent,
 )
-from coderouter.translation.convert import (
-    stream_anthropic_to_chat_chunks,
-    to_anthropic_request,
-    to_chat_response,
-)
+
+# NOTE: `coderouter.translation.convert` is intentionally NOT imported here
+# at module scope (see H-7). The import chain is:
+#   translation/__init__.py -> convert.py -> adapters/__init__.py
+#     -> registry.py -> anthropic_native.py -> translation.convert (again)
+# A top-level import here closes that cycle and makes standalone imports of
+# `coderouter.translation.*` fail with a partial-initialization ImportError
+# unless `coderouter.adapters` happened to be imported first. The three
+# symbols used from `convert` are imported lazily inside `generate()` /
+# `stream()` instead, which breaks the cycle without changing behavior.
 
 logger = get_logger(__name__)
 
@@ -210,6 +215,12 @@ class AnthropicAdapter(BaseAdapter):
         ``to_chat_response``. The ``coderouter_provider`` tag is preserved
         on both sides.
         """
+        # Local import to avoid a circular import at module load time (H-7):
+        # convert.py transitively imports coderouter.adapters, which imports
+        # this module. Importing convert.py here (call time, not load time)
+        # keeps `coderouter.translation.*` importable standalone.
+        from coderouter.translation.convert import to_anthropic_request, to_chat_response
+
         anth_req = to_anthropic_request(request)
         anth_resp = await self.generate_anthropic(anth_req, overrides=overrides)
         chat_resp = to_chat_response(anth_resp)
@@ -241,6 +252,13 @@ class AnthropicAdapter(BaseAdapter):
             - Anthropic ``event: error`` → translator raises
               AdapterError(retryable=False), same treatment as above.
         """
+        # Local import to avoid a circular import at module load time (H-7);
+        # see the matching comment in generate() above.
+        from coderouter.translation.convert import (
+            stream_anthropic_to_chat_chunks,
+            to_anthropic_request,
+        )
+
         anth_req = to_anthropic_request(request)
         events = self.stream_anthropic(anth_req, overrides=overrides)
         async for chunk in stream_anthropic_to_chat_chunks(events, provider_name=self.name):

{coderouter_cli-2.11.0 → coderouter_cli-2.11.1}/coderouter/cli.py

@@ -624,6 +624,24 @@ def _resolve_config_path(explicit: str | None) -> Path:
     return candidates[-1]
 
 
+def _write_verdict_line(*, write: bool, files_written: int) -> None:
+    """Print the one-line "did we touch the disk?" verdict.
+
+    Called on **every** exit path of :func:`_run_apply_or_dry_run`.
+    The v1.x regression this guards against: an ``--apply`` run that
+    silently rewrote providers.yaml while the summary said "already
+    applied" and printed neither a diff nor a ``Backup:`` line. Making
+    the statement unconditional means no future early-return can go
+    quiet about a write again.
+    """
+    if not write:
+        print("  0 files written (dry-run).")
+    elif files_written == 0:
+        print("  0 files written — no file contents changed.")
+    else:
+        print(f"  {files_written} file(s) written.")
+
+
 def _run_apply_or_dry_run(
     *,
     report: object,
@@ -655,9 +673,13 @@ def _run_apply_or_dry_run(
         )
     except MissingDependencyError as exc:
         print(f"doctor --apply: {exc}", file=sys.stderr)
+        _write_verdict_line(write=write, files_written=0)
         return 1
     except DoctorApplyError as exc:
+        # Every merge happens before the first byte is written, so an
+        # abort here always leaves the disk untouched.
         print(f"doctor --apply: {exc}", file=sys.stderr)
+        _write_verdict_line(write=write, files_written=0)
         return 1
 
     label = "Apply" if write else "Dry-run"
@@ -680,6 +702,8 @@ def _run_apply_or_dry_run(
                 f"  All {result.no_op_patches} patch(es) already applied "
                 f"— providers.yaml is up to date."
             )
+        _write_verdict_line(write=write, files_written=len(result.written_paths))
+        _print_reformat_notice(result, write=write)
         return 0
 
     print(
@@ -694,16 +718,41 @@ def _run_apply_or_dry_run(
         print()
         print(diff, end="" if diff.endswith("\n") else "\n")
 
+    _write_verdict_line(write=write, files_written=len(result.written_paths))
     if write:
         for orig, bak in result.backups.items():
             print(f"  Backup: {orig} → {bak}")
     else:
+        _print_reformat_notice(result, write=write)
         print()
         print("  (dry-run — no files were modified. Re-run with --apply to write.)")
 
     return 0
 
 
+def _print_reformat_notice(result: object, *, write: bool) -> None:
+    """Dry-run-only heads-up about cosmetic re-serialization deltas.
+
+    ``reformat_only`` holds targets whose re-dump differs from disk
+    without any patch having changed a value — today that is explicit
+    ``key: null`` scalars, which ruamel re-emits as empty scalars.
+    These bytes are never written, so the note is purely so an operator
+    comparing "the diff I expected" with "the file I have" is not
+    surprised. Suppressed under ``--apply``, where nothing about them
+    is actionable.
+    """
+    reformat = getattr(result, "reformat_only", None) or {}
+    if write or not reformat:
+        return
+    print(
+        f"  note: {len(reformat)} file(s) would re-serialize with cosmetic "
+        "differences (e.g. explicit `null` → empty scalar). These are NOT "
+        "written — --apply only rewrites files whose values actually changed."
+    )
+    for path in sorted(reformat):
+        print(f"    - {path}")
+
+
 
 
 def _run_audit(args: argparse.Namespace) -> int:

{coderouter_cli-2.11.0 → coderouter_cli-2.11.1}/coderouter/config/loader.py

@@ -7,6 +7,17 @@ Search order (first hit wins):
     4. ~/.coderouter/providers.yaml
 
 Secrets are resolved by reading the env var named by `api_key_env`.
+
+.. note::
+    **[Unreleased] deprecation notice (planned v2.12.0):** step 3 above
+    (implicit CWD discovery) is slated to become opt-in, gated behind
+    ``CODEROUTER_ALLOW_CWD_CONFIG``. Landing that change without warning
+    first would silently break anyone currently relying on "run from the
+    directory with providers.yaml in it" with no diagnostic. Until that
+    lands, :func:`load_config` emits a one-time ``cwd-config-loaded``
+    warning whenever step 3 is the one that actually resolved — never
+    when an explicit ``--config`` / ``CODEROUTER_CONFIG`` path was used,
+    even if it happens to point at the same file.
 """
 
 from __future__ import annotations
@@ -17,6 +28,14 @@ from pathlib import Path
 import yaml
 
 from coderouter.config.schemas import CodeRouterConfig
+from coderouter.logging import get_logger
+
+logger = get_logger(__name__)
+
+# Guards the one-time [Unreleased]/v2.12.0 CWD-config deprecation warning
+# (see module docstring) so a process that calls load_config() repeatedly
+# (tests, hot-reload, multiple create_app() calls) only logs it once.
+_cwd_config_warning_emitted = False
 
 
 def _candidate_paths(explicit: str | os.PathLike[str] | None) -> list[Path]:
@@ -30,6 +49,51 @@ def _candidate_paths(explicit: str | os.PathLike[str] | None) -> list[Path]:
     return paths
 
 
+def _warn_if_cwd_config(
+    chosen: Path, *, explicit: str | os.PathLike[str] | None
+) -> None:
+    """Emit the one-time [Unreleased]/v2.12.0 CWD-config deprecation warning.
+
+    Only fires when ``chosen`` was resolved via the *implicit* CWD-search
+    step. Compares ``chosen`` against the *literal* explicit / env
+    candidate paths (not merely whether those inputs were set) so that:
+
+      * an explicit ``--config`` (or ``CODEROUTER_CONFIG``) path that
+        happens to coincide with ``./providers.yaml`` stays quiet — an
+        explicit choice, however coincidental, is not the thing being
+        deprecated; but
+      * an explicit path/env var that was set but did NOT resolve (file
+        missing, so the search fell through to CWD) still warns, because
+        the CWD step is what actually served the config in that case.
+    """
+    global _cwd_config_warning_emitted
+    if _cwd_config_warning_emitted:
+        return
+    cwd_path = Path.cwd() / "providers.yaml"
+    if chosen != cwd_path:
+        return
+    if explicit and Path(explicit) == chosen:
+        return
+    if (env_path := os.environ.get("CODEROUTER_CONFIG")) and Path(env_path) == chosen:
+        return
+
+    _cwd_config_warning_emitted = True
+    logger.warning(
+        "cwd-config-loaded",
+        extra={
+            "path": str(chosen),
+            "hint": (
+                f"loaded providers.yaml from the current working "
+                f"directory ({chosen}). Starting in v2.12.0, this "
+                "implicit CWD discovery becomes opt-in (gated behind "
+                "CODEROUTER_ALLOW_CWD_CONFIG) — pass --config or set "
+                "CODEROUTER_CONFIG to pin the file explicitly and avoid "
+                "a startup break when that lands."
+            ),
+        },
+    )
+
+
 def load_config(path: str | os.PathLike[str] | None = None) -> CodeRouterConfig:
     """Load providers.yaml + apply ALLOW_PAID env override."""
     candidates = _candidate_paths(path)
@@ -40,6 +104,7 @@ def load_config(path: str | os.PathLike[str] | None = None) -> CodeRouterConfig:
             f"providers.yaml not found. Searched:\n  {searched}\n"
             f"Hint: copy examples/providers.yaml to ~/.coderouter/providers.yaml"
         )
+    _warn_if_cwd_config(chosen, explicit=path)
 
     with chosen.open("r", encoding="utf-8") as f:
         raw = yaml.safe_load(f) or {}

{coderouter_cli-2.11.0 → coderouter_cli-2.11.1}/coderouter/config/schemas.py

@@ -26,6 +26,10 @@ from pydantic import (
     model_validator,
 )
 
+from coderouter.logging import get_logger
+
+logger = get_logger(__name__)
+
 
 class Capabilities(BaseModel):
     """Capability flags per provider (plan.md §2.5)."""
@@ -350,6 +354,17 @@ class AgentCliConfig(BaseModel):
         return self
 
 
+# [Unreleased]/planned v2.12.0: patterns used by ProviderConfig's
+# ``_warn_restart_command_shell_syntax`` validator to flag
+# ``restart_command`` values that rely on shell syntax not honored by
+# the planned ``shlex.split`` + ``shell=False`` dispatch (see that
+# validator's docstring and the field description below for the full
+# rationale). Compiled once at module scope since every ProviderConfig
+# validation reuses them.
+_RESTART_COMMAND_SHELL_META_RE = re.compile(r"(&&|\|\||\||;|>|<|\$\(|`)")
+_RESTART_COMMAND_ENV_PREFIX_RE = re.compile(r"^\w+=")
+
+
 class ProviderConfig(BaseModel):
     """A single provider entry from providers.yaml.
 
@@ -497,15 +512,82 @@ class ProviderConfig(BaseModel):
     restart_command: str | None = Field(
         default=None,
         description=(
-            "v2.0-J (Self-healing): shell command to restart this "
-            "provider's backend process. Examples: 'ollama serve', "
+            "v2.0-J (Self-healing): command to restart this provider's "
+            "backend process. Examples: 'ollama serve', "
             "'open -a LM\\ Studio'. Only executed when the profile's "
             "backend_health_action is 'exclude' and the provider "
             "transitions to UNHEALTHY. Unset = no automatic restart "
-            "(recovery probe still runs, waiting for manual restart)."
+            "(recovery probe still runs, waiting for manual restart). "
+            "\n\n"
+            "[Unreleased]/planned v2.12.0: currently run as "
+            "``subprocess.run(command, shell=True)`` (coderouter/guards/"
+            "self_healing.py), so shell syntax works today — pipelines "
+            "(``pkill ollama && ollama serve``), ``~`` expansion, and "
+            "leading env-var assignments (``OLLAMA_HOST=0.0.0.0 ollama "
+            "serve``) are all honored. A future minor switches this to "
+            "``shlex.split(command)`` + ``shell=False`` (argv dispatch, "
+            "no shell in between), which does NOT support any of the "
+            "above — ``&&`` becomes a literal argument to the first "
+            "command instead of a separator, ``~/...`` paths are not "
+            "expanded, and ``FOO=bar cmd`` fails to exec. If your "
+            "command needs shell features, wrap it in a small script "
+            "and point restart_command at that script instead, e.g. "
+            "``restart_command: /path/to/restart-ollama.sh``."
         ),
     )
 
+    @model_validator(mode="after")
+    def _warn_restart_command_shell_syntax(self) -> ProviderConfig:
+        """[Unreleased]/planned v2.12.0 breaking-change heads-up (warning only).
+
+        ``coderouter/guards/self_healing.py`` currently runs
+        ``restart_command`` via ``subprocess.run(command, shell=True)``.
+        The planned v2.12.0 change switches that to
+        ``shlex.split(command)`` + ``shell=False`` — a shell-syntax
+        ``restart_command`` that works fine today would then either
+        crash (``FileNotFoundError`` for ``~/...`` paths or an
+        ``ENV=val cmd`` prefix) or, worse, silently misbehave (``&&`` /
+        ``||`` / ``|`` / ``;`` / redirects becoming literal argv tokens
+        instead of shell operators — a provider "restart" that quietly
+        does the wrong thing is worse than one that errors loudly).
+
+        Deliberately never raises: this validator does not enforce
+        anything, it only warns ahead of the wire change so operators
+        can migrate ``restart_command`` to a plain argv (or a wrapper
+        script) before v2.12.0 lands, instead of discovering the break
+        the next time a provider actually goes UNHEALTHY.
+        """
+        cmd = self.restart_command
+        if not cmd:
+            return self
+        stripped = cmd.strip()
+        reasons: list[str] = []
+        if _RESTART_COMMAND_SHELL_META_RE.search(cmd):
+            reasons.append("shell metacharacter (&&, ||, |, ;, >, <, $(...), or `...`)")
+        if stripped.startswith("~/"):
+            reasons.append("leading '~/' path (no shell expansion under shell=False)")
+        if _RESTART_COMMAND_ENV_PREFIX_RE.match(stripped):
+            reasons.append("leading environment-variable assignment (FOO=bar ...)")
+        if reasons:
+            logger.warning(
+                "restart-command-shell-syntax",
+                extra={
+                    "provider": self.name,
+                    "restart_command": cmd,
+                    "reasons": reasons,
+                    "hint": (
+                        "restart_command currently runs via "
+                        "subprocess.run(..., shell=True); a planned "
+                        "v2.12.0 change switches to shlex.split(...) + "
+                        "shell=False, which does not support this "
+                        "command's shell syntax. Rewrite it as plain "
+                        "argv, or wrap it in a script and point "
+                        "restart_command at that script."
+                    ),
+                },
+            )
+        return self
+
     @model_validator(mode="after")
     def _check_output_filters_known(self) -> ProviderConfig:
         """v1.0-A: fail at config-load on a typo'd filter name.