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

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

@@ -9,6 +9,199 @@ are kept verbatim where the Japanese text itself is the subject).
 
 ---
 
+## [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.unknown_device_ids`.
+
+### 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 vscode-init` — one-shot VSCode workspace scaffolder.**
+  Writes `.vscode/settings.json` with `terminal.integrated.env.osx` /
+  `.linux` / `.windows` populated so a Claude Code session launched
+  from VSCode's integrated terminal auto-points at CodeRouter with no
+  manual `ANTHROPIC_BASE_URL` juggling. Optionally emits a direnv
+  `.envrc` (`--with-envrc`). The command is **idempotent** (re-running
+  with the same arguments is a no-op) and **conflict-aware**: if an
+  existing `settings.json` has different values for one of our managed
+  keys, the file is left untouched and a unified diff is printed —
+  operators re-run with `--force` to overwrite. Unrelated top-level
+  keys (`editor.fontSize`, `python.testing.pytestEnabled`, etc.) and
+  unrelated env keys inside the terminal blocks (a user's `PATH`
+  tweak) are preserved verbatim on merge. All writes are atomic
+  (temp file + `os.replace`) so a partial write cannot corrupt an
+  existing `settings.json`. Non-Claude-Code extensions (Cline / Roo
+  Code / Kilo Code / Continue.dev) are handled by a cheat sheet
+  printed at end of run plus the fuller `docs/guides/vscode.md` —
+  `vscode-init` deliberately does NOT reach into those extensions'
+  own config schemas (each ships its own release cadence, so any
+  automation would need continuous maintenance to follow). The
+  Continue.dev cheat-sheet snippet is built via `json.dumps` rather
+  than hand-formatted concatenation, so it is guaranteed to be
+  syntactically valid JSON (an early hand-formatted version leaked
+  an extra `}` from mismatched f-string / plain-string brace
+  escaping; a test round-trips the snippet through `json.loads` to
+  pin the invariant). Options: `--target PATH` (default cwd),
+  `--port PORT` (default **8088**, matching every docs / quickstart
+  example — note that `coderouter serve` alone still defaults to
+  4000, so if you serve on 4000 pass `--port 4000` here too),
+  `--profile NAME` (adds `CODEROUTER_MODE=<profile>` to the terminal
+  env for header-less profile routing), `--with-envrc` (also emit
+  `.envrc`), `--dry-run` (compute diffs but write nothing —
+  byte-identical to the write path minus the final `os.replace`),
+  and `--force` (overwrite conflicting values). Exit codes: 0 clean,
+  2 conflicts (nothing was written for the conflicting file), 1
+  hard error (unparseable JSON, missing target directory, write
+  failure). Implementation lives in `coderouter/vscode_init.py`
+  (stdlib only — no new runtime deps, keeping the strict-5-package
+  rule in `pyproject.toml` intact); the CLI wrapper
+  (`_run_vscode_init` in `coderouter/cli.py`) mirrors the existing
+  `stats` / `audit` / `replay` "thin argparse plumbing + logic in a
+  sibling module" pattern. See `tests/test_vscode_init.py` (33 cases
+  across happy paths, merge preservation, conflict detection,
+  `--force`, `--dry-run` byte parity, `.envrc`, malformed inputs,
+  JSON validity of the Continue.dev snippet, and CLI wrapper
+  plumbing) and the new `docs/guides/vscode.md` for the full Cline /
+  Roo / Continue.dev cheat sheet.
+
+### Documentation
+
+- **Launcher port ↔ `providers.yaml` mismatch, three ways to prevent
+  it.** New section
+  ["providers.yaml とのポート整合"](docs/backends/launcher.md#providersyaml-とのポート整合食い違いを構造的に防ぐ)
+  in the Launcher guide walks through the three coexisting patterns
+  — (A) hardcoded `providers.yaml` with matching Launcher port
+  (traditional), (B) v2.7.4 Launcher auto-sync
+  (`launcher-<backend>-<port>` provider names, no `providers.yaml`
+  edit needed), and (C) the recommended hybrid where
+  `option_profiles` pins the port so the Launcher UI and
+  `providers.yaml` cannot drift. Includes a copy-paste `cr-check`
+  shell function that runs `coderouter doctor --check-model <name>`
+  against every hand-declared provider before work begins so
+  operators catch a port mismatch in seconds rather than after a
+  session of quiet fallback churn. The symptom side (dashboard's
+  `unhealthy` badge + half-and-half `provider-failed` events in the
+  ring buffer while requests still succeed via fallback) is
+  documented as a new
+  [troubleshooting §1-7](docs/guides/troubleshooting.md#1-7-transport-error-all-connections-failed--ポート不一致の疑い)
+  entry, cross-linked back to the Launcher guide for the fix. Both
+  additions are Japanese-side only (English counterpart will follow
+  in a later docs-sync commit).
+
+### Fixed
+
+- **`ProviderConfig.timeout_s` upper bound raised from 600s (10 min) to
+  86400s (24h)** (#76, contributed by @firelzrd). The previous 10-minute
+  ceiling was too restrictive for long-running local model inference —
+  configurations that legitimately need multi-hour timeouts (heavy
+  reasoning models, large-context sweeps, batch operations) were being
+  rejected by the Pydantic `le=600` validator before the request could
+  even leave the router. The default (30s) and lower bound (1s) are
+  unchanged, so existing configs are unaffected; only users who were
+  hitting the ceiling gain the new headroom.
+
+---
+
 ## [v2.9.4] — 2026-07-19 (launcher device selection & bench sweep, cache-stable system prompt)
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coderouter-cli
-Version: 2.9.4
+Version: 2.11.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
@@ -132,6 +132,8 @@ ANTHROPIC_BASE_URL=http://localhost:8088 ANTHROPIC_AUTH_TOKEN=dummy claude
 
 これだけ。Claude Code はいつも通り動きますが、裏ではローカルの Ollama が答えています。
 
+**VSCode の統合ターミナルから使う場合** は、環境変数の書き忘れを避けるため `coderouter vscode-init` が便利です。プロジェクトルートで 1 回叩くと `.vscode/settings.json` に `terminal.integrated.env.*` をマージ書き込みするので、以後 VSCode のターミナルで `claude` と打つだけで通ります。Cline / Roo Code / Continue.dev の設定コピペも含めて → [VSCode 連携ガイド](./docs/guides/vscode.md)
+
 ---
 
 ## 自分に必要？
@@ -222,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 に追記するだけで有効になる
@@ -281,6 +284,7 @@ providers:
 | 無料で回す | [無料枠ガイド](./docs/guides/free-tier-guide.md) |
 | llama.cpp / vllm を GUI で起動 | [Launcher ガイド](./docs/backends/launcher.md) |
 | 言語税を計測・回避する | [言語税ガイド](./docs/guides/language-tax.md) |
+| VSCode / Cline / Continue から使う | [VSCode 連携ガイド](./docs/guides/vscode.md) |
 | 別の PC から安全に繋ぐ | [リモートアクセスガイド](./docs/guides/remote-access.md) |
 | 詰まった | [トラブルシューティング](./docs/guides/troubleshooting.md) |
 | 設計を知りたい | [アーキテクチャ詳細](./docs/concepts/architecture.md) |

{coderouter_cli-2.9.4 → coderouter_cli-2.11.0}/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.9.4 → coderouter_cli-2.11.0}/README.md

@@ -87,6 +87,8 @@ ANTHROPIC_BASE_URL=http://localhost:8088 ANTHROPIC_AUTH_TOKEN=dummy claude
 
 これだけ。Claude Code はいつも通り動きますが、裏ではローカルの Ollama が答えています。
 
+**VSCode の統合ターミナルから使う場合** は、環境変数の書き忘れを避けるため `coderouter vscode-init` が便利です。プロジェクトルートで 1 回叩くと `.vscode/settings.json` に `terminal.integrated.env.*` をマージ書き込みするので、以後 VSCode のターミナルで `claude` と打つだけで通ります。Cline / Roo Code / Continue.dev の設定コピペも含めて → [VSCode 連携ガイド](./docs/guides/vscode.md)
+
 ---
 
 ## 自分に必要？
@@ -177,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 に追記するだけで有効になる
@@ -236,6 +239,7 @@ providers:
 | 無料で回す | [無料枠ガイド](./docs/guides/free-tier-guide.md) |
 | llama.cpp / vllm を GUI で起動 | [Launcher ガイド](./docs/backends/launcher.md) |
 | 言語税を計測・回避する | [言語税ガイド](./docs/guides/language-tax.md) |
+| VSCode / Cline / Continue から使う | [VSCode 連携ガイド](./docs/guides/vscode.md) |
 | 別の PC から安全に繋ぐ | [リモートアクセスガイド](./docs/guides/remote-access.md) |
 | 詰まった | [トラブルシューティング](./docs/guides/troubleshooting.md) |
 | 設計を知りたい | [アーキテクチャ詳細](./docs/concepts/architecture.md) |

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

@@ -336,6 +336,78 @@ def _build_parser() -> argparse.ArgumentParser:
         ),
     )
 
+    # v2.10-A: `coderouter vscode-init` — scaffold a VSCode workspace so
+    # Claude Code launched from the integrated terminal auto-points at
+    # CodeRouter (no manual env-var juggling). Optionally writes .envrc
+    # for direnv users. Cline / Roo / Continue are covered by the cheat
+    # sheet printed on completion and docs/guides/vscode.md — this
+    # command deliberately does NOT touch those extensions' settings
+    # (their schemas change with their own release cadence).
+    vscode_init = sub.add_parser(
+        "vscode-init",
+        help="Scaffold VSCode workspace settings for CodeRouter (v2.10-A).",
+        description=(
+            "Write .vscode/settings.json (terminal.integrated.env.*) so a "
+            "Claude Code session launched from VSCode's integrated terminal "
+            "auto-points at CodeRouter. Optionally emit a direnv .envrc. "
+            "Idempotent: safe to re-run. Conflict-aware: refuses to overwrite "
+            "differing existing values without --force."
+        ),
+    )
+    vscode_init.add_argument(
+        "--target",
+        default=".",
+        metavar="PATH",
+        help="Workspace root (default: current directory).",
+    )
+    vscode_init.add_argument(
+        "--port",
+        type=int,
+        default=None,
+        metavar="PORT",
+        help=(
+            "CodeRouter port for ANTHROPIC_BASE_URL. Defaults to 8088 "
+            "(matches every docs / quickstart example). Note that "
+            "`coderouter serve` alone defaults to 4000; if you serve on "
+            "4000, pass --port 4000 here too."
+        ),
+    )
+    vscode_init.add_argument(
+        "--profile",
+        default=None,
+        metavar="NAME",
+        help=(
+            "Preload CODEROUTER_MODE=<profile> so the VSCode terminal "
+            "routes to a non-default profile without a per-request header."
+        ),
+    )
+    vscode_init.add_argument(
+        "--with-envrc",
+        action="store_true",
+        help=(
+            "Also write .envrc (direnv). Run `direnv allow` once after "
+            "generation. Tip: keep secrets in a separate .envrc.local."
+        ),
+    )
+    vscode_init.add_argument(
+        "--dry-run",
+        action="store_true",
+        help=(
+            "Compute all changes and print unified diffs, but do not write "
+            "any files. Byte-identical to the write path minus the final "
+            "os.replace."
+        ),
+    )
+    vscode_init.add_argument(
+        "--force",
+        action="store_true",
+        help=(
+            "Overwrite existing conflicting values. Without this flag, a "
+            "conflict is reported with a diff and the file is left "
+            "untouched (exit 2)."
+        ),
+    )
+
     return parser
 
 
@@ -432,6 +504,9 @@ def main(argv: list[str] | None = None) -> int:
     if args.command == "replay":
         return _run_replay(args)
 
+    if args.command == "vscode-init":
+        return _run_vscode_init(args)
+
     print(f"unknown command: {args.command}", file=sys.stderr)
     return 2
 
@@ -765,6 +840,56 @@ def _run_replay(args: argparse.Namespace) -> int:
     return 0
 
 
+def _run_vscode_init(args: argparse.Namespace) -> int:
+    """v2.10-A: drive :func:`coderouter.vscode_init.run_vscode_init`.
+
+    Kept small and testable — the actual scaffolding logic lives in
+    :mod:`coderouter.vscode_init` so tests can exercise it without
+    argparse in the way. This wrapper's job is:
+
+    * resolve the ``--target`` argument to a real directory
+    * map ``--port`` (default None) to the module's ``DEFAULT_PORT``
+    * translate exceptions (missing target directory) to a friendly
+      stderr message + exit 1
+    * print the formatted result and propagate the module's exit code
+    """
+    from coderouter.vscode_init import (
+        DEFAULT_PORT,
+        exit_code_for,
+        format_result,
+        run_vscode_init,
+    )
+
+    target = Path(args.target).expanduser()
+    if not target.is_dir():
+        print(
+            f"vscode-init: target directory does not exist: {target}",
+            file=sys.stderr,
+        )
+        return 1
+
+    port = args.port if args.port is not None else DEFAULT_PORT
+
+    try:
+        result = run_vscode_init(
+            target,
+            port=port,
+            profile=args.profile,
+            with_envrc=args.with_envrc,
+            dry_run=args.dry_run,
+            force=args.force,
+        )
+    except FileNotFoundError as exc:
+        # Raised only when target vanishes between the pre-check above
+        # and the module's own check — unlikely in practice, but map
+        # it to the same shape as the pre-check for consistency.
+        print(f"vscode-init: {exc}", file=sys.stderr)
+        return 1
+
+    print(format_result(result, dry_run=args.dry_run, port=port))
+    return exit_code_for(result)
+
+
 def _run_check_env(arg_value: str) -> int:
     """v1.6.3: filesystem / git security checks for `.env`.
 

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

@@ -17,7 +17,14 @@ import re
 import warnings
 from typing import Any, Literal, Self
 
-from pydantic import BaseModel, ConfigDict, Field, HttpUrl, model_validator
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    HttpUrl,
+    field_validator,
+    model_validator,
+)
 
 
 class Capabilities(BaseModel):
@@ -394,7 +401,7 @@ class ProviderConfig(BaseModel):
         default=False,
         description="If true, only used when ALLOW_PAID=true (plan.md §2.3).",
     )
-    timeout_s: float = Field(default=30.0, ge=1.0, le=600.0)
+    timeout_s: float = Field(default=30.0, ge=1.0, le=86400.0)
 
     # v2.6 language-tax track: path to a LOCAL ``tokenizer.json`` for this
     # provider's model, used to measure the CJK over-count vs the char/4
@@ -1414,6 +1421,29 @@ class LauncherBackendConfig(BaseModel):
             binary: ~/llama.cpp/build/bin/llama-server
           vllm:
             binary: ~/.venv/bin/python
+
+    **Backend variants** (v2.11.0+, docs/designs/launcher-multi-build.md):
+    a key may also be ``<base>-<variant>`` to register an additional build of
+    the same backend — typically llama.cpp compiled for a specific GPU
+    runtime. Each variant appears as its own entry in the Launcher's backend
+    select, gets its own ``--list-devices`` probe (device IDs differ per
+    build: ``CUDA0`` and ``Vulkan0`` are not the same GPU) and can carry its
+    own ``option_profiles``. ``binary`` is **required** for a variant::
+
+        backends:
+          llama.cpp:                    # 素のビルド (binary 省略可 = PATH)
+            binary: ~/llm/apps/llama.cpp/build/bin/llama-server
+          llama.cpp-cuda:
+            binary: ~/llm/apps/llama.cpp/build-cuda/bin/llama-server
+          llama.cpp-vulkan:
+            binary: ~/llm/apps/llama.cpp/build-vulkan/bin/llama-server
+          llama.cpp-rocm:
+            binary: ~/llm/apps/llama.cpp/build-rocm/bin/llama-server
+
+    Variants are an advanced option: the matching GPU runtime (CUDA Toolkit /
+    Vulkan runtime + ICD / ROCm) must already be installed by the operator.
+    CodeRouter never selects a variant implicitly — omit them and both the UI
+    and the resulting argv are identical to before.
     """
 
     model_config = ConfigDict(extra="forbid")
@@ -1544,9 +1574,39 @@ class SwapModelSpec(BaseModel):
             "only widens *catalog* matching for ``SwapManager.match``."
         ),
     )
-    backend: Literal["llama.cpp", "vllm", "mlx"] = Field(
-        ..., description="Same backend set as the manual launcher UI / _build_cmd.",
+    backend: str = Field(
+        ...,
+        description=(
+            "Same backend set as the manual launcher UI / _build_cmd: "
+            "'llama.cpp' / 'vllm' / 'mlx', optionally with a '-<variant>' "
+            "suffix naming a specific build declared in launcher.backends "
+            "(e.g. 'llama.cpp-cuda' to pin this model to the CUDA build). "
+            "Validated by the field validator below plus "
+            "LauncherConfig._check_swap_backends_declared."
+        ),
     )
+
+    @field_validator("backend")
+    @classmethod
+    def _check_backend_name(cls, v: str) -> str:
+        """基底名 or 既知基底名 + 妥当なバリアントのみ許す。
+
+        以前は ``Literal["llama.cpp","vllm","mlx"]`` だった。バリアント
+        (``llama.cpp-cuda``) を通すため str に緩めたので、代わりに形式検証を
+        ここで行う。既存の 3 値はそのまま通る (後方互換)。
+        """
+        from coderouter.launcher_devices import (
+            KNOWN_BASE_BACKENDS,
+            is_valid_backend_name,
+        )
+
+        if not is_valid_backend_name(v):
+            raise ValueError(
+                f"backend {v!r} is not valid. Expected one of "
+                f"{list(KNOWN_BASE_BACKENDS)} or '<base>-<variant>' "
+                "(e.g. 'llama.cpp-cuda')."
+            )
+        return v
     model_path: str = Field(
         ...,
         description=(
@@ -1802,10 +1862,13 @@ class LauncherConfig(BaseModel):
         default_factory=dict,
         description=(
             "Per-backend binary path overrides. "
-            "Keys are backend names ('llama.cpp', 'vllm'). "
-            "When a key is absent, the default executable is used "
-            "('llama-server' / 'python') and resolved via PATH. "
-            "Useful when running a from-source build or a venv-specific binary."
+            "Keys are backend names ('llama.cpp', 'vllm', 'mlx') or backend "
+            "variants ('llama.cpp-cuda', 'llama.cpp-vulkan', ...) naming an "
+            "additional build of the same backend — see "
+            "LauncherBackendConfig. When a base key is absent, the default "
+            "executable is used ('llama-server' / 'python') and resolved via "
+            "PATH. Variants must set 'binary' explicitly and additionally "
+            "appear in the Launcher's backend select."
         ),
     )
     option_profiles: dict[str, list[LauncherOptionProfile]] = Field(
@@ -1813,6 +1876,10 @@ class LauncherConfig(BaseModel):
         description=(
             "Named option presets per backend. "
             "Keys should be backend names: 'llama.cpp', 'vllm'. "
+            "A backend-variant key ('llama.cpp-cuda') is also accepted: its "
+            "presets are appended to the base backend's list, and a preset "
+            "whose 'name' collides replaces the inherited one in place "
+            "(see launcher_devices.resolve_option_profiles). "
             "Each key maps to an ordered list of named presets. "
             "A free-form 'extra args' field is always available in the UI "
             "for one-off overrides without touching this config."
@@ -1929,15 +1996,82 @@ class LauncherConfig(BaseModel):
             )
         return self
 
+    @model_validator(mode="after")
+    def _check_backend_names_and_variant_binaries(self) -> LauncherConfig:
+        """``backends`` のキー形式と、バリアントの ``binary`` 必須を検証する。
+
+        設計: docs/designs/launcher-multi-build.md §5.2。
+
+        1. キーは既知基底名 (``llama.cpp`` / ``vllm`` / ``mlx``) そのもの、
+           または ``<既知基底名>-<バリアント>`` (``llama.cpp-cuda`` 等) のみ。
+           **破壊的変更**: これまで ``llamacpp:`` のような typo は黙って無視
+           されていた (バックエンド一覧が固定 3 キーだったため)。今後は
+           ロード時エラーになる。
+        2. **バリアントは ``binary`` 必須**。``llama.cpp-cuda: {}`` を許すと
+           既定名フォールバックで PATH の ``llama-server`` が使われ、CUDA
+           ビルドを指定したつもりで素のビルドが静かに動く —— 本機能で最も
+           気づきにくい事故なのでロード時に殺す。基底名は従来どおり
+           ``binary`` 省略可 (PATH 解決)。
+        """
+        from coderouter.launcher_devices import (
+            KNOWN_BASE_BACKENDS,
+            is_valid_backend_name,
+            is_variant,
+        )
+
+        for name, bc in self.backends.items():
+            if not is_valid_backend_name(name):
+                raise ValueError(
+                    f"launcher.backends: invalid backend key {name!r}. "
+                    f"Expected one of {list(KNOWN_BASE_BACKENDS)} or "
+                    "'<base>-<variant>' where variant matches "
+                    "[a-z0-9][a-z0-9._-]* (e.g. 'llama.cpp-cuda')."
+                )
+            if is_variant(name) and not bc.binary:
+                raise ValueError(
+                    f"launcher.backends[{name!r}]: 'binary' is required for a "
+                    "backend variant. Without it the launcher would fall back "
+                    "to the base default on PATH and silently run a different "
+                    "build than the one you selected."
+                )
+        return self
+
+    @model_validator(mode="after")
+    def _check_swap_backends_declared(self) -> LauncherConfig:
+        """swap のモデルがバリアントを指すなら ``backends`` に実在すること。
+
+        設計 §5.2-3。基底名 (``llama.cpp`` 等) は ``backends`` に書かなくても
+        PATH 解決で動くので従来どおり不要。バリアントは実行ファイルパスが
+        ``backends`` にしか無いので、宣言漏れをロード時に弾く。
+        """
+        if self.swap is None:
+            return self
+        from coderouter.launcher_devices import is_variant
+
+        for spec in self.swap.models:
+            if is_variant(spec.backend) and spec.backend not in self.backends:
+                raise ValueError(
+                    f"launcher.swap.models[{spec.name!r}]: backend "
+                    f"{spec.backend!r} is a variant but is not declared in "
+                    "launcher.backends (its binary path is unknown)."
+                )
+        return self
+
     @model_validator(mode="after")
     def _check_swap_option_profiles_exist(self) -> LauncherConfig:
-        """§5.4 #2: a swap model's ``option_profile`` must be a real preset."""
+        """§5.4 #2: a swap model's ``option_profile`` must be a real preset.
+
+        バリアント backend の場合は基底名のプロファイルも継承されるので
+        (:func:`resolve_option_profiles`)、マージ後の一覧で判定する。
+        """
         if self.swap is None:
             return self
+        from coderouter.launcher_devices import resolve_option_profiles
+
         for spec in self.swap.models:
             if spec.option_profile is None:
                 continue
-            profiles = self.option_profiles.get(spec.backend, [])
+            profiles = resolve_option_profiles(self.option_profiles, spec.backend)
             if not any(p.name == spec.option_profile for p in profiles):
                 raise ValueError(
                     f"launcher.swap.models[{spec.name!r}]: option_profile "