From b965a285ca6f71d7d699225bd355562fb31f4b81 Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Sun, 26 Jul 2026 04:45:34 +0000
Subject: [PATCH 01/56] Studio: say which model is missing instead of "No model
 loaded"

A /v1 request naming a model that is not downloaded returned the generic
"No model loaded. Call POST /inference/load first.", which cannot fix it.
Return 404 model_not_found naming the model and listing what can serve,
and make the API usage examples name a model the server actually has.
---
 .../core/inference/local_model_resolver.py    |  27 ++
 studio/backend/routes/inference.py            | 174 +++++++++++--
 .../backend/tests/test_openai_auto_switch.py  | 241 +++++++++++++++++-
 .../features/settings/api/openai-models.ts    |  38 +++
 .../settings/components/usage-examples.tsx    | 209 ++++-----------
 ...st_usage_examples_model_source_contract.py |  47 ++++
 6 files changed, 546 insertions(+), 190 deletions(-)
 create mode 100644 studio/frontend/src/features/settings/api/openai-models.ts
 create mode 100644 tests/studio/test_usage_examples_model_source_contract.py

diff --git a/studio/backend/core/inference/local_model_resolver.py b/studio/backend/core/inference/local_model_resolver.py
index 9e3eaeda3f8..3c5e55ed873 100644
--- a/studio/backend/core/inference/local_model_resolver.py
+++ b/studio/backend/core/inference/local_model_resolver.py
@@ -277,3 +277,30 @@ def resolve_local_gguf(requested: str) -> Optional[tuple[str, Optional[str], str
         # Best-effort: any resolver failure falls through to the loaded model,
         # so a malformed name can never turn a servable request into a 500.
         return None
+
+
+MISS_MODEL_NOT_FOUND = "model_not_found"
+MISS_VARIANT_NOT_FOUND = "variant_not_found"
+
+
+def describe_local_miss(requested: str) -> tuple[str, tuple[str, ...]]:
+    """Why :func:`resolve_local_gguf` missed, so an error can say "wrong quant"
+    instead of "no such model".
+
+    ``(MISS_VARIANT_NOT_FOUND, <local quants>)`` when the repo is downloaded but
+    the requested ``:VARIANT`` is not, else ``(MISS_MODEL_NOT_FOUND, ())``. Splits
+    the name like the resolver so the two agree. Fail-safe: a scan failure reports
+    the generic miss rather than raising into the handler.
+    """
+    if not isinstance(requested, str) or not requested.strip():
+        return MISS_MODEL_NOT_FOUND, ()
+    base, sep, _variant = requested.strip().rpartition(":")
+    if not sep:
+        return MISS_MODEL_NOT_FOUND, ()
+    try:
+        entry = _index().get(base.strip().lower())
+    except Exception:
+        return MISS_MODEL_NOT_FOUND, ()
+    if entry is None or not entry.variants:
+        return MISS_MODEL_NOT_FOUND, ()
+    return MISS_VARIANT_NOT_FOUND, entry.variants
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 9d40650a569..46df46a54a7 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -28,7 +28,7 @@
 # Model size extraction (shared with core/inference/llama_cpp.py)
 from utils.models import extract_model_size_b as _extract_model_size_b
 
-from utils.api_errors import openai_error_body, anthropic_error_body
+from utils.api_errors import openai_error_body, anthropic_error_body, error_body_for_path
 from utils.upload_limits import STT_AUDIO_B64_MAX_CHARS, STT_AUDIO_RAW_MAX_BYTES
 from hub.dependencies import get_hf_token
 from core.inference.orchestrator import GenStreamError, GenStreamErrorRaised
@@ -3562,6 +3562,116 @@ def _no_model_loaded_detail(base: str) -> str:
     )
 
 
+# Cap on ids listed by a "not downloaded" error: useful in a terminal without
+# burying the message.
+_MAX_LISTED_AVAILABLE_MODELS = 8
+
+
+def _raw_body_model(body) -> Optional[str]:
+    """The ``model`` a raw-body endpoint was given, else None (same value
+    :func:`_auto_switch_from_request_body` fed the switch hook)."""
+    return body.get("model") if isinstance(body, dict) else None
+
+
+async def _available_model_ids() -> list[str]:
+    """Sorted ids a /v1 request may name, from the catalog ``GET /v1/models``
+    serves, so an error and the listing can't disagree."""
+    return sorted(
+        mid for mid in (m.get("id") for m in await _openai_catalog_objects())
+        if isinstance(mid, str) and mid
+    )
+
+
+def _format_available_models(ids: list[str]) -> str:
+    if not ids:
+        return ""
+    shown = ", ".join(ids[:_MAX_LISTED_AVAILABLE_MODELS])
+    extra = len(ids) - _MAX_LISTED_AVAILABLE_MODELS
+    return f"{shown} and {extra} more" if extra > 0 else shown
+
+
+async def _unavailable_model_message(requested_model: str) -> str:
+    """Why a named model can't serve this request, and what can.
+
+    Auto-switch only loads already-downloaded GGUFs, so a request naming a real
+    model usually fails because it is not on this machine. Pointing the caller at
+    /inference/load cannot fix that; say what is actually wrong.
+    """
+    from core.inference.local_model_resolver import (
+        MISS_VARIANT_NOT_FOUND,
+        describe_local_miss,
+    )
+
+    reason, variants = await asyncio.to_thread(describe_local_miss, requested_model)
+    if reason == MISS_VARIANT_NOT_FOUND:
+        # Repo downloaded, only the quant missing: sibling quants beat the catalog.
+        base_id, _, wanted = requested_model.strip().rpartition(":")
+        return (
+            f"The model '{base_id}' is downloaded, but the quant '{wanted}' is not. "
+            f"Available quants: {', '.join(variants)}."
+        )
+    available = _format_available_models(await _available_model_ids())
+    if not available:
+        return (
+            f"The model '{requested_model}' is not downloaded on this server, and no "
+            "models are downloaded yet. Download one in Unsloth Studio."
+        )
+    return (
+        f"The model '{requested_model}' is not downloaded on this server. "
+        f"Available models: {available}. Download more in Unsloth Studio, "
+        "or list them with GET /v1/models."
+    )
+
+
+async def _no_model_loaded_error(
+    base: str,
+    requested_model: Optional[str],
+    fastapi_request: Optional[Request],
+    *,
+    status: int,
+):
+    """``(status, detail)`` for the /v1 sites that fail because nothing is loaded.
+
+    Changes only the case the generic text describes wrongly: auto-switch on, a
+    model named, and that name resolves to nothing local, so the switch silently
+    did nothing. That becomes a 404 model_not_found. Toggle off or no model named
+    keeps ``status`` and the :func:`_no_model_loaded_detail` text verbatim.
+    """
+    from utils.openai_auto_switch_settings import get_openai_auto_switch_enabled
+    from core.inference.local_model_resolver import resolve_local_gguf
+
+    named = (
+        requested_model
+        if isinstance(requested_model, str)
+        and requested_model.strip()
+        and requested_model != _RELOAD_ONLY_MODEL
+        else None
+    )
+    if named is None or not get_openai_auto_switch_enabled():
+        return status, _no_model_loaded_detail(base)
+    try:
+        if await asyncio.to_thread(resolve_local_gguf, named) is not None:
+            # Resolvable but unloaded: the switch failed (load error, race), which
+            # the generic text describes correctly.
+            return status, _no_model_loaded_detail(base)
+        message = await _unavailable_model_message(named)
+    except Exception as exc:
+        # The diagnosis is a nicety; never let it turn a 4xx into a 500.
+        logger.debug("no-model-loaded diagnosis failed for %r: %s", named, exc)
+        return status, _no_model_loaded_detail(base)
+    path = getattr(getattr(fastapi_request, "url", None), "path", None)
+    if not isinstance(path, str):
+        # No request in hand: let the global /v1/* handler pick the envelope.
+        return 404, message
+    return 404, error_body_for_path(
+        path,
+        message,
+        status = 404,
+        code = "model_not_found",
+        param = "model",
+    )
+
+
 async def _maybe_auto_switch_model(
     requested_model: Optional[str],
     fastapi_request: Request,
@@ -7754,10 +7864,13 @@ async def _monitored_generate_audio(model_label: str, context_length: Optional[i
     else:
         backend = get_inference_backend()
         if not backend.active_model_name:
-            raise HTTPException(
-                status_code = 400,
-                detail = _no_model_loaded_detail("No model loaded. Call POST /inference/load first."),
+            _status, _detail = await _no_model_loaded_error(
+                "No model loaded. Call POST /inference/load first.",
+                _switch_model_for_payload(payload),
+                request,
+                status = 400,
             )
+            raise HTTPException(status_code = _status, detail = _detail)
         # Clean public id so the response never echoes a local path; the audio
         # branch below receives this sanitized label too.
         model_name = public_model_id(backend.active_model_name) or payload.model
@@ -10721,10 +10834,13 @@ async def openai_completions(request: Request, current_subject: str = Depends(ge
     # Opt-in: load the requested local GGUF before the loaded-state check.
     body = await _auto_switch_from_request_body(request, current_subject)
     if not llama_backend.is_loaded:
-        raise HTTPException(
-            status_code = 503,
-            detail = _no_model_loaded_detail("No GGUF model loaded. Load a GGUF model first."),
+        _status, _detail = await _no_model_loaded_error(
+            "No GGUF model loaded. Load a GGUF model first.",
+            _raw_body_model(body),
+            request,
+            status = 503,
         )
+        raise HTTPException(status_code = _status, detail = _detail)
     if not isinstance(body, dict):
         # Re-read to re-raise a malformed-body error (post-503, pre-feature behavior);
         # a valid non-dict body such as a list is a clean 400 rather than a 500.
@@ -10941,10 +11057,13 @@ async def openai_embeddings(request: Request, current_subject: str = Depends(get
     # a non-embedding target switches, then llama-server returns a no-pooling error.
     body = await _auto_switch_from_request_body(request, current_subject)
     if not llama_backend.is_loaded:
-        raise HTTPException(
-            status_code = 503,
-            detail = _no_model_loaded_detail("No GGUF model loaded. Load a GGUF model first."),
+        _status, _detail = await _no_model_loaded_error(
+            "No GGUF model loaded. Load a GGUF model first.",
+            _raw_body_model(body),
+            request,
+            status = 503,
         )
+        raise HTTPException(status_code = _status, detail = _detail)
     if not isinstance(body, dict):
         # Re-read to re-raise a malformed-body error (post-503, pre-feature behavior);
         # a valid non-dict body such as a list is a clean 400 rather than a 500.
@@ -11681,14 +11800,15 @@ async def _responses_stream(
         # double-layer asyncgen close pattern that produces "Attempted to exit
         # cancel scope in a different task" on Python 3.13. Surface a typed 400
         # so the client sees a useful error instead of a dangling stream.
-        raise HTTPException(
-            status_code = 400,
-            detail = _no_model_loaded_detail(
-                "Streaming /v1/responses requires a GGUF model loaded via "
-                "llama-server. Use non-streaming /v1/responses, "
-                "/v1/chat/completions, or load a GGUF model."
-            ),
+        _status, _detail = await _no_model_loaded_error(
+            "Streaming /v1/responses requires a GGUF model loaded via "
+            "llama-server. Use non-streaming /v1/responses, "
+            "/v1/chat/completions, or load a GGUF model.",
+            _switch_model_for_payload(payload),
+            request,
+            status = 400,
         )
+        raise HTTPException(status_code = _status, detail = _detail)
 
     # Direct pass-through bypasses the openai_chat_completions image gate.
     if not llama_backend.is_vision and any(
@@ -12930,10 +13050,13 @@ async def anthropic_count_tokens(
 
     llama_backend = get_llama_cpp_backend()
     if not llama_backend.is_loaded:
-        raise HTTPException(
-            status_code = 503,
-            detail = _no_model_loaded_detail("No GGUF model loaded. Load a GGUF model first."),
+        _status, _detail = await _no_model_loaded_error(
+            "No GGUF model loaded. Load a GGUF model first.",
+            _switch_model_for_payload(payload),
+            request,
+            status = 503,
         )
+        raise HTTPException(status_code = _status, detail = _detail)
 
     # Same Anthropic → OpenAI translation as anthropic_messages: system is
     # folded into the messages list, so pass system=None to the counter.
@@ -13002,6 +13125,8 @@ async def anthropic_messages(
     # before any request-shape check, exactly as the pre-feature endpoint did. When
     # an automatic load can run (auto-switch or a standalone idle TTL), fall through
     # so validation runs before the reload hook gets a chance to restore the model.
+    # Plain detail, not _no_model_loaded_error: no automatic load was possible, the
+    # case that helper leaves unchanged. The 404 comes from the post-switch check below.
     if not llama_backend.is_loaded and not _automatic_model_load_may_run():
         raise HTTPException(
             status_code = 503,
@@ -13101,10 +13226,13 @@ async def anthropic_messages(
         require_vision = _anthropic_request_has_image(payload),
     )
     if not llama_backend.is_loaded:
-        raise HTTPException(
-            status_code = 503,
-            detail = _no_model_loaded_detail("No GGUF model loaded. Load a GGUF model first."),
+        _status, _detail = await _no_model_loaded_error(
+            "No GGUF model loaded. Load a GGUF model first.",
+            _switch_model_for_payload(payload),
+            request,
+            status = 503,
         )
+        raise HTTPException(status_code = _status, detail = _detail)
 
     # Advertised repo id after an auto-switch load, else a clean public id, never
     # the local .gguf path (and a legacy raw path in payload.model is sanitized).
diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index 9c6c20e6b6f..a614a0bc030 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -387,6 +387,50 @@ def test_resolver_nonstring_model_is_failsafe():
     assert resolver.resolve_local_gguf(None) is None
 
 
+def test_describe_local_miss_separates_missing_repo_from_missing_quant(monkeypatch):
+    # A miss is two different situations and the error should say which: the repo
+    # isn't downloaded, or it is and only that quant is absent.
+    monkeypatch.setattr(
+        resolver,
+        "_build_index",
+        lambda: {"unsloth/b-gguf": _entry("unsloth/B-GGUF", "UD-Q5_K_XL", "Q4_K_M")},
+    )
+    resolver._scan = (0.0, {})
+    assert resolver.describe_local_miss("unsloth/B-GGUF:Q8_0") == (
+        resolver.MISS_VARIANT_NOT_FOUND,
+        ("UD-Q5_K_XL", "Q4_K_M"),
+    )
+    # Split the same way resolve_local_gguf does, so the two never disagree.
+    assert resolver.describe_local_miss("unsloth/b-gguf:q8_0")[0] == (
+        resolver.MISS_VARIANT_NOT_FOUND
+    )
+    # Unknown repo, and a bare id with no ":VARIANT" to blame.
+    assert resolver.describe_local_miss("totally/unknown:Q8_0") == (
+        resolver.MISS_MODEL_NOT_FOUND,
+        (),
+    )
+    assert resolver.describe_local_miss("unsloth/B-GGUF") == (
+        resolver.MISS_MODEL_NOT_FOUND,
+        (),
+    )
+
+
+def test_describe_local_miss_is_failsafe(monkeypatch):
+    # Runs inside an error path, so a broken scan must degrade to the generic miss
+    # rather than raise a 500 over what was already a 4xx.
+    def boom():
+        raise RuntimeError("scan blew up")
+
+    monkeypatch.setattr(resolver, "_build_index", boom)
+    resolver._scan = (0.0, {})
+    assert resolver.describe_local_miss("unsloth/B-GGUF:Q8_0") == (
+        resolver.MISS_MODEL_NOT_FOUND,
+        (),
+    )
+    assert resolver.describe_local_miss(123) == (resolver.MISS_MODEL_NOT_FOUND, ())
+    assert resolver.describe_local_miss("") == (resolver.MISS_MODEL_NOT_FOUND, ())
+
+
 def test_resolver_exact_id_with_colon_wins(monkeypatch):
     # A local id that itself contains a colon (e.g. a Windows path) must match
     # exactly rather than being split at the drive-letter colon.
@@ -3240,13 +3284,14 @@ def test_no_model_loaded_detail_appends_hint_only_when_off(monkeypatch):
     assert inference_route._no_model_loaded_detail(base) == base
 
 
-def _run_responses_stream_no_model(monkeypatch, *, enabled, active_model_name):
+def _run_responses_stream_no_model(monkeypatch, *, enabled, active_model_name, resolves_to = None):
     # Drive _responses_stream's GGUF-not-loaded guard: llama backend unloaded,
-    # inference backend maybe holding a non-GGUF model. Returns the 400 detail.
+    # inference backend maybe holding a non-GGUF model. Returns (status, detail).
     from fastapi import HTTPException
     from models.inference import ResponsesRequest, ChatMessage
 
     monkeypatch.setattr(settings, "get_openai_auto_switch_enabled", lambda: enabled)
+    monkeypatch.setattr(resolver, "resolve_local_gguf", lambda name: resolves_to)
     monkeypatch.setattr(
         inference_route, "get_llama_cpp_backend", lambda: _FakeBackend(loaded_id = None)
     )
@@ -3259,29 +3304,199 @@ def _run_responses_stream_no_model(monkeypatch, *, enabled, active_model_name):
     messages = [ChatMessage(role = "user", content = "hi")]
     with pytest.raises(HTTPException) as exc:
         asyncio.run(inference_route._responses_stream(payload, messages, None))
-    assert exc.value.status_code == 400
-    return exc.value.detail
+    return exc.value.status_code, exc.value.detail
 
 
 def test_responses_stream_hint_matches_toggle_regardless_of_active_model(monkeypatch):
-    # Streaming /v1/responses shares the GGUF-only 400 with the other "no model
-    # loaded" sites, so the auto-switch hint attaches whenever the toggle is
-    # off -- including while a non-GGUF model is active, since auto-switch
-    # evicts it to load a resolved GGUF (_maybe_auto_switch_model's resolver
-    # branch has no active-model guard, unlike its reload-stash branch). Only
-    # the toggle being on suppresses it.
-    hinted = _run_responses_stream_no_model(monkeypatch, enabled = False, active_model_name = None)
+    # The hint attaches whenever the toggle is off, including while a non-GGUF
+    # model is active, since auto-switch evicts it to load a resolved GGUF
+    # (the resolver branch has no active-model guard, unlike the reload stash).
+    # With it on the error changes kind: the name resolved to nothing local, so
+    # 404 model_not_found rather than a 400 pointing at /inference/load.
+    off_status, hinted = _run_responses_stream_no_model(
+        monkeypatch, enabled = False, active_model_name = None
+    )
+    assert off_status == 400
     assert "Model auto-switch" in hinted
 
-    on = _run_responses_stream_no_model(monkeypatch, enabled = True, active_model_name = None)
+    on_status, on = _run_responses_stream_no_model(
+        monkeypatch, enabled = True, active_model_name = None
+    )
+    assert on_status == 404
     assert "Model auto-switch" not in on
+    assert "unsloth/Qwen3.5-4B-GGUF" in on
 
-    non_gguf_loaded = _run_responses_stream_no_model(
+    non_gguf_status, non_gguf_loaded = _run_responses_stream_no_model(
         monkeypatch, enabled = False, active_model_name = "unsloth/Llama-3.2-1B-Instruct"
     )
+    assert non_gguf_status == 400
     assert "Model auto-switch" in non_gguf_loaded
 
 
+def _wire_unloaded_chat(monkeypatch, *, enabled, catalog = ("org/A-GGUF", "org/B-GGUF")):
+    # Nothing loaded, so a chat request reaches the "no model loaded" error. Pin
+    # the catalog so listed ids don't depend on what is cached on the test machine.
+    async def _catalog():
+        return [{"id": mid} for mid in catalog]
+
+    monkeypatch.setattr(settings, "get_openai_auto_switch_enabled", lambda: enabled)
+    monkeypatch.setattr(resolver, "resolve_local_gguf", lambda _m: None)
+    monkeypatch.setattr(
+        resolver, "describe_local_miss", lambda _m: (resolver.MISS_MODEL_NOT_FOUND, ())
+    )
+    monkeypatch.setattr(inference_route, "_openai_catalog_objects", _catalog)
+    monkeypatch.setattr(
+        inference_route, "get_llama_cpp_backend", lambda: _FakeBackend(loaded_id = None)
+    )
+    monkeypatch.setattr(
+        inference_route,
+        "get_inference_backend",
+        lambda: type("_B", (), {"active_model_name": None, "models": {}})(),
+    )
+
+
+def _chat_error(payload):
+    from fastapi import HTTPException
+
+    with pytest.raises(HTTPException) as exc:
+        asyncio.run(inference_route.openai_chat_completions(payload, object(), "tester"))
+    return exc.value.status_code, exc.value.detail
+
+
+def test_chat_names_undownloaded_model_404s_with_available_ids(monkeypatch):
+    # The reported bug: auto-switch on, the named model is not on this machine, so
+    # the switch silently did nothing and /inference/load cannot fix it. Name the
+    # model and list what can serve, from the catalog GET /v1/models returns.
+    _wire_unloaded_chat(monkeypatch, enabled = True)
+    status, detail = _chat_error(_chat_request(model = "unsloth/gemma-4-E4B-it-GGUF:UD-Q5_K_XL"))
+    assert status == 404
+    assert "unsloth/gemma-4-E4B-it-GGUF:UD-Q5_K_XL" in detail
+    assert "org/A-GGUF, org/B-GGUF" in detail
+    assert "GET /v1/models" in detail
+    assert "POST /inference/load" not in detail
+
+
+def test_chat_undownloaded_model_with_empty_catalog(monkeypatch):
+    # Nothing downloaded: an empty list would read as a bug, so say so plainly.
+    _wire_unloaded_chat(monkeypatch, enabled = True, catalog = ())
+    status, detail = _chat_error(_chat_request(model = "org/nope-GGUF"))
+    assert status == 404
+    assert "no models are downloaded yet" in detail
+
+
+def test_chat_wrong_quant_lists_the_local_quants(monkeypatch):
+    # Repo downloaded, only the quant missing: sibling quants, not the catalog.
+    _wire_unloaded_chat(monkeypatch, enabled = True)
+    monkeypatch.setattr(
+        resolver,
+        "describe_local_miss",
+        lambda _m: (resolver.MISS_VARIANT_NOT_FOUND, ("Q4_K_M", "Q8_0")),
+    )
+    status, detail = _chat_error(_chat_request(model = "org/A-GGUF:UD-Q5_K_XL"))
+    assert status == 404
+    assert "'org/A-GGUF' is downloaded, but the quant 'UD-Q5_K_XL' is not" in detail
+    assert "Q4_K_M, Q8_0" in detail
+
+
+def test_chat_error_unchanged_when_auto_switch_off(monkeypatch):
+    # Toggle off: nothing was resolved, so "not downloaded" would be a guess. Keep
+    # the pre-existing status and text, hint included.
+    _wire_unloaded_chat(monkeypatch, enabled = False)
+    status, detail = _chat_error(_chat_request(model = "org/nope-GGUF"))
+    assert status == 400
+    assert detail.startswith("No model loaded. Call POST /inference/load first.")
+    assert "Model auto-switch" in detail
+
+
+def test_chat_error_unchanged_when_no_model_named(monkeypatch):
+    # An omitted model means "serve whatever is loaded", so the generic text is
+    # right and there is no name to report as missing.
+    _wire_unloaded_chat(monkeypatch, enabled = True)
+    status, detail = _chat_error(_chat_request())
+    assert status == 400
+    assert detail == "No model loaded. Call POST /inference/load first."
+
+
+def test_chat_not_downloaded_error_survives_a_broken_catalog_scan(monkeypatch):
+    # The diagnosis is layered onto an already-failing path: a scan blowing up
+    # must not turn the 4xx into a 500.
+    async def _boom():
+        raise RuntimeError("catalog scan blew up")
+
+    _wire_unloaded_chat(monkeypatch, enabled = True)
+    monkeypatch.setattr(inference_route, "_openai_catalog_objects", _boom)
+    status, detail = _chat_error(_chat_request(model = "org/nope-GGUF"))
+    assert status == 400
+    assert detail.startswith("No model loaded. Call POST /inference/load first.")
+
+
+def test_chat_available_id_list_is_capped(monkeypatch):
+    # A machine with 40 GGUFs must not print all 40 into a terminal error.
+    _wire_unloaded_chat(
+        monkeypatch, enabled = True, catalog = tuple(f"org/m{i:02d}-GGUF" for i in range(20))
+    )
+    status, detail = _chat_error(_chat_request(model = "org/nope-GGUF"))
+    assert status == 404
+    assert "and 12 more" in detail
+    assert "org/m08-GGUF" not in detail
+
+
+def test_anthropic_undownloaded_model_uses_the_anthropic_envelope(monkeypatch):
+    # Shared with /v1/messages, so the 404 must not leak an OpenAI-shaped body.
+    from fastapi import HTTPException
+
+    async def _noop_switch(*a, **k):
+        return None
+
+    _wire_unloaded_chat(monkeypatch, enabled = True)
+    monkeypatch.setattr(inference_route, "_automatic_model_load_may_run", lambda: True)
+    monkeypatch.setattr(inference_route, "_maybe_auto_switch_model", _noop_switch)
+
+    request = type("_R", (), {"url": type("_U", (), {"path": "/v1/messages"})()})()
+    with pytest.raises(HTTPException) as exc:
+        asyncio.run(
+            inference_route.anthropic_messages(_anthropic_payload(64), request, "tester")
+        )
+    assert exc.value.status_code == 404
+    body = exc.value.detail
+    assert body["type"] == "error"
+    assert body["error"]["type"] == "not_found_error"
+    assert "claude-x" in body["error"]["message"]
+
+
+def test_chat_undownloaded_model_uses_the_openai_envelope(monkeypatch):
+    # On the OpenAI surface it carries param/code so SDK clients can branch on it,
+    # matching GET /v1/models/{id}'s existing model_not_found.
+    from fastapi import HTTPException
+
+    _wire_unloaded_chat(monkeypatch, enabled = True)
+    request = type("_R", (), {"url": type("_U", (), {"path": "/v1/chat/completions"})()})()
+    with pytest.raises(HTTPException) as exc:
+        asyncio.run(
+            inference_route.openai_chat_completions(
+                _chat_request(model = "org/nope-GGUF"), request, "tester"
+            )
+        )
+    assert exc.value.status_code == 404
+    err = exc.value.detail["error"]
+    assert err["type"] == "not_found_error"
+    assert err["code"] == "model_not_found"
+    assert err["param"] == "model"
+
+
+def test_responses_stream_keeps_generic_error_when_target_is_local(monkeypatch):
+    # Name resolves locally yet nothing is loaded: the switch failed, so the
+    # generic text is right and the status stays 400, not a bogus "missing".
+    status, detail = _run_responses_stream_no_model(
+        monkeypatch,
+        enabled = True,
+        active_model_name = None,
+        resolves_to = ("/p/A", "Q4_K_M", "unsloth/Qwen3.5-4B-GGUF"),
+    )
+    assert status == 400
+    assert "not downloaded" not in detail
+
+
 # ── idle-unload KV persistence (slot save/restore) ──────────────────
 
 
diff --git a/studio/frontend/src/features/settings/api/openai-models.ts b/studio/frontend/src/features/settings/api/openai-models.ts
new file mode 100644
index 00000000000..31c651f5c2d
--- /dev/null
+++ b/studio/frontend/src/features/settings/api/openai-models.ts
@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { authFetch } from "@/features/auth";
+
+export type OpenAIModel = {
+  id: string;
+  // Resident in memory now; the rest are downloaded and servable.
+  loaded?: boolean;
+};
+
+type ApiOpenAIModelList = {
+  data?: { id?: unknown; loaded?: unknown }[];
+};
+
+/**
+ * The models this server can serve.
+ *
+ * `/v1/models` rather than the hub inventory: it returns exactly the ids
+ * `/v1/chat/completions` resolves against, so a snippet built from it is
+ * runnable as printed. `/v1` accepts the UI session JWT as well as
+ * `sk-unsloth-` keys, so `authFetch` works unchanged.
+ */
+export async function listOpenAIModels(): Promise<OpenAIModel[]> {
+  const res = await authFetch("/v1/models");
+  if (!res.ok) {
+    throw new Error(`Failed to list models (${res.status})`);
+  }
+  const body = (await res.json()) as ApiOpenAIModelList;
+  if (!Array.isArray(body?.data)) {
+    return [];
+  }
+  return body.data.flatMap((entry) =>
+    typeof entry?.id === "string" && entry.id
+      ? [{ id: entry.id, loaded: entry.loaded === true }]
+      : [],
+  );
+}
diff --git a/studio/frontend/src/features/settings/components/usage-examples.tsx b/studio/frontend/src/features/settings/components/usage-examples.tsx
index ade181f632b..3fdb65ea3a2 100644
--- a/studio/frontend/src/features/settings/components/usage-examples.tsx
+++ b/studio/frontend/src/features/settings/components/usage-examples.tsx
@@ -29,11 +29,7 @@ import { HugeiconsIcon } from "@hugeicons/react";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { Streamdown } from "streamdown";
 import { loadCodingAgents } from "../api/coding-agents";
-import {
-  type OpenAIAutoSwitchSettings,
-  loadOpenAIAutoSwitchSettings,
-  updateOpenAIAutoSwitchSettings,
-} from "../api/openai-auto-switch";
+import { type OpenAIModel, listOpenAIModels } from "../api/openai-models";
 import { buildAgentCommand, isLoopbackHost, normalizeHost } from "./agent-command";
 
 type ExampleType =
@@ -90,13 +86,6 @@ const JAVASCRIPT_TYPES = new Set<ExampleType>([
 ]);
 
 const PROMPT = "Can Unsloth Studio do API calling?";
-// Auto-switch demo: a second call naming a different downloaded GGUF so the
-// example shows that the model field selects which model serves.
-// A placeholder the user replaces with one of their downloaded GGUFs. A fixed
-// repo is usually not one they have, so the resolver would fall through and the
-// demo would keep serving the current model instead of switching.
-const SWITCH_MODEL = "your-other-downloaded-GGUF";
-const SWITCH_PROMPT = "Now answer as a different model.";
 // web_search + python + terminal are the reliable built-in tools.
 const TOOLS = ["web_search", "python", "terminal"];
 const ADV = {
@@ -195,19 +184,13 @@ function winBody(model: string, variant: Variant): string {
   return JSON.stringify(body, null, 2);
 }
 
-// A leading comment (valid in both bash and PowerShell) noting the model field
-// selects the served model when auto-switch is on.
-const SWITCH_NOTE =
-  '# "Switch model by request" is on: set "model" to any downloaded GGUF to switch.\n';
-
 function curlUnix(
   base: string,
   key: string,
   model: string,
   variant: Variant,
-  autoSwitch: boolean,
 ): string {
-  return `${autoSwitch ? SWITCH_NOTE : ""}curl ${base}/v1/chat/completions \\
+  return `curl ${base}/v1/chat/completions \\
   -H "Authorization: Bearer ${key}" \\
   -H "Content-Type: application/json" \\
   -d '${shSingle(curlBodyPretty(model, variant))}'`;
@@ -218,9 +201,8 @@ function curlWindows(
   key: string,
   model: string,
   variant: Variant,
-  autoSwitch: boolean,
 ): string {
-  return `${autoSwitch ? SWITCH_NOTE : ""}$body = '${psSingle(winBody(model, variant))}'
+  return `$body = '${psSingle(winBody(model, variant))}'
 Set-Content -Path body.json -Value $body -Encoding ascii
 curl.exe ${base}/v1/chat/completions \`
   -H "Authorization: Bearer ${key}" \`
@@ -228,29 +210,11 @@ curl.exe ${base}/v1/chat/completions \`
   -d "@body.json"`;
 }
 
-// A second OpenAI call naming a different downloaded GGUF: with auto-switch on,
-// Unsloth loads it before serving, so the model field selects the served model.
-function pythonSwitchDemo(): string {
-  return `
-
-# "Switch model by request" is on: replace the model below with another GGUF you
-# have downloaded and Unsloth loads it before serving. Unknown names keep serving
-# the current model.
-response = client.chat.completions.create(
-    model=${j(SWITCH_MODEL)},
-    messages=[{"role": "user", "content": ${j(SWITCH_PROMPT)}}],
-    stream=True,
-)
-for chunk in response:
-    print(chunk.choices[0].delta.content or "", end="")`;
-}
-
 function pythonSnippet(
   base: string,
   key: string,
   model: string,
   variant: Variant,
-  autoSwitch: boolean,
 ): string {
   const named =
     variant === "advanced"
@@ -295,7 +259,7 @@ response = client.chat.completions.create(
     messages=[{"role": "user", "content": ${j(PROMPT)}}],${named}${extraBody}
     stream=True,
 )
-${loop}${autoSwitch ? pythonSwitchDemo() : ""}`;
+${loop}`;
 }
 
 function javascriptSnippet(
@@ -303,7 +267,6 @@ function javascriptSnippet(
   key: string,
   model: string,
   variant: Variant,
-  autoSwitch: boolean,
 ): string {
   const options: string[] = [];
   if (variant === "advanced") {
@@ -342,23 +305,6 @@ const response = await client.chat.completions.create({
 
 for await (const chunk of response) {
   process.stdout.write(chunk.choices?.[0]?.delta?.content || "");
-}${autoSwitch ? javascriptSwitchDemo() : ""}`;
-}
-
-function javascriptSwitchDemo(): string {
-  return `
-
-// "Switch model by request" is on: replace the model below with another GGUF you
-// have downloaded and Unsloth loads it before serving. Unknown names keep serving
-// the current model.
-const switchResponse = await client.chat.completions.create({
-  model: ${j(SWITCH_MODEL)},
-  messages: [{ role: "user", content: ${j(SWITCH_PROMPT)} }],
-  stream: true,
-});
-
-for await (const chunk of switchResponse) {
-  process.stdout.write(chunk.choices?.[0]?.delta?.content || "");
 }`;
 }
 
@@ -367,25 +313,18 @@ function buildSnippets(
   key: string,
   model: string,
   os: Os,
-  autoSwitch: boolean,
 ): Record<ExampleType, string> {
   const curl = os === "windows" ? curlWindows : curlUnix;
   return {
-    curl: curl(base, key, model, "plain", autoSwitch),
-    python: pythonSnippet(base, key, model, "plain", autoSwitch),
-    javascript: javascriptSnippet(base, key, model, "plain", autoSwitch),
-    curlTools: curl(base, key, model, "tools", autoSwitch),
-    pythonTools: pythonSnippet(base, key, model, "tools", autoSwitch),
-    javascriptTools: javascriptSnippet(base, key, model, "tools", autoSwitch),
-    curlAdvanced: curl(base, key, model, "advanced", autoSwitch),
-    pythonAdvanced: pythonSnippet(base, key, model, "advanced", autoSwitch),
-    javascriptAdvanced: javascriptSnippet(
-      base,
-      key,
-      model,
-      "advanced",
-      autoSwitch,
-    ),
+    curl: curl(base, key, model, "plain"),
+    python: pythonSnippet(base, key, model, "plain"),
+    javascript: javascriptSnippet(base, key, model, "plain"),
+    curlTools: curl(base, key, model, "tools"),
+    pythonTools: pythonSnippet(base, key, model, "tools"),
+    javascriptTools: javascriptSnippet(base, key, model, "tools"),
+    curlAdvanced: curl(base, key, model, "advanced"),
+    pythonAdvanced: pythonSnippet(base, key, model, "advanced"),
+    javascriptAdvanced: javascriptSnippet(base, key, model, "advanced"),
   };
 }
 
@@ -411,18 +350,46 @@ function writeUseTunnelPref(value: boolean): void {
   }
 }
 
-function useLoadedModelName(): string {
+// The model the examples name. With nothing loaded this used to print
+// MODEL_FALLBACK, a repo id the user likely never downloaded, so the copied
+// snippet 404d. Prefer a real id from the catalog /v1 resolves against; the
+// constant is only the floor for a server with no models, so it is never blank.
+function useExampleModelName(): string {
   const checkpoint = useChatRuntimeStore((s) => s.params.checkpoint);
   const ggufVariant = useChatRuntimeStore((s) => s.activeGgufVariant);
+  const [catalog, setCatalog] = useState<OpenAIModel[]>([]);
+  const needsCatalog = !checkpoint || checkpoint.startsWith("external::");
+
+  // Only when the checkpoint can't answer it: /v1/models scans the model dirs and
+  // HF caches. Re-runs when a model is loaded or unloaded.
+  useEffect(() => {
+    if (!needsCatalog) return;
+    let cancelled = false;
+    void listOpenAIModels()
+      .then((models) => {
+        if (!cancelled) setCatalog(models);
+      })
+      .catch(() => {
+        // Best-effort: fall through to the placeholder.
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [needsCatalog]);
+
   return useMemo(() => {
-    if (!checkpoint || checkpoint.startsWith("external::")) {
-      return MODEL_FALLBACK;
-    }
-    if (ggufVariant && !checkpoint.includes(":")) {
-      return `${checkpoint}:${ggufVariant}`;
+    if (checkpoint && !checkpoint.startsWith("external::")) {
+      if (ggufVariant && !checkpoint.includes(":")) {
+        return `${checkpoint}:${ggufVariant}`;
+      }
+      return checkpoint;
     }
-    return checkpoint;
-  }, [checkpoint, ggufVariant]);
+    // No local checkpoint (or an external provider, which /v1 cannot serve):
+    // name something this server actually holds.
+    return (
+      catalog.find((m) => m.loaded)?.id ?? catalog[0]?.id ?? MODEL_FALLBACK
+    );
+  }, [catalog, checkpoint, ggufVariant]);
 }
 
 // Backend PATH detection is only safe in the desktop app, where the UI owns
@@ -492,11 +459,6 @@ export function UsageExamples({ apiKey }: { apiKey?: string | null }) {
   const base =
     useTunnel && cloudflareUrl ? cloudflareUrl : (serverUrl ?? origin);
   const localAgentDetection = canUseLocalAgentDetection(base);
-  // null while loading; the same setting the General tab exposes (shared cache).
-  const [autoSwitch, setAutoSwitch] = useState<OpenAIAutoSwitchSettings | null>(
-    null,
-  );
-  const [savingAutoSwitch, setSavingAutoSwitch] = useState(false);
 
   useEffect(() => {
     void fetchDeviceType({ force: true });
@@ -574,27 +536,12 @@ export function UsageExamples({ apiKey }: { apiKey?: string | null }) {
     }
   }, [agent, detectedAgents, activeGgufVariant, activeNativePathToken, ggufContextLength]);
 
-  useEffect(() => {
-    let cancelled = false;
-    void loadOpenAIAutoSwitchSettings()
-      .then((s) => {
-        if (!cancelled) setAutoSwitch(s);
-      })
-      .catch(() => {
-        // Best-effort: leave the toggle off if the setting can't be read.
-      });
-    return () => {
-      cancelled = true;
-    };
-  }, []);
-
-  const model = useLoadedModelName();
+  const model = useExampleModelName();
   const key = apiKey || KEY_PLACEHOLDER;
 
-  const autoSwitchOn = autoSwitch?.enabled ?? false;
   const snippets = useMemo(
-    () => buildSnippets(base, key, model, os, autoSwitchOn),
-    [base, key, model, os, autoSwitchOn],
+    () => buildSnippets(base, key, model, os),
+    [base, key, model, os],
   );
   // Agent command must target the server the panel shows, not the :8888 default.
   const agentCommand = useMemo(
@@ -623,20 +570,6 @@ export function UsageExamples({ apiKey }: { apiKey?: string | null }) {
     writeUseTunnelPref(next);
   };
 
-  // Same setting as the General tab; persist optimistically and revert on failure
-  // so the examples reflect the live model-switch behavior.
-  const handleToggleAutoSwitch = (next: boolean) => {
-    const idle = autoSwitch?.autoUnloadIdleSeconds ?? 0;
-    setAutoSwitch((prev) => (prev ? { ...prev, enabled: next } : prev));
-    setSavingAutoSwitch(true);
-    void updateOpenAIAutoSwitchSettings(next, idle)
-      .then(setAutoSwitch)
-      .catch(() => {
-        setAutoSwitch((prev) => (prev ? { ...prev, enabled: !next } : prev));
-      })
-      .finally(() => setSavingAutoSwitch(false));
-  };
-
   const handleCopyUrl = async () => {
     if (cloudflareUrl && (await copyToClipboard(cloudflareUrl))) {
       setCopiedUrl(true);
@@ -657,41 +590,9 @@ export function UsageExamples({ apiKey }: { apiKey?: string | null }) {
         {t("settings.apiKeys.usageExamples")}
       </h2>
       <div className="min-w-0 max-w-full overflow-hidden rounded-lg border border-border bg-muted/20">
-        {/* Same setting as the General tab; surfaced here so the request `model`
-            actually switches the served model, which the examples below show. */}
-        <div className="flex min-w-0 items-center justify-between gap-2 border-b border-border px-2 py-1.5">
-          <div className="flex shrink-0 items-center gap-1.5">
-            <Switch
-              size="sm"
-              checked={autoSwitchOn}
-              disabled={autoSwitch === null || savingAutoSwitch}
-              onCheckedChange={handleToggleAutoSwitch}
-              aria-label={t("settings.general.modelAutoSwitch.enable")}
-            />
-            <span className="text-ui-11 font-medium text-foreground">
-              {t("settings.general.modelAutoSwitch.enable")}
-            </span>
-            <Tooltip>
-              <TooltipTrigger asChild={true}>
-                <button
-                  type="button"
-                  className="flex items-center rounded text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
-                  aria-label={t(
-                    "settings.general.modelAutoSwitch.enableDescription",
-                  )}
-                >
-                  <HugeiconsIcon
-                    icon={InformationCircleIcon}
-                    className="size-3.5"
-                  />
-                </button>
-              </TooltipTrigger>
-              <TooltipContent className="max-w-[260px] text-ui-11 leading-snug">
-                {t("settings.general.modelAutoSwitch.enableDescription")}
-              </TooltipContent>
-            </Tooltip>
-          </div>
-        </div>
+        {/* No model-auto-switch row: ModelAutoSwitchSection renders the same
+            setting just below on this tab, and the two do not share state (the
+            settings module caches on first read), so a duplicate drifts. */}
         {cloudflareUrl ? (
           <div className="flex min-w-0 items-center justify-between gap-2 border-b border-border px-2 py-1.5">
             <div className="flex shrink-0 items-center gap-1.5">
diff --git a/tests/studio/test_usage_examples_model_source_contract.py b/tests/studio/test_usage_examples_model_source_contract.py
new file mode 100644
index 00000000000..549957ea60c
--- /dev/null
+++ b/tests/studio/test_usage_examples_model_source_contract.py
@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Static contract for which model the API usage examples name, and for the
+model-auto-switch control living in exactly one place on the API keys tab."""
+
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[2]
+SETTINGS = REPO / "studio/frontend/src/features/settings"
+USAGE_EXAMPLES_TSX = SETTINGS / "components/usage-examples.tsx"
+OPENAI_MODELS_TS = SETTINGS / "api/openai-models.ts"
+API_KEYS_TAB_TSX = SETTINGS / "tabs/api-keys-tab.tsx"
+
+
+def test_examples_name_a_model_the_server_can_serve():
+    # The snippets used to fall back to a hardcoded repo id whenever nothing was
+    # loaded, so a copied curl named a model the user had never downloaded and
+    # 404d. Read the servable ids from /v1/models instead -- the same list the
+    # backend's model-not-downloaded error lists, so the two cannot disagree.
+    src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")
+    assert 'from "../api/openai-models"' in src
+    assert "function useExampleModelName(): string" in src
+    hook = src[src.find("function useExampleModelName") : src.find("// Backend PATH detection")]
+    assert "listOpenAIModels()" in hook
+    # Precedence: live checkpoint, then a loaded catalog entry, then any entry,
+    # and only then the placeholder.
+    assert "catalog.find((m) => m.loaded)?.id ?? catalog[0]?.id ?? MODEL_FALLBACK" in hook
+
+    api = OPENAI_MODELS_TS.read_text(encoding = "utf-8")
+    assert 'authFetch("/v1/models")' in api
+
+
+def test_usage_examples_has_no_duplicate_auto_switch_control():
+    # ModelAutoSwitchSection renders the same setting immediately below this
+    # panel on the same tab, and the two do not share state, so a second switch
+    # here drifts out of sync with the one the user can also see.
+    src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")
+    assert "openai-auto-switch" not in src
+    assert "SWITCH_NOTE" not in src
+    assert "Switch model by request" not in src
+    assert "pythonSwitchDemo" not in src
+    assert "javascriptSwitchDemo" not in src
+    assert "modelAutoSwitch" not in src
+
+    tab = API_KEYS_TAB_TSX.read_text(encoding = "utf-8")
+    assert "<ModelAutoSwitchSection />" in tab

From fed31afa45d1be720c9f4c603d49a9b6bcdb5a44 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Sun, 26 Jul 2026 04:46:49 +0000
Subject: [PATCH 02/56] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 studio/backend/routes/inference.py            |  9 +++----
 .../backend/tests/test_openai_auto_switch.py  | 25 +++++++++++--------
 2 files changed, 18 insertions(+), 16 deletions(-)

diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 46df46a54a7..289dd268682 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3577,7 +3577,8 @@ async def _available_model_ids() -> list[str]:
     """Sorted ids a /v1 request may name, from the catalog ``GET /v1/models``
     serves, so an error and the listing can't disagree."""
     return sorted(
-        mid for mid in (m.get("id") for m in await _openai_catalog_objects())
+        mid
+        for mid in (m.get("id") for m in await _openai_catalog_objects())
         if isinstance(mid, str) and mid
     )
 
@@ -3624,11 +3625,7 @@ async def _unavailable_model_message(requested_model: str) -> str:
 
 
 async def _no_model_loaded_error(
-    base: str,
-    requested_model: Optional[str],
-    fastapi_request: Optional[Request],
-    *,
-    status: int,
+    base: str, requested_model: Optional[str], fastapi_request: Optional[Request], *, status: int
 ):
     """``(status, detail)`` for the /v1 sites that fail because nothing is loaded.
 
diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index a614a0bc030..a3c96ec23c5 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -409,10 +409,7 @@ def test_describe_local_miss_separates_missing_repo_from_missing_quant(monkeypat
         resolver.MISS_MODEL_NOT_FOUND,
         (),
     )
-    assert resolver.describe_local_miss("unsloth/B-GGUF") == (
-        resolver.MISS_MODEL_NOT_FOUND,
-        (),
-    )
+    assert resolver.describe_local_miss("unsloth/B-GGUF") == (resolver.MISS_MODEL_NOT_FOUND, ())
 
 
 def test_describe_local_miss_is_failsafe(monkeypatch):
@@ -3284,7 +3281,13 @@ def test_no_model_loaded_detail_appends_hint_only_when_off(monkeypatch):
     assert inference_route._no_model_loaded_detail(base) == base
 
 
-def _run_responses_stream_no_model(monkeypatch, *, enabled, active_model_name, resolves_to = None):
+def _run_responses_stream_no_model(
+    monkeypatch,
+    *,
+    enabled,
+    active_model_name,
+    resolves_to = None,
+):
     # Drive _responses_stream's GGUF-not-loaded guard: llama backend unloaded,
     # inference backend maybe holding a non-GGUF model. Returns (status, detail).
     from fastapi import HTTPException
@@ -3333,7 +3336,12 @@ def test_responses_stream_hint_matches_toggle_regardless_of_active_model(monkeyp
     assert "Model auto-switch" in non_gguf_loaded
 
 
-def _wire_unloaded_chat(monkeypatch, *, enabled, catalog = ("org/A-GGUF", "org/B-GGUF")):
+def _wire_unloaded_chat(
+    monkeypatch,
+    *,
+    enabled,
+    catalog = ("org/A-GGUF", "org/B-GGUF"),
+):
     # Nothing loaded, so a chat request reaches the "no model loaded" error. Pin
     # the catalog so listed ids don't depend on what is cached on the test machine.
     async def _catalog():
@@ -3357,7 +3365,6 @@ async def _catalog():
 
 def _chat_error(payload):
     from fastapi import HTTPException
-
     with pytest.raises(HTTPException) as exc:
         asyncio.run(inference_route.openai_chat_completions(payload, object(), "tester"))
     return exc.value.status_code, exc.value.detail
@@ -3454,9 +3461,7 @@ async def _noop_switch(*a, **k):
 
     request = type("_R", (), {"url": type("_U", (), {"path": "/v1/messages"})()})()
     with pytest.raises(HTTPException) as exc:
-        asyncio.run(
-            inference_route.anthropic_messages(_anthropic_payload(64), request, "tester")
-        )
+        asyncio.run(inference_route.anthropic_messages(_anthropic_payload(64), request, "tester"))
     assert exc.value.status_code == 404
     body = exc.value.detail
     assert body["type"] == "error"

From 88f1e5eb4a8a3db9ef95b1466d191b6b223e51b9 Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Sun, 26 Jul 2026 07:31:35 +0000
Subject: [PATCH 03/56] Studio: page the API monitor, show model load/unload,
 pin the example quant

The monitor rendered all 50 retained entries in one scroller: page it 5 at a
time, freezing history while paged back so live traffic cannot reorder it.
Add model load/unload rows so the feed shows what the server is doing, and
stop the header rendering the loaded model as a raw host path. Advertise each
model's GGUF quant on /v1/models so the example pins repo:QUANT, and move the
auto-switch section above the monitor with shorter copy.
---
 studio/backend/core/inference/api_monitor.py  |  95 ++++++++++-
 .../backend/core/inference/llama_keepwarm.py  |  19 +++
 .../core/inference/local_model_resolver.py    |  22 ++-
 studio/backend/routes/inference.py            |  92 ++++++++++-
 studio/backend/tests/test_api_monitor.py      | 101 ++++++++++++
 studio/backend/tests/test_openai_catalog.py   |  54 +++++-
 .../frontend/src/features/chat/types/api.ts   |   5 +
 .../features/settings/api/openai-models.ts    |  13 +-
 .../components/api-monitor-console.tsx        | 154 ++++++++++++++++--
 .../settings/components/usage-examples.tsx    |  37 ++++-
 .../features/settings/tabs/api-keys-tab.tsx   |   4 +-
 studio/frontend/src/i18n/locales/en.ts        |  12 +-
 ...st_usage_examples_model_source_contract.py |  35 +++-
 13 files changed, 591 insertions(+), 52 deletions(-)

diff --git a/studio/backend/core/inference/api_monitor.py b/studio/backend/core/inference/api_monitor.py
index f76a38576fc..2390d235a2e 100644
--- a/studio/backend/core/inference/api_monitor.py
+++ b/studio/backend/core/inference/api_monitor.py
@@ -52,6 +52,13 @@ class ApiMonitorEntry:
     total_tokens: Optional[int] = None
     total_tokens_authoritative: bool = False
     error: Optional[str] = None
+    # "request" (an HTTP call) or "lifecycle" (a model load/unload). Lifecycle
+    # rows carry event/reason instead of a prompt and are server-wide, so they
+    # are shared across subjects rather than owned by the caller that caused them.
+    kind: str = "request"
+    event: Optional[str] = None
+    reason: Optional[str] = None
+    shared: bool = False
 
     def snapshot(self, *, include_details: bool = True) -> dict[str, Any]:
         duration_ms = None
@@ -85,6 +92,9 @@ def snapshot(self, *, include_details: bool = True) -> dict[str, Any]:
             "completion_tokens": self.completion_tokens,
             "total_tokens": self.total_tokens,
             "error": self.error,
+            "kind": self.kind,
+            "event": self.event,
+            "reason": self.reason,
         }
         if include_details:
             payload["prompt"] = self.prompt
@@ -127,6 +137,65 @@ def start(
             self._trim_terminal_locked()
         return entry.id
 
+    def record_lifecycle(
+        self,
+        *,
+        event: str,
+        model: str,
+        reason: Optional[str] = None,
+        running: bool = False,
+    ) -> str:
+        """Record a model load/unload alongside the request traffic that caused it.
+
+        ``running=True`` opens the row (a load in progress) and the caller closes
+        it with the usual :meth:`finish` / :meth:`fail`; an unload is terminal on
+        arrival. Rows are shared, so every subject sees them, and share the same
+        retention budget as requests.
+        """
+        now = time.time()
+        entry = ApiMonitorEntry(
+            id = f"apievt_{uuid.uuid4().hex[:12]}",
+            endpoint = f"model.{event}",
+            method = "",
+            model = model or "default",
+            prompt = "",
+            status = "running" if running else "completed",
+            started_at = now,
+            updated_at = now,
+            started_monotonic = time.monotonic(),
+            finished_at = None if running else now,
+            finished_monotonic = None if running else time.monotonic(),
+            kind = "lifecycle",
+            event = event,
+            reason = reason,
+            shared = True,
+        )
+        with self._lock:
+            self._entries.appendleft(entry)
+            self._trim_terminal_locked()
+        return entry.id
+
+    def relabel(self, entry_id: Optional[str], model: str) -> None:
+        """Rename an open lifecycle row once the load resolves its real id (the
+        caller only has the load path up front, which may be an HF snapshot dir)."""
+        if not entry_id or not model:
+            return
+        with self._lock:
+            entry = self._find_locked(entry_id)
+            if entry is not None:
+                entry.model = model
+                entry.updated_at = time.time()
+
+    def discard(self, entry_id: Optional[str]) -> None:
+        """Drop a row that turned out not to be an event (a load that was already
+        satisfied, so nothing was actually loaded)."""
+        if not entry_id:
+            return
+        with self._lock:
+            entry = self._find_locked(entry_id)
+            if entry is not None:
+                self._entries.remove(entry)
+
     def append_reply(self, entry_id: Optional[str], text: str) -> None:
         if not entry_id or not text:
             return
@@ -212,6 +281,18 @@ def finish(
             self._entries.appendleft(entry)
             self._trim_terminal_locked()
 
+    def fail_open(self, entry_id: Optional[str], error: str) -> None:
+        """Fail only a still-open row. Unlike :meth:`fail` this never touches an
+        entry that already finished, so a catch-all in a ``finally`` cannot stamp
+        an error onto a request that in fact succeeded."""
+        if not entry_id:
+            return
+        with self._lock:
+            entry = self._find_locked(entry_id)
+            if entry is None or entry.finished_at is not None:
+                return
+        self.fail(entry_id, error)
+
     def fail(self, entry_id: Optional[str], error: str) -> None:
         if not entry_id:
             return
@@ -244,7 +325,7 @@ def snapshot(
             return [
                 entry.snapshot(include_details = include_details)
                 for entry in self._entries
-                if subject is None or entry.subject == subject
+                if self._visible(entry, subject)
             ]
 
     def get(
@@ -257,22 +338,30 @@ def get(
             entry = self._find_locked(entry_id)
             if entry is None:
                 return None
-            if subject is not None and entry.subject != subject:
+            if not self._visible(entry, subject):
                 return None
             return entry.snapshot(include_details = True)
 
     def active_count(self, *, subject: Optional[str] = None) -> int:
+        # Lifecycle rows are excluded: a load in progress is "running" so the row
+        # can show as live, but it is not an in-flight API request.
         with self._lock:
             return sum(
                 1
                 for entry in self._entries
-                if entry.status == "running" and (subject is None or entry.subject == subject)
+                if entry.status == "running"
+                and entry.kind != "lifecycle"
+                and (subject is None or entry.subject == subject)
             )
 
     def clear(self) -> None:
         with self._lock:
             self._entries.clear()
 
+    @staticmethod
+    def _visible(entry: ApiMonitorEntry, subject: Optional[str]) -> bool:
+        return subject is None or entry.subject == subject or entry.shared
+
     def _find_locked(self, entry_id: str) -> Optional[ApiMonitorEntry]:
         for entry in self._entries:
             if entry.id == entry_id:
diff --git a/studio/backend/core/inference/llama_keepwarm.py b/studio/backend/core/inference/llama_keepwarm.py
index 3380ebf5f59..44ce54d8ba5 100644
--- a/studio/backend/core/inference/llama_keepwarm.py
+++ b/studio/backend/core/inference/llama_keepwarm.py
@@ -345,6 +345,22 @@ def _loaded_identity(backend):
     return (backend.model_identifier, getattr(backend, "hf_variant", None), advertised)
 
 
+def _note_idle_unload_event(freed) -> None:
+    """Record an idle auto-unload in the API monitor, using the advertised repo id
+    from the stash so the row never shows the on-disk load path. Best-effort."""
+    try:
+        from core.inference.api_monitor import api_monitor
+        from core.inference.model_ids import public_model_id
+
+        identifier, variant, advertised = (list(freed) + [None, None, None])[:3]
+        label = public_model_id(advertised or identifier) or "model"
+        if variant and ":" not in label:
+            label = f"{label}:{variant}"
+        api_monitor.record_lifecycle(event = "unload", model = label, reason = "idle")
+    except Exception as exc:
+        logger.debug("idle unload monitor event failed: %s", exc)
+
+
 async def idle_unload_loop(poll_seconds: float = 15.0) -> None:
     """Unload the loaded GGUF once idle past the configured TTL. Inert when off."""
     from utils.openai_auto_switch_settings import (
@@ -407,6 +423,9 @@ async def idle_unload_loop(poll_seconds: float = 15.0) -> None:
                     elif manifest:
                         _delete_resume_files(manifest)
                     logger.info("Idle auto-unload: freed GGUF after %ss idle", ttl)
+                    # This path deliberately skips note_model_unloaded (an idle
+                    # unload stashes for reload), so record the monitor row here.
+                    _note_idle_unload_event(freed)
                     seen_model = None
         except Exception as exc:
             logger.debug("idle_unload_loop iteration failed: %s", exc)
diff --git a/studio/backend/core/inference/local_model_resolver.py b/studio/backend/core/inference/local_model_resolver.py
index 3c5e55ed873..0533db944f6 100644
--- a/studio/backend/core/inference/local_model_resolver.py
+++ b/studio/backend/core/inference/local_model_resolver.py
@@ -108,12 +108,12 @@ def _local_gguf_entry(loader_id: str, info) -> Optional[_LocalGgufEntry]:
         return None
 
 
-def info_has_local_gguf(info) -> bool:
-    """True when *info* (a LocalModelInfo) points to on-disk GGUF weights the
-    auto-switch path can load. Read from the files, not ``info.model_format``: the
-    HF-cache scanner leaves model_format unset for GGUF snapshots, so a
-    model_format filter would drop every cached GGUF. Lets /v1/models advertise
-    exactly what /v1 can serve."""
+def local_gguf_quants(info) -> Optional[tuple[str, ...]]:
+    """On-disk quant labels for *info*, or None when it is not a servable local
+    GGUF. Read from the files, not ``info.model_format``: the HF-cache scanner
+    leaves model_format unset for GGUF snapshots, so a model_format filter would
+    drop every cached GGUF. Lets /v1/models advertise exactly what /v1 can serve,
+    and which quant to name, from a single scan."""
     from pathlib import Path
 
     path = getattr(info, "path", None)
@@ -123,8 +123,14 @@ def info_has_local_gguf(info) -> bool:
     if isinstance(path, str) and any(
         seg in (".studio_links", "ollama_links") for seg in Path(path).parts
     ):
-        return False
-    return _local_gguf_entry(getattr(info, "id", "") or "", info) is not None
+        return None
+    entry = _local_gguf_entry(getattr(info, "id", "") or "", info)
+    return entry.variants if entry is not None else None
+
+
+def info_has_local_gguf(info) -> bool:
+    """True when *info* points to on-disk GGUF weights the auto-switch path can load."""
+    return local_gguf_quants(info) is not None
 
 
 def _build_index() -> dict[str, _LocalGgufEntry]:
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 289dd268682..dc63eff45ea 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3070,12 +3070,50 @@ def _monitor_context_length() -> Optional[int]:
     return None
 
 
+def _hf_cache_repo_id(path: Optional[str]) -> Optional[str]:
+    """``.../models--org--name/snapshots/<sha>`` -> ``org/name``, else None.
+
+    An auto-switch load is handed the concrete snapshot dir, whose basename is the
+    commit sha, so public_model_id alone would label the row with a hash.
+    """
+    if not path:
+        return None
+    for part in str(path).replace("\\", "/").split("/"):
+        if part.startswith("models--"):
+            return part[len("models--") :].replace("--", "/")
+    return None
+
+
+def _lifecycle_model_label(model: Optional[str], variant: Optional[str] = None) -> str:
+    """A path-free ``repo`` / ``repo:QUANT`` label for a monitor lifecycle row."""
+    clean = _hf_cache_repo_id(model) or public_model_id(model) or model or "model"
+    return f"{clean}:{variant}" if variant and ":" not in clean else clean
+
+
+def _close_load_event(
+    entry_id: Optional[str], model: Optional[str], variant: Optional[str]
+) -> None:
+    """Close a monitor load row, relabelled with the id the load actually resolved
+    (the row opened on the request's model_path, which may be an HF snapshot dir)."""
+    api_monitor.relabel(entry_id, _lifecycle_model_label(model, variant))
+    api_monitor.finish(entry_id)
+
+
 def _monitor_active_model() -> Optional[str]:
+    """The loaded model as a client-facing id, quant included when known.
+
+    Cleaned like /v1/models: this is rendered in the settings UI and served over
+    the public --secure tunnel, so it must never be the on-disk load path.
+    """
     llama_backend = get_llama_cpp_backend()
     if getattr(llama_backend, "is_loaded", False):
-        return getattr(llama_backend, "model_identifier", None)
+        model_id = _llama_public_model_id(llama_backend)
+        variant = getattr(llama_backend, "hf_variant", None)
+        if model_id and variant and ":" not in model_id:
+            return f"{model_id}:{variant}"
+        return model_id
     backend = get_inference_backend()
-    return backend.active_model_name
+    return public_model_id(backend.active_model_name) or backend.active_model_name
 
 
 def _validate_native_gguf_companion(
@@ -4402,6 +4440,15 @@ async def _load_model_impl(
     # sampled step logs even if it reports 100% immediately (cached/small load).
     _reset_load_progress_step()
 
+    # Open a live "loading" row in the API monitor. Discarded below if the model
+    # turned out to be already loaded, relabelled once the real id is known, and
+    # closed on every exit by the handlers at the end of this function.
+    _load_event = api_monitor.record_lifecycle(
+        event = "load",
+        model = _lifecycle_model_label(request.model_path, request.gguf_variant),
+        running = True,
+    )
+
     native_grant_backed = False
     model_log_label = request.model_path
     gguf_load_stack = ExitStack()
@@ -4495,6 +4542,8 @@ async def _load_model_impl(
                 and getattr(llama_backend, "_audio_probed", True)
             ):
                 llama_backend._record_matching_gpu_request(request.gpu_ids)
+                # Nothing was loaded, so the monitor must not show a load row.
+                api_monitor.discard(_load_event)
                 logger.info(
                     "Model already loaded (GGUF): "
                     f"{model_log_label} variant={request.gguf_variant or llama_backend.hf_variant}, skipping reload"
@@ -4548,6 +4597,7 @@ async def _load_model_impl(
                 backend.active_model_name
                 and backend.active_model_name.lower() == model_identifier.lower()
             ):
+                api_monitor.discard(_load_event)  # nothing loaded, no monitor row
                 logger.info(f"Model already loaded (Unsloth): {model_log_label}, skipping reload")
                 inference_config = load_inference_config(backend.active_model_name)
                 _model_info = backend.models.get(backend.active_model_name, {})
@@ -4860,6 +4910,11 @@ async def _attempt_gguf_load(
             logger.info(
                 f"Loaded GGUF model via llama-server: {model_log_label if native_grant_backed else config.identifier}"
             )
+            _close_load_event(
+                _load_event,
+                model_log_label if native_grant_backed else config.identifier,
+                request.gguf_variant or getattr(llama_backend, "hf_variant", None),
+            )
             # Clear any idle-unload reload stash now, not only on the next poll.
             from core.inference.llama_keepwarm import note_model_loaded
 
@@ -4978,6 +5033,9 @@ async def _attempt_gguf_load(
         logger.info(
             f"Loaded model: {model_log_label if native_grant_backed else config.identifier}"
         )
+        _close_load_event(
+            _load_event, model_log_label if native_grant_backed else config.identifier, None
+        )
         # Clear any idle-unload reload stash: a manual load supersedes an idle-freed
         # GGUF, so the next /v1 request must not resurrect it. Mirror the GGUF branch
         # above; without this a non-GGUF load leaves a stale stash until the idle
@@ -5100,6 +5158,9 @@ async def _attempt_gguf_load(
         raise HTTPException(status_code = 500, detail = f"Failed to load model: {msg}")
     finally:
         gguf_load_stack.close()
+        # Catch-all: any exit that did not already close or discard the row (an
+        # error, or a cancelled load) leaves it stuck "loading" otherwise.
+        api_monitor.fail_open(_load_event, "Load did not complete")
 
 
 def _requires_trust_remote_code_for_model(
@@ -5720,6 +5781,11 @@ async def unload_model(request: UnloadRequest, current_subject: str = Depends(ge
                 # request is mid-stream (only the automatic idle loop defers to it).
                 llama_backend.unload_model()
                 note_model_unloaded()
+                api_monitor.record_lifecycle(
+                    event = "unload",
+                    model = _lifecycle_model_label(request.model_path),
+                    reason = "manual",
+                )
                 logger.info(f"Unloaded GGUF model: {request.model_path}")
                 return UnloadResponse(status = "unloaded", model = request.model_path)
 
@@ -5729,6 +5795,11 @@ async def unload_model(request: UnloadRequest, current_subject: str = Depends(ge
             backend = get_inference_backend()
             await asyncio.to_thread(backend.unload_model, request.model_path)
             note_model_unloaded()
+            api_monitor.record_lifecycle(
+                event = "unload",
+                model = _lifecycle_model_label(request.model_path),
+                reason = "manual",
+            )
             logger.info(f"Unloaded model: {request.model_path}")
             return UnloadResponse(status = "unloaded", model = request.model_path)
 
@@ -10575,6 +10646,9 @@ def _openai_model_objects() -> list[dict]:
             "created": _created,
             "owned_by": _OWNED_BY,
         }
+        _quant = getattr(llama_backend, "hf_variant", None)
+        if _quant:
+            entry["quant"] = _quant
         _ctx = _positive_int_or_none(getattr(llama_backend, "context_length", None))
         if _ctx is not None:
             entry["context_length"] = _ctx
@@ -10681,11 +10755,15 @@ async def _openai_catalog_objects() -> list[dict]:
     # read from the on-disk files, not model_format: the HF-cache scanner leaves
     # model_format unset for GGUF snapshots, so a model_format filter would drop
     # every cached GGUF. The file checks run off the loop.
-    from core.inference.local_model_resolver import info_has_local_gguf
+    from core.inference.local_model_resolver import local_gguf_quants
 
     catalog = await _cached_local_catalog()
-    servable = await asyncio.to_thread(lambda: [i for i in catalog if info_has_local_gguf(i)])
-    for info in servable:
+    # One scan yields both "is this servable" and its on-disk quants, so an entry
+    # can advertise the quant to name without a second pass over the model dirs.
+    servable = await asyncio.to_thread(
+        lambda: [(i, q) for i in catalog if (q := local_gguf_quants(i)) is not None]
+    )
+    for info, quants in servable:
         cid = getattr(info, "model_id", None) or public_model_id(getattr(info, "id", None))
         if not cid or cid in by_id:
             continue
@@ -10696,6 +10774,10 @@ async def _openai_catalog_objects() -> list[dict]:
             "owned_by": _OWNED_BY,
             "loaded": False,
         }
+        # Bare label (never a filename or path): the id stays bare for OpenAI
+        # compat, and a client appends ":<quant>" to pin this exact quant.
+        if quants:
+            obj["quant"] = quants[0]
         display = getattr(info, "display_name", None)
         if display:
             obj["display_name"] = display
diff --git a/studio/backend/tests/test_api_monitor.py b/studio/backend/tests/test_api_monitor.py
index 56bc4043503..44b1f5fecde 100644
--- a/studio/backend/tests/test_api_monitor.py
+++ b/studio/backend/tests/test_api_monitor.py
@@ -258,3 +258,104 @@ def test_api_monitor_append_reply_exact_cap_then_more_marks_truncated():
     monitor.append_reply(entry_id, "y")
     reply = monitor.snapshot()[0]["reply"]
     assert len(reply) == m._MAX_REPLY_CHARS and reply.endswith("...")
+
+
+# ── model lifecycle rows (load / unload) ────────────────────────────
+
+
+def test_lifecycle_load_row_opens_running_then_closes():
+    monitor = ApiMonitor(max_entries = 5)
+    event_id = monitor.record_lifecycle(event = "load", model = "org/A-GGUF", running = True)
+    row = monitor.snapshot()[0]
+    assert row["kind"] == "lifecycle" and row["event"] == "load"
+    assert row["status"] == "running" and row["duration_ms"] is None
+    # A load in progress is not an in-flight API request.
+    assert monitor.active_count() == 0
+
+    monitor.relabel(event_id, "org/A-GGUF:Q4_K_M")
+    monitor.finish(event_id)
+    row = monitor.snapshot()[0]
+    assert row["status"] == "completed"
+    assert row["model"] == "org/A-GGUF:Q4_K_M"
+    assert row["duration_ms"] is not None
+
+
+def test_lifecycle_unload_row_is_terminal_on_arrival():
+    monitor = ApiMonitor(max_entries = 5)
+    monitor.record_lifecycle(event = "unload", model = "org/A-GGUF", reason = "idle")
+    row = monitor.snapshot()[0]
+    assert row["status"] == "completed"
+    assert (row["event"], row["reason"]) == ("unload", "idle")
+    assert monitor.active_count() == 0
+
+
+def test_lifecycle_rows_are_visible_to_every_subject():
+    # A load is server-wide, not owned by whoever happened to trigger it, so it
+    # must not vanish for other API keys the way a request does.
+    monitor = ApiMonitor(max_entries = 5)
+    monitor.start(
+        endpoint = "/v1/chat/completions",
+        method = "POST",
+        model = "m",
+        prompt = "hi",
+        subject = "alice",
+    )
+    event_id = monitor.record_lifecycle(event = "unload", model = "org/A-GGUF")
+
+    bob = monitor.snapshot(subject = "bob")
+    assert [r["kind"] for r in bob] == ["lifecycle"]
+    assert monitor.get(event_id, subject = "bob") is not None
+    assert len(monitor.snapshot(subject = "alice")) == 2
+
+
+def test_request_rows_stay_private_to_their_subject():
+    monitor = ApiMonitor(max_entries = 5)
+    rid = monitor.start(
+        endpoint = "/v1/chat/completions",
+        method = "POST",
+        model = "m",
+        prompt = "hi",
+        subject = "alice",
+    )
+    assert monitor.snapshot(subject = "bob") == []
+    assert monitor.get(rid, subject = "bob") is None
+
+
+def test_discard_drops_a_row_that_never_happened():
+    # A load that found the model already resident must leave no trace.
+    monitor = ApiMonitor(max_entries = 5)
+    event_id = monitor.record_lifecycle(event = "load", model = "org/A-GGUF", running = True)
+    monitor.discard(event_id)
+    assert monitor.snapshot() == []
+    monitor.discard(event_id)  # idempotent
+
+
+def test_fail_open_never_touches_a_finished_row():
+    # The load path calls this from a finally, so it must not stamp an error onto
+    # a load that in fact succeeded.
+    monitor = ApiMonitor(max_entries = 5)
+    event_id = monitor.record_lifecycle(event = "load", model = "org/A-GGUF", running = True)
+    monitor.finish(event_id)
+    monitor.fail_open(event_id, "Load did not complete")
+    row = monitor.snapshot()[0]
+    assert row["status"] == "completed" and row["error"] is None
+
+    still_open = monitor.record_lifecycle(event = "load", model = "org/B-GGUF", running = True)
+    monitor.fail_open(still_open, "Load did not complete")
+    assert monitor.snapshot()[0]["status"] == "error"
+
+
+def test_lifecycle_rows_share_the_retention_budget():
+    monitor = ApiMonitor(max_entries = 2)
+    for i in range(4):
+        monitor.record_lifecycle(event = "unload", model = f"org/M{i}")
+    models = [r["model"] for r in monitor.snapshot()]
+    assert models == ["org/M3", "org/M2"]
+
+
+def test_request_rows_report_kind_request():
+    monitor = ApiMonitor(max_entries = 2)
+    monitor.start(
+        endpoint = "/v1/chat/completions", method = "POST", model = "m", prompt = "hi"
+    )
+    assert monitor.snapshot()[0]["kind"] == "request"
diff --git a/studio/backend/tests/test_openai_catalog.py b/studio/backend/tests/test_openai_catalog.py
index 552f122ebb6..3c5c953b962 100644
--- a/studio/backend/tests/test_openai_catalog.py
+++ b/studio/backend/tests/test_openai_catalog.py
@@ -64,8 +64,11 @@ async def _fake_catalog():
         ]
 
     monkeypatch.setattr(inf, "_cached_local_catalog", _fake_catalog)
-    # GGUF-ness is read from the on-disk files; drive it off each info's flag here.
-    monkeypatch.setattr(resolver, "info_has_local_gguf", lambda info: info.is_gguf)
+    # GGUF-ness and the quant labels both come from the on-disk files in one scan;
+    # drive them off each info's flag here.
+    monkeypatch.setattr(
+        resolver, "local_gguf_quants", lambda info: ("Q8_0",) if info.is_gguf else None
+    )
 
     data = asyncio.run(inf._openai_catalog_objects())
     ids = {m["id"]: m for m in data}
@@ -73,8 +76,10 @@ async def _fake_catalog():
     # Loaded model is present, marked loaded, and keeps context fields.
     assert ids["Qwen3-Q4"]["loaded"] is True
     assert ids["Qwen3-Q4"]["context_length"] == 4096
-    # Available-but-not-loaded GGUF models are listed too.
+    # Available-but-not-loaded GGUF models are listed too, with the quant a client
+    # appends to the id to pin it.
     assert ids["Llama-8B-Q8"]["loaded"] is False
+    assert ids["Llama-8B-Q8"]["quant"] == "Q8_0"
     # The HF-cache GGUF is listed despite model_format being unset.
     assert ids["org/Foo"]["loaded"] is False
     # The non-GGUF model is filtered out (/v1 can never serve it).
@@ -205,3 +210,46 @@ async def _run():
     assert second is first or [i.id for i in second] == [i.id for i in first]
     assert calls["scan"] == 1  # cached: scanned once for two calls
     assert calls["threaded"] == 1  # offloaded to a worker thread
+
+
+def test_monitor_active_model_is_a_public_id_not_a_host_path(monkeypatch):
+    # The settings UI renders this and --secure serves it over a public tunnel, so
+    # it must never be the on-disk load path (it used to be model_identifier raw).
+    class _Llama:
+        is_loaded = True
+        model_identifier = "/home/me/.cache/huggingface/hub/models--org--A-GGUF/snapshots/abc"
+        hf_variant = "UD-Q4_K_XL"
+        _openai_advertised_id = "org/A-GGUF"
+
+    monkeypatch.setattr(inf, "get_llama_cpp_backend", lambda: _Llama())
+    assert inf._monitor_active_model() == "org/A-GGUF:UD-Q4_K_XL"
+
+
+def test_monitor_active_model_cleans_a_path_with_no_advertised_id(monkeypatch):
+    class _Llama:
+        is_loaded = True
+        model_identifier = "/data/models/Llama-8B-Q8.gguf"
+        hf_variant = None
+        _openai_advertised_id = None
+
+    monkeypatch.setattr(inf, "get_llama_cpp_backend", lambda: _Llama())
+    label = inf._monitor_active_model()
+    assert "/" not in label and ".gguf" not in label
+
+
+def test_lifecycle_label_recovers_the_repo_id_from_an_hf_cache_path():
+    # An auto-switch load is handed the snapshot dir, whose basename is a commit
+    # sha, so the row would otherwise be labelled with a hash.
+    snap = "/home/me/.cache/huggingface/hub/models--unsloth--gemma-4-E4B-it-GGUF/snapshots/bfc15c3"
+    assert (
+        inf._lifecycle_model_label(snap, "UD-Q4_K_XL")
+        == "unsloth/gemma-4-E4B-it-GGUF:UD-Q4_K_XL"
+    )
+
+
+def test_lifecycle_model_label_is_path_free():
+    label = inf._lifecycle_model_label("/data/models/Llama-8B-Q8.gguf", "Q8_0")
+    assert "/" not in label and ".gguf" not in label
+    assert inf._lifecycle_model_label("org/A-GGUF", "Q4_K_M") == "org/A-GGUF:Q4_K_M"
+    # An id that already carries a quant is not double-suffixed.
+    assert inf._lifecycle_model_label("org/A-GGUF:Q4_K_M", "Q8_0") == "org/A-GGUF:Q4_K_M"
diff --git a/studio/frontend/src/features/chat/types/api.ts b/studio/frontend/src/features/chat/types/api.ts
index 6c3e919efe7..7f50fcfdaf4 100644
--- a/studio/frontend/src/features/chat/types/api.ts
+++ b/studio/frontend/src/features/chat/types/api.ts
@@ -283,6 +283,11 @@ export interface ApiMonitorEntry {
   completion_tokens?: number | null;
   total_tokens?: number | null;
   error?: string | null;
+  // "request" is an HTTP call; "lifecycle" is a model load/unload, which carries
+  // event/reason instead of a prompt and has no detail to fetch.
+  kind?: "request" | "lifecycle";
+  event?: "load" | "unload" | null;
+  reason?: "manual" | "idle" | null;
 }
 
 export interface ApiMonitorResponse {
diff --git a/studio/frontend/src/features/settings/api/openai-models.ts b/studio/frontend/src/features/settings/api/openai-models.ts
index 31c651f5c2d..d4f7c18a63d 100644
--- a/studio/frontend/src/features/settings/api/openai-models.ts
+++ b/studio/frontend/src/features/settings/api/openai-models.ts
@@ -7,10 +7,13 @@ export type OpenAIModel = {
   id: string;
   // Resident in memory now; the rest are downloaded and servable.
   loaded?: boolean;
+  // On-disk GGUF quant. Ids stay bare for OpenAI compat, so append it as
+  // `id:quant` to pin this exact quant rather than letting the server pick.
+  quant?: string;
 };
 
 type ApiOpenAIModelList = {
-  data?: { id?: unknown; loaded?: unknown }[];
+  data?: { id?: unknown; loaded?: unknown; quant?: unknown }[];
 };
 
 /**
@@ -32,7 +35,13 @@ export async function listOpenAIModels(): Promise<OpenAIModel[]> {
   }
   return body.data.flatMap((entry) =>
     typeof entry?.id === "string" && entry.id
-      ? [{ id: entry.id, loaded: entry.loaded === true }]
+      ? [
+          {
+            id: entry.id,
+            loaded: entry.loaded === true,
+            quant: typeof entry.quant === "string" ? entry.quant : undefined,
+          },
+        ]
       : [],
   );
 }
diff --git a/studio/frontend/src/features/settings/components/api-monitor-console.tsx b/studio/frontend/src/features/settings/components/api-monitor-console.tsx
index 0f931ff4daa..41cd504f47f 100644
--- a/studio/frontend/src/features/settings/components/api-monitor-console.tsx
+++ b/studio/frontend/src/features/settings/components/api-monitor-console.tsx
@@ -22,6 +22,7 @@ import type { ApiMonitorEntry, ApiMonitorResponse } from "../../chat/types/api";
 
 const API_INFERENCE_PREFIX_RE = /^\/api\/inference/;
 const V1_PREFIX_RE = /^\/v1\//;
+const PAGE_SIZE = 5;
 
 function formatTime(value: number): string {
   return new Date(value * 1000).toLocaleTimeString([], {
@@ -87,6 +88,53 @@ function UsageBar({ value }: { value?: number | null }): ReactElement | null {
   );
 }
 
+function isLifecycle(entry: ApiMonitorEntry): boolean {
+  return entry.kind === "lifecycle";
+}
+
+function lifecycleLabel(entry: ApiMonitorEntry): string {
+  if (entry.event === "unload") {
+    return entry.reason === "idle" ? "Model unloaded (idle)" : "Model unloaded";
+  }
+  if (entry.status === "running") {
+    return "Loading model";
+  }
+  if (entry.status === "completed") {
+    return "Model loaded";
+  }
+  return "Model load failed";
+}
+
+// Load/unload rows: a label, the model and a time. No prompt, reply, tokens or
+// detail fetch, so unlike a request row there is nothing to expand.
+function LifecycleEntry({ entry }: { entry: ApiMonitorEntry }): ReactElement {
+  return (
+    <article className="min-w-0 rounded-lg border border-border/70 bg-muted/25">
+      <div className="flex w-full min-w-0 items-start justify-between gap-3 p-3">
+        <div className="min-w-0">
+          <div className="flex min-w-0 items-center gap-2">
+            <ActivityIcon
+              className={cn("size-3.5 shrink-0", statusTone(entry.status))}
+            />
+            <span className="truncate text-xs font-medium">
+              {lifecycleLabel(entry)}
+            </span>
+          </div>
+          <div className="mt-1 truncate text-ui-11 text-muted-foreground">
+            {entry.model}
+          </div>
+        </div>
+        <div className="shrink-0 text-right text-ui-11 text-muted-foreground">
+          <div>{formatTime(entry.started_at)}</div>
+          {entry.event === "load" ? (
+            <div>{formatDuration(entry.duration_ms)}</div>
+          ) : null}
+        </div>
+      </div>
+    </article>
+  );
+}
+
 function MonitorEntry({
   entry,
   detail,
@@ -253,6 +301,51 @@ export function ApiMonitorConsole(): ReactElement {
   const statusLabel = data?.status ?? "idle";
   const hasActive = (data?.active_requests ?? 0) > 0;
   const entries = useMemo(() => data?.entries ?? [], [data]);
+
+  // Page 1 tracks the live list. Paging back freezes the id order captured at
+  // that moment: the poll keeps refreshing row contents, but new traffic must not
+  // shove history down a page while it is being read (finishing a request also
+  // moves it to the head, so even an idle server reorders).
+  const [page, setPage] = useState(0);
+  const [frozenIds, setFrozenIds] = useState<string[] | null>(null);
+  const byId = useMemo(
+    () => new Map(entries.map((entry) => [entry.id, entry])),
+    [entries],
+  );
+  const ordered = useMemo(() => {
+    if (frozenIds === null) {
+      return entries;
+    }
+    return frozenIds.flatMap((id) => {
+      const entry = byId.get(id);
+      return entry ? [entry] : [];
+    });
+  }, [byId, entries, frozenIds]);
+  const pageCount = Math.max(1, Math.ceil(ordered.length / PAGE_SIZE));
+  const pageIndex = Math.min(page, pageCount - 1);
+  const visible = ordered.slice(
+    pageIndex * PAGE_SIZE,
+    pageIndex * PAGE_SIZE + PAGE_SIZE,
+  );
+  const newerCount =
+    frozenIds === null
+      ? 0
+      : entries.filter((entry) => !frozenIds.includes(entry.id)).length;
+
+  const goToPage = useCallback(
+    (next: number): void => {
+      if (next <= 0) {
+        setFrozenIds(null);
+        setPage(0);
+        return;
+      }
+      // Freeze on the way off page 1 so the history under the cursor holds still.
+      setFrozenIds((prev) => prev ?? entries.map((entry) => entry.id));
+      setPage(next);
+    },
+    [entries],
+  );
+
   const loadDetail = useCallback(
     (id: string): void => {
       if (loadingDetailsRef.current.has(id)) {
@@ -305,8 +398,10 @@ export function ApiMonitorConsole(): ReactElement {
   );
 
   useEffect(() => {
-    for (const entry of entries) {
-      if (!expandedIds.has(entry.id)) {
+    // Only rows actually on screen: an expanded row left behind on another page
+    // would otherwise keep polling its detail every tick.
+    for (const entry of visible) {
+      if (isLifecycle(entry) || !expandedIds.has(entry.id)) {
         continue;
       }
       const cached = detailsRef.current[entry.id];
@@ -314,7 +409,7 @@ export function ApiMonitorConsole(): ReactElement {
         loadDetail(entry.id);
       }
     }
-  }, [entries, expandedIds, loadDetail]);
+  }, [visible, expandedIds, loadDetail]);
 
   return (
     <section className="flex min-w-0 flex-col rounded-lg border border-border/70 bg-background">
@@ -375,19 +470,52 @@ export function ApiMonitorConsole(): ReactElement {
           </div>
         ) : (
           <div className="grid gap-3">
-            {entries.map((entry) => (
-              <MonitorEntry
-                key={entry.id}
-                entry={entry}
-                detail={details[entry.id]}
-                expanded={expandedIds.has(entry.id)}
-                loading={loadingDetails.has(entry.id)}
-                onToggle={() => toggleEntry(entry)}
-              />
-            ))}
+            {visible.map((entry) =>
+              isLifecycle(entry) ? (
+                <LifecycleEntry key={entry.id} entry={entry} />
+              ) : (
+                <MonitorEntry
+                  key={entry.id}
+                  entry={entry}
+                  detail={details[entry.id]}
+                  expanded={expandedIds.has(entry.id)}
+                  loading={loadingDetails.has(entry.id)}
+                  onToggle={() => toggleEntry(entry)}
+                />
+              ),
+            )}
           </div>
         )}
       </div>
+
+      {ordered.length > PAGE_SIZE ? (
+        <div className="flex items-center justify-between gap-2 border-t border-border/60 px-4 py-2 text-xs text-muted-foreground">
+          <span>
+            Page {pageIndex + 1} of {pageCount}
+            {newerCount > 0 ? ` (${newerCount.toLocaleString()} new)` : ""}
+          </span>
+          <div className="flex items-center gap-1">
+            <Button
+              variant="ghost"
+              size="sm"
+              className="h-7 px-2 text-xs"
+              onClick={() => goToPage(pageIndex - 1)}
+              disabled={pageIndex === 0}
+            >
+              Newer
+            </Button>
+            <Button
+              variant="ghost"
+              size="sm"
+              className="h-7 px-2 text-xs"
+              onClick={() => goToPage(pageIndex + 1)}
+              disabled={pageIndex >= pageCount - 1}
+            >
+              Older
+            </Button>
+          </div>
+        </div>
+      ) : null}
     </section>
   );
 }
diff --git a/studio/frontend/src/features/settings/components/usage-examples.tsx b/studio/frontend/src/features/settings/components/usage-examples.tsx
index 3fdb65ea3a2..e26a6ed4f63 100644
--- a/studio/frontend/src/features/settings/components/usage-examples.tsx
+++ b/studio/frontend/src/features/settings/components/usage-examples.tsx
@@ -350,6 +350,20 @@ function writeUseTunnelPref(value: boolean): void {
   }
 }
 
+// A checkpoint can be an on-disk load path (an auto-switch load resolves to the
+// GGUF/snapshot dir), which must never reach a printed snippet: it leaks the host
+// layout and is not an id /v1 advertises. Mirrors the backend's _looks_like_path.
+function looksLikePath(id: string): boolean {
+  return (
+    id.startsWith("/") ||
+    id.startsWith("~") ||
+    id.startsWith(".") ||
+    id.includes("\\") ||
+    id.toLowerCase().endsWith(".gguf") ||
+    (id.match(/\//g)?.length ?? 0) >= 2
+  );
+}
+
 // The model the examples name. With nothing loaded this used to print
 // MODEL_FALLBACK, a repo id the user likely never downloaded, so the copied
 // snippet 404d. Prefer a real id from the catalog /v1 resolves against; the
@@ -358,7 +372,9 @@ function useExampleModelName(): string {
   const checkpoint = useChatRuntimeStore((s) => s.params.checkpoint);
   const ggufVariant = useChatRuntimeStore((s) => s.activeGgufVariant);
   const [catalog, setCatalog] = useState<OpenAIModel[]>([]);
-  const needsCatalog = !checkpoint || checkpoint.startsWith("external::");
+  const usableCheckpoint =
+    !!checkpoint && !checkpoint.startsWith("external::") && !looksLikePath(checkpoint);
+  const needsCatalog = !usableCheckpoint;
 
   // Only when the checkpoint can't answer it: /v1/models scans the model dirs and
   // HF caches. Re-runs when a model is loaded or unloaded.
@@ -378,18 +394,23 @@ function useExampleModelName(): string {
   }, [needsCatalog]);
 
   return useMemo(() => {
-    if (checkpoint && !checkpoint.startsWith("external::")) {
+    if (usableCheckpoint && checkpoint) {
       if (ggufVariant && !checkpoint.includes(":")) {
         return `${checkpoint}:${ggufVariant}`;
       }
       return checkpoint;
     }
-    // No local checkpoint (or an external provider, which /v1 cannot serve):
-    // name something this server actually holds.
-    return (
-      catalog.find((m) => m.loaded)?.id ?? catalog[0]?.id ?? MODEL_FALLBACK
-    );
-  }, [catalog, checkpoint, ggufVariant]);
+    // No usable checkpoint (none, an external provider, or a raw load path):
+    // name something this server actually holds, quant included so the request
+    // pins the file on disk instead of letting the server pick a quant.
+    const pick = catalog.find((m) => m.loaded) ?? catalog[0];
+    if (!pick) {
+      return MODEL_FALLBACK;
+    }
+    return pick.quant && !pick.id.includes(":")
+      ? `${pick.id}:${pick.quant}`
+      : pick.id;
+  }, [catalog, checkpoint, ggufVariant, usableCheckpoint]);
 }
 
 // Backend PATH detection is only safe in the desktop app, where the UI owns
diff --git a/studio/frontend/src/features/settings/tabs/api-keys-tab.tsx b/studio/frontend/src/features/settings/tabs/api-keys-tab.tsx
index f1e503f7a3f..7a1fdc1fb23 100644
--- a/studio/frontend/src/features/settings/tabs/api-keys-tab.tsx
+++ b/studio/frontend/src/features/settings/tabs/api-keys-tab.tsx
@@ -168,12 +168,12 @@ export function ApiKeysTab() {
         )}
       </section>
 
+      <ModelAutoSwitchSection />
+
       <ApiMonitorConsole />
 
       <UsageExamples apiKey={revealed} />
 
-      <ModelAutoSwitchSection />
-
       <Dialog open={revokeTarget !== null} onOpenChange={(o) => !o && setRevokeTarget(null)}>
         <DialogContent className="max-w-md">
           <DialogHeader>
diff --git a/studio/frontend/src/i18n/locales/en.ts b/studio/frontend/src/i18n/locales/en.ts
index 2e6571c3002..1b7a11213fa 100644
--- a/studio/frontend/src/i18n/locales/en.ts
+++ b/studio/frontend/src/i18n/locales/en.ts
@@ -282,20 +282,18 @@ export const en = {
         sectionTitle: "Model auto-switch (OpenAI API)",
         enable: "Switch model by request",
         enableDescription:
-          "When an OpenAI-compatible request names a different downloaded GGUF, load it before serving. Off by default; unknown names keep serving the loaded model.",
+          "Load a downloaded GGUF named in an API request before serving. Off by default.",
         idleUnload: "Idle auto-unload",
         idleUnloadDescription:
-          "Unload the model after this many idle seconds to free VRAM; the next request reloads it. 0 keeps it loaded. Minimum 60 seconds.",
-        idleNeedsEnable:
-          "Turn on Switch model by request so an unloaded model reloads on next use.",
-        idleActiveViaEnv:
-          "Idle auto-unload is active via the UNSLOTH_MODEL_IDLE_TTL environment variable.",
+          "Free VRAM after this many idle seconds. 0 keeps it loaded, minimum 60.",
+        idleNeedsEnable: "Turn on Switch model by request first.",
+        idleActiveViaEnv: "Active via UNSLOTH_MODEL_IDLE_TTL.",
         loadError: "Failed to load model auto-switch settings.",
         saveError: "Failed to save model auto-switch settings.",
         idleError: "Enter 0 to keep the model loaded, or at least 60 seconds.",
         keepKv: "Keep chat context across idle unload",
         keepKvDescription:
-          "Save the model's KV cache to disk before an idle unload and restore it on reload, so resumed chats skip re-reading their history. Chat context is written to disk (up to 10 GB) until it is restored or cleaned up.",
+          "Save the KV cache before an idle unload so resumed chats skip re-reading history. Up to 10 GB on disk.",
       },
       previewSharing: {
         sectionTitle: "Preview sharing",
diff --git a/tests/studio/test_usage_examples_model_source_contract.py b/tests/studio/test_usage_examples_model_source_contract.py
index 549957ea60c..8e355de3a19 100644
--- a/tests/studio/test_usage_examples_model_source_contract.py
+++ b/tests/studio/test_usage_examples_model_source_contract.py
@@ -25,7 +25,9 @@ def test_examples_name_a_model_the_server_can_serve():
     assert "listOpenAIModels()" in hook
     # Precedence: live checkpoint, then a loaded catalog entry, then any entry,
     # and only then the placeholder.
-    assert "catalog.find((m) => m.loaded)?.id ?? catalog[0]?.id ?? MODEL_FALLBACK" in hook
+    assert "catalog.find((m) => m.loaded) ?? catalog[0]" in hook
+    # The snippet pins the quant so the request names the file on disk.
+    assert "`${pick.id}:${pick.quant}`" in hook
 
     api = OPENAI_MODELS_TS.read_text(encoding = "utf-8")
     assert 'authFetch("/v1/models")' in api
@@ -45,3 +47,34 @@ def test_usage_examples_has_no_duplicate_auto_switch_control():
 
     tab = API_KEYS_TAB_TSX.read_text(encoding = "utf-8")
     assert "<ModelAutoSwitchSection />" in tab
+
+
+API_MONITOR_TSX = SETTINGS / "components/api-monitor-console.tsx"
+
+
+def test_api_monitor_pages_five_at_a_time():
+    # 50 terminal entries are retained backend-side; the console used to dump all
+    # of them into one scroller.
+    src = API_MONITOR_TSX.read_text(encoding = "utf-8")
+    assert "const PAGE_SIZE = 5;" in src
+    assert "ordered.slice(" in src
+    # Paging back must freeze the id order, or live traffic reorders history
+    # under the cursor between polls.
+    assert "frozenIds" in src
+    assert "setFrozenIds((prev) => prev ?? entries.map((entry) => entry.id))" in src
+
+
+def test_api_monitor_renders_lifecycle_rows():
+    src = API_MONITOR_TSX.read_text(encoding = "utf-8")
+    assert "function LifecycleEntry(" in src
+    assert 'entry.kind === "lifecycle"' in src
+    for label in ("Loading model", "Model loaded", "Model unloaded"):
+        assert label in src
+    # Lifecycle rows have no prompt/reply to fetch.
+    assert "isLifecycle(entry) || !expandedIds.has(entry.id)" in src
+
+
+def test_auto_switch_section_sits_above_the_monitor():
+    tab = API_KEYS_TAB_TSX.read_text(encoding = "utf-8")
+    assert tab.index("<ModelAutoSwitchSection />") < tab.index("<ApiMonitorConsole />")
+    assert tab.index("<ApiMonitorConsole />") < tab.index("<UsageExamples")

From 41b3e3a57beb5669107708b33fbfc1d342fa428e Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Sun, 26 Jul 2026 07:33:28 +0000
Subject: [PATCH 04/56] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 studio/backend/tests/test_api_monitor.py    | 4 +---
 studio/backend/tests/test_openai_catalog.py | 3 +--
 2 files changed, 2 insertions(+), 5 deletions(-)

diff --git a/studio/backend/tests/test_api_monitor.py b/studio/backend/tests/test_api_monitor.py
index 44b1f5fecde..6a7b228f59d 100644
--- a/studio/backend/tests/test_api_monitor.py
+++ b/studio/backend/tests/test_api_monitor.py
@@ -355,7 +355,5 @@ def test_lifecycle_rows_share_the_retention_budget():
 
 def test_request_rows_report_kind_request():
     monitor = ApiMonitor(max_entries = 2)
-    monitor.start(
-        endpoint = "/v1/chat/completions", method = "POST", model = "m", prompt = "hi"
-    )
+    monitor.start(endpoint = "/v1/chat/completions", method = "POST", model = "m", prompt = "hi")
     assert monitor.snapshot()[0]["kind"] == "request"
diff --git a/studio/backend/tests/test_openai_catalog.py b/studio/backend/tests/test_openai_catalog.py
index 3c5c953b962..9f44eddd281 100644
--- a/studio/backend/tests/test_openai_catalog.py
+++ b/studio/backend/tests/test_openai_catalog.py
@@ -242,8 +242,7 @@ def test_lifecycle_label_recovers_the_repo_id_from_an_hf_cache_path():
     # sha, so the row would otherwise be labelled with a hash.
     snap = "/home/me/.cache/huggingface/hub/models--unsloth--gemma-4-E4B-it-GGUF/snapshots/bfc15c3"
     assert (
-        inf._lifecycle_model_label(snap, "UD-Q4_K_XL")
-        == "unsloth/gemma-4-E4B-it-GGUF:UD-Q4_K_XL"
+        inf._lifecycle_model_label(snap, "UD-Q4_K_XL") == "unsloth/gemma-4-E4B-it-GGUF:UD-Q4_K_XL"
     )
 
 

From d80cb3a121818c955816512edfce54eb4580ce7d Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Sun, 26 Jul 2026 09:51:53 +0000
Subject: [PATCH 05/56] Studio: optionally download a model named in an OpenAI
 API request

Auto-switch only ever loaded models already on disk, so naming one this
server does not have either 404s or, when something else is loaded, gets
quietly answered by the resident model.

Add openai_api_auto_download_model (off by default, gated on auto-switch).
When on, a /v1 request naming a GGUF repo that is not downloaded starts a
background fetch and returns 503 with Retry-After and a typed
model_downloading code. The resident model keeps serving in the meantime,
and the retry after the download completes is served by the new model
through the existing auto-switch path.

The download reuses the Hub manager's service layer, which already does
repo-id validation, casing, claim bookkeeping, disk preflight, resume and
cancel. The in-loader download is deliberately not used: it silently falls
back to a smaller quant under low disk, which is wrong when the caller
named an exact one.

Admission is narrow, since a request only needs an API key:

- namespace/name only, so gpt-4 and other foreign ids fall through to the
  resident model exactly as before
- GGUF only, decided from the remote file list rather than the repo name
- anything declaring auto_map is refused, so trust_remote_code stays a
  deliberate opt-in in the UI and can never be granted over the API
- a single download at a time, plus a free-disk reserve
- one model_info call answers existence, gating and the quant list, so a
  missing repo, a gated repo and a wrong quant each get their own error

With the setting off every one of these paths is byte-identical to before.

Also:

- monitor rows for downloads, with a live percentage
- public_model_id resolves an HF cache snapshot to its repo id, so a
  cache-loaded model is no longer labelled with a commit sha; this drops
  the duplicate helper added for the monitor and fixes the same leak in
  the inference status response
- the unedited sk-unsloth-YOUR_KEY from the copyable examples now says so
  instead of "Invalid or expired API key"; every other bad key keeps the
  generic message
---
 studio/backend/auth/authentication.py         |  19 +-
 studio/backend/core/inference/api_monitor.py  |  13 +
 .../core/inference/local_model_resolver.py    |   8 +
 studio/backend/core/inference/model_ids.py    |  23 +-
 .../core/inference/openai_auto_download.py    | 488 ++++++++++++++++++
 studio/backend/routes/inference.py            |  91 +++-
 studio/backend/routes/settings.py             |  15 +-
 studio/backend/tests/test_model_ids.py        |  18 +
 .../tests/test_openai_auto_download.py        | 470 +++++++++++++++++
 .../backend/tests/test_openai_auto_switch.py  |  15 +-
 .../utils/openai_auto_switch_settings.py      |  44 +-
 .../frontend/src/features/chat/types/api.ts   |  10 +-
 .../settings/api/openai-auto-switch.ts        |  11 +
 .../components/api-monitor-console.tsx        |  13 +-
 .../components/model-auto-switch-section.tsx  |  19 +
 studio/frontend/src/i18n/locales/en.ts        |   3 +
 ...st_usage_examples_model_source_contract.py |  29 ++
 17 files changed, 1256 insertions(+), 33 deletions(-)
 create mode 100644 studio/backend/core/inference/openai_auto_download.py
 create mode 100644 studio/backend/tests/test_openai_auto_download.py

diff --git a/studio/backend/auth/authentication.py b/studio/backend/auth/authentication.py
index dfb8fc513e3..cdb2b897c50 100644
--- a/studio/backend/auth/authentication.py
+++ b/studio/backend/auth/authentication.py
@@ -164,6 +164,23 @@ async def get_current_subject_allow_password_change(
     )
 
 
+# The literal the copyable API examples ship with. Pasting a snippet unedited is
+# a much likelier mistake than a revoked key, so say so instead of "invalid".
+API_KEY_PLACEHOLDER = f"{API_KEY_PREFIX}YOUR_KEY"
+
+
+def _invalid_api_key_detail(token: str) -> str:
+    """Why the key failed. Only the unedited example placeholder is called out;
+    every real key still gets one indistinguishable message, so this reveals
+    nothing about which keys exist."""
+    if token == API_KEY_PLACEHOLDER:
+        return (
+            "This is the placeholder key from the example. Create an API key in "
+            f"Unsloth Studio under Settings > API and use it in place of {API_KEY_PLACEHOLDER}."
+        )
+    return "Invalid or expired API key"
+
+
 async def _get_current_subject(
     credentials: HTTPAuthorizationCredentials, *, allow_password_change: bool
 ) -> str:
@@ -176,7 +193,7 @@ async def _get_current_subject(
         if username is None:
             raise HTTPException(
                 status_code = status.HTTP_401_UNAUTHORIZED,
-                detail = "Invalid or expired API key",
+                detail = _invalid_api_key_detail(token),
             )
         return username
 
diff --git a/studio/backend/core/inference/api_monitor.py b/studio/backend/core/inference/api_monitor.py
index 2390d235a2e..e2a72f31419 100644
--- a/studio/backend/core/inference/api_monitor.py
+++ b/studio/backend/core/inference/api_monitor.py
@@ -59,6 +59,8 @@ class ApiMonitorEntry:
     event: Optional[str] = None
     reason: Optional[str] = None
     shared: bool = False
+    # 0-100 for a running download row; None when not applicable.
+    progress: Optional[float] = None
 
     def snapshot(self, *, include_details: bool = True) -> dict[str, Any]:
         duration_ms = None
@@ -95,6 +97,7 @@ def snapshot(self, *, include_details: bool = True) -> dict[str, Any]:
             "kind": self.kind,
             "event": self.event,
             "reason": self.reason,
+            "progress": self.progress,
         }
         if include_details:
             payload["prompt"] = self.prompt
@@ -186,6 +189,16 @@ def relabel(self, entry_id: Optional[str], model: str) -> None:
                 entry.model = model
                 entry.updated_at = time.time()
 
+    def set_progress(self, entry_id: Optional[str], progress: Optional[float]) -> None:
+        """Update an open download row's percentage (clamped to 0-100)."""
+        if not entry_id or progress is None:
+            return
+        with self._lock:
+            entry = self._find_locked(entry_id)
+            if entry is not None and entry.status == "running":
+                entry.progress = min(100.0, max(0.0, float(progress)))
+                entry.updated_at = time.time()
+
     def discard(self, entry_id: Optional[str]) -> None:
         """Drop a row that turned out not to be an event (a load that was already
         satisfied, so nothing was actually loaded)."""
diff --git a/studio/backend/core/inference/local_model_resolver.py b/studio/backend/core/inference/local_model_resolver.py
index 0533db944f6..61e4db8f4ea 100644
--- a/studio/backend/core/inference/local_model_resolver.py
+++ b/studio/backend/core/inference/local_model_resolver.py
@@ -232,6 +232,14 @@ def _scan_hf_once(directory) -> list:
     return index
 
 
+def invalidate_index() -> None:
+    """Drop the cached scan so the next resolve sees a just-finished download,
+    rather than waiting out the TTL."""
+    global _scan
+    with _lock:
+        _scan = (0.0, {})
+
+
 def _index() -> dict[str, _LocalGgufEntry]:
     global _scan
     # Build under the lock so concurrent callers with an expired cache don't all
diff --git a/studio/backend/core/inference/model_ids.py b/studio/backend/core/inference/model_ids.py
index 548cc60f94a..07148402dd7 100644
--- a/studio/backend/core/inference/model_ids.py
+++ b/studio/backend/core/inference/model_ids.py
@@ -39,10 +39,28 @@ def _looks_like_path(identifier: str) -> bool:
     return False
 
 
+def hf_cache_repo_id(path: Optional[str]) -> Optional[str]:
+    """``.../models--org--name/snapshots/<sha>`` -> ``org/name``, else None.
+
+    A model loaded straight out of the HF cache has a snapshot directory as its
+    identifier, whose basename is a commit hash. Recover the repo id so callers
+    show ``unsloth/gemma-4-31B-it-GGUF`` rather than ``c1ac76e99d55...``.
+    """
+    if not path:
+        return None
+    for part in str(path).replace("\\", "/").split("/"):
+        if part.startswith("models--"):
+            return part[len("models--") :].replace("--", "/")
+    return None
+
+
 def public_model_id(identifier: Optional[str]) -> Optional[str]:
     """Return a clean, path-free public id for *identifier*.
 
-    - Local GGUF path -> the file stem with ``.gguf`` stripped, e.g.
+    - HF cache path -> the repo id it came from, e.g.
+      ``~/.cache/huggingface/hub/models--unsloth--X-GGUF/snapshots/<sha>`` ->
+      ``unsloth/X-GGUF``.
+    - Other local GGUF path -> the file stem with ``.gguf`` stripped, e.g.
       ``/srv/models/Qwen3-30B-A3B-Q4_K_M.gguf`` -> ``Qwen3-30B-A3B-Q4_K_M``.
     - HF repo id (``org/model``) and already-clean names -> returned unchanged.
     - ``None`` / empty -> returned unchanged.
@@ -51,6 +69,9 @@ def public_model_id(identifier: Optional[str]) -> Optional[str]:
         return identifier
     if not _looks_like_path(identifier):
         return identifier
+    repo_id = hf_cache_repo_id(identifier)
+    if repo_id:
+        return repo_id
     name = os.path.basename(identifier.replace("\\", "/").rstrip("/"))
     if name.lower().endswith(_GGUF_SUFFIX):
         name = name[: -len(_GGUF_SUFFIX)]
diff --git a/studio/backend/core/inference/openai_auto_download.py b/studio/backend/core/inference/openai_auto_download.py
new file mode 100644
index 00000000000..3f6670c14e8
--- /dev/null
+++ b/studio/backend/core/inference/openai_auto_download.py
@@ -0,0 +1,488 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Opt-in: fetch a GGUF a /v1 request names but this server doesn't have.
+
+Auto-switch only loads models already on disk. With
+``openai_api_auto_download_model`` on, a miss that looks like a real Hub repo is
+downloaded in the background instead of erroring, and the request is told to
+retry rather than being held open: a quant is routinely tens of GB, far longer
+than any client (or the Cloudflare edge on ``--secure``) will wait, and the
+inference lifecycle gate must not be held meanwhile. The resident model keeps
+serving throughout, and the retry that lands after the download is served by the
+new model through the ordinary auto-switch path.
+
+Admission is deliberately narrow, since a request only needs an API key:
+- ``namespace/name`` only. A bare name like ``gpt-4`` falls through to the
+  resident model exactly as before, so drop-in clients are unaffected.
+- GGUF repos only, decided from the remote file list, not the repo name. GGUF
+  runs under llama.cpp, which never imports repo Python.
+- Anything declaring ``auto_map`` is refused, so ``trust_remote_code`` can only
+  ever be granted deliberately in the UI, never by an API call.
+- One download at a time, so a key holder cannot fan out fetches.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import shutil
+import threading
+import time
+from dataclasses import dataclass
+from typing import Optional
+
+from loggers import get_logger
+
+logger = get_logger(__name__)
+
+# Hub metadata is one small request; keep it short so a slow Hub can't stall the
+# request path for long.
+_MODEL_INFO_TIMEOUT_S = 8.0
+# Headroom left free after the download, so filling the disk can't wedge the box.
+_DISK_RESERVE_BYTES = 5 * 1024**3
+_WATCH_POLL_S = 2.0
+# A stalled watcher must not pin the single-flight slot forever.
+_MAX_WATCH_S = 24 * 60 * 60
+_RETRY_AFTER_S = 30
+_MAX_LISTED_VARIANTS = 8
+
+
+@dataclass(frozen = True)
+class AutoDownloadRefusal:
+    """Why this request cannot be served yet. The route turns it into an
+    HTTPException with the surface's own error envelope."""
+
+    status: int
+    code: str
+    message: str
+    retry_after: Optional[int] = None
+
+
+@dataclass
+class _Active:
+    repo_id: str
+    # None while the Hub probe is still deciding which quant to fetch.
+    variant: Optional[str] = None
+    expected_bytes: int = 0
+    monitor_id: Optional[str] = None
+    started_at: float = 0.0
+
+
+_lock = threading.Lock()
+_active: Optional[_Active] = None
+
+
+def _public_label(repo_id: str, variant: Optional[str]) -> str:
+    return f"{repo_id}:{variant}" if variant else repo_id
+
+
+def split_model_ref(requested: str) -> tuple[str, Optional[str]]:
+    """``org/repo:QUANT`` -> ``("org/repo", "QUANT")``; no suffix -> variant None.
+
+    Splits on the last colon only when the suffix carries no slash, so a Windows
+    drive letter or a path never reads as a quant.
+    """
+    text = (requested or "").strip()
+    base, sep, suffix = text.rpartition(":")
+    if not sep or not base or "/" in suffix or not suffix:
+        return text, None
+    return base.strip(), suffix.strip()
+
+
+def is_downloadable_ref(requested: str) -> bool:
+    """Whether *requested* is shaped like a Hub repo we may fetch.
+
+    Requires an explicit namespace. That keeps ``gpt-4`` and other foreign ids
+    falling through untouched, and avoids the bare-name ``unsloth/`` prefixing in
+    ModelConfig.from_identifier turning an unrelated label into a real repo.
+    """
+    from hub.utils.paths import is_valid_repo_id
+
+    repo_id, variant = split_model_ref(requested)
+    if "/" not in repo_id or not is_valid_repo_id(repo_id):
+        return False
+    if variant is not None:
+        from hub.utils.paths import is_valid_gguf_variant
+        return is_valid_gguf_variant(variant)
+    return True
+
+
+def _gguf_variants(siblings) -> dict[str, int]:
+    """Quant label -> total bytes, from a model_info sibling list.
+
+    Mirrors list_gguf_variants: companions (mmproj/MTP) and big-endian builds
+    are not selectable quants, and sharded quants sum across their shards.
+    """
+    from utils.models.model_config import (
+        _extract_quant_label,
+        _is_big_endian_gguf_path,
+        _is_mmproj,
+        _is_mtp_drafter,
+    )
+
+    sizes: dict[str, int] = {}
+    for sibling in siblings or []:
+        name = getattr(sibling, "rfilename", "") or ""
+        if not name.lower().endswith(".gguf"):
+            continue
+        quant = _extract_quant_label(name)
+        if _is_mmproj(name) or _is_mtp_drafter(name) or _is_big_endian_gguf_path(name, quant):
+            continue
+        sizes[quant] = sizes.get(quant, 0) + int(getattr(sibling, "size", 0) or 0)
+    return sizes
+
+
+def _enough_disk(need_bytes: int) -> tuple[bool, int]:
+    """(fits, free_bytes). Fail-open on an unreadable cache root: the download
+    worker runs its own preflight, this only adds the reserve margin."""
+    try:
+        from hub.utils.hf_cache_state import hf_cache_root
+
+        root = hf_cache_root(create = True)
+        if root is None:
+            return True, 0
+        free = shutil.disk_usage(root).free
+    except Exception:
+        return True, 0
+    return free >= need_bytes + _DISK_RESERVE_BYTES, free
+
+
+def _gb(num_bytes: int) -> str:
+    return f"{num_bytes / 1024**3:.1f} GB"
+
+
+async def _job_state(repo_id: str, variant: Optional[str]) -> tuple[str, Optional[str]]:
+    from hub.services.models import downloads
+    try:
+        status = await downloads.get_download_status_response(repo_id, variant or "")
+        return status.state, status.error
+    except Exception as exc:
+        logger.debug("auto-download: status probe failed for %r: %s", repo_id, exc)
+        return "idle", None
+
+
+async def _progress_percent(
+    repo_id: str, variant: Optional[str], expected_bytes: int, hf_token: Optional[str]
+) -> Optional[float]:
+    """0-100, or None. The hub service reports a 0-1 fraction, so scale it."""
+    from hub.services.models import downloads
+    try:
+        payload = await downloads.get_gguf_download_progress_response(
+            repo_id, variant or "", expected_bytes, hf_token
+        )
+        fraction = payload.get("progress")
+        if not isinstance(fraction, (int, float)):
+            return None
+        return min(100.0, max(0.0, float(fraction) * 100.0))
+    except Exception:
+        return None
+
+
+def _release(repo_id: str) -> None:
+    global _active
+    with _lock:
+        if _active is not None and _active.repo_id == repo_id:
+            _active = None
+
+
+async def _watch(active: _Active, hf_token: Optional[str]) -> None:
+    """Poll a dispatched job so the monitor row resolves and the resolver cache
+    is dropped the moment the weights land."""
+    from core.inference import api_monitor as monitor_module
+    from core.inference.local_model_resolver import invalidate_index
+
+    api_monitor = monitor_module.api_monitor
+    deadline = time.monotonic() + _MAX_WATCH_S
+    try:
+        while time.monotonic() < deadline:
+            await asyncio.sleep(_WATCH_POLL_S)
+            state, error = await _job_state(active.repo_id, active.variant)
+            if state == "running":
+                api_monitor.set_progress(
+                    active.monitor_id,
+                    await _progress_percent(
+                        active.repo_id, active.variant, active.expected_bytes, hf_token
+                    ),
+                )
+                continue
+            if state == "complete":
+                # Drop the 5s resolver cache so the next retry resolves the new
+                # model instead of missing it again.
+                await asyncio.to_thread(invalidate_index)
+                api_monitor.finish(active.monitor_id, status = "completed")
+            elif state == "idle":
+                # The job vanished without a terminal state (worker killed).
+                api_monitor.fail_open(active.monitor_id, "Download did not complete")
+            else:
+                api_monitor.fail_open(active.monitor_id, error or f"Download {state}")
+            return
+        api_monitor.fail_open(active.monitor_id, "Download timed out")
+    except asyncio.CancelledError:
+        raise
+    except Exception as exc:
+        logger.warning("auto-download: watcher failed for %r: %s", active.repo_id, exc)
+        api_monitor.fail_open(active.monitor_id, "Download tracking failed")
+    finally:
+        _release(active.repo_id)
+
+
+def _downloading_refusal(label: str, percent: Optional[float]) -> AutoDownloadRefusal:
+    progress = f" ({percent:.0f}% done)" if percent is not None else ""
+    return AutoDownloadRefusal(
+        status = 503,
+        code = "model_downloading",
+        message = (f"Downloading '{label}'{progress}. Retry shortly. Track it in Unsloth Studio."),
+        retry_after = _RETRY_AFTER_S,
+    )
+
+
+async def maybe_auto_download(
+    requested_model: str, *, hf_token: Optional[str] = None
+) -> Optional[AutoDownloadRefusal]:
+    """Start (or report on) a background fetch of *requested_model*.
+
+    Returns None when the request should carry on unchanged, or a refusal the
+    caller must raise. Only called after the local resolver has already missed.
+    """
+    global _active
+
+    repo_id, wanted_variant = split_model_ref(requested_model)
+    if not is_downloadable_ref(requested_model):
+        return None
+
+    # Adopt or reject against the single in-flight slot before touching the
+    # network, so retries during a long download stay free.
+    with _lock:
+        current = _active
+        if current is not None and current.repo_id == repo_id:
+            adopted = current
+        elif current is not None:
+            return AutoDownloadRefusal(
+                status = 503,
+                code = "model_download_busy",
+                message = (
+                    f"Already downloading '{_public_label(current.repo_id, current.variant)}'. "
+                    f"Retry '{requested_model}' once it finishes."
+                ),
+                retry_after = _RETRY_AFTER_S,
+            )
+        else:
+            adopted = None
+            _active = _Active(repo_id = repo_id, started_at = time.time())
+
+    if adopted is not None:
+        state, error = await _job_state(adopted.repo_id, adopted.variant)
+        if state in ("running", "cancelling"):
+            return _downloading_refusal(
+                _public_label(adopted.repo_id, adopted.variant),
+                await _progress_percent(
+                    adopted.repo_id, adopted.variant, adopted.expected_bytes, hf_token
+                ),
+            )
+        if state == "error":
+            # Surface once, then free the slot so a retry can start over.
+            _release(adopted.repo_id)
+            return AutoDownloadRefusal(
+                status = 502,
+                code = "model_download_failed",
+                message = f"Downloading '{requested_model}' failed: {error or 'unknown error'}",
+            )
+        if adopted.variant is None:
+            # Another request is still probing this same repo.
+            return _downloading_refusal(adopted.repo_id, None)
+        # complete/idle: the watcher is about to release; ask for one more retry.
+        return _downloading_refusal(_public_label(adopted.repo_id, adopted.variant), 100.0)
+
+    try:
+        return await _admit_and_start(repo_id, wanted_variant, requested_model, hf_token)
+    except Exception:
+        _release(repo_id)
+        raise
+
+
+async def _admit_and_start(
+    repo_id: str, wanted_variant: Optional[str], requested_model: str, hf_token: Optional[str]
+) -> Optional[AutoDownloadRefusal]:
+    from hub.utils.hf_errors import hf_error_status
+
+    def _probe():
+        from huggingface_hub import HfApi
+        return HfApi(token = hf_token).model_info(
+            repo_id, files_metadata = True, timeout = _MODEL_INFO_TIMEOUT_S
+        )
+
+    try:
+        info = await asyncio.to_thread(_probe)
+    except Exception as exc:
+        _release(repo_id)
+        status = hf_error_status(exc)
+        if status == 403:
+            return AutoDownloadRefusal(
+                status = 403,
+                code = "model_access_denied",
+                message = (
+                    f"'{repo_id}' is gated on Hugging Face. Accept its licence and add an "
+                    "access token in Unsloth Studio, then retry."
+                ),
+            )
+        if status == 404:
+            # A private repo reads as absent without a token; don't confirm either way.
+            return AutoDownloadRefusal(
+                status = 404,
+                code = "model_not_found",
+                message = f"'{repo_id}' was not found on Hugging Face, or is not accessible.",
+            )
+        logger.warning("auto-download: Hub lookup failed for %r: %s", repo_id, exc)
+        return AutoDownloadRefusal(
+            status = 503,
+            code = "model_lookup_failed",
+            message = f"Could not reach Hugging Face to look up '{repo_id}'. Retry shortly.",
+            retry_after = _RETRY_AFTER_S,
+        )
+
+    variants = _gguf_variants(getattr(info, "siblings", None))
+    if not variants:
+        _release(repo_id)
+        return AutoDownloadRefusal(
+            status = 400,
+            code = "model_not_supported",
+            message = (
+                f"'{repo_id}' has no GGUF weights. Automatic download serves GGUF only; "
+                "load other formats from Unsloth Studio."
+            ),
+        )
+
+    # trust_remote_code gate. _config_has_auto_map is tri-state: refuse on True
+    # and on None (unreadable), rather than _requires_trust_remote_code_for_model,
+    # which swallows errors into False. Fine as a UI hint, wrong as an admission.
+    from utils.security.consent import _config_has_auto_map
+
+    has_auto_map = await asyncio.to_thread(_config_has_auto_map, repo_id, hf_token)
+    if has_auto_map is not False:
+        _release(repo_id)
+        unknown = has_auto_map is None
+        return AutoDownloadRefusal(
+            status = 403,
+            code = "remote_code_consent_required",
+            message = (
+                f"'{repo_id}' "
+                + (
+                    "could not be checked for custom code"
+                    if unknown
+                    else "ships custom code that runs on load"
+                )
+                + ". Load it once in Unsloth Studio to review and approve it, then retry."
+            ),
+        )
+
+    variant = _match_variant(wanted_variant, variants)
+    if variant is None:
+        _release(repo_id)
+        listed = sorted(variants)
+        shown = ", ".join(listed[:_MAX_LISTED_VARIANTS])
+        extra = len(listed) - _MAX_LISTED_VARIANTS
+        return AutoDownloadRefusal(
+            status = 404,
+            code = "model_not_found",
+            message = (
+                f"'{repo_id}' has no quant '{wanted_variant}'. Available quants: "
+                f"{shown}{f' and {extra} more' if extra > 0 else ''}."
+            ),
+        )
+
+    expected_bytes = variants[variant]
+    fits, free = _enough_disk(expected_bytes)
+    if not fits:
+        _release(repo_id)
+        return AutoDownloadRefusal(
+            status = 507,
+            code = "insufficient_disk_space",
+            message = (
+                f"'{_public_label(repo_id, variant)}' needs {_gb(expected_bytes)} plus "
+                f"{_gb(_DISK_RESERVE_BYTES)} headroom, but only {_gb(free)} is free."
+            ),
+        )
+
+    return await _dispatch(repo_id, variant, expected_bytes, requested_model, hf_token)
+
+
+def _match_variant(wanted: Optional[str], variants: dict[str, int]) -> Optional[str]:
+    """Resolve the requested quant against what the repo actually has.
+
+    An explicit quant matches case-insensitively and must exist: never quietly
+    substitute another, unlike the loader's low-disk fallback. A bare repo id
+    uses the same preference order as a manual load.
+    """
+    if wanted:
+        lowered = {name.lower(): name for name in variants}
+        return lowered.get(wanted.strip().lower())
+    from utils.models.model_config import _pick_best_gguf
+
+    # _pick_best_gguf ranks filenames by quant substring, so give it synthesized
+    # "<label>.gguf" names and take the label back off the winner.
+    best = _pick_best_gguf([f"{name}.gguf" for name in variants])
+    return best[: -len(".gguf")] if best else None
+
+
+async def _dispatch(
+    repo_id: str, variant: str, expected_bytes: int, requested_model: str, hf_token: Optional[str]
+) -> AutoDownloadRefusal:
+    global _active
+
+    from core.inference.api_monitor import api_monitor
+    from hub.schemas.downloads import DownloadModelRequest
+    from hub.services.models import downloads
+
+    label = _public_label(repo_id, variant)
+    try:
+        await downloads.download_model_response(
+            DownloadModelRequest(repo_id = repo_id, gguf_variant = variant), hf_token
+        )
+    except Exception as exc:
+        _release(repo_id)
+        status = getattr(exc, "status_code", None)
+        if status == 409:
+            # A manual load or hub download already owns this repo.
+            return AutoDownloadRefusal(
+                status = 503,
+                code = "model_download_busy",
+                message = f"'{repo_id}' is already being downloaded or loaded. Retry shortly.",
+                retry_after = _RETRY_AFTER_S,
+            )
+        logger.warning("auto-download: could not start %r: %s", label, exc)
+        return AutoDownloadRefusal(
+            status = 502,
+            code = "model_download_failed",
+            message = f"Could not start downloading '{requested_model}'.",
+        )
+
+    monitor_id = api_monitor.record_lifecycle(
+        event = "download", model = label, reason = "api", running = True
+    )
+    with _lock:
+        if _active is not None and _active.repo_id == repo_id:
+            _active.variant = variant
+            _active.expected_bytes = expected_bytes
+            _active.monitor_id = monitor_id
+            tracked = _active
+        else:  # released underneath us; still track the job we just started
+            tracked = _Active(repo_id, variant, expected_bytes, monitor_id, time.time())
+            _active = tracked
+
+    asyncio.create_task(_watch(tracked, hf_token))
+    logger.info("auto-download: started %s (%s)", label, _gb(expected_bytes))
+    return AutoDownloadRefusal(
+        status = 503,
+        code = "model_downloading",
+        message = (
+            f"Downloading '{label}' ({_gb(expected_bytes)}). Retry shortly. "
+            "Track it in Unsloth Studio."
+        ),
+        retry_after = _RETRY_AFTER_S,
+    )
+
+
+def reset_for_tests() -> None:
+    global _active
+    with _lock:
+        _active = None
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index dc63eff45ea..25a157308f4 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3070,23 +3070,9 @@ def _monitor_context_length() -> Optional[int]:
     return None
 
 
-def _hf_cache_repo_id(path: Optional[str]) -> Optional[str]:
-    """``.../models--org--name/snapshots/<sha>`` -> ``org/name``, else None.
-
-    An auto-switch load is handed the concrete snapshot dir, whose basename is the
-    commit sha, so public_model_id alone would label the row with a hash.
-    """
-    if not path:
-        return None
-    for part in str(path).replace("\\", "/").split("/"):
-        if part.startswith("models--"):
-            return part[len("models--") :].replace("--", "/")
-    return None
-
-
 def _lifecycle_model_label(model: Optional[str], variant: Optional[str] = None) -> str:
     """A path-free ``repo`` / ``repo:QUANT`` label for a monitor lifecycle row."""
-    clean = _hf_cache_repo_id(model) or public_model_id(model) or model or "model"
+    clean = public_model_id(model) or model or "model"
     return f"{clean}:{variant}" if variant and ":" not in clean else clean
 
 
@@ -3707,6 +3693,69 @@ async def _no_model_loaded_error(
     )
 
 
+def _auto_download_hf_token(fastapi_request: Optional[Request]) -> Optional[str]:
+    """The token to fetch with: the Hub header if the caller sent one, else the
+    server's own. The OpenAI bearer key is never used as an HF token."""
+    from hub.dependencies import HUB_HF_TOKEN_HEADER, HUB_HF_TOKEN_MAX_LENGTH
+
+    headers = getattr(fastapi_request, "headers", None)
+    if headers is not None:
+        supplied = (headers.get(HUB_HF_TOKEN_HEADER) or "").strip()
+        if supplied and len(supplied) <= HUB_HF_TOKEN_MAX_LENGTH:
+            return supplied
+    try:
+        from routes.settings import _ambient_hf_token
+        return _ambient_hf_token()
+    except Exception:
+        return None
+
+
+async def _maybe_auto_download_model(
+    requested_model: str, fastapi_request: Optional[Request]
+) -> None:
+    """Opt-in: start fetching a named GGUF this server doesn't have.
+
+    Raises to stop the request when the model is downloading or cannot be
+    fetched. Off by default, and it never fires on a name that isn't shaped like
+    a Hub repo, so an unknown id like "gpt-4" still falls through to the resident
+    model as before.
+    """
+    from utils.openai_auto_switch_settings import get_openai_auto_download_enabled
+    from core.inference.openai_auto_download import is_downloadable_ref, maybe_auto_download
+
+    if not requested_model or not get_openai_auto_download_enabled():
+        return
+    if not is_downloadable_ref(requested_model):
+        return
+    try:
+        refusal = await maybe_auto_download(
+            requested_model, hf_token = _auto_download_hf_token(fastapi_request)
+        )
+    except Exception as exc:
+        # Never turn a servable request into a 500 over the download attempt.
+        logger.warning("auto-download failed for %r: %s", requested_model, exc)
+        return
+    if refusal is None:
+        return
+    path = getattr(getattr(fastapi_request, "url", None), "path", None)
+    detail = (
+        error_body_for_path(
+            path,
+            refusal.message,
+            status = refusal.status,
+            code = refusal.code,
+            param = "model",
+        )
+        if isinstance(path, str)
+        else refusal.message
+    )
+    raise HTTPException(
+        status_code = refusal.status,
+        detail = detail,
+        headers = ({"Retry-After": str(refusal.retry_after)} if refusal.retry_after else None),
+    )
+
+
 async def _maybe_auto_switch_model(
     requested_model: Optional[str],
     fastapi_request: Request,
@@ -3718,7 +3767,8 @@ async def _maybe_auto_switch_model(
 
     No-op unless enabled and ``requested_model`` resolves to a downloaded local
     model different from the loaded one. Unknown names fall through (drop-in
-    compat) and no remote download is triggered. ``require_vision`` rejects a swap
+    compat); a miss only reaches the network when auto-download is also on, and
+    even then only for ``namespace/name`` ids. ``require_vision`` rejects a swap
     to a text-only target before it runs, so an image request can't evict the
     resident vision model only to 400 afterwards.
     """
@@ -3761,6 +3811,10 @@ async def _resolve_and_switch() -> None:
             else None
         )
         if resolved is None:
+            # Not on disk. Opt-in: fetch it in the background and tell the caller to
+            # retry, rather than silently answering from whatever is resident.
+            if auto_switch_on and not reload_only:
+                await _maybe_auto_download_model(requested_model, fastapi_request)
             # Idle-unload may have freed the model; reload exactly what it freed
             # (path + quant + advertised id) so an alias/unknown name stays servable
             # and keeps the override keyed by the advertised id, not the load path.
@@ -6054,6 +6108,11 @@ async def get_status(current_subject: str = Depends(get_current_subject)):
                 and os.path.isabs(_model_id)
             ):
                 _display_model_id = os.path.basename(_model_id)
+            elif not _native_grant_backed and _display_model_id == _model_id:
+                # Not a leased native path, so no label was registered and the raw
+                # identifier came back. Report the clean public id instead: an HF
+                # cache load would otherwise show the snapshot's commit sha.
+                _display_model_id = _llama_public_model_id(llama_backend) or _display_model_id
             _inference_cfg = load_inference_config(_model_id) if _model_id else None
             _audio_type = getattr(llama_backend, "_audio_type", None)
             # Don't surface Unsloth's auto-applied bundled family template (e.g. the
diff --git a/studio/backend/routes/settings.py b/studio/backend/routes/settings.py
index fef18a91456..91bcb89add3 100644
--- a/studio/backend/routes/settings.py
+++ b/studio/backend/routes/settings.py
@@ -37,12 +37,14 @@
 from utils.coding_agents import CODING_AGENTS, detect_installed_coding_agents
 from utils.openai_auto_switch_settings import (
     DEFAULT_AUTO_UNLOAD_KEEP_KV,
+    DEFAULT_OPENAI_AUTO_DOWNLOAD_ENABLED,
     DEFAULT_OPENAI_AUTO_SWITCH_ENABLED,
     get_auto_unload_idle_seconds,
     get_auto_unload_keep_kv,
     get_model_overrides,
     get_openai_auto_switch_enabled,
     get_stored_auto_unload_idle_seconds,
+    get_stored_openai_auto_download_enabled,
     set_model_override,
     set_openai_auto_switch,
 )
@@ -112,6 +114,7 @@ class OpenAIAutoSwitchPayload(BaseModel):
     # None leaves the stored value untouched (partial updates can't clobber it).
     auto_unload_idle_seconds: Optional[int] = Field(default = None, ge = 0)
     auto_unload_keep_kv: Optional[bool] = None
+    auto_download_model: Optional[bool] = None
 
 
 class OpenAIAutoSwitchResponse(BaseModel):
@@ -123,6 +126,9 @@ class OpenAIAutoSwitchResponse(BaseModel):
     # is false, so the UI can show idle-unload as active instead of "needs enable".
     idle_unload_active: bool = False
     auto_unload_keep_kv: bool = DEFAULT_AUTO_UNLOAD_KEEP_KV
+    # Stored, not effective: it only takes effect while auto-switch is on, but the
+    # UI must round-trip the saved value across an auto-switch toggle.
+    auto_download_model: bool = DEFAULT_OPENAI_AUTO_DOWNLOAD_ENABLED
 
 
 class ModelOverridePayload(BaseModel):
@@ -245,6 +251,7 @@ def get_openai_auto_switch(
         auto_unload_idle_seconds = get_stored_auto_unload_idle_seconds(),
         idle_unload_active = get_auto_unload_idle_seconds() > 0,
         auto_unload_keep_kv = get_auto_unload_keep_kv(),
+        auto_download_model = get_stored_openai_auto_download_enabled(),
     )
 
 
@@ -253,8 +260,11 @@ def update_openai_auto_switch(
     payload: OpenAIAutoSwitchPayload, current_subject: str = Depends(get_current_subject)
 ) -> OpenAIAutoSwitchResponse:
     try:
-        enabled, idle_seconds, keep_kv = set_openai_auto_switch(
-            payload.enabled, payload.auto_unload_idle_seconds, payload.auto_unload_keep_kv
+        enabled, idle_seconds, keep_kv, auto_download = set_openai_auto_switch(
+            payload.enabled,
+            payload.auto_unload_idle_seconds,
+            payload.auto_unload_keep_kv,
+            payload.auto_download_model,
         )
     except ValueError as exc:
         raise log_and_http_error(
@@ -274,6 +284,7 @@ def update_openai_auto_switch(
         auto_unload_idle_seconds = idle_seconds,
         idle_unload_active = idle_unload_active,
         auto_unload_keep_kv = keep_kv,
+        auto_download_model = auto_download,
     )
 
 
diff --git a/studio/backend/tests/test_model_ids.py b/studio/backend/tests/test_model_ids.py
index f9116afec37..50c89d9ec12 100644
--- a/studio/backend/tests/test_model_ids.py
+++ b/studio/backend/tests/test_model_ids.py
@@ -37,6 +37,24 @@ def test_directory_path_uses_basename():
     assert public_model_id("a/b/c") == "c"
 
 
+def test_hf_cache_snapshot_recovers_the_repo_id():
+    from core.inference.model_ids import hf_cache_repo_id
+
+    # The snapshot basename is a commit sha, so plain basename() would label a
+    # cache-loaded model "c1ac76e9...". Recover org/name instead.
+    snapshot = (
+        "/home/u/.cache/huggingface/hub/models--unsloth--gemma-4-31B-it-GGUF"
+        "/snapshots/c1ac76e99d5513b141e8adde7288b85c3f9c32ec"
+    )
+    assert public_model_id(snapshot) == "unsloth/gemma-4-31B-it-GGUF"
+    # A file inside the snapshot resolves the same way, not to the file stem.
+    assert public_model_id(snapshot + "/gemma-4-31B-it-UD-Q5_K_XL.gguf") == (
+        "unsloth/gemma-4-31B-it-GGUF"
+    )
+    assert hf_cache_repo_id("/opt/models/plain.gguf") is None
+    assert hf_cache_repo_id(None) is None
+
+
 def test_relative_and_home_paths_are_sanitized():
     # ./ ../ ~ prefixed paths are local and must not be echoed raw.
     assert public_model_id("./model.gguf") == "model"
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
new file mode 100644
index 00000000000..3370dd0c4cb
--- /dev/null
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -0,0 +1,470 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Opt-in auto-download of a GGUF a /v1 request names but this server lacks.
+
+No network: huggingface_hub, the consent probe and the Hub download service are
+all mocked. The invariant these guard is that with the setting off nothing here
+runs at all, and with it on a name that isn't shaped like a repo still falls
+through to the resident model.
+"""
+
+import asyncio
+
+import pytest
+
+import routes.inference as inference_route
+from core.inference import openai_auto_download as auto_dl
+from utils import openai_auto_switch_settings as settings
+
+
+class _Sibling:
+    def __init__(
+        self,
+        rfilename,
+        size = 0,
+    ):
+        self.rfilename = rfilename
+        self.size = size
+
+
+class _Info:
+    def __init__(
+        self,
+        siblings,
+        sha = "abc123",
+        gated = False,
+        private = False,
+    ):
+        self.siblings = siblings
+        self.sha = sha
+        self.gated = gated
+        self.private = private
+
+
+def _gguf_repo_info():
+    gb = 1024**3
+    return _Info(
+        [
+            _Sibling("model-UD-Q4_K_XL.gguf", 4 * gb),
+            _Sibling("model-UD-Q5_K_XL.gguf", 5 * gb),
+            _Sibling("model-Q8_0-00001-of-00002.gguf", 4 * gb),
+            _Sibling("model-Q8_0-00002-of-00002.gguf", 4 * gb),
+            _Sibling("mmproj-F16.gguf", 1 * gb),
+            _Sibling("mtp-model.gguf", 1 * gb),
+            _Sibling("README.md", 1024),
+        ]
+    )
+
+
+@pytest.fixture(autouse = True)
+def _clean_slot():
+    auto_dl.reset_for_tests()
+    yield
+    auto_dl.reset_for_tests()
+
+
+@pytest.fixture
+def hub(monkeypatch):
+    """Wire the whole remote surface to fakes and record what was dispatched."""
+    import huggingface_hub
+    from hub.services.models import downloads
+
+    state = {"info": _gguf_repo_info(), "raise": None, "auto_map": False, "started": []}
+
+    class _FakeApi:
+        def __init__(self, token = None):
+            state["token"] = token
+
+        def model_info(self, repo_id, **kwargs):
+            if state["raise"] is not None:
+                raise state["raise"]
+            return state["info"]
+
+    async def _start(body, hf_token = None):
+        state["started"].append((body.repo_id, body.gguf_variant, hf_token))
+        return {"job_key": "k", "state": "running"}
+
+    async def _no_watch(active, hf_token):
+        return None
+
+    monkeypatch.setattr(huggingface_hub, "HfApi", _FakeApi)
+    monkeypatch.setattr(downloads, "download_model_response", _start)
+    monkeypatch.setattr(auto_dl, "_watch", _no_watch)
+    monkeypatch.setattr(auto_dl, "_enough_disk", lambda need: (True, 10 * 1024**4))
+    monkeypatch.setattr(
+        "utils.security.consent._config_has_auto_map",
+        lambda repo, token = None: state["auto_map"],
+    )
+    return state
+
+
+def _run(model, hf_token = None):
+    return asyncio.run(auto_dl.maybe_auto_download(model, hf_token = hf_token))
+
+
+# --- pure helpers ------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "raw,expected",
+    [
+        ("org/repo:UD-Q4_K_XL", ("org/repo", "UD-Q4_K_XL")),
+        ("org/repo", ("org/repo", None)),
+        ("gpt-4", ("gpt-4", None)),
+        # A colon followed by a path segment is not a quant.
+        ("C:/models/x.gguf", ("C:/models/x.gguf", None)),
+        ("org/repo:", ("org/repo:", None)),
+    ],
+)
+def test_split_model_ref(raw, expected):
+    assert auto_dl.split_model_ref(raw) == expected
+
+
+@pytest.mark.parametrize(
+    "raw",
+    [
+        "gpt-4",  # no namespace: a foreign id, must keep falling through
+        "gpt-4o-mini",
+        "../../etc/passwd",
+        "https://evil.example/x",
+        "/abs/path/model.gguf",
+        "org/repo/extra",
+        "org/re..po",
+        "org/repo\nX-Injected: 1",
+        "",
+    ],
+)
+def test_not_downloadable(raw):
+    assert auto_dl.is_downloadable_ref(raw) is False
+
+
+@pytest.mark.parametrize(
+    "raw", ["unsloth/gemma-4-31B-it-GGUF", "unsloth/gemma-4-31B-it-GGUF:UD-Q5_K_XL"]
+)
+def test_downloadable(raw):
+    assert auto_dl.is_downloadable_ref(raw) is True
+
+
+def test_gguf_variants_skips_companions():
+    variants = auto_dl._gguf_variants(_gguf_repo_info().siblings)
+    assert set(variants) == {"UD-Q4_K_XL", "UD-Q5_K_XL", "Q8_0"}
+    # Shards of one quant sum together.
+    assert variants["Q8_0"] == 8 * 1024**3
+
+
+def test_match_variant_is_case_insensitive_and_exact():
+    variants = {"UD-Q4_K_XL": 1, "Q8_0": 2}
+    assert auto_dl._match_variant("ud-q4_k_xl", variants) == "UD-Q4_K_XL"
+    assert auto_dl._match_variant("Q5_K_M", variants) is None
+    # A bare id picks a real local label, never invents one.
+    assert auto_dl._match_variant(None, variants) in variants
+
+
+# --- admission ---------------------------------------------------------------
+
+
+def test_foreign_id_never_probes(hub):
+    assert _run("gpt-4") is None
+    assert hub["started"] == []
+
+
+def test_starts_download_and_asks_for_a_retry(hub):
+    refusal = _run("unsloth/x-GGUF:UD-Q5_K_XL")
+    assert refusal.status == 503
+    assert refusal.code == "model_downloading"
+    assert refusal.retry_after and refusal.retry_after > 0
+    assert "unsloth/x-GGUF:UD-Q5_K_XL" in refusal.message
+    assert hub["started"] == [("unsloth/x-GGUF", "UD-Q5_K_XL", None)]
+
+
+def test_bare_id_freezes_the_same_quant_a_manual_load_would_pick(hub):
+    from utils.models.model_config import _extract_quant_label, _pick_best_gguf
+
+    refusal = _run("unsloth/x-GGUF")
+    assert refusal.status == 503
+    repo, variant, _token = hub["started"][0]
+    expected = _extract_quant_label(
+        _pick_best_gguf([s.rfilename for s in _gguf_repo_info().siblings])
+    )
+    assert (repo, variant) == ("unsloth/x-GGUF", expected)
+    assert variant == "UD-Q4_K_XL"
+
+
+def test_missing_quant_lists_the_real_ones(hub):
+    refusal = _run("unsloth/x-GGUF:Q2_K")
+    assert refusal.status == 404 and refusal.code == "model_not_found"
+    assert "UD-Q4_K_XL" in refusal.message and "Q8_0" in refusal.message
+    assert hub["started"] == []
+
+
+def test_missing_repo_is_404_without_confirming_existence(hub):
+    from huggingface_hub.utils import RepositoryNotFoundError
+
+    hub["raise"] = RepositoryNotFoundError("nope")
+    refusal = _run("unsloth/not-real")
+    assert refusal.status == 404 and refusal.code == "model_not_found"
+    assert "not accessible" in refusal.message
+    assert hub["started"] == []
+
+
+def test_gated_repo_is_403(hub):
+    from huggingface_hub.utils import GatedRepoError
+
+    hub["raise"] = GatedRepoError("gated")
+    refusal = _run("meta-llama/Llama-2-7b-hf")
+    assert refusal.status == 403 and refusal.code == "model_access_denied"
+    assert hub["started"] == []
+
+
+def test_hub_unreachable_is_retryable(hub):
+    hub["raise"] = OSError("network down")
+    refusal = _run("unsloth/x-GGUF")
+    assert refusal.status == 503 and refusal.code == "model_lookup_failed"
+    assert refusal.retry_after
+    assert hub["started"] == []
+
+
+def test_non_gguf_repo_is_refused(hub):
+    hub["info"] = _Info([_Sibling("model.safetensors", 100), _Sibling("config.json", 10)])
+    refusal = _run("unsloth/plain-transformers")
+    assert refusal.status == 400 and refusal.code == "model_not_supported"
+    assert hub["started"] == []
+
+
+def test_remote_code_repo_is_refused(hub):
+    hub["auto_map"] = True
+    refusal = _run("someone/custom-arch-GGUF")
+    assert refusal.status == 403 and refusal.code == "remote_code_consent_required"
+    assert "Unsloth Studio" in refusal.message
+    assert hub["started"] == []
+
+
+def test_unreadable_config_fails_closed(hub):
+    # _config_has_auto_map returns None when it cannot tell; refuse rather than
+    # assume the repo is safe.
+    hub["auto_map"] = None
+    refusal = _run("someone/unknown-GGUF")
+    assert refusal.status == 403 and refusal.code == "remote_code_consent_required"
+    assert hub["started"] == []
+
+
+def test_insufficient_disk_never_downgrades_the_quant(hub, monkeypatch):
+    monkeypatch.setattr(auto_dl, "_enough_disk", lambda need: (False, 1024**3))
+    refusal = _run("unsloth/x-GGUF:UD-Q5_K_XL")
+    assert refusal.status == 507 and refusal.code == "insufficient_disk_space"
+    assert hub["started"] == []
+
+
+def test_second_model_waits_for_the_first(hub):
+    assert _run("unsloth/first-GGUF").code == "model_downloading"
+    refusal = _run("unsloth/second-GGUF")
+    assert refusal.status == 503 and refusal.code == "model_download_busy"
+    assert "unsloth/first-GGUF" in refusal.message
+    # Only the first was dispatched.
+    assert len(hub["started"]) == 1
+
+
+def test_repeat_request_reports_progress_without_reprobing(hub, monkeypatch):
+    assert _run("unsloth/x-GGUF:UD-Q5_K_XL").code == "model_downloading"
+
+    async def _running(repo, variant):
+        return "running", None
+
+    async def _pct(repo, variant, expected, token):
+        return 42.0
+
+    monkeypatch.setattr(auto_dl, "_job_state", _running)
+    monkeypatch.setattr(auto_dl, "_progress_percent", _pct)
+    refusal = _run("unsloth/x-GGUF:UD-Q5_K_XL")
+    assert refusal.code == "model_downloading" and "42%" in refusal.message
+    assert len(hub["started"]) == 1
+
+
+def test_progress_is_scaled_to_a_percentage(monkeypatch):
+    # The hub service reports a 0-1 fraction; a raw 0.492 would render as "0%".
+    from hub.services.models import downloads
+
+    async def _fraction(
+        repo_id,
+        variant = "",
+        expected_bytes = 0,
+        hf_token = None,
+    ):
+        return {"progress": 0.492}
+
+    monkeypatch.setattr(downloads, "get_gguf_download_progress_response", _fraction)
+    percent = asyncio.run(auto_dl._progress_percent("org/repo", "Q4_K_M", 0, None))
+    assert percent == pytest.approx(49.2)
+
+
+def test_failed_job_surfaces_once_then_frees_the_slot(hub, monkeypatch):
+    assert _run("unsloth/x-GGUF").code == "model_downloading"
+
+    async def _errored(repo, variant):
+        return "error", "disk exploded"
+
+    monkeypatch.setattr(auto_dl, "_job_state", _errored)
+    refusal = _run("unsloth/x-GGUF")
+    assert refusal.status == 502 and "disk exploded" in refusal.message
+    # Slot released, so a different model can now start.
+    assert _run("unsloth/other-GGUF").code == "model_downloading"
+
+
+def test_hf_token_is_passed_to_the_worker(hub):
+    _run("unsloth/x-GGUF", hf_token = "hf_secret")
+    assert hub["started"][0][2] == "hf_secret"
+
+
+# --- route wiring ------------------------------------------------------------
+
+
+class _Url:
+    def __init__(self, path):
+        self.path = path
+
+
+class _Req:
+    def __init__(
+        self,
+        path = "/v1/chat/completions",
+        headers = None,
+    ):
+        self.url = _Url(path)
+        self.headers = headers or {}
+
+
+def _hook(model, request, enabled):
+    import utils.openai_auto_switch_settings as s
+
+    original = s.get_openai_auto_download_enabled
+    s.get_openai_auto_download_enabled = lambda: enabled
+    try:
+        return asyncio.run(inference_route._maybe_auto_download_model(model, request))
+    finally:
+        s.get_openai_auto_download_enabled = original
+
+
+def test_setting_off_does_nothing_at_all(hub):
+    # The compatibility invariant: no probe, no dispatch, no raise.
+    assert _hook("unsloth/x-GGUF:UD-Q5_K_XL", _Req(), enabled = False) is None
+    assert hub["started"] == []
+
+
+def test_hook_raises_the_openai_envelope_with_retry_after(hub):
+    from fastapi import HTTPException
+
+    with pytest.raises(HTTPException) as excinfo:
+        _hook("unsloth/x-GGUF:UD-Q5_K_XL", _Req(), enabled = True)
+    exc = excinfo.value
+    assert exc.status_code == 503
+    assert exc.headers and exc.headers["Retry-After"]
+    assert exc.detail["error"]["code"] == "model_downloading"
+    assert exc.detail["error"]["param"] == "model"
+    assert exc.detail["error"]["type"] == "api_error"
+
+
+def test_hook_uses_the_anthropic_envelope_on_messages(hub):
+    from fastapi import HTTPException
+
+    with pytest.raises(HTTPException) as excinfo:
+        _hook("unsloth/x-GGUF", _Req(path = "/v1/messages"), enabled = True)
+    detail = excinfo.value.detail
+    assert detail["type"] == "error"
+    assert detail["error"]["type"] == "api_error"
+
+
+def test_hook_swallows_unexpected_failures(hub, monkeypatch):
+    # A broken download path must not turn a servable request into a 500.
+    async def _boom(model, hf_token = None):
+        raise RuntimeError("boom")
+
+    monkeypatch.setattr(auto_dl, "maybe_auto_download", _boom)
+    assert _hook("unsloth/x-GGUF", _Req(), enabled = True) is None
+
+
+def test_hook_prefers_the_hub_header_token(hub):
+    from fastapi import HTTPException
+    from hub.dependencies import HUB_HF_TOKEN_HEADER
+
+    with pytest.raises(HTTPException):
+        _hook(
+            "unsloth/x-GGUF",
+            _Req(headers = {HUB_HF_TOKEN_HEADER: "hf_from_header"}),
+            enabled = True,
+        )
+    assert hub["started"][0][2] == "hf_from_header"
+
+
+# --- settings ----------------------------------------------------------------
+
+
+def test_auto_download_defaults_off_and_is_gated_on_auto_switch(monkeypatch):
+    store = {}
+    monkeypatch.setattr(settings, "_cached_setting", lambda k, d = None: store.get(k, d))
+    assert settings.get_stored_openai_auto_download_enabled() is False
+    assert settings.get_openai_auto_download_enabled() is False
+
+    store[settings.OPENAI_AUTO_DOWNLOAD_SETTING_KEY] = True
+    # Stored on, but auto-switch off: nothing would load the result, so it is off.
+    assert settings.get_stored_openai_auto_download_enabled() is True
+    assert settings.get_openai_auto_download_enabled() is False
+
+    store[settings.OPENAI_AUTO_SWITCH_SETTING_KEY] = True
+    assert settings.get_openai_auto_download_enabled() is True
+
+
+def test_setter_round_trips_auto_download_in_one_transaction(monkeypatch):
+    import storage.studio_db as db
+
+    calls = []
+    store = {}
+
+    def _upsert(mapping):
+        calls.append(dict(mapping))
+        store.update(mapping)
+
+    monkeypatch.setattr(db, "upsert_app_settings", _upsert)
+    monkeypatch.setattr(settings, "_cached_setting", lambda k, d = None: store.get(k, d))
+
+    result = settings.set_openai_auto_switch(True, 120, None, True)
+    assert result == (True, 120, True, True)
+    assert len(calls) == 1
+    assert calls[0][settings.OPENAI_AUTO_DOWNLOAD_SETTING_KEY] is True
+
+
+def test_setter_rejects_a_non_boolean_auto_download(monkeypatch):
+    monkeypatch.setattr(settings, "_cached_setting", lambda k, d = None: None)
+    with pytest.raises(ValueError, match = "true or false"):
+        settings.set_openai_auto_switch(True, None, None, "garbage")
+
+
+def test_settings_route_exposes_auto_download(monkeypatch):
+    import routes.settings as settings_route
+
+    monkeypatch.setattr(settings_route, "get_openai_auto_switch_enabled", lambda: True)
+    monkeypatch.setattr(settings_route, "get_stored_auto_unload_idle_seconds", lambda: 0)
+    monkeypatch.setattr(settings_route, "get_auto_unload_idle_seconds", lambda: 0)
+    monkeypatch.setattr(settings_route, "get_auto_unload_keep_kv", lambda: True)
+    monkeypatch.setattr(settings_route, "get_stored_openai_auto_download_enabled", lambda: True)
+    assert settings_route.get_openai_auto_switch("tester").auto_download_model is True
+
+
+# --- the placeholder API key -------------------------------------------------
+
+
+def test_placeholder_api_key_gets_a_specific_message():
+    from auth.authentication import API_KEY_PLACEHOLDER, _invalid_api_key_detail
+
+    detail = _invalid_api_key_detail(API_KEY_PLACEHOLDER)
+    assert "placeholder" in detail
+    assert "Settings > API" in detail
+
+
+def test_every_other_bad_key_stays_indistinguishable():
+    from auth.authentication import _invalid_api_key_detail
+
+    generic = "Invalid or expired API key"
+    assert _invalid_api_key_detail("sk-unsloth-revoked") == generic
+    assert _invalid_api_key_detail("sk-unsloth-YOUR_KEY ") == generic
+    assert _invalid_api_key_detail("sk-unsloth-your_key") == generic
diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index a3c96ec23c5..36c369a314f 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -289,9 +289,9 @@ def test_openai_compat_routes_bound_to_handlers_with_auth():
     for key, handler in expected.items():
         assert key in seen, f"route {key} is not registered"
         route = seen[key]
-        assert (
-            route.endpoint.__name__ == handler
-        ), f"{key} bound to {route.endpoint.__name__}, expected {handler}"
+        assert route.endpoint.__name__ == handler, (
+            f"{key} bound to {route.endpoint.__name__}, expected {handler}"
+        )
         deps = [d.call.__name__ for d in route.dependant.dependencies]
         assert "get_current_subject" in deps, f"{key} lost its auth dependency"
 
@@ -578,7 +578,9 @@ def test_disabling_idle_unload_purges_saved_kv(monkeypatch, tmp_path):
         "dir": str(tmp_path),
         "slots": [{"id": 0, "filename": saved.name}],
     }
-    monkeypatch.setattr(settings_route, "set_openai_auto_switch", lambda *a: (False, 300, True))
+    monkeypatch.setattr(
+        settings_route, "set_openai_auto_switch", lambda *a: (False, 300, True, False)
+    )
     monkeypatch.setattr(settings_route, "get_auto_unload_idle_seconds", lambda: 0)
 
     payload = settings_route.OpenAIAutoSwitchPayload(enabled = False)
@@ -3954,10 +3956,11 @@ def test_keep_kv_only_update_leaves_env_idle_ttl_active(monkeypatch):
     monkeypatch.setenv(settings.MODEL_IDLE_TTL_ENV_VAR, "600")
 
     assert settings_route.OpenAIAutoSwitchPayload(enabled = False).auto_unload_idle_seconds is None
-    enabled, idle, keep_kv = settings.set_openai_auto_switch(False, None, False)
+    enabled, idle, keep_kv, auto_dl = settings.set_openai_auto_switch(False, None, False)
     assert settings.AUTO_UNLOAD_IDLE_SETTING_KEY not in store  # idle untouched
+    assert settings.OPENAI_AUTO_DOWNLOAD_SETTING_KEY not in store  # nor auto-download
     assert settings.get_auto_unload_idle_seconds() == 600  # env TTL still active
-    assert (enabled, idle, keep_kv) == (False, 600, False)
+    assert (enabled, idle, keep_kv, auto_dl) == (False, 600, False, False)
 
 
 def test_load_impl_notes_loaded_with_backend_off_loop():
diff --git a/studio/backend/utils/openai_auto_switch_settings.py b/studio/backend/utils/openai_auto_switch_settings.py
index 7007440f4c8..a112391edc4 100644
--- a/studio/backend/utils/openai_auto_switch_settings.py
+++ b/studio/backend/utils/openai_auto_switch_settings.py
@@ -3,10 +3,14 @@
 
 """Persisted opt-in controls for OpenAI-compatible model auto-switching.
 
-Two settings, both off by default so existing API behavior is unchanged:
+All off by default so existing API behavior is unchanged:
 - ``openai_api_auto_switch_model``: when on, a ``/v1`` request whose ``model``
   names a downloaded local GGUF different from the loaded one transparently
   loads it before serving (llama-swap-style). Unknown names pass through.
+- ``openai_api_auto_download_model``: when on (and auto-switch is too), a
+  ``/v1`` request naming a GGUF repo that is *not* downloaded starts a
+  background download instead of failing. Gated on auto-switch, which is what
+  serves the model once it lands.
 - ``openai_api_auto_unload_idle_seconds``: when > 0, the loaded GGUF is
   unloaded after this many idle seconds to free VRAM. Enabled values have a
   60s floor (0 stays "off"): a tiny TTL tears the model down between turns of
@@ -29,12 +33,14 @@
 from typing import Any, Optional
 
 OPENAI_AUTO_SWITCH_SETTING_KEY = "openai_api_auto_switch_model"
+OPENAI_AUTO_DOWNLOAD_SETTING_KEY = "openai_api_auto_download_model"
 AUTO_UNLOAD_IDLE_SETTING_KEY = "openai_api_auto_unload_idle_seconds"
 AUTO_UNLOAD_KEEP_KV_SETTING_KEY = "openai_api_auto_unload_keep_kv"
 MODEL_OVERRIDES_SETTING_KEY = "openai_api_auto_switch_overrides"
 MODEL_IDLE_TTL_ENV_VAR = "UNSLOTH_MODEL_IDLE_TTL"
 
 DEFAULT_OPENAI_AUTO_SWITCH_ENABLED = False
+DEFAULT_OPENAI_AUTO_DOWNLOAD_ENABLED = False
 DEFAULT_AUTO_UNLOAD_IDLE_SECONDS = 0
 DEFAULT_AUTO_UNLOAD_KEEP_KV = True
 MIN_AUTO_UNLOAD_IDLE_SECONDS = 60
@@ -95,6 +101,25 @@ def get_openai_auto_switch_enabled() -> bool:
     return parsed if parsed is not None else DEFAULT_OPENAI_AUTO_SWITCH_ENABLED
 
 
+def get_stored_openai_auto_download_enabled() -> bool:
+    """The persisted auto-download flag, independent of auto-switch.
+
+    The settings UI reads this so toggling auto-switch off displays and
+    round-trips the saved value rather than erasing it.
+    """
+    parsed = _coerce_bool(_cached_setting(OPENAI_AUTO_DOWNLOAD_SETTING_KEY, None))
+    return parsed if parsed is not None else DEFAULT_OPENAI_AUTO_DOWNLOAD_ENABLED
+
+
+def get_openai_auto_download_enabled() -> bool:
+    """Whether a /v1 request may download a GGUF repo it names but doesn't have.
+
+    Gated on auto-switch: auto-switch is what loads the model once it lands, so
+    downloading without it would fetch gigabytes nothing can then serve.
+    """
+    return get_stored_openai_auto_download_enabled() and get_openai_auto_switch_enabled()
+
+
 def _stored_idle_seconds() -> Optional[int]:
     """The persisted idle TTL as an int, or None when never set."""
     return _coerce_int(_cached_setting(AUTO_UNLOAD_IDLE_SETTING_KEY, None))
@@ -170,7 +195,8 @@ def set_openai_auto_switch(
     enabled: Any,
     idle_seconds: Any,
     keep_kv: Any = None,
-) -> tuple[bool, int, bool]:
+    auto_download: Any = None,
+) -> tuple[bool, int, bool, bool]:
     """One-transaction write; ``None`` leaves a stored value untouched."""
     parsed_enabled = _coerce_bool(enabled)
     if parsed_enabled is None:
@@ -190,6 +216,11 @@ def set_openai_auto_switch(
         parsed_keep_kv = _coerce_bool(keep_kv)
         if parsed_keep_kv is None:
             raise ValueError("Keep KV on idle unload must be true or false.")
+    parsed_auto_download = None
+    if auto_download is not None:
+        parsed_auto_download = _coerce_bool(auto_download)
+        if parsed_auto_download is None:
+            raise ValueError("Auto-download missing models must be true or false.")
     from storage.studio_db import upsert_app_settings
 
     updates: dict[str, Any] = {OPENAI_AUTO_SWITCH_SETTING_KEY: parsed_enabled}
@@ -197,16 +228,25 @@ def set_openai_auto_switch(
         updates[AUTO_UNLOAD_IDLE_SETTING_KEY] = parsed_idle
     if parsed_keep_kv is not None:
         updates[AUTO_UNLOAD_KEEP_KV_SETTING_KEY] = parsed_keep_kv
+    if parsed_auto_download is not None:
+        updates[OPENAI_AUTO_DOWNLOAD_SETTING_KEY] = parsed_auto_download
     upsert_app_settings(updates)
     _invalidate(OPENAI_AUTO_SWITCH_SETTING_KEY)
     if parsed_idle is not None:
         _invalidate(AUTO_UNLOAD_IDLE_SETTING_KEY)
     if parsed_keep_kv is not None:
         _invalidate(AUTO_UNLOAD_KEEP_KV_SETTING_KEY)
+    if parsed_auto_download is not None:
+        _invalidate(OPENAI_AUTO_DOWNLOAD_SETTING_KEY)
     return (
         parsed_enabled,
         parsed_idle if parsed_idle is not None else get_stored_auto_unload_idle_seconds(),
         parsed_keep_kv if parsed_keep_kv is not None else get_auto_unload_keep_kv(),
+        (
+            parsed_auto_download
+            if parsed_auto_download is not None
+            else get_stored_openai_auto_download_enabled()
+        ),
     )
 
 
diff --git a/studio/frontend/src/features/chat/types/api.ts b/studio/frontend/src/features/chat/types/api.ts
index 7f50fcfdaf4..94b06282cda 100644
--- a/studio/frontend/src/features/chat/types/api.ts
+++ b/studio/frontend/src/features/chat/types/api.ts
@@ -283,11 +283,13 @@ export interface ApiMonitorEntry {
   completion_tokens?: number | null;
   total_tokens?: number | null;
   error?: string | null;
-  // "request" is an HTTP call; "lifecycle" is a model load/unload, which carries
-  // event/reason instead of a prompt and has no detail to fetch.
+  // "request" is an HTTP call; "lifecycle" is a model load/unload/download, which
+  // carries event/reason instead of a prompt and has no detail to fetch.
   kind?: "request" | "lifecycle";
-  event?: "load" | "unload" | null;
-  reason?: "manual" | "idle" | null;
+  event?: "load" | "unload" | "download" | null;
+  reason?: "manual" | "idle" | "api" | null;
+  // 0-100 while a download row is running.
+  progress?: number | null;
 }
 
 export interface ApiMonitorResponse {
diff --git a/studio/frontend/src/features/settings/api/openai-auto-switch.ts b/studio/frontend/src/features/settings/api/openai-auto-switch.ts
index 47bad56eabf..c5a272f7d65 100644
--- a/studio/frontend/src/features/settings/api/openai-auto-switch.ts
+++ b/studio/frontend/src/features/settings/api/openai-auto-switch.ts
@@ -13,6 +13,9 @@ export type OpenAIAutoSwitchSettings = {
   idleUnloadActive: boolean;
   // Persist the KV cache to disk on idle unload and restore it on reload.
   autoUnloadKeepKv: boolean;
+  // Fetch a GGUF named in an API request that isn't downloaded yet. Stored
+  // independently, but only takes effect while `enabled` is on.
+  autoDownloadModel: boolean;
 };
 
 type ApiOpenAIAutoSwitchSettings = {
@@ -25,6 +28,8 @@ type ApiOpenAIAutoSwitchSettings = {
   idle_unload_active?: boolean;
   // biome-ignore lint/style/useNamingConvention: API schema
   auto_unload_keep_kv?: boolean;
+  // biome-ignore lint/style/useNamingConvention: API schema
+  auto_download_model?: boolean;
 };
 
 let cachedSettings: OpenAIAutoSwitchSettings | null = null;
@@ -39,6 +44,7 @@ function fromApi(
     defaultEnabled: settings.default_enabled,
     idleUnloadActive: settings.idle_unload_active ?? false,
     autoUnloadKeepKv: settings.auto_unload_keep_kv ?? true,
+    autoDownloadModel: settings.auto_download_model ?? false,
   };
 }
 
@@ -73,6 +79,7 @@ export async function updateOpenAIAutoSwitchSettings(
   enabled: boolean,
   autoUnloadIdleSeconds?: number,
   autoUnloadKeepKv?: boolean,
+  autoDownloadModel?: boolean,
 ): Promise<OpenAIAutoSwitchSettings> {
   const res = await authFetch("/api/settings/openai-auto-switch", {
     method: "PUT",
@@ -88,6 +95,10 @@ export async function updateOpenAIAutoSwitchSettings(
         ? {}
         : // biome-ignore lint/style/useNamingConvention: API schema
           { auto_unload_keep_kv: autoUnloadKeepKv }),
+      ...(autoDownloadModel === undefined
+        ? {}
+        : // biome-ignore lint/style/useNamingConvention: API schema
+          { auto_download_model: autoDownloadModel }),
     }),
   });
   if (!res.ok) {
diff --git a/studio/frontend/src/features/settings/components/api-monitor-console.tsx b/studio/frontend/src/features/settings/components/api-monitor-console.tsx
index 41cd504f47f..03ab95bdd62 100644
--- a/studio/frontend/src/features/settings/components/api-monitor-console.tsx
+++ b/studio/frontend/src/features/settings/components/api-monitor-console.tsx
@@ -96,6 +96,17 @@ function lifecycleLabel(entry: ApiMonitorEntry): string {
   if (entry.event === "unload") {
     return entry.reason === "idle" ? "Model unloaded (idle)" : "Model unloaded";
   }
+  if (entry.event === "download") {
+    if (entry.status === "running") {
+      const pct = entry.progress;
+      return typeof pct === "number"
+        ? `Downloading model (${Math.round(pct)}%)`
+        : "Downloading model";
+    }
+    return entry.status === "completed"
+      ? "Model downloaded"
+      : "Model download failed";
+  }
   if (entry.status === "running") {
     return "Loading model";
   }
@@ -126,7 +137,7 @@ function LifecycleEntry({ entry }: { entry: ApiMonitorEntry }): ReactElement {
         </div>
         <div className="shrink-0 text-right text-ui-11 text-muted-foreground">
           <div>{formatTime(entry.started_at)}</div>
-          {entry.event === "load" ? (
+          {entry.event === "load" || entry.event === "download" ? (
             <div>{formatDuration(entry.duration_ms)}</div>
           ) : null}
         </div>
diff --git a/studio/frontend/src/features/settings/components/model-auto-switch-section.tsx b/studio/frontend/src/features/settings/components/model-auto-switch-section.tsx
index aa6857cff53..6ebd12ce3c0 100644
--- a/studio/frontend/src/features/settings/components/model-auto-switch-section.tsx
+++ b/studio/frontend/src/features/settings/components/model-auto-switch-section.tsx
@@ -65,6 +65,7 @@ export function ModelAutoSwitchSection() {
     idleSeconds: number | undefined,
     syncDraft = true,
     keepKv?: boolean,
+    autoDownload?: boolean,
   ) => {
     setIsSaving(true);
     setError(null);
@@ -73,6 +74,7 @@ export function ModelAutoSwitchSection() {
         enabled,
         idleSeconds,
         keepKv,
+        autoDownload,
       );
       setSettings(saved);
       if (syncDraft) {
@@ -117,6 +119,11 @@ export function ModelAutoSwitchSection() {
     void persist(settings.enabled, undefined, false, keepKv);
   };
 
+  const handleAutoDownloadToggle = (autoDownload: boolean) => {
+    if (!settings) return;
+    void persist(settings.enabled, undefined, false, undefined, autoDownload);
+  };
+
   return (
     <SettingsSection title={t("settings.general.modelAutoSwitch.sectionTitle")}>
       <SettingsRow
@@ -129,6 +136,18 @@ export function ModelAutoSwitchSection() {
           onCheckedChange={handleToggle}
         />
       </SettingsRow>
+      <SettingsRow
+        label={t("settings.general.modelAutoSwitch.autoDownload")}
+        description={t(
+          "settings.general.modelAutoSwitch.autoDownloadDescription",
+        )}
+      >
+        <Switch
+          checked={settings?.autoDownloadModel ?? false}
+          disabled={!settings?.enabled || isSaving}
+          onCheckedChange={handleAutoDownloadToggle}
+        />
+      </SettingsRow>
       <SettingsRow
         label={t("settings.general.modelAutoSwitch.idleUnload")}
         description={t(
diff --git a/studio/frontend/src/i18n/locales/en.ts b/studio/frontend/src/i18n/locales/en.ts
index 1b7a11213fa..bda564e4d7e 100644
--- a/studio/frontend/src/i18n/locales/en.ts
+++ b/studio/frontend/src/i18n/locales/en.ts
@@ -283,6 +283,9 @@ export const en = {
         enable: "Switch model by request",
         enableDescription:
           "Load a downloaded GGUF named in an API request before serving. Off by default.",
+        autoDownload: "Download missing models",
+        autoDownloadDescription:
+          "Fetch a GGUF named in an API request that is not downloaded yet. Anyone with an API key can then use disk and bandwidth.",
         idleUnload: "Idle auto-unload",
         idleUnloadDescription:
           "Free VRAM after this many idle seconds. 0 keeps it loaded, minimum 60.",
diff --git a/tests/studio/test_usage_examples_model_source_contract.py b/tests/studio/test_usage_examples_model_source_contract.py
index 8e355de3a19..34c645c3351 100644
--- a/tests/studio/test_usage_examples_model_source_contract.py
+++ b/tests/studio/test_usage_examples_model_source_contract.py
@@ -78,3 +78,32 @@ def test_auto_switch_section_sits_above_the_monitor():
     tab = API_KEYS_TAB_TSX.read_text(encoding = "utf-8")
     assert tab.index("<ModelAutoSwitchSection />") < tab.index("<ApiMonitorConsole />")
     assert tab.index("<ApiMonitorConsole />") < tab.index("<UsageExamples")
+
+
+AUTO_SWITCH_TSX = SETTINGS / "components/model-auto-switch-section.tsx"
+EN_TS = REPO / "studio/frontend/src/i18n/locales/en.ts"
+
+
+def test_api_monitor_renders_download_rows():
+    src = API_MONITOR_TSX.read_text(encoding = "utf-8")
+    assert 'entry.event === "download"' in src
+    for label in ("Downloading model", "Model downloaded", "Model download failed"):
+        assert label in src
+
+
+def test_auto_download_toggle_is_gated_on_auto_switch():
+    # Downloading a model auto-switch is not allowed to load would fetch
+    # gigabytes nothing can then serve, so the row follows the enabled flag.
+    src = AUTO_SWITCH_TSX.read_text(encoding = "utf-8")
+    assert "modelAutoSwitch.autoDownload" in src
+    assert "settings?.autoDownloadModel ?? false" in src
+    row = src[src.find("modelAutoSwitch.autoDownload") :]
+    assert "disabled={!settings?.enabled || isSaving}" in row[: row.find("</SettingsRow>")]
+
+
+def test_auto_download_copy_warns_about_api_key_holders():
+    en = EN_TS.read_text(encoding = "utf-8")
+    start = en.find("autoDownloadDescription:")
+    assert start != -1
+    description = en[start : en.find("\n", en.find('",', start))]
+    assert "API key" in description

From d61ca7b08f0fefd3ce75776cf2b2d6b5ee3689d2 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Sun, 26 Jul 2026 09:54:45 +0000
Subject: [PATCH 06/56] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 studio/backend/tests/test_openai_auto_switch.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index 36c369a314f..0049f0f97c7 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -289,9 +289,9 @@ def test_openai_compat_routes_bound_to_handlers_with_auth():
     for key, handler in expected.items():
         assert key in seen, f"route {key} is not registered"
         route = seen[key]
-        assert route.endpoint.__name__ == handler, (
-            f"{key} bound to {route.endpoint.__name__}, expected {handler}"
-        )
+        assert (
+            route.endpoint.__name__ == handler
+        ), f"{key} bound to {route.endpoint.__name__}, expected {handler}"
         deps = [d.call.__name__ for d in route.dependant.dependencies]
         assert "get_current_subject" in deps, f"{key} lost its auth dependency"
 

From 658f106fc2f8d18a3172fb3d20db14ece3dbd6ed Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Sun, 26 Jul 2026 10:18:28 +0000
Subject: [PATCH 07/56] Studio: add an Unload button to the API monitor

The monitor names the loaded model but offered no way to free it. Idle
auto-unload is the only existing release path, and it needs a TTL and a
wait.

The button sits next to Refresh, appears only while a model is loaded and
is disabled mid-unload. /unload matches on the internal identifier, which
this response deliberately omits because it would be a host path, so the
click reads it from /api/inference/status the same way the chat runtime
does rather than widening the monitor payload.

Also stamp the manual unload row with the quant, read before the teardown
clears it, so it reads repo:QUANT like the load row it pairs with.
---
 studio/backend/routes/inference.py            |  6 ++-
 .../components/api-monitor-console.tsx        | 46 ++++++++++++++++++-
 ...st_usage_examples_model_source_contract.py | 12 +++++
 3 files changed, 62 insertions(+), 2 deletions(-)

diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 25a157308f4..bfdd3a1e412 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -5831,13 +5831,17 @@ async def unload_model(request: UnloadRequest, current_subject: str = Depends(ge
                 )
                 or not llama_backend.is_loaded
             ):
+                # Read the identity before the teardown clears it, so the row reads
+                # repo:QUANT like the matching load row rather than a bare path.
+                _unloaded = _llama_public_model_id(llama_backend, request.model_path)
+                _unloaded_variant = getattr(llama_backend, "hf_variant", None)
                 # A manual unload is a deliberate user action: tear down now even if a
                 # request is mid-stream (only the automatic idle loop defers to it).
                 llama_backend.unload_model()
                 note_model_unloaded()
                 api_monitor.record_lifecycle(
                     event = "unload",
-                    model = _lifecycle_model_label(request.model_path),
+                    model = _lifecycle_model_label(_unloaded, _unloaded_variant),
                     reason = "manual",
                 )
                 logger.info(f"Unloaded GGUF model: {request.model_path}")
diff --git a/studio/frontend/src/features/settings/components/api-monitor-console.tsx b/studio/frontend/src/features/settings/components/api-monitor-console.tsx
index 03ab95bdd62..0d242e59503 100644
--- a/studio/frontend/src/features/settings/components/api-monitor-console.tsx
+++ b/studio/frontend/src/features/settings/components/api-monitor-console.tsx
@@ -7,6 +7,7 @@ import {
   ActivityIcon,
   ChevronDownIcon,
   CircleIcon,
+  PowerOffIcon,
   RefreshCwIcon,
 } from "lucide-react";
 import {
@@ -17,7 +18,13 @@ import {
   useRef,
   useState,
 } from "react";
-import { getApiMonitor, getApiMonitorEntry } from "../../chat/api/chat-api";
+import {
+  getApiMonitor,
+  getApiMonitorEntry,
+  getInferenceStatus,
+  unloadModel,
+} from "../../chat/api/chat-api";
+import { resolveInferenceCheckpointId } from "../../chat/lib/apply-inference-status-to-store";
 import type { ApiMonitorEntry, ApiMonitorResponse } from "../../chat/types/api";
 
 const API_INFERENCE_PREFIX_RE = /^\/api\/inference/;
@@ -250,6 +257,7 @@ export function ApiMonitorConsole(): ReactElement {
   const [data, setData] = useState<ApiMonitorResponse | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [refreshing, setRefreshing] = useState(false);
+  const [unloading, setUnloading] = useState(false);
   const [expandedIds, setExpandedIds] = useState<Set<string>>(() => new Set());
   const [details, setDetails] = useState<Record<string, ApiMonitorEntry>>({});
   const [loadingDetails, setLoadingDetails] = useState<Set<string>>(
@@ -270,6 +278,29 @@ export function ApiMonitorConsole(): ReactElement {
     }
   }, []);
 
+  // Free the VRAM the loaded model is holding. The monitor only knows the model's
+  // public id, and /unload matches on the internal one, so read that from status
+  // the same way the chat runtime does rather than putting a host path in this
+  // response. With auto-switch on the next API request loads a model again.
+  const unloadActiveModel = useCallback(async (): Promise<void> => {
+    setUnloading(true);
+    try {
+      const status = await getInferenceStatus();
+      const checkpoint = resolveInferenceCheckpointId(status);
+      if (!checkpoint) {
+        setError(null);
+        return;
+      }
+      await unloadModel({ model_path: checkpoint });
+      setError(null);
+      await loadMonitor();
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : "Failed to unload the model");
+    } finally {
+      setUnloading(false);
+    }
+  }, [loadMonitor]);
+
   useEffect(() => {
     let cancelled = false;
     let timer: number | undefined;
@@ -445,6 +476,19 @@ export function ApiMonitorConsole(): ReactElement {
           <div className="rounded-full border border-border px-2.5 py-1 text-xs capitalize text-muted-foreground">
             {statusLabel}
           </div>
+          {data?.active_model ? (
+            <Button
+              type="button"
+              variant="ghost"
+              size="sm"
+              onClick={() => void unloadActiveModel()}
+              disabled={unloading}
+              title="Unload the model and free its VRAM"
+            >
+              <PowerOffIcon className="size-3.5" />
+              {unloading ? "Unloading" : "Unload"}
+            </Button>
+          ) : null}
           <Button
             type="button"
             variant="ghost"
diff --git a/tests/studio/test_usage_examples_model_source_contract.py b/tests/studio/test_usage_examples_model_source_contract.py
index 34c645c3351..a9f122d4216 100644
--- a/tests/studio/test_usage_examples_model_source_contract.py
+++ b/tests/studio/test_usage_examples_model_source_contract.py
@@ -91,6 +91,18 @@ def test_api_monitor_renders_download_rows():
         assert label in src
 
 
+def test_monitor_can_unload_the_loaded_model():
+    src = API_MONITOR_TSX.read_text(encoding = "utf-8")
+    assert "unloadActiveModel" in src
+    # Shown only when something is loaded, and disabled mid-unload.
+    assert "{data?.active_model ? (" in src
+    assert "disabled={unloading}" in src
+    # /unload matches on the internal id, which this response deliberately omits
+    # (it would be a host path), so it must be read from status.
+    assert "resolveInferenceCheckpointId(status)" in src
+    assert "unloadModel({ model_path: checkpoint })" in src
+
+
 def test_auto_download_toggle_is_gated_on_auto_switch():
     # Downloading a model auto-switch is not allowed to load would fetch
     # gigabytes nothing can then serve, so the row follows the enabled flag.

From 0104baa6b6126328261e6dd0dfd5a1ad2058670c Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Sun, 26 Jul 2026 10:36:18 +0000
Subject: [PATCH 08/56] Studio: keep the API monitor Unload button visible when
 idle

It only rendered while a model was loaded, which hid the one manual
release path at exactly the moment someone goes looking for it. Render it
always, disabled with a "No model is loaded" tooltip when there is nothing
to free.
---
 .../components/api-monitor-console.tsx        | 30 +++++++++++--------
 ...st_usage_examples_model_source_contract.py |  7 +++--
 2 files changed, 21 insertions(+), 16 deletions(-)

diff --git a/studio/frontend/src/features/settings/components/api-monitor-console.tsx b/studio/frontend/src/features/settings/components/api-monitor-console.tsx
index 0d242e59503..0f07b4a95b2 100644
--- a/studio/frontend/src/features/settings/components/api-monitor-console.tsx
+++ b/studio/frontend/src/features/settings/components/api-monitor-console.tsx
@@ -476,19 +476,23 @@ export function ApiMonitorConsole(): ReactElement {
           <div className="rounded-full border border-border px-2.5 py-1 text-xs capitalize text-muted-foreground">
             {statusLabel}
           </div>
-          {data?.active_model ? (
-            <Button
-              type="button"
-              variant="ghost"
-              size="sm"
-              onClick={() => void unloadActiveModel()}
-              disabled={unloading}
-              title="Unload the model and free its VRAM"
-            >
-              <PowerOffIcon className="size-3.5" />
-              {unloading ? "Unloading" : "Unload"}
-            </Button>
-          ) : null}
+          {/* Always rendered, disabled when idle: hiding it made the only manual
+              release path invisible exactly when someone goes looking for it. */}
+          <Button
+            type="button"
+            variant="ghost"
+            size="sm"
+            onClick={() => void unloadActiveModel()}
+            disabled={unloading || !data?.active_model}
+            title={
+              data?.active_model
+                ? "Unload the model and free its VRAM"
+                : "No model is loaded"
+            }
+          >
+            <PowerOffIcon className="size-3.5" />
+            {unloading ? "Unloading" : "Unload"}
+          </Button>
           <Button
             type="button"
             variant="ghost"
diff --git a/tests/studio/test_usage_examples_model_source_contract.py b/tests/studio/test_usage_examples_model_source_contract.py
index a9f122d4216..1224b93209a 100644
--- a/tests/studio/test_usage_examples_model_source_contract.py
+++ b/tests/studio/test_usage_examples_model_source_contract.py
@@ -94,9 +94,10 @@ def test_api_monitor_renders_download_rows():
 def test_monitor_can_unload_the_loaded_model():
     src = API_MONITOR_TSX.read_text(encoding = "utf-8")
     assert "unloadActiveModel" in src
-    # Shown only when something is loaded, and disabled mid-unload.
-    assert "{data?.active_model ? (" in src
-    assert "disabled={unloading}" in src
+    # Always rendered, so the manual release path stays discoverable; disabled
+    # when idle or mid-unload rather than hidden.
+    assert "disabled={unloading || !data?.active_model}" in src
+    assert "{data?.active_model ? (" not in src
     # /unload matches on the internal id, which this response deliberately omits
     # (it would be a host path), so it must be read from status.
     assert "resolveInferenceCheckpointId(status)" in src

From 2f7bb5877e30a4e0e6c9a91ba3ffcb5ccd66d26b Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Sun, 26 Jul 2026 11:23:53 +0000
Subject: [PATCH 09/56] Studio: never answer a named model with a different one

Asking for a model this server is not serving returned 200 from whatever
was resident. Requesting gemma-4-E2B-it-GGUF:UD-Q6_K_XL while UD-Q4_K_XL
was loaded got a confident answer from the wrong quant, with nothing in
the response saying so.

A name carrying a namespace (org/model, optionally :QUANT) is a concrete
reference, so 404 instead, with the reason:

- wrong quant  -> names the quants that are actually downloaded
- not on disk  -> lists what is available
- on disk but auto-switch off -> says to turn it on

Ids without a namespace (gpt-4, claude-3, default) are foreign labels
rather than references, so they still fall through to the resident model
and drop-in clients are unaffected. A bare org/model is still satisfied by
any loaded quant of that repo; only an explicit :QUANT must match.

The check runs whatever the auto-switch and auto-download toggles are,
since serving the wrong weights is wrong in every configuration. It is
skipped when nothing is loaded, where the existing no-model-loaded error
already says the right thing, and when the model is on disk with
auto-switch on, where a failed swap should still fall back.
---
 studio/backend/routes/inference.py            |  99 ++++++++++++
 .../tests/test_openai_auto_download.py        | 147 ++++++++++++++++++
 .../backend/tests/test_openai_auto_switch.py  |  28 +++-
 3 files changed, 266 insertions(+), 8 deletions(-)

diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index bfdd3a1e412..941049e20ab 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3756,6 +3756,99 @@ async def _maybe_auto_download_model(
     )
 
 
+def _loaded_satisfies(requested: str) -> bool:
+    """Whether what is serving right now actually answers to *requested*.
+
+    A bare ``org/model`` is satisfied by any loaded quant of that repo; an
+    explicit ``:QUANT`` must match the loaded one.
+    """
+    from core.inference.openai_auto_download import split_model_ref
+
+    base, variant = split_model_ref(requested)
+    base = base.lower()
+    llama_backend = get_llama_cpp_backend()
+    if getattr(llama_backend, "is_loaded", False):
+        keys = {
+            candidate.lower()
+            for candidate in (
+                getattr(llama_backend, "model_identifier", None),
+                getattr(llama_backend, "_openai_advertised_id", None),
+                _llama_public_model_id(llama_backend),
+            )
+            if candidate
+        }
+        if base not in keys:
+            return False
+        if not variant:
+            return True
+        return (getattr(llama_backend, "hf_variant", None) or "").lower() == variant.lower()
+    active = getattr(get_inference_backend(), "active_model_name", None)
+    if not active:
+        return False
+    return base in {active.lower(), (public_model_id(active) or "").lower()}
+
+
+async def _reject_unservable_model(
+    requested_model: Optional[str], fastapi_request: Optional[Request]
+) -> None:
+    """404 rather than answer a named model with a different one.
+
+    ``org/model`` (optionally ``:QUANT``) is a concrete reference: serving it
+    from whatever happens to be resident returns a confident answer from the
+    wrong weights. Ids without a namespace (``gpt-4``) are foreign labels, so
+    they still fall through and drop-in clients are unaffected. Only runs while
+    something is serving; with nothing loaded the caller's own
+    :func:`_no_model_loaded_error` already says the right thing.
+    """
+    from core.inference.openai_auto_download import split_model_ref
+
+    if (
+        not isinstance(requested_model, str)
+        or not requested_model.strip()
+        or requested_model == _RELOAD_ONLY_MODEL
+    ):
+        return
+    base, _variant = split_model_ref(requested_model)
+    if "/" not in base:
+        return
+    try:
+        if _loaded_satisfies(requested_model):
+            return
+        if not (
+            get_llama_cpp_backend().is_loaded
+            or getattr(get_inference_backend(), "active_model_name", None)
+        ):
+            return
+        from core.inference.local_model_resolver import resolve_local_gguf
+        from utils.openai_auto_switch_settings import get_openai_auto_switch_enabled
+
+        downloaded = await asyncio.to_thread(resolve_local_gguf, requested_model) is not None
+        if downloaded and get_openai_auto_switch_enabled():
+            # On disk and switching is allowed, so the swap failed (load error,
+            # race). Serving the resident model is the sane fallback.
+            return
+        message = (
+            f"The model '{requested_model}' is downloaded but not loaded, and "
+            "'Switch model by request' is off, so this server can only serve the "
+            "loaded model. Turn it on in Unsloth Studio under Settings > API."
+            if downloaded
+            else await _unavailable_model_message(requested_model)
+        )
+    except Exception as exc:
+        # A diagnosis failure must never break a request the server can answer.
+        logger.debug("unservable-model check failed for %r: %s", requested_model, exc)
+        return
+    path = getattr(getattr(fastapi_request, "url", None), "path", None)
+    raise HTTPException(
+        status_code = 404,
+        detail = (
+            error_body_for_path(path, message, status = 404, code = "model_not_found", param = "model")
+            if isinstance(path, str)
+            else message
+        ),
+    )
+
+
 async def _maybe_auto_switch_model(
     requested_model: Optional[str],
     fastapi_request: Request,
@@ -3798,6 +3891,9 @@ async def _maybe_auto_switch_model(
     # loop freed is restored on the next request. The resolver-based switch still
     # requires the auto-switch toggle.
     if not auto_switch_on and get_auto_unload_idle_seconds() <= 0:
+        # No switching to do, but a named model still must not be answered by a
+        # different one.
+        await _reject_unservable_model(requested_model, fastapi_request)
         return
 
     async def _resolve_and_switch() -> None:
@@ -3945,6 +4041,9 @@ def _record_serving_alias() -> None:
                 _note_switch_waiter(key, -1)
 
     await _resolve_and_switch()
+    # The switch may have missed (not downloaded, or a swap that failed): refuse
+    # rather than let the handler answer as whatever is still resident.
+    await _reject_unservable_model(requested_model, fastapi_request)
 
 
 async def _auto_switch_from_request_body(request: Request, current_subject: str):
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index 3370dd0c4cb..dfe67db103b 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -12,6 +12,7 @@
 import asyncio
 
 import pytest
+from fastapi import HTTPException
 
 import routes.inference as inference_route
 from core.inference import openai_auto_download as auto_dl
@@ -396,6 +397,152 @@ def test_hook_prefers_the_hub_header_token(hub):
     assert hub["started"][0][2] == "hf_from_header"
 
 
+# --- never answer as a different model ----------------------------------------
+
+
+class _Loaded:
+    """Minimal stand-in for the GGUF backend with one model resident."""
+
+    def __init__(
+        self,
+        identifier,
+        variant = None,
+        advertised = None,
+    ):
+        self.is_loaded = True
+        self.model_identifier = identifier
+        self.hf_variant = variant
+        self._openai_advertised_id = advertised
+
+
+def _reject(
+    model,
+    loaded,
+    monkeypatch,
+    *,
+    downloaded = False,
+    auto_switch = False,
+):
+    monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+    monkeypatch.setattr(
+        inference_route,
+        "get_inference_backend",
+        lambda: type("B", (), {"active_model_name": None})(),
+    )
+    monkeypatch.setattr(
+        "core.inference.local_model_resolver.resolve_local_gguf",
+        lambda name: ("/p", None, name) if downloaded else None,
+    )
+    monkeypatch.setattr(
+        "utils.openai_auto_switch_settings.get_openai_auto_switch_enabled",
+        lambda: auto_switch,
+    )
+    monkeypatch.setattr(inference_route, "_unavailable_model_message", _fake_unavailable_message)
+    return asyncio.run(inference_route._reject_unservable_model(model, _Req()))
+
+
+async def _fake_unavailable_message(model):
+    return f"The model '{model}' is not downloaded on this server."
+
+
+def test_wrong_quant_is_not_answered_by_the_loaded_one(monkeypatch):
+    # The reported bug: asking for UD-Q6_K_XL while UD-Q4_K_XL is resident used to
+    # return 200 from the wrong weights.
+    loaded = _Loaded("unsloth/gemma-4-E2B-it-GGUF", "UD-Q4_K_XL")
+    with pytest.raises(HTTPException) as excinfo:
+        _reject("unsloth/gemma-4-E2B-it-GGUF:UD-Q6_K_XL", loaded, monkeypatch)
+    assert excinfo.value.status_code == 404
+
+
+def test_bare_repo_id_is_satisfied_by_any_loaded_quant(monkeypatch):
+    # No quant named means "this model", so the resident quant answers it.
+    loaded = _Loaded("unsloth/gemma-4-E2B-it-GGUF", "UD-Q4_K_XL")
+    assert _reject("unsloth/gemma-4-E2B-it-GGUF", loaded, monkeypatch) is None
+
+
+def test_matching_quant_is_served(monkeypatch):
+    loaded = _Loaded("unsloth/gemma-4-E2B-it-GGUF", "UD-Q4_K_XL")
+    assert _reject("unsloth/gemma-4-E2B-it-GGUF:ud-q4_k_xl", loaded, monkeypatch) is None
+
+
+def test_advertised_alias_counts_as_serving(monkeypatch):
+    # Loaded by path, requested by the repo id auto-switch advertised for it.
+    loaded = _Loaded("/cache/snap/abc", "UD-Q4_K_XL", "unsloth/gemma-4-E2B-it-GGUF")
+    assert _reject("unsloth/gemma-4-E2B-it-GGUF", loaded, monkeypatch) is None
+
+
+@pytest.mark.parametrize("foreign", ["gpt-4", "gpt-4o-mini", "claude-3-5-sonnet", "default"])
+def test_foreign_ids_still_fall_through(monkeypatch, foreign):
+    # Drop-in compatibility: an id with no namespace is a label, not a reference.
+    loaded = _Loaded("unsloth/gemma-4-E2B-it-GGUF", "UD-Q4_K_XL")
+    assert _reject(foreign, loaded, monkeypatch) is None
+
+
+def test_downloaded_but_auto_switch_off_says_so(monkeypatch):
+    loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
+    with pytest.raises(HTTPException) as excinfo:
+        _reject("unsloth/B-GGUF", loaded, monkeypatch, downloaded = True)
+    assert "Switch model by request" in str(excinfo.value.detail)
+
+
+def test_downloaded_with_auto_switch_on_falls_through(monkeypatch):
+    # On disk and switching allowed means the swap failed; the resident model is
+    # the sane fallback rather than a hard error.
+    loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
+    assert _reject("unsloth/B-GGUF", loaded, monkeypatch, downloaded = True, auto_switch = True) is None
+
+
+def test_nothing_loaded_leaves_the_existing_error_alone(monkeypatch):
+    # With no model resident the handler's own no-model-loaded error is already
+    # correct, so this check must not preempt it.
+    idle = type("B", (), {"is_loaded": False, "model_identifier": None, "hf_variant": None})()
+    monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: idle)
+    monkeypatch.setattr(
+        inference_route,
+        "get_inference_backend",
+        lambda: type("B", (), {"active_model_name": None})(),
+    )
+    assert asyncio.run(inference_route._reject_unservable_model("unsloth/B-GGUF", _Req())) is None
+
+
+def test_reload_only_sentinel_is_ignored(monkeypatch):
+    loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
+    assert _reject(inference_route._RELOAD_ONLY_MODEL, loaded, monkeypatch) is None
+
+
+def test_diagnosis_failure_never_breaks_a_servable_request(monkeypatch):
+    loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
+
+    def _boom(_name):
+        raise RuntimeError("scan exploded")
+
+    monkeypatch.setattr("core.inference.local_model_resolver.resolve_local_gguf", _boom)
+    monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+    monkeypatch.setattr(
+        inference_route,
+        "get_inference_backend",
+        lambda: type("B", (), {"active_model_name": None})(),
+    )
+    assert asyncio.run(inference_route._reject_unservable_model("unsloth/B-GGUF", _Req())) is None
+
+
+def test_anthropic_surface_gets_its_own_envelope(monkeypatch):
+    loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
+    monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+    monkeypatch.setattr(
+        inference_route,
+        "get_inference_backend",
+        lambda: type("B", (), {"active_model_name": None})(),
+    )
+    monkeypatch.setattr("core.inference.local_model_resolver.resolve_local_gguf", lambda name: None)
+    monkeypatch.setattr(inference_route, "_unavailable_model_message", _fake_unavailable_message)
+    with pytest.raises(HTTPException) as excinfo:
+        asyncio.run(
+            inference_route._reject_unservable_model("unsloth/B-GGUF", _Req(path = "/v1/messages"))
+        )
+    assert excinfo.value.detail["type"] == "error"
+
+
 # --- settings ----------------------------------------------------------------
 
 
diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index 0049f0f97c7..abafff8269f 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -11,6 +11,7 @@
 import os
 
 import pytest
+from fastapi import HTTPException
 
 import routes.inference as inference_route
 from models.inference import LoadRequest
@@ -116,7 +117,11 @@ def test_flag_off_never_loads(monkeypatch):
         backend = backend,
         recorder = rec,
     )
-    _run_hook("unsloth/B-GGUF")
+    # Off means no load, but A must not answer as B either: say why instead.
+    with pytest.raises(HTTPException) as excinfo:
+        _run_hook("unsloth/B-GGUF")
+    assert excinfo.value.status_code == 404
+    assert "Switch model by request" in str(excinfo.value.detail)
     assert rec.calls == []
 
 
@@ -289,9 +294,9 @@ def test_openai_compat_routes_bound_to_handlers_with_auth():
     for key, handler in expected.items():
         assert key in seen, f"route {key} is not registered"
         route = seen[key]
-        assert (
-            route.endpoint.__name__ == handler
-        ), f"{key} bound to {route.endpoint.__name__}, expected {handler}"
+        assert route.endpoint.__name__ == handler, (
+            f"{key} bound to {route.endpoint.__name__}, expected {handler}"
+        )
         deps = [d.call.__name__ for d in route.dependant.dependencies]
         assert "get_current_subject" in deps, f"{key} lost its auth dependency"
 
@@ -1870,7 +1875,10 @@ def test_env_idle_standalone_reloads_freed_model_with_auto_switch_off(monkeypatc
     monkeypatch.setattr(settings, "get_auto_unload_idle_seconds", lambda: 600)  # standalone env TTL
     monkeypatch.setattr(kw, "_inflight", 0)
     monkeypatch.setattr(kw, "_last_unloaded_model", ("/cache/snap/A", "Q4_K_M", "org/A-GGUF"))
-    _run_hook("org/B-GGUF")
+    # A is restored, but the request named B, so it is told so rather than served A.
+    with pytest.raises(HTTPException) as excinfo:
+        _run_hook("org/B-GGUF")
+    assert excinfo.value.status_code == 404
     # Resolver skipped (auto-switch off), so only the stash reload runs: the freed A
     # is restored, not the resolves_to target B.
     assert len(rec.calls) == 1
@@ -2940,9 +2948,13 @@ def test_require_vision_ignores_reload_stash(monkeypatch):
     monkeypatch.setattr(
         inference_route, "_target_is_vision", lambda _p: False
     )  # would reject if used
-    asyncio.run(
-        inference_route._maybe_auto_switch_model("org/B-GGUF", object(), "t", require_vision = True)
-    )
+    # 404 because the restored A is not the requested B; the restore still ran.
+    with pytest.raises(HTTPException):
+        asyncio.run(
+            inference_route._maybe_auto_switch_model(
+                "org/B-GGUF", object(), "t", require_vision = True
+            )
+        )
     assert len(rec.calls) == 1
     assert rec.calls[0].model_path == "/cache/snap/A"  # restored despite require_vision
 

From a4aa2cf974665661a043a4c91290250768feb78c Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Sun, 26 Jul 2026 11:29:16 +0000
Subject: [PATCH 10/56] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 studio/backend/tests/test_openai_auto_switch.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index abafff8269f..b607af1a0ef 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -294,9 +294,9 @@ def test_openai_compat_routes_bound_to_handlers_with_auth():
     for key, handler in expected.items():
         assert key in seen, f"route {key} is not registered"
         route = seen[key]
-        assert route.endpoint.__name__ == handler, (
-            f"{key} bound to {route.endpoint.__name__}, expected {handler}"
-        )
+        assert (
+            route.endpoint.__name__ == handler
+        ), f"{key} bound to {route.endpoint.__name__}, expected {handler}"
         deps = [d.call.__name__ for d in route.dependant.dependencies]
         assert "get_current_subject" in deps, f"{key} lost its auth dependency"
 

From 3f51a73aa7010136bbadbde7128ce186794fad41 Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Sun, 26 Jul 2026 11:55:06 +0000
Subject: [PATCH 11/56] Studio: use a simpler prompt in the API usage examples

"What is Unsloth Studio?" rather than "Can Unsloth Studio do API calling?".
One constant feeds all nine snippet tabs.
---
 .../src/features/settings/components/usage-examples.tsx         | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/studio/frontend/src/features/settings/components/usage-examples.tsx b/studio/frontend/src/features/settings/components/usage-examples.tsx
index e26a6ed4f63..6bd74f1371b 100644
--- a/studio/frontend/src/features/settings/components/usage-examples.tsx
+++ b/studio/frontend/src/features/settings/components/usage-examples.tsx
@@ -85,7 +85,7 @@ const JAVASCRIPT_TYPES = new Set<ExampleType>([
   "javascriptAdvanced",
 ]);
 
-const PROMPT = "Can Unsloth Studio do API calling?";
+const PROMPT = "What is Unsloth Studio?";
 // web_search + python + terminal are the reliable built-in tools.
 const TOOLS = ["web_search", "python", "terminal"];
 const ADV = {

From 723528d1efaaf00ad6859fc6505ce0ccda0478c0 Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Sun, 26 Jul 2026 12:43:32 +0000
Subject: [PATCH 12/56] Studio: only refuse a model reference meant for this
 server

A namespace alone was treated as a concrete model reference, so a /v1
request naming anthropic/claude-3.5-sonnet, openai/gpt-4o or any other
LiteLLM or OpenRouter style vendor/model id started returning 404 instead
of being answered by the resident model. Refuse only on evidence the
caller meant this server: an explicit GGUF quant label, or a repo that is
actually on disk here. gpt-4 and vendor/model alike fall through again,
while the wrong-quant and wrong-repo cases this PR exists for still
refuse.

Also from review:

- Release the single download slot by object identity, not repo id. A
  stale watcher could clear a newer download of the same repo and let a
  second multi-GB fetch start alongside it.
- Catch BaseException around admission: CancelledError is not an
  Exception, so a cancelled request stranded the slot for the process
  lifetime.
- Honour the download service's accepted=False, which it returns without
  raising for a cross-variant conflict, instead of promising a download
  that was never dispatched.
- Treat a failed status probe as unknown rather than idle, so a transient
  read cannot fail the monitor row and free the slot under a live worker.
- Check gated repos with auth_check. The Hub serves metadata for a gated
  repo without granting its files, so the licence gate was being reported
  as the unrelated custom-code refusal.
- Size the disk reserve from the download plan, which includes the mmproj
  and MTP companions the worker fetches with every quant.
- Never fetch under the server's own HF token. The repo is named by
  whoever holds an API key, so the ambient token let that key pull the
  owner's private repos.
- Refuse an explicit quant on a backend with no quant identity, gated on
  the suffix really being a quant so Ollama style :latest tags still match.
- Raise instead of falling through when the diagnosis fails: the mismatch
  is already established by then, only the wording is uncertain.
- Report a failed switch as 503 model_switch_failed rather than answering
  as the resident model.
- Fail an open monitor row under the same lock as the check, so a finish
  landing in between cannot stamp an error onto a completed row.
- Usage examples never emit a hardcoded model id: the catalog is tri-state
  and the panel asks for a model to be loaded instead of printing one the
  server cannot serve. It also refreshes when the loaded model changes.
- Keep the monitor pager reachable while frozen entries expire.
---
 studio/backend/core/inference/api_monitor.py  |  25 +-
 .../core/inference/openai_auto_download.py    | 255 ++++++++++---
 studio/backend/routes/inference.py            | 108 ++++--
 .../tests/test_openai_auto_download.py        | 338 +++++++++++++++++-
 .../backend/tests/test_openai_auto_switch.py  |  53 ++-
 .../components/api-monitor-console.tsx        |   9 +-
 .../settings/components/usage-examples.tsx    | 100 ++++--
 studio/frontend/src/i18n/locales/en.ts        |   2 +
 ...st_usage_examples_model_source_contract.py |  41 ++-
 9 files changed, 768 insertions(+), 163 deletions(-)

diff --git a/studio/backend/core/inference/api_monitor.py b/studio/backend/core/inference/api_monitor.py
index e2a72f31419..d84de3ab2bc 100644
--- a/studio/backend/core/inference/api_monitor.py
+++ b/studio/backend/core/inference/api_monitor.py
@@ -304,7 +304,9 @@ def fail_open(self, entry_id: Optional[str], error: str) -> None:
             entry = self._find_locked(entry_id)
             if entry is None or entry.finished_at is not None:
                 return
-        self.fail(entry_id, error)
+            # Same lock as the check: a finish() landing in between would
+            # otherwise stamp this error onto a row that in fact succeeded.
+            self._fail_locked(entry, error)
 
     def fail(self, entry_id: Optional[str], error: str) -> None:
         if not entry_id:
@@ -318,15 +320,18 @@ def fail(self, entry_id: Optional[str], error: str) -> None:
                 if error:
                     entry.error = _trim(error, 1000)
                 return
-            now = time.time()
-            entry.status = "error"
-            entry.error = _trim(error, 1000)
-            entry.updated_at = now
-            entry.finished_at = now
-            entry.finished_monotonic = time.monotonic()
-            self._entries.remove(entry)
-            self._entries.appendleft(entry)
-            self._trim_terminal_locked()
+            self._fail_locked(entry, error)
+
+    def _fail_locked(self, entry: ApiMonitorEntry, error: str) -> None:
+        now = time.time()
+        entry.status = "error"
+        entry.error = _trim(error, 1000)
+        entry.updated_at = now
+        entry.finished_at = now
+        entry.finished_monotonic = time.monotonic()
+        self._entries.remove(entry)
+        self._entries.appendleft(entry)
+        self._trim_terminal_locked()
 
     def snapshot(
         self,
diff --git a/studio/backend/core/inference/openai_auto_download.py b/studio/backend/core/inference/openai_auto_download.py
index 3f6670c14e8..a65bd70853b 100644
--- a/studio/backend/core/inference/openai_auto_download.py
+++ b/studio/backend/core/inference/openai_auto_download.py
@@ -13,8 +13,10 @@
 new model through the ordinary auto-switch path.
 
 Admission is deliberately narrow, since a request only needs an API key:
-- ``namespace/name`` only. A bare name like ``gpt-4`` falls through to the
-  resident model exactly as before, so drop-in clients are unaffected.
+- ``namespace/name`` only, and only when the Hub confirms it is a GGUF repo.
+  ``gpt-4`` and ``anthropic/claude-3.5-sonnet`` alike fall through to the
+  resident model as before: a namespace is not evidence of intent, since LiteLLM
+  and OpenRouter address every provider that way.
 - GGUF repos only, decided from the remote file list, not the repo name. GGUF
   runs under llama.cpp, which never imports repo Python.
 - Anything declaring ``auto_map`` is refused, so ``trust_remote_code`` can only
@@ -71,6 +73,14 @@ class _Active:
 _lock = threading.Lock()
 _active: Optional[_Active] = None
 
+# Repos the Hub says this server cannot serve. A LiteLLM or OpenRouter client
+# names every provider "vendor/model", so without this each such request pays
+# another Hub probe on the way to being answered by the resident model.
+_NOT_SERVABLE_TTL_S = 10 * 60
+_NOT_SERVABLE_MAX = 256
+_cache_lock = threading.Lock()
+_not_servable: dict[str, float] = {}
+
 
 def _public_label(repo_id: str, variant: Optional[str]) -> str:
     return f"{repo_id}:{variant}" if variant else repo_id
@@ -107,12 +117,73 @@ def is_downloadable_ref(requested: str) -> bool:
     return True
 
 
+def looks_like_quant(variant: Optional[str]) -> bool:
+    """Whether a ``:suffix`` names a GGUF quant rather than a foreign tag.
+
+    ``vendor/model`` is how LiteLLM and OpenRouter address every provider, and
+    ``name:latest`` is how Ollama tags one, so neither a namespace nor a colon
+    proves a request was meant for this server. A real quant label does.
+    """
+    from utils.models.model_config import _GGUF_KNOWN_QUANT_RE
+
+    if not variant:
+        return False
+    return _GGUF_KNOWN_QUANT_RE.fullmatch(variant.strip()) is not None
+
+
+def _mark_not_servable(repo_id: str) -> None:
+    with _cache_lock:
+        if len(_not_servable) >= _NOT_SERVABLE_MAX:
+            _not_servable.clear()
+        _not_servable[repo_id.lower()] = time.monotonic() + _NOT_SERVABLE_TTL_S
+
+
+def _is_not_servable(repo_id: str) -> bool:
+    key = repo_id.lower()
+    with _cache_lock:
+        expires = _not_servable.get(key)
+        if expires is None:
+            return False
+        if expires <= time.monotonic():
+            del _not_servable[key]
+            return False
+        return True
+
+
+def _gated_refusal(repo_id: str) -> AutoDownloadRefusal:
+    return AutoDownloadRefusal(
+        status = 403,
+        code = "model_access_denied",
+        message = (
+            f"'{repo_id}' is gated on Hugging Face. Accept its licence and add an "
+            "access token in Unsloth Studio, then retry."
+        ),
+    )
+
+
+def _auth_denied(repo_id: str, hf_token: Optional[str]) -> bool:
+    """Whether this token lacks file access to a gated repo. False when the
+    check is inconclusive: the download's own auth is the real gate."""
+    from hub.utils.hf_errors import hf_error_status
+
+    try:
+        from huggingface_hub import auth_check
+        auth_check(repo_id, token = hf_token)
+    except Exception as exc:
+        return hf_error_status(exc) in (401, 403)
+    return False
+
+
 def _gguf_variants(siblings) -> dict[str, int]:
-    """Quant label -> total bytes, from a model_info sibling list.
+    """Quant label -> bytes the download will actually fetch.
 
-    Mirrors list_gguf_variants: companions (mmproj/MTP) and big-endian builds
-    are not selectable quants, and sharded quants sum across their shards.
+    Mirrors list_gguf_variants for the selectable labels: companions (mmproj/MTP)
+    and big-endian builds are not quants of their own, and sharded quants sum
+    across their shards. The byte total comes from the download plan, which folds
+    the companions back into every quant, so the disk reserve is measured against
+    what the worker fetches rather than the main files alone.
     """
+    from hub.utils.gguf_plan import build_gguf_variant_plans
     from utils.models.model_config import (
         _extract_quant_label,
         _is_big_endian_gguf_path,
@@ -120,15 +191,21 @@ def _gguf_variants(siblings) -> dict[str, int]:
         _is_mtp_drafter,
     )
 
+    siblings = list(siblings or [])
+    plans = build_gguf_variant_plans(siblings)
     sizes: dict[str, int] = {}
-    for sibling in siblings or []:
+    for sibling in siblings:
         name = getattr(sibling, "rfilename", "") or ""
         if not name.lower().endswith(".gguf"):
             continue
         quant = _extract_quant_label(name)
         if _is_mmproj(name) or _is_mtp_drafter(name) or _is_big_endian_gguf_path(name, quant):
             continue
-        sizes[quant] = sizes.get(quant, 0) + int(getattr(sibling, "size", 0) or 0)
+        plan = plans.get(quant.lower())
+        if plan is not None:
+            sizes[quant] = plan.download_size_bytes
+        else:
+            sizes[quant] = sizes.get(quant, 0) + int(getattr(sibling, "size", 0) or 0)
     return sizes
 
 
@@ -157,8 +234,10 @@ async def _job_state(repo_id: str, variant: Optional[str]) -> tuple[str, Optiona
         status = await downloads.get_download_status_response(repo_id, variant or "")
         return status.state, status.error
     except Exception as exc:
+        # "unknown", not "idle": a probe that failed says nothing about the
+        # worker, and idle is read as "the job vanished" and ends the watch.
         logger.debug("auto-download: status probe failed for %r: %s", repo_id, exc)
-        return "idle", None
+        return "unknown", None
 
 
 async def _progress_percent(
@@ -178,10 +257,20 @@ async def _progress_percent(
         return None
 
 
-def _release(repo_id: str) -> None:
+def _release(active: Optional[_Active]) -> None:
+    """Free the single-flight slot, but only while *active* still owns it.
+
+    Keying the release on ``repo_id`` alone let a stale operation clear a newer
+    one for the same repo: variant A errors, an adopting request frees the slot,
+    a retry starts variant B, and A's watcher then matches on the repo and clears
+    B on its way out -- admitting a second repository download alongside B.
+    Identity ties every release to the operation that actually took the slot.
+    """
     global _active
+    if active is None:
+        return
     with _lock:
-        if _active is not None and _active.repo_id == repo_id:
+        if _active is active:
             _active = None
 
 
@@ -197,13 +286,16 @@ async def _watch(active: _Active, hf_token: Optional[str]) -> None:
         while time.monotonic() < deadline:
             await asyncio.sleep(_WATCH_POLL_S)
             state, error = await _job_state(active.repo_id, active.variant)
-            if state == "running":
-                api_monitor.set_progress(
-                    active.monitor_id,
-                    await _progress_percent(
-                        active.repo_id, active.variant, active.expected_bytes, hf_token
-                    ),
-                )
+            if state in ("running", "cancelling", "unknown"):
+                # Only "running" has progress to report; the other two are still
+                # in flight, so keep the slot rather than failing the row.
+                if state == "running":
+                    api_monitor.set_progress(
+                        active.monitor_id,
+                        await _progress_percent(
+                            active.repo_id, active.variant, active.expected_bytes, hf_token
+                        ),
+                    )
                 continue
             if state == "complete":
                 # Drop the 5s resolver cache so the next retry resolves the new
@@ -223,7 +315,7 @@ async def _watch(active: _Active, hf_token: Optional[str]) -> None:
         logger.warning("auto-download: watcher failed for %r: %s", active.repo_id, exc)
         api_monitor.fail_open(active.monitor_id, "Download tracking failed")
     finally:
-        _release(active.repo_id)
+        _release(active)
 
 
 def _downloading_refusal(label: str, percent: Optional[float]) -> AutoDownloadRefusal:
@@ -249,6 +341,8 @@ async def maybe_auto_download(
     repo_id, wanted_variant = split_model_ref(requested_model)
     if not is_downloadable_ref(requested_model):
         return None
+    if _is_not_servable(repo_id) and not looks_like_quant(wanted_variant):
+        return None
 
     # Adopt or reject against the single in-flight slot before touching the
     # network, so retries during a long download stay free.
@@ -268,11 +362,12 @@ async def maybe_auto_download(
             )
         else:
             adopted = None
-            _active = _Active(repo_id = repo_id, started_at = time.time())
+            provisional = _Active(repo_id = repo_id, started_at = time.time())
+            _active = provisional
 
     if adopted is not None:
         state, error = await _job_state(adopted.repo_id, adopted.variant)
-        if state in ("running", "cancelling"):
+        if state in ("running", "cancelling", "unknown"):
             return _downloading_refusal(
                 _public_label(adopted.repo_id, adopted.variant),
                 await _progress_percent(
@@ -281,7 +376,7 @@ async def maybe_auto_download(
             )
         if state == "error":
             # Surface once, then free the slot so a retry can start over.
-            _release(adopted.repo_id)
+            _release(adopted)
             return AutoDownloadRefusal(
                 status = 502,
                 code = "model_download_failed",
@@ -290,18 +385,33 @@ async def maybe_auto_download(
         if adopted.variant is None:
             # Another request is still probing this same repo.
             return _downloading_refusal(adopted.repo_id, None)
-        # complete/idle: the watcher is about to release; ask for one more retry.
-        return _downloading_refusal(_public_label(adopted.repo_id, adopted.variant), 100.0)
+        # complete/idle/cancelled: the watcher is about to release the slot, so
+        # ask for one more retry. Only "complete" actually got there.
+        return _downloading_refusal(
+            _public_label(adopted.repo_id, adopted.variant),
+            100.0 if state == "complete" else None,
+        )
 
     try:
-        return await _admit_and_start(repo_id, wanted_variant, requested_model, hf_token)
-    except Exception:
-        _release(repo_id)
+        return await _admit_and_start(
+            repo_id, wanted_variant, requested_model, hf_token, provisional
+        )
+    except BaseException:
+        # BaseException, not Exception: asyncio.CancelledError has not been an
+        # Exception since 3.8, so a request cancelled mid-probe would otherwise
+        # leave the provisional slot installed with variant None -- every other
+        # repo permanently model_download_busy and this one permanently
+        # "downloading", until the process restarts.
+        _release(provisional)
         raise
 
 
 async def _admit_and_start(
-    repo_id: str, wanted_variant: Optional[str], requested_model: str, hf_token: Optional[str]
+    repo_id: str,
+    wanted_variant: Optional[str],
+    requested_model: str,
+    hf_token: Optional[str],
+    active: _Active,
 ) -> Optional[AutoDownloadRefusal]:
     from hub.utils.hf_errors import hf_error_status
 
@@ -314,18 +424,18 @@ def _probe():
     try:
         info = await asyncio.to_thread(_probe)
     except Exception as exc:
-        _release(repo_id)
+        _release(active)
         status = hf_error_status(exc)
         if status == 403:
-            return AutoDownloadRefusal(
-                status = 403,
-                code = "model_access_denied",
-                message = (
-                    f"'{repo_id}' is gated on Hugging Face. Accept its licence and add an "
-                    "access token in Unsloth Studio, then retry."
-                ),
-            )
+            return _gated_refusal(repo_id)
         if status == 404:
+            _mark_not_servable(repo_id)
+            # An id the Hub does not know is a foreign label, not a miss: pass it
+            # to the resident model as before rather than 404 every LiteLLM and
+            # OpenRouter "vendor/model". An explicit quant is a deliberate GGUF
+            # reference, so that one is answered.
+            if not looks_like_quant(wanted_variant):
+                return None
             # A private repo reads as absent without a token; don't confirm either way.
             return AutoDownloadRefusal(
                 status = 404,
@@ -340,9 +450,19 @@ def _probe():
             retry_after = _RETRY_AFTER_S,
         )
 
+    if getattr(info, "gated", False) and await asyncio.to_thread(_auth_denied, repo_id, hf_token):
+        # The Hub serves metadata for a gated repo without granting its files, so
+        # a probe that returned is not proof of access. Left unchecked the config
+        # read below fails instead and reports the unrelated custom-code refusal.
+        _release(active)
+        return _gated_refusal(repo_id)
+
     variants = _gguf_variants(getattr(info, "siblings", None))
     if not variants:
-        _release(repo_id)
+        _release(active)
+        _mark_not_servable(repo_id)
+        if not looks_like_quant(wanted_variant):
+            return None
         return AutoDownloadRefusal(
             status = 400,
             code = "model_not_supported",
@@ -359,7 +479,7 @@ def _probe():
 
     has_auto_map = await asyncio.to_thread(_config_has_auto_map, repo_id, hf_token)
     if has_auto_map is not False:
-        _release(repo_id)
+        _release(active)
         unknown = has_auto_map is None
         return AutoDownloadRefusal(
             status = 403,
@@ -377,7 +497,7 @@ def _probe():
 
     variant = _match_variant(wanted_variant, variants)
     if variant is None:
-        _release(repo_id)
+        _release(active)
         listed = sorted(variants)
         shown = ", ".join(listed[:_MAX_LISTED_VARIANTS])
         extra = len(listed) - _MAX_LISTED_VARIANTS
@@ -393,7 +513,7 @@ def _probe():
     expected_bytes = variants[variant]
     fits, free = _enough_disk(expected_bytes)
     if not fits:
-        _release(repo_id)
+        _release(active)
         return AutoDownloadRefusal(
             status = 507,
             code = "insufficient_disk_space",
@@ -403,7 +523,7 @@ def _probe():
             ),
         )
 
-    return await _dispatch(repo_id, variant, expected_bytes, requested_model, hf_token)
+    return await _dispatch(repo_id, variant, expected_bytes, requested_model, hf_token, active)
 
 
 def _match_variant(wanted: Optional[str], variants: dict[str, int]) -> Optional[str]:
@@ -425,7 +545,12 @@ def _match_variant(wanted: Optional[str], variants: dict[str, int]) -> Optional[
 
 
 async def _dispatch(
-    repo_id: str, variant: str, expected_bytes: int, requested_model: str, hf_token: Optional[str]
+    repo_id: str,
+    variant: str,
+    expected_bytes: int,
+    requested_model: str,
+    hf_token: Optional[str],
+    active: _Active,
 ) -> AutoDownloadRefusal:
     global _active
 
@@ -434,21 +559,22 @@ async def _dispatch(
     from hub.services.models import downloads
 
     label = _public_label(repo_id, variant)
+    busy = AutoDownloadRefusal(
+        status = 503,
+        code = "model_download_busy",
+        message = f"'{repo_id}' is already being downloaded or loaded. Retry shortly.",
+        retry_after = _RETRY_AFTER_S,
+    )
     try:
-        await downloads.download_model_response(
+        dispatched = await downloads.download_model_response(
             DownloadModelRequest(repo_id = repo_id, gguf_variant = variant), hf_token
         )
     except Exception as exc:
-        _release(repo_id)
+        _release(active)
         status = getattr(exc, "status_code", None)
         if status == 409:
             # A manual load or hub download already owns this repo.
-            return AutoDownloadRefusal(
-                status = 503,
-                code = "model_download_busy",
-                message = f"'{repo_id}' is already being downloaded or loaded. Retry shortly.",
-                retry_after = _RETRY_AFTER_S,
-            )
+            return busy
         logger.warning("auto-download: could not start %r: %s", label, exc)
         return AutoDownloadRefusal(
             status = 502,
@@ -456,18 +582,31 @@ async def _dispatch(
             message = f"Could not start downloading '{requested_model}'.",
         )
 
+    # A same-repo whole-repo/cross-transport download or an in-progress delete
+    # makes the service refuse *without* raising: it returns accepted=False and
+    # launches no worker. Taking the slot then would promise a download that does
+    # not exist, and the watcher would fail its own monitor row two seconds later
+    # on a key that is idle by construction. Report the conflict instead.
+    if isinstance(dispatched, dict) and not dispatched.get("accepted", True):
+        _release(active)
+        logger.info("auto-download: dispatch refused for %s (%s)", label, dispatched.get("state"))
+        return busy
+
     monitor_id = api_monitor.record_lifecycle(
         event = "download", model = label, reason = "api", running = True
     )
     with _lock:
-        if _active is not None and _active.repo_id == repo_id:
-            _active.variant = variant
-            _active.expected_bytes = expected_bytes
-            _active.monitor_id = monitor_id
-            tracked = _active
-        else:  # released underneath us; still track the job we just started
+        if _active is active:
+            active.variant = variant
+            active.expected_bytes = expected_bytes
+            active.monitor_id = monitor_id
+            tracked = active
+        else:
+            # Released underneath us: still track the job we just started so its
+            # monitor row resolves, but never stomp a newer owner of the slot.
             tracked = _Active(repo_id, variant, expected_bytes, monitor_id, time.time())
-            _active = tracked
+            if _active is None:
+                _active = tracked
 
     asyncio.create_task(_watch(tracked, hf_token))
     logger.info("auto-download: started %s (%s)", label, _gb(expected_bytes))
@@ -486,3 +625,5 @@ def reset_for_tests() -> None:
     global _active
     with _lock:
         _active = None
+    with _cache_lock:
+        _not_servable.clear()
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 941049e20ab..5de18727fd7 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3671,6 +3671,12 @@ async def _no_model_loaded_error(
     if named is None or not get_openai_auto_switch_enabled():
         return status, _no_model_loaded_detail(base)
     try:
+        if _loaded_satisfies(named):
+            # The named model IS resident, just not on a backend this endpoint can
+            # use (a Transformers model on a GGUF-only surface). "Not downloaded"
+            # would be false, and the catalog GET /v1/models serves lists this very
+            # id as available, so keep the generic diagnosis, which is accurate.
+            return status, _no_model_loaded_detail(base)
         if await asyncio.to_thread(resolve_local_gguf, named) is not None:
             # Resolvable but unloaded: the switch failed (load error, race), which
             # the generic text describes correctly.
@@ -3694,20 +3700,22 @@ async def _no_model_loaded_error(
 
 
 def _auto_download_hf_token(fastapi_request: Optional[Request]) -> Optional[str]:
-    """The token to fetch with: the Hub header if the caller sent one, else the
-    server's own. The OpenAI bearer key is never used as an HF token."""
+    """The token to fetch with: only one the caller sent themselves.
+
+    Never the server's ambient token. The repo here is named by whoever holds an
+    API key, so borrowing the owner's Hub identity would let that key pull the
+    owner's private repos and publish them in /v1/models for every other key.
+    The OpenAI bearer key is never used as an HF token either.
+    """
     from hub.dependencies import HUB_HF_TOKEN_HEADER, HUB_HF_TOKEN_MAX_LENGTH
 
     headers = getattr(fastapi_request, "headers", None)
-    if headers is not None:
-        supplied = (headers.get(HUB_HF_TOKEN_HEADER) or "").strip()
-        if supplied and len(supplied) <= HUB_HF_TOKEN_MAX_LENGTH:
-            return supplied
-    try:
-        from routes.settings import _ambient_hf_token
-        return _ambient_hf_token()
-    except Exception:
+    if headers is None:
         return None
+    supplied = (headers.get(HUB_HF_TOKEN_HEADER) or "").strip()
+    if supplied and len(supplied) <= HUB_HF_TOKEN_MAX_LENGTH:
+        return supplied
+    return None
 
 
 async def _maybe_auto_download_model(
@@ -3762,7 +3770,7 @@ def _loaded_satisfies(requested: str) -> bool:
     A bare ``org/model`` is satisfied by any loaded quant of that repo; an
     explicit ``:QUANT`` must match the loaded one.
     """
-    from core.inference.openai_auto_download import split_model_ref
+    from core.inference.openai_auto_download import looks_like_quant, split_model_ref
 
     base, variant = split_model_ref(requested)
     base = base.lower()
@@ -3785,22 +3793,28 @@ def _loaded_satisfies(requested: str) -> bool:
     active = getattr(get_inference_backend(), "active_model_name", None)
     if not active:
         return False
+    # Only llama.cpp carries a quant identity, so this backend cannot show that
+    # an explicit quant is what is loaded. A non-quant tag is not a claim about
+    # the weights, so it still matches on the repo alone.
+    if looks_like_quant(variant):
+        return False
     return base in {active.lower(), (public_model_id(active) or "").lower()}
 
 
 async def _reject_unservable_model(
     requested_model: Optional[str], fastapi_request: Optional[Request]
 ) -> None:
-    """404 rather than answer a named model with a different one.
-
-    ``org/model`` (optionally ``:QUANT``) is a concrete reference: serving it
-    from whatever happens to be resident returns a confident answer from the
-    wrong weights. Ids without a namespace (``gpt-4``) are foreign labels, so
-    they still fall through and drop-in clients are unaffected. Only runs while
-    something is serving; with nothing loaded the caller's own
-    :func:`_no_model_loaded_error` already says the right thing.
+    """Refuse rather than answer a named model with a different one.
+
+    Only for a reference this server can tell was meant for it: an explicit GGUF
+    quant, or a repo that is actually here. A bare ``vendor/model`` is not enough
+    on its own, because that is how LiteLLM and OpenRouter name every provider,
+    so ``anthropic/claude-3.5-sonnet`` keeps falling through to the resident
+    model exactly like ``gpt-4``. Only runs while something is serving; with
+    nothing loaded the caller's own :func:`_no_model_loaded_error` already says
+    the right thing.
     """
-    from core.inference.openai_auto_download import split_model_ref
+    from core.inference.openai_auto_download import looks_like_quant, split_model_ref
 
     if (
         not isinstance(requested_model, str)
@@ -3808,9 +3822,13 @@ async def _reject_unservable_model(
         or requested_model == _RELOAD_ONLY_MODEL
     ):
         return
-    base, _variant = split_model_ref(requested_model)
+    base, variant = split_model_ref(requested_model)
     if "/" not in base:
         return
+    quantified = looks_like_quant(variant)
+    from core.inference.local_model_resolver import resolve_local_gguf
+    from utils.openai_auto_switch_settings import get_openai_auto_switch_enabled
+
     try:
         if _loaded_satisfies(requested_model):
             return
@@ -3819,33 +3837,53 @@ async def _reject_unservable_model(
             or getattr(get_inference_backend(), "active_model_name", None)
         ):
             return
-        from core.inference.local_model_resolver import resolve_local_gguf
-        from utils.openai_auto_switch_settings import get_openai_auto_switch_enabled
-
         downloaded = await asyncio.to_thread(resolve_local_gguf, requested_model) is not None
-        if downloaded and get_openai_auto_switch_enabled():
-            # On disk and switching is allowed, so the swap failed (load error,
-            # race). Serving the resident model is the sane fallback.
+        # The exact ref may miss on the quant alone, so ask about the repo too.
+        here = downloaded or (
+            variant is not None and await asyncio.to_thread(resolve_local_gguf, base) is not None
+        )
+        switchable = downloaded and get_openai_auto_switch_enabled()
+    except Exception as exc:
+        # Can't verify. An explicit quant is still proof the caller meant this
+        # server, so refuse; anything else may be a foreign label, so let it by.
+        logger.debug("unservable-model check failed for %r: %s", requested_model, exc)
+        if not quantified:
             return
+        downloaded = here = switchable = False
+    if not (quantified or here):
+        return
+    if switchable:
+        # On disk and switching is allowed, so the swap itself failed. Answering
+        # as the resident model would be the wrong weights under the right name.
+        status_code, code = 503, "model_switch_failed"
+        message = (
+            f"The model '{requested_model}' is downloaded, but this server could not "
+            "switch to it. Retry shortly, or load it in Unsloth Studio."
+        )
+    elif downloaded:
+        status_code, code = 404, "model_not_found"
         message = (
             f"The model '{requested_model}' is downloaded but not loaded, and "
             "'Switch model by request' is off, so this server can only serve the "
             "loaded model. Turn it on in Unsloth Studio under Settings > API."
-            if downloaded
-            else await _unavailable_model_message(requested_model)
         )
-    except Exception as exc:
-        # A diagnosis failure must never break a request the server can answer.
-        logger.debug("unservable-model check failed for %r: %s", requested_model, exc)
-        return
+    else:
+        status_code, code = 404, "model_not_found"
+        try:
+            message = await _unavailable_model_message(requested_model)
+        except Exception as exc:
+            # Only the wording is uncertain; the mismatch is already established.
+            logger.debug("unavailable-model diagnosis failed for %r: %s", requested_model, exc)
+            message = f"The model '{requested_model}' is not the model this server is serving."
     path = getattr(getattr(fastapi_request, "url", None), "path", None)
     raise HTTPException(
-        status_code = 404,
+        status_code = status_code,
         detail = (
-            error_body_for_path(path, message, status = 404, code = "model_not_found", param = "model")
+            error_body_for_path(path, message, status = status_code, code = code, param = "model")
             if isinstance(path, str)
             else message
         ),
+        headers = {"Retry-After": "5"} if status_code == 503 else None,
     )
 
 
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index dfe67db103b..8cfef1e85d6 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -65,34 +65,82 @@ def _clean_slot():
     auto_dl.reset_for_tests()
 
 
+def _repo_not_found_error():
+    from huggingface_hub.utils import RepositoryNotFoundError
+    return RepositoryNotFoundError
+
+
+def _gated_error():
+    from huggingface_hub.utils import GatedRepoError
+    return GatedRepoError
+
+
+def _hub_error(error_type, status_code: int, message: str):
+    """Build a Hub exception across huggingface_hub majors.
+
+    huggingface_hub 1.x made ``response`` a required keyword-only argument, and
+    the project floor is 0.34, so construct positionally and fall back.
+    """
+    try:
+        return error_type(message)
+    except TypeError:
+        import httpx
+        return error_type(
+            message,
+            response = httpx.Response(
+                status_code,
+                request = httpx.Request("GET", "https://huggingface.co/api/models/org/repo"),
+            ),
+        )
+
+
 @pytest.fixture
 def hub(monkeypatch):
     """Wire the whole remote surface to fakes and record what was dispatched."""
     import huggingface_hub
     from hub.services.models import downloads
 
-    state = {"info": _gguf_repo_info(), "raise": None, "auto_map": False, "started": []}
+    state = {
+        "info": _gguf_repo_info(),
+        "raise": None,
+        "auto_map": False,
+        "started": [],
+        "watched": [],
+        # What the hub download service hands back. accepted=False means it
+        # refused the claim and launched no worker.
+        "dispatch_result": {"job_key": "k", "state": "running", "accepted": True},
+        "on_probe": None,
+        "probes": 0,
+        "auth_denied": False,
+    }
 
     class _FakeApi:
         def __init__(self, token = None):
             state["token"] = token
 
         def model_info(self, repo_id, **kwargs):
+            state["probes"] += 1
+            if state["on_probe"] is not None:
+                state["on_probe"]()
             if state["raise"] is not None:
                 raise state["raise"]
             return state["info"]
 
     async def _start(body, hf_token = None):
         state["started"].append((body.repo_id, body.gguf_variant, hf_token))
-        return {"job_key": "k", "state": "running"}
+        return state["dispatch_result"]
 
     async def _no_watch(active, hf_token):
+        state["watched"].append(active)
         return None
 
     monkeypatch.setattr(huggingface_hub, "HfApi", _FakeApi)
     monkeypatch.setattr(downloads, "download_model_response", _start)
+    # Keep the real watcher reachable: one test drives its cleanup directly.
+    state["real_watch"] = auto_dl._watch
     monkeypatch.setattr(auto_dl, "_watch", _no_watch)
     monkeypatch.setattr(auto_dl, "_enough_disk", lambda need: (True, 10 * 1024**4))
+    monkeypatch.setattr(auto_dl, "_auth_denied", lambda repo, token: state["auth_denied"])
     monkeypatch.setattr(
         "utils.security.consent._config_has_auto_map",
         lambda repo, token = None: state["auto_map"],
@@ -149,9 +197,23 @@ def test_downloadable(raw):
 
 def test_gguf_variants_skips_companions():
     variants = auto_dl._gguf_variants(_gguf_repo_info().siblings)
+    # Companions are not quants of their own...
     assert set(variants) == {"UD-Q4_K_XL", "UD-Q5_K_XL", "Q8_0"}
-    # Shards of one quant sum together.
-    assert variants["Q8_0"] == 8 * 1024**3
+    # ...but the worker fetches them with every quant, so the disk reserve has
+    # to count them. Shards of one quant sum together on top of that.
+    companions = 2 * 1024**3  # mmproj + MTP drafter
+    assert variants["Q8_0"] == 8 * 1024**3 + companions
+    assert variants["UD-Q4_K_XL"] == 4 * 1024**3 + companions
+
+
+def test_looks_like_quant_separates_quants_from_foreign_tags():
+    assert auto_dl.looks_like_quant("UD-Q6_K_XL")
+    assert auto_dl.looks_like_quant("q4_k_m")
+    assert auto_dl.looks_like_quant("F16")
+    # Ollama-style tags are not quants and must not read as a GGUF reference.
+    assert not auto_dl.looks_like_quant("latest")
+    assert not auto_dl.looks_like_quant("8b")
+    assert not auto_dl.looks_like_quant(None)
 
 
 def test_match_variant_is_case_insensitive_and_exact():
@@ -200,24 +262,63 @@ def test_missing_quant_lists_the_real_ones(hub):
 
 
 def test_missing_repo_is_404_without_confirming_existence(hub):
-    from huggingface_hub.utils import RepositoryNotFoundError
-
-    hub["raise"] = RepositoryNotFoundError("nope")
-    refusal = _run("unsloth/not-real")
+    hub["raise"] = _hub_error(_repo_not_found_error(), 404, "nope")
+    # An explicit quant is a deliberate GGUF reference, so a miss is answered.
+    refusal = _run("unsloth/not-real:UD-Q4_K_XL")
     assert refusal.status == 404 and refusal.code == "model_not_found"
     assert "not accessible" in refusal.message
     assert hub["started"] == []
 
 
+def test_an_id_the_hub_does_not_know_falls_through(hub):
+    hub["raise"] = _hub_error(_repo_not_found_error(), 404, "nope")
+    # LiteLLM and OpenRouter name every provider "vendor/model". A namespace is
+    # not intent, so an id the Hub has never heard of stays a foreign label and
+    # the resident model answers it, exactly as before this feature existed.
+    for foreign in (
+        "anthropic/claude-3.5-sonnet",
+        "openai/gpt-4o",
+        "meta-llama/llama-3-70b-instruct",
+    ):
+        assert _run(foreign) is None
+    assert hub["started"] == []
+
+
+def test_a_foreign_id_is_probed_once_then_cached(hub):
+    hub["raise"] = _hub_error(_repo_not_found_error(), 404, "nope")
+    assert _run("anthropic/claude-3.5-sonnet") is None
+    assert hub["probes"] == 1
+    # Every later request would otherwise pay another Hub round trip.
+    assert _run("anthropic/claude-3.5-sonnet") is None
+    assert hub["probes"] == 1
+
+
 def test_gated_repo_is_403(hub):
-    from huggingface_hub.utils import GatedRepoError
+    hub["raise"] = _hub_error(_gated_error(), 403, "gated")
+    refusal = _run("meta-llama/Llama-2-7b-hf")
+    assert refusal.status == 403 and refusal.code == "model_access_denied"
+    assert hub["started"] == []
+
 
-    hub["raise"] = GatedRepoError("gated")
+def test_a_gated_repo_that_still_returns_metadata_is_403(hub):
+    # The Hub serves metadata for a gated repo without granting its files, so a
+    # probe that returned is not access. Reported as the licence gate it is, not
+    # as the custom-code refusal the unreadable config would otherwise produce.
+    hub["info"] = _Info(_gguf_repo_info().siblings, gated = "manual")
+    hub["auth_denied"] = True
     refusal = _run("meta-llama/Llama-2-7b-hf")
     assert refusal.status == 403 and refusal.code == "model_access_denied"
+    assert "licence" in refusal.message
     assert hub["started"] == []
 
 
+def test_a_gated_repo_this_token_may_read_still_downloads(hub):
+    hub["info"] = _Info(_gguf_repo_info().siblings, gated = "manual")
+    refusal = _run("meta-llama/Llama-2-7b-hf")
+    assert refusal.code == "model_downloading"
+    assert len(hub["started"]) == 1
+
+
 def test_hub_unreachable_is_retryable(hub):
     hub["raise"] = OSError("network down")
     refusal = _run("unsloth/x-GGUF")
@@ -228,11 +329,18 @@ def test_hub_unreachable_is_retryable(hub):
 
 def test_non_gguf_repo_is_refused(hub):
     hub["info"] = _Info([_Sibling("model.safetensors", 100), _Sibling("config.json", 10)])
-    refusal = _run("unsloth/plain-transformers")
+    refusal = _run("unsloth/plain-transformers:Q4_K_M")
     assert refusal.status == 400 and refusal.code == "model_not_supported"
     assert hub["started"] == []
 
 
+def test_a_bare_non_gguf_id_falls_through(hub):
+    # Without a quant this is indistinguishable from a foreign provider label.
+    hub["info"] = _Info([_Sibling("model.safetensors", 100)])
+    assert _run("unsloth/plain-transformers") is None
+    assert hub["started"] == []
+
+
 def test_remote_code_repo_is_refused(hub):
     hub["auto_map"] = True
     refusal = _run("someone/custom-arch-GGUF")
@@ -317,6 +425,115 @@ def test_hf_token_is_passed_to_the_worker(hub):
     assert hub["started"][0][2] == "hf_secret"
 
 
+# --- the single-flight slot ---------------------------------------------------
+
+
+def test_a_refused_dispatch_is_not_reported_as_downloading(hub):
+    # A same-repo whole-repo download or an in-progress delete makes the hub
+    # service decline the claim without raising: accepted=False, no worker. The
+    # caller must hear "busy", not a download that was never started (which the
+    # watcher would then fail two seconds later on an idle key).
+    hub["dispatch_result"] = {
+        "job_key": "unsloth/x-gguf::ud-q5_k_xl",
+        "state": "running",  # the blocking job's state, not ours
+        "accepted": False,
+        "generation": 3,
+    }
+    refusal = _run("unsloth/x-GGUF:UD-Q5_K_XL")
+    assert refusal.status == 503 and refusal.code == "model_download_busy"
+    # No monitor row was opened and no watcher installed for a job that is not running.
+    assert hub["watched"] == []
+    # The slot is free, so an unrelated repo is still admitted.
+    assert auto_dl._active is None
+    hub["dispatch_result"] = {"job_key": "k", "state": "running", "accepted": True}
+    assert _run("unsloth/other-GGUF").code == "model_downloading"
+
+
+def test_an_adoptable_dispatch_still_tracks_the_existing_job(hub):
+    # accepted=True with claimed=False means this exact repo+quant is already
+    # downloading (started from the Hub UI); attach to it rather than refuse.
+    hub["dispatch_result"] = {"job_key": "k", "state": "running", "accepted": True}
+    assert _run("unsloth/x-GGUF:UD-Q5_K_XL").code == "model_downloading"
+    assert len(hub["watched"]) == 1
+
+
+def test_a_failed_status_probe_does_not_end_the_watch(hub, monkeypatch):
+    # A probe that raised says nothing about the worker. Reading it as "idle"
+    # failed the monitor row and freed the slot under a live download, which is
+    # how a second multi-GB fetch got admitted alongside the first.
+    from hub.services.models import downloads
+
+    async def _boom(repo_id, gguf_variant = ""):
+        raise RuntimeError("registry unavailable")
+
+    monkeypatch.setattr(downloads, "get_download_status_response", _boom)
+    state, error = asyncio.run(auto_dl._job_state("unsloth/x-GGUF", "UD-Q4_K_XL"))
+    assert (state, error) == ("unknown", None)
+
+
+def test_an_unknown_state_still_reports_the_download_to_a_retry(hub, monkeypatch):
+    assert _run("unsloth/x-GGUF:UD-Q4_K_XL").code == "model_downloading"
+
+    async def _unknown(repo, variant):
+        return "unknown", None
+
+    monkeypatch.setattr(auto_dl, "_job_state", _unknown)
+    # Still downloading as far as anyone knows, so the slot stays taken.
+    assert _run("unsloth/x-GGUF:UD-Q4_K_XL").code == "model_downloading"
+    assert _run("unsloth/other-GGUF").code == "model_download_busy"
+
+
+def test_a_stale_watcher_cannot_release_a_newer_download(hub, monkeypatch):
+    # Variant A is downloading; its watcher holds the slot.
+    assert _run("unsloth/x-GGUF:UD-Q4_K_XL").code == "model_downloading"
+    watcher_a = hub["watched"][-1]
+
+    # A fails, so an adopting request surfaces the error and frees the slot.
+    real_job_state = auto_dl._job_state
+    errored = {"on": True}
+
+    async def _maybe_errored(repo, variant):
+        if errored["on"]:
+            return "error", "boom"
+        return await real_job_state(repo, variant)
+
+    monkeypatch.setattr(auto_dl, "_job_state", _maybe_errored)
+    assert _run("unsloth/x-GGUF:UD-Q4_K_XL").code == "model_download_failed"
+    errored["on"] = False
+
+    # The retry starts variant B of the same repo, which now owns the slot.
+    assert _run("unsloth/x-GGUF:UD-Q5_K_XL").code == "model_downloading"
+    watcher_b = hub["watched"][-1]
+    assert auto_dl._active is watcher_b
+
+    # Only now does A's watcher wake up and run its cleanup. Keyed on repo_id
+    # alone that cleared B, letting a second repo download start alongside it.
+    errored["on"] = True
+    monkeypatch.setattr(auto_dl, "_WATCH_POLL_S", 0.0)
+    asyncio.run(hub["real_watch"](watcher_a, None))
+    assert auto_dl._active is watcher_b
+    assert _run("unsloth/other-GGUF").code == "model_download_busy"
+
+
+def test_a_cancelled_admission_does_not_wedge_the_slot(hub):
+    # CancelledError is a BaseException, so an `except Exception` cleanup would
+    # leave the provisional slot installed and refuse every later request for the
+    # rest of the process.
+    def _cancel():
+        raise asyncio.CancelledError()
+
+    hub["on_probe"] = _cancel
+
+    async def _cancelled_request():
+        with pytest.raises(asyncio.CancelledError):
+            await auto_dl.maybe_auto_download("unsloth/x-GGUF")
+
+    asyncio.run(_cancelled_request())
+    assert auto_dl._active is None
+    hub["on_probe"] = None
+    assert _run("unsloth/other-GGUF").code == "model_downloading"
+
+
 # --- route wiring ------------------------------------------------------------
 
 
@@ -485,11 +702,70 @@ def test_downloaded_but_auto_switch_off_says_so(monkeypatch):
     assert "Switch model by request" in str(excinfo.value.detail)
 
 
-def test_downloaded_with_auto_switch_on_falls_through(monkeypatch):
-    # On disk and switching allowed means the swap failed; the resident model is
-    # the sane fallback rather than a hard error.
+def test_a_failed_switch_is_reported_not_answered_by_the_resident_model(monkeypatch):
+    # On disk and switching allowed means the swap itself failed. Answering from
+    # whatever is resident would be the wrong weights under the right name.
     loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
-    assert _reject("unsloth/B-GGUF", loaded, monkeypatch, downloaded = True, auto_switch = True) is None
+    with pytest.raises(HTTPException) as excinfo:
+        _reject("unsloth/B-GGUF", loaded, monkeypatch, downloaded = True, auto_switch = True)
+    assert excinfo.value.status_code == 503
+    assert excinfo.value.detail["error"]["code"] == "model_switch_failed"
+    assert excinfo.value.headers["Retry-After"] == "5"
+
+
+@pytest.mark.parametrize(
+    "foreign",
+    [
+        "anthropic/claude-3.5-sonnet",
+        "openai/gpt-4o",
+        "meta-llama/llama-3-70b-instruct",
+        "mistralai/Mistral-7B-Instruct-v0.2",
+    ],
+)
+def test_a_provider_prefixed_label_still_reaches_the_resident_model(foreign, monkeypatch):
+    # LiteLLM and OpenRouter address every provider as "vendor/model". Treating a
+    # namespace as a concrete reference 404s all of them, so a bare one that is
+    # not on disk has to keep falling through.
+    loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
+    assert _reject(foreign, loaded, monkeypatch) is None
+
+
+def test_an_explicit_quant_is_still_refused(monkeypatch):
+    # The signal that separates a GGUF reference from a foreign label: no
+    # LiteLLM or OpenRouter id carries a quant.
+    loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
+    with pytest.raises(HTTPException) as excinfo:
+        _reject("unsloth/B-GGUF:UD-Q6_K_XL", loaded, monkeypatch)
+    assert excinfo.value.status_code == 404
+
+
+def test_a_repo_that_is_here_is_refused_without_a_quant(monkeypatch):
+    # The other half of the evidence test: a repo this server actually has is a
+    # reference to this server whether or not a quant was named.
+    loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
+    with pytest.raises(HTTPException) as excinfo:
+        _reject("unsloth/B-GGUF", loaded, monkeypatch, downloaded = True)
+    assert excinfo.value.status_code == 404
+
+
+def test_a_diagnosis_failure_does_not_serve_the_wrong_model(monkeypatch):
+    # The mismatch is already established before the diagnosis runs, so only the
+    # wording is uncertain. Falling through here would answer as another model.
+    loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
+    monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+    monkeypatch.setattr(
+        inference_route,
+        "get_inference_backend",
+        lambda: type("B", (), {"active_model_name": None})(),
+    )
+
+    def _boom(name):
+        raise OSError("cache scan unavailable")
+
+    monkeypatch.setattr("core.inference.local_model_resolver.resolve_local_gguf", _boom)
+    with pytest.raises(HTTPException) as excinfo:
+        asyncio.run(inference_route._reject_unservable_model("unsloth/B-GGUF:UD-Q6_K_XL", _Req()))
+    assert excinfo.value.status_code == 404
 
 
 def test_nothing_loaded_leaves_the_existing_error_alone(monkeypatch):
@@ -538,7 +814,9 @@ def test_anthropic_surface_gets_its_own_envelope(monkeypatch):
     monkeypatch.setattr(inference_route, "_unavailable_model_message", _fake_unavailable_message)
     with pytest.raises(HTTPException) as excinfo:
         asyncio.run(
-            inference_route._reject_unservable_model("unsloth/B-GGUF", _Req(path = "/v1/messages"))
+            inference_route._reject_unservable_model(
+                "unsloth/B-GGUF:UD-Q6_K_XL", _Req(path = "/v1/messages")
+            )
         )
     assert excinfo.value.detail["type"] == "error"
 
@@ -615,3 +893,31 @@ def test_every_other_bad_key_stays_indistinguishable():
     assert _invalid_api_key_detail("sk-unsloth-revoked") == generic
     assert _invalid_api_key_detail("sk-unsloth-YOUR_KEY ") == generic
     assert _invalid_api_key_detail("sk-unsloth-your_key") == generic
+
+
+def test_the_servers_own_hf_token_is_never_borrowed(monkeypatch):
+    # The repo here is named by whoever holds an API key. Fetching it under the
+    # owner's Hub identity would let that key pull the owner's private repos and
+    # publish them in /v1/models for every other key.
+    import routes.settings as settings_route
+
+    monkeypatch.setattr(settings_route, "_ambient_hf_token", lambda: "hf_owner_secret")
+    assert inference_route._auto_download_hf_token(_Req()) is None
+    caller = _Req(headers = {"X-Unsloth-HF-Token": "hf_caller_own"})
+    assert inference_route._auto_download_hf_token(caller) == "hf_caller_own"
+
+
+def test_a_quant_cannot_be_satisfied_by_a_non_gguf_backend(monkeypatch):
+    # The llama.cpp branch requires :QUANT to match hf_variant. The Transformers
+    # branch has no quant identity at all, so it cannot claim one is loaded.
+    idle = type("B", (), {"is_loaded": False, "model_identifier": None, "hf_variant": None})()
+    monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: idle)
+    monkeypatch.setattr(
+        inference_route,
+        "get_inference_backend",
+        lambda: type("B", (), {"active_model_name": "org/model"})(),
+    )
+    assert inference_route._loaded_satisfies("org/model") is True
+    assert inference_route._loaded_satisfies("org/model:Q4_K_M") is False
+    # An Ollama-style tag is not a claim about the weights, so it still matches.
+    assert inference_route._loaded_satisfies("org/model:latest") is True
diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index b607af1a0ef..394833a38bc 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -294,9 +294,9 @@ def test_openai_compat_routes_bound_to_handlers_with_auth():
     for key, handler in expected.items():
         assert key in seen, f"route {key} is not registered"
         route = seen[key]
-        assert (
-            route.endpoint.__name__ == handler
-        ), f"{key} bound to {route.endpoint.__name__}, expected {handler}"
+        assert route.endpoint.__name__ == handler, (
+            f"{key} bound to {route.endpoint.__name__}, expected {handler}"
+        )
         deps = [d.call.__name__ for d in route.dependant.dependencies]
         assert "get_current_subject" in deps, f"{key} lost its auth dependency"
 
@@ -2949,10 +2949,12 @@ def test_require_vision_ignores_reload_stash(monkeypatch):
         inference_route, "_target_is_vision", lambda _p: False
     )  # would reject if used
     # 404 because the restored A is not the requested B; the restore still ran.
+    # B carries a quant so it reads as a reference to this server, not a foreign
+    # provider label.
     with pytest.raises(HTTPException):
         asyncio.run(
             inference_route._maybe_auto_switch_model(
-                "org/B-GGUF", object(), "t", require_vision = True
+                "org/B-GGUF:UD-Q6_K_XL", object(), "t", require_vision = True
             )
         )
     assert len(rec.calls) == 1
@@ -3503,6 +3505,49 @@ def test_chat_undownloaded_model_uses_the_openai_envelope(monkeypatch):
     assert err["param"] == "model"
 
 
+def test_gguf_only_paths_keep_the_generic_error_for_the_resident_non_gguf_model(monkeypatch):
+    # A Transformers model is resident and the caller names that exact model on a
+    # GGUF-only path. It is not a GGUF, so resolve_local_gguf misses -- but the
+    # catalog GET /v1/models serves lists this very id as available, so "not
+    # downloaded on this server. Available models: <that same id>" is both false
+    # and self-contradictory. The generic "no GGUF loaded" diagnosis is correct.
+    resident = "unsloth/Qwen3.5-4B-GGUF"  # the id _run_responses_stream_no_model asks for
+
+    async def _catalog():
+        return [{"id": resident}]
+
+    monkeypatch.setattr(inference_route, "_openai_catalog_objects", _catalog)
+    status, detail = _run_responses_stream_no_model(
+        monkeypatch, enabled = True, active_model_name = resident
+    )
+    assert status == 400
+    assert "requires a GGUF model" in detail
+    assert "not downloaded" not in detail
+
+
+def test_completions_keeps_the_generic_error_for_the_resident_non_gguf_model(monkeypatch):
+    # Same contradiction on the raw-body surface, which reaches the diagnosis
+    # through _auto_switch_from_request_body rather than a typed payload.
+    from fastapi import HTTPException
+
+    resident = "unsloth/Llama-3.2-1B-Instruct"
+    _wire_unloaded_chat(monkeypatch, enabled = True, catalog = (resident,))
+    monkeypatch.setattr(
+        inference_route,
+        "get_inference_backend",
+        lambda: type("_B", (), {"active_model_name": resident, "models": {}})(),
+    )
+    with pytest.raises(HTTPException) as exc:
+        asyncio.run(
+            inference_route.openai_completions(
+                _json_body_request({"model": resident, "prompt": "hi"}), "tester"
+            )
+        )
+    assert exc.value.status_code == 503
+    assert exc.value.detail.startswith("No GGUF model loaded.")
+    assert "not downloaded" not in exc.value.detail
+
+
 def test_responses_stream_keeps_generic_error_when_target_is_local(monkeypatch):
     # Name resolves locally yet nothing is loaded: the switch failed, so the
     # generic text is right and the status stays 400, not a bogus "missing".
diff --git a/studio/frontend/src/features/settings/components/api-monitor-console.tsx b/studio/frontend/src/features/settings/components/api-monitor-console.tsx
index 0f07b4a95b2..27439399c35 100644
--- a/studio/frontend/src/features/settings/components/api-monitor-console.tsx
+++ b/studio/frontend/src/features/settings/components/api-monitor-console.tsx
@@ -547,7 +547,12 @@ export function ApiMonitorConsole(): ReactElement {
         )}
       </div>
 
-      {ordered.length > PAGE_SIZE ? (
+      {/* Also whenever a snapshot is frozen: the backend's 50-entry retention
+          window evicts frozen ids as new traffic arrives, so the frozen list can
+          shrink below one page (and eventually to nothing). Hiding the pager then
+          strands the console on a stale -- finally empty -- snapshot with no way
+          back to the live list short of closing the panel. */}
+      {ordered.length > PAGE_SIZE || frozenIds !== null ? (
         <div className="flex items-center justify-between gap-2 border-t border-border/60 px-4 py-2 text-xs text-muted-foreground">
           <span>
             Page {pageIndex + 1} of {pageCount}
@@ -559,7 +564,7 @@ export function ApiMonitorConsole(): ReactElement {
               size="sm"
               className="h-7 px-2 text-xs"
               onClick={() => goToPage(pageIndex - 1)}
-              disabled={pageIndex === 0}
+              disabled={pageIndex === 0 && frozenIds === null}
             >
               Newer
             </Button>
diff --git a/studio/frontend/src/features/settings/components/usage-examples.tsx b/studio/frontend/src/features/settings/components/usage-examples.tsx
index 6bd74f1371b..5acdb6911ae 100644
--- a/studio/frontend/src/features/settings/components/usage-examples.tsx
+++ b/studio/frontend/src/features/settings/components/usage-examples.tsx
@@ -329,8 +329,10 @@ function buildSnippets(
 }
 
 const KEY_PLACEHOLDER = "sk-unsloth-YOUR_KEY";
-const MODEL_FALLBACK = "unsloth/gemma-4-E4B-it-GGUF:UD-Q5_K_XL";
 const USE_TUNNEL_KEY = "unsloth_api_use_tunnel";
+// Slow retry while /v1 has nothing to name: a download or a load can finish
+// while this panel is open, and neither moves the checkpoint below.
+const CATALOG_RETRY_MS = 15000;
 
 function readUseTunnelPref(): boolean {
   if (typeof window === "undefined") return true;
@@ -364,34 +366,48 @@ function looksLikePath(id: string): boolean {
   );
 }
 
-// The model the examples name. With nothing loaded this used to print
-// MODEL_FALLBACK, a repo id the user likely never downloaded, so the copied
-// snippet 404d. Prefer a real id from the catalog /v1 resolves against; the
-// constant is only the floor for a server with no models, so it is never blank.
-function useExampleModelName(): string {
+// The model the examples name. With nothing loaded this used to print a
+// hardcoded repo id the user likely never downloaded, so the copied snippet
+// 404d. Only ever name an id /v1 resolves against; null means this server has
+// nothing to serve yet and the panel says so instead of printing a dead id.
+function useExampleModelName(): string | null {
   const checkpoint = useChatRuntimeStore((s) => s.params.checkpoint);
   const ggufVariant = useChatRuntimeStore((s) => s.activeGgufVariant);
-  const [catalog, setCatalog] = useState<OpenAIModel[]>([]);
+  // null until /v1/models answers: "not asked yet" must not read as "this
+  // server holds nothing", or the first render already picks a name.
+  const [catalog, setCatalog] = useState<OpenAIModel[] | null>(null);
   const usableCheckpoint =
     !!checkpoint && !checkpoint.startsWith("external::") && !looksLikePath(checkpoint);
   const needsCatalog = !usableCheckpoint;
 
   // Only when the checkpoint can't answer it: /v1/models scans the model dirs and
-  // HF caches. Re-runs when a model is loaded or unloaded.
+  // HF caches. Re-runs when a model is loaded or unloaded, and retries until the
+  // server reports something servable, since a download moves no store state.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: a load or unload must refetch the servable ids
   useEffect(() => {
     if (!needsCatalog) return;
     let cancelled = false;
-    void listOpenAIModels()
-      .then((models) => {
-        if (!cancelled) setCatalog(models);
-      })
-      .catch(() => {
-        // Best-effort: fall through to the placeholder.
-      });
+    let timeoutId: number | null = null;
+
+    const update = () => {
+      void listOpenAIModels()
+        .then((models) => {
+          if (!cancelled) setCatalog(models);
+          return models.length > 0;
+        })
+        .catch(() => false)
+        .then((resolved) => {
+          if (cancelled || resolved) return;
+          timeoutId = window.setTimeout(update, CATALOG_RETRY_MS);
+        });
+    };
+
+    update();
     return () => {
       cancelled = true;
+      if (timeoutId !== null) window.clearTimeout(timeoutId);
     };
-  }, [needsCatalog]);
+  }, [needsCatalog, checkpoint, ggufVariant]);
 
   return useMemo(() => {
     if (usableCheckpoint && checkpoint) {
@@ -403,9 +419,9 @@ function useExampleModelName(): string {
     // No usable checkpoint (none, an external provider, or a raw load path):
     // name something this server actually holds, quant included so the request
     // pins the file on disk instead of letting the server pick a quant.
-    const pick = catalog.find((m) => m.loaded) ?? catalog[0];
+    const pick = catalog?.find((m) => m.loaded) ?? catalog?.[0];
     if (!pick) {
-      return MODEL_FALLBACK;
+      return null;
     }
     return pick.quant && !pick.id.includes(":")
       ? `${pick.id}:${pick.quant}`
@@ -560,8 +576,9 @@ export function UsageExamples({ apiKey }: { apiKey?: string | null }) {
   const model = useExampleModelName();
   const key = apiKey || KEY_PLACEHOLDER;
 
+  // Null model: nothing is servable, so there is no snippet worth copying.
   const snippets = useMemo(
-    () => buildSnippets(base, key, model, os),
+    () => (model ? buildSnippets(base, key, model, os) : null),
     [base, key, model, os],
   );
   // Agent command must target the server the panel shows, not the :8888 default.
@@ -580,6 +597,7 @@ export function UsageExamples({ apiKey }: { apiKey?: string | null }) {
       : "python";
 
   const handleCopy = async () => {
+    if (!snippets) return;
     if (await copyToClipboard(snippets[lang])) {
       setCopied(true);
       setTimeout(() => setCopied(false), 1800);
@@ -723,25 +741,33 @@ export function UsageExamples({ apiKey }: { apiKey?: string | null }) {
             </button>
           </div>
         ) : null}
-        <div className="relative min-w-0">
-          <button
-            type="button"
-            onClick={handleCopy}
-            className="absolute right-2 top-2 z-10 flex items-center gap-1 rounded border border-border bg-background/80 px-1.5 py-1 text-ui-11 text-muted-foreground backdrop-blur transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
-            aria-label={t("settings.apiKeys.copySnippet")}
-          >
-            <HugeiconsIcon
-              icon={copied ? Tick02Icon : Copy01Icon}
-              className={cn("size-3.5", copied && "text-emerald-600")}
+        {snippets ? (
+          <div className="relative min-w-0">
+            <button
+              type="button"
+              onClick={handleCopy}
+              className="absolute right-2 top-2 z-10 flex items-center gap-1 rounded border border-border bg-background/80 px-1.5 py-1 text-ui-11 text-muted-foreground backdrop-blur transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+              aria-label={t("settings.apiKeys.copySnippet")}
+            >
+              <HugeiconsIcon
+                icon={copied ? Tick02Icon : Copy01Icon}
+                className={cn("size-3.5", copied && "text-emerald-600")}
+              />
+              {copied
+                ? t("settings.apiKeys.copied")
+                : t("settings.apiKeys.copy")}
+            </button>
+            <HighlightedCode
+              key={snippets[lang]}
+              code={snippets[lang]}
+              language={shikiLang}
             />
-            {copied ? t("settings.apiKeys.copied") : t("settings.apiKeys.copy")}
-          </button>
-          <HighlightedCode
-            key={snippets[lang]}
-            code={snippets[lang]}
-            language={shikiLang}
-          />
-        </div>
+          </div>
+        ) : (
+          <div className="min-w-0 px-3 py-2.5 text-ui-11 leading-snug text-muted-foreground">
+            {t("settings.apiKeys.usageNoModel")}
+          </div>
+        )}
         <div className="flex min-w-0 flex-col gap-1.5 border-t border-border px-3 py-2.5">
           <span className="text-ui-11 font-semibold text-foreground">
             {t("settings.apiKeys.codingAgents")}
diff --git a/studio/frontend/src/i18n/locales/en.ts b/studio/frontend/src/i18n/locales/en.ts
index bda564e4d7e..24bf9555376 100644
--- a/studio/frontend/src/i18n/locales/en.ts
+++ b/studio/frontend/src/i18n/locales/en.ts
@@ -722,6 +722,8 @@ export const en = {
       copyAccessToken: "Copy access token",
       copyNow: "Copy now - this won't be shown again.",
       usageExamples: "Usage examples",
+      usageNoModel:
+        "Load or download a model to see runnable examples. This server has no model to name yet.",
       usageTools: "Tools",
       exampleCurlTools: "curl + tools",
       examplePythonTools: "Python + tools",
diff --git a/tests/studio/test_usage_examples_model_source_contract.py b/tests/studio/test_usage_examples_model_source_contract.py
index 1224b93209a..8b93bbfcde4 100644
--- a/tests/studio/test_usage_examples_model_source_contract.py
+++ b/tests/studio/test_usage_examples_model_source_contract.py
@@ -4,6 +4,7 @@
 """Static contract for which model the API usage examples name, and for the
 model-auto-switch control living in exactly one place on the API keys tab."""
 
+import re
 from pathlib import Path
 
 REPO = Path(__file__).resolve().parents[2]
@@ -24,8 +25,8 @@ def test_examples_name_a_model_the_server_can_serve():
     hook = src[src.find("function useExampleModelName") : src.find("// Backend PATH detection")]
     assert "listOpenAIModels()" in hook
     # Precedence: live checkpoint, then a loaded catalog entry, then any entry,
-    # and only then the placeholder.
-    assert "catalog.find((m) => m.loaded) ?? catalog[0]" in hook
+    # and only then no model at all.
+    assert "catalog?.find((m) => m.loaded) ?? catalog?.[0]" in hook
     # The snippet pins the quant so the request names the file on disk.
     assert "`${pick.id}:${pick.quant}`" in hook
 
@@ -33,6 +34,42 @@ def test_examples_name_a_model_the_server_can_serve():
     assert 'authFetch("/v1/models")' in api
 
 
+def test_examples_never_print_a_hardcoded_model_id():
+    # The bug this contract exists for. The catalog started as `[]`, so the very
+    # first render, and every render after a slow or failed /v1/models fetch,
+    # printed a copyable snippet naming a repo id the server cannot serve. The
+    # catalog is tri-state now (null until /v1 answers) and the panel says to
+    # load or download a model rather than naming one that does not exist.
+    src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")
+    assert "MODEL_FALLBACK" not in src
+    # No repo-shaped literal anywhere: a snippet may only name what /v1 returns.
+    assert re.search(r'"unsloth/[^"]+"', src) is None
+    assert "function useExampleModelName(): string | null" in src
+    assert "useState<OpenAIModel[] | null>(null)" in src
+    # Nothing servable means nothing is built, so there is nothing to copy.
+    assert "(model ? buildSnippets(base, key, model, os) : null)" in src
+    assert "if (!snippets) return;" in src
+    assert "{snippets ? (" in src
+    assert 't("settings.apiKeys.usageNoModel")' in src
+
+    en = EN_TS.read_text(encoding = "utf-8")
+    assert "usageNoModel:" in en
+
+
+def test_catalog_refresh_follows_the_loaded_model():
+    # `[needsCatalog]` alone never re-ran: it stays true the whole time there is
+    # no local checkpoint, so a model finishing its load left the snippet naming
+    # whatever the first fetch happened to see.
+    src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")
+    hook = src[src.find("function useExampleModelName") : src.find("// Backend PATH detection")]
+    assert "}, [needsCatalog, checkpoint, ggufVariant]);" in hook
+    # A finishing download moves no store state at all, so the fetch also
+    # retries itself until /v1 has something, on a timer the effect clears.
+    assert "window.setTimeout(update, CATALOG_RETRY_MS)" in hook
+    assert "window.clearTimeout(timeoutId)" in hook
+    assert "const CATALOG_RETRY_MS = 15000;" in src
+
+
 def test_usage_examples_has_no_duplicate_auto_switch_control():
     # ModelAutoSwitchSection renders the same setting immediately below this
     # panel on the same tab, and the two do not share state, so a second switch

From d76f56d372f5d8e1888aebbba58be1bb27e508cf Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Sun, 26 Jul 2026 12:44:20 +0000
Subject: [PATCH 13/56] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 studio/backend/tests/test_openai_auto_switch.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index 394833a38bc..e3386e9a732 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -294,9 +294,9 @@ def test_openai_compat_routes_bound_to_handlers_with_auth():
     for key, handler in expected.items():
         assert key in seen, f"route {key} is not registered"
         route = seen[key]
-        assert route.endpoint.__name__ == handler, (
-            f"{key} bound to {route.endpoint.__name__}, expected {handler}"
-        )
+        assert (
+            route.endpoint.__name__ == handler
+        ), f"{key} bound to {route.endpoint.__name__}, expected {handler}"
         deps = [d.call.__name__ for d in route.dependant.dependencies]
         assert "get_current_subject" in deps, f"{key} lost its auth dependency"
 

From f913d33d56a3ee4cc3f2d24dddf6a112eaebe524 Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Sun, 26 Jul 2026 13:09:18 +0000
Subject: [PATCH 14/56] Studio: scope the auto-download 404 cache to the
 caller's credentials

The Hub answers 404 for a private repo the caller cannot see, so caching
that verdict per repo alone let one anonymous request mark a private repo
unservable for everyone for the whole TTL. A later caller sending a valid
X-Unsloth-HF-Token skipped the probe and fell through to the resident
model instead of downloading what it asked for. Keyed on the repo id plus
a digest of the token now, so the token itself is never held.

Two more from the same review:

- Clear the chat runtime checkpoint after unloading from the API monitor,
  as the chat eject flow already does. The store went on treating the
  freed checkpoint as loaded and the usage examples kept naming it.
- Point gated and not-found callers at the X-Unsloth-HF-Token header.
  Automatic download deliberately ignores the server's own Hugging Face
  identity, so telling the user to add a token in Studio sent them round
  the same 403 forever.
---
 .../core/inference/openai_auto_download.py    | 37 ++++++++++++++-----
 .../tests/test_openai_auto_download.py        | 33 +++++++++++++++++
 .../components/api-monitor-console.tsx        |  4 ++
 3 files changed, 64 insertions(+), 10 deletions(-)

diff --git a/studio/backend/core/inference/openai_auto_download.py b/studio/backend/core/inference/openai_auto_download.py
index a65bd70853b..bd6d0bce874 100644
--- a/studio/backend/core/inference/openai_auto_download.py
+++ b/studio/backend/core/inference/openai_auto_download.py
@@ -131,15 +131,28 @@ def looks_like_quant(variant: Optional[str]) -> bool:
     return _GGUF_KNOWN_QUANT_RE.fullmatch(variant.strip()) is not None
 
 
-def _mark_not_servable(repo_id: str) -> None:
+def _servable_key(repo_id: str, hf_token: Optional[str]) -> str:
+    """Cache key, per credential.
+
+    The Hub answers 404 for a private repo the caller cannot see, so a verdict
+    reached without a token says nothing about a caller who has one. Keyed on a
+    digest so the token itself is never held here.
+    """
+    import hashlib
+
+    seen_as = hashlib.sha256(hf_token.encode()).hexdigest()[:16] if hf_token else "anon"
+    return f"{repo_id.lower()}\n{seen_as}"
+
+
+def _mark_not_servable(repo_id: str, hf_token: Optional[str]) -> None:
     with _cache_lock:
         if len(_not_servable) >= _NOT_SERVABLE_MAX:
             _not_servable.clear()
-        _not_servable[repo_id.lower()] = time.monotonic() + _NOT_SERVABLE_TTL_S
+        _not_servable[_servable_key(repo_id, hf_token)] = time.monotonic() + _NOT_SERVABLE_TTL_S
 
 
-def _is_not_servable(repo_id: str) -> bool:
-    key = repo_id.lower()
+def _is_not_servable(repo_id: str, hf_token: Optional[str]) -> bool:
+    key = _servable_key(repo_id, hf_token)
     with _cache_lock:
         expires = _not_servable.get(key)
         if expires is None:
@@ -155,8 +168,9 @@ def _gated_refusal(repo_id: str) -> AutoDownloadRefusal:
         status = 403,
         code = "model_access_denied",
         message = (
-            f"'{repo_id}' is gated on Hugging Face. Accept its licence and add an "
-            "access token in Unsloth Studio, then retry."
+            f"'{repo_id}' is gated on Hugging Face. Accept its licence, then retry with "
+            "your own token in the X-Unsloth-HF-Token header: automatic download never "
+            "uses this server's Hugging Face identity."
         ),
     )
 
@@ -341,7 +355,7 @@ async def maybe_auto_download(
     repo_id, wanted_variant = split_model_ref(requested_model)
     if not is_downloadable_ref(requested_model):
         return None
-    if _is_not_servable(repo_id) and not looks_like_quant(wanted_variant):
+    if _is_not_servable(repo_id, hf_token) and not looks_like_quant(wanted_variant):
         return None
 
     # Adopt or reject against the single in-flight slot before touching the
@@ -429,7 +443,7 @@ def _probe():
         if status == 403:
             return _gated_refusal(repo_id)
         if status == 404:
-            _mark_not_servable(repo_id)
+            _mark_not_servable(repo_id, hf_token)
             # An id the Hub does not know is a foreign label, not a miss: pass it
             # to the resident model as before rather than 404 every LiteLLM and
             # OpenRouter "vendor/model". An explicit quant is a deliberate GGUF
@@ -440,7 +454,10 @@ def _probe():
             return AutoDownloadRefusal(
                 status = 404,
                 code = "model_not_found",
-                message = f"'{repo_id}' was not found on Hugging Face, or is not accessible.",
+                message = (
+                    f"'{repo_id}' was not found on Hugging Face, or is not accessible. "
+                    "If it is private, send a token in the X-Unsloth-HF-Token header."
+                ),
             )
         logger.warning("auto-download: Hub lookup failed for %r: %s", repo_id, exc)
         return AutoDownloadRefusal(
@@ -460,7 +477,7 @@ def _probe():
     variants = _gguf_variants(getattr(info, "siblings", None))
     if not variants:
         _release(active)
-        _mark_not_servable(repo_id)
+        _mark_not_servable(repo_id, hf_token)
         if not looks_like_quant(wanted_variant):
             return None
         return AutoDownloadRefusal(
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index 8cfef1e85d6..33705b50653 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -293,6 +293,39 @@ def test_a_foreign_id_is_probed_once_then_cached(hub):
     assert hub["probes"] == 1
 
 
+def test_an_anonymous_404_does_not_silence_an_authorised_caller(hub):
+    # The Hub answers 404 for a private repo the caller cannot see, so caching
+    # that verdict globally would let one anonymous request hide a private repo
+    # from the token holder for the whole TTL.
+    hub["raise"] = _hub_error(_repo_not_found_error(), 404, "nope")
+    assert _run("myorg/private-GGUF") is None
+    assert hub["probes"] == 1
+
+    hub["raise"] = None
+    refusal = _run("myorg/private-GGUF", hf_token = "hf_caller_own")
+    assert hub["probes"] == 2
+    assert refusal.code == "model_downloading"
+
+
+def test_the_cache_is_per_token(hub):
+    hub["raise"] = _hub_error(_repo_not_found_error(), 404, "nope")
+    assert _run("myorg/private-GGUF", hf_token = "hf_a") is None
+    assert _run("myorg/private-GGUF", hf_token = "hf_a") is None
+    assert hub["probes"] == 1
+    # A different credential gets its own verdict.
+    assert _run("myorg/private-GGUF", hf_token = "hf_b") is None
+    assert hub["probes"] == 2
+
+
+def test_the_gated_message_names_the_header_that_actually_works(hub):
+    # Auto-download never uses the server's ambient token, so pointing the
+    # caller at a Studio setting would loop them on the same 403.
+    hub["info"] = _Info(_gguf_repo_info().siblings, gated = "manual")
+    hub["auth_denied"] = True
+    refusal = _run("meta-llama/Llama-2-7b-hf")
+    assert "X-Unsloth-HF-Token" in refusal.message
+
+
 def test_gated_repo_is_403(hub):
     hub["raise"] = _hub_error(_gated_error(), 403, "gated")
     refusal = _run("meta-llama/Llama-2-7b-hf")
diff --git a/studio/frontend/src/features/settings/components/api-monitor-console.tsx b/studio/frontend/src/features/settings/components/api-monitor-console.tsx
index 27439399c35..77f1e2492dd 100644
--- a/studio/frontend/src/features/settings/components/api-monitor-console.tsx
+++ b/studio/frontend/src/features/settings/components/api-monitor-console.tsx
@@ -25,6 +25,7 @@ import {
   unloadModel,
 } from "../../chat/api/chat-api";
 import { resolveInferenceCheckpointId } from "../../chat/lib/apply-inference-status-to-store";
+import { useChatRuntimeStore } from "../../chat/stores/chat-runtime-store";
 import type { ApiMonitorEntry, ApiMonitorResponse } from "../../chat/types/api";
 
 const API_INFERENCE_PREFIX_RE = /^\/api\/inference/;
@@ -292,6 +293,9 @@ export function ApiMonitorConsole(): ReactElement {
         return;
       }
       await unloadModel({ model_path: checkpoint });
+      // Same as the chat eject flow: the store still holds the checkpoint this
+      // just freed, and the usage examples would keep naming it.
+      useChatRuntimeStore.getState().clearCheckpoint();
       setError(null);
       await loadMonitor();
     } catch (err: unknown) {

From 014e1fb588e87031cfd07c9e8925d116e80810d9 Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Sun, 26 Jul 2026 13:27:31 +0000
Subject: [PATCH 15/56] Studio: tighten the comments added by this branch

---
 studio/backend/auth/authentication.py         |  3 +-
 studio/backend/core/inference/api_monitor.py  | 11 +--
 .../backend/core/inference/llama_keepwarm.py  |  4 +-
 .../core/inference/openai_auto_download.py    | 60 +++++--------
 studio/backend/routes/inference.py            | 60 +++++--------
 studio/backend/routes/settings.py             |  3 +-
 studio/backend/tests/test_api_monitor.py      |  6 +-
 studio/backend/tests/test_model_ids.py        |  3 +-
 .../tests/test_openai_auto_download.py        | 86 ++++++++-----------
 .../backend/tests/test_openai_auto_switch.py  | 60 +++++--------
 studio/backend/tests/test_openai_catalog.py   | 12 +--
 .../frontend/src/features/chat/types/api.ts   |  4 +-
 .../settings/api/openai-auto-switch.ts        |  4 +-
 .../features/settings/api/openai-models.ts    |  8 +-
 .../components/api-monitor-console.tsx        | 33 +++----
 .../settings/components/usage-examples.tsx    | 33 +++----
 ...st_usage_examples_model_source_contract.py | 45 ++++------
 17 files changed, 164 insertions(+), 271 deletions(-)

diff --git a/studio/backend/auth/authentication.py b/studio/backend/auth/authentication.py
index cdb2b897c50..2481cd13e64 100644
--- a/studio/backend/auth/authentication.py
+++ b/studio/backend/auth/authentication.py
@@ -164,8 +164,7 @@ async def get_current_subject_allow_password_change(
     )
 
 
-# The literal the copyable API examples ship with. Pasting a snippet unedited is
-# a much likelier mistake than a revoked key, so say so instead of "invalid".
+# The literal the examples ship with; pasting one unedited is likelier than a revoked key.
 API_KEY_PLACEHOLDER = f"{API_KEY_PREFIX}YOUR_KEY"
 
 
diff --git a/studio/backend/core/inference/api_monitor.py b/studio/backend/core/inference/api_monitor.py
index d84de3ab2bc..a28210caf23 100644
--- a/studio/backend/core/inference/api_monitor.py
+++ b/studio/backend/core/inference/api_monitor.py
@@ -52,9 +52,8 @@ class ApiMonitorEntry:
     total_tokens: Optional[int] = None
     total_tokens_authoritative: bool = False
     error: Optional[str] = None
-    # "request" (an HTTP call) or "lifecycle" (a model load/unload). Lifecycle
-    # rows carry event/reason instead of a prompt and are server-wide, so they
-    # are shared across subjects rather than owned by the caller that caused them.
+    # "request" (an HTTP call) or "lifecycle" (a model load/unload). Lifecycle rows carry
+    # event/reason instead of a prompt, and are server-wide so every subject sees them.
     kind: str = "request"
     event: Optional[str] = None
     reason: Optional[str] = None
@@ -304,8 +303,7 @@ def fail_open(self, entry_id: Optional[str], error: str) -> None:
             entry = self._find_locked(entry_id)
             if entry is None or entry.finished_at is not None:
                 return
-            # Same lock as the check: a finish() landing in between would
-            # otherwise stamp this error onto a row that in fact succeeded.
+            # Same lock as the check, so a finish() cannot land in between.
             self._fail_locked(entry, error)
 
     def fail(self, entry_id: Optional[str], error: str) -> None:
@@ -361,8 +359,7 @@ def get(
             return entry.snapshot(include_details = True)
 
     def active_count(self, *, subject: Optional[str] = None) -> int:
-        # Lifecycle rows are excluded: a load in progress is "running" so the row
-        # can show as live, but it is not an in-flight API request.
+        # Lifecycle rows show as "running" while loading but are not in-flight API requests.
         with self._lock:
             return sum(
                 1
diff --git a/studio/backend/core/inference/llama_keepwarm.py b/studio/backend/core/inference/llama_keepwarm.py
index 44ce54d8ba5..88ea5360cc6 100644
--- a/studio/backend/core/inference/llama_keepwarm.py
+++ b/studio/backend/core/inference/llama_keepwarm.py
@@ -423,8 +423,8 @@ async def idle_unload_loop(poll_seconds: float = 15.0) -> None:
                     elif manifest:
                         _delete_resume_files(manifest)
                     logger.info("Idle auto-unload: freed GGUF after %ss idle", ttl)
-                    # This path deliberately skips note_model_unloaded (an idle
-                    # unload stashes for reload), so record the monitor row here.
+                    # This path skips note_model_unloaded (an idle unload stashes for
+                    # reload), so record the monitor row here.
                     _note_idle_unload_event(freed)
                     seen_model = None
         except Exception as exc:
diff --git a/studio/backend/core/inference/openai_auto_download.py b/studio/backend/core/inference/openai_auto_download.py
index bd6d0bce874..e58a7a3a481 100644
--- a/studio/backend/core/inference/openai_auto_download.py
+++ b/studio/backend/core/inference/openai_auto_download.py
@@ -37,8 +37,7 @@
 
 logger = get_logger(__name__)
 
-# Hub metadata is one small request; keep it short so a slow Hub can't stall the
-# request path for long.
+# Keep the Hub probe short so a slow Hub can't stall the request path.
 _MODEL_INFO_TIMEOUT_S = 8.0
 # Headroom left free after the download, so filling the disk can't wedge the box.
 _DISK_RESERVE_BYTES = 5 * 1024**3
@@ -73,9 +72,8 @@ class _Active:
 _lock = threading.Lock()
 _active: Optional[_Active] = None
 
-# Repos the Hub says this server cannot serve. A LiteLLM or OpenRouter client
-# names every provider "vendor/model", so without this each such request pays
-# another Hub probe on the way to being answered by the resident model.
+# Repos the Hub says this server cannot serve. Without it, every LiteLLM or OpenRouter
+# "vendor/model" request pays a Hub probe before falling through to the resident model.
 _NOT_SERVABLE_TTL_S = 10 * 60
 _NOT_SERVABLE_MAX = 256
 _cache_lock = threading.Lock()
@@ -248,8 +246,7 @@ async def _job_state(repo_id: str, variant: Optional[str]) -> tuple[str, Optiona
         status = await downloads.get_download_status_response(repo_id, variant or "")
         return status.state, status.error
     except Exception as exc:
-        # "unknown", not "idle": a probe that failed says nothing about the
-        # worker, and idle is read as "the job vanished" and ends the watch.
+        # "unknown", not "idle": idle ends the watch, and a failed probe proves nothing.
         logger.debug("auto-download: status probe failed for %r: %s", repo_id, exc)
         return "unknown", None
 
@@ -301,8 +298,7 @@ async def _watch(active: _Active, hf_token: Optional[str]) -> None:
             await asyncio.sleep(_WATCH_POLL_S)
             state, error = await _job_state(active.repo_id, active.variant)
             if state in ("running", "cancelling", "unknown"):
-                # Only "running" has progress to report; the other two are still
-                # in flight, so keep the slot rather than failing the row.
+                # Only "running" has progress; the others are still in flight, so keep the slot.
                 if state == "running":
                     api_monitor.set_progress(
                         active.monitor_id,
@@ -312,8 +308,7 @@ async def _watch(active: _Active, hf_token: Optional[str]) -> None:
                     )
                 continue
             if state == "complete":
-                # Drop the 5s resolver cache so the next retry resolves the new
-                # model instead of missing it again.
+                # Drop the resolver cache so the next retry sees the new model.
                 await asyncio.to_thread(invalidate_index)
                 api_monitor.finish(active.monitor_id, status = "completed")
             elif state == "idle":
@@ -358,8 +353,8 @@ async def maybe_auto_download(
     if _is_not_servable(repo_id, hf_token) and not looks_like_quant(wanted_variant):
         return None
 
-    # Adopt or reject against the single in-flight slot before touching the
-    # network, so retries during a long download stay free.
+    # Adopt or reject against the single in-flight slot before touching the network, so
+    # retries during a long download stay free.
     with _lock:
         current = _active
         if current is not None and current.repo_id == repo_id:
@@ -399,8 +394,7 @@ async def maybe_auto_download(
         if adopted.variant is None:
             # Another request is still probing this same repo.
             return _downloading_refusal(adopted.repo_id, None)
-        # complete/idle/cancelled: the watcher is about to release the slot, so
-        # ask for one more retry. Only "complete" actually got there.
+        # complete/idle/cancelled: the watcher is about to free the slot, so retry once more.
         return _downloading_refusal(
             _public_label(adopted.repo_id, adopted.variant),
             100.0 if state == "complete" else None,
@@ -411,11 +405,8 @@ async def maybe_auto_download(
             repo_id, wanted_variant, requested_model, hf_token, provisional
         )
     except BaseException:
-        # BaseException, not Exception: asyncio.CancelledError has not been an
-        # Exception since 3.8, so a request cancelled mid-probe would otherwise
-        # leave the provisional slot installed with variant None -- every other
-        # repo permanently model_download_busy and this one permanently
-        # "downloading", until the process restarts.
+        # BaseException, not Exception: CancelledError is not an Exception, so a request
+        # cancelled mid-probe would otherwise wedge the provisional slot until restart.
         _release(provisional)
         raise
 
@@ -444,10 +435,8 @@ def _probe():
             return _gated_refusal(repo_id)
         if status == 404:
             _mark_not_servable(repo_id, hf_token)
-            # An id the Hub does not know is a foreign label, not a miss: pass it
-            # to the resident model as before rather than 404 every LiteLLM and
-            # OpenRouter "vendor/model". An explicit quant is a deliberate GGUF
-            # reference, so that one is answered.
+            # An id the Hub does not know is a foreign label, not a miss: fall through to the
+            # resident model. An explicit quant is a deliberate GGUF reference, so answer it.
             if not looks_like_quant(wanted_variant):
                 return None
             # A private repo reads as absent without a token; don't confirm either way.
@@ -468,9 +457,8 @@ def _probe():
         )
 
     if getattr(info, "gated", False) and await asyncio.to_thread(_auth_denied, repo_id, hf_token):
-        # The Hub serves metadata for a gated repo without granting its files, so
-        # a probe that returned is not proof of access. Left unchecked the config
-        # read below fails instead and reports the unrelated custom-code refusal.
+        # The Hub serves metadata for a gated repo without granting its files, so a probe that
+        # returned is not proof of access. Unchecked, the config read below misreports it.
         _release(active)
         return _gated_refusal(repo_id)
 
@@ -489,9 +477,8 @@ def _probe():
             ),
         )
 
-    # trust_remote_code gate. _config_has_auto_map is tri-state: refuse on True
-    # and on None (unreadable), rather than _requires_trust_remote_code_for_model,
-    # which swallows errors into False. Fine as a UI hint, wrong as an admission.
+    # trust_remote_code gate. _config_has_auto_map is tri-state, so refuse on True and on None
+    # (unreadable); _requires_trust_remote_code_for_model swallows errors into False.
     from utils.security.consent import _config_has_auto_map
 
     has_auto_map = await asyncio.to_thread(_config_has_auto_map, repo_id, hf_token)
@@ -555,8 +542,7 @@ def _match_variant(wanted: Optional[str], variants: dict[str, int]) -> Optional[
         return lowered.get(wanted.strip().lower())
     from utils.models.model_config import _pick_best_gguf
 
-    # _pick_best_gguf ranks filenames by quant substring, so give it synthesized
-    # "<label>.gguf" names and take the label back off the winner.
+    # _pick_best_gguf ranks filenames, so feed it "<label>.gguf" and strip the suffix back off.
     best = _pick_best_gguf([f"{name}.gguf" for name in variants])
     return best[: -len(".gguf")] if best else None
 
@@ -599,11 +585,8 @@ async def _dispatch(
             message = f"Could not start downloading '{requested_model}'.",
         )
 
-    # A same-repo whole-repo/cross-transport download or an in-progress delete
-    # makes the service refuse *without* raising: it returns accepted=False and
-    # launches no worker. Taking the slot then would promise a download that does
-    # not exist, and the watcher would fail its own monitor row two seconds later
-    # on a key that is idle by construction. Report the conflict instead.
+    # The service can refuse without raising (accepted=False, no worker launched). Taking the
+    # slot would promise a download that does not exist, so report the conflict instead.
     if isinstance(dispatched, dict) and not dispatched.get("accepted", True):
         _release(active)
         logger.info("auto-download: dispatch refused for %s (%s)", label, dispatched.get("state"))
@@ -619,8 +602,7 @@ async def _dispatch(
             active.monitor_id = monitor_id
             tracked = active
         else:
-            # Released underneath us: still track the job we just started so its
-            # monitor row resolves, but never stomp a newer owner of the slot.
+            # Released underneath us: track the job we started, but never stomp a newer owner.
             tracked = _Active(repo_id, variant, expected_bytes, monitor_id, time.time())
             if _active is None:
                 _active = tracked
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 5de18727fd7..7d32c7fa9ea 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3586,8 +3586,7 @@ def _no_model_loaded_detail(base: str) -> str:
     )
 
 
-# Cap on ids listed by a "not downloaded" error: useful in a terminal without
-# burying the message.
+# Cap on ids listed by a "not downloaded" error, so it stays readable in a terminal.
 _MAX_LISTED_AVAILABLE_MODELS = 8
 
 
@@ -3672,14 +3671,11 @@ async def _no_model_loaded_error(
         return status, _no_model_loaded_detail(base)
     try:
         if _loaded_satisfies(named):
-            # The named model IS resident, just not on a backend this endpoint can
-            # use (a Transformers model on a GGUF-only surface). "Not downloaded"
-            # would be false, and the catalog GET /v1/models serves lists this very
-            # id as available, so keep the generic diagnosis, which is accurate.
+            # Resident, just not on a backend this endpoint can use (a Transformers model
+            # on a GGUF-only surface). "Not downloaded" would be false, so stay generic.
             return status, _no_model_loaded_detail(base)
         if await asyncio.to_thread(resolve_local_gguf, named) is not None:
-            # Resolvable but unloaded: the switch failed (load error, race), which
-            # the generic text describes correctly.
+            # Resolvable but unloaded: the switch failed, which the generic text covers.
             return status, _no_model_loaded_detail(base)
         message = await _unavailable_model_message(named)
     except Exception as exc:
@@ -3793,9 +3789,8 @@ def _loaded_satisfies(requested: str) -> bool:
     active = getattr(get_inference_backend(), "active_model_name", None)
     if not active:
         return False
-    # Only llama.cpp carries a quant identity, so this backend cannot show that
-    # an explicit quant is what is loaded. A non-quant tag is not a claim about
-    # the weights, so it still matches on the repo alone.
+    # Only llama.cpp carries a quant identity, so this backend cannot confirm an explicit
+    # quant. A non-quant tag claims nothing about the weights, so it matches on the repo.
     if looks_like_quant(variant):
         return False
     return base in {active.lower(), (public_model_id(active) or "").lower()}
@@ -3844,8 +3839,8 @@ async def _reject_unservable_model(
         )
         switchable = downloaded and get_openai_auto_switch_enabled()
     except Exception as exc:
-        # Can't verify. An explicit quant is still proof the caller meant this
-        # server, so refuse; anything else may be a foreign label, so let it by.
+        # Can't verify: an explicit quant still proves intent, so refuse; anything else
+        # may be a foreign label, so let it by.
         logger.debug("unservable-model check failed for %r: %s", requested_model, exc)
         if not quantified:
             return
@@ -3853,8 +3848,8 @@ async def _reject_unservable_model(
     if not (quantified or here):
         return
     if switchable:
-        # On disk and switching is allowed, so the swap itself failed. Answering
-        # as the resident model would be the wrong weights under the right name.
+        # On disk and switching allowed, so the swap failed. Answering as the resident
+        # model would be the wrong weights under the right name.
         status_code, code = 503, "model_switch_failed"
         message = (
             f"The model '{requested_model}' is downloaded, but this server could not "
@@ -3929,8 +3924,7 @@ async def _maybe_auto_switch_model(
     # loop freed is restored on the next request. The resolver-based switch still
     # requires the auto-switch toggle.
     if not auto_switch_on and get_auto_unload_idle_seconds() <= 0:
-        # No switching to do, but a named model still must not be answered by a
-        # different one.
+        # No switching to do, but a named model must still not be answered by another.
         await _reject_unservable_model(requested_model, fastapi_request)
         return
 
@@ -3945,8 +3939,8 @@ async def _resolve_and_switch() -> None:
             else None
         )
         if resolved is None:
-            # Not on disk. Opt-in: fetch it in the background and tell the caller to
-            # retry, rather than silently answering from whatever is resident.
+            # Not on disk. Opt-in: fetch in the background and ask the caller to retry,
+            # rather than silently answering from whatever is resident.
             if auto_switch_on and not reload_only:
                 await _maybe_auto_download_model(requested_model, fastapi_request)
             # Idle-unload may have freed the model; reload exactly what it freed
@@ -4079,8 +4073,7 @@ def _record_serving_alias() -> None:
                 _note_switch_waiter(key, -1)
 
     await _resolve_and_switch()
-    # The switch may have missed (not downloaded, or a swap that failed): refuse
-    # rather than let the handler answer as whatever is still resident.
+    # The switch may have missed, so refuse rather than answer as whatever is resident.
     await _reject_unservable_model(requested_model, fastapi_request)
 
 
@@ -4631,9 +4624,8 @@ async def _load_model_impl(
     # sampled step logs even if it reports 100% immediately (cached/small load).
     _reset_load_progress_step()
 
-    # Open a live "loading" row in the API monitor. Discarded below if the model
-    # turned out to be already loaded, relabelled once the real id is known, and
-    # closed on every exit by the handlers at the end of this function.
+    # Open a live "loading" row: discarded below if already loaded, relabelled once the
+    # real id is known, and closed on every exit by the handlers at the end of this function.
     _load_event = api_monitor.record_lifecycle(
         event = "load",
         model = _lifecycle_model_label(request.model_path, request.gguf_variant),
@@ -5349,8 +5341,7 @@ async def _attempt_gguf_load(
         raise HTTPException(status_code = 500, detail = f"Failed to load model: {msg}")
     finally:
         gguf_load_stack.close()
-        # Catch-all: any exit that did not already close or discard the row (an
-        # error, or a cancelled load) leaves it stuck "loading" otherwise.
+        # Catch-all: an error or cancelled load would otherwise leave the row "loading".
         api_monitor.fail_open(_load_event, "Load did not complete")
 
 
@@ -5968,8 +5959,7 @@ async def unload_model(request: UnloadRequest, current_subject: str = Depends(ge
                 )
                 or not llama_backend.is_loaded
             ):
-                # Read the identity before the teardown clears it, so the row reads
-                # repo:QUANT like the matching load row rather than a bare path.
+                # Read the identity before teardown clears it, so the row reads repo:QUANT.
                 _unloaded = _llama_public_model_id(llama_backend, request.model_path)
                 _unloaded_variant = getattr(llama_backend, "hf_variant", None)
                 # A manual unload is a deliberate user action: tear down now even if a
@@ -6250,9 +6240,8 @@ async def get_status(current_subject: str = Depends(get_current_subject)):
             ):
                 _display_model_id = os.path.basename(_model_id)
             elif not _native_grant_backed and _display_model_id == _model_id:
-                # Not a leased native path, so no label was registered and the raw
-                # identifier came back. Report the clean public id instead: an HF
-                # cache load would otherwise show the snapshot's commit sha.
+                # No label was registered, so the raw identifier came back. Report the clean
+                # public id: an HF cache load would otherwise show the snapshot's commit sha.
                 _display_model_id = _llama_public_model_id(llama_backend) or _display_model_id
             _inference_cfg = load_inference_config(_model_id) if _model_id else None
             _audio_type = getattr(llama_backend, "_audio_type", None)
@@ -10958,8 +10947,7 @@ async def _openai_catalog_objects() -> list[dict]:
     from core.inference.local_model_resolver import local_gguf_quants
 
     catalog = await _cached_local_catalog()
-    # One scan yields both "is this servable" and its on-disk quants, so an entry
-    # can advertise the quant to name without a second pass over the model dirs.
+    # One scan yields both "is this servable" and its on-disk quants, so no second pass.
     servable = await asyncio.to_thread(
         lambda: [(i, q) for i in catalog if (q := local_gguf_quants(i)) is not None]
     )
@@ -10974,8 +10962,7 @@ async def _openai_catalog_objects() -> list[dict]:
             "owned_by": _OWNED_BY,
             "loaded": False,
         }
-        # Bare label (never a filename or path): the id stays bare for OpenAI
-        # compat, and a client appends ":<quant>" to pin this exact quant.
+        # The id stays bare for OpenAI compat; a client appends ":<quant>" to pin one.
         if quants:
             obj["quant"] = quants[0]
         display = getattr(info, "display_name", None)
@@ -13404,8 +13391,7 @@ async def anthropic_messages(
     # before any request-shape check, exactly as the pre-feature endpoint did. When
     # an automatic load can run (auto-switch or a standalone idle TTL), fall through
     # so validation runs before the reload hook gets a chance to restore the model.
-    # Plain detail, not _no_model_loaded_error: no automatic load was possible, the
-    # case that helper leaves unchanged. The 404 comes from the post-switch check below.
+    # Plain detail, not _no_model_loaded_error: that helper leaves this case unchanged.
     if not llama_backend.is_loaded and not _automatic_model_load_may_run():
         raise HTTPException(
             status_code = 503,
diff --git a/studio/backend/routes/settings.py b/studio/backend/routes/settings.py
index 91bcb89add3..7770c12a8a4 100644
--- a/studio/backend/routes/settings.py
+++ b/studio/backend/routes/settings.py
@@ -126,8 +126,7 @@ class OpenAIAutoSwitchResponse(BaseModel):
     # is false, so the UI can show idle-unload as active instead of "needs enable".
     idle_unload_active: bool = False
     auto_unload_keep_kv: bool = DEFAULT_AUTO_UNLOAD_KEEP_KV
-    # Stored, not effective: it only takes effect while auto-switch is on, but the
-    # UI must round-trip the saved value across an auto-switch toggle.
+    # Stored, not effective: the UI must round-trip the saved value across an auto-switch toggle.
     auto_download_model: bool = DEFAULT_OPENAI_AUTO_DOWNLOAD_ENABLED
 
 
diff --git a/studio/backend/tests/test_api_monitor.py b/studio/backend/tests/test_api_monitor.py
index 6a7b228f59d..7dd4baa2dd4 100644
--- a/studio/backend/tests/test_api_monitor.py
+++ b/studio/backend/tests/test_api_monitor.py
@@ -290,8 +290,7 @@ def test_lifecycle_unload_row_is_terminal_on_arrival():
 
 
 def test_lifecycle_rows_are_visible_to_every_subject():
-    # A load is server-wide, not owned by whoever happened to trigger it, so it
-    # must not vanish for other API keys the way a request does.
+    # A load is server-wide, so it must not vanish for other API keys like a request does.
     monitor = ApiMonitor(max_entries = 5)
     monitor.start(
         endpoint = "/v1/chat/completions",
@@ -331,8 +330,7 @@ def test_discard_drops_a_row_that_never_happened():
 
 
 def test_fail_open_never_touches_a_finished_row():
-    # The load path calls this from a finally, so it must not stamp an error onto
-    # a load that in fact succeeded.
+    # Called from a finally, so it must not stamp an error onto a load that succeeded.
     monitor = ApiMonitor(max_entries = 5)
     event_id = monitor.record_lifecycle(event = "load", model = "org/A-GGUF", running = True)
     monitor.finish(event_id)
diff --git a/studio/backend/tests/test_model_ids.py b/studio/backend/tests/test_model_ids.py
index 50c89d9ec12..38392c3906c 100644
--- a/studio/backend/tests/test_model_ids.py
+++ b/studio/backend/tests/test_model_ids.py
@@ -40,8 +40,7 @@ def test_directory_path_uses_basename():
 def test_hf_cache_snapshot_recovers_the_repo_id():
     from core.inference.model_ids import hf_cache_repo_id
 
-    # The snapshot basename is a commit sha, so plain basename() would label a
-    # cache-loaded model "c1ac76e9...". Recover org/name instead.
+    # The snapshot basename is a commit sha, so recover org/name instead.
     snapshot = (
         "/home/u/.cache/huggingface/hub/models--unsloth--gemma-4-31B-it-GGUF"
         "/snapshots/c1ac76e99d5513b141e8adde7288b85c3f9c32ec"
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index 33705b50653..f6c39f2bcb1 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -106,8 +106,7 @@ def hub(monkeypatch):
         "auto_map": False,
         "started": [],
         "watched": [],
-        # What the hub download service hands back. accepted=False means it
-        # refused the claim and launched no worker.
+        # What the hub service returns; accepted=False means no worker was launched.
         "dispatch_result": {"job_key": "k", "state": "running", "accepted": True},
         "on_probe": None,
         "probes": 0,
@@ -199,8 +198,7 @@ def test_gguf_variants_skips_companions():
     variants = auto_dl._gguf_variants(_gguf_repo_info().siblings)
     # Companions are not quants of their own...
     assert set(variants) == {"UD-Q4_K_XL", "UD-Q5_K_XL", "Q8_0"}
-    # ...but the worker fetches them with every quant, so the disk reserve has
-    # to count them. Shards of one quant sum together on top of that.
+    # ...but every quant fetches them, so they count, and shards sum on top.
     companions = 2 * 1024**3  # mmproj + MTP drafter
     assert variants["Q8_0"] == 8 * 1024**3 + companions
     assert variants["UD-Q4_K_XL"] == 4 * 1024**3 + companions
@@ -272,9 +270,8 @@ def test_missing_repo_is_404_without_confirming_existence(hub):
 
 def test_an_id_the_hub_does_not_know_falls_through(hub):
     hub["raise"] = _hub_error(_repo_not_found_error(), 404, "nope")
-    # LiteLLM and OpenRouter name every provider "vendor/model". A namespace is
-    # not intent, so an id the Hub has never heard of stays a foreign label and
-    # the resident model answers it, exactly as before this feature existed.
+    # LiteLLM and OpenRouter name every provider "vendor/model", so a namespace is not
+    # intent: an id the Hub never heard of stays a foreign label the resident model answers.
     for foreign in (
         "anthropic/claude-3.5-sonnet",
         "openai/gpt-4o",
@@ -294,9 +291,8 @@ def test_a_foreign_id_is_probed_once_then_cached(hub):
 
 
 def test_an_anonymous_404_does_not_silence_an_authorised_caller(hub):
-    # The Hub answers 404 for a private repo the caller cannot see, so caching
-    # that verdict globally would let one anonymous request hide a private repo
-    # from the token holder for the whole TTL.
+    # The Hub 404s a private repo the caller cannot see, so caching that verdict globally
+    # would let one anonymous request hide it from the token holder for the whole TTL.
     hub["raise"] = _hub_error(_repo_not_found_error(), 404, "nope")
     assert _run("myorg/private-GGUF") is None
     assert hub["probes"] == 1
@@ -318,8 +314,8 @@ def test_the_cache_is_per_token(hub):
 
 
 def test_the_gated_message_names_the_header_that_actually_works(hub):
-    # Auto-download never uses the server's ambient token, so pointing the
-    # caller at a Studio setting would loop them on the same 403.
+    # Auto-download never uses the server's token, so naming a Studio setting would loop
+    # the caller on the same 403.
     hub["info"] = _Info(_gguf_repo_info().siblings, gated = "manual")
     hub["auth_denied"] = True
     refusal = _run("meta-llama/Llama-2-7b-hf")
@@ -334,9 +330,8 @@ def test_gated_repo_is_403(hub):
 
 
 def test_a_gated_repo_that_still_returns_metadata_is_403(hub):
-    # The Hub serves metadata for a gated repo without granting its files, so a
-    # probe that returned is not access. Reported as the licence gate it is, not
-    # as the custom-code refusal the unreadable config would otherwise produce.
+    # Metadata for a gated repo is not file access, so report the licence gate rather than
+    # the custom-code refusal the unreadable config would otherwise produce.
     hub["info"] = _Info(_gguf_repo_info().siblings, gated = "manual")
     hub["auth_denied"] = True
     refusal = _run("meta-llama/Llama-2-7b-hf")
@@ -383,8 +378,7 @@ def test_remote_code_repo_is_refused(hub):
 
 
 def test_unreadable_config_fails_closed(hub):
-    # _config_has_auto_map returns None when it cannot tell; refuse rather than
-    # assume the repo is safe.
+    # _config_has_auto_map returns None when it cannot tell; never assume safe.
     hub["auto_map"] = None
     refusal = _run("someone/unknown-GGUF")
     assert refusal.status == 403 and refusal.code == "remote_code_consent_required"
@@ -462,10 +456,8 @@ def test_hf_token_is_passed_to_the_worker(hub):
 
 
 def test_a_refused_dispatch_is_not_reported_as_downloading(hub):
-    # A same-repo whole-repo download or an in-progress delete makes the hub
-    # service decline the claim without raising: accepted=False, no worker. The
-    # caller must hear "busy", not a download that was never started (which the
-    # watcher would then fail two seconds later on an idle key).
+    # The hub service can decline a claim without raising (accepted=False, no worker), so
+    # the caller must hear "busy", not a download that was never started.
     hub["dispatch_result"] = {
         "job_key": "unsloth/x-gguf::ud-q5_k_xl",
         "state": "running",  # the blocking job's state, not ours
@@ -474,7 +466,7 @@ def test_a_refused_dispatch_is_not_reported_as_downloading(hub):
     }
     refusal = _run("unsloth/x-GGUF:UD-Q5_K_XL")
     assert refusal.status == 503 and refusal.code == "model_download_busy"
-    # No monitor row was opened and no watcher installed for a job that is not running.
+    # No watcher installed for a job that is not running.
     assert hub["watched"] == []
     # The slot is free, so an unrelated repo is still admitted.
     assert auto_dl._active is None
@@ -483,17 +475,16 @@ def test_a_refused_dispatch_is_not_reported_as_downloading(hub):
 
 
 def test_an_adoptable_dispatch_still_tracks_the_existing_job(hub):
-    # accepted=True with claimed=False means this exact repo+quant is already
-    # downloading (started from the Hub UI); attach to it rather than refuse.
+    # accepted=True with claimed=False means this repo+quant is already downloading
+    # (started from the Hub UI); attach to it rather than refuse.
     hub["dispatch_result"] = {"job_key": "k", "state": "running", "accepted": True}
     assert _run("unsloth/x-GGUF:UD-Q5_K_XL").code == "model_downloading"
     assert len(hub["watched"]) == 1
 
 
 def test_a_failed_status_probe_does_not_end_the_watch(hub, monkeypatch):
-    # A probe that raised says nothing about the worker. Reading it as "idle"
-    # failed the monitor row and freed the slot under a live download, which is
-    # how a second multi-GB fetch got admitted alongside the first.
+    # A probe that raised says nothing about the worker. Reading it as "idle" freed the
+    # slot under a live download, admitting a second multi-GB fetch alongside the first.
     from hub.services.models import downloads
 
     async def _boom(repo_id, gguf_variant = ""):
@@ -539,8 +530,7 @@ async def _maybe_errored(repo, variant):
     watcher_b = hub["watched"][-1]
     assert auto_dl._active is watcher_b
 
-    # Only now does A's watcher wake up and run its cleanup. Keyed on repo_id
-    # alone that cleared B, letting a second repo download start alongside it.
+    # Only now does A's watcher clean up. Keyed on repo_id alone, that cleared B.
     errored["on"] = True
     monkeypatch.setattr(auto_dl, "_WATCH_POLL_S", 0.0)
     asyncio.run(hub["real_watch"](watcher_a, None))
@@ -549,9 +539,8 @@ async def _maybe_errored(repo, variant):
 
 
 def test_a_cancelled_admission_does_not_wedge_the_slot(hub):
-    # CancelledError is a BaseException, so an `except Exception` cleanup would
-    # leave the provisional slot installed and refuse every later request for the
-    # rest of the process.
+    # CancelledError is a BaseException, so an `except Exception` cleanup would leave the
+    # provisional slot installed and refuse every later request.
     def _cancel():
         raise asyncio.CancelledError()
 
@@ -696,8 +685,7 @@ async def _fake_unavailable_message(model):
 
 
 def test_wrong_quant_is_not_answered_by_the_loaded_one(monkeypatch):
-    # The reported bug: asking for UD-Q6_K_XL while UD-Q4_K_XL is resident used to
-    # return 200 from the wrong weights.
+    # The reported bug: asking for UD-Q6_K_XL while UD-Q4_K_XL is resident returned 200.
     loaded = _Loaded("unsloth/gemma-4-E2B-it-GGUF", "UD-Q4_K_XL")
     with pytest.raises(HTTPException) as excinfo:
         _reject("unsloth/gemma-4-E2B-it-GGUF:UD-Q6_K_XL", loaded, monkeypatch)
@@ -736,8 +724,8 @@ def test_downloaded_but_auto_switch_off_says_so(monkeypatch):
 
 
 def test_a_failed_switch_is_reported_not_answered_by_the_resident_model(monkeypatch):
-    # On disk and switching allowed means the swap itself failed. Answering from
-    # whatever is resident would be the wrong weights under the right name.
+    # On disk and switching allowed means the swap failed, so answering from the resident
+    # model would be the wrong weights under the right name.
     loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
     with pytest.raises(HTTPException) as excinfo:
         _reject("unsloth/B-GGUF", loaded, monkeypatch, downloaded = True, auto_switch = True)
@@ -756,16 +744,14 @@ def test_a_failed_switch_is_reported_not_answered_by_the_resident_model(monkeypa
     ],
 )
 def test_a_provider_prefixed_label_still_reaches_the_resident_model(foreign, monkeypatch):
-    # LiteLLM and OpenRouter address every provider as "vendor/model". Treating a
-    # namespace as a concrete reference 404s all of them, so a bare one that is
-    # not on disk has to keep falling through.
+    # LiteLLM and OpenRouter address every provider as "vendor/model", so treating a
+    # namespace as a concrete reference would 404 all of them.
     loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
     assert _reject(foreign, loaded, monkeypatch) is None
 
 
 def test_an_explicit_quant_is_still_refused(monkeypatch):
-    # The signal that separates a GGUF reference from a foreign label: no
-    # LiteLLM or OpenRouter id carries a quant.
+    # A quant is the signal: no LiteLLM or OpenRouter id carries one.
     loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
     with pytest.raises(HTTPException) as excinfo:
         _reject("unsloth/B-GGUF:UD-Q6_K_XL", loaded, monkeypatch)
@@ -773,8 +759,7 @@ def test_an_explicit_quant_is_still_refused(monkeypatch):
 
 
 def test_a_repo_that_is_here_is_refused_without_a_quant(monkeypatch):
-    # The other half of the evidence test: a repo this server actually has is a
-    # reference to this server whether or not a quant was named.
+    # The other half of the evidence test: a repo this server has is a reference to it.
     loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
     with pytest.raises(HTTPException) as excinfo:
         _reject("unsloth/B-GGUF", loaded, monkeypatch, downloaded = True)
@@ -782,8 +767,8 @@ def test_a_repo_that_is_here_is_refused_without_a_quant(monkeypatch):
 
 
 def test_a_diagnosis_failure_does_not_serve_the_wrong_model(monkeypatch):
-    # The mismatch is already established before the diagnosis runs, so only the
-    # wording is uncertain. Falling through here would answer as another model.
+    # The mismatch is established before the diagnosis runs, so only the wording is
+    # uncertain; falling through here would answer as another model.
     loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
     monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
     monkeypatch.setattr(
@@ -802,8 +787,7 @@ def _boom(name):
 
 
 def test_nothing_loaded_leaves_the_existing_error_alone(monkeypatch):
-    # With no model resident the handler's own no-model-loaded error is already
-    # correct, so this check must not preempt it.
+    # The handler's own no-model-loaded error is already correct; don't preempt it.
     idle = type("B", (), {"is_loaded": False, "model_identifier": None, "hf_variant": None})()
     monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: idle)
     monkeypatch.setattr(
@@ -929,9 +913,8 @@ def test_every_other_bad_key_stays_indistinguishable():
 
 
 def test_the_servers_own_hf_token_is_never_borrowed(monkeypatch):
-    # The repo here is named by whoever holds an API key. Fetching it under the
-    # owner's Hub identity would let that key pull the owner's private repos and
-    # publish them in /v1/models for every other key.
+    # The repo is named by whoever holds an API key, so fetching under the owner's Hub
+    # identity would let that key pull the owner's private repos.
     import routes.settings as settings_route
 
     monkeypatch.setattr(settings_route, "_ambient_hf_token", lambda: "hf_owner_secret")
@@ -941,8 +924,7 @@ def test_the_servers_own_hf_token_is_never_borrowed(monkeypatch):
 
 
 def test_a_quant_cannot_be_satisfied_by_a_non_gguf_backend(monkeypatch):
-    # The llama.cpp branch requires :QUANT to match hf_variant. The Transformers
-    # branch has no quant identity at all, so it cannot claim one is loaded.
+    # llama.cpp matches :QUANT against hf_variant; Transformers has no quant identity.
     idle = type("B", (), {"is_loaded": False, "model_identifier": None, "hf_variant": None})()
     monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: idle)
     monkeypatch.setattr(
diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index e3386e9a732..117c0d5de1a 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -294,9 +294,9 @@ def test_openai_compat_routes_bound_to_handlers_with_auth():
     for key, handler in expected.items():
         assert key in seen, f"route {key} is not registered"
         route = seen[key]
-        assert (
-            route.endpoint.__name__ == handler
-        ), f"{key} bound to {route.endpoint.__name__}, expected {handler}"
+        assert route.endpoint.__name__ == handler, (
+            f"{key} bound to {route.endpoint.__name__}, expected {handler}"
+        )
         deps = [d.call.__name__ for d in route.dependant.dependencies]
         assert "get_current_subject" in deps, f"{key} lost its auth dependency"
 
@@ -393,8 +393,7 @@ def test_resolver_nonstring_model_is_failsafe():
 
 
 def test_describe_local_miss_separates_missing_repo_from_missing_quant(monkeypatch):
-    # A miss is two different situations and the error should say which: the repo
-    # isn't downloaded, or it is and only that quant is absent.
+    # Two different misses: the repo isn't downloaded, or only that quant is absent.
     monkeypatch.setattr(
         resolver,
         "_build_index",
@@ -418,8 +417,7 @@ def test_describe_local_miss_separates_missing_repo_from_missing_quant(monkeypat
 
 
 def test_describe_local_miss_is_failsafe(monkeypatch):
-    # Runs inside an error path, so a broken scan must degrade to the generic miss
-    # rather than raise a 500 over what was already a 4xx.
+    # Runs inside an error path, so a broken scan must degrade, not turn a 4xx into a 500.
     def boom():
         raise RuntimeError("scan blew up")
 
@@ -2948,9 +2946,8 @@ def test_require_vision_ignores_reload_stash(monkeypatch):
     monkeypatch.setattr(
         inference_route, "_target_is_vision", lambda _p: False
     )  # would reject if used
-    # 404 because the restored A is not the requested B; the restore still ran.
-    # B carries a quant so it reads as a reference to this server, not a foreign
-    # provider label.
+    # 404 because the restored A is not the requested B; the restore still ran. B carries
+    # a quant, so it reads as a reference to this server, not a foreign provider label.
     with pytest.raises(HTTPException):
         asyncio.run(
             inference_route._maybe_auto_switch_model(
@@ -3327,11 +3324,9 @@ def _run_responses_stream_no_model(
 
 
 def test_responses_stream_hint_matches_toggle_regardless_of_active_model(monkeypatch):
-    # The hint attaches whenever the toggle is off, including while a non-GGUF
-    # model is active, since auto-switch evicts it to load a resolved GGUF
-    # (the resolver branch has no active-model guard, unlike the reload stash).
-    # With it on the error changes kind: the name resolved to nothing local, so
-    # 404 model_not_found rather than a 400 pointing at /inference/load.
+    # The hint attaches whenever the toggle is off, even with a non-GGUF model active,
+    # since auto-switch evicts it to load a resolved GGUF. With it on the error changes
+    # kind: the name resolved to nothing local, so 404 rather than 400.
     off_status, hinted = _run_responses_stream_no_model(
         monkeypatch, enabled = False, active_model_name = None
     )
@@ -3358,8 +3353,8 @@ def _wire_unloaded_chat(
     enabled,
     catalog = ("org/A-GGUF", "org/B-GGUF"),
 ):
-    # Nothing loaded, so a chat request reaches the "no model loaded" error. Pin
-    # the catalog so listed ids don't depend on what is cached on the test machine.
+    # Nothing loaded, so a chat request reaches the "no model loaded" error. Pin the
+    # catalog so listed ids don't depend on what is cached on the test machine.
     async def _catalog():
         return [{"id": mid} for mid in catalog]
 
@@ -3387,9 +3382,8 @@ def _chat_error(payload):
 
 
 def test_chat_names_undownloaded_model_404s_with_available_ids(monkeypatch):
-    # The reported bug: auto-switch on, the named model is not on this machine, so
-    # the switch silently did nothing and /inference/load cannot fix it. Name the
-    # model and list what can serve, from the catalog GET /v1/models returns.
+    # The reported bug: the named model is not on this machine, so the switch silently
+    # did nothing and /inference/load cannot fix it. Name it and list what can serve.
     _wire_unloaded_chat(monkeypatch, enabled = True)
     status, detail = _chat_error(_chat_request(model = "unsloth/gemma-4-E4B-it-GGUF:UD-Q5_K_XL"))
     assert status == 404
@@ -3422,8 +3416,8 @@ def test_chat_wrong_quant_lists_the_local_quants(monkeypatch):
 
 
 def test_chat_error_unchanged_when_auto_switch_off(monkeypatch):
-    # Toggle off: nothing was resolved, so "not downloaded" would be a guess. Keep
-    # the pre-existing status and text, hint included.
+    # Toggle off: nothing resolved, so "not downloaded" would be a guess. Keep the
+    # pre-existing status and text, hint included.
     _wire_unloaded_chat(monkeypatch, enabled = False)
     status, detail = _chat_error(_chat_request(model = "org/nope-GGUF"))
     assert status == 400
@@ -3432,8 +3426,7 @@ def test_chat_error_unchanged_when_auto_switch_off(monkeypatch):
 
 
 def test_chat_error_unchanged_when_no_model_named(monkeypatch):
-    # An omitted model means "serve whatever is loaded", so the generic text is
-    # right and there is no name to report as missing.
+    # An omitted model means "serve whatever is loaded", so there is no name to report.
     _wire_unloaded_chat(monkeypatch, enabled = True)
     status, detail = _chat_error(_chat_request())
     assert status == 400
@@ -3441,8 +3434,7 @@ def test_chat_error_unchanged_when_no_model_named(monkeypatch):
 
 
 def test_chat_not_downloaded_error_survives_a_broken_catalog_scan(monkeypatch):
-    # The diagnosis is layered onto an already-failing path: a scan blowing up
-    # must not turn the 4xx into a 500.
+    # Layered onto an already-failing path, so a broken scan must not make it a 500.
     async def _boom():
         raise RuntimeError("catalog scan blew up")
 
@@ -3486,8 +3478,7 @@ async def _noop_switch(*a, **k):
 
 
 def test_chat_undownloaded_model_uses_the_openai_envelope(monkeypatch):
-    # On the OpenAI surface it carries param/code so SDK clients can branch on it,
-    # matching GET /v1/models/{id}'s existing model_not_found.
+    # The OpenAI surface carries param/code so SDK clients can branch on it.
     from fastapi import HTTPException
 
     _wire_unloaded_chat(monkeypatch, enabled = True)
@@ -3506,11 +3497,8 @@ def test_chat_undownloaded_model_uses_the_openai_envelope(monkeypatch):
 
 
 def test_gguf_only_paths_keep_the_generic_error_for_the_resident_non_gguf_model(monkeypatch):
-    # A Transformers model is resident and the caller names that exact model on a
-    # GGUF-only path. It is not a GGUF, so resolve_local_gguf misses -- but the
-    # catalog GET /v1/models serves lists this very id as available, so "not
-    # downloaded on this server. Available models: <that same id>" is both false
-    # and self-contradictory. The generic "no GGUF loaded" diagnosis is correct.
+    # A resident Transformers model named on a GGUF-only path: resolve_local_gguf misses,
+    # but the catalog lists that same id, so "not downloaded" would contradict itself.
     resident = "unsloth/Qwen3.5-4B-GGUF"  # the id _run_responses_stream_no_model asks for
 
     async def _catalog():
@@ -3526,8 +3514,7 @@ async def _catalog():
 
 
 def test_completions_keeps_the_generic_error_for_the_resident_non_gguf_model(monkeypatch):
-    # Same contradiction on the raw-body surface, which reaches the diagnosis
-    # through _auto_switch_from_request_body rather than a typed payload.
+    # Same contradiction on the raw-body surface, via _auto_switch_from_request_body.
     from fastapi import HTTPException
 
     resident = "unsloth/Llama-3.2-1B-Instruct"
@@ -3549,8 +3536,7 @@ def test_completions_keeps_the_generic_error_for_the_resident_non_gguf_model(mon
 
 
 def test_responses_stream_keeps_generic_error_when_target_is_local(monkeypatch):
-    # Name resolves locally yet nothing is loaded: the switch failed, so the
-    # generic text is right and the status stays 400, not a bogus "missing".
+    # Resolves locally yet nothing is loaded: the switch failed, so keep the generic 400.
     status, detail = _run_responses_stream_no_model(
         monkeypatch,
         enabled = True,
diff --git a/studio/backend/tests/test_openai_catalog.py b/studio/backend/tests/test_openai_catalog.py
index 9f44eddd281..0efa19f6253 100644
--- a/studio/backend/tests/test_openai_catalog.py
+++ b/studio/backend/tests/test_openai_catalog.py
@@ -64,8 +64,7 @@ async def _fake_catalog():
         ]
 
     monkeypatch.setattr(inf, "_cached_local_catalog", _fake_catalog)
-    # GGUF-ness and the quant labels both come from the on-disk files in one scan;
-    # drive them off each info's flag here.
+    # GGUF-ness and the quant labels come from one on-disk scan; drive both off the flag.
     monkeypatch.setattr(
         resolver, "local_gguf_quants", lambda info: ("Q8_0",) if info.is_gguf else None
     )
@@ -76,8 +75,7 @@ async def _fake_catalog():
     # Loaded model is present, marked loaded, and keeps context fields.
     assert ids["Qwen3-Q4"]["loaded"] is True
     assert ids["Qwen3-Q4"]["context_length"] == 4096
-    # Available-but-not-loaded GGUF models are listed too, with the quant a client
-    # appends to the id to pin it.
+    # Not-loaded GGUFs are listed too, with the quant a client appends to pin them.
     assert ids["Llama-8B-Q8"]["loaded"] is False
     assert ids["Llama-8B-Q8"]["quant"] == "Q8_0"
     # The HF-cache GGUF is listed despite model_format being unset.
@@ -213,8 +211,7 @@ async def _run():
 
 
 def test_monitor_active_model_is_a_public_id_not_a_host_path(monkeypatch):
-    # The settings UI renders this and --secure serves it over a public tunnel, so
-    # it must never be the on-disk load path (it used to be model_identifier raw).
+    # The settings UI renders this and --secure serves it publicly, so never a load path.
     class _Llama:
         is_loaded = True
         model_identifier = "/home/me/.cache/huggingface/hub/models--org--A-GGUF/snapshots/abc"
@@ -238,8 +235,7 @@ class _Llama:
 
 
 def test_lifecycle_label_recovers_the_repo_id_from_an_hf_cache_path():
-    # An auto-switch load is handed the snapshot dir, whose basename is a commit
-    # sha, so the row would otherwise be labelled with a hash.
+    # An auto-switch load gets the snapshot dir, whose basename is a commit sha.
     snap = "/home/me/.cache/huggingface/hub/models--unsloth--gemma-4-E4B-it-GGUF/snapshots/bfc15c3"
     assert (
         inf._lifecycle_model_label(snap, "UD-Q4_K_XL") == "unsloth/gemma-4-E4B-it-GGUF:UD-Q4_K_XL"
diff --git a/studio/frontend/src/features/chat/types/api.ts b/studio/frontend/src/features/chat/types/api.ts
index 94b06282cda..a1783431217 100644
--- a/studio/frontend/src/features/chat/types/api.ts
+++ b/studio/frontend/src/features/chat/types/api.ts
@@ -283,8 +283,8 @@ export interface ApiMonitorEntry {
   completion_tokens?: number | null;
   total_tokens?: number | null;
   error?: string | null;
-  // "request" is an HTTP call; "lifecycle" is a model load/unload/download, which
-  // carries event/reason instead of a prompt and has no detail to fetch.
+  // "lifecycle" is a model load/unload/download: event/reason instead of a prompt,
+  // and no detail to fetch.
   kind?: "request" | "lifecycle";
   event?: "load" | "unload" | "download" | null;
   reason?: "manual" | "idle" | "api" | null;
diff --git a/studio/frontend/src/features/settings/api/openai-auto-switch.ts b/studio/frontend/src/features/settings/api/openai-auto-switch.ts
index c5a272f7d65..b76cfc62997 100644
--- a/studio/frontend/src/features/settings/api/openai-auto-switch.ts
+++ b/studio/frontend/src/features/settings/api/openai-auto-switch.ts
@@ -13,8 +13,8 @@ export type OpenAIAutoSwitchSettings = {
   idleUnloadActive: boolean;
   // Persist the KV cache to disk on idle unload and restore it on reload.
   autoUnloadKeepKv: boolean;
-  // Fetch a GGUF named in an API request that isn't downloaded yet. Stored
-  // independently, but only takes effect while `enabled` is on.
+  // Fetch a GGUF named in an API request. Stored independently, but only
+  // takes effect while `enabled` is on.
   autoDownloadModel: boolean;
 };
 
diff --git a/studio/frontend/src/features/settings/api/openai-models.ts b/studio/frontend/src/features/settings/api/openai-models.ts
index d4f7c18a63d..882d1adc75e 100644
--- a/studio/frontend/src/features/settings/api/openai-models.ts
+++ b/studio/frontend/src/features/settings/api/openai-models.ts
@@ -7,8 +7,7 @@ export type OpenAIModel = {
   id: string;
   // Resident in memory now; the rest are downloaded and servable.
   loaded?: boolean;
-  // On-disk GGUF quant. Ids stay bare for OpenAI compat, so append it as
-  // `id:quant` to pin this exact quant rather than letting the server pick.
+  // On-disk GGUF quant. Ids stay bare for OpenAI compat, so append `:quant` to pin it.
   quant?: string;
 };
 
@@ -20,9 +19,8 @@ type ApiOpenAIModelList = {
  * The models this server can serve.
  *
  * `/v1/models` rather than the hub inventory: it returns exactly the ids
- * `/v1/chat/completions` resolves against, so a snippet built from it is
- * runnable as printed. `/v1` accepts the UI session JWT as well as
- * `sk-unsloth-` keys, so `authFetch` works unchanged.
+ * `/v1/chat/completions` resolves against, so a snippet built from it runs as
+ * printed. `/v1` accepts the UI session JWT, so `authFetch` works unchanged.
  */
 export async function listOpenAIModels(): Promise<OpenAIModel[]> {
   const res = await authFetch("/v1/models");
diff --git a/studio/frontend/src/features/settings/components/api-monitor-console.tsx b/studio/frontend/src/features/settings/components/api-monitor-console.tsx
index 77f1e2492dd..edc15c06e17 100644
--- a/studio/frontend/src/features/settings/components/api-monitor-console.tsx
+++ b/studio/frontend/src/features/settings/components/api-monitor-console.tsx
@@ -124,8 +124,7 @@ function lifecycleLabel(entry: ApiMonitorEntry): string {
   return "Model load failed";
 }
 
-// Load/unload rows: a label, the model and a time. No prompt, reply, tokens or
-// detail fetch, so unlike a request row there is nothing to expand.
+// Load/unload rows: label, model and time. No prompt or detail, so nothing to expand.
 function LifecycleEntry({ entry }: { entry: ApiMonitorEntry }): ReactElement {
   return (
     <article className="min-w-0 rounded-lg border border-border/70 bg-muted/25">
@@ -279,10 +278,8 @@ export function ApiMonitorConsole(): ReactElement {
     }
   }, []);
 
-  // Free the VRAM the loaded model is holding. The monitor only knows the model's
-  // public id, and /unload matches on the internal one, so read that from status
-  // the same way the chat runtime does rather than putting a host path in this
-  // response. With auto-switch on the next API request loads a model again.
+  // /unload matches on the internal id, which the monitor response omits (it would be
+  // a host path), so read it from status the same way the chat runtime does.
   const unloadActiveModel = useCallback(async (): Promise<void> => {
     setUnloading(true);
     try {
@@ -293,8 +290,7 @@ export function ApiMonitorConsole(): ReactElement {
         return;
       }
       await unloadModel({ model_path: checkpoint });
-      // Same as the chat eject flow: the store still holds the checkpoint this
-      // just freed, and the usage examples would keep naming it.
+      // Same as the chat eject flow: the store still holds the freed checkpoint.
       useChatRuntimeStore.getState().clearCheckpoint();
       setError(null);
       await loadMonitor();
@@ -348,10 +344,8 @@ export function ApiMonitorConsole(): ReactElement {
   const hasActive = (data?.active_requests ?? 0) > 0;
   const entries = useMemo(() => data?.entries ?? [], [data]);
 
-  // Page 1 tracks the live list. Paging back freezes the id order captured at
-  // that moment: the poll keeps refreshing row contents, but new traffic must not
-  // shove history down a page while it is being read (finishing a request also
-  // moves it to the head, so even an idle server reorders).
+  // Page 1 tracks the live list. Paging back freezes the id order: rows keep
+  // refreshing, but new traffic must not shove history down a page while it is read.
   const [page, setPage] = useState(0);
   const [frozenIds, setFrozenIds] = useState<string[] | null>(null);
   const byId = useMemo(
@@ -444,8 +438,7 @@ export function ApiMonitorConsole(): ReactElement {
   );
 
   useEffect(() => {
-    // Only rows actually on screen: an expanded row left behind on another page
-    // would otherwise keep polling its detail every tick.
+    // Only rows on screen: an expanded row on another page would keep polling.
     for (const entry of visible) {
       if (isLifecycle(entry) || !expandedIds.has(entry.id)) {
         continue;
@@ -480,8 +473,8 @@ export function ApiMonitorConsole(): ReactElement {
           <div className="rounded-full border border-border px-2.5 py-1 text-xs capitalize text-muted-foreground">
             {statusLabel}
           </div>
-          {/* Always rendered, disabled when idle: hiding it made the only manual
-              release path invisible exactly when someone goes looking for it. */}
+          {/* Always rendered, disabled when idle: hiding the only manual release path
+              made it invisible exactly when someone goes looking for it. */}
           <Button
             type="button"
             variant="ghost"
@@ -551,11 +544,9 @@ export function ApiMonitorConsole(): ReactElement {
         )}
       </div>
 
-      {/* Also whenever a snapshot is frozen: the backend's 50-entry retention
-          window evicts frozen ids as new traffic arrives, so the frozen list can
-          shrink below one page (and eventually to nothing). Hiding the pager then
-          strands the console on a stale -- finally empty -- snapshot with no way
-          back to the live list short of closing the panel. */}
+      {/* Also whenever a snapshot is frozen: retention evicts frozen ids as new traffic
+          arrives, so the frozen list can shrink below one page. Hiding the pager then
+          strands the console on a stale snapshot with no way back to the live list. */}
       {ordered.length > PAGE_SIZE || frozenIds !== null ? (
         <div className="flex items-center justify-between gap-2 border-t border-border/60 px-4 py-2 text-xs text-muted-foreground">
           <span>
diff --git a/studio/frontend/src/features/settings/components/usage-examples.tsx b/studio/frontend/src/features/settings/components/usage-examples.tsx
index 5acdb6911ae..385912ac3d1 100644
--- a/studio/frontend/src/features/settings/components/usage-examples.tsx
+++ b/studio/frontend/src/features/settings/components/usage-examples.tsx
@@ -330,8 +330,8 @@ function buildSnippets(
 
 const KEY_PLACEHOLDER = "sk-unsloth-YOUR_KEY";
 const USE_TUNNEL_KEY = "unsloth_api_use_tunnel";
-// Slow retry while /v1 has nothing to name: a download or a load can finish
-// while this panel is open, and neither moves the checkpoint below.
+// Slow retry while /v1 has nothing to name: a download or load can finish while this
+// panel is open, and neither moves the checkpoint below.
 const CATALOG_RETRY_MS = 15000;
 
 function readUseTunnelPref(): boolean {
@@ -352,9 +352,8 @@ function writeUseTunnelPref(value: boolean): void {
   }
 }
 
-// A checkpoint can be an on-disk load path (an auto-switch load resolves to the
-// GGUF/snapshot dir), which must never reach a printed snippet: it leaks the host
-// layout and is not an id /v1 advertises. Mirrors the backend's _looks_like_path.
+// A checkpoint can be an on-disk load path, which leaks the host layout and is not an
+// id /v1 advertises. Mirrors the backend's _looks_like_path.
 function looksLikePath(id: string): boolean {
   return (
     id.startsWith("/") ||
@@ -366,23 +365,19 @@ function looksLikePath(id: string): boolean {
   );
 }
 
-// The model the examples name. With nothing loaded this used to print a
-// hardcoded repo id the user likely never downloaded, so the copied snippet
-// 404d. Only ever name an id /v1 resolves against; null means this server has
-// nothing to serve yet and the panel says so instead of printing a dead id.
+// The model the examples name. Only ever an id /v1 resolves against; null means the
+// server has nothing to serve yet, and the panel says so instead of a dead id.
 function useExampleModelName(): string | null {
   const checkpoint = useChatRuntimeStore((s) => s.params.checkpoint);
   const ggufVariant = useChatRuntimeStore((s) => s.activeGgufVariant);
-  // null until /v1/models answers: "not asked yet" must not read as "this
-  // server holds nothing", or the first render already picks a name.
+  // null until /v1/models answers: "not asked yet" must not read as "holds nothing".
   const [catalog, setCatalog] = useState<OpenAIModel[] | null>(null);
   const usableCheckpoint =
     !!checkpoint && !checkpoint.startsWith("external::") && !looksLikePath(checkpoint);
   const needsCatalog = !usableCheckpoint;
 
-  // Only when the checkpoint can't answer it: /v1/models scans the model dirs and
-  // HF caches. Re-runs when a model is loaded or unloaded, and retries until the
-  // server reports something servable, since a download moves no store state.
+  // Only when the checkpoint can't answer it, since /v1/models scans the model dirs.
+  // Retries until something is servable, since a download moves no store state.
   // biome-ignore lint/correctness/useExhaustiveDependencies: a load or unload must refetch the servable ids
   useEffect(() => {
     if (!needsCatalog) return;
@@ -416,9 +411,8 @@ function useExampleModelName(): string | null {
       }
       return checkpoint;
     }
-    // No usable checkpoint (none, an external provider, or a raw load path):
-    // name something this server actually holds, quant included so the request
-    // pins the file on disk instead of letting the server pick a quant.
+    // No usable checkpoint: name something this server holds, quant included so the
+    // request pins the file on disk rather than letting the server pick.
     const pick = catalog?.find((m) => m.loaded) ?? catalog?.[0];
     if (!pick) {
       return null;
@@ -629,9 +623,8 @@ export function UsageExamples({ apiKey }: { apiKey?: string | null }) {
         {t("settings.apiKeys.usageExamples")}
       </h2>
       <div className="min-w-0 max-w-full overflow-hidden rounded-lg border border-border bg-muted/20">
-        {/* No model-auto-switch row: ModelAutoSwitchSection renders the same
-            setting just below on this tab, and the two do not share state (the
-            settings module caches on first read), so a duplicate drifts. */}
+        {/* No model-auto-switch row: ModelAutoSwitchSection renders the same setting
+            just below and shares no state with it, so a duplicate would drift. */}
         {cloudflareUrl ? (
           <div className="flex min-w-0 items-center justify-between gap-2 border-b border-border px-2 py-1.5">
             <div className="flex shrink-0 items-center gap-1.5">
diff --git a/tests/studio/test_usage_examples_model_source_contract.py b/tests/studio/test_usage_examples_model_source_contract.py
index 8b93bbfcde4..0ecd944c008 100644
--- a/tests/studio/test_usage_examples_model_source_contract.py
+++ b/tests/studio/test_usage_examples_model_source_contract.py
@@ -15,17 +15,14 @@
 
 
 def test_examples_name_a_model_the_server_can_serve():
-    # The snippets used to fall back to a hardcoded repo id whenever nothing was
-    # loaded, so a copied curl named a model the user had never downloaded and
-    # 404d. Read the servable ids from /v1/models instead -- the same list the
-    # backend's model-not-downloaded error lists, so the two cannot disagree.
+    # The snippets used to fall back to a hardcoded repo id, so a copied curl 404d. Read
+    # the servable ids from /v1/models, the same list the backend's error lists.
     src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")
     assert 'from "../api/openai-models"' in src
     assert "function useExampleModelName(): string" in src
     hook = src[src.find("function useExampleModelName") : src.find("// Backend PATH detection")]
     assert "listOpenAIModels()" in hook
-    # Precedence: live checkpoint, then a loaded catalog entry, then any entry,
-    # and only then no model at all.
+    # Precedence: live checkpoint, then a loaded catalog entry, then any entry, then none.
     assert "catalog?.find((m) => m.loaded) ?? catalog?.[0]" in hook
     # The snippet pins the quant so the request names the file on disk.
     assert "`${pick.id}:${pick.quant}`" in hook
@@ -35,11 +32,9 @@ def test_examples_name_a_model_the_server_can_serve():
 
 
 def test_examples_never_print_a_hardcoded_model_id():
-    # The bug this contract exists for. The catalog started as `[]`, so the very
-    # first render, and every render after a slow or failed /v1/models fetch,
-    # printed a copyable snippet naming a repo id the server cannot serve. The
-    # catalog is tri-state now (null until /v1 answers) and the panel says to
-    # load or download a model rather than naming one that does not exist.
+    # The bug this contract exists for: the catalog started as `[]`, so any render before
+    # /v1/models answered printed a snippet naming a model the server cannot serve. It is
+    # tri-state now (null until /v1 answers) and the panel asks for a model instead.
     src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")
     assert "MODEL_FALLBACK" not in src
     # No repo-shaped literal anywhere: a snippet may only name what /v1 returns.
@@ -57,23 +52,20 @@ def test_examples_never_print_a_hardcoded_model_id():
 
 
 def test_catalog_refresh_follows_the_loaded_model():
-    # `[needsCatalog]` alone never re-ran: it stays true the whole time there is
-    # no local checkpoint, so a model finishing its load left the snippet naming
-    # whatever the first fetch happened to see.
+    # `[needsCatalog]` alone never re-ran while there was no local checkpoint, so a
+    # finished load left the snippet naming whatever the first fetch saw.
     src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")
     hook = src[src.find("function useExampleModelName") : src.find("// Backend PATH detection")]
     assert "}, [needsCatalog, checkpoint, ggufVariant]);" in hook
-    # A finishing download moves no store state at all, so the fetch also
-    # retries itself until /v1 has something, on a timer the effect clears.
+    # A finishing download moves no store state, so the fetch retries on a timer too.
     assert "window.setTimeout(update, CATALOG_RETRY_MS)" in hook
     assert "window.clearTimeout(timeoutId)" in hook
     assert "const CATALOG_RETRY_MS = 15000;" in src
 
 
 def test_usage_examples_has_no_duplicate_auto_switch_control():
-    # ModelAutoSwitchSection renders the same setting immediately below this
-    # panel on the same tab, and the two do not share state, so a second switch
-    # here drifts out of sync with the one the user can also see.
+    # ModelAutoSwitchSection renders the same setting just below this panel and shares no
+    # state with it, so a second switch here would drift out of sync.
     src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")
     assert "openai-auto-switch" not in src
     assert "SWITCH_NOTE" not in src
@@ -90,13 +82,11 @@ def test_usage_examples_has_no_duplicate_auto_switch_control():
 
 
 def test_api_monitor_pages_five_at_a_time():
-    # 50 terminal entries are retained backend-side; the console used to dump all
-    # of them into one scroller.
+    # The backend retains 50 terminal entries; the console used to dump them all at once.
     src = API_MONITOR_TSX.read_text(encoding = "utf-8")
     assert "const PAGE_SIZE = 5;" in src
     assert "ordered.slice(" in src
-    # Paging back must freeze the id order, or live traffic reorders history
-    # under the cursor between polls.
+    # Paging back must freeze the id order, or live traffic reorders history under it.
     assert "frozenIds" in src
     assert "setFrozenIds((prev) => prev ?? entries.map((entry) => entry.id))" in src
 
@@ -131,19 +121,16 @@ def test_api_monitor_renders_download_rows():
 def test_monitor_can_unload_the_loaded_model():
     src = API_MONITOR_TSX.read_text(encoding = "utf-8")
     assert "unloadActiveModel" in src
-    # Always rendered, so the manual release path stays discoverable; disabled
-    # when idle or mid-unload rather than hidden.
+    # Always rendered so the manual release stays discoverable; disabled, not hidden.
     assert "disabled={unloading || !data?.active_model}" in src
     assert "{data?.active_model ? (" not in src
-    # /unload matches on the internal id, which this response deliberately omits
-    # (it would be a host path), so it must be read from status.
+    # /unload matches on the internal id, omitted here (a host path), so read it from status.
     assert "resolveInferenceCheckpointId(status)" in src
     assert "unloadModel({ model_path: checkpoint })" in src
 
 
 def test_auto_download_toggle_is_gated_on_auto_switch():
-    # Downloading a model auto-switch is not allowed to load would fetch
-    # gigabytes nothing can then serve, so the row follows the enabled flag.
+    # Downloading what auto-switch cannot load fetches gigabytes nothing can serve.
     src = AUTO_SWITCH_TSX.read_text(encoding = "utf-8")
     assert "modelAutoSwitch.autoDownload" in src
     assert "settings?.autoDownloadModel ?? false" in src

From 21cc4fc674bc5c5a69180ae1c0d528c91df6070a Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Sun, 26 Jul 2026 13:28:16 +0000
Subject: [PATCH 16/56] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 studio/backend/tests/test_openai_auto_switch.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index 117c0d5de1a..457df3487d3 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -294,9 +294,9 @@ def test_openai_compat_routes_bound_to_handlers_with_auth():
     for key, handler in expected.items():
         assert key in seen, f"route {key} is not registered"
         route = seen[key]
-        assert route.endpoint.__name__ == handler, (
-            f"{key} bound to {route.endpoint.__name__}, expected {handler}"
-        )
+        assert (
+            route.endpoint.__name__ == handler
+        ), f"{key} bound to {route.endpoint.__name__}, expected {handler}"
         deps = [d.call.__name__ for d in route.dependant.dependencies]
         assert "get_current_subject" in deps, f"{key} lost its auth dependency"
 

From 9eb5a7af5d7bffc0df0cf34fe44992e51148f5c1 Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Sun, 26 Jul 2026 13:38:11 +0000
Subject: [PATCH 17/56] Studio: keep API auto-download off the server's Hugging
 Face identity

Passing None for the caller's token was not anonymous. spawn_worker
substitutes the backend's HF_TOKEN for a falsy one, and HfApi(token=None)
falls back to a cached login, so a repo named by an API-key holder could
still be fetched under the owner's Hub identity and land in the shared
catalog. The metadata probe and auth_check now pass an explicit False,
and dispatch threads allow_ambient_token=False so the worker stays
anonymous too. The flag defaults to True, so the UI download path keeps
the ambient fallback that private repos rely on.

Three more from the same review:

- Require an exact hf_variant match only when the suffix is really a
  quant. The llama.cpp branch still compared Ollama style :latest and :8b
  against the loaded quant and refused the resident model, which is the
  opposite of what looks_like_quant classifies them as.
- Decode an HF cache repo id only when the models-- component is followed
  by snapshots. An ordinary directory whose name merely starts with
  models-- was being read as an encoded repo id.
- Return the probing response before consulting the job registry when an
  adopted claim has no variant yet. A stale error on the whole-repo key
  could otherwise release the slot the first request's probe still holds,
  letting a second large download start beside it.
---
 studio/backend/core/inference/model_ids.py    |  7 ++-
 .../core/inference/openai_auto_download.py    | 25 ++++++--
 .../hub/services/download_lifecycle.py        |  8 ++-
 .../backend/hub/services/models/downloads.py  | 16 +++++-
 studio/backend/routes/inference.py            |  4 +-
 .../tests/test_openai_auto_download.py        | 57 ++++++++++++++++++-
 6 files changed, 102 insertions(+), 15 deletions(-)

diff --git a/studio/backend/core/inference/model_ids.py b/studio/backend/core/inference/model_ids.py
index 07148402dd7..80314eb1475 100644
--- a/studio/backend/core/inference/model_ids.py
+++ b/studio/backend/core/inference/model_ids.py
@@ -48,8 +48,11 @@ def hf_cache_repo_id(path: Optional[str]) -> Optional[str]:
     """
     if not path:
         return None
-    for part in str(path).replace("\\", "/").split("/"):
-        if part.startswith("models--"):
+    parts = str(path).replace("\\", "/").split("/")
+    for index, part in enumerate(parts):
+        # Only inside the real cache layout: an ordinary directory that merely
+        # starts with "models--" is not an encoded repo id.
+        if part.startswith("models--") and parts[index + 1 : index + 2] == ["snapshots"]:
             return part[len("models--") :].replace("--", "/")
     return None
 
diff --git a/studio/backend/core/inference/openai_auto_download.py b/studio/backend/core/inference/openai_auto_download.py
index e58a7a3a481..9b42110fd5d 100644
--- a/studio/backend/core/inference/openai_auto_download.py
+++ b/studio/backend/core/inference/openai_auto_download.py
@@ -129,6 +129,15 @@ def looks_like_quant(variant: Optional[str]) -> bool:
     return _GGUF_KNOWN_QUANT_RE.fullmatch(variant.strip()) is not None
 
 
+def _hub_token(hf_token: Optional[str]):
+    """The caller's token, or an explicit False.
+
+    None makes huggingface_hub fall back to a cached login, which here would be
+    the server owner's. False is what actually means anonymous.
+    """
+    return hf_token or False
+
+
 def _servable_key(repo_id: str, hf_token: Optional[str]) -> str:
     """Cache key, per credential.
 
@@ -180,7 +189,7 @@ def _auth_denied(repo_id: str, hf_token: Optional[str]) -> bool:
 
     try:
         from huggingface_hub import auth_check
-        auth_check(repo_id, token = hf_token)
+        auth_check(repo_id, token = _hub_token(hf_token))
     except Exception as exc:
         return hf_error_status(exc) in (401, 403)
     return False
@@ -375,6 +384,11 @@ async def maybe_auto_download(
             _active = provisional
 
     if adopted is not None:
+        if adopted.variant is None:
+            # Still probing, so it owns the slot and has no job to look up yet.
+            # Reading the whole-repo key here could find an older error and
+            # release a slot the probe is still using.
+            return _downloading_refusal(adopted.repo_id, None)
         state, error = await _job_state(adopted.repo_id, adopted.variant)
         if state in ("running", "cancelling", "unknown"):
             return _downloading_refusal(
@@ -391,9 +405,6 @@ async def maybe_auto_download(
                 code = "model_download_failed",
                 message = f"Downloading '{requested_model}' failed: {error or 'unknown error'}",
             )
-        if adopted.variant is None:
-            # Another request is still probing this same repo.
-            return _downloading_refusal(adopted.repo_id, None)
         # complete/idle/cancelled: the watcher is about to free the slot, so retry once more.
         return _downloading_refusal(
             _public_label(adopted.repo_id, adopted.variant),
@@ -422,7 +433,7 @@ async def _admit_and_start(
 
     def _probe():
         from huggingface_hub import HfApi
-        return HfApi(token = hf_token).model_info(
+        return HfApi(token = _hub_token(hf_token)).model_info(
             repo_id, files_metadata = True, timeout = _MODEL_INFO_TIMEOUT_S
         )
 
@@ -570,7 +581,9 @@ async def _dispatch(
     )
     try:
         dispatched = await downloads.download_model_response(
-            DownloadModelRequest(repo_id = repo_id, gguf_variant = variant), hf_token
+            DownloadModelRequest(repo_id = repo_id, gguf_variant = variant),
+            hf_token,
+            allow_ambient_token = False,
         )
     except Exception as exc:
         _release(active)
diff --git a/studio/backend/hub/services/download_lifecycle.py b/studio/backend/hub/services/download_lifecycle.py
index 8e14427a56f..5b028bab0e6 100644
--- a/studio/backend/hub/services/download_lifecycle.py
+++ b/studio/backend/hub/services/download_lifecycle.py
@@ -58,6 +58,7 @@ def spawn_worker(
     use_xet: bool,
     protected_blob_hashes: Optional[frozenset[str]] = None,
     cache_env: Optional[Mapping[str, str]] = None,
+    allow_ambient_token: bool = True,
 ) -> subprocess.Popen:
     """Spawn the download worker.
 
@@ -83,7 +84,9 @@ def spawn_worker(
     env["HF_HUB_DISABLE_XET"] = "0" if use_xet else "1"
     # No token in Unsloth settings: fall back to the backend's own HF_TOKEN so
     # private repos stay downloadable (needed while inkling repos are private).
-    if not hf_token:
+    # Not for a repo an API caller named: that would lend them the owner's Hub
+    # identity, so those dispatches opt out and stay anonymous.
+    if not hf_token and allow_ambient_token:
         hf_token = os.environ.get("HF_TOKEN") or None
     env["HF_HUB_DISABLE_IMPLICIT_TOKEN"] = "0" if hf_token else "1"
     # hf_transfer's parallel Range chunks can leave sparse partials even in
@@ -244,8 +247,7 @@ def finalize_worker_exit(
         if stderr_text:
             if download_manifest.MANIFEST_DEGRADED_MARKER in stderr_text:
                 logger.warning(
-                    f"{log_prefix} complete with degraded diagnostics for "
-                    f"{label}: {stderr_text}"
+                    f"{log_prefix} complete with degraded diagnostics for {label}: {stderr_text}"
                 )
             else:
                 logger.info(f"{log_prefix} worker diagnostics for {label}: {stderr_text}")
diff --git a/studio/backend/hub/services/models/downloads.py b/studio/backend/hub/services/models/downloads.py
index c93b21c082f..26eb15cb9fb 100644
--- a/studio/backend/hub/services/models/downloads.py
+++ b/studio/backend/hub/services/models/downloads.py
@@ -91,6 +91,7 @@ def _spawn_download_worker(
     use_xet: bool = True,
     protected_blob_hashes: Optional[frozenset[str]] = None,
     cache_env: Optional[dict[str, str]] = None,
+    allow_ambient_token: bool = True,
 ) -> subprocess.Popen:
     args = ["--repo-id", repo_id]
     if variant:
@@ -101,11 +102,21 @@ def _spawn_download_worker(
         use_xet = use_xet,
         protected_blob_hashes = protected_blob_hashes,
         cache_env = cache_env,
+        allow_ambient_token = allow_ambient_token,
     )
 
 
-async def download_model_response(body: DownloadModelRequest, hf_token: Optional[str] = None):
-    """Start a background download for a HuggingFace model."""
+async def download_model_response(
+    body: DownloadModelRequest,
+    hf_token: Optional[str] = None,
+    *,
+    allow_ambient_token: bool = True,
+):
+    """Start a background download for a HuggingFace model.
+
+    ``allow_ambient_token=False`` keeps the worker anonymous when the caller
+    supplied no token, for repos named over the API rather than chosen here.
+    """
     repo_id = body.repo_id.strip()
     if not _is_valid_repo_id(repo_id):
         raise HTTPException(
@@ -218,6 +229,7 @@ async def download_model_response(body: DownloadModelRequest, hf_token: Optional
             use_xet = use_xet,
             protected_blob_hashes = protected_blob_hashes,
             cache_env = cache_env,
+            allow_ambient_token = allow_ambient_token,
         ),
         hf_token = hf_token,
         label = label,
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 7d32c7fa9ea..0aba0d9a2b5 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3783,7 +3783,9 @@ def _loaded_satisfies(requested: str) -> bool:
         }
         if base not in keys:
             return False
-        if not variant:
+        if not looks_like_quant(variant):
+            # A non-quant tag (Ollama style ":latest", ":8b") is not a claim
+            # about which file is loaded, so the repo match is enough.
             return True
         return (getattr(llama_backend, "hf_variant", None) or "").lower() == variant.lower()
     active = getattr(get_inference_backend(), "active_model_name", None)
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index f6c39f2bcb1..5adb96d7866 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -111,6 +111,7 @@ def hub(monkeypatch):
         "on_probe": None,
         "probes": 0,
         "auth_denied": False,
+        "allow_ambient": None,
     }
 
     class _FakeApi:
@@ -125,8 +126,14 @@ def model_info(self, repo_id, **kwargs):
                 raise state["raise"]
             return state["info"]
 
-    async def _start(body, hf_token = None):
+    async def _start(
+        body,
+        hf_token = None,
+        *,
+        allow_ambient_token = True,
+    ):
         state["started"].append((body.repo_id, body.gguf_variant, hf_token))
+        state["allow_ambient"] = allow_ambient_token
         return state["dispatch_result"]
 
     async def _no_watch(active, hf_token):
@@ -936,3 +943,51 @@ def test_a_quant_cannot_be_satisfied_by_a_non_gguf_backend(monkeypatch):
     assert inference_route._loaded_satisfies("org/model:Q4_K_M") is False
     # An Ollama-style tag is not a claim about the weights, so it still matches.
     assert inference_route._loaded_satisfies("org/model:latest") is True
+
+
+def test_the_worker_is_never_given_the_servers_own_token(hub):
+    # download_lifecycle substitutes the backend's HF_TOKEN for a falsy one, so
+    # passing None here would hand an API caller the owner's Hub identity.
+    assert _run("unsloth/x-GGUF").code == "model_downloading"
+    assert hub["started"][0][2] is None
+    assert hub["allow_ambient"] is False
+
+
+def test_the_metadata_probe_is_explicitly_anonymous(hub):
+    # huggingface_hub treats token=None as "use a cached login"; only False is
+    # anonymous, and the cached login here would be the server owner's.
+    _run("unsloth/x-GGUF")
+    assert hub["token"] is False
+    auto_dl.reset_for_tests()
+    _run("unsloth/y-GGUF", hf_token = "hf_caller_own")
+    assert hub["token"] == "hf_caller_own"
+
+
+def test_an_ollama_tag_still_matches_the_resident_gguf(monkeypatch):
+    # looks_like_quant() calls these foreign tags, so the llama.cpp branch must
+    # not compare them against hf_variant and refuse the resident model.
+    loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
+    monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+    assert inference_route._loaded_satisfies("unsloth/A-GGUF:latest") is True
+    assert inference_route._loaded_satisfies("unsloth/A-GGUF:8b") is True
+    assert inference_route._loaded_satisfies("unsloth/A-GGUF:UD-Q4_K_XL") is True
+    assert inference_route._loaded_satisfies("unsloth/A-GGUF:Q8_0") is False
+
+
+def test_a_probing_adoption_never_releases_the_slot(hub, monkeypatch):
+    # A second request arriving while the first is still probing must not read
+    # the whole-repo job key: a stale error there would free the probe's slot.
+    hub["on_probe"] = lambda: _run_nested()
+    seen = {}
+
+    def _run_nested():
+        async def _stale(repo, variant):
+            seen["queried"] = True
+            return "error", "an older failure"
+
+        monkeypatch.setattr(auto_dl, "_job_state", _stale)
+        seen["refusal"] = _run("unsloth/x-GGUF")
+
+    assert _run("unsloth/x-GGUF").code == "model_downloading"
+    assert seen["refusal"].code == "model_downloading"
+    assert "queried" not in seen  # the stale job key was never consulted

From 68723b44835c39c48d0387811a2541be0471932b Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Sun, 26 Jul 2026 14:10:46 +0000
Subject: [PATCH 18/56] Studio: stop treating a namespace as what decides model
 intent

The rule refused a reference only when it carried a namespace, which was
wrong in both directions. vendor/model is how LiteLLM and OpenRouter name
every provider, and a standalone or custom-folder GGUF is advertised
without one, so asking for a path-free local id such as model-Q4_K_M was
answered by whatever else happened to be resident. The slashless early
return is gone and the same evidence test now applies to every id: an
explicit quant, or a model that actually resolves here. gpt-4 and default
still fall through because they are not local, not because of their shape.

Also:

- Recognise bits-per-weight quant labels. _extract_quant_label emits
  IQ4_XS-3.53bpw and the resolver and downloader both accept it, but
  _GGUF_KNOWN_QUANT_RE has no bpw group, so looks_like_quant rejected a
  reference the rest of the machinery understands.
- Upper-case the synthetic names handed to _pick_best_gguf. Its preference
  tokens are upper case and matched case-sensitively, so a repo with
  lower-case filenames skipped the preference and took the first entry,
  which can be F16.
- Only offer a downloaded but unloaded model as a runnable example when
  auto-switch is on. It is off by default, so the copied snippet hit the
  no-model-loaded error, which is the failure this branch exists to fix.

The tool-passthrough cancel test stubbed asyncio.to_thread module-wide, so
it cancelled at the first thread hop rather than the generation hop it
means to test. Model resolution runs off the loop before the monitor row
opens, so that stub now passes the resolver through.
---
 .../core/inference/openai_auto_download.py    | 18 ++++++--
 studio/backend/routes/inference.py            | 15 +++---
 .../tests/test_openai_auto_download.py        | 46 +++++++++++++++++++
 .../tests/test_openai_tool_passthrough.py     | 13 +++++-
 .../settings/components/usage-examples.tsx    | 29 ++++++++----
 ...st_usage_examples_model_source_contract.py |  7 ++-
 6 files changed, 104 insertions(+), 24 deletions(-)

diff --git a/studio/backend/core/inference/openai_auto_download.py b/studio/backend/core/inference/openai_auto_download.py
index 9b42110fd5d..f6bca0e3f3a 100644
--- a/studio/backend/core/inference/openai_auto_download.py
+++ b/studio/backend/core/inference/openai_auto_download.py
@@ -122,11 +122,16 @@ def looks_like_quant(variant: Optional[str]) -> bool:
     ``name:latest`` is how Ollama tags one, so neither a namespace nor a colon
     proves a request was meant for this server. A real quant label does.
     """
+    import re
+
     from utils.models.model_config import _GGUF_KNOWN_QUANT_RE
 
     if not variant:
         return False
-    return _GGUF_KNOWN_QUANT_RE.fullmatch(variant.strip()) is not None
+    # _extract_quant_label appends a bits-per-weight modifier when a repo ships
+    # several files at one base quant (IQ4_XS-3.53bpw); still a quant request.
+    label = re.sub(r"-[0-9]+(?:\.[0-9]+)?bpw$", "", variant.strip(), flags = re.IGNORECASE)
+    return _GGUF_KNOWN_QUANT_RE.fullmatch(label) is not None
 
 
 def _hub_token(hf_token: Optional[str]):
@@ -553,9 +558,14 @@ def _match_variant(wanted: Optional[str], variants: dict[str, int]) -> Optional[
         return lowered.get(wanted.strip().lower())
     from utils.models.model_config import _pick_best_gguf
 
-    # _pick_best_gguf ranks filenames, so feed it "<label>.gguf" and strip the suffix back off.
-    best = _pick_best_gguf([f"{name}.gguf" for name in variants])
-    return best[: -len(".gguf")] if best else None
+    # _pick_best_gguf ranks filenames, so feed it "<label>.gguf". Its preference
+    # tokens are upper case and matched case-sensitively, so upper-case the keys
+    # and map the winner back, or a lower-case repo takes the first entry.
+    synthetic: dict[str, str] = {}
+    for name in variants:
+        synthetic.setdefault(f"{name.upper()}.gguf", name)
+    best = _pick_best_gguf(list(synthetic))
+    return synthetic.get(best) if best else None
 
 
 async def _dispatch(
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 0aba0d9a2b5..172c9ea4804 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3804,12 +3804,13 @@ async def _reject_unservable_model(
     """Refuse rather than answer a named model with a different one.
 
     Only for a reference this server can tell was meant for it: an explicit GGUF
-    quant, or a repo that is actually here. A bare ``vendor/model`` is not enough
-    on its own, because that is how LiteLLM and OpenRouter name every provider,
-    so ``anthropic/claude-3.5-sonnet`` keeps falling through to the resident
-    model exactly like ``gpt-4``. Only runs while something is serving; with
-    nothing loaded the caller's own :func:`_no_model_loaded_error` already says
-    the right thing.
+    quant, or a model that is actually here. A namespace decides nothing either
+    way. ``vendor/model`` is how LiteLLM and OpenRouter name every provider, so
+    ``anthropic/claude-3.5-sonnet`` falls through like ``gpt-4``; a standalone or
+    custom-folder GGUF is advertised without one, so a slashless id that does
+    resolve locally is still a concrete reference. Only runs while something is
+    serving; with nothing loaded the caller's own :func:`_no_model_loaded_error`
+    already says the right thing.
     """
     from core.inference.openai_auto_download import looks_like_quant, split_model_ref
 
@@ -3820,8 +3821,6 @@ async def _reject_unservable_model(
     ):
         return
     base, variant = split_model_ref(requested_model)
-    if "/" not in base:
-        return
     quantified = looks_like_quant(variant)
     from core.inference.local_model_resolver import resolve_local_gguf
     from utils.openai_auto_switch_settings import get_openai_auto_switch_enabled
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index 5adb96d7866..f9d9d12d816 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -991,3 +991,49 @@ async def _stale(repo, variant):
     assert _run("unsloth/x-GGUF").code == "model_downloading"
     assert seen["refusal"].code == "model_downloading"
     assert "queried" not in seen  # the stale job key was never consulted
+
+
+def test_a_bpw_qualified_quant_is_a_quant_request():
+    # _extract_quant_label emits these for repos shipping several files at one
+    # base quant, and the resolver and downloader both accept them.
+    assert auto_dl.looks_like_quant("IQ4_XS-3.53bpw")
+    assert auto_dl.looks_like_quant("UD-Q4_K_XL-4.19BPW")
+    assert not auto_dl.looks_like_quant("3.53bpw")
+
+
+def test_the_default_pick_survives_lowercase_quant_labels():
+    # _pick_best_gguf matches its upper-case preference tokens case-sensitively,
+    # so a lower-case repo would otherwise take the first entry, often F16.
+    lowered = {"f16": 20, "ud-q4_k_xl": 4, "q8_0": 9}
+    assert auto_dl._match_variant(None, lowered) == "ud-q4_k_xl"
+    # The upper-case case must be unchanged.
+    assert auto_dl._match_variant(None, {"F16": 20, "UD-Q4_K_XL": 4}) == "UD-Q4_K_XL"
+
+
+def test_a_slashless_local_model_is_still_a_concrete_reference(monkeypatch):
+    # Standalone and custom-folder GGUFs are advertised by /v1/models without a
+    # namespace, so a namespace cannot be what decides intent.
+    loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
+    monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+    monkeypatch.setattr(
+        inference_route,
+        "get_inference_backend",
+        lambda: type("B", (), {"active_model_name": None})(),
+    )
+    monkeypatch.setattr(inference_route, "_unavailable_model_message", _fake_unavailable_message)
+    monkeypatch.setattr(
+        "utils.openai_auto_switch_settings.get_openai_auto_switch_enabled", lambda: False
+    )
+
+    monkeypatch.setattr(
+        "core.inference.local_model_resolver.resolve_local_gguf",
+        lambda name: ("/p", None, name) if name.startswith("standalone-Q4_K_M") else None,
+    )
+    with pytest.raises(HTTPException) as excinfo:
+        asyncio.run(inference_route._reject_unservable_model("standalone-Q4_K_M", _Req()))
+    assert excinfo.value.status_code == 404
+
+    # A slashless name that is not here stays a foreign label.
+    monkeypatch.setattr("core.inference.local_model_resolver.resolve_local_gguf", lambda name: None)
+    assert asyncio.run(inference_route._reject_unservable_model("gpt-4", _Req())) is None
+    assert asyncio.run(inference_route._reject_unservable_model("default", _Req())) is None
diff --git a/studio/backend/tests/test_openai_tool_passthrough.py b/studio/backend/tests/test_openai_tool_passthrough.py
index 161c8743c40..10e3fd4f381 100644
--- a/studio/backend/tests/test_openai_tool_passthrough.py
+++ b/studio/backend/tests/test_openai_tool_passthrough.py
@@ -1611,7 +1611,7 @@ def test_openai_compat_stream_stall_timeout_non_positive_env_disables(
     def test_openai_stream_error_sse_closes_with_done(self):
         error = {"error": {"message": "boom"}}
         assert _openai_stream_error_sse(error) == (
-            'data: {"error": {"message": "boom"}}\n\n' "data: [DONE]\n\n"
+            'data: {"error": {"message": "boom"}}\n\ndata: [DONE]\n\n'
         )
 
     @pytest.mark.parametrize(
@@ -6473,7 +6473,16 @@ def reset_generation_state(self):
                     nonlocal reset_called
                     reset_called = True
 
-            async def fake_to_thread(*_args, **_kwargs):
+            async def fake_to_thread(
+                func = None,
+                *_args,
+                **_kwargs,
+            ):
+                # Only the generation hop should cancel. Model resolution also
+                # runs off the loop, and it happens before the monitor row opens,
+                # so cancelling there would test nothing about finalization.
+                if getattr(func, "__name__", "") == "resolve_local_gguf":
+                    return None
                 raise asyncio.CancelledError()
 
             monitor = ApiMonitor(max_entries = 3)
diff --git a/studio/frontend/src/features/settings/components/usage-examples.tsx b/studio/frontend/src/features/settings/components/usage-examples.tsx
index 385912ac3d1..e7cf29a5a25 100644
--- a/studio/frontend/src/features/settings/components/usage-examples.tsx
+++ b/studio/frontend/src/features/settings/components/usage-examples.tsx
@@ -29,6 +29,7 @@ import { HugeiconsIcon } from "@hugeicons/react";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { Streamdown } from "streamdown";
 import { loadCodingAgents } from "../api/coding-agents";
+import { loadOpenAIAutoSwitchSettings } from "../api/openai-auto-switch";
 import { type OpenAIModel, listOpenAIModels } from "../api/openai-models";
 import { buildAgentCommand, isLoopbackHost, normalizeHost } from "./agent-command";
 
@@ -372,6 +373,8 @@ function useExampleModelName(): string | null {
   const ggufVariant = useChatRuntimeStore((s) => s.activeGgufVariant);
   // null until /v1/models answers: "not asked yet" must not read as "holds nothing".
   const [catalog, setCatalog] = useState<OpenAIModel[] | null>(null);
+  // A downloaded but unloaded model is only runnable when switching is on.
+  const [autoSwitch, setAutoSwitch] = useState(false);
   const usableCheckpoint =
     !!checkpoint && !checkpoint.startsWith("external::") && !looksLikePath(checkpoint);
   const needsCatalog = !usableCheckpoint;
@@ -385,12 +388,20 @@ function useExampleModelName(): string | null {
     let timeoutId: number | null = null;
 
     const update = () => {
-      void listOpenAIModels()
-        .then((models) => {
-          if (!cancelled) setCatalog(models);
-          return models.length > 0;
+      void Promise.all([
+        listOpenAIModels().catch(() => [] as OpenAIModel[]),
+        loadOpenAIAutoSwitchSettings()
+          .then((s) => s.enabled)
+          .catch(() => false),
+      ])
+        .then(([models, enabled]) => {
+          if (cancelled) return true;
+          setCatalog(models);
+          setAutoSwitch(enabled);
+          // Keep retrying until a snippet would actually run, so turning
+          // switching on in the row above is picked up here too.
+          return models.some((m) => m.loaded) || (enabled && models.length > 0);
         })
-        .catch(() => false)
         .then((resolved) => {
           if (cancelled || resolved) return;
           timeoutId = window.setTimeout(update, CATALOG_RETRY_MS);
@@ -412,15 +423,17 @@ function useExampleModelName(): string | null {
       return checkpoint;
     }
     // No usable checkpoint: name something this server holds, quant included so the
-    // request pins the file on disk rather than letting the server pick.
-    const pick = catalog?.find((m) => m.loaded) ?? catalog?.[0];
+    // request pins the file on disk rather than letting the server pick. An
+    // unloaded one only answers when switching is on, which is off by default.
+    const pick =
+      catalog?.find((m) => m.loaded) ?? (autoSwitch ? catalog?.[0] : undefined);
     if (!pick) {
       return null;
     }
     return pick.quant && !pick.id.includes(":")
       ? `${pick.id}:${pick.quant}`
       : pick.id;
-  }, [catalog, checkpoint, ggufVariant, usableCheckpoint]);
+  }, [autoSwitch, catalog, checkpoint, ggufVariant, usableCheckpoint]);
 }
 
 // Backend PATH detection is only safe in the desktop app, where the UI owns
diff --git a/tests/studio/test_usage_examples_model_source_contract.py b/tests/studio/test_usage_examples_model_source_contract.py
index 0ecd944c008..d06453849f2 100644
--- a/tests/studio/test_usage_examples_model_source_contract.py
+++ b/tests/studio/test_usage_examples_model_source_contract.py
@@ -23,7 +23,8 @@ def test_examples_name_a_model_the_server_can_serve():
     hook = src[src.find("function useExampleModelName") : src.find("// Backend PATH detection")]
     assert "listOpenAIModels()" in hook
     # Precedence: live checkpoint, then a loaded catalog entry, then any entry, then none.
-    assert "catalog?.find((m) => m.loaded) ?? catalog?.[0]" in hook
+    # An unloaded entry is only offered when switching would actually load it.
+    assert "catalog?.find((m) => m.loaded) ?? (autoSwitch ? catalog?.[0] : undefined)" in hook
     # The snippet pins the quant so the request names the file on disk.
     assert "`${pick.id}:${pick.quant}`" in hook
 
@@ -67,7 +68,9 @@ def test_usage_examples_has_no_duplicate_auto_switch_control():
     # ModelAutoSwitchSection renders the same setting just below this panel and shares no
     # state with it, so a second switch here would drift out of sync.
     src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")
-    assert "openai-auto-switch" not in src
+    # Reading the setting is required: an unloaded model only answers when
+    # switching is on. Writing it here is what would be the second control.
+    assert "updateOpenAIAutoSwitchSettings" not in src
     assert "SWITCH_NOTE" not in src
     assert "Switch model by request" not in src
     assert "pythonSwitchDemo" not in src

From 86f772d2a2948ed8f081c74776d6f7db5e91b335 Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Sun, 26 Jul 2026 14:18:11 +0000
Subject: [PATCH 19/56] Studio: tighten the comments added since the last pass

---
 studio/backend/core/inference/model_ids.py    |  3 +--
 .../core/inference/openai_auto_download.py    | 13 +++++------
 .../hub/services/download_lifecycle.py        |  3 +--
 studio/backend/routes/inference.py            |  3 +--
 .../tests/test_openai_auto_download.py        | 22 ++++++-------------
 .../tests/test_openai_tool_passthrough.py     |  5 ++---
 .../settings/components/usage-examples.tsx    |  6 ++---
 ...st_usage_examples_model_source_contract.py |  6 ++---
 8 files changed, 21 insertions(+), 40 deletions(-)

diff --git a/studio/backend/core/inference/model_ids.py b/studio/backend/core/inference/model_ids.py
index 80314eb1475..a6270b955e2 100644
--- a/studio/backend/core/inference/model_ids.py
+++ b/studio/backend/core/inference/model_ids.py
@@ -50,8 +50,7 @@ def hf_cache_repo_id(path: Optional[str]) -> Optional[str]:
         return None
     parts = str(path).replace("\\", "/").split("/")
     for index, part in enumerate(parts):
-        # Only inside the real cache layout: an ordinary directory that merely
-        # starts with "models--" is not an encoded repo id.
+        # Only inside the real cache layout: a "models--" name alone is not a repo id.
         if part.startswith("models--") and parts[index + 1 : index + 2] == ["snapshots"]:
             return part[len("models--") :].replace("--", "/")
     return None
diff --git a/studio/backend/core/inference/openai_auto_download.py b/studio/backend/core/inference/openai_auto_download.py
index f6bca0e3f3a..d002c757e56 100644
--- a/studio/backend/core/inference/openai_auto_download.py
+++ b/studio/backend/core/inference/openai_auto_download.py
@@ -128,8 +128,7 @@ def looks_like_quant(variant: Optional[str]) -> bool:
 
     if not variant:
         return False
-    # _extract_quant_label appends a bits-per-weight modifier when a repo ships
-    # several files at one base quant (IQ4_XS-3.53bpw); still a quant request.
+    # _extract_quant_label can append a bpw modifier (IQ4_XS-3.53bpw); still a quant.
     label = re.sub(r"-[0-9]+(?:\.[0-9]+)?bpw$", "", variant.strip(), flags = re.IGNORECASE)
     return _GGUF_KNOWN_QUANT_RE.fullmatch(label) is not None
 
@@ -390,9 +389,8 @@ async def maybe_auto_download(
 
     if adopted is not None:
         if adopted.variant is None:
-            # Still probing, so it owns the slot and has no job to look up yet.
-            # Reading the whole-repo key here could find an older error and
-            # release a slot the probe is still using.
+            # Still probing: no job yet, and a stale whole-repo error would
+            # release the slot the probe is using.
             return _downloading_refusal(adopted.repo_id, None)
         state, error = await _job_state(adopted.repo_id, adopted.variant)
         if state in ("running", "cancelling", "unknown"):
@@ -558,9 +556,8 @@ def _match_variant(wanted: Optional[str], variants: dict[str, int]) -> Optional[
         return lowered.get(wanted.strip().lower())
     from utils.models.model_config import _pick_best_gguf
 
-    # _pick_best_gguf ranks filenames, so feed it "<label>.gguf". Its preference
-    # tokens are upper case and matched case-sensitively, so upper-case the keys
-    # and map the winner back, or a lower-case repo takes the first entry.
+    # _pick_best_gguf ranks filenames, so feed it "<label>.gguf". It matches its
+    # upper-case preference tokens case-sensitively, so upper-case and map back.
     synthetic: dict[str, str] = {}
     for name in variants:
         synthetic.setdefault(f"{name.upper()}.gguf", name)
diff --git a/studio/backend/hub/services/download_lifecycle.py b/studio/backend/hub/services/download_lifecycle.py
index 5b028bab0e6..78a5bc4c132 100644
--- a/studio/backend/hub/services/download_lifecycle.py
+++ b/studio/backend/hub/services/download_lifecycle.py
@@ -84,8 +84,7 @@ def spawn_worker(
     env["HF_HUB_DISABLE_XET"] = "0" if use_xet else "1"
     # No token in Unsloth settings: fall back to the backend's own HF_TOKEN so
     # private repos stay downloadable (needed while inkling repos are private).
-    # Not for a repo an API caller named: that would lend them the owner's Hub
-    # identity, so those dispatches opt out and stay anonymous.
+    # Not for a repo an API caller named: that would lend them the owner's identity.
     if not hf_token and allow_ambient_token:
         hf_token = os.environ.get("HF_TOKEN") or None
     env["HF_HUB_DISABLE_IMPLICIT_TOKEN"] = "0" if hf_token else "1"
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 172c9ea4804..8b3b34ceef1 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3784,8 +3784,7 @@ def _loaded_satisfies(requested: str) -> bool:
         if base not in keys:
             return False
         if not looks_like_quant(variant):
-            # A non-quant tag (Ollama style ":latest", ":8b") is not a claim
-            # about which file is loaded, so the repo match is enough.
+            # An Ollama-style tag (":latest", ":8b") names no file, so the repo is enough.
             return True
         return (getattr(llama_backend, "hf_variant", None) or "").lower() == variant.lower()
     active = getattr(get_inference_backend(), "active_model_name", None)
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index f9d9d12d816..147df580572 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -946,16 +946,14 @@ def test_a_quant_cannot_be_satisfied_by_a_non_gguf_backend(monkeypatch):
 
 
 def test_the_worker_is_never_given_the_servers_own_token(hub):
-    # download_lifecycle substitutes the backend's HF_TOKEN for a falsy one, so
-    # passing None here would hand an API caller the owner's Hub identity.
+    # A falsy token would make the worker fall back to the server owner's HF_TOKEN.
     assert _run("unsloth/x-GGUF").code == "model_downloading"
     assert hub["started"][0][2] is None
     assert hub["allow_ambient"] is False
 
 
 def test_the_metadata_probe_is_explicitly_anonymous(hub):
-    # huggingface_hub treats token=None as "use a cached login"; only False is
-    # anonymous, and the cached login here would be the server owner's.
+    # token=None means "use the cached login" to huggingface_hub; only False is anonymous.
     _run("unsloth/x-GGUF")
     assert hub["token"] is False
     auto_dl.reset_for_tests()
@@ -964,8 +962,7 @@ def test_the_metadata_probe_is_explicitly_anonymous(hub):
 
 
 def test_an_ollama_tag_still_matches_the_resident_gguf(monkeypatch):
-    # looks_like_quant() calls these foreign tags, so the llama.cpp branch must
-    # not compare them against hf_variant and refuse the resident model.
+    # looks_like_quant() calls these foreign, so they must not be checked against hf_variant.
     loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
     monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
     assert inference_route._loaded_satisfies("unsloth/A-GGUF:latest") is True
@@ -975,8 +972,7 @@ def test_an_ollama_tag_still_matches_the_resident_gguf(monkeypatch):
 
 
 def test_a_probing_adoption_never_releases_the_slot(hub, monkeypatch):
-    # A second request arriving while the first is still probing must not read
-    # the whole-repo job key: a stale error there would free the probe's slot.
+    # The whole-repo job key can hold a stale error that would free the probe's slot.
     hub["on_probe"] = lambda: _run_nested()
     seen = {}
 
@@ -994,25 +990,21 @@ async def _stale(repo, variant):
 
 
 def test_a_bpw_qualified_quant_is_a_quant_request():
-    # _extract_quant_label emits these for repos shipping several files at one
-    # base quant, and the resolver and downloader both accept them.
+    # _extract_quant_label emits these for repos shipping several files at one base quant.
     assert auto_dl.looks_like_quant("IQ4_XS-3.53bpw")
     assert auto_dl.looks_like_quant("UD-Q4_K_XL-4.19BPW")
     assert not auto_dl.looks_like_quant("3.53bpw")
 
 
 def test_the_default_pick_survives_lowercase_quant_labels():
-    # _pick_best_gguf matches its upper-case preference tokens case-sensitively,
-    # so a lower-case repo would otherwise take the first entry, often F16.
+    # Preference tokens match case-sensitively, so a lower-case repo would take F16.
     lowered = {"f16": 20, "ud-q4_k_xl": 4, "q8_0": 9}
     assert auto_dl._match_variant(None, lowered) == "ud-q4_k_xl"
-    # The upper-case case must be unchanged.
     assert auto_dl._match_variant(None, {"F16": 20, "UD-Q4_K_XL": 4}) == "UD-Q4_K_XL"
 
 
 def test_a_slashless_local_model_is_still_a_concrete_reference(monkeypatch):
-    # Standalone and custom-folder GGUFs are advertised by /v1/models without a
-    # namespace, so a namespace cannot be what decides intent.
+    # /v1/models advertises these without a namespace, so a namespace decides nothing.
     loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
     monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
     monkeypatch.setattr(
diff --git a/studio/backend/tests/test_openai_tool_passthrough.py b/studio/backend/tests/test_openai_tool_passthrough.py
index 10e3fd4f381..9a17e52ae78 100644
--- a/studio/backend/tests/test_openai_tool_passthrough.py
+++ b/studio/backend/tests/test_openai_tool_passthrough.py
@@ -6478,9 +6478,8 @@ async def fake_to_thread(
                 *_args,
                 **_kwargs,
             ):
-                # Only the generation hop should cancel. Model resolution also
-                # runs off the loop, and it happens before the monitor row opens,
-                # so cancelling there would test nothing about finalization.
+                # Only the generation hop should cancel: resolution runs off the loop
+                # too, but before the monitor row opens, so it would test nothing.
                 if getattr(func, "__name__", "") == "resolve_local_gguf":
                     return None
                 raise asyncio.CancelledError()
diff --git a/studio/frontend/src/features/settings/components/usage-examples.tsx b/studio/frontend/src/features/settings/components/usage-examples.tsx
index e7cf29a5a25..c1df784a8eb 100644
--- a/studio/frontend/src/features/settings/components/usage-examples.tsx
+++ b/studio/frontend/src/features/settings/components/usage-examples.tsx
@@ -398,8 +398,7 @@ function useExampleModelName(): string | null {
           if (cancelled) return true;
           setCatalog(models);
           setAutoSwitch(enabled);
-          // Keep retrying until a snippet would actually run, so turning
-          // switching on in the row above is picked up here too.
+          // Retry until a snippet would actually run, so switching turned on above lands.
           return models.some((m) => m.loaded) || (enabled && models.length > 0);
         })
         .then((resolved) => {
@@ -423,8 +422,7 @@ function useExampleModelName(): string | null {
       return checkpoint;
     }
     // No usable checkpoint: name something this server holds, quant included so the
-    // request pins the file on disk rather than letting the server pick. An
-    // unloaded one only answers when switching is on, which is off by default.
+    // request pins the file on disk. An unloaded one only answers if switching is on.
     const pick =
       catalog?.find((m) => m.loaded) ?? (autoSwitch ? catalog?.[0] : undefined);
     if (!pick) {
diff --git a/tests/studio/test_usage_examples_model_source_contract.py b/tests/studio/test_usage_examples_model_source_contract.py
index d06453849f2..9d47aebcda2 100644
--- a/tests/studio/test_usage_examples_model_source_contract.py
+++ b/tests/studio/test_usage_examples_model_source_contract.py
@@ -22,8 +22,7 @@ def test_examples_name_a_model_the_server_can_serve():
     assert "function useExampleModelName(): string" in src
     hook = src[src.find("function useExampleModelName") : src.find("// Backend PATH detection")]
     assert "listOpenAIModels()" in hook
-    # Precedence: live checkpoint, then a loaded catalog entry, then any entry, then none.
-    # An unloaded entry is only offered when switching would actually load it.
+    # Precedence: live checkpoint, then a loaded entry, then any entry if switching is on.
     assert "catalog?.find((m) => m.loaded) ?? (autoSwitch ? catalog?.[0] : undefined)" in hook
     # The snippet pins the quant so the request names the file on disk.
     assert "`${pick.id}:${pick.quant}`" in hook
@@ -68,8 +67,7 @@ def test_usage_examples_has_no_duplicate_auto_switch_control():
     # ModelAutoSwitchSection renders the same setting just below this panel and shares no
     # state with it, so a second switch here would drift out of sync.
     src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")
-    # Reading the setting is required: an unloaded model only answers when
-    # switching is on. Writing it here is what would be the second control.
+    # Reading the setting is fine; writing it here is what would be a second control.
     assert "updateOpenAIAutoSwitchSettings" not in src
     assert "SWITCH_NOTE" not in src
     assert "Switch model by request" not in src

From 00f1c939ba170e5f70b49e9622cc26eaa0068e0f Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Sun, 26 Jul 2026 15:06:02 +0000
Subject: [PATCH 20/56] Studio: match a resident model through its resolver
 alias

A manual load stores the model by its on-disk path while the resolver and
/v1/models advertise it as publisher/model, so _loaded_satisfies could not
recognise the alias. Reducing the resolution to a boolean then threw away
the load path that would have proved the match, and the request was
refused with 404 for a model the server was serving at that moment. Common
for LM Studio models and custom-folder aliases. The resolved path is
compared against the resident backend before anything is refused.

Also:

- Size disk admission on what is left to fetch. expected_bytes is the whole
  plan, so a resumed quant or a companion already pulled in by another
  quant was charged for twice and could 507 a download that fits. Cached
  blobs are subtracted through existing_blob_bytes, the same accounting the
  worker's own preflight does, and it falls open to the full size when no
  blob hashes are available.
- Report a cancelled download as cancelled. The catch-all sent every state
  other than complete or idle through fail_open, so a deliberate cancel
  rendered as a download failure rather than the monitor's cancelled state.
- Keep polling the servable ids while nothing is loaded. The poll settled
  as soon as auto-switch was on, so turning it back off left the examples
  naming an unloaded model until something else remounted the panel.
---
 .../core/inference/openai_auto_download.py    | 29 +++++++-
 studio/backend/routes/inference.py            | 35 +++++++++-
 .../tests/test_openai_auto_download.py        | 69 +++++++++++++++++++
 .../settings/components/usage-examples.tsx    |  5 +-
 4 files changed, 133 insertions(+), 5 deletions(-)

diff --git a/studio/backend/core/inference/openai_auto_download.py b/studio/backend/core/inference/openai_auto_download.py
index d002c757e56..cefcc550dca 100644
--- a/studio/backend/core/inference/openai_auto_download.py
+++ b/studio/backend/core/inference/openai_auto_download.py
@@ -234,6 +234,22 @@ def _gguf_variants(siblings) -> dict[str, int]:
     return sizes
 
 
+def _remaining_bytes(repo_id: str, plan, expected_bytes: int) -> int:
+    """Bytes still to fetch: a resumed quant or a companion shared with another
+    quant is already on disk, and charging for it can 507 a download that fits."""
+    try:
+        from hub.utils.download_registry import existing_blob_bytes
+
+        hashes = frozenset(
+            file.sha256 for file in getattr(plan, "expected_files", ()) or () if file.sha256
+        )
+        if not hashes:
+            return expected_bytes
+        return max(0, expected_bytes - existing_blob_bytes("model", repo_id, hashes))
+    except Exception:
+        return expected_bytes
+
+
 def _enough_disk(need_bytes: int) -> tuple[bool, int]:
     """(fits, free_bytes). Fail-open on an unreadable cache root: the download
     worker runs its own preflight, this only adds the reserve margin."""
@@ -320,6 +336,9 @@ async def _watch(active: _Active, hf_token: Optional[str]) -> None:
                         ),
                     )
                 continue
+            if state == "cancelled":
+                api_monitor.finish(active.monitor_id, status = "cancelled")
+                return
             if state == "complete":
                 # Drop the resolver cache so the next retry sees the new model.
                 await asyncio.to_thread(invalidate_index)
@@ -529,14 +548,20 @@ def _probe():
         )
 
     expected_bytes = variants[variant]
-    fits, free = _enough_disk(expected_bytes)
+    from hub.utils.gguf_plan import build_gguf_variant_plans
+
+    plan = build_gguf_variant_plans(list(getattr(info, "siblings", None) or [])).get(
+        variant.lower()
+    )
+    need_bytes = _remaining_bytes(repo_id, plan, expected_bytes)
+    fits, free = _enough_disk(need_bytes)
     if not fits:
         _release(active)
         return AutoDownloadRefusal(
             status = 507,
             code = "insufficient_disk_space",
             message = (
-                f"'{_public_label(repo_id, variant)}' needs {_gb(expected_bytes)} plus "
+                f"'{_public_label(repo_id, variant)}' needs {_gb(need_bytes)} plus "
                 f"{_gb(_DISK_RESERVE_BYTES)} headroom, but only {_gb(free)} is free."
             ),
         )
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 8b3b34ceef1..a8c29da9eea 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3797,6 +3797,33 @@ def _loaded_satisfies(requested: str) -> bool:
     return base in {active.lower(), (public_model_id(active) or "").lower()}
 
 
+def _resolves_to_resident(load_path: Optional[str]) -> bool:
+    """Whether a resolved on-disk path is what is already loaded."""
+    if not load_path:
+        return False
+    target = str(load_path).replace("\\", "/").rstrip("/").lower()
+    llama_backend = get_llama_cpp_backend()
+    for candidate in (
+        getattr(llama_backend, "gguf_path", None)
+        if getattr(llama_backend, "is_loaded", False)
+        else None,
+        getattr(llama_backend, "model_identifier", None)
+        if getattr(llama_backend, "is_loaded", False)
+        else None,
+        getattr(get_inference_backend(), "active_model_name", None),
+    ):
+        if not candidate:
+            continue
+        current = str(candidate).replace("\\", "/").rstrip("/").lower()
+        if (
+            current == target
+            or current.startswith(f"{target}/")
+            or target.startswith(f"{current}/")
+        ):
+            return True
+    return False
+
+
 async def _reject_unservable_model(
     requested_model: Optional[str], fastapi_request: Optional[Request]
 ) -> None:
@@ -3832,7 +3859,13 @@ async def _reject_unservable_model(
             or getattr(get_inference_backend(), "active_model_name", None)
         ):
             return
-        downloaded = await asyncio.to_thread(resolve_local_gguf, requested_model) is not None
+        resolved = await asyncio.to_thread(resolve_local_gguf, requested_model)
+        # A manual load stores the on-disk path while the resolver advertises a
+        # publisher/model alias for it (LM Studio, custom folders), so compare the
+        # resolved path too before calling a resident model unservable.
+        if resolved is not None and _resolves_to_resident(resolved[0]):
+            return
+        downloaded = resolved is not None
         # The exact ref may miss on the quant alone, so ask about the repo too.
         here = downloaded or (
             variant is not None and await asyncio.to_thread(resolve_local_gguf, base) is not None
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index 147df580572..1c18f1b7596 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -24,9 +24,12 @@ def __init__(
         self,
         rfilename,
         size = 0,
+        blob_id = None,
     ):
         self.rfilename = rfilename
         self.size = size
+        # The plan identifies cached blobs by hash; None means "not known".
+        self.blob_id = blob_id
 
 
 class _Info:
@@ -1029,3 +1032,69 @@ def test_a_slashless_local_model_is_still_a_concrete_reference(monkeypatch):
     monkeypatch.setattr("core.inference.local_model_resolver.resolve_local_gguf", lambda name: None)
     assert asyncio.run(inference_route._reject_unservable_model("gpt-4", _Req())) is None
     assert asyncio.run(inference_route._reject_unservable_model("default", _Req())) is None
+
+
+def test_a_cancelled_download_is_not_reported_as_failed(hub, monkeypatch):
+    # The monitor has its own cancelled state; routing every non-complete state
+    # through fail_open rendered a deliberate cancel as "Model download failed".
+    from core.inference import api_monitor as monitor_module
+
+    assert _run("unsloth/x-GGUF:UD-Q4_K_XL").code == "model_downloading"
+    active = hub["watched"][-1]
+
+    async def _cancelled(repo, variant):
+        return "cancelled", None
+
+    monkeypatch.setattr(auto_dl, "_job_state", _cancelled)
+    monkeypatch.setattr(auto_dl, "_WATCH_POLL_S", 0)
+    asyncio.run(hub["real_watch"](active, None))
+    [row] = [e for e in monitor_module.api_monitor.snapshot() if e["id"] == active.monitor_id]
+    assert row["status"] == "cancelled"
+    assert row.get("error") is None
+
+
+def test_disk_admission_counts_only_what_is_left_to_fetch(hub, monkeypatch):
+    # A resumed quant, or a companion already pulled in by another quant, is on
+    # disk; charging for it 507s a download that fits.
+    seen = {}
+
+    def _enough(need):
+        seen["need"] = need
+        return True, 10 * 1024**4
+
+    gb = 1024**3
+    hub["info"] = _Info(
+        [
+            _Sibling("model-UD-Q4_K_XL.gguf", 4 * gb, blob_id = "sha-main"),
+            _Sibling("mmproj-F16.gguf", 1 * gb, blob_id = "sha-mmproj"),
+            _Sibling("mtp-model.gguf", 1 * gb, blob_id = "sha-mtp"),
+        ]
+    )
+    monkeypatch.setattr(auto_dl, "_enough_disk", _enough)
+    monkeypatch.setattr(
+        "hub.utils.download_registry.existing_blob_bytes",
+        lambda repo_type, repo_id, hashes: 3 * gb,
+    )
+    assert _run("unsloth/x-GGUF:UD-Q4_K_XL").code == "model_downloading"
+    # 4 GB quant + 2 GB companions, 3 GB of which is already cached.
+    assert seen["need"] == 3 * gb
+
+
+def test_a_resolver_alias_for_the_resident_model_is_not_refused(monkeypatch):
+    # A manual load stores the on-disk path while /v1/models advertises
+    # publisher/model for it, so the alias must not read as unservable.
+    loaded = _Loaded("/models/publisher/model/weights.gguf", None)
+    monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+    monkeypatch.setattr(
+        inference_route,
+        "get_inference_backend",
+        lambda: type("B", (), {"active_model_name": None})(),
+    )
+    monkeypatch.setattr(
+        "core.inference.local_model_resolver.resolve_local_gguf",
+        lambda name: ("/models/publisher/model/weights.gguf", None, "publisher/model"),
+    )
+    monkeypatch.setattr(
+        "utils.openai_auto_switch_settings.get_openai_auto_switch_enabled", lambda: False
+    )
+    assert asyncio.run(inference_route._reject_unservable_model("publisher/model", _Req())) is None
diff --git a/studio/frontend/src/features/settings/components/usage-examples.tsx b/studio/frontend/src/features/settings/components/usage-examples.tsx
index c1df784a8eb..bee3295a9ef 100644
--- a/studio/frontend/src/features/settings/components/usage-examples.tsx
+++ b/studio/frontend/src/features/settings/components/usage-examples.tsx
@@ -398,8 +398,9 @@ function useExampleModelName(): string | null {
           if (cancelled) return true;
           setCatalog(models);
           setAutoSwitch(enabled);
-          // Retry until a snippet would actually run, so switching turned on above lands.
-          return models.some((m) => m.loaded) || (enabled && models.length > 0);
+          // Only a resident model settles this: while nothing is loaded the answer
+          // still follows the switch above, which can be turned back off.
+          return models.some((m) => m.loaded);
         })
         .then((resolved) => {
           if (cancelled || resolved) return;

From f180d585b5602af258d96884b316ca3a85b08d8d Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Sun, 26 Jul 2026 15:20:07 +0000
Subject: [PATCH 21/56] Studio: shorten the comments added in the last pass

---
 studio/backend/routes/inference.py                     |  5 ++---
 studio/backend/tests/test_openai_auto_download.py      | 10 +++-------
 .../features/settings/components/usage-examples.tsx    |  3 +--
 3 files changed, 6 insertions(+), 12 deletions(-)

diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index a8c29da9eea..af88850ac5d 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3860,9 +3860,8 @@ async def _reject_unservable_model(
         ):
             return
         resolved = await asyncio.to_thread(resolve_local_gguf, requested_model)
-        # A manual load stores the on-disk path while the resolver advertises a
-        # publisher/model alias for it (LM Studio, custom folders), so compare the
-        # resolved path too before calling a resident model unservable.
+        # A manual load stores the on-disk path that the resolver advertises under a
+        # publisher/model alias (LM Studio, custom folders); match on the path too.
         if resolved is not None and _resolves_to_resident(resolved[0]):
             return
         downloaded = resolved is not None
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index 1c18f1b7596..93fb1d4738a 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -28,7 +28,6 @@ def __init__(
     ):
         self.rfilename = rfilename
         self.size = size
-        # The plan identifies cached blobs by hash; None means "not known".
         self.blob_id = blob_id
 
 
@@ -1035,8 +1034,7 @@ def test_a_slashless_local_model_is_still_a_concrete_reference(monkeypatch):
 
 
 def test_a_cancelled_download_is_not_reported_as_failed(hub, monkeypatch):
-    # The monitor has its own cancelled state; routing every non-complete state
-    # through fail_open rendered a deliberate cancel as "Model download failed".
+    # fail_open rendered a deliberate cancel as "Model download failed".
     from core.inference import api_monitor as monitor_module
 
     assert _run("unsloth/x-GGUF:UD-Q4_K_XL").code == "model_downloading"
@@ -1054,8 +1052,7 @@ async def _cancelled(repo, variant):
 
 
 def test_disk_admission_counts_only_what_is_left_to_fetch(hub, monkeypatch):
-    # A resumed quant, or a companion already pulled in by another quant, is on
-    # disk; charging for it 507s a download that fits.
+    # Charging again for bytes already on disk 507s a download that fits.
     seen = {}
 
     def _enough(need):
@@ -1081,8 +1078,7 @@ def _enough(need):
 
 
 def test_a_resolver_alias_for_the_resident_model_is_not_refused(monkeypatch):
-    # A manual load stores the on-disk path while /v1/models advertises
-    # publisher/model for it, so the alias must not read as unservable.
+    # A manual load stores the on-disk path /v1/models aliases as publisher/model.
     loaded = _Loaded("/models/publisher/model/weights.gguf", None)
     monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
     monkeypatch.setattr(
diff --git a/studio/frontend/src/features/settings/components/usage-examples.tsx b/studio/frontend/src/features/settings/components/usage-examples.tsx
index bee3295a9ef..0dfb84ec24b 100644
--- a/studio/frontend/src/features/settings/components/usage-examples.tsx
+++ b/studio/frontend/src/features/settings/components/usage-examples.tsx
@@ -398,8 +398,7 @@ function useExampleModelName(): string | null {
           if (cancelled) return true;
           setCatalog(models);
           setAutoSwitch(enabled);
-          // Only a resident model settles this: while nothing is loaded the answer
-          // still follows the switch above, which can be turned back off.
+          // Only a resident model settles this; auto-switch can be turned back off.
           return models.some((m) => m.loaded);
         })
         .then((resolved) => {

From 300881e1e7a0595c884e996dccb5ae1bc0655644 Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Mon, 27 Jul 2026 00:23:10 +0000
Subject: [PATCH 22/56] Studio: keep the FLA fast-path tests hermetic across
 transformers versions

_discover_fla_model_types scans the *installed* transformers for modeling
files importing `from fla.`, so `models/qwen3_5/` only exists from
transformers 5.x. The backend supports transformers>=4.51, and on a 4.x
install the Qwen3.5 gate returns False, so 14 tests in
test_training_worker_flash_attn.py silently exercised a no-op instead of the
install path and failed their call-count assertions.

Pin the discovered model_type set in those 14 tests, the same way
test_hook_does_not_install_tilelang_for_model_outside_allowlist already pins
it against newly added FLA model_types. Test-only change: the production
gate and the _discover_fla_model_types unit tests are untouched.
---
 .../tests/test_training_worker_flash_attn.py  | 33 +++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/studio/backend/tests/test_training_worker_flash_attn.py b/studio/backend/tests/test_training_worker_flash_attn.py
index 7e7fc1af486..0c2fdc4628e 100644
--- a/studio/backend/tests/test_training_worker_flash_attn.py
+++ b/studio/backend/tests/test_training_worker_flash_attn.py
@@ -209,7 +209,27 @@ def fake_import(name, *a, **kw):
     monkeypatch.setattr(builtins, "__import__", fake_import)
 
 
+def _pin_fla_model_types(monkeypatch):
+    """Pin the auto-discovered FLA allowlist to the Qwen GDN families.
+
+    `_discover_fla_model_types` scans the *installed* transformers for modeling
+    files importing `from fla.`, and `models/qwen3_5/` only exists from
+    transformers 5.x. The backend supports `transformers>=4.51`, so on a 4.x
+    install the gate returns False and every Qwen3.5 assertion below silently
+    passes through a no-op instead of exercising the install path. Pinning keeps
+    these tests hermetic across the whole supported transformers range, the same
+    way test_hook_does_not_install_tilelang_for_model_outside_allowlist pins it
+    against newly added FLA model_types.
+    """
+    monkeypatch.setattr(
+        worker,
+        "_discover_fla_model_types",
+        lambda: frozenset({"qwen3_5", "qwen3_5_moe", "qwen3_6", "qwen3_next"}),
+    )
+
+
 def test_flash_linear_attention_installs_pinned_pair_for_qwen3_5(monkeypatch):
+    _pin_fla_model_types(monkeypatch)
     monkeypatch.setattr(worker.shutil, "which", lambda name: "/usr/bin/uv")
     run_mock = mock.Mock(return_value = mock.Mock(returncode = 0, stdout = ""))
     monkeypatch.setattr(worker._sp, "run", run_mock)
@@ -315,6 +335,7 @@ def test_flash_linear_attention_skipped_via_env(monkeypatch):
 
 
 def test_flash_linear_attention_skipped_below_torch_2_7(monkeypatch):
+    _pin_fla_model_types(monkeypatch)
     monkeypatch.delenv(worker._FLA_SKIP_ENV, raising = False)
     monkeypatch.setattr(worker, "_installed_torch_version_tuple", lambda: (2, 5))
     run_mock = mock.Mock(return_value = mock.Mock(returncode = 0, stdout = ""))
@@ -332,6 +353,7 @@ def test_flash_linear_attention_skipped_below_torch_2_7(monkeypatch):
 
 
 def test_flash_linear_attention_install_includes_einops(monkeypatch):
+    _pin_fla_model_types(monkeypatch)
     monkeypatch.delenv(worker._FLA_SKIP_ENV, raising = False)
     monkeypatch.setattr(worker.shutil, "which", lambda name: "/usr/bin/uv")
     monkeypatch.setattr(worker, "_installed_torch_version_tuple", lambda: (2, 9))
@@ -358,6 +380,7 @@ def test_flash_linear_attention_install_includes_einops(monkeypatch):
 
 def test_flash_linear_attention_logs_post_install_import_failure(monkeypatch):
     """pip exits 0 but `import fla.modules` still fails (missing transitive)."""
+    _pin_fla_model_types(monkeypatch)
     monkeypatch.delenv(worker._FLA_SKIP_ENV, raising = False)
     monkeypatch.setattr(worker.shutil, "which", lambda name: "/usr/bin/uv")
     monkeypatch.setattr(worker, "_installed_torch_version_tuple", lambda: (2, 9))
@@ -402,6 +425,7 @@ def test_tilelang_backend_skipped_on_unsupported_linux_arch(monkeypatch):
 
 
 def test_tilelang_backend_pins_only_binary(monkeypatch):
+    _pin_fla_model_types(monkeypatch)
     monkeypatch.delenv(worker._TILELANG_SKIP_ENV, raising = False)
     monkeypatch.setattr(worker.shutil, "which", lambda name: "/usr/bin/uv")
     monkeypatch.setattr(worker, "_installed_tvm_ffi_version", lambda: None)
@@ -442,6 +466,7 @@ def fake_import(name, *a, **kw):
 
 
 def test_tilelang_backend_installs_pinned_pair_for_qwen3_5(monkeypatch):
+    _pin_fla_model_types(monkeypatch)
     monkeypatch.delenv(worker._TILELANG_SKIP_ENV, raising = False)
     monkeypatch.setattr(worker.shutil, "which", lambda name: "/usr/bin/uv")
     monkeypatch.setattr(worker, "_installed_tvm_ffi_version", lambda: None)
@@ -472,6 +497,7 @@ def test_tilelang_backend_reinstalls_when_tvm_ffi_is_broken(monkeypatch):
     2 (install): plain apache-tvm-ffi + tilelang -- resolves missing transitive
       deps without --force-reinstall, so it never replaces correct packages.
     """
+    _pin_fla_model_types(monkeypatch)
     monkeypatch.delenv(worker._TILELANG_SKIP_ENV, raising = False)
     monkeypatch.setattr(worker.shutil, "which", lambda name: "/usr/bin/uv")
     monkeypatch.setattr(worker, "_installed_tvm_ffi_version", lambda: "0.1.11")
@@ -533,6 +559,7 @@ def test_tilelang_backend_skipped_on_windows(monkeypatch):
 
 
 def test_tilelang_backend_swallows_install_timeout(monkeypatch):
+    _pin_fla_model_types(monkeypatch)
     monkeypatch.delenv(worker._TILELANG_SKIP_ENV, raising = False)
     monkeypatch.setattr(worker.shutil, "which", lambda name: "/usr/bin/uv")
     monkeypatch.setattr(worker, "_installed_tvm_ffi_version", lambda: None)
@@ -586,6 +613,7 @@ def test_tilelang_backend_skipped_via_env(monkeypatch):
 
 
 def test_tilelang_backend_swallows_install_failure(monkeypatch):
+    _pin_fla_model_types(monkeypatch)
     monkeypatch.delenv(worker._TILELANG_SKIP_ENV, raising = False)
     monkeypatch.setattr(worker.shutil, "which", lambda name: None)
     monkeypatch.setattr(worker, "_installed_tvm_ffi_version", lambda: None)
@@ -649,6 +677,7 @@ def _patch_iu_gates(monkeypatch, fla_gate, conv_gate):
 
 
 def test_hook_installs_when_gate_returns_false(monkeypatch):
+    _pin_fla_model_types(monkeypatch)
     fla_gate = _make_fake_gate(initial_return = False)
     conv_gate = _make_fake_gate(initial_return = False)
     _patch_iu_gates(monkeypatch, fla_gate, conv_gate)
@@ -716,6 +745,7 @@ def test_hook_skips_install_when_gate_already_true(monkeypatch):
 
 
 def test_hook_idempotent_on_repeat_call(monkeypatch):
+    _pin_fla_model_types(monkeypatch)
     fla_gate = _make_fake_gate(initial_return = False)
     conv_gate = _make_fake_gate(initial_return = False)
     _patch_iu_gates(monkeypatch, fla_gate, conv_gate)
@@ -924,6 +954,7 @@ def _fla_install(eq):
 
 def test_hook_does_install_tilelang_for_qwen35(monkeypatch):
     """Positive control for finding #1: Qwen3.5 still gets tilelang."""
+    _pin_fla_model_types(monkeypatch)
     fla_gate = _make_fake_gate(initial_return = False)
     conv_gate = _make_fake_gate(initial_return = True)
     _patch_iu_gates(monkeypatch, fla_gate, conv_gate)
@@ -953,6 +984,7 @@ def test_tilelang_repair_does_not_touch_torch_cuda_stack(monkeypatch):
     forced step so --force-reinstall doesn't cascade through
     apache-tvm-ffi's dep graph and pull a different torch wheel.
     """
+    _pin_fla_model_types(monkeypatch)
     monkeypatch.delenv(worker._TILELANG_SKIP_ENV, raising = False)
     monkeypatch.setattr(worker.shutil, "which", lambda name: "/usr/bin/uv")
     monkeypatch.setattr(worker, "_installed_tvm_ffi_version", lambda: "0.1.10")
@@ -1065,6 +1097,7 @@ def test_hook_runs_tilelang_repair_when_fla_already_true(monkeypatch):
     probe) but tilelang is missing or apache-tvm-ffi is on the broken
     list, the post-available action must still run tilelang.
     """
+    _pin_fla_model_types(monkeypatch)
     fla_gate = _make_fake_gate(initial_return = True)
     conv_gate = _make_fake_gate(initial_return = True)
     _patch_iu_gates(monkeypatch, fla_gate, conv_gate)

From 46232e4f8b8d9305cbf6063da54a373466e88765 Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Mon, 27 Jul 2026 00:27:42 +0000
Subject: [PATCH 23/56] Studio: keep the /v1 admission check off the
 model-scanning path

The admission check added here runs on every /v1 request, including with
auto-switch off, where the route used to return straight away. It called
resolve_local_gguf, whose index is cached for 5s and otherwise rebuilt by
walking ./models and every HF cache root, under a lock the next caller waits
on. On an install with a large cache that scan measured 6.1s, longer than the
TTL that is meant to amortise it, so steady traffic would keep rebuilding it.

Answer from the last built index instead and never rebuild from the request
path: a stale answer is fine here, since what is on disk barely moves and a
finished download already invalidates the index. The first request, before any
scan has completed, warms the index on a background thread and skips the check
rather than blocking on it. That also makes the lookup a dict read, so it no
longer needs handing to a thread.

Cold resolve on this box goes from 6152495us to 0.4us, and the whole hook now
costs the same for a foreign label as for the resident model.
---
 .../core/inference/local_model_resolver.py    | 40 +++++++++-
 studio/backend/routes/inference.py            | 17 ++++-
 .../tests/test_openai_auto_download.py        | 76 +++++++++++++++++--
 .../backend/tests/test_openai_auto_switch.py  |  5 +-
 4 files changed, 124 insertions(+), 14 deletions(-)

diff --git a/studio/backend/core/inference/local_model_resolver.py b/studio/backend/core/inference/local_model_resolver.py
index 61e4db8f4ea..0e5f30ffc07 100644
--- a/studio/backend/core/inference/local_model_resolver.py
+++ b/studio/backend/core/inference/local_model_resolver.py
@@ -34,6 +34,7 @@ class _LocalGgufEntry:
 _CACHE_TTL_S = 5.0
 _lock = threading.Lock()
 _scan: tuple[float, dict[str, _LocalGgufEntry]] = (0.0, {})
+_warming = False
 
 
 def _is_abs_path_id(value: str) -> bool:
@@ -257,7 +258,36 @@ def _index() -> dict[str, _LocalGgufEntry]:
         return fresh
 
 
-def resolve_local_gguf(requested: str) -> Optional[tuple[str, Optional[str], str]]:
+def index_is_built() -> bool:
+    """Whether a scan has ever completed, freshness aside."""
+    with _lock:
+        return bool(_scan[0])
+
+
+def warm_index_soon() -> None:
+    """Build the index off the request path, once."""
+    global _warming
+    with _lock:
+        if _warming or _scan[0]:
+            return
+        _warming = True
+
+    def _run() -> None:
+        global _warming
+        try:
+            _index()
+        except Exception:
+            pass
+        finally:
+            with _lock:
+                _warming = False
+
+    threading.Thread(target = _run, name = "local-model-index-warm", daemon = True).start()
+
+
+def resolve_local_gguf(
+    requested: str, *, allow_scan: bool = True
+) -> Optional[tuple[str, Optional[str], str]]:
     """Return ``(load_path, gguf_variant, loader_id)`` for a local match, else None.
 
     ``load_path`` is the concrete on-disk path to hand /load (so it never fetches
@@ -265,12 +295,18 @@ def resolve_local_gguf(requested: str) -> Optional[tuple[str, Optional[str], str
     ``requested`` is ``repo`` or ``repo:VARIANT``. An exact id match wins first
     (so ids containing a colon still resolve); else the last ``:VARIANT`` is split
     off and resolves only when that quant is on disk.
+
+    ``allow_scan=False`` answers from the last built index and never rebuilds,
+    for callers on the request path: the scan walks several model dirs and HF
+    caches, takes seconds on a large install, and holds a lock every other
+    caller queues behind. A stale answer is fine there, since what is on disk
+    barely moves and a finished download calls :func:`invalidate_index`.
     """
     if not isinstance(requested, str) or not requested.strip():
         return None
     requested = requested.strip()
     try:
-        index = _index()
+        index = _index() if allow_scan else _scan[1]
         entry = index.get(requested.lower())
         if entry is not None:
             variant = entry.variants[0] if entry.variants else None
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index af88850ac5d..1394bf25bea 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3848,7 +3848,11 @@ async def _reject_unservable_model(
         return
     base, variant = split_model_ref(requested_model)
     quantified = looks_like_quant(variant)
-    from core.inference.local_model_resolver import resolve_local_gguf
+    from core.inference.local_model_resolver import (
+        index_is_built,
+        resolve_local_gguf,
+        warm_index_soon,
+    )
     from utils.openai_auto_switch_settings import get_openai_auto_switch_enabled
 
     try:
@@ -3859,7 +3863,14 @@ async def _reject_unservable_model(
             or getattr(get_inference_backend(), "active_model_name", None)
         ):
             return
-        resolved = await asyncio.to_thread(resolve_local_gguf, requested_model)
+        if not index_is_built():
+            # Nothing to answer from yet, and building it here would stall the
+            # request for as long as the scan takes. Warm it for the next one.
+            warm_index_soon()
+            return
+        # Never rebuild from here (see resolve_local_gguf's allow_scan note), which
+        # also makes this a dict read, so it costs less than handing it to a thread.
+        resolved = resolve_local_gguf(requested_model, allow_scan = False)
         # A manual load stores the on-disk path that the resolver advertises under a
         # publisher/model alias (LM Studio, custom folders); match on the path too.
         if resolved is not None and _resolves_to_resident(resolved[0]):
@@ -3867,7 +3878,7 @@ async def _reject_unservable_model(
         downloaded = resolved is not None
         # The exact ref may miss on the quant alone, so ask about the repo too.
         here = downloaded or (
-            variant is not None and await asyncio.to_thread(resolve_local_gguf, base) is not None
+            variant is not None and resolve_local_gguf(base, allow_scan = False) is not None
         )
         switchable = downloaded and get_openai_auto_switch_enabled()
     except Exception as exc:
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index 93fb1d4738a..97ceadb3855 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -677,9 +677,10 @@ def _reject(
         "get_inference_backend",
         lambda: type("B", (), {"active_model_name": None})(),
     )
+    monkeypatch.setattr("core.inference.local_model_resolver.index_is_built", lambda: True)
     monkeypatch.setattr(
         "core.inference.local_model_resolver.resolve_local_gguf",
-        lambda name: ("/p", None, name) if downloaded else None,
+        lambda name, **_kw: ("/p", None, name) if downloaded else None,
     )
     monkeypatch.setattr(
         "utils.openai_auto_switch_settings.get_openai_auto_switch_enabled",
@@ -786,9 +787,10 @@ def test_a_diagnosis_failure_does_not_serve_the_wrong_model(monkeypatch):
         lambda: type("B", (), {"active_model_name": None})(),
     )
 
-    def _boom(name):
+    def _boom(name, **_kw):
         raise OSError("cache scan unavailable")
 
+    monkeypatch.setattr("core.inference.local_model_resolver.index_is_built", lambda: True)
     monkeypatch.setattr("core.inference.local_model_resolver.resolve_local_gguf", _boom)
     with pytest.raises(HTTPException) as excinfo:
         asyncio.run(inference_route._reject_unservable_model("unsloth/B-GGUF:UD-Q6_K_XL", _Req()))
@@ -815,9 +817,10 @@ def test_reload_only_sentinel_is_ignored(monkeypatch):
 def test_diagnosis_failure_never_breaks_a_servable_request(monkeypatch):
     loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
 
-    def _boom(_name):
+    def _boom(_name, **_kw):
         raise RuntimeError("scan exploded")
 
+    monkeypatch.setattr("core.inference.local_model_resolver.index_is_built", lambda: True)
     monkeypatch.setattr("core.inference.local_model_resolver.resolve_local_gguf", _boom)
     monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
     monkeypatch.setattr(
@@ -836,7 +839,10 @@ def test_anthropic_surface_gets_its_own_envelope(monkeypatch):
         "get_inference_backend",
         lambda: type("B", (), {"active_model_name": None})(),
     )
-    monkeypatch.setattr("core.inference.local_model_resolver.resolve_local_gguf", lambda name: None)
+    monkeypatch.setattr("core.inference.local_model_resolver.index_is_built", lambda: True)
+    monkeypatch.setattr(
+        "core.inference.local_model_resolver.resolve_local_gguf", lambda name, **_kw: None
+    )
     monkeypatch.setattr(inference_route, "_unavailable_model_message", _fake_unavailable_message)
     with pytest.raises(HTTPException) as excinfo:
         asyncio.run(
@@ -1019,16 +1025,20 @@ def test_a_slashless_local_model_is_still_a_concrete_reference(monkeypatch):
         "utils.openai_auto_switch_settings.get_openai_auto_switch_enabled", lambda: False
     )
 
+    monkeypatch.setattr("core.inference.local_model_resolver.index_is_built", lambda: True)
     monkeypatch.setattr(
         "core.inference.local_model_resolver.resolve_local_gguf",
-        lambda name: ("/p", None, name) if name.startswith("standalone-Q4_K_M") else None,
+        lambda name, **_kw: ("/p", None, name) if name.startswith("standalone-Q4_K_M") else None,
     )
     with pytest.raises(HTTPException) as excinfo:
         asyncio.run(inference_route._reject_unservable_model("standalone-Q4_K_M", _Req()))
     assert excinfo.value.status_code == 404
 
     # A slashless name that is not here stays a foreign label.
-    monkeypatch.setattr("core.inference.local_model_resolver.resolve_local_gguf", lambda name: None)
+    monkeypatch.setattr("core.inference.local_model_resolver.index_is_built", lambda: True)
+    monkeypatch.setattr(
+        "core.inference.local_model_resolver.resolve_local_gguf", lambda name, **_kw: None
+    )
     assert asyncio.run(inference_route._reject_unservable_model("gpt-4", _Req())) is None
     assert asyncio.run(inference_route._reject_unservable_model("default", _Req())) is None
 
@@ -1086,11 +1096,63 @@ def test_a_resolver_alias_for_the_resident_model_is_not_refused(monkeypatch):
         "get_inference_backend",
         lambda: type("B", (), {"active_model_name": None})(),
     )
+    monkeypatch.setattr("core.inference.local_model_resolver.index_is_built", lambda: True)
     monkeypatch.setattr(
         "core.inference.local_model_resolver.resolve_local_gguf",
-        lambda name: ("/models/publisher/model/weights.gguf", None, "publisher/model"),
+        lambda name, **_kw: ("/models/publisher/model/weights.gguf", None, "publisher/model"),
     )
     monkeypatch.setattr(
         "utils.openai_auto_switch_settings.get_openai_auto_switch_enabled", lambda: False
     )
     assert asyncio.run(inference_route._reject_unservable_model("publisher/model", _Req())) is None
+
+
+def test_the_request_path_never_triggers_a_model_index_rescan(monkeypatch):
+    # The scan walks several model dirs and HF caches under a lock every other
+    # caller queues behind, and takes seconds on a large install. With
+    # auto-switch off this hook is the only thing between a request and that
+    # scan, so it must answer from the last built index instead.
+    from core.inference import local_model_resolver as resolver
+
+    scans = []
+    monkeypatch.setattr(resolver, "_build_index", lambda: scans.append(1) or {})
+    monkeypatch.setattr(resolver, "_scan", (1.0, {}))
+    loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
+    monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+    monkeypatch.setattr(
+        inference_route,
+        "get_inference_backend",
+        lambda: type("B", (), {"active_model_name": None})(),
+    )
+    monkeypatch.setattr(inference_route, "_unavailable_model_message", _fake_unavailable_message)
+    monkeypatch.setattr(
+        "utils.openai_auto_switch_settings.get_openai_auto_switch_enabled", lambda: False
+    )
+    for model in ("gpt-4", "anthropic/claude-3.5-sonnet", "unsloth/B-GGUF:UD-Q6_K_XL"):
+        try:
+            asyncio.run(inference_route._reject_unservable_model(model, _Req()))
+        except HTTPException:
+            pass
+    assert scans == []
+
+
+def test_an_unbuilt_index_warms_instead_of_blocking(monkeypatch):
+    # Nothing to answer from yet: building it inline would stall this request
+    # for the length of the scan, so it falls through and warms in the back.
+    from core.inference import local_model_resolver as resolver
+
+    warmed = []
+    monkeypatch.setattr(resolver, "index_is_built", lambda: False)
+    monkeypatch.setattr(resolver, "warm_index_soon", lambda: warmed.append(1))
+    loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
+    monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+    monkeypatch.setattr(
+        inference_route,
+        "get_inference_backend",
+        lambda: type("B", (), {"active_model_name": None})(),
+    )
+    assert (
+        asyncio.run(inference_route._reject_unservable_model("unsloth/B-GGUF:Q8_0", _Req()))
+        is None
+    )
+    assert warmed == [1]
diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index 457df3487d3..bf6c6c9a3b0 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -95,7 +95,8 @@ async def __call__(
 
 def _wire(monkeypatch, *, enabled, resolves_to, backend, recorder):
     monkeypatch.setattr(settings, "get_openai_auto_switch_enabled", lambda: enabled)
-    monkeypatch.setattr(resolver, "resolve_local_gguf", lambda _m: resolves_to)
+    monkeypatch.setattr(resolver, "resolve_local_gguf", lambda _m, **_kw: resolves_to)
+    monkeypatch.setattr(resolver, "index_is_built", lambda: True)
     monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: backend)
     # Auto-switch loads via _load_model_impl (the /load route holds the lifecycle
     # gate that auto-switch already owns, so it calls the impl directly).
@@ -3359,7 +3360,7 @@ async def _catalog():
         return [{"id": mid} for mid in catalog]
 
     monkeypatch.setattr(settings, "get_openai_auto_switch_enabled", lambda: enabled)
-    monkeypatch.setattr(resolver, "resolve_local_gguf", lambda _m: None)
+    monkeypatch.setattr(resolver, "resolve_local_gguf", lambda _m, **_kw: None)
     monkeypatch.setattr(
         resolver, "describe_local_miss", lambda _m: (resolver.MISS_MODEL_NOT_FOUND, ())
     )

From a551910936226e718a9358b9c78845ff5b48c225 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 27 Jul 2026 00:37:03 +0000
Subject: [PATCH 24/56] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 studio/backend/tests/test_openai_auto_download.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index 97ceadb3855..f6240e171c1 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -1152,7 +1152,6 @@ def test_an_unbuilt_index_warms_instead_of_blocking(monkeypatch):
         lambda: type("B", (), {"active_model_name": None})(),
     )
     assert (
-        asyncio.run(inference_route._reject_unservable_model("unsloth/B-GGUF:Q8_0", _Req()))
-        is None
+        asyncio.run(inference_route._reject_unservable_model("unsloth/B-GGUF:Q8_0", _Req())) is None
     )
     assert warmed == [1]

From aba885806ba2ec0408add9e5e0a9bd23d8c676e5 Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Mon, 27 Jul 2026 01:52:32 +0000
Subject: [PATCH 25/56] Studio: fix the admission hook's cold, stale and
 contended index paths

Five review items, four of them on the admission hook added here.

Skipping the check until the first scan lands also skipped explicit quant
mismatches, so the first request after startup could ask for :Q8_0 while
Q4_K_M was resident and be answered by it. The early return was redundant as
well: with an empty index resolved is None and here is False, so the gate below
already lets a bare name through and refuses an explicit quant, which is what
the except branch has always concluded. Dropped it and index_is_built with it.

index_is_built took _lock, which _index holds for the whole scan, so once a
warm was running every later request blocked on the event loop for exactly as
long as the scan it was there to avoid. The warm now has its own lock and reads
the timestamp unlocked, which is safe because _scan is only ever rebound.

Warming only when the index had never been built left a model fetched in the
Hub UI, or dropped into a scan folder, invisible for the life of the process,
since only the auto-download watcher calls invalidate_index. Warm on staleness
too, and unconditionally, so it refreshes within a TTL without a scan on the
request path. Rescanning is capped at a tenth of the scan's own duration: a big
install takes longer to scan than the TTL, and warming on the TTL alone would
keep a thread scanning continuously.

An Ollama-style tag names no quant, so the resolver misses it and auto-download
saw a model the resident one already answers to, then 404'd it for having no
such quant. Return early when the loaded model satisfies the reference.

Frontend: a cancelled download said "Model download failed", because the label
collapsed everything non-completed into failure.

The backend tests get an autouse fixture that stops the warm from walking the
developer's real HF caches; that scan starved the loop under the timing
sensitive streaming tests.
---
 .../core/inference/local_model_resolver.py    | 35 +++++---
 studio/backend/routes/inference.py            | 24 +++---
 studio/backend/tests/conftest.py              | 14 +++
 .../tests/test_openai_auto_download.py        | 86 +++++++++++++++----
 .../backend/tests/test_openai_auto_switch.py  | 14 ++-
 .../components/api-monitor-console.tsx        |  6 +-
 6 files changed, 139 insertions(+), 40 deletions(-)

diff --git a/studio/backend/core/inference/local_model_resolver.py b/studio/backend/core/inference/local_model_resolver.py
index e6bdfc07cc0..fba52552482 100644
--- a/studio/backend/core/inference/local_model_resolver.py
+++ b/studio/backend/core/inference/local_model_resolver.py
@@ -34,7 +34,15 @@ class _LocalGgufEntry:
 _CACHE_TTL_S = 5.0
 _lock = threading.Lock()
 _scan: tuple[float, dict[str, _LocalGgufEntry]] = (0.0, {})
+# Separate from _lock on purpose: _lock is held for the whole scan, so sharing it
+# would make the request path wait on the very scan it is trying to stay off.
+_warm_lock = threading.Lock()
 _warming = False
+_last_scan_s = 0.0
+# Rescan for at most a tenth of the time. A big install can take longer to scan
+# than the TTL, and warming on the TTL alone would then keep one thread scanning
+# more or less continuously, starving the loop it was meant to keep free.
+_WARM_DUTY = 10.0
 
 
 def _is_abs_path_id(value: str) -> bool:
@@ -319,28 +327,35 @@ def _index() -> dict[str, _LocalGgufEntry]:
         return fresh
 
 
-def index_is_built() -> bool:
-    """Whether a scan has ever completed, freshness aside."""
-    with _lock:
-        return bool(_scan[0])
+def warm_index_soon() -> None:
+    """(Re)build the index off the request path when it is missing or past its TTL.
 
+    Callers that cannot afford the scan use this plus ``allow_scan=False``, so this
+    is the only thing that ever refreshes the index for them. It has to cover a
+    stale index and not just an absent one: a model downloaded through the Hub UI
+    or dropped into a scan folder has no invalidation hook, and would otherwise stay
+    invisible to those callers for the life of the process.
 
-def warm_index_soon() -> None:
-    """Build the index off the request path, once."""
+    Never touches ``_lock``, which the scan holds throughout, and never blocks.
+    """
     global _warming
-    with _lock:
-        if _warming or _scan[0]:
+    if time.monotonic() - _scan[0] < max(_CACHE_TTL_S, _last_scan_s * _WARM_DUTY):
+        return
+    with _warm_lock:
+        if _warming:
             return
         _warming = True
 
     def _run() -> None:
-        global _warming
+        global _warming, _last_scan_s
+        started = time.monotonic()
         try:
             _index()
         except Exception:
             pass
         finally:
-            with _lock:
+            _last_scan_s = time.monotonic() - started
+            with _warm_lock:
                 _warming = False
 
     threading.Thread(target = _run, name = "local-model-index-warm", daemon = True).start()
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 52929f3b121..ee114976b5d 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3730,6 +3730,11 @@ async def _maybe_auto_download_model(
         return
     if not is_downloadable_ref(requested_model):
         return
+    # An Ollama-style tag (":latest", ":8b") names no quant, so the resolver misses it
+    # and we land here even when the resident model answers to it. Downloading would
+    # be wrong, and the quant match below would 404 a request that is already servable.
+    if _loaded_satisfies(requested_model):
+        return
     try:
         refusal = await maybe_auto_download(
             requested_model, hf_token = _auto_download_hf_token(fastapi_request)
@@ -3847,11 +3852,7 @@ async def _reject_unservable_model(
         return
     base, variant = split_model_ref(requested_model)
     quantified = looks_like_quant(variant)
-    from core.inference.local_model_resolver import (
-        index_is_built,
-        resolve_local_gguf,
-        warm_index_soon,
-    )
+    from core.inference.local_model_resolver import resolve_local_gguf, warm_index_soon
     from utils.openai_auto_switch_settings import get_openai_auto_switch_enabled
 
     try:
@@ -3862,13 +3863,12 @@ async def _reject_unservable_model(
             or getattr(get_inference_backend(), "active_model_name", None)
         ):
             return
-        if not index_is_built():
-            # Nothing to answer from yet, and building it here would stall the
-            # request for as long as the scan takes. Warm it for the next one.
-            warm_index_soon()
-            return
-        # Never rebuild from here (see resolve_local_gguf's allow_scan note), which
-        # also makes this a dict read, so it costs less than handing it to a thread.
+        # Refresh in the background when stale, and read whatever is there now. Never
+        # scan from here (see resolve_local_gguf's allow_scan note): a cold or stale
+        # index only costs evidence, and the gate below already fails safe without it,
+        # whereas scanning would stall this request for as long as it takes. Reading
+        # the built index is a dict lookup, cheaper than handing it to a thread.
+        warm_index_soon()
         resolved = resolve_local_gguf(requested_model, allow_scan = False)
         # A manual load stores the on-disk path that the resolver advertises under a
         # publisher/model alias (LM Studio, custom folders); match on the path too.
diff --git a/studio/backend/tests/conftest.py b/studio/backend/tests/conftest.py
index c2216104a3f..01e7000d91f 100644
--- a/studio/backend/tests/conftest.py
+++ b/studio/backend/tests/conftest.py
@@ -58,6 +58,20 @@ def pytest_addoption(parser):
 # E2E server fixtures
 
 
+@pytest.fixture(autouse = True)
+def _no_background_model_scan(monkeypatch):
+    """Keep the /v1 admission hook from scanning the real HF cache during tests.
+
+    The hook warms the local-model index on a background thread. That is right in a
+    server and wrong here: it walks the developer's actual caches, which on a large
+    install takes seconds, and the resulting I/O starves the loop under the
+    timing-sensitive streaming tests. Tests that exercise the warm patch it back.
+    """
+    from core.inference import local_model_resolver
+
+    monkeypatch.setattr(local_model_resolver, "warm_index_soon", lambda: None)
+
+
 @pytest.fixture(scope = "session")
 def studio_server(request):
     """Yield ``(base_url, api_key)`` for e2e tests.
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index f6240e171c1..0c75e7fcbfc 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -10,12 +10,14 @@
 """
 
 import asyncio
+import time
 
 import pytest
 from fastapi import HTTPException
 
 import routes.inference as inference_route
 from core.inference import openai_auto_download as auto_dl
+from core.inference.local_model_resolver import warm_index_soon as _real_warm_index_soon
 from utils import openai_auto_switch_settings as settings
 
 
@@ -62,9 +64,15 @@ def _gguf_repo_info():
 
 @pytest.fixture(autouse = True)
 def _clean_slot():
+    from core.inference import local_model_resolver
+
     auto_dl.reset_for_tests()
+    # The hook warms the index in the background; drop it so one test's scan is
+    # never handed to the next one inside the TTL.
+    local_model_resolver.invalidate_index()
     yield
     auto_dl.reset_for_tests()
+    local_model_resolver.invalidate_index()
 
 
 def _repo_not_found_error():
@@ -677,7 +685,6 @@ def _reject(
         "get_inference_backend",
         lambda: type("B", (), {"active_model_name": None})(),
     )
-    monkeypatch.setattr("core.inference.local_model_resolver.index_is_built", lambda: True)
     monkeypatch.setattr(
         "core.inference.local_model_resolver.resolve_local_gguf",
         lambda name, **_kw: ("/p", None, name) if downloaded else None,
@@ -790,7 +797,6 @@ def test_a_diagnosis_failure_does_not_serve_the_wrong_model(monkeypatch):
     def _boom(name, **_kw):
         raise OSError("cache scan unavailable")
 
-    monkeypatch.setattr("core.inference.local_model_resolver.index_is_built", lambda: True)
     monkeypatch.setattr("core.inference.local_model_resolver.resolve_local_gguf", _boom)
     with pytest.raises(HTTPException) as excinfo:
         asyncio.run(inference_route._reject_unservable_model("unsloth/B-GGUF:UD-Q6_K_XL", _Req()))
@@ -820,7 +826,6 @@ def test_diagnosis_failure_never_breaks_a_servable_request(monkeypatch):
     def _boom(_name, **_kw):
         raise RuntimeError("scan exploded")
 
-    monkeypatch.setattr("core.inference.local_model_resolver.index_is_built", lambda: True)
     monkeypatch.setattr("core.inference.local_model_resolver.resolve_local_gguf", _boom)
     monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
     monkeypatch.setattr(
@@ -839,7 +844,6 @@ def test_anthropic_surface_gets_its_own_envelope(monkeypatch):
         "get_inference_backend",
         lambda: type("B", (), {"active_model_name": None})(),
     )
-    monkeypatch.setattr("core.inference.local_model_resolver.index_is_built", lambda: True)
     monkeypatch.setattr(
         "core.inference.local_model_resolver.resolve_local_gguf", lambda name, **_kw: None
     )
@@ -1025,7 +1029,6 @@ def test_a_slashless_local_model_is_still_a_concrete_reference(monkeypatch):
         "utils.openai_auto_switch_settings.get_openai_auto_switch_enabled", lambda: False
     )
 
-    monkeypatch.setattr("core.inference.local_model_resolver.index_is_built", lambda: True)
     monkeypatch.setattr(
         "core.inference.local_model_resolver.resolve_local_gguf",
         lambda name, **_kw: ("/p", None, name) if name.startswith("standalone-Q4_K_M") else None,
@@ -1035,7 +1038,6 @@ def test_a_slashless_local_model_is_still_a_concrete_reference(monkeypatch):
     assert excinfo.value.status_code == 404
 
     # A slashless name that is not here stays a foreign label.
-    monkeypatch.setattr("core.inference.local_model_resolver.index_is_built", lambda: True)
     monkeypatch.setattr(
         "core.inference.local_model_resolver.resolve_local_gguf", lambda name, **_kw: None
     )
@@ -1096,7 +1098,6 @@ def test_a_resolver_alias_for_the_resident_model_is_not_refused(monkeypatch):
         "get_inference_backend",
         lambda: type("B", (), {"active_model_name": None})(),
     )
-    monkeypatch.setattr("core.inference.local_model_resolver.index_is_built", lambda: True)
     monkeypatch.setattr(
         "core.inference.local_model_resolver.resolve_local_gguf",
         lambda name, **_kw: ("/models/publisher/model/weights.gguf", None, "publisher/model"),
@@ -1115,8 +1116,11 @@ def test_the_request_path_never_triggers_a_model_index_rescan(monkeypatch):
     from core.inference import local_model_resolver as resolver
 
     scans = []
+    warmed = []
     monkeypatch.setattr(resolver, "_build_index", lambda: scans.append(1) or {})
     monkeypatch.setattr(resolver, "_scan", (1.0, {}))
+    # Stub the warm: it is allowed to scan, just not on the thread serving the request.
+    monkeypatch.setattr(resolver, "warm_index_soon", lambda: warmed.append(1))
     loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
     monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
     monkeypatch.setattr(
@@ -1134,15 +1138,18 @@ def test_the_request_path_never_triggers_a_model_index_rescan(monkeypatch):
         except HTTPException:
             pass
     assert scans == []
+    assert warmed == [1, 1, 1]
 
 
-def test_an_unbuilt_index_warms_instead_of_blocking(monkeypatch):
-    # Nothing to answer from yet: building it inline would stall this request
-    # for the length of the scan, so it falls through and warms in the back.
+def test_a_cold_index_still_refuses_an_explicit_quant_and_warms_in_the_background(monkeypatch):
+    # Before the first scan there is no evidence of what is on disk, but an explicit
+    # quant is evidence enough on its own: answering it from the resident model's own
+    # quant would be the wrong weights under the right name. A bare name proves
+    # nothing, so it still falls through. Either way the warm happens off this request.
     from core.inference import local_model_resolver as resolver
 
     warmed = []
-    monkeypatch.setattr(resolver, "index_is_built", lambda: False)
+    monkeypatch.setattr(resolver, "_scan", (0.0, {}))
     monkeypatch.setattr(resolver, "warm_index_soon", lambda: warmed.append(1))
     loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
     monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
@@ -1151,7 +1158,56 @@ def test_an_unbuilt_index_warms_instead_of_blocking(monkeypatch):
         "get_inference_backend",
         lambda: type("B", (), {"active_model_name": None})(),
     )
-    assert (
-        asyncio.run(inference_route._reject_unservable_model("unsloth/B-GGUF:Q8_0", _Req())) is None
-    )
-    assert warmed == [1]
+    monkeypatch.setattr(inference_route, "_unavailable_model_message", _fake_unavailable_message)
+    with pytest.raises(HTTPException) as excinfo:
+        asyncio.run(inference_route._reject_unservable_model("unsloth/A-GGUF:Q8_0", _Req()))
+    assert excinfo.value.status_code == 404
+    assert asyncio.run(inference_route._reject_unservable_model("gpt-4", _Req())) is None
+    assert warmed == [1, 1]
+
+
+def test_warming_the_index_never_waits_on_the_scan_lock(monkeypatch):
+    # _lock is held for the whole scan. If the request path contended for it, the
+    # first cold request would park every later one on the event loop for the length
+    # of the very scan it is meant to stay off.
+    import threading
+    import time as _time
+
+    from core.inference import local_model_resolver as resolver
+
+    monkeypatch.setattr(resolver, "_scan", (0.0, {}))
+    released = threading.Event()
+    monkeypatch.setattr(resolver, "_build_index", lambda: (released.wait(5), {})[1])
+    _real_warm_index_soon()
+    try:
+        started = _time.perf_counter()
+        _real_warm_index_soon()
+        resolver.resolve_local_gguf("unsloth/A-GGUF", allow_scan = False)
+        elapsed = _time.perf_counter() - started
+    finally:
+        released.set()
+        # Join before the monkeypatches unwind, or the scan finishes against the real
+        # module state and publishes its stub result over it.
+        for _ in range(500):
+            if not resolver._warming:
+                break
+            _time.sleep(0.01)
+    assert elapsed < 0.5, f"request path blocked on the warm scan for {elapsed:.2f}s"
+
+
+def test_a_stale_index_is_refreshed_so_a_hub_download_becomes_visible(monkeypatch):
+    # Only the API auto-download watcher calls invalidate_index. A model fetched in
+    # the Hub UI has no such hook, so if the warm only ever ran once this path would
+    # never see it and would keep answering from the resident model.
+    from core.inference import local_model_resolver as resolver
+
+    scans = []
+    monkeypatch.setattr(resolver, "_build_index", lambda: scans.append(1) or {})
+    monkeypatch.setattr(resolver, "_scan", (time.monotonic() - resolver._CACHE_TTL_S - 1, {}))
+    monkeypatch.setattr(resolver, "_last_scan_s", 0.0)
+    _real_warm_index_soon()
+    for _ in range(500):
+        if scans and not resolver._warming:
+            break
+        time.sleep(0.01)
+    assert scans == [1]
diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index 3a7a3bb9bed..97366cb0110 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -19,6 +19,19 @@
 from utils import openai_auto_switch_settings as settings
 
 
+@pytest.fixture(autouse = True)
+def _clean_resolver_index():
+    """Drop the scan cache around every test.
+
+    The /v1 admission hook warms the index in the background, so without this a
+    test that exercises the hook can publish its own fixture's scan and, inside the
+    TTL, hand it to the next test that expects a fresh one.
+    """
+    resolver.invalidate_index()
+    yield
+    resolver.invalidate_index()
+
+
 class _FakeBackend:
     effective_parallel_slots = 1
     _slot_save_binary = None
@@ -96,7 +109,6 @@ async def __call__(
 def _wire(monkeypatch, *, enabled, resolves_to, backend, recorder):
     monkeypatch.setattr(settings, "get_openai_auto_switch_enabled", lambda: enabled)
     monkeypatch.setattr(resolver, "resolve_local_gguf", lambda _m, **_kw: resolves_to)
-    monkeypatch.setattr(resolver, "index_is_built", lambda: True)
     monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: backend)
     # Auto-switch loads via _load_model_impl (the /load route holds the lifecycle
     # gate that auto-switch already owns, so it calls the impl directly).
diff --git a/studio/frontend/src/features/settings/components/api-monitor-console.tsx b/studio/frontend/src/features/settings/components/api-monitor-console.tsx
index edc15c06e17..59e89661707 100644
--- a/studio/frontend/src/features/settings/components/api-monitor-console.tsx
+++ b/studio/frontend/src/features/settings/components/api-monitor-console.tsx
@@ -111,8 +111,10 @@ function lifecycleLabel(entry: ApiMonitorEntry): string {
         ? `Downloading model (${Math.round(pct)}%)`
         : "Downloading model";
     }
-    return entry.status === "completed"
-      ? "Model downloaded"
+    if (entry.status === "completed") return "Model downloaded";
+    // A cancel is deliberate, so saying it failed misreads the user's own action.
+    return entry.status === "cancelled"
+      ? "Model download cancelled"
       : "Model download failed";
   }
   if (entry.status === "running") {

From 345bbc09a5e07f575504bf3ec02c271911b63574 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 27 Jul 2026 01:53:14 +0000
Subject: [PATCH 26/56] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 studio/backend/tests/conftest.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/studio/backend/tests/conftest.py b/studio/backend/tests/conftest.py
index 01e7000d91f..c9e028eaffb 100644
--- a/studio/backend/tests/conftest.py
+++ b/studio/backend/tests/conftest.py
@@ -68,7 +68,6 @@ def _no_background_model_scan(monkeypatch):
     timing-sensitive streaming tests. Tests that exercise the warm patch it back.
     """
     from core.inference import local_model_resolver
-
     monkeypatch.setattr(local_model_resolver, "warm_index_soon", lambda: None)
 
 

From 5791f7b5ebeb8a74fd21295a9f7b3de4398d32d2 Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Mon, 27 Jul 2026 03:04:17 +0000
Subject: [PATCH 27/56] Studio: make /v1/models and the admission hook agree on
 what is local

Three review items, all on the seam between the catalog scan and the resolver
index, which run on separate schedules.

/v1/models can advertise a local GGUF the resolver has not indexed yet. A bare
id carries no quant to refuse on, so a client asking for one it had just been
handed was answered by the resident model instead. The hook now reads the
catalog cache as evidence too, never scanning it. It takes the path rather than
a yes/no because the converse also happens: the catalog can list the resident
weights under an alias the loaded entry does not answer to, and those must stay
served.

That alias was also emitted twice by /v1/models, once as the loaded basename a
manual load records and once as publisher/model marked unloaded, because the
dedup only compared ids. Compare the path as well.

A directly loaded standalone .gguf takes its quant from the filename, but the
resolver stores such files with no quants, so the advertised <stem>:<quant>
stopped resolving as soon as anything else loaded. Advertise a quant only when
that reference resolves, and downgrade only on a definite answer so a cold
index leaves the metadata alone.
---
 studio/backend/routes/inference.py            | 53 ++++++++++++++--
 .../tests/test_openai_auto_download.py        | 61 +++++++++++++++++++
 studio/backend/tests/test_openai_catalog.py   | 40 ++++++++++++
 3 files changed, 150 insertions(+), 4 deletions(-)

diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index ee114976b5d..16cbff3a3f0 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3875,9 +3875,16 @@ async def _reject_unservable_model(
         if resolved is not None and _resolves_to_resident(resolved[0]):
             return
         downloaded = resolved is not None
+        # /v1/models may already have advertised this id off its own scan while the
+        # resolver index is still cold, and that is evidence too.
+        advertised = _advertised_local_path(base)
+        if advertised is not None and _resolves_to_resident(advertised):
+            return
         # The exact ref may miss on the quant alone, so ask about the repo too.
-        here = downloaded or (
-            variant is not None and resolve_local_gguf(base, allow_scan = False) is not None
+        here = (
+            downloaded
+            or advertised is not None
+            or (variant is not None and resolve_local_gguf(base, allow_scan = False) is not None)
         )
         switchable = downloaded and get_openai_auto_switch_enabled()
     except Exception as exc:
@@ -10878,7 +10885,7 @@ def _openai_model_objects() -> list[dict]:
             "owned_by": _OWNED_BY,
         }
         _quant = getattr(llama_backend, "hf_variant", None)
-        if _quant:
+        if _quant and _quant_reference_resolves(entry["id"], _quant):
             entry["quant"] = _quant
         _ctx = _positive_int_or_none(getattr(llama_backend, "context_length", None))
         if _ctx is not None:
@@ -10920,6 +10927,41 @@ def _openai_model_objects() -> list[dict]:
 # Brief cache for the local-model filesystem scan so repeated /v1/models calls
 # don't rescan the HF cache and models dirs on every request.
 _CATALOG_CACHE: dict = {"at": 0.0, "models": []}
+# Ids the last catalog scan listed, rebuilt only when that scan is replaced.
+_ADVERTISED_CACHE: dict = {"at": None, "paths": {}}
+
+
+def _quant_reference_resolves(model_id: Optional[str], quant: str) -> bool:
+    """Whether ``<model_id>:<quant>`` still resolves once this model is not resident.
+
+    A standalone .gguf takes its quant from the filename, but the resolver stores
+    such files with no quants at all, so advertising one hands out a pin that dies
+    the moment another model loads. Only downgrade on a definite answer: the id
+    itself indexed, that quant not among what it has.
+    """
+    from core.inference.local_model_resolver import resolve_local_gguf
+
+    if not model_id or resolve_local_gguf(model_id, allow_scan = False) is None:
+        return True
+    return resolve_local_gguf(f"{model_id}:{quant}", allow_scan = False) is not None
+
+
+def _advertised_local_path(model: str) -> Optional[str]:
+    """On-disk path of *model* if the last /v1/models scan listed it, else None.
+
+    Cache-only, never scans. The catalog scans on its own schedule, so it can have
+    advertised a local model the resolver index has not picked up yet; having
+    advertised it is evidence the name means something other than the resident one.
+    """
+    if _ADVERTISED_CACHE["at"] != _CATALOG_CACHE["at"]:
+        paths = {}
+        for info in _CATALOG_CACHE["models"] or ():
+            cid = getattr(info, "model_id", None) or public_model_id(getattr(info, "id", None))
+            path = getattr(info, "path", None)
+            if cid and path:
+                paths.setdefault(cid.strip().lower(), path)
+        _ADVERTISED_CACHE.update(at = _CATALOG_CACHE["at"], paths = paths)
+    return _ADVERTISED_CACHE["paths"].get(model.strip().lower())
 _CATALOG_TTL_S = 30.0
 # Per-loop lock (like _auto_switch_lock): a module-level asyncio.Lock ties its
 # waiters to the loop that first awaited it, so a second event loop awaiting it
@@ -11002,7 +11044,10 @@ async def _openai_catalog_objects() -> list[dict]:
             "object": "model",
             "created": _created,
             "owned_by": _OWNED_BY,
-            "loaded": False,
+            # A manual load keys the resident entry by the path basename while the
+            # catalog knows the same weights as "publisher/model", so match on the
+            # path too or the alias is advertised as not loaded.
+            "loaded": _resolves_to_resident(getattr(info, "path", None)),
         }
         # The id stays bare for OpenAI compat; a client appends ":<quant>" to pin one.
         if quants:
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index 0c75e7fcbfc..89708e7aedc 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -656,6 +656,15 @@ def test_hook_prefers_the_hub_header_token(hub):
 # --- never answer as a different model ----------------------------------------
 
 
+class _CatalogInfo:
+    """Minimal stand-in for a local model the /v1/models scan listed."""
+
+    def __init__(self, model_id, path):
+        self.model_id = model_id
+        self.id = model_id
+        self.path = path
+
+
 class _Loaded:
     """Minimal stand-in for the GGUF backend with one model resident."""
 
@@ -1211,3 +1220,55 @@ def test_a_stale_index_is_refreshed_so_a_hub_download_becomes_visible(monkeypatc
             break
         time.sleep(0.01)
     assert scans == [1]
+
+
+def test_an_id_v1_models_advertised_is_refused_before_the_resolver_warms(monkeypatch):
+    # Codex P1: /v1/models scans on its own schedule, so it can advertise an
+    # unloaded local GGUF while the resolver index is still cold. A bare id carries
+    # no quant to refuse on, so without the catalog as evidence that request would
+    # be answered by the unrelated resident model.
+    from core.inference import local_model_resolver as resolver
+
+    monkeypatch.setattr(resolver, "_scan", (0.0, {}))
+    monkeypatch.setattr(
+        inference_route,
+        "_CATALOG_CACHE",
+        {"at": 1.0, "models": [_CatalogInfo("org/Other", "/srv/models/org--Other")]},
+    )
+    monkeypatch.setattr(inference_route, "_ADVERTISED_CACHE", {"at": None, "paths": {}})
+    loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
+    monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+    monkeypatch.setattr(
+        inference_route,
+        "get_inference_backend",
+        lambda: type("B", (), {"active_model_name": None})(),
+    )
+    monkeypatch.setattr(inference_route, "_unavailable_model_message", _fake_unavailable_message)
+    with pytest.raises(HTTPException) as excinfo:
+        asyncio.run(inference_route._reject_unservable_model("org/Other", _Req()))
+    assert excinfo.value.status_code == 404
+    # An id the catalog never listed still proves nothing, so it falls through.
+    assert asyncio.run(inference_route._reject_unservable_model("org/Unlisted", _Req())) is None
+
+
+def test_an_advertised_alias_for_the_resident_weights_is_still_served(monkeypatch):
+    # The flip side: the catalog can list the resident weights under an alias the
+    # loaded entry does not answer to. That is not evidence of a different model.
+    from core.inference import local_model_resolver as resolver
+
+    monkeypatch.setattr(resolver, "_scan", (0.0, {}))
+    monkeypatch.setattr(
+        inference_route,
+        "_CATALOG_CACHE",
+        {"at": 2.0, "models": [_CatalogInfo("publisher/Qwen3", "/srv/models")]},
+    )
+    monkeypatch.setattr(inference_route, "_ADVERTISED_CACHE", {"at": None, "paths": {}})
+    loaded = _Loaded("/srv/models/Qwen3-Q4.gguf", "Q4_K_M")
+    loaded.gguf_path = "/srv/models/Qwen3-Q4.gguf"
+    monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+    monkeypatch.setattr(
+        inference_route,
+        "get_inference_backend",
+        lambda: type("B", (), {"active_model_name": None})(),
+    )
+    assert asyncio.run(inference_route._reject_unservable_model("publisher/Qwen3", _Req())) is None
diff --git a/studio/backend/tests/test_openai_catalog.py b/studio/backend/tests/test_openai_catalog.py
index 0efa19f6253..d8876ac76ed 100644
--- a/studio/backend/tests/test_openai_catalog.py
+++ b/studio/backend/tests/test_openai_catalog.py
@@ -248,3 +248,43 @@ def test_lifecycle_model_label_is_path_free():
     assert inf._lifecycle_model_label("org/A-GGUF", "Q4_K_M") == "org/A-GGUF:Q4_K_M"
     # An id that already carries a quant is not double-suffixed.
     assert inf._lifecycle_model_label("org/A-GGUF:Q4_K_M", "Q8_0") == "org/A-GGUF:Q4_K_M"
+
+
+def test_a_standalone_gguf_does_not_advertise_a_quant_that_stops_resolving(monkeypatch):
+    # Codex P1: llama.cpp reads hf_variant off the filename for a directly loaded
+    # .gguf, but the resolver stores standalone files with no quants, so a client
+    # that pinned "<stem>:<quant>" would get model-not-found once it is not resident.
+    from core.inference.local_model_resolver import _LocalGgufEntry
+
+    standalone = _LocalGgufEntry("Qwen3-Q4", "/srv/models/Qwen3-Q4.gguf", ())
+    repo = _LocalGgufEntry("org/Foo", "/hf/models--org--Foo/snapshots/a", ("Q4_K_M",))
+    monkeypatch.setattr(resolver, "_scan", (1.0, {"qwen3-q4": standalone, "org/foo": repo}))
+    monkeypatch.setattr(inf, "get_inference_backend", lambda: _FakeUnsloth())
+
+    llama = _FakeLlama()
+    llama.hf_variant = "Q4_K_M"
+    monkeypatch.setattr(inf, "get_llama_cpp_backend", lambda: llama)
+    assert "quant" not in inf._openai_model_objects()[0]
+
+    # The same quant on a repo the resolver does list stays advertised.
+    llama.model_identifier = "org/Foo"
+    assert inf._openai_model_objects()[0]["quant"] == "Q4_K_M"
+
+
+def test_an_alias_for_the_resident_weights_is_not_listed_as_unloaded(monkeypatch):
+    # Codex P2: an LM Studio publisher/model GGUF loaded by absolute path keys the
+    # resident entry by the path basename, so an id-only dedup emits the alias a
+    # second time marked not loaded, which is the wrong residency for those weights.
+    monkeypatch.setattr(inf, "get_llama_cpp_backend", lambda: _FakeLlama())
+    monkeypatch.setattr(inf, "get_inference_backend", lambda: _FakeUnsloth())
+
+    alias = _Info("/srv/models", "Qwen3", model_id = "publisher/Qwen3")
+    alias.path = "/srv/models"  # holds the resident /srv/models/Qwen3-Q4.gguf
+
+    async def _fake_catalog():
+        return [alias]
+
+    monkeypatch.setattr(inf, "_cached_local_catalog", _fake_catalog)
+    monkeypatch.setattr(resolver, "local_gguf_quants", lambda info: ("Q4_K_M",))
+    ids = {m["id"]: m for m in asyncio.run(inf._openai_catalog_objects())}
+    assert ids["publisher/Qwen3"]["loaded"] is True

From 76dad06b2c74fbb347431835725ddffffa6a0e11 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 27 Jul 2026 03:06:37 +0000
Subject: [PATCH 28/56] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 studio/backend/routes/inference.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 16cbff3a3f0..97ea5f08510 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -10962,6 +10962,8 @@ def _advertised_local_path(model: str) -> Optional[str]:
                 paths.setdefault(cid.strip().lower(), path)
         _ADVERTISED_CACHE.update(at = _CATALOG_CACHE["at"], paths = paths)
     return _ADVERTISED_CACHE["paths"].get(model.strip().lower())
+
+
 _CATALOG_TTL_S = 30.0
 # Per-loop lock (like _auto_switch_lock): a module-level asyncio.Lock ties its
 # waiters to the loop that first awaited it, so a second event loop awaiting it

From d7d113ab8e8ab2cc78f53718509ad0eca963a5ac Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Mon, 27 Jul 2026 03:12:36 +0000
Subject: [PATCH 29/56] Studio: tighten the comments this branch adds

Collapse the multi-line notes in the auto-download path, the /v1 admission
hook and their tests to one line each, keeping the reason and dropping the
restatement. No behaviour change.
---
 studio/backend/core/inference/api_monitor.py  |  3 +-
 .../backend/core/inference/llama_keepwarm.py  |  3 +-
 .../core/inference/local_model_resolver.py    |  7 +-
 .../core/inference/openai_auto_download.py    | 27 +++----
 studio/backend/routes/inference.py            | 46 +++++-------
 .../tests/test_openai_auto_download.py        | 72 +++++++------------
 .../backend/tests/test_openai_auto_switch.py  | 31 ++++----
 studio/backend/tests/test_openai_catalog.py   | 10 ++-
 .../tests/test_openai_tool_passthrough.py     |  3 +-
 .../frontend/src/features/chat/types/api.ts   |  3 +-
 .../settings/api/openai-auto-switch.ts        |  3 +-
 .../features/settings/api/openai-models.ts    |  7 +-
 .../components/api-monitor-console.tsx        | 14 ++--
 .../settings/components/usage-examples.tsx    | 18 ++---
 ...st_usage_examples_model_source_contract.py | 14 ++--
 15 files changed, 92 insertions(+), 169 deletions(-)

diff --git a/studio/backend/core/inference/api_monitor.py b/studio/backend/core/inference/api_monitor.py
index a28210caf23..2de042ab37f 100644
--- a/studio/backend/core/inference/api_monitor.py
+++ b/studio/backend/core/inference/api_monitor.py
@@ -52,8 +52,7 @@ class ApiMonitorEntry:
     total_tokens: Optional[int] = None
     total_tokens_authoritative: bool = False
     error: Optional[str] = None
-    # "request" (an HTTP call) or "lifecycle" (a model load/unload). Lifecycle rows carry
-    # event/reason instead of a prompt, and are server-wide so every subject sees them.
+    # "request" (HTTP call) or "lifecycle" (model load/unload: event/reason, not a prompt; shared).
     kind: str = "request"
     event: Optional[str] = None
     reason: Optional[str] = None
diff --git a/studio/backend/core/inference/llama_keepwarm.py b/studio/backend/core/inference/llama_keepwarm.py
index 88ea5360cc6..f3ec5f573f5 100644
--- a/studio/backend/core/inference/llama_keepwarm.py
+++ b/studio/backend/core/inference/llama_keepwarm.py
@@ -423,8 +423,7 @@ async def idle_unload_loop(poll_seconds: float = 15.0) -> None:
                     elif manifest:
                         _delete_resume_files(manifest)
                     logger.info("Idle auto-unload: freed GGUF after %ss idle", ttl)
-                    # This path skips note_model_unloaded (an idle unload stashes for
-                    # reload), so record the monitor row here.
+                    # An idle unload stashes for reload and skips note_model_unloaded.
                     _note_idle_unload_event(freed)
                     seen_model = None
         except Exception as exc:
diff --git a/studio/backend/core/inference/local_model_resolver.py b/studio/backend/core/inference/local_model_resolver.py
index fba52552482..0cb46447461 100644
--- a/studio/backend/core/inference/local_model_resolver.py
+++ b/studio/backend/core/inference/local_model_resolver.py
@@ -34,14 +34,11 @@ class _LocalGgufEntry:
 _CACHE_TTL_S = 5.0
 _lock = threading.Lock()
 _scan: tuple[float, dict[str, _LocalGgufEntry]] = (0.0, {})
-# Separate from _lock on purpose: _lock is held for the whole scan, so sharing it
-# would make the request path wait on the very scan it is trying to stay off.
+# Not _lock: that is held for the whole scan, so the request path would wait on it.
 _warm_lock = threading.Lock()
 _warming = False
 _last_scan_s = 0.0
-# Rescan for at most a tenth of the time. A big install can take longer to scan
-# than the TTL, and warming on the TTL alone would then keep one thread scanning
-# more or less continuously, starving the loop it was meant to keep free.
+# Rescan at most a tenth of the time: on the TTL alone a slow scan would run continuously.
 _WARM_DUTY = 10.0
 
 
diff --git a/studio/backend/core/inference/openai_auto_download.py b/studio/backend/core/inference/openai_auto_download.py
index cefcc550dca..167ffd61e44 100644
--- a/studio/backend/core/inference/openai_auto_download.py
+++ b/studio/backend/core/inference/openai_auto_download.py
@@ -72,8 +72,7 @@ class _Active:
 _lock = threading.Lock()
 _active: Optional[_Active] = None
 
-# Repos the Hub says this server cannot serve. Without it, every LiteLLM or OpenRouter
-# "vendor/model" request pays a Hub probe before falling through to the resident model.
+# Repos the Hub says are not servable, so a "vendor/model" miss doesn't re-probe every request.
 _NOT_SERVABLE_TTL_S = 10 * 60
 _NOT_SERVABLE_MAX = 256
 _cache_lock = threading.Lock()
@@ -385,8 +384,7 @@ async def maybe_auto_download(
     if _is_not_servable(repo_id, hf_token) and not looks_like_quant(wanted_variant):
         return None
 
-    # Adopt or reject against the single in-flight slot before touching the network, so
-    # retries during a long download stay free.
+    # Settle the single-flight slot before the network, so retries during a download stay cheap.
     with _lock:
         current = _active
         if current is not None and current.repo_id == repo_id:
@@ -408,8 +406,7 @@ async def maybe_auto_download(
 
     if adopted is not None:
         if adopted.variant is None:
-            # Still probing: no job yet, and a stale whole-repo error would
-            # release the slot the probe is using.
+            # Still probing: no job yet, and a stale whole-repo error would free the probe's slot.
             return _downloading_refusal(adopted.repo_id, None)
         state, error = await _job_state(adopted.repo_id, adopted.variant)
         if state in ("running", "cancelling", "unknown"):
@@ -438,8 +435,7 @@ async def maybe_auto_download(
             repo_id, wanted_variant, requested_model, hf_token, provisional
         )
     except BaseException:
-        # BaseException, not Exception: CancelledError is not an Exception, so a request
-        # cancelled mid-probe would otherwise wedge the provisional slot until restart.
+        # Not `except Exception`: a cancel mid-probe would otherwise wedge the provisional slot.
         _release(provisional)
         raise
 
@@ -468,8 +464,7 @@ def _probe():
             return _gated_refusal(repo_id)
         if status == 404:
             _mark_not_servable(repo_id, hf_token)
-            # An id the Hub does not know is a foreign label, not a miss: fall through to the
-            # resident model. An explicit quant is a deliberate GGUF reference, so answer it.
+            # Unknown to the Hub reads as a foreign label; only an explicit quant makes it ours.
             if not looks_like_quant(wanted_variant):
                 return None
             # A private repo reads as absent without a token; don't confirm either way.
@@ -490,8 +485,7 @@ def _probe():
         )
 
     if getattr(info, "gated", False) and await asyncio.to_thread(_auth_denied, repo_id, hf_token):
-        # The Hub serves metadata for a gated repo without granting its files, so a probe that
-        # returned is not proof of access. Unchecked, the config read below misreports it.
+        # Metadata for a gated repo is not file access; unchecked, the config read below lies.
         _release(active)
         return _gated_refusal(repo_id)
 
@@ -510,8 +504,7 @@ def _probe():
             ),
         )
 
-    # trust_remote_code gate. _config_has_auto_map is tri-state, so refuse on True and on None
-    # (unreadable); _requires_trust_remote_code_for_model swallows errors into False.
+    # trust_remote_code gate: _config_has_auto_map is tri-state, so refuse on True and on None.
     from utils.security.consent import _config_has_auto_map
 
     has_auto_map = await asyncio.to_thread(_config_has_auto_map, repo_id, hf_token)
@@ -581,8 +574,7 @@ def _match_variant(wanted: Optional[str], variants: dict[str, int]) -> Optional[
         return lowered.get(wanted.strip().lower())
     from utils.models.model_config import _pick_best_gguf
 
-    # _pick_best_gguf ranks filenames, so feed it "<label>.gguf". It matches its
-    # upper-case preference tokens case-sensitively, so upper-case and map back.
+    # _pick_best_gguf ranks filenames and matches upper-case tokens, so feed "<LABEL>.gguf".
     synthetic: dict[str, str] = {}
     for name in variants:
         synthetic.setdefault(f"{name.upper()}.gguf", name)
@@ -630,8 +622,7 @@ async def _dispatch(
             message = f"Could not start downloading '{requested_model}'.",
         )
 
-    # The service can refuse without raising (accepted=False, no worker launched). Taking the
-    # slot would promise a download that does not exist, so report the conflict instead.
+    # accepted=False means no worker launched, so report the conflict instead of taking the slot.
     if isinstance(dispatched, dict) and not dispatched.get("accepted", True):
         _release(active)
         logger.info("auto-download: dispatch refused for %s (%s)", label, dispatched.get("state"))
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 16cbff3a3f0..a7c43e4964a 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3670,8 +3670,7 @@ async def _no_model_loaded_error(
         return status, _no_model_loaded_detail(base)
     try:
         if _loaded_satisfies(named):
-            # Resident, just not on a backend this endpoint can use (a Transformers model
-            # on a GGUF-only surface). "Not downloaded" would be false, so stay generic.
+            # Resident but on a backend this endpoint can't use, so "not downloaded" is false.
             return status, _no_model_loaded_detail(base)
         if await asyncio.to_thread(resolve_local_gguf, named) is not None:
             # Resolvable but unloaded: the switch failed, which the generic text covers.
@@ -3730,9 +3729,7 @@ async def _maybe_auto_download_model(
         return
     if not is_downloadable_ref(requested_model):
         return
-    # An Ollama-style tag (":latest", ":8b") names no quant, so the resolver misses it
-    # and we land here even when the resident model answers to it. Downloading would
-    # be wrong, and the quant match below would 404 a request that is already servable.
+    # An Ollama-style tag (":latest") names no quant, so the resolver misses a servable model.
     if _loaded_satisfies(requested_model):
         return
     try:
@@ -3794,8 +3791,7 @@ def _loaded_satisfies(requested: str) -> bool:
     active = getattr(get_inference_backend(), "active_model_name", None)
     if not active:
         return False
-    # Only llama.cpp carries a quant identity, so this backend cannot confirm an explicit
-    # quant. A non-quant tag claims nothing about the weights, so it matches on the repo.
+    # Only llama.cpp carries a quant identity, so this backend can only match on the repo.
     if looks_like_quant(variant):
         return False
     return base in {active.lower(), (public_model_id(active) or "").lower()}
@@ -3863,20 +3859,16 @@ async def _reject_unservable_model(
             or getattr(get_inference_backend(), "active_model_name", None)
         ):
             return
-        # Refresh in the background when stale, and read whatever is there now. Never
-        # scan from here (see resolve_local_gguf's allow_scan note): a cold or stale
-        # index only costs evidence, and the gate below already fails safe without it,
-        # whereas scanning would stall this request for as long as it takes. Reading
-        # the built index is a dict lookup, cheaper than handing it to a thread.
+        # Refresh in the background and read the index as-is: scanning here would stall the
+        # request, and a cold index only costs evidence (the gate below fails safe without it).
         warm_index_soon()
         resolved = resolve_local_gguf(requested_model, allow_scan = False)
-        # A manual load stores the on-disk path that the resolver advertises under a
-        # publisher/model alias (LM Studio, custom folders); match on the path too.
+        # A manual load stores the on-disk path the resolver advertises under an alias, so
+        # match on the path too.
         if resolved is not None and _resolves_to_resident(resolved[0]):
             return
         downloaded = resolved is not None
-        # /v1/models may already have advertised this id off its own scan while the
-        # resolver index is still cold, and that is evidence too.
+        # /v1/models may have advertised this id off its own scan while the index is cold.
         advertised = _advertised_local_path(base)
         if advertised is not None and _resolves_to_resident(advertised):
             return
@@ -3888,8 +3880,7 @@ async def _reject_unservable_model(
         )
         switchable = downloaded and get_openai_auto_switch_enabled()
     except Exception as exc:
-        # Can't verify: an explicit quant still proves intent, so refuse; anything else
-        # may be a foreign label, so let it by.
+        # Can't verify: an explicit quant still proves intent, so refuse; let anything else by.
         logger.debug("unservable-model check failed for %r: %s", requested_model, exc)
         if not quantified:
             return
@@ -3897,8 +3888,7 @@ async def _reject_unservable_model(
     if not (quantified or here):
         return
     if switchable:
-        # On disk and switching allowed, so the swap failed. Answering as the resident
-        # model would be the wrong weights under the right name.
+        # On disk and switching allowed, so the swap failed: the resident model is wrong weights.
         status_code, code = 503, "model_switch_failed"
         message = (
             f"The model '{requested_model}' is downloaded, but this server could not "
@@ -3988,8 +3978,7 @@ async def _resolve_and_switch() -> None:
             else None
         )
         if resolved is None:
-            # Not on disk. Opt-in: fetch in the background and ask the caller to retry,
-            # rather than silently answering from whatever is resident.
+            # Not on disk. Opt-in: fetch in the background and ask the caller to retry.
             if auto_switch_on and not reload_only:
                 await _maybe_auto_download_model(requested_model, fastapi_request)
             # Idle-unload may have freed the model; reload exactly what it freed
@@ -4673,8 +4662,7 @@ async def _load_model_impl(
     # sampled step logs even if it reports 100% immediately (cached/small load).
     _reset_load_progress_step()
 
-    # Open a live "loading" row: discarded below if already loaded, relabelled once the
-    # real id is known, and closed on every exit by the handlers at the end of this function.
+    # Live "loading" row: discarded if already loaded, relabelled on the real id, closed on exit.
     _load_event = api_monitor.record_lifecycle(
         event = "load",
         model = _lifecycle_model_label(request.model_path, request.gguf_variant),
@@ -6289,8 +6277,7 @@ async def get_status(current_subject: str = Depends(get_current_subject)):
             ):
                 _display_model_id = os.path.basename(_model_id)
             elif not _native_grant_backed and _display_model_id == _model_id:
-                # No label was registered, so the raw identifier came back. Report the clean
-                # public id: an HF cache load would otherwise show the snapshot's commit sha.
+                # No label registered, so report the clean public id, not the snapshot's sha.
                 _display_model_id = _llama_public_model_id(llama_backend) or _display_model_id
             _inference_cfg = load_inference_config(_model_id) if _model_id else None
             _audio_type = getattr(llama_backend, "_audio_type", None)
@@ -10962,6 +10949,8 @@ def _advertised_local_path(model: str) -> Optional[str]:
                 paths.setdefault(cid.strip().lower(), path)
         _ADVERTISED_CACHE.update(at = _CATALOG_CACHE["at"], paths = paths)
     return _ADVERTISED_CACHE["paths"].get(model.strip().lower())
+
+
 _CATALOG_TTL_S = 30.0
 # Per-loop lock (like _auto_switch_lock): a module-level asyncio.Lock ties its
 # waiters to the loop that first awaited it, so a second event loop awaiting it
@@ -11044,9 +11033,8 @@ async def _openai_catalog_objects() -> list[dict]:
             "object": "model",
             "created": _created,
             "owned_by": _OWNED_BY,
-            # A manual load keys the resident entry by the path basename while the
-            # catalog knows the same weights as "publisher/model", so match on the
-            # path too or the alias is advertised as not loaded.
+            # A manual load keys the resident entry by path basename while the catalog uses
+            # the alias, so match on the path or the alias reads as not loaded.
             "loaded": _resolves_to_resident(getattr(info, "path", None)),
         }
         # The id stays bare for OpenAI compat; a client appends ":<quant>" to pin one.
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index 89708e7aedc..4be056638c0 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -67,8 +67,7 @@ def _clean_slot():
     from core.inference import local_model_resolver
 
     auto_dl.reset_for_tests()
-    # The hook warms the index in the background; drop it so one test's scan is
-    # never handed to the next one inside the TTL.
+    # The hook warms the index in the background; drop it so a scan never leaks between tests.
     local_model_resolver.invalidate_index()
     yield
     auto_dl.reset_for_tests()
@@ -287,8 +286,7 @@ def test_missing_repo_is_404_without_confirming_existence(hub):
 
 def test_an_id_the_hub_does_not_know_falls_through(hub):
     hub["raise"] = _hub_error(_repo_not_found_error(), 404, "nope")
-    # LiteLLM and OpenRouter name every provider "vendor/model", so a namespace is not
-    # intent: an id the Hub never heard of stays a foreign label the resident model answers.
+    # "vendor/model" is how LiteLLM names providers, so an unknown id stays a foreign label.
     for foreign in (
         "anthropic/claude-3.5-sonnet",
         "openai/gpt-4o",
@@ -308,8 +306,7 @@ def test_a_foreign_id_is_probed_once_then_cached(hub):
 
 
 def test_an_anonymous_404_does_not_silence_an_authorised_caller(hub):
-    # The Hub 404s a private repo the caller cannot see, so caching that verdict globally
-    # would let one anonymous request hide it from the token holder for the whole TTL.
+    # The Hub 404s a private repo, so a global verdict would hide it from the token holder.
     hub["raise"] = _hub_error(_repo_not_found_error(), 404, "nope")
     assert _run("myorg/private-GGUF") is None
     assert hub["probes"] == 1
@@ -331,8 +328,7 @@ def test_the_cache_is_per_token(hub):
 
 
 def test_the_gated_message_names_the_header_that_actually_works(hub):
-    # Auto-download never uses the server's token, so naming a Studio setting would loop
-    # the caller on the same 403.
+    # Auto-download never uses the server's token, so a Studio setting would loop the caller.
     hub["info"] = _Info(_gguf_repo_info().siblings, gated = "manual")
     hub["auth_denied"] = True
     refusal = _run("meta-llama/Llama-2-7b-hf")
@@ -347,8 +343,7 @@ def test_gated_repo_is_403(hub):
 
 
 def test_a_gated_repo_that_still_returns_metadata_is_403(hub):
-    # Metadata for a gated repo is not file access, so report the licence gate rather than
-    # the custom-code refusal the unreadable config would otherwise produce.
+    # Metadata for a gated repo is not file access, so report the licence gate, not custom code.
     hub["info"] = _Info(_gguf_repo_info().siblings, gated = "manual")
     hub["auth_denied"] = True
     refusal = _run("meta-llama/Llama-2-7b-hf")
@@ -473,8 +468,7 @@ def test_hf_token_is_passed_to_the_worker(hub):
 
 
 def test_a_refused_dispatch_is_not_reported_as_downloading(hub):
-    # The hub service can decline a claim without raising (accepted=False, no worker), so
-    # the caller must hear "busy", not a download that was never started.
+    # The hub service can decline without raising (accepted=False), so the caller hears "busy".
     hub["dispatch_result"] = {
         "job_key": "unsloth/x-gguf::ud-q5_k_xl",
         "state": "running",  # the blocking job's state, not ours
@@ -492,16 +486,14 @@ def test_a_refused_dispatch_is_not_reported_as_downloading(hub):
 
 
 def test_an_adoptable_dispatch_still_tracks_the_existing_job(hub):
-    # accepted=True with claimed=False means this repo+quant is already downloading
-    # (started from the Hub UI); attach to it rather than refuse.
+    # accepted=True with claimed=False means it is already downloading (Hub UI); attach to it.
     hub["dispatch_result"] = {"job_key": "k", "state": "running", "accepted": True}
     assert _run("unsloth/x-GGUF:UD-Q5_K_XL").code == "model_downloading"
     assert len(hub["watched"]) == 1
 
 
 def test_a_failed_status_probe_does_not_end_the_watch(hub, monkeypatch):
-    # A probe that raised says nothing about the worker. Reading it as "idle" freed the
-    # slot under a live download, admitting a second multi-GB fetch alongside the first.
+    # A probe that raised says nothing: reading it as "idle" freed the slot mid-download.
     from hub.services.models import downloads
 
     async def _boom(repo_id, gguf_variant = ""):
@@ -556,8 +548,7 @@ async def _maybe_errored(repo, variant):
 
 
 def test_a_cancelled_admission_does_not_wedge_the_slot(hub):
-    # CancelledError is a BaseException, so an `except Exception` cleanup would leave the
-    # provisional slot installed and refuse every later request.
+    # CancelledError is a BaseException, so an `except Exception` cleanup would wedge the slot.
     def _cancel():
         raise asyncio.CancelledError()
 
@@ -750,8 +741,7 @@ def test_downloaded_but_auto_switch_off_says_so(monkeypatch):
 
 
 def test_a_failed_switch_is_reported_not_answered_by_the_resident_model(monkeypatch):
-    # On disk and switching allowed means the swap failed, so answering from the resident
-    # model would be the wrong weights under the right name.
+    # On disk and switching allowed means the swap failed; the resident model is wrong weights.
     loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
     with pytest.raises(HTTPException) as excinfo:
         _reject("unsloth/B-GGUF", loaded, monkeypatch, downloaded = True, auto_switch = True)
@@ -770,8 +760,7 @@ def test_a_failed_switch_is_reported_not_answered_by_the_resident_model(monkeypa
     ],
 )
 def test_a_provider_prefixed_label_still_reaches_the_resident_model(foreign, monkeypatch):
-    # LiteLLM and OpenRouter address every provider as "vendor/model", so treating a
-    # namespace as a concrete reference would 404 all of them.
+    # A namespace is how LiteLLM addresses providers, so reading it as a reference 404s them.
     loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
     assert _reject(foreign, loaded, monkeypatch) is None
 
@@ -793,8 +782,7 @@ def test_a_repo_that_is_here_is_refused_without_a_quant(monkeypatch):
 
 
 def test_a_diagnosis_failure_does_not_serve_the_wrong_model(monkeypatch):
-    # The mismatch is established before the diagnosis runs, so only the wording is
-    # uncertain; falling through here would answer as another model.
+    # The mismatch is already established, so falling through would answer as another model.
     loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
     monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
     monkeypatch.setattr(
@@ -941,8 +929,7 @@ def test_every_other_bad_key_stays_indistinguishable():
 
 
 def test_the_servers_own_hf_token_is_never_borrowed(monkeypatch):
-    # The repo is named by whoever holds an API key, so fetching under the owner's Hub
-    # identity would let that key pull the owner's private repos.
+    # The repo is named by an API key holder, so the owner's Hub identity must not be used.
     import routes.settings as settings_route
 
     monkeypatch.setattr(settings_route, "_ambient_hf_token", lambda: "hf_owner_secret")
@@ -1118,10 +1105,7 @@ def test_a_resolver_alias_for_the_resident_model_is_not_refused(monkeypatch):
 
 
 def test_the_request_path_never_triggers_a_model_index_rescan(monkeypatch):
-    # The scan walks several model dirs and HF caches under a lock every other
-    # caller queues behind, and takes seconds on a large install. With
-    # auto-switch off this hook is the only thing between a request and that
-    # scan, so it must answer from the last built index instead.
+    # The scan takes seconds under a lock, so this hook must answer from the last built index.
     from core.inference import local_model_resolver as resolver
 
     scans = []
@@ -1151,10 +1135,8 @@ def test_the_request_path_never_triggers_a_model_index_rescan(monkeypatch):
 
 
 def test_a_cold_index_still_refuses_an_explicit_quant_and_warms_in_the_background(monkeypatch):
-    # Before the first scan there is no evidence of what is on disk, but an explicit
-    # quant is evidence enough on its own: answering it from the resident model's own
-    # quant would be the wrong weights under the right name. A bare name proves
-    # nothing, so it still falls through. Either way the warm happens off this request.
+    # A cold index has no evidence of what is on disk, but an explicit quant is evidence on
+    # its own; a bare name proves nothing. Either way the warm happens off this request.
     from core.inference import local_model_resolver as resolver
 
     warmed = []
@@ -1176,9 +1158,7 @@ def test_a_cold_index_still_refuses_an_explicit_quant_and_warms_in_the_backgroun
 
 
 def test_warming_the_index_never_waits_on_the_scan_lock(monkeypatch):
-    # _lock is held for the whole scan. If the request path contended for it, the
-    # first cold request would park every later one on the event loop for the length
-    # of the very scan it is meant to stay off.
+    # _lock is held for the whole scan, so contending for it would park every later request.
     import threading
     import time as _time
 
@@ -1195,8 +1175,7 @@ def test_warming_the_index_never_waits_on_the_scan_lock(monkeypatch):
         elapsed = _time.perf_counter() - started
     finally:
         released.set()
-        # Join before the monkeypatches unwind, or the scan finishes against the real
-        # module state and publishes its stub result over it.
+        # Join before the monkeypatches unwind, or the scan publishes its stub result over them.
         for _ in range(500):
             if not resolver._warming:
                 break
@@ -1205,9 +1184,8 @@ def test_warming_the_index_never_waits_on_the_scan_lock(monkeypatch):
 
 
 def test_a_stale_index_is_refreshed_so_a_hub_download_becomes_visible(monkeypatch):
-    # Only the API auto-download watcher calls invalidate_index. A model fetched in
-    # the Hub UI has no such hook, so if the warm only ever ran once this path would
-    # never see it and would keep answering from the resident model.
+    # Only the auto-download watcher calls invalidate_index, so a Hub UI download is seen
+    # only if the warm can run again.
     from core.inference import local_model_resolver as resolver
 
     scans = []
@@ -1223,10 +1201,8 @@ def test_a_stale_index_is_refreshed_so_a_hub_download_becomes_visible(monkeypatc
 
 
 def test_an_id_v1_models_advertised_is_refused_before_the_resolver_warms(monkeypatch):
-    # Codex P1: /v1/models scans on its own schedule, so it can advertise an
-    # unloaded local GGUF while the resolver index is still cold. A bare id carries
-    # no quant to refuse on, so without the catalog as evidence that request would
-    # be answered by the unrelated resident model.
+    # /v1/models can advertise an unloaded local GGUF while the resolver index is cold. A bare
+    # id has no quant to refuse on, so without that evidence the resident model would answer.
     from core.inference import local_model_resolver as resolver
 
     monkeypatch.setattr(resolver, "_scan", (0.0, {}))
@@ -1252,8 +1228,8 @@ def test_an_id_v1_models_advertised_is_refused_before_the_resolver_warms(monkeyp
 
 
 def test_an_advertised_alias_for_the_resident_weights_is_still_served(monkeypatch):
-    # The flip side: the catalog can list the resident weights under an alias the
-    # loaded entry does not answer to. That is not evidence of a different model.
+    # The flip side: the catalog can list the resident weights under an alias, which is not
+    # evidence of a different model.
     from core.inference import local_model_resolver as resolver
 
     monkeypatch.setattr(resolver, "_scan", (0.0, {}))
diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index 97366cb0110..2f4645e7ed0 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -307,9 +307,9 @@ def test_openai_compat_routes_bound_to_handlers_with_auth():
     for key, handler in expected.items():
         assert key in seen, f"route {key} is not registered"
         route = seen[key]
-        assert (
-            route.endpoint.__name__ == handler
-        ), f"{key} bound to {route.endpoint.__name__}, expected {handler}"
+        assert route.endpoint.__name__ == handler, (
+            f"{key} bound to {route.endpoint.__name__}, expected {handler}"
+        )
         deps = [d.call.__name__ for d in route.dependant.dependencies]
         assert "get_current_subject" in deps, f"{key} lost its auth dependency"
 
@@ -3009,8 +3009,7 @@ def test_require_vision_ignores_reload_stash(monkeypatch):
     monkeypatch.setattr(
         inference_route, "_target_is_vision", lambda _p: False
     )  # would reject if used
-    # 404 because the restored A is not the requested B; the restore still ran. B carries
-    # a quant, so it reads as a reference to this server, not a foreign provider label.
+    # 404 because the restored A is not the requested B, whose quant makes it a real reference.
     with pytest.raises(HTTPException):
         asyncio.run(
             inference_route._maybe_auto_switch_model(
@@ -3364,8 +3363,7 @@ def _run_responses_stream_no_model(
     active_model_name,
     resolves_to = None,
 ):
-    # Drive _responses_stream's GGUF-not-loaded guard: llama backend unloaded,
-    # inference backend maybe holding a non-GGUF model. Returns (status, detail).
+    # Drive _responses_stream's GGUF-not-loaded guard. Returns (status, detail).
     from fastapi import HTTPException
     from models.inference import ResponsesRequest, ChatMessage
 
@@ -3387,9 +3385,8 @@ def _run_responses_stream_no_model(
 
 
 def test_responses_stream_hint_matches_toggle_regardless_of_active_model(monkeypatch):
-    # The hint attaches whenever the toggle is off, even with a non-GGUF model active,
-    # since auto-switch evicts it to load a resolved GGUF. With it on the error changes
-    # kind: the name resolved to nothing local, so 404 rather than 400.
+    # The hint attaches whenever the toggle is off, whatever is active. With it on the name
+    # resolved to nothing local, so 404 rather than 400.
     off_status, hinted = _run_responses_stream_no_model(
         monkeypatch, enabled = False, active_model_name = None
     )
@@ -3416,8 +3413,7 @@ def _wire_unloaded_chat(
     enabled,
     catalog = ("org/A-GGUF", "org/B-GGUF"),
 ):
-    # Nothing loaded, so a chat request reaches the "no model loaded" error. Pin the
-    # catalog so listed ids don't depend on what is cached on the test machine.
+    # Nothing loaded, so a chat request hits "no model loaded". Pin the catalog for determinism.
     async def _catalog():
         return [{"id": mid} for mid in catalog]
 
@@ -3445,8 +3441,8 @@ def _chat_error(payload):
 
 
 def test_chat_names_undownloaded_model_404s_with_available_ids(monkeypatch):
-    # The reported bug: the named model is not on this machine, so the switch silently
-    # did nothing and /inference/load cannot fix it. Name it and list what can serve.
+    # The reported bug: the model is not here, so the switch did nothing and /inference/load
+    # cannot fix it. Name it and list what can serve.
     _wire_unloaded_chat(monkeypatch, enabled = True)
     status, detail = _chat_error(_chat_request(model = "unsloth/gemma-4-E4B-it-GGUF:UD-Q5_K_XL"))
     assert status == 404
@@ -3479,8 +3475,7 @@ def test_chat_wrong_quant_lists_the_local_quants(monkeypatch):
 
 
 def test_chat_error_unchanged_when_auto_switch_off(monkeypatch):
-    # Toggle off: nothing resolved, so "not downloaded" would be a guess. Keep the
-    # pre-existing status and text, hint included.
+    # Toggle off: nothing resolved, so keep the pre-existing status and text, hint included.
     _wire_unloaded_chat(monkeypatch, enabled = False)
     status, detail = _chat_error(_chat_request(model = "org/nope-GGUF"))
     assert status == 400
@@ -3560,8 +3555,8 @@ def test_chat_undownloaded_model_uses_the_openai_envelope(monkeypatch):
 
 
 def test_gguf_only_paths_keep_the_generic_error_for_the_resident_non_gguf_model(monkeypatch):
-    # A resident Transformers model named on a GGUF-only path: resolve_local_gguf misses,
-    # but the catalog lists that same id, so "not downloaded" would contradict itself.
+    # resolve_local_gguf misses a resident Transformers model the catalog does list, so
+    # "not downloaded" would contradict itself.
     resident = "unsloth/Qwen3.5-4B-GGUF"  # the id _run_responses_stream_no_model asks for
 
     async def _catalog():
diff --git a/studio/backend/tests/test_openai_catalog.py b/studio/backend/tests/test_openai_catalog.py
index d8876ac76ed..92f0698e170 100644
--- a/studio/backend/tests/test_openai_catalog.py
+++ b/studio/backend/tests/test_openai_catalog.py
@@ -251,9 +251,8 @@ def test_lifecycle_model_label_is_path_free():
 
 
 def test_a_standalone_gguf_does_not_advertise_a_quant_that_stops_resolving(monkeypatch):
-    # Codex P1: llama.cpp reads hf_variant off the filename for a directly loaded
-    # .gguf, but the resolver stores standalone files with no quants, so a client
-    # that pinned "<stem>:<quant>" would get model-not-found once it is not resident.
+    # llama.cpp reads hf_variant off the filename, but the resolver stores standalone files
+    # with no quants, so a pinned "<stem>:<quant>" would 404 once it is not resident.
     from core.inference.local_model_resolver import _LocalGgufEntry
 
     standalone = _LocalGgufEntry("Qwen3-Q4", "/srv/models/Qwen3-Q4.gguf", ())
@@ -272,9 +271,8 @@ def test_a_standalone_gguf_does_not_advertise_a_quant_that_stops_resolving(monke
 
 
 def test_an_alias_for_the_resident_weights_is_not_listed_as_unloaded(monkeypatch):
-    # Codex P2: an LM Studio publisher/model GGUF loaded by absolute path keys the
-    # resident entry by the path basename, so an id-only dedup emits the alias a
-    # second time marked not loaded, which is the wrong residency for those weights.
+    # A GGUF loaded by absolute path keys the resident entry by basename, so an id-only dedup
+    # would emit the alias again marked not loaded.
     monkeypatch.setattr(inf, "get_llama_cpp_backend", lambda: _FakeLlama())
     monkeypatch.setattr(inf, "get_inference_backend", lambda: _FakeUnsloth())
 
diff --git a/studio/backend/tests/test_openai_tool_passthrough.py b/studio/backend/tests/test_openai_tool_passthrough.py
index 9a17e52ae78..d98e08db93f 100644
--- a/studio/backend/tests/test_openai_tool_passthrough.py
+++ b/studio/backend/tests/test_openai_tool_passthrough.py
@@ -6478,8 +6478,7 @@ async def fake_to_thread(
                 *_args,
                 **_kwargs,
             ):
-                # Only the generation hop should cancel: resolution runs off the loop
-                # too, but before the monitor row opens, so it would test nothing.
+                # Only the generation hop should cancel; resolution runs before the row opens.
                 if getattr(func, "__name__", "") == "resolve_local_gguf":
                     return None
                 raise asyncio.CancelledError()
diff --git a/studio/frontend/src/features/chat/types/api.ts b/studio/frontend/src/features/chat/types/api.ts
index e1f9e9b60c6..d554eb777e7 100644
--- a/studio/frontend/src/features/chat/types/api.ts
+++ b/studio/frontend/src/features/chat/types/api.ts
@@ -291,8 +291,7 @@ export interface ApiMonitorEntry {
   completion_tokens?: number | null;
   total_tokens?: number | null;
   error?: string | null;
-  // "lifecycle" is a model load/unload/download: event/reason instead of a prompt,
-  // and no detail to fetch.
+  // "lifecycle" is a model load/unload/download: event/reason instead of a prompt.
   kind?: "request" | "lifecycle";
   event?: "load" | "unload" | "download" | null;
   reason?: "manual" | "idle" | "api" | null;
diff --git a/studio/frontend/src/features/settings/api/openai-auto-switch.ts b/studio/frontend/src/features/settings/api/openai-auto-switch.ts
index b76cfc62997..a7e93aa68d2 100644
--- a/studio/frontend/src/features/settings/api/openai-auto-switch.ts
+++ b/studio/frontend/src/features/settings/api/openai-auto-switch.ts
@@ -13,8 +13,7 @@ export type OpenAIAutoSwitchSettings = {
   idleUnloadActive: boolean;
   // Persist the KV cache to disk on idle unload and restore it on reload.
   autoUnloadKeepKv: boolean;
-  // Fetch a GGUF named in an API request. Stored independently, but only
-  // takes effect while `enabled` is on.
+  // Fetch a GGUF named in an API request; stored independently of `enabled`, gated on it.
   autoDownloadModel: boolean;
 };
 
diff --git a/studio/frontend/src/features/settings/api/openai-models.ts b/studio/frontend/src/features/settings/api/openai-models.ts
index 882d1adc75e..f7f858452ad 100644
--- a/studio/frontend/src/features/settings/api/openai-models.ts
+++ b/studio/frontend/src/features/settings/api/openai-models.ts
@@ -16,11 +16,8 @@ type ApiOpenAIModelList = {
 };
 
 /**
- * The models this server can serve.
- *
- * `/v1/models` rather than the hub inventory: it returns exactly the ids
- * `/v1/chat/completions` resolves against, so a snippet built from it runs as
- * printed. `/v1` accepts the UI session JWT, so `authFetch` works unchanged.
+ * The models this server can serve: `/v1/models` returns exactly the ids
+ * `/v1/chat/completions` resolves against, and accepts the UI session JWT.
  */
 export async function listOpenAIModels(): Promise<OpenAIModel[]> {
   const res = await authFetch("/v1/models");
diff --git a/studio/frontend/src/features/settings/components/api-monitor-console.tsx b/studio/frontend/src/features/settings/components/api-monitor-console.tsx
index 59e89661707..332cd4f2f9d 100644
--- a/studio/frontend/src/features/settings/components/api-monitor-console.tsx
+++ b/studio/frontend/src/features/settings/components/api-monitor-console.tsx
@@ -280,8 +280,7 @@ export function ApiMonitorConsole(): ReactElement {
     }
   }, []);
 
-  // /unload matches on the internal id, which the monitor response omits (it would be
-  // a host path), so read it from status the same way the chat runtime does.
+  // /unload matches on the internal id, which the monitor omits, so read it from status.
   const unloadActiveModel = useCallback(async (): Promise<void> => {
     setUnloading(true);
     try {
@@ -346,8 +345,7 @@ export function ApiMonitorConsole(): ReactElement {
   const hasActive = (data?.active_requests ?? 0) > 0;
   const entries = useMemo(() => data?.entries ?? [], [data]);
 
-  // Page 1 tracks the live list. Paging back freezes the id order: rows keep
-  // refreshing, but new traffic must not shove history down a page while it is read.
+  // Page 1 tracks the live list; paging back freezes the id order so history holds still.
   const [page, setPage] = useState(0);
   const [frozenIds, setFrozenIds] = useState<string[] | null>(null);
   const byId = useMemo(
@@ -475,8 +473,7 @@ export function ApiMonitorConsole(): ReactElement {
           <div className="rounded-full border border-border px-2.5 py-1 text-xs capitalize text-muted-foreground">
             {statusLabel}
           </div>
-          {/* Always rendered, disabled when idle: hiding the only manual release path
-              made it invisible exactly when someone goes looking for it. */}
+          {/* Always rendered, disabled when idle: the only manual release must stay visible. */}
           <Button
             type="button"
             variant="ghost"
@@ -546,9 +543,8 @@ export function ApiMonitorConsole(): ReactElement {
         )}
       </div>
 
-      {/* Also whenever a snapshot is frozen: retention evicts frozen ids as new traffic
-          arrives, so the frozen list can shrink below one page. Hiding the pager then
-          strands the console on a stale snapshot with no way back to the live list. */}
+      {/* Also while frozen: retention can shrink that list below one page, and hiding the
+          pager would strand the console on a stale snapshot. */}
       {ordered.length > PAGE_SIZE || frozenIds !== null ? (
         <div className="flex items-center justify-between gap-2 border-t border-border/60 px-4 py-2 text-xs text-muted-foreground">
           <span>
diff --git a/studio/frontend/src/features/settings/components/usage-examples.tsx b/studio/frontend/src/features/settings/components/usage-examples.tsx
index 173e1e96928..9a2e2a8f0e9 100644
--- a/studio/frontend/src/features/settings/components/usage-examples.tsx
+++ b/studio/frontend/src/features/settings/components/usage-examples.tsx
@@ -332,8 +332,7 @@ function buildSnippets(
 
 const KEY_PLACEHOLDER = "sk-unsloth-YOUR_KEY";
 const USE_TUNNEL_KEY = "unsloth_api_use_tunnel";
-// Slow retry while /v1 has nothing to name: a download or load can finish while this
-// panel is open, and neither moves the checkpoint below.
+// Slow retry while /v1 has nothing to name: a download or load moves no store state.
 const CATALOG_RETRY_MS = 15000;
 
 function readUseTunnelPref(): boolean {
@@ -354,8 +353,7 @@ function writeUseTunnelPref(value: boolean): void {
   }
 }
 
-// A checkpoint can be an on-disk load path, which leaks the host layout and is not an
-// id /v1 advertises. Mirrors the backend's _looks_like_path.
+// A checkpoint can be an on-disk load path, which /v1 never advertises. Mirrors _looks_like_path.
 function looksLikePath(id: string): boolean {
   return (
     id.startsWith("/") ||
@@ -367,8 +365,7 @@ function looksLikePath(id: string): boolean {
   );
 }
 
-// The model the examples name. Only ever an id /v1 resolves against; null means the
-// server has nothing to serve yet, and the panel says so instead of a dead id.
+// The model the examples name: always an id /v1 resolves against, null when there is none.
 function useExampleModelName(): string | null {
   const checkpoint = useChatRuntimeStore((s) => s.params.checkpoint);
   const ggufVariant = useChatRuntimeStore((s) => s.activeGgufVariant);
@@ -380,8 +377,7 @@ function useExampleModelName(): string | null {
     !!checkpoint && !checkpoint.startsWith("external::") && !looksLikePath(checkpoint);
   const needsCatalog = !usableCheckpoint;
 
-  // Only when the checkpoint can't answer it, since /v1/models scans the model dirs.
-  // Retries until something is servable, since a download moves no store state.
+  // Only when the checkpoint can't answer it; retries until something is servable.
   // biome-ignore lint/correctness/useExhaustiveDependencies: a load or unload must refetch the servable ids
   useEffect(() => {
     if (!needsCatalog) return;
@@ -422,8 +418,7 @@ function useExampleModelName(): string | null {
       }
       return checkpoint;
     }
-    // No usable checkpoint: name something this server holds, quant included so the
-    // request pins the file on disk. An unloaded one only answers if switching is on.
+    // No usable checkpoint: name something held here, with its quant to pin the file on disk.
     const pick =
       catalog?.find((m) => m.loaded) ?? (autoSwitch ? catalog?.[0] : undefined);
     if (!pick) {
@@ -635,8 +630,7 @@ export function UsageExamples({ apiKey }: { apiKey?: string | null }) {
         {t("settings.apiKeys.usageExamples")}
       </h2>
       <div className="min-w-0 max-w-full overflow-hidden rounded-lg border border-border bg-muted/20">
-        {/* No model-auto-switch row: ModelAutoSwitchSection renders the same setting
-            just below and shares no state with it, so a duplicate would drift. */}
+        {/* No model-auto-switch row: ModelAutoSwitchSection renders that setting just below. */}
         {cloudflareUrl ? (
           <div className="flex min-w-0 items-center justify-between gap-2 border-b border-border px-2 py-1.5">
             <div className="flex shrink-0 items-center gap-1.5">
diff --git a/tests/studio/test_usage_examples_model_source_contract.py b/tests/studio/test_usage_examples_model_source_contract.py
index 9d47aebcda2..dba901438e3 100644
--- a/tests/studio/test_usage_examples_model_source_contract.py
+++ b/tests/studio/test_usage_examples_model_source_contract.py
@@ -15,8 +15,7 @@
 
 
 def test_examples_name_a_model_the_server_can_serve():
-    # The snippets used to fall back to a hardcoded repo id, so a copied curl 404d. Read
-    # the servable ids from /v1/models, the same list the backend's error lists.
+    # A hardcoded repo id made copied curls 404; read the servable ids from /v1/models.
     src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")
     assert 'from "../api/openai-models"' in src
     assert "function useExampleModelName(): string" in src
@@ -32,9 +31,8 @@ def test_examples_name_a_model_the_server_can_serve():
 
 
 def test_examples_never_print_a_hardcoded_model_id():
-    # The bug this contract exists for: the catalog started as `[]`, so any render before
-    # /v1/models answered printed a snippet naming a model the server cannot serve. It is
-    # tri-state now (null until /v1 answers) and the panel asks for a model instead.
+    # The bug this exists for: a `[]` catalog printed a snippet before /v1/models answered.
+    # It is tri-state now, and the panel asks for a model instead.
     src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")
     assert "MODEL_FALLBACK" not in src
     # No repo-shaped literal anywhere: a snippet may only name what /v1 returns.
@@ -52,8 +50,7 @@ def test_examples_never_print_a_hardcoded_model_id():
 
 
 def test_catalog_refresh_follows_the_loaded_model():
-    # `[needsCatalog]` alone never re-ran while there was no local checkpoint, so a
-    # finished load left the snippet naming whatever the first fetch saw.
+    # `[needsCatalog]` alone never re-ran, so a finished load left the first fetch's name.
     src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")
     hook = src[src.find("function useExampleModelName") : src.find("// Backend PATH detection")]
     assert "}, [needsCatalog, checkpoint, ggufVariant]);" in hook
@@ -64,8 +61,7 @@ def test_catalog_refresh_follows_the_loaded_model():
 
 
 def test_usage_examples_has_no_duplicate_auto_switch_control():
-    # ModelAutoSwitchSection renders the same setting just below this panel and shares no
-    # state with it, so a second switch here would drift out of sync.
+    # ModelAutoSwitchSection renders this setting just below and shares no state with it.
     src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")
     # Reading the setting is fine; writing it here is what would be a second control.
     assert "updateOpenAIAutoSwitchSettings" not in src

From 03e43647b1944b63dede8694e259a33c4d8ed96e Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 27 Jul 2026 03:14:19 +0000
Subject: [PATCH 30/56] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 studio/backend/tests/test_openai_auto_switch.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index 2f4645e7ed0..8190483be80 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -307,9 +307,9 @@ def test_openai_compat_routes_bound_to_handlers_with_auth():
     for key, handler in expected.items():
         assert key in seen, f"route {key} is not registered"
         route = seen[key]
-        assert route.endpoint.__name__ == handler, (
-            f"{key} bound to {route.endpoint.__name__}, expected {handler}"
-        )
+        assert (
+            route.endpoint.__name__ == handler
+        ), f"{key} bound to {route.endpoint.__name__}, expected {handler}"
         deps = [d.call.__name__ for d in route.dependant.dependencies]
         assert "get_current_subject" in deps, f"{key} lost its auth dependency"
 

From 7be429bd6251d9e6bcd3cf542f08ce8b9aecf11d Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Mon, 27 Jul 2026 04:02:24 +0000
Subject: [PATCH 31/56] Studio: four admission and catalog fixes from review

Lowercasing paths in _resolves_to_resident made /srv/models/Foo and
/srv/models/foo the same weights on any case-sensitive filesystem, so a request
for one could be answered by the other and /v1/models could mark the wrong
entry loaded. That helper now backs residency as well as admission, so use
os.path.normcase, which folds case only where the filesystem does.

Advertising a quant whenever the resolver could not disprove it kept the bug it
was meant to fix: a standalone .gguf loaded before the first scan still got
<stem>:<quant> published, and the usage examples persist that. No proof is not
proof, so omit it and warm the index instead.

A 401 from an expired or invalid X-Unsloth-HF-Token skipped the 403 and 404
branches and surfaced as "could not reach Hugging Face, retry shortly". It now
says to replace the token, kept apart from the gated refusal since a rejected
credential is not an unaccepted licence.

An image request naming an undownloaded text-only GGUF started the whole
download and only then hit the capability guard, which never sees a remote
target, so every retry 400d and the bytes were wasted. Thread require_vision
into admission and check it against the mmproj companions the disk preflight
already asks build_gguf_variant_plans for.
---
 .../core/inference/openai_auto_download.py    | 30 +++++++++-
 studio/backend/routes/inference.py            | 34 +++++++----
 .../tests/test_openai_auto_download.py        | 58 +++++++++++++++++++
 studio/backend/tests/test_openai_catalog.py   |  6 ++
 4 files changed, 116 insertions(+), 12 deletions(-)

diff --git a/studio/backend/core/inference/openai_auto_download.py b/studio/backend/core/inference/openai_auto_download.py
index 167ffd61e44..0ecb49d1472 100644
--- a/studio/backend/core/inference/openai_auto_download.py
+++ b/studio/backend/core/inference/openai_auto_download.py
@@ -369,12 +369,16 @@ def _downloading_refusal(label: str, percent: Optional[float]) -> AutoDownloadRe
 
 
 async def maybe_auto_download(
-    requested_model: str, *, hf_token: Optional[str] = None
+    requested_model: str, *, hf_token: Optional[str] = None, require_vision: bool = False
 ) -> Optional[AutoDownloadRefusal]:
     """Start (or report on) a background fetch of *requested_model*.
 
     Returns None when the request should carry on unchanged, or a refusal the
     caller must raise. Only called after the local resolver has already missed.
+
+    ``require_vision`` refuses a target with no mmproj companion rather than
+    spending gigabytes on weights that cannot answer the request that asked for
+    them; the local capability guard only ever sees an already-downloaded model.
     """
     global _active
 
@@ -432,7 +436,7 @@ async def maybe_auto_download(
 
     try:
         return await _admit_and_start(
-            repo_id, wanted_variant, requested_model, hf_token, provisional
+            repo_id, wanted_variant, requested_model, hf_token, provisional, require_vision
         )
     except BaseException:
         # Not `except Exception`: a cancel mid-probe would otherwise wedge the provisional slot.
@@ -446,6 +450,7 @@ async def _admit_and_start(
     requested_model: str,
     hf_token: Optional[str],
     active: _Active,
+    require_vision: bool = False,
 ) -> Optional[AutoDownloadRefusal]:
     from hub.utils.hf_errors import hf_error_status
 
@@ -460,6 +465,15 @@ def _probe():
     except Exception as exc:
         _release(active)
         status = hf_error_status(exc)
+        if status == 401:
+            return AutoDownloadRefusal(
+                status = 401,
+                code = "model_access_denied",
+                message = (
+                    f"Hugging Face rejected the token sent for '{repo_id}'. Replace the "
+                    "X-Unsloth-HF-Token header with a valid token; retrying will not help."
+                ),
+            )
         if status == 403:
             return _gated_refusal(repo_id)
         if status == 404:
@@ -546,6 +560,18 @@ def _probe():
     plan = build_gguf_variant_plans(list(getattr(info, "siblings", None) or [])).get(
         variant.lower()
     )
+    if require_vision and not (plan and plan.mmproj_filenames):
+        _release(active)
+        return AutoDownloadRefusal(
+            status = 400,
+            code = "invalid_value",
+            message = (
+                f"'{_public_label(repo_id, variant)}' ships no mmproj companion, so it "
+                "cannot answer the image or audio input in this request. It was not "
+                "downloaded."
+            ),
+        )
+
     need_bytes = _remaining_bytes(repo_id, plan, expected_bytes)
     fits, free = _enough_disk(need_bytes)
     if not fits:
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index a7c43e4964a..aee5df328cc 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3713,7 +3713,7 @@ def _auto_download_hf_token(fastapi_request: Optional[Request]) -> Optional[str]
 
 
 async def _maybe_auto_download_model(
-    requested_model: str, fastapi_request: Optional[Request]
+    requested_model: str, fastapi_request: Optional[Request], *, require_vision: bool = False
 ) -> None:
     """Opt-in: start fetching a named GGUF this server doesn't have.
 
@@ -3734,7 +3734,9 @@ async def _maybe_auto_download_model(
         return
     try:
         refusal = await maybe_auto_download(
-            requested_model, hf_token = _auto_download_hf_token(fastapi_request)
+            requested_model,
+            hf_token = _auto_download_hf_token(fastapi_request),
+            require_vision = require_vision,
         )
     except Exception as exc:
         # Never turn a servable request into a 500 over the download attempt.
@@ -3797,11 +3799,19 @@ def _loaded_satisfies(requested: str) -> bool:
     return base in {active.lower(), (public_model_id(active) or "").lower()}
 
 
+def _norm_path(value: str) -> str:
+    """Compare-ready path. normcase, not lower: on a case-sensitive filesystem
+    /srv/models/Foo and /srv/models/foo are different models."""
+    import os
+
+    return os.path.normcase(str(value).replace("\\", "/").rstrip("/"))
+
+
 def _resolves_to_resident(load_path: Optional[str]) -> bool:
     """Whether a resolved on-disk path is what is already loaded."""
     if not load_path:
         return False
-    target = str(load_path).replace("\\", "/").rstrip("/").lower()
+    target = _norm_path(load_path)
     llama_backend = get_llama_cpp_backend()
     for candidate in (
         getattr(llama_backend, "gguf_path", None)
@@ -3814,7 +3824,7 @@ def _resolves_to_resident(load_path: Optional[str]) -> bool:
     ):
         if not candidate:
             continue
-        current = str(candidate).replace("\\", "/").rstrip("/").lower()
+        current = _norm_path(candidate)
         if (
             current == target
             or current.startswith(f"{target}/")
@@ -3980,7 +3990,9 @@ async def _resolve_and_switch() -> None:
         if resolved is None:
             # Not on disk. Opt-in: fetch in the background and ask the caller to retry.
             if auto_switch_on and not reload_only:
-                await _maybe_auto_download_model(requested_model, fastapi_request)
+                await _maybe_auto_download_model(
+                    requested_model, fastapi_request, require_vision = require_vision
+                )
             # Idle-unload may have freed the model; reload exactly what it freed
             # (path + quant + advertised id) so an alias/unknown name stays servable
             # and keeps the override keyed by the advertised id, not the load path.
@@ -10923,13 +10935,15 @@ def _quant_reference_resolves(model_id: Optional[str], quant: str) -> bool:
 
     A standalone .gguf takes its quant from the filename, but the resolver stores
     such files with no quants at all, so advertising one hands out a pin that dies
-    the moment another model loads. Only downgrade on a definite answer: the id
-    itself indexed, that quant not among what it has.
+    the moment another model loads.
     """
-    from core.inference.local_model_resolver import resolve_local_gguf
+    from core.inference.local_model_resolver import resolve_local_gguf, warm_index_soon
 
-    if not model_id or resolve_local_gguf(model_id, allow_scan = False) is None:
-        return True
+    if not model_id:
+        return False
+    # Cold index proves nothing, and publishing on no proof is what hands out the
+    # dead pin; warm so the next response carries the quant.
+    warm_index_soon()
     return resolve_local_gguf(f"{model_id}:{quant}", allow_scan = False) is not None
 
 
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index 4be056638c0..36ca1d2395f 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -1248,3 +1248,61 @@ def test_an_advertised_alias_for_the_resident_weights_is_still_served(monkeypatc
         lambda: type("B", (), {"active_model_name": None})(),
     )
     assert asyncio.run(inference_route._reject_unservable_model("publisher/Qwen3", _Req())) is None
+
+
+def test_a_rejected_token_says_so_instead_of_asking_for_a_retry(hub):
+    # Hugging Face answers an expired or invalid X-Unsloth-HF-Token with 401. Only
+    # 403 and 404 were handled, so it fell through to "could not reach Hugging Face"
+    # with a 503, telling the caller to retry something that cannot start working.
+    from types import SimpleNamespace
+
+    from huggingface_hub.utils import HfHubHTTPError
+
+    err = HfHubHTTPError("unauthorized")
+    err.response = SimpleNamespace(status_code = 401)
+    hub["raise"] = err
+    refusal = _run("unsloth/x-GGUF:UD-Q5_K_XL", hf_token = "hf_expired")
+    assert refusal.status == 401 and refusal.code == "model_access_denied"
+    assert "token" in refusal.message.lower()
+    assert hub["started"] == []
+
+
+def test_an_image_request_does_not_download_a_text_only_model(hub):
+    # The capability guard only ever sees an already-local target, so without this
+    # an image request would spend gigabytes on weights that cannot answer it and
+    # then 400 on every retry.
+    gb = 1024**3
+    hub["info"] = _Info([_Sibling("model-UD-Q5_K_XL.gguf", 5 * gb)])
+    refusal = asyncio.run(
+        auto_dl.maybe_auto_download("unsloth/text-GGUF:UD-Q5_K_XL", require_vision = True)
+    )
+    assert refusal.status == 400 and refusal.code == "invalid_value"
+    assert "mmproj" in refusal.message
+    assert hub["started"] == []
+    # The stock fixture repo ships mmproj-F16.gguf, so that one is allowed to start.
+    hub["info"] = _gguf_repo_info()
+    assert (
+        asyncio.run(
+            auto_dl.maybe_auto_download("unsloth/x-GGUF:UD-Q5_K_XL", require_vision = True)
+        ).code
+        == "model_downloading"
+    )
+    assert len(hub["started"]) == 1
+
+
+def test_two_models_differing_only_in_case_are_not_the_same_weights(monkeypatch):
+    # Lowercasing paths made /srv/models/Foo and /srv/models/foo compare equal, so
+    # on a case-sensitive filesystem a request for one was answered by the other.
+    import os
+
+    loaded = _Loaded("/srv/models/Foo/model.gguf")
+    loaded.gguf_path = "/srv/models/Foo/model.gguf"
+    monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+    monkeypatch.setattr(
+        inference_route,
+        "get_inference_backend",
+        lambda: type("B", (), {"active_model_name": None})(),
+    )
+    assert inference_route._resolves_to_resident("/srv/models/Foo") is True
+    same = os.path.normcase("A") == os.path.normcase("a")
+    assert inference_route._resolves_to_resident("/srv/models/foo") is same
diff --git a/studio/backend/tests/test_openai_catalog.py b/studio/backend/tests/test_openai_catalog.py
index 92f0698e170..6c68ddec400 100644
--- a/studio/backend/tests/test_openai_catalog.py
+++ b/studio/backend/tests/test_openai_catalog.py
@@ -269,6 +269,12 @@ def test_a_standalone_gguf_does_not_advertise_a_quant_that_stops_resolving(monke
     llama.model_identifier = "org/Foo"
     assert inf._openai_model_objects()[0]["quant"] == "Q4_K_M"
 
+    # A cold index cannot prove the reference either, and publishing on no proof is
+    # exactly what hands out the pin that later fails to resolve.
+    monkeypatch.setattr(resolver, "_scan", (0.0, {}))
+    monkeypatch.setattr(resolver, "warm_index_soon", lambda: None)
+    assert "quant" not in inf._openai_model_objects()[0]
+
 
 def test_an_alias_for_the_resident_weights_is_not_listed_as_unloaded(monkeypatch):
     # A GGUF loaded by absolute path keys the resident entry by basename, so an id-only dedup

From d2954e6386d89ddf616bcbfda7b5c19bdde8260a Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 27 Jul 2026 04:03:07 +0000
Subject: [PATCH 32/56] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 studio/backend/core/inference/openai_auto_download.py | 5 ++++-
 studio/backend/routes/inference.py                    | 6 ++++--
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/studio/backend/core/inference/openai_auto_download.py b/studio/backend/core/inference/openai_auto_download.py
index 0ecb49d1472..b0ad731e33e 100644
--- a/studio/backend/core/inference/openai_auto_download.py
+++ b/studio/backend/core/inference/openai_auto_download.py
@@ -369,7 +369,10 @@ def _downloading_refusal(label: str, percent: Optional[float]) -> AutoDownloadRe
 
 
 async def maybe_auto_download(
-    requested_model: str, *, hf_token: Optional[str] = None, require_vision: bool = False
+    requested_model: str,
+    *,
+    hf_token: Optional[str] = None,
+    require_vision: bool = False,
 ) -> Optional[AutoDownloadRefusal]:
     """Start (or report on) a background fetch of *requested_model*.
 
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index aee5df328cc..fcc4a1dbbea 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3713,7 +3713,10 @@ def _auto_download_hf_token(fastapi_request: Optional[Request]) -> Optional[str]
 
 
 async def _maybe_auto_download_model(
-    requested_model: str, fastapi_request: Optional[Request], *, require_vision: bool = False
+    requested_model: str,
+    fastapi_request: Optional[Request],
+    *,
+    require_vision: bool = False,
 ) -> None:
     """Opt-in: start fetching a named GGUF this server doesn't have.
 
@@ -3803,7 +3806,6 @@ def _norm_path(value: str) -> str:
     """Compare-ready path. normcase, not lower: on a case-sensitive filesystem
     /srv/models/Foo and /srv/models/foo are different models."""
     import os
-
     return os.path.normcase(str(value).replace("\\", "/").rstrip("/"))
 
 

From 7a96e57afbe2ea099d65c2a4ddf0fe88e188ce4d Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Mon, 27 Jul 2026 04:36:59 +0000
Subject: [PATCH 33/56] Studio: make the Hub error fixture carry a status on
 both hub majors

The 401 test built HfHubHTTPError directly, which works on 0.x and fails on 1.x
where response is required and keyword-only, so all four Python jobs failed
while the same test passed locally.

_hub_error already handled both constructors, but the 0.x branch left the
exception with no response at all, and hf_error_status reads the status off it
for the types that do not encode it in their name. So it could only produce a
usable error on 1.x, which is why the test bypassed it. Attach the status when
the constructed exception lacks it, and use the helper.

Cover the helper itself against stand-ins for both constructor shapes, since
whichever hub is installed only ever exercises one of them.
---
 .../tests/test_openai_auto_download.py        | 43 +++++++++++++++----
 1 file changed, 35 insertions(+), 8 deletions(-)

diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index 36ca1d2395f..00d69eae231 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -88,19 +88,50 @@ def _hub_error(error_type, status_code: int, message: str):
     """Build a Hub exception across huggingface_hub majors.
 
     huggingface_hub 1.x made ``response`` a required keyword-only argument, and
-    the project floor is 0.34, so construct positionally and fall back.
+    the project floor is 0.34, so construct positionally and fall back. The
+    positional form carries no response, and hf_error_status reads the status off
+    it for the types that do not encode it in their name, so attach one either way.
     """
     try:
-        return error_type(message)
+        exc = error_type(message)
     except TypeError:
         import httpx
-        return error_type(
+        exc = error_type(
             message,
             response = httpx.Response(
                 status_code,
                 request = httpx.Request("GET", "https://huggingface.co/api/models/org/repo"),
             ),
         )
+    if getattr(getattr(exc, "response", None), "status_code", None) != status_code:
+        from types import SimpleNamespace
+
+        try:
+            exc.response = SimpleNamespace(status_code = status_code)
+        except AttributeError:
+            pass
+    return exc
+
+
+def test_the_hub_error_helper_carries_a_status_on_both_majors():
+    # CI runs huggingface_hub 1.x and this box runs 0.x, and only one of the two
+    # constructor shapes works on each. hf_error_status reads the status off the
+    # response, so a helper that silently produced one without it would make an
+    # error-mapping test pass here and fail there.
+    from hub.utils.hf_errors import hf_error_status
+
+    class _Legacy(Exception):
+        """0.x: response is optional and unset when built positionally."""
+
+    class _Modern(Exception):
+        """1.x: response is required and keyword-only."""
+
+        def __init__(self, message, *, response):
+            super().__init__(message)
+            self.response = response
+
+    for error_type in (_Legacy, _Modern):
+        assert hf_error_status(_hub_error(error_type, 401, "unauthorized")) == 401
 
 
 @pytest.fixture
@@ -1254,13 +1285,9 @@ def test_a_rejected_token_says_so_instead_of_asking_for_a_retry(hub):
     # Hugging Face answers an expired or invalid X-Unsloth-HF-Token with 401. Only
     # 403 and 404 were handled, so it fell through to "could not reach Hugging Face"
     # with a 503, telling the caller to retry something that cannot start working.
-    from types import SimpleNamespace
-
     from huggingface_hub.utils import HfHubHTTPError
 
-    err = HfHubHTTPError("unauthorized")
-    err.response = SimpleNamespace(status_code = 401)
-    hub["raise"] = err
+    hub["raise"] = _hub_error(HfHubHTTPError, 401, "unauthorized")
     refusal = _run("unsloth/x-GGUF:UD-Q5_K_XL", hf_token = "hf_expired")
     assert refusal.status == 401 and refusal.code == "model_access_denied"
     assert "token" in refusal.message.lower()

From 03ac326bd1a720d9f270741a67bdcea37f1540ca Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 27 Jul 2026 04:39:14 +0000
Subject: [PATCH 34/56] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 studio/backend/tests/test_openai_auto_download.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index 00d69eae231..54b3864c646 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -105,7 +105,6 @@ def _hub_error(error_type, status_code: int, message: str):
         )
     if getattr(getattr(exc, "response", None), "status_code", None) != status_code:
         from types import SimpleNamespace
-
         try:
             exc.response = SimpleNamespace(status_code = status_code)
         except AttributeError:

From da452bf679f63344b56179c4c8be5f8e2b7ffcd1 Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Mon, 27 Jul 2026 04:50:16 +0000
Subject: [PATCH 35/56] Studio: invalidate on every download, resolve bare
 tags, keep polling

Three review items.

Only the API auto-download watcher dropped the resolver cache, so a GGUF
fetched in the Hub UI stayed absent to the cache-only request path and the
request was answered by whatever was resident. finalize_worker_exit is the one
point every download worker exits through, so invalidate there. That closes the
window without leaning on the TTL, which the scan-duration throttle can stretch
past 5s on an install where the scan itself takes longer than that.

A downloaded but unloaded GGUF asked for as org/model:latest missed the
resolver, since the suffix was always treated as an exact quant. With
auto-download on that probed the Hub and returned a 404 for a quant that was
never a quant; with it off it refused without switching. Fall back to the base
entry when the suffix is not quant-shaped, and keep exact matching for real
quants so a swap can never serve the wrong weights under the right name.

The usage examples stopped polling once a model was resident, but idle unload
frees one without touching the store, so nothing re-ran the effect and the
examples kept naming a model that could no longer be reloaded. Slow the poll to
60s instead of stopping it.
---
 .../core/inference/local_model_resolver.py    | 11 ++-
 .../hub/services/download_lifecycle.py        | 10 +++
 .../backend/tests/test_openai_auto_switch.py  | 70 +++++++++++++++++++
 .../settings/components/usage-examples.tsx    | 14 ++--
 4 files changed, 99 insertions(+), 6 deletions(-)

diff --git a/studio/backend/core/inference/local_model_resolver.py b/studio/backend/core/inference/local_model_resolver.py
index 0cb46447461..ea6242be539 100644
--- a/studio/backend/core/inference/local_model_resolver.py
+++ b/studio/backend/core/inference/local_model_resolver.py
@@ -367,7 +367,8 @@ def resolve_local_gguf(
     a remote), ``loader_id`` is the advertised id used as the launch-override key.
     ``requested`` is ``repo`` or ``repo:VARIANT``. An exact id match wins first
     (so ids containing a colon still resolve); else the last ``:VARIANT`` is split
-    off and resolves only when that quant is on disk.
+    off and resolves only when that quant is on disk, unless it names no quant at
+    all (an Ollama-style ":latest"), which means the repo.
 
     ``allow_scan=False`` answers from the last built index and never rebuilds,
     for callers on the request path: the scan walks several model dirs and HF
@@ -395,7 +396,13 @@ def resolve_local_gguf(
         for v in entry.variants:
             if v.lower() == wanted:
                 return entry.load_path, v, entry.loader_id
-        return None
+        from core.inference.openai_auto_download import looks_like_quant
+
+        if looks_like_quant(variant):
+            return None
+        # ":latest" or ":8b" names no file, so it means the repo; a real quant that
+        # is not on disk still misses, or a swap would serve the wrong weights.
+        return entry.load_path, (entry.variants[0] if entry.variants else None), entry.loader_id
     except Exception:
         # Best-effort: any resolver failure falls through to the loaded model,
         # so a malformed name can never turn a servable request into a 500.
diff --git a/studio/backend/hub/services/download_lifecycle.py b/studio/backend/hub/services/download_lifecycle.py
index 78a5bc4c132..df5b067ab60 100644
--- a/studio/backend/hub/services/download_lifecycle.py
+++ b/studio/backend/hub/services/download_lifecycle.py
@@ -241,6 +241,16 @@ def finalize_worker_exit(
     state = classify_exit(rc, cancel_requested = cancel_requested)
     if state == "complete":
         registry.set_job(key, "complete")
+        # Every download lands here, so this is where /v1 learns a new model exists.
+        # Its resolver answers the request path from a cached scan with no watcher,
+        # and would otherwise keep reporting the model absent and let the request be
+        # served by whatever is resident.
+        try:
+            from core.inference.local_model_resolver import invalidate_index
+
+            invalidate_index()
+        except Exception:
+            pass
         if transport == download_registry.TRANSPORT_HTTP:
             registry.update_job_transport(key, download_registry.TRANSPORT_HTTP)
         if stderr_text:
diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index 8190483be80..559ef6d5b19 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -4143,3 +4143,73 @@ def test_env_idle_below_floor_is_clamped(monkeypatch):
     assert settings.get_auto_unload_idle_seconds() == 600
     monkeypatch.delenv(settings.MODEL_IDLE_TTL_ENV_VAR)
     assert settings.get_auto_unload_idle_seconds() == 0
+
+
+def test_a_tag_that_names_no_quant_resolves_to_the_repo(monkeypatch):
+    # A downloaded but unloaded GGUF asked for as org/model:latest missed the
+    # resolver, so the switch path could not load it: with auto-download on it
+    # probed the Hub and 404d on a quant that was never a quant, and with it off it
+    # refused without switching. A real quant that is not on disk must still miss,
+    # or a swap would serve the wrong weights under the right name.
+    from core.inference.local_model_resolver import _LocalGgufEntry
+
+    import time
+
+    entry = _LocalGgufEntry("org/model", "/srv/models/org--model", ("Q4_K_M",))
+    # Fresh stamp so _index serves this instead of rescanning over it.
+    monkeypatch.setattr(resolver, "_scan", (time.monotonic(), {"org/model": entry}))
+    for tag in ("org/model:latest", "org/model:8b", "org/model"):
+        assert resolver.resolve_local_gguf(tag) == (
+            "/srv/models/org--model",
+            "Q4_K_M",
+            "org/model",
+        )
+    assert resolver.resolve_local_gguf("org/model:Q8_0") is None
+    assert resolver.resolve_local_gguf("org/model:Q4_K_M") == (
+        "/srv/models/org--model",
+        "Q4_K_M",
+        "org/model",
+    )
+
+
+def test_any_finished_download_drops_the_resolver_cache(monkeypatch):
+    # Only the API auto-download watcher invalidated, so a GGUF fetched in the Hub
+    # UI stayed absent to the cache-only request path and the request was answered
+    # by the resident model instead. Every worker exits through here.
+    import logging
+
+    from hub.services import download_lifecycle
+
+    class _Proc:
+        stderr = None
+
+        def wait(self):
+            return 0
+
+    class _Registry:
+        def cancel_requested(self, key):
+            return False
+
+        def drop_process(self, key, proc):
+            return True
+
+        def get_job_metadata(self, key):
+            return None
+
+        def set_job(self, key, state):
+            self.state = state
+
+    resolver._scan = (1234.0, {"stale": "entry"})
+    assert (
+        download_lifecycle.finalize_worker_exit(
+            _Registry(),
+            "org/model:Q4_K_M",
+            _Proc(),
+            hf_token = None,
+            label = "org/model",
+            log_prefix = "[test]",
+            logger = logging.getLogger(__name__),
+        )
+        == "complete"
+    )
+    assert resolver._scan == (0.0, {}), "a finished download left the scan cached"
diff --git a/studio/frontend/src/features/settings/components/usage-examples.tsx b/studio/frontend/src/features/settings/components/usage-examples.tsx
index 9a2e2a8f0e9..0f72615afb7 100644
--- a/studio/frontend/src/features/settings/components/usage-examples.tsx
+++ b/studio/frontend/src/features/settings/components/usage-examples.tsx
@@ -334,6 +334,9 @@ const KEY_PLACEHOLDER = "sk-unsloth-YOUR_KEY";
 const USE_TUNNEL_KEY = "unsloth_api_use_tunnel";
 // Slow retry while /v1 has nothing to name: a download or load moves no store state.
 const CATALOG_RETRY_MS = 15000;
+// Slower beat once something is servable: idle unload frees a model without
+// touching the store, so residency is never settled for good.
+const CATALOG_IDLE_MS = 60000;
 
 function readUseTunnelPref(): boolean {
   if (typeof window === "undefined") return true;
@@ -377,7 +380,7 @@ function useExampleModelName(): string | null {
     !!checkpoint && !checkpoint.startsWith("external::") && !looksLikePath(checkpoint);
   const needsCatalog = !usableCheckpoint;
 
-  // Only when the checkpoint can't answer it; retries until something is servable.
+  // Only when the checkpoint can't answer it; polls for as long as it is mounted.
   // biome-ignore lint/correctness/useExhaustiveDependencies: a load or unload must refetch the servable ids
   useEffect(() => {
     if (!needsCatalog) return;
@@ -395,12 +398,15 @@ function useExampleModelName(): string | null {
           if (cancelled) return true;
           setCatalog(models);
           setAutoSwitch(enabled);
-          // Only a resident model settles this; auto-switch can be turned back off.
+          // Resident only slows the polling; it never stops it.
           return models.some((m) => m.loaded);
         })
         .then((resolved) => {
-          if (cancelled || resolved) return;
-          timeoutId = window.setTimeout(update, CATALOG_RETRY_MS);
+          if (cancelled) return;
+          timeoutId = window.setTimeout(
+            update,
+            resolved ? CATALOG_IDLE_MS : CATALOG_RETRY_MS,
+          );
         });
     };
 

From 2b7be7e1953b29688adc0118266d87c7560ef7d7 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 27 Jul 2026 04:52:16 +0000
Subject: [PATCH 36/56] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 studio/backend/hub/services/download_lifecycle.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/studio/backend/hub/services/download_lifecycle.py b/studio/backend/hub/services/download_lifecycle.py
index df5b067ab60..8b2516ee9da 100644
--- a/studio/backend/hub/services/download_lifecycle.py
+++ b/studio/backend/hub/services/download_lifecycle.py
@@ -247,7 +247,6 @@ def finalize_worker_exit(
         # served by whatever is resident.
         try:
             from core.inference.local_model_resolver import invalidate_index
-
             invalidate_index()
         except Exception:
             pass

From 7c4918d56a78770e3ac198a2e0500f671ca3d08c Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Mon, 27 Jul 2026 05:03:42 +0000
Subject: [PATCH 37/56] Studio: hold the download slot while it is in use, and
 keep quants to llama.cpp

_loaded_satisfies refuses a quant reference against the Transformers backend by
name, but the path match did not carry that rule. A Transformers model active
from a directory that also holds GGUF exports therefore matched a request for
one of those quants and answered it with the safetensors weights. Only
llama.cpp has a quant identity, so admission now passes llama_only whenever the
reference is quant-qualified. A bare name still matches either backend, and
/v1/models residency keeps the default so a loaded Transformers model is still
reported loaded.

The 24 hour watch window was bounding ownership of the single-flight slot when
it should only have been bounding progress reporting, so a legitimately slow
download had its slot handed back while the worker was still writing, admitting
a second multi-gigabyte download beside it. Resolve the row on the clock, but
keep the slot on a slower poll until the job is actually terminal. Past the
deadline an unknown state does release it, since it means the worker cannot be
probed and holding it on that forever would wedge auto-download.
---
 .../core/inference/openai_auto_download.py    | 21 +++++-
 studio/backend/routes/inference.py            | 16 ++--
 .../tests/test_openai_auto_download.py        | 75 +++++++++++++++++++
 3 files changed, 104 insertions(+), 8 deletions(-)

diff --git a/studio/backend/core/inference/openai_auto_download.py b/studio/backend/core/inference/openai_auto_download.py
index b0ad731e33e..20d3c9fa503 100644
--- a/studio/backend/core/inference/openai_auto_download.py
+++ b/studio/backend/core/inference/openai_auto_download.py
@@ -44,6 +44,9 @@
 _WATCH_POLL_S = 2.0
 # A stalled watcher must not pin the single-flight slot forever.
 _MAX_WATCH_S = 24 * 60 * 60
+# Past the watch window the row is already resolved, so poll only to see whether
+# the worker is still alive and still owns the slot.
+_TIMED_OUT_POLL_S = 60.0
 _RETRY_AFTER_S = 30
 _MAX_LISTED_VARIANTS = 8
 
@@ -321,11 +324,24 @@ async def _watch(active: _Active, hf_token: Optional[str]) -> None:
 
     api_monitor = monitor_module.api_monitor
     deadline = time.monotonic() + _MAX_WATCH_S
+    timed_out = False
     try:
-        while time.monotonic() < deadline:
-            await asyncio.sleep(_WATCH_POLL_S)
+        while True:
+            await asyncio.sleep(_TIMED_OUT_POLL_S if timed_out else _WATCH_POLL_S)
             state, error = await _job_state(active.repo_id, active.variant)
             if state in ("running", "cancelling", "unknown"):
+                if timed_out:
+                    # A worker still running still owns the slot: releasing it on the
+                    # clock alone would admit a second multi-GB download alongside it.
+                    # "unknown" cannot confirm it is alive, so stop holding it then,
+                    # or a broken probe would wedge auto-download for good.
+                    if state == "unknown":
+                        return
+                    continue
+                if time.monotonic() >= deadline:
+                    api_monitor.fail_open(active.monitor_id, "Download timed out")
+                    timed_out = True
+                    continue
                 # Only "running" has progress; the others are still in flight, so keep the slot.
                 if state == "running":
                     api_monitor.set_progress(
@@ -348,7 +364,6 @@ async def _watch(active: _Active, hf_token: Optional[str]) -> None:
             else:
                 api_monitor.fail_open(active.monitor_id, error or f"Download {state}")
             return
-        api_monitor.fail_open(active.monitor_id, "Download timed out")
     except asyncio.CancelledError:
         raise
     except Exception as exc:
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index fcc4a1dbbea..05d25fe8ec3 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3809,8 +3809,14 @@ def _norm_path(value: str) -> str:
     return os.path.normcase(str(value).replace("\\", "/").rstrip("/"))
 
 
-def _resolves_to_resident(load_path: Optional[str]) -> bool:
-    """Whether a resolved on-disk path is what is already loaded."""
+def _resolves_to_resident(load_path: Optional[str], *, llama_only: bool = False) -> bool:
+    """Whether a resolved on-disk path is what is already loaded.
+
+    ``llama_only`` drops the Transformers backend from the comparison. Only
+    llama.cpp carries a quant identity, so a Transformers model active from a
+    directory that also holds GGUF exports would otherwise match a request for
+    one of those quants and answer it with the safetensors weights.
+    """
     if not load_path:
         return False
     target = _norm_path(load_path)
@@ -3822,7 +3828,7 @@ def _resolves_to_resident(load_path: Optional[str]) -> bool:
         getattr(llama_backend, "model_identifier", None)
         if getattr(llama_backend, "is_loaded", False)
         else None,
-        getattr(get_inference_backend(), "active_model_name", None),
+        None if llama_only else getattr(get_inference_backend(), "active_model_name", None),
     ):
         if not candidate:
             continue
@@ -3877,12 +3883,12 @@ async def _reject_unservable_model(
         resolved = resolve_local_gguf(requested_model, allow_scan = False)
         # A manual load stores the on-disk path the resolver advertises under an alias, so
         # match on the path too.
-        if resolved is not None and _resolves_to_resident(resolved[0]):
+        if resolved is not None and _resolves_to_resident(resolved[0], llama_only = quantified):
             return
         downloaded = resolved is not None
         # /v1/models may have advertised this id off its own scan while the index is cold.
         advertised = _advertised_local_path(base)
-        if advertised is not None and _resolves_to_resident(advertised):
+        if advertised is not None and _resolves_to_resident(advertised, llama_only = quantified):
             return
         # The exact ref may miss on the quant alone, so ask about the repo too.
         here = (
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index 54b3864c646..1c54bec14e2 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -1332,3 +1332,78 @@ def test_two_models_differing_only_in_case_are_not_the_same_weights(monkeypatch)
     assert inference_route._resolves_to_resident("/srv/models/Foo") is True
     same = os.path.normcase("A") == os.path.normcase("a")
     assert inference_route._resolves_to_resident("/srv/models/foo") is same
+
+
+def test_a_quant_request_is_not_satisfied_by_transformers_weights(monkeypatch):
+    # A Transformers model active from a directory that also holds GGUF exports
+    # resolves to that same directory, and the path match let admission answer an
+    # explicit quant with the safetensors weights. Only llama.cpp has a quant
+    # identity, which is why _loaded_satisfies already refuses this by name.
+    from core.inference import local_model_resolver as resolver
+
+    entry = resolver._LocalGgufEntry("alias", "/srv/models/tuned", ("Q4_K_M",))
+    monkeypatch.setattr(resolver, "_scan", (time.monotonic(), {"alias": entry}))
+    monkeypatch.setattr(
+        inference_route, "get_llama_cpp_backend", lambda: type("L", (), {"is_loaded": False})()
+    )
+    monkeypatch.setattr(
+        inference_route,
+        "get_inference_backend",
+        lambda: type("B", (), {"active_model_name": "/srv/models/tuned"})(),
+    )
+    monkeypatch.setattr(inference_route, "_unavailable_model_message", _fake_unavailable_message)
+    with pytest.raises(HTTPException) as excinfo:
+        asyncio.run(inference_route._reject_unservable_model("alias:Q4_K_M", _Req()))
+    assert excinfo.value.status_code == 404
+    # A bare name claims nothing about the weights, so the active model still answers.
+    assert asyncio.run(inference_route._reject_unservable_model("alias", _Req())) is None
+
+
+def test_a_timed_out_download_keeps_the_slot_while_it_is_still_running(monkeypatch):
+    # The watch window only bounds progress reporting. Releasing on the clock while
+    # the worker is alive would admit a second multi-GB download beside it.
+    monkeypatch.setattr(auto_dl, "_MAX_WATCH_S", 0.0)
+    monkeypatch.setattr(auto_dl, "_WATCH_POLL_S", 0.001)
+    monkeypatch.setattr(auto_dl, "_TIMED_OUT_POLL_S", 0.001)
+    active = auto_dl._Active(repo_id = "org/big-GGUF", variant = "Q4_K_M")
+
+    async def _drive():
+        finished = asyncio.Event()
+
+        async def _state(repo, variant):
+            return ("complete" if finished.is_set() else "running"), None
+
+        monkeypatch.setattr(auto_dl, "_job_state", _state)
+        auto_dl._active = active
+        watcher = asyncio.create_task(auto_dl._watch(active, None))
+        # Long past the deadline, and still running: the slot must not come back.
+        await asyncio.sleep(0.05)
+        held = auto_dl._active is active
+        finished.set()
+        await watcher
+        return held, auto_dl._active
+
+    held, after = asyncio.run(_drive())
+    assert held, "the slot was released while the worker was still running"
+    assert after is None, "the slot was not released once the job finished"
+
+
+def test_a_timed_out_download_stops_holding_the_slot_once_unprobeable(monkeypatch):
+    # The other direction: a probe that can no longer confirm the worker is alive
+    # must not wedge auto-download for the life of the process.
+    monkeypatch.setattr(auto_dl, "_MAX_WATCH_S", 0.0)
+    monkeypatch.setattr(auto_dl, "_WATCH_POLL_S", 0.001)
+    monkeypatch.setattr(auto_dl, "_TIMED_OUT_POLL_S", 0.001)
+    active = auto_dl._Active(repo_id = "org/big-GGUF", variant = "Q4_K_M")
+
+    async def _unknown(repo, variant):
+        return "unknown", None
+
+    monkeypatch.setattr(auto_dl, "_job_state", _unknown)
+
+    async def _drive():
+        auto_dl._active = active
+        await auto_dl._watch(active, None)
+        return auto_dl._active
+
+    assert asyncio.run(_drive()) is None

From 3fbd46228435583bbd2658bd68d63b2d78802e21 Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Mon, 27 Jul 2026 05:15:13 +0000
Subject: [PATCH 38/56] Studio: keep what the resolver already knew when a
 download lands

Invalidating cleared the index to empty. The request path reads that cache
without scanning, so from a completed download until the rebuild landed it had
no evidence about any local model, not just the new one, and a bare request for
any of them was answered by whatever was resident. Wiring the hook into the
shared completion path in the last commit widened that from auto-download to
every download.

Mark the scan stale and keep the entries instead. Both _index and
warm_index_soon rebuild on a zero stamp, while the request path still sees
everything it knew a moment ago. Only a completed download invalidates, and
that only ever adds models, so nothing retained goes false.

Warm from the completion hook too, so the rebuild starts when the download
lands rather than when the next request happens to need it.
---
 .../core/inference/local_model_resolver.py    | 13 +++++++---
 .../hub/services/download_lifecycle.py        |  5 +++-
 .../backend/tests/test_openai_auto_switch.py  | 25 +++++++++++++++++--
 3 files changed, 37 insertions(+), 6 deletions(-)

diff --git a/studio/backend/core/inference/local_model_resolver.py b/studio/backend/core/inference/local_model_resolver.py
index ea6242be539..363926a4c74 100644
--- a/studio/backend/core/inference/local_model_resolver.py
+++ b/studio/backend/core/inference/local_model_resolver.py
@@ -300,11 +300,18 @@ def _sibling_revision_entries(raw_id: str, loader_id: str):
 
 
 def invalidate_index() -> None:
-    """Drop the cached scan so the next resolve sees a just-finished download,
-    rather than waiting out the TTL."""
+    """Mark the cached scan stale so the next resolve sees a just-finished
+    download, rather than waiting out the TTL.
+
+    Keeps the entries. Callers on the request path read this cache without
+    scanning, so emptying it would leave them with no evidence about any local
+    model until the rebuild lands, and a bare request for one of them would be
+    answered by whatever is resident. Only a completed download invalidates, and
+    that only ever adds models, so the retained entries stay true.
+    """
     global _scan
     with _lock:
-        _scan = (0.0, {})
+        _scan = (0.0, _scan[1])
 
 
 def _index() -> dict[str, _LocalGgufEntry]:
diff --git a/studio/backend/hub/services/download_lifecycle.py b/studio/backend/hub/services/download_lifecycle.py
index 8b2516ee9da..01e0e0fefbb 100644
--- a/studio/backend/hub/services/download_lifecycle.py
+++ b/studio/backend/hub/services/download_lifecycle.py
@@ -246,8 +246,11 @@ def finalize_worker_exit(
         # and would otherwise keep reporting the model absent and let the request be
         # served by whatever is resident.
         try:
-            from core.inference.local_model_resolver import invalidate_index
+            from core.inference.local_model_resolver import invalidate_index, warm_index_soon
             invalidate_index()
+            # Rebuild from here rather than from the first request that needs it,
+            # so the new model becomes resolvable without a scan on the request path.
+            warm_index_soon()
         except Exception:
             pass
         if transport == download_registry.TRANSPORT_HTTP:
diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index 559ef6d5b19..53e5b621495 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -4199,7 +4199,7 @@ def get_job_metadata(self, key):
         def set_job(self, key, state):
             self.state = state
 
-    resolver._scan = (1234.0, {"stale": "entry"})
+    resolver._scan = (1234.0, {"already-here": "entry"})
     assert (
         download_lifecycle.finalize_worker_exit(
             _Registry(),
@@ -4212,4 +4212,25 @@ def set_job(self, key, state):
         )
         == "complete"
     )
-    assert resolver._scan == (0.0, {}), "a finished download left the scan cached"
+    stamp, entries = resolver._scan
+    assert stamp == 0.0, "a finished download left the scan looking fresh"
+    # Evidence for models already indexed has to survive, or a bare request for one
+    # of them during the rebuild is answered by whatever is resident.
+    assert entries == {"already-here": "entry"}
+
+
+def test_invalidating_keeps_the_entries_it_already_had(monkeypatch):
+    # The request path reads this cache without scanning, so emptying it leaves it
+    # with no evidence about any local model until the rebuild lands. Only a
+    # completed download invalidates, and that only adds, so the entries stay true.
+    import time
+
+    entry = resolver._LocalGgufEntry("org/old", "/srv/models/org--old", ("Q4_K_M",))
+    monkeypatch.setattr(resolver, "_scan", (time.monotonic(), {"org/old": entry}))
+    resolver.invalidate_index()
+    assert resolver._scan[0] == 0.0
+    assert resolver.resolve_local_gguf("org/old", allow_scan = False) == (
+        "/srv/models/org--old",
+        "Q4_K_M",
+        "org/old",
+    )

From d8b001fd7a8049fabbf59203fc68d14a39bfa440 Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Mon, 27 Jul 2026 05:26:24 +0000
Subject: [PATCH 39/56] Studio: match the quant, not just the directory, and
 default-select bare tags

Two quants of one repo share a directory, so the path match could not tell them
apart and an explicit :Q8_0 was answered by a resident Q4_K_M that
_loaded_satisfies had already refused by name. The llama_only fix in the last
commit only ruled out the wrong backend, not the wrong quant on the right one.
Both path matches now require the resident hf_variant to equal the requested
quant whenever the reference is quantified; a bare name still matches on the
path alone, since it claims nothing about the weights.

The local resolver already treated a tag that names no quant as meaning the
repo, but remote admission still looked for a quant literally called "latest",
so the same reference resolved locally and 404d remotely. Branch on
looks_like_quant there too. A real quant the repo does not have is still a 404
and never a substitution, which is what separates this from the loader's
low-disk fallback.
---
 .../core/inference/openai_auto_download.py    |  8 ++--
 studio/backend/routes/inference.py            | 21 ++++++++-
 .../tests/test_openai_auto_download.py        | 46 +++++++++++++++++++
 3 files changed, 70 insertions(+), 5 deletions(-)

diff --git a/studio/backend/core/inference/openai_auto_download.py b/studio/backend/core/inference/openai_auto_download.py
index 20d3c9fa503..c51a159faaf 100644
--- a/studio/backend/core/inference/openai_auto_download.py
+++ b/studio/backend/core/inference/openai_auto_download.py
@@ -610,10 +610,12 @@ def _match_variant(wanted: Optional[str], variants: dict[str, int]) -> Optional[
     """Resolve the requested quant against what the repo actually has.
 
     An explicit quant matches case-insensitively and must exist: never quietly
-    substitute another, unlike the loader's low-disk fallback. A bare repo id
-    uses the same preference order as a manual load.
+    substitute another, unlike the loader's low-disk fallback. A bare repo id, or
+    an Ollama-style tag that names no quant at all (":latest", ":8b"), uses the
+    same preference order as a manual load, matching what the local resolver does
+    with the same tag.
     """
-    if wanted:
+    if wanted and looks_like_quant(wanted):
         lowered = {name.lower(): name for name in variants}
         return lowered.get(wanted.strip().lower())
     from utils.models.model_config import _pick_best_gguf
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 05d25fe8ec3..366501fc3d3 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3809,6 +3809,12 @@ def _norm_path(value: str) -> str:
     return os.path.normcase(str(value).replace("\\", "/").rstrip("/"))
 
 
+def _resident_quant_is(variant: Optional[str]) -> bool:
+    """Whether the loaded GGUF is that exact quant."""
+    resident = getattr(get_llama_cpp_backend(), "hf_variant", None) or ""
+    return bool(variant) and resident.lower() == variant.strip().lower()
+
+
 def _resolves_to_resident(load_path: Optional[str], *, llama_only: bool = False) -> bool:
     """Whether a resolved on-disk path is what is already loaded.
 
@@ -3883,12 +3889,23 @@ async def _reject_unservable_model(
         resolved = resolve_local_gguf(requested_model, allow_scan = False)
         # A manual load stores the on-disk path the resolver advertises under an alias, so
         # match on the path too.
-        if resolved is not None and _resolves_to_resident(resolved[0], llama_only = quantified):
+        # Quants of one repo share a directory, so the path alone cannot tell them
+        # apart: without the variant check an explicit :Q8_0 would be answered by a
+        # resident Q4_K_M, which _loaded_satisfies has already refused by name.
+        if (
+            resolved is not None
+            and _resolves_to_resident(resolved[0], llama_only = quantified)
+            and (not quantified or _resident_quant_is(variant))
+        ):
             return
         downloaded = resolved is not None
         # /v1/models may have advertised this id off its own scan while the index is cold.
         advertised = _advertised_local_path(base)
-        if advertised is not None and _resolves_to_resident(advertised, llama_only = quantified):
+        if (
+            advertised is not None
+            and _resolves_to_resident(advertised, llama_only = quantified)
+            and (not quantified or _resident_quant_is(variant))
+        ):
             return
         # The exact ref may miss on the quant alone, so ask about the repo too.
         here = (
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index 1c54bec14e2..de805e75080 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -1407,3 +1407,49 @@ async def _drive():
         return auto_dl._active
 
     assert asyncio.run(_drive()) is None
+
+
+def test_a_sibling_quant_in_the_same_directory_is_not_the_resident_one(monkeypatch):
+    # Quants of one repo share a directory, so the path match alone cannot tell
+    # them apart, and an explicit :Q8_0 was answered by a resident Q4_K_M that
+    # _loaded_satisfies had already refused by name.
+    from core.inference import local_model_resolver as resolver
+
+    entry = resolver._LocalGgufEntry("org/model", "/hf/org--model/snap", ("Q4_K_M", "Q8_0"))
+    monkeypatch.setattr(resolver, "_scan", (time.monotonic(), {"org/model": entry}))
+    loaded = _Loaded("org/model", "Q4_K_M")
+    loaded.gguf_path = "/hf/org--model/snap/model-Q4_K_M.gguf"
+    monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+    monkeypatch.setattr(
+        inference_route,
+        "get_inference_backend",
+        lambda: type("B", (), {"active_model_name": None})(),
+    )
+    monkeypatch.setattr(inference_route, "_unavailable_model_message", _fake_unavailable_message)
+    with pytest.raises(HTTPException):
+        asyncio.run(inference_route._reject_unservable_model("org/model:Q8_0", _Req()))
+    # The quant that is actually resident still answers.
+    assert (
+        asyncio.run(inference_route._reject_unservable_model("org/model:Q4_K_M", _Req())) is None
+    )
+
+
+def test_a_remote_tag_that_names_no_quant_picks_the_preferred_one(hub):
+    # ":latest" and ":8b" name no quant, so remote admission must default-select
+    # like a bare repo id instead of 404ing on a quant that never existed. Matches
+    # what the local resolver now does with the same tag.
+    assert _run("unsloth/x-GGUF").code == "model_downloading"
+    bare_repo, bare_variant, _ = hub["started"][0]
+    for tag in (":latest", ":8b"):
+        auto_dl.reset_for_tests()
+        hub["started"].clear()
+        assert _run(f"unsloth/x-GGUF{tag}").code == "model_downloading"
+        assert hub["started"][0][0] == bare_repo
+        assert hub["started"][0][1] == bare_variant, f"{tag} did not default-select"
+
+    # A real quant the repo does not have is still a 404, never a substitution.
+    auto_dl.reset_for_tests()
+    hub["started"].clear()
+    refusal = _run("unsloth/x-GGUF:Q2_K")
+    assert refusal.status == 404 and "no quant" in refusal.message
+    assert hub["started"] == []

From 9616211d55fbdb25bfb806c08b747a45291dc2ee Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 27 Jul 2026 05:27:09 +0000
Subject: [PATCH 40/56] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 studio/backend/tests/test_openai_auto_download.py | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index de805e75080..7a962032257 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -1429,9 +1429,7 @@ def test_a_sibling_quant_in_the_same_directory_is_not_the_resident_one(monkeypat
     with pytest.raises(HTTPException):
         asyncio.run(inference_route._reject_unservable_model("org/model:Q8_0", _Req()))
     # The quant that is actually resident still answers.
-    assert (
-        asyncio.run(inference_route._reject_unservable_model("org/model:Q4_K_M", _Req())) is None
-    )
+    assert asyncio.run(inference_route._reject_unservable_model("org/model:Q4_K_M", _Req())) is None
 
 
 def test_a_remote_tag_that_names_no_quant_picks_the_preferred_one(hub):

From a260c96c8078e1b72a66b1551d9a766c567f94e3 Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Mon, 27 Jul 2026 05:39:49 +0000
Subject: [PATCH 41/56] Studio: one quant preference, and stop trusting a stale
 checkpoint

list_local_gguf_variants sorts by descending size, so the head of variants was
the biggest quant, often F16, while remote admission and a plain load both rank
through _pick_best_gguf. A bare id therefore meant a different quant depending
on which side answered it, and the local answer was the one that could evict a
working model and then fail or OOM starting an F16 next to a usable Q4.
/v1/models advertised that same head for pinning. Pull the ranking into one
preferred_quant helper and have both sides use it.

The usage examples returned a stored checkpoint without ever consulting
/v1/models, and the polling added last round was gated on not having one, so
for a stored checkpoint it never ran. An idle unload then left the panel
showing a snippet that could not run. Poll whenever mounted, and prefer the
checkpoint only while the catalog still backs it or switching can reload it. A
catalog that has not answered yet is not evidence against it.

The static contract pinned the old dependency array, so it now asserts the
intent it documents: a finished load re-runs the fetch, and the effect is not
gated on having no checkpoint.
---
 .../core/inference/local_model_resolver.py    | 13 +++++-
 .../core/inference/openai_auto_download.py    | 26 ++++++++----
 .../backend/tests/test_openai_auto_switch.py  | 24 +++++++++++
 .../settings/components/usage-examples.tsx    | 42 ++++++++++++-------
 ...st_usage_examples_model_source_contract.py | 13 ++++--
 5 files changed, 91 insertions(+), 27 deletions(-)

diff --git a/studio/backend/core/inference/local_model_resolver.py b/studio/backend/core/inference/local_model_resolver.py
index 363926a4c74..4f1286cd8e5 100644
--- a/studio/backend/core/inference/local_model_resolver.py
+++ b/studio/backend/core/inference/local_model_resolver.py
@@ -109,7 +109,18 @@ def _local_gguf_entry(loader_id: str, info) -> Optional[_LocalGgufEntry]:
         load_dir = _resolve_load_dir(p)
         variants, _ = list_local_gguf_variants(str(load_dir))
         quants = tuple(v.quant for v in variants if getattr(v, "quant", None))
-        return _LocalGgufEntry(loader_id, str(load_dir), quants) if quants else None
+        if not quants:
+            return None
+        # That call orders by descending size, so the head is the biggest quant,
+        # often F16. A bare id means whichever quant a plain load would take, so put
+        # that first: everything downstream reads [0], and answering with the
+        # largest can evict a working model and then OOM starting it.
+        from core.inference.openai_auto_download import preferred_quant
+
+        best = preferred_quant(quants)
+        if best and quants[0] != best:
+            quants = (best, *(q for q in quants if q != best))
+        return _LocalGgufEntry(loader_id, str(load_dir), quants)
     except Exception:
         return None
 
diff --git a/studio/backend/core/inference/openai_auto_download.py b/studio/backend/core/inference/openai_auto_download.py
index c51a159faaf..01cbb21ea93 100644
--- a/studio/backend/core/inference/openai_auto_download.py
+++ b/studio/backend/core/inference/openai_auto_download.py
@@ -606,6 +606,23 @@ def _probe():
     return await _dispatch(repo_id, variant, expected_bytes, requested_model, hf_token, active)
 
 
+def preferred_quant(labels) -> Optional[str]:
+    """The quant a plain load would pick from *labels*, or None.
+
+    The one ranking for "which quant did they mean": local resolution, remote
+    admission and what /v1/models advertises all have to agree, or a bare id
+    means a different quant depending on which of them answered it.
+    """
+    from utils.models.model_config import _pick_best_gguf
+
+    # _pick_best_gguf ranks filenames and matches upper-case tokens, so feed "<LABEL>.gguf".
+    synthetic: dict[str, str] = {}
+    for name in labels:
+        synthetic.setdefault(f"{name.upper()}.gguf", name)
+    best = _pick_best_gguf(list(synthetic))
+    return synthetic.get(best) if best else None
+
+
 def _match_variant(wanted: Optional[str], variants: dict[str, int]) -> Optional[str]:
     """Resolve the requested quant against what the repo actually has.
 
@@ -618,14 +635,7 @@ def _match_variant(wanted: Optional[str], variants: dict[str, int]) -> Optional[
     if wanted and looks_like_quant(wanted):
         lowered = {name.lower(): name for name in variants}
         return lowered.get(wanted.strip().lower())
-    from utils.models.model_config import _pick_best_gguf
-
-    # _pick_best_gguf ranks filenames and matches upper-case tokens, so feed "<LABEL>.gguf".
-    synthetic: dict[str, str] = {}
-    for name in variants:
-        synthetic.setdefault(f"{name.upper()}.gguf", name)
-    best = _pick_best_gguf(list(synthetic))
-    return synthetic.get(best) if best else None
+    return preferred_quant(variants)
 
 
 async def _dispatch(
diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index 53e5b621495..914ff8e6db2 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -4234,3 +4234,27 @@ def test_invalidating_keeps_the_entries_it_already_had(monkeypatch):
         "Q4_K_M",
         "org/old",
     )
+
+
+def test_a_bare_local_id_takes_the_quant_a_plain_load_would(monkeypatch, tmp_path):
+    # list_local_gguf_variants orders by descending size, so the head is the biggest
+    # quant. Resolving a bare id to that could evict a working model and then OOM
+    # starting an F16 on a box sized for the Q4 sitting right next to it, and
+    # /v1/models advertised the same head for pinning.
+    from core.inference.local_model_resolver import _local_gguf_entry
+
+    for name, size in (("model-F16.gguf", 900), ("model-Q4_K_M.gguf", 100)):
+        (tmp_path / name).write_bytes(b"\0" * size)
+    entry = _local_gguf_entry("org/model", type("I", (), {"path": str(tmp_path)})())
+    assert entry is not None
+    assert set(entry.variants) == {"F16", "Q4_K_M"}
+    assert entry.variants[0] == "Q4_K_M", "a bare id would have resolved to F16"
+
+
+def test_local_and_remote_agree_on_the_preferred_quant():
+    # A bare id must mean the same quant whichever side answered it.
+    from core.inference.openai_auto_download import _match_variant, preferred_quant
+
+    labels = ("F16", "Q8_0", "UD-Q4_K_XL", "Q4_K_M")
+    assert preferred_quant(labels) == _match_variant(None, dict.fromkeys(labels, 1))
+    assert preferred_quant(labels) not in ("F16",)
diff --git a/studio/frontend/src/features/settings/components/usage-examples.tsx b/studio/frontend/src/features/settings/components/usage-examples.tsx
index 0f72615afb7..7786a55384d 100644
--- a/studio/frontend/src/features/settings/components/usage-examples.tsx
+++ b/studio/frontend/src/features/settings/components/usage-examples.tsx
@@ -368,6 +368,12 @@ function looksLikePath(id: string): boolean {
   );
 }
 
+// Same model, ignoring any ":quant" a caller pinned.
+function sameBaseModelId(a: string, b: string): boolean {
+  const base = (id: string) => id.trim().toLowerCase().split(":")[0];
+  return a.trim().toLowerCase() === b.trim().toLowerCase() || base(a) === base(b);
+}
+
 // The model the examples name: always an id /v1 resolves against, null when there is none.
 function useExampleModelName(): string | null {
   const checkpoint = useChatRuntimeStore((s) => s.params.checkpoint);
@@ -378,12 +384,10 @@ function useExampleModelName(): string | null {
   const [autoSwitch, setAutoSwitch] = useState(false);
   const usableCheckpoint =
     !!checkpoint && !checkpoint.startsWith("external::") && !looksLikePath(checkpoint);
-  const needsCatalog = !usableCheckpoint;
 
-  // Only when the checkpoint can't answer it; polls for as long as it is mounted.
+  // Always: a stored checkpoint can stop being servable without the store changing.
   // biome-ignore lint/correctness/useExhaustiveDependencies: a load or unload must refetch the servable ids
   useEffect(() => {
-    if (!needsCatalog) return;
     let cancelled = false;
     let timeoutId: number | null = null;
 
@@ -415,24 +419,34 @@ function useExampleModelName(): string | null {
       cancelled = true;
       if (timeoutId !== null) window.clearTimeout(timeoutId);
     };
-  }, [needsCatalog, checkpoint, ggufVariant]);
+  }, [checkpoint, ggufVariant]);
 
   return useMemo(() => {
-    if (usableCheckpoint && checkpoint) {
+    // Name something held here, with its quant to pin the file on disk.
+    const fromCatalog = (): string | null => {
+      const pick =
+        catalog?.find((m) => m.loaded) ?? (autoSwitch ? catalog?.[0] : undefined);
+      if (!pick) {
+        return null;
+      }
+      return pick.quant && !pick.id.includes(":")
+        ? `${pick.id}:${pick.quant}`
+        : pick.id;
+    };
+    // The store keeps a checkpoint across an idle unload, so it only names a
+    // runnable model while the catalog still backs it, or switching can reload it.
+    // null catalog means /v1/models has not answered, so don't call it unrunnable.
+    const backed =
+      catalog === null ||
+      autoSwitch ||
+      catalog.some((m) => m.loaded && sameBaseModelId(m.id, checkpoint ?? ""));
+    if (usableCheckpoint && checkpoint && backed) {
       if (ggufVariant && !checkpoint.includes(":")) {
         return `${checkpoint}:${ggufVariant}`;
       }
       return checkpoint;
     }
-    // No usable checkpoint: name something held here, with its quant to pin the file on disk.
-    const pick =
-      catalog?.find((m) => m.loaded) ?? (autoSwitch ? catalog?.[0] : undefined);
-    if (!pick) {
-      return null;
-    }
-    return pick.quant && !pick.id.includes(":")
-      ? `${pick.id}:${pick.quant}`
-      : pick.id;
+    return fromCatalog();
   }, [autoSwitch, catalog, checkpoint, ggufVariant, usableCheckpoint]);
 }
 
diff --git a/tests/studio/test_usage_examples_model_source_contract.py b/tests/studio/test_usage_examples_model_source_contract.py
index dba901438e3..a708c28f7c3 100644
--- a/tests/studio/test_usage_examples_model_source_contract.py
+++ b/tests/studio/test_usage_examples_model_source_contract.py
@@ -50,14 +50,19 @@ def test_examples_never_print_a_hardcoded_model_id():
 
 
 def test_catalog_refresh_follows_the_loaded_model():
-    # `[needsCatalog]` alone never re-ran, so a finished load left the first fetch's name.
+    # A dep list that misses these never re-ran, so a finished load left the first
+    # fetch's name. It must not be gated on having no checkpoint either: the store
+    # keeps one across an idle unload, which changes nothing React can see.
     src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")
     hook = src[src.find("function useExampleModelName") : src.find("// Backend PATH detection")]
-    assert "}, [needsCatalog, checkpoint, ggufVariant]);" in hook
-    # A finishing download moves no store state, so the fetch retries on a timer too.
-    assert "window.setTimeout(update, CATALOG_RETRY_MS)" in hook
+    assert "}, [checkpoint, ggufVariant]);" in hook
+    assert "needsCatalog" not in hook
+    # A finishing download moves no store state, so the fetch retries on a timer too,
+    # and residency only slows that timer rather than stopping it.
+    assert "CATALOG_RETRY_MS" in hook and "CATALOG_IDLE_MS" in hook
     assert "window.clearTimeout(timeoutId)" in hook
     assert "const CATALOG_RETRY_MS = 15000;" in src
+    assert "const CATALOG_IDLE_MS = 60000;" in src
 
 
 def test_usage_examples_has_no_duplicate_auto_switch_control():

From 667edccdf34c3b3cc6f64ccec3b6ed419642dd62 Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Mon, 27 Jul 2026 05:51:42 +0000
Subject: [PATCH 42/56] Studio: fix the Windows path compare, and advertise a
 label the worker knows

The case fix normalized the separator to "/" and then called os.path.normcase,
which on Windows folds case and rewrites the separator back to a backslash, so
the descendant checks compared against a "/" the path no longer had. A manually
loaded GGUF reached through an alias then read as a different model, giving a
false 404 and an alias marked unloaded. Run normcase first and normalize the
separator after it.

There are two quant-label extractors and they only agree while a recognized
quant token is present. With none, _extract_quant_label takes the last
hyphenated segment, "7b" of llama-7b, while build_gguf_variant_plans and the
worker key the whole stem: the plan lookup missed and the job exited on a
variant it had no shards for. Use the canonical extractor for the unrecognized
case only. Checked across real filenames first, the two match on every
recognized quant and part on bpw-qualified labels, which _extract_quant_label
keeps apart on purpose so byteshape's IQ4_XS at 3.53, 3.97 and 4.19 bpw stay
separate variants.
---
 .../core/inference/openai_auto_download.py    |  7 ++++
 studio/backend/routes/inference.py            |  5 ++-
 .../tests/test_openai_auto_download.py        | 38 +++++++++++++++++++
 3 files changed, 49 insertions(+), 1 deletion(-)

diff --git a/studio/backend/core/inference/openai_auto_download.py b/studio/backend/core/inference/openai_auto_download.py
index 01cbb21ea93..f51f83c7a92 100644
--- a/studio/backend/core/inference/openai_auto_download.py
+++ b/studio/backend/core/inference/openai_auto_download.py
@@ -210,6 +210,7 @@ def _gguf_variants(siblings) -> dict[str, int]:
     the companions back into every quant, so the disk reserve is measured against
     what the worker fetches rather than the main files alone.
     """
+    from hub.utils.gguf import extract_quant_label as canonical_quant_label
     from hub.utils.gguf_plan import build_gguf_variant_plans
     from utils.models.model_config import (
         _extract_quant_label,
@@ -226,6 +227,12 @@ def _gguf_variants(siblings) -> dict[str, int]:
         if not name.lower().endswith(".gguf"):
             continue
         quant = _extract_quant_label(name)
+        if not looks_like_quant(quant):
+            # With no recognized quant token the two extractors part ways: this one
+            # takes the last hyphenated segment ("7b" of llama-7b) while the plan and
+            # the worker key the whole stem. Advertising ours dispatches a variant the
+            # worker cannot resolve, so take theirs for the unrecognized case only.
+            quant = canonical_quant_label(name) or quant
         if _is_mmproj(name) or _is_mtp_drafter(name) or _is_big_endian_gguf_path(name, quant):
             continue
         plan = plans.get(quant.lower())
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 366501fc3d3..0393f077b50 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3806,7 +3806,10 @@ def _norm_path(value: str) -> str:
     """Compare-ready path. normcase, not lower: on a case-sensitive filesystem
     /srv/models/Foo and /srv/models/foo are different models."""
     import os
-    return os.path.normcase(str(value).replace("\\", "/").rstrip("/"))
+    # normcase after, not before: on Windows it folds case *and* rewrites the
+    # separator to a backslash, so normalizing first leaves the descendant checks
+    # below comparing a "/" against a path that no longer has any.
+    return os.path.normcase(str(value)).replace("\\", "/").rstrip("/")
 
 
 def _resident_quant_is(variant: Optional[str]) -> bool:
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index 7a962032257..2ba7aea8dae 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -1451,3 +1451,41 @@ def test_a_remote_tag_that_names_no_quant_picks_the_preferred_one(hub):
     refusal = _run("unsloth/x-GGUF:Q2_K")
     assert refusal.status == 404 and "no quant" in refusal.message
     assert hub["started"] == []
+
+
+def test_a_generic_gguf_advertises_the_label_the_worker_resolves(hub):
+    # With no recognized quant token the label extractors part ways: one takes the
+    # last hyphenated segment, the plan and the worker key the whole stem. Dispatching
+    # ours made the worker exit with "No GGUF shards matching variant".
+    from hub.utils.gguf import extract_quant_label as canonical
+    from hub.utils.gguf_plan import build_gguf_variant_plans
+
+    sibling = _Sibling("llama-7b.gguf", 4 * 1024**3)
+    hub["info"] = _Info([sibling])
+    assert _run("unsloth/generic-GGUF").code == "model_downloading"
+    dispatched = hub["started"][0][1]
+    assert dispatched == canonical("llama-7b.gguf")
+    # The key the worker will look up has to contain it, which is the whole point.
+    assert dispatched.lower() in build_gguf_variant_plans([sibling])
+
+
+def test_windows_style_paths_still_match_their_own_directory(monkeypatch):
+    # normcase folds case and rewrites the separator to a backslash on Windows, so
+    # normalizing to "/" before it left the descendant checks comparing a "/" against
+    # a path that had none, and a resident model read as a different one.
+    import ntpath
+
+    monkeypatch.setattr(inference_route.os.path, "normcase", ntpath.normcase)
+    # A manual load records the file, so only the descendant check can match the
+    # directory the resolver returns; an equality match would prove nothing here.
+    loaded = _Loaded("C:\\models\\repo\\model.gguf")
+    loaded.gguf_path = "C:\\models\\repo\\model.gguf"
+    monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+    monkeypatch.setattr(
+        inference_route,
+        "get_inference_backend",
+        lambda: type("B", (), {"active_model_name": None})(),
+    )
+    assert inference_route._resolves_to_resident("C:\\models\\repo") is True
+    assert inference_route._resolves_to_resident("C:\\Models\\Repo") is True
+    assert inference_route._resolves_to_resident("C:\\models\\other") is False

From 4e09d9d768185b7d34aff2ec5fd11b51dc5f2fbe Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 27 Jul 2026 05:54:09 +0000
Subject: [PATCH 43/56] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 studio/backend/routes/inference.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 0393f077b50..818f516ee76 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3806,6 +3806,7 @@ def _norm_path(value: str) -> str:
     """Compare-ready path. normcase, not lower: on a case-sensitive filesystem
     /srv/models/Foo and /srv/models/foo are different models."""
     import os
+
     # normcase after, not before: on Windows it folds case *and* rewrites the
     # separator to a backslash, so normalizing first leaves the descendant checks
     # below comparing a "/" against a path that no longer has any.

From c5a06cb32f5886225d444741664e2669f571fd9f Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Mon, 27 Jul 2026 06:01:25 +0000
Subject: [PATCH 44/56] Studio: a stored checkpoint needs catalog evidence, not
 just the switch setting

Preferring it whenever switching was on short-circuited the catalog check, so a
checkpoint the store still held after the model was deleted or moved kept being
named even though /v1/models had already proved it absent, and the snippets 404d
instead of falling back to a model that is actually there.

A lookup rather than a disjunction, which settles the whole matrix in one place:
no answer yet keeps the checkpoint, since that is not evidence against it; listed
and resident keeps it; listed but unloaded keeps it only when switching can
reload it; absent falls back whatever the setting says.
---
 .../features/settings/components/usage-examples.tsx | 13 ++++++-------
 .../test_usage_examples_model_source_contract.py    | 12 ++++++++++++
 2 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/studio/frontend/src/features/settings/components/usage-examples.tsx b/studio/frontend/src/features/settings/components/usage-examples.tsx
index 7786a55384d..833d1bb1253 100644
--- a/studio/frontend/src/features/settings/components/usage-examples.tsx
+++ b/studio/frontend/src/features/settings/components/usage-examples.tsx
@@ -433,13 +433,12 @@ function useExampleModelName(): string | null {
         ? `${pick.id}:${pick.quant}`
         : pick.id;
     };
-    // The store keeps a checkpoint across an idle unload, so it only names a
-    // runnable model while the catalog still backs it, or switching can reload it.
-    // null catalog means /v1/models has not answered, so don't call it unrunnable.
-    const backed =
-      catalog === null ||
-      autoSwitch ||
-      catalog.some((m) => m.loaded && sameBaseModelId(m.id, checkpoint ?? ""));
+    // The store keeps a checkpoint across an idle unload, and across the model
+    // being deleted, so it only names a runnable model while the catalog still
+    // lists it: resident, or downloaded with switching able to reload it. A null
+    // catalog means /v1/models has not answered, which is not evidence against it.
+    const entry = catalog?.find((m) => sameBaseModelId(m.id, checkpoint ?? ""));
+    const backed = catalog === null || (!!entry && (entry.loaded || autoSwitch));
     if (usableCheckpoint && checkpoint && backed) {
       if (ggufVariant && !checkpoint.includes(":")) {
         return `${checkpoint}:${ggufVariant}`;
diff --git a/tests/studio/test_usage_examples_model_source_contract.py b/tests/studio/test_usage_examples_model_source_contract.py
index a708c28f7c3..37a274d1bda 100644
--- a/tests/studio/test_usage_examples_model_source_contract.py
+++ b/tests/studio/test_usage_examples_model_source_contract.py
@@ -65,6 +65,18 @@ def test_catalog_refresh_follows_the_loaded_model():
     assert "const CATALOG_IDLE_MS = 60000;" in src
 
 
+def test_a_stored_checkpoint_needs_catalog_evidence():
+    # The store keeps a checkpoint across an idle unload and across the model being
+    # deleted. Preferring it on the switch setting alone kept naming one /v1/models
+    # had already proved absent, so the snippets 404d instead of falling back.
+    src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")
+    hook = src[src.find("function useExampleModelName") : src.find("// Backend PATH detection")]
+    assert "const entry = catalog?.find((m) => sameBaseModelId(m.id, checkpoint ?? \"\"));" in hook
+    # Resident, or downloaded with switching able to reload it. Never the setting alone.
+    assert "catalog === null || (!!entry && (entry.loaded || autoSwitch))" in hook
+    assert "autoSwitch ||\n" not in hook
+
+
 def test_usage_examples_has_no_duplicate_auto_switch_control():
     # ModelAutoSwitchSection renders this setting just below and shares no state with it.
     src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")

From 278d459da67bb4afae37232b9879cd00c5a27d22 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 27 Jul 2026 06:02:09 +0000
Subject: [PATCH 45/56] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 tests/studio/test_usage_examples_model_source_contract.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/studio/test_usage_examples_model_source_contract.py b/tests/studio/test_usage_examples_model_source_contract.py
index 37a274d1bda..2eebe053603 100644
--- a/tests/studio/test_usage_examples_model_source_contract.py
+++ b/tests/studio/test_usage_examples_model_source_contract.py
@@ -71,7 +71,7 @@ def test_a_stored_checkpoint_needs_catalog_evidence():
     # had already proved absent, so the snippets 404d instead of falling back.
     src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")
     hook = src[src.find("function useExampleModelName") : src.find("// Backend PATH detection")]
-    assert "const entry = catalog?.find((m) => sameBaseModelId(m.id, checkpoint ?? \"\"));" in hook
+    assert 'const entry = catalog?.find((m) => sameBaseModelId(m.id, checkpoint ?? ""));' in hook
     # Resident, or downloaded with switching able to reload it. Never the setting alone.
     assert "catalog === null || (!!entry && (entry.loaded || autoSwitch))" in hook
     assert "autoSwitch ||\n" not in hook

From a59b2abcb0798fecb59d48b15ea03eacfd355119 Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Mon, 27 Jul 2026 06:03:17 +0000
Subject: [PATCH 46/56] Studio: normalize the quote style pre-commit would have
 rewritten

---
 tests/studio/test_usage_examples_model_source_contract.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/studio/test_usage_examples_model_source_contract.py b/tests/studio/test_usage_examples_model_source_contract.py
index 37a274d1bda..2eebe053603 100644
--- a/tests/studio/test_usage_examples_model_source_contract.py
+++ b/tests/studio/test_usage_examples_model_source_contract.py
@@ -71,7 +71,7 @@ def test_a_stored_checkpoint_needs_catalog_evidence():
     # had already proved absent, so the snippets 404d instead of falling back.
     src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")
     hook = src[src.find("function useExampleModelName") : src.find("// Backend PATH detection")]
-    assert "const entry = catalog?.find((m) => sameBaseModelId(m.id, checkpoint ?? \"\"));" in hook
+    assert 'const entry = catalog?.find((m) => sameBaseModelId(m.id, checkpoint ?? ""));' in hook
     # Resident, or downloaded with switching able to reload it. Never the setting alone.
     assert "catalog === null || (!!entry && (entry.loaded || autoSwitch))" in hook
     assert "autoSwitch ||\n" not in hook

From 20ed0b04b29644aaa9519c53a8e91bf51647f3d4 Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Mon, 27 Jul 2026 06:27:20 +0000
Subject: [PATCH 47/56] Studio: cover the model that just landed, and pin the
 quant the catalog has

Retaining the index on invalidation protects what was already scanned and by
construction cannot contain the model that just finished downloading, so a bare
request for it in the window before the rebuild was still answered by the
resident model. Record the repo at the completion hook and treat that as
admission evidence alongside the resolver and the catalog; the next completed
scan clears the notes, since the index then covers them. Publishing a rebuilt
index before completion becomes observable would have closed it too, but that
blocks the download worker for the length of the scan.

Catalog membership proves the repo, not the saved quant, and the examples then
pinned the stored one. A quant deleted while another quant of the same repo
remained produced repo:deleted-quant, a missing-quant 404 with a runnable
alternative listed right beside it. Pin what the catalog advertises: for a
resident entry that is the resident quant, for an unloaded one it is a quant
actually on disk. The store is only consulted before /v1/models has answered.
---
 .../core/inference/local_model_resolver.py    | 21 ++++++++
 .../hub/services/download_lifecycle.py        |  7 ++-
 studio/backend/routes/inference.py            | 14 +++++-
 .../tests/test_openai_auto_download.py        | 22 +++++++++
 .../backend/tests/test_openai_auto_switch.py  | 48 +++++++++++++++++++
 .../settings/components/usage-examples.tsx    | 10 ++--
 ...st_usage_examples_model_source_contract.py | 10 ++++
 7 files changed, 126 insertions(+), 6 deletions(-)

diff --git a/studio/backend/core/inference/local_model_resolver.py b/studio/backend/core/inference/local_model_resolver.py
index 4f1286cd8e5..ddfa8ea5372 100644
--- a/studio/backend/core/inference/local_model_resolver.py
+++ b/studio/backend/core/inference/local_model_resolver.py
@@ -36,6 +36,10 @@ class _LocalGgufEntry:
 _scan: tuple[float, dict[str, _LocalGgufEntry]] = (0.0, {})
 # Not _lock: that is held for the whole scan, so the request path would wait on it.
 _warm_lock = threading.Lock()
+# Repos that finished downloading but are not in the published index yet. The
+# retained index covers what was already known; nothing covers the one that just
+# landed until the next scan, and the request path must not call it absent.
+_just_downloaded: set[str] = set()
 _warming = False
 _last_scan_s = 0.0
 # Rescan at most a tenth of the time: on the TTL alone a slow scan would run continuously.
@@ -310,6 +314,21 @@ def _sibling_revision_entries(raw_id: str, loader_id: str):
             yield sibling.name, entry
 
 
+def note_downloaded(repo_id: Optional[str]) -> None:
+    """Record a repo as present ahead of the scan that will index it."""
+    if not repo_id:
+        return
+    with _lock:
+        _just_downloaded.add(repo_id.strip().lower())
+
+
+def recently_downloaded(repo_id: str) -> bool:
+    """Whether *repo_id* finished downloading since the last completed scan."""
+    if not isinstance(repo_id, str) or not repo_id.strip():
+        return False
+    return repo_id.strip().lower() in _just_downloaded
+
+
 def invalidate_index() -> None:
     """Mark the cached scan stale so the next resolve sees a just-finished
     download, rather than waiting out the TTL.
@@ -339,6 +358,8 @@ def _index() -> dict[str, _LocalGgufEntry]:
         # an install with many local models can itself exceed the TTL, which would
         # store the cache already expired and make every request rebuild the index.
         _scan = (time.monotonic(), fresh)
+        # The scan supersedes the notes: whatever landed is in the index now.
+        _just_downloaded.clear()
         return fresh
 
 
diff --git a/studio/backend/hub/services/download_lifecycle.py b/studio/backend/hub/services/download_lifecycle.py
index 01e0e0fefbb..49a500d0f0e 100644
--- a/studio/backend/hub/services/download_lifecycle.py
+++ b/studio/backend/hub/services/download_lifecycle.py
@@ -246,7 +246,12 @@ def finalize_worker_exit(
         # and would otherwise keep reporting the model absent and let the request be
         # served by whatever is resident.
         try:
-            from core.inference.local_model_resolver import invalidate_index, warm_index_soon
+            from core.inference.local_model_resolver import (
+                invalidate_index,
+                note_downloaded,
+                warm_index_soon,
+            )
+            note_downloaded(repo_id)
             invalidate_index()
             # Rebuild from here rather than from the first request that needs it,
             # so the new model becomes resolvable without a scan on the request path.
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 818f516ee76..983b3430d78 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3876,7 +3876,11 @@ async def _reject_unservable_model(
         return
     base, variant = split_model_ref(requested_model)
     quantified = looks_like_quant(variant)
-    from core.inference.local_model_resolver import resolve_local_gguf, warm_index_soon
+    from core.inference.local_model_resolver import (
+        recently_downloaded,
+        resolve_local_gguf,
+        warm_index_soon,
+    )
     from utils.openai_auto_switch_settings import get_openai_auto_switch_enabled
 
     try:
@@ -3915,6 +3919,8 @@ async def _reject_unservable_model(
         here = (
             downloaded
             or advertised is not None
+            # Just landed, so no scan has indexed it yet and neither of the above sees it.
+            or recently_downloaded(base)
             or (variant is not None and resolve_local_gguf(base, allow_scan = False) is not None)
         )
         switchable = downloaded and get_openai_auto_switch_enabled()
@@ -10966,7 +10972,11 @@ def _quant_reference_resolves(model_id: Optional[str], quant: str) -> bool:
     such files with no quants at all, so advertising one hands out a pin that dies
     the moment another model loads.
     """
-    from core.inference.local_model_resolver import resolve_local_gguf, warm_index_soon
+    from core.inference.local_model_resolver import (
+        recently_downloaded,
+        resolve_local_gguf,
+        warm_index_soon,
+    )
 
     if not model_id:
         return False
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index 2ba7aea8dae..7997e5c5031 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -1489,3 +1489,25 @@ def test_windows_style_paths_still_match_their_own_directory(monkeypatch):
     assert inference_route._resolves_to_resident("C:\\models\\repo") is True
     assert inference_route._resolves_to_resident("C:\\Models\\Repo") is True
     assert inference_route._resolves_to_resident("C:\\models\\other") is False
+
+
+def test_a_bare_request_for_a_just_downloaded_model_is_refused(monkeypatch):
+    # End of the same chain: the note has to reach admission, or a bare request in
+    # the window between the download landing and the scan is served by the resident
+    # model, which is the whole failure this hook exists to stop.
+    from core.inference import local_model_resolver as resolver
+
+    monkeypatch.setattr(resolver, "_scan", (time.monotonic(), {}))
+    monkeypatch.setattr(resolver, "_just_downloaded", {"org/fresh"})
+    loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
+    monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+    monkeypatch.setattr(
+        inference_route,
+        "get_inference_backend",
+        lambda: type("B", (), {"active_model_name": None})(),
+    )
+    monkeypatch.setattr(inference_route, "_unavailable_model_message", _fake_unavailable_message)
+    with pytest.raises(HTTPException) as excinfo:
+        asyncio.run(inference_route._reject_unservable_model("org/fresh", _Req()))
+    assert excinfo.value.status_code == 404
+    assert asyncio.run(inference_route._reject_unservable_model("org/never", _Req())) is None
diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index 914ff8e6db2..af03baeb139 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -4258,3 +4258,51 @@ def test_local_and_remote_agree_on_the_preferred_quant():
     labels = ("F16", "Q8_0", "UD-Q4_K_XL", "Q4_K_M")
     assert preferred_quant(labels) == _match_variant(None, dict.fromkeys(labels, 1))
     assert preferred_quant(labels) not in ("F16",)
+
+
+def test_a_just_downloaded_model_is_evidence_before_the_scan_indexes_it(monkeypatch):
+    # Retaining the old index covers what was already known, but nothing covers the
+    # model that just landed until the next scan finishes. A bare request for it in
+    # that window was answered by the unrelated resident model.
+    import logging
+
+    from hub.services import download_lifecycle
+
+    class _Proc:
+        stderr = None
+
+        def wait(self):
+            return 0
+
+    class _Registry:
+        def cancel_requested(self, key):
+            return False
+
+        def drop_process(self, key, proc):
+            return True
+
+        def get_job_metadata(self, key):
+            return None
+
+        def set_job(self, key, state):
+            pass
+
+    assert not resolver.recently_downloaded("org/fresh")
+    download_lifecycle.finalize_worker_exit(
+        _Registry(),
+        "org/fresh:Q4_K_M",
+        _Proc(),
+        hf_token = None,
+        label = "org/fresh",
+        log_prefix = "[test]",
+        logger = logging.getLogger(__name__),
+        repo_id = "org/fresh",
+    )
+    assert resolver.recently_downloaded("org/fresh"), "no evidence for the new model"
+    assert resolver.recently_downloaded("ORG/Fresh"), "evidence must be case-insensitive"
+    assert not resolver.recently_downloaded("org/other")
+
+    # The scan that indexes it supersedes the note.
+    monkeypatch.setattr(resolver, "_build_index", dict)
+    resolver._index()
+    assert not resolver.recently_downloaded("org/fresh")
diff --git a/studio/frontend/src/features/settings/components/usage-examples.tsx b/studio/frontend/src/features/settings/components/usage-examples.tsx
index 833d1bb1253..e3a254a8154 100644
--- a/studio/frontend/src/features/settings/components/usage-examples.tsx
+++ b/studio/frontend/src/features/settings/components/usage-examples.tsx
@@ -440,10 +440,14 @@ function useExampleModelName(): string | null {
     const entry = catalog?.find((m) => sameBaseModelId(m.id, checkpoint ?? ""));
     const backed = catalog === null || (!!entry && (entry.loaded || autoSwitch));
     if (usableCheckpoint && checkpoint && backed) {
-      if (ggufVariant && !checkpoint.includes(":")) {
-        return `${checkpoint}:${ggufVariant}`;
+      if (checkpoint.includes(":")) {
+        return checkpoint;
       }
-      return checkpoint;
+      // Pin the quant the catalog advertises, not the stored one: membership proves
+      // the repo, and the saved quant can name a file deleted while another quant of
+      // the same repo remains. Fall back to the store only before /v1/models answers.
+      const quant = catalog === null ? ggufVariant : entry?.quant;
+      return quant ? `${checkpoint}:${quant}` : checkpoint;
     }
     return fromCatalog();
   }, [autoSwitch, catalog, checkpoint, ggufVariant, usableCheckpoint]);
diff --git a/tests/studio/test_usage_examples_model_source_contract.py b/tests/studio/test_usage_examples_model_source_contract.py
index 2eebe053603..f353d1ccda8 100644
--- a/tests/studio/test_usage_examples_model_source_contract.py
+++ b/tests/studio/test_usage_examples_model_source_contract.py
@@ -77,6 +77,16 @@ def test_a_stored_checkpoint_needs_catalog_evidence():
     assert "autoSwitch ||\n" not in hook
 
 
+def test_the_pinned_quant_comes_from_the_catalog():
+    # Catalog membership proves the repo, not the saved quant. The stored one can
+    # name a file deleted while another quant of the same repo remains, and pinning
+    # it emitted repo:deleted-quant, a missing-quant 404 with a runnable one listed.
+    src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")
+    hook = src[src.find("function useExampleModelName") : src.find("// Backend PATH detection")]
+    assert "const quant = catalog === null ? ggufVariant : entry?.quant;" in hook
+    assert "`${checkpoint}:${ggufVariant}`" not in hook
+
+
 def test_usage_examples_has_no_duplicate_auto_switch_control():
     # ModelAutoSwitchSection renders this setting just below and shares no state with it.
     src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")

From 19c572c739186795b80c508f9cf7ad3cb8d6cdc5 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 27 Jul 2026 06:28:57 +0000
Subject: [PATCH 48/56] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 studio/backend/hub/services/download_lifecycle.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/studio/backend/hub/services/download_lifecycle.py b/studio/backend/hub/services/download_lifecycle.py
index 49a500d0f0e..397b835d127 100644
--- a/studio/backend/hub/services/download_lifecycle.py
+++ b/studio/backend/hub/services/download_lifecycle.py
@@ -251,6 +251,7 @@ def finalize_worker_exit(
                 note_downloaded,
                 warm_index_soon,
             )
+
             note_downloaded(repo_id)
             invalidate_index()
             # Rebuild from here rather than from the first request that needs it,

From 68199da9b00e592ad915685cca572ea9ad63e8b4 Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Mon, 27 Jul 2026 07:04:12 +0000
Subject: [PATCH 49/56] Studio: apply three rules everywhere they belong, not
 only where reported

The trust probe was the last credential handoff still passing a raw token.
huggingface_hub reads None as "use the cached login", so a caller-named repo
was read with this server's Hugging Face identity whenever the caller sent
none, which is exactly the isolation the metadata probe and the worker already
keep. It takes _hub_token now. Enumerated the rest of that path while there:
auth_check, model_info and spawn_worker were already correct.

finalize_worker_exit is shared with dataset downloads, so the resolver hook
fired for every completed dataset, scanning the model directories for nothing
and recording the dataset id as local-model evidence, which turns a bare /v1
request naming that id into a refusal instead of a foreign-id fallthrough.
Gated on repo_type.

_already_serving decided "bare" on the presence of a colon while
_loaded_satisfies and the resolver decide it on whether the suffix names a
quant, so org/model:latest against a serving Q8_0 read as a mismatch and
swapped in the preferred Q4_K_M for a request either one answers. That rule now
lives in four places, each fixed in its own round, so this time I looked for
the rest and found a fifth: describe_local_miss splits on the bare colon and
its docstring claims it splits like the resolver. It no longer did, and would
report a missing quant named "latest". Fixed here too, unreported.
---
 .../core/inference/local_model_resolver.py    |  8 ++-
 .../core/inference/openai_auto_download.py    |  5 +-
 .../hub/services/download_lifecycle.py        | 36 +++++++------
 studio/backend/routes/inference.py            |  8 ++-
 .../tests/test_openai_auto_download.py        | 52 +++++++++++++++++++
 .../backend/tests/test_openai_auto_switch.py  | 49 +++++++++++++++++
 6 files changed, 137 insertions(+), 21 deletions(-)

diff --git a/studio/backend/core/inference/local_model_resolver.py b/studio/backend/core/inference/local_model_resolver.py
index ddfa8ea5372..fdc639ff217 100644
--- a/studio/backend/core/inference/local_model_resolver.py
+++ b/studio/backend/core/inference/local_model_resolver.py
@@ -463,8 +463,12 @@ def describe_local_miss(requested: str) -> tuple[str, tuple[str, ...]]:
     """
     if not isinstance(requested, str) or not requested.strip():
         return MISS_MODEL_NOT_FOUND, ()
-    base, sep, _variant = requested.strip().rpartition(":")
-    if not sep:
+    base, sep, variant = requested.strip().rpartition(":")
+    from core.inference.openai_auto_download import looks_like_quant
+
+    # Split like the resolver or the two disagree: a tag naming no quant means the
+    # repo there, so reporting a missing quant for it would name one nobody asked for.
+    if not sep or not looks_like_quant(variant):
         return MISS_MODEL_NOT_FOUND, ()
     try:
         entry = _index().get(base.strip().lower())
diff --git a/studio/backend/core/inference/openai_auto_download.py b/studio/backend/core/inference/openai_auto_download.py
index f51f83c7a92..db00b624322 100644
--- a/studio/backend/core/inference/openai_auto_download.py
+++ b/studio/backend/core/inference/openai_auto_download.py
@@ -546,7 +546,10 @@ def _probe():
     # trust_remote_code gate: _config_has_auto_map is tri-state, so refuse on True and on None.
     from utils.security.consent import _config_has_auto_map
 
-    has_auto_map = await asyncio.to_thread(_config_has_auto_map, repo_id, hf_token)
+    # _hub_token, not the raw token: None lets huggingface_hub fall back to a cached
+    # server login, so a caller-named repo would be probed with this server's identity.
+    # Same rule as the metadata probe and the worker.
+    has_auto_map = await asyncio.to_thread(_config_has_auto_map, repo_id, _hub_token(hf_token))
     if has_auto_map is not False:
         _release(active)
         unknown = has_auto_map is None
diff --git a/studio/backend/hub/services/download_lifecycle.py b/studio/backend/hub/services/download_lifecycle.py
index 397b835d127..b01e25500ef 100644
--- a/studio/backend/hub/services/download_lifecycle.py
+++ b/studio/backend/hub/services/download_lifecycle.py
@@ -241,24 +241,26 @@ def finalize_worker_exit(
     state = classify_exit(rc, cancel_requested = cancel_requested)
     if state == "complete":
         registry.set_job(key, "complete")
-        # Every download lands here, so this is where /v1 learns a new model exists.
-        # Its resolver answers the request path from a cached scan with no watcher,
-        # and would otherwise keep reporting the model absent and let the request be
-        # served by whatever is resident.
-        try:
-            from core.inference.local_model_resolver import (
-                invalidate_index,
-                note_downloaded,
-                warm_index_soon,
-            )
+        # Where /v1 learns a new model exists: its resolver answers the request path
+        # from a cached scan with no watcher, and would otherwise report the model
+        # absent and let the request be served by whatever is resident. Models only,
+        # since datasets share this path and noting one as a local model would refuse
+        # a bare request naming that id instead of letting a foreign id fall through.
+        if repo_type == "model":
+            try:
+                from core.inference.local_model_resolver import (
+                    invalidate_index,
+                    note_downloaded,
+                    warm_index_soon,
+                )
 
-            note_downloaded(repo_id)
-            invalidate_index()
-            # Rebuild from here rather than from the first request that needs it,
-            # so the new model becomes resolvable without a scan on the request path.
-            warm_index_soon()
-        except Exception:
-            pass
+                note_downloaded(repo_id)
+                invalidate_index()
+                # Rebuild here rather than on the first request that needs it, so the
+                # new model resolves without a scan on the request path.
+                warm_index_soon()
+            except Exception:
+                pass
         if transport == download_registry.TRANSPORT_HTTP:
             registry.update_job_transport(key, download_registry.TRANSPORT_HTTP)
         if stderr_text:
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 983b3430d78..e335f44e731 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -4054,7 +4054,13 @@ async def _resolve_and_switch() -> None:
         backend = get_llama_cpp_backend()
         # A bare model id (no :VARIANT) is satisfied by any loaded quant of that
         # repo, so it never reloads a different local quant that already serves it.
-        bare = ":" not in requested_model
+        from core.inference.openai_auto_download import looks_like_quant, split_model_ref
+
+        # A tag that names no quant (":latest", ":8b") means the repo, exactly as
+        # _loaded_satisfies and the resolver read it. Treating it as a quant tears
+        # down a serving Q8 to load the preferred Q4 for a request either satisfies.
+        _, _requested_variant = split_model_ref(requested_model)
+        bare = not looks_like_quant(_requested_variant)
 
         def _already_serving() -> bool:
             # Match against both the concrete load path and the advertised repo id,
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index 7997e5c5031..60b1defb3cf 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -1511,3 +1511,55 @@ def test_a_bare_request_for_a_just_downloaded_model_is_refused(monkeypatch):
         asyncio.run(inference_route._reject_unservable_model("org/fresh", _Req()))
     assert excinfo.value.status_code == 404
     assert asyncio.run(inference_route._reject_unservable_model("org/never", _Req())) is None
+
+
+def test_a_non_quant_tag_does_not_tear_down_a_serving_quant(monkeypatch):
+    # _already_serving split on ":" rather than on whether the suffix names a quant,
+    # so org/model:latest against a serving Q8_0 counted as a quant mismatch and
+    # swapped in the preferred Q4_K_M, for a request either one satisfies.
+    from core.inference import local_model_resolver as resolver
+
+    entry = resolver._LocalGgufEntry("org/model", "/hf/org--model/snap", ("Q4_K_M", "Q8_0"))
+    monkeypatch.setattr(resolver, "_scan", (time.monotonic(), {"org/model": entry}))
+    loaded = _Loaded("org/model", "Q8_0")
+    loaded.gguf_path = "/hf/org--model/snap/model-Q8_0.gguf"
+    monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+    monkeypatch.setattr(
+        inference_route,
+        "get_inference_backend",
+        lambda: type("B", (), {"active_model_name": None})(),
+    )
+    loads: list = []
+
+    async def _record_load(request, *a, **k):
+        loads.append(getattr(request, "gguf_variant", None))
+
+    monkeypatch.setattr(inference_route, "_load_model_impl", _record_load)
+    monkeypatch.setattr(
+        "utils.openai_auto_switch_settings.get_openai_auto_switch_enabled", lambda: True
+    )
+    for tag in ("org/model:latest", "org/model:8b", "org/model"):
+        asyncio.run(
+            inference_route._maybe_auto_switch_model(tag, _Req(), "tester")
+        )
+    assert loads == [], "a tag naming no quant swapped the serving model out"
+
+
+def test_the_trust_probe_never_falls_back_to_the_server_identity(hub, monkeypatch):
+    # huggingface_hub treats None as "use the cached login", so only an explicit
+    # False is anonymous. The metadata probe and the worker already pass one; this
+    # probe did not, so a caller-named repo was read with the server's identity.
+    seen: list = []
+
+    def _probe(model_name, hf_token = None):
+        seen.append(hf_token)
+        return False
+
+    monkeypatch.setattr("utils.security.consent._config_has_auto_map", _probe)
+    _run("unsloth/x-GGUF:UD-Q5_K_XL")
+    assert seen == [False], f"trust probe ran with {seen!r}, not an explicit anonymous token"
+
+    seen.clear()
+    auto_dl.reset_for_tests()
+    _run("unsloth/x-GGUF:UD-Q5_K_XL", hf_token = "hf_caller")
+    assert seen == ["hf_caller"], "the caller's own token must still be used"
diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index af03baeb139..a53e42b04c8 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -4209,6 +4209,8 @@ def set_job(self, key, state):
             label = "org/model",
             log_prefix = "[test]",
             logger = logging.getLogger(__name__),
+            repo_type = "model",
+            repo_id = "org/model",
         )
         == "complete"
     )
@@ -4296,6 +4298,7 @@ def set_job(self, key, state):
         label = "org/fresh",
         log_prefix = "[test]",
         logger = logging.getLogger(__name__),
+        repo_type = "model",
         repo_id = "org/fresh",
     )
     assert resolver.recently_downloaded("org/fresh"), "no evidence for the new model"
@@ -4306,3 +4309,49 @@ def set_job(self, key, state):
     monkeypatch.setattr(resolver, "_build_index", dict)
     resolver._index()
     assert not resolver.recently_downloaded("org/fresh")
+
+
+def test_a_finished_dataset_is_not_recorded_as_a_local_model(monkeypatch):
+    # finalize_worker_exit is shared with dataset downloads. Noting one as a local
+    # model would refuse a bare /v1 request naming that id while another model is
+    # resident, instead of letting a foreign id fall through, and would kick off a
+    # multi-directory model scan for nothing.
+    import logging
+    import time
+
+    from hub.services import download_lifecycle
+
+    class _Proc:
+        stderr = None
+
+        def wait(self):
+            return 0
+
+    class _Registry:
+        def cancel_requested(self, key):
+            return False
+
+        def drop_process(self, key, proc):
+            return True
+
+        def get_job_metadata(self, key):
+            return None
+
+        def set_job(self, key, state):
+            pass
+
+    stamp = time.monotonic()
+    monkeypatch.setattr(resolver, "_scan", (stamp, {"kept": "entry"}))
+    download_lifecycle.finalize_worker_exit(
+        _Registry(),
+        "org/corpus",
+        _Proc(),
+        hf_token = None,
+        label = "org/corpus",
+        log_prefix = "[test]",
+        logger = logging.getLogger(__name__),
+        repo_type = "dataset",
+        repo_id = "org/corpus",
+    )
+    assert not resolver.recently_downloaded("org/corpus")
+    assert resolver._scan == (stamp, {"kept": "entry"}), "a dataset invalidated the index"

From 3ddc1b6c7c602f56ddf1260145b9097aecb5009d Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 27 Jul 2026 07:04:59 +0000
Subject: [PATCH 50/56] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 studio/backend/tests/test_openai_auto_download.py | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index 60b1defb3cf..ed7669da9b7 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -1539,9 +1539,7 @@ async def _record_load(request, *a, **k):
         "utils.openai_auto_switch_settings.get_openai_auto_switch_enabled", lambda: True
     )
     for tag in ("org/model:latest", "org/model:8b", "org/model"):
-        asyncio.run(
-            inference_route._maybe_auto_switch_model(tag, _Req(), "tester")
-        )
+        asyncio.run(inference_route._maybe_auto_switch_model(tag, _Req(), "tester"))
     assert loads == [], "a tag naming no quant swapped the serving model out"
 
 

From ce50721e94e25ca0b2a91d928ff2baddd7c60f93 Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Mon, 27 Jul 2026 07:50:17 +0000
Subject: [PATCH 51/56] Studio: probe before refusing busy, and scan once when
 the index is cold

The busy refusal fired before anything established the requested label was a
model at all, so any namespaced id a drop-in client sends was told to wait out
an unrelated download for as long as it ran. Probe first and refuse only a
label the Hub actually serves as GGUF; anything else falls through to the
resident model as before. A probe failure answers "not downloadable", since
stranding ordinary traffic costs more than missing a busy refusal.

Treating an unbuilt index as "nothing here" let the first request after startup
be answered by the resident model under another model's name. That was a
deliberate trade to keep the scan off the request path, and it was the wrong
one. Cold, the scan now runs once on a thread, bounded so a pathological
install falls through rather than hanging the request. Built, the request path
still never scans, so the latency fix stands.

The watcher freed the slot the moment it saw an error, while Retry-After is
thirty times the poll interval, so the client came back to an empty slot and
restarted the same failing download instead of being told. Hold the failure on
the slot until a retry surfaces it, and let another repo take it after three
retry intervals so a client that never returns cannot keep it.

The watcher also invalidated on completion, which now lands after
finalize_worker_exit's warm and marks that fresh scan stale, pushing a
synchronous rescan onto the retry. Removed.

_loaded_satisfies lowercased paths as well as aliases, so it returned satisfied
before the case-preserving compare below could run. Both now go through one
helper: paths compare with normcase, aliases stay case-insensitive.
---
 .../core/inference/local_model_resolver.py    |  10 ++
 .../core/inference/openai_auto_download.py    |  89 +++++++++++--
 studio/backend/routes/inference.py            |  60 +++++++--
 .../tests/test_openai_auto_download.py        | 120 +++++++++++++++++-
 .../backend/tests/test_openai_auto_switch.py  |  23 ++++
 5 files changed, 273 insertions(+), 29 deletions(-)

diff --git a/studio/backend/core/inference/local_model_resolver.py b/studio/backend/core/inference/local_model_resolver.py
index fdc639ff217..c4ac085ebeb 100644
--- a/studio/backend/core/inference/local_model_resolver.py
+++ b/studio/backend/core/inference/local_model_resolver.py
@@ -363,6 +363,16 @@ def _index() -> dict[str, _LocalGgufEntry]:
         return fresh
 
 
+def index_is_built() -> bool:
+    """Whether a scan has ever completed, freshness aside.
+
+    Lock-free on purpose: ``_lock`` is held for the whole scan, so taking it here
+    would park the request path on the very scan it is trying to stay off. Reading
+    ``_scan[0]`` is safe because ``_scan`` is only ever rebound, never mutated.
+    """
+    return bool(_scan[0])
+
+
 def warm_index_soon() -> None:
     """(Re)build the index off the request path when it is missing or past its TTL.
 
diff --git a/studio/backend/core/inference/openai_auto_download.py b/studio/backend/core/inference/openai_auto_download.py
index db00b624322..38de114954d 100644
--- a/studio/backend/core/inference/openai_auto_download.py
+++ b/studio/backend/core/inference/openai_auto_download.py
@@ -48,6 +48,9 @@
 # the worker is still alive and still owns the slot.
 _TIMED_OUT_POLL_S = 60.0
 _RETRY_AFTER_S = 30
+# Long enough for a client honouring Retry-After to come back and be told, short
+# enough that a client that never returns cannot hold the slot.
+_FAILED_HOLD_S = 3 * _RETRY_AFTER_S
 _MAX_LISTED_VARIANTS = 8
 
 
@@ -70,6 +73,11 @@ class _Active:
     expected_bytes: int = 0
     monitor_id: Optional[str] = None
     started_at: float = 0.0
+    # Set when the worker failed. The slot is kept until a retry surfaces it, since
+    # the advertised retry interval is far longer than the watcher's poll and the
+    # client would otherwise just restart the same failing download.
+    error: Optional[str] = None
+    failed_at: float = 0.0
 
 
 _lock = threading.Lock()
@@ -327,7 +335,6 @@ async def _watch(active: _Active, hf_token: Optional[str]) -> None:
     """Poll a dispatched job so the monitor row resolves and the resolver cache
     is dropped the moment the weights land."""
     from core.inference import api_monitor as monitor_module
-    from core.inference.local_model_resolver import invalidate_index
 
     api_monitor = monitor_module.api_monitor
     deadline = time.monotonic() + _MAX_WATCH_S
@@ -362,14 +369,20 @@ async def _watch(active: _Active, hf_token: Optional[str]) -> None:
                 api_monitor.finish(active.monitor_id, status = "cancelled")
                 return
             if state == "complete":
-                # Drop the resolver cache so the next retry sees the new model.
-                await asyncio.to_thread(invalidate_index)
+                # No invalidate here: finalize_worker_exit already dropped the cache and
+                # started the warm, and a second one would mark that fresh scan stale and
+                # push a synchronous rescan onto the client's retry.
                 api_monitor.finish(active.monitor_id, status = "completed")
             elif state == "idle":
                 # The job vanished without a terminal state (worker killed).
                 api_monitor.fail_open(active.monitor_id, "Download did not complete")
             else:
                 api_monitor.fail_open(active.monitor_id, error or f"Download {state}")
+                # Keep the slot so the next retry is told it failed rather than
+                # silently starting the same download again.
+                active.error = error or f"Download {state}"
+                active.failed_at = time.monotonic()
+                return
             return
     except asyncio.CancelledError:
         raise
@@ -377,7 +390,8 @@ async def _watch(active: _Active, hf_token: Optional[str]) -> None:
         logger.warning("auto-download: watcher failed for %r: %s", active.repo_id, exc)
         api_monitor.fail_open(active.monitor_id, "Download tracking failed")
     finally:
-        _release(active)
+        if not active.failed_at:
+            _release(active)
 
 
 def _downloading_refusal(label: str, percent: Optional[float]) -> AutoDownloadRefusal:
@@ -390,6 +404,37 @@ def _downloading_refusal(label: str, percent: Optional[float]) -> AutoDownloadRe
     )
 
 
+async def _is_downloadable_model(repo_id: str, hf_token: Optional[str]) -> bool:
+    """Whether the Hub has this repo with GGUF weights we could fetch.
+
+    Only asked while another download holds the slot, to tell a second download
+    apart from an ordinary foreign label. Any failure answers False: falling
+    through to the resident model is what such a label does anyway, and refusing
+    it would strand normal traffic for the length of the download.
+    """
+    if _is_not_servable(repo_id, hf_token):
+        return False
+
+    def _probe():
+        from huggingface_hub import HfApi
+
+        return HfApi(token = _hub_token(hf_token)).model_info(
+            repo_id, timeout = _MODEL_INFO_TIMEOUT_S
+        )
+
+    try:
+        info = await asyncio.to_thread(_probe)
+    except Exception:
+        return False
+    siblings = list(getattr(info, "siblings", None) or [])
+    servable = any(
+        str(getattr(s, "rfilename", "") or "").lower().endswith(".gguf") for s in siblings
+    )
+    if not servable:
+        _mark_not_servable(repo_id, hf_token)
+    return servable
+
+
 async def maybe_auto_download(
     requested_model: str,
     *,
@@ -414,25 +459,40 @@ async def maybe_auto_download(
         return None
 
     # Settle the single-flight slot before the network, so retries during a download stay cheap.
+    busy: Optional[_Active] = None
     with _lock:
         current = _active
+        if current is not None and current.failed_at:
+            # A held failure only owns the slot until someone is told about it.
+            if current.repo_id != repo_id and time.monotonic() - current.failed_at > _FAILED_HOLD_S:
+                _active = current = None
         if current is not None and current.repo_id == repo_id:
             adopted = current
         elif current is not None:
-            return AutoDownloadRefusal(
-                status = 503,
-                code = "model_download_busy",
-                message = (
-                    f"Already downloading '{_public_label(current.repo_id, current.variant)}'. "
-                    f"Retry '{requested_model}' once it finishes."
-                ),
-                retry_after = _RETRY_AFTER_S,
-            )
+            adopted = None
+            busy = current
         else:
             adopted = None
             provisional = _Active(repo_id = repo_id, started_at = time.time())
             _active = provisional
 
+    if busy is not None:
+        # Refusing before the probe blocks ordinary drop-in traffic: a namespaced label
+        # that is not a downloadable GGUF repo (LiteLLM/OpenRouter style) would be told
+        # to wait out a multi-hour download instead of falling through to the resident
+        # model. Only a label that could itself be downloaded is a second download.
+        if not await _is_downloadable_model(repo_id, hf_token):
+            return None
+        return AutoDownloadRefusal(
+            status = 503,
+            code = "model_download_busy",
+            message = (
+                f"Already downloading '{_public_label(busy.repo_id, busy.variant)}'. "
+                f"Retry '{requested_model}' once it finishes."
+            ),
+            retry_after = _RETRY_AFTER_S,
+        )
+
     if adopted is not None:
         if adopted.variant is None:
             # Still probing: no job yet, and a stale whole-repo error would free the probe's slot.
@@ -445,7 +505,8 @@ async def maybe_auto_download(
                     adopted.repo_id, adopted.variant, adopted.expected_bytes, hf_token
                 ),
             )
-        if state == "error":
+        if state == "error" or adopted.error:
+            error = error or adopted.error
             # Surface once, then free the slot so a retry can start over.
             _release(adopted)
             return AutoDownloadRefusal(
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index e335f44e731..65fc9229773 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3500,6 +3500,9 @@ def _llama_public_model_id(llama_backend, fallback: Optional[str] = None) -> Opt
 # only restore an idle-freed model, never run the resolver (so a downloaded GGUF
 # literally named "default" can't be swapped to). The NUL keeps it off any index.
 _RELOAD_ONLY_MODEL = "\x00reload-only"
+# One cold scan is worth paying to avoid answering a named model with another; a
+# pathological install must not hang the request behind it forever.
+_COLD_INDEX_WAIT_S = 10.0
 
 
 def _switch_model_for_payload(payload) -> str:
@@ -3775,19 +3778,18 @@ def _loaded_satisfies(requested: str) -> bool:
     from core.inference.openai_auto_download import looks_like_quant, split_model_ref
 
     base, variant = split_model_ref(requested)
-    base = base.lower()
     llama_backend = get_llama_cpp_backend()
     if getattr(llama_backend, "is_loaded", False):
-        keys = {
-            candidate.lower()
+        candidates = [
+            candidate
             for candidate in (
                 getattr(llama_backend, "model_identifier", None),
                 getattr(llama_backend, "_openai_advertised_id", None),
                 _llama_public_model_id(llama_backend),
             )
             if candidate
-        }
-        if base not in keys:
+        ]
+        if not _matches_any(base, candidates):
             return False
         if not looks_like_quant(variant):
             # An Ollama-style tag (":latest", ":8b") names no file, so the repo is enough.
@@ -3799,7 +3801,33 @@ def _loaded_satisfies(requested: str) -> bool:
     # Only llama.cpp carries a quant identity, so this backend can only match on the repo.
     if looks_like_quant(variant):
         return False
-    return base in {active.lower(), (public_model_id(active) or "").lower()}
+    return _matches_any(base, [active, public_model_id(active)])
+
+
+def _matches_any(requested: str, candidates) -> bool:
+    """Whether *requested* names any of *candidates*.
+
+    A repo alias is case-insensitive, a filesystem path is not: lowercasing both
+    made /srv/models/foo.gguf and /srv/models/Foo.gguf the same weights, which is
+    the same trap _norm_path exists for one comparison further down.
+    """
+    lowered = requested.strip().lower()
+    for candidate in candidates:
+        if not candidate:
+            continue
+        if _looks_like_local_path(requested) or _looks_like_local_path(candidate):
+            if _norm_path(requested) == _norm_path(candidate):
+                return True
+            continue
+        if lowered == str(candidate).strip().lower():
+            return True
+    return False
+
+
+def _looks_like_local_path(value: str) -> bool:
+    """A filesystem path rather than a repo id, so case matters."""
+    text = str(value)
+    return text.startswith("/") or text.startswith("~") or ":\\" in text or "\\" in text
 
 
 def _norm_path(value: str) -> str:
@@ -3877,6 +3905,7 @@ async def _reject_unservable_model(
     base, variant = split_model_ref(requested_model)
     quantified = looks_like_quant(variant)
     from core.inference.local_model_resolver import (
+        index_is_built,
         recently_downloaded,
         resolve_local_gguf,
         warm_index_soon,
@@ -3893,8 +3922,22 @@ async def _reject_unservable_model(
             return
         # Refresh in the background and read the index as-is: scanning here would stall the
         # request, and a cold index only costs evidence (the gate below fails safe without it).
-        warm_index_soon()
-        resolved = resolve_local_gguf(requested_model, allow_scan = False)
+        if index_is_built():
+            warm_index_soon()
+            resolved = resolve_local_gguf(requested_model, allow_scan = False)
+        else:
+            # Before the first scan there is nothing cached to reason from, and falling
+            # through would answer a named model with the resident one. Pay the scan
+            # once, off the loop and bounded, rather than reading "not scanned yet" as
+            # "not here". Later requests take the cached branch above.
+            try:
+                resolved = await asyncio.wait_for(
+                    asyncio.to_thread(resolve_local_gguf, requested_model),
+                    _COLD_INDEX_WAIT_S,
+                )
+            except (TimeoutError, asyncio.TimeoutError):
+                warm_index_soon()
+                resolved = None
         # A manual load stores the on-disk path the resolver advertises under an alias, so
         # match on the path too.
         # Quants of one repo share a directory, so the path alone cannot tell them
@@ -10979,6 +11022,7 @@ def _quant_reference_resolves(model_id: Optional[str], quant: str) -> bool:
     the moment another model loads.
     """
     from core.inference.local_model_resolver import (
+        index_is_built,
         recently_downloaded,
         resolve_local_gguf,
         warm_index_soon,
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index ed7669da9b7..dca25735734 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -1164,14 +1164,21 @@ def test_the_request_path_never_triggers_a_model_index_rescan(monkeypatch):
     assert warmed == [1, 1, 1]
 
 
-def test_a_cold_index_still_refuses_an_explicit_quant_and_warms_in_the_background(monkeypatch):
-    # A cold index has no evidence of what is on disk, but an explicit quant is evidence on
-    # its own; a bare name proves nothing. Either way the warm happens off this request.
+def test_a_cold_index_is_scanned_rather_than_read_as_nothing_here(monkeypatch):
+    # Before the first scan there is no cached evidence, and treating that as "not
+    # downloaded" answers a named local model with the resident one. The scan is paid
+    # once, off the loop; every later request reads the built index instead.
     from core.inference import local_model_resolver as resolver
 
-    warmed = []
+    entry = resolver._LocalGgufEntry("org/other", "/srv/models/org--other", ("Q4_K_M",))
+    scans = []
+
+    def _build():
+        scans.append(1)
+        return {"org/other": entry}
+
     monkeypatch.setattr(resolver, "_scan", (0.0, {}))
-    monkeypatch.setattr(resolver, "warm_index_soon", lambda: warmed.append(1))
+    monkeypatch.setattr(resolver, "_build_index", _build)
     loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
     monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
     monkeypatch.setattr(
@@ -1180,11 +1187,46 @@ def test_a_cold_index_still_refuses_an_explicit_quant_and_warms_in_the_backgroun
         lambda: type("B", (), {"active_model_name": None})(),
     )
     monkeypatch.setattr(inference_route, "_unavailable_model_message", _fake_unavailable_message)
+    monkeypatch.setattr(
+        "utils.openai_auto_switch_settings.get_openai_auto_switch_enabled", lambda: False
+    )
+
+    # The bug: a bare name that IS on disk used to fall through to the resident model.
     with pytest.raises(HTTPException) as excinfo:
-        asyncio.run(inference_route._reject_unservable_model("unsloth/A-GGUF:Q8_0", _Req()))
+        asyncio.run(inference_route._reject_unservable_model("org/other", _Req()))
     assert excinfo.value.status_code == 404
+    assert scans == [1], "the cold index was not scanned"
+
+    # Built now, so the request path reads the cache and never scans again.
     assert asyncio.run(inference_route._reject_unservable_model("gpt-4", _Req())) is None
-    assert warmed == [1, 1]
+    assert scans == [1]
+
+
+def test_a_cold_scan_that_never_finishes_does_not_hang_the_request(monkeypatch):
+    # Correctness is worth one scan, not an unbounded wait: a pathological install
+    # falls through on the timeout rather than holding the request open.
+    import threading
+
+    from core.inference import local_model_resolver as resolver
+
+    monkeypatch.setattr(resolver, "_scan", (0.0, {}))
+    monkeypatch.setattr(inference_route, "_COLD_INDEX_WAIT_S", 0.05)
+    released = threading.Event()
+    monkeypatch.setattr(resolver, "_build_index", lambda: (released.wait(5), {})[1])
+    warmed = []
+    monkeypatch.setattr(resolver, "warm_index_soon", lambda: warmed.append(1))
+    loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
+    monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+    monkeypatch.setattr(
+        inference_route,
+        "get_inference_backend",
+        lambda: type("B", (), {"active_model_name": None})(),
+    )
+    try:
+        assert asyncio.run(inference_route._reject_unservable_model("gpt-4", _Req())) is None
+        assert warmed == [1]
+    finally:
+        released.set()
 
 
 def test_warming_the_index_never_waits_on_the_scan_lock(monkeypatch):
@@ -1561,3 +1603,67 @@ def _probe(model_name, hf_token = None):
     auto_dl.reset_for_tests()
     _run("unsloth/x-GGUF:UD-Q5_K_XL", hf_token = "hf_caller")
     assert seen == ["hf_caller"], "the caller's own token must still be used"
+
+
+def test_a_foreign_label_is_not_told_to_wait_for_someone_elses_download(hub):
+    # The busy refusal fired before the probe, so any namespaced label a drop-in
+    # client sends (LiteLLM/OpenRouter style) was told to wait out a download that
+    # has nothing to do with it, for as long as that download runs.
+    assert _run("unsloth/first-GGUF").code == "model_downloading"
+
+    hub["info"] = _Info([_Sibling("README.md", 1024)])  # real repo, no GGUF
+    assert _run("anthropic/claude-3.5-sonnet") is None, "a foreign label was refused as busy"
+
+    # A label that really is another downloadable model still gets the busy refusal.
+    hub["info"] = _gguf_repo_info()
+    refusal = _run("unsloth/second-GGUF")
+    assert refusal.status == 503 and refusal.code == "model_download_busy"
+
+
+def test_a_failed_download_keeps_the_slot_until_someone_is_told(monkeypatch):
+    # The watcher freed the slot the moment it saw the error, but Retry-After is 30s
+    # and the poll is 2s, so the client came back to an empty slot and started the
+    # identical failing download again instead of being told it had failed.
+    monkeypatch.setattr(auto_dl, "_MAX_WATCH_S", 60.0)
+    monkeypatch.setattr(auto_dl, "_WATCH_POLL_S", 0.001)
+
+    async def _errored(repo, variant):
+        return "error", "disk exploded"
+
+    monkeypatch.setattr(auto_dl, "_job_state", _errored)
+    active = auto_dl._Active(repo_id = "org/x-GGUF", variant = "Q4_K_M")
+    auto_dl._active = active
+    asyncio.run(auto_dl._watch(active, None))
+    assert auto_dl._active is active, "the slot was freed before anyone was told"
+    assert active.error == "disk exploded"
+
+
+def test_the_retry_after_a_failure_is_told_instead_of_restarting_it(hub, monkeypatch):
+    # End of the same chain: the held failure has to reach the caller.
+    active = auto_dl._Active(
+        repo_id = "unsloth/x-GGUF",
+        variant = "UD-Q5_K_XL",
+        error = "disk exploded",
+        failed_at = 1.0,
+    )
+    auto_dl._active = active
+
+    async def _idle(repo, variant):
+        return "idle", None
+
+    monkeypatch.setattr(auto_dl, "_job_state", _idle)
+    refusal = _run("unsloth/x-GGUF:UD-Q5_K_XL")
+    assert refusal.status == 502 and "disk exploded" in refusal.message
+    assert hub["started"] == [], "the retry restarted the failing download"
+    # Told once, so the slot is free again for a fresh attempt.
+    assert auto_dl._active is None
+
+
+def test_a_completed_download_does_not_restage_the_scan_it_just_warmed(monkeypatch):
+    # finalize_worker_exit invalidates and warms. A second invalidation here marks
+    # that fresh scan stale and pushes a synchronous rescan onto the client's retry.
+    import inspect
+
+    src = inspect.getsource(auto_dl._watch)
+    complete_branch = src[src.index('if state == "complete"') :]
+    assert "invalidate_index" not in complete_branch
diff --git a/studio/backend/tests/test_openai_auto_switch.py b/studio/backend/tests/test_openai_auto_switch.py
index a53e42b04c8..aa08f9fe1aa 100644
--- a/studio/backend/tests/test_openai_auto_switch.py
+++ b/studio/backend/tests/test_openai_auto_switch.py
@@ -4355,3 +4355,26 @@ def set_job(self, key, state):
     )
     assert not resolver.recently_downloaded("org/corpus")
     assert resolver._scan == (stamp, {"kept": "entry"}), "a dataset invalidated the index"
+
+
+def test_two_local_paths_differing_only_in_case_are_not_the_same_model(monkeypatch):
+    # _loaded_satisfies lowercased the request and every backend identifier, so on a
+    # case-sensitive filesystem /srv/models/foo.gguf counted as satisfied by a
+    # resident /srv/models/Foo.gguf and returned before the case-preserving compare
+    # further down ever ran. A repo alias must stay case-insensitive.
+    import os
+
+    loaded = _FakeBackend(loaded_id = "/srv/models/Foo.gguf")
+    monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+    monkeypatch.setattr(
+        inference_route,
+        "get_inference_backend",
+        lambda: type("B", (), {"active_model_name": None})(),
+    )
+    assert inference_route._loaded_satisfies("/srv/models/Foo.gguf") is True
+    same = os.path.normcase("A") == os.path.normcase("a")
+    assert inference_route._loaded_satisfies("/srv/models/foo.gguf") is same
+
+    alias = _FakeBackend(loaded_id = "unsloth/Qwen3-4B-GGUF")
+    monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: alias)
+    assert inference_route._loaded_satisfies("unsloth/qwen3-4b-gguf") is True

From e32b486170e01cc45812f288f396527055ed6b16 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 27 Jul 2026 07:51:10 +0000
Subject: [PATCH 52/56] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 studio/backend/core/inference/openai_auto_download.py | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/studio/backend/core/inference/openai_auto_download.py b/studio/backend/core/inference/openai_auto_download.py
index 38de114954d..1efe039c38a 100644
--- a/studio/backend/core/inference/openai_auto_download.py
+++ b/studio/backend/core/inference/openai_auto_download.py
@@ -417,10 +417,7 @@ async def _is_downloadable_model(repo_id: str, hf_token: Optional[str]) -> bool:
 
     def _probe():
         from huggingface_hub import HfApi
-
-        return HfApi(token = _hub_token(hf_token)).model_info(
-            repo_id, timeout = _MODEL_INFO_TIMEOUT_S
-        )
+        return HfApi(token = _hub_token(hf_token)).model_info(repo_id, timeout = _MODEL_INFO_TIMEOUT_S)
 
     try:
         info = await asyncio.to_thread(_probe)

From a52f0285a39439f1a234484adc5cc07a60a9ae1b Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Mon, 27 Jul 2026 08:41:02 +0000
Subject: [PATCH 53/56] Studio: an unfinished scan is not absence, and a
 decided refusal is not a failure

Bounding the cold scan then reading the bound as "not here" left the same hole
one branch over. A timeout now answers 503 model_indexing with a Retry-After
and leaves the warm running. A foreign label sent inside that window is asked
to retry rather than falling through, which is a real cost, but the window is
one request on an install whose scan exceeds ten seconds and it clears itself,
where answering with the wrong weights does not.

That uncovered a worse one. Every check here runs inside a broad except whose
job is "could not verify, so fall through", so an HTTPException raised in the
block was logged as a verification failure and the request was answered by the
resident model. Any refusal decided in there was being swallowed. Re-raise it
ahead of that handler.

Canonicalizing generic labels made them real variant keys, but the matcher
still decided on shape, so repo:llama-13b fell past an exact match and fetched
llama-7b. Match exactly first, whatever the shape; a quant-shaped suffix that
matches nothing is still a miss and never a swap.

Marking a catalog alias loaded while publishing the preferred on-disk quant
claimed alias:Q4 was loaded while Q8 was serving, and requiring the resident
quant to match then made pinning it a 404. Advertise the resident variant when
the entry resolves to the resident model.
---
 .../core/inference/openai_auto_download.py    | 10 +++-
 studio/backend/routes/inference.py            | 37 +++++++++++-
 .../tests/test_openai_auto_download.py        | 56 +++++++++++++++++--
 studio/backend/tests/test_openai_catalog.py   | 21 +++++++
 4 files changed, 116 insertions(+), 8 deletions(-)

diff --git a/studio/backend/core/inference/openai_auto_download.py b/studio/backend/core/inference/openai_auto_download.py
index 1efe039c38a..c259a744c61 100644
--- a/studio/backend/core/inference/openai_auto_download.py
+++ b/studio/backend/core/inference/openai_auto_download.py
@@ -700,9 +700,15 @@ def _match_variant(wanted: Optional[str], variants: dict[str, int]) -> Optional[
     same preference order as a manual load, matching what the local resolver does
     with the same tag.
     """
-    if wanted and looks_like_quant(wanted):
+    if wanted:
+        # Exact first, whatever shape it is: a repo of generically named GGUFs has
+        # real variants like "llama-13b" that are valid worker keys but do not look
+        # like quants, and defaulting past one would fetch a model nobody asked for.
         lowered = {name.lower(): name for name in variants}
-        return lowered.get(wanted.strip().lower())
+        exact = lowered.get(wanted.strip().lower())
+        if exact is not None or looks_like_quant(wanted):
+            # A quant-shaped suffix that matches nothing is a miss, never a swap.
+            return exact
     return preferred_quant(variants)
 
 
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 65fc9229773..d8765177f6b 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3804,6 +3804,24 @@ def _loaded_satisfies(requested: str) -> bool:
     return _matches_any(base, [active, public_model_id(active)])
 
 
+def _raise_still_indexing(requested_model: str, fastapi_request) -> None:
+    """Refuse a name we cannot yet place, rather than answer it with another model."""
+    path = getattr(getattr(fastapi_request, "url", None), "path", None)
+    message = (
+        f"This server is still indexing its local models, so it cannot confirm "
+        f"'{requested_model}' yet. Retry shortly."
+    )
+    raise HTTPException(
+        status_code = 503,
+        detail = (
+            error_body_for_path(path, message, status = 503, code = "model_indexing")
+            if isinstance(path, str)
+            else message
+        ),
+        headers = {"Retry-After": "5"},
+    )
+
+
 def _matches_any(requested: str, candidates) -> bool:
     """Whether *requested* names any of *candidates*.
 
@@ -3912,6 +3930,7 @@ async def _reject_unservable_model(
     )
     from utils.openai_auto_switch_settings import get_openai_auto_switch_enabled
 
+    still_indexing = False
     try:
         if _loaded_satisfies(requested_model):
             return
@@ -3936,7 +3955,11 @@ async def _reject_unservable_model(
                     _COLD_INDEX_WAIT_S,
                 )
             except (TimeoutError, asyncio.TimeoutError):
+                # Still scanning, so nothing is known about this name. Falling through
+                # would put the resident model behind it, which is the failure this
+                # whole hook exists to stop, so say "not yet" instead of guessing.
                 warm_index_soon()
+                still_indexing = True
                 resolved = None
         # A manual load stores the on-disk path the resolver advertises under an alias, so
         # match on the path too.
@@ -3967,12 +3990,18 @@ async def _reject_unservable_model(
             or (variant is not None and resolve_local_gguf(base, allow_scan = False) is not None)
         )
         switchable = downloaded and get_openai_auto_switch_enabled()
+    except HTTPException:
+        # A refusal decided above is the answer, not a failure to decide. Without this
+        # the handler below would log it and fall through to the resident model.
+        raise
     except Exception as exc:
         # Can't verify: an explicit quant still proves intent, so refuse; let anything else by.
         logger.debug("unservable-model check failed for %r: %s", requested_model, exc)
         if not quantified:
             return
         downloaded = here = switchable = False
+    if still_indexing:
+        _raise_still_indexing(requested_model, fastapi_request)
     if not (quantified or here):
         return
     if switchable:
@@ -11141,7 +11170,13 @@ async def _openai_catalog_objects() -> list[dict]:
             "loaded": _resolves_to_resident(getattr(info, "path", None)),
         }
         # The id stays bare for OpenAI compat; a client appends ":<quant>" to pin one.
-        if quants:
+        # For the resident model that has to be the quant actually loaded, not the
+        # preferred one on disk, or the listing advertises alias:Q4 as loaded while
+        # Q8 is serving and pinning it 404s.
+        resident_quant = getattr(get_llama_cpp_backend(), "hf_variant", None)
+        if obj["loaded"] and resident_quant:
+            obj["quant"] = resident_quant
+        elif quants:
             obj["quant"] = quants[0]
         display = getattr(info, "display_name", None)
         if display:
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index dca25735734..835c021b86b 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -1202,9 +1202,10 @@ def _build():
     assert scans == [1]
 
 
-def test_a_cold_scan_that_never_finishes_does_not_hang_the_request(monkeypatch):
-    # Correctness is worth one scan, not an unbounded wait: a pathological install
-    # falls through on the timeout rather than holding the request open.
+def test_a_cold_scan_that_never_finishes_says_so_instead_of_guessing(monkeypatch):
+    # The scan is bounded so a pathological install cannot hold the request open, but
+    # an unfinished scan knows nothing about the name, and falling through would put
+    # the resident model behind it. Answer "not yet", with a Retry-After.
     import threading
 
     from core.inference import local_model_resolver as resolver
@@ -1223,12 +1224,40 @@ def test_a_cold_scan_that_never_finishes_does_not_hang_the_request(monkeypatch):
         lambda: type("B", (), {"active_model_name": None})(),
     )
     try:
-        assert asyncio.run(inference_route._reject_unservable_model("gpt-4", _Req())) is None
-        assert warmed == [1]
+        with pytest.raises(HTTPException) as excinfo:
+            asyncio.run(inference_route._reject_unservable_model("gpt-4", _Req()))
+        assert excinfo.value.status_code == 503
+        assert excinfo.value.headers.get("Retry-After")
+        assert warmed == [1], "the scan was not left to finish in the background"
     finally:
         released.set()
 
 
+def test_a_refusal_is_never_swallowed_by_the_cannot_verify_handler(monkeypatch):
+    # The checks run inside a broad `except Exception` that turns a failure to decide
+    # into a fallthrough. An HTTPException raised in there is a decision, and was
+    # being logged as a failure and answered by the resident model instead.
+    loaded = _Loaded("unsloth/A-GGUF", "UD-Q4_K_XL")
+    monkeypatch.setattr(inference_route, "get_llama_cpp_backend", lambda: loaded)
+    monkeypatch.setattr(
+        inference_route,
+        "get_inference_backend",
+        lambda: type("B", (), {"active_model_name": None})(),
+    )
+
+    def _boom(*_a, **_k):
+        raise HTTPException(status_code = 418, detail = "decided")
+
+    monkeypatch.setattr(inference_route, "_resolves_to_resident", _boom)
+    monkeypatch.setattr(
+        "core.inference.local_model_resolver.resolve_local_gguf",
+        lambda *_a, **_k: ("/srv/models/x", "Q4_K_M", "x"),
+    )
+    with pytest.raises(HTTPException) as excinfo:
+        asyncio.run(inference_route._reject_unservable_model("org/x", _Req()))
+    assert excinfo.value.status_code == 418
+
+
 def test_warming_the_index_never_waits_on_the_scan_lock(monkeypatch):
     # _lock is held for the whole scan, so contending for it would park every later request.
     import threading
@@ -1667,3 +1696,20 @@ def test_a_completed_download_does_not_restage_the_scan_it_just_warmed(monkeypat
     src = inspect.getsource(auto_dl._watch)
     complete_branch = src[src.index('if state == "complete"') :]
     assert "invalidate_index" not in complete_branch
+
+
+def test_an_exact_generic_variant_beats_the_default_pick(hub):
+    # Canonicalizing generic labels made them real worker keys, but the matcher still
+    # read anything non-quant-shaped as a tag, so repo:llama-13b default-selected and
+    # fetched llama-7b instead of the model that was actually asked for.
+    gb = 1024**3
+    hub["info"] = _Info([_Sibling("llama-7b.gguf", 4 * gb), _Sibling("llama-13b.gguf", 8 * gb)])
+    assert _run("unsloth/generic-GGUF:llama-13b").code == "model_downloading"
+    assert hub["started"][0][1] == "llama-13b"
+
+    # A quant-shaped suffix that matches nothing is still a miss, never a swap.
+    auto_dl.reset_for_tests()
+    hub["started"].clear()
+    hub["info"] = _gguf_repo_info()
+    assert _run("unsloth/x-GGUF:Q2_K").status == 404
+    assert hub["started"] == []
diff --git a/studio/backend/tests/test_openai_catalog.py b/studio/backend/tests/test_openai_catalog.py
index 6c68ddec400..5a253fe8411 100644
--- a/studio/backend/tests/test_openai_catalog.py
+++ b/studio/backend/tests/test_openai_catalog.py
@@ -276,6 +276,27 @@ def test_a_standalone_gguf_does_not_advertise_a_quant_that_stops_resolving(monke
     assert "quant" not in inf._openai_model_objects()[0]
 
 
+def test_a_loaded_alias_advertises_the_quant_that_is_actually_loaded(monkeypatch):
+    # Marking the alias loaded while still publishing the preferred on-disk quant said
+    # alias:Q4 was loaded while Q8 was serving, and pinning that 404s with switching off.
+    monkeypatch.setattr(inf, "get_inference_backend", lambda: _FakeUnsloth())
+    llama = _FakeLlama()
+    llama.hf_variant = "Q8_0"
+    monkeypatch.setattr(inf, "get_llama_cpp_backend", lambda: llama)
+
+    alias = _Info("/srv/models", "Qwen3", model_id = "publisher/Qwen3")
+    alias.path = "/srv/models"  # holds the resident /srv/models/Qwen3-Q4.gguf
+
+    async def _fake_catalog():
+        return [alias]
+
+    monkeypatch.setattr(inf, "_cached_local_catalog", _fake_catalog)
+    monkeypatch.setattr(resolver, "local_gguf_quants", lambda info: ("Q4_K_M", "Q8_0"))
+    ids = {m["id"]: m for m in asyncio.run(inf._openai_catalog_objects())}
+    assert ids["publisher/Qwen3"]["loaded"] is True
+    assert ids["publisher/Qwen3"]["quant"] == "Q8_0"
+
+
 def test_an_alias_for_the_resident_weights_is_not_listed_as_unloaded(monkeypatch):
     # A GGUF loaded by absolute path keys the resident entry by basename, so an id-only dedup
     # would emit the alias again marked not loaded.

From 091806d109c1db93f09d272ebe43df55e8a06fa9 Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Mon, 27 Jul 2026 08:56:10 +0000
Subject: [PATCH 54/56] Studio: keep the asyncio.timeout fallback tests
 runnable on Python 3.10

Both tests deleted asyncio.timeout to force _wall_clock_timeout down its
pre-3.11 branch, but monkeypatch.delattr raises when the attribute is already
absent. On Python 3.10, the one version the fallback exists for, there is
nothing to delete, so the two tests errored with AttributeError before reaching
the code they cover. Passing raising=False makes the deletion a no-op there and
leaves the assertions running against the same branch on every version.

Every other delattr in the repo already passes raising=False for exactly this
reason. Verified with asyncio.timeout removed from the interpreter: the two
tests fail with the CI AttributeError before this change and pass after, and
the file still runs 89 passed on 3.13 where the deletion is real.
---
 studio/backend/tests/test_research_runs_hardening.py | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/studio/backend/tests/test_research_runs_hardening.py b/studio/backend/tests/test_research_runs_hardening.py
index e49a12ab40b..04d9020a5e1 100644
--- a/studio/backend/tests/test_research_runs_hardening.py
+++ b/studio/backend/tests/test_research_runs_hardening.py
@@ -861,7 +861,8 @@ async def run():
 
 
 def test_wall_clock_timeout_supports_python_without_asyncio_timeout(monkeypatch):
-    monkeypatch.delattr(research_runs.asyncio, "timeout")
+    # 3.10 has no asyncio.timeout to delete, and it is the version the fallback is for.
+    monkeypatch.delattr(research_runs.asyncio, "timeout", raising = False)
 
     async def run():
         async with research_runs._wall_clock_timeout(0.01):
@@ -872,7 +873,7 @@ async def run():
 
 
 def test_wall_clock_timeout_does_not_swallow_shutdown_cancellation(monkeypatch):
-    monkeypatch.delattr(research_runs.asyncio, "timeout")
+    monkeypatch.delattr(research_runs.asyncio, "timeout", raising = False)
 
     async def run(cleanup_started: asyncio.Event):
         async with research_runs._wall_clock_timeout(0.01):

From c24ed1200a9a6c479716baafd8d17fe622b60a6c Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Mon, 27 Jul 2026 09:37:40 +0000
Subject: [PATCH 55/56] Studio: decide GGUF residency, servability and variant
 keys by one rule each

Four admission and catalog fixes, each closing a gap between two places that
were answering the same question differently.

The /v1/models catalog asked _resolves_to_resident without llama_only, so a
Transformers model live from a directory that also holds GGUF exports marked a
GGUF alias loaded and gave it a GGUF quant. The usage examples then pinned
alias:quant that nothing could serve with switching off. Every entry in that
loop is advertised as GGUF, so residency there is llama.cpp residency.

The busy probe accepted any .gguf sibling while admission excludes mmproj, MTP
drafters and big-endian builds. A repo holding only companions is not
downloadable, so it was held at model_download_busy for the length of an
unrelated download instead of falling through to the resident model as it does
when no download is running. It now reuses _gguf_variants, the same filter.

split_model_ref refused any slash-bearing suffix, but an unrecognized GGUF below
a subdirectory keys on its path (build/llama-13b), which is_valid_gguf_variant
allows and the catalog advertises. Pinning such a variant could not parse, so
only the default-ranked one was reachable. A slash-bearing suffix is now a
variant exactly when a real Hub repo precedes it, which still leaves
C:/models/x.gguf a path rather than a quant.

The usage examples treated a downloaded-but-unloaded model as runnable only
under auto-switch, but a standalone UNSLOTH_MODEL_IDLE_TTL reloads exactly what
it freed on the next request. The panel hid runnable examples after an idle
unload. Tracked apart from auto-switch, because the stash restores the stored
checkpoint only and never an arbitrary catalog entry.

Also stub the index walk in the three cold-index tests that missed it: a real
multi-root scan inside the cold-wait budget made them time out into a 503 under
load rather than assert what they are there for. One of them flaked locally.

Verified each fix is load-bearing by reverting it and watching its test fail.
Backend CI command: 10195 passed, 0 failed. tsc -b and the frontend build clean.
---
 .../core/inference/openai_auto_download.py    | 24 +++++++++++------
 studio/backend/routes/inference.py            |  7 +++--
 .../tests/test_openai_auto_download.py        | 26 +++++++++++++++++++
 studio/backend/tests/test_openai_catalog.py   | 25 ++++++++++++++++++
 .../settings/components/usage-examples.tsx    | 16 ++++++++----
 ...st_usage_examples_model_source_contract.py | 18 +++++++++++--
 6 files changed, 99 insertions(+), 17 deletions(-)

diff --git a/studio/backend/core/inference/openai_auto_download.py b/studio/backend/core/inference/openai_auto_download.py
index c259a744c61..8595489253c 100644
--- a/studio/backend/core/inference/openai_auto_download.py
+++ b/studio/backend/core/inference/openai_auto_download.py
@@ -97,14 +97,21 @@ def _public_label(repo_id: str, variant: Optional[str]) -> str:
 def split_model_ref(requested: str) -> tuple[str, Optional[str]]:
     """``org/repo:QUANT`` -> ``("org/repo", "QUANT")``; no suffix -> variant None.
 
-    Splits on the last colon only when the suffix carries no slash, so a Windows
-    drive letter or a path never reads as a quant.
+    Splits on the last colon. A slash-bearing suffix is only a variant when a real
+    Hub repo precedes it: an unrecognized GGUF below a subdirectory keys on its path
+    ("build/llama-13b", which is_valid_gguf_variant allows and the catalog advertises),
+    while "C:/models/x.gguf" leaves a drive letter that is no repo id at all.
     """
     text = (requested or "").strip()
     base, sep, suffix = text.rpartition(":")
-    if not sep or not base or "/" in suffix or not suffix:
+    if not sep or not base or not suffix:
         return text, None
-    return base.strip(), suffix.strip()
+    stripped = base.strip()
+    if "/" in suffix:
+        from hub.utils.paths import is_valid_repo_id
+        if "/" not in stripped or not is_valid_repo_id(stripped):
+            return text, None
+    return stripped, suffix.strip()
 
 
 def is_downloadable_ref(requested: str) -> bool:
@@ -423,10 +430,11 @@ def _probe():
         info = await asyncio.to_thread(_probe)
     except Exception:
         return False
-    siblings = list(getattr(info, "siblings", None) or [])
-    servable = any(
-        str(getattr(s, "rfilename", "") or "").lower().endswith(".gguf") for s in siblings
-    )
+    # The same filter admission uses, not a bare .gguf test: mmproj, MTP drafters and
+    # big-endian builds are companions rather than quants, so a repo holding only those
+    # is not downloadable here either. Answering otherwise would hold an ordinary
+    # foreign label at model_download_busy for the length of an unrelated download.
+    servable = bool(_gguf_variants(getattr(info, "siblings", None)))
     if not servable:
         _mark_not_servable(repo_id, hf_token)
     return servable
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index d8765177f6b..85b38931c05 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -11166,8 +11166,11 @@ async def _openai_catalog_objects() -> list[dict]:
             "created": _created,
             "owned_by": _OWNED_BY,
             # A manual load keys the resident entry by path basename while the catalog uses
-            # the alias, so match on the path or the alias reads as not loaded.
-            "loaded": _resolves_to_resident(getattr(info, "path", None)),
+            # the alias, so match on the path or the alias reads as not loaded. llama-only:
+            # these entries are advertised as GGUF with a GGUF quant, so a Transformers
+            # model live from a directory that also holds GGUF exports must not mark one
+            # loaded, or the examples pin a quant nothing can serve with switching off.
+            "loaded": _resolves_to_resident(getattr(info, "path", None), llama_only = True),
         }
         # The id stays bare for OpenAI compat; a client appends ":<quant>" to pin one.
         # For the resident model that has to be the quant actually loaded, not the
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index 835c021b86b..cd0c5d4c46a 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -209,6 +209,12 @@ def _run(model, hf_token = None):
         # A colon followed by a path segment is not a quant.
         ("C:/models/x.gguf", ("C:/models/x.gguf", None)),
         ("org/repo:", ("org/repo:", None)),
+        # An unrecognized GGUF below a subdirectory keys on its path, and that key is
+        # what the catalog advertises, so pinning it has to parse.
+        ("org/repo:build/llama-13b", ("org/repo", "build/llama-13b")),
+        # Still a path, not a variant: no Hub repo precedes the colon.
+        ("/home/me/models/x:build/llama-13b", ("/home/me/models/x:build/llama-13b", None)),
+        ("D:/models/repo:build/llama-13b", ("D:/models/repo:build/llama-13b", None)),
     ],
 )
 def test_split_model_ref(raw, expected):
@@ -546,6 +552,20 @@ async def _unknown(repo, variant):
     assert _run("unsloth/other-GGUF").code == "model_download_busy"
 
 
+def test_a_companion_only_repo_is_not_held_at_busy(hub):
+    # mmproj and MTP files are companions, not quants, so admission classifies such a
+    # repo as non-servable and lets the label fall through to the resident model. The
+    # busy probe accepted any .gguf, which stranded that ordinary traffic behind an
+    # unrelated multi-hour download.
+    assert _run("unsloth/x-GGUF:UD-Q4_K_XL").code == "model_downloading"
+    gb = 1024**3
+    hub["info"] = _Info([_Sibling("mmproj-F16.gguf", gb), _Sibling("mtp-model.gguf", gb)])
+    assert _run("unsloth/companions-GGUF") is None
+    # A repo that does hold a real quant is still a second download.
+    hub["info"] = _gguf_repo_info()
+    assert _run("unsloth/other-GGUF").code == "model_download_busy"
+
+
 def test_a_stale_watcher_cannot_release_a_newer_download(hub, monkeypatch):
     # Variant A is downloading; its watcher holds the slot.
     assert _run("unsloth/x-GGUF:UD-Q4_K_XL").code == "model_downloading"
@@ -1307,6 +1327,9 @@ def test_an_id_v1_models_advertised_is_refused_before_the_resolver_warms(monkeyp
     from core.inference import local_model_resolver as resolver
 
     monkeypatch.setattr(resolver, "_scan", (0.0, {}))
+    # Stub the walk: a real multi-root scan inside the cold-wait budget makes this
+    # test time out into a 503 under load instead of asserting what it is here for.
+    monkeypatch.setattr(resolver, "_build_index", lambda: {})
     monkeypatch.setattr(
         inference_route,
         "_CATALOG_CACHE",
@@ -1334,6 +1357,9 @@ def test_an_advertised_alias_for_the_resident_weights_is_still_served(monkeypatc
     from core.inference import local_model_resolver as resolver
 
     monkeypatch.setattr(resolver, "_scan", (0.0, {}))
+    # Stub the walk: a real multi-root scan inside the cold-wait budget makes this
+    # test time out into a 503 under load instead of asserting what it is here for.
+    monkeypatch.setattr(resolver, "_build_index", lambda: {})
     monkeypatch.setattr(
         inference_route,
         "_CATALOG_CACHE",
diff --git a/studio/backend/tests/test_openai_catalog.py b/studio/backend/tests/test_openai_catalog.py
index 5a253fe8411..6292ab0ca05 100644
--- a/studio/backend/tests/test_openai_catalog.py
+++ b/studio/backend/tests/test_openai_catalog.py
@@ -272,6 +272,9 @@ def test_a_standalone_gguf_does_not_advertise_a_quant_that_stops_resolving(monke
     # A cold index cannot prove the reference either, and publishing on no proof is
     # exactly what hands out the pin that later fails to resolve.
     monkeypatch.setattr(resolver, "_scan", (0.0, {}))
+    # Stub the walk: a real multi-root scan inside the cold-wait budget makes this
+    # test time out into a 503 under load instead of asserting what it is here for.
+    monkeypatch.setattr(resolver, "_build_index", lambda: {})
     monkeypatch.setattr(resolver, "warm_index_soon", lambda: None)
     assert "quant" not in inf._openai_model_objects()[0]
 
@@ -297,6 +300,28 @@ async def _fake_catalog():
     assert ids["publisher/Qwen3"]["quant"] == "Q8_0"
 
 
+def test_a_transformers_model_does_not_mark_a_gguf_alias_loaded(monkeypatch):
+    # Every entry in this loop is advertised as GGUF and carries a GGUF quant. A
+    # Transformers model live from a directory that also holds GGUF exports is not one
+    # of them, and marking the alias loaded had the usage examples pin alias:quant that
+    # nothing can serve while switching is off.
+    unsloth = _FakeUnsloth()
+    unsloth.active_model_name = "/srv/models"
+    monkeypatch.setattr(inf, "get_inference_backend", lambda: unsloth)
+    monkeypatch.setattr(inf, "get_llama_cpp_backend", lambda: _FakeLlama(loaded = False))
+
+    alias = _Info("/srv/models", "Qwen3", model_id = "publisher/Qwen3")
+    alias.path = "/srv/models"  # also holds /srv/models/Qwen3-Q4.gguf
+
+    async def _fake_catalog():
+        return [alias]
+
+    monkeypatch.setattr(inf, "_cached_local_catalog", _fake_catalog)
+    monkeypatch.setattr(resolver, "local_gguf_quants", lambda info: ("Q4_K_M",))
+    ids = {m["id"]: m for m in asyncio.run(inf._openai_catalog_objects())}
+    assert ids["publisher/Qwen3"]["loaded"] is False
+
+
 def test_an_alias_for_the_resident_weights_is_not_listed_as_unloaded(monkeypatch):
     # A GGUF loaded by absolute path keys the resident entry by basename, so an id-only dedup
     # would emit the alias again marked not loaded.
diff --git a/studio/frontend/src/features/settings/components/usage-examples.tsx b/studio/frontend/src/features/settings/components/usage-examples.tsx
index e3a254a8154..4da0f4d4617 100644
--- a/studio/frontend/src/features/settings/components/usage-examples.tsx
+++ b/studio/frontend/src/features/settings/components/usage-examples.tsx
@@ -382,6 +382,10 @@ function useExampleModelName(): string | null {
   const [catalog, setCatalog] = useState<OpenAIModel[] | null>(null);
   // A downloaded but unloaded model is only runnable when switching is on.
   const [autoSwitch, setAutoSwitch] = useState(false);
+  // Idle-unload running on its own (UNSLOTH_MODEL_IDLE_TTL, switching off) still
+  // reloads exactly what it freed on the next request. That restores the stored
+  // checkpoint only, never an arbitrary catalog entry, so it is tracked apart.
+  const [idleReload, setIdleReload] = useState(false);
   const usableCheckpoint =
     !!checkpoint && !checkpoint.startsWith("external::") && !looksLikePath(checkpoint);
 
@@ -395,13 +399,14 @@ function useExampleModelName(): string | null {
       void Promise.all([
         listOpenAIModels().catch(() => [] as OpenAIModel[]),
         loadOpenAIAutoSwitchSettings()
-          .then((s) => s.enabled)
-          .catch(() => false),
+          .then((s) => [s.enabled, s.idleUnloadActive] as const)
+          .catch(() => [false, false] as const),
       ])
-        .then(([models, enabled]) => {
+        .then(([models, [enabled, idleActive]]) => {
           if (cancelled) return true;
           setCatalog(models);
           setAutoSwitch(enabled);
+          setIdleReload(idleActive);
           // Resident only slows the polling; it never stops it.
           return models.some((m) => m.loaded);
         })
@@ -438,7 +443,8 @@ function useExampleModelName(): string | null {
     // lists it: resident, or downloaded with switching able to reload it. A null
     // catalog means /v1/models has not answered, which is not evidence against it.
     const entry = catalog?.find((m) => sameBaseModelId(m.id, checkpoint ?? ""));
-    const backed = catalog === null || (!!entry && (entry.loaded || autoSwitch));
+    const backed =
+      catalog === null || (!!entry && (entry.loaded || autoSwitch || idleReload));
     if (usableCheckpoint && checkpoint && backed) {
       if (checkpoint.includes(":")) {
         return checkpoint;
@@ -450,7 +456,7 @@ function useExampleModelName(): string | null {
       return quant ? `${checkpoint}:${quant}` : checkpoint;
     }
     return fromCatalog();
-  }, [autoSwitch, catalog, checkpoint, ggufVariant, usableCheckpoint]);
+  }, [autoSwitch, catalog, checkpoint, ggufVariant, idleReload, usableCheckpoint]);
 }
 
 // Backend PATH detection is only safe in the desktop app, where the UI owns
diff --git a/tests/studio/test_usage_examples_model_source_contract.py b/tests/studio/test_usage_examples_model_source_contract.py
index f353d1ccda8..5d27c5c050d 100644
--- a/tests/studio/test_usage_examples_model_source_contract.py
+++ b/tests/studio/test_usage_examples_model_source_contract.py
@@ -72,11 +72,25 @@ def test_a_stored_checkpoint_needs_catalog_evidence():
     src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")
     hook = src[src.find("function useExampleModelName") : src.find("// Backend PATH detection")]
     assert 'const entry = catalog?.find((m) => sameBaseModelId(m.id, checkpoint ?? ""));' in hook
-    # Resident, or downloaded with switching able to reload it. Never the setting alone.
-    assert "catalog === null || (!!entry && (entry.loaded || autoSwitch))" in hook
+    # Resident, or downloaded with something able to reload it. Never the setting alone.
+    assert "(!!entry && (entry.loaded || autoSwitch || idleReload))" in hook
     assert "autoSwitch ||\n" not in hook
 
 
+def test_standalone_idle_unload_still_names_the_stored_checkpoint():
+    # UNSLOTH_MODEL_IDLE_TTL without auto-switch reloads exactly what it freed, so the
+    # stored checkpoint stays runnable after an idle unload and the panel must keep
+    # showing it. The stash restores only that model, so it can never pick catalog[0].
+    src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")
+    hook = src[src.find("function useExampleModelName") : src.find("// Backend PATH detection")]
+    assert "const [idleReload, setIdleReload] = useState(false);" in hook
+    assert "setIdleReload(idleActive)" in hook
+    assert "s.idleUnloadActive" in hook
+    # fromCatalog stays gated on auto-switch alone.
+    assert "?? (autoSwitch ? catalog?.[0] : undefined)" in hook
+    assert "idleReload ? catalog" not in hook
+
+
 def test_the_pinned_quant_comes_from_the_catalog():
     # Catalog membership proves the repo, not the saved quant. The stored one can
     # name a file deleted while another quant of the same repo remains, and pinning

From 1d82c3d13e12d8b0f8dc93afc4119e612c996bbc Mon Sep 17 00:00:00 2001
From: danielhanchen <danielhanchen@gmail.com>
Date: Mon, 27 Jul 2026 10:21:51 +0000
Subject: [PATCH 56/56] Studio: bound the Hub admission probes and stop
 guessing at nested model paths

Three review fixes plus a test-isolation one.

_resolves_to_resident matched on a path prefix, so two separately indexed models
that nest (/models/A alongside /models/A/sub/B) both satisfied it: loading B
made a request for A resident and answered it with B's weights, and the catalog
marked A loaded. A prefix match now counts only when no catalog entry sits
deeper, which is the innermost indexed model that actually owns the file. With
nothing indexed there is no nesting to tell apart, so the directory-to-weights
match this exists for is unchanged.

auth_check and hf_hub_download take no timeout of their own, and both ran while
the provisional single-flight slot was held, so an unresponsive Hub stalled the
request far past the metadata budget and reported every other model busy for the
duration. Both are bounded now. Each default errs the safe way: an unchecked
repo is not a cleared one, so the custom-code probe refuses on timeout, while a
slow gated-repo check stays inconclusive because the download's own auth is the
real gate.

The usage examples caught a failed refresh into an empty catalog and a disabled
auto-switch, which made a transient error authoritative and blanked every
example while the model was still servable. The catalog is deliberately
tri-state; a failure now keeps the last answer and retries.

Also start the backend tests from a built, empty model index. Stubbing only the
background warm still left the cold path walking real caches synchronously
inside the admission wait, so on a large install a test asserted against a 503
"still indexing" instead of its subject. _build_index is untouched, so the tests
that call it directly still exercise the real walk.

Verified each fix is load-bearing by reverting it and watching its test fail.
tsc -b clean. Backend CI command green apart from two failures reproduced only
on this box (a real model-dir scan and an orphan-process cleanup), neither
touched by this PR; staging CI is the gate for those.
---
 .../core/inference/openai_auto_download.py    | 33 ++++++++++-
 studio/backend/routes/inference.py            | 31 ++++++++--
 studio/backend/tests/conftest.py              |  9 +++
 .../tests/test_openai_auto_download.py        | 57 +++++++++++++++++++
 studio/backend/tests/test_openai_catalog.py   | 24 ++++++++
 .../settings/components/usage-examples.tsx    | 19 ++++---
 ...st_usage_examples_model_source_contract.py | 18 +++++-
 7 files changed, 176 insertions(+), 15 deletions(-)

diff --git a/studio/backend/core/inference/openai_auto_download.py b/studio/backend/core/inference/openai_auto_download.py
index 8595489253c..fee87a42f2e 100644
--- a/studio/backend/core/inference/openai_auto_download.py
+++ b/studio/backend/core/inference/openai_auto_download.py
@@ -39,6 +39,11 @@
 
 # Keep the Hub probe short so a slow Hub can't stall the request path.
 _MODEL_INFO_TIMEOUT_S = 8.0
+# auth_check and hf_hub_download take no timeout of their own, and both run while the
+# provisional slot is held, so an unresponsive Hub would pin the single flight and stall
+# the request long past the metadata budget. The code probe fetches up to three small
+# configs, so it gets more room than the single auth call.
+_CODE_PROBE_TIMEOUT_S = 20.0
 # Headroom left free after the download, so filling the disk can't wedge the box.
 _DISK_RESERVE_BYTES = 5 * 1024**3
 _WATCH_POLL_S = 2.0
@@ -203,6 +208,20 @@ def _gated_refusal(repo_id: str) -> AutoDownloadRefusal:
     )
 
 
+async def _bounded_probe(fn, *args, timeout: float, default):
+    """Run a blocking Hub probe off the loop, bounding only the wait.
+
+    The thread is left to finish (a blocking socket read cannot be cancelled); the
+    caller stops waiting and takes *default*, which each call site chooses so that a
+    timeout errs the safe way.
+    """
+    try:
+        return await asyncio.wait_for(asyncio.to_thread(fn, *args), timeout)
+    except (TimeoutError, asyncio.TimeoutError):
+        logger.debug("hub probe %s timed out after %ss", getattr(fn, "__name__", fn), timeout)
+        return default
+
+
 def _auth_denied(repo_id: str, hf_token: Optional[str]) -> bool:
     """Whether this token lacks file access to a gated repo. False when the
     check is inconclusive: the download's own auth is the real gate."""
@@ -589,7 +608,10 @@ def _probe():
             retry_after = _RETRY_AFTER_S,
         )
 
-    if getattr(info, "gated", False) and await asyncio.to_thread(_auth_denied, repo_id, hf_token):
+    # Inconclusive on timeout: the download's own auth is the real gate.
+    if getattr(info, "gated", False) and await _bounded_probe(
+        _auth_denied, repo_id, hf_token, timeout = _MODEL_INFO_TIMEOUT_S, default = False
+    ):
         # Metadata for a gated repo is not file access; unchecked, the config read below lies.
         _release(active)
         return _gated_refusal(repo_id)
@@ -615,7 +637,14 @@ def _probe():
     # _hub_token, not the raw token: None lets huggingface_hub fall back to a cached
     # server login, so a caller-named repo would be probed with this server's identity.
     # Same rule as the metadata probe and the worker.
-    has_auto_map = await asyncio.to_thread(_config_has_auto_map, repo_id, _hub_token(hf_token))
+    # None on timeout, which refuses: an unchecked repo is not a cleared one.
+    has_auto_map = await _bounded_probe(
+        _config_has_auto_map,
+        repo_id,
+        _hub_token(hf_token),
+        timeout = _CODE_PROBE_TIMEOUT_S,
+        default = None,
+    )
     if has_auto_map is not False:
         _release(active)
         unknown = has_auto_map is None
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 188b0bfae42..72870af439f 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3889,15 +3889,36 @@ def _resolves_to_resident(load_path: Optional[str], *, llama_only: bool = False)
         if not candidate:
             continue
         current = _norm_path(candidate)
-        if (
-            current == target
-            or current.startswith(f"{target}/")
-            or target.startswith(f"{current}/")
-        ):
+        if current == target:
+            return True
+        if current.startswith(f"{target}/"):
+            # A model directory holding the weights loaded from it. Nested entries
+            # (/models/A alongside /models/A/sub/B) satisfied this too, so a request
+            # for A was answered with B. The innermost indexed model owns the file;
+            # with none indexed there is no nesting to tell apart, so keep matching.
+            owner = _innermost_indexed_owner(current)
+            if owner is None or owner == target:
+                return True
+            continue
+        if target.startswith(f"{current}/"):
             return True
     return False
 
 
+def _innermost_indexed_owner(path: str) -> Optional[str]:
+    """Longest catalog-listed model path containing *path*, or None if none does."""
+    best = None
+    for info in _CATALOG_CACHE["models"] or ():
+        listed = getattr(info, "path", None)
+        if not listed:
+            continue
+        normalized = _norm_path(listed)
+        if path == normalized or path.startswith(f"{normalized}/"):
+            if best is None or len(normalized) > len(best):
+                best = normalized
+    return best
+
+
 async def _reject_unservable_model(
     requested_model: Optional[str], fastapi_request: Optional[Request]
 ) -> None:
diff --git a/studio/backend/tests/conftest.py b/studio/backend/tests/conftest.py
index c9e028eaffb..37c933ea418 100644
--- a/studio/backend/tests/conftest.py
+++ b/studio/backend/tests/conftest.py
@@ -67,8 +67,17 @@ def _no_background_model_scan(monkeypatch):
     install takes seconds, and the resulting I/O starves the loop under the
     timing-sensitive streaming tests. Tests that exercise the warm patch it back.
     """
+    import time
+
     from core.inference import local_model_resolver
+
     monkeypatch.setattr(local_model_resolver, "warm_index_soon", lambda: None)
+    # Start from a built, empty index. Stubbing only the background warm still left the
+    # cold path walking those caches synchronously inside the admission wait, so on a
+    # large install the assertion became a 503 "still indexing". Tests that want the
+    # cold path set _scan back themselves (and stub the scan). _build_index is left
+    # alone so the tests that call it directly still exercise the real walk.
+    monkeypatch.setattr(local_model_resolver, "_scan", (time.monotonic(), {}))
 
 
 @pytest.fixture(scope = "session")
diff --git a/studio/backend/tests/test_openai_auto_download.py b/studio/backend/tests/test_openai_auto_download.py
index cd0c5d4c46a..c12a254fc35 100644
--- a/studio/backend/tests/test_openai_auto_download.py
+++ b/studio/backend/tests/test_openai_auto_download.py
@@ -552,6 +552,63 @@ async def _unknown(repo, variant):
     assert _run("unsloth/other-GGUF").code == "model_download_busy"
 
 
+def test_a_hanging_code_probe_does_not_pin_the_slot(hub, monkeypatch):
+    # hf_hub_download and auth_check take no timeout, and both run while the provisional
+    # slot is held, so an unresponsive Hub stalled the request far past the metadata
+    # budget and reported every other model busy meanwhile. Unchecked is not cleared,
+    # so the bounded probe refuses rather than admitting the repo.
+    import threading
+
+    entered, release = threading.Event(), threading.Event()
+
+    def _hang(repo, token = None):
+        entered.set()
+        release.wait(30)
+        return False
+
+    monkeypatch.setattr("utils.security.consent._config_has_auto_map", _hang)
+    monkeypatch.setattr(auto_dl, "_CODE_PROBE_TIMEOUT_S", 0.2)
+
+    async def _timed():
+        # Time the await, not asyncio.run: the probe thread cannot be cancelled, so
+        # loop shutdown waits for it here in a way a long-lived server loop never does.
+        started = time.monotonic()
+        refusal = await auto_dl.maybe_auto_download("unsloth/x-GGUF:UD-Q4_K_XL")
+        waited = time.monotonic() - started
+        release.set()
+        return refusal, waited
+
+    refusal, waited = asyncio.run(_timed())
+    assert entered.is_set()
+    assert refusal.status == 403 and refusal.code == "remote_code_consent_required"
+    assert waited < 5
+    # The slot was handed back, so the next request is admitted rather than told busy.
+    assert auto_dl._active is None
+
+
+def test_a_hanging_auth_check_falls_through_to_the_download(hub, monkeypatch):
+    # Inconclusive, not denied: the download's own auth is the real gate, so a slow
+    # gated-repo check must not turn into a refusal.
+    import threading
+
+    hub["info"].gated = True
+    release = threading.Event()
+
+    def _hang(repo, token = None):
+        release.wait(30)
+        return True
+
+    monkeypatch.setattr(auto_dl, "_auth_denied", _hang)
+    monkeypatch.setattr(auto_dl, "_MODEL_INFO_TIMEOUT_S", 0.2)
+
+    async def _timed():
+        refusal = await auto_dl.maybe_auto_download("unsloth/x-GGUF:UD-Q4_K_XL")
+        release.set()
+        return refusal
+
+    assert asyncio.run(_timed()).code == "model_downloading"
+
+
 def test_a_companion_only_repo_is_not_held_at_busy(hub):
     # mmproj and MTP files are companions, not quants, so admission classifies such a
     # repo as non-servable and lets the label fall through to the resident model. The
diff --git a/studio/backend/tests/test_openai_catalog.py b/studio/backend/tests/test_openai_catalog.py
index 6292ab0ca05..37236fbf66a 100644
--- a/studio/backend/tests/test_openai_catalog.py
+++ b/studio/backend/tests/test_openai_catalog.py
@@ -300,6 +300,30 @@ async def _fake_catalog():
     assert ids["publisher/Qwen3"]["quant"] == "Q8_0"
 
 
+def test_a_nested_model_directory_is_not_the_resident_one(monkeypatch):
+    # Two separately indexed models can nest (/models/A holding A, /models/A/sub/B
+    # holding B). A plain prefix test made loading B mark A resident, so a request for
+    # A was answered with B's weights. The innermost indexed model owns the file.
+    outer = _Info("/models/A", "A", model_id = "publisher/A")
+    outer.path = "/models/A"
+    inner = _Info("/models/A/sub/B", "B", model_id = "publisher/B")
+    inner.path = "/models/A/sub/B"
+    monkeypatch.setitem(inf._CATALOG_CACHE, "models", [outer, inner])
+
+    llama = _FakeLlama()
+    llama.gguf_path = "/models/A/sub/B/model-Q4_K_M.gguf"
+    llama.model_identifier = llama.gguf_path
+    monkeypatch.setattr(inf, "get_llama_cpp_backend", lambda: llama)
+    monkeypatch.setattr(inf, "get_inference_backend", lambda: _FakeUnsloth())
+
+    assert inf._resolves_to_resident("/models/A/sub/B") is True
+    assert inf._resolves_to_resident("/models/A") is False
+    # With nothing indexed there is no nesting to tell apart, so the directory-to-file
+    # match this exists for must still hold.
+    monkeypatch.setitem(inf._CATALOG_CACHE, "models", [])
+    assert inf._resolves_to_resident("/models/A") is True
+
+
 def test_a_transformers_model_does_not_mark_a_gguf_alias_loaded(monkeypatch):
     # Every entry in this loop is advertised as GGUF and carries a GGUF quant. A
     # Transformers model live from a directory that also holds GGUF exports is not one
diff --git a/studio/frontend/src/features/settings/components/usage-examples.tsx b/studio/frontend/src/features/settings/components/usage-examples.tsx
index 4da0f4d4617..6bb92c55890 100644
--- a/studio/frontend/src/features/settings/components/usage-examples.tsx
+++ b/studio/frontend/src/features/settings/components/usage-examples.tsx
@@ -396,19 +396,24 @@ function useExampleModelName(): string | null {
     let timeoutId: number | null = null;
 
     const update = () => {
+      // null on failure, never [] or false: a transient error is not evidence that the
+      // server holds nothing, and feeding those negatives in blanked every example while
+      // the model was still servable. Keep the last answer and retry.
       void Promise.all([
-        listOpenAIModels().catch(() => [] as OpenAIModel[]),
+        listOpenAIModels().catch(() => null),
         loadOpenAIAutoSwitchSettings()
           .then((s) => [s.enabled, s.idleUnloadActive] as const)
-          .catch(() => [false, false] as const),
+          .catch(() => null),
       ])
-        .then(([models, [enabled, idleActive]]) => {
+        .then(([models, settings]) => {
           if (cancelled) return true;
-          setCatalog(models);
-          setAutoSwitch(enabled);
-          setIdleReload(idleActive);
+          if (models !== null) setCatalog(models);
+          if (settings !== null) {
+            setAutoSwitch(settings[0]);
+            setIdleReload(settings[1]);
+          }
           // Resident only slows the polling; it never stops it.
-          return models.some((m) => m.loaded);
+          return models !== null && models.some((m) => m.loaded);
         })
         .then((resolved) => {
           if (cancelled) return;
diff --git a/tests/studio/test_usage_examples_model_source_contract.py b/tests/studio/test_usage_examples_model_source_contract.py
index 5d27c5c050d..446cc619b22 100644
--- a/tests/studio/test_usage_examples_model_source_contract.py
+++ b/tests/studio/test_usage_examples_model_source_contract.py
@@ -84,13 +84,29 @@ def test_standalone_idle_unload_still_names_the_stored_checkpoint():
     src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")
     hook = src[src.find("function useExampleModelName") : src.find("// Backend PATH detection")]
     assert "const [idleReload, setIdleReload] = useState(false);" in hook
-    assert "setIdleReload(idleActive)" in hook
+    assert "setIdleReload(settings[1])" in hook
     assert "s.idleUnloadActive" in hook
     # fromCatalog stays gated on auto-switch alone.
     assert "?? (autoSwitch ? catalog?.[0] : undefined)" in hook
     assert "idleReload ? catalog" not in hook
 
 
+def test_a_failed_refresh_does_not_erase_what_the_server_holds():
+    # Catching into [] and false made a transient error authoritative: the panel
+    # dropped a still-servable model and printed "No model" until the next poll.
+    # The catalog is deliberately tri-state, and a failure must stay the unknown one.
+    src = USAGE_EXAMPLES_TSX.read_text(encoding = "utf-8")
+    hook = src[src.find("function useExampleModelName") : src.find("// Backend PATH detection")]
+    assert "listOpenAIModels().catch(() => null)" in hook
+    assert ".catch(() => null)," in hook
+    assert "if (models !== null) setCatalog(models);" in hook
+    assert "if (settings !== null) {" in hook
+    # The old negatives must be gone entirely.
+    assert "catch(() => [] as OpenAIModel[])" not in hook
+    assert "catch(() => [false, false] as const)" not in hook
+    assert "catch(() => false)" not in hook
+
+
 def test_the_pinned_quant_comes_from_the_catalog():
     # Catalog membership proves the repo, not the saved quant. The stored one can
     # name a file deleted while another quant of the same repo remains, and pinning