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: name the llama.cpp backend in the install log, and stop labelling Windows ROCm torch as CPU (#10370)

Daniel Han9b302761bd57
diff --git a/studio/backend/tests/test_torch_step_label.py b/studio/backend/tests/test_torch_step_label.py
new file mode 100644
index 00000000000..8bd52050c11
--- /dev/null
+++ b/studio/backend/tests/test_torch_step_label.py
@@ -0,0 +1,428 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Tests for _torch_step_label: which backend it names, and what answering costs.
+
+rocminfo and amd-smi ship with the HIP SDK, not with AMD's bundled-runtime wheels, so a
+working Windows ROCm host printed "torch check (cpu)". Answering with `import torch`
+instead cost up to the probe's 90s timeout before _progress() emitted anything.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+_INSTALL_SCRIPT = Path(__file__).resolve().parents[2] / "install_python_stack.py"
+
+
+def _load_module(monkeypatch):
+ sys.modules.pop("install_python_stack", None)
+ monkeypatch.syspath_prepend(str(_INSTALL_SCRIPT.parent))
+ import install_python_stack
+
+ return install_python_stack
+
+
+# "amd_bundled" is the Strix Halo case: no rocminfo, no amd-smi, only version.py knows.
+_HARDWARE = {
+ "nvidia": dict(nvidia = True, rocm_probe = False, hip = "", label = "2.9.1+cu128"),
+ "amd_tooling": dict(nvidia = False, rocm_probe = True, hip = "6.4.43483", label = "2.8.0+rocm6.4"),
+ "amd_bundled": dict(
+ nvidia = False, rocm_probe = False, hip = "6.4.43483-a1", label = "2.8.0a0+rocmsdk20250901"
+ ),
+ "xpu": dict(nvidia = False, rocm_probe = False, hip = "", label = "2.9.1+xpu"),
+ "cpu": dict(nvidia = False, rocm_probe = False, hip = "", label = "2.9.1+cpu"),
+ "no_torch": dict(nvidia = False, rocm_probe = False, hip = "", label = ""),
+}
+
+_PLATFORMS = {
+ "windows": dict(is_windows = True, is_macos = False, is_wsl = False),
+ "linux": dict(is_windows = False, is_macos = False, is_wsl = False),
+ "wsl": dict(is_windows = False, is_macos = False, is_wsl = True),
+ "macos": dict(is_windows = False, is_macos = True, is_wsl = False),
+}
+
+
+def _prepare(
+ monkeypatch,
+ *,
+ platform_name,
+ hardware_name,
+ known_backend = "",
+ warm_probe = None,
+):
+ """One matrix cell, stubbed only at names both trees have, so this file discriminates.
+
+ Returns the recorded _probe_torch_runtime calls; empty means the label cost nothing.
+ """
+ mod = _load_module(monkeypatch)
+ plat = _PLATFORMS[platform_name]
+ hw = _HARDWARE[hardware_name]
+
+ monkeypatch.setattr(mod, "_TORCH_BACKEND", known_backend)
+ monkeypatch.setattr(mod, "IS_WINDOWS", plat["is_windows"])
+ monkeypatch.setattr(mod, "IS_MACOS", plat["is_macos"])
+ monkeypatch.setattr(mod, "IS_LINUX", not plat["is_windows"] and not plat["is_macos"])
+ monkeypatch.setattr(mod, "_is_wsl", lambda: plat["is_wsl"])
+ monkeypatch.setattr(mod, "_has_usable_nvidia_gpu", lambda: hw["nvidia"])
+ monkeypatch.setattr(mod, "_has_rocm_gpu", lambda: hw["rocm_probe"])
+ # raising = False: _torch_hip_version_on_disk does not exist on the pre-fix tree.
+ monkeypatch.setattr(mod, "_torch_hip_version_on_disk", lambda: hw["hip"], raising = False)
+ monkeypatch.setattr(mod, "_installed_torch_version_label", lambda: hw["label"])
+ monkeypatch.setattr(mod, "_TORCH_RUNTIME_PROBE", warm_probe)
+
+ probe_calls = []
+ probe_result = (
+ warm_probe
+ if warm_probe is not None
+ else (True, bool(hw["label"]), hw["label"] or None, hw["hip"], "")
+ )
+
+ def _recording_probe():
+ # Mirror the real memo: only a COLD entry is an interpreter start.
+ if mod._TORCH_RUNTIME_PROBE is not None:
+ return mod._TORCH_RUNTIME_PROBE
+ probe_calls.append(probe_result)
+ mod._TORCH_RUNTIME_PROBE = probe_result
+ return probe_result
+
+ monkeypatch.setattr(mod, "_probe_torch_runtime", _recording_probe)
+ monkeypatch.setattr(
+ mod.subprocess,
+ "run",
+ lambda *a, **k: pytest.fail(f"a progress label must not start a subprocess: {a!r}"),
+ )
+ return mod, probe_calls
+
+
+# UNSLOTH_TORCH_BACKEND unset. Only Windows consults torch's own build, which is what
+# keeps Linux, WSL and macOS on their pre-existing answers.
+_MATRIX = {
+ ("windows", "nvidia"): "cuda",
+ ("windows", "amd_tooling"): "rocm",
+ ("windows", "amd_bundled"): "rocm", # the regression this PR fixes
+ ("windows", "xpu"): "cpu",
+ ("windows", "cpu"): "cpu",
+ ("windows", "no_torch"): "cpu",
+ ("linux", "nvidia"): "cuda",
+ ("linux", "amd_tooling"): "rocm",
+ ("linux", "amd_bundled"): "cpu", # no rocminfo on Linux means no ROCm claim
+ ("linux", "xpu"): "cpu",
+ ("linux", "cpu"): "cpu",
+ ("linux", "no_torch"): "cpu",
+ ("wsl", "nvidia"): "cuda",
+ ("wsl", "amd_tooling"): "rocm",
+ ("wsl", "amd_bundled"): "cpu",
+ ("wsl", "xpu"): "cpu",
+ ("wsl", "cpu"): "cpu",
+ ("wsl", "no_torch"): "cpu",
+ # macOS rows pin actual behaviour, not supported configurations.
+ ("macos", "nvidia"): "cuda",
+ ("macos", "amd_tooling"): "rocm",
+ ("macos", "amd_bundled"): "cpu",
+ ("macos", "xpu"): "cpu",
+ ("macos", "cpu"): "cpu",
+ ("macos", "no_torch"): "cpu",
+}
+
+
[email protected](("platform_name", "hardware_name"), sorted(_MATRIX))
+def test_label_over_the_platform_and_hardware_matrix(monkeypatch, platform_name, hardware_name):
+ mod, _calls = _prepare(monkeypatch, platform_name = platform_name, hardware_name = hardware_name)
+ expected = _MATRIX[(platform_name, hardware_name)]
+ assert mod._torch_step_label("check") == f"torch check ({expected})"
+
+
[email protected](("platform_name", "hardware_name"), sorted(_MATRIX))
[email protected]("suffix", ["check", "final", "flavor"])
+def test_every_suffix_keeps_the_same_backend(monkeypatch, platform_name, hardware_name, suffix):
+ mod, _calls = _prepare(monkeypatch, platform_name = platform_name, hardware_name = hardware_name)
+ expected = _MATRIX[(platform_name, hardware_name)]
+ assert mod._torch_step_label(suffix) == f"torch {suffix} ({expected})"
+
+
[email protected]("known_backend", ["cuda", "rocm", "cpu", "xpu", "gfx1151-custom"])
[email protected]("platform_name", sorted(_PLATFORMS))
+def test_an_explicit_backend_wins_over_every_probe(monkeypatch, known_backend, platform_name):
+ mod, _calls = _prepare(
+ monkeypatch,
+ platform_name = platform_name,
+ # deliberately contradictory hardware: nothing below may override the pin
+ hardware_name = "amd_bundled",
+ known_backend = known_backend,
+ )
+ assert mod._torch_step_label("check") == f"torch check ({known_backend})"
+
+
+def test_an_explicit_backend_consults_no_detector(monkeypatch):
+ mod = _load_module(monkeypatch)
+ monkeypatch.setattr(mod, "_TORCH_BACKEND", "cuda")
+ for name in (
+ "_has_usable_nvidia_gpu",
+ "_has_rocm_gpu",
+ "_installed_torch_is_windows_rocm",
+ "_installed_torch_is_windows_rocm_cheap",
+ "_torch_hip_version_on_disk",
+ "_installed_torch_version_label",
+ ):
+ monkeypatch.setattr(
+ mod,
+ name,
+ lambda *_a, **_k: pytest.fail(f"{name} must not run for a pinned backend"),
+ raising = False,
+ )
+ assert mod._torch_step_label("check") == "torch check (cuda)"
+
+
+def test_nvidia_still_takes_priority(monkeypatch):
+ mod, _calls = _prepare(monkeypatch, platform_name = "windows", hardware_name = "nvidia")
+ monkeypatch.setattr(mod, "_torch_hip_version_on_disk", lambda: "6.4.43483")
+ assert mod._torch_step_label("check") == "torch check (cuda)"
+
+
+def test_the_rocm_probe_still_answers(monkeypatch):
+ mod, _calls = _prepare(monkeypatch, platform_name = "linux", hardware_name = "amd_tooling")
+ monkeypatch.setattr(mod, "_torch_hip_version_on_disk", lambda: "")
+ monkeypatch.setattr(mod, "_installed_torch_version_label", lambda: "")
+ assert mod._torch_step_label("check") == "torch check (rocm)"
+
+
+def test_a_windows_rocm_torch_is_rocm_even_with_no_rocm_tooling(monkeypatch):
+ mod, _calls = _prepare(monkeypatch, platform_name = "windows", hardware_name = "amd_bundled")
+ assert mod._torch_step_label("check") == "torch check (rocm)"
+
+
+def test_a_windows_rocm_torch_is_recognised_by_version_string_alone(monkeypatch):
+ mod, _calls = _prepare(monkeypatch, platform_name = "windows", hardware_name = "amd_bundled")
+ monkeypatch.setattr(mod, "_torch_hip_version_on_disk", lambda: "")
+ assert mod._torch_step_label("check") == "torch check (rocm)"
+
+
+def test_a_host_with_neither_is_still_cpu(monkeypatch):
+ mod, _calls = _prepare(monkeypatch, platform_name = "windows", hardware_name = "cpu")
+ assert mod._torch_step_label("check") == "torch check (cpu)"
+
+
[email protected]("platform_name", sorted(_PLATFORMS))
[email protected]("hardware_name", sorted(_HARDWARE))
+def test_the_label_never_runs_the_torch_probe(monkeypatch, platform_name, hardware_name):
+ mod, probe_calls = _prepare(
+ monkeypatch, platform_name = platform_name, hardware_name = hardware_name
+ )
+ mod._torch_step_label("check")
+ assert probe_calls == []
+
+
+def test_the_label_leaves_the_probe_memo_cold(monkeypatch):
+ """The discriminating case: pre-fix the label probed here, and pip_install then
+ invalidated the memo three statements later, so the 90s was not even amortised.
+ """
+ mod, probe_calls = _prepare(monkeypatch, platform_name = "windows", hardware_name = "amd_bundled")
+ assert mod._TORCH_RUNTIME_PROBE is None
+ assert mod._torch_step_label("check") == "torch check (rocm)"
+ assert probe_calls == []
+ assert mod._TORCH_RUNTIME_PROBE is None
+
+
+def test_the_label_reuses_a_warm_probe_instead_of_the_disk(monkeypatch):
+ warm = (True, True, "2.8.0a0+rocmsdk20250901", "6.4.43483", "")
+ mod, probe_calls = _prepare(
+ monkeypatch,
+ platform_name = "windows",
+ hardware_name = "cpu", # disk says CPU
+ warm_probe = warm,
+ )
+ disk_reads = []
+ monkeypatch.setattr(
+ mod,
+ "_torch_hip_version_on_disk",
+ lambda: disk_reads.append("hip") or "",
+ raising = False,
+ )
+ assert mod._torch_step_label("check") == "torch check (rocm)"
+ assert probe_calls == [] # a warm memo is reused, never re-probed
+ assert disk_reads == [] # and the disk is not consulted behind it
+
+
+def test_a_warm_negative_probe_is_believed(monkeypatch):
+ warm = (True, True, "2.9.1+cpu", "", "")
+ mod, probe_calls = _prepare(
+ monkeypatch,
+ platform_name = "windows",
+ hardware_name = "amd_bundled",
+ warm_probe = warm,
+ )
+ assert mod._torch_step_label("check") == "torch check (cpu)"
+ assert probe_calls == []
+
+
+def test_an_inconclusive_warm_probe_is_not_read_as_rocm(monkeypatch):
+ mod, probe_calls = _prepare(
+ monkeypatch,
+ platform_name = "windows",
+ hardware_name = "cpu",
+ warm_probe = (False, False, None, "", ""),
+ )
+ assert mod._torch_step_label("check") == "torch check (cpu)"
+ assert probe_calls == []
+
+
[email protected]("platform_name", ["linux", "wsl", "macos"])
+def test_non_windows_never_touches_the_torch_build(monkeypatch, platform_name):
+ """Linux, WSL and macOS short-circuit, so the change cannot alter their answer."""
+ mod, probe_calls = _prepare(
+ monkeypatch, platform_name = platform_name, hardware_name = "amd_bundled"
+ )
+ touched = []
+ monkeypatch.setattr(
+ mod,
+ "_torch_hip_version_on_disk",
+ lambda: touched.append("hip") or "",
+ raising = False,
+ )
+ monkeypatch.setattr(
+ mod, "_installed_torch_version_label", lambda: touched.append("label") or ""
+ )
+ # Not whether the helper is called off Windows (free either way), but that nothing
+ # happens behind it.
+ assert mod._torch_step_label("check") == "torch check (cpu)"
+ assert touched == []
+ assert probe_calls == []
+
+
+# Skipped, not failed, on a tree without the helper: these hold it, not discriminate.
+
+
+def _requires_hip_reader(mod):
+ if not hasattr(mod, "_torch_hip_version_on_disk"):
+ pytest.skip("_torch_hip_version_on_disk does not exist on this tree")
+
+
+def _fake_torch_on_path(
+ monkeypatch,
+ tmp_path,
+ version_py,
+ *,
+ as_directory = False,
+):
+ """Put a stand-in torch package where find_spec will see it.
+
+ find_spec returns sys.modules[name].__spec__ for an already-imported module, so on a
+ runner that has torch, prepending sys.path alone leaves the fixture ignored.
+ """
+ torch_dir = tmp_path / "torch"
+ torch_dir.mkdir(exist_ok = True)
+ (torch_dir / "__init__.py").write_text("", encoding = "utf-8")
+ if as_directory:
+ (torch_dir / "version.py").mkdir()
+ else:
+ (torch_dir / "version.py").write_text(version_py, encoding = "utf-8")
+ monkeypatch.delitem(sys.modules, "torch", raising = False)
+ monkeypatch.delitem(sys.modules, "torch.version", raising = False)
+ monkeypatch.syspath_prepend(str(tmp_path))
+ return torch_dir
+
+
+_VERSION_PY_ROCM = """\
+from typing import Optional
+
+__all__ = ['__version__', 'debug', 'cuda', 'git_version', 'hip', 'xpu']
+__version__ = '2.8.0a0+rocmsdk20250901'
+debug = False
+cuda: Optional[str] = None
+git_version = 'deadbeef'
+hip: Optional[str] = '6.4.43483-a1b2c3d'
+xpu: Optional[str] = None
+"""
+
+_VERSION_PY_CUDA = """\
+from typing import Optional
+
+__all__ = ['__version__', 'debug', 'cuda', 'git_version', 'hip', 'xpu']
+__version__ = '2.9.1+cu128'
+debug = False
+cuda: Optional[str] = '12.8'
+git_version = 'deadbeef'
+hip: Optional[str] = None
+xpu: Optional[str] = None
+"""
+
+# The un-annotated form older torch builds wrote.
+_VERSION_PY_ROCM_UNANNOTATED = """\
+__version__ = '2.7.0+rocm6.3'
+hip = '6.3.42131'
+cuda = None
+"""
+
+
+ ("text", "expected"),
+ [
+ (_VERSION_PY_ROCM, "6.4.43483-a1b2c3d"),
+ (_VERSION_PY_ROCM_UNANNOTATED, "6.3.42131"),
+ (_VERSION_PY_CUDA, ""), # hip = None must not read as a HIP string
+ ("", ""),
+ ('hip = "6.9.0"\n', "6.9.0"), # double-quoted
+ ("__version__ = '2.9.1'\n", ""),
+ ("# hip = '1.0'\n", ""), # not at the start of a line after ^ anchoring
+ ],
+)
+def test_the_hip_reader_matches_only_a_quoted_value(monkeypatch, tmp_path, text, expected):
+ mod = _load_module(monkeypatch)
+ _requires_hip_reader(mod)
+ _fake_torch_on_path(monkeypatch, tmp_path, text)
+ assert mod._torch_hip_version_on_disk() == expected
+
+
+def test_the_hip_reader_survives_a_missing_torch(monkeypatch, tmp_path):
+ mod = _load_module(monkeypatch)
+ _requires_hip_reader(mod)
+ monkeypatch.setattr(
+ mod.importlib.util, "find_spec", lambda _name: (_ for _ in ()).throw(ImportError("x"))
+ )
+ assert mod._torch_hip_version_on_disk() == ""
+
+
+def test_the_hip_reader_survives_an_unreadable_version_py(monkeypatch, tmp_path):
+ mod = _load_module(monkeypatch)
+ _requires_hip_reader(mod)
+ # version.py is a directory: the read raises OSError, which must be swallowed.
+ _fake_torch_on_path(monkeypatch, tmp_path, "", as_directory = True)
+ assert mod._torch_hip_version_on_disk() == ""
+
+
+def test_the_hip_reader_starts_no_subprocess(monkeypatch, tmp_path):
+ mod = _load_module(monkeypatch)
+ _requires_hip_reader(mod)
+ monkeypatch.setattr(
+ mod.subprocess,
+ "run",
+ lambda *a, **k: pytest.fail("reading version.py must not start a subprocess"),
+ )
+ _fake_torch_on_path(monkeypatch, tmp_path, _VERSION_PY_ROCM)
+ assert mod._torch_hip_version_on_disk() == "6.4.43483-a1b2c3d"
+
+
+def test_the_label_on_this_real_host(monkeypatch):
+ """One unsimulated observation. Asserts the shape, so it holds on CPU and GPU alike."""
+ mod = _load_module(monkeypatch)
+ monkeypatch.setattr(mod, "_TORCH_BACKEND", "")
+ monkeypatch.setattr(mod, "_TORCH_RUNTIME_PROBE", None)
+ real_run = subprocess.run
+ calls = []
+
+ def _record(*args, **kwargs):
+ calls.append(args)
+ return real_run(*args, **kwargs)
+
+ monkeypatch.setattr(mod.subprocess, "run", _record)
+ label = mod._torch_step_label("check")
+ assert label.startswith("torch check (") and label.endswith(")")
+ assert label[len("torch check (") : -1] in {"cuda", "rocm", "cpu"}
+ # nvidia-smi/rocminfo may run; the expensive `import torch` must not.
+ assert not any("import torch" in str(a) for a in calls), calls
+ assert mod._TORCH_RUNTIME_PROBE is None
diff --git a/studio/install_python_stack.py b/studio/install_python_stack.py
index 17d7c7e7779..438ac7066d0 100644
--- a/studio/install_python_stack.py
+++ b/studio/install_python_stack.py
@@ -5135,6 +5135,44 @@ if not _TORCH_BACKEND:
_TORCH_BACKEND = "cuda"
+# Quoted values only, so the `hip: Optional[str] = None` a non-ROCm build writes is negative.
+_TORCH_VERSION_PY_HIP_RE = re.compile(r"""^hip\s*(?::[^=]*)?=\s*['"]([^'"]*)['"]""", re.MULTILINE)
+
+
+def _torch_hip_version_on_disk() -> str:
+ """torch.version.hip read from torch/version.py, launching no interpreter."""
+ try:
+ importlib.invalidate_caches()
+ spec = importlib.util.find_spec("torch")
+ except (ImportError, ValueError):
+ return ""
+ if spec is None or not spec.origin:
+ return ""
+ try:
+ text = (
+ Path(spec.origin).with_name("version.py").read_text(encoding = "utf-8", errors = "replace")
+ )
+ except OSError:
+ return ""
+ match = _TORCH_VERSION_PY_HIP_RE.search(text)
+ return match.group(1) if match else ""
+
+
+def _installed_torch_is_windows_rocm_cheap() -> bool:
+ """_installed_torch_is_windows_rocm's verdict without ever running `import torch`.
+
+ _torch_step_label runs with the probe memo cold, so the probing form spent up to its
+ 90s timeout before _progress() emitted anything, to format a string.
+ """
+ if not IS_WINDOWS:
+ return False
+ if _TORCH_RUNTIME_PROBE is not None:
+ return _installed_torch_is_windows_rocm()
+ if _torch_hip_version_on_disk():
+ return True
+ return "rocm" in _installed_torch_version_label().lower()
+
+
def _torch_step_label(suffix: str) -> str:
"""Return a progress label like 'torch check (cuda)' using the known backend.
@@ -5145,7 +5183,9 @@ def _torch_step_label(suffix: str) -> str:
if not backend:
if _has_usable_nvidia_gpu():
backend = "cuda"
- elif _has_rocm_gpu():
+ # rocminfo and amd-smi ship with the HIP SDK, not with AMD's bundled-runtime
+ # wheels, so a Windows ROCm host reads as CPU without the second operand.
+ elif _has_rocm_gpu() or _installed_torch_is_windows_rocm_cheap():
backend = "rocm"
else:
backend = "cpu"
diff --git a/studio/setup.ps1 b/studio/setup.ps1
index 4da6ff89569..9accb5fe264 100644
--- a/studio/setup.ps1
+++ b/studio/setup.ps1
@@ -576,13 +576,38 @@ function Get-InstalledLlamaPrebuiltRelease {
return $null
}
+ # An interrupted write leaves an empty marker, which deserializes to $null: reading a
+ # property off that is fatal under a caller's Set-StrictMode, and printed "@" without one.
+ if ($null -eq $payload -or $payload -isnot [System.Management.Automation.PSCustomObject]) {
+ return $null
+ }
+ if (-not ($payload.PSObject.Properties.Name -ccontains 'published_repo') -or
+ -not ($payload.PSObject.Properties.Name -ccontains 'release_tag')) {
+ return $null
+ }
if (-not $payload.published_repo -or -not $payload.release_tag) {
return $null
}
$message = "installed release: $($payload.published_repo)@$($payload.release_tag)"
- if ($payload.tag -and $payload.tag -ne $payload.release_tag) {
- $message += " (tag $($payload.tag))"
+ # tag is optional too, so it carries the same strict-mode hazard as backend.
+ $llamaTag = ""
+ if ($payload.PSObject.Properties.Name -ccontains 'tag') {
+ $llamaTag = [string]$payload.tag
+ }
+ if ($llamaTag -and $llamaTag -ne $payload.release_tag) {
+ $message += " (tag $llamaTag)"
+ }
+ # Name the backend: a Vulkan and a ROCm bundle print an identical line without it.
+ # Absent in every marker written before #8520, and a missing property is fatal under a
+ # caller's Set-StrictMode. -ccontains and the type/shape checks keep this byte-identical
+ # to the setup.sh twin, which is case-sensitive and renders non-strings differently.
+ $backendName = ""
+ if (($payload.PSObject.Properties.Name -ccontains 'backend') -and ($payload.backend -is [string])) {
+ $backendName = $payload.backend.Trim()
+ }
+ if ($backendName -match '^[A-Za-z0-9._+-]{1,32}$') {
+ $message += " -- $backendName backend"
}
return $message
}
diff --git a/studio/setup.sh b/studio/setup.sh
index 80621b062b0..09325c75267 100755
--- a/studio/setup.sh
+++ b/studio/setup.sh
@@ -775,6 +775,7 @@ installed_llama_prebuilt_release() {
[ -f "$metadata_path" ] || return 0
python - "$metadata_path" <<'PY' 2>/dev/null || true
import json
+import re
import sys
from pathlib import Path
@@ -792,6 +793,10 @@ llama_tag = str(payload.get("tag") or "").strip()
source = str(payload.get("source") or "").strip()
binary_repo = str(payload.get("binary_repo") or "").strip()
binary_tag = str(payload.get("binary_release_tag") or "").strip()
+_backend_raw = payload.get("backend")
+# Absent before #8520, and null when backend_for_install_kind() had no answer. str() on a
+# non-string would diverge from the setup.ps1 twin (Python "[1, 2]" vs PowerShell "1 2").
+backend = _backend_raw.strip() if isinstance(_backend_raw, str) else ""
if not repo or not release_tag:
raise SystemExit(0)
@@ -804,6 +809,10 @@ else:
message = f"installed release: {repo}@{release_tag}"
if llama_tag and llama_tag != release_tag:
message += f" (tag {llama_tag})"
+# Name the backend: a Vulkan and a ROCm bundle print an identical line without it. The
+# shape check keeps the line single-line and matches the setup.ps1 twin byte for byte.
+if re.fullmatch(r"[A-Za-z0-9._+-]{1,32}", backend):
+ message += f" -- {backend} backend"
print(message)
PY
}
diff --git a/tests/studio/install/test_installed_release_backend_line.py b/tests/studio/install/test_installed_release_backend_line.py
new file mode 100644
index 00000000000..2242d4494fd
--- /dev/null
+++ b/tests/studio/install/test_installed_release_backend_line.py
@@ -0,0 +1,681 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""The "installed release: ..." line, in both setup twins, against real markers.
+
+Two things this holds. `backend` is absent from every marker written before #8520
+(2026-08-13), and reading a missing property is a terminating error under a caller's
+Set-StrictMode 2.0+, so an unguarded read aborts setup on those installs. And the twins
+must render identical bytes: PowerShell prints @(1, 2) as "1 2", Python as "[1, 2]".
+
+Both functions are sliced out rather than sourced whole, because both scripts run install
+steps at load (as tests/studio_setup_ps1/Get-FunctionSource.ps1 and tests/sh/ do).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[3]
+SETUP_PS1 = PACKAGE_ROOT / "studio" / "setup.ps1"
+SETUP_SH = PACKAGE_ROOT / "studio" / "setup.sh"
+GET_FUNCTION_SOURCE = PACKAGE_ROOT / "tests" / "studio_setup_ps1" / "Get-FunctionSource.ps1"
+
+requires_pwsh = pytest.mark.skipif(
+ shutil.which("pwsh") is None, reason = "pwsh is required to run the setup.ps1 printer"
+)
+
+
+def _usable_bash():
+ """A bash that actually runs a command, or None.
+
+ shutil.which("bash") alone is wrong on Windows: C:\\Windows\\System32\\bash.exe is the
+ WSL launcher, so it is the first PATH hit even with no distro installed, and running it
+ writes "Windows Subsystem for Linux has no installed distributions." to stdout as UTF-16
+ -- which this file then compared against a printer line. setup.sh is never executed on
+ Windows anyway (_find_setup_script picks setup.ps1 there), so probe before trusting.
+ """
+ exe = shutil.which("bash")
+ if exe is None:
+ return None
+ try:
+ probe = subprocess.run(
+ [exe, "-c", "printf ok"],
+ stdout = subprocess.PIPE,
+ stderr = subprocess.DEVNULL,
+ text = True,
+ errors = "replace",
+ timeout = 60,
+ )
+ except (OSError, subprocess.TimeoutExpired):
+ return None
+ return exe if probe.stdout.strip() == "ok" else None
+
+
+BASH = _usable_bash()
+requires_bash = pytest.mark.skipif(
+ BASH is None, reason = "a working bash is required to run the setup.sh printer"
+)
+
+# 2.0 is where missing-property reads turn fatal; 3.0 and Latest keep that rule.
+STRICT_MODES = ["off", "1.0", "2.0", "3.0", "Latest"]
+
+_BASE_MARKER = {
+ "published_repo": "unslothai/llama.cpp",
+ "release_tag": "b10715-mix-86bd2d3",
+ "tag": "b10715",
+}
+_BASE_LINE = "installed release: unslothai/llama.cpp@b10715-mix-86bd2d3 (tag b10715)"
+
+
+def _marker(**overrides):
+ payload = dict(_BASE_MARKER)
+ payload.update(overrides)
+ return json.dumps(payload)
+
+
+def _with_backend(value):
+ payload = dict(_BASE_MARKER)
+ payload["backend"] = value
+ return json.dumps(payload)
+
+
+def _drop_backend_key():
+ return json.dumps(dict(_BASE_MARKER))
+
+
+# (id, raw file text or None for "no file", expected printed line)
+_CASES = [
+ # the legacy shape, which is the whole point of the guard
+ ("legacy_no_backend_key", _drop_backend_key(), _BASE_LINE),
+ ("cuda", _with_backend("cuda"), _BASE_LINE + " -- cuda backend"),
+ ("rocm", _with_backend("rocm"), _BASE_LINE + " -- rocm backend"),
+ ("vulkan", _with_backend("vulkan"), _BASE_LINE + " -- vulkan backend"),
+ ("cpu", _with_backend("cpu"), _BASE_LINE + " -- cpu backend"),
+ ("metal", _with_backend("metal"), _BASE_LINE + " -- metal backend"),
+ # an unknown name still prints: no allowlist
+ ("unknown_future_backend", _with_backend("sycl2"), _BASE_LINE + " -- sycl2 backend"),
+ (
+ "backend_with_punctuation",
+ _with_backend("cuda13.0+x-1"),
+ _BASE_LINE + " -- cuda13.0+x-1 backend",
+ ),
+ ("backend_padded", _with_backend(" vulkan "), _BASE_LINE + " -- vulkan backend"),
+ ("backend_max_length", _with_backend("a" * 32), _BASE_LINE + " -- " + "a" * 32 + " backend"),
+ ("backend_null", _with_backend(None), _BASE_LINE),
+ ("backend_empty", _with_backend(""), _BASE_LINE),
+ ("backend_whitespace", _with_backend(" "), _BASE_LINE),
+ ("backend_zero", _with_backend(0), _BASE_LINE),
+ ("backend_false", _with_backend(False), _BASE_LINE),
+ ("backend_true", _with_backend(True), _BASE_LINE),
+ ("backend_int", _with_backend(7), _BASE_LINE),
+ ("backend_float", _with_backend(1.5), _BASE_LINE),
+ ("backend_empty_list", _with_backend([]), _BASE_LINE),
+ ("backend_list", _with_backend(["rocm", "vulkan"]), _BASE_LINE),
+ ("backend_empty_object", _with_backend({}), _BASE_LINE),
+ ("backend_object", _with_backend({"name": "rocm"}), _BASE_LINE),
+ ("backend_too_long", _with_backend("a" * 33), _BASE_LINE),
+ ("backend_unicode", _with_backend("vulkän"), _BASE_LINE),
+ ("backend_emoji", _with_backend("rocm\U0001f680"), _BASE_LINE),
+ ("backend_cjk", _with_backend("显卡"), _BASE_LINE),
+ ("backend_1kib", _with_backend("v" * 1024), _BASE_LINE),
+ ("backend_64kib", _with_backend("v" * 65536), _BASE_LINE),
+ ("backend_with_space", _with_backend("vulkan gpu"), _BASE_LINE),
+ ("backend_underscore", _with_backend("windows_rocm"), _BASE_LINE + " -- windows_rocm backend"),
+ ("backend_double_quote", _with_backend('vul"kan'), _BASE_LINE),
+ ("backend_single_quote", _with_backend("vul'kan"), _BASE_LINE),
+ ("backend_backtick", _with_backend("vul`kan"), _BASE_LINE),
+ ("backend_ps_subexpression", _with_backend("$(Write-Output pwned)"), _BASE_LINE),
+ ("backend_ps_variable", _with_backend("$env:PATH"), _BASE_LINE),
+ ("backend_shell_semicolon", _with_backend("vulkan; echo pwned"), _BASE_LINE),
+ ("backend_shell_substitution", _with_backend("$(echo pwned)"), _BASE_LINE),
+ ("backend_backslash", _with_backend("vul\\kan"), _BASE_LINE),
+ ("backend_newline", _with_backend("vulkan\nrocm"), _BASE_LINE),
+ ("backend_crlf", _with_backend("vulkan\r\nrocm"), _BASE_LINE),
+ ("backend_tab", _with_backend("vul\tkan"), _BASE_LINE),
+ ("backend_ansi", _with_backend("\x1b[31mrocm\x1b[0m"), _BASE_LINE),
+ ("backend_nul", _with_backend("rocm\x00x"), _BASE_LINE),
+ # -ccontains, so a case-folded key is ignored by both rather than only by Python.
+ ("backend_key_uppercase", _marker(BACKEND = "vulkan"), _BASE_LINE),
+ ("backend_key_mixed_case", _marker(Backend = "vulkan"), _BASE_LINE),
+ (
+ "no_tag_key",
+ json.dumps({"published_repo": "unslothai/llama.cpp", "release_tag": "b10715-mix"}),
+ "installed release: unslothai/llama.cpp@b10715-mix",
+ ),
+ (
+ "tag_equals_release_tag",
+ json.dumps({"published_repo": "r/l", "release_tag": "b1", "tag": "b1", "backend": "rocm"}),
+ "installed release: r/l@b1 -- rocm backend",
+ ),
+ (
+ "upstream_binary_source",
+ json.dumps(
+ {
+ "published_repo": "unslothai/unsloth",
+ "release_tag": "b10715-mix",
+ "tag": "b10715",
+ "source": "ggml-org",
+ "binary_repo": "ggml-org/llama.cpp",
+ "binary_release_tag": "b10715",
+ "backend": "cpu",
+ }
+ ),
+ "installed release: unslothai/unsloth@b10715-mix + ggml-org@b10715 -- cpu backend",
+ ),
+ ("missing_published_repo", json.dumps({"release_tag": "b1", "backend": "rocm"}), ""),
+ ("missing_release_tag", json.dumps({"published_repo": "r/l", "backend": "rocm"}), ""),
+ (
+ "extra_unknown_keys",
+ _marker(backend = "rocm", future_key = {"a": [1, 2]}),
+ _BASE_LINE + " -- rocm backend",
+ ),
+ ("malformed_json", "{not json at all", ""),
+ ("truncated_json", '{"published_repo": "r/l", "release_ta', ""),
+ ("empty_file", "", ""),
+ ("whitespace_file", " \n ", ""),
+ ("absent_file", None, ""),
+]
+
+_IDS = [case[0] for case in _CASES]
+
+# setup.sh has a "+ <source>@<binary_tag>" branch setup.ps1 never has. Pre-existing.
+_PS1_EXPECTED_OVERRIDES = {
+ "upstream_binary_source": "installed release: unslothai/unsloth@b10715-mix (tag b10715) -- cpu backend",
+}
+_HISTORICAL_PS1_OVERRIDES = {
+ "2026_05_30_61df3aaef": "installed release: unslothai/llama.cpp@b5300-mix (tag b5300)",
+}
+_KNOWN_TWIN_DIVERGENCES = frozenset(_PS1_EXPECTED_OVERRIDES) | frozenset(_HISTORICAL_PS1_OVERRIDES)
+
+
+def marker_dir(tmp_path):
+ def _write(raw):
+ install_dir = tmp_path / "llama.cpp"
+ install_dir.mkdir(exist_ok = True)
+ if raw is not None:
+ (install_dir / "UNSLOTH_PREBUILT_INFO.json").write_text(raw, encoding = "utf-8")
+ return install_dir
+
+ return _write
+
+
+_PS_HARNESS = """
+param([string]$InstallDir, [string]$StrictMode)
+
+if ($StrictMode -ne 'off') {{ Set-StrictMode -Version $StrictMode }}
+
+# Stubbed: the real Get-PathState pulls in half the installer.
+function Test-PathQuiet {{
+ param([string]$Path, [string]$PathType = "Any")
+ return (Test-Path -LiteralPath $Path)
+}}
+
+. {get_function_source}
+$src = Get-FunctionSource -Path {setup_ps1} -Name Get-InstalledLlamaPrebuiltRelease
+if (-not $src) {{ Write-Error "could not slice Get-InstalledLlamaPrebuiltRelease"; exit 2 }}
+. ([scriptblock]::Create($src))
+
+$result = Get-InstalledLlamaPrebuiltRelease -InstallDir $InstallDir
+if ($null -ne $result) {{ [Console]::Out.Write($result) }}
+"""
+
+
+def _run_ps1_printer(install_dir, strict_mode):
+ script = _PS_HARNESS.format(
+ get_function_source = f"'{GET_FUNCTION_SOURCE}'",
+ setup_ps1 = f"'{SETUP_PS1}'",
+ )
+ # -File, not -Command: param() only binds named args from a file, and strict mode has
+ # to sit in the CALLER's scope.
+ script_path = Path(install_dir).parent / f"drive_{strict_mode.replace('.', '_')}.ps1"
+ script_path.write_text(script, encoding = "utf-8")
+ proc = subprocess.run(
+ [
+ "pwsh",
+ "-NoLogo",
+ "-NoProfile",
+ "-NonInteractive",
+ "-File",
+ str(script_path),
+ "-InstallDir",
+ str(install_dir),
+ "-StrictMode",
+ strict_mode,
+ ],
+ stdout = subprocess.PIPE,
+ stderr = subprocess.PIPE,
+ text = True,
+ encoding = "utf-8",
+ errors = "replace",
+ timeout = 120,
+ )
+ return proc
+
+
+_SH_HARNESS = """
+set -u
+_FUNC_FILE="$1"
+_INSTALL_DIR="$2"
+# shellcheck disable=SC1090
+. "$_FUNC_FILE"
+installed_llama_prebuilt_release "$_INSTALL_DIR"
+"""
+
+
+def _sliced_sh_function(tmp_path):
+ text = SETUP_SH.read_text(encoding = "utf-8")
+ start = text.index("installed_llama_prebuilt_release() {")
+ end = text.index("\n}\n", start) + len("\n}\n")
+ body = text[start:end]
+ assert "UNSLOTH_PREBUILT_INFO.json" in body, "sliced the wrong block out of setup.sh"
+ assert body.count("<<'PY'") == 1, "expected exactly one heredoc in the sliced block"
+ path = tmp_path / "installed_release_fn.sh"
+ path.write_text(body, encoding = "utf-8")
+ return path
+
+
+def _run_sh_printer(install_dir, tmp_path):
+ func_file = _sliced_sh_function(tmp_path)
+ script = tmp_path / "drive.sh"
+ script.write_text(_SH_HARNESS, encoding = "utf-8")
+ # The sliced function shells out to `python`; pin it to the test interpreter.
+ shim_dir = tmp_path / "shim"
+ shim_dir.mkdir(exist_ok = True)
+ shim = shim_dir / "python"
+ shim.write_text(f'#!/bin/sh\nexec "{sys.executable}" "$@"\n', encoding = "utf-8")
+ shim.chmod(0o755)
+ env = dict(os.environ)
+ env["PATH"] = f"{shim_dir}{os.pathsep}{env.get('PATH', '')}"
+ proc = subprocess.run(
+ [BASH, str(script), str(func_file), str(install_dir)],
+ stdout = subprocess.PIPE,
+ stderr = subprocess.PIPE,
+ text = True,
+ encoding = "utf-8",
+ errors = "replace",
+ env = env,
+ timeout = 120,
+ )
+ return proc
+
+
+@requires_pwsh
[email protected]("strict_mode", STRICT_MODES)
[email protected](("case_id", "raw", "expected"), _CASES, ids = _IDS)
+def test_ps1_printer(marker_dir, strict_mode, case_id, raw, expected):
+ expected = _PS1_EXPECTED_OVERRIDES.get(case_id, expected)
+ install_dir = marker_dir(raw)
+ proc = _run_ps1_printer(install_dir, strict_mode)
+ assert proc.returncode == 0, proc.stderr
+ assert (
+ proc.stdout == expected
+ ), f"{case_id} under StrictMode {strict_mode}: {proc.stdout!r} != {expected!r}"
+ assert proc.stderr == "", f"{case_id} wrote to the error stream: {proc.stderr!r}"
+
+
+@requires_pwsh
[email protected]("strict_mode", ["2.0", "3.0", "Latest"])
+def test_a_legacy_marker_does_not_abort_under_strict_mode(marker_dir, strict_mode):
+ """The discriminating case: markers between #4562 and #8520 have no backend key, and
+ the function's only try/catch wraps ConvertFrom-Json, so the read escapes it.
+ """
+ install_dir = marker_dir(_drop_backend_key())
+ proc = _run_ps1_printer(install_dir, strict_mode)
+ assert "PropertyNotFound" not in proc.stderr, proc.stderr
+ assert proc.returncode == 0, proc.stderr
+ assert proc.stdout == _BASE_LINE
+ assert proc.stderr == ""
+
+
+@requires_pwsh
+ "payload",
+ [
+ "$(Write-Output pwned)",
+ "`$(Write-Output pwned)",
+ "vulkan; Write-Output pwned",
+ "$(1+1)",
+ ],
+)
+def test_ps1_printer_never_evaluates_the_marker(marker_dir, payload):
+ install_dir = marker_dir(_with_backend(payload))
+ proc = _run_ps1_printer(install_dir, "Latest")
+ assert proc.returncode == 0, proc.stderr
+ assert "pwned" not in proc.stdout
+ assert proc.stdout == _BASE_LINE
+
+
+@requires_bash
[email protected](("case_id", "raw", "expected"), _CASES, ids = _IDS)
+def test_sh_printer(marker_dir, tmp_path, case_id, raw, expected):
+ install_dir = marker_dir(raw)
+ proc = _run_sh_printer(install_dir, tmp_path)
+ assert proc.returncode == 0, proc.stderr
+ assert proc.stdout.rstrip("\n") == expected, f"{case_id}: {proc.stdout!r} != {expected!r}"
+
+
+@requires_bash
+ "payload", ["vulkan; echo pwned", "$(echo pwned)", "`echo pwned`", "$(id)"]
+)
+def test_sh_printer_never_evaluates_the_marker(marker_dir, tmp_path, payload):
+ install_dir = marker_dir(_with_backend(payload))
+ proc = _run_sh_printer(install_dir, tmp_path)
+ assert proc.returncode == 0, proc.stderr
+ assert "pwned" not in proc.stdout
+ assert proc.stdout.rstrip("\n") == _BASE_LINE
+
+
+@requires_pwsh
+@requires_bash
[email protected](("case_id", "raw", "expected"), _CASES, ids = _IDS)
+def test_the_two_printers_agree(marker_dir, tmp_path, case_id, raw, expected):
+ """Byte-for-byte parity. Without it the twins drift and nobody notices."""
+ if case_id in _KNOWN_TWIN_DIVERGENCES:
+ pytest.skip("documented pre-existing divergence; see the dedicated test")
+ install_dir = marker_dir(raw)
+ ps1 = _run_ps1_printer(install_dir, "Latest")
+ sh = _run_sh_printer(install_dir, tmp_path)
+ assert ps1.returncode == 0, ps1.stderr
+ assert sh.returncode == 0, sh.stderr
+ assert ps1.stdout == sh.stdout.rstrip(
+ "\n"
+ ), f"{case_id}: setup.ps1 printed {ps1.stdout!r}, setup.sh printed {sh.stdout!r}"
+
+
+# Every key set write_prebuilt_metadata has emitted; the 2026-04-01 to 2026-08-13 era is
+# on disk today with no backend key.
+
+_HISTORICAL_MARKERS = {
+ # no published_repo / release_tag yet, so both printers print nothing.
+ "2026_03_25_f4d8a246b": (
+ {
+ "requested_tag": "b4000",
+ "tag": "b4000",
+ "asset": "linux-cuda",
+ "source": "unsloth",
+ "bundle_profile": "full",
+ "runtime_line": "cuda",
+ "coverage_class": "broad",
+ "prebuilt_fallback_used": False,
+ "installed_at_utc": "2026-03-25T00:00:00Z",
+ },
+ "",
+ ),
+ "2026_04_01_428efc7d9": (
+ {
+ "requested_tag": "b4100",
+ "tag": "b4100",
+ "release_tag": "b4100-mix",
+ "published_repo": "unslothai/llama.cpp",
+ "asset": "linux-cuda",
+ "asset_sha256": "0" * 64,
+ "source": "unsloth",
+ "source_sha256": "1" * 64,
+ "source_commit": "a" * 40,
+ "install_fingerprint": "fp",
+ "bundle_profile": "full",
+ "runtime_line": "cuda",
+ "coverage_class": "broad",
+ "prebuilt_fallback_used": False,
+ "installed_at_utc": "2026-04-01T00:00:00Z",
+ },
+ "installed release: unslothai/llama.cpp@b4100-mix (tag b4100)",
+ ),
+ "2026_04_02_1ce8a8e7c": (
+ {
+ "requested_tag": "b4200",
+ "tag": "b4200",
+ "release_tag": "b4200-mix",
+ "published_repo": "unslothai/llama.cpp",
+ "asset": "linux-vulkan",
+ "source_asset": "src.tar.gz",
+ "source_commit_short": "aaaaaaa",
+ "source_repo": "ggml-org/llama.cpp",
+ "source_repo_url": "https://x",
+ "source_ref_kind": "tag",
+ "requested_source_ref": "b4200",
+ "resolved_source_ref": "b4200",
+ "installed_at_utc": "2026-04-02T00:00:00Z",
+ },
+ "installed release: unslothai/llama.cpp@b4200-mix (tag b4200)",
+ ),
+ "2026_05_30_61df3aaef": (
+ {
+ "tag": "b5300",
+ "release_tag": "b5300-mix",
+ "published_repo": "unslothai/llama.cpp",
+ "source": "ggml-org",
+ "binary_repo": "ggml-org/llama.cpp",
+ "binary_release_tag": "b5300",
+ "installed_at_utc": "2026-05-30T00:00:00Z",
+ },
+ "installed release: unslothai/llama.cpp@b5300-mix + ggml-org@b5300",
+ ),
+ "2026_07_20_cf912cbd8": (
+ {
+ "tag": "b6900",
+ "release_tag": "b6900-mix",
+ "published_repo": "unslothai/llama.cpp",
+ "force_cpu": True,
+ "asset": "linux-cpu",
+ "installed_at_utc": "2026-07-20T00:00:00Z",
+ },
+ "installed release: unslothai/llama.cpp@b6900-mix (tag b6900)",
+ ),
+ # llama_backend is the pre-#8520 field, not the key the printer reads.
+ "2026_07_27_7917c7828": (
+ {
+ "tag": "b7100",
+ "release_tag": "b7100-mix",
+ "published_repo": "unslothai/llama.cpp",
+ "llama_backend": "vulkan",
+ "installed_at_utc": "2026-07-27T00:00:00Z",
+ },
+ "installed release: unslothai/llama.cpp@b7100-mix (tag b7100)",
+ ),
+ "2026_08_04_9b452cb3b": (
+ {
+ "tag": "b7400",
+ "release_tag": "b7400-mix",
+ "published_repo": "unslothai/llama.cpp",
+ "ggml_tree": "abc123",
+ "installed_at_utc": "2026-08-04T00:00:00Z",
+ },
+ "installed release: unslothai/llama.cpp@b7400-mix (tag b7400)",
+ ),
+ "2026_08_08_738413ab0": (
+ {
+ "tag": "b7600",
+ "release_tag": "b7600-mix",
+ "published_repo": "unslothai/llama.cpp",
+ "llama_backend": "auto",
+ "rocm_gfx": "gfx1151",
+ "installed_at_utc": "2026-08-08T00:00:00Z",
+ },
+ "installed release: unslothai/llama.cpp@b7600-mix (tag b7600)",
+ ),
+ "2026_08_13_5426a78c3": (
+ {
+ "tag": "b7900",
+ "release_tag": "b7900-mix",
+ "published_repo": "unslothai/llama.cpp",
+ "backend": "vulkan",
+ "backend_request": "auto",
+ "installed_at_utc": "2026-08-13T00:00:00Z",
+ },
+ "installed release: unslothai/llama.cpp@b7900-mix (tag b7900) -- vulkan backend",
+ ),
+ # backend_for_install_kind() returns None for an unknown kind, landing as JSON null.
+ "backend_written_as_null": (
+ {
+ "tag": "b7900",
+ "release_tag": "b7900-mix",
+ "published_repo": "unslothai/llama.cpp",
+ "backend": None,
+ "backend_request": "auto",
+ "installed_at_utc": "2026-08-13T00:00:00Z",
+ },
+ "installed release: unslothai/llama.cpp@b7900-mix (tag b7900)",
+ ),
+ "2026_08_13_5a3e9fc7a": (
+ {
+ "tag": "b8000",
+ "release_tag": "b8000-mix",
+ "published_repo": "unslothai/llama.cpp",
+ "backend": "rocm",
+ "gfx_target": "gfx1151",
+ "mapped_targets": ["gfx1151", "gfx1200"],
+ "installed_at_utc": "2026-08-13T00:00:00Z",
+ },
+ "installed release: unslothai/llama.cpp@b8000-mix (tag b8000) -- rocm backend",
+ ),
+ "2026_08_18_9d1dcfe58": (
+ {
+ "tag": "b8300",
+ "release_tag": "b8300-mix",
+ "published_repo": "unslothai/llama.cpp",
+ "backend": "cuda",
+ "supported_sms": ["90", "100"],
+ "installed_at_utc": "2026-08-18T00:00:00Z",
+ },
+ "installed release: unslothai/llama.cpp@b8300-mix (tag b8300) -- cuda backend",
+ ),
+ # the current shape.
+ "2026_08_31_1400031e2_current": (
+ {
+ "requested_tag": "b10715",
+ "tag": "b10715",
+ "release_tag": "b10715-mix-86bd2d3",
+ "published_repo": "unslothai/llama.cpp",
+ "asset": "windows-vulkan",
+ "force_cpu": False,
+ "llama_backend": "vulkan",
+ "backend": "vulkan",
+ "backend_request": "auto",
+ "asset_sha256": "0" * 64,
+ "runtime_asset": "runtime.zip",
+ "source": "unsloth",
+ "binary_repo": "unslothai/llama.cpp",
+ "binary_release_tag": "b10715-mix",
+ "source_asset": "src.tar.gz",
+ "source_sha256": "1" * 64,
+ "source_commit": "a" * 40,
+ "source_commit_short": "aaaaaaa",
+ "source_repo": "ggml-org/llama.cpp",
+ "source_repo_url": "https://x",
+ "source_ref_kind": "tag",
+ "requested_source_ref": "b10715",
+ "resolved_source_ref": "b10715",
+ "ggml_tree": "abc123",
+ "bundle_profile": "full",
+ "runtime_line": "vulkan",
+ "coverage_class": "broad",
+ "gfx_target": "",
+ "mapped_targets": [],
+ "supported_sms": [],
+ "install_fingerprint": "fp",
+ "prebuilt_fallback_used": False,
+ "installed_at_utc": "2026-08-31T00:00:00Z",
+ },
+ "installed release: unslothai/llama.cpp@b10715-mix-86bd2d3 (tag b10715) -- vulkan backend",
+ ),
+}
+
+
+@requires_pwsh
[email protected]("strict_mode", STRICT_MODES)
[email protected]("shape_id", sorted(_HISTORICAL_MARKERS))
+def test_every_historical_marker_shape_on_ps1(marker_dir, strict_mode, shape_id):
+ payload, expected = _HISTORICAL_MARKERS[shape_id]
+ expected = _HISTORICAL_PS1_OVERRIDES.get(shape_id, expected)
+ install_dir = marker_dir(json.dumps(payload, indent = 2) + "\n")
+ proc = _run_ps1_printer(install_dir, strict_mode)
+ assert proc.returncode == 0, proc.stderr
+ assert proc.stderr == "", f"{shape_id} under {strict_mode}: {proc.stderr!r}"
+ assert proc.stdout == expected, f"{shape_id} under {strict_mode}"
+
+
+@requires_bash
[email protected]("shape_id", sorted(_HISTORICAL_MARKERS))
+def test_every_historical_marker_shape_on_sh(marker_dir, tmp_path, shape_id):
+ payload, expected = _HISTORICAL_MARKERS[shape_id]
+ install_dir = marker_dir(json.dumps(payload, indent = 2) + "\n")
+ proc = _run_sh_printer(install_dir, tmp_path)
+ assert proc.returncode == 0, proc.stderr
+ assert proc.stdout.rstrip("\n") == expected, shape_id
+
+
+@requires_pwsh
+@requires_bash
[email protected]("shape_id", sorted(_HISTORICAL_MARKERS))
+def test_every_historical_marker_shape_agrees(marker_dir, tmp_path, shape_id):
+ if shape_id in _KNOWN_TWIN_DIVERGENCES:
+ pytest.skip("documented pre-existing divergence; see the dedicated test")
+ payload, _expected = _HISTORICAL_MARKERS[shape_id]
+ install_dir = marker_dir(json.dumps(payload, indent = 2) + "\n")
+ ps1 = _run_ps1_printer(install_dir, "Latest")
+ sh = _run_sh_printer(install_dir, tmp_path)
+ assert ps1.stdout == sh.stdout.rstrip("\n"), shape_id
+
+
+def test_the_ps1_guard_checks_property_existence():
+ text = SETUP_PS1.read_text(encoding = "utf-8")
+ start = text.index("function Get-InstalledLlamaPrebuiltRelease")
+ body = text[start : text.index("\nfunction ", start + 1)]
+ assert "PSObject.Properties.Name -ccontains 'backend'" in body, (
+ "the backend read must stay guarded: a bare $payload.backend is a terminating "
+ "error under a caller's Set-StrictMode for every marker written before #8520"
+ )
+
+
+def test_both_printers_share_one_backend_shape_rule():
+ shape = "[A-Za-z0-9._+-]{1,32}"
+ assert shape in SETUP_PS1.read_text(encoding = "utf-8")
+ assert shape in SETUP_SH.read_text(encoding = "utf-8")
+
+
+def test_the_sh_printer_only_accepts_a_string():
+ text = SETUP_SH.read_text(encoding = "utf-8")
+ assert (
+ "isinstance(_backend_raw, str)" in text
+ ), "str() on a non-string diverges from the PowerShell twin"
+
+
+@requires_pwsh
+@requires_bash
+def test_the_upstream_source_branch_is_a_known_pre_existing_divergence(marker_dir, tmp_path):
+ """Recorded, not fixed: teaching setup.ps1 this branch changes what Windows prints
+ for upstream bundles, which is a separate change from naming the backend.
+ """
+ raw = json.dumps(
+ {
+ "published_repo": "unslothai/unsloth",
+ "release_tag": "b10715-mix",
+ "tag": "b10715",
+ "source": "ggml-org",
+ "binary_repo": "ggml-org/llama.cpp",
+ "binary_release_tag": "b10715",
+ "backend": "cpu",
+ }
+ )
+ install_dir = marker_dir(raw)
+ ps1 = _run_ps1_printer(install_dir, "Latest")
+ sh = _run_sh_printer(install_dir, tmp_path)
+ assert ps1.stdout == (
+ "installed release: unslothai/unsloth@b10715-mix (tag b10715) -- cpu backend"
+ )
+ assert sh.stdout.rstrip("\n") == (
+ "installed release: unslothai/unsloth@b10715-mix + ggml-org@b10715 -- cpu backend"
+ )
+ assert ps1.stdout.endswith(" -- cpu backend")
+ assert sh.stdout.rstrip("\n").endswith(" -- cpu backend")