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

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

@@ -9,6 +9,298 @@ 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
+
+- **Backend variants — pick which llama.cpp build to launch.**
+  `launcher.backends` now accepts keys of the form `<base>-<variant>`
+  (`llama.cpp-cuda`, `llama.cpp-vulkan`, `llama.cpp-rocm`), each naming
+  an additional build of the same backend with its own `binary` path.
+  Declared variants appear as extra entries in the Launcher's backend
+  select (GUI and Web) marked `⚙`, and each one gets its own
+  `--list-devices` probe, its own `option_profiles`, and can be pinned
+  per model in `launcher.swap`. Motivation: on a machine with mixed
+  GPUs the visible devices differ per build — the CUDA build enumerates
+  `CUDA0`/`CUDA1` (RTX 5090 + 3090) while the Vulkan build also
+  enumerates `Vulkan2` (Radeon 8060S) and the ROCm build only the
+  Radeon — so the best build varies by model. Previously `binary` held
+  a single path and switching meant editing `providers.yaml` and
+  restarting. Docs: `docs/backends/launcher.md` "特化ビルドの切り替え",
+  design: `docs/designs/launcher-multi-build.md`.
+- **`option_profiles` inheritance for variants.** A variant key
+  inherits the base backend's presets and appends its own; a preset
+  whose `name` collides replaces the inherited one *in place* (order
+  stays stable, no duplicate at the tail). Shared presets no longer
+  need duplicating under every variant key. Shared implementation:
+  `launcher_devices.resolve_option_profiles` (used by the Web routes,
+  the Tk GUI and `launcher_swap`).
+- **Cross-build bench sweep.** With two or more llama.cpp builds
+  declared, the sweep panel shows a "⚙ ビルド横断" button that probes
+  every build and generates configurations labelled
+  `cuda / CUDA0 単体`, `vulkan / Vulkan2 単体`, … Running the sweep
+  launches the same model on each build in turn, so one sweep answers
+  "which build is fastest for this model". `SweepStep.backend` /
+  `SweepConfigItem.backend` carry the per-step build; `None` keeps the
+  previous plan-wide behaviour. New
+  `launcher_devices.build_cross_variant_sweep_configs`. Configurations
+  never mix devices across builds — one process runs one executable.
+- **Device-id namespace guard.** Device ids are build-specific
+  (`CUDA0` and `Vulkan0` are not the same GPU). Switching backend in
+  either launcher now clears the device selection, and
+  `POST /api/launcher/start` / `sweep/start` reject ids that do not
+  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.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
+
+- **BREAKING: `launcher.backends` keys are now validated.** A key must
+  be `llama.cpp` / `vllm` / `mlx` or one of those with a
+  `-<variant>` suffix (variant matching `[a-z0-9][a-z0-9._-]*`).
+  Previously any key was accepted and silently ignored, because the
+  backend list was a hard-coded set of three; a typo such as
+  `llamacpp:` therefore had no effect and no warning. It is now a
+  config-load error. Check key spelling if startup fails after
+  upgrading.
+- **A backend variant must set `binary`.** Allowing it to be omitted
+  would fall back to the base default on PATH, meaning an operator who
+  selected `llama.cpp-cuda` could silently get the plain build — the
+  hardest failure of this feature to notice. Rejected at config load.
+  Base keys keep `binary` optional (PATH resolution), unchanged.
+- **The Launcher's backend list is now config-derived.** Both launchers
+  build the select from the three base backends plus whatever variants
+  `launcher.backends` declares, instead of a hard-coded list. Declaring
+  no variants yields exactly the previous three entries, so specialized
+  builds stay invisible to operators who have not opted in.
+- `SwapModelSpec.backend` relaxed from
+  `Literal["llama.cpp","vllm","mlx"]` to a validated `str` so it can
+  name a variant; the three previous values still validate unchanged.
+  When a variant is named, config load verifies it is declared in
+  `launcher.backends`.
+- `GET /api/launcher/backends` entries gained `base` and `variant`
+  keys. All pre-existing keys (`resolved` / `configured` / `default` /
+  `is_custom` / `found`) are unchanged.
+
+### Fixed
+
+- **Backend-name branches are normalized through a single helper.**
+  Backend name drove behaviour in ten places, several of which would
+  have failed *open* for a variant name rather than raising. Two
+  mattered: `_MODEL_FLAGS.get(backend, frozenset())` would have
+  returned an empty set and **disabled the H8 model-override guard**
+  (letting `options` / `extra_args` re-specify `-m` and load an
+  arbitrary model), and `_backend_ready`'s
+  `backend in ("llama.cpp","vllm")` would have degraded readiness to a
+  bare TCP connect — re-introducing the bug readiness gating was added
+  to fix (provider registered before the model finished loading). All
+  branches now go through `launcher_devices.base_backend()`, in
+  `launcher_routes.py`, `launcher_speculative.py`, `launcher_gui.py`
+  and the inline SPA JS. `_assert_no_model_override` additionally
+  became fail-closed: an unrecognized base uses the union of every
+  banned flag set rather than an empty one.
+
+### Tests
+
+- 4 new files, 150 new cases (`test_launcher_backend_variants.py`,
+  `test_launcher_variant_config.py`, `test_launcher_variant_routes.py`,
+  `test_launcher_variant_sweep.py`, `test_launcher_variant_gui.py`).
+  The fail-open branches above each have a 1:1 regression test, plus
+  byte-identical-argv and unchanged-API-payload tests for configs
+  without variants. Suite: 2098 passed, ruff clean.
+
+---
+
 ## [v2.10.0] — 2026-07-20 (VSCode workspace scaffolder)
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coderouter-cli
-Version: 2.10.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
@@ -224,6 +224,7 @@ providers:
 | **ログビューア** | 各プロセスの stdout/stderr をブラウザ内でリアルタイム確認 |
 | **provider 自動同期** (v2.7.4) | 起動したバックエンドを provider として自動登録(`launcher-llamacpp-8085` 等)。providers.yaml 無編集で `X-CodeRouter-Profile: launcher` からルーティング可能。メモリ内のみ・serve と同寿命 |
 | **モデル名パススルー** (v2.7.4) | `model: ""` の provider は `/v1/models` が上流のロード中モデル ID(gguf 名)をそのまま返す。gguf を差し替えても config 編集不要 — 外部ベンチからモデルを識別できる |
+| **特化ビルドの切り替え** (v2.11.0) | `llama.cpp-cuda` / `-vulkan` / `-rocm` を `backends` に登録すると、起動ごとにどのビルドの `llama-server` を使うか選べる。ビルド別にデバイス検出・option_profiles・ベンチスイープが独立(書かなければ従来どおり) |
 
 ```yaml
 # providers.yaml に追記するだけで有効になる

{coderouter_cli-2.10.0 → coderouter_cli-2.11.1}/README.en.md

@@ -69,6 +69,8 @@ ANTHROPIC_BASE_URL=http://localhost:8088 ANTHROPIC_AUTH_TOKEN=dummy claude
 
 That's it. Claude Code works as usual, but your local Ollama is answering behind the scenes.
 
+**From VSCode's integrated terminal**, avoid the env-var footgun with `coderouter vscode-init`. Run it once at your project root and it merges `terminal.integrated.env.*` into `.vscode/settings.json`, so `claude` in VSCode's terminal just works from then on. Cheat-sheet snippets for Cline / Roo Code / Continue.dev are printed at the end of the same run → [VSCode integration guide](./docs/guides/vscode.md) (JP only for now).
+
 ---
 
 ## Do you need it?
@@ -217,6 +219,7 @@ More detail → [Usage guide](./docs/guides/usage-guide.en.md) · [Architecture]
 | Run for free | [Free-tier guide](./docs/guides/free-tier-guide.en.md) |
 | Launch llama.cpp / vllm via GUI | [Launcher guide](./docs/backends/launcher.md) |
 | Measure & avoid the language tax | [Language Tax guide](./docs/guides/language-tax.en.md) |
+| Use from VSCode / Cline / Continue | [VSCode integration guide](./docs/guides/vscode.md) (JP) |
 | Reach it safely from another machine | [Remote access guide](./docs/guides/remote-access.en.md) |
 | Stuck? | [Troubleshooting](./docs/guides/troubleshooting.en.md) |
 | Understand the design | [Architecture](./docs/concepts/architecture.md) |

{coderouter_cli-2.10.0 → coderouter_cli-2.11.1}/README.md

@@ -179,6 +179,7 @@ providers:
 | **ログビューア** | 各プロセスの stdout/stderr をブラウザ内でリアルタイム確認 |
 | **provider 自動同期** (v2.7.4) | 起動したバックエンドを provider として自動登録(`launcher-llamacpp-8085` 等)。providers.yaml 無編集で `X-CodeRouter-Profile: launcher` からルーティング可能。メモリ内のみ・serve と同寿命 |
 | **モデル名パススルー** (v2.7.4) | `model: ""` の provider は `/v1/models` が上流のロード中モデル ID(gguf 名)をそのまま返す。gguf を差し替えても config 編集不要 — 外部ベンチからモデルを識別できる |
+| **特化ビルドの切り替え** (v2.11.0) | `llama.cpp-cuda` / `-vulkan` / `-rocm` を `backends` に登録すると、起動ごとにどのビルドの `llama-server` を使うか選べる。ビルド別にデバイス検出・option_profiles・ベンチスイープが独立(書かなければ従来どおり) |
 
 ```yaml
 # providers.yaml に追記するだけで有効になる

{coderouter_cli-2.10.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.10.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.10.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 {}