From 96897dc07036989226c163b1ad9a600eb2475164 Mon Sep 17 00:00:00 2001
From: Teknium <127238744+teknium1@users.noreply.github.com>
Date: Wed, 2 Sep 2026 23:55:00 -0700
Subject: [PATCH 1/3] =?UTF-8?q?refactor(hermes=5Fcli/web=5Frouters):=20loc?=
 =?UTF-8?q?al=5Fmodels=20=E2=80=94=20fold=20download-job/target/runtime-ta?=
 =?UTF-8?q?rget=20helpers,=20nvidia-smi=20+=20restart=20phase=20helpers?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 hermes_cli/web_routers/local_models.py | 601 ++++++++++++-------------
 1 file changed, 282 insertions(+), 319 deletions(-)

diff --git a/hermes_cli/web_routers/local_models.py b/hermes_cli/web_routers/local_models.py
index cb771e482a..111b874696 100644
--- a/hermes_cli/web_routers/local_models.py
+++ b/hermes_cli/web_routers/local_models.py
@@ -45,6 +45,11 @@ _JOBS: Dict[str, Dict[str, Any]] = {}
 _JOBS_LOCK = threading.Lock()
 _LLAMACPP_PROVIDERS = ("llamacpp", "llama.cpp", "llama-cpp")
 _SPLIT_PART_RE = r"-\d{5}-of-\d{5}"
+# One TCP stream to a CDN rarely fills a fast line; 8 ranged connections
+# writing into a preallocated file saturate consumer gigabit.
+_DOWNLOAD_CONNECTIONS = 8
+_CHUNK = 4 << 20
+_SERVER_START_FAILED = "The local server could not start — check the runtime is installed"
 
 
 def _human_gb(n: int | float) -> str:
@@ -64,6 +69,15 @@ def _http_error(status: int, prefix: str = ""):
         raise HTTPException(status_code=status, detail=f"{prefix}{exc}") from exc
 
 
+def _quiet(fn: Callable[[], Any], default: Any) -> Any:
+    """``fn()`` or ``default`` on any exception — for garnish that must never 500."""
+    try:
+        return fn()
+    except Exception:  # noqa: BLE001
+        return default
+
+
+# ── jobs ─────────────────────────────────────────────────────
 def _job(kind: str, target: str, model_id: str | None = None) -> Dict[str, Any]:
     job = {
         "job_id": uuid.uuid4().hex[:12], "kind": kind, "target": target,
@@ -94,13 +108,17 @@ def _finish(job: Dict[str, Any], detail: str) -> None:
     job["status"] = "done"
 
 
-def _spawn_job(job: Dict[str, Any], name: str, body: Callable[[], None], *,
-               fail_msg: str | None = None, on_exit: Callable[[], None] | None = None) -> None:
+def _spawn_job(job: Dict[str, Any], name: str, body: Callable[[], None], *, fail_msg: str | None = None,
+               on_exit: Callable[[], None] | None = None, download_label: str | None = None) -> None:
     """Run ``body`` on a daemon thread; an exception marks the job errored (warning
-    ``fail_msg`` when given). ``on_exit`` always runs last."""
+    ``fail_msg`` when given). ``on_exit`` always runs last. ``download_label`` makes it
+    a download job: it finishes as "<label> ready" and bounces the router to pick the file up."""
     def _run():
         try:
             body()
+            if download_label is not None:
+                _finish(job, f"{download_label} ready")
+                _refresh_runtime("post-download runtime refresh skipped")
         except Exception as exc:  # noqa: BLE001
             if fail_msg:
                 logger.warning(fail_msg, exc)
@@ -113,6 +131,7 @@ def _spawn_job(job: Dict[str, Any], name: str, body: Callable[[], None], *,
     threading.Thread(target=_run, daemon=True, name=name).start()
 
 
+# ── runtime / router plumbing ────────────────────────────────
 def _refresh_runtime(skip_msg: str) -> None:
     """Bounce a running router so it rescans the models dir (it only scans at spawn).
     Never raises — the file operation already succeeded."""
@@ -122,8 +141,7 @@ def _refresh_runtime(skip_msg: str) -> None:
         logger.debug(skip_msg, exc_info=True)
 
 
-def _router_request(endpoint: Dict[str, Any], path: str, *, timeout: float,
-                    payload: dict | None = None) -> Any:
+def _router_request(endpoint: Dict[str, Any], path: str, *, timeout: float, payload: dict | None = None) -> Any:
     """Call the local router (base_url minus ``/v1``) with its bearer key. GET (no
     payload) returns the parsed JSON body; POST returns None."""
     headers = {"Authorization": f"Bearer {endpoint.get('api_key', '')}"}
@@ -137,182 +155,6 @@ def _router_request(endpoint: Dict[str, Any], path: str, *, timeout: float,
         return None if payload is not None else json.loads(r.read())
 
 
-# ── fast download: ranged parallel streams ───────────────────
-
-# One TCP stream to a CDN rarely fills a fast line; 8 ranged connections
-# writing into a preallocated file saturate consumer gigabit.
-_DOWNLOAD_CONNECTIONS = 8
-_CHUNK = 4 << 20
-
-
-def _probe_range_support(url: str) -> int:
-    """Total size when the server honors Range requests, else 0. A 401/403 means a
-    gated repo or a wrong catalog repo — raise a plain-language message, not a bare status."""
-    req = urllib.request.Request(url, headers={"Range": "bytes=0-0"})
-    try:
-        with urllib.request.urlopen(req, timeout=60) as r:
-            if r.status == 206:
-                content_range = r.headers.get("Content-Range", "")
-                if "/" in content_range:
-                    return int(content_range.rsplit("/", 1)[1])
-    except urllib.error.HTTPError as exc:
-        if exc.code in (401, 403):
-            raise RuntimeError("The model host refused the download (gated or moved). "
-                               "This is a catalog problem, not yours — please report it.") from exc
-        raise
-    except Exception:  # noqa: BLE001
-        pass
-    return 0
-
-
-def _model_id_for(gguf: Path) -> str:
-    """Variant model id for a staged file (strips split-part suffixes)."""
-    return re.sub(_SPLIT_PART_RE + "$", "", gguf.stem)
-
-
-def _variant_files_on_disk(model_id: str) -> "list[Path]":
-    """Every local file belonging to a staged model: all split parts plus its
-    catalog-declared assets (mmproj/draft) when present."""
-    files = [p for p in _models_dir().glob("*.gguf") if _model_id_for(p) == model_id]
-    hit = catalog.find_entry_for_model(model_id)
-    if hit is not None:
-        for asset in (hit[0].mmproj, hit[0].draft):
-            if asset is not None and (bootstrap.assets_dir() / asset.local_name).exists():
-                files.append(bootstrap.assets_dir() / asset.local_name)
-    return files
-
-
-def download_file(url: str, dest: Path, job: Dict[str, Any], *,
-                  base_done: int = 0, keep_totals: bool = False) -> None:
-    """Download url -> dest with byte progress on ``job``; ranged-parallel when the
-    server supports it, single-stream otherwise. Never leaves a .part.
-
-    Completeness is checked only against what the SERVER declared (range-probe
-    total / Content-Length), never the CATALOG (its sizes may lag a re-upload), so
-    a dropped connection still errors instead of staging a truncated file.
-    Multi-file variants: ``base_done`` offsets progress onto earlier files and
-    ``keep_totals=True`` stops the per-file size from overwriting the variant's total.
-    """
-    tmp = dest.with_suffix(".part")
-    dest.parent.mkdir(parents=True, exist_ok=True)
-    file_done = [0]
-    progress_lock = threading.Lock()
-
-    def pump(r, f) -> None:
-        while True:
-            chunk = r.read(_CHUNK)
-            if not chunk:
-                break
-            f.write(chunk)
-            with progress_lock:
-                file_done[0] += len(chunk)
-                job["done_bytes"] = base_done + file_done[0]
-
-    try:
-        # The probe and the preallocation both take real seconds on a 20+ GB
-        # file — narrate them, or the pane shows a dead '— of X GB'.
-        job["detail"] = "Connecting"
-        total = _probe_range_support(url)
-        if total:
-            if not keep_totals:
-                job["total_bytes"] = total
-            # Preallocate so each worker writes at its own offset.
-            job["detail"] = f"Reserving {_human_gb(total)} of disk space"
-            with open(tmp, "wb") as f:
-                f.truncate(total)
-            job["detail"] = ""
-            errors: list[Exception] = []
-            n = _DOWNLOAD_CONNECTIONS
-
-            def fetch_range(start: int, end: int) -> None:
-                try:
-                    req = urllib.request.Request(url, headers={"Range": f"bytes={start}-{end}"})
-                    with urllib.request.urlopen(req, timeout=120) as r, open(tmp, "r+b") as f:
-                        f.seek(start)
-                        pump(r, f)
-                except Exception as exc:  # noqa: BLE001
-                    errors.append(exc)
-
-            threads = [threading.Thread(target=fetch_range, daemon=True, name=f"lm-dl-{i}",
-                                        args=(i * total // n, (i + 1) * total // n - 1))
-                       for i in range(n)]
-            for t in threads:
-                t.start()
-            for t in threads:
-                t.join()
-            if errors:
-                raise errors[0]
-            if file_done[0] != total:
-                raise RuntimeError(f"download incomplete ({file_done[0]} of {total} bytes)")
-        else:
-            # No range support: single stream. Completeness is judged by the
-            # server's own Content-Length when it sent one — never the catalog.
-            with urllib.request.urlopen(url, timeout=120) as r, open(tmp, "wb") as f:
-                length = int(r.headers.get("Content-Length") or 0)
-                if length and not keep_totals:
-                    job["total_bytes"] = length
-                pump(r, f)
-            if length and file_done[0] != length:
-                raise RuntimeError(f"Download ended at {file_done[0]:,} bytes but the server "
-                                   f"said {length:,} — connection dropped? Removed; try again")
-
-        shutil.move(str(tmp), str(dest))
-    except Exception:
-        tmp.unlink(missing_ok=True)
-        raise
-
-
-def _models_dir() -> Path:
-    return bootstrap.models_dir()
-
-
-def _hf_url(repo: str, path: str) -> str:
-    return f"https://huggingface.co/{repo}/resolve/main/{path}"
-
-
-def _download_plan(entry, variant) -> list:
-    """Everything a variant needs: split parts + mmproj/draft assets, as (url, dest, bytes) tuples."""
-    plan = [(_hf_url(entry.repo, a.path), _models_dir() / a.local_name, a.size_bytes) for a in variant.files]
-    plan += [(_hf_url(entry.repo, a.path), bootstrap.assets_dir() / a.local_name, a.size_bytes)
-             for a in (entry.mmproj, entry.draft) if a is not None]
-    return plan
-
-
-def _run_download_plan(job: Dict[str, Any], plan: list, label: str) -> None:
-    """Download every missing file in ``plan``; already-present files count toward progress without a transfer."""
-    total = sum(p[2] for p in plan)
-    _step(job, "downloading", f"{label} — {_human_gb(total)}")
-    done_before = 0
-    for url, dest, size in plan:
-        if not dest.exists():
-            download_file(url, dest, job, base_done=done_before, keep_totals=True)
-            job["phase"] = "downloading"
-        done_before += size
-        job["done_bytes"] = done_before
-
-
-def _engine_too_old(min_engine: str) -> bool:
-    """True when the installed llama.cpp predates a model's requirement. Tags are
-    release numbers (b10362); no engine installed compares as too old only when
-    the model states a requirement."""
-    if not min_engine:
-        return False
-    try:
-        tags = binaries.installed_tags() or [binaries.default_tag()]
-        newest = max(int(t.lstrip("b")) for t in tags if t.lstrip("b").isdigit())
-        return newest < int(min_engine.lstrip("b"))
-    except Exception:  # noqa: BLE001
-        return False
-
-
-def _quiet(fn: Callable[[], Any], default: Any) -> Any:
-    """``fn()`` or ``default`` on any exception — for garnish that must never 500."""
-    try:
-        return fn()
-    except Exception:  # noqa: BLE001
-        return default
-
-
 def _load_config() -> dict:
     return _quiet(config_mod.load_config, {})
 
@@ -329,14 +171,15 @@ def _set_runtime_enabled(enabled: bool) -> dict:
     return config
 
 
-def _resolve_backend(section: dict, requested: str | None = None) -> str:
+def _runtime_target(requested: str | None = None) -> "tuple[str, str]":
+    """(tag, backend) the runtime routes act on: configured tag or release default;
+    ``auto`` backend resolved from the detected GPU vendor."""
+    section = _runtime_section()
+    tag = section.get("tag") or binaries.default_tag()
     backend = requested or section.get("backend", "auto")
-    return binaries.select_backend(bootstrap._detect_gpu_vendor()) if backend == "auto" else backend
-
-
-def _eligible_entries():
-    """Catalog entries this engine can activate today (engine-gated ones can't be the recommendation either)."""
-    return tuple(e for e in catalog.CATALOG if not _engine_too_old(e.min_engine))
+    if backend == "auto":
+        backend = binaries.select_backend(bootstrap._detect_gpu_vendor())
+    return tag, backend
 
 
 def _resolve_assets_or_400(tag: str, backend: str):
@@ -345,6 +188,22 @@ def _resolve_assets_or_400(tag: str, backend: str):
         return binaries.resolve_assets(tag, backend)
 
 
+def _engine_too_old(min_engine: str) -> bool:
+    """True when the installed llama.cpp predates a model's requirement. Tags are
+    release numbers (b10362); no engine installed compares as too old only when
+    the model states a requirement."""
+    def newest_installed() -> int:
+        tags = binaries.installed_tags() or [binaries.default_tag()]
+        return max(int(t.lstrip("b")) for t in tags if t.lstrip("b").isdigit())
+
+    return bool(min_engine) and _quiet(lambda: newest_installed() < int(min_engine.lstrip("b")), False)
+
+
+def _eligible_entries():
+    """Catalog entries this engine can activate today (engine-gated ones can't be the recommendation either)."""
+    return tuple(e for e in catalog.CATALOG if not _engine_too_old(e.min_engine))
+
+
 def _start_local_server(config: dict, fail_detail: str):
     """Start the local server (force) and return the supervisor; raise ``fail_detail``
     when neither we nor another process ended up serving."""
@@ -354,8 +213,7 @@ def _start_local_server(config: dict, fail_detail: str):
     return sup
 
 
-def _ensure_server(job: Dict[str, Any], config: dict, model_id: str, *,
-                   fail_detail: str, skip_msg: str) -> None:
+def _ensure_server(job: Dict[str, Any], config: dict, model_id: str, *, fail_detail: str, skip_msg: str) -> None:
     """Start the local server if needed and self-heal a stale router: the model
     list is spawn-only, so a server started before ``model_id`` finished
     downloading can't serve it — bounce it when it doesn't know the model."""
@@ -377,14 +235,149 @@ def _assign_default(job: Dict[str, Any], model_id: str) -> None:
     web_deps.late("_apply_model_assignment_sync")("main", "llamacpp", model_id, "", "", "")
 
 
+# ── downloads: ranged parallel streams ───────────────────────
+def _hf_url(repo: str, path: str) -> str:
+    return f"https://huggingface.co/{repo}/resolve/main/{path}"
+
+
+def _model_id_for(gguf: Path) -> str:
+    """Variant model id for a staged file (strips split-part suffixes)."""
+    return re.sub(_SPLIT_PART_RE + "$", "", gguf.stem)
+
+
+def _variant_files_on_disk(model_id: str) -> "list[Path]":
+    """Every local file belonging to a staged model: all split parts plus its
+    catalog-declared assets (mmproj/draft) when present."""
+    files = [p for p in bootstrap.models_dir().glob("*.gguf") if _model_id_for(p) == model_id]
+    hit = catalog.find_entry_for_model(model_id)
+    assets = (hit[0].mmproj, hit[0].draft) if hit is not None else ()
+    files += [bootstrap.assets_dir() / a.local_name for a in assets
+              if a is not None and (bootstrap.assets_dir() / a.local_name).exists()]
+    return files
+
+
+def _probe_range_support(url: str) -> int:
+    """Total size when the server honors Range requests, else 0. A 401/403 means a
+    gated repo or a wrong catalog repo — raise a plain-language message, not a bare status."""
+    req = urllib.request.Request(url, headers={"Range": "bytes=0-0"})
+    try:
+        with urllib.request.urlopen(req, timeout=60) as r:
+            content_range = r.headers.get("Content-Range", "") if r.status == 206 else ""
+            if "/" in content_range:
+                return int(content_range.rsplit("/", 1)[1])
+    except urllib.error.HTTPError as exc:
+        if exc.code in (401, 403):
+            raise RuntimeError("The model host refused the download (gated or moved). "
+                               "This is a catalog problem, not yours — please report it.") from exc
+        raise
+    except Exception:  # noqa: BLE001
+        pass
+    return 0
+
+
+def download_file(url: str, dest: Path, job: Dict[str, Any], *, base_done: int = 0, keep_totals: bool = False) -> None:
+    """Download url -> dest with byte progress on ``job``; ranged-parallel when the
+    server supports it, single-stream otherwise. Never leaves a .part.
+
+    Completeness is checked only against what the SERVER declared (range-probe
+    total / Content-Length), never the CATALOG (its sizes may lag a re-upload), so
+    a dropped connection still errors instead of staging a truncated file.
+    Multi-file variants: ``base_done`` offsets progress onto earlier files and
+    ``keep_totals=True`` stops the per-file size from overwriting the variant's total.
+    """
+    tmp = dest.with_suffix(".part")
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    file_done = [0]
+    progress_lock = threading.Lock()
+    errors: list[Exception] = []
+
+    def pump(r, f) -> None:
+        while True:
+            chunk = r.read(_CHUNK)
+            if not chunk:
+                break
+            f.write(chunk)
+            with progress_lock:
+                file_done[0] += len(chunk)
+                job["done_bytes"] = base_done + file_done[0]
+
+    def fetch_range(start: int, end: int) -> None:
+        try:
+            req = urllib.request.Request(url, headers={"Range": f"bytes={start}-{end}"})
+            with urllib.request.urlopen(req, timeout=120) as r, open(tmp, "r+b") as f:
+                f.seek(start)
+                pump(r, f)
+        except Exception as exc:  # noqa: BLE001
+            errors.append(exc)
+
+    try:
+        # The probe and the preallocation both take real seconds on a 20+ GB
+        # file — narrate them, or the pane shows a dead '— of X GB'.
+        job["detail"] = "Connecting"
+        total = _probe_range_support(url)
+        if total:
+            if not keep_totals:
+                job["total_bytes"] = total
+            # Preallocate so each worker writes at its own offset.
+            job["detail"] = f"Reserving {_human_gb(total)} of disk space"
+            with open(tmp, "wb") as f:
+                f.truncate(total)
+            job["detail"] = ""
+            n = _DOWNLOAD_CONNECTIONS
+            threads = [threading.Thread(target=fetch_range, daemon=True, name=f"lm-dl-{i}",
+                                        args=(i * total // n, (i + 1) * total // n - 1)) for i in range(n)]
+            for t in threads:
+                t.start()
+            for t in threads:
+                t.join()
+            if errors:
+                raise errors[0]
+            if file_done[0] != total:
+                raise RuntimeError(f"download incomplete ({file_done[0]} of {total} bytes)")
+        else:
+            # No range support: single stream; completeness judged by the server's
+            # own Content-Length when it sent one — never the catalog.
+            with urllib.request.urlopen(url, timeout=120) as r, open(tmp, "wb") as f:
+                length = int(r.headers.get("Content-Length") or 0)
+                if length and not keep_totals:
+                    job["total_bytes"] = length
+                pump(r, f)
+            if length and file_done[0] != length:
+                raise RuntimeError(f"Download ended at {file_done[0]:,} bytes but the server "
+                                   f"said {length:,} — connection dropped? Removed; try again")
+        shutil.move(str(tmp), str(dest))
+    except Exception:
+        tmp.unlink(missing_ok=True)
+        raise
+
+
+def _download_plan(entry, variant) -> list:
+    """Everything a variant needs: split parts + mmproj/draft assets, as (url, dest, bytes) tuples."""
+    plan = [(_hf_url(entry.repo, a.path), bootstrap.models_dir() / a.local_name, a.size_bytes) for a in variant.files]
+    plan += [(_hf_url(entry.repo, a.path), bootstrap.assets_dir() / a.local_name, a.size_bytes)
+             for a in (entry.mmproj, entry.draft) if a is not None]
+    return plan
+
+
+def _run_download_plan(job: Dict[str, Any], plan: list, label: str) -> None:
+    """Download every missing file in ``plan``; already-present files count toward progress without a transfer."""
+    _step(job, "downloading", f"{label} — {_human_gb(sum(p[2] for p in plan))}")
+    done_before = 0
+    for url, dest, size in plan:
+        if not dest.exists():
+            download_file(url, dest, job, base_done=done_before, keep_totals=True)
+            job["phase"] = "downloading"
+        done_before += size
+        job["done_bytes"] = done_before
+
+
 # ── status: the one call the pane opens with ─────────────────
 def _loaded_models(running: Dict[str, Any]) -> "tuple[Dict[str, str], Dict[str, Any]]":
     """Resident models right now, plus how each is placed (granted window from the
     child, spill facts from the preset decision) — the difference between 'fast'
-    and 'why is my CPU busy', so it must be inspectable."""
+    and 'why is my CPU busy', so it must be inspectable. 'loading' is its own state
+    (a 20-GB load in flight is the most important thing the pane can show)."""
     data = _router_request(running, "/models", timeout=3)
-    # Everything resident or becoming resident: 'loading' renders as its own state
-    # in the pane (a 20-GB load in flight is the most important thing it can show).
     loaded = {m["id"]: m.get("status", {}).get("value", "unknown") for m in data.get("data", [])
               if m.get("status", {}).get("value") in ("loaded", "ready", "loading")}
     placement: Dict[str, Any] = {}
@@ -394,14 +387,11 @@ def _loaded_models(running: Dict[str, Any]) -> "tuple[Dict[str, str], Dict[str,
         plan = decisions.get(model_id)
         if plan is not None:
             facts.update(window=plan.window, window_label=_k_label(plan.window), spilled=plan.spilled)
-        if state in ("loaded", "ready"):
-            try:
-                props = _router_request(running, f"/props?model={model_id}", timeout=3)
-                n_ctx = props.get("default_generation_settings", {}).get("n_ctx")
-                if n_ctx:
-                    facts.update(granted_window=int(n_ctx), granted_window_label=_k_label(int(n_ctx)))
-            except Exception:  # noqa: BLE001
-                pass
+        n_ctx = state in ("loaded", "ready") and _quiet(
+            lambda: _router_request(running, f"/props?model={model_id}", timeout=3)
+            .get("default_generation_settings", {}).get("n_ctx"), None)
+        if n_ctx:
+            facts.update(granted_window=int(n_ctx), granted_window_label=_k_label(int(n_ctx)))
         if facts:
             placement[model_id] = facts
     return loaded, placement
@@ -429,13 +419,13 @@ def _staged_row(gguf: Path) -> Dict[str, Any]:
 def _active_llamacpp_model_id() -> str | None:
     """The active main model when it is one of ours (config authority: the same
     model.provider + model.default that /api/model/set writes)."""
-    try:
+    def read() -> str | None:
         model_section = (_load_config() or {}).get("model") or {}
         if str(model_section.get("provider", "")).strip().lower() in _LLAMACPP_PROVIDERS:
             return str(model_section.get("default") or model_section.get("name") or "").strip() or None
-    except Exception:  # noqa: BLE001
-        pass
-    return None
+        return None
+
+    return _quiet(read, None)
 
 
 @router.get("/api/local-models/status")
@@ -446,15 +436,13 @@ def local_models_status():
     section = _runtime_section()
     configured_tag = section.get("tag") or binaries.default_tag()
     have = binaries.installed_tags()
-
     # The tag actually serving (boot ladder: configured if installed, else newest installed).
     tag = configured_tag if configured_tag in have else (have[0] if have else configured_tag)
     # Update pending = engine in use (enabled + something installed) and the configured
     # tag (pinned or release default) isn't on disk. The download is a button click, never automatic.
     update_available = bool(section.get("enabled") and have and configured_tag not in have)
     runtime_backend = _installed_backend(tag)
-    mdir = _models_dir()
-    staged = [_staged_row(gguf) for gguf in bootstrap.staged_models()] if mdir.exists() else []
+    mdir = bootstrap.models_dir()
     running = _state_endpoint()
 
     # Resident models from the live router ({} when down): Loaded pills + eject.
@@ -477,11 +465,28 @@ def local_models_status():
         # Live load progress per model (SSE-fed): {model_id: {stage, value, percent}}.
         # The chat's loading bar and the picker rows poll this; garnish, never a 500.
         "loading": _quiet(load_progress.get_loading_progress, {}),
-        "placement": placement, "models": staged, "models_dir": str(mdir),
+        "placement": placement,
+        "models": [_staged_row(gguf) for gguf in bootstrap.staged_models()] if mdir.exists() else [],
+        "models_dir": str(mdir),
     }
 
 
 # ── hardware: what this machine can do ───────────────────────
+def _nvidia_smi_facts() -> dict:
+    """GPU identity + live utilization (NVIDIA only; other vendors degrade to {} and
+    the UI hides those readouts)."""
+    smi_exe = hardware._nvidia_smi_path()
+    if not smi_exe:
+        return {}
+    smi = subprocess.run(
+        [smi_exe, "--query-gpu=name,utilization.gpu,memory.used", "--format=csv,noheader,nounits"],
+        capture_output=True, text=True, timeout=5)
+    if smi.returncode != 0 or not smi.stdout.strip():
+        return {}
+    name, util, used_mib = (x.strip() for x in smi.stdout.strip().splitlines()[0].split(","))
+    return dict(gpu_name=name, gpu_util_percent=int(util), vram_used_bytes=int(used_mib) << 20)
+
+
 @router.get("/api/local-models/hardware")
 def local_models_hardware():
     """The budget as plain facts, polled by the pane and statusbar. Sync def on
@@ -493,22 +498,11 @@ def local_models_hardware():
         "ram_total_bytes": ram_total, "ram_available_bytes": ram_avail, "vram_label": _human_gb(budget.total_device_bytes),
         "gpu_name": None, "gpu_util_percent": None, "vram_used_bytes": None,
     }
-    # GPU identity + live utilization (NVIDIA; other vendors degrade to None and the UI hides those readouts).
-    try:
-        smi_exe = hardware._nvidia_smi_path()
-        smi = subprocess.run(
-            [smi_exe, "--query-gpu=name,utilization.gpu,memory.used", "--format=csv,noheader,nounits"],
-            capture_output=True, text=True, timeout=5) if smi_exe else None
-        if smi and smi.returncode == 0 and smi.stdout.strip():
-            name, util, used_mib = (x.strip() for x in smi.stdout.strip().splitlines()[0].split(","))
-            out.update(gpu_name=name, gpu_util_percent=int(util), vram_used_bytes=int(used_mib) << 20)
-    except Exception:  # noqa: BLE001
-        pass
+    out.update(_quiet(_nvidia_smi_facts, {}))
     return out
 
 
 # ── catalog: priced for THIS machine before download ─────────
-
 _QUANT_REASONS = {
     "best-large-window": ("Recommended build ({quant}) — the quant class this engine is optimized for; "
                           "runs fully on your GPU with a large context window"),
@@ -569,9 +563,7 @@ def _catalog_row(entry, budget, recommended, recommended_reason, staged_ids) ->
         shape = f"runs at its full {row['native_context_label']} context"
     else:
         shape = f"starts at {row['start_window_label']} and grows toward {row['native_context_label']} as you use it"
-    if decision.spilled:
-        shape += " (larger than your GPU memory — runs slower)"
-    row["fit_summary"] = shape
+    row["fit_summary"] = shape + (" (larger than your GPU memory — runs slower)" if decision.spilled else "")
     return row
 
 
@@ -590,13 +582,12 @@ def local_models_catalog():
     budget = hardware.probe_budget(planning=True)
     # The reason key ships with the row so the Recommended badge's tooltip is the
     # branch that actually fired, not a re-derivation that can drift.
-    picked = catalog.recommended_entry(budget, _eligible_entries())
-    recommended = picked[0].id if picked is not None else None
-    recommended_reason = picked[1] if picked is not None else None
+    recommended, recommended_reason = catalog.recommended_entry(budget, _eligible_entries()) or (None, None)
+    recommended_id = recommended.id if recommended is not None else None
     # Completeness-checked staging (split parts all present) — same answer the
     # picker and router see, so a mid-download model never reads as downloaded.
     staged_ids = set(bootstrap.staged_model_ids())
-    return {"models": [_catalog_row(e, budget, recommended, recommended_reason, staged_ids) for e in catalog.CATALOG]}
+    return {"models": [_catalog_row(e, budget, recommended_id, recommended_reason, staged_ids) for e in catalog.CATALOG]}
 
 
 # ── runtime install (job) ────────────────────────────────────
@@ -640,11 +631,25 @@ def _runtime_progress_hook(job: Dict[str, Any]):
     return hook
 
 
+def _restart_on_new_tag(job: Dict[str, Any], tag: str, previous: list) -> bool:
+    """Engine update path: a server already running on an older tag moves to the new
+    one now — the click was the consent. Fresh installs (no server) skip this;
+    Use/boot handles their start. Failure is logged only: the new build is
+    installed either way and the next boot serves it."""
+    try:
+        if bootstrap.get_supervisor() is not None and previous and tag not in previous:
+            _step(job, "restarting", "Switching the running server to the new build")
+            bootstrap.shutdown_local_runtime()
+            bootstrap.ensure_local_runtime(_load_config(), force=True)
+            return True
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("post-update restart skipped: %s", exc)
+    return False
+
+
 @router.post("/api/local-models/runtime/install")
 async def local_models_runtime_install(body: RuntimeInstallBody):
-    section = _runtime_section()
-    tag = section.get("tag") or binaries.default_tag()
-    backend = _resolve_backend(section, body.backend)
+    tag, backend = _runtime_target(body.backend)
     plan = _resolve_assets_or_400(tag, backend)
     job = _job("runtime-install", f"llama.cpp {tag} ({backend})")
 
@@ -652,28 +657,13 @@ async def local_models_runtime_install(body: RuntimeInstallBody):
         previous = binaries.installed_tags()
         _step(job, "downloading", f"Fetching {len(plan.assets)} package(s) for {backend}")
         binaries.ensure_runtime_installed(tag, backend, progress=_runtime_progress_hook(job))
-
-        # Engine update path: a server already running on an older tag moves to the
-        # new one now — the click was the consent. Fresh installs (no server) skip
-        # this; Use/boot handles their start.
-        restarted = False
-        try:
-            if bootstrap.get_supervisor() is not None and previous and tag not in previous:
-                _step(job, "restarting", "Switching the running server to the new build")
-                bootstrap.shutdown_local_runtime()
-                bootstrap.ensure_local_runtime(_load_config(), force=True)
-                restarted = True
-        except Exception as exc:  # noqa: BLE001
-            # The new build is installed either way; the next boot serves it.
-            logger.warning("post-update restart skipped: %s", exc)
-
+        restarted = _restart_on_new_tag(job, tag, previous)
         # N-1 retention, only after the new tag verified: keep it and the newest
         # previous build as the rollback pin target.
         try:
             binaries.prune_old_tags([tag] + [t for t in previous if t != tag][:1])
         except Exception as exc:  # noqa: BLE001
             logger.warning("runtime prune skipped: %s", exc)
-
         _finish(job, f"llama.cpp {tag} ready ({backend})" + (" — server restarted on the new build" if restarted else ""))
 
     _spawn_job(job, "lr-runtime-install", _run, fail_msg="runtime install failed: %s")
@@ -685,47 +675,36 @@ class ModelDownloadBody(BaseModel):
     model_id: str
 
 
-def _download_job(job: Dict[str, Any], body: Callable[[], None], name: str, label: str, fail_msg: str | None = None) -> None:
-    """Spawn a download job: ``body`` fetches, then the job finishes as "<label> ready"
-    and the router is bounced to pick the file up."""
-    def _run():
-        body()
-        _finish(job, f"{label} ready")
-        _refresh_runtime("post-download runtime refresh skipped")
-
-    _spawn_job(job, name, _run, fail_msg=fail_msg)
+def _download_target(model_id: str):
+    """(entry, variant) for a family id (this machine's selected variant — the same
+    planning budget as the catalog, so the user downloads exactly the build the row
+    advertised) or an exact variant model_id."""
+    entry = catalog.catalog_by_id().get(model_id)
+    if entry is None:
+        hit = catalog.find_entry_for_model(model_id)
+        if hit is None:
+            raise HTTPException(status_code=404, detail=f"unknown model {model_id}")
+        return hit
+    if _engine_too_old(entry.min_engine):
+        raise HTTPException(status_code=409, detail=(
+            f"{entry.display_name} needs llama.cpp {entry.min_engine} or newer — update the engine first"))
+    choice = catalog.select_variant(entry, hardware.probe_budget(planning=True))
+    if choice is None:
+        raise HTTPException(status_code=409, detail=f"no variant of {entry.id} fits this machine")
+    return entry, choice.variant
 
 
 @router.post("/api/local-models/download")
 async def local_models_download(body: ModelDownloadBody):
     """Accepts either a family id (downloads this machine's selected variant) or an exact variant model_id."""
-    entry = catalog.catalog_by_id().get(body.model_id)
-    variant = None
-    if entry is not None:
-        if _engine_too_old(entry.min_engine):
-            raise HTTPException(status_code=409, detail=(
-                f"{entry.display_name} needs llama.cpp {entry.min_engine} or newer — update the engine first"))
-        # Same planning budget as the catalog — the user downloads exactly
-        # the build the row advertised.
-        choice = catalog.select_variant(entry, hardware.probe_budget(planning=True))
-        if choice is None:
-            raise HTTPException(status_code=409, detail=f"no variant of {entry.id} fits this machine")
-        variant = choice.variant
-    else:
-        hit = catalog.find_entry_for_model(body.model_id)
-        if hit is not None:
-            entry, variant = hit
-    if entry is None or variant is None:
-        raise HTTPException(status_code=404, detail=f"unknown model {body.model_id}")
-
+    entry, variant = _download_target(body.model_id)
     if variant.model_id in bootstrap.staged_model_ids():
         return {"job_id": None, "already_downloaded": True, "model_id": variant.model_id}
-
     plan = _download_plan(entry, variant)
     job = _job("model-download", f"{entry.display_name} ({variant.quant})", model_id=entry.id)
     job["total_bytes"] = sum(p[2] for p in plan)
-    _download_job(job, lambda: _run_download_plan(job, plan, entry.display_name),
-                  "lr-model-download", entry.display_name, fail_msg="model download failed: %s")
+    _spawn_job(job, "lr-model-download", lambda: _run_download_plan(job, plan, entry.display_name),
+               fail_msg="model download failed: %s", download_label=entry.display_name)
     return {"job_id": job["job_id"], "model_id": variant.model_id}
 
 
@@ -745,7 +724,6 @@ async def local_models_delete(model_id: str):
         growth.clear_window_override(model_id)
     except Exception:  # noqa: BLE001
         logger.debug("window-override clear skipped", exc_info=True)
-
     threading.Thread(target=_refresh_runtime, args=("post-delete runtime refresh skipped",), daemon=True,
                      name="lr-post-delete").start()
     return {"ok": True}
@@ -772,8 +750,7 @@ def _quickstart_target(body: QuickstartBody, budget):
         candidates = [entry]
     else:
         picked = catalog.recommended_entry(budget, _eligible_entries())
-        best = picked[0] if picked is not None else None
-        candidates = ([best] if best is not None else []) + [e for e in catalog.CATALOG if best is None or e.id != best.id]
+        candidates = ([picked[0]] if picked else []) + [e for e in catalog.CATALOG if not picked or e.id != picked[0].id]
     for candidate in candidates:
         choice = catalog.select_variant(candidate, budget)
         if choice is not None and not _engine_too_old(candidate.min_engine):
@@ -791,21 +768,16 @@ async def local_models_quickstart(body: QuickstartBody):
     synchronously so the button can explain itself; everything slow runs in the
     job with phase/byte progress."""
     entry, variant = _quickstart_target(body, hardware.probe_budget(planning=True))
-
-    section = _runtime_section()
-    tag = section.get("tag") or binaries.default_tag()
-    backend = _resolve_backend(section)
+    tag, backend = _runtime_target()
     need_runtime = not binaries.installed_tags()
     if need_runtime:
         _resolve_assets_or_400(tag, backend)
-
     need_download = variant.model_id not in bootstrap.staged_model_ids()
     download_plan = _download_plan(entry, variant) if need_download else []
     download_bytes = sum(p[2] for p in download_plan)
 
     if not _QUICKSTART_LOCK.acquire(blocking=False):
         raise HTTPException(status_code=409, detail="Setup is already running")
-
     job = _job("quickstart", entry.display_name, model_id=entry.id)
     job["total_bytes"] = download_bytes or None
 
@@ -813,19 +785,16 @@ async def local_models_quickstart(body: QuickstartBody):
         if need_runtime:
             _step(job, "installing-runtime", "Installing the local engine")
             binaries.ensure_runtime_installed(tag, backend, progress=_runtime_progress_hook(job))
-
         if need_download:
             # The runtime leg repurposed the byte counters for its own stages —
             # reset them to the model plan before download.
             job["done_bytes"] = 0
             job["total_bytes"] = download_bytes
             _run_download_plan(job, download_plan, entry.display_name)
-
         # Activate: same sequence as /activate's job body.
-        _ensure_server(
-            job, _set_runtime_enabled(True), variant.model_id,
-            fail_detail="The local server could not start — open Local Models for details",
-            skip_msg="quickstart rescan check skipped")
+        _ensure_server(job, _set_runtime_enabled(True), variant.model_id,
+                       fail_detail="The local server could not start — open Local Models for details",
+                       skip_msg="quickstart rescan check skipped")
         _assign_default(job, variant.model_id)
         _finish(job, f"{entry.display_name} is ready — new chats use it")
 
@@ -839,27 +808,28 @@ class ServerActionBody(BaseModel):
     action: str                 # "stop" | "start"
 
 
+def _terminate_state_pid() -> None:
+    """Server owned by another process (or an orphan): terminate via the state
+    file's pid, then clear the state."""
+    import psutil  # type: ignore
+
+    state = json.loads(supervisor.state_path().read_text(encoding="utf-8"))
+    pid = int(state.get("pid") or 0)
+    if pid > 0 and psutil.pid_exists(pid):
+        psutil.Process(pid).terminate()
+    supervisor.state_path().unlink(missing_ok=True)
+
+
 def _stop_server() -> None:
     if bootstrap.get_supervisor() is not None:
         bootstrap.shutdown_local_runtime()
     elif _state_endpoint() is not None:
-        # Server owned by another process (or an orphan): best-effort terminate
-        # via the state file's pid, then clear the state.
-        try:
-            import psutil  # type: ignore
-
-            state = json.loads(supervisor.state_path().read_text(encoding="utf-8"))
-            pid = int(state.get("pid") or 0)
-            if pid > 0 and psutil.pid_exists(pid):
-                psutil.Process(pid).terminate()
-            supervisor.state_path().unlink(missing_ok=True)
-        except Exception:  # noqa: BLE001
-            pass
+        _quiet(_terminate_state_pid, None)  # best-effort
     _set_runtime_enabled(False)
 
 
 def _start_server() -> None:
-    _start_local_server(_set_runtime_enabled(True), "The local server could not start — check the runtime is installed")
+    _start_local_server(_set_runtime_enabled(True), _SERVER_START_FAILED)
 
 
 _SERVER_ACTIONS = {"stop": _stop_server, "start": _start_server}
@@ -893,7 +863,6 @@ def local_models_eject(body: ModelEjectBody):
         with _http_error(502):
             sup.unload_model(body.model_id)
         return {"ok": True}
-
     # Server owned by another process (or state-file only): drive the router
     # directly with the persisted endpoint.
     endpoint = _state_endpoint()
@@ -917,14 +886,11 @@ async def local_models_activate(body: ModelActivateBody):
     # Split variants stage under their first part — resolve like the other routes.
     if body.model_id not in bootstrap.staged_model_ids():
         raise HTTPException(status_code=404, detail=f"{body.model_id} is not downloaded")
-
     job = _job("model-activate", body.model_id, model_id=body.model_id)
 
     def _run():
-        _ensure_server(
-            job, config_mod.load_config(), body.model_id,
-            fail_detail="The local server could not start — check the runtime is installed",
-            skip_msg="activate rescan check skipped")
+        _ensure_server(job, config_mod.load_config(), body.model_id,
+                       fail_detail=_SERVER_START_FAILED, skip_msg="activate rescan check skipped")
         _step(job, "setting-default", "Making it your default")
         _set_runtime_enabled(True)
         _assign_default(job, body.model_id)
@@ -987,25 +953,22 @@ async def local_models_download_browsed(body: BrowsedDownloadBody):
     paths = [p for p in (body.paths or []) if p.lower().endswith(".gguf")]
     if not paths:
         raise HTTPException(status_code=422, detail="no .gguf files given")
-    first = paths[0].rsplit("/", 1)[-1]
-    model_id = re.sub(_SPLIT_PART_RE + r"\.gguf$", "", first, flags=re.IGNORECASE)
-    model_id = model_id[:-5] if model_id.lower().endswith(".gguf") else model_id
+    model_id = re.sub(rf"(?:{_SPLIT_PART_RE})?\.gguf$", "", paths[0].rsplit("/", 1)[-1], flags=re.IGNORECASE)
     if model_id in bootstrap.staged_model_ids():
         return {"job_id": None, "already_downloaded": True, "model_id": model_id}
-
     job = _job("model-download", f"{model_id} (from {body.repo})", model_id=model_id)
 
     def _fetch():
         job["phase"] = "downloading"
         for p in paths:
-            dest = _models_dir() / p.rsplit("/", 1)[-1]
+            dest = bootstrap.models_dir() / p.rsplit("/", 1)[-1]
             if dest.exists():
                 continue
             download_file(_hf_url(body.repo, urllib.parse.quote(p)), dest, job,
                           base_done=int(job.get("done_bytes") or 0), keep_totals=bool(job.get("total_bytes")))
             job["phase"] = "downloading"
 
-    _download_job(job, _fetch, "lm-download-browsed", model_id)
+    _spawn_job(job, "lm-download-browsed", _fetch, download_label=model_id)
     return {"job_id": job["job_id"], "model_id": model_id}
 
 
@@ -1021,7 +984,7 @@ async def local_models_sideload(body: SideloadBody):
     src = Path(body.path)
     if not src.is_file() or src.suffix.lower() != ".gguf":
         raise HTTPException(status_code=422, detail="Pick a .gguf model file")
-    dest = _models_dir() / src.name
+    dest = bootstrap.models_dir() / src.name
     if dest.exists():
         return {"ok": True, "model_id": dest.stem, "already_present": True}
     dest.parent.mkdir(parents=True, exist_ok=True)

From d55239274f8fbc03a115801c6e4d0d94f062cb08 Mon Sep 17 00:00:00 2001
From: Teknium <127238744+teknium1@users.noreply.github.com>
Date: Thu, 3 Sep 2026 00:03:45 -0700
Subject: [PATCH 2/3] =?UTF-8?q?refactor(hermes=5Fcli/web=5Frouters):=20loc?=
 =?UTF-8?q?al=5Fmodels=20=E2=80=94=20models=20grouped=20up=20top,=20=5Fent?=
 =?UTF-8?q?ry=5For=5F404,=20compact=20docstrings/comments=20(WHY=20kept)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 hermes_cli/web_routers/local_models.py | 342 +++++++++++--------------
 1 file changed, 143 insertions(+), 199 deletions(-)

diff --git a/hermes_cli/web_routers/local_models.py b/hermes_cli/web_routers/local_models.py
index 111b874696..3e98eb7872 100644
--- a/hermes_cli/web_routers/local_models.py
+++ b/hermes_cli/web_routers/local_models.py
@@ -40,20 +40,54 @@ logger = logging.getLogger(__name__)
 
 router = APIRouter()
 
-_GIB = 1 << 30
 _JOBS: Dict[str, Dict[str, Any]] = {}
 _JOBS_LOCK = threading.Lock()
+# One quickstart at a time: the job sequences installs, downloads, a server bounce and a config write — two
+# racing runs would interleave all four. Held for the job's lifetime, released in the worker.
+_QUICKSTART_LOCK = threading.Lock()
 _LLAMACPP_PROVIDERS = ("llamacpp", "llama.cpp", "llama-cpp")
 _SPLIT_PART_RE = r"-\d{5}-of-\d{5}"
-# One TCP stream to a CDN rarely fills a fast line; 8 ranged connections
-# writing into a preallocated file saturate consumer gigabit.
+# One TCP stream to a CDN rarely fills a fast line; 8 ranged connections into a preallocated file saturate gigabit.
 _DOWNLOAD_CONNECTIONS = 8
 _CHUNK = 4 << 20
 _SERVER_START_FAILED = "The local server could not start — check the runtime is installed"
 
 
+class RuntimeInstallBody(BaseModel):
+    backend: Optional[str] = None   # None/auto -> detect
+
+
+class ModelDownloadBody(BaseModel):
+    model_id: str
+
+
+class QuickstartBody(BaseModel):
+    model_id: str | None = None   # default: the catalog's recommended entry
+
+
+class ServerActionBody(BaseModel):
+    action: str                 # "stop" | "start"
+
+
+class ModelEjectBody(BaseModel):
+    model_id: str
+
+
+class ModelActivateBody(BaseModel):
+    model_id: str               # exact variant id (a staged .gguf stem)
+
+
+class BrowsedDownloadBody(BaseModel):
+    repo: str
+    paths: list[str]            # one GGUF, or every part of a split, in order
+
+
+class SideloadBody(BaseModel):
+    path: str                   # absolute path to a .gguf on this machine
+
+
 def _human_gb(n: int | float) -> str:
-    return f"{n / _GIB:.1f} GB"
+    return f"{n / (1 << 30):.1f} GB"
 
 
 def _k_label(tokens: int) -> str:
@@ -110,9 +144,9 @@ def _finish(job: Dict[str, Any], detail: str) -> None:
 
 def _spawn_job(job: Dict[str, Any], name: str, body: Callable[[], None], *, fail_msg: str | None = None,
                on_exit: Callable[[], None] | None = None, download_label: str | None = None) -> None:
-    """Run ``body`` on a daemon thread; an exception marks the job errored (warning
-    ``fail_msg`` when given). ``on_exit`` always runs last. ``download_label`` makes it
-    a download job: it finishes as "<label> ready" and bounces the router to pick the file up."""
+    """Run ``body`` on a daemon thread; an exception marks the job errored (warning ``fail_msg`` when
+    given); ``on_exit`` always runs last. ``download_label`` = download job: finishes as "<label> ready"
+    and bounces the router to pick the file up."""
     def _run():
         try:
             body()
@@ -142,8 +176,7 @@ def _refresh_runtime(skip_msg: str) -> None:
 
 
 def _router_request(endpoint: Dict[str, Any], path: str, *, timeout: float, payload: dict | None = None) -> Any:
-    """Call the local router (base_url minus ``/v1``) with its bearer key. GET (no
-    payload) returns the parsed JSON body; POST returns None."""
+    """Call the local router (base_url minus ``/v1``) with its bearer key; GET (no payload) -> parsed JSON, POST -> None."""
     headers = {"Authorization": f"Bearer {endpoint.get('api_key', '')}"}
     data = None
     if payload is not None:
@@ -172,8 +205,7 @@ def _set_runtime_enabled(enabled: bool) -> dict:
 
 
 def _runtime_target(requested: str | None = None) -> "tuple[str, str]":
-    """(tag, backend) the runtime routes act on: configured tag or release default;
-    ``auto`` backend resolved from the detected GPU vendor."""
+    """(tag, backend) the runtime routes act on: configured tag or release default; ``auto`` -> detected GPU vendor."""
     section = _runtime_section()
     tag = section.get("tag") or binaries.default_tag()
     backend = requested or section.get("backend", "auto")
@@ -189,9 +221,8 @@ def _resolve_assets_or_400(tag: str, backend: str):
 
 
 def _engine_too_old(min_engine: str) -> bool:
-    """True when the installed llama.cpp predates a model's requirement. Tags are
-    release numbers (b10362); no engine installed compares as too old only when
-    the model states a requirement."""
+    """True when the installed llama.cpp predates a model's requirement. Tags are release numbers (b10362);
+    no engine installed compares as too old only when the model states a requirement."""
     def newest_installed() -> int:
         tags = binaries.installed_tags() or [binaries.default_tag()]
         return max(int(t.lstrip("b")) for t in tags if t.lstrip("b").isdigit())
@@ -204,9 +235,15 @@ def _eligible_entries():
     return tuple(e for e in catalog.CATALOG if not _engine_too_old(e.min_engine))
 
 
+def _entry_or_404(model_id: str):
+    entry = catalog.catalog_by_id().get(model_id)
+    if entry is None:
+        raise HTTPException(status_code=404, detail=f"unknown model {model_id}")
+    return entry
+
+
 def _start_local_server(config: dict, fail_detail: str):
-    """Start the local server (force) and return the supervisor; raise ``fail_detail``
-    when neither we nor another process ended up serving."""
+    """Force-start the local server; raise ``fail_detail`` when neither we nor another process ended up serving."""
     sup = bootstrap.ensure_local_runtime(config, force=True)
     if sup is None and _state_endpoint() is None:
         raise RuntimeError(fail_detail)
@@ -214,9 +251,8 @@ def _start_local_server(config: dict, fail_detail: str):
 
 
 def _ensure_server(job: Dict[str, Any], config: dict, model_id: str, *, fail_detail: str, skip_msg: str) -> None:
-    """Start the local server if needed and self-heal a stale router: the model
-    list is spawn-only, so a server started before ``model_id`` finished
-    downloading can't serve it — bounce it when it doesn't know the model."""
+    """Start the local server if needed and self-heal a stale router: the model list is spawn-only, so a
+    server started before ``model_id`` finished downloading can't serve it — bounce it when it doesn't know it."""
     _step(job, "starting-server", "Starting the local server")
     sup = _start_local_server(config, fail_detail)
     if sup is not None:
@@ -229,8 +265,7 @@ def _ensure_server(job: Dict[str, Any], config: dict, model_id: str, *, fail_det
 
 
 def _assign_default(job: Dict[str, Any], model_id: str) -> None:
-    """Make ``model_id`` the main model through the same machinery as /api/model/set
-    (late-bound so tests can stub web_deps.late)."""
+    """Make ``model_id`` the main model via the same machinery as /api/model/set (late-bound: tests stub web_deps.late)."""
     _step(job, "setting-default", "Making it your default")
     web_deps.late("_apply_model_assignment_sync")("main", "llamacpp", model_id, "", "", "")
 
@@ -246,8 +281,7 @@ def _model_id_for(gguf: Path) -> str:
 
 
 def _variant_files_on_disk(model_id: str) -> "list[Path]":
-    """Every local file belonging to a staged model: all split parts plus its
-    catalog-declared assets (mmproj/draft) when present."""
+    """Every local file of a staged model: all split parts plus catalog-declared assets (mmproj/draft) when present."""
     files = [p for p in bootstrap.models_dir().glob("*.gguf") if _model_id_for(p) == model_id]
     hit = catalog.find_entry_for_model(model_id)
     assets = (hit[0].mmproj, hit[0].draft) if hit is not None else ()
@@ -257,8 +291,8 @@ def _variant_files_on_disk(model_id: str) -> "list[Path]":
 
 
 def _probe_range_support(url: str) -> int:
-    """Total size when the server honors Range requests, else 0. A 401/403 means a
-    gated repo or a wrong catalog repo — raise a plain-language message, not a bare status."""
+    """Total size when the server honors Range requests, else 0. 401/403 = gated repo or wrong catalog
+    repo — raise a plain-language message, not a bare status."""
     req = urllib.request.Request(url, headers={"Range": "bytes=0-0"})
     try:
         with urllib.request.urlopen(req, timeout=60) as r:
@@ -276,15 +310,12 @@ def _probe_range_support(url: str) -> int:
 
 
 def download_file(url: str, dest: Path, job: Dict[str, Any], *, base_done: int = 0, keep_totals: bool = False) -> None:
-    """Download url -> dest with byte progress on ``job``; ranged-parallel when the
-    server supports it, single-stream otherwise. Never leaves a .part.
-
-    Completeness is checked only against what the SERVER declared (range-probe
-    total / Content-Length), never the CATALOG (its sizes may lag a re-upload), so
-    a dropped connection still errors instead of staging a truncated file.
-    Multi-file variants: ``base_done`` offsets progress onto earlier files and
-    ``keep_totals=True`` stops the per-file size from overwriting the variant's total.
-    """
+    """Download url -> dest with byte progress on ``job``; ranged-parallel when the server supports it,
+    single-stream otherwise. Never leaves a .part. Completeness is checked only against what the SERVER
+    declared (range-probe total / Content-Length), never the CATALOG (its sizes may lag a re-upload), so a
+    dropped connection still errors instead of staging a truncated file. Multi-file variants: ``base_done``
+    offsets progress onto earlier files; ``keep_totals=True`` keeps the per-file size from overwriting the
+    variant's total."""
     tmp = dest.with_suffix(".part")
     dest.parent.mkdir(parents=True, exist_ok=True)
     file_done = [0]
@@ -292,10 +323,7 @@ def download_file(url: str, dest: Path, job: Dict[str, Any], *, base_done: int =
     errors: list[Exception] = []
 
     def pump(r, f) -> None:
-        while True:
-            chunk = r.read(_CHUNK)
-            if not chunk:
-                break
+        for chunk in iter(lambda: r.read(_CHUNK), b""):
             f.write(chunk)
             with progress_lock:
                 file_done[0] += len(chunk)
@@ -311,8 +339,7 @@ def download_file(url: str, dest: Path, job: Dict[str, Any], *, base_done: int =
             errors.append(exc)
 
     try:
-        # The probe and the preallocation both take real seconds on a 20+ GB
-        # file — narrate them, or the pane shows a dead '— of X GB'.
+        # Probe and preallocation take real seconds on a 20+ GB file — narrate them, or the pane shows a dead '— of X GB'.
         job["detail"] = "Connecting"
         total = _probe_range_support(url)
         if total:
@@ -373,10 +400,9 @@ def _run_download_plan(job: Dict[str, Any], plan: list, label: str) -> None:
 
 # ── status: the one call the pane opens with ─────────────────
 def _loaded_models(running: Dict[str, Any]) -> "tuple[Dict[str, str], Dict[str, Any]]":
-    """Resident models right now, plus how each is placed (granted window from the
-    child, spill facts from the preset decision) — the difference between 'fast'
-    and 'why is my CPU busy', so it must be inspectable. 'loading' is its own state
-    (a 20-GB load in flight is the most important thing the pane can show)."""
+    """Resident models right now, plus how each is placed (granted window from the child, spill facts from
+    the preset decision) — the difference between 'fast' and 'why is my CPU busy', so it must be inspectable.
+    'loading' is its own state (a 20-GB load in flight is the most important thing the pane can show)."""
     data = _router_request(running, "/models", timeout=3)
     loaded = {m["id"]: m.get("status", {}).get("value", "unknown") for m in data.get("data", [])
               if m.get("status", {}).get("value") in ("loaded", "ready", "loading")}
@@ -400,12 +426,8 @@ def _loaded_models(running: Dict[str, Any]) -> "tuple[Dict[str, str], Dict[str,
 def _installed_backend(tag: str) -> str | None:
     """Name of the first backend dir under ``tag`` with a working server binary."""
     root = binaries.runtimes_root() / tag
-    if not root.exists():
-        return None
-    for backend_dir in sorted(p for p in root.iterdir() if p.is_dir()):
-        if _quiet(lambda: binaries.server_binary(backend_dir), None) is not None:
-            return backend_dir.name
-    return None
+    dirs = sorted(p for p in root.iterdir() if p.is_dir()) if root.exists() else []
+    return next((d.name for d in dirs if _quiet(lambda: binaries.server_binary(d), None) is not None), None)
 
 
 def _staged_row(gguf: Path) -> Dict[str, Any]:
@@ -417,8 +439,8 @@ def _staged_row(gguf: Path) -> Dict[str, Any]:
 
 
 def _active_llamacpp_model_id() -> str | None:
-    """The active main model when it is one of ours (config authority: the same
-    model.provider + model.default that /api/model/set writes)."""
+    """The active main model when it is one of ours (config authority: the model.provider + model.default
+    that /api/model/set writes)."""
     def read() -> str | None:
         model_section = (_load_config() or {}).get("model") or {}
         if str(model_section.get("provider", "")).strip().lower() in _LLAMACPP_PROVIDERS:
@@ -430,21 +452,16 @@ def _active_llamacpp_model_id() -> str | None:
 
 @router.get("/api/local-models/status")
 def local_models_status():
-    """Cheap, immediate: config state + installed runtime + staged models + supervisor
-    state (GPU facts live in /hardware). Sync def on purpose: blocking urlopen/scans
-    run in the threadpool."""
+    """Cheap, immediate: config state + installed runtime + staged models + supervisor state (GPU facts live
+    in /hardware). Sync def on purpose: blocking urlopen/scans run in the threadpool."""
     section = _runtime_section()
     configured_tag = section.get("tag") or binaries.default_tag()
     have = binaries.installed_tags()
     # The tag actually serving (boot ladder: configured if installed, else newest installed).
     tag = configured_tag if configured_tag in have else (have[0] if have else configured_tag)
-    # Update pending = engine in use (enabled + something installed) and the configured
-    # tag (pinned or release default) isn't on disk. The download is a button click, never automatic.
-    update_available = bool(section.get("enabled") and have and configured_tag not in have)
     runtime_backend = _installed_backend(tag)
     mdir = bootstrap.models_dir()
     running = _state_endpoint()
-
     # Resident models from the live router ({} when down): Loaded pills + eject.
     loaded: Dict[str, str] = {}
     placement: Dict[str, Any] = {}
@@ -452,16 +469,16 @@ def local_models_status():
         try:
             loaded, placement = _loaded_models(running)
         except Exception as exc:  # noqa: BLE001
-            # Never silent: an empty dict here renders as 'Not in memory'
-            # on a machine whose VRAM is visibly full.
+            # Never silent: an empty dict here renders as 'Not in memory' on a machine whose VRAM is visibly full.
             logger.warning("loaded-models read failed: %r", exc)
-
     return {
         "enabled": bool(section.get("enabled")), "tag": tag, "configured_tag": configured_tag,
-        "update_available": update_available, "runtime_installed": runtime_backend is not None,
-        "runtime_backend": runtime_backend, "server_running": running is not None,
-        "server_base_url": (running or {}).get("base_url"), "active_model_id": _active_llamacpp_model_id(),
-        "loaded_models": loaded,
+        # Update pending = engine in use (enabled + something installed) and the configured tag
+        # (pinned or release default) isn't on disk. The download is a button click, never automatic.
+        "update_available": bool(section.get("enabled") and have and configured_tag not in have),
+        "runtime_installed": runtime_backend is not None, "runtime_backend": runtime_backend,
+        "server_running": running is not None, "server_base_url": (running or {}).get("base_url"),
+        "active_model_id": _active_llamacpp_model_id(), "loaded_models": loaded,
         # Live load progress per model (SSE-fed): {model_id: {stage, value, percent}}.
         # The chat's loading bar and the picker rows poll this; garnish, never a 500.
         "loading": _quiet(load_progress.get_loading_progress, {}),
@@ -473,14 +490,12 @@ def local_models_status():
 
 # ── hardware: what this machine can do ───────────────────────
 def _nvidia_smi_facts() -> dict:
-    """GPU identity + live utilization (NVIDIA only; other vendors degrade to {} and
-    the UI hides those readouts)."""
+    """GPU identity + live utilization (NVIDIA only; other vendors degrade to {} and the UI hides those readouts)."""
     smi_exe = hardware._nvidia_smi_path()
     if not smi_exe:
         return {}
-    smi = subprocess.run(
-        [smi_exe, "--query-gpu=name,utilization.gpu,memory.used", "--format=csv,noheader,nounits"],
-        capture_output=True, text=True, timeout=5)
+    smi = subprocess.run([smi_exe, "--query-gpu=name,utilization.gpu,memory.used", "--format=csv,noheader,nounits"],
+                         capture_output=True, text=True, timeout=5)
     if smi.returncode != 0 or not smi.stdout.strip():
         return {}
     name, util, used_mib = (x.strip() for x in smi.stdout.strip().splitlines()[0].split(","))
@@ -489,8 +504,7 @@ def _nvidia_smi_facts() -> dict:
 
 @router.get("/api/local-models/hardware")
 def local_models_hardware():
-    """The budget as plain facts, polled by the pane and statusbar. Sync def on
-    purpose: shells out to nvidia-smi — threadpool, not loop."""
+    """The budget as plain facts, polled by the pane and statusbar. Sync def: shells out to nvidia-smi — threadpool."""
     budget = hardware.probe_budget()
     ram_total, ram_avail = hardware._ram_bytes()
     out = {
@@ -523,9 +537,8 @@ def _catalog_row(entry, budget, recommended, recommended_reason, staged_ids) ->
         "recommended_reason": recommended_reason if entry.id == recommended else None,
         "downloaded": dl is not None, "downloaded_model_id": dl.model_id if dl else None,
         "downloaded_quant": dl.quant if dl else None, "mtp": entry.mtp, "vision": entry.mmproj is not None,
-        # Day-0 architectures need the llama.cpp release where their support landed:
-        # True gates download/activate until the engine updates, but the row still
-        # renders (visible + explained beats hidden).
+        # Day-0 architectures need the llama.cpp release where their support landed: True gates
+        # download/activate until the engine updates, but the row still renders (visible + explained beats hidden).
         "needs_engine": _engine_too_old(entry.min_engine),
         "min_engine": entry.min_engine or None,
     }
@@ -541,9 +554,8 @@ def _catalog_row(entry, budget, recommended, recommended_reason, staged_ids) ->
         return row
 
     variant = choice.variant
-    # Same overhead the launch decision prices (runtime buffers + vision projector +
-    # microbatch/MTP logits): the row must advertise the window the model will
-    # actually get, not a paper number.
+    # Same overhead the launch decision prices (runtime buffers + vision projector + microbatch/MTP
+    # logits): the row must advertise the window the model will actually get, not a paper number.
     overhead = (context_policy.RUNTIME_OVERHEAD_BYTES
                 + (entry.mmproj.size_bytes if entry.mmproj else 0)
                 + context_policy.ub_logits_bytes(entry.n_vocab, mtp_capable=entry.mtp))
@@ -569,38 +581,31 @@ def _catalog_row(entry, budget, recommended, recommended_reason, staged_ids) ->
 
 @router.get("/api/local-models/catalog")
 def local_models_catalog():
-    """Every entry answers up front: how big is the download, will it fit, and what
-    context/speed shape will I get. The row advertises the BEST build for this
-    machine (highest quality fully on GPU at the 64K floor; else the smallest that
-    works, spilled and priced). No entry is hidden; unaffordable models show WHY.
+    """Every entry answers up front: how big is the download, will it fit, what context/speed shape will I
+    get. The row advertises the BEST build for this machine (highest quality fully on GPU at the 64K floor;
+    else the smallest that works, spilled and priced). No entry is hidden; unaffordable models show WHY.
     Sync def: blocking I/O -> threadpool."""
-    # Serve the in-memory catalog; a TTL-gated background fetch lands new entries
-    # for the next call (day-0 models without an app release).
+    # Serve the in-memory catalog; a TTL-gated background fetch lands new entries for the next call
+    # (day-0 models without an app release).
     catalog.refresh_catalog_soon()
-    # Planning budget: machine capacity, not live-free VRAM — a loaded model must
-    # not make every row unaffordable.
+    # Planning budget: machine capacity, not live-free VRAM — a loaded model must not make every row unaffordable.
     budget = hardware.probe_budget(planning=True)
-    # The reason key ships with the row so the Recommended badge's tooltip is the
-    # branch that actually fired, not a re-derivation that can drift.
+    # The reason key ships with the row so the Recommended badge's tooltip is the branch that actually
+    # fired, not a re-derivation that can drift.
     recommended, recommended_reason = catalog.recommended_entry(budget, _eligible_entries()) or (None, None)
     recommended_id = recommended.id if recommended is not None else None
-    # Completeness-checked staging (split parts all present) — same answer the
-    # picker and router see, so a mid-download model never reads as downloaded.
+    # Completeness-checked staging (split parts all present) — same answer the picker and router see, so a
+    # mid-download model never reads as downloaded.
     staged_ids = set(bootstrap.staged_model_ids())
     return {"models": [_catalog_row(e, budget, recommended_id, recommended_reason, staged_ids) for e in catalog.CATALOG]}
 
 
 # ── runtime install (job) ────────────────────────────────────
-class RuntimeInstallBody(BaseModel):
-    backend: Optional[str] = None   # None/auto -> detect
-
-
 def _runtime_progress_hook(job: Dict[str, Any]):
-    """Adapter: ensure_runtime_installed's progress stream -> job fields, throttled
-    to ~4 updates/s. Byte counters are CUMULATIVE across the plan (a multi-asset
-    engine reads as one growing download, total growing as each asset's size becomes
-    known); unpack/verify keep the counters — a bar bouncing back to zero after the
-    bytes finished reads as failure."""
+    """Adapter: ensure_runtime_installed's progress stream -> job fields, throttled to ~4 updates/s. Byte
+    counters are CUMULATIVE across the plan (a multi-asset engine reads as one growing download, total
+    growing as each asset's size becomes known); unpack/verify keep the counters — a bar bouncing back to
+    zero after the bytes finished reads as failure."""
     state = {"last": 0.0, "banked": 0, "asset": None, "asset_total": 0}
 
     def hook(stage: str, done: int, total: int, label: str) -> None:
@@ -611,8 +616,7 @@ def _runtime_progress_hook(job: Dict[str, Any]):
         suffix = f" ({label})" if label else ""
         if stage == "download":
             if label != state["asset"]:
-                # Previous asset finished: bank its bytes so the counters keep
-                # climbing instead of restarting for the next asset.
+                # Previous asset finished: bank its bytes so the counters keep climbing instead of restarting.
                 state["banked"] += state["asset_total"]
                 state["asset"] = label
             state["asset_total"] = total or done
@@ -632,10 +636,9 @@ def _runtime_progress_hook(job: Dict[str, Any]):
 
 
 def _restart_on_new_tag(job: Dict[str, Any], tag: str, previous: list) -> bool:
-    """Engine update path: a server already running on an older tag moves to the new
-    one now — the click was the consent. Fresh installs (no server) skip this;
-    Use/boot handles their start. Failure is logged only: the new build is
-    installed either way and the next boot serves it."""
+    """Engine update path: a server already running on an older tag moves to the new one now — the click was
+    the consent. Fresh installs (no server) skip this; Use/boot handles their start. Failure is logged only:
+    the new build is installed either way and the next boot serves it."""
     try:
         if bootstrap.get_supervisor() is not None and previous and tag not in previous:
             _step(job, "restarting", "Switching the running server to the new build")
@@ -658,8 +661,7 @@ async def local_models_runtime_install(body: RuntimeInstallBody):
         _step(job, "downloading", f"Fetching {len(plan.assets)} package(s) for {backend}")
         binaries.ensure_runtime_installed(tag, backend, progress=_runtime_progress_hook(job))
         restarted = _restart_on_new_tag(job, tag, previous)
-        # N-1 retention, only after the new tag verified: keep it and the newest
-        # previous build as the rollback pin target.
+        # N-1 retention, only after the new tag verified: keep it + the newest previous build as the rollback pin target.
         try:
             binaries.prune_old_tags([tag] + [t for t in previous if t != tag][:1])
         except Exception as exc:  # noqa: BLE001
@@ -671,20 +673,12 @@ async def local_models_runtime_install(body: RuntimeInstallBody):
 
 
 # ── model download (job with byte progress) ──────────────────
-class ModelDownloadBody(BaseModel):
-    model_id: str
-
-
 def _download_target(model_id: str):
-    """(entry, variant) for a family id (this machine's selected variant — the same
-    planning budget as the catalog, so the user downloads exactly the build the row
-    advertised) or an exact variant model_id."""
+    """(entry, variant) for a family id (this machine's selected variant — the same planning budget as the
+    catalog, so the user downloads exactly the build the row advertised) or an exact variant model_id."""
     entry = catalog.catalog_by_id().get(model_id)
-    if entry is None:
-        hit = catalog.find_entry_for_model(model_id)
-        if hit is None:
-            raise HTTPException(status_code=404, detail=f"unknown model {model_id}")
-        return hit
+    if entry is None:  # exact variant id, or nothing we know (404)
+        return catalog.find_entry_for_model(model_id) or _entry_or_404(model_id)
     if _engine_too_old(entry.min_engine):
         raise HTTPException(status_code=409, detail=(
             f"{entry.display_name} needs llama.cpp {entry.min_engine} or newer — update the engine first"))
@@ -710,16 +704,14 @@ async def local_models_download(body: ModelDownloadBody):
 
 @router.delete("/api/local-models/models/{model_id}")
 async def local_models_delete(model_id: str):
-    """Remove every split part plus private assets, then bounce the router off the
-    request thread (deleting the active file mid-serve is exactly the stale state
-    the refresh exists for)."""
+    """Remove every split part plus private assets, then bounce the router off the request thread (deleting
+    the active file mid-serve is exactly the stale state the refresh exists for)."""
     files = _variant_files_on_disk(model_id)
     if not files:
         raise HTTPException(status_code=404, detail="model not found")
     for path in files:
         path.unlink(missing_ok=True)
-    # Growth state dies with the model: a re-download starts back at its zero-spill
-    # window instead of inheriting a stale grown one.
+    # Growth state dies with the model: a re-download starts back at its zero-spill window, not a stale grown one.
     try:
         growth.clear_window_override(model_id)
     except Exception:  # noqa: BLE001
@@ -730,24 +722,10 @@ async def local_models_delete(model_id: str):
 
 
 # ── quickstart: one click from nothing to a working default ──
-class QuickstartBody(BaseModel):
-    model_id: str | None = None   # default: the catalog's recommended entry
-
-
-# One quickstart at a time: the job sequences installs, downloads, a server bounce,
-# and a config write — two racing runs would interleave all four. Held for the
-# job's lifetime, released in the worker.
-_QUICKSTART_LOCK = threading.Lock()
-
-
 def _quickstart_target(body: QuickstartBody, budget):
-    """(entry, variant) to set up: explicit id, else this machine's recommendation,
-    else the first catalog entry this machine can serve."""
+    """(entry, variant) to set up: explicit id, else this machine's recommendation, else the first servable entry."""
     if body.model_id:
-        entry = catalog.catalog_by_id().get(body.model_id)
-        if entry is None:
-            raise HTTPException(status_code=404, detail=f"unknown model {body.model_id}")
-        candidates = [entry]
+        candidates = [_entry_or_404(body.model_id)]
     else:
         picked = catalog.recommended_entry(budget, _eligible_entries())
         candidates = ([picked[0]] if picked else []) + [e for e in catalog.CATALOG if not picked or e.id != picked[0].id]
@@ -761,12 +739,10 @@ def _quickstart_target(body: QuickstartBody, budget):
 
 @router.post("/api/local-models/quickstart")
 async def local_models_quickstart(body: QuickstartBody):
-    """One job: install the runtime (if missing), download this machine's build of
-    the recommended model (if missing), make it the default. Each leg is the same
-    code the individual routes run, so 'Configure' and quickstart can never
-    disagree. Preflight rejects (no servable entry, engine too old) fail the POST
-    synchronously so the button can explain itself; everything slow runs in the
-    job with phase/byte progress."""
+    """One job: install the runtime (if missing), download this machine's build of the recommended model (if
+    missing), make it the default. Each leg is the same code the individual routes run, so 'Configure' and
+    quickstart can never disagree. Preflight rejects (no servable entry, engine too old) fail the POST
+    synchronously so the button can explain itself; everything slow runs in the job with phase/byte progress."""
     entry, variant = _quickstart_target(body, hardware.probe_budget(planning=True))
     tag, backend = _runtime_target()
     need_runtime = not binaries.installed_tags()
@@ -775,7 +751,6 @@ async def local_models_quickstart(body: QuickstartBody):
     need_download = variant.model_id not in bootstrap.staged_model_ids()
     download_plan = _download_plan(entry, variant) if need_download else []
     download_bytes = sum(p[2] for p in download_plan)
-
     if not _QUICKSTART_LOCK.acquire(blocking=False):
         raise HTTPException(status_code=409, detail="Setup is already running")
     job = _job("quickstart", entry.display_name, model_id=entry.id)
@@ -786,8 +761,7 @@ async def local_models_quickstart(body: QuickstartBody):
             _step(job, "installing-runtime", "Installing the local engine")
             binaries.ensure_runtime_installed(tag, backend, progress=_runtime_progress_hook(job))
         if need_download:
-            # The runtime leg repurposed the byte counters for its own stages —
-            # reset them to the model plan before download.
+            # The runtime leg repurposed the byte counters for its own stages — reset them to the model plan.
             job["done_bytes"] = 0
             job["total_bytes"] = download_bytes
             _run_download_plan(job, download_plan, entry.display_name)
@@ -804,13 +778,8 @@ async def local_models_quickstart(body: QuickstartBody):
 
 
 # ── server lifecycle: turn the engine on/off ─────────────────
-class ServerActionBody(BaseModel):
-    action: str                 # "stop" | "start"
-
-
 def _terminate_state_pid() -> None:
-    """Server owned by another process (or an orphan): terminate via the state
-    file's pid, then clear the state."""
+    """Server owned by another process (or an orphan): terminate via the state file's pid, then clear the state."""
     import psutil  # type: ignore
 
     state = json.loads(supervisor.state_path().read_text(encoding="utf-8"))
@@ -837,9 +806,8 @@ _SERVER_ACTIONS = {"stop": _stop_server, "start": _start_server}
 
 @router.post("/api/local-models/server")
 async def local_models_server(body: ServerActionBody):
-    """Turn the local engine off (stop the server, free ALL GPU memory, disable
-    auto-start) or back on. Unlike per-model eject the off switch IS durable: the
-    user said off, so boots stay off until they say on."""
+    """Turn the local engine off (stop the server, free ALL GPU memory, disable auto-start) or back on. Unlike
+    per-model eject the off switch IS durable: the user said off, so boots stay off until they say on."""
     action = (body.action or "").strip().lower()
     if action not in _SERVER_ACTIONS:
         raise HTTPException(status_code=400, detail="action must be 'stop' or 'start'")
@@ -848,23 +816,17 @@ async def local_models_server(body: ServerActionBody):
     return {"ok": True, "action": action}
 
 
-# ── activate: make a downloaded model THE model ──────────────
-class ModelEjectBody(BaseModel):
-    model_id: str
-
-
+# ── eject / activate ─────────────────────────────────────────
 @router.post("/api/local-models/eject")
 def local_models_eject(body: ModelEjectBody):
-    """Free a loaded model's GPU memory now; only demand (the next message) reloads
-    it — residency v2 has no automatic loading anywhere. Sync def: the fallback
-    path blocks on a 120s urlopen — threadpool, never the loop."""
+    """Free a loaded model's GPU memory now; only demand (the next message) reloads it — residency v2 has no
+    automatic loading anywhere. Sync def: the fallback path blocks on a 120s urlopen — threadpool, never the loop."""
     sup = bootstrap.get_supervisor()
     if sup is not None:
         with _http_error(502):
             sup.unload_model(body.model_id)
         return {"ok": True}
-    # Server owned by another process (or state-file only): drive the router
-    # directly with the persisted endpoint.
+    # Server owned by another process (or state-file only): drive the router directly with the persisted endpoint.
     endpoint = _state_endpoint()
     if endpoint is None:
         raise HTTPException(status_code=409, detail="local server is not running")
@@ -873,16 +835,11 @@ def local_models_eject(body: ModelEjectBody):
     return {"ok": True}
 
 
-class ModelActivateBody(BaseModel):
-    model_id: str               # exact variant id (a staged .gguf stem)
-
-
 @router.post("/api/local-models/activate")
 async def local_models_activate(body: ModelActivateBody):
-    """Make a downloaded model the default for new chats: a config write via the
-    same machinery as /api/model/set plus making sure the server is up. NO model
-    loading (residency v2: models load on first inference; an empty router costs
-    nothing). Kept as a job for UI continuity."""
+    """Make a downloaded model the default for new chats: a config write via the same machinery as
+    /api/model/set plus making sure the server is up. NO model loading (residency v2: models load on first
+    inference; an empty router costs nothing). Kept as a job for UI continuity."""
     # Split variants stage under their first part — resolve like the other routes.
     if body.model_id not in bootstrap.staged_model_ids():
         raise HTTPException(status_code=404, detail=f"{body.model_id} is not downloaded")
@@ -903,8 +860,7 @@ async def local_models_activate(body: ModelActivateBody):
 # ── job polling ──────────────────────────────────────────────
 @router.get("/api/local-models/jobs")
 async def local_models_jobs():
-    """All recent jobs, running first — the pane and the app-level poller rediscover
-    in-flight work here after a remount or app restart."""
+    """All recent jobs, running first — the pane and app-level poller rediscover in-flight work here after a remount."""
     with _JOBS_LOCK:
         jobs = sorted(_JOBS.values(), key=lambda j: (j["status"] != "running", -j["started_at"]))
     return {"jobs": [_job_view(job) for job in jobs[:20]]}
@@ -922,8 +878,7 @@ async def local_models_job(job_id: str):
 # ── Hugging Face browser: search, repo files, arbitrary download ─
 @router.get("/api/local-models/search")
 async def local_models_search(q: str, limit: int = 20):
-    """Full-text HF search over GGUF models — the firehose behind the curated catalog;
-    per-quant fit pills come from the repo-files call."""
+    """Full-text HF search over GGUF models — the firehose behind the curated catalog; fit pills come from /search/files."""
     if not q.strip():
         return {"hits": []}
     with _http_error(502, "Hugging Face search unavailable: "):
@@ -932,24 +887,18 @@ async def local_models_search(q: str, limit: int = 20):
 
 @router.get("/api/local-models/search/files")
 async def local_models_search_files(repo: str):
-    """Servable GGUFs in one HF repo with a rough pre-download fit verdict per quant
-    (file size + conservative fill-ins; the GGUF header refines it)."""
+    """Servable GGUFs in one HF repo with a rough pre-download fit verdict per quant (file size + conservative
+    fill-ins; the GGUF header refines it)."""
     with _http_error(502, f"Could not list {repo}: "):
         groups = await run_in_threadpool(hf_browse.priced_repo_files, repo, hardware.probe_budget(planning=True))
     return {"files": [dict(g.__dict__, paths=list(g.paths)) for g in groups]}
 
 
-class BrowsedDownloadBody(BaseModel):
-    repo: str
-    paths: list[str]            # one GGUF, or every part of a split, in order
-
-
 @router.post("/api/local-models/download-browsed")
 async def local_models_download_browsed(body: BrowsedDownloadBody):
-    """Download an arbitrary HF GGUF into the managed models dir. Once landed it is
-    a normal staged model (the post-download bounce regenerates presets from its
-    real header); with no catalog entry it serves 'unverified', capabilities
-    answered from the live server only."""
+    """Download an arbitrary HF GGUF into the managed models dir. Once landed it is a normal staged model (the
+    post-download bounce regenerates presets from its real header); with no catalog entry it serves
+    'unverified', capabilities answered from the live server only."""
     paths = [p for p in (body.paths or []) if p.lower().endswith(".gguf")]
     if not paths:
         raise HTTPException(status_code=422, detail="no .gguf files given")
@@ -972,15 +921,10 @@ async def local_models_download_browsed(body: BrowsedDownloadBody):
     return {"job_id": job["job_id"], "model_id": model_id}
 
 
-class SideloadBody(BaseModel):
-    path: str                   # absolute path to a .gguf on this machine
-
-
 @router.post("/api/local-models/sideload")
 async def local_models_sideload(body: SideloadBody):
-    """Register a GGUF already on this machine: link it into the managed models dir
-    (copy only when linking is impossible) and bounce the router. The original
-    stays put; delete-from-Hermes removes only our link."""
+    """Register a GGUF already on this machine: link it into the managed models dir (copy only when linking is
+    impossible) and bounce the router. The original stays put; delete-from-Hermes removes only our link."""
     src = Path(body.path)
     if not src.is_file() or src.suffix.lower() != ".gguf":
         raise HTTPException(status_code=422, detail="Pick a .gguf model file")

From 0b19fab861944cf92c5aa2c73dc80d322aa02d55 Mon Sep 17 00:00:00 2001
From: Teknium <127238744+teknium1@users.noreply.github.com>
Date: Thu, 3 Sep 2026 00:05:28 -0700
Subject: [PATCH 3/3] =?UTF-8?q?refactor(hermes=5Fcli/web=5Frouters):=20loc?=
 =?UTF-8?q?al=5Fmodels=20=E2=80=94=20=5Fquiet(warn=3D/debug=3D)=20absorbs?=
 =?UTF-8?q?=206=20try/except-log=20sites?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 hermes_cli/web_routers/local_models.py | 74 +++++++++++---------------
 1 file changed, 32 insertions(+), 42 deletions(-)

diff --git a/hermes_cli/web_routers/local_models.py b/hermes_cli/web_routers/local_models.py
index 3e98eb7872..1044053fc1 100644
--- a/hermes_cli/web_routers/local_models.py
+++ b/hermes_cli/web_routers/local_models.py
@@ -103,11 +103,16 @@ def _http_error(status: int, prefix: str = ""):
         raise HTTPException(status_code=status, detail=f"{prefix}{exc}") from exc
 
 
-def _quiet(fn: Callable[[], Any], default: Any) -> Any:
-    """``fn()`` or ``default`` on any exception — for garnish that must never 500."""
+def _quiet(fn: Callable[[], Any], default: Any, *, warn: str | None = None, debug: str | None = None) -> Any:
+    """``fn()`` or ``default`` on any exception — for garnish that must never 500. ``warn`` logs a
+    warning with the exception (%s), ``debug`` a debug line with traceback; silent otherwise."""
     try:
         return fn()
-    except Exception:  # noqa: BLE001
+    except Exception as exc:  # noqa: BLE001
+        if warn:
+            logger.warning(warn, exc)
+        if debug:
+            logger.debug(debug, exc_info=True)
         return default
 
 
@@ -169,10 +174,7 @@ def _spawn_job(job: Dict[str, Any], name: str, body: Callable[[], None], *, fail
 def _refresh_runtime(skip_msg: str) -> None:
     """Bounce a running router so it rescans the models dir (it only scans at spawn).
     Never raises — the file operation already succeeded."""
-    try:
-        bootstrap.refresh_local_runtime()
-    except Exception:  # noqa: BLE001
-        logger.debug(skip_msg, exc_info=True)
+    _quiet(bootstrap.refresh_local_runtime, None, debug=skip_msg)
 
 
 def _router_request(endpoint: Dict[str, Any], path: str, *, timeout: float, payload: dict | None = None) -> Any:
@@ -255,13 +257,14 @@ def _ensure_server(job: Dict[str, Any], config: dict, model_id: str, *, fail_det
     server started before ``model_id`` finished downloading can't serve it — bounce it when it doesn't know it."""
     _step(job, "starting-server", "Starting the local server")
     sup = _start_local_server(config, fail_detail)
+
+    def rescan_if_unknown() -> None:
+        if model_id not in sup.models():
+            job["detail"] = "Refreshing the local server"
+            bootstrap.refresh_local_runtime()
+
     if sup is not None:
-        try:
-            if model_id not in sup.models():
-                job["detail"] = "Refreshing the local server"
-                bootstrap.refresh_local_runtime()
-        except Exception:  # noqa: BLE001
-            logger.debug(skip_msg, exc_info=True)
+        _quiet(rescan_if_unknown, None, debug=skip_msg)
 
 
 def _assign_default(job: Dict[str, Any], model_id: str) -> None:
@@ -462,15 +465,10 @@ def local_models_status():
     runtime_backend = _installed_backend(tag)
     mdir = bootstrap.models_dir()
     running = _state_endpoint()
-    # Resident models from the live router ({} when down): Loaded pills + eject.
-    loaded: Dict[str, str] = {}
-    placement: Dict[str, Any] = {}
-    if running is not None:
-        try:
-            loaded, placement = _loaded_models(running)
-        except Exception as exc:  # noqa: BLE001
-            # Never silent: an empty dict here renders as 'Not in memory' on a machine whose VRAM is visibly full.
-            logger.warning("loaded-models read failed: %r", exc)
+    # Resident models from the live router ({} when down): Loaded pills + eject. A failed read is never
+    # silent: an empty dict here renders as 'Not in memory' on a machine whose VRAM is visibly full.
+    loaded, placement = ({}, {}) if running is None else _quiet(
+        lambda: _loaded_models(running), ({}, {}), warn="loaded-models read failed: %r")
     return {
         "enabled": bool(section.get("enabled")), "tag": tag, "configured_tag": configured_tag,
         # Update pending = engine in use (enabled + something installed) and the configured tag
@@ -637,17 +635,13 @@ def _runtime_progress_hook(job: Dict[str, Any]):
 
 def _restart_on_new_tag(job: Dict[str, Any], tag: str, previous: list) -> bool:
     """Engine update path: a server already running on an older tag moves to the new one now — the click was
-    the consent. Fresh installs (no server) skip this; Use/boot handles their start. Failure is logged only:
-    the new build is installed either way and the next boot serves it."""
-    try:
-        if bootstrap.get_supervisor() is not None and previous and tag not in previous:
-            _step(job, "restarting", "Switching the running server to the new build")
-            bootstrap.shutdown_local_runtime()
-            bootstrap.ensure_local_runtime(_load_config(), force=True)
-            return True
-    except Exception as exc:  # noqa: BLE001
-        logger.warning("post-update restart skipped: %s", exc)
-    return False
+    the consent. Fresh installs (no server) skip this; Use/boot handles their start."""
+    if bootstrap.get_supervisor() is None or not previous or tag in previous:
+        return False
+    _step(job, "restarting", "Switching the running server to the new build")
+    bootstrap.shutdown_local_runtime()
+    bootstrap.ensure_local_runtime(_load_config(), force=True)
+    return True
 
 
 @router.post("/api/local-models/runtime/install")
@@ -660,12 +654,11 @@ async def local_models_runtime_install(body: RuntimeInstallBody):
         previous = binaries.installed_tags()
         _step(job, "downloading", f"Fetching {len(plan.assets)} package(s) for {backend}")
         binaries.ensure_runtime_installed(tag, backend, progress=_runtime_progress_hook(job))
-        restarted = _restart_on_new_tag(job, tag, previous)
+        # Restart failure is logged only: the new build is installed either way and the next boot serves it.
+        restarted = _quiet(lambda: _restart_on_new_tag(job, tag, previous), False, warn="post-update restart skipped: %s")
         # N-1 retention, only after the new tag verified: keep it + the newest previous build as the rollback pin target.
-        try:
-            binaries.prune_old_tags([tag] + [t for t in previous if t != tag][:1])
-        except Exception as exc:  # noqa: BLE001
-            logger.warning("runtime prune skipped: %s", exc)
+        _quiet(lambda: binaries.prune_old_tags([tag] + [t for t in previous if t != tag][:1]), None,
+               warn="runtime prune skipped: %s")
         _finish(job, f"llama.cpp {tag} ready ({backend})" + (" — server restarted on the new build" if restarted else ""))
 
     _spawn_job(job, "lr-runtime-install", _run, fail_msg="runtime install failed: %s")
@@ -712,10 +705,7 @@ async def local_models_delete(model_id: str):
     for path in files:
         path.unlink(missing_ok=True)
     # Growth state dies with the model: a re-download starts back at its zero-spill window, not a stale grown one.
-    try:
-        growth.clear_window_override(model_id)
-    except Exception:  # noqa: BLE001
-        logger.debug("window-override clear skipped", exc_info=True)
+    _quiet(lambda: growth.clear_window_override(model_id), None, debug="window-override clear skipped")
     threading.Thread(target=_refresh_runtime, args=("post-delete runtime refresh skipped",), daemon=True,
                      name="lr-post-delete").start()
     return {"ok": True}