coderouter-cli 2.9.2__tar.gz → 2.9.3__tar.gz

{coderouter_cli-2.9.2 → coderouter_cli-2.9.3}/CHANGELOG.md

@@ -9,6 +9,90 @@ are kept verbatim where the Japanese text itself is the subject).
 
 ---
 
+## [v2.9.3] — 2026-07-12 (GUI/Web parity, swap polish, launcher UI fixes)
+
+### Added
+
+- **Per-model TTL override for `launcher.swap`.** `SwapModelSpec.ttl_seconds`
+  (new, optional, `None` by default) lets a catalog entry override the
+  global `launcher.swap.ttl_seconds` for just that one model — `None`
+  keeps following the global value, `0` unloads the model as soon as
+  its last in-flight lease releases (same meaning as the global field's
+  `0`, just scoped to one entry). `SwapManager.sweep_once` now resolves
+  each model's effective TTL individually, and the sweeper starts
+  whenever either the global TTL or at least one catalog entry's
+  override is set (previously gated solely on the global value). See
+  `tests/test_launcher_swap.py` (`test_ttl_override_spec_wins_over_global`,
+  `test_ttl_override_unset_falls_back_to_global`,
+  `test_ttl_override_zero_unloads_even_when_global_ttl_disabled`) and the
+  updated `launcher.swap` field table in `docs/backends/launcher.md` /
+  `launcher.en.md`.
+- **Configurable ephemeral-port retry count for `launcher.swap`.**
+  `LauncherSwapConfig.port_retry_attempts` (new, default `2`, range
+  0–5) replaces the previously hard-coded single retry for catalog
+  entries that leave `port` unset — the swap manager now attempts up
+  to `1 + port_retry_attempts` spawns (each on a freshly picked
+  ephemeral port) before giving up, versus the previous fixed 2 total
+  attempts. Fixed-port entries are unaffected (still exactly one
+  attempt — a second try on the same port would just collide again).
+  This narrows the practical impact of the known pick-then-bind TOCTOU
+  window documented on `SwapModelSpec.port` / `_pick_ephemeral_port`
+  but does not close it outright; a fixed `port` remains the only way
+  to eliminate the race entirely. See
+  `tests/test_launcher_swap.py`
+  (`test_port_none_retries_default_port_retry_attempts`,
+  `test_port_retry_attempts_exhausted_raises`,
+  `test_port_retry_attempts_configurable_to_zero`).
+- **`/launcher` UI now shows which processes are swap-managed.**
+  `GET /api/launcher/processes` includes `swap_managed` (bool) and
+  `swap_model` (the swap catalog model name, or `null`) for every
+  process; `spawn_process` gained a `swap_model` kwarg that
+  `SwapManager._spawn` now passes through. The process table renders a
+  small "swap" badge next to the name of any swap-managed process
+  (title shows the backing catalog model when known). Manually-started
+  processes are unaffected (`swap_managed: false`, `swap_model: null`).
+  See `tests/test_launcher_swap.py::test_i1_on_demand_spawn_reaches_200`.
+
+### Fixed
+
+- **Swap-managed "stopped" processes no longer accumulate in the launcher
+  registry.** `stop_process` only sets `status="stopped"` and never
+  removes the entry — deliberate for manually started processes (the
+  stopped row is visible history in the /launcher UI, with logs and an
+  explicit ✕ delete button), but swap-managed processes went through the
+  same path, so every failed readiness attempt left one permanent
+  "stopped" row (`1 + port_retry_attempts` rows per failed load — 3 with
+  the defaults) and every TTL unload left another, all growing
+  `GET /api/launcher/processes` and the UI without bound. `SwapManager`
+  now removes its own processes from the registry after stopping them,
+  in both the failed-readiness cleanup (`_spawn_with_retry`) and the TTL
+  unload (`_unload_locked`), guarded on `ManagedProcess.swap_managed` so
+  a manual process is never swept up. Crash leftovers (a swap process
+  that died on its own) are deliberately kept — their log tail is the
+  only crash forensics an operator has. See `tests/test_launcher_swap.py`
+  (`test_failed_load_leaves_no_registry_litter`,
+  `test_ttl_unload_removes_registry_entry`,
+  `test_registry_removal_skips_non_swap_processes`; adapted from the
+  review repro with its assertions inverted).
+- **/launcher UI no longer 404-polls a removed process's logs forever.**
+  The log panel's poller (`poll()` → `refreshLogs()`, every 3s) never
+  checked the response status: once the polled id left the registry —
+  a `coderouter serve` restart under a still-open browser tab, a delete
+  issued from another client, or (with the fix above) a swap TTL unload
+  removing the entry mid-view — the 404 body has no `.logs`, the
+  resulting TypeError landed in the generic catch, and `selectedLogId`
+  was never cleared, so the tab kept hitting
+  `GET /api/launcher/logs/<stale-id>` and spamming `404 Not Found` into
+  the serve log indefinitely. The UI now stops polling as soon as the
+  selected id disappears from the periodic `/api/launcher/processes`
+  refresh (usually before a single 404 is even issued), treats a logs
+  404 as terminal (shows "(process removed)" instead of retrying), and
+  the server keeps answering 404 for unknown ids — that behavior is
+  correct and now pinned by
+  `tests/test_launcher_swap.py::test_logs_unknown_proc_id_is_404`.
+
+---
+
 ## [v2.9.2] — 2026-07-12 (config: no more dummy provider for swap-only setups)
 
 ### Changed

{coderouter_cli-2.9.2 → coderouter_cli-2.9.3}/PKG-INFO

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

@@ -1518,10 +1518,25 @@ class SwapModelSpec(BaseModel):
         le=65535,
         description=(
             "Fixed port (recommended — §10 Q2). When unset, the swap "
-            "manager picks an OS-assigned ephemeral port and retries "
-            "once on a different port if the backend fails to become "
-            "ready. Best-effort only — no strong TOCTOU guarantee "
-            "(§6.6 known-trap #4)."
+            "manager picks an OS-assigned ephemeral port and retries, "
+            "each time on a freshly picked port, up to "
+            "``LauncherSwapConfig.port_retry_attempts`` additional "
+            "times if the backend fails to become ready. Best-effort "
+            "only — no strong TOCTOU guarantee (§6.6 known-trap #4)."
+        ),
+    )
+    ttl_seconds: float | None = Field(
+        default=None,
+        ge=0.0,
+        description=(
+            "[Unreleased] Per-model override of "
+            "``LauncherSwapConfig.ttl_seconds``. ``None`` (default) = "
+            "use the global value. ``0`` = unload as soon as the last "
+            "in-flight lease for THIS model releases — same meaning as "
+            "the global field's ``0``, just scoped to one catalog "
+            "entry. Lets a large/expensive model unload sooner (or "
+            "stay resident longer) than the rest of the catalog "
+            "without changing the global default."
         ),
     )
     option_profile: str | None = Field(
@@ -1611,8 +1626,10 @@ class LauncherSwapConfig(BaseModel):
             "Seconds of no in-flight requests after which an idle swap "
             "process is auto-stopped. None = TTL disabled (runs until "
             "explicitly stopped). 0 = unload as soon as the last "
-            "in-flight lease releases. §10 Q1: one GLOBAL value for "
-            "Phase 1 — no per-model override yet."
+            "in-flight lease releases. §10 Q1: this is the GLOBAL "
+            "default; a catalog entry's ``SwapModelSpec.ttl_seconds`` "
+            "overrides it for that one model when set "
+            "([Unreleased] per-model TTL override)."
         ),
     )
     readiness_timeout_s: float = Field(
@@ -1631,6 +1648,24 @@ class LauncherSwapConfig(BaseModel):
         le=600.0,
         description="How often the TTL sweeper background task scans for idle processes.",
     )
+    port_retry_attempts: int = Field(
+        default=2,
+        ge=0,
+        le=5,
+        description=(
+            "[Unreleased] Number of ADDITIONAL spawn attempts (each on a "
+            "freshly picked ephemeral port) after the first, used only "
+            "when a catalog entry's ``port`` is unset and the previous "
+            "attempt fails to become ready. 0 = no retry. Ignored when "
+            "``port`` is set — a fixed port never retries (a second "
+            "attempt would just collide on the same port again). This "
+            "does not close the pick-then-bind TOCTOU window (see "
+            "``coderouter.launcher_swap._pick_ephemeral_port``); it only "
+            "bounds how many times the swap manager re-rolls the dice. "
+            "A fixed ``port`` remains the recommended way to eliminate "
+            "the race entirely (§10 Q2)."
+        ),
+    )
     inject_auto_router_rules: bool = Field(
         default=True,
         description=(

{coderouter_cli-2.9.2 → coderouter_cli-2.9.3}/coderouter/ingress/launcher_routes.py

@@ -171,6 +171,13 @@ class ManagedProcess:
     #     under its per-model lock); a launcher auto-restart racing that
     #     re-spawn would fight over the same fixed port.
     swap_managed: bool = False
+    # [Unreleased]: the swap catalog model name (SwapModelSpec.name) this
+    # process backs, set by SwapManager._spawn via spawn_process's
+    # swap_model kwarg. None for a manually-started process (swap_managed
+    # is False) or if a future swap-managed spawn path omits it. Purely
+    # informational — surfaced by GET /api/launcher/processes so the
+    # /launcher UI can label which catalog entry a running process is.
+    swap_model: str | None = None
     # asyncio subprocess handle — not serialised
     _proc: Any = field(default=None, repr=False, compare=False)
 
@@ -1027,7 +1034,13 @@ async def api_launcher_config_debug(request: Request) -> dict[str, Any]:
 
 @router.get("/api/launcher/processes")
 async def api_processes(request: Request) -> dict[str, Any]:
-    """List all managed processes."""
+    """List all managed processes.
+
+    [Unreleased]: ``swap_managed`` / ``swap_model`` let the ``/launcher``
+    UI (and other API clients) tell an on-demand SwapManager-spawned
+    process apart from a manually-started one, and label which swap
+    catalog model it backs.
+    """
     reg = _registry(request)
     return {
         "processes": [
@@ -1040,6 +1053,8 @@ async def api_processes(request: Request) -> dict[str, Any]:
                 "status": p.status,
                 "pid": p.pid,
                 "returncode": p.returncode,
+                "swap_managed": p.swap_managed,
+                "swap_model": p.swap_model,
             }
             for p in reg.all()
         ]
@@ -1100,6 +1115,7 @@ async def spawn_process(
     draft_model_path: str | None = None,
     mtp_mode: str = "auto",
     swap_managed: bool = False,
+    swap_model: str | None = None,
 ) -> ManagedProcess:
     """Build argv, spawn the child process, and arm readiness/log tailing.
 
@@ -1116,6 +1132,12 @@ async def spawn_process(
     exist. Any other exception from ``create_subprocess_exec`` propagates
     as-is. Callers decide how to surface these (HTTP 400/500 for
     ``api_start``, a retryable ``AdapterError`` for SwapManager).
+
+    ``swap_model`` ([Unreleased]) is purely informational — the swap
+    catalog model name (``SwapModelSpec.name``), recorded on the
+    resulting ``ManagedProcess`` for ``GET /api/launcher/processes`` /
+    the ``/launcher`` UI. Only ``SwapManager._spawn`` passes it; the
+    manual ``POST /api/launcher/start`` path leaves it ``None``.
     """
     options = options if options is not None else {}
     configured_binary: str | None = None
@@ -1178,6 +1200,7 @@ async def spawn_process(
         spec_auto=spec_auto and fallback_cmd is not None,
         fallback_cmd=fallback_cmd,
         swap_managed=swap_managed,
+        swap_model=swap_model,
     )
     proc.log_tail.append(f"[launcher] cmd: {' '.join(cmd)}")
     for note in spec_notes:
@@ -1378,6 +1401,10 @@ _LAUNCHER_HTML = r"""<!doctype html>
   <style>
     .dot { width:.5rem;height:.5rem;border-radius:9999px;display:inline-block; }
     .tabnum { font-variant-numeric:tabular-nums; }
+    .badge-swap { font-size:10px; text-transform:uppercase; letter-spacing:.02em;
+                  background:rgba(99,102,241,.2); color:#a5b4fc; padding:1px 6px;
+                  border-radius:9999px; margin-left:6px; vertical-align:middle;
+                  white-space:nowrap; }
     .log-box { font-family:monospace;font-size:.75rem;line-height:1.4;
                overflow-y:auto;max-height:14rem;white-space:pre-wrap;word-break:break-all; }
     .model-row:hover { background:rgba(255,255,255,.04);cursor:pointer; }
@@ -1851,7 +1878,17 @@ _LAUNCHER_HTML = r"""<!doctype html>
     try {
       const r = await fetch("/api/launcher/processes");
       const d = await r.json();
-      renderProcesses(d.processes || []);
+      const procs = d.processes || [];
+      renderProcesses(procs);
+      // [Unreleased] 404-loop fix: if the process whose logs we're
+      // polling is no longer in the registry (deleted from another
+      // client, swap TTL unload removed it, or the server restarted
+      // under a still-open tab), stop the log polling BEFORE it even
+      // issues a 404 — otherwise poll() would hit
+      // /api/launcher/logs/<stale-id> every POLL_MS forever.
+      if (selectedLogId && !procs.some(p => p.id === selectedLogId)) {
+        markLogGone();
+      }
     } catch (_) {}
   };
 
@@ -1871,8 +1908,14 @@ _LAUNCHER_HTML = r"""<!doctype html>
         ? `<button onclick="deleteProc('${p.id}')" class="btn-sm btn-slate ml-1">✕</button>`
         : "";
       const logBtn = `<button onclick="openLog('${p.id}','${esc(p.name)}')" class="btn-sm btn-indigo ml-1">📋 ログ</button>`;
+      // [Unreleased]: swap badge — marks processes SwapManager spawned
+      // on demand, distinct from manually-started ones. Title shows the
+      // catalog model name when the backend supplied it.
+      const swapBadge = p.swap_managed
+        ? `<span class="badge-swap" title="${esc(p.swap_model ? "swap model: " + p.swap_model : "swap-managed")}">swap</span>`
+        : "";
       return `<tr>
-        <td class="py-2 pr-3 font-medium">${esc(p.name)}</td>
+        <td class="py-2 pr-3 font-medium">${esc(p.name)}${swapBadge}</td>
         <td class="py-2 pr-3 text-slate-400">${esc(p.backend)}</td>
         <td class="py-2 pr-3 text-slate-400 truncate max-w-[10rem]" title="${esc(p.model_path)}">${esc(modelName)}</td>
         <td class="py-2 pr-3 text-right">${p.port}</td>
@@ -1912,6 +1955,11 @@ _LAUNCHER_HTML = r"""<!doctype html>
     if (!selectedLogId) return;
     try {
       const r = await fetch(`/api/launcher/logs/${selectedLogId}?n=200`);
+      // [Unreleased] 404-loop fix: the id is gone from the registry —
+      // stop polling instead of retrying (and 404-spamming the serve
+      // log) every POLL_MS forever. The server keeps answering 404 for
+      // unknown ids (correct); the client just has to take the hint.
+      if (r.status === 404) { markLogGone(); return; }
       const d = await r.json();
       const box = document.getElementById("log-box");
       box.textContent = d.logs.join("\n") || "(ログなし)";
@@ -1921,6 +1969,15 @@ _LAUNCHER_HTML = r"""<!doctype html>
     }
   };
 
+  // [Unreleased] 404-loop fix: the process we were tailing no longer
+  // exists server-side. Clear selectedLogId (which is what stops both
+  // poll()'s refreshLogs call and any manual ↻) but keep the panel open
+  // with a terminal message so the user sees WHY the logs stopped.
+  const markLogGone = () => {
+    selectedLogId = null;
+    document.getElementById("log-box").textContent = "(process removed)";
+  };
+
   window.closeLog = () => {
     selectedLogId = null;
     document.getElementById("log-panel").classList.add("hidden");

{coderouter_cli-2.9.2 → coderouter_cli-2.9.3}/coderouter/launcher_swap.py

@@ -85,9 +85,18 @@ class _ModelState:
 def _pick_ephemeral_port() -> int:
     """Ask the OS for a free port. Best-effort only (§6.6 known-trap #4):
 
-    there is an unavoidable TOCTOU window between this call returning
-    and the child actually binding the port. Fixed ``port:`` in the
-    catalog entry avoids the race entirely (§10 Q2, recommended).
+    there is an unavoidable TOCTOU window between this call's bind+close
+    returning a "free" port and the child actually binding that same
+    port a moment later — nothing stops another process (or another
+    concurrent swap spawn) from grabbing it first. Retrying on a fresh
+    port when the child fails to come up
+    (``LauncherSwapConfig.port_retry_attempts``, default 2 additional
+    attempts) narrows the *impact* of losing that race but does NOT
+    close the window itself — a genuinely race-free allocation would
+    need the OS to hand the child an already-bound socket fd, which the
+    current spawn path (argv ``--port N``) does not support. Fixed
+    ``port:`` in the catalog entry avoids the race entirely (§10 Q2,
+    recommended) and remains the only way to eliminate it outright.
     """
     with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
         s.bind(("127.0.0.1", 0))
@@ -126,6 +135,13 @@ class SwapManager:
         self._readiness_timeout_s = config.readiness_timeout_s
         self._sweep_interval_s = config.sweep_interval_s
         self._sweeper_task: asyncio.Task[None] | None = None
+        # [Unreleased] per-model TTL override: the sweeper must run
+        # whenever EITHER the global TTL is enabled OR at least one
+        # catalog entry sets its own ``ttl_seconds`` (even if the global
+        # value is None/disabled) — see _effective_ttl / start().
+        self._any_ttl_configured = self._ttl_seconds is not None or any(
+            m.ttl_seconds is not None for m in config.models
+        )
 
     # ------------------------------------------------------------------
     # Catalog matching
@@ -214,24 +230,40 @@ class SwapManager:
         async with state.lock:
             await self._unload_locked(state, spec, reason)
 
+    def _effective_ttl(self, spec: SwapModelSpec) -> float | None:
+        """``spec.ttl_seconds`` if set, else the global ``self._ttl_seconds``.
+
+        [Unreleased] per-model TTL override (docs/backends/launcher.md
+        "launcher.swap fields" table). ``None`` at either level keeps
+        its usual meaning ("TTL disabled") — a spec-level override only
+        takes effect when it's not ``None``.
+        """
+        return spec.ttl_seconds if spec.ttl_seconds is not None else self._ttl_seconds
+
     async def sweep_once(self) -> None:
         """One TTL sweep pass: stop every idle, un-leased, expired model.
 
         Takes each model's own lock independently (never more than one
         per-model lock at a time — §6.6 known-trap #7) so a slow unload
-        for model A never delays the sweep of model B.
+        for model A never delays the sweep of model B. Each model's TTL
+        is resolved individually via :meth:`_effective_ttl` — a model
+        whose global TTL is disabled can still expire on its own
+        override, and vice versa.
         """
-        if self._ttl_seconds is None:
+        if not self._any_ttl_configured:
             return
         now = time.monotonic()
         for spec in list(self._catalog.values()):
+            ttl = self._effective_ttl(spec)
+            if ttl is None:
+                continue
             state = self._states.get(spec.name)
             if state is None:
                 continue
             async with state.lock:
                 if state.status != "ready" or state.in_flight > 0:
                     continue
-                if (now - state.last_used) < self._ttl_seconds:
+                if (now - state.last_used) < ttl:
                     continue
                 await self._unload_locked(state, spec, reason="ttl")
 
@@ -240,8 +272,14 @@ class SwapManager:
     # ------------------------------------------------------------------
 
     async def start(self) -> None:
-        """Start the TTL sweeper background task. No-op when TTL is disabled."""
-        if self._ttl_seconds is None or self._sweeper_task is not None:
+        """Start the TTL sweeper background task.
+
+        No-op when TTL is disabled both globally AND on every catalog
+        entry (``self._any_ttl_configured`` — [Unreleased] per-model
+        override means a per-model ``ttl_seconds`` alone is enough to
+        need the sweeper, even with the global TTL off).
+        """
+        if not self._any_ttl_configured or self._sweeper_task is not None:
             return
         self._sweeper_task = asyncio.create_task(self._sweeper_loop())
 
@@ -285,6 +323,35 @@ class SwapManager:
     def _engine(self) -> Any | None:
         return getattr(self._app.state, "engine", None)
 
+    def _remove_from_registry(self, proc_id: str) -> None:
+        """Drop a swap-managed ``ManagedProcess`` from the launcher registry.
+
+        [Unreleased] registry-litter fix: ``stop_process`` only sets
+        ``status="stopped"`` — it never removes the entry, because for
+        MANUALLY started processes the stopped row doubles as visible
+        history in the /launcher UI (with logs and an explicit ✕ delete
+        button). Swap-managed processes have no such contract: every
+        failed readiness attempt (times ``1 + port_retry_attempts``) and
+        every TTL unload would otherwise leave a permanent "stopped" row
+        accumulating unboundedly in ``GET /api/launcher/processes``. So
+        SwapManager removes ITS OWN processes right after it stops them,
+        guarded on ``swap_managed`` so a manual process can never be
+        swept up by mistake. Crash leftovers (a swap process that died
+        on its own, status "error"/"stopped" without SwapManager
+        stopping it) are deliberately NOT removed here — their log tail
+        is the only crash forensics an operator has; the ✕ button still
+        applies.
+        """
+        reg = _registry_for_app(self._app)
+        try:
+            proc = reg.get(proc_id)
+        except KeyError:
+            return
+        if not proc.swap_managed:
+            return
+        with contextlib.suppress(KeyError):
+            reg.remove(proc_id)
+
     def _resolve_options(self, spec: SwapModelSpec) -> dict[str, Any]:
         """Resolve ``spec.option_profile`` into the launcher options dict."""
         if not spec.option_profile or self._launcher_cfg is None:
@@ -346,11 +413,20 @@ class SwapManager:
     async def _spawn_with_retry(
         self, spec: SwapModelSpec
     ) -> tuple[ManagedProcess | None, Exception | None]:
-        """Spawn + wait for readiness. §10 Q2: one retry on a fresh ephemeral
-        port when ``spec.port`` is unset and the first attempt doesn't come
-        up (fixed ports never retry — a second attempt would collide again).
+        """Spawn + wait for readiness.
+
+        §10 Q2: when ``spec.port`` is unset, up to
+        ``1 + LauncherSwapConfig.port_retry_attempts`` attempts total
+        (default: 1 initial + 2 retries = 3), each on a freshly picked
+        ephemeral port via :func:`_pick_ephemeral_port` — see that
+        function's docstring for the residual pick-then-bind TOCTOU
+        window this does NOT close, only bounds the impact of. Fixed
+        ports never retry — a second attempt on the same port would
+        just collide again.
         """
-        attempts = 1 if spec.port is not None else 2
+        attempts = (
+            1 if spec.port is not None else 1 + self._config.port_retry_attempts
+        )
         last_exc: Exception | None = None
         for _attempt in range(attempts):
             port = spec.port if spec.port is not None else _pick_ephemeral_port()
@@ -368,6 +444,10 @@ class SwapManager:
             )
             with contextlib.suppress(Exception):
                 await stop_process(self._app, proc.id)
+            # [Unreleased] registry-litter fix: without this, every failed
+            # readiness attempt leaves one "stopped" row in the registry
+            # forever (1 + port_retry_attempts rows per failed load).
+            self._remove_from_registry(proc.id)
         return None, last_exc
 
     async def _spawn(self, spec: SwapModelSpec, port: int) -> ManagedProcess:
@@ -394,6 +474,10 @@ class SwapManager:
             # provider). H-2: exempt from launcher auto-restart (crash
             # recovery = next-request re-spawn under the per-model lock).
             swap_managed=True,
+            # [Unreleased]: catalog model name, surfaced by
+            # GET /api/launcher/processes as "swap_model" so the /launcher
+            # UI can show which swap catalog entry a process backs.
+            swap_model=spec.name,
         )
 
     async def _await_ready(self, proc: ManagedProcess) -> bool:
@@ -457,6 +541,10 @@ class SwapManager:
             with contextlib.suppress(Exception):
                 await stop_process(self._app, proc_id)
             await self._deregister(spec)
+            # [Unreleased] registry-litter fix: a TTL-unloaded swap process
+            # is not "history" the way a manually stopped one is — leaving
+            # it would grow the registry by one row per load/unload cycle.
+            self._remove_from_registry(proc_id)
         logger.info(
             "swap-unload",
             extra={"model": spec.name, "reason": reason, "proc_id": proc_id},

{coderouter_cli-2.9.2 → coderouter_cli-2.9.3}/docs/backends/launcher.en.md

@@ -276,14 +276,16 @@ For a more realistic example that mixes swap with an always-on backend like Olla
 | Field | Type | Default | Description |
 |---|---|---|---|
 | `enabled` | bool | `false` | Enable on-demand swap. `false` preserves manual-only startup exactly as before (no impact on existing deployments) |
-| `ttl_seconds` | float \| null | `1800.0` | Seconds of no in-flight requests after which the process is auto-stopped. `null` = disabled (runs until explicitly stopped), `0` = unload as soon as the last request completes. Phase 1 has a single global value only — no per-model override |
+| `ttl_seconds` | float \| null | `1800.0` | Seconds of no in-flight requests after which the process is auto-stopped. `null` = disabled (runs until explicitly stopped), `0` = unload as soon as the last request completes. This is the global default shared by all models — `models[].ttl_seconds` overrides it per model ([Unreleased]) |
 | `readiness_timeout_s` | float | `120.0` (1–1800) | Upper bound (seconds) a **request** will wait for an on-demand spawn to become ready before the dispatch hook raises a retryable `AdapterError`. **Distinct from `launcher.readiness_timeout_s` below (default 300s)** — this one bounds "how long one request waits," that one bounds "the general readiness-monitoring window for a process" |
 | `sweep_interval_s` | float | `15.0` (1–600) | How often the TTL sweeper background task scans for idle processes |
+| `port_retry_attempts` | int | `2` (0–5) | [Unreleased] Number of additional retries (each on a freshly picked ephemeral port) after a failed startup, for catalog entries that leave `models[].port` unset. `0` = no retry. Irrelevant for a fixed `port` (always exactly one attempt). Does not close the TOCTOU window itself — see `models[].port` below |
 | `inject_auto_router_rules` | bool | `true` | Whether to auto-generate an `auto_router` rule per catalog model (`id: swap:<name>`, `model_pattern` is an exact match on the name). Set `false` to wire routing yourself (e.g. via the `X-CodeRouter-Profile` header) |
 | `models[].name` | str (required) | — | Logical name matched against the request's `model` field. The provider name and dedicated profile name are automatically `launcher-swap-<name>` |
 | `models[].backend` | `"llama.cpp" \| "vllm" \| "mlx"` (required) | — | Same backend set as the manual Launcher UI |
 | `models[].model_path` | str (required) | — | Absolute or `~`-relative model file path. Must be **under `launcher.model_dirs`** — re-validated both at config load and at spawn time (defense against path traversal) |
-| `models[].port` | int \| null | `null` | Fixed port recommended. When unset, an OS-assigned ephemeral port is used, with one retry on a different port if startup fails (best-effort — no strong TOCTOU guarantee) |
+| `models[].port` | int \| null | `null` | Fixed port recommended. When unset, an OS-assigned ephemeral port is used, retrying on a fresh port up to `launcher.swap.port_retry_attempts` times (default 2) if startup fails. Best-effort — the gap between picking the port and the child actually binding it (TOCTOU) is never fully closed. Use a fixed port if you need a strong guarantee |
+| `models[].ttl_seconds` | float \| null | `null` | [Unreleased] Per-model TTL override. `null` (default) = follow the global `launcher.swap.ttl_seconds`. `0` means the same thing as the global field's `0` (unload as soon as the last lease releases), scoped to just this model |
 | `models[].option_profile` | str \| null | `null` | Name of an existing preset in `launcher.option_profiles[backend]`. A name that doesn't exist is a config-load error |
 | `models[].num_ctx` | int | `8192` (≥256) | Baseline used for KV estimation / launch parameters |
 | `models[].extra_args` | str | `""` | One-off extra CLI flags (a single string, parsed with `shlex`; re-specifying the model/draft model is rejected) |

{coderouter_cli-2.9.2 → coderouter_cli-2.9.3}/docs/backends/launcher.md

@@ -276,14 +276,16 @@ Ollama など常用の backend と併用する、より実運用寄りの設定
 | フィールド | 型 | 既定値 | 説明 |
 |---|---|---|---|
 | `enabled` | bool | `false` | オンデマンドスワップを有効化。`false` ならこれまで通り手動起動のみ(既存デプロイに影響なし) |
-| `ttl_seconds` | float \| null | `1800.0` | 進行中リクエストが無い状態がこの秒数続くとプロセスを自動停止。`null` = 無効(明示停止まで起動し続ける)、`0` = 最後のリクエスト完了で即アンロード。Phase 1 はグローバル1値のみ(モデル毎の上書きは未対応) |
+| `ttl_seconds` | float \| null | `1800.0` | 進行中リクエストが無い状態がこの秒数続くとプロセスを自動停止。`null` = 無効(明示停止まで起動し続ける)、`0` = 最後のリクエスト完了で即アンロード。全モデル共通のグローバル既定値 — `models[].ttl_seconds` で個別上書き可能([Unreleased]) |
 | `readiness_timeout_s` | float | `120.0`(1〜1800) | オンデマンド起動したモデルの準備完了を**リクエスト側が待つ**上限秒数。超えると dispatch フックが retryable な `AdapterError` を送出する。**下記の `launcher.readiness_timeout_s`(既定 300s)とは別物** — こちらは「1リクエストが待つ上限」、あちらは「プロセスの readiness 監視全般の上限」 |
 | `sweep_interval_s` | float | `15.0`(1〜600) | TTL 監視(sweeper)がアイドルプロセスを走査する間隔 |
+| `port_retry_attempts` | int | `2`(0〜5) | [Unreleased] `models[].port` が未指定のカタログエントリに対する、起動失敗時の追加リトライ回数(毎回新しいエフェメラルポートを取り直す)。`0` ならリトライなし。固定ポート指定時は無関係(常に1回のみ)。TOCTOU窓自体は解消しない — 詳細は `models[].port` の説明を参照 |
 | `inject_auto_router_rules` | bool | `true` | カタログの各モデル名ごとに `auto_router` ルール(`id: swap:<name>`、`model_pattern` は名前の完全一致)を自動生成するか。`false` にした場合は `X-CodeRouter-Profile` ヘッダ等で自分でルーティングを配線する |
 | `models[].name` | str(必須) | — | リクエストの `model` フィールドと照合される論理名。provider 名・専用プロファイル名は自動的に `launcher-swap-<name>` になる |
 | `models[].backend` | `"llama.cpp" \| "vllm" \| "mlx"`(必須) | — | 手動 Launcher UI と同じバックエンド種別 |
 | `models[].model_path` | str(必須) | — | モデルファイルの絶対または `~` 相対パス。**必ず `launcher.model_dirs` の配下**である必要があり、設定ロード時と起動時の2回検証される(パストラバーサル対策) |
-| `models[].port` | int \| null | `null` | 固定ポート推奨。省略時は OS 割当のエフェメラルポートを使い、起動失敗時に別ポートで1回だけリトライする(best-effort、強い TOCTOU 保証はない) |
+| `models[].port` | int \| null | `null` | 固定ポート推奨。省略時は OS 割当のエフェメラルポートを使い、起動失敗時に `launcher.swap.port_retry_attempts` 回まで(既定2回)別ポートでリトライする。best-effort — pick してから子プロセスが実際に bind するまでの間隙(TOCTOU)は解消されない。強い保証が要る場合は固定ポートを使うこと |
+| `models[].ttl_seconds` | float \| null | `null` | [Unreleased] このモデルだけの TTL 上書き。`null`(既定) = グローバルの `launcher.swap.ttl_seconds` に従う。`0` を指定するとグローバルの `0` と同じ意味(最後のリース解放で即アンロード)がこのモデルにだけ適用される |
 | `models[].option_profile` | str \| null | `null` | `launcher.option_profiles[backend]` の既存プリセット名。存在しない名前を指定すると設定ロード時にエラーになる |
 | `models[].num_ctx` | int | `8192`(≥256) | KV 見積り・起動パラメータの基準値 |
 | `models[].extra_args` | str | `""` | 追加 CLI フラグ(1本の文字列。`shlex` でパース。モデル/draft モデルの再指定は不可) |

{coderouter_cli-2.9.2 → coderouter_cli-2.9.3}/docs/designs/orchestration-companion.md

@@ -1,7 +1,8 @@
 # オーケストレーション・コンパニオン設計書（Ecosystem 層、構想）
 
+> 編集注記（2026-07-12）: リンク整理。`future.md` は現リポジトリに非収録のため、リンクは注記化または現存ドキュメントへの付け替え済み（記述内容自体は変更していない）。
 > ステータス: **構想（Concept）**。実装前。Core/Plugin の変更は伴わない。
-> 正典: [`docs/inside/future.md`](../inside/future.md) §5（2026-06-27 追記）・§1.2（三層モデル）・§2.5（2026-07-11 追記）
+> 正典: `future.md`（当時の内部設計メモ。現リポジトリには未収録）§5（2026-06-27 追記）・§1.2（三層モデル）・§2.5（2026-07-11 追記）。§1.2 の判定基準に相当する記述は [`agent-cli-plugin-extraction.md`](./agent-cli-plugin-extraction.md) §1.3、§2.5 のopusplan構成例・既知の制限(G1/G6)に相当する記述は [`subagent-routing.md`](../guides/subagent-routing.md) §5(a)・§7 に移設されている。
 > 前提: agent_cli Phase 1 完結（v2.7.10、[`external-agents-adapter.md`](./external-agents-adapter.md)）
 > 作成: 2026-07-11 / 出典: 作者方向性指示 `_article/direction-brief-2026-07-11.md`・解析書 `_article/analysis-direction-2026-07.md` D-補足
 
@@ -60,7 +61,7 @@ Voice Bridge と同型で、CodeRouter Plugin SDK は使わない。future.md §
 [推論バックエンド] — agent_cli(claude opus 等) / ローカル / クラウド混在
 ```
 
-`providers.yaml` 側の構成例は future.md §2.5「opusplan 型構成例」を参照（本書では重複させない）。
+`providers.yaml` 側の構成例は [`subagent-routing.md`](../guides/subagent-routing.md) §5(a)「opusplan 型」を参照（本書では重複させない。旧 future.md §2.5「opusplan 型構成例」に相当する記述。future.md は当時の内部設計メモで、現リポジトリには未収録）。
 
 ---
 
@@ -71,10 +72,10 @@ Voice Bridge と同型で、CodeRouter Plugin SDK は使わない。future.md §
 - 役割別 profile 解決、agent_cli backend、fallback、L1〜L6 guards、plugin-memory/compress の透過適用は**すべて既存資産で足りる**。追加実装は不要（future.md §2.5 (1) 確信度 HIGH）。
 - `X-CodeRouter-Profile` ヘッダの precedence 機構は v1.6 以降既存。
 
-**G1/G3（future.md §2.5 (4) のギャップ表）が欲しくなる条件**:
+**G1/G3（当時の内部設計メモ future.md §2.5 (4) のギャップ表より。現リポジトリには未収録。G1 は現存記述として [`subagent-routing.md`](../guides/subagent-routing.md) §7 に対応項目あり）が欲しくなる条件**:
 
-- G1（複合条件マッチャ）: orchestrator が profile ヘッダを明示付与している限り不要。**auto_router の保険ルールを複雑化させたい場合のみ**（例: 「コード密度が高く *かつ* ツール宣言あり」を 1 ルールで表現したい）に欲しくなる。orchestrator 側が常にヘッダを付ける設計なら発生しない。
-- G3（ヘッダ/ツール名ベースのルール条件）: 同上。orchestrator が特定 MCP ツール名に応じて動的に profile を切り替えたい場合に初めて必要になる。
+- G1（複合条件マッチャ）: orchestrator が profile ヘッダを明示付与している限り不要。**auto_router の保険ルールを複雑化させたい場合のみ**（例: 「コード密度が高く *かつ* ツール宣言あり」を 1 ルールで表現したい）に欲しくなる。orchestrator 側が常にヘッダを付ける設計なら発生しない（cf. [`subagent-routing.md`](../guides/subagent-routing.md) §7 の G1 記述）。
+- G3（ヘッダ/ツール名ベースのルール条件）: 同上。orchestrator が特定 MCP ツール名に応じて動的に profile を切り替えたい場合に初めて必要になる（future.md 由来。現リポジトリには対応する記述なし）。
 
 **明確に CodeRouter 側に要求しないもの**: 段階判定（今が Plan か実行かの意味的分類、G2）・深度連動 routing（G4）・並列 fan-out（G5）はすべて orchestrator 側の責務であり、wire 層に持ち込まない。
 
@@ -104,6 +105,6 @@ Voice Bridge と同型で、CodeRouter Plugin SDK は使わない。future.md §
 
 ## 関連ドキュメント
 
-- [`docs/inside/future.md`](../inside/future.md) §5・§1.2・§2.5 — 正典
+- `future.md` §5・§1.2・§2.5 — 正典（当時の内部設計メモ future.md より。現リポジトリには未収録）。§1.2 相当は [`docs/designs/agent-cli-plugin-extraction.md`](./agent-cli-plugin-extraction.md) §1.3、§2.5 の一部（opusplan構成例・G1/G6）相当は [`docs/guides/subagent-routing.md`](../guides/subagent-routing.md) §5(a)・§7 を参照
 - [`docs/designs/external-agents-adapter.md`](./external-agents-adapter.md) — agent_cli backend（本書が利用する CodeRouter 側の対応機能）
-- `_OUTPUTS/04-計画-方向性/multiagent/` — 実機プロトタイプ一式（orchestrator/safe-edit/ベンチ）
+- `_OUTPUTS/04-計画-方向性/multiagent/` — 実機プロトタイプ一式（orchestrator/safe-edit/ベンチ。当時の作業ディレクトリ参照。現リポジトリには未収録）

{coderouter_cli-2.9.2 → coderouter_cli-2.9.3}/pyproject.toml

@@ -11,7 +11,7 @@
 # in plan.md §11.B; once granted, this name will become an alias and
 # `coderouter` will become the canonical distribution name.
 name = "coderouter-cli"
-version = "2.9.2"
+version = "2.9.3"
 description = "Local-first, free-first, fallback-built-in LLM router. Claude Code / OpenAI compatible."
 readme = "README.md"
 requires-python = ">=3.12"