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

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

@@ -9,6 +9,301 @@ are kept verbatim where the Japanese text itself is the subject).
 
 ---
 
+## [v2.13.0] — 2026-08-07 (remaining-high security hardening)
+
+### Changed (BREAKING)
+
+- **Implicit `./providers.yaml` discovery is now opt-in, gated behind
+  `CODEROUTER_ALLOW_CWD_CONFIG`.** Previously, starting CodeRouter (or the
+  GUI launcher) from a directory containing a `providers.yaml` loaded that
+  file automatically. That was a code-execution vector: a hostile config
+  dropped into a repo could steer `restart_command`,
+  `launcher.backends[*].binary`, and `launcher.bench.command_template` —
+  all of which name executables — simply because of the working directory.
+  The current-working-directory step now runs only when
+  `CODEROUTER_ALLOW_CWD_CONFIG` is truthy (`1`/`true`/`yes`/`on`). When the
+  opt-in is off but a `./providers.yaml` exists and was not explicitly
+  named, a one-time `cwd-config-skipped` warning explains why it was
+  ignored and how to enable it (`--config`, `CODEROUTER_CONFIG`, or the
+  opt-in). To keep the old behaviour, set `CODEROUTER_ALLOW_CWD_CONFIG=1`
+  in directories you trust. (The v2.12.0 heads-up mis-stated the landing
+  release as "v2.12.0"; it actually lands here in v2.13.0.)
+- **`restart_command` is now run as `subprocess.run(shlex.split(command),
+  shell=False)` — argv dispatch, no shell.** Self-healing previously ran
+  it through `shell=True`, so a `providers.yaml` from an untrusted source
+  meant arbitrary shell execution (directly, and unconditionally at
+  startup when excluded providers were restored from `state_dir`).
+  Pipelines, redirects, `~` expansion, and `FOO=bar cmd` env prefixes are
+  no longer supported. A value containing shell metacharacters (`&&`,
+  `||`, `|`, `;`, `>`, `<`, `$(...)`, `` ` ``) is now **refused (not run)**
+  rather than half-executed — under `shell=False`, `touch a; b` would
+  otherwise create a file literally named `a;` and report a "successful"
+  restart. Wrap shell-dependent commands in a script, or write them as
+  `/bin/sh -c '...'` explicitly.
+- **`doctor --apply` now writes back to exactly the file the loader read.**
+  The apply path's config resolution was a hand-maintained copy of the
+  loader's search order; it now delegates to the loader's single
+  `resolve_config_path`, so the v2.13.0 CWD change can never make `--apply`
+  rewrite a file that `load_config` did not actually load.
+- **The GUI launcher (`launcher_gui.py`) applies the same
+  `CODEROUTER_ALLOW_CWD_CONFIG` gate** to its own `providers.yaml`
+  discovery.
+- **The launcher sweep API no longer accepts a `bench_command` (or
+  `results_dir`) from the request body.** `POST /api/launcher/sweep/start`
+  previously took an arbitrary command string, `shlex.split` it, and ran
+  it — so anyone who could reach the (loopback, token-optional) launcher
+  port could run any program under the CodeRouter process. The request now
+  carries only a `bench_preset` key that must name an entry under
+  `launcher.bench.presets` in `providers.yaml`; the executable template
+  lives solely in the operator-owned config, matching the trust boundary
+  already used for `launcher.backends[*].binary`. `bench_command` /
+  `results_dir` in a request are rejected with `400`. To keep a custom
+  sweep command, declare it under `launcher.bench.presets`; a single
+  `launcher.bench.command_template` still works unchanged as the implicit
+  `default` preset. Placeholder substitution in bench templates now splits
+  the template into argv *before* substituting, so a config label can no
+  longer inject extra arguments.
+
+### Fixed (security)
+
+- **The launcher HTML no longer embeds `CODEROUTER_LAUNCHER_TOKEN`.**
+  `GET /launcher` used to substitute the shared secret straight into the
+  page, so `curl /launcher | grep` recovered it and defeated
+  `_require_launcher_token`. The page now receives only a boolean telling
+  the UI whether auth is enabled; the operator enters the token once and it
+  is held in `sessionStorage` (per-tab). Token-free deployments are
+  unaffected.
+- **`POST /api/launcher/start` and `/sweep/start` now validate
+  `model_path` / `draft_model_path` against `launcher.model_dirs`** (the
+  same check previously applied only to `/suggest`). When `model_dirs` is
+  unset the endpoints stay open as before, with a one-time warning;
+  configure `model_dirs` when the launcher is reachable beyond loopback.
+- **Stored XSS in the launcher process table is fixed.** Process-row
+  buttons no longer build `onclick` attributes from the process name
+  (which an HTML parser decoded back into executable JS); they use
+  `data-*` attributes with a single delegated listener, so a name like
+  `x');alert(1);//` renders as inert text.
+- **The request body-size limit is now enforced for
+  `Transfer-Encoding: chunked` requests.** The middleware previously only
+  read `Content-Length`, so a chunked body bypassed the cap entirely (and
+  a malformed length header fell through as unlimited). It now also counts
+  bytes as they are received and aborts with `413` the moment the running
+  total exceeds the cap, without buffering the body.
+- **The GUI bench-sweep window no longer orphans `llama-server`
+  processes.** Closing the sweep window (the `×` button) did not signal the
+  worker, and sweep child processes were never registered for the app's
+  bulk shutdown, so backends kept running and leaked VRAM and ports. The
+  window now stops the worker and its children on close (non-blocking, via
+  an `after()` poll with a grace period then `SIGKILL`), sweep children are
+  drained when the app closes, and the app confirms before quitting while a
+  sweep is running.
+
+---
+
+## [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.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coderouter-cli
-Version: 2.11.2
+Version: 2.13.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.13.0}/coderouter/cli.py

@@ -600,28 +600,27 @@ def _run_check_model(args: argparse.Namespace) -> int:
 
 
 def _resolve_config_path(explicit: str | None) -> Path:
-    """Mirror loader._candidate_paths and return the file actually used.
-
-    Used by ``--apply`` to write back to the same path the loader
-    picked up when it parsed providers.yaml. Falls through the same
-    search order so a ``CODEROUTER_CONFIG`` env or default-path lookup
-    matches the live config.
+    """Return the file the loader actually read, for ``--apply`` write-back.
+
+    Delegates the search order to
+    :func:`coderouter.config.loader.resolve_config_path` rather than
+    re-implementing it. Re-implementing it here is exactly how the
+    v2.13.0 CWD opt-in change would introduce a silent bug: if the loader
+    gates ``./providers.yaml`` behind ``CODEROUTER_ALLOW_CWD_CONFIG`` but
+    this copy still searched CWD unconditionally, ``doctor --apply`` would
+    write patches back into a file that ``load_config`` never read. Keeping
+    one source of truth makes that impossible.
+
+    When nothing exists, falls back to ``~/.coderouter/providers.yaml``
+    (the loader's last candidate) — the apply step surfaces a clearer
+    error against that path than this resolver would.
     """
-    import os
-
-    candidates: list[Path] = []
-    if explicit:
-        candidates.append(Path(explicit))
-    if env_path := os.environ.get("CODEROUTER_CONFIG"):
-        candidates.append(Path(env_path))
-    candidates.append(Path.cwd() / "providers.yaml")
-    candidates.append(Path.home() / ".coderouter" / "providers.yaml")
-    for p in candidates:
-        if p.is_file():
-            return p
-    # Fall back to the last candidate even if absent — the apply step
-    # will surface a clearer error than this resolver would.
-    return candidates[-1]
+    from coderouter.config.loader import resolve_config_path
+
+    resolved = resolve_config_path(explicit)
+    if resolved is not None:
+        return resolved
+    return Path.home() / ".coderouter" / "providers.yaml"
 
 
 def _write_verdict_line(*, write: bool, files_written: int) -> None:

coderouter_cli-2.13.0/coderouter/config/loader.py

@@ -0,0 +1,264 @@
+"""Load and validate CodeRouter configuration.
+
+Search order (first hit wins):
+    1. Path passed explicitly (CLI --config flag)
+    2. $CODEROUTER_CONFIG env var
+    3. ./providers.yaml (current working dir) — opt-in since v2.13.0,
+       gated behind ``CODEROUTER_ALLOW_CWD_CONFIG`` (truthy: 1/true/yes/on)
+    4. ~/.coderouter/providers.yaml
+
+Secrets are resolved by reading the env var named by `api_key_env`.
+
+.. note::
+    **v2.13.0 (security):** step 3 above (implicit CWD discovery) is now
+    opt-in, gated behind ``CODEROUTER_ALLOW_CWD_CONFIG``. It was a code
+    execution vector: a hostile ``providers.yaml`` dropped into a repo
+    could steer ``restart_command`` / ``launcher.backends[*].binary`` /
+    ``launcher.bench.command_template`` — all of which name executables —
+    simply because CodeRouter happened to be started from that directory.
+    When the opt-in is enabled and step 3 resolves the config, a one-time
+    ``cwd-config-loaded`` warning fires (never when an explicit
+    ``--config`` / ``CODEROUTER_CONFIG`` path was used, even if it happens
+    to point at the same file). When the opt-in is NOT set but a
+    ``./providers.yaml`` exists and was not explicitly named, a one-time
+    ``cwd-config-skipped`` warning fires so the operator understands why
+    that file was ignored.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import yaml
+
+from coderouter.config.schemas import CodeRouterConfig
+from coderouter.logging import get_logger
+
+logger = get_logger(__name__)
+
+# Name of the env var that opts CWD ``providers.yaml`` discovery back in
+# (see module docstring). v2.13.0 gates step 3 of the search behind it.
+CWD_CONFIG_ENV = "CODEROUTER_ALLOW_CWD_CONFIG"
+# Truthy vocabulary shared by every CWD-opt-in / ALLOW_PAID style toggle.
+_TRUTHY = {"1", "true", "yes", "on"}
+
+# Guards the one-time ``cwd-config-loaded`` warning (opt-in enabled and the
+# CWD step actually resolved) so a process that calls load_config()
+# repeatedly (tests, hot-reload, multiple create_app() calls) only logs it
+# once.
+_cwd_config_warning_emitted = False
+# Guards the one-time ``cwd-config-skipped`` warning (opt-in NOT set but a
+# ./providers.yaml exists and was ignored) — same once-per-process rationale.
+_cwd_config_skip_warning_emitted = False
+
+
+def cwd_config_allowed() -> bool:
+    """True iff the CWD ``providers.yaml`` opt-in is enabled (v2.13.0)."""
+    return os.environ.get(CWD_CONFIG_ENV, "").strip().lower() in _TRUTHY
+
+
+def _candidate_paths(explicit: str | os.PathLike[str] | None) -> list[Path]:
+    paths: list[Path] = []
+    if explicit:
+        paths.append(Path(explicit))
+    if env_path := os.environ.get("CODEROUTER_CONFIG"):
+        paths.append(Path(env_path))
+    # v2.13.0: implicit CWD discovery is opt-in — a hostile providers.yaml
+    # dropped into a repo could otherwise steer restart_command / launcher
+    # binaries simply because CodeRouter was started from that directory.
+    if cwd_config_allowed():
+        paths.append(Path.cwd() / "providers.yaml")
+    paths.append(Path.home() / ".coderouter" / "providers.yaml")
+    return paths
+
+
+def resolve_config_path(
+    explicit: str | os.PathLike[str] | None = None,
+) -> Path | None:
+    """Return the config file the loader would pick, or None if none exists.
+
+    Single source of truth for the search order so callers (e.g.
+    ``coderouter.cli._resolve_config_path`` driving ``doctor --apply``)
+    never re-implement it. Re-implementing it risks writing back to a
+    different file than the one :func:`load_config` actually read — the
+    exact regression the v2.13.0 CWD opt-in would otherwise introduce.
+    """
+    return next((p for p in _candidate_paths(explicit) if p.is_file()), None)
+
+
+def _explicitly_named(
+    path: Path, explicit: str | os.PathLike[str] | None
+) -> bool:
+    """True iff ``path`` matches the literal --config or CODEROUTER_CONFIG value.
+
+    Used to keep the CWD warnings quiet when ``./providers.yaml`` was
+    chosen on purpose (an explicit choice, however coincidental, is not
+    the implicit-discovery behaviour being gated).
+    """
+    if explicit and Path(explicit) == path:
+        return True
+    env_path = os.environ.get("CODEROUTER_CONFIG")
+    return env_path is not None and Path(env_path) == path
+
+
+def _warn_if_cwd_config(
+    chosen: Path, *, explicit: str | os.PathLike[str] | None
+) -> None:
+    """Emit the one-time ``cwd-config-loaded`` warning (opt-in is enabled).
+
+    Only fires when ``chosen`` was resolved via the *implicit* CWD-search
+    step — which, since v2.13.0, only runs when
+    ``CODEROUTER_ALLOW_CWD_CONFIG`` is set. 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, while an explicit path/env var that
+    was set but did NOT resolve (file missing, search fell through to CWD)
+    still warns — the CWD step is what actually served the config there.
+    """
+    global _cwd_config_warning_emitted
+    if _cwd_config_warning_emitted:
+        return
+    cwd_path = Path.cwd() / "providers.yaml"
+    if chosen != cwd_path:
+        return
+    if _explicitly_named(chosen, explicit):
+        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}) because CODEROUTER_ALLOW_CWD_CONFIG "
+                "opt-in is enabled. This file's restart_command / "
+                "launcher.backends[*].binary / "
+                "launcher.bench.command_template decide which executables "
+                "run — only enable the opt-in in directories you trust."
+            ),
+        },
+    )
+
+
+def _warn_if_cwd_config_skipped(
+    explicit: str | os.PathLike[str] | None,
+) -> Path | None:
+    """Warn once when a ./providers.yaml exists but was skipped (no opt-in).
+
+    Returns the skipped CWD path (so :func:`load_config` can name it in a
+    later ``FileNotFoundError``), or None when there is nothing to skip:
+    the opt-in is enabled, no ``./providers.yaml`` exists, or the file was
+    explicitly named (``--config`` / ``CODEROUTER_CONFIG``) — in which case
+    it is not being skipped at all.
+    """
+    global _cwd_config_skip_warning_emitted
+    if cwd_config_allowed():
+        return None
+    cwd_path = Path.cwd() / "providers.yaml"
+    if not cwd_path.is_file():
+        return None
+    if _explicitly_named(cwd_path, explicit):
+        return None
+
+    if not _cwd_config_skip_warning_emitted:
+        _cwd_config_skip_warning_emitted = True
+        logger.warning(
+            "cwd-config-skipped",
+            extra={
+                "path": str(cwd_path),
+                "hint": (
+                    f"found providers.yaml in the current working "
+                    f"directory ({cwd_path}) but did NOT load it: implicit "
+                    "CWD discovery is opt-in since v2.13.0 (a hostile "
+                    "providers.yaml can steer restart_command / launcher "
+                    "binaries). To use it, set CODEROUTER_ALLOW_CWD_CONFIG=1 "
+                    "(only in directories you trust) or pass --config "
+                    f"{cwd_path} to name it explicitly."
+                ),
+            },
+        )
+    return cwd_path
+
+
+def load_config(path: str | os.PathLike[str] | None = None) -> CodeRouterConfig:
+    """Load providers.yaml + apply ALLOW_PAID env override."""
+    skipped_cwd = _warn_if_cwd_config_skipped(path)
+    candidates = _candidate_paths(path)
+    chosen: Path | None = next((p for p in candidates if p.is_file()), None)
+    if chosen is None:
+        searched = "\n  ".join(str(p) for p in candidates)
+        message = (
+            f"providers.yaml not found. Searched:\n  {searched}\n"
+            f"Hint: copy examples/providers.yaml to ~/.coderouter/providers.yaml"
+        )
+        if skipped_cwd is not None:
+            message += (
+                f"\nNote: {skipped_cwd} exists but was NOT read — implicit "
+                "CWD discovery is opt-in since v2.13.0. Three ways to use "
+                f"it: pass --config {skipped_cwd}, set "
+                f"CODEROUTER_CONFIG={skipped_cwd}, or set "
+                "CODEROUTER_ALLOW_CWD_CONFIG=1 (only in directories you trust)."
+            )
+        raise FileNotFoundError(message)
+    _warn_if_cwd_config(chosen, explicit=path)
+
+    with chosen.open("r", encoding="utf-8") as f:
+        raw = yaml.safe_load(f) or {}
+
+    # v0.6-A: CODEROUTER_MODE env overrides the YAML default_profile BEFORE
+    # initial validation, so that (a) a typo'd file default that would otherwise
+    # fail can be rescued by an explicit env-set mode, and (b) the model-
+    # validator's "default_profile must exist in profiles" check applies to the
+    # *effective* mode the engine will see, not the pre-override YAML value.
+    #
+    # v1.8.0+: also resolve env_mode through ``mode_aliases`` before assigning,
+    # so that startup-time ``--mode coding`` (env CODEROUTER_MODE=coding)
+    # behaves symmetrically with the runtime ``X-CodeRouter-Mode: coding``
+    # header — both should accept short intent names like ``coding`` /
+    # ``general`` / ``reasoning`` and resolve them to the underlying profile
+    # (e.g. ``claude-code-nim`` in providers.nvidia-nim.yaml). Without this,
+    # users on the NIM example yaml hit
+    #   "default_profile 'coding' is not declared in profiles:
+    #    known=['claude-code-nim', ...]"
+    # because mode_aliases only fired at request time, not at startup.
+    env_mode = os.environ.get("CODEROUTER_MODE", "").strip()
+    if env_mode:
+        # Pre-validation alias resolution: if env_mode isn't directly a
+        # profile name but matches an entry in raw["mode_aliases"], swap it
+        # for the underlying profile name. This avoids forcing every example
+        # yaml to mirror the v1.8.0 four-profile names (multi/coding/general
+        # /reasoning) just to accept the canonical short --mode flags.
+        raw_profiles = raw.get("profiles", []) or []
+        profile_names = {
+            p.get("name") for p in raw_profiles if isinstance(p, dict)
+        }
+        raw_aliases = raw.get("mode_aliases", {}) or {}
+        if (
+            env_mode not in profile_names
+            and isinstance(raw_aliases, dict)
+            and env_mode in raw_aliases
+        ):
+            env_mode = raw_aliases[env_mode]
+        raw["default_profile"] = env_mode
+
+    config = CodeRouterConfig.model_validate(raw)
+
+    # Env var ALLOW_PAID overrides file value (so users can flip it per-shell)
+    env_paid = os.environ.get("ALLOW_PAID", "").strip().lower()
+    if env_paid in {"1", "true", "yes", "on"}:
+        config.allow_paid = True
+    elif env_paid in {"0", "false", "no", "off"}:
+        config.allow_paid = False
+
+    return config
+
+
+def resolve_api_key(api_key_env: str | None) -> str | None:
+    """Look up an API key from the named env var. Returns None if unset."""
+    if not api_key_env:
+        return None
+    value = os.environ.get(api_key_env, "").strip()
+    return value or None