diff --git a/hermes_cli/web_routers/dashboard_ui.py b/hermes_cli/web_routers/dashboard_ui.py
index 6753e26f5e..6510fed9e0 100644
--- a/hermes_cli/web_routers/dashboard_ui.py
+++ b/hermes_cli/web_routers/dashboard_ui.py
@@ -1,22 +1,26 @@
 """Dashboard theme/font and dashboard-plugin (discovery, hub, install/enable, asset serving) routes.
 
 Extracted from ``hermes_cli.web_server``; helpers/state that tests monkeypatch on
-``web_server`` stay there and are imported lazily at call time (cycle-safe).
+``web_server`` stay there and are resolved late at call time (cycle-safe).
 """
 
-import logging
 import asyncio
-from fastapi import APIRouter
-from hermes_cli.web_deps import late
-from fastapi import HTTPException, Request
-from fastapi.responses import FileResponse
-from hermes_cli.web_models import ThemeSetBody, FontSetBody, _AgentPluginInstallBody, _PluginProvidersPutBody, _PluginVisibilityBody
+import logging
 from pathlib import Path
+from typing import Callable
+
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import FileResponse
+
+from hermes_cli.web_deps import LateState, late
+from hermes_cli.web_models import (
+    FontSetBody, ThemeSetBody, _AgentPluginInstallBody, _PluginProvidersPutBody, _PluginVisibilityBody,
+)
 
 _log = logging.getLogger("hermes_cli.web_server")
 router = APIRouter()
 
-# web_server helpers, late-bound so monkeypatch.setattr(web_server, ...) stays authoritative.
+# web_server helpers/state, late-bound so monkeypatch.setattr(web_server, ...) stays authoritative.
 _discover_user_themes = late("_discover_user_themes")
 _get_dashboard_plugins = late("_get_dashboard_plugins")
 _invalidate_plugins_hub_cache = late("_invalidate_plugins_hub_cache")
@@ -27,37 +31,35 @@ _require_token = late("_require_token")
 cfg_get = late("cfg_get")
 load_config = late("load_config")
 save_config = late("save_config")
+_BUILTIN_DASHBOARD_THEMES = LateState("_BUILTIN_DASHBOARD_THEMES")
+_CONFIG_MUTATION_LOCK = LateState("_CONFIG_MUTATION_LOCK")
+
+
+def _set_dashboard_key(key: str, value) -> None:
+    """Write ``dashboard.<key>`` to config.yaml under the config mutation lock."""
+    with _CONFIG_MUTATION_LOCK:
+        config = load_config()
+        if "dashboard" not in config:
+            config["dashboard"] = {}
+        config["dashboard"][key] = value
+        save_config(config)
 
 
 @router.get("/api/dashboard/themes")
 async def get_dashboard_themes():
-    """Return available themes and the currently active one.
-
-    Built-in entries ship name/label/description only (the frontend owns
-    their full definitions in `web/src/themes/presets.ts`).  User themes
-    from `~/.hermes/dashboard-themes/*.yaml` ship with their full
-    normalised definition under `definition`, so the client can apply
-    them without a stub.
-    """
-    from hermes_cli.web_server import _BUILTIN_DASHBOARD_THEMES
+    """Available themes and the active one. Built-ins ship name/label/description
+    only (the frontend owns their definitions in `web/src/themes/presets.ts`);
+    user themes from `~/.hermes/dashboard-themes/*.yaml` ship their normalised
+    definition under `definition` so the client can apply them without a stub."""
     def _run():
         config = load_config()
         active = cfg_get(config, "dashboard", "theme", default="default")
-        user_themes = _discover_user_themes()
-        seen = set()
-        themes = []
-        for t in _BUILTIN_DASHBOARD_THEMES:
-            seen.add(t["name"])
-            themes.append(t)
-        for t in user_themes:
+        themes = list(_BUILTIN_DASHBOARD_THEMES)
+        seen = {t["name"] for t in themes}
+        for t in _discover_user_themes():
             if t["name"] in seen:
                 continue
-            themes.append({
-                "name": t["name"],
-                "label": t["label"],
-                "description": t["description"],
-                "definition": t,
-            })
+            themes.append({"name": t["name"], "label": t["label"], "description": t["description"], "definition": t})
             seen.add(t["name"])
         return {"themes": themes, "active": active}
 
@@ -67,27 +69,15 @@ async def get_dashboard_themes():
 @router.put("/api/dashboard/theme")
 async def set_dashboard_theme(body: ThemeSetBody):
     """Set the active dashboard theme (persists to config.yaml)."""
-    from hermes_cli.web_server import _CONFIG_MUTATION_LOCK
-    def _run():
-        with _CONFIG_MUTATION_LOCK:
-            config = load_config()
-            if "dashboard" not in config:
-                config["dashboard"] = {}
-            config["dashboard"]["theme"] = body.name
-            save_config(config)
-        return {"ok": True, "theme": body.name}
-
-    return await asyncio.to_thread(_run)
+    await asyncio.to_thread(_set_dashboard_key, "theme", body.name)
+    return {"ok": True, "theme": body.name}
 
 
-# Curated font-override ids. Kept in sync with FONT_CHOICES in
-# web/src/themes/fonts.ts — the frontend owns the stacks + webfont URLs;
-# the backend only needs the id allow-list so it can reject anything not
-# in the vetted catalog (the font's webfont URL is injected as a <link>,
-# so we never accept an arbitrary user-supplied id/URL here).
+# Curated font-override ids, kept in sync with FONT_CHOICES in web/src/themes/fonts.ts.
+# The frontend owns the stacks + webfont URLs; the backend only needs the id
+# allow-list so it can reject anything not in the vetted catalog (the webfont URL
+# is injected as a <link>, so we never accept an arbitrary user-supplied id/URL).
 _FONT_DEFAULT_ID = "theme"
-
-
 _FONT_CHOICES = frozenset({
     "system-sans", "system-serif", "system-mono",
     "inter", "ibm-plex-sans", "work-sans", "atkinson-hyperlegible", "dm-sans",
@@ -100,37 +90,41 @@ _FONT_CHOICES = frozenset({
 async def get_dashboard_font():
     """Return the active font override (``"theme"`` = use the theme's font)."""
     def _run():
-        config = load_config()
-        font = cfg_get(config, "dashboard", "font", default=_FONT_DEFAULT_ID)
-        if font not in _FONT_CHOICES:
-            font = _FONT_DEFAULT_ID
-        return {"font": font}
+        font = cfg_get(load_config(), "dashboard", "font", default=_FONT_DEFAULT_ID)
+        return {"font": font if font in _FONT_CHOICES else _FONT_DEFAULT_ID}
 
     return await asyncio.to_thread(_run)
 
 
 @router.put("/api/dashboard/font")
 async def set_dashboard_font(body: FontSetBody):
-    """Set the dashboard font override (persists to config.yaml).
-
-    Accepts any id in the curated catalog, or ``"theme"`` to clear the
-    override and fall back to the active theme's own font. Unknown ids are
-    coerced to ``"theme"`` rather than 400'd so a stale client can't wedge
-    the picker.
-    """
-    from hermes_cli.web_server import _CONFIG_MUTATION_LOCK
+    """Set the dashboard font override (persists to config.yaml). Unknown ids are
+    coerced to ``"theme"`` rather than 400'd so a stale client can't wedge the picker."""
     font = body.font if body.font in _FONT_CHOICES else _FONT_DEFAULT_ID
+    await asyncio.to_thread(_set_dashboard_key, "font", font)
+    return {"ok": True, "font": font}
 
-    def _run():
-        with _CONFIG_MUTATION_LOCK:
-            config = load_config()
-            if "dashboard" not in config:
-                config["dashboard"] = {}
-            config["dashboard"]["font"] = font
-            save_config(config)
-        return {"ok": True, "font": font}
 
-    return await asyncio.to_thread(_run)
+def _plugin_enable_sets() -> tuple[set, set]:
+    """(enabled, disabled) plugin name sets; empty on any failure."""
+    try:
+        from hermes_cli.plugins_cmd import _get_enabled_set, _get_disabled_set
+        return _get_enabled_set(), _get_disabled_set()
+    except Exception:
+        return set(), set()
+
+
+def _plugin_activated(plugin: dict, enabled_set: set, disabled_set: set) -> bool:
+    """Gate: user plugins must be in plugins.enabled and not in plugins.disabled;
+    bundled plugins must not be explicitly disabled. Keeps the frontend from
+    loading JS/CSS from plugins the user never activated."""
+    name = plugin.get("name", "")
+    source = plugin.get("source")
+    if source == "user":
+        return name not in disabled_set and name in enabled_set
+    if source == "bundled":
+        return name not in disabled_set
+    return True
 
 
 @router.get("/api/dashboard/plugins")
@@ -138,42 +132,16 @@ async def get_dashboard_plugins():
     """Return discovered dashboard plugins (excludes user-hidden and non-enabled ones)."""
     def _run():
         plugins = _get_dashboard_plugins()
-        # Read user's hidden plugins list from config.
-        config = load_config()
-        hidden: list = cfg_get(config, "dashboard", "hidden_plugins", default=[]) or []
-        # Gate: only serve user plugins that are in plugins.enabled and not
-        # in plugins.disabled.  This prevents the frontend from loading JS/CSS
-        # from plugins the user has not explicitly activated.  (#46435)
-        try:
-            from hermes_cli.plugins_cmd import _get_enabled_set, _get_disabled_set
-            enabled_set = _get_enabled_set()
-            disabled_set = _get_disabled_set()
-        except Exception:
-            enabled_set = set()
-            disabled_set = set()
-        return plugins, hidden, enabled_set, disabled_set
+        hidden: list = cfg_get(load_config(), "dashboard", "hidden_plugins", default=[]) or []
+        return plugins, hidden, *_plugin_enable_sets()
 
     plugins, hidden, enabled_set, disabled_set = await asyncio.to_thread(_run)
 
-    def _is_active(p: dict) -> bool:
-        name = p.get("name", "")
-        if name in hidden:
-            return False
-        if p.get("source") == "user":
-            if name in disabled_set:
-                return False
-            if name not in enabled_set:
-                return False
-        elif p.get("source") == "bundled":
-            if name in disabled_set:
-                return False
-        return True
-
     # Strip internal fields before sending to frontend.
     return [
         {k: v for k, v in p.items() if not k.startswith("_")}
         for p in plugins
-        if _is_active(p)
+        if p.get("name", "") not in hidden and _plugin_activated(p, enabled_set, disabled_set)
     ]
 
 
@@ -195,23 +163,24 @@ async def get_plugins_hub(request: Request):
         raise HTTPException(status_code=500, detail="Failed to build plugins hub.") from exc
 
 
+def _plugin_action(result: dict, fallback_error: str, *, rescan: bool) -> dict:
+    """Common tail of the agent-plugin mutations: 400 on ``ok=False``, then
+    invalidate caches (rescanning discovery when files changed on disk)."""
+    if not result.get("ok"):
+        raise HTTPException(status_code=400, detail=result.get("error") or fallback_error)
+    if rescan:
+        _get_dashboard_plugins(force_rescan=True)
+    _invalidate_plugins_hub_cache()
+    return result
+
+
 @router.post("/api/dashboard/agent-plugins/install")
 async def post_agent_plugin_install(request: Request, body: _AgentPluginInstallBody):
     _require_token(request)
     from hermes_cli.plugins_cmd import dashboard_install_plugin
 
-    result = dashboard_install_plugin(
-        body.identifier.strip(),
-        force=body.force,
-        enable=body.enable,
-    )
-    if not result.get("ok"):
-        raise HTTPException(
-            status_code=400,
-            detail=result.get("error") or "Install failed.",
-        )
-    _get_dashboard_plugins(force_rescan=True)
-    _invalidate_plugins_hub_cache()
+    result = dashboard_install_plugin(body.identifier.strip(), force=body.force, enable=body.enable)
+    result = _plugin_action(result, "Install failed.", rescan=True)
     # Strip internal paths from the response
     result.pop("after_install_path", None)
     return result
@@ -225,69 +194,42 @@ def _validate_plugin_name(name: str) -> str:
     return name
 
 
+def _named_plugin_action(request: Request, name: str, action: Callable[[str], dict], fallback_error: str, *, rescan: bool) -> dict:
+    _require_token(request)
+    return _plugin_action(action(_validate_plugin_name(name)), fallback_error, rescan=rescan)
+
+
 @router.post("/api/dashboard/agent-plugins/{name:path}/enable")
 async def post_agent_plugin_enable(request: Request, name: str):
-    _require_token(request)
-    name = _validate_plugin_name(name)
     from hermes_cli.plugins_cmd import dashboard_set_agent_plugin_enabled
-
-    result = dashboard_set_agent_plugin_enabled(name, enabled=True)
-    if not result.get("ok"):
-        raise HTTPException(status_code=400, detail=result.get("error") or "Enable failed.")
-    _invalidate_plugins_hub_cache()
-    return result
+    return _named_plugin_action(request, name, lambda n: dashboard_set_agent_plugin_enabled(n, enabled=True),
+                                "Enable failed.", rescan=False)
 
 
 @router.post("/api/dashboard/agent-plugins/{name:path}/disable")
 async def post_agent_plugin_disable(request: Request, name: str):
-    _require_token(request)
-    name = _validate_plugin_name(name)
     from hermes_cli.plugins_cmd import dashboard_set_agent_plugin_enabled
-
-    result = dashboard_set_agent_plugin_enabled(name, enabled=False)
-    if not result.get("ok"):
-        raise HTTPException(status_code=400, detail=result.get("error") or "Disable failed.")
-    _invalidate_plugins_hub_cache()
-    return result
+    return _named_plugin_action(request, name, lambda n: dashboard_set_agent_plugin_enabled(n, enabled=False),
+                                "Disable failed.", rescan=False)
 
 
 @router.post("/api/dashboard/agent-plugins/{name:path}/update")
 async def post_agent_plugin_update(request: Request, name: str):
-    _require_token(request)
-    name = _validate_plugin_name(name)
     from hermes_cli.plugins_cmd import dashboard_update_user_plugin
-
-    result = dashboard_update_user_plugin(name)
-    if not result.get("ok"):
-        raise HTTPException(status_code=400, detail=result.get("error") or "Update failed.")
-    _get_dashboard_plugins(force_rescan=True)
-    _invalidate_plugins_hub_cache()
-    return result
+    return _named_plugin_action(request, name, dashboard_update_user_plugin, "Update failed.", rescan=True)
 
 
 @router.delete("/api/dashboard/agent-plugins/{name:path}")
 async def delete_agent_plugin(request: Request, name: str):
-    _require_token(request)
-    name = _validate_plugin_name(name)
     from hermes_cli.plugins_cmd import dashboard_remove_user_plugin
-
-    result = dashboard_remove_user_plugin(name)
-    if not result.get("ok"):
-        raise HTTPException(status_code=400, detail=result.get("error") or "Remove failed.")
-    _get_dashboard_plugins(force_rescan=True)
-    _invalidate_plugins_hub_cache()
-    return result
+    return _named_plugin_action(request, name, dashboard_remove_user_plugin, "Remove failed.", rescan=True)
 
 
 @router.put("/api/dashboard/plugin-providers")
 async def put_plugin_providers(request: Request, body: _PluginProvidersPutBody):
     """Persist memory provider / context engine selection (writes config.yaml)."""
-    from hermes_cli.web_server import _CONFIG_MUTATION_LOCK
     _require_token(request)
-    from hermes_cli.plugins_cmd import (
-        _save_context_engine,
-        _save_memory_provider,
-    )
+    from hermes_cli.plugins_cmd import _save_context_engine, _save_memory_provider
 
     def _run():
         with _CONFIG_MUTATION_LOCK:
@@ -306,7 +248,6 @@ async def put_plugin_providers(request: Request, body: _PluginProvidersPutBody):
 @router.post("/api/dashboard/plugins/{name:path}/visibility")
 async def post_plugin_visibility(request: Request, name: str, body: _PluginVisibilityBody):
     """Toggle a plugin's sidebar visibility (persists to config.yaml dashboard.hidden_plugins)."""
-    from hermes_cli.web_server import _CONFIG_MUTATION_LOCK
     _require_token(request)
     name = _validate_plugin_name(name)
 
@@ -318,12 +259,10 @@ async def post_plugin_visibility(request: Request, name: str, body: _PluginVisib
             hidden_list: list = config["dashboard"].get("hidden_plugins") or []
             if not isinstance(hidden_list, list):
                 hidden_list = []
-
             if body.hidden and name not in hidden_list:
                 hidden_list.append(name)
             elif not body.hidden and name in hidden_list:
                 hidden_list.remove(name)
-
             config["dashboard"]["hidden_plugins"] = hidden_list
             save_config(config)
         _invalidate_plugins_hub_cache()
@@ -332,48 +271,35 @@ async def post_plugin_visibility(request: Request, name: str, body: _PluginVisib
     return await asyncio.to_thread(_run)
 
 
+# Browser-asset suffix allowlist. Everything outside this set is 404'd so we
+# never leak ``.py`` backend sources, READMEs, ``.env.example`` templates, etc.
+# Add to it deliberately when a new asset type comes up; do NOT add a fallback.
+_PLUGIN_ASSET_CONTENT_TYPES = {
+    ".js": "application/javascript", ".mjs": "application/javascript", ".css": "text/css",
+    ".json": "application/json", ".html": "text/html", ".svg": "image/svg+xml",
+    ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif",
+    ".webp": "image/webp", ".ico": "image/x-icon", ".woff2": "font/woff2", ".woff": "font/woff",
+    ".ttf": "font/ttf", ".otf": "font/otf", ".map": "application/json",
+}
+
+
 @router.get("/dashboard-plugins/{plugin_name}/{file_path:path}")
 async def serve_plugin_asset(plugin_name: str, file_path: str):
-    """Serve static assets from a dashboard plugin directory.
+    """Serve static assets from a dashboard plugin's ``dashboard/`` directory.
 
-    Only serves files from the plugin's ``dashboard/`` subdirectory.
-    Path traversal is blocked by checking ``resolve().is_relative_to()``.
-
-    Restricted to a browser-fetchable suffix allowlist (JS/CSS/JSON/HTML/
-    SVG/PNG/JPG/WOFF). The dashboard loads plugin JS via ``<script src>``
-    and CSS via ``<link href>``, neither of which can attach a custom
-    auth header — so this route stays unauthenticated to keep the SPA
-    working. But user-installed plugins ship a ``plugin_api.py``
-    backend module that the browser never fetches; it's only imported
-    by :func:`_mount_plugin_api_routes` at startup. Without a suffix
-    allowlist, anyone on the loopback port can curl the ``.py`` source
-    of a private third-party plugin. Reject everything outside the
-    browser-asset set.
-
-    User plugins must be in plugins.enabled before their assets are
-    served. (#46435, GHSA-mcfc-hp25-cjv7)
+    Unauthenticated on purpose: the SPA loads plugin JS via ``<script src>``
+    and CSS via ``<link href>``, which cannot attach an auth header. That is
+    why the suffix allowlist exists — user plugins ship a ``plugin_api.py``
+    backend the browser never fetches, and without it anyone on the loopback
+    port could curl a private plugin's source. Path traversal is blocked via
+    ``resolve().is_relative_to()``; user plugins must be enabled (bundled ones
+    not disabled) before their assets are served (GHSA-mcfc-hp25-cjv7).
     """
     plugins = _get_dashboard_plugins()
     plugin = next((p for p in plugins if p["name"] == plugin_name), None)
-    if not plugin:
+    if not plugin or not _plugin_activated(plugin, *_plugin_enable_sets()):
         raise HTTPException(status_code=404, detail="Plugin not found")
 
-    # Gate: user plugins must be enabled to serve assets;
-    # bundled plugins must not be explicitly disabled.
-    try:
-        from hermes_cli.plugins_cmd import _get_enabled_set, _get_disabled_set
-        enabled_set = _get_enabled_set()
-        disabled_set = _get_disabled_set()
-    except Exception:
-        enabled_set = set()
-        disabled_set = set()
-    if plugin.get("source") == "user":
-        if plugin_name in disabled_set or plugin_name not in enabled_set:
-            raise HTTPException(status_code=404, detail="Plugin not found")
-    elif plugin.get("source") == "bundled":
-        if plugin_name in disabled_set:
-            raise HTTPException(status_code=404, detail="Plugin not found")
-
     base = Path(plugin["_dir"])
     target = (base / file_path).resolve()
 
@@ -382,39 +308,7 @@ async def serve_plugin_asset(plugin_name: str, file_path: str):
     if not target.exists() or not target.is_file():
         raise HTTPException(status_code=404, detail="File not found")
 
-    # Browser-asset suffix allowlist. Everything outside this set is
-    # rejected with 404 so we don't leak ``.py`` backend sources, README
-    # files, ``.env.example`` templates, etc. — none of which the SPA
-    # actually fetches. Add to this set deliberately when a new asset
-    # type comes up; do NOT change the default fallback.
-    suffix = target.suffix.lower()
-    content_types = {
-        ".js": "application/javascript",
-        ".mjs": "application/javascript",
-        ".css": "text/css",
-        ".json": "application/json",
-        ".html": "text/html",
-        ".svg": "image/svg+xml",
-        ".png": "image/png",
-        ".jpg": "image/jpeg",
-        ".jpeg": "image/jpeg",
-        ".gif": "image/gif",
-        ".webp": "image/webp",
-        ".ico": "image/x-icon",
-        ".woff2": "font/woff2",
-        ".woff": "font/woff",
-        ".ttf": "font/ttf",
-        ".otf": "font/otf",
-        ".map": "application/json",
-    }
-    if suffix not in content_types:
-        raise HTTPException(
-            status_code=404,
-            detail="File not found",
-        )
-    media_type = content_types[suffix]
-    return FileResponse(
-        target,
-        media_type=media_type,
-        headers={"Cache-Control": "no-store, no-cache, must-revalidate"},
-    )
+    media_type = _PLUGIN_ASSET_CONTENT_TYPES.get(target.suffix.lower())
+    if media_type is None:
+        raise HTTPException(status_code=404, detail="File not found")
+    return FileResponse(target, media_type=media_type, headers={"Cache-Control": "no-store, no-cache, must-revalidate"})
diff --git a/hermes_cli/web_routers/local_models.py b/hermes_cli/web_routers/local_models.py
index b07cdd3993..9c83df19de 100644
--- a/hermes_cli/web_routers/local_models.py
+++ b/hermes_cli/web_routers/local_models.py
@@ -1,15 +1,15 @@
-"""Local-models dashboard routes — the desktop's window into the managed
-llama.cpp runtime.
+"""Local-models dashboard routes — the desktop's window into the managed llama.cpp runtime.
 
-Every payload carries plain-language, pre-formatted facts the UI shows
-verbatim (what will this model do ON THIS MACHINE, how big is the download,
-what is the runtime doing), never raw internals. Long jobs follow the repo's
-job pattern: start-POST -> {job_id} -> GET poll with byte progress.
+Every payload carries plain-language, pre-formatted facts the UI shows verbatim
+(what will this model do ON THIS MACHINE, how big is the download, what is the
+runtime doing), never raw internals. Long jobs follow the repo's job pattern:
+start-POST -> {job_id} -> GET poll with byte progress.
 """
 
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import json
 import logging
 import os
@@ -31,17 +31,8 @@ from starlette.concurrency import run_in_threadpool
 
 from hermes_cli import config as config_mod, web_deps
 from hermes_cli.local_runtime import (
-    binaries,
-    bootstrap,
-    catalog,
-    context_policy,
-    estimator,
-    growth,
-    hardware,
-    hf_browse,
-    load_progress,
-    presets,
-    supervisor,
+    binaries, bootstrap, catalog, context_policy, estimator, growth, hardware, hf_browse,
+    load_progress, presets, supervisor,
 )
 from hermes_cli.local_runtime.endpoint import _state_endpoint
 
@@ -53,20 +44,33 @@ _GIB = 1 << 30
 _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}"
 
 
 def _human_gb(n: int | float) -> str:
     return f"{n / _GIB:.1f} GB"
 
 
+def _k_label(tokens: int) -> str:
+    return f"{tokens // 1024}K"
+
+
+@contextlib.contextmanager
+def _http_error(status: int, prefix: str = ""):
+    """Map any exception to ``HTTPException(status, f"{prefix}{exc}")``."""
+    try:
+        yield
+    except Exception as exc:  # noqa: BLE001
+        raise HTTPException(status_code=status, detail=f"{prefix}{exc}") from exc
+
+
 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,
         "model_id": model_id,       # catalog id for downloads; None otherwise
         "status": "running",        # running | done | error
         "phase": "starting",        # human-readable step name
-        "detail": "", "total_bytes": None, "done_bytes": 0,
-        "started_at": time.time(), "error": None,
+        "detail": "", "total_bytes": None, "done_bytes": 0, "started_at": time.time(), "error": None,
     }
     with _JOBS_LOCK:
         _JOBS[job["job_id"]] = job
@@ -80,17 +84,20 @@ def _job_view(job: Dict[str, Any]) -> Dict[str, Any]:
     return out
 
 
-def _finish(job: Dict[str, Any], detail: str) -> None:
-    job["phase"] = "done"
-    job["status"] = "done"
+def _step(job: Dict[str, Any], phase: str, detail: str) -> None:
+    job["phase"] = phase
     job["detail"] = detail
 
 
+def _finish(job: Dict[str, Any], detail: str) -> None:
+    _step(job, "done", detail)
+    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:
-    """Run ``body`` on a daemon thread; an exception marks the job errored
-    (warning ``fail_msg`` when given). ``on_exit`` always runs last."""
+               fail_msg: str | None = None, on_exit: Callable[[], None] | 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."""
     def _run():
         try:
             body()
@@ -107,10 +114,9 @@ def _spawn_job(job: Dict[str, Any], name: str, body: Callable[[], None], *,
 
 
 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."""
+    """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)
@@ -118,16 +124,15 @@ 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) returns the parsed JSON body; POST returns None."""
     headers = {"Authorization": f"Bearer {endpoint.get('api_key', '')}"}
     data = None
     if payload is not None:
         headers["Content-Type"] = "application/json"
         data = json.dumps(payload).encode()
-    req = urllib.request.Request(
-        endpoint["base_url"].rsplit("/v1", 1)[0] + path, data=data, headers=headers,
-        method="POST" if payload is not None else None)
+    req = urllib.request.Request(endpoint["base_url"].rsplit("/v1", 1)[0] + path, data=data, headers=headers,
+                                 method="POST" if payload is not None else None)
     with urllib.request.urlopen(req, timeout=timeout) as r:
         return None if payload is not None else json.loads(r.read())
 
@@ -141,9 +146,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 the repo is gated or the catalog names a wrong repo — raise with a
-    plain-language message, not a bare status."""
+    """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:
@@ -153,9 +157,8 @@ def _probe_range_support(url: str) -> int:
                     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 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
@@ -164,13 +167,12 @@ def _probe_range_support(url: str) -> int:
 
 def _model_id_for(gguf: Path) -> str:
     """Variant model id for a staged file (strips split-part suffixes)."""
-    return re.sub(r"-\d{5}-of-\d{5}$", "", gguf.stem)
+    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."""
-
+    """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:
@@ -180,36 +182,31 @@ def _variant_files_on_disk(model_id: str) -> "list[Path]":
     return files
 
 
-def download_file(url: str, dest: Path, job: Dict[str, Any],
-                  *,
+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.
+    """Download url -> dest with byte progress on ``job``; ranged-parallel when the
+    server supports it, single-stream otherwise. Never leaves a .part.
 
-    No integrity check against the CATALOG by design (catalog sizes may lag a
-    re-upload); completeness is checked only against what the SERVER declared
-    (range-probe total / Content-Length), 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.
+    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 bump(n: int) -> None:
-        with progress_lock:
-            file_done[0] += n
-            job["done_bytes"] = base_done + file_done[0]
-
     def pump(r, f) -> None:
         while True:
             chunk = r.read(_CHUNK)
             if not chunk:
                 break
             f.write(chunk)
-            bump(len(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
@@ -229,10 +226,8 @@ def download_file(url: str, dest: Path, job: Dict[str, Any],
 
             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:
+                    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
@@ -248,8 +243,7 @@ def download_file(url: str, dest: Path, job: Dict[str, Any],
             if errors:
                 raise errors[0]
             if file_done[0] != total:
-                raise RuntimeError(
-                    f"download incomplete ({file_done[0]} of {total} bytes)")
+                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.
@@ -259,9 +253,8 @@ def download_file(url: str, dest: Path, job: Dict[str, Any],
                     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")
+                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:
@@ -270,7 +263,6 @@ def download_file(url: str, dest: Path, job: Dict[str, Any],
 
 
 def _models_dir() -> Path:
-
     return bootstrap.models_dir()
 
 
@@ -279,22 +271,17 @@ def _hf_url(repo: str, path: str) -> str:
 
 
 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]
+    """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."""
+    """Download every missing file in ``plan``; already-present files count toward progress without a transfer."""
     total = sum(p[2] for p in plan)
-    job["phase"] = "downloading"
-    job["detail"] = f"{label} — {_human_gb(total)}"
+    _step(job, "downloading", f"{label} — {_human_gb(total)}")
     done_before = 0
     for url, dest, size in plan:
         if not dest.exists():
@@ -305,13 +292,12 @@ def _run_download_plan(job: Dict[str, Any], plan: list, label: str) -> None:
 
 
 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."""
     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"))
@@ -320,7 +306,6 @@ def _engine_too_old(min_engine: str) -> bool:
 
 
 def _load_config() -> dict:
-
     try:
         return config_mod.load_config()
     except Exception:  # noqa: BLE001
@@ -333,7 +318,6 @@ def _runtime_section() -> dict:
 
 def _set_runtime_enabled(enabled: bool) -> dict:
     """Persist ``local_runtime.enabled`` and return the config written."""
-
     config = config_mod.load_config()
     config.setdefault("local_runtime", {})["enabled"] = enabled
     config_mod.save_config(config)
@@ -341,30 +325,37 @@ def _set_runtime_enabled(enabled: bool) -> dict:
 
 
 def _resolve_backend(section: dict, requested: str | None = None) -> str:
-
     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)."""
-
+    """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 _resolve_assets_or_400(tag: str, backend: str):
+    """Resolve first so an impossible combination fails the POST, not the job."""
+    with _http_error(400):
+        return binaries.resolve_assets(tag, backend)
+
+
+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."""
+    sup = bootstrap.ensure_local_runtime(config, force=True)
+    if sup is None and _state_endpoint() is None:
+        raise RuntimeError(fail_detail)
+    return sup
+
+
 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."""
-
-    job["phase"] = "starting-server"
-    job["detail"] = "Starting the local server"
-    sup = bootstrap.ensure_local_runtime(config, force=True)
-    if sup is None and _state_endpoint() is None:
-        raise RuntimeError(fail_detail)
+    """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."""
+    _step(job, "starting-server", "Starting the local server")
+    sup = _start_local_server(config, fail_detail)
     if sup is not None:
         try:
             if model_id not in sup.models():
@@ -375,47 +366,35 @@ def _ensure_server(job: Dict[str, Any], config: dict, model_id: str, *,
 
 
 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)."""
-
-    job["phase"] = "setting-default"
-    job["detail"] = "Making it your default"
+    """Make ``model_id`` the main model through the same machinery as /api/model/set
+    (late-bound so tests can stub web_deps.late)."""
+    _step(job, "setting-default", "Making it your default")
     web_deps.late("_apply_model_assignment_sync")("main", "llamacpp", model_id, "", "", "")
 
 
 # ── 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."""
-
+    """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."""
     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
-    # the pane 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")
-    }
+    # 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] = {}
     decisions = presets.read_preset_decisions()
     for model_id, state in loaded.items():
         facts: Dict[str, Any] = {}
         plan = decisions.get(model_id)
         if plan is not None:
-            facts["window"] = plan.window
-            facts["window_label"] = f"{plan.window // 1024}K"
-            facts["spilled"] = plan.spilled
+            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["granted_window"] = int(n_ctx)
-                    facts["granted_window_label"] = f"{int(n_ctx) // 1024}K"
+                    facts.update(granted_window=int(n_ctx), granted_window_label=_k_label(int(n_ctx)))
             except Exception:  # noqa: BLE001
                 pass
         if facts:
@@ -423,41 +402,52 @@ def _loaded_models(running: Dict[str, Any]) -> "tuple[Dict[str, str], Dict[str,
     return loaded, placement
 
 
+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()):
+        try:
+            binaries.server_binary(backend_dir)
+            return backend_dir.name
+        except Exception:  # noqa: BLE001
+            continue
+    return None
+
+
+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:
+        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
+
+
 @router.get("/api/local-models/status")
 def local_models_status():
-    """Cheap, immediate, never blocks on probes: 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).
+    # 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 = None
-    root = binaries.runtimes_root() / tag
-    if root.exists():
-        for backend_dir in sorted(p for p in root.iterdir() if p.is_dir()):
-            try:
-                binaries.server_binary(backend_dir)
-                runtime_backend = backend_dir.name
-                break
-            except Exception:  # noqa: BLE001
-                continue
+    # 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)
 
     staged = []
     mdir = _models_dir()
     if mdir.exists():
-
         for gguf in bootstrap.staged_models():
             model_id = _model_id_for(gguf)
             # Split models: report the whole variant's bytes, not one part's.
@@ -477,78 +467,48 @@ def local_models_status():
             # 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)
-            loaded = {}
-
-    # The active main model, when it is one of ours (config authority: the
-    # same model.provider + model.default that /api/model/set writes).
-    active_model_id = None
-    try:
-        model_section = (_load_config() or {}).get("model") or {}
-        if str(model_section.get("provider", "")).strip().lower() in _LLAMACPP_PROVIDERS:
-            active_model_id = str(
-                model_section.get("default") or model_section.get("name") or ""
-            ).strip() or None
-    except Exception:  # noqa: BLE001
-        pass
 
     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_model_id,
+        "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,
         # Live load progress per model (SSE-fed): {model_id: {stage, value,
         # percent}}. The chat's loading bar and the picker rows poll this.
         "loading": _loading_progress(),
-        "placement": placement,
-        "models": staged,
-        "models_dir": str(mdir),
+        "placement": placement, "models": staged, "models_dir": str(mdir),
     }
 
 
 def _loading_progress() -> Dict[str, Any]:
     try:
-
         return load_progress.get_loading_progress()
     except Exception:  # noqa: BLE001 — progress is garnish, never a 500
         return {}
 
 
 # ── hardware: what this machine can do ───────────────────────
-
-
 @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 on
+    purpose: shells out to nvidia-smi — threadpool, not loop."""
     budget = hardware.probe_budget()
     ram_total, ram_avail = hardware._ram_bytes()
     out = {
-        "uma": budget.uma, "vram_total_bytes": budget.total_device_bytes,
-        "vram_usable_bytes": budget.usable_vram_bytes, "ram_total_bytes": ram_total,
-        "ram_available_bytes": ram_avail, "vram_label": _human_gb(budget.total_device_bytes),
+        "uma": budget.uma, "vram_total_bytes": budget.total_device_bytes, "vram_usable_bytes": budget.usable_vram_bytes,
+        "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).
+    # 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"],
+            [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["gpu_name"] = name
-            out["gpu_util_percent"] = int(util)
-            out["vram_used_bytes"] = int(used_mib) << 20
+            out.update(gpu_name=name, gpu_util_percent=int(util), vram_used_bytes=int(used_mib) << 20)
     except Exception:  # noqa: BLE001
         pass
     return out
@@ -557,118 +517,106 @@ def local_models_hardware():
 # ── 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"),
-    "best-fits": ("Recommended build ({quant}) — the quant class this "
-                  "engine is optimized for; runs fully on your GPU"),
+    "best-large-window": ("Recommended build ({quant}) — the quant class this engine is optimized for; "
+                          "runs fully on your GPU with a large context window"),
+    "best-fits": ("Recommended build ({quant}) — the quant class this engine is optimized for; "
+                  "runs fully on your GPU"),
 }
-_QUANT_REASON_COMPACT = ("Compact build sized for this machine ({quant}) — "
-                         "larger than GPU memory, runs slower")
+_QUANT_REASON_COMPACT = "Compact build sized for this machine ({quant}) — larger than GPU memory, runs slower"
+
+
+def _catalog_row(entry, budget, recommended, recommended_reason, staged_ids) -> Dict[str, Any]:
+    choice = catalog.select_variant(entry, budget)
+    # Any variant of this family on disk counts as downloaded.
+    dl = next((v for v in entry.variants if v.model_id in staged_ids), None)
+    row: Dict[str, Any] = {
+        "id": entry.id, "display_name": entry.display_name, "description": entry.description,
+        "native_context": entry.n_ctx_train, "native_context_label": _k_label(entry.n_ctx_train),
+        "recommended": entry.id == recommended,
+        "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).
+        "needs_engine": _engine_too_old(entry.min_engine),
+        "min_engine": entry.min_engine or None,
+    }
+    if choice is None:
+        smallest = min(entry.variants, key=lambda v: v.size_bytes)
+        smallest_total = entry.download_bytes(smallest)
+        row.update({
+            "fits": False, "size_bytes": smallest_total, "size_label": _human_gb(smallest_total),
+            "fit_summary": "Needs more memory than this machine has",
+            "fit_detail": (f"even the most compact build ({smallest.quant}, {_human_gb(smallest_total)}) "
+                           "exceeds GPU + system memory"),
+        })
+        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.
+    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))
+    decision = context_policy.initial_window(entry.profile(variant), budget, overhead_bytes=overhead)
+    download_total = entry.download_bytes(variant)
+    row.update({
+        "fits": True, "model_id": variant.model_id, "quant": variant.quant,
+        "quant_validated": variant.validated, "size_bytes": download_total,
+        "size_label": _human_gb(download_total), "variant_count": len(entry.variants),
+        "quant_reason": _QUANT_REASONS.get(choice.reason_key, _QUANT_REASON_COMPACT).format(quant=variant.quant),
+    })
+    if isinstance(decision, estimator.PhysicsRefusal):
+        row["fit_summary"] = row["quant_reason"]
+        return row
+    row.update(start_window=decision.window, start_window_label=_k_label(decision.window), spilled=decision.spilled)
+    if decision.window >= entry.n_ctx_train:
+        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
+    return row
 
 
 @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. 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).
+    """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.
+    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).
     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.
     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
     # 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())
-    entries = []
-    for entry in catalog.CATALOG:
-        choice = catalog.select_variant(entry, budget)
-        # Any variant of this family on disk counts as downloaded.
-        dl = next((v for v in entry.variants if v.model_id in staged_ids), None)
-        row: Dict[str, Any] = {
-            "id": entry.id, "display_name": entry.display_name, "description": entry.description,
-            "native_context": entry.n_ctx_train,
-            "native_context_label": f"{entry.n_ctx_train // 1024}K",
-            "recommended": entry.id == recommended,
-            "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).
-            "needs_engine": _engine_too_old(entry.min_engine),
-            "min_engine": entry.min_engine or None,
-        }
-        if choice is None:
-            smallest = min(entry.variants, key=lambda v: v.size_bytes)
-            smallest_total = entry.download_bytes(smallest)
-            row.update({
-                "fits": False, "size_bytes": smallest_total, "size_label": _human_gb(smallest_total),
-                "fit_summary": "Needs more memory than this machine has",
-                "fit_detail": (f"even the most compact build ({smallest.quant}, "
-                               f"{_human_gb(smallest_total)}) exceeds GPU + system memory"),
-            })
-            entries.append(row)
-            continue
-
-        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.
-        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))
-        decision = context_policy.initial_window(entry.profile(variant), budget, overhead_bytes=overhead)
-        download_total = entry.download_bytes(variant)
-        row.update({
-            "fits": True, "model_id": variant.model_id, "quant": variant.quant,
-            "quant_validated": variant.validated, "size_bytes": download_total,
-            "size_label": _human_gb(download_total), "variant_count": len(entry.variants),
-            "quant_reason": _QUANT_REASONS.get(
-                choice.reason_key, _QUANT_REASON_COMPACT).format(quant=variant.quant),
-        })
-        if not isinstance(decision, estimator.PhysicsRefusal):
-            row["start_window"] = decision.window
-            row["start_window_label"] = f"{decision.window // 1024}K"
-            row["spilled"] = decision.spilled
-            if decision.window >= entry.n_ctx_train:
-                shape = f"runs at its full {row['native_context_label']} context"
-            else:
-                shape = (f"starts at {row['start_window_label']} and grows toward "
-                         f"{row['native_context_label']} as you use it")
-            if decision.spilled:
-                shape += " (larger than your GPU memory — runs slower)"
-            row["fit_summary"] = shape
-        else:
-            row["fit_summary"] = row["quant_reason"]
-        entries.append(row)
-    return {"models": entries}
+    return {"models": [_catalog_row(e, budget, recommended, 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:
@@ -686,53 +634,39 @@ def _runtime_progress_hook(job: Dict[str, Any]):
             state["asset_total"] = total or done
             plan_done = state["banked"] + done
             plan_total = state["banked"] + (total or 0)
-            job["phase"] = "downloading-runtime"
-            job["detail"] = f"Downloading the local engine{suffix} — {_human_gb(plan_done)}"
-            if total:
-                job["detail"] += f" of {_human_gb(plan_total)}"
+            _step(job, "downloading-runtime", f"Downloading the local engine{suffix} — {_human_gb(plan_done)}"
+                  + (f" of {_human_gb(plan_total)}" if total else ""))
             job["done_bytes"] = plan_done
             job["total_bytes"] = plan_total or None
         elif stage == "extract":
-            job["phase"] = "unpacking-runtime"
             pct = f" — {min(100, round(done / total * 100))}%" if total else ""
-            job["detail"] = f"Unpacking the engine{suffix}{pct}"
+            _step(job, "unpacking-runtime", f"Unpacking the engine{suffix}{pct}")
         else:  # verify
-            job["phase"] = "verifying-runtime"
-            job["detail"] = f"Verifying the engine{suffix}"
+            _step(job, "verifying-runtime", f"Verifying the engine{suffix}")
 
     return hook
 
 
 @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)
-    # Resolve first so an impossible combination fails the POST, not the job.
-    try:
-        plan = binaries.resolve_assets(tag, backend)
-    except Exception as exc:  # noqa: BLE001
-        raise HTTPException(status_code=400, detail=str(exc))
-
+    plan = _resolve_assets_or_400(tag, backend)
     job = _job("runtime-install", f"llama.cpp {tag} ({backend})")
 
     def _run():
-
         previous = binaries.installed_tags()
-        job["phase"] = "downloading"
-        job["detail"] = f"Fetching {len(plan.assets)} package(s) for {backend}"
+        _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.
+        # 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:
-                job["phase"] = "restarting"
-                job["detail"] = "Switching the running server to the new build"
+                _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
@@ -740,46 +674,49 @@ async def local_models_runtime_install(body: RuntimeInstallBody):
             # The new build is installed either way; the next boot serves it.
             logger.warning("post-update restart skipped: %s", exc)
 
-        # 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 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 ""))
+        _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")
     return {"job_id": job["job_id"], "backend": backend, "tag": tag}
 
 
 # ── model download (job with byte progress) ──────────────────
-
-
 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)
+
+
 @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."""
-
+    """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} "
-                        f"or newer — update the engine first"))
+            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")
+            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)
@@ -792,130 +729,101 @@ async def local_models_download(body: ModelDownloadBody):
         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 = _job("model-download", f"{entry.display_name} ({variant.quant})", model_id=entry.id)
     job["total_bytes"] = sum(p[2] for p in plan)
-
-    def _run():
-        _run_download_plan(job, plan, entry.display_name)
-        _finish(job, f"{entry.display_name} ready")
-        _refresh_runtime("post-download runtime refresh skipped")
-
-    _spawn_job(job, "lr-model-download", _run, fail_msg="model download failed: %s")
+    _download_job(job, lambda: _run_download_plan(job, plan, entry.display_name),
+                  "lr-model-download", entry.display_name, fail_msg="model download failed: %s")
     return {"job_id": job["job_id"], "model_id": variant.model_id}
 
 
 @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 instead of inheriting a stale grown one.
     try:
-
         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()
+    threading.Thread(target=_refresh_runtime, args=("post-delete runtime refresh skipped",), daemon=True,
+                     name="lr-post-delete").start()
     return {"ok": True}
 
 
-# ── server lifecycle: turn the engine on/off ─────────────────
-
-
-class ServerActionBody(BaseModel):
-    action: str                 # "stop" | "start"
-
-
 # ── 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.
+# 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()
 
 
-@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."""
-
-    # Resolve the target entry: explicit id, else this machine's
-    # recommendation, else the first catalog entry this machine can serve.
-    budget = hardware.probe_budget(planning=True)
+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."""
     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}")
+            raise HTTPException(status_code=404, detail=f"unknown model {body.model_id}")
         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]
-    chosen = None
+        candidates = ([best] if best is not None else []) + [e for e in catalog.CATALOG if best is None or e.id != best.id]
     for candidate in candidates:
         choice = catalog.select_variant(candidate, budget)
         if choice is not None and not _engine_too_old(candidate.min_engine):
-            chosen = (candidate, choice.variant)
-            break
-    if chosen is None:
-        raise HTTPException(
-            status_code=409,
-            detail="no catalog model fits this machine — open Local Models "
-                   "to browse for a smaller build")
-    entry, variant = chosen
+            return candidate, choice.variant
+    raise HTTPException(status_code=409, detail=(
+        "no catalog model fits this machine — open Local Models to browse for a smaller build"))
+
+
+@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."""
+    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)
     need_runtime = not binaries.installed_tags()
     if need_runtime:
-        # Same preflight as /runtime/install: impossible combos fail the POST.
-        try:
-            binaries.resolve_assets(tag, backend)
-        except Exception as exc:  # noqa: BLE001
-            raise HTTPException(status_code=400, detail=str(exc))
+        _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")
+        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
 
     def _run():
         if need_runtime:
-
-            job["phase"] = "installing-runtime"
-            job["detail"] = "Installing the local engine"
+            _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 before download.
             job["done_bytes"] = 0
             job["total_bytes"] = download_bytes
             _run_download_plan(job, download_plan, entry.display_name)
@@ -928,24 +836,25 @@ async def local_models_quickstart(body: QuickstartBody):
         _assign_default(job, variant.model_id)
         _finish(job, f"{entry.display_name} is ready — new chats use it")
 
-    _spawn_job(job, "lr-quickstart", _run, fail_msg="quickstart failed: %s",
-               on_exit=_QUICKSTART_LOCK.release)
+    _spawn_job(job, "lr-quickstart", _run, fail_msg="quickstart failed: %s", on_exit=_QUICKSTART_LOCK.release)
     return {"job_id": job["job_id"], "model_id": entry.id, "display_name": entry.display_name,
-            "needs_runtime": need_runtime, "needs_download": need_download,
-            "download_bytes": download_bytes}
+            "needs_runtime": need_runtime, "needs_download": need_download, "download_bytes": download_bytes}
+
+
+# ── server lifecycle: turn the engine on/off ─────────────────
+class ServerActionBody(BaseModel):
+    action: str                 # "stop" | "start"
 
 
 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.
+        # 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):
@@ -957,11 +866,7 @@ def _stop_server() -> None:
 
 
 def _start_server() -> None:
-
-    sup = bootstrap.ensure_local_runtime(_set_runtime_enabled(True), force=True)
-    if sup is None and _state_endpoint() is None:
-        raise RuntimeError("The local server could not start — check the "
-                           "runtime is installed")
+    _start_local_server(_set_runtime_enabled(True), "The local server could not start — check the runtime is installed")
 
 
 _SERVER_ACTIONS = {"stop": _stop_server, "start": _start_server}
@@ -969,51 +874,41 @@ _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'")
-    try:
+    with _http_error(502):
         await asyncio.to_thread(_SERVER_ACTIONS[action])
-    except Exception as exc:  # noqa: BLE001
-        raise HTTPException(status_code=502, detail=str(exc)) from exc
     return {"ok": True, "action": action}
 
 
 # ── activate: make a downloaded model THE model ──────────────
-
-
 class ModelEjectBody(BaseModel):
     model_id: str
 
 
 @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:
-        try:
+        with _http_error(502):
             sup.unload_model(body.model_id)
-            return {"ok": True}
-        except Exception as exc:  # noqa: BLE001
-            raise HTTPException(status_code=502, detail=str(exc)) from exc
+        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")
-    try:
-        _router_request(endpoint, "/models/unload", timeout=120,
-                        payload={"model": body.model_id})
-        return {"ok": True}
-    except Exception as exc:  # noqa: BLE001
-        raise HTTPException(status_code=502, detail=str(exc)) from exc
+    with _http_error(502):
+        _router_request(endpoint, "/models/unload", timeout=120, payload={"model": body.model_id})
+    return {"ok": True}
 
 
 class ModelActivateBody(BaseModel):
@@ -1022,25 +917,22 @@ class ModelActivateBody(BaseModel):
 
 @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")
 
     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")
-        job["phase"] = "setting-default"
-        job["detail"] = "Making it your default"
+        _step(job, "setting-default", "Making it your default")
         _set_runtime_enabled(True)
         _assign_default(job, body.model_id)
         _finish(job, f"{body.model_id} is the default for new chats")
@@ -1050,15 +942,12 @@ 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 the app-level poller rediscover
+    in-flight work here after a remount or app restart."""
     with _JOBS_LOCK:
-        jobs = sorted(_JOBS.values(),
-                      key=lambda j: (j["status"] != "running", -j["started_at"]))
+        jobs = sorted(_JOBS.values(), key=lambda j: (j["status"] != "running", -j["started_at"]))
     return {"jobs": [_job_view(job) for job in jobs[:20]]}
 
 
@@ -1072,36 +961,22 @@ 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;
+    per-quant fit pills come from the repo-files call."""
     if not q.strip():
         return {"hits": []}
-    try:
-        hits = await run_in_threadpool(hf_browse.search_models, q, limit)
-    except Exception as exc:  # noqa: BLE001
-        raise HTTPException(status_code=502,
-                            detail=f"Hugging Face search unavailable: {exc}") from exc
-    return {"hits": [h.__dict__ for h in hits]}
+    with _http_error(502, "Hugging Face search unavailable: "):
+        return {"hits": [h.__dict__ for h in await run_in_threadpool(hf_browse.search_models, q, limit)]}
 
 
 @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)."""
-
-
-    try:
-        groups = await run_in_threadpool(
-            hf_browse.priced_repo_files, repo, hardware.probe_budget(planning=True))
-    except Exception as exc:  # noqa: BLE001
-        raise HTTPException(status_code=502,
-                            detail=f"Could not list {repo}: {exc}") from exc
+    """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]}
 
 
@@ -1112,37 +987,32 @@ class BrowsedDownloadBody(BaseModel):
 
 @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")
     first = paths[0].rsplit("/", 1)[-1]
-    model_id = re.sub(r"-\d{5}-of-\d{5}\.gguf$", "", first, flags=re.IGNORECASE)
+    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
     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)
+    job = _job("model-download", f"{model_id} (from {body.repo})", model_id=model_id)
 
-    def _run():
+    def _fetch():
         job["phase"] = "downloading"
         for p in paths:
             dest = _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")))
+                          base_done=int(job.get("done_bytes") or 0), keep_totals=bool(job.get("total_bytes")))
             job["phase"] = "downloading"
-        _finish(job, f"{model_id} ready")
-        _refresh_runtime("post-download runtime refresh skipped")
 
-    _spawn_job(job, "lm-download-browsed", _run)
+    _download_job(job, _fetch, "lm-download-browsed", model_id)
     return {"job_id": job["job_id"], "model_id": model_id}
 
 
@@ -1152,10 +1022,9 @@ class SideloadBody(BaseModel):
 
 @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")
diff --git a/hermes_cli/web_routers/messaging.py b/hermes_cli/web_routers/messaging.py
index 455bfc26d0..05362bfad2 100644
--- a/hermes_cli/web_routers/messaging.py
+++ b/hermes_cli/web_routers/messaging.py
@@ -1,36 +1,40 @@
 """Messaging dashboard routes: WhatsApp/Telegram onboarding and per-platform enable/config/test.
 
 Extracted from ``hermes_cli.web_server``; helpers/state that tests monkeypatch on
-``web_server`` stay there and are imported lazily at call time (cycle-safe).
+``web_server`` stay there and are resolved late at call time (cycle-safe).
 """
 
+import asyncio
+import contextlib
+import json
 import logging
+import os
 import re
+import secrets
 import subprocess
 import threading
-import asyncio
-import json
-import secrets
 import time
 import urllib.parse
-import os
 from datetime import datetime, timezone
-from fastapi import APIRouter
-from hermes_cli.web_deps import late
-from fastapi import HTTPException
-from hermes_cli._subprocess_compat import windows_hide_flags
-from hermes_cli.config import get_env_path
-from hermes_cli.web_models import MessagingPlatformUpdate, TelegramOnboardingStart, TelegramOnboardingApply, WhatsAppOnboardingStart, WhatsAppOnboardingApply
 from pathlib import Path
 from typing import Any, Optional
-from hermes_cli.config import redact_key
+
+from fastapi import APIRouter, HTTPException
+
 from gateway.status import resolve_gateway_liveness
-from hermes_cli.config import OPTIONAL_ENV_VARS
+from hermes_cli._subprocess_compat import windows_hide_flags
+from hermes_cli.config import OPTIONAL_ENV_VARS, get_env_path, redact_key
+from hermes_cli.web_deps import LateState, late
+from hermes_cli.web_routers._common import http_failure
+from hermes_cli.web_models import (
+    MessagingPlatformUpdate, TelegramOnboardingApply, TelegramOnboardingStart,
+    WhatsAppOnboardingApply, WhatsAppOnboardingStart,
+)
 
 _log = logging.getLogger("hermes_cli.web_server")
 router = APIRouter()
 
-# web_server helpers, late-bound so monkeypatch.setattr(web_server, ...) stays authoritative.
+# web_server helpers/state, late-bound so monkeypatch.setattr(web_server, ...) stays authoritative.
 _config_profile_scope = late("_config_profile_scope")
 _messaging_platform_catalog = late("_messaging_platform_catalog")
 _profile_scope = late("_profile_scope")
@@ -43,164 +47,103 @@ _whatsapp_onboarding_payload = late("_whatsapp_onboarding_payload")
 _whatsapp_session_path = late("_whatsapp_session_path")
 _write_platform_enabled = late("_write_platform_enabled")
 load_env = late("load_env")
+load_config = late("load_config")
 read_runtime_status = late("read_runtime_status")
 remove_env_value = late("remove_env_value")
 save_env_value = late("save_env_value")
 _gateway_subcommand = late("_gateway_subcommand")
 _probe_gateway_health = late("_probe_gateway_health")
+get_running_pid_cached = late("get_running_pid_cached")
+get_runtime_status_running_pid = late("get_runtime_status_running_pid")
+_WhatsAppOnboardingSession = late("_WhatsAppOnboardingSession")
+_TelegramOnboardingPairing = late("_TelegramOnboardingPairing")
+_GATEWAY_HEALTH_URL = LateState("_GATEWAY_HEALTH_URL")
+_whatsapp_onboarding_sessions = LateState("_whatsapp_onboarding_sessions")
+_telegram_onboarding_lock = LateState("_telegram_onboarding_lock")
+_telegram_onboarding_pairings = LateState("_telegram_onboarding_pairings")
 
 
 # Display labels for env vars not in OPTIONAL_ENV_VARS (HOME_CHANNEL_*, bridge
-# toggles, Twilio, HASS, Email, etc.). Anything missing from OPTIONAL_ENV_VARS
-# falls back here so the UI can still render a friendly label.
+# toggles, Twilio, HASS, Email, etc.) so the UI can still render a friendly label.
+# (key, description, prompt, extra flags: url / password / advanced)
 _MESSAGING_ENV_FALLBACKS: dict[str, dict[str, Any]] = {
-    "SIGNAL_HTTP_URL": {
-        "description": "signal-cli REST API base URL, e.g. http://127.0.0.1:8080",
-        "prompt": "Signal bridge URL",
-        "url": "https://github.com/bbernhard/signal-cli-rest-api",
-    },
-    "SIGNAL_ACCOUNT": {
-        "description": "Signal account phone number registered with the bridge",
-        "prompt": "Signal account",
-    },
-    "SIGNAL_ALLOWED_USERS": {
-        "description": "Comma-separated Signal users allowed to use the bot",
-        "prompt": "Allowed Signal users",
-    },
-    "WHATSAPP_ENABLED": {
-        "description": "Enable the WhatsApp gateway adapter",
-        "prompt": "Enable WhatsApp",
-        "advanced": True,
-    },
-    "WHATSAPP_MODE": {
-        "description": "WhatsApp bridge mode",
-        "prompt": "WhatsApp mode",
-        "advanced": True,
-    },
-    "WHATSAPP_DM_POLICY": {
-        "description": "How WhatsApp direct messages are authorized",
-        "prompt": "WhatsApp DM policy",
-        "advanced": True,
-    },
-    "WHATSAPP_ALLOWED_USERS": {
-        "description": "Comma-separated WhatsApp users allowed to use the bot",
-        "prompt": "Allowed WhatsApp users",
-    },
-    "HASS_URL": {
-        "description": "Home Assistant base URL, e.g. https://homeassistant.local:8123",
-        "prompt": "Home Assistant URL",
-    },
-    "HASS_TOKEN": {
-        "description": "Long-lived access token from Home Assistant (Profile → Security)",
-        "prompt": "Home Assistant access token",
-        "password": True,
-    },
-    "EMAIL_ADDRESS": {
-        "description": "Email address to send and receive from",
-        "prompt": "Email address",
-    },
-    "EMAIL_PASSWORD": {
-        "description": "Email account password or app password",
-        "prompt": "Email password",
-        "password": True,
-    },
-    "EMAIL_IMAP_HOST": {
-        "description": "IMAP server host (e.g. imap.gmail.com)",
-        "prompt": "IMAP host",
-    },
-    "EMAIL_SMTP_HOST": {
-        "description": "SMTP server host (e.g. smtp.gmail.com)",
-        "prompt": "SMTP host",
-    },
-    "TWILIO_ACCOUNT_SID": {
-        "description": "Twilio Account SID",
-        "prompt": "Twilio Account SID",
-        "url": "https://www.twilio.com/console",
-    },
-    "TWILIO_AUTH_TOKEN": {
-        "description": "Twilio Auth Token",
-        "prompt": "Twilio Auth Token",
-        "password": True,
-    },
-    "WECOM_BOT_ID": {"description": "WeCom group bot ID", "prompt": "WeCom Bot ID"},
-    "WECOM_SECRET": {
-        "description": "WeCom group bot secret",
-        "prompt": "WeCom Secret",
-        "password": True,
-    },
-    "WECOM_CALLBACK_CORP_ID": {
-        "description": "WeCom corp ID",
-        "prompt": "WeCom Corp ID",
-    },
-    "WECOM_CALLBACK_CORP_SECRET": {
-        "description": "WeCom app corp secret",
-        "prompt": "WeCom Corp Secret",
-        "password": True,
-    },
-    "WECOM_CALLBACK_AGENT_ID": {
-        "description": "WeCom app agent ID",
-        "prompt": "WeCom Agent ID",
-    },
-    "WECOM_CALLBACK_TOKEN": {
-        "description": "WeCom callback verification token",
-        "prompt": "WeCom Token",
-    },
-    "WECOM_CALLBACK_ENCODING_AES_KEY": {
-        "description": "WeCom callback AES encoding key",
-        "prompt": "WeCom AES Key",
-        "password": True,
-    },
-    "WEIXIN_ACCOUNT_ID": {
-        "description": "iLink Bot account ID obtained through QR login in hermes gateway setup",
-        "prompt": "iLink Bot account ID",
-    },
-    "WEIXIN_TOKEN": {
-        "description": "iLink Bot token obtained through QR login in hermes gateway setup",
-        "prompt": "iLink Bot token",
-        "password": True,
-    },
-    "WEIXIN_BASE_URL": {
-        "description": "iLink API base URL saved by QR login (default: https://ilinkai.weixin.qq.com)",
-        "prompt": "iLink API base URL",
-    },
-    "FEISHU_APP_ID": {"description": "Feishu / Lark app ID", "prompt": "App ID"},
-    "FEISHU_APP_SECRET": {
-        "description": "Feishu / Lark app secret",
-        "prompt": "App secret",
-        "password": True,
-    },
-    "FEISHU_ENCRYPT_KEY": {
-        "description": "Feishu / Lark encrypt key",
-        "prompt": "Encrypt key",
-        "password": True,
-    },
-    "FEISHU_VERIFICATION_TOKEN": {
-        "description": "Feishu / Lark verification token",
-        "prompt": "Verification token",
-        "password": True,
-    },
-    "DINGTALK_CLIENT_ID": {
-        "description": "DingTalk client ID (App key)",
-        "prompt": "Client ID",
-    },
-    "DINGTALK_CLIENT_SECRET": {
-        "description": "DingTalk client secret (App secret)",
-        "prompt": "Client secret",
-        "password": True,
-    },
+    key: {"description": description, "prompt": prompt, **extra}
+    for key, description, prompt, extra in (
+        ("SIGNAL_HTTP_URL", "signal-cli REST API base URL, e.g. http://127.0.0.1:8080", "Signal bridge URL", {"url": "https://github.com/bbernhard/signal-cli-rest-api"}),
+        ("SIGNAL_ACCOUNT", "Signal account phone number registered with the bridge", "Signal account", {}),
+        ("SIGNAL_ALLOWED_USERS", "Comma-separated Signal users allowed to use the bot", "Allowed Signal users", {}),
+        ("WHATSAPP_ENABLED", "Enable the WhatsApp gateway adapter", "Enable WhatsApp", {"advanced": True}),
+        ("WHATSAPP_MODE", "WhatsApp bridge mode", "WhatsApp mode", {"advanced": True}),
+        ("WHATSAPP_DM_POLICY", "How WhatsApp direct messages are authorized", "WhatsApp DM policy", {"advanced": True}),
+        ("WHATSAPP_ALLOWED_USERS", "Comma-separated WhatsApp users allowed to use the bot", "Allowed WhatsApp users", {}),
+        ("HASS_URL", "Home Assistant base URL, e.g. https://homeassistant.local:8123", "Home Assistant URL", {}),
+        ("HASS_TOKEN", "Long-lived access token from Home Assistant (Profile → Security)", "Home Assistant access token", {"password": True}),
+        ("EMAIL_ADDRESS", "Email address to send and receive from", "Email address", {}),
+        ("EMAIL_PASSWORD", "Email account password or app password", "Email password", {"password": True}),
+        ("EMAIL_IMAP_HOST", "IMAP server host (e.g. imap.gmail.com)", "IMAP host", {}),
+        ("EMAIL_SMTP_HOST", "SMTP server host (e.g. smtp.gmail.com)", "SMTP host", {}),
+        ("TWILIO_ACCOUNT_SID", "Twilio Account SID", "Twilio Account SID", {"url": "https://www.twilio.com/console"}),
+        ("TWILIO_AUTH_TOKEN", "Twilio Auth Token", "Twilio Auth Token", {"password": True}),
+        ("WECOM_BOT_ID", "WeCom group bot ID", "WeCom Bot ID", {}),
+        ("WECOM_SECRET", "WeCom group bot secret", "WeCom Secret", {"password": True}),
+        ("WECOM_CALLBACK_CORP_ID", "WeCom corp ID", "WeCom Corp ID", {}),
+        ("WECOM_CALLBACK_CORP_SECRET", "WeCom app corp secret", "WeCom Corp Secret", {"password": True}),
+        ("WECOM_CALLBACK_AGENT_ID", "WeCom app agent ID", "WeCom Agent ID", {}),
+        ("WECOM_CALLBACK_TOKEN", "WeCom callback verification token", "WeCom Token", {}),
+        ("WECOM_CALLBACK_ENCODING_AES_KEY", "WeCom callback AES encoding key", "WeCom AES Key", {"password": True}),
+        ("WEIXIN_ACCOUNT_ID", "iLink Bot account ID obtained through QR login in hermes gateway setup", "iLink Bot account ID", {}),
+        ("WEIXIN_TOKEN", "iLink Bot token obtained through QR login in hermes gateway setup", "iLink Bot token", {"password": True}),
+        ("WEIXIN_BASE_URL", "iLink API base URL saved by QR login (default: https://ilinkai.weixin.qq.com)", "iLink API base URL", {}),
+        ("FEISHU_APP_ID", "Feishu / Lark app ID", "App ID", {}),
+        ("FEISHU_APP_SECRET", "Feishu / Lark app secret", "App secret", {"password": True}),
+        ("FEISHU_ENCRYPT_KEY", "Feishu / Lark encrypt key", "Encrypt key", {"password": True}),
+        ("FEISHU_VERIFICATION_TOKEN", "Feishu / Lark verification token", "Verification token", {"password": True}),
+        ("DINGTALK_CLIENT_ID", "DingTalk client ID (App key)", "Client ID", {}),
+        ("DINGTALK_CLIENT_SECRET", "DingTalk client secret (App secret)", "Client secret", {"password": True}),
+    )
 }
 
 
 # Kept in sync with the corresponding frontend validation in ChannelsPage.tsx.
 _TELEGRAM_BOT_TOKEN_RE = re.compile(r"\d+:[A-Za-z0-9_-]{30,}")
-
-
 _TELEGRAM_USER_ID_RE = re.compile(r"\d+")
-
-
 _SLACK_MEMBER_ID_RE = re.compile(r"[UW][A-Z0-9]{2,}")
 
 
+def _csv_ids(value: str) -> list[str]:
+    """Split like the gateway parsers do (gateway/platforms/*.py): comma, strip,
+    drop empties — so a trailing/interior comma isn't rejected here when the
+    runtime would accept it."""
+    return [part.strip() for part in value.split(",") if part.strip()]
+
+
+# (platform, env key) -> (accepts(value), 400 detail). Rejects credentials that
+# are clearly in the wrong field. "*" is Slack's allow-all wildcard.
+_ENV_VALUE_RULES: dict[tuple[str, str], tuple[Any, str]] = {
+    ("telegram", "TELEGRAM_BOT_TOKEN"): (
+        _TELEGRAM_BOT_TOKEN_RE.fullmatch,
+        "Telegram bot token must be the complete token from @BotFather, such as 123456789:ABC…"),
+    ("telegram", "TELEGRAM_ALLOWED_USERS"): (
+        lambda v: all(_TELEGRAM_USER_ID_RE.fullmatch(u) for u in _csv_ids(v)),
+        "Telegram allowed users must be comma-separated numeric user IDs."),
+    ("slack", "SLACK_BOT_TOKEN"): (
+        lambda v: v.startswith("xoxb-"),
+        "Slack Bot Token must start with xoxb-. Paste the bot token from OAuth & Permissions."),
+    ("slack", "SLACK_APP_TOKEN"): (
+        lambda v: v.startswith("xapp-"),
+        "Slack App Token must start with xapp-. Paste the app-level token from Basic Information > App-Level Tokens."),
+    ("slack", "SLACK_ALLOWED_USERS"): (
+        lambda v: all(u == "*" or _SLACK_MEMBER_ID_RE.fullmatch(u) for u in _csv_ids(v)),
+        "Slack allowed user IDs must be comma-separated member IDs like U01ABC2DEF3."),
+}
+
+
+def _validate_messaging_env_value(platform_id: str, key: str, value: str) -> None:
+    rule = _ENV_VALUE_RULES.get((platform_id, key))
+    if value and rule and not rule[0](value):
+        raise HTTPException(status_code=400, detail=rule[1])
+
+
 def _messaging_env_info(key: str) -> dict[str, Any]:
     info = OPTIONAL_ENV_VARS.get(key) or _MESSAGING_ENV_FALLBACKS.get(key) or {}
     return {
@@ -213,265 +156,157 @@ def _messaging_env_info(key: str) -> dict[str, Any]:
     }
 
 
-def _gateway_platform_config(platform_id: str):
-    from gateway.config import Platform, load_gateway_config
-
-    config = load_gateway_config()
-    platform = Platform(platform_id)
-    platform_config = config.platforms.get(platform)
-    return config, platform, platform_config
-
-
-def _gateway_display_command(profile: Optional[str], verb: str) -> str:
-    return " ".join(["hermes", *_gateway_subcommand(profile, verb)])
-
-
-def _validate_messaging_env_value(platform_id: str, key: str, value: str) -> None:
-    """Reject platform credentials that are clearly in the wrong field."""
-    if not value:
-        return
-
-    if platform_id == "telegram":
-        if key == "TELEGRAM_BOT_TOKEN" and not _TELEGRAM_BOT_TOKEN_RE.fullmatch(value):
-            raise HTTPException(
-                status_code=400,
-                detail="Telegram bot token must be the complete token from @BotFather, such as 123456789:ABC…",
-            )
-        if key == "TELEGRAM_ALLOWED_USERS":
-            user_ids = [part.strip() for part in value.split(",") if part.strip()]
-            if any(not _TELEGRAM_USER_ID_RE.fullmatch(user_id) for user_id in user_ids):
-                raise HTTPException(
-                    status_code=400,
-                    detail="Telegram allowed users must be comma-separated numeric user IDs.",
-                )
-        return
-
-    if platform_id != "slack":
-        return
-
-    if key == "SLACK_BOT_TOKEN" and not value.startswith("xoxb-"):
-        raise HTTPException(
-            status_code=400,
-            detail="Slack Bot Token must start with xoxb-. Paste the bot token from OAuth & Permissions.",
-        )
-    if key == "SLACK_APP_TOKEN" and not value.startswith("xapp-"):
-        raise HTTPException(
-            status_code=400,
-            detail="Slack App Token must start with xapp-. Paste the app-level token from Basic Information > App-Level Tokens.",
-        )
-    if key == "SLACK_ALLOWED_USERS":
-        # Mirror the gateway's parse (gateway/platforms/slack.py): split on comma,
-        # strip, and drop empty entries so a trailing/interior comma isn't rejected
-        # here when the runtime would accept it. "*" is the allow-all wildcard.
-        user_ids = [part.strip() for part in value.split(",") if part.strip()]
-        invalid = [
-            user_id
-            for user_id in user_ids
-            if user_id != "*" and not _SLACK_MEMBER_ID_RE.fullmatch(user_id)
-        ]
-        if invalid:
-            raise HTTPException(
-                status_code=400,
-                detail="Slack allowed user IDs must be comma-separated member IDs like U01ABC2DEF3.",
-            )
-
-
 def _catalog_lookup(platform_id: str) -> dict[str, Any] | None:
-    for entry in _messaging_platform_catalog():
-        if entry["id"] == platform_id:
-            return entry
-    return None
+    return next((e for e in _messaging_platform_catalog() if e["id"] == platform_id), None)
 
 
-def _messaging_platform_payload(
-    entry: dict[str, Any],
-    env_on_disk: dict[str, str],
-    runtime: dict | None,
-    scoped: bool = False,
-    profile_home: Optional[Path] = None,
-) -> dict[str, Any]:
-    from hermes_cli.web_server import (
-        _GATEWAY_HEALTH_URL,
-        get_running_pid_cached,
-        get_runtime_status_running_pid,
-        load_config,
-    )
-    platform_id = entry["id"]
-    runtime_platforms = runtime.get("platforms") if runtime else {}
-    runtime_platform = (
-        runtime_platforms.get(platform_id, {})
-        if isinstance(runtime_platforms, dict)
-        else {}
-    )
-    # Same shared ladder /api/status uses. Before this was unified, the two
-    # endpoints disagreed on the same page load — the sidebar strip read
-    # "running" (it probed GATEWAY_HEALTH_URL and scoped to the requested
-    # profile) while the Channels page rendered "The gateway is not running"
-    # (it did neither). Cross-container, profile-scoped, and
-    # launch-service-managed deployments each hit that split.
-    #
-    # profile_home is passed when the request was scoped to a named profile:
-    # gateway/status readers resolve process-level paths and do NOT follow the
-    # HERMES_HOME contextvar override (#56986 / #69143), so the profile's
-    # directory has to be handed over explicitly or messaging silently reports
-    # another profile's gateway (#71211).
-    liveness = resolve_gateway_liveness(
-        profile_dir=profile_home,
-        runtime=runtime,
-        health_probe=(
-            _probe_gateway_health if _GATEWAY_HEALTH_URL else None
-        ),
-        pid_probe=get_running_pid_cached,
-        runtime_reader=read_runtime_status,
-        runtime_pid_probe=get_runtime_status_running_pid,
-    )
-    gateway_running = liveness.running
-    env_vars = []
+def _require_platform(platform_id: str) -> dict[str, Any]:
+    entry = _catalog_lookup(platform_id)
+    if not entry:
+        raise HTTPException(status_code=404, detail=f"Unknown messaging platform: {platform_id}")
+    return entry
 
-    for key in entry["env_vars"]:
-        # When profile-scoped, judge only the profile's own .env — the
-        # dashboard process's os.environ carries the ROOT install's .env
-        # (loaded at startup) and would falsely report the root credentials
-        # as the profile's.
-        value = env_on_disk.get(key) or ("" if scoped else os.getenv(key, ""))
-        env_vars.append(
-            {
-                "key": key,
-                "required": key in entry["required_env"],
-                "is_set": bool(value),
-                "redacted_value": redact_key(value) if value else None,
-                **_messaging_env_info(key),
-            }
-        )
 
+def _platform_enablement(
+    platform_id: str, entry: dict[str, Any], env_on_disk: dict[str, str], scoped: bool
+) -> tuple[bool, bool, dict | None]:
+    """(enabled, configured, home_channel) for a platform.
+
+    Profile-scoped: derive from the profile's config.yaml + .env only —
+    load_gateway_config()'s env-override layer reads os.environ and would leak
+    the root install's tokens into the profile's reported state.
+    """
+    required = entry["required_env"]
     if scoped:
-        # Profile-scoped view: derive enablement/configuration from the
-        # profile's config.yaml + .env only. load_gateway_config()'s
-        # env-override layer reads os.environ and would leak the root
-        # install's tokens into the profile's reported state.
         try:
-            cfg = load_config()
-            platforms_cfg = cfg.get("platforms") or {}
-            plat_cfg = platforms_cfg.get(platform_id)
+            plat_cfg = (load_config().get("platforms") or {}).get(platform_id)
             if not isinstance(plat_cfg, dict):
                 plat_cfg = {}
             enabled = bool(plat_cfg.get("enabled"))
             hc = plat_cfg.get("home_channel")
             home_channel = hc if isinstance(hc, dict) else None
         except Exception:
-            enabled = False
-            home_channel = None
-        configured = all(env_on_disk.get(key) for key in entry["required_env"])
-    else:
-        try:
-            gateway_config, platform, platform_config = _gateway_platform_config(
-                platform_id
-            )
-            enabled = bool(platform_config and platform_config.enabled)
-            configured = bool(
-                platform_config
-                and gateway_config._is_platform_connected(platform, platform_config)
-            )
-            home_channel = (
-                platform_config.home_channel.to_dict()
-                if platform_config and platform_config.home_channel
-                else None
-            )
-        except Exception:
-            enabled = False
-            configured = all(
-                env_on_disk.get(key) or os.getenv(key, "")
-                for key in entry["required_env"]
-            )
-            home_channel = None
+            enabled, home_channel = False, None
+        return enabled, all(env_on_disk.get(key) for key in required), home_channel
+    try:
+        from gateway.config import Platform, load_gateway_config
 
-    state = (
-        runtime_platform.get("state") if isinstance(runtime_platform, dict) else None
-    )
-    runtime_gateway_state = runtime.get("gateway_state") if isinstance(runtime, dict) else None
-    runtime_gateway_error = runtime.get("exit_reason") if isinstance(runtime, dict) else None
+        gateway_config = load_gateway_config()
+        platform = Platform(platform_id)
+        platform_config = gateway_config.platforms.get(platform)
+        enabled = bool(platform_config and platform_config.enabled)
+        configured = bool(platform_config and gateway_config._is_platform_connected(platform, platform_config))
+        home_channel = platform_config.home_channel.to_dict() if platform_config and platform_config.home_channel else None
+    except Exception:
+        enabled, home_channel = False, None
+        configured = all(env_on_disk.get(key) or os.getenv(key, "") for key in required)
+    return enabled, configured, home_channel
+
+
+def _messaging_platform_payload(
+    entry: dict[str, Any], env_on_disk: dict[str, str], runtime: dict | None,
+    scoped: bool = False, profile_home: Optional[Path] = None,
+) -> dict[str, Any]:
+    platform_id = entry["id"]
+    rt = runtime if isinstance(runtime, dict) else {}
+    runtime_platforms = rt.get("platforms")
+    runtime_platform = runtime_platforms.get(platform_id, {}) if isinstance(runtime_platforms, dict) else {}
+    if not isinstance(runtime_platform, dict):
+        runtime_platform = {}
+    # Same shared liveness ladder /api/status uses, so the sidebar strip and the
+    # Channels page can never disagree on the same page load. profile_home is
+    # passed when scoped to a named profile: gateway/status readers resolve
+    # process-level paths and do NOT follow the HERMES_HOME contextvar override,
+    # so the profile's directory is handed over explicitly or messaging silently
+    # reports another profile's gateway.
+    gateway_running = resolve_gateway_liveness(
+        profile_dir=profile_home, runtime=runtime,
+        health_probe=_probe_gateway_health if _GATEWAY_HEALTH_URL else None,
+        pid_probe=get_running_pid_cached, runtime_reader=read_runtime_status,
+        runtime_pid_probe=get_runtime_status_running_pid,
+    ).running
+
+    def env_value(key: str) -> str:
+        # When profile-scoped, judge only the profile's own .env — the dashboard
+        # process's os.environ carries the ROOT install's .env (loaded at startup)
+        # and would falsely report the root credentials as the profile's.
+        return env_on_disk.get(key) or ("" if scoped else os.getenv(key, ""))
+
+    env_vars = [
+        {
+            "key": key, "required": key in entry["required_env"], "is_set": bool(value),
+            "redacted_value": redact_key(value) if value else None, **_messaging_env_info(key),
+        }
+        for key, value in ((key, env_value(key)) for key in entry["env_vars"])
+    ]
+
+    enabled, configured, home_channel = _platform_enablement(platform_id, entry, env_on_disk, scoped)
+
+    state = runtime_platform.get("state")
     if not enabled:
         state = "disabled"
     elif not configured:
         state = "not_configured"
     elif gateway_running and not state:
         state = "pending_restart"
-    elif (
-        not gateway_running
-        and not state
-        and runtime_gateway_state == "startup_failed"
-    ):
-        state = "startup_failed"
     elif not gateway_running and not state:
-        state = "gateway_stopped"
+        state = "startup_failed" if rt.get("gateway_state") == "startup_failed" else "gateway_stopped"
 
-    error_code = (
-        runtime_platform.get("error_code")
-        if isinstance(runtime_platform, dict)
-        else None
-    )
-    error_message = (
-        runtime_platform.get("error_message")
-        if isinstance(runtime_platform, dict)
-        else None
-    )
+    error_code = runtime_platform.get("error_code")
+    error_message = runtime_platform.get("error_message")
     if state == "startup_failed":
         error_code = error_code or "startup_failed"
-        error_message = error_message or runtime_gateway_error
-
-    whatsapp_setup = None
-    if platform_id == "whatsapp":
-        whatsapp_mode = (
-            env_on_disk.get("WHATSAPP_MODE")
-            or ("" if scoped else os.getenv("WHATSAPP_MODE", ""))
-        ).strip()
-        allowed_users_value = (
-            env_on_disk.get("WHATSAPP_ALLOWED_USERS")
-            or ("" if scoped else os.getenv("WHATSAPP_ALLOWED_USERS", ""))
-        ).strip()
-        whatsapp_setup = {
-            "mode": whatsapp_mode if whatsapp_mode in {"bot", "self-chat"} else "",
-            "allowed_users_set": bool(allowed_users_value),
-            "home_channel_set": bool(home_channel),
-        }
+        error_message = error_message or rt.get("exit_reason")
 
     payload = {
-        "id": platform_id,
-        "name": entry["name"],
-        "description": entry["description"],
-        "docs_url": entry["docs_url"],
-        "enabled": enabled,
-        "configured": configured,
-        "gateway_running": gateway_running,
-        "state": state,
-        "error_code": error_code,
-        "error_message": error_message,
-        "updated_at": (
-            runtime_platform.get("updated_at")
-            if isinstance(runtime_platform, dict)
-            else None
-        ),
-        "home_channel": home_channel,
-        "env_vars": env_vars,
+        "id": platform_id, "name": entry["name"], "description": entry["description"],
+        "docs_url": entry["docs_url"], "enabled": enabled, "configured": configured,
+        "gateway_running": gateway_running, "state": state, "error_code": error_code,
+        "error_message": error_message, "updated_at": runtime_platform.get("updated_at"),
+        "home_channel": home_channel, "env_vars": env_vars,
     }
-    if whatsapp_setup is not None:
-        payload["whatsapp_setup"] = whatsapp_setup
+    if platform_id == "whatsapp":
+        whatsapp_mode = env_value("WHATSAPP_MODE").strip()
+        payload["whatsapp_setup"] = {
+            "mode": whatsapp_mode if whatsapp_mode in {"bot", "self-chat"} else "",
+            "allowed_users_set": bool(env_value("WHATSAPP_ALLOWED_USERS").strip()),
+            "home_channel_set": bool(home_channel),
+        }
     return payload
 
 
+def _platform_payloads(scoped_dir: Optional[Path], entries) -> list[dict[str, Any]]:
+    """Payloads for ``entries``; call inside ``_profile_scope`` (load_env honors the
+    HERMES_HOME contextvar; the gateway status readers do not, hence the explicit path)."""
+    env_on_disk = load_env()
+    runtime = read_runtime_status(path=scoped_dir / "gateway_state.json") if scoped_dir is not None else read_runtime_status()
+    return [_messaging_platform_payload(entry, env_on_disk, runtime, scoped=scoped_dir is not None, profile_home=scoped_dir)
+            for entry in entries]
+
+
+@contextlib.contextmanager
+def _onboarding_save_errors(log_msg: str, detail: str):
+    """Map onboarding env/config write failures: ValueError -> 400 (its text),
+    anything else -> logged + fixed 500 ``detail``; HTTPException passes through."""
+    try:
+        yield
+    except HTTPException:
+        raise
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except Exception as exc:
+        _log.exception(log_msg)
+        raise HTTPException(status_code=500, detail=detail) from exc
+
+
+# ── WhatsApp QR onboarding ─────────────────────────────────────
+
 _WHATSAPP_ONBOARDING_TTL_SECONDS = 600
-
-
 _WHATSAPP_ONBOARDING_TERMINAL_STATUSES = {"connected", "error", "expired", "cancelled"}
-
-
+_WHATSAPP_SESSION_NOT_FOUND = "WhatsApp setup session was not found. Start a new setup."
 _whatsapp_onboarding_lock = threading.RLock()
 
 
-def _utc_iso_from_ts(ts: float) -> str:
-    return datetime.fromtimestamp(ts, timezone.utc).isoformat().replace("+00:00", "Z")
-
-
 def _normalize_whatsapp_onboarding_mode(value: Any) -> str:
     mode = str(value or "bot").strip().lower()
     if mode not in {"bot", "self-chat"}:
@@ -490,41 +325,24 @@ def _whatsapp_phone_from_identifier(value: Any) -> str | None:
     raw = str(value or "").strip()
     if not raw:
         return None
-    candidate = raw.split("@", 1)[0].split(":", 1)[0]
-    digits = re.sub(r"\D+", "", candidate)
+    digits = re.sub(r"\D+", "", raw.split("@", 1)[0].split(":", 1)[0])
     return digits or None
 
 
+def _first_str(candidate: Any, keys: tuple[str, ...]) -> str | None:
+    if not isinstance(candidate, dict):
+        return None
+    return next((v for v in (str(candidate.get(k) or "").strip() for k in keys) if v), None)
+
+
 def _whatsapp_linked_account_from_session(session_path: Path) -> tuple[str | None, str | None, str | None]:
-    creds_path = session_path / "creds.json"
     try:
-        payload = json.loads(creds_path.read_text(encoding="utf-8"))
+        payload = json.loads((session_path / "creds.json").read_text(encoding="utf-8"))
     except Exception:
         return None, None, None
-
-    account_id: str | None = None
-    account_name: str | None = None
-
-    def collect(candidate: Any) -> None:
-        nonlocal account_id, account_name
-        if not isinstance(candidate, dict):
-            return
-        if account_id is None:
-            for key in ("id", "jid", "lid"):
-                value = str(candidate.get(key) or "").strip()
-                if value:
-                    account_id = value
-                    break
-        if account_name is None:
-            for key in ("name", "verifiedName", "notify", "pushName"):
-                value = str(candidate.get(key) or "").strip()
-                if value:
-                    account_name = value
-                    break
-
-    collect(payload.get("me"))
-    collect(payload.get("account"))
-    collect(payload)
+    candidates = (payload.get("me"), payload.get("account"), payload)
+    account_id = next((v for v in (_first_str(c, ("id", "jid", "lid")) for c in candidates) if v), None)
+    account_name = next((v for v in (_first_str(c, ("name", "verifiedName", "notify", "pushName")) for c in candidates) if v), None)
     return account_id, account_name, _whatsapp_phone_from_identifier(account_id)
 
 
@@ -538,45 +356,26 @@ def _ensure_whatsapp_bridge_dependencies(bridge_dir: Path) -> None:
 
     npm = find_node_executable("npm")
     if not npm:
-        raise HTTPException(
-            status_code=500,
-            detail="npm was not found. WhatsApp setup needs Node.js and npm.",
-        )
+        raise HTTPException(status_code=500, detail="npm was not found. WhatsApp setup needs Node.js and npm.")
 
-    timeout = env_int("WHATSAPP_NPM_INSTALL_TIMEOUT", 300)
     try:
+        # npm output is UTF-8; encoding= guards the Windows ANSI-code-page
+        # default against undefined bytes crashing the reader thread.
         result = subprocess.run(
-            [npm, "install", "--silent"],
-            cwd=str(bridge_dir),
-            capture_output=True,
-            text=True,
-            # npm output is UTF-8; guard the Windows ANSI-code-page default
-            # against undefined bytes crashing the reader thread (#52649).
-            encoding="utf-8",
-            errors="replace",
-            timeout=timeout,
-            env=with_hermes_node_path(),
-            creationflags=windows_hide_flags(),
+            [npm, "install", "--silent"], cwd=str(bridge_dir), capture_output=True, text=True,
+            encoding="utf-8", errors="replace", timeout=env_int("WHATSAPP_NPM_INSTALL_TIMEOUT", 300),
+            env=with_hermes_node_path(), creationflags=windows_hide_flags(),
         )
     except subprocess.TimeoutExpired as exc:
-        raise HTTPException(
-            status_code=500,
-            detail="Installing WhatsApp bridge dependencies timed out.",
-        ) from exc
+        raise HTTPException(status_code=500, detail="Installing WhatsApp bridge dependencies timed out.") from exc
     except OSError as exc:
-        raise HTTPException(
-            status_code=500,
-            detail=f"Failed to install WhatsApp bridge dependencies: {exc}",
-        ) from exc
+        raise HTTPException(status_code=500, detail=f"Failed to install WhatsApp bridge dependencies: {exc}") from exc
 
     if result.returncode != 0:
         detail = (result.stderr or result.stdout or "").strip()
         if detail:
             detail = "\n".join(detail.splitlines()[-10:])
-        raise HTTPException(
-            status_code=500,
-            detail=f"npm install failed for WhatsApp bridge: {detail or 'no output'}",
-        )
+        raise HTTPException(status_code=500, detail=f"npm install failed for WhatsApp bridge: {detail or 'no output'}")
 
 
 def _spawn_whatsapp_pairing_process(session_path: Path, mode: str) -> subprocess.Popen:
@@ -586,16 +385,10 @@ def _spawn_whatsapp_pairing_process(session_path: Path, mode: str) -> subprocess
     bridge_dir = resolve_whatsapp_bridge_dir()
     bridge_script = bridge_dir / "bridge.js"
     if not bridge_script.exists():
-        raise HTTPException(
-            status_code=500,
-            detail=f"WhatsApp bridge script was not found at {bridge_script}.",
-        )
+        raise HTTPException(status_code=500, detail=f"WhatsApp bridge script was not found at {bridge_script}.")
     node = find_node_executable("node")
     if not node:
-        raise HTTPException(
-            status_code=500,
-            detail="Node.js was not found. WhatsApp setup needs Node.js.",
-        )
+        raise HTTPException(status_code=500, detail="Node.js was not found. WhatsApp setup needs Node.js.")
 
     _ensure_whatsapp_bridge_dependencies(bridge_dir)
     session_path.mkdir(parents=True, exist_ok=True)
@@ -604,105 +397,85 @@ def _spawn_whatsapp_pairing_process(session_path: Path, mode: str) -> subprocess
     env["WHATSAPP_MODE"] = mode
     env["WHATSAPP_DM_POLICY"] = "pairing"
     return subprocess.Popen(
-        [
-            node,
-            str(bridge_script),
-            "--pair-only",
-            "--pair-json",
-            "--session",
-            str(session_path),
-        ],
-        cwd=str(bridge_dir),
-        stdout=subprocess.PIPE,
-        stderr=subprocess.STDOUT,
-        text=True,
-        encoding="utf-8",
-        errors="replace",
-        start_new_session=True,
-        env=env,
+        [node, str(bridge_script), "--pair-only", "--pair-json", "--session", str(session_path)],
+        cwd=str(bridge_dir), stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True,
+        encoding="utf-8", errors="replace", start_new_session=True, env=env,
         creationflags=windows_hide_flags(),
     )
 
 
 def _terminate_whatsapp_pairing(proc: subprocess.Popen | None) -> None:
-    if proc is None:
-        return
-    if proc.poll() is not None:
+    if proc is None or proc.poll() is not None:
         return
     try:
         proc.terminate()
         proc.wait(timeout=3)
     except Exception:
-        try:
+        with contextlib.suppress(Exception):
             proc.kill()
-        except Exception:
-            pass
+
+
+def _fail_whatsapp_pairing(pairing_id: str, error: str, *, proc=None, unless=_WHATSAPP_ONBOARDING_TERMINAL_STATUSES) -> None:
+    """Mark the session errored unless its status is in ``unless`` (or, when
+    ``proc`` is given, it has since been superseded by another process)."""
+    with _whatsapp_onboarding_lock:
+        record = _whatsapp_onboarding_sessions.get(pairing_id)
+        if record and (proc is None or record.proc is proc) and record.status not in unless:
+            record.status = "error"
+            record.error = error
+
+
+def _apply_pairing_event(record, payload: dict) -> None:
+    event = str(payload.get("event") or "").strip()
+    if event == "qr":
+        qr = str(payload.get("qr") or "").strip()
+        if qr:
+            record.qr_payload = qr
+            record.status = "waiting"
+            record.error = None
+    elif event == "connected":
+        user = payload.get("user")
+        if isinstance(user, dict):
+            account_id = str(user.get("id") or "").strip()
+            record.account_id = account_id or None
+            record.account_name = str(user.get("name") or "").strip() or None
+            record.account_phone = _whatsapp_phone_from_identifier(account_id)
+        record.status = "connected"
+        record.error = None
+    elif event == "error":
+        record.status = "error"
+        record.error = str(payload.get("error") or "WhatsApp pairing failed.")
+    elif event == "disconnected" and record.status == "starting":
+        record.status = "waiting"
 
 
 def _watch_whatsapp_pairing(pairing_id: str, proc: subprocess.Popen) -> None:
-    from hermes_cli.web_server import _whatsapp_onboarding_sessions
     try:
-        stream = proc.stdout
-        if stream is not None:
-            for line in stream:
-                raw = line.strip()
-                if not raw:
-                    continue
-                try:
-                    payload = json.loads(raw)
-                except json.JSONDecodeError:
-                    continue
-                event = str(payload.get("event") or "").strip()
-                with _whatsapp_onboarding_lock:
-                    record = _whatsapp_onboarding_sessions.get(pairing_id)
-                    if not record or record.proc is not proc:
-                        return
-                    if event == "qr":
-                        qr = str(payload.get("qr") or "").strip()
-                        if qr:
-                            record.qr_payload = qr
-                            record.status = "waiting"
-                            record.error = None
-                    elif event == "connected":
-                        user = payload.get("user")
-                        if isinstance(user, dict):
-                            account_id = str(user.get("id") or "").strip()
-                            account_name = str(user.get("name") or "").strip()
-                            record.account_id = account_id or None
-                            record.account_name = account_name or None
-                            record.account_phone = _whatsapp_phone_from_identifier(account_id)
-                        record.status = "connected"
-                        record.error = None
-                    elif event == "error":
-                        record.status = "error"
-                        record.error = str(payload.get("error") or "WhatsApp pairing failed.")
-                    elif event == "disconnected" and record.status == "starting":
-                        record.status = "waiting"
+        for line in proc.stdout or ():
+            raw = line.strip()
+            if not raw:
+                continue
+            try:
+                payload = json.loads(raw)
+            except json.JSONDecodeError:
+                continue
+            with _whatsapp_onboarding_lock:
+                record = _whatsapp_onboarding_sessions.get(pairing_id)
+                if not record or record.proc is not proc:
+                    return
+                _apply_pairing_event(record, payload)
         returncode = proc.wait()
     except Exception as exc:
-        with _whatsapp_onboarding_lock:
-            record = _whatsapp_onboarding_sessions.get(pairing_id)
-            if record and record.proc is proc and record.status not in _WHATSAPP_ONBOARDING_TERMINAL_STATUSES:
-                record.status = "error"
-                record.error = str(exc)
+        _fail_whatsapp_pairing(pairing_id, str(exc), proc=proc)
         return
-
-    with _whatsapp_onboarding_lock:
-        record = _whatsapp_onboarding_sessions.get(pairing_id)
-        if not record or record.proc is not proc:
-            return
-        if record.status in {"connected", "cancelled", "expired"}:
-            return
-        record.status = "error"
-        record.error = (
-            "WhatsApp pairing process exited before pairing completed."
-            if returncode == 0
-            else f"WhatsApp pairing process exited with code {returncode}."
-        )
+    # An "error" status from the stream may be overwritten by the exit reason.
+    _fail_whatsapp_pairing(
+        pairing_id, "WhatsApp pairing process exited before pairing completed." if returncode == 0
+        else f"WhatsApp pairing process exited with code {returncode}.",
+        proc=proc, unless={"connected", "cancelled", "expired"})
 
 
 def _run_whatsapp_pairing(pairing_id: str, session_path: Path, mode: str) -> None:
-    from hermes_cli.web_server import _whatsapp_onboarding_sessions
     with _whatsapp_onboarding_lock:
         record = _whatsapp_onboarding_sessions.get(pairing_id)
         if not record or record.status in _WHATSAPP_ONBOARDING_TERMINAL_STATUSES:
@@ -712,11 +485,7 @@ def _run_whatsapp_pairing(pairing_id: str, session_path: Path, mode: str) -> Non
     try:
         proc = _spawn_whatsapp_pairing_process(session_path, mode)
     except Exception as exc:
-        with _whatsapp_onboarding_lock:
-            record = _whatsapp_onboarding_sessions.get(pairing_id)
-            if record and record.status not in _WHATSAPP_ONBOARDING_TERMINAL_STATUSES:
-                record.status = "error"
-                record.error = str(exc)
+        _fail_whatsapp_pairing(pairing_id, str(exc))
         return
 
     with _whatsapp_onboarding_lock:
@@ -731,18 +500,15 @@ def _run_whatsapp_pairing(pairing_id: str, session_path: Path, mode: str) -> Non
 
 
 def _prune_whatsapp_onboarding_sessions() -> None:
-    from hermes_cli.web_server import _whatsapp_onboarding_sessions
     now = time.time()
     remove_ids: list[str] = []
     for pairing_id, record in _whatsapp_onboarding_sessions.items():
-        if (
-            record.proc is not None
-            and record.status not in _WHATSAPP_ONBOARDING_TERMINAL_STATUSES
-            and record.proc.poll() is not None
-        ):
+        live = record.status not in _WHATSAPP_ONBOARDING_TERMINAL_STATUSES
+        if live and record.proc is not None and record.proc.poll() is not None:
             record.status = "error"
             record.error = "WhatsApp pairing process exited before pairing completed."
-        if record.expires_at_ts <= now and record.status not in _WHATSAPP_ONBOARDING_TERMINAL_STATUSES:
+            live = False
+        if live and record.expires_at_ts <= now:
             _terminate_whatsapp_pairing(record.proc)
             record.status = "expired"
             record.error = "WhatsApp QR setup expired. Start a new setup."
@@ -752,149 +518,99 @@ def _prune_whatsapp_onboarding_sessions() -> None:
         _whatsapp_onboarding_sessions.pop(pairing_id, None)
 
 
-def _supersede_whatsapp_onboarding_sessions(session_path: Path) -> None:
-    from hermes_cli.web_server import _whatsapp_onboarding_sessions
-    for existing in _whatsapp_onboarding_sessions.values():
-        if existing.session_path == str(session_path) and existing.status not in _WHATSAPP_ONBOARDING_TERMINAL_STATUSES:
-            existing.status = "cancelled"
-            existing.error = "Superseded by a newer WhatsApp setup session."
-            _terminate_whatsapp_pairing(existing.proc)
+def _register_whatsapp_session(session_path: Path, record) -> str:
+    """Store ``record`` under a fresh pairing id, cancelling any live session on
+    the same session dir (superseded by the newer setup)."""
+    pairing_id = secrets.token_urlsafe(16)
+    with _whatsapp_onboarding_lock:
+        _prune_whatsapp_onboarding_sessions()
+        for existing in _whatsapp_onboarding_sessions.values():
+            if existing.session_path == str(session_path) and existing.status not in _WHATSAPP_ONBOARDING_TERMINAL_STATUSES:
+                existing.status = "cancelled"
+                existing.error = "Superseded by a newer WhatsApp setup session."
+                _terminate_whatsapp_pairing(existing.proc)
+        _whatsapp_onboarding_sessions[pairing_id] = record
+    return pairing_id
 
 
 @router.post("/api/messaging/whatsapp/onboarding/start")
 async def start_whatsapp_onboarding(body: WhatsAppOnboardingStart):
-    from hermes_cli.web_server import _WhatsAppOnboardingSession, _whatsapp_onboarding_sessions
     mode = _normalize_whatsapp_onboarding_mode(body.mode)
     allowed_users = _normalize_whatsapp_allowed_users(body.allowed_users)
-    effective_profile = body.profile
 
-    with _config_profile_scope(effective_profile):
+    with _config_profile_scope(body.profile):
         session_path = _whatsapp_session_path()
         expires_at_ts = time.time() + _WHATSAPP_ONBOARDING_TTL_SECONDS
-        expires_at = _utc_iso_from_ts(expires_at_ts)
-        if (session_path / "creds.json").exists():
-            pairing_id = secrets.token_urlsafe(16)
+        fields = dict(
+            proc=None, mode=mode, allowed_users=allowed_users, session_path=str(session_path),
+            expires_at=datetime.fromtimestamp(expires_at_ts, timezone.utc).isoformat().replace("+00:00", "Z"),
+            expires_at_ts=expires_at_ts, profile=body.profile,
+        )
+        already_linked = (session_path / "creds.json").exists()
+        if already_linked:
             account_id, account_name, account_phone = _whatsapp_linked_account_from_session(session_path)
-            record = _WhatsAppOnboardingSession(
-                proc=None,
-                mode=mode,
-                allowed_users=allowed_users,
-                session_path=str(session_path),
-                expires_at=expires_at,
-                expires_at_ts=expires_at_ts,
-                profile=effective_profile,
-                status="connected",
-                account_id=account_id,
-                account_name=account_name,
-                account_phone=account_phone,
-            )
-            with _whatsapp_onboarding_lock:
-                _prune_whatsapp_onboarding_sessions()
-                _supersede_whatsapp_onboarding_sessions(session_path)
-                _whatsapp_onboarding_sessions[pairing_id] = record
+            record = _WhatsAppOnboardingSession(**fields, status="connected", account_id=account_id,
+                                                account_name=account_name, account_phone=account_phone)
+            pairing_id = _register_whatsapp_session(session_path, record)
             return _whatsapp_onboarding_payload(pairing_id, record)
 
-    pairing_id = secrets.token_urlsafe(16)
-    record = _WhatsAppOnboardingSession(
-        proc=None,
-        mode=mode,
-        allowed_users=allowed_users,
-        session_path=str(session_path),
-        expires_at=expires_at,
-        expires_at_ts=expires_at_ts,
-        profile=effective_profile,
-    )
-
-    with _whatsapp_onboarding_lock:
-        _prune_whatsapp_onboarding_sessions()
-        _supersede_whatsapp_onboarding_sessions(session_path)
-        _whatsapp_onboarding_sessions[pairing_id] = record
-
-    threading.Thread(
-        target=_run_whatsapp_pairing,
-        args=(pairing_id, session_path, mode),
-        daemon=True,
-    ).start()
-
+    record = _WhatsAppOnboardingSession(**fields)
+    pairing_id = _register_whatsapp_session(session_path, record)
+    threading.Thread(target=_run_whatsapp_pairing, args=(pairing_id, session_path, mode), daemon=True).start()
     return _whatsapp_onboarding_payload(pairing_id, record)
 
 
+def _whatsapp_record_or_404(pairing_id: str):
+    """Call with ``_whatsapp_onboarding_lock`` held."""
+    _prune_whatsapp_onboarding_sessions()
+    record = _whatsapp_onboarding_sessions.get(pairing_id)
+    if not record:
+        raise HTTPException(status_code=404, detail=_WHATSAPP_SESSION_NOT_FOUND)
+    return record
+
+
 @router.get("/api/messaging/whatsapp/onboarding/{pairing_id}")
 async def get_whatsapp_onboarding_status(pairing_id: str):
-    from hermes_cli.web_server import _whatsapp_onboarding_sessions
     with _whatsapp_onboarding_lock:
-        _prune_whatsapp_onboarding_sessions()
-        record = _whatsapp_onboarding_sessions.get(pairing_id)
-        if not record:
-            raise HTTPException(
-                status_code=404,
-                detail="WhatsApp setup session was not found. Start a new setup.",
-            )
+        record = _whatsapp_record_or_404(pairing_id)
         if record.status == "expired":
             raise HTTPException(status_code=410, detail=record.error or "WhatsApp setup expired.")
         return _whatsapp_onboarding_payload(pairing_id, record)
 
 
 @router.post("/api/messaging/whatsapp/onboarding/{pairing_id}/apply")
-async def apply_whatsapp_onboarding(
-    pairing_id: str, body: WhatsAppOnboardingApply, profile: Optional[str] = None
-):
-    from hermes_cli.web_server import _whatsapp_onboarding_sessions
+async def apply_whatsapp_onboarding(pairing_id: str, body: WhatsAppOnboardingApply, profile: Optional[str] = None):
     with _whatsapp_onboarding_lock:
-        _prune_whatsapp_onboarding_sessions()
-        record = _whatsapp_onboarding_sessions.get(pairing_id)
-        if not record:
-            raise HTTPException(
-                status_code=404,
-                detail="WhatsApp setup session was not found. Start a new setup.",
-            )
+        record = _whatsapp_record_or_404(pairing_id)
         if record.status != "connected":
             raise HTTPException(status_code=409, detail="WhatsApp setup is not connected yet.")
         mode = _normalize_whatsapp_onboarding_mode(body.mode or record.mode)
-        allowed_users = _normalize_whatsapp_allowed_users(
-            record.allowed_users if body.allowed_users is None else body.allowed_users
-        )
+        allowed_users = _normalize_whatsapp_allowed_users(record.allowed_users if body.allowed_users is None else body.allowed_users)
         if mode == "self-chat" and not allowed_users:
             allowed_users = record.account_phone or record.account_id or ""
         record_profile = record.profile
 
     effective_profile = body.profile or profile or record_profile
-    try:
+    with _onboarding_save_errors("WhatsApp onboarding apply failed", "Failed to save WhatsApp setup."):
         with _config_profile_scope(effective_profile):
             save_env_value("WHATSAPP_MODE", mode)
             save_env_value("WHATSAPP_DM_POLICY", "pairing")
-            if allowed_users:
-                save_env_value("WHATSAPP_ALLOWED_USERS", allowed_users)
             # Blank means "keep the existing allowlist"; explicit clearing
             # still lives in the normal config editor where the field is visible.
+            if allowed_users:
+                save_env_value("WHATSAPP_ALLOWED_USERS", allowed_users)
             save_env_value("WHATSAPP_ENABLED", "true")
             _write_platform_enabled("whatsapp", True)
-    except HTTPException:
-        raise
-    except ValueError as exc:
-        raise HTTPException(status_code=400, detail=str(exc)) from exc
-    except Exception as exc:
-        _log.exception("WhatsApp onboarding apply failed")
-        raise HTTPException(
-            status_code=500,
-            detail="Failed to save WhatsApp setup.",
-        ) from exc
 
     with _whatsapp_onboarding_lock:
         _whatsapp_onboarding_sessions.pop(pairing_id, None)
 
     restart_result = _restart_gateway_after_whatsapp_onboarding(effective_profile)
-    return {
-        "ok": True,
-        "platform": "whatsapp",
-        "needs_restart": not restart_result["restart_started"],
-        **restart_result,
-    }
+    return {"ok": True, "platform": "whatsapp", "needs_restart": not restart_result["restart_started"], **restart_result}
 
 
 @router.delete("/api/messaging/whatsapp/onboarding/{pairing_id}")
 async def cancel_whatsapp_onboarding(pairing_id: str):
-    from hermes_cli.web_server import _whatsapp_onboarding_sessions
     with _whatsapp_onboarding_lock:
         record = _whatsapp_onboarding_sessions.pop(pairing_id, None)
     if record:
@@ -903,10 +619,15 @@ async def cancel_whatsapp_onboarding(pairing_id: str):
     return {"ok": True}
 
 
+# ── Telegram QR onboarding ─────────────────────────────────────
+
+_TELEGRAM_SESSION_NOT_FOUND = "Telegram setup session was not found. Start a new setup."
+_TELEGRAM_INCOMPLETE_RESPONSE = "Telegram setup service returned an incomplete response."
+
+
 def _parse_expiry_ts(value: str) -> float:
     try:
-        normalized = value.replace("Z", "+00:00")
-        parsed = datetime.fromisoformat(normalized)
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
         if parsed.tzinfo is None:
             parsed = parsed.replace(tzinfo=timezone.utc)
         return parsed.timestamp()
@@ -915,108 +636,69 @@ def _parse_expiry_ts(value: str) -> float:
 
 
 def _prune_telegram_onboarding_pairings() -> None:
-    from hermes_cli.web_server import _telegram_onboarding_pairings
     now = time.time()
-    expired = [
-        pairing_id
-        for pairing_id, record in _telegram_onboarding_pairings.items()
-        if record.expires_at_ts <= now
-    ]
-    for pairing_id in expired:
+    for pairing_id in [pid for pid, record in _telegram_onboarding_pairings.items() if record.expires_at_ts <= now]:
         _telegram_onboarding_pairings.pop(pairing_id, None)
 
 
 def _normalize_telegram_user_id(value: Any) -> str | None:
     normalized = str(value or "").strip()
-    if _TELEGRAM_USER_ID_RE.fullmatch(normalized):
-        return normalized
-    return None
+    return normalized if _TELEGRAM_USER_ID_RE.fullmatch(normalized) else None
 
 
-async def _telegram_onboarding_request(
-    method: str,
-    path: str,
-    *,
-    body: dict[str, Any] | None = None,
-    bearer_token: str | None = None,
-) -> dict[str, Any]:
-    return await asyncio.to_thread(
-        _telegram_onboarding_request_sync,
-        method,
-        path,
-        body=body,
-        bearer_token=bearer_token,
-    )
+def _telegram_record_or_404(pairing_id: str):
+    """Call with ``_telegram_onboarding_lock`` held."""
+    _prune_telegram_onboarding_pairings()
+    record = _telegram_onboarding_pairings.get(pairing_id)
+    if not record:
+        raise HTTPException(status_code=404, detail=_TELEGRAM_SESSION_NOT_FOUND)
+    return record
+
+
+def _telegram_ready_payload(record) -> dict[str, Any]:
+    return {
+        "status": "ready", "bot_username": record.bot_username,
+        "owner_user_id": record.owner_user_id, "expires_at": record.expires_at,
+    }
+
+
+async def _telegram_onboarding_request(method: str, path: str, *, body=None, bearer_token=None) -> dict[str, Any]:
+    return await asyncio.to_thread(_telegram_onboarding_request_sync, method, path, body=body, bearer_token=bearer_token)
 
 
 @router.post("/api/messaging/telegram/onboarding/start")
 async def start_telegram_onboarding(body: TelegramOnboardingStart):
-    from hermes_cli.web_server import (
-        _TelegramOnboardingPairing,
-        _telegram_onboarding_lock,
-        _telegram_onboarding_pairings,
-    )
     bot_name = (body.bot_name or "Hermes Agent").strip() or "Hermes Agent"
-    payload = await _telegram_onboarding_request(
-        "POST",
-        "/v1/telegram/pairings",
-        body={"bot_name": bot_name},
-    )
+    payload = await _telegram_onboarding_request("POST", "/v1/telegram/pairings", body={"bot_name": bot_name})
 
-    pairing_id = str(payload.get("pairing_id") or "").strip()
-    poll_token = str(payload.get("poll_token") or "").strip()
-    expires_at = str(payload.get("expires_at") or "").strip()
-    deep_link = str(payload.get("deep_link") or "").strip()
-    qr_payload = str(payload.get("qr_payload") or deep_link).strip()
-    suggested_username = str(payload.get("suggested_username") or "").strip()
+    def field(key: str) -> str:
+        return str(payload.get(key) or "").strip()
+
+    pairing_id, poll_token, expires_at, deep_link = map(field, ("pairing_id", "poll_token", "expires_at", "deep_link"))
     if not pairing_id or not poll_token or not expires_at or not deep_link:
-        raise HTTPException(
-            status_code=502,
-            detail="Telegram setup service returned an incomplete response.",
-        )
+        raise HTTPException(status_code=502, detail=_TELEGRAM_INCOMPLETE_RESPONSE)
 
     with _telegram_onboarding_lock:
         _prune_telegram_onboarding_pairings()
         _telegram_onboarding_pairings[pairing_id] = _TelegramOnboardingPairing(
-            poll_token=poll_token,
-            expires_at=expires_at,
-            expires_at_ts=_parse_expiry_ts(expires_at),
-        )
+            poll_token=poll_token, expires_at=expires_at, expires_at_ts=_parse_expiry_ts(expires_at))
 
     return {
-        "pairing_id": pairing_id,
-        "suggested_username": suggested_username,
-        "deep_link": deep_link,
-        "qr_payload": qr_payload,
-        "expires_at": expires_at,
+        "pairing_id": pairing_id, "suggested_username": field("suggested_username"), "deep_link": deep_link,
+        "qr_payload": str(payload.get("qr_payload") or deep_link).strip(), "expires_at": expires_at,
     }
 
 
 @router.get("/api/messaging/telegram/onboarding/{pairing_id}")
 async def get_telegram_onboarding_status(pairing_id: str):
-    from hermes_cli.web_server import _telegram_onboarding_lock, _telegram_onboarding_pairings
     with _telegram_onboarding_lock:
-        _prune_telegram_onboarding_pairings()
-        record = _telegram_onboarding_pairings.get(pairing_id)
-        if not record:
-            raise HTTPException(
-                status_code=404,
-                detail="Telegram setup session was not found. Start a new setup.",
-            )
+        record = _telegram_record_or_404(pairing_id)
         if record.bot_token:
-            return {
-                "status": "ready",
-                "bot_username": record.bot_username,
-                "owner_user_id": record.owner_user_id,
-                "expires_at": record.expires_at,
-            }
+            return _telegram_ready_payload(record)
         poll_token = record.poll_token
 
     payload = await _telegram_onboarding_request(
-        "GET",
-        f"/v1/telegram/pairings/{urllib.parse.quote(pairing_id, safe='')}",
-        bearer_token=poll_token,
-    )
+        "GET", f"/v1/telegram/pairings/{urllib.parse.quote(pairing_id, safe='')}", bearer_token=poll_token)
     status = str(payload.get("status") or "").strip()
     if status == "waiting":
         with _telegram_onboarding_lock:
@@ -1026,96 +708,44 @@ async def get_telegram_onboarding_status(pairing_id: str):
 
     if status == "ready":
         bot_token = str(payload.get("token") or "").strip()
-        bot_username = str(payload.get("bot_username") or "").strip()
         if not bot_token:
-            raise HTTPException(
-                status_code=502,
-                detail="Telegram setup service returned an incomplete response.",
-            )
-        owner_user_id = _normalize_telegram_user_id(payload.get("owner_user_id"))
+            raise HTTPException(status_code=502, detail=_TELEGRAM_INCOMPLETE_RESPONSE)
         with _telegram_onboarding_lock:
             record = _telegram_onboarding_pairings.get(pairing_id)
             if not record:
-                raise HTTPException(
-                    status_code=404,
-                    detail="Telegram setup session was not found. Start a new setup.",
-                )
+                raise HTTPException(status_code=404, detail=_TELEGRAM_SESSION_NOT_FOUND)
             record.bot_token = bot_token
-            record.bot_username = bot_username or None
-            record.owner_user_id = owner_user_id
-            return {
-                "status": "ready",
-                "bot_username": record.bot_username,
-                "owner_user_id": record.owner_user_id,
-                "expires_at": record.expires_at,
-            }
+            record.bot_username = str(payload.get("bot_username") or "").strip() or None
+            record.owner_user_id = _normalize_telegram_user_id(payload.get("owner_user_id"))
+            return _telegram_ready_payload(record)
 
     if status in {"expired", "claimed"}:
         with _telegram_onboarding_lock:
             _telegram_onboarding_pairings.pop(pairing_id, None)
-        raise HTTPException(
-            status_code=410,
-            detail=_telegram_onboarding_error_message(
-                status,
-                "Telegram setup is no longer available. Start a new setup.",
-            ),
-        )
+        raise HTTPException(status_code=410, detail=_telegram_onboarding_error_message(
+            status, "Telegram setup is no longer available. Start a new setup."))
 
-    raise HTTPException(
-        status_code=502,
-        detail="Telegram setup service returned an unknown status.",
-    )
-
-
-def _restart_gateway_after_telegram_onboarding(profile: Optional[str] = None) -> dict[str, Any]:
-    """Best-effort gateway restart after saving Telegram QR onboarding.
-
-    The QR flow naturally pulls users into Telegram on another device. If the
-    saved token waits on a separate dashboard restart click, Hermes appears
-    broken from the chat side. Keep the config save authoritative, but report
-    restart failures so the UI can fall back to the existing manual banner.
-    """
-    return _restart_gateway_after(profile, what="Telegram onboarding", label="Telegram onboarding")
+    raise HTTPException(status_code=502, detail="Telegram setup service returned an unknown status.")
 
 
 @router.post("/api/messaging/telegram/onboarding/{pairing_id}/apply")
-async def apply_telegram_onboarding(
-    pairing_id: str, body: TelegramOnboardingApply, profile: Optional[str] = None
-):
-    from hermes_cli.web_server import _telegram_onboarding_lock, _telegram_onboarding_pairings
-    allowed_user_ids = []
-    seen = set()
+async def apply_telegram_onboarding(pairing_id: str, body: TelegramOnboardingApply, profile: Optional[str] = None):
+    allowed_user_ids: list[str] = []
     for raw_id in body.allowed_user_ids:
         normalized = _normalize_telegram_user_id(raw_id)
         if not normalized:
-            raise HTTPException(
-                status_code=400,
-                detail="Allowed Telegram user IDs must be numeric.",
-            )
-        if normalized not in seen:
-            seen.add(normalized)
+            raise HTTPException(status_code=400, detail="Allowed Telegram user IDs must be numeric.")
+        if normalized not in allowed_user_ids:
             allowed_user_ids.append(normalized)
     if not allowed_user_ids:
-        raise HTTPException(
-            status_code=400,
-            detail="Add at least one allowed Telegram user ID.",
-        )
+        raise HTTPException(status_code=400, detail="Add at least one allowed Telegram user ID.")
 
     with _telegram_onboarding_lock:
-        _prune_telegram_onboarding_pairings()
-        record = _telegram_onboarding_pairings.get(pairing_id)
-        if not record:
-            raise HTTPException(
-                status_code=404,
-                detail="Telegram setup session was not found. Start a new setup.",
-            )
+        record = _telegram_record_or_404(pairing_id)
         bot_token = record.bot_token
         bot_username = record.bot_username
         if not bot_token:
-            raise HTTPException(
-                status_code=409,
-                detail="Telegram setup is not ready yet.",
-            )
+            raise HTTPException(status_code=409, detail="Telegram setup is not ready yet.")
 
     effective_profile = body.profile or profile
 
@@ -1125,89 +755,58 @@ async def apply_telegram_onboarding(
             save_env_value("TELEGRAM_ALLOWED_USERS", ",".join(allowed_user_ids))
             _write_platform_enabled("telegram", True)
 
-    try:
+    with _onboarding_save_errors("Telegram onboarding apply failed", "Failed to save Telegram setup."):
         await asyncio.to_thread(_apply)
-    except HTTPException:
-        raise
-    except ValueError as exc:
-        raise HTTPException(status_code=400, detail=str(exc)) from exc
-    except Exception as exc:
-        _log.exception("Telegram onboarding apply failed")
-        raise HTTPException(
-            status_code=500,
-            detail="Failed to save Telegram setup.",
-        ) from exc
 
     with _telegram_onboarding_lock:
         _telegram_onboarding_pairings.pop(pairing_id, None)
 
-    restart_result = _restart_gateway_after_telegram_onboarding(effective_profile)
-
+    # Best-effort restart: the QR flow pulls users into Telegram on another
+    # device, so a saved token waiting on a manual restart click reads as
+    # "Hermes is broken" from the chat side. The config save stays
+    # authoritative; a failed restart is reported so the UI shows its banner.
+    restart_result = _restart_gateway_after(effective_profile, what="Telegram onboarding", label="Telegram onboarding")
     return {
-        "ok": True,
-        "platform": "telegram",
-        "bot_username": bot_username,
-        "needs_restart": not restart_result["restart_started"],
-        **restart_result,
+        "ok": True, "platform": "telegram", "bot_username": bot_username,
+        "needs_restart": not restart_result["restart_started"], **restart_result,
     }
 
 
 @router.delete("/api/messaging/telegram/onboarding/{pairing_id}")
 async def cancel_telegram_onboarding(pairing_id: str):
-    from hermes_cli.web_server import _telegram_onboarding_lock, _telegram_onboarding_pairings
     with _telegram_onboarding_lock:
         _telegram_onboarding_pairings.pop(pairing_id, None)
     return {"ok": True}
 
 
+# ── platform list / update / test ──────────────────────────────
+
+
 @router.get("/api/messaging/platforms")
 async def get_messaging_platforms(profile: Optional[str] = None):
     # Profile-scoped so the dashboard's global profile switcher shows the
     # TARGET profile's channel credentials/state, not the root install's.
-    # load_env() honors the HERMES_HOME contextvar override; the gateway
-    # status readers do NOT (they resolve process-level paths), so the
-    # profile directory is passed explicitly for those (#71211).
     def _run():
         with _profile_scope(profile) as scoped_dir:
-            env_on_disk = load_env()
-            runtime = (
-                read_runtime_status(path=scoped_dir / "gateway_state.json")
-                if scoped_dir is not None
-                else read_runtime_status()
-            )
             return {
                 "env_path": str(get_env_path()),
-                "gateway_start_command": _gateway_display_command(profile, "start"),
-                "platforms": [
-                    _messaging_platform_payload(
-                        entry,
-                        env_on_disk,
-                        runtime,
-                        scoped=scoped_dir is not None,
-                        profile_home=scoped_dir,
-                    )
-                    for entry in _messaging_platform_catalog()
-                ]
+                "gateway_start_command": " ".join(["hermes", *_gateway_subcommand(profile, "start")]),
+                "platforms": _platform_payloads(scoped_dir, _messaging_platform_catalog()),
             }
 
     return await asyncio.to_thread(_run)
 
 
-def _multiplex_port_binding_conflict(
-    platform_id: str, requested_profile: Optional[str]
-) -> Optional[str]:
+def _multiplex_port_binding_conflict(platform_id: str, requested_profile: Optional[str]) -> Optional[str]:
     """Reason enabling ``platform_id`` on the target profile would break a
-    multiplexed gateway, or ``None`` when the change is allowed.
+    multiplexed gateway, or ``None`` when allowed.
 
-    Mirrors the gateway's startup rule (``_start_one_profile_adapters`` in
-    gateway/run.py): with ``gateway.multiplex_profiles`` on, the default
-    profile owns the single shared HTTP listener and serves every profile via
-    the ``/p/<profile>/`` prefix, so a SECONDARY profile must never enable a
-    port-binding platform. Without this pre-write check the dashboard happily
-    persisted the invalid config and the shared gateway died with
-    ``MultiplexConfigError`` on its next start — for ALL profiles. Only
-    *enabling* is blocked; disabling/clearing stays allowed so users can
-    repair an already-invalid profile.
+    Mirrors ``_start_one_profile_adapters`` (gateway/run.py): with
+    ``gateway.multiplex_profiles`` on, the default profile owns the single shared
+    HTTP listener (``/p/<profile>/``), so a SECONDARY profile must never enable a
+    port-binding platform or the shared gateway dies with ``MultiplexConfigError``
+    for ALL profiles. Only *enabling* is blocked; disabling/clearing stays allowed
+    so users can repair an invalid profile.
     """
     from gateway.config import PORT_BINDING_PLATFORM_VALUES, load_gateway_config
 
@@ -1219,8 +818,7 @@ def _multiplex_port_binding_conflict(
         from hermes_cli.profiles import get_active_profile_name
 
         # The dashboard's own profile. "custom" (an unrecognized HERMES_HOME)
-        # is outside the profiles tree, so a multiplexed gateway never serves
-        # it — nothing to guard.
+        # is outside the profiles tree, so a multiplexed gateway never serves it.
         target = get_active_profile_name()
     else:
         _resolve_profile_dir(requested)  # same 400/404 as _profile_scope
@@ -1228,31 +826,24 @@ def _multiplex_port_binding_conflict(
     if target in ("default", "custom"):
         return None
 
-    # The multiplex flag that matters is the one the shared gateway reads at
-    # startup: the DEFAULT profile's gateway config (plus the process-wide
+    # The flag that matters is the one the shared gateway reads at startup: the
+    # DEFAULT profile's gateway config (plus the process-wide
     # GATEWAY_MULTIPLEX_PROFILES override, which load_gateway_config applies).
     with _config_profile_scope("default"):
         if not load_gateway_config().multiplex_profiles:
             return None
 
     return (
-        f"Cannot enable '{platform_id}' on profile '{target}': it binds its "
-        "own listener port, and gateway.multiplex_profiles is on, so the "
-        "default profile owns the single shared HTTP listener for every "
-        "profile. Configure this channel on the default profile instead "
+        f"Cannot enable '{platform_id}' on profile '{target}': it binds its own listener port, "
+        "and gateway.multiplex_profiles is on, so the default profile owns the single shared HTTP "
+        "listener for every profile. Configure this channel on the default profile instead "
         "(disabling or clearing it here is still allowed)."
     )
 
 
 @router.put("/api/messaging/platforms/{platform_id}")
-async def update_messaging_platform(
-    platform_id: str, body: MessagingPlatformUpdate, profile: Optional[str] = None
-):
-    entry = _catalog_lookup(platform_id)
-    if not entry:
-        raise HTTPException(
-            status_code=404, detail=f"Unknown messaging platform: {platform_id}"
-        )
+async def update_messaging_platform(platform_id: str, body: MessagingPlatformUpdate, profile: Optional[str] = None):
+    entry = _require_platform(platform_id)
 
     target_profile = body.profile or profile
     if body.enabled:
@@ -1262,30 +853,24 @@ async def update_messaging_platform(
             # loadable by the multiplexed gateway.
             _log.info(
                 "Rejected messaging platform update: platform=%s profile=%s "
-                "(multiplex port-binding conflict)",
-                platform_id,
-                target_profile or "current",
+                "(multiplex port-binding conflict)", platform_id, target_profile or "current",
             )
             raise HTTPException(status_code=409, detail=conflict)
 
     allowed_env = set(entry["env_vars"])
 
+    def _check_allowed(key: str) -> None:
+        if key not in allowed_env:
+            raise HTTPException(status_code=400, detail=f"{key} is not configurable for {entry['name']}")
+
     def _apply():
-        with _profile_scope(body.profile or profile):
+        with _profile_scope(target_profile):
             for key in body.clear_env:
-                if key not in allowed_env:
-                    raise HTTPException(
-                        status_code=400,
-                        detail=f"{key} is not configurable for {entry['name']}",
-                    )
+                _check_allowed(key)
                 remove_env_value(key)
 
             for key, value in body.env.items():
-                if key not in allowed_env:
-                    raise HTTPException(
-                        status_code=400,
-                        detail=f"{key} is not configurable for {entry['name']}",
-                    )
+                _check_allowed(key)
                 trimmed = value.strip()
                 if trimmed:
                     _validate_messaging_env_value(platform_id, key, trimmed)
@@ -1294,87 +879,40 @@ async def update_messaging_platform(
             if body.enabled is not None:
                 _write_platform_enabled(platform_id, body.enabled)
 
-    try:
+    with http_failure(f"PUT /api/messaging/platforms/{platform_id} failed", 500, detail="Internal server error"):
         await asyncio.to_thread(_apply)
 
         # Audit trail for channel config mutations: names only, never values.
         _log.info(
             "Messaging platform updated: platform=%s profile=%s enabled=%s "
             "env_keys=%s cleared_keys=%s",
-            platform_id,
-            target_profile or "current",
-            body.enabled,
-            sorted(body.env),
-            sorted(body.clear_env),
+            platform_id, target_profile or "current", body.enabled, sorted(body.env), sorted(body.clear_env),
         )
         return {"ok": True, "platform": platform_id}
-    except HTTPException:
-        raise
-    except Exception:
-        _log.exception("PUT /api/messaging/platforms/%s failed", platform_id)
-        raise HTTPException(status_code=500, detail="Internal server error")
 
 
 @router.post("/api/messaging/platforms/{platform_id}/test")
 async def test_messaging_platform(platform_id: str, profile: Optional[str] = None):
-    entry = _catalog_lookup(platform_id)
-    if not entry:
-        raise HTTPException(
-            status_code=404, detail=f"Unknown messaging platform: {platform_id}"
-        )
+    entry = _require_platform(platform_id)
 
     def _run():
         with _profile_scope(profile) as scoped_dir:
-            env_on_disk = load_env()
-            runtime = (
-                read_runtime_status(path=scoped_dir / "gateway_state.json")
-                if scoped_dir is not None
-                else read_runtime_status()
-            )
-            return _messaging_platform_payload(
-                entry,
-                env_on_disk,
-                runtime,
-                scoped=scoped_dir is not None,
-                profile_home=scoped_dir,
-            )
+            return _platform_payloads(scoped_dir, [entry])[0]
 
     payload = await asyncio.to_thread(_run)
+
+    def result(ok: bool, message: str) -> dict[str, Any]:
+        return {"ok": ok, "state": payload["state"], "message": message}
+
     if not payload["enabled"]:
-        message = f"{entry['name']} is disabled. Enable it, then restart the gateway."
-        return {"ok": False, "state": payload["state"], "message": message}
+        return result(False, f"{entry['name']} is disabled. Enable it, then restart the gateway.")
     if not payload["configured"]:
-        missing = [
-            field["key"]
-            for field in payload["env_vars"]
-            if field["required"] and not field["is_set"]
-        ]
-        message = (
-            f"Missing required setup: {', '.join(missing)}"
-            if missing
-            else "Platform setup is incomplete."
-        )
-        return {"ok": False, "state": payload["state"], "message": message}
+        missing = [field["key"] for field in payload["env_vars"] if field["required"] and not field["is_set"]]
+        return result(False, f"Missing required setup: {', '.join(missing)}" if missing else "Platform setup is incomplete.")
     if not payload["gateway_running"]:
-        return {
-            "ok": False,
-            "state": payload["state"],
-            "message": "Gateway is not running. Restart the gateway to connect this platform.",
-        }
+        return result(False, "Gateway is not running. Restart the gateway to connect this platform.")
     if payload["state"] == "connected":
-        return {
-            "ok": True,
-            "state": payload["state"],
-            "message": f"{entry['name']} is connected.",
-        }
+        return result(True, f"{entry['name']} is connected.")
     if payload.get("error_message"):
-        return {
-            "ok": False,
-            "state": payload["state"],
-            "message": payload["error_message"],
-        }
-    return {
-        "ok": False,
-        "state": payload["state"],
-        "message": "Setup looks complete, but the gateway has not reported a connection yet. Restart the gateway.",
-    }
+        return result(False, payload["error_message"])
+    return result(False, "Setup looks complete, but the gateway has not reported a connection yet. Restart the gateway.")
diff --git a/hermes_cli/web_routers/models.py b/hermes_cli/web_routers/models.py
index e6c05a5d2e..a36db8d172 100644
--- a/hermes_cli/web_routers/models.py
+++ b/hermes_cli/web_routers/models.py
@@ -1,18 +1,19 @@
 """Model assignment dashboard routes: model info/options/recommended default, auxiliary + MoA slots, /api/model/set.
 
 Extracted from ``hermes_cli.web_server``; helpers/state that tests monkeypatch on
-``web_server`` stay there and are imported lazily at call time (cycle-safe).
+``web_server`` stay there and are resolved late at call time (cycle-safe).
 """
 
-import logging
 import asyncio
-from fastapi import APIRouter
-from hermes_cli.web_routers._common import http_failure
-from hermes_cli.web_deps import late
-from fastapi import HTTPException
-from hermes_cli.web_models import ModelAssignment, MoaModelSlot, MoaPresetPayload, MoaConfigPayload
+import logging
 from typing import Optional
 
+from fastapi import APIRouter, HTTPException
+
+from hermes_cli.web_deps import LateState, late
+from hermes_cli.web_models import ModelAssignment, MoaConfigPayload, MoaModelSlot
+from hermes_cli.web_routers._common import http_failure
+
 _log = logging.getLogger("hermes_cli.web_server")
 router = APIRouter()
 
@@ -24,89 +25,69 @@ _profile_scope = late("_profile_scope")
 load_config = late("load_config")
 run_in_threadpool = late("run_in_threadpool")
 save_config = late("save_config")
+_AUX_TASK_SLOTS = LateState("_AUX_TASK_SLOTS")
 
 
 _EMPTY_MODEL_INFO: dict = {
-    "model": "",
-    "provider": "",
-    "auto_context_length": 0,
-    "config_context_length": 0,
-    "effective_context_length": 0,
-    "capabilities": {},
+    "model": "", "provider": "", "auto_context_length": 0, "config_context_length": 0,
+    "effective_context_length": 0, "capabilities": {},
 }
+_CAPABILITY_FIELDS = ("supports_tools", "supports_vision", "supports_reasoning", "context_window",
+                      "max_output_tokens", "model_family")
+
+
+def _main_model_fields(model_cfg) -> tuple[str, str]:
+    """(model, provider) from config's ``model`` section, which may be a plain string."""
+    if isinstance(model_cfg, dict):
+        return model_cfg.get("default", model_cfg.get("name", "")), model_cfg.get("provider", "")
+    return (str(model_cfg) if model_cfg else ""), ""
+
+
+def _load_config_scoped(profile: Optional[str]) -> dict:
+    with _profile_scope(profile):
+        return load_config()
 
 
 @router.get("/api/model/info")
 def get_model_info(profile: Optional[str] = None):
-    """Return resolved model metadata for the currently configured model.
-
-    Calls the same context-length resolution chain the agent uses, so the
-    frontend can display "Auto-detected: 200K" alongside the override field.
-    Also returns model capabilities (vision, reasoning, tools) when available.
-    """
+    """Resolved metadata for the configured model: auto-detected vs configured
+    context length (so the UI can show "Auto-detected: 200K" beside the
+    override) plus models.dev capabilities when available."""
     try:
-        with _profile_scope(profile):
-            cfg = load_config()
-        model_cfg = cfg.get("model", "")
-
-        # Extract model name and provider from the config
-        if isinstance(model_cfg, dict):
-            model_name = model_cfg.get("default", model_cfg.get("name", ""))
-            provider = model_cfg.get("provider", "")
-            base_url = model_cfg.get("base_url", "")
-            config_ctx = model_cfg.get("context_length")
-        else:
-            model_name = str(model_cfg) if model_cfg else ""
-            provider = ""
-            base_url = ""
-            config_ctx = None
+        model_cfg = _load_config_scoped(profile).get("model", "")
+        model_name, provider = _main_model_fields(model_cfg)
+        base_url = model_cfg.get("base_url", "") if isinstance(model_cfg, dict) else ""
+        config_ctx = model_cfg.get("context_length") if isinstance(model_cfg, dict) else None
 
         if not model_name:
             return dict(_EMPTY_MODEL_INFO, provider=provider)
 
-        # Resolve auto-detected context length (pass config_ctx=None to get
-        # purely auto-detected value, then separately report the override)
         try:
             from agent.model_metadata import get_model_context_length
             auto_ctx = get_model_context_length(
                 model=model_name,
                 base_url=base_url,
                 provider=provider,
-                config_context_length=None,  # ignore override — we want auto value
+                config_context_length=None,  # ignore override — we want the auto value
             )
         except Exception:
             auto_ctx = 0
 
-        config_ctx_int = 0
-        if isinstance(config_ctx, int) and config_ctx > 0:
-            config_ctx_int = config_ctx
+        config_ctx_int = config_ctx if isinstance(config_ctx, int) and config_ctx > 0 else 0
 
-        # Effective is what the agent actually uses
-        effective_ctx = config_ctx_int if config_ctx_int > 0 else auto_ctx
-
-        # Try to get model capabilities from models.dev
         caps = {}
         try:
             from agent.models_dev import get_model_capabilities
             mc = get_model_capabilities(provider=provider, model=model_name)
             if mc is not None:
-                caps = {
-                    "supports_tools": mc.supports_tools,
-                    "supports_vision": mc.supports_vision,
-                    "supports_reasoning": mc.supports_reasoning,
-                    "context_window": mc.context_window,
-                    "max_output_tokens": mc.max_output_tokens,
-                    "model_family": mc.model_family,
-                }
+                caps = {name: getattr(mc, name) for name in _CAPABILITY_FIELDS}
         except Exception:
             pass
 
         return {
-            "model": model_name,
-            "provider": provider,
-            "auto_context_length": auto_ctx,
+            "model": model_name, "provider": provider, "auto_context_length": auto_ctx,
             "config_context_length": config_ctx_int,
-            "effective_context_length": effective_ctx,
+            "effective_context_length": config_ctx_int or auto_ctx,  # what the agent actually uses
             "capabilities": caps,
         }
     except HTTPException:
@@ -125,39 +106,28 @@ async def get_model_options(
     include_unconfigured: bool = False,
     explicit_only: bool = False,
 ):
-    """Return authenticated providers + their curated model lists.
+    """Authenticated providers + curated model lists — REST twin of the
+    ``model.options`` JSON-RPC on tui_gateway, same response shape so
+    ``ModelPickerDialog`` shares the types.
 
-    REST equivalent of the ``model.options`` JSON-RPC on tui_gateway, so the
-    dashboard Models page can render the picker without a live chat session.
-    The response shape matches ``model.options`` 1:1 so ``ModelPickerDialog``
-    can share the same types.
-
-    ``profile`` scopes the picker context (current model/provider, custom
-    providers from config, per-profile .env auth state) so the Models page
-    reads the SAME profile /api/model/set writes.
-
-    ``refresh`` busts the per-provider model-id disk cache so every row
-    re-fetches its live catalog — used by the picker's explicit "Refresh
-    Models" control. Normal opens leave it false to stay on the 1h cache.
+    ``profile`` scopes the picker context so the Models page reads the SAME
+    profile /api/model/set writes. ``refresh`` busts the per-provider model-id
+    disk cache (picker's explicit "Refresh Models"); normal opens stay on the 1h cache.
     """
     with http_failure("GET /api/model/options failed", 500, detail="Failed to list model options"):
         skew_msg = _dashboard_code_skew_guard()
         if skew_msg:
             _log.warning("GET /api/model/options refused: %s", skew_msg)
-            raise HTTPException(
-                status_code=503, detail=f"Restart required: {skew_msg}"
-            )
+            raise HTTPException(status_code=503, detail=f"Restart required: {skew_msg}")
 
         from hermes_cli.inventory import build_model_options_payload, load_picker_context
 
         def _build_payload_scoped() -> dict:
-            # Keep the profile override inside the worker thread so the full
-            # sync picker build (config load, pricing, refresh probes) runs
-            # off the event loop under the requested profile.
-            # Use _config_profile_scope (contextvar only, no skill-module
-            # lock) — the payload build can block for 15s on a models.dev
-            # cache miss, and _profile_scope's RLock held across that block
-            # starves concurrent /api/config and freezes the server (#58576).
+            # The full sync picker build runs off the event loop under the
+            # requested profile. _config_profile_scope (contextvar only, no
+            # skill-module lock): the build can block 15s on a models.dev cache
+            # miss, and _profile_scope's RLock held across that starves
+            # concurrent /api/config and freezes the server.
             with _config_profile_scope(profile):
                 return build_model_options_payload(
                     load_picker_context(),
@@ -169,82 +139,55 @@ async def get_model_options(
         return await run_in_threadpool(_build_payload_scoped)
 
 
+def _nous_recommended_default() -> dict:
+    from hermes_cli import models as m
+    from hermes_cli.auth import get_provider_auth_state
+
+    model_ids = m.get_curated_nous_model_ids()
+    pricing = m.get_pricing_for_provider("nous") or {}
+    free_tier = m.check_nous_free_tier(force_fresh=True)
+
+    try:
+        portal_url = (get_provider_auth_state("nous") or {}).get("portal_base_url", "") or ""
+    except Exception:
+        portal_url = ""
+
+    # This endpoint picks the model a user lands on without choosing it, so an
+    # unreachable one here is worse than in a picker. Narrow to policy before
+    # the tier split, so a rescued id still has to pass the free/paid predicate.
+    policy_allowed = m.nous_policy_allowed_ids()
+    union = m.union_with_portal_free_recommendations if free_tier else m.union_with_portal_paid_recommendations
+    model_ids, pricing = union(model_ids, pricing, portal_url)
+    model_ids = m.restrict_to_nous_policy(model_ids, policy_allowed, rescue_empty=True)
+    if free_tier:
+        model_ids, _unavailable = m.partition_nous_models_by_tier(model_ids, pricing, free_tier=True)
+
+    model = m.pick_silent_default_model(model_ids, provider="nous")
+    return {"provider": "nous", "model": model, "free_tier": bool(free_tier)}
+
+
 @router.get("/api/model/recommended-default")
 def get_recommended_default_model(provider: str = ""):
-    """Return the recommended default model for a freshly-authenticated provider.
+    """Recommended default model for a freshly-authenticated provider, mirroring
+    ``hermes model``'s curation so GUI onboarding lands on a sensible default.
 
-    Mirrors the model-curation `hermes model` does so GUI onboarding lands on a
-    sensible default instead of blindly taking the first curated entry. For
-    Nous this honors the user's free/paid tier: free users get a free model,
-    paid users get the full curated default. For any other provider it falls
-    back to the first curated model (same as before).
+    Nous honors the user's free/paid tier. Any other provider gets the preferred
+    silent default when its curated list carries it, else the first curated model
+    — aggregator lists lead with the priciest Anthropic flagship, which must never
+    be the model a user lands on without explicitly picking it.
 
-    Response: {"provider": str, "model": str, "free_tier": bool | None}
-    where free_tier is True/False for Nous and None otherwise. `model` may be
-    empty if nothing could be resolved (caller degrades gracefully).
+    Response: {"provider", "model", "free_tier": bool | None} — free_tier only
+    for Nous; ``model`` may be empty (caller degrades gracefully).
     """
     slug = (provider or "").strip().lower()
 
     if slug == "nous":
         try:
-            from hermes_cli.models import (
-                get_curated_nous_model_ids,
-                get_pricing_for_provider,
-                check_nous_free_tier,
-                nous_policy_allowed_ids,
-                partition_nous_models_by_tier,
-                pick_silent_default_model,
-                restrict_to_nous_policy,
-                union_with_portal_free_recommendations,
-                union_with_portal_paid_recommendations,
-            )
-            from hermes_cli.auth import get_provider_auth_state
-
-            model_ids = get_curated_nous_model_ids()
-            pricing = get_pricing_for_provider("nous") or {}
-            free_tier = check_nous_free_tier(force_fresh=True)
-
-            portal_url = ""
-            try:
-                state = get_provider_auth_state("nous") or {}
-                portal_url = state.get("portal_base_url", "") or ""
-            except Exception:
-                portal_url = ""
-
-            # This endpoint picks the model a user lands on without choosing it,
-            # so an unreachable one here is worse than in a picker. Narrow before
-            # the tier split, so a rescued id still has to pass the free/paid
-            # predicate.
-            _policy_allowed = nous_policy_allowed_ids()
-
-            if free_tier:
-                model_ids, pricing = union_with_portal_free_recommendations(
-                    model_ids, pricing, portal_url
-                )
-                model_ids = restrict_to_nous_policy(
-                    model_ids, _policy_allowed, rescue_empty=True,
-                )
-                model_ids, _unavailable = partition_nous_models_by_tier(
-                    model_ids, pricing, free_tier=True
-                )
-            else:
-                model_ids, pricing = union_with_portal_paid_recommendations(
-                    model_ids, pricing, portal_url
-                )
-                model_ids = restrict_to_nous_policy(
-                    model_ids, _policy_allowed, rescue_empty=True,
-                )
-
-            model = pick_silent_default_model(model_ids, provider="nous")
-            return {"provider": "nous", "model": model, "free_tier": bool(free_tier)}
+            return _nous_recommended_default()
         except Exception:
             _log.exception("GET /api/model/recommended-default (nous) failed")
             return {"provider": "nous", "model": "", "free_tier": None}
 
-    # Non-Nous: preferred silent default when the provider's curated list
-    # carries it, else the first curated model. Aggregator lists lead with the
-    # priciest Anthropic flagship (claude-fable-5), which must never be the
-    # model a user lands on without explicitly picking it.
     try:
         from hermes_cli.inventory import build_models_payload, load_picker_context
         from hermes_cli.models import pick_silent_default_model
@@ -262,25 +205,14 @@ def get_recommended_default_model(provider: str = ""):
 
 @router.get("/api/model/auxiliary")
 def get_auxiliary_models(profile: Optional[str] = None):
-    """Return current auxiliary task assignments.
+    """Current auxiliary task assignments: ``{"tasks": [{task, provider, model,
+    base_url}, ...], "main": {provider, model}}``.
 
-    Shape:
-      {
-        "tasks": [
-          {"task": "vision", "provider": "auto", "model": "", "base_url": ""},
-          ...
-        ],
-        "main": {"provider": "openrouter", "model": "anthropic/claude-opus-4.7"},
-      }
-
-    ``profile`` scopes the read — without it, the Models page would show
-    the dashboard profile's auxiliary pins while /api/model/set wrote the
-    selected profile's (read/write asymmetry).
+    ``profile`` scopes the read — without it the Models page would show the
+    dashboard profile's pins while /api/model/set wrote the selected profile's.
     """
-    from hermes_cli.web_server import _AUX_TASK_SLOTS
     with http_failure("GET /api/model/auxiliary failed", 500, detail="Failed to read auxiliary config"):
-        with _profile_scope(profile):
-            cfg = load_config()
+        cfg = _load_config_scoped(profile)
         aux_cfg = cfg.get("auxiliary", {})
         if not isinstance(aux_cfg, dict):
             aux_cfg = {}
@@ -289,22 +221,12 @@ def get_auxiliary_models(profile: Optional[str] = None):
         for slot in _AUX_TASK_SLOTS:
             slot_cfg = aux_cfg.get(slot, {}) if isinstance(aux_cfg.get(slot), dict) else {}
             tasks.append({
-                "task": slot,
-                "provider": str(slot_cfg.get("provider", "auto") or "auto"),
-                "model": str(slot_cfg.get("model", "") or ""),
-                "base_url": str(slot_cfg.get("base_url", "") or ""),
+                "task": slot, "provider": str(slot_cfg.get("provider", "auto") or "auto"),
+                "model": str(slot_cfg.get("model", "") or ""), "base_url": str(slot_cfg.get("base_url", "") or ""),
             })
 
-        model_cfg = cfg.get("model", {})
-        if isinstance(model_cfg, dict):
-            main = {
-                "provider": str(model_cfg.get("provider", "") or ""),
-                "model": str(model_cfg.get("default", model_cfg.get("name", "")) or ""),
-            }
-        else:
-            main = {"provider": "", "model": str(model_cfg) if model_cfg else ""}
-
-        return {"tasks": tasks, "main": main}
+        model, provider = _main_model_fields(cfg.get("model", {}))
+        return {"tasks": tasks, "main": {"provider": str(provider or ""), "model": str(model or "")}}
 
 
 @router.get("/api/model/moa")
@@ -318,30 +240,32 @@ def get_moa_models(profile: Optional[str] = None):
             return normalize_moa_config(cfg.get("moa") if isinstance(cfg, dict) else {})
 
 
+_MOA_PRESET_FIELDS = (
+    "reference_temperature", "aggregator_temperature", "reference_timeout",
+    "degraded_reference_policy", "max_tokens", "reference_max_tokens", "fanout", "enabled",
+)
+
+
+def _slot_dict(slot: MoaModelSlot) -> dict:
+    # Drop unset optionals so saved slots stay minimal ({provider, model}).
+    return {k: v for k, v in slot.dict().items() if v is not None}
+
+
+def _preset_dict(preset) -> dict:
+    """Raw preset dict from a MoaPresetPayload or the flat MoaConfigPayload fields."""
+    return {
+        "reference_models": [_slot_dict(slot) for slot in preset.reference_models],
+        "aggregator": _slot_dict(preset.aggregator),
+        **{name: getattr(preset, name) for name in _MOA_PRESET_FIELDS},
+    }
+
+
 @router.put("/api/model/moa")
 def set_moa_models(body: MoaConfigPayload, profile: Optional[str] = None):
     """Persist the Mixture-of-Agents provider/model slots."""
     with http_failure("PUT /api/model/moa failed", 500, detail="Failed to save MoA config"):
         from hermes_cli.moa_config import normalize_moa_config, validate_moa_payload
 
-        def _slot_dict(slot: MoaModelSlot) -> dict:
-            # Drop unset optionals so saved slots stay minimal ({provider, model}).
-            return {k: v for k, v in slot.dict().items() if v is not None}
-
-        def _preset_dict(preset: MoaPresetPayload) -> dict:
-            return {
-                "reference_models": [_slot_dict(slot) for slot in preset.reference_models],
-                "aggregator": _slot_dict(preset.aggregator),
-                "reference_temperature": preset.reference_temperature,
-                "aggregator_temperature": preset.aggregator_temperature,
-                "reference_timeout": preset.reference_timeout,
-                "degraded_reference_policy": preset.degraded_reference_policy,
-                "max_tokens": preset.max_tokens,
-                "reference_max_tokens": preset.reference_max_tokens,
-                "fanout": preset.fanout,
-                "enabled": preset.enabled,
-            }
-
         with _profile_scope(body.profile or profile):
             cfg = load_config()
             if body.presets:
@@ -351,37 +275,19 @@ def set_moa_models(body: MoaConfigPayload, profile: Optional[str] = None):
                     "presets": {name: _preset_dict(preset) for name, preset in body.presets.items()},
                 }
             else:
-                raw = _preset_dict(
-                    MoaPresetPayload(
-                        reference_models=body.reference_models,
-                        aggregator=body.aggregator,
-                        reference_temperature=body.reference_temperature,
-                        aggregator_temperature=body.aggregator_temperature,
-                        reference_timeout=body.reference_timeout,
-                        degraded_reference_policy=body.degraded_reference_policy,
-                        max_tokens=body.max_tokens,
-                        reference_max_tokens=body.reference_max_tokens,
-                        fanout=body.fanout,
-                        enabled=body.enabled,
-                    )
-                )
+                raw = _preset_dict(body)  # legacy flat payload from older clients
 
             # Reject-don't-repair: normalize_moa_config() silently swaps any
             # preset containing incomplete slots for the hardcoded defaults —
-            # correct tolerance for hand-edited configs at READ time, silent
-            # data loss at WRITE time (#64156: desktop autosave of a
-            # half-filled slot replaced the user's whole preset). Refuse the
-            # save loudly so no client can corrupt config through this route.
+            # correct tolerance at READ time, silent data loss at WRITE time
+            # (desktop autosave of a half-filled slot replaced the user's whole
+            # preset). Refuse loudly so no client can corrupt config here.
             problems = validate_moa_payload(raw)
             if problems:
-                raise HTTPException(
-                    status_code=422,
-                    detail="Invalid MoA config: " + "; ".join(problems),
-                )
+                raise HTTPException(status_code=422, detail="Invalid MoA config: " + "; ".join(problems))
             normalized = normalize_moa_config(raw)
-            # Merge instead of overwrite so that hand-edited keys not declared
-            # in MoaConfigPayload (e.g. save_traces, trace_dir) survive a GUI
-            # save.  See issue #58819.
+            # Merge instead of overwrite so hand-edited keys not declared in
+            # MoaConfigPayload (e.g. save_traces, trace_dir) survive a GUI save.
             cfg.setdefault("moa", {}).update(normalized)
             save_config(cfg)
             return {"ok": True, **normalized}
@@ -391,16 +297,12 @@ def set_moa_models(body: MoaConfigPayload, profile: Optional[str] = None):
 async def set_model_assignment(body: ModelAssignment, profile: Optional[str] = None):
     """Assign a model to the main slot or an auxiliary task slot.
 
-    Writes to ``~/.hermes/config.yaml`` — applies to **new** sessions only.
-    The currently running chat PTY (if any) is not affected; use the
-    ``/model`` slash command inside a chat to hot-swap that specific session.
+    Writes ``~/.hermes/config.yaml`` — applies to **new** sessions only; a
+    running chat PTY hot-swaps via the ``/model`` slash command instead.
     """
-    scope = (body.scope or "").strip().lower()
-    provider = (body.provider or "").strip()
-    model = (body.model or "").strip()
-    task = (body.task or "").strip().lower()
-    base_url = (body.base_url or "").strip()
-    api_key = (body.api_key or "").strip()
+    scope, task = (body.scope or "").strip().lower(), (body.task or "").strip().lower()
+    provider, model = (body.provider or "").strip(), (body.model or "").strip()
+    base_url, api_key = (body.base_url or "").strip(), (body.api_key or "").strip()
 
     if scope not in {"main", "auxiliary"}:
         raise HTTPException(status_code=400, detail="scope must be 'main' or 'auxiliary'")
@@ -417,27 +319,16 @@ async def set_model_assignment(body: ModelAssignment, profile: Optional[str] = N
                 # Pricing lookup can hit models.dev / a /models endpoint on a
                 # cache miss — keep it off the event loop.
                 warning = await asyncio.to_thread(
-                    combined_selection_warning,
-                    model,
-                    provider=provider,
-                    base_url=base_url,
+                    combined_selection_warning, model, provider=provider, base_url=base_url
                 )
             except Exception:
                 warning = None
             if warning is not None:
-                return {
-                    "ok": False,
-                    "scope": scope,
-                    "provider": provider,
-                    "model": model,
-                    "confirm_required": True,
-                    "confirm_message": warning.message,
-                }
+                return {"ok": False, "scope": scope, "provider": provider, "model": model,
+                        "confirm_required": True, "confirm_message": warning.message}
 
         def _apply_assignment():
             with _profile_scope(body.profile or profile):
-                return _apply_model_assignment_sync(
-                    scope, provider, model, task, base_url, api_key
-                )
+                return _apply_model_assignment_sync(scope, provider, model, task, base_url, api_key)
 
         return await asyncio.to_thread(_apply_assignment)