Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: show a download start the moment it is requested, and serialise the first zoo import with the media import window (#13738)

Eyera5337c8f53aa7
diff --git a/studio/backend/tests/test_xet_import_window.py b/studio/backend/tests/test_xet_import_window.py
new file mode 100644
index 00000000000..cb284a305c2
--- /dev/null
+++ b/studio/backend/tests/test_xet_import_window.py
@@ -0,0 +1,381 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""A download's first ``unsloth_zoo`` import holds the media import window, so it cannot interleave
+with the post-warm worker's torchao and diffusers imports (half-built ``torchao.kernel``)."""
+
+from __future__ import annotations
+
+import ast
+import importlib
+import importlib.util
+import sys
+import threading
+import time
+import types
+from pathlib import Path
+
+import pytest
+
+_BACKEND = Path(__file__).resolve().parent.parent
+_HEALTH = "unsloth_zoo.hf_xet_health"
+_SHARED = "unsloth_zoo.hf_xet_fallback"
+
+
+class _Log:
+ def __init__(self):
+ self.lines = []
+
+ def info(self, msg, *args):
+ self.lines.append(("info", msg % args if args else msg))
+
+ def warning(self, msg, *args):
+ self.lines.append(("warning", msg % args if args else msg))
+
+
+def warm(monkeypatch):
+ from utils import torch_warmup
+
+ monkeypatch.setattr(torch_warmup, "_dynamo_done", True)
+ monkeypatch.setattr(torch_warmup, "_media_import_claimed", False)
+ monkeypatch.setattr(torch_warmup, "_media_import_owner", None)
+ monkeypatch.delenv(torch_warmup.DYNAMO_GATE_DISABLE_ENV_VAR, raising = False)
+ monkeypatch.delenv(torch_warmup.DYNAMO_GATE_TIMEOUT_ENV_VAR, raising = False)
+ return torch_warmup
+
+
+def shim(monkeypatch):
+ from utils import hf_xet_fallback
+
+ monkeypatch.setattr(hf_xet_fallback, "_gpu_present", lambda: True)
+ # The full-init path is the one that needs the window; the init-free route (#13849) imports no torch.
+ monkeypatch.setattr(hf_xet_fallback, "_import_light", lambda name: None)
+ hf_xet_fallback._reset_optional_module_cache()
+ yield hf_xet_fallback
+ hf_xet_fallback._reset_optional_module_cache()
+
+
+def _observing_import(warm, seen: dict, module):
+ def _import(name, package = None):
+ seen["name"] = name
+ seen["locked"] = warm._media_import_lock.locked()
+ seen["owner"] = warm._media_import_owner == threading.get_ident()
+ return module
+
+ return _import
+
+
+class _RecordingFinder:
+ def __init__(self, warm, seen: dict):
+ self.warm = warm
+ self.seen = seen
+
+ def find_spec(
+ self,
+ name,
+ path = None,
+ target = None,
+ ):
+ if name != _SHARED:
+ return None
+ return importlib.util.spec_from_loader(name, self)
+
+ def create_module(self, spec):
+ return None
+
+ def exec_module(self, module):
+ self.seen["locked"] = self.warm._media_import_lock.locked()
+ self.seen["owner"] = self.warm._media_import_owner == threading.get_ident()
+
+
+def test_the_optional_import_holds_the_window(warm, shim, monkeypatch):
+ seen: dict = {}
+ fake = types.ModuleType(_HEALTH)
+ monkeypatch.setattr(importlib, "import_module", _observing_import(warm, seen, fake))
+
+ assert shim._load_optional(_HEALTH) is fake
+
+ assert seen == {"name": _HEALTH, "locked": True, "owner": True}
+ assert not warm._media_import_lock.locked()
+ assert warm._media_import_owner is None
+
+
+def test_the_shared_import_holds_the_window(warm, shim, monkeypatch):
+ seen: dict = {}
+ package = types.ModuleType("unsloth_zoo")
+ package.__path__ = []
+ finder = _RecordingFinder(warm, seen)
+ monkeypatch.setattr(shim, "_shared", None)
+ monkeypatch.setattr(shim, "_shared_available", None)
+ monkeypatch.setattr(shim, "_shared_import_error", None)
+ monkeypatch.setitem(sys.modules, "unsloth_zoo", package)
+ saved = sys.modules.pop(_SHARED, None)
+ sys.meta_path.insert(0, finder)
+ try:
+ assert shim._load_shared() is True
+ finally:
+ sys.meta_path.remove(finder)
+ if saved is None:
+ sys.modules.pop(_SHARED, None)
+ else:
+ sys.modules[_SHARED] = saved
+
+ assert seen == {"locked": True, "owner": True}
+ assert shim._shared.__name__ == _SHARED
+ assert not warm._media_import_lock.locked()
+ assert warm._media_import_owner is None
+
+
+def test_the_import_waits_for_a_background_media_import_in_flight(warm, shim, monkeypatch):
+ seen: dict = {}
+ fake = types.ModuleType(_HEALTH)
+ monkeypatch.setattr(importlib, "import_module", _observing_import(warm, seen, fake))
+ in_window = threading.Event()
+ release = threading.Event()
+
+ def _background():
+ with warm.background_media_import():
+ in_window.set()
+ release.wait(10)
+
+ background = threading.Thread(target = _background, daemon = True)
+ background.start()
+ assert in_window.wait(10)
+
+ result = []
+ done = threading.Event()
+ loader = threading.Thread(
+ target = lambda: (result.append(shim._load_optional(_HEALTH)), done.set()), daemon = True
+ )
+ loader.start()
+ try:
+ assert not done.wait(0.5), "unsloth_zoo was imported while a background media import ran"
+ finally:
+ release.set()
+ background.join(10)
+ assert done.wait(10)
+ loader.join(10)
+
+ assert result == [fake]
+ assert seen["locked"] is True and seen["owner"] is True
+ assert not warm._media_import_lock.locked()
+
+
+def test_the_import_still_runs_when_the_wait_expires(warm, shim, monkeypatch):
+ monkeypatch.setenv(warm.DYNAMO_GATE_TIMEOUT_ENV_VAR, "0.2")
+ seen: dict = {}
+ fake = types.ModuleType(_HEALTH)
+ monkeypatch.setattr(importlib, "import_module", _observing_import(warm, seen, fake))
+
+ assert warm._media_import_lock.acquire(timeout = 5)
+ started = time.perf_counter()
+ try:
+ assert shim._load_optional(_HEALTH) is fake
+ assert warm._media_import_lock.locked()
+ finally:
+ warm._media_import_lock.release()
+ assert time.perf_counter() - started >= 0.15
+ assert seen == {"name": _HEALTH, "locked": True, "owner": False}
+
+
+def test_a_failed_first_attempt_keeps_the_window_for_its_retry(warm, shim, monkeypatch):
+ monkeypatch.setattr(shim, "_gpu_present", lambda: False)
+ fake = types.ModuleType(_HEALTH)
+ attempts: list = []
+
+ def _import(name, package = None):
+ attempts.append(
+ (warm._media_import_lock.locked(), warm._media_import_owner == threading.get_ident())
+ )
+ if len(attempts) == 1:
+ raise RuntimeError("init raised")
+ return fake
+
+ monkeypatch.setattr(importlib, "import_module", _import)
+
+ assert shim._load_optional(_HEALTH) is fake
+
+ assert attempts == [(True, True), (True, True)]
+ assert not warm._media_import_lock.locked()
+ assert warm._media_import_owner is None
+
+
+def test_an_expired_wait_is_logged_and_releases_nothing(warm, monkeypatch):
+ monkeypatch.setenv(warm.DYNAMO_GATE_TIMEOUT_ENV_VAR, "0.2")
+ log = _Log()
+
+ assert warm._media_import_lock.acquire(timeout = 5)
+ try:
+ with warm.hold_media_import_window("unsloth_zoo import", log):
+ assert warm._media_import_owner is None
+ assert warm._media_import_lock.locked()
+ finally:
+ warm._media_import_lock.release()
+
+ assert [level for level, _ in log.lines] == ["info", "warning"], log.lines
+ assert "unsloth_zoo import: waiting for a background media import" in log.lines[0][1]
+ assert "gave up waiting" in log.lines[1][1]
+
+
[email protected]("setting", ["inf", "1e30"])
+def test_an_unbounded_timeout_setting_still_waits_instead_of_raising(warm, monkeypatch, setting):
+ monkeypatch.setenv(warm.DYNAMO_GATE_TIMEOUT_ENV_VAR, setting)
+ assert warm._dynamo_gate_timeout() == threading.TIMEOUT_MAX
+
+ assert warm._media_import_lock.acquire(timeout = 5)
+ entered = threading.Event()
+
+ def _hold():
+ with warm.hold_media_import_window("unsloth_zoo import"):
+ entered.set()
+
+ waiter = threading.Thread(target = _hold, daemon = True)
+ waiter.start()
+ try:
+ assert not entered.wait(0.2)
+ finally:
+ warm._media_import_lock.release()
+ assert entered.wait(5)
+ waiter.join(5)
+ assert not waiter.is_alive()
+ assert not warm._media_import_lock.locked()
+
+
+def test_a_failure_inside_the_window_releases_it(warm):
+ with pytest.raises(ImportError):
+ with warm.hold_media_import_window("unsloth_zoo import"):
+ assert warm._media_import_lock.locked()
+ raise ImportError("half-built module")
+
+ assert not warm._media_import_lock.locked()
+ assert warm._media_import_owner is None
+
+
+def test_the_kill_switch_skips_the_window(warm, monkeypatch):
+ monkeypatch.setenv(warm.DYNAMO_GATE_DISABLE_ENV_VAR, "1")
+
+ with warm.hold_media_import_window("unsloth_zoo import"):
+ assert not warm._media_import_lock.locked()
+ assert warm._media_import_owner is None
+
+
+def test_the_loader_runs_unguarded_without_the_warm_module(warm, shim, monkeypatch):
+ fake = types.ModuleType(_HEALTH)
+ monkeypatch.setattr(importlib, "import_module", lambda name, package = None: fake)
+ monkeypatch.setitem(sys.modules, "utils.torch_warmup", None)
+
+ assert shim._load_optional(_HEALTH) is fake
+ assert not warm._media_import_lock.locked()
+
+
+def test_background_work_reaching_the_import_does_not_wait_on_itself(warm):
+ result = []
+
+ def _background():
+ with warm.background_media_import():
+ with warm.hold_media_import_window("unsloth_zoo import"):
+ result.append(warm._media_import_lock.locked())
+
+ thread = threading.Thread(target = _background, daemon = True)
+ thread.start()
+ thread.join(5)
+
+ assert not thread.is_alive(), "background work deadlocked on its own window"
+ assert result == [True]
+ assert not warm._media_import_lock.locked()
+
+
+def _reaches_unsloth_zoo(node: ast.AST) -> bool:
+ if isinstance(node, ast.Import):
+ return any(alias.name.startswith("unsloth_zoo") for alias in node.names)
+ if isinstance(node, ast.ImportFrom):
+ return (node.module or "").startswith("unsloth_zoo")
+ return (
+ isinstance(node, ast.Call)
+ and isinstance(node.func, ast.Attribute)
+ and node.func.attr == "import_module"
+ )
+
+
+def _inside_the_window(fn: ast.FunctionDef) -> set:
+ inside = set()
+ for node in ast.walk(fn):
+ if not isinstance(node, ast.With):
+ continue
+ if not any(
+ isinstance(item.context_expr, ast.Call)
+ and getattr(item.context_expr.func, "id", None) == "_media_import_window"
+ for item in node.items
+ ):
+ continue
+ inside.update(id(inner) for inner in ast.walk(node))
+ return inside
+
+
+def _loaders() -> list:
+ tree = ast.parse((_BACKEND / "utils" / "hf_xet_fallback.py").read_text(encoding = "utf-8"))
+ loaders = [
+ node
+ for node in tree.body
+ if isinstance(node, ast.FunctionDef) and node.name in {"_load_shared", "_load_optional"}
+ ]
+ assert [fn.name for fn in loaders] == ["_load_shared", "_load_optional"]
+ return loaders
+
+
+def _windows(fn: ast.FunctionDef) -> list:
+ return [
+ node
+ for node in ast.walk(fn)
+ if isinstance(node, ast.With)
+ and any(
+ isinstance(item.context_expr, ast.Call)
+ and getattr(item.context_expr.func, "id", None) == "_media_import_window"
+ for item in node.items
+ )
+ ]
+
+
+def test_every_zoo_import_in_the_shim_is_inside_the_window():
+ for fn in _loaders():
+ inside = _inside_the_window(fn)
+ imports = [node for node in ast.walk(fn) if _reaches_unsloth_zoo(node)]
+ assert len(imports) == 2, fn.name
+ assert all(id(node) in inside for node in imports), fn.name
+
+
+def test_each_loader_opens_the_window_once():
+ for fn in _loaders():
+ assert len(_windows(fn)) == 1, fn.name
+
+
+def test_the_dynamo_gate_runs_before_the_window_and_the_window_wraps_the_load_lock():
+ for fn in _loaders():
+ gate = min(
+ (
+ node.lineno
+ for node in ast.walk(fn)
+ if isinstance(node, ast.Call)
+ and getattr(node.func, "id", None) == "_gate_torch_stack"
+ ),
+ default = None,
+ )
+ assert gate is not None, fn.name
+ windows = _windows(fn)
+ assert windows and gate < min(node.lineno for node in windows), fn.name
+ locks = [
+ node
+ for node in ast.walk(fn)
+ if isinstance(node, ast.With)
+ and any(getattr(item.context_expr, "id", None) == "_load_lock" for item in node.items)
+ # The init-free route (#13849) takes the lock before the gate and imports no torch.
+ and node.lineno > gate
+ ]
+ assert locks, fn.name
+ for lock in locks:
+ assert any(window.lineno < lock.lineno <= window.end_lineno for window in windows), (
+ fn.name,
+ lock.lineno,
+ )
diff --git a/studio/backend/utils/hf_xet_fallback.py b/studio/backend/utils/hf_xet_fallback.py
index 970bfe3fe5c..f8b2d8ca66f 100644
--- a/studio/backend/utils/hf_xet_fallback.py
+++ b/studio/backend/utils/hf_xet_fallback.py
@@ -23,6 +23,7 @@ from __future__ import annotations
import os
import threading
import time
+from contextlib import nullcontext
from dataclasses import dataclass
from functools import partial
from pathlib import Path
@@ -84,6 +85,14 @@ def _gate_torch_stack(reason: str) -> None:
pass
+def _media_import_window(reason: str):
+ try:
+ from utils.torch_warmup import hold_media_import_window
+ except Exception: # noqa: BLE001
+ return nullcontext()
+ return hold_media_import_window(reason)
+
+
def _import_light(module_name: str) -> Any:
"""``unsloth_zoo.<name>`` from the init-free ``unsloth_zoo_downloads`` (unsloth-zoo#1752), else ``None``.
@@ -122,43 +131,10 @@ def _load_shared() -> bool:
return _shared_available
# Outside _load_lock: a thread waiting on the warm must not hold up the env-var bookkeeping.
_gate_torch_stack("unsloth_zoo.hf_xet_fallback import")
- with _load_lock:
- if _shared_available is not None:
- return _shared_available
- try:
- import unsloth_zoo.hf_xet_fallback as shared
-
- _shared = shared
- _shared_available = True
- _shared_import_error = None
- return True
- except Exception as exc: # noqa: BLE001 - any import failure must degrade, not crash
- # unsloth_zoo's __init__ runs torch/GPU detection, which raises on a torch-less/GPU-less
- # host. The download helper needs none of it, so retry via UNSLOTH_ZOO_DISABLE_GPU_INIT.
- _shared_import_error = exc
- import os as _os
-
- # ...but NOT on a CUDA/XPU host (see _gpu_present). That flag makes unsloth_zoo take its MLX/CPU path,
- # injecting triton and bitsandbytes STUBS into sys.modules for the process. On a working GPU box those stubs
- # raise from the first CUDA-only kernel, turning a healthy GPU into 500s.
- if _gpu_present():
- _shared_available = False
- import logging as _logging
-
- _logging.getLogger(__name__).warning(
- "unsloth_zoo.hf_xet_fallback unavailable (%s); the Xet stall watchdog is "
- "disabled. Not retrying under UNSLOTH_ZOO_DISABLE_GPU_INIT because this host "
- "has an accelerator and that path would stub out triton/bitsandbytes for the "
- "whole process.",
- exc,
- )
- return False
-
- global _gpu_init_override_depth
- _prev_gpu_init = _os.environ.get("UNSLOTH_ZOO_DISABLE_GPU_INIT")
- _ours = _prev_gpu_init != "1"
- _gpu_init_override_depth += _ours
- _os.environ["UNSLOTH_ZOO_DISABLE_GPU_INIT"] = "1"
+ with _media_import_window("unsloth_zoo.hf_xet_fallback import"):
+ with _load_lock:
+ if _shared_available is not None:
+ return _shared_available
try:
import unsloth_zoo.hf_xet_fallback as shared
@@ -166,24 +142,58 @@ def _load_shared() -> bool:
_shared_available = True
_shared_import_error = None
return True
- except Exception as exc2: # noqa: BLE001 - degrade so Unsloth still boots with plain HF
- _shared_import_error = exc2
- _shared_available = False
- import logging as _logging
-
- _logging.getLogger(__name__).warning(
- "unsloth_zoo.hf_xet_fallback unavailable (%s); the Xet stall watchdog is "
- "disabled. Install/upgrade unsloth_zoo (and its torch dependency) to "
- "re-enable automatic Xet -> HTTP download recovery.",
- _shared_import_error,
- )
- return False
- finally:
- if _prev_gpu_init is None:
- _os.environ.pop("UNSLOTH_ZOO_DISABLE_GPU_INIT", None)
- else:
- _os.environ["UNSLOTH_ZOO_DISABLE_GPU_INIT"] = _prev_gpu_init
- _gpu_init_override_depth -= _ours
+ except Exception as exc: # noqa: BLE001 - any import failure must degrade, not crash
+ # unsloth_zoo's __init__ runs torch/GPU detection, which raises on a torch-less/GPU-less
+ # host. The download helper needs none of it, so retry via UNSLOTH_ZOO_DISABLE_GPU_INIT.
+ _shared_import_error = exc
+ import os as _os
+
+ # ...but NOT on a CUDA/XPU host (see _gpu_present). That flag makes unsloth_zoo take its MLX/CPU path,
+ # injecting triton and bitsandbytes STUBS into sys.modules for the process. On a working GPU box those stubs
+ # raise from the first CUDA-only kernel, turning a healthy GPU into 500s.
+ if _gpu_present():
+ _shared_available = False
+ import logging as _logging
+
+ _logging.getLogger(__name__).warning(
+ "unsloth_zoo.hf_xet_fallback unavailable (%s); the Xet stall watchdog is "
+ "disabled. Not retrying under UNSLOTH_ZOO_DISABLE_GPU_INIT because this host "
+ "has an accelerator and that path would stub out triton/bitsandbytes for the "
+ "whole process.",
+ exc,
+ )
+ return False
+
+ global _gpu_init_override_depth
+ _prev_gpu_init = _os.environ.get("UNSLOTH_ZOO_DISABLE_GPU_INIT")
+ _ours = _prev_gpu_init != "1"
+ _gpu_init_override_depth += _ours
+ _os.environ["UNSLOTH_ZOO_DISABLE_GPU_INIT"] = "1"
+ try:
+ import unsloth_zoo.hf_xet_fallback as shared
+
+ _shared = shared
+ _shared_available = True
+ _shared_import_error = None
+ return True
+ except Exception as exc2: # noqa: BLE001 - degrade so Unsloth still boots with plain HF
+ _shared_import_error = exc2
+ _shared_available = False
+ import logging as _logging
+
+ _logging.getLogger(__name__).warning(
+ "unsloth_zoo.hf_xet_fallback unavailable (%s); the Xet stall watchdog is "
+ "disabled. Install/upgrade unsloth_zoo (and its torch dependency) to "
+ "re-enable automatic Xet -> HTTP download recovery.",
+ _shared_import_error,
+ )
+ return False
+ finally:
+ if _prev_gpu_init is None:
+ _os.environ.pop("UNSLOTH_ZOO_DISABLE_GPU_INIT", None)
+ else:
+ _os.environ["UNSLOTH_ZOO_DISABLE_GPU_INIT"] = _prev_gpu_init
+ _gpu_init_override_depth -= _ours
# Memoising the FAILURE is the point: on a zoo predating these modules the import can never start
@@ -223,62 +233,66 @@ def _load_optional(module_name: str) -> Any:
return light
_gate_torch_stack(f"{module_name} import")
- try:
- module = importlib.import_module(module_name)
- _optional_modules[module_name] = module
- return module
- except Exception as exc: # noqa: BLE001 - an older/absent unsloth_zoo must degrade, not crash
- first_error = exc
-
- # Deliberately the SAME lock _load_shared uses: interleaved save/set/restore would leave
- # UNSLOTH_ZOO_DISABLE_GPU_INIT set for the life of the process (see _load_lock).
- with _load_lock:
- cached = _optional_modules.get(module_name, _UNTRIED)
- if cached is not _UNTRIED:
- return cached
- # Same rule as _load_shared: the retry's triton/bitsandbytes stubs stay in sys.modules for good.
- if _gpu_present():
- import sys as _sys
-
- # A zoo __init__ failing late leaves the submodules it already ran (hf_xet_tuning) in sys.modules.
- module = _sys.modules.get(module_name)
- # Still executing in another thread: never memoise a half-built module.
- if getattr(getattr(module, "__spec__", None), "_initializing", False):
- module = None
- if module is None:
- import logging as _logging
- _logging.getLogger(__name__).warning(
- "%s unavailable (%s); not retrying under UNSLOTH_ZOO_DISABLE_GPU_INIT because this host has an "
- "accelerator and that path would stub out triton/bitsandbytes for the whole process.",
- module_name,
- first_error,
- )
+ with _media_import_window(f"{module_name} import"):
+ try:
+ module = importlib.import_module(module_name)
_optional_modules[module_name] = module
return module
- global _gpu_init_override_depth
- previous = _os.environ.get("UNSLOTH_ZOO_DISABLE_GPU_INIT")
- ours = previous != "1"
- # Claim BEFORE the write, release AFTER the restore.
- _gpu_init_override_depth += ours
- try:
- _os.environ["UNSLOTH_ZOO_DISABLE_GPU_INIT"] = "1"
+ except Exception as exc: # noqa: BLE001 - an older/absent unsloth_zoo must degrade, not crash
+ first_error = exc
+
+ # Deliberately the SAME lock _load_shared uses: interleaved save/set/restore would leave
+ # UNSLOTH_ZOO_DISABLE_GPU_INIT set for the life of the process (see _load_lock).
+ with _load_lock:
+ cached = _optional_modules.get(module_name, _UNTRIED)
+ if cached is not _UNTRIED:
+ return cached
+ # Same rule as _load_shared: the retry's triton/bitsandbytes stubs stay in sys.modules for good.
+ if _gpu_present():
+ import sys as _sys
+
+ # A zoo __init__ failing late leaves the submodules it already ran (hf_xet_tuning) in sys.modules.
+ module = _sys.modules.get(module_name)
+ # Still executing in another thread: never memoise a half-built module.
+ if getattr(getattr(module, "__spec__", None), "_initializing", False):
+ module = None
+ if module is None:
+ import logging as _logging
+ _logging.getLogger(__name__).warning(
+ "%s unavailable (%s); not retrying under UNSLOTH_ZOO_DISABLE_GPU_INIT because this host has an "
+ "accelerator and that path would stub out triton/bitsandbytes for the whole process.",
+ module_name,
+ first_error,
+ )
+ _optional_modules[module_name] = module
+ return module
+ global _gpu_init_override_depth
+ previous = _os.environ.get("UNSLOTH_ZOO_DISABLE_GPU_INIT")
+ ours = previous != "1"
+ # Claim BEFORE the write, release AFTER the restore.
+ _gpu_init_override_depth += ours
try:
- module = importlib.import_module(module_name)
- except Exception as exc: # noqa: BLE001
- import logging as _logging
- _logging.getLogger(__name__).debug(
- "%s unavailable (%s; with GPU init disabled: %s)", module_name, first_error, exc
- )
- module = None
+ _os.environ["UNSLOTH_ZOO_DISABLE_GPU_INIT"] = "1"
+ try:
+ module = importlib.import_module(module_name)
+ except Exception as exc: # noqa: BLE001
+ import logging as _logging
+ _logging.getLogger(__name__).debug(
+ "%s unavailable (%s; with GPU init disabled: %s)",
+ module_name,
+ first_error,
+ exc,
+ )
+ module = None
+ finally:
+ if previous is None:
+ _os.environ.pop("UNSLOTH_ZOO_DISABLE_GPU_INIT", None)
+ else:
+ _os.environ["UNSLOTH_ZOO_DISABLE_GPU_INIT"] = previous
finally:
- if previous is None:
- _os.environ.pop("UNSLOTH_ZOO_DISABLE_GPU_INIT", None)
- else:
- _os.environ["UNSLOTH_ZOO_DISABLE_GPU_INIT"] = previous
- finally:
- _gpu_init_override_depth -= ours
- _optional_modules[module_name] = module
- return module
+ _gpu_init_override_depth -= ours
+ _optional_modules[module_name] = module
+ return module
@dataclass(frozen = True)
diff --git a/studio/backend/utils/torch_warmup.py b/studio/backend/utils/torch_warmup.py
index fba6cf2547c..a1004ec36e2 100644
--- a/studio/backend/utils/torch_warmup.py
+++ b/studio/backend/utils/torch_warmup.py
@@ -257,7 +257,7 @@ def _dynamo_gate_timeout() -> float:
value = float(os.environ.get(DYNAMO_GATE_TIMEOUT_ENV_VAR, _DEFAULT_DYNAMO_GATE_TIMEOUT_S))
except ValueError:
return _DEFAULT_DYNAMO_GATE_TIMEOUT_S
- return value if value > 0 else _DEFAULT_DYNAMO_GATE_TIMEOUT_S
+ return min(value, threading.TIMEOUT_MAX) if value > 0 else _DEFAULT_DYNAMO_GATE_TIMEOUT_S
def gate_torch_stack_import(reason: str, log = None) -> bool:
@@ -398,6 +398,44 @@ def claim_media_import_window(log = None) -> bool:
_media_import_lock.release()
+@contextmanager
+def hold_media_import_window(reason: str, log = None):
+ """Hold the window around a foreground import of the torch compile stack; an expired wait still imports."""
+ global _media_import_owner
+ if (
+ os.environ.get(DYNAMO_GATE_DISABLE_ENV_VAR) == "1"
+ or _media_import_owner == threading.get_ident()
+ ):
+ yield
+ return
+ held = _media_import_lock.acquire(blocking = False)
+ if not held:
+ waited = time.perf_counter()
+ (log or logger).info("%s: waiting for a background media import to finish", reason)
+ held = _media_import_lock.acquire(timeout = _dynamo_gate_timeout())
+ if held:
+ (log or logger).info(
+ "%s: background media import finished after waiting %.1fs",
+ reason,
+ time.perf_counter() - waited,
+ )
+ else:
+ (log or logger).warning(
+ "%s: gave up waiting for the background media import after %.0fs; importing unguarded",
+ reason,
+ time.perf_counter() - waited,
+ )
+ if not held:
+ yield
+ return
+ _media_import_owner = threading.get_ident()
+ try:
+ yield
+ finally:
+ _media_import_owner = None
+ _media_import_lock.release()
+
+
_STAGES = (
("hardware", _warm_hardware),
("inference_backend", _warm_inference_backend),
diff --git a/studio/frontend/scripts/check-bundle-budget.ts b/studio/frontend/scripts/check-bundle-budget.ts
index 832185588d5..eb2d53f4260 100644
--- a/studio/frontend/scripts/check-bundle-budget.ts
+++ b/studio/frontend/scripts/check-bundle-budget.ts
@@ -154,8 +154,10 @@ export const BUDGET = {
// transfer (6,778,788 -> 6,780,604 B raw, 2,038,337 -> 2,038,856 B transfer against 62e063618, one machine
// and build, Node 24, chunk count unchanged at 95). Main already measured 3,656 B raw / 1,180 B transfer over
// the previous limits there, so they are set to the measured build.
- transferBytes: 2_038_856,
- rawBytes: 6_780_604,
+ // The downloads panel's "Starting…" row (#13738) adds 1,404 B raw / 353 B transfer (6,778,788 -> 6,780,192 B raw,
+ // 2,038,337 -> 2,038,690 B transfer against 7c235de6f, one machine and build, Node 24, 95 chunks). Raised by that growth.
+ transferBytes: 2_039_209,
+ rawBytes: 6_782_008,
};
// The chunk count is reported but not budgeted. Splitting a page out of the entry raises it while lowering the
diff --git a/studio/frontend/src/features/hub/download-manager/download-manager-controller.ts b/studio/frontend/src/features/hub/download-manager/download-manager-controller.ts
index e0e1511cbab..89f626f5abf 100644
--- a/studio/frontend/src/features/hub/download-manager/download-manager-controller.ts
+++ b/studio/frontend/src/features/hub/download-manager/download-manager-controller.ts
@@ -16,6 +16,7 @@ import {
useDownloadManagerStore,
} from "./download-manager-state";
import { hydrateDownloadManager, resetHydrationState } from "./hydration";
+import { resetPendingStarts } from "./pending-starts";
import { cancelJob, probeAndAdopt, setExpected } from "./poll-loop";
import { runtimeRegistry } from "./runtime-registry";
import { resetStagedQueues } from "./staged-download-queue";
@@ -51,6 +52,7 @@ function resetDownloadManagerState(): void {
setState(createDownloadManagerInitialState());
// A media page stays mounted across a cross-tab session change, so its queue would outlive the jobs.
resetStagedQueues();
+ resetPendingStarts();
}
export function __resetDownloadManagerForTests(): void {
diff --git a/studio/frontend/src/features/hub/download-manager/download-manager-panel.tsx b/studio/frontend/src/features/hub/download-manager/download-manager-panel.tsx
index cd869618c29..285229dec30 100644
--- a/studio/frontend/src/features/hub/download-manager/download-manager-panel.tsx
+++ b/studio/frontend/src/features/hub/download-manager/download-manager-panel.tsx
@@ -33,9 +33,19 @@ import {
} from "./download-manager-controller";
import { DownloadProgressBar } from "./download-progress-bar";
import { presentedProgress } from "./download-presentation";
+import {
+ type PendingStart,
+ usePendingStarts,
+ visiblePendingStarts,
+} from "./pending-starts";
import { assetLabel } from "./required-assets";
import { queuedStagedEntries, useStagedDownloadQueues } from "./staged-download-queue";
+type RowSubject = Pick<
+ ManagedDownload,
+ "repoId" | "variant" | "presentation" | "checkpoint" | "scopedFiles"
+>;
+
function createOrderedJobKeysSelector(): (state: {
jobs: Record<string, ManagedDownload>;
}) => string[] {
@@ -87,7 +97,7 @@ function repoLabel(repoId: string): string {
return isAudioCppFolderId(repoId) ? audioCppDisplayName(repoId) : repoId;
}
-function isRequiredAssetJob(job: ManagedDownload): boolean {
+function isRequiredAssetJob(job: RowSubject): boolean {
if (!job.variant?.startsWith("@")) return false;
// The staging page tagged the entry it picked, which is the only reliable answer: a checkpoint
// can be a curated single .safetensors and companion repos carry .safetensors too, so the
@@ -103,7 +113,7 @@ function isRequiredAssetJob(job: ManagedDownload): boolean {
const REQUIRED_ASSET_NOTE =
"Required to run this model. Downloaded once, shared across compatible variants.";
-function variantSuffix(job: ManagedDownload): string {
+function variantSuffix(job: RowSubject): string {
if (job.variant?.startsWith("@")) {
return ` · ${
isRequiredAssetJob(job)
@@ -117,6 +127,45 @@ function variantSuffix(job: ManagedDownload): string {
return job.variant ? ` · ${job.variant}` : "";
}
+function RowTitle({ job }: { job: RowSubject }) {
+ return (
+ <span className="min-w-0 flex-1 truncate text-ui-12p5 font-medium text-foreground">
+ {job.presentation?.label ?? repoLabel(job.repoId)}
+ <span className="text-muted-foreground">
+ {job.presentation ? ` · ${repoLabel(job.repoId)}` : variantSuffix(job)}
+ </span>
+ </span>
+ );
+}
+
+function RowDetail({ job }: { job: RowSubject }) {
+ return job.presentation ? (
+ <div className="truncate text-ui-10p5 text-muted-foreground">
+ {job.presentation.filename}
+ </div>
+ ) : isRequiredAssetJob(job) && job.checkpoint === false ? (
+ <div className="text-ui-10p5 text-muted-foreground">
+ {REQUIRED_ASSET_NOTE}
+ </div>
+ ) : null;
+}
+
+function StartingLine() {
+ return <div className="text-ui-11 text-muted-foreground">Starting…</div>;
+}
+
+function PendingStartRow({ start }: { start: PendingStart }) {
+ return (
+ <li className="flex flex-col gap-1.5 py-2.5 pl-4 pr-3">
+ <div className="flex items-center gap-2">
+ <RowTitle job={start} />
+ </div>
+ <RowDetail job={start} />
+ <StartingLine />
+ </li>
+ );
+}
+
function StatusLine({ job }: { job: ManagedDownload }) {
if (job.state === "complete") {
return <span className="text-status-success">Downloaded</span>;
@@ -138,9 +187,17 @@ function StatusLine({ job }: { job: ManagedDownload }) {
return null;
}
-function DownloadRow({ jobKey }: { jobKey: string }) {
+function DownloadRow({
+ jobKey,
+ pendingStart,
+}: {
+ jobKey: string;
+ pendingStart?: PendingStart;
+}) {
const job = useDownloadManagerStore((state) => state.jobs[jobKey]);
if (!job) return null;
+ const starting = pendingStart !== undefined;
+ const subject = pendingStart ?? job;
const active = job.state === "running" || job.state === "cancelling";
const terminal =
job.state === "complete" ||
@@ -150,22 +207,15 @@ function DownloadRow({ jobKey }: { jobKey: string }) {
return (
<li className="flex flex-col gap-1.5 py-2.5 pl-4 pr-3">
<div className="flex items-center gap-2">
- <span className="min-w-0 flex-1 truncate text-ui-12p5 font-medium text-foreground">
- {job.presentation?.label ?? repoLabel(job.repoId)}
- <span className="text-muted-foreground">
- {job.presentation
- ? ` · ${repoLabel(job.repoId)}`
- : variantSuffix(job)}
- </span>
- </span>
- {job.state === "complete" && (
+ <RowTitle job={subject} />
+ {job.state === "complete" && !starting && (
<HugeiconsIcon
icon={CheckmarkCircle02Icon}
strokeWidth={2}
className="size-4 shrink-0 text-status-success"
/>
)}
- {job.state === "error" && (
+ {job.state === "error" && !starting && (
<HugeiconsIcon
icon={Alert02Icon}
strokeWidth={2}
@@ -177,7 +227,7 @@ function DownloadRow({ jobKey }: { jobKey: string }) {
<button
type="button"
aria-label={active ? "Cancel download" : "Dismiss"}
- disabled={job.state === "cancelling"}
+ disabled={job.state === "cancelling" || starting}
onClick={() =>
active
? void downloadManager.cancel(job.key)
@@ -200,15 +250,7 @@ function DownloadRow({ jobKey }: { jobKey: string }) {
</TooltipContent>
</Tooltip>
</div>
- {job.presentation ? (
- <div className="truncate text-ui-10p5 text-muted-foreground">
- {job.presentation.filename}
- </div>
- ) : isRequiredAssetJob(job) && job.checkpoint === false ? (
- <div className="text-ui-10p5 text-muted-foreground">
- {REQUIRED_ASSET_NOTE}
- </div>
- ) : null}
+ <RowDetail job={subject} />
{active ? (
<DownloadProgressBar
progress={progress}
@@ -218,7 +260,7 @@ function DownloadRow({ jobKey }: { jobKey: string }) {
activity={job.activity}
/>
) : null}
- {job.details?.length ? (
+ {!starting && job.details?.length ? (
<details className="text-ui-11">
<summary>Installation details</summary>
<pre className="max-h-40 overflow-auto whitespace-pre-wrap break-all">
@@ -226,7 +268,9 @@ function DownloadRow({ jobKey }: { jobKey: string }) {
</pre>
</details>
) : null}
- {terminal || job.state === "cancelling" || job.error ? (
+ {starting ? (
+ <StartingLine />
+ ) : terminal || job.state === "cancelling" || job.error ? (
<div className="px-0 text-ui-11 text-muted-foreground tabular-nums">
<StatusLine job={job} />
</div>
@@ -255,9 +299,23 @@ export function DownloadManagerPanel({
const stagedQueues = useStagedDownloadQueues((s) => s.queues);
const jobs = useDownloadManagerStore((s) => s.jobs);
const queued = [...hubQueued, ...queuedStagedEntries(stagedQueues, jobs)];
- const activeCount = useDownloadManagerStore(selectActiveJobCount) + queued.length;
+ const pendingStarts = usePendingStarts((s) => s.starts);
+ const pending = visiblePendingStarts(pendingStarts, jobs, queued);
+ const unlistedStarts = pending.filter((start) => !(start.key in jobs));
+ const startingByKey = new Map(
+ pending.map((start) => [start.key, start] as const),
+ );
+ const activeCount =
+ useDownloadManagerStore(selectActiveJobCount) +
+ queued.length +
+ pending.length;
- if (!enabled || (jobKeys.length === 0 && queued.length === 0)) return null;
+ if (
+ !enabled ||
+ (jobKeys.length === 0 && queued.length === 0 && pending.length === 0)
+ ) {
+ return null;
+ }
const headerLabel =
activeCount > 0
@@ -319,12 +377,19 @@ export function DownloadManagerPanel({
</div>
<ul className="max-h-[60dvh] divide-y divide-foreground/[0.06] overflow-y-auto [scrollbar-width:thin]">
{jobKeys.map((jobKey) => (
- <DownloadRow key={jobKey} jobKey={jobKey} />
+ <DownloadRow
+ key={jobKey}
+ jobKey={jobKey}
+ pendingStart={startingByKey.get(jobKey)}
+ />
))}
{queued.map((entry, i) => <li key={`${entry.planId}:${i}`} className="flex flex-col gap-1.5 py-2.5 pl-4 pr-3">
<span className="truncate text-ui-12p5 font-medium">{entry.repoId}<span className="text-muted-foreground"> · {entry.checkpoint !== false ? "Model file" : assetLabel(entry, "Required assets")}</span></span>
<span className="text-ui-11 text-muted-foreground">{entry.checkpoint !== false ? "Queued" : `Queued · ${REQUIRED_ASSET_NOTE}`}</span>
</li>)}
+ {unlistedStarts.map((start) => (
+ <PendingStartRow key={start.key} start={start} />
+ ))}
</ul>
</div>
)}
diff --git a/studio/frontend/src/features/hub/download-manager/pending-starts.ts b/studio/frontend/src/features/hub/download-manager/pending-starts.ts
new file mode 100644
index 00000000000..75f6a6f5871
--- /dev/null
+++ b/studio/frontend/src/features/hub/download-manager/pending-starts.ts
@@ -0,0 +1,75 @@
+// 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 { create } from "zustand";
+import { DOWNLOAD_KIND, type DownloadKind } from "./constants";
+import { ACTIVE_STATES } from "./download-manager-config";
+import { jobKeyOf } from "./download-manager-state";
+import type {
+ DownloadPresentation,
+ DownloadRequest,
+ ManagedDownload,
+} from "./download-manager-types";
+
+export interface PendingStart {
+ key: string;
+ kind: DownloadKind;
+ repoId: string;
+ variant: string | null;
+ presentation?: DownloadPresentation;
+ checkpoint?: boolean;
+ scopedFiles?: string[];
+}
+
+export const usePendingStarts = create<{
+ starts: Record<string, PendingStart>;
+}>(() => ({ starts: {} }));
+
+export function publishPendingStart(
+ key: string,
+ req: DownloadRequest,
+): PendingStart {
+ const start: PendingStart = {
+ key,
+ kind: req.kind,
+ repoId: req.repoId,
+ variant: req.variant,
+ ...(req.presentation ? { presentation: req.presentation } : {}),
+ ...(req.checkpoint !== undefined ? { checkpoint: req.checkpoint } : {}),
+ ...(req.files ? { scopedFiles: req.files } : {}),
+ };
+ usePendingStarts.setState(({ starts }) => ({
+ starts: { ...starts, [key]: start },
+ }));
+ return start;
+}
+
+export function retirePendingStart(start: PendingStart): void {
+ usePendingStarts.setState(({ starts }) => {
+ if (starts[start.key] !== start) return { starts };
+ const next = { ...starts };
+ delete next[start.key];
+ return { starts: next };
+ });
+}
+
+export function resetPendingStarts(): void {
+ usePendingStarts.setState({ starts: {} });
+}
+
+export function visiblePendingStarts(
+ starts: Record<string, PendingStart>,
+ jobs: Record<string, Pick<ManagedDownload, "state">>,
+ queued: readonly { repoId: string; variant: string | null }[],
+): PendingStart[] {
+ const queuedKeys = new Set(
+ queued.map((entry) =>
+ jobKeyOf(DOWNLOAD_KIND.MODEL, entry.repoId, entry.variant),
+ ),
+ );
+ return Object.values(starts).filter((start) => {
+ const job = jobs[start.key];
+ if (job && ACTIVE_STATES.has(job.state)) return false;
+ return !queuedKeys.has(start.key);
+ });
+}
diff --git a/studio/frontend/src/features/hub/download-manager/staged-download-queue.ts b/studio/frontend/src/features/hub/download-manager/staged-download-queue.ts
index 2d3a1e280ec..aeb3983c24e 100644
--- a/studio/frontend/src/features/hub/download-manager/staged-download-queue.ts
+++ b/studio/frontend/src/features/hub/download-manager/staged-download-queue.ts
@@ -56,7 +56,15 @@ export function queuedStagedEntries(
(entry.files.length === job.scopedFiles?.length &&
entry.files.every((file) => job.scopedFiles?.includes(file)))),
);
- return active ? [] : [{ ...entry, planId: `staged:${owner}:${index}` }];
+ return active
+ ? []
+ : [
+ {
+ ...entry,
+ planId: `staged:${owner}:${index}`,
+ variant: entry.ggufVariant ?? scopedVariant(scopeId),
+ },
+ ];
}),
);
}
diff --git a/studio/frontend/src/features/hub/download-manager/transport-conflict.ts b/studio/frontend/src/features/hub/download-manager/transport-conflict.ts
index 1164576bb62..b5c6e73dae9 100644
--- a/studio/frontend/src/features/hub/download-manager/transport-conflict.ts
+++ b/studio/frontend/src/features/hub/download-manager/transport-conflict.ts
@@ -29,6 +29,7 @@ import {
setConflict,
} from "./download-manager-state";
import { downloadDirForRequest } from "./download-location";
+import { publishPendingStart, retirePendingStart } from "./pending-starts";
import { startJob } from "./poll-loop";
import {
currentRoute,
@@ -148,6 +149,7 @@ async function runWithPendingStartGuard(
return "started";
}
runtimeRegistry.pendingStartRepoKeys.add(startKey);
+ const start = publishPendingStart(startKey, req);
try {
return await action();
} catch (error) {
@@ -155,6 +157,7 @@ async function runWithPendingStartGuard(
return "error";
} finally {
runtimeRegistry.pendingStartRepoKeys.delete(startKey);
+ retirePendingStart(start);
}
}
diff --git a/studio/frontend/src/features/hub/download-manager/use-hub-download-queue.ts b/studio/frontend/src/features/hub/download-manager/use-hub-download-queue.ts
index aa6264c5c84..1afca931fb4 100644
--- a/studio/frontend/src/features/hub/download-manager/use-hub-download-queue.ts
+++ b/studio/frontend/src/features/hub/download-manager/use-hub-download-queue.ts
@@ -117,6 +117,6 @@ export function useQueuedHubEntries() {
e.files.every((f) => j.scopedFiles?.includes(f)),
),
)
- .map((e) => ({ ...e, planId: p.id })),
+ .map((e) => ({ ...e, planId: p.id, variant: "@hub-assets" })),
);
}
diff --git a/studio/frontend/tests/download-panel-not-permanent.test.ts b/studio/frontend/tests/download-panel-not-permanent.test.ts
index eca81a19bbf..4bdd7fe0275 100644
--- a/studio/frontend/tests/download-panel-not-permanent.test.ts
+++ b/studio/frontend/tests/download-panel-not-permanent.test.ts
@@ -115,7 +115,7 @@ function isEmptyTest(node: ts.Node, jobKeys: string): boolean {
type Truth = true | false | null;
function underAnEmptyList(node: ts.Node, jobKeys: string): Truth {
- // Queued plans show before their first job exists, so the panel hides only when both are empty.
+ // Queued plans and preflight starts show before any job exists.
const declarations = panelComponent().body?.statements.flatMap(statement =>
ts.isVariableStatement(statement) ? [...statement.declarationList.declarations] : []
) ?? [];
@@ -130,7 +130,15 @@ function underAnEmptyList(node: ts.Node, jobKeys: string): Truth {
const queued = (combined ?? declarations.find(declaration =>
declaration.initializer?.getText() === "useQueuedHubEntries()"
))?.name.getText();
- if (isEmptyTest(node, jobKeys) || (queued && isEmptyTest(node, queued))) return true;
+ const pending = declarations.find(declaration =>
+ declaration.initializer && ts.isCallExpression(declaration.initializer) &&
+ declaration.initializer.expression.getText() === "visiblePendingStarts"
+ )?.name.getText();
+ if (
+ isEmptyTest(node, jobKeys) ||
+ (queued && isEmptyTest(node, queued)) ||
+ (pending && isEmptyTest(node, pending))
+ ) return true;
if (ts.isParenthesizedExpression(node)) {
return underAnEmptyList(node.expression, jobKeys);
}
diff --git a/studio/frontend/tests/download-pending-start.test.ts b/studio/frontend/tests/download-pending-start.test.ts
new file mode 100644
index 00000000000..23e612dd267
--- /dev/null
+++ b/studio/frontend/tests/download-pending-start.test.ts
@@ -0,0 +1,281 @@
+// 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 assert from "node:assert/strict";
+import test, { after } from "node:test";
+import { register } from "node:module";
+
+import { installLocalStorageFake, readSrc } from "./helpers/kit.ts";
+
+register("./helpers/download-lifecycle-resolver.mjs", import.meta.url);
+
+const { storage } = installLocalStorageFake();
+Object.assign(globalThis.window, {
+ location: { protocol: "http:", pathname: "/chat" },
+ setTimeout: globalThis.setTimeout.bind(globalThis),
+ clearTimeout: globalThis.clearTimeout.bind(globalThis),
+});
+storage.setItem("unsloth.studio.transportMode", "xet");
+
+const originalFetch = globalThis.fetch;
+after(() => {
+ globalThis.fetch = originalFetch;
+});
+
+const { requestStart } =
+ await import("../src/features/hub/download-manager/transport-conflict.ts");
+const { jobKeyOf, removeJob, useDownloadManagerStore } =
+ await import("../src/features/hub/download-manager/download-manager-state.ts");
+const { finalize } =
+ await import("../src/features/hub/download-manager/poll-loop.ts");
+const {
+ publishPendingStart,
+ resetPendingStarts,
+ retirePendingStart,
+ usePendingStarts,
+ visiblePendingStarts,
+} = await import("../src/features/hub/download-manager/pending-starts.ts");
+
+function json(body: unknown): Response {
+ return Response.json(body, { status: 200 });
+}
+
+const capabilities = {
+ http: { available: true, reason: null },
+ xet: { available: true, reason: null },
+ auto_resolves_to: "xet",
+ auto_reason: null,
+};
+
+type StartAnswer = "accepted" | "rejected" | "unreachable";
+
+function stubBackend({ start = "accepted" }: { start?: StartAnswer } = {}) {
+ let release!: () => void;
+ let markRequested!: () => void;
+ const requested = new Promise<void>((resolve) => {
+ markRequested = resolve;
+ });
+ const held = new Promise<Response>((resolve) => {
+ release = () => resolve(json({ downloads: [] }));
+ });
+ globalThis.fetch = (async (input: RequestInfo | URL) => {
+ const url = String(input);
+ if (url.startsWith("/api/studio/download-transport-capabilities")) {
+ return json(capabilities);
+ }
+ if (url.startsWith("/api/hub/active-downloads")) {
+ markRequested();
+ return held;
+ }
+ if (url.startsWith("/api/hub/transport-status")) {
+ return json({ has_partial: false, last_transport: null, resumable: false });
+ }
+ if (url === "/api/system/disk") {
+ return new Response(null, { status: 503 });
+ }
+ if (url === "/api/hub/download") {
+ if (start === "unreachable") throw new Error("backend down");
+ return json({
+ accepted: start === "accepted",
+ attached: false,
+ state: start === "accepted" ? "running" : "deleting",
+ generation: 1,
+ transport: "xet",
+ job_key: "backend-key",
+ });
+ }
+ if (url === "/api/settings/xet-notice/reserve") {
+ return json({ granted: false, shown: 3, limit: 3 });
+ }
+ throw new Error(`Unexpected request: ${url}`);
+ }) as typeof fetch;
+ return { requested, release: () => release() };
+}
+
+test("a requested start is visible while its preflight runs, until the backend accepts it", async () => {
+ const backend = stubBackend();
+ const request = {
+ kind: "model" as const,
+ repoId: "org/pending-model",
+ variant: "Q4_K_M",
+ expectedBytes: 4096,
+ presentation: {
+ label: "Pending model",
+ filename: "pending-q4_k_m.gguf",
+ expectedBytes: 4096,
+ },
+ };
+ const key = jobKeyOf(request.kind, request.repoId, request.variant);
+ assert.deepEqual(usePendingStarts.getState().starts, {});
+
+ const starting = requestStart(request);
+ await backend.requested;
+ assert.deepEqual(usePendingStarts.getState().starts, {
+ [key]: {
+ key,
+ kind: "model",
+ repoId: request.repoId,
+ variant: request.variant,
+ presentation: request.presentation,
+ },
+ });
+ assert.equal(
+ visiblePendingStarts(
+ usePendingStarts.getState().starts,
+ useDownloadManagerStore.getState().jobs,
+ [],
+ ).length,
+ 1,
+ );
+
+ assert.equal(await requestStart(request), "busy");
+ assert.deepEqual(Object.keys(usePendingStarts.getState().starts), [key]);
+
+ backend.release();
+ assert.equal(await starting, "started");
+ assert.deepEqual(usePendingStarts.getState().starts, {});
+ assert.equal(useDownloadManagerStore.getState().jobs[key]?.state, "running");
+
+ finalize(key, "complete");
+ removeJob(key);
+});
+
+test("a start the backend cannot be reached for leaves no pending entry behind", async () => {
+ const backend = stubBackend({ start: "unreachable" });
+ const request = {
+ kind: "model" as const,
+ repoId: "org/refused-model",
+ variant: "Q8_0",
+ expectedBytes: 4096,
+ };
+ const key = jobKeyOf(request.kind, request.repoId, request.variant);
+
+ const starting = requestStart(request);
+ backend.release();
+
+ assert.notEqual(await starting, "started");
+ assert.deepEqual(usePendingStarts.getState().starts, {});
+ removeJob(key);
+});
+
+test("a start the backend rejects ends as an error row with no pending entry behind it", async () => {
+ const backend = stubBackend({ start: "rejected" });
+ const request = {
+ kind: "model" as const,
+ repoId: "org/rejected-model",
+ variant: "Q5_K_M",
+ expectedBytes: 4096,
+ };
+ const key = jobKeyOf(request.kind, request.repoId, request.variant);
+
+ const starting = requestStart(request);
+ backend.release();
+
+ assert.notEqual(await starting, "started");
+ const job = useDownloadManagerStore.getState().jobs[key];
+ assert.equal(job?.state, "error");
+ assert.match(job?.error ?? "", /being removed/);
+ assert.deepEqual(usePendingStarts.getState().starts, {});
+ removeJob(key);
+});
+
+test("retiring a start removes only the entry that was published for it", () => {
+ const request = {
+ kind: "model" as const,
+ repoId: "org/reset-model",
+ variant: "Q4_K_M",
+ expectedBytes: 4096,
+ };
+ const key = jobKeyOf(request.kind, request.repoId, request.variant);
+
+ const first = publishPendingStart(key, request);
+ resetPendingStarts();
+ const second = publishPendingStart(key, request);
+
+ retirePendingStart(first);
+ assert.equal(usePendingStarts.getState().starts[key], second);
+ retirePendingStart(second);
+ assert.deepEqual(usePendingStarts.getState().starts, {});
+});
+
+test("visible pending starts yield to an active job and to a queued plan for the same transfer", () => {
+ const model = {
+ key: "model:org/a#q4_k_m",
+ kind: "model" as const,
+ repoId: "org/a",
+ variant: "Q4_K_M",
+ };
+ const dataset = {
+ key: "dataset:org/a",
+ kind: "dataset" as const,
+ repoId: "org/a",
+ variant: null,
+ };
+ const starts = { [model.key]: model, [dataset.key]: dataset };
+
+ assert.deepEqual(visiblePendingStarts(starts, {}, []), [model, dataset]);
+ assert.deepEqual(
+ visiblePendingStarts(starts, { [model.key]: { state: "running" as const } }, []),
+ [dataset],
+ );
+ assert.deepEqual(
+ visiblePendingStarts(starts, { [model.key]: { state: "cancelled" as const } }, []),
+ [model, dataset],
+ );
+ assert.deepEqual(
+ visiblePendingStarts(starts, {}, [{ repoId: "Org/A", variant: "q4_k_m" }]),
+ [dataset],
+ );
+ assert.deepEqual(
+ visiblePendingStarts(starts, {}, [{ repoId: "org/a", variant: "@hub-assets" }]),
+ [model, dataset],
+ );
+});
+
+test("a restart inside a finished row's linger keeps that row and marks it starting", async () => {
+ const request = {
+ kind: "model" as const,
+ repoId: "org/retried-model",
+ variant: "Q4_K_M",
+ expectedBytes: 4096,
+ };
+ const key = jobKeyOf(request.kind, request.repoId, request.variant);
+ stubBackend().release();
+ assert.equal(await requestStart(request), "started");
+ finalize(key, "cancelled");
+ assert.equal(useDownloadManagerStore.getState().jobs[key]?.state, "cancelled");
+
+ const backend = stubBackend();
+ const restarting = requestStart(request);
+ await backend.requested;
+ const { jobs } = useDownloadManagerStore.getState();
+ const { starts } = usePendingStarts.getState();
+ assert.equal(jobs[key]?.state, "cancelled");
+ assert.deepEqual(Object.keys(starts), [key]);
+ assert.equal(visiblePendingStarts(starts, jobs, []).length, 1);
+
+ backend.release();
+ assert.equal(await restarting, "started");
+ assert.equal(useDownloadManagerStore.getState().jobs[key]?.state, "running");
+ assert.deepEqual(usePendingStarts.getState().starts, {});
+
+ finalize(key, "complete");
+ removeJob(key);
+});
+
+test("the panel derives a start's own row and a listed row's starting state from the same visible set, and a reused row describes the pending start", () => {
+ const panel = readSrc("features/hub/download-manager/download-manager-panel.tsx");
+ assert.match(
+ panel,
+ /const unlistedStarts = pending\.filter\(\(start\) => !\(start\.key in jobs\)\)/,
+ );
+ assert.match(
+ panel,
+ /const startingByKey = new Map\(\s*pending\.map\(\(start\) => \[start\.key, start\] as const\),?\s*\)/,
+ );
+ assert.match(panel, /pendingStart=\{startingByKey\.get\(jobKey\)\}/);
+ assert.match(panel, /const subject = pendingStart \?\? job/);
+ assert.match(panel, /<RowTitle job=\{subject\} \/>/);
+ assert.match(panel, /<RowDetail job=\{subject\} \/>/);
+ assert.match(panel, /\{!starting && job\.details\?\.length \? \(/);
+});