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.

Recognise Windows code integrity blocks, and require the runtime we ship (#10404)

Daniel Han9ee322400a01
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 9a465bdfea3..0d3acaae567 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -444,6 +444,7 @@ from state.tool_approvals import (
wait_tool_decision,
)
from utils.paths.path_utils import _is_wsl, is_appledouble_metadata
+from utils.code_integrity import code_integrity_block_reason, code_integrity_user_message
# The leaf module, not utils.models: importing anything from that package runs its __init__,
# which pulls in model_config and therefore PyYAML. This is the chat backend, imported wherever
@@ -7770,8 +7771,10 @@ class LlamaCppBackend:
# Nanoseconds and size, not int(st_mtime): an update landing in the same second as
# the probe kept the key identical and got the old build's capabilities.
_CAPABILITY_PROBE_RETRY_SECONDS = 30.0
+ _CAPABILITY_PROBE_RETRY_MAX_SECONDS = 600.0
_capability_cache: dict[tuple[str, int, int], dict[str, object]] = {}
_capability_retry_after: dict[tuple[str, int, int], float] = {}
+ _capability_retry_backoff: dict[tuple[str, int, int], float] = {}
_capability_cache_lock = threading.Lock()
# The value form of the flash-attention flag. Newer llama.cpp declares it
@@ -7933,6 +7936,7 @@ class LlamaCppBackend:
# compile exceeds this probe's timeout; no device is needed to
# enumerate the command-line flags.
probe_env["GGML_METAL_DEVICES"] = "0"
+ code_integrity_blocked: Optional[str] = None
result = subprocess.run(
[bin_path, "--help"],
capture_output = True,
@@ -7942,9 +7946,22 @@ class LlamaCppBackend:
timeout = 10,
check = False,
env = probe_env,
+ # Else the probe flashes a console window on every status poll.
+ **_windows_hidden_subprocess_kwargs(),
)
probe_ok = result.returncode == 0
help_text = (result.stdout or "") + "\n" + (result.stderr or "")
+ if not probe_ok:
+ # The LOADER kills the created process: the NTSTATUS arrives as
+ # a return code, or in the output when a DLL was refused.
+ code_integrity_blocked = code_integrity_block_reason(
+ result.returncode
+ ) or code_integrity_block_reason(help_text)
+ if code_integrity_blocked is not None:
+ logger.warning(
+ "llama-server is blocked by Windows code integrity policy: "
+ f"{code_integrity_blocked}. Binary: {bin_path}"
+ )
# Split into per-flag blocks (each --flag line + its indented
# continuation), so the "argument has been removed" description
# sits with its flag.
@@ -8130,7 +8147,16 @@ class LlamaCppBackend:
spec_draft_cache_v_flag = _alias
break
except (OSError, subprocess.SubprocessError) as exc:
- logger.debug(f"llama-server --help probe failed: {exc}")
+ blocked = code_integrity_block_reason(exc)
+ code_integrity_blocked = blocked
+ if blocked is not None:
+ # Warning, not debug: the only other symptom is a silent probe.
+ logger.warning(
+ f"llama-server is blocked by Windows code integrity policy: {blocked}. "
+ f"Binary: {bin_path}"
+ )
+ else:
+ logger.debug(f"llama-server --help probe failed: {exc}")
saw_spec_type = False
probe_ok = False
help_text = ""
@@ -8226,11 +8252,22 @@ class LlamaCppBackend:
# Bound both failure modes: do not pin a transient failure for
# the process lifetime, and do not make every caller repeat a
# 10-second timeout while a persistent failure remains (#8317).
- cls._capability_retry_after[cache_key] = (
- time.monotonic() + cls._CAPABILITY_PROBE_RETRY_SECONDS
- )
+ # Only a CONFIRMED block doubles, being permanent; escalating on
+ # an inconclusive probe would strand a busy machine on stale caps.
+ if code_integrity_blocked is not None:
+ delay = cls._capability_retry_backoff.get(
+ cache_key, cls._CAPABILITY_PROBE_RETRY_SECONDS
+ )
+ cls._capability_retry_backoff[cache_key] = min(
+ delay * 2.0, cls._CAPABILITY_PROBE_RETRY_MAX_SECONDS
+ )
+ else:
+ delay = cls._CAPABILITY_PROBE_RETRY_SECONDS
+ cls._capability_retry_backoff.pop(cache_key, None)
+ cls._capability_retry_after[cache_key] = time.monotonic() + delay
else:
cls._capability_retry_after.pop(cache_key, None)
+ cls._capability_retry_backoff.pop(cache_key, None)
return info
@staticmethod
@@ -16176,6 +16213,12 @@ class LlamaCppBackend:
"""
lowered = (output or "").lower()
+ # First: every branch below advises reinstall, memory or administrator,
+ # none of which lift a refusal to load a file that is present.
+ blocked = code_integrity_block_reason(returncode) or code_integrity_block_reason(output)
+ if blocked is not None:
+ return code_integrity_user_message(binary or "the llama.cpp runtime", blocked)
+
# The dynamic loader kills llama-server before main(), so nothing below
# matches and the fallback blames the file or memory instead. The Linux
# prebuilt links libgomp.so.1, which a stock container does not ship.
diff --git a/studio/backend/tests/test_code_integrity.py b/studio/backend/tests/test_code_integrity.py
new file mode 100644
index 00000000000..0863668dcd4
--- /dev/null
+++ b/studio/backend/tests/test_code_integrity.py
@@ -0,0 +1,146 @@
+# 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 code integrity refusal needs the opposite advice to a corrupt download."""
+
+import pytest
+
+from utils.code_integrity import (
+ code_integrity_block_reason,
+ code_integrity_user_message,
+ is_bad_image_text,
+)
+
+
+class _WinError(OSError):
+ def __init__(self, winerror: int):
+ super().__init__("launch failed")
+ self.winerror = winerror
+
+
+def test_smart_app_control_status_from_text():
+ text = (
+ r"C:\Users\x\.unsloth\llama.cpp\build\bin\Release\llama-common.dll is either "
+ r"not designed to run on Windows or it contains an error. Error status 0xc0e90002."
+ )
+ reason = code_integrity_block_reason(text)
+ assert reason is not None
+ assert "Smart App Control" in reason
+
+
[email protected]("winerror", [577, 1260, 4551])
+def test_win32_error_numbers_are_recognised(winerror: int):
+ assert code_integrity_block_reason(_WinError(winerror)) is not None
+
+
[email protected]("status", [0xC0E90002, 0xC0000428, 0xC0000602])
+def test_ntstatus_return_codes_are_recognised(status: int):
+ # Popen reports the same status as a negative int, read as signed.
+ assert code_integrity_block_reason(status) is not None
+ assert code_integrity_block_reason(status - (1 << 32)) is not None
+
+
+def test_application_control_phrasing():
+ """The wording from unslothai/unsloth#8490."""
+ text = (
+ "Program 'unsloth.exe' failed to run: An Application Control policy has blocked this file"
+ )
+ assert code_integrity_block_reason(text) is not None
+
+
+def test_ordinary_failures_are_not_misreported():
+ assert code_integrity_block_reason(FileNotFoundError("no such file")) is None
+ assert code_integrity_block_reason(_WinError(2)) is None
+ assert code_integrity_block_reason("llama-server: unknown argument --nope") is None
+ assert code_integrity_block_reason(1) is None
+ assert code_integrity_block_reason("") is None
+ assert code_integrity_block_reason(None) is None
+
+
+def test_user_message_names_the_binary_and_rules_out_reinstalling():
+ message = code_integrity_user_message(r"C:\Users\x\.unsloth\llama.cpp", "blocked")
+ assert r"C:\Users\x\.unsloth\llama.cpp" in message
+ assert "reinstalling" in message
+ assert "administrator" in message
+
+
+def test_an_administrator_policy_block_is_not_sent_to_smart_app_control():
+ """winerror 1260 and the AppLocker wording mean an admin policy, which
+ turning Smart App Control off does not lift."""
+ for error in (_WinError(1260), "An Application Control policy has blocked this file"):
+ reason = code_integrity_block_reason(error)
+ assert reason is not None
+ message = code_integrity_user_message(r"C:\Users\x\.unsloth\llama.cpp", reason)
+ assert "administers this device" in message
+ assert "only local workaround" not in message
+
+ sac_reason = code_integrity_block_reason("This app was blocked by Smart App Control")
+ assert sac_reason is not None
+ sac_message = code_integrity_user_message(r"C:\x", sac_reason)
+ assert "only local workaround" in sac_message
+ assert "administers this device" not in sac_message
+
+ # SAC and WDAC both report 0xC0E90002, so it offers both remedies.
+ ambiguous = code_integrity_user_message(r"C:\x", code_integrity_block_reason(0xC0E90002))
+ assert "Smart App Control" in ambiguous
+ assert "managed by an administrator" in ambiguous
+
+
+def test_an_invalid_image_hash_does_not_deny_corruption():
+ """0xC0000428 / winerror 577 are a hash mismatch, which Windows reports for a
+ damaged file too, so the message must not rule out a reinstall."""
+ for error in (0xC0000428, 0xC0000428 - (1 << 32), _WinError(577)):
+ reason = code_integrity_block_reason(error)
+ assert reason is not None
+ message = code_integrity_user_message(r"C:\Users\x\.unsloth\llama.cpp", reason)
+ assert r"C:\Users\x\.unsloth\llama.cpp" in message
+ assert "not a corrupt download" not in message
+ assert "Reinstalling" in message
+ assert "Smart App Control" in message
+ assert "managed by an administrator" in message
+
+ policy = code_integrity_user_message(r"C:\x", code_integrity_block_reason(0xC0E90002))
+ assert "not a corrupt download" in policy
+
+
+def test_bad_image_without_a_status_is_not_called_a_policy_block():
+ """Windows prints the same sentence for a corrupt or wrong-architecture DLL,
+ which does need the reinstall this module rules out."""
+ corrupt = (
+ r"C:\Users\x\.unsloth\llama.cpp\build\bin\Release\ggml-base.dll is either not "
+ r"designed to run on Windows or it contains an error."
+ )
+ assert code_integrity_block_reason(corrupt) is None
+ assert is_bad_image_text(corrupt) is True
+ assert code_integrity_block_reason(corrupt + " Error status 0xc0e90002.") is not None
+
+
+def test_a_blocked_start_is_explained_to_the_user_not_blamed_on_the_model():
+ import sys
+ from pathlib import Path
+
+ backend = Path(__file__).resolve().parents[1]
+ if str(backend) not in sys.path:
+ sys.path.insert(0, str(backend))
+ from core.inference.llama_cpp import LlamaCppBackend
+
+ message = LlamaCppBackend._classify_start_failure_text(
+ output = (
+ r"C:\Users\x\.unsloth\llama.cpp\build\bin\Release\llama-common.dll is either "
+ r"not designed to run on Windows or it contains an error. Error status 0xc0e90002."
+ ),
+ gguf_path = "C:\\models\\qwen.gguf",
+ model_identifier = "unsloth/Qwen3.5-2B-MTP-GGUF",
+ binary = r"C:\Users\x\.unsloth\llama.cpp",
+ )
+ assert "Smart App Control" in message
+ assert "reinstalling" in message
+ assert "out of memory" not in message.lower()
+
+ by_status = LlamaCppBackend._classify_start_failure_text(
+ output = "",
+ gguf_path = None,
+ model_identifier = None,
+ returncode = 0xC0E90002,
+ binary = r"C:\Users\x\.unsloth\llama.cpp",
+ )
+ assert "Smart App Control" in by_status
diff --git a/studio/backend/tests/test_llama_cpp_mtp_detection.py b/studio/backend/tests/test_llama_cpp_mtp_detection.py
index 20892d7dfaf..c444b09dd62 100644
--- a/studio/backend/tests/test_llama_cpp_mtp_detection.py
+++ b/studio/backend/tests/test_llama_cpp_mtp_detection.py
@@ -3110,6 +3110,48 @@ def test_probe_reports_no_draft_ngl_flag_when_the_build_has_neither(tmp_path):
assert LlamaCppBackend.probe_server_capabilities(str(neither))["spec_draft_ngl_flag"] is None
+@_NEEDS_BASH
+def test_a_code_integrity_block_escalates_the_retry_window(tmp_path, monkeypatch):
+ """Only a confirmed block earns the doubling; a merely loaded machine that
+ times out a few probes and recovers must not inherit that wait. It arrives
+ the way Windows delivers it: subprocess.run returns the NTSTATUS from a
+ loader-killed process rather than raising.
+ """
+ import types as _types
+
+ fake = _make_fake_llama_server(
+ tmp_path / "llama-server",
+ "--spec-type none,draft-mtp,ngram-mod",
+ )
+ _clear_caps_cache()
+ now = [100.0]
+ calls = []
+
+ def _run(cmd, **kwargs):
+ calls.append(cmd)
+ # The Smart App Control refusal, as an exit status.
+ return _types.SimpleNamespace(stdout = "", stderr = "", returncode = 0xC0E90002)
+
+ monkeypatch.setattr("core.inference.llama_cpp.subprocess.run", _run)
+ monkeypatch.setattr("core.inference.llama_cpp.time.monotonic", lambda: now[0])
+
+ first = LlamaCppBackend.probe_server_capabilities(str(fake))
+ assert first["mtp_probe_inconclusive"] is True
+ assert len(calls) == 1
+
+ now[0] += LlamaCppBackend._CAPABILITY_PROBE_RETRY_SECONDS + 1
+ LlamaCppBackend.probe_server_capabilities(str(fake))
+ assert len(calls) == 2
+
+ now[0] += LlamaCppBackend._CAPABILITY_PROBE_RETRY_SECONDS + 1
+ LlamaCppBackend.probe_server_capabilities(str(fake))
+ assert len(calls) == 2, "a confirmed block must not be re-probed on the flat window"
+
+ now[0] += 2 * LlamaCppBackend._CAPABILITY_PROBE_RETRY_SECONDS + 1
+ LlamaCppBackend.probe_server_capabilities(str(fake))
+ assert len(calls) == 3
+
+
@_NEEDS_BASH
def test_inconclusive_probe_retries_after_a_bounded_cache_window(tmp_path, monkeypatch):
"""A transient timeout may not be pinned for the whole process, while a
@@ -3155,8 +3197,7 @@ def test_inconclusive_probe_retries_after_a_bounded_cache_window(tmp_path, monke
assert LlamaCppBackend.probe_server_capabilities(str(fake)) is retried
assert len(calls) == 2
- # Once a later retry succeeds, the result returns to the normal long-lived
- # cache.
+ # A timeout is TRANSIENT: the window stays flat, only a block doubles.
now[0] += LlamaCppBackend._CAPABILITY_PROBE_RETRY_SECONDS + 1
recovered = LlamaCppBackend.probe_server_capabilities(str(fake))
assert recovered["mtp_probe_inconclusive"] is False
diff --git a/studio/backend/utils/code_integrity.py b/studio/backend/utils/code_integrity.py
new file mode 100644
index 00000000000..4ed3f12178a
--- /dev/null
+++ b/studio/backend/utils/code_integrity.py
@@ -0,0 +1,134 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+"""Recognise a Windows code integrity refusal in a failed process launch.
+
+Smart App Control, WDAC and AppLocker all refuse through the same kernel path.
+"""
+
+from __future__ import annotations
+
+import re
+
+
+_REASON_SAC_OR_POLICY = "Smart App Control or an Application Control policy blocked the image"
+_REASON_ADMIN_POLICY = "an Application Control policy blocked this program"
+_REASON_SMART_APP_CONTROL = "Smart App Control blocked this program"
+_REASON_INVALID_HASH_STATUS = (
+ "the image failed code integrity validation (invalid or missing signature)"
+)
+_REASON_INVALID_HASH_WINERROR = "Windows could not verify the digital signature of the image"
+
+# NTSTATUS refusals: SAC facility, INVALID_IMAGE_HASH, FAIL_FAST_EXCEPTION.
+_BLOCK_STATUS_CODES = {
+ 0xC0E90002: _REASON_SAC_OR_POLICY,
+ 0xC0000428: _REASON_INVALID_HASH_STATUS,
+ 0xC0000602: "the image was refused by a code integrity fail-fast",
+}
+
+# winerror equivalents; CI_BLOCKED is from unslothai/unsloth#6648.
+_BLOCK_WINERRORS = {
+ 577: _REASON_INVALID_HASH_WINERROR,
+ 1260: _REASON_ADMIN_POLICY,
+ 4551: "code integrity blocked the image",
+}
+
+# 0xC0E90002 is SAC or WDAC, so only 1260 and the AppLocker wording prove admin.
+_ADMIN_POLICY_REASONS = frozenset({_REASON_ADMIN_POLICY})
+_SMART_APP_CONTROL_REASONS = frozenset({_REASON_SMART_APP_CONTROL})
+
+# A hash mismatch, not a policy verdict: Microsoft's text is "signed incorrectly
+# or damaged" (event 5038), so these must not deny corruption.
+_INVALID_HASH_REASONS = frozenset({_REASON_INVALID_HASH_STATUS, _REASON_INVALID_HASH_WINERROR})
+
+_STATUS_TEXT_RE = re.compile(r"0x(c0e90002|c0000428|c0000602)\b", re.IGNORECASE)
+_BAD_IMAGE_RE = re.compile(
+ r"is either not designed to run on Windows or it contains an error", re.IGNORECASE
+)
+_SAC_TEXT_RE = re.compile(r"blocked by smart app control", re.IGNORECASE)
+_ADMIN_POLICY_TEXT_RE = re.compile(
+ r"(application control policy has blocked|blocked by group policy)",
+ re.IGNORECASE,
+)
+
+
+def is_bad_image_text(error: object) -> bool:
+ """True when Windows reported a Bad Image, whatever the cause."""
+ text = error if isinstance(error, str) else str(error)
+ return bool(text) and _BAD_IMAGE_RE.search(text) is not None
+
+
+def code_integrity_block_reason(error: object) -> str | None:
+ """Return a human reason when ``error`` is a code integrity refusal, else None."""
+ winerror = getattr(error, "winerror", None)
+ if isinstance(winerror, int):
+ reason = _BLOCK_WINERRORS.get(winerror)
+ if reason is not None:
+ return reason
+ # winerror also carries the raw NTSTATUS on some launch failures.
+ reason = _BLOCK_STATUS_CODES.get(winerror & 0xFFFFFFFF)
+ if reason is not None:
+ return reason
+
+ returncode = getattr(error, "returncode", None)
+ if isinstance(error, int):
+ returncode = error
+ if isinstance(returncode, int):
+ # A negative return code is the same status read as signed.
+ reason = _BLOCK_STATUS_CODES.get(returncode & 0xFFFFFFFF)
+ if reason is not None:
+ return reason
+
+ text = error if isinstance(error, str) else str(error)
+ if not text:
+ return None
+ match = _STATUS_TEXT_RE.search(text)
+ if match is not None:
+ return _BLOCK_STATUS_CODES[int(match.group(1), 16)]
+ if _SAC_TEXT_RE.search(text):
+ return _REASON_SMART_APP_CONTROL
+ if _ADMIN_POLICY_TEXT_RE.search(text):
+ return _REASON_ADMIN_POLICY
+ # "Bad Image" alone is NOT a block: a corrupt DLL prints it too, and there
+ # reinstalling IS the remedy.
+ return None
+
+
+def code_integrity_user_message(binary: str, reason: str) -> str:
+ if reason in _INVALID_HASH_REASONS:
+ return (
+ f"Windows refused to load part of the local model runtime: {reason}. "
+ f"The refused file is under {binary}. "
+ "Windows reports this both for a file a code integrity policy will not "
+ "accept and for one that is damaged or was downloaded incompletely, so "
+ "the error alone does not say which. Reinstalling the local runtime "
+ "replaces the files and clears the damaged case. If it fails again after "
+ "that, it is a policy: Smart App Control has no per-application exception "
+ "and turning it off in Windows Security under App & browser control is "
+ "the only local workaround, while on a device managed by an administrator "
+ "the policy is theirs to change."
+ )
+ opening = (
+ f"Windows blocked part of the local model runtime: {reason}. "
+ f"The blocked file is under {binary}. "
+ "This is a Windows code integrity policy refusing to load code it does not "
+ "recognise, not a corrupt download, so reinstalling or running as "
+ "administrator will not clear it. "
+ )
+ if reason in _ADMIN_POLICY_REASONS:
+ return opening + (
+ "The policy is set by whoever administers this device (AppLocker, WDAC "
+ "or Group Policy) and can only be changed there, so ask them to allow "
+ "the files in that folder. Turning off Smart App Control does not "
+ "affect an administrator policy."
+ )
+ if reason in _SMART_APP_CONTROL_REASONS:
+ return opening + (
+ "Smart App Control has no per-application exception; turning it off in "
+ "Windows Security under App & browser control is the only local workaround."
+ )
+ return opening + (
+ "If Smart App Control is on, it has no per-application exception and turning "
+ "it off in Windows Security under App & browser control is the only local "
+ "workaround. If this device is managed by an administrator, the policy is "
+ "theirs to change and turning off Smart App Control will not help."
+ )
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index f02bce3a9de..0bf5a14c4dd 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -6941,11 +6941,47 @@ def installed_llama_ggml_tree(install_dir: Path | None = None) -> str | None:
return tree if isinstance(tree, str) and tree else None
+# ggml-org/llama.cpp#23462 split per-binary entry code into ``lib<binary>-impl``
+# libraries between b9279 and b9283; an older archive is monolithic and healthy
+# without llama-server-impl.dll, so requiring it there forces a source build.
+LLAMA_SERVER_IMPL_SPLIT_BUILD = 9283
+
+
+def _release_build_number(tag: str | None) -> int | None:
+ """Build number of a ``bNNNN`` tag, also matching the fork's ``bNNNN-mix-<sha>``.
+ None for a branch or commit pin, which callers treat as "assume current"."""
+ if not isinstance(tag, str):
+ return None
+ match = re.match(r"b(\d+)(?:[-.]|$)", tag.strip())
+ return int(match.group(1)) if match else None
+
+
+def _windows_shared_groups(source_label: str | None, tag: str | None = None) -> list[list[str]]:
+ """Runtime files every Windows install kind owes, before its backend DLL.
+
+ Requiring only ``llama.dll`` let a truncated extract validate then fail at exec.
+ Prebuilt sources only: ``setup.ps1`` links statically and ships none of these.
+ """
+ groups: list[list[str]] = [["llama.dll"]]
+ if source_label in {"published", "upstream"}:
+ groups.append(["llama-common.dll"])
+ groups.append(["llama-server.exe"])
+ build = _release_build_number(tag)
+ if build is None or build >= LLAMA_SERVER_IMPL_SPLIT_BUILD:
+ groups.append(["llama-server-impl.dll"])
+ groups.append(["ggml.dll"])
+ groups.append(["ggml-base.dll"])
+ groups.append(["ggml-cpu*.dll"])
+ groups.append(["mtmd.dll"])
+ return groups
+
+
def runtime_payload_health_groups(
install_kind: str,
*,
source_label: str | None = None,
runtime_name: str | None = None,
+ tag: str | None = None,
) -> list[list[str]]:
"""Return required runtime file groups for an install kind."""
if install_kind in {"linux-cpu", "linux-arm64"}:
@@ -7001,9 +7037,9 @@ def runtime_payload_health_groups(
groups.append(["llama-diffusion-gemma-visual-server"])
return groups
if install_kind in {"windows-cpu", "windows-arm64"}:
- return [["llama.dll"]]
+ return _windows_shared_groups(source_label, tag)
if install_kind == "windows-cuda":
- groups = [["llama.dll"], ["ggml-cuda.dll"]]
+ groups = _windows_shared_groups(source_label, tag) + [["ggml-cuda.dll"]]
# Require the complete cudart trio only when it was paired with this install.
if runtime_name:
groups.append(["cudart64_*.dll"])
@@ -7011,9 +7047,9 @@ def runtime_payload_health_groups(
groups.append(["cublasLt64_*.dll"])
return groups
if install_kind in {"windows-hip", "windows-rocm"}:
- return [["llama.dll"], ["*hip*.dll"]]
+ return _windows_shared_groups(source_label, tag) + [["*hip*.dll"]]
if install_kind == "windows-vulkan":
- groups = [["llama.dll"], ["ggml-vulkan.dll"]]
+ groups = _windows_shared_groups(source_label, tag) + [["ggml-vulkan.dll"]]
if source_label == "published":
groups.append(["llama-diffusion-gemma-visual-server.exe"])
return groups
@@ -7049,6 +7085,7 @@ def runtime_payload_is_healthy(install_dir: Path, host: HostInfo, choice: AssetC
choice.install_kind,
source_label = choice.source_label,
runtime_name = choice.runtime_name,
+ tag = choice.tag,
),
)
@@ -7069,12 +7106,16 @@ def _kept_install_payload_is_healthy(install_dir: Path, host: HostInfo) -> bool:
# A backend can map to multiple kinds, so require only their shared payload.
runtime_asset = (marker or {}).get("runtime_asset")
source_label = (marker or {}).get("source")
+ marker_tag = (marker or {}).get("tag")
shared = set.intersection(
*(
{
tuple(group)
for group in runtime_payload_health_groups(
- kind, source_label = source_label, runtime_name = runtime_asset
+ kind,
+ source_label = source_label,
+ runtime_name = runtime_asset,
+ tag = marker_tag if isinstance(marker_tag, str) else None,
)
}
for kind in kinds
@@ -7317,10 +7358,14 @@ def validate_prebuilt_choice(
)
log(f"overlaying prebuilt bundle {choice.name} into {install_dir}")
server_path, quantize_path = install_from_archives(choice, host, install_dir, work_dir)
- if choice.install_kind in VULKAN_INSTALL_KINDS and not runtime_payload_is_healthy(
- install_dir, host, choice
- ):
- raise PrebuiltFallback(f"Vulkan bundle {choice.name} omitted a required runtime component")
+ # Every WINDOWS kind: gating only Vulkan activated a fresh tree missing
+ # llama-common.dll and reported success.
+ if (
+ choice.install_kind in VULKAN_INSTALL_KINDS or choice.install_kind.startswith("windows-")
+ ) and not runtime_payload_is_healthy(install_dir, host, choice):
+ raise PrebuiltFallback(
+ f"{choice.install_kind} bundle {choice.name} omitted a required runtime component"
+ )
preflight_linux_installed_binaries((server_path, quantize_path), install_dir, host)
preflight_macos_installed_binaries((server_path, quantize_path), install_dir, host)
ensure_repo_shape(install_dir)
diff --git a/tests/studio/install/test_install_llama_prebuilt_logic.py b/tests/studio/install/test_install_llama_prebuilt_logic.py
index 52ae197ee51..31bcb85647a 100644
--- a/tests/studio/install/test_install_llama_prebuilt_logic.py
+++ b/tests/studio/install/test_install_llama_prebuilt_logic.py
@@ -50,6 +50,7 @@ write_prebuilt_metadata = INSTALL_LLAMA_PREBUILT.write_prebuilt_metadata
existing_install_matches_plan = INSTALL_LLAMA_PREBUILT.existing_install_matches_plan
existing_install_matches_choice = INSTALL_LLAMA_PREBUILT.existing_install_matches_choice
ensure_diffusion_visual_server = INSTALL_LLAMA_PREBUILT.ensure_diffusion_visual_server
+runtime_payload_health_groups = INSTALL_LLAMA_PREBUILT.runtime_payload_health_groups
def linux_host() -> HostInfo:
@@ -2400,11 +2401,23 @@ def write_windows_install_shape(
include_llama_dll: bool = True,
include_cuda_dll: bool = False,
include_cudart_dlls: bool = False,
+ include_shared_runtime: bool = True,
) -> None:
runtime_dir = install_dir / "build" / "bin" / "Release"
runtime_dir.mkdir(parents = True, exist_ok = True)
(runtime_dir / "llama-server.exe").write_bytes(b"MZ")
(runtime_dir / "llama-quantize.exe").write_bytes(b"MZ")
+ if include_shared_runtime:
+ # What a BUILD_SHARED_LIBS bundle carries alongside llama.dll.
+ for name in (
+ "llama-common.dll",
+ "llama-server-impl.dll",
+ "ggml.dll",
+ "ggml-base.dll",
+ "ggml-cpu-x64.dll",
+ "mtmd.dll",
+ ):
+ (runtime_dir / name).write_bytes(b"DLL")
if include_llama_dll:
(runtime_dir / "llama.dll").write_bytes(b"DLL")
if include_cuda_dll:
@@ -6880,3 +6893,142 @@ def test_detect_host_reads_the_driver_cuda_version_from_a_localized_nvidia_smi(
host = INSTALL_LLAMA_PREBUILT.detect_host()
assert host.compute_caps == ["86"]
assert host.driver_cuda_version == (13, 1)
+
+
+def _flat(groups: list[list[str]]) -> set[str]:
+ return {pattern for group in groups for pattern in group}
+
+
+ "install_kind",
+ [
+ "windows-cpu",
+ "windows-arm64",
+ "windows-cuda",
+ "windows-hip",
+ "windows-rocm",
+ "windows-vulkan",
+ ],
+)
+def test_windows_prebuilt_health_requires_the_shared_runtime(install_kind: str):
+ """Requiring only llama.dll let a tree missing llama-common.dll validate and
+ then fail at exec."""
+ patterns = _flat(runtime_payload_health_groups(install_kind, source_label = "published"))
+ for required in (
+ "llama.dll",
+ "llama-common.dll",
+ "llama-server.exe",
+ "llama-server-impl.dll",
+ "ggml.dll",
+ "ggml-base.dll",
+ "ggml-cpu*.dll",
+ "mtmd.dll",
+ ):
+ assert required in patterns, f"{install_kind} does not require {required}"
+
+
+def test_windows_source_build_does_not_require_the_shared_runtime():
+ """setup.ps1 builds with -DBUILD_SHARED_LIBS=OFF, so requiring these would
+ fail a healthy tree."""
+ patterns = _flat(runtime_payload_health_groups("windows-cpu", source_label = None))
+ assert "llama.dll" in patterns
+ for absent in ("llama-common.dll", "llama-server-impl.dll", "mtmd.dll"):
+ assert absent not in patterns
+
+
+def test_windows_upstream_bundles_require_the_shared_runtime_too():
+ """Upstream ggml-org Windows zips are also built with shared libs on."""
+ patterns = _flat(runtime_payload_health_groups("windows-cpu", source_label = "upstream"))
+ assert "llama-common.dll" in patterns
+
+
+# Real win-cpu-x64 zip payloads either side of the impl split (llama.cpp#23462).
+_PRE_SPLIT_WINDOWS_PAYLOAD = (
+ "llama.dll",
+ "llama-common.dll",
+ "llama-server.exe",
+ "ggml.dll",
+ "ggml-base.dll",
+ "ggml-cpu-haswell.dll",
+ "mtmd.dll",
+)
+_POST_SPLIT_WINDOWS_PAYLOAD = _PRE_SPLIT_WINDOWS_PAYLOAD + ("llama-server-impl.dll",)
+
+
+ ("tag", "payload", "healthy"),
+ [
+ ("b9279", _PRE_SPLIT_WINDOWS_PAYLOAD, True),
+ ("b9283", _POST_SPLIT_WINDOWS_PAYLOAD, True),
+ ("b9283", _PRE_SPLIT_WINDOWS_PAYLOAD, False),
+ ],
+ ids = ["pre-split-monolithic", "post-split-complete", "post-split-truncated"],
+)
+def test_pre_split_upstream_windows_pin_is_not_forced_to_a_source_build(
+ tmp_path: Path, tag: str, payload: tuple[str, ...], healthy: bool
+):
+ """A pinned upstream tag older than b9283 ships no llama-server-impl.dll.
+
+ Requiring it unconditionally made validate_prebuilt_choice reject a valid
+ downloaded prebuilt and fall back to a costly Windows source build.
+ """
+ install_dir = tmp_path / "llama.cpp"
+ runtime_dir = install_dir / "build" / "bin" / "Release"
+ runtime_dir.mkdir(parents = True)
+ for name in payload:
+ (runtime_dir / name).write_bytes(b"DLL")
+
+ choice = AssetChoice(
+ repo = "ggml-org/llama.cpp",
+ tag = tag,
+ name = f"llama-{tag}-bin-win-cpu-x64.zip",
+ url = f"https://github.com/ggml-org/llama.cpp/releases/download/{tag}/x.zip",
+ source_label = "upstream",
+ install_kind = "windows-cpu",
+ )
+ assert (
+ INSTALL_LLAMA_PREBUILT.runtime_payload_is_healthy(install_dir, _windows_host(), choice)
+ is healthy
+ )
+
+
+def test_existing_install_matches_plan_windows_rejects_missing_llama_common(tmp_path: Path):
+ install_dir = tmp_path / "llama.cpp"
+ install_dir.mkdir()
+ write_windows_install_shape(install_dir, include_llama_dll = True)
+ runtime_dir = install_dir / "build" / "bin" / "Release"
+ (runtime_dir / "llama-common.dll").unlink()
+
+ groups = runtime_payload_health_groups("windows-cpu", source_label = "published")
+ host = HostInfo(
+ system = "Windows",
+ machine = "AMD64",
+ is_windows = True,
+ is_linux = False,
+ is_macos = False,
+ is_x86_64 = True,
+ is_arm64 = False,
+ nvidia_smi = None,
+ driver_cuda_version = None,
+ compute_caps = [],
+ visible_cuda_devices = None,
+ has_physical_nvidia = False,
+ has_usable_nvidia = False,
+ )
+ assert INSTALL_LLAMA_PREBUILT._runtime_payload_has(install_dir, host, groups) is False
+
+ (runtime_dir / "llama-common.dll").write_bytes(b"DLL")
+ assert INSTALL_LLAMA_PREBUILT._runtime_payload_has(install_dir, host, groups) is True
+
+
+def test_a_fresh_windows_install_is_payload_checked_not_just_vulkan():
+ """A source guard: reaching that call needs a real download, but the check
+ has to run where the bundle is unpacked, not only on the reuse path."""
+ source = MODULE_PATH.read_text(encoding = "utf-8")
+ gate = source[source.index("overlaying prebuilt bundle") :]
+ gate = gate[: gate.index("preflight_linux_installed_binaries")]
+ assert "runtime_payload_is_healthy" in gate, "fresh installs are not payload checked at all"
+ assert (
+ 'choice.install_kind.startswith("windows-")' in gate
+ ), "fresh Windows installs are not payload checked"
+ assert "VULKAN_INSTALL_KINDS" in gate, "the Vulkan check must not be dropped"
diff --git a/tests/studio/install/test_keep_install_backcompat_9979.py b/tests/studio/install/test_keep_install_backcompat_9979.py
index de568a80c06..1ff51ad43c4 100644
--- a/tests/studio/install/test_keep_install_backcompat_9979.py
+++ b/tests/studio/install/test_keep_install_backcompat_9979.py
@@ -128,7 +128,16 @@ _SHARED_PAYLOAD = {
"libggml-cpu.so",
"libmtmd.so",
],
- "windows": ["llama.dll"],
+ # Written unconditionally: the check is "has", not "has only".
+ "windows": [
+ "llama.dll",
+ "llama-common.dll",
+ "llama-server-impl.dll",
+ "ggml.dll",
+ "ggml-base.dll",
+ "ggml-cpu.dll",
+ "mtmd.dll",
+ ],
"macos": ["libllama.dylib", "libggml.dylib", "libmtmd.dylib"],
}
_BACKEND_PAYLOAD = {