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.

Repair a quarantined llama.cpp runtime at launch instead of failing at model load (#10494)

Daniel Hanacf2de64c3cf
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 5983cdc0a31..13bc4b52d46 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -6938,6 +6938,18 @@ def _metal_capable_host() -> bool:
return sys.platform == "darwin"
+# Shared with the settings reader so the search, the settings UI and the process
+# allowlist expand one value the same way, and none of them raises on a named user
+# the password database cannot answer for. Path.expanduser() does raise, which is
+# what took runtime discovery down on a stale ~deleted-user pin.
+def _expanded_user_path(value) -> Path:
+ try:
+ from utils.llama_cpp_path_settings import expanded_user_path
+ return expanded_user_path(value)
+ except Exception:
+ return Path(os.path.expanduser(str(value)))
+
+
def _write_direct_stream_key(key: str) -> "Path":
"""Store the direct-streaming key where only the server user can read it."""
from utils.paths.storage_roots import auth_root
@@ -8612,7 +8624,18 @@ class LlamaCppBackend:
custom_llama_cpp = os.environ.get("UNSLOTH_LLAMA_CPP_PATH")
managed_path_marker = os.environ.get("UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH") == "1"
if custom_llama_cpp and not managed_path_marker:
- hit, locked = _scan_pinned(_layout_candidates(Path(custom_llama_cpp)))
+ # expanduser, like every other reader of this variable:
+ # default_managed_llama_dir, get_stored_custom_llama_cpp_path and the
+ # desktop's own pinning all expand it, and the literal lookup here was
+ # the only one that did not. A "~/llama.cpp" written into a service
+ # unit, a .env or the Windows environment dialog reaches the process
+ # unexpanded, and the literal form made this search a folder named ~
+ # beside the working directory, walk past it, and load a different
+ # runtime than every other component was reporting on.
+ # Not Path.expanduser: it raises RuntimeError on a name it cannot
+ # resolve, so a stale ~deleted-user pin made discovery itself throw
+ # instead of falling through to the rest of the order below.
+ hit, locked = _scan_pinned(_layout_candidates(_expanded_user_path(custom_llama_cpp)))
if locked is not None:
return _unavailable(locked)
if hit:
@@ -32079,7 +32102,10 @@ class LlamaCppBackend:
# UNSLOTH_LLAMA_CPP_PATH env var (custom install dir)
custom_dir = os.environ.get("UNSLOTH_LLAMA_CPP_PATH")
if custom_dir:
- install_roots.append(Path(custom_dir))
+ # expanduser to match _find_llama_server_binary: the allowlist has
+ # to name the tree discovery actually spawns from, or a server
+ # started out of an expanded ~ is one this refuses to clean up.
+ install_roots.append(_expanded_user_path(custom_dir))
# LLAMA_SERVER_PATH env var (exact binary path)
exact_binaries: list[Path] = []
diff --git a/studio/backend/tests/test_llama_cpp_path_settings.py b/studio/backend/tests/test_llama_cpp_path_settings.py
index 8b479cb019d..02383e88b40 100644
--- a/studio/backend/tests/test_llama_cpp_path_settings.py
+++ b/studio/backend/tests/test_llama_cpp_path_settings.py
@@ -360,3 +360,61 @@ def test_settings_route_returns_the_specific_validation_error(settings_store, tm
f"No executable {path_settings.llama_server_binary_name()} was found in that folder "
"or its build/bin directory."
)
+
+
+# The account that does not exist anywhere, which is what a rename leaves behind in a
+# service unit or a .env.
+_UNKNOWN_USER = "~no-such-account-anywhere/llama.cpp"
+
+
+def test_an_unresolvable_named_user_does_not_raise_out_of_the_expansion():
+ """Codex 3962583754, P2. Path.expanduser() raises RuntimeError on a name it cannot
+ resolve, unlike os.path.expanduser, which hands the value straight back.
+
+ Measured on this host:
+
+ Path("~no-such-account-anywhere/llama.cpp").expanduser()
+ RuntimeError: Could not determine home directory.
+
+ Every reader of UNSLOTH_LLAMA_CPP_PATH used the raising form, so a stale pin made
+ runtime discovery itself throw rather than treating the override as unusable and
+ continuing down the documented search order.
+ """
+ with pytest.raises(RuntimeError):
+ Path(_UNKNOWN_USER).expanduser()
+ assert path_settings.expanded_user_path(_UNKNOWN_USER) == Path(_UNKNOWN_USER)
+
+
+def test_the_resolvable_forms_still_expand(monkeypatch, tmp_path):
+ """The guard must not cost the expansion that was the point of adding it."""
+ monkeypatch.setenv("HOME", str(tmp_path))
+ monkeypatch.setenv("USERPROFILE", str(tmp_path))
+ assert path_settings.expanded_user_path("~/llama.cpp") == tmp_path / "llama.cpp"
+ assert path_settings.expanded_user_path("~") == tmp_path
+ absolute = tmp_path / "elsewhere" / "llama.cpp"
+ assert path_settings.expanded_user_path(absolute) == absolute
+ assert path_settings.expanded_user_path("relative/llama.cpp") == Path("relative/llama.cpp")
+
+
+def test_the_status_payload_survives_an_unresolvable_override(settings_store, monkeypatch):
+ """The UI reads this, and a raise here is a broken settings page rather than a
+ message saying the pin is unusable."""
+ monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", _UNKNOWN_USER)
+ status = path_settings.custom_llama_cpp_path_status()
+ assert status["source"] == "environment"
+ assert status["path"] == _UNKNOWN_USER
+ assert status["resolved_binary"] is None
+ assert status["available"] is False
+
+
+def test_discovery_continues_past_an_unresolvable_override(monkeypatch, tmp_path):
+ """The failure the item is actually about: _find_llama_server_binary threw instead
+ of falling through, and several callers have no exception boundary, so a model
+ operation reported the expansion error rather than using another runtime."""
+ llama_cpp = pytest.importorskip("core.inference.llama_cpp")
+ monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", _UNKNOWN_USER)
+ monkeypatch.delenv("UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH", raising = False)
+ # Not asserting which runtime is found: the machine decides that. The claim under
+ # test is only that the search reaches its own answer instead of raising.
+ result = llama_cpp.LlamaCppBackend._find_llama_server_binary()
+ assert result is None or isinstance(result, (str, Path, tuple))
diff --git a/studio/backend/utils/llama_cpp_path_settings.py b/studio/backend/utils/llama_cpp_path_settings.py
index f875587e298..d16476a43e8 100644
--- a/studio/backend/utils/llama_cpp_path_settings.py
+++ b/studio/backend/utils/llama_cpp_path_settings.py
@@ -21,6 +21,24 @@ _settings_lock = threading.RLock()
_path_revision = 0
+def expanded_user_path(value: Path | str) -> Path:
+ """``~`` and ``~name`` expanded, never raising on a name that does not resolve.
+
+ ``Path.expanduser()`` raises ``RuntimeError`` when the home cannot be
+ determined, which includes every unknown named user: ``~deleted-user/llama.cpp``
+ left in a service unit or a ``.env`` after an account rename took runtime
+ discovery down with it, so a model operation reported the expansion error
+ rather than falling through to another runtime or saying none was found.
+
+ ``os.path.expanduser`` is the reader that does not raise: it hands an
+ unresolvable name straight back, which is also what the desktop's pinning does
+ with one, so the two halves of a launch still agree about the value. An
+ unexpandable override then reaches the search as an ordinary path, finds
+ nothing, and the documented order continues.
+ """
+ return Path(os.path.expanduser(str(value)))
+
+
def mark_managed_llama_cpp_path(directory: Path | str) -> bool:
"""Mark Unsloth's inherited install path without hiding a real env override."""
configured = os.environ.get("UNSLOTH_LLAMA_CPP_PATH", "").strip()
@@ -28,8 +46,8 @@ def mark_managed_llama_cpp_path(directory: Path | str) -> bool:
os.environ.pop(MANAGED_LLAMA_CPP_PATH_MARKER, None)
return False
try:
- managed = Path(directory).expanduser().resolve(strict = False)
- inherited = Path(configured).expanduser().resolve(strict = False)
+ managed = expanded_user_path(directory).resolve(strict = False)
+ inherited = expanded_user_path(configured).resolve(strict = False)
is_managed = inherited == managed
except (OSError, RuntimeError, ValueError):
is_managed = False
@@ -246,7 +264,7 @@ def get_stored_custom_llama_cpp_path() -> Optional[Path]:
value = value.strip()
if not value or len(value) > MAX_CUSTOM_LLAMA_CPP_PATH_LENGTH:
return None
- return Path(value).expanduser()
+ return expanded_user_path(value)
def _environment_override() -> tuple[Optional[str], Optional[str], bool]:
@@ -277,7 +295,7 @@ def _canonical_directory(value: str) -> Path:
if len(raw) > MAX_CUSTOM_LLAMA_CPP_PATH_LENGTH:
raise ValueError("The llama.cpp folder path is too long.")
try:
- directory = Path(raw).expanduser().resolve(strict = True)
+ directory = expanded_user_path(raw).resolve(strict = True)
except (OSError, RuntimeError, ValueError) as exc:
raise ValueError("The llama.cpp folder does not exist or cannot be accessed.") from exc
if not directory.is_dir():
@@ -321,7 +339,7 @@ def custom_llama_cpp_path_status() -> dict:
if env_path is not None:
source = "environment"
- path = Path(env_path).expanduser()
+ path = expanded_user_path(env_path)
if direct_binary:
binary = path if _usable_binary(path) else None
else:
diff --git a/studio/frontend/src/hooks/backend-preflight-message.ts b/studio/frontend/src/hooks/backend-preflight-message.ts
index 494408a788e..b219578c0a4 100644
--- a/studio/frontend/src/hooks/backend-preflight-message.ts
+++ b/studio/frontend/src/hooks/backend-preflight-message.ts
@@ -17,6 +17,15 @@ export const MANAGED_ENVIRONMENT_BUSY = "managed_environment_busy";
/// Mirrors MANAGED_ENVIRONMENT_UPDATING in studio/src-tauri/src/preflight/managed.rs.
export const MANAGED_ENVIRONMENT_UPDATING = "managed_environment_updating";
+/// The managed llama.cpp runtime is installed but missing files. Mirrors the
+/// reasons installed_runtime_health() returns in studio/install_llama_prebuilt.py.
+export const LLAMA_RUNTIME_REASONS = [
+ "llama_runtime_dir_missing",
+ "llama_runtime_payload_incomplete",
+ "llama_runtime_binaries_missing",
+ "llama_runtime_incomplete",
+];
+
export function preflightStaleMessage(
disposition: string,
reason: string | null,
@@ -40,6 +49,21 @@ export function preflightStaleMessage(
const which = setting ? `${setting} points` : "One of Unsloth's folder settings points";
return `${which} somewhere that cannot be resolved, so Unsloth has nowhere safe to run from. Set it to a full path, such as D:\\unsloth-cache, and try again.`;
}
+ // The install is current, some of its files are gone, so "too old" sends people
+ // to an update that reports they are up to date. Name the usual cause: a
+ // reinstall into the same quarantine needs an exclusion, not a retry.
+ if (LLAMA_RUNTIME_REASONS.includes(kind)) {
+ // Named, because "allow the folder" leaves the user to find out which folder,
+ // and an exclusion is the one step that stops this recurring. The default
+ // root, since UNSLOTH_LLAMA_CPP_PATH can move it and preflight does not send
+ // the path: hedged with "usually" rather than asserted. Windows spelling on
+ // Windows, the same platform test the roaming-profile hint above uses.
+ const folder =
+ typeof navigator !== "undefined" && /Win/i.test(navigator.platform ?? "")
+ ? "%USERPROFILE%\\.unsloth\\llama.cpp"
+ : "~/.unsloth/llama.cpp";
+ return `Unsloth's llama.cpp runtime is missing files, which usually means security software quarantined them. Run \`unsloth studio update\` to reinstall it, and allow the folder it installs into, usually ${folder}, in your antivirus if it happens again.`;
+ }
if (disposition === "owned_stale") {
return "Desktop-owned Unsloth backend is too old for this desktop app. Run `unsloth studio update`, then restart Unsloth.";
}
diff --git a/studio/frontend/tests/backend-preflight-message.test.ts b/studio/frontend/tests/backend-preflight-message.test.ts
index aa4851b9d06..f28b2fefa8d 100644
--- a/studio/frontend/tests/backend-preflight-message.test.ts
+++ b/studio/frontend/tests/backend-preflight-message.test.ts
@@ -6,8 +6,9 @@ import { readFile } from "node:fs/promises";
import test from "node:test";
// use-tauri-backend.ts pulls in React and the Tauri APIs, so the message choice
-// lives in its own module and is driven directly here.
+// lives in its own module.
import {
+ LLAMA_RUNTIME_REASONS,
MANAGED_ENVIRONMENT_BUSY,
MANAGED_ENVIRONMENT_UPDATING,
WORKING_DIRECTORY_UNAVAILABLE,
@@ -20,6 +21,7 @@ const UPDATE_ADVICE = /unsloth studio update/;
const MANAGED_TOO_OLD = /Managed Unsloth install is too old/;
const OWNED_TOO_OLD = /Desktop-owned Unsloth backend is too old/;
const TOO_OLD = /too old/;
+const RUNTIME_MISSING_FILES = /llama\.cpp runtime is missing files/;
test("an unreachable profile is not reported as an outdated install", () => {
for (const disposition of ["managed_stale", "owned_stale"]) {
@@ -28,7 +30,7 @@ test("an unreachable profile is not reported as an outdated install", () => {
WORKING_DIRECTORY_UNAVAILABLE,
);
assert.match(message, UNREACHABLE_PROFILE);
- // Updating needs the same folder, so it must not be the advice given.
+ // Updating needs the same folder, so it must not be the advice.
assert.doesNotMatch(message, UPDATE_ADVICE);
}
});
@@ -50,9 +52,8 @@ test("the reason string matches the one the Rust side sends", () => {
});
test("the roaming-profile cause is offered on Windows and withheld elsewhere", () => {
- // The probe calls `home_dir_available()` ungated, so this reason reaches Linux
- // and macOS, where the same symptom is an unmounted home or a permissions
- // problem rather than a roaming profile.
+ // The probe is ungated, so this reason reaches Linux and macOS, where the cause
+ // is an unmounted home or permissions rather than a roaming profile.
const original = globalThis.navigator;
const withPlatform = (platform: string) => {
Object.defineProperty(globalThis, "navigator", {
@@ -66,7 +67,7 @@ test("the roaming-profile cause is offered on Windows and withheld elsewhere", (
for (const platform of ["Linux x86_64", "MacIntel"]) {
const message = withPlatform(platform);
assert.doesNotMatch(message, /roaming profile/);
- // The symptom and the remedy still have to survive the trim.
+ // Symptom and remedy still survive the trim.
assert.match(message, UNREACHABLE_PROFILE);
assert.match(message, /Reconnect and try again/);
}
@@ -81,14 +82,14 @@ test("the roaming-profile cause is offered on Windows and withheld elsewhere", (
test("a path setting that cannot be resolved is told apart from an unreachable folder", () => {
const message = preflightStaleMessage("managed_stale", PATH_SETTING_UNRESOLVABLE);
assert.match(message, /folder settings/);
- // Not the profile, and not something an update can fix: the value is the fix.
+ // Not the profile, and not fixable by an update: the value is the fix.
assert.doesNotMatch(message, /user folder/);
assert.doesNotMatch(message, /update/);
});
test("the setting that could not be resolved is named", () => {
- // "one of Unsloth's folder settings" is not something anyone can act on, so
- // the backend appends the name and the message uses it.
+ // "one of Unsloth's folder settings" is not actionable, so the backend appends
+ // the name and the message uses it.
const named = preflightStaleMessage(
"managed_stale",
`${PATH_SETTING_UNRESOLVABLE}:HF_HOME`,
@@ -101,6 +102,153 @@ test("the setting that could not be resolved is named", () => {
assert.doesNotMatch(unnamed, UPDATE_ADVICE);
});
+test("a quarantined llama.cpp runtime is not reported as an outdated install", () => {
+ // "too old" would send the user to an update that reports they are up to date.
+ // Every reason the health check can produce must reach the new message.
+ for (const reason of LLAMA_RUNTIME_REASONS) {
+ for (const disposition of ["managed_stale", "owned_stale"]) {
+ const message = preflightStaleMessage(disposition, reason);
+ assert.match(message, RUNTIME_MISSING_FILES);
+ assert.doesNotMatch(message, TOO_OLD);
+ // A reinstall is the fix here, so the update command must survive.
+ assert.match(message, UPDATE_ADVICE);
+ // A reinstall into the same quarantine needs an exclusion, not a retry.
+ assert.match(message, /quarantined/);
+ // And an exclusion needs a folder, so the advice has to name one.
+ assert.match(message, /\.unsloth[\\/]llama\.cpp/);
+ }
+ }
+});
+
+test("the folder to exclude is spelled the way the platform spells it", () => {
+ // The user pastes this into an antivirus exclusion list, so a POSIX path on
+ // Windows is not advice. Same platform test as the roaming-profile hint.
+ const original = globalThis.navigator;
+ const withPlatform = (platform: string) => {
+ Object.defineProperty(globalThis, "navigator", {
+ value: { platform },
+ configurable: true,
+ });
+ return preflightStaleMessage("managed_stale", "llama_runtime_payload_incomplete");
+ };
+ try {
+ const windows = withPlatform("Win32");
+ assert.match(windows, /%USERPROFILE%\\\.unsloth\\llama\.cpp/);
+ assert.doesNotMatch(windows, /~\//);
+ for (const platform of ["Linux x86_64", "MacIntel"]) {
+ const message = withPlatform(platform);
+ assert.match(message, /~\/\.unsloth\/llama\.cpp/);
+ assert.doesNotMatch(message, /%USERPROFILE%/);
+ }
+ } finally {
+ Object.defineProperty(globalThis, "navigator", {
+ value: original,
+ configurable: true,
+ });
+ }
+});
+
+test("a missing navigator does not cost the folder advice", () => {
+ // The hook runs under node in these tests and in any non-browser context the
+ // desktop shell hands it; the POSIX spelling is the fallback, not no advice.
+ const original = globalThis.navigator;
+ try {
+ Object.defineProperty(globalThis, "navigator", {
+ value: undefined,
+ configurable: true,
+ });
+ assert.match(
+ preflightStaleMessage("managed_stale", "llama_runtime_binaries_missing"),
+ /~\/\.unsloth\/llama\.cpp/,
+ );
+ } finally {
+ Object.defineProperty(globalThis, "navigator", {
+ value: original,
+ configurable: true,
+ });
+ }
+});
+
+test("the llama runtime reasons match the ones the Python and Rust sides send", () => {
+ // installed_runtime_health() returns the first three; managed.rs substitutes the
+ // fourth when the CLI reports llama_runtime_ok false with an empty reason. A
+ // string that drifts on either side silently falls through to "too old".
+ assert.deepEqual(LLAMA_RUNTIME_REASONS, [
+ "llama_runtime_dir_missing",
+ "llama_runtime_payload_incomplete",
+ "llama_runtime_binaries_missing",
+ "llama_runtime_incomplete",
+ ]);
+});
+
+test("an unrelated stale reason is still reported as an outdated install", () => {
+ // Only a reason that names the runtime may change the message.
+ for (const reason of [
+ "backend_outdated",
+ "studio_install_incomplete",
+ "desktop_backend_ownership_unsupported",
+ // Near misses: the match is on the whole token before the colon.
+ "llama_runtime",
+ "not_llama_runtime_dir_missing",
+ "llama_runtime_dir_missing_extra",
+ ]) {
+ const message = preflightStaleMessage("managed_stale", reason);
+ assert.match(message, MANAGED_TOO_OLD);
+ assert.doesNotMatch(message, RUNTIME_MISSING_FILES);
+ }
+ assert.match(
+ preflightStaleMessage("owned_stale", "backend_outdated"),
+ OWNED_TOO_OLD,
+ );
+});
+
+test("a suffix on a llama runtime reason does not change the message", () => {
+ // The split applies to every reason, so a runtime reason that ever gains a
+ // suffix must still match on the token before the colon.
+ for (const reason of LLAMA_RUNTIME_REASONS) {
+ assert.match(
+ preflightStaleMessage("managed_stale", `${reason}:llama-server.exe`),
+ RUNTIME_MISSING_FILES,
+ );
+ // split(":", 2) drops anything after the second colon, harmless since the
+ // message ignores the suffix.
+ assert.match(
+ preflightStaleMessage("managed_stale", `${reason}:C:\\quarantine`),
+ RUNTIME_MISSING_FILES,
+ );
+ }
+});
+
+test("an absent or empty reason still falls through to the old behaviour", () => {
+ // reason is optional and the CLI defaults it to "", so neither may be mistaken
+ // for a runtime reason.
+ for (const reason of [null, "", ":", ":llama_runtime_dir_missing"]) {
+ assert.match(
+ preflightStaleMessage("managed_stale", reason),
+ MANAGED_TOO_OLD,
+ );
+ assert.match(preflightStaleMessage("owned_stale", reason), OWNED_TOO_OLD);
+ }
+});
+
+test("the context reasons still win over the runtime reason", () => {
+ // Both are checked first, and both would be made worse by advice to reinstall
+ // the runtime into them.
+ const unreachable = preflightStaleMessage(
+ "managed_stale",
+ WORKING_DIRECTORY_UNAVAILABLE,
+ );
+ assert.match(unreachable, UNREACHABLE_PROFILE);
+ assert.doesNotMatch(unreachable, RUNTIME_MISSING_FILES);
+
+ const unresolvable = preflightStaleMessage(
+ "managed_stale",
+ `${PATH_SETTING_UNRESOLVABLE}:HF_HOME`,
+ );
+ assert.match(unresolvable, /HF_HOME points somewhere/);
+ assert.doesNotMatch(unresolvable, RUNTIME_MISSING_FILES);
+});
+
test("the busy reasons are spelled the same in Rust", async () => {
const native = await readFile(
new URL("../../src-tauri/src/preflight/managed.rs", import.meta.url),
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index 222b7a404eb..f9d52f2a2cc 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -7759,7 +7759,13 @@ def _windows_shared_groups(source_label: str | None, tag: str | None = None) ->
groups.append(["llama-server.exe"])
build = _release_build_number(tag)
if build is None or build >= LLAMA_SERVER_IMPL_SPLIT_BUILD:
+ # Both halves of the split, not just the server's. llama-quantize.exe
+ # links against llama-quantize-impl.dll exactly as llama-server.exe
+ # links against llama-server-impl.dll, and a b10798 windows-x64-rocm
+ # bundle ships both; requiring only one let a quarantined quantize
+ # implementation read as healthy while quantization could not start.
groups.append(["llama-server-impl.dll"])
+ groups.append(["llama-quantize-impl.dll"])
groups.append(["ggml.dll"])
groups.append(["ggml-base.dll"])
groups.append(["ggml-cpu*.dll"])
@@ -7767,14 +7773,83 @@ def _windows_shared_groups(source_label: str | None, tag: str | None = None) ->
return groups
+"""The CUDA runtime a windows-cuda bundle pairs with, installed and removed together."""
+_CUDA_RUNTIME_TRIO = ("cudart64_*.dll", "cublas64_*.dll", "cublasLt64_*.dll")
+
+
+def _has_a_paired_cuda_runtime(install_dir: Path) -> bool:
+ """Whether a windows-cuda tree carries any member of that trio.
+
+ A marker written before ``runtime_asset`` existed names no paired archive, so the
+ trio was dropped from the table entirely and losing one member read as healthy while
+ llama-server.exe died in the loader with no repair offered and no marker backfilled.
+ The three arrive and go together, so one of them still being there is what says this
+ install was paired; a machine running on a system CUDA toolkit has none and is asked
+ for none.
+ """
+ runtime_dir = install_dir / "build" / "bin" / "Release"
+ return any(
+ any(_payload_match_is_loadable(match) for match in runtime_dir.glob(pattern))
+ for pattern in _CUDA_RUNTIME_TRIO
+ )
+
+
+def _linux_split_entrypoint_groups(
+ source_label: str | None, tag: str | None = None
+) -> list[list[str]]:
+ """The impl libraries a Linux entrypoint links against, when the release has them.
+
+ The same upstream split that gave Windows ``llama-server-impl.dll`` gives Linux
+ ``libllama-server-impl.so``: ``llama-server`` and ``llama-quantize`` carry no
+ entry code of their own any more and load these by DT_NEEDED. The library
+ groups above name only the shared libraries, so quarantining one of these left
+ every group satisfied while ``llama-server`` died in the loader and
+ ``_existing_install_runs`` returned false, which is the disagreement this whole
+ probe exists to prevent. Measured on a b10360 managed install: removing either
+ one leaves ``installed_runtime_health`` answering ``(True, "")`` and
+ ``_existing_install_runs`` answering false.
+
+ Gated exactly as the Windows side is, and on the same build for the same
+ reason: an older monolithic archive is healthy without them, and requiring one
+ a bundle does not carry would reinstall on every check forever.
+ """
+ if source_label not in {"published", "upstream"}:
+ return []
+ build = _release_build_number(tag)
+ if build is not None and build < LLAMA_SERVER_IMPL_SPLIT_BUILD:
+ return []
+ return [["libllama-server-impl.so*"], ["libllama-quantize-impl.so*"]]
+
+
+def _macos_split_entrypoint_groups(
+ source_label: str | None, tag: str | None = None
+) -> list[list[str]]:
+ """The macOS half of the same upstream split, gated by the same rule.
+
+ The bundles carry them: b10840 and b11007 macos-arm64 both ship
+ libllama-server-impl.dylib and libllama-quantize-impl.dylib, and
+ _PREBUILT_TREE_EVIDENCE already reads the first as proof of a prebuilt macOS tree.
+ Without them here every group and both executable checks passed while dyld could not
+ start the entrypoint. Delegates the gate so the build floor cannot drift from Linux.
+ """
+ if not _linux_split_entrypoint_groups(source_label, tag):
+ return []
+ return [["libllama-server-impl*.dylib"], ["libllama-quantize-impl*.dylib"]]
+
+
def runtime_payload_health_groups(
install_kind: str,
*,
source_label: str | None = None,
runtime_name: str | None = None,
tag: str | None = None,
+ install_dir: Path | None = None,
) -> list[list[str]]:
- """Return required runtime file groups for an install kind."""
+ """Return required runtime file groups for an install kind.
+
+ ``install_dir`` is read only where the marker cannot answer on its own, which today
+ is the windows-cuda trio a legacy marker does not name.
+ """
if install_kind in {"linux-cpu", "linux-arm64"}:
return [
["libllama-common.so*"],
@@ -7783,7 +7858,7 @@ def runtime_payload_health_groups(
["libggml-base.so*"],
["libggml-cpu*.so*"],
["libmtmd.so*"],
- ]
+ ] + _linux_split_entrypoint_groups(source_label, tag)
if install_kind in {"linux-cuda", "linux-arm64-cuda"}:
return [
["libllama-common.so*"],
@@ -7793,13 +7868,33 @@ def runtime_payload_health_groups(
["libggml-cpu*.so*"],
["libmtmd.so*"],
["libggml-cuda.so*"],
- ]
+ ] + _linux_split_entrypoint_groups(source_label, tag)
if install_kind in {"macos-arm64", "macos-x64"}:
+ # One group per library, not three broad alternatives. A real bundle
+ # ships libggml, libggml-base, libggml-blas, libggml-cpu, libggml-metal
+ # and libggml-rpc, so a single libggml*.dylib group stayed satisfied by
+ # the siblings after the one the loader needs was quarantined, and the
+ # tree reported healthy while llama-server died in dyld. The names are
+ # taken from the shipped macos-arm64 bundle rather than guessed. The dot
+ # is what keeps each pattern off its siblings: libggml.* cannot match
+ # libggml-base. Each library is a symlink chain onto one versioned file
+ # (libggml.dylib -> libggml.0.dylib -> libggml.0.23.0.dylib). Losing the
+ # target is caught by the resolved is_file test in
+ # _payload_match_is_loadable, and losing the middle link, which is the
+ # install name dyld actually asks for, by the version-depth test there:
+ # libggml.0.23.0.dylib cannot satisfy the group on its own.
+ #
+ # blas, metal and rpc are deliberately absent: they are the accelerator
+ # and transport backends, the way libggml-cuda is on Linux, and requiring
+ # one a bundle does not carry would reinstall every install that lacks it.
return [
- ["libllama*.dylib"],
- ["libggml*.dylib"],
- ["libmtmd*.dylib"],
- ]
+ ["libllama-common.dylib", "libllama-common.*.dylib"],
+ ["libllama.dylib", "libllama.*.dylib"],
+ ["libggml.dylib", "libggml.*.dylib"],
+ ["libggml-base.dylib", "libggml-base.*.dylib"],
+ ["libggml-cpu.dylib", "libggml-cpu.*.dylib"],
+ ["libmtmd.dylib", "libmtmd.*.dylib"],
+ ] + _macos_split_entrypoint_groups(source_label, tag)
if install_kind == "linux-rocm":
return [
["libllama-common.so*"],
@@ -7809,7 +7904,7 @@ def runtime_payload_health_groups(
["libggml-cpu*.so*"],
["libmtmd.so*"],
["libggml-hip.so*"],
- ]
+ ] + _linux_split_entrypoint_groups(source_label, tag)
if install_kind == "linux-vulkan":
groups = [
["libllama-common.so*"],
@@ -7826,19 +7921,24 @@ def runtime_payload_health_groups(
]
if source_label == "published":
groups.append(["llama-diffusion-gemma-visual-server"])
- return groups
+ return groups + _linux_split_entrypoint_groups(source_label, tag)
if install_kind in {"windows-cpu", "windows-arm64"}:
return _windows_shared_groups(source_label, tag)
if install_kind in {"windows-cuda", "windows-arm64-cuda"}:
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:
+ if runtime_name or (install_dir is not None and _has_a_paired_cuda_runtime(install_dir)):
groups.append(["cudart64_*.dll"])
groups.append(["cublas64_*.dll"])
groups.append(["cublasLt64_*.dll"])
return groups
if install_kind in {"windows-hip", "windows-rocm"}:
- return _windows_shared_groups(source_label, tag) + [["*hip*.dll"]]
+ # ggml-hip.dll by name. A real ROCm bundle carries amdhip64_7.dll,
+ # hipblas.dll and libhipblaslt.dll beside it, all of which match a
+ # "*hip*.dll" group, so quarantining the one module ggml actually loads
+ # left the group satisfied by three libraries that cannot stand in for it.
+ # Measured on app-b10798-mix-659e406-windows-x64-rocm-gfx1150.zip.
+ return _windows_shared_groups(source_label, tag) + [["ggml-hip*.dll"]]
if install_kind == "windows-vulkan":
groups = _windows_shared_groups(source_label, tag) + [["ggml-vulkan.dll"]]
if source_label == "published":
@@ -7853,6 +7953,125 @@ def install_runtime_dir(install_dir: Path, host: HostInfo) -> Path:
return install_dir / "build" / "bin"
+"""``libfoo.so``, or ``libfoo.so.0``, but not ``libfoo.so.0.0.10360``."""
+_LINKER_NAME_RE = re.compile(r"^.+\.so(?P<version>(?:\.\d+)*)$")
+"""``libfoo.dylib``, or ``libfoo.0.dylib``, but not ``libfoo.0.23.0.dylib``."""
+_DYLIB_NAME_RE = re.compile(r"^.+?(?P<version>(?:\.\d+)*)\.dylib$")
+
+
+def _family_base(name: str) -> str | None:
+ """``libllama`` for every spelling of the libllama family, or None if not one."""
+ if name.endswith(".dylib"):
+ stem = name[: -len(".dylib")]
+ return re.sub(r"(?:\.\d+)+$", "", stem) or None
+ at = name.find(".so")
+ if at <= 0:
+ return None
+ if name[at + 3 :] and not re.fullmatch(r"(?:\.\d+)+", name[at + 3 :]):
+ return None
+ return name[:at]
+
+
+def _has_versioned_siblings(path: Path) -> bool:
+ """Whether a versionless library sits beside versioned copies of itself.
+
+ A family that only ever ships one unversioned file (``libggml-cpu-x64.so``) is
+ loadable under that name, and the versionless member of a versioned family is
+ not: the loader asks for the SONAME, one component deep. Reading the directory
+ is the only way to tell those apart, since both are the same name.
+ """
+ base = _family_base(path.name)
+ if base is None:
+ return False
+ try:
+ siblings = list(path.parent.iterdir())
+ except OSError:
+ # Unreadable directory: keep the older, more permissive answer rather than
+ # calling a tree broken over something that was never inspected.
+ return False
+ for sibling in siblings:
+ if sibling.name == path.name or _family_base(sibling.name) != base:
+ continue
+ match = _LINKER_NAME_RE.match(sibling.name) or _DYLIB_NAME_RE.match(sibling.name)
+ if match is not None and match.group("version"):
+ return True
+ return False
+
+
+def _is_nonempty_file(path: Path) -> bool:
+ """A regular file with something in it.
+
+ Length is the one property of a file's contents this probe may read: it executes
+ nothing, and a zero-length library or entrypoint is not a thing any loader can use.
+ An interrupted extraction and security software that empties a file in place both
+ leave the directory entry, so ``is_file()`` and the execute bit stayed true while
+ ``_existing_install_runs`` rejected the tree on ENOEXEC or a loader failure. No real
+ payload file is empty, so nothing shipped is refused by this.
+ """
+ try:
+ status = path.stat()
+ except OSError:
+ return False
+ return stat.S_ISREG(status.st_mode) and status.st_size > 0
+
+
+def _payload_match_is_loadable(path: Path) -> bool:
+ """Whether a glob match is a file the loader would actually resolve.
+
+ ``Path.glob`` does not follow links, so a dangling link (or a directory)
+ still matches the pattern; ``is_file()`` drops both.
+
+ A release ships ``libllama.so.0`` (the SONAME the binary asks for) beside
+ ``libllama.so.0.0.10360``, and ``libllama.so*`` matches both, so quarantining
+ the SONAME left the group satisfied by the twin while ``llama-server
+ --version`` exited 127. A name with more version components than a SONAME can
+ only be the twin, so it does not count on its own.
+
+ macOS names the same pair the other way round, and needs the same rule: the
+ shipped bundle carries ``libggml.dylib -> libggml.0.dylib ->
+ libggml.0.23.0.dylib``, and ``llama-server``'s LC_LOAD_DYLIB entry is
+ ``@rpath/libggml.0.dylib`` (the install name recorded in the terminal file's
+ own LC_ID_DYLIB), so losing the middle link is fatal to dyld while
+ ``libggml.*.dylib`` stays satisfied by the terminal file. ``.dll`` names and
+ bare executables are unaffected.
+ """
+ if not _is_nonempty_file(path):
+ return False
+ match = _LINKER_NAME_RE.match(path.name) or _DYLIB_NAME_RE.match(path.name)
+ if match is None:
+ # A name carrying ``.so`` whose tail is not a version is not a name any
+ # loader asks for. The Linux groups all end in ``.so*``, so quarantine
+ # that renames in place rather than deleting left the group satisfied by
+ # its own victim: renaming libggml-base.so.0 to libggml-base.so.0.vir on
+ # a b10840 install kept this answering healthy while llama-server exited
+ # with "cannot open shared object file". Windows and macOS groups end in
+ # the extension itself, so a suffixed name misses them already.
+ return ".so" not in path.name
+ depth = match.group("version").count(".")
+ if depth > 1:
+ # More components than a SONAME can carry, so this is the terminal file
+ # and never what a DT_NEEDED entry or an LC_LOAD_DYLIB names.
+ return False
+ if depth == 1:
+ return True
+ # Versionless. Whether that is the loadable name depends on the family around
+ # it, which is why this is not a decision the name alone can make: b10840
+ # ships libllama.so, libllama.so.0 and libllama.so.0.4.0, and copy_globs
+ # flattens all three into regular files because shutil.copy2 follows the
+ # links the tarball uses. Quarantining libllama.so.0 then left libllama.so
+ # standing, the group satisfied, and llama-server dying in the loader.
+ #
+ # Any versioned sibling is enough to disqualify it, not only a SONAME-shaped
+ # one. Asking for a SONAME specifically would read the family as versionless
+ # again the moment the SONAME is the file that went missing, which is the
+ # case this exists to catch. The cost is that a bundle shipping a versionless
+ # name beside a fully versioned one and no SONAME at all would be called
+ # broken; no release ships that, and the answer a directory listing can give
+ # ends here, since what the loader asks for lives in the dependent binary's
+ # DT_NEEDED rather than in any of these names.
+ return not _has_versioned_siblings(path)
+
+
def _runtime_payload_has(install_dir: Path, host: HostInfo, groups: list[list[str]]) -> bool:
runtime_dir = install_runtime_dir(install_dir, host)
if not runtime_dir.exists():
@@ -7860,7 +8079,7 @@ def _runtime_payload_has(install_dir: Path, host: HostInfo, groups: list[list[st
for pattern_group in groups:
matched = False
for pattern in pattern_group:
- if any(runtime_dir.glob(pattern)):
+ if any(_payload_match_is_loadable(path) for path in runtime_dir.glob(pattern)):
matched = True
break
if not matched:
@@ -7877,10 +8096,48 @@ def runtime_payload_is_healthy(install_dir: Path, host: HostInfo, choice: AssetC
source_label = choice.source_label,
runtime_name = choice.runtime_name,
tag = choice.tag,
+ install_dir = install_dir,
),
)
+"""Files only a published bundle ships, per platform.
+
+A source build links these into its binaries: ``setup.ps1`` builds statically, and
+no source tree produces a per-binary ``-impl`` library. So finding one is evidence
+that the tree came from a release even when the marker cannot say so.
+"""
+_PREBUILT_TREE_EVIDENCE = {
+ "windows": ["llama-common.dll", "mtmd.dll", "llama-server-impl.dll"],
+ "linux": ["libllama-server-impl.so*", "libmtmd.so*"],
+ "macos": ["libllama-server-impl*.dylib", "libmtmd*.dylib"],
+}
+
+
+def _tree_looks_prebuilt(install_dir: Path, host: HostInfo) -> bool:
+ """Whether the runtime tree carries a file only a published bundle ships.
+
+ An unparseable marker names no source, and grading such a tree as though it
+ might be a source build drops every source-gated group: on Windows that left
+ ``llama.dll`` alone standing for the whole payload, so an interrupted marker
+ plus a quarantined ``ggml-base.dll`` still answered healthy and the runtime
+ launched into the loader error this check exists to pre-empt.
+
+ Reading the tree rather than assuming either answer keeps the other half
+ honest too: a statically linked source build ships none of these names, and
+ requiring a published payload of it would fail health on a tree the setup
+ scripts keep, which is the repair loop the docstring above forbids. When
+ quarantine has taken the evidence as well, the lenient answer stands, and the
+ entrypoint checks below still grade the tree.
+ """
+ key = "windows" if host.is_windows else "macos" if host.is_macos else "linux"
+ runtime_dir = install_runtime_dir(install_dir, host)
+ return any(
+ any(_payload_match_is_loadable(match) for match in runtime_dir.glob(pattern))
+ for pattern in _PREBUILT_TREE_EVIDENCE[key]
+ )
+
+
# The binaries a reuse decision would otherwise start; the DiffusionGemma visual server is optional.
_RUNTIME_RECORD_NAMES = (
"llama-server",
@@ -8703,7 +8960,12 @@ def existing_install_current_without_plan(
install_runtime_dir(install_dir, host) / f"llama-{name}{extension}"
for name in ("server", "quantize")
]
- if not all(os.access(binary, os.X_OK) for binary in binaries):
+ # _damaged_entrypoint rather than X_OK over these two, because it is the owner of this
+ # question and also covers the install root's copies, which _find_llama_server_binary
+ # reaches FIRST. Checking build/bin alone made this shortcut accept a tree that
+ # installed_runtime_health rejects: the desktop marked the install stale, the update ran,
+ # this returned True before reinstalling anything, and the next launch was stale again.
+ if _damaged_entrypoint(install_dir, host) is not None:
return False
# (6) the bytes are the ones installed; before the preflight, whose probe skip trusts them.
if not _runtime_files_match(install_dir, host, marker):
@@ -8778,6 +9040,9 @@ 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")
+ if not isinstance(source_label, str) or not source_label:
+ # No marker to read, or one that parsed without a source. Ask the tree.
+ source_label = "published" if _tree_looks_prebuilt(install_dir, host) else None
marker_tag = (marker or {}).get("tag")
shared = set.intersection(
*(
@@ -8788,6 +9053,7 @@ def _kept_install_payload_is_healthy(install_dir: Path, host: HostInfo) -> bool:
source_label = source_label,
runtime_name = runtime_asset,
tag = marker_tag if isinstance(marker_tag, str) else None,
+ install_dir = install_dir,
)
}
for kind in kinds
@@ -8796,6 +9062,168 @@ def _kept_install_payload_is_healthy(install_dir: Path, host: HostInfo) -> bool:
return _runtime_payload_has(install_dir, host, [list(group) for group in sorted(shared)])
+def platform_only_host() -> HostInfo:
+ """A HostInfo carrying platform facts and nothing probed.
+
+ detect_host() costs over a second shelling out to nvidia-smi and friends. The
+ payload health checks read only the platform booleans and the marker's own
+ backend, never a probed GPU field, so they should not pay for that. A parity
+ test against detect_host() holds this to it. macos_version is derived from
+ platform.mac_ver() rather than probed.
+ """
+ system = platform.system()
+ machine = platform.machine().lower()
+ is_macos = system == "Darwin"
+ return HostInfo(
+ system = system,
+ machine = machine,
+ is_windows = system == "Windows",
+ is_linux = system == "Linux",
+ is_macos = is_macos,
+ is_x86_64 = machine in {"x86_64", "amd64"},
+ is_arm64 = machine in {"arm64", "aarch64"},
+ nvidia_smi = None,
+ driver_cuda_version = None,
+ compute_caps = [],
+ visible_cuda_devices = None,
+ has_physical_nvidia = False,
+ has_usable_nvidia = False,
+ macos_version = parse_macos_version(platform.mac_ver()[0]) if is_macos else None,
+ )
+
+
+def installed_runtime_health(
+ install_dir: Path | None = None, *, host: HostInfo | None = None
+) -> tuple[bool, str] | None:
+ """(ok, reason) for the managed llama.cpp runtime, or None when none is installed.
+
+ Smart App Control and antivirus quarantine individual files out of a tree
+ that is otherwise present, so "the marker says installed" is not "the binaries
+ are still there". Launch preflight asks this so such a runtime is offered for
+ repair instead of failing later at model load.
+
+ Must stay no stricter than the setup scripts' own keep-or-reinstall decision:
+ a tree rejected here but kept by ``_existing_install_runs`` would be repaired,
+ left unchanged, and rejected again next launch, a loop with no way out. Every
+ check below has a counterpart there. Nothing is executed, only looked for,
+ since preflight is on the launch path.
+ """
+ root = install_dir if install_dir is not None else default_managed_llama_dir()
+ if load_prebuilt_metadata(root) is None:
+ # An absent marker means nobody installed a runtime. A marker that is
+ # present but unparseable is a real tree, and answering None for it would
+ # leave preflight Ready with the repair unoffered, the exact failure this
+ # catches, so fall through and grade it instead.
+ # _kept_install_payload_is_healthy treats such a marker as an unknown
+ # backend and checks only the payload every kind on the platform shares,
+ # so the no-stricter rule still holds.
+ if not (root / "UNSLOTH_PREBUILT_INFO.json").is_file():
+ return None
+ host = host if host is not None else platform_only_host()
+ runtime_dir = install_runtime_dir(root, host)
+ if not runtime_dir.is_dir():
+ return False, "llama_runtime_dir_missing"
+ if not _kept_install_payload_is_healthy(root, host):
+ return False, "llama_runtime_payload_incomplete"
+ # The payload groups name libraries only, so on Linux and macOS a quarantined
+ # llama-server would otherwise read as a complete install.
+ # _existing_install_runs requires both of these too, and asks for the execute
+ # bit rather than mere presence, so this asks the same way: extraction damage
+ # or security software that clears the bit without deleting the file leaves
+ # _find_llama_server_binary rejecting the tree (os.access X_OK, "non
+ # executable", no fallback) while an exists() check here still answered Ready.
+ # Windows has no execute bit, and the host is a parameter here, so the check
+ # follows the tree being graded rather than the interpreter doing the grading:
+ # a Windows bundle unpacked on a POSIX filesystem is not a broken install. The
+ # reason stays llama_runtime_binaries_missing: the repair is the same
+ # reinstall, and the frontend renders that reason already.
+ # A regular file first: a directory of that name is searchable, so os.access
+ # X_OK answers true for it and exists() does too, while _file_status in the
+ # finder asks is_file() and rejects the tree. Failed extraction leaves exactly
+ # that.
+ if _damaged_entrypoint(root, host, selected_root_only = True) is not None:
+ return False, "llama_runtime_binaries_missing"
+ return True, ""
+
+
+def _damaged_entrypoint(
+ install_dir: Path,
+ host: HostInfo,
+ *,
+ selected_root_only: bool = False,
+) -> Path | None:
+ """The first runtime entrypoint the loader would not start, or None.
+
+ build/bin, and the install root's own copy: ``create_exec_entrypoint`` writes a
+ real wrapper there when it cannot make a symlink, and it can rot on its own.
+
+ ``selected_root_only`` is the launch probe's rule, and the two questions differ.
+ The installer asks whether it can reuse this tree as it stands, and a rotten root
+ wrapper is worth replacing. The launch probe asks whether the runtime the backend
+ will actually start is broken, and ``resolve_llama_server_binary`` returns the
+ first USABLE candidate rather than the first that exists (``_usable_binary`` is
+ ``is_file()`` plus ``os.access(X_OK)`` off Windows), so it walks past a wrapper
+ whose execute bit is gone and runs build/bin. Grading that tree damaged marked a
+ working runtime stale and sent it through a repair, and where repair is
+ unavailable it blocked the launch outright. Pinned from the other side by
+ ``test_runtime_skips_non_executable_root_entrypoint_for_valid_build_layout``.
+
+ Never the reverse: the launch verdict stays no stricter than the keep decision,
+ which is what stops a tree being repaired by changing nothing and rejected again.
+
+ One owner for the question, so the launch verdict and both keep decisions cannot
+ answer it differently: a tree one rejects and another keeps is repaired by
+ changing nothing and rejected again on the next launch.
+ """
+ runtime_dir = install_runtime_dir(install_dir, host)
+ ext = ".exe" if host.is_windows else ""
+ for name in ("llama-server", "llama-quantize"):
+ binary = runtime_dir / f"{name}{ext}"
+ if not _entrypoint_is_runnable(binary, host):
+ return binary
+ root_binary = install_dir / f"{name}{ext}"
+ present = (
+ _discovery_would_select(root_binary, host)
+ if selected_root_only
+ else root_binary.exists()
+ )
+ if present and not _entrypoint_is_runnable(root_binary, host):
+ return root_binary
+ return None
+
+
+def _discovery_would_select(binary: Path, host: HostInfo) -> bool:
+ """Whether the backend's resolver would stop at this candidate.
+
+ Mirrors ``_usable_binary`` in studio/backend/utils/llama_cpp_path_settings.py,
+ which is what decides the question at runtime. Kept in step with it deliberately:
+ a candidate the resolver walks past cannot break a launch, so grading it would
+ repair a runtime that works.
+ """
+ try:
+ if not binary.is_file():
+ return False
+ except OSError:
+ return False
+ return host.is_windows or os.access(binary, os.X_OK)
+
+
+def _entrypoint_is_runnable(binary: Path, host: HostInfo) -> bool:
+ """Whether a runtime entrypoint is a file the loader would start.
+
+ Shared with ``_existing_install_runs`` so the keep-or-reinstall decision and
+ the launch-time verdict cannot disagree: a tree this rejects but that one
+ keeps would be repaired, left unchanged and rejected again next launch.
+
+ Empty is not runnable, whatever its mode bits say. A truncated entrypoint keeps
+ its execute bit, so os.access answered true while the exec of it dies on ENOEXEC,
+ which is what _binary_image_runs sees over in the keep decision.
+ """
+ if not _is_nonempty_file(binary):
+ return False
+ return True if host.is_windows else os.access(binary, os.X_OK)
+
+
# SIGKILL is absent: that is an OOM, not a broken image.
_BROKEN_IMAGE_SIGNALS = frozenset(
{signal.SIGSEGV, signal.SIGILL, signal.SIGFPE}
@@ -8892,7 +9320,7 @@ def _existing_install_runs(install_dir: Path, host: HostInfo) -> bool:
runtime_dir = install_runtime_dir(install_dir, host)
ext = ".exe" if host.is_windows else ""
binaries = [runtime_dir / f"llama-{name}{ext}" for name in ("server", "quantize")]
- if not all(os.access(binary, os.X_OK) for binary in binaries):
+ if _damaged_entrypoint(install_dir, host) is not None:
return False
# A current macOS load record also replaces the `--version` probes below.
recorded_bytes_intact = _macos_load_record_is_current(marker, host) and _runtime_files_match(
@@ -8935,6 +9363,23 @@ def _existing_install_runs(install_dir: Path, host: HostInfo) -> bool:
return True
+def reusable_existing_install(install_dir: Path, host: HostInfo) -> bool:
+ """Whether setup.sh may keep this tree instead of building llama.cpp from source.
+
+ Only reached once the prebuilt path has failed, so a tree that cannot load a
+ model is never worth keeping. The shell test was just "both entrypoints are
+ executable", which a quarantine that took a library leaves untouched: the
+ rebuild was skipped, the tree came back identical, and an update that repaired
+ nothing reported success while preflight kept flagging it.
+
+ A tree with no marker is a genuine source build, which ships none of the
+ prebuilt payload (setup.ps1 links statically), so it keeps the old test.
+ """
+ if not (install_dir / "UNSLOTH_PREBUILT_INFO.json").is_file():
+ return True
+ return _existing_install_runs(install_dir, host)
+
+
def existing_install_matches_choice(
install_dir: Path,
host: HostInfo,
@@ -8959,6 +9404,16 @@ def existing_install_matches_choice(
if not runtime_payload_is_healthy(install_dir, host, choice):
return False
+ # Verify primary executables are still startable (catches partial deletion, and
+ # damage that leaves the name behind). The same test _existing_install_runs and
+ # installed_runtime_health use, deliberately: this is the keep-or-reinstall
+ # decision, and a tree the probe rejects but this one keeps is repaired by
+ # downloading nothing and rejected again on the next launch. exists() was that
+ # tree: security software or a bad extraction that clears the execute bit
+ # leaves the file in place, and ldd reads a non-executable ELF quite happily,
+ # so both gates here passed while the probe said llama_runtime_binaries_missing.
+ if _damaged_entrypoint(install_dir, host) is not None:
+ return False
# Non-empty: a zero-byte llama-server.exe under a pre-record marker was reused as current.
runtime_dir = install_runtime_dir(install_dir, host)
ext = ".exe" if host.is_windows else ""
@@ -10969,6 +11424,15 @@ def parse_args() -> argparse.Namespace:
"linux-rocm, macos-arm64). When omitted, host detection decides."
),
)
+ parser.add_argument(
+ "--check-existing-install",
+ default = None,
+ metavar = "DIR",
+ help = (
+ "Exit 0 when setup.sh may reuse DIR instead of building from source, "
+ "1 when it must not. Prints nothing."
+ ),
+ )
parser.add_argument(
"--output-format",
choices = ("plain", "json"),
@@ -11126,6 +11590,10 @@ def resolve_backends_payload(
def main() -> int:
args = parse_args()
+ if args.check_existing_install is not None:
+ install_dir = Path(args.check_existing_install)
+ return EXIT_SUCCESS if reusable_existing_install(install_dir, detect_host()) else 1
+
if args.check_installed is not None:
# setup.sh asks before keeping a GPU prebuilt over a CPU source build: no download,
# since the update that failed usually failed for want of one.
diff --git a/studio/setup.ps1 b/studio/setup.ps1
index fd5f1ec764d..5672c1461bf 100644
--- a/studio/setup.ps1
+++ b/studio/setup.ps1
@@ -8678,6 +8678,39 @@ function Invoke-LlamaHelper {
}
}
+function Test-LlamaTreeStillHealthy {
+ <#
+ Whether a tree the reuse shortcut is about to keep is one preflight will accept.
+
+ llama-server.exe existing is not enough. Quarantine and a truncated extract both
+ take a library and leave the entrypoint in place, and this branch is only reached
+ once the prebuilt path has already failed, so keeping such a tree returns it byte
+ for byte identical and reports success. Desktop preflight grades the same tree on
+ every launch, so an update that repaired nothing left it offering the same repair
+ forever, which is the loop installed_runtime_health exists to prevent.
+
+ The setup.sh side of this gate is the same call. Both go through
+ install_llama_prebuilt so there is one definition of healthy rather than two that
+ can disagree.
+
+ Healthy on any failure to ask. A helper that cannot run, or a python that is not
+ there yet, must not turn into a rebuild: that trades a wrong keep for a
+ multi-gigabyte source build on a machine whose only fault was an unreadable tree.
+ #>
+ param([Parameter(Mandatory = $true)][AllowEmptyString()][string]$TreeRoot)
+ if ([string]::IsNullOrWhiteSpace($TreeRoot)) { return $true }
+ if (-not (Test-PathQuiet $TreeRoot "Container")) { return $true }
+ try {
+ $probe = Invoke-LlamaHelper -Arguments @("--check-existing-install", $TreeRoot)
+ } catch {
+ return $true
+ }
+ if ($null -eq $probe) { return $true }
+ if ($probe.ExitCode -eq 0) { return $true }
+ step "llama.cpp" "existing build is incomplete; rebuilding" "Yellow"
+ return $false
+}
+
if ($LlamaSource -ne "https://github.com/ggml-org/llama.cpp") {
step "llama.cpp" "custom source: $LlamaSource -- forcing source build" "Yellow"
$NeedLlamaSourceBuild = $true
@@ -9194,8 +9227,19 @@ if ($llamaBinState -eq "Present") {
}
}
-$WillBuildLlamaFromSource = $NeedLlamaSourceBuild -and `
- -not ((Test-PathQuiet $LlamaServerBin "Leaf") -and -not $NeedRebuild -and $RequestedLlamaTag -ne "master")
+# One predicate for the plan and the shortcut. The health gate belongs in both: read only
+# by the shortcut, a tree it refuses left $WillBuildLlamaFromSource false, so the git
+# install and Ensure-BuildToolsForLlamaSourceBuild below were skipped and the rebuild the
+# refusal forces then reached cmake on a prebuilt-only box with no toolchain.
+# Asked once, so the helper runs once and its "incomplete" line is printed once. A linked
+# local dir is excluded here as it is everywhere else on this route: nothing reads into the
+# user's own checkout, and the branch below takes it before the shortcut anyway.
+$CanReuseLlamaBuild = (Test-PathQuiet $LlamaServerBin "Leaf") -and -not $NeedRebuild -and `
+ $RequestedLlamaTag -ne "master"
+if ($CanReuseLlamaBuild -and $NeedLlamaSourceBuild -and -not $LocalLlamaCppLinked) {
+ $CanReuseLlamaBuild = Test-LlamaTreeStillHealthy $LlamaCppDir
+}
+$WillBuildLlamaFromSource = $NeedLlamaSourceBuild -and -not $CanReuseLlamaBuild
if ($WillBuildLlamaFromSource) {
if (-not $HasGitForBuild) {
# Phase 1 keeps git optional, so only the automatic fallback after a failed prebuilt
@@ -9229,10 +9273,11 @@ if ($LocalLlamaCppLinked) {
} elseif (-not $NeedLlamaSourceBuild) {
Write-StudioLine ""
step "llama.cpp" "prebuilt (validated)"
-} elseif ((Test-PathQuiet $LlamaServerBin "Leaf") -and -not $NeedRebuild -and $RequestedLlamaTag -ne "master") {
+} elseif ($CanReuseLlamaBuild) {
# Skip rebuild only for pinned tags (e.g. b8635). When the requested
# tag is "master" (a moving target), always rebuild so the binary picks
- # up new model architecture support (e.g. Gemma 4).
+ # up new model architecture support (e.g. Gemma 4). Health is folded into
+ # $CanReuseLlamaBuild above, so refusing here also planned the toolchain.
Write-StudioLine ""
step "llama.cpp" "already built"
} elseif (-not $HasGitForBuild) {
diff --git a/studio/setup.sh b/studio/setup.sh
index 6e5c6a6740a..70260ae0be5 100755
--- a/studio/setup.sh
+++ b/studio/setup.sh
@@ -4142,7 +4142,7 @@ _keep_installed_gpu_prebuilt() {
[ -z "${_explicit_llama_source_backend:-}" ] || return 1
_has_local_llama_server "$install_dir" || return 1
[ -f "$install_dir/UNSLOTH_PREBUILT_INFO.json" ] || return 1
- python - "$install_dir/UNSLOTH_PREBUILT_INFO.json" "$requested_tag" "$repo" "$release_pin" <<'PY' 2>/dev/null
+ python - "$install_dir/UNSLOTH_PREBUILT_INFO.json" "$requested_tag" "$repo" "$release_pin" "$SCRIPT_DIR" <<'PY' 2>/dev/null
import json
import re
import sys
@@ -4191,7 +4191,13 @@ if requested and requested.lower() != "latest":
elif requested not in recorded:
# b10840-mix-new and b10840-mix-old share a base build but are different bundles.
raise SystemExit(1)
-raise SystemExit(0)
+# Keep the Docker shortcut consistent with desktop preflight without probing a GPU
+# or executing the CUDA binaries on the GPU-less image build host.
+sys.path.insert(0, sys.argv[5])
+from install_llama_prebuilt import installed_runtime_health
+
+health = installed_runtime_health(Path(sys.argv[1]).parent)
+raise SystemExit(1 if health is not None and not health[0] else 0)
PY
}
@@ -4459,9 +4465,24 @@ fi
# Source-built llama.cpp installs do not have the prebuilt metadata used above
# for exact release matching. Reuse a complete local source build unless the
# caller explicitly requested a rebuild or a PR-specific llama.cpp checkout.
+# The two entrypoints being executable is not enough on its own. Quarantine and
+# a truncated extract both take a library and leave llama-server in place, and
+# this branch only runs once the prebuilt path has already failed, so keeping
+# such a tree returns it byte for byte identical and reports success. Desktop
+# preflight asks about the same tree on every launch, so an update that repaired
+# nothing left it asking forever. A tree with no prebuilt marker is a real source
+# build and keeps the old test.
+_LLAMA_REUSE_EXISTING=true
+if [ "$_NEED_LLAMA_SOURCE_BUILD" = true ] && [ -d "$LLAMA_CPP_DIR" ]; then
+ python "$SCRIPT_DIR/install_llama_prebuilt.py" \
+ --check-existing-install "$LLAMA_CPP_DIR" >/dev/null 2>&1 \
+ || _LLAMA_REUSE_EXISTING=false
+fi
+
if [ "$_NEED_LLAMA_SOURCE_BUILD" = true ] && \
[ "$_LLAMA_FORCE_COMPILE" != "1" ] && \
[ -z "$_LLAMA_PR" ] && \
+ [ "$_LLAMA_REUSE_EXISTING" = true ] && \
[ -x "$LLAMA_CPP_DIR/build/bin/llama-server" ] && \
[ -x "$LLAMA_CPP_DIR/build/bin/llama-quantize" ]; then
step "llama.cpp" "existing source build found; skipping rebuild"
diff --git a/studio/src-tauri/src/preflight.rs b/studio/src-tauri/src/preflight.rs
index cf282781771..69a43b3f48f 100644
--- a/studio/src-tauri/src/preflight.rs
+++ b/studio/src-tauri/src/preflight.rs
@@ -1,5 +1,5 @@
mod backend;
-mod managed;
+pub(crate) mod managed;
mod pid_records;
mod types;
mod version;
diff --git a/studio/src-tauri/src/preflight/managed.rs b/studio/src-tauri/src/preflight/managed.rs
index c1ad821e9c7..640e3fa996b 100644
--- a/studio/src-tauri/src/preflight/managed.rs
+++ b/studio/src-tauri/src/preflight/managed.rs
@@ -11,7 +11,9 @@ use std::time::{Duration, Instant, UNIX_EPOCH};
use tokio::io::AsyncReadExt;
// 3: the cached capability gained studio_install_ok / studio_install_reason.
-const MANAGED_CAPABILITY_CACHE_SCHEMA: u16 = 3;
+// 4: the fingerprint gained the llama.cpp runtime, so a quarantined file
+// invalidates the entry instead of being served a stale Ready.
+const MANAGED_CAPABILITY_CACHE_SCHEMA: u16 = 4;
/// The install is fine; the directory its children must run from is not reachable.
pub(super) const WORKING_DIRECTORY_UNAVAILABLE: &str = "working_directory_unavailable";
@@ -105,6 +107,12 @@ struct DesktopCapability {
// on `import structlog`, so a running CLI does not mean ready.
studio_install_ok: Option<bool>,
studio_install_reason: Option<String>,
+ // Quarantine takes files out of an otherwise present llama.cpp tree, which
+ // staleness on the managed Python alone missed: the desktop launched and the
+ // model load failed later looking like a bad GGUF. None when the CLI is too
+ // old to answer or nothing is installed yet.
+ llama_runtime_ok: Option<bool>,
+ llama_runtime_reason: Option<String>,
version: Option<String>,
}
@@ -118,6 +126,7 @@ struct ManagedCapabilityCache {
marker_path: Option<String>,
marker_size: Option<u64>,
marker_mtime_ms: Option<u64>,
+ llama_runtime: Option<String>,
desktop_protocol_version: u16,
desktop_manageability_version: u16,
capability: DesktopCapability,
@@ -140,6 +149,7 @@ struct ManagedBinFingerprint {
marker_path: Option<String>,
marker_size: Option<u64>,
marker_mtime_ms: Option<u64>,
+ llama_runtime: Option<String>,
}
fn modified_ms(metadata: &fs::Metadata) -> Option<u64> {
@@ -313,9 +323,555 @@ fn managed_bin_fingerprint(bin: &Path) -> Option<ManagedBinFingerprint> {
marker_path,
marker_size,
marker_mtime_ms,
+ llama_runtime: llama_runtime_fingerprint(bin),
})
}
+/// The folder a leading `~` names, resolved the way the CLI child resolves it.
+///
+/// `ntpath.expanduser` answers USERPROFILE, while `dirs::home_dir()` reads the
+/// known folder, which a portable or overridden profile moves. Taking the latter
+/// would fingerprint a tree the child never looks at.
+///
+/// process.rs calls this rather than keeping its own order: it used to pass
+/// `dirs::home_dir()` straight into `expand_windows_user`, so on a Windows box with
+/// an overridden USERPROFILE the child was pinned to the known folder while this
+/// fingerprinted the profile, and quarantine in the tree actually in use never
+/// invalidated a cached healthy result.
+pub(crate) fn tilde_home() -> Option<PathBuf> {
+ if cfg!(windows) {
+ if let Some(profile) = std::env::var_os("USERPROFILE") {
+ if !profile.is_empty() {
+ return Some(PathBuf::from(profile));
+ }
+ }
+ }
+ dirs::home_dir()
+}
+
+/// `UNSLOTH_LLAMA_CPP_PATH` resolved the way the CLI child sees it: trimmed, `~`
+/// expanded (`default_managed_llama_dir` calls expanduser), and a relative value
+/// anchored to this process's working directory (`relative_override_pins` pins it
+/// from exactly there before the spawn).
+///
+/// `~name` is left alone, since nothing here can resolve another user's home; it
+/// is then relative, so it is anchored like any other relative value.
+///
+/// UNSLOTH_STUDIO_HOME is deliberately not consulted: managed spawns scrub it
+/// (MANAGED_CHILD_SCRUBBED_ENV), so the CLI falls through to the legacy root too.
+#[cfg_attr(test, allow(dead_code))]
+fn llama_runtime_override() -> Option<PathBuf> {
+ llama_runtime_override_from(
+ std::env::var("UNSLOTH_LLAMA_CPP_PATH").ok().as_deref(),
+ tilde_home().as_deref(),
+ std::env::current_dir().ok().as_deref(),
+ )
+}
+
+/// Split out from the reads so tests can drive it without a process-wide variable.
+pub(crate) fn llama_runtime_override_from(
+ value: Option<&str>,
+ home: Option<&Path>,
+ cwd: Option<&Path>,
+) -> Option<PathBuf> {
+ let value = value?.trim();
+ if value.is_empty() {
+ return None;
+ }
+ if value == "~" {
+ return home.map(Path::to_path_buf);
+ }
+ if let Some(rest) = value
+ .strip_prefix("~/")
+ .or_else(|| cfg!(windows).then(|| value.strip_prefix("~\\")).flatten())
+ {
+ return Some(home?.join(rest));
+ }
+ if let Some(named) = named_user_home(value, home) {
+ return Some(named);
+ }
+ let path = PathBuf::from(value);
+ if path.is_absolute() {
+ return Some(path);
+ }
+ // Anchored, not discarded: dropping it makes both halves of a launch pair
+ // report None, so the cache keeps hitting while the real runtime rots. The
+ // child joins this value to this same directory, so joining it here watches
+ // the tree the child was told about.
+ Some(cwd?.join(path))
+}
+
+/// `~alice/llama.cpp` resolved to Alice's home, the way `Path.expanduser()` does.
+///
+/// posixpath.expanduser answers this out of the password database, so leaving it
+/// alone made the value relative, anchored it under the desktop's own directory,
+/// and fingerprinted a tree the child never opens. getpwnam is the same lookup
+/// Python makes, so the two agree for LDAP and SSSD users as well as local ones.
+/// None when the name is unknown, which leaves the value to be anchored like any
+/// other relative path rather than guessed at. Windows has its own rule and its
+/// own arm below.
+#[cfg(unix)]
+pub(crate) fn named_user_home(value: &str, _home: Option<&Path>) -> Option<PathBuf> {
+ use std::os::unix::ffi::OsStrExt;
+
+ let rest = value.strip_prefix('~')?;
+ if rest.is_empty() {
+ return None;
+ }
+ let (name, tail) = match rest.find('/') {
+ Some(at) => (&rest[..at], &rest[at + 1..]),
+ None => (rest, ""),
+ };
+ if name.is_empty() {
+ return None;
+ }
+ let c_name = std::ffi::CString::new(name).ok()?;
+ // getpwnam_r, not getpwnam: this runs on a Tauri worker thread, and getpwnam
+ // hands back a pointer into storage shared by the whole process, so a
+ // concurrent passwd lookup anywhere else could overwrite pw_dir while it was
+ // being copied. Copying promptly narrows that window, it does not close it,
+ // and a torn read here fingerprints an unrelated tree. The _r form writes
+ // into a buffer this call owns.
+ let mut buffer = vec![0i8; 1024];
+ let mut passwd: libc::passwd = unsafe { std::mem::zeroed() };
+ let home = loop {
+ let mut found: *mut libc::passwd = std::ptr::null_mut();
+ let code = unsafe {
+ libc::getpwnam_r(
+ c_name.as_ptr(),
+ &mut passwd,
+ buffer.as_mut_ptr() as *mut libc::c_char,
+ buffer.len(),
+ &mut found,
+ )
+ };
+ if code == libc::ERANGE && buffer.len() < 1 << 20 {
+ // The name resolves, the buffer was too small for its record. Only
+ // grow so far, so a hostile or broken passwd source cannot make this
+ // allocate without end.
+ buffer.resize(buffer.len() * 2, 0);
+ continue;
+ }
+ // A nonzero code is a lookup error and a null found is "no such user".
+ // Both leave the value to be anchored like any other relative path.
+ if code != 0 || found.is_null() {
+ return None;
+ }
+ let dir = passwd.pw_dir;
+ if dir.is_null() {
+ return None;
+ }
+ break PathBuf::from(std::ffi::OsStr::from_bytes(unsafe {
+ std::ffi::CStr::from_ptr(dir).to_bytes()
+ }));
+ };
+ Some(if tail.is_empty() { home } else { home.join(tail) })
+}
+
+#[cfg(windows)]
+pub(crate) fn named_user_home(value: &str, home: Option<&Path>) -> Option<PathBuf> {
+ named_windows_user_home(value, home?, std::env::var("USERNAME").ok().as_deref())
+}
+
+#[cfg(not(any(unix, windows)))]
+pub(crate) fn named_user_home(_value: &str, _home: Option<&Path>) -> Option<PathBuf> {
+ None
+}
+
+/// `~name` on Windows, the way ntpath.expanduser resolves it: the sibling of this
+/// profile, and only where ntpath is willing to guess at all.
+///
+/// Leaving it alone made the value relative, so the fingerprint watched
+/// `<cwd>\~other\llama.cpp` while process.rs pins the variable for the child
+/// through its own `expand_windows_user` and the CLI's `Path.expanduser()` reads
+/// it the same way, both landing on the real profile. Quarantine under that
+/// profile then never invalidated a cached healthy result.
+///
+/// Compiled on every platform so the rule is testable off Windows; only the
+/// Windows arm above calls it. None when ntpath would decline (a profile folder
+/// not named after the current user, an unknown USERNAME), which leaves the value
+/// anchored like any other relative path rather than guessed at.
+#[cfg_attr(not(windows), allow(dead_code))]
+fn named_windows_user_home(value: &str, home: &Path, username: Option<&str>) -> Option<PathBuf> {
+ let rest = value.strip_prefix('~')?;
+ let end = rest.find(['\\', '/']).unwrap_or(rest.len());
+ let (name, tail) = (&rest[..end], &rest[end..]);
+ if name.is_empty() {
+ return None;
+ }
+ let home = home.to_string_lossy();
+ // Split on the string, not with Path::parent: these are Windows paths
+ // whichever platform is reading them.
+ let cut = home.rfind(['\\', '/'])?;
+ let this_profile = &home[cut + 1..];
+ let base = match username {
+ Some(user) if user == name => home.clone().into_owned(),
+ // C:\Users\alice.DOMAIN is not alice's sibling, so ntpath refuses unless
+ // this profile is named after the current user.
+ Some(user) if user == this_profile => format!("{}{}", &home[..cut + 1], name),
+ _ => return None,
+ };
+ Some(PathBuf::from(format!("{base}{tail}")))
+}
+
+/// The markers install.ps1 writes into its generated `unsloth.cmd`, and the size
+/// past which the file is not that shim. Same pair `_is_managed_cmd_shim` reads,
+/// so a hand rolled wrapper that happens to call the CLI is not mistaken for one.
+#[cfg(any(windows, test))]
+const CMD_SHIM_MARKERS: [&[u8]; 2] = [b"unsloth-studio-managed-launcher", b"from unsloth_cli import app"];
+#[cfg(any(windows, test))]
+const CMD_SHIM_MAX_BYTES: u64 = 8192;
+
+/// Whether a directory carries the sentinel an installer-managed Studio root has,
+/// mirroring `_looks_like_installer_managed_studio_home` in the CLI.
+///
+/// Compiled on every platform so the rule is testable off Windows; the runtime
+/// answer follows the platform this is built for, as it does in Python.
+fn looks_like_installer_managed_studio_home(candidate: &Path) -> bool {
+ if candidate.join("share").join("studio.conf").is_file() {
+ return true;
+ }
+ #[cfg(not(windows))]
+ {
+ candidate.join("bin").join("unsloth").is_file()
+ }
+ #[cfg(windows)]
+ {
+ if candidate.join("bin").join("unsloth.exe").is_file() {
+ return true;
+ }
+ is_managed_cmd_shim(&candidate.join("bin").join("unsloth.cmd"))
+ }
+}
+
+/// Whether a path is the `.cmd` shim this installer generates.
+#[cfg(any(windows, test))]
+fn is_managed_cmd_shim(path: &Path) -> bool {
+ let Ok(metadata) = fs::metadata(path) else {
+ return false;
+ };
+ if !metadata.is_file() || metadata.len() > CMD_SHIM_MAX_BYTES {
+ return false;
+ }
+ let Ok(body) = fs::read(path) else {
+ return false;
+ };
+ CMD_SHIM_MARKERS
+ .iter()
+ .all(|marker| body.windows(marker.len()).any(|window| window == *marker))
+}
+
+/// The llama.cpp root an installer-managed venv implies, with no ambient
+/// override to say so.
+///
+/// The desktop strips UNSLOTH_STUDIO_HOME before spawning the CLI, but the CLI
+/// puts it back: `_resolve_studio_home` re-infers the root from `sys.prefix` when
+/// the venv is named `unsloth_studio` and the root carries an installer sentinel,
+/// and `_ensure_studio_env_exported` then points UNSLOTH_LLAMA_CPP_PATH at that
+/// root's llama.cpp. Reading only the ambient environment here fingerprinted the
+/// legacy ~/.unsloth/llama.cpp instead, so quarantine inside the custom runtime
+/// never moved the fingerprint and a cached Ready kept being served for a tree
+/// the new health check never got to grade.
+///
+/// `bin` is the launcher file inside the venv, so its grandparent is `sys.prefix`.
+fn inferred_studio_llama_root(bin: &Path) -> Option<PathBuf> {
+ let prefix = bin.parent()?.parent()?;
+ if prefix.file_name()? != "unsloth_studio" {
+ return None;
+ }
+ let root = prefix.parent()?;
+ // Python resolves both sides before comparing, so a symlinked or relative
+ // path to the legacy root is still the legacy root, and the answer there is
+ // the legacy llama.cpp rather than <root>/llama.cpp.
+ let legacy = dirs::home_dir()?.join(".unsloth").join("studio");
+ let same = match (root.canonicalize(), legacy.canonicalize()) {
+ (Ok(left), Ok(right)) => left == right,
+ _ => root == legacy,
+ };
+ if same {
+ return None;
+ }
+ if !looks_like_installer_managed_studio_home(root) {
+ return None;
+ }
+ // A master root puts the runtimes BESIDE studio/, and the CLI recovers that note
+ // and grades <master>/llama.cpp. Fingerprinting <root>/llama.cpp here would watch a
+ // tree nothing loads, so one healthy cached result would survive quarantine in the
+ // runtime actually in use.
+ if let Some(master) = recorded_master_root(root) {
+ return Some(master.join("llama.cpp"));
+ }
+ Some(root.join("llama.cpp"))
+}
+
+/// The master root `<studio home>/share/.unsloth-master-root` records, or None.
+///
+/// Same rule as `_recorded_master_root` in unsloth_cli/commands/studio.py: the
+/// recorded root must exist and must CONTAIN this Studio tree, so a tree copied from
+/// one master root to another does not point the fingerprint back at the original.
+/// The legacy shape is declined by the caller before this runs, as it is there.
+fn recorded_master_root(studio_home: &Path) -> Option<PathBuf> {
+ let note = studio_home.join("share").join(".unsloth-master-root");
+ let recorded = std::fs::read_to_string(note).ok()?;
+ let recorded = recorded.trim();
+ if recorded.is_empty() {
+ return None;
+ }
+ let master = PathBuf::from(recorded);
+ if !master.is_dir() {
+ return None;
+ }
+ let master = master.canonicalize().unwrap_or_else(|_| master.clone());
+ let here = studio_home
+ .canonicalize()
+ .unwrap_or_else(|_| studio_home.to_path_buf());
+ if here == master || here.ancestors().any(|ancestor| ancestor == master) {
+ return Some(master);
+ }
+ None
+}
+
+/// Whether a folder holds a llama-server in one of the layouts the backend
+/// accepts, which is the question that decides whether discovery stops there.
+///
+/// Presence, not usability, and the CLI half agrees: `_scan_pinned` returns a hit
+/// for an executable candidate and an unavailable path for one that is merely
+/// present, and both end the search. Only a layout holding no server at all is
+/// walked past, so asking for the execute bit here would fingerprint a different
+/// tree than the CLI grades in exactly the case where the pinned one is damaged.
+fn holds_a_llama_server(root: &Path) -> bool {
+ let name = if cfg!(windows) {
+ "llama-server.exe"
+ } else {
+ "llama-server"
+ };
+ let mut candidates = vec![root.join(name), root.join("build").join("bin").join(name)];
+ if cfg!(windows) {
+ candidates.push(root.join("build").join("bin").join("Release").join(name));
+ }
+ candidates.iter().any(|candidate| {
+ let Ok(metadata) = fs::metadata(candidate) else {
+ return false;
+ };
+ // Presence, not usability. _scan_pinned answers "non_executable" for a
+ // candidate without the bit and the caller turns that into _unavailable,
+ // which ends the search rather than falling through, so a server the
+ // loader could not run still stops discovery at this folder.
+ metadata.is_file()
+ })
+}
+
+/// The managed llama.cpp install root, the same one default_managed_llama_dir
+/// picks in Python.
+fn llama_runtime_root(bin: &Path) -> Option<PathBuf> {
+ // Hermetic under test: this walks a real directory, so otherwise a developer
+ // with a runtime installed and a CI runner without one run different tests.
+ // Unset means no runtime at all. Mirrors capability_cache_path()'s hook.
+ #[cfg(test)]
+ {
+ let _ = bin;
+ return std::env::var_os("UNSLOTH_TEST_LLAMA_RUNTIME_ROOT").map(PathBuf::from);
+ }
+ // The override is asked first and its answer is final: falling back to the
+ // legacy tree when it is set but unresolvable would fingerprint a directory
+ // the CLI is not reporting on.
+ // Trimmed before deciding, because default_managed_llama_dir strips the value
+ // and a whitespace-only one therefore sends the child to the legacy tree. A
+ // raw is_empty test called that an override, took this branch, resolved to
+ // None, and left the tree the child actually grades with no fingerprint at
+ // all, so a library removed after a healthy result never invalidated Ready.
+ #[cfg(not(test))]
+ if std::env::var("UNSLOTH_LLAMA_CPP_PATH")
+ .is_ok_and(|value| !value.trim().is_empty())
+ {
+ // An override the desktop wrote points at the managed tree and the CLI
+ // grades it whatever it holds, so it is taken as given. A user-written one
+ // only stops _scan_pinned when it actually holds a server; when it does
+ // not, the CLI walks past it and grades the tree behind it, so stopping
+ // here would fingerprint a folder nobody loads.
+ let desktop_wrote_it =
+ std::env::var("UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH").as_deref() == Ok("1");
+ let override_root = llama_runtime_override();
+ if desktop_wrote_it {
+ return override_root;
+ }
+ if let Some(root) = override_root {
+ if holds_a_llama_server(&root) {
+ return Some(root);
+ }
+ }
+ }
+ // No ambient override, so ask the venv the same question the CLI asks itself
+ // before falling back to the legacy tree.
+ #[cfg(not(test))]
+ if let Some(inferred) = inferred_studio_llama_root(bin) {
+ return Some(inferred);
+ }
+ #[cfg(not(test))]
+ return Some(dirs::home_dir()?.join(".unsloth").join("llama.cpp"));
+}
+
+/// A cheap stand-in for "the llama.cpp runtime tree is unchanged": how many files
+/// sit in its binary directory and how many bytes they total.
+///
+/// The rest of this fingerprint covers the managed venv only, so a quarantined
+/// runtime file left it identical and preflight answered Ready from the cache
+/// without ever asking the CLI. None when no runtime is installed, which is
+/// NotInstalled rather than broken.
+fn llama_runtime_fingerprint(bin: &Path) -> Option<String> {
+ llama_runtime_fingerprint_at(&llama_runtime_root(bin)?)
+}
+
+/// The walk itself, against a given root, so the tests need no shared state.
+fn llama_runtime_fingerprint_at(root: &Path) -> Option<String> {
+ let mut bin = root.join("build").join("bin");
+ if cfg!(windows) {
+ bin = bin.join("Release");
+ }
+ let root_part = root_entrypoints(root);
+ match fs::read_dir(&bin) {
+ Ok(entries) => Some(format!("bin:{}|root:{root_part}", counted(entries))),
+ // build/bin is gone but something is still there. Answering None would
+ // make that identical to "nothing was ever installed", so a Ready cached
+ // while no runtime existed kept matching once a marker appeared over a
+ // missing build/bin, and the CLI never got to say llama_runtime_dir_missing.
+ // Fingerprinting the root's own entries makes the marker's arrival move it.
+ Err(_) => fs::read_dir(root)
+ .ok()
+ .map(|entries| format!("nobin:{}|root:{root_part}", counted(entries))),
+ }
+}
+
+/// The two entrypoints at the install root, which the walk above cannot see.
+///
+/// `_find_llama_server_binary` reaches `<root>/llama-server` before `build/bin`, and
+/// `create_exec_entrypoint` writes a real wrapper there when it cannot make a symlink, so
+/// its mode can move while `build/bin` stays byte for byte identical. That is what
+/// `installed_runtime_health` now grades, and without it here the cached Ready survived the
+/// damage and the CLI was never asked. Following links deliberately: the CLI follows them
+/// too, and a dangling one is absent to both.
+fn root_entrypoints(root: &Path) -> String {
+ let ext = if cfg!(windows) { ".exe" } else { "" };
+ let mut out = String::new();
+ for name in ["llama-server", "llama-quantize"] {
+ if !out.is_empty() {
+ out.push(',');
+ }
+ match fs::metadata(root.join(format!("{name}{ext}"))) {
+ Ok(meta) => {
+ #[cfg(unix)]
+ let mode = {
+ use std::os::unix::fs::PermissionsExt;
+ u64::from(meta.permissions().mode() & 0o7777)
+ };
+ #[cfg(not(unix))]
+ let mode = 0u64;
+ out.push_str(&format!("{}:{}:{mode}", u64::from(meta.is_file()), meta.len()));
+ }
+ // Absent, or a link whose target went. Not a pin either way, which is
+ // what installed_runtime_health does with it.
+ Err(_) => out.push('-'),
+ }
+ }
+ out
+}
+
+/// How many files a directory holds, how many bytes they total, how many links
+/// sit beside them and what their permission bits add up to. A subdirectory is
+/// not a file, so it cannot read as a binary.
+///
+/// The last two counters are here because the first two answered the same for
+/// trees the CLI grades differently. DirEntry::metadata does not follow a link,
+/// so a link is not a file and neither its presence nor its loss moved a count
+/// or a byte total, yet losing the install-name link (libggml.0.dylib, and the
+/// SONAME link on Linux) is exactly what installed_runtime_health calls a broken
+/// payload. Clearing the execute bit on llama-server moves neither the count nor
+/// the length either, and that is the other thing health rejects. Either state
+/// used to leave a cached Ready matching, so the repair was never offered and
+/// the launch failed instead.
+fn counted(entries: fs::ReadDir) -> String {
+ let mut count: u64 = 0;
+ let mut bytes: u64 = 0;
+ let mut links: u64 = 0;
+ let mut modes: u64 = 0;
+ let mut names: u64 = 0;
+ for entry in entries.flatten() {
+ let Ok(meta) = entry.metadata() else {
+ continue;
+ };
+ // Every entry this walk counts, link or file, contributes its name. A
+ // subdirectory still does not, matching the counters.
+ if meta.is_symlink() {
+ links += 1;
+ names = names.wrapping_add(name_hash(&entry.file_name()));
+ continue;
+ }
+ if meta.is_file() {
+ count += 1;
+ names = names.wrapping_add(name_hash(&entry.file_name()));
+ bytes += meta.len();
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::PermissionsExt;
+ // The permission bits themselves, not a count of "has some execute
+ // bit". os.access(X_OK) asks whether THIS user may run the file,
+ // and the owner's bits decide that on their own: 0755 -> 0655
+ // leaves group and other executable while the owner can no longer
+ // run it, so a counter of any-bit-set never moved for the state
+ // health rejects. Summed rather than folded, since read_dir order
+ // is unspecified. Windows has no bits to read and stays at zero,
+ // where the other three carry the tree.
+ modes += u64::from(meta.permissions().mode() & 0o7777);
+ }
+ }
+ }
+ format!("{count}:{bytes}:{links}:{modes}:{names}")
+}
+
+/// FNV-1a over one entry's name, summed into the fingerprint by the caller.
+///
+/// Names are here because the four counters are all aggregates, and a rename in
+/// place moves none of them: security software that renames ggml-base.dll to a
+/// quarantine suffix beside itself leaves the count, the byte total, the link
+/// count and the mode sum identical, so installed_runtime_health rejected the
+/// tree while the cached Ready still matched and preflight answered Ready without
+/// ever running the capability probe. The launch then failed with no repair
+/// offered, which is the exact hole the runtime half of this fingerprint exists
+/// to close.
+///
+/// Summed rather than folded in sequence, because read_dir order is unspecified
+/// and the counters beside it are order-independent for that reason; sorting
+/// would cost an allocation per entry on a walk that runs before the window
+/// opens. FNV-1a rather than DefaultHasher so the value is stable across Rust
+/// releases: a hash that moved on a toolchain bump would invalidate every cached
+/// verdict on the first launch after an upgrade. A sum admits collisions in
+/// principle, but the thing being detected is a rename, and a renamed file has to
+/// collide with the name it replaced, not with any name.
+fn name_hash(name: &std::ffi::OsStr) -> u64 {
+ let mut hash: u64 = 0xcbf2_9ce4_8422_2325;
+ for byte in name.to_string_lossy().as_bytes() {
+ hash ^= u64::from(*byte);
+ hash = hash.wrapping_mul(0x1000_0000_01b3);
+ }
+ hash
+}
+
+/// The fingerprint an answer may be stored under, or None when it may not be stored.
+///
+/// The one taken before the probe, and only while the tree still matches it. Reading
+/// the fingerprint afresh afterwards instead meant a file quarantined while
+/// desktop-capabilities was running was cached as healthy under its own damaged
+/// fingerprint, which then matched on every later launch, so the CLI was never asked
+/// again and the repair was never offered. A mismatch describes a tree that no longer
+/// exists; there is nothing worth keeping and the next launch asks again.
+fn fingerprint_to_cache_under<'a>(
+ before: Option<&'a ManagedBinFingerprint>,
+ after: Option<ManagedBinFingerprint>,
+) -> Option<&'a ManagedBinFingerprint> {
+ let before = before?;
+ (after.as_ref() == Some(before)).then_some(before)
+}
+
fn capability_cache_path() -> Option<PathBuf> {
#[cfg(test)]
if let Some(home) = std::env::var_os("UNSLOTH_TEST_DESKTOP_CAPABILITY_CACHE_HOME") {
@@ -345,6 +901,7 @@ fn cache_matches(cache: &ManagedCapabilityCache, fingerprint: &ManagedBinFingerp
&& cache.marker_path == fingerprint.marker_path
&& cache.marker_size == fingerprint.marker_size
&& cache.marker_mtime_ms == fingerprint.marker_mtime_ms
+ && cache.llama_runtime == fingerprint.llama_runtime
&& desktop_capability_ready(&cache.capability)
}
@@ -359,7 +916,38 @@ fn read_cached_capability(fingerprint: &ManagedBinFingerprint) -> Option<Desktop
}
}
+/// The CLI's word for "another runtime is the active one, so the managed tree is
+/// not mine to grade". Its null verdict is about a selection, not about the tree.
+const LLAMA_RUNTIME_NOT_MANAGED: &str = "llama_runtime_not_managed";
+
+/// And its word for "the probe itself raised", which is about one attempt.
+const LLAMA_RUNTIME_PROBE_FAILED: &str = "llama_runtime_probe_failed";
+
+/// Whether the runtime verdict in this answer was skipped rather than reached.
+///
+/// Both reasons mean no verdict was reached, and neither is a fact this fingerprint
+/// watches: the selection lives in the settings database and the environment, and a
+/// probe that raised shares the damaged tree's fingerprint exactly. The third null,
+/// nothing installed at all, is a fact about the tree and stays cacheable.
+fn llama_runtime_verdict_was_skipped(capability: &DesktopCapability) -> bool {
+ capability.llama_runtime_ok.is_none()
+ && matches!(
+ capability.llama_runtime_reason.as_deref(),
+ Some(LLAMA_RUNTIME_NOT_MANAGED) | Some(LLAMA_RUNTIME_PROBE_FAILED)
+ )
+}
+
fn write_cached_capability(fingerprint: &ManagedBinFingerprint, capability: &DesktopCapability) {
+ if llama_runtime_verdict_was_skipped(capability) {
+ // Nothing in this fingerprint watches which runtime is selected: the
+ // stored custom folder lives in the settings database and LLAMA_SERVER_PATH
+ // in the environment. Caching the skip meant that clearing the selection
+ // made a damaged managed tree active with its fingerprint unchanged, so
+ // the cache kept serving the Ready it was never graded for and repair was
+ // never offered. Re-probing costs one CLI call, and only for the users who
+ // run their own build.
+ return;
+ }
let Some(path) = capability_cache_path() else {
return;
};
@@ -372,6 +960,7 @@ fn write_cached_capability(fingerprint: &ManagedBinFingerprint, capability: &Des
marker_path: fingerprint.marker_path.clone(),
marker_size: fingerprint.marker_size,
marker_mtime_ms: fingerprint.marker_mtime_ms,
+ llama_runtime: fingerprint.llama_runtime.clone(),
desktop_protocol_version: DESKTOP_PROTOCOL_VERSION,
desktop_manageability_version: DESKTOP_MANAGEABILITY_VERSION,
capability: capability.clone(),
@@ -591,6 +1180,18 @@ fn desktop_capability_stale_reason(capability: &DesktopCapability) -> Option<Str
.unwrap_or_else(|| "studio_install_incomplete".to_string()),
);
}
+ // Only an explicit false. None means the CLI predates the field or nothing is
+ // installed yet, and calling either stale would put every older install into
+ // repair on its first launch after an upgrade.
+ if capability.llama_runtime_ok == Some(false) {
+ return Some(
+ capability
+ .llama_runtime_reason
+ .clone()
+ .filter(|reason| !reason.is_empty())
+ .unwrap_or_else(|| "llama_runtime_incomplete".to_string()),
+ );
+ }
managed_backend_version_stale_reason(capability.version.as_deref())
}
@@ -658,8 +1259,13 @@ pub(super) async fn probe_managed_bin(bin: PathBuf) -> ManagedProbe {
Ok(true) => {}
}
- if let Some(fingerprint) = managed_bin_fingerprint(&bin) {
- if read_cached_capability(&fingerprint).is_some() {
+ // Taken before the probe and kept, so the answer is stored against the tree the
+ // CLI actually read. Re-reading it afterwards instead let a file quarantined
+ // during the probe be cached as healthy under its own damaged fingerprint, which
+ // then matched on every later launch and the CLI was never asked again.
+ let fingerprint_before = managed_bin_fingerprint(&bin);
+ if let Some(fingerprint) = fingerprint_before.as_ref() {
+ if read_cached_capability(fingerprint).is_some() {
info!(
"Managed preflight: using cached desktop capability for {:?} in {}ms",
bin,
@@ -684,8 +1290,11 @@ pub(super) async fn probe_managed_bin(bin: PathBuf) -> ManagedProbe {
}
};
if let Some(capability) = capability {
- if let Some(fingerprint) = managed_bin_fingerprint(&bin) {
- write_cached_capability(&fingerprint, &capability);
+ if let Some(fingerprint) = fingerprint_to_cache_under(
+ fingerprint_before.as_ref(),
+ managed_bin_fingerprint(&bin),
+ ) {
+ write_cached_capability(fingerprint, &capability);
}
if desktop_capability_ready(&capability) {
info!(
@@ -762,6 +1371,8 @@ mod tests {
desktop_auth_stale_reason: None,
studio_install_ok: Some(true),
studio_install_reason: None,
+ llama_runtime_ok: Some(true),
+ llama_runtime_reason: None,
version: Some(MIN_DESKTOP_BACKEND_VERSION.to_string()),
}
}
@@ -822,37 +1433,142 @@ mod tests {
}
#[test]
- fn older_cli_is_rejected_on_manageability_before_the_install_check() {
- // A CLI predating this feature cannot answer studio_install_ok, so the
- // more specific manageability reason must win in the diagnostics.
+ fn a_quarantined_llama_runtime_is_stale() {
+ // The venv is fine and the marker says installed; quarantine took a DLL out
+ // of the tree. Repairing here stops it surfacing as a model load failure.
let mut capability = healthy_capability();
- capability.desktop_manageability_version = Some(1);
- capability.studio_install_ok = None;
+ capability.llama_runtime_ok = Some(false);
+ capability.llama_runtime_reason = Some("llama_runtime_payload_incomplete".to_string());
assert_eq!(
desktop_capability_stale_reason(&capability).as_deref(),
- Some("desktop_manageability_unsupported")
+ Some("llama_runtime_payload_incomplete")
);
+ assert!(!desktop_capability_ready(&capability));
}
#[test]
- fn a_stale_capability_is_never_served_from_cache() {
- // write_cached_capability runs before the ready check, so an incomplete
- // install does get cached; reusing it would outlive the repair.
+ fn a_broken_runtime_without_a_reason_falls_back_to_a_generic_one() {
let mut capability = healthy_capability();
- capability.studio_install_ok = Some(false);
- let cache = ManagedCapabilityCache {
- schema: MANAGED_CAPABILITY_CACHE_SCHEMA,
- bin_path: "/managed/unsloth".to_string(),
- bin_size: 1,
- bin_mtime_ms: 1,
- studio_root_id: None,
- marker_path: None,
- marker_size: None,
- marker_mtime_ms: None,
- desktop_protocol_version: DESKTOP_PROTOCOL_VERSION,
- desktop_manageability_version: DESKTOP_MANAGEABILITY_VERSION,
- capability,
- };
+ capability.llama_runtime_ok = Some(false);
+ capability.llama_runtime_reason = Some(String::new());
+ assert_eq!(
+ desktop_capability_stale_reason(&capability).as_deref(),
+ Some("llama_runtime_incomplete")
+ );
+ }
+
+ #[test]
+ fn an_unknown_llama_runtime_is_not_stale() {
+ // None is both "no runtime yet" and "this CLI predates the field", and
+ // calling either stale would send every install through repair.
+ let mut capability = healthy_capability();
+ capability.llama_runtime_ok = None;
+ capability.llama_runtime_reason = None;
+ assert_eq!(desktop_capability_stale_reason(&capability), None);
+ assert!(desktop_capability_ready(&capability));
+ }
+
+ /// The payload a CLI without this PR prints. JSON, not a struct literal, which
+ /// cannot show that a missing key deserializes.
+ fn pre_pr_capability_json() -> String {
+ format!(
+ r#"{{
+ "desktop_protocol_version": {protocol},
+ "desktop_manageability_version": {manageability},
+ "supports_api_only": true,
+ "supports_provision_desktop_auth": true,
+ "supports_desktop_backend_ownership": true,
+ "desktop_auth_stale_reason": null,
+ "studio_install_ok": true,
+ "studio_install_reason": null,
+ "version": "{version}"
+ }}"#,
+ protocol = DESKTOP_PROTOCOL_VERSION,
+ manageability = DESKTOP_MANAGEABILITY_VERSION,
+ version = MIN_DESKTOP_BACKEND_VERSION,
+ )
+ }
+
+ #[test]
+ fn a_capability_payload_without_the_new_keys_still_parses_and_is_ready() {
+ // Every install whose CLI predates this prints a payload with neither key.
+ // Failing to parse, or parsing to something stale, would send every
+ // existing user into repair on their next launch.
+ let capability: DesktopCapability =
+ serde_json::from_str(&pre_pr_capability_json()).expect("pre-PR payload must parse");
+ assert_eq!(capability.llama_runtime_ok, None);
+ assert_eq!(capability.llama_runtime_reason, None);
+ assert_eq!(desktop_capability_stale_reason(&capability), None);
+ assert!(desktop_capability_ready(&capability));
+ }
+
+ #[test]
+ fn a_payload_from_a_newer_cli_ignores_keys_this_desktop_does_not_know() {
+ // The CLI and the desktop shell update separately, so a newer CLI can answer
+ // an older desktop. An unknown key must be ignored, not fatal.
+ let json = pre_pr_capability_json().replace(
+ "\"studio_install_ok\": true,",
+ "\"studio_install_ok\": true, \"a_field_from_the_future\": {\"nested\": [1]},",
+ );
+ let capability: DesktopCapability =
+ serde_json::from_str(&json).expect("an unknown key must not be fatal");
+ assert!(desktop_capability_ready(&capability));
+ }
+
+ #[test]
+ fn a_null_llama_runtime_ok_is_not_a_broken_runtime() {
+ // What the CLI prints when the probe itself failed, which is not a verdict.
+ // Explicit nulls, not absent keys, since the CLI seeds both before trying.
+ let json = pre_pr_capability_json().replace(
+ "\"studio_install_ok\": true,",
+ "\"llama_runtime_ok\": null, \"llama_runtime_reason\": \"\", \"studio_install_ok\": true,",
+ );
+ let capability: DesktopCapability = serde_json::from_str(&json).unwrap();
+ assert_eq!(desktop_capability_stale_reason(&capability), None);
+ }
+
+ #[test]
+ fn a_broken_runtime_survives_the_json_round_trip() {
+ // The frontend switches its message on this exact string.
+ let json = pre_pr_capability_json().replace(
+ "\"studio_install_ok\": true,",
+ "\"llama_runtime_ok\": false, \"llama_runtime_reason\": \"llama_runtime_binaries_missing\", \"studio_install_ok\": true,",
+ );
+ let capability: DesktopCapability = serde_json::from_str(&json).unwrap();
+ assert_eq!(
+ desktop_capability_stale_reason(&capability).as_deref(),
+ Some("llama_runtime_binaries_missing")
+ );
+ }
+
+ #[test]
+ fn a_cache_file_written_before_this_field_is_ignored_rather_than_fatal() {
+ // On disk in every existing install. Schema 3 predates the runtime
+ // fingerprint, so its Ready was reached without looking at the runtime: it
+ // must miss and be rewritten, not panic and not be served.
+ let old = format!(
+ r#"{{
+ "schema": 3,
+ "bin_path": "/managed/unsloth",
+ "bin_size": 1,
+ "bin_mtime_ms": 1,
+ "studio_root_id": null,
+ "marker_path": null,
+ "marker_size": null,
+ "marker_mtime_ms": null,
+ "desktop_protocol_version": {protocol},
+ "desktop_manageability_version": {manageability},
+ "capability": {capability}
+ }}"#,
+ protocol = DESKTOP_PROTOCOL_VERSION,
+ manageability = DESKTOP_MANAGEABILITY_VERSION,
+ capability = pre_pr_capability_json(),
+ );
+ let cache: ManagedCapabilityCache =
+ serde_json::from_str(&old).expect("an old cache file must still parse");
+ assert_eq!(cache.llama_runtime, None);
+ assert_ne!(cache.schema, MANAGED_CAPABILITY_CACHE_SCHEMA);
+
let fingerprint = ManagedBinFingerprint {
bin_path: "/managed/unsloth".to_string(),
bin_size: 1,
@@ -861,65 +1577,296 @@ mod tests {
marker_path: None,
marker_size: None,
marker_mtime_ms: None,
+ llama_runtime: Some("12:345".to_string()),
};
- assert!(!cache_matches(&cache, &fingerprint));
+ assert!(
+ !cache_matches(&cache, &fingerprint),
+ "a cache from before the runtime was fingerprinted must not be served"
+ );
}
- // Quarantine deletes the generated unsloth.exe, so the supported stubless layout
- // hands back a launcher path that is not on disk. Without a stand-in the
- // fingerprint is None, the capability cache can be neither read nor written, and
- // every preflight pays both probe subprocesses again.
- #[cfg(windows)]
#[test]
- fn a_quarantined_launcher_is_fingerprinted_through_its_interpreter() {
- let venv = std::env::temp_dir().join(format!(
- "unsloth-fingerprint-quarantined-{}-{:?}",
+ fn a_quarantined_runtime_file_changes_the_fingerprint() {
+ // Without the runtime in the fingerprint the cache hits, preflight answers
+ // Ready from it, and the CLI is never asked whether the runtime is intact.
+ let root = std::env::temp_dir().join(format!(
+ "unsloth-llama-fingerprint-{}-{:?}",
std::process::id(),
std::thread::current().id()
));
- let scripts = venv.join("Scripts");
- fs::create_dir_all(&scripts).unwrap();
- let bin = scripts.join("unsloth.exe");
- let interpreter = scripts.join("python.exe");
- fs::write(&interpreter, "python").unwrap();
- assert!(!bin.exists(), "this case is about the launcher being gone");
+ let _ = fs::remove_dir_all(&root);
+ let mut bin = root.join("build").join("bin");
+ if cfg!(windows) {
+ bin = bin.join("Release");
+ }
+ fs::create_dir_all(&bin).unwrap();
+ fs::write(bin.join("llama.dll"), vec![0u8; 1024]).unwrap();
+ fs::write(bin.join("ggml-base.dll"), vec![0u8; 2048]).unwrap();
- let fingerprint = managed_bin_fingerprint(&bin)
- .expect("a stubless venv must still fingerprint, through python.exe");
- // The identity stays the launcher path, so the two layouts of one install
- // cannot share a cache entry.
- assert!(fingerprint.bin_path.ends_with("unsloth.exe"));
- // And it tracks the interpreter, so a venv replaced by an update invalidates.
- fs::write(&interpreter, "python-after-an-update").unwrap();
- let after = managed_bin_fingerprint(&bin).unwrap();
- assert_ne!(fingerprint.bin_size, after.bin_size);
+ let intact =
+ llama_runtime_fingerprint_at(&root).expect("an installed runtime must fingerprint");
+ assert_eq!(
+ intact,
+ llama_runtime_fingerprint_at(&root).unwrap(),
+ "the same tree must fingerprint the same twice, or every launch misses its own cache"
+ );
- // With no interpreter either there is nothing to stand in, and None is right.
- fs::remove_file(&interpreter).unwrap();
- assert!(managed_bin_fingerprint(&bin).is_none());
+ fs::remove_file(bin.join("ggml-base.dll")).unwrap();
+ let quarantined = llama_runtime_fingerprint_at(&root).unwrap();
+ assert_ne!(intact, quarantined);
- let _ = fs::remove_dir_all(&venv);
+ // A directory is not a file: a stray subfolder must not read as a binary.
+ fs::create_dir(bin.join("some-subdir")).unwrap();
+ assert_eq!(quarantined, llama_runtime_fingerprint_at(&root).unwrap());
+
+ // A file replaced by one of a different size is caught by the byte total
+ // even though the count is unchanged.
+ fs::write(bin.join("llama.dll"), vec![0u8; 4096]).unwrap();
+ assert_ne!(quarantined, llama_runtime_fingerprint_at(&root).unwrap());
+
+ // The whole tree going is distinct from an empty one: only one of the two
+ // means nothing was ever installed.
+ fs::remove_dir_all(&root).unwrap();
+ assert_eq!(llama_runtime_fingerprint_at(&root), None);
+ fs::create_dir_all(&bin).unwrap();
+ assert_eq!(
+ llama_runtime_fingerprint_at(&root).as_deref(),
+ Some("bin:0:0:0:0:0|root:-,-")
+ );
+
+ let _ = fs::remove_dir_all(&root);
}
#[test]
- fn dropping_the_manifest_changes_the_fingerprint() {
- // Otherwise a cache entry written while healthy outlives the manifest,
- // and the probe returns Ready on the very venv this is meant to catch.
- let venv = std::env::temp_dir().join(format!(
- "unsloth-fingerprint-{}-{:?}",
+ fn a_marker_left_over_a_missing_build_dir_changes_the_fingerprint() {
+ // The transition a read_dir(bin).ok()? alone cannot see: nothing installed
+ // and a marker over a tree with no build/bin both fail that read, so both
+ // fingerprinted as None, while the CLI's verdict moves from null (not
+ // stale) to llama_runtime_dir_missing. The cached Ready outlived it.
+ let root = std::env::temp_dir().join(format!(
+ "unsloth-llama-nobin-{}-{:?}",
std::process::id(),
std::thread::current().id()
));
- let scripts = venv.join("bin");
- fs::create_dir_all(&scripts).unwrap();
- let bin = scripts.join("unsloth");
- fs::write(&bin, "#!/bin/sh\nexit 0\n").unwrap();
- let manifest = venv.join("unsloth_install_manifest.json");
- fs::write(&manifest, "{}").unwrap();
+ let _ = fs::remove_dir_all(&root);
- let with_manifest = managed_bin_fingerprint(&bin).unwrap();
- fs::remove_file(&manifest).unwrap();
- let without_manifest = managed_bin_fingerprint(&bin).unwrap();
+ assert_eq!(
+ llama_runtime_fingerprint_at(&root),
+ None,
+ "no tree at all is the NotInstalled case, and stays None"
+ );
+
+ fs::create_dir_all(&root).unwrap();
+ let empty_tree = llama_runtime_fingerprint_at(&root);
+ assert!(
+ empty_tree.is_some(),
+ "a runtime root with no build/bin is a broken install, not an absent one"
+ );
+
+ fs::write(root.join("unsloth_llama_prebuilt.json"), b"{}").unwrap();
+ assert_ne!(
+ empty_tree,
+ llama_runtime_fingerprint_at(&root),
+ "a marker arriving over a missing build/bin must invalidate the cached Ready"
+ );
+
+ // Still distinct from a tree whose build/bin exists and is empty.
+ let mut bin = root.join("build").join("bin");
+ if cfg!(windows) {
+ bin = bin.join("Release");
+ }
+ fs::create_dir_all(&bin).unwrap();
+ assert_ne!(
+ llama_runtime_fingerprint_at(&root),
+ empty_tree,
+ "an empty binary directory is not the same state as a missing one"
+ );
+
+ let _ = fs::remove_dir_all(&root);
+ }
+
+ #[test]
+ fn the_runtime_override_is_resolved_the_way_python_resolves_it() {
+ // default_managed_llama_dir() strips the value and calls expanduser. Reading
+ // it raw would fingerprint a folder literally named "~" and silently drop the
+ // runtime out for every user who wrote the override that way.
+ let home = PathBuf::from(if cfg!(windows) {
+ "C:\\Users\\me"
+ } else {
+ "/home/me"
+ });
+ let cwd = PathBuf::from(if cfg!(windows) { "C:\\work" } else { "/work" });
+ let absolute = if cfg!(windows) {
+ "C:\\opt\\llama.cpp"
+ } else {
+ "/opt/llama.cpp"
+ };
+ let cases: Vec<(Option<&str>, Option<PathBuf>)> = vec![
+ (None, None),
+ (Some(""), None),
+ (Some(" "), None),
+ (Some("~"), Some(home.clone())),
+ (Some("~/llama.cpp"), Some(home.join("llama.cpp"))),
+ (Some(" ~/llama.cpp "), Some(home.join("llama.cpp"))),
+ (Some(absolute), Some(PathBuf::from(absolute))),
+ // Not expanded, since nothing here can resolve another user's home, so
+ // it is anchored like any other relative value.
+ (
+ Some("~someone/llama.cpp"),
+ Some(cwd.join("~someone/llama.cpp")),
+ ),
+ // Anchored to this process's directory, the one
+ // relative_override_pins joins the child's copy against.
+ (Some("llama.cpp"), Some(cwd.join("llama.cpp"))),
+ (Some("./llama.cpp"), Some(cwd.join("./llama.cpp"))),
+ (Some("../llama.cpp"), Some(cwd.join("../llama.cpp"))),
+ ];
+ for (value, expected) in cases {
+ assert_eq!(
+ llama_runtime_override_from(value, Some(&home), Some(&cwd)),
+ expected,
+ "value {value:?}"
+ );
+ }
+ }
+
+ #[test]
+ fn an_override_that_cannot_be_anchored_is_dropped_rather_than_guessed() {
+ // No home to expand against and no directory to anchor to. Guessing would
+ // make the cached verdict track a folder the child was never pointed at.
+ assert_eq!(llama_runtime_override_from(Some("~/x"), None, None), None);
+ assert_eq!(llama_runtime_override_from(Some("x"), None, None), None);
+ // An absolute value needs neither, so it still resolves.
+ let absolute = if cfg!(windows) {
+ "C:\\opt\\llama.cpp"
+ } else {
+ "/opt/llama.cpp"
+ };
+ assert_eq!(
+ llama_runtime_override_from(Some(absolute), None, None),
+ Some(PathBuf::from(absolute))
+ );
+ }
+
+ #[cfg(windows)]
+ #[test]
+ fn the_windows_tilde_resolves_through_the_same_profile_the_child_uses() {
+ // ntpath.expanduser answers USERPROFILE, while dirs::home_dir() reads the
+ // known folder, which a portable or overridden profile moves. Taking the
+ // known folder would fingerprint a tree the child never looks at.
+ // process.rs carries the same note at its own read.
+ let _guard = crate::native_path_policy::PROCESS_ENV_LOCK.lock();
+ let previous = std::env::var_os("USERPROFILE");
+ std::env::set_var("USERPROFILE", "C:\\Portable\\Profile");
+ let resolved = tilde_home();
+ match previous {
+ Some(value) => std::env::set_var("USERPROFILE", value),
+ None => std::env::remove_var("USERPROFILE"),
+ }
+ assert_eq!(resolved, Some(PathBuf::from("C:\\Portable\\Profile")));
+ }
+
+ #[test]
+ fn older_cli_is_rejected_on_manageability_before_the_install_check() {
+ // A CLI predating this feature cannot answer studio_install_ok, so the
+ // more specific manageability reason must win in the diagnostics.
+ let mut capability = healthy_capability();
+ capability.desktop_manageability_version = Some(1);
+ capability.studio_install_ok = None;
+ assert_eq!(
+ desktop_capability_stale_reason(&capability).as_deref(),
+ Some("desktop_manageability_unsupported")
+ );
+ }
+
+ #[test]
+ fn a_stale_capability_is_never_served_from_cache() {
+ // write_cached_capability runs before the ready check, so an incomplete
+ // install does get cached; reusing it would outlive the repair.
+ let mut capability = healthy_capability();
+ capability.studio_install_ok = Some(false);
+ let cache = ManagedCapabilityCache {
+ schema: MANAGED_CAPABILITY_CACHE_SCHEMA,
+ bin_path: "/managed/unsloth".to_string(),
+ bin_size: 1,
+ bin_mtime_ms: 1,
+ studio_root_id: None,
+ marker_path: None,
+ marker_size: None,
+ marker_mtime_ms: None,
+ llama_runtime: None,
+ desktop_protocol_version: DESKTOP_PROTOCOL_VERSION,
+ desktop_manageability_version: DESKTOP_MANAGEABILITY_VERSION,
+ capability,
+ };
+ let fingerprint = ManagedBinFingerprint {
+ bin_path: "/managed/unsloth".to_string(),
+ bin_size: 1,
+ bin_mtime_ms: 1,
+ studio_root_id: None,
+ marker_path: None,
+ marker_size: None,
+ marker_mtime_ms: None,
+ llama_runtime: None,
+ };
+ assert!(!cache_matches(&cache, &fingerprint));
+ }
+
+ // Quarantine deletes the generated unsloth.exe, so the supported stubless layout
+ // hands back a launcher path that is not on disk. Without a stand-in the
+ // fingerprint is None, the capability cache can be neither read nor written, and
+ // every preflight pays both probe subprocesses again.
+ #[cfg(windows)]
+ #[test]
+ fn a_quarantined_launcher_is_fingerprinted_through_its_interpreter() {
+ let venv = std::env::temp_dir().join(format!(
+ "unsloth-fingerprint-quarantined-{}-{:?}",
+ std::process::id(),
+ std::thread::current().id()
+ ));
+ let scripts = venv.join("Scripts");
+ fs::create_dir_all(&scripts).unwrap();
+ let bin = scripts.join("unsloth.exe");
+ let interpreter = scripts.join("python.exe");
+ fs::write(&interpreter, "python").unwrap();
+ assert!(!bin.exists(), "this case is about the launcher being gone");
+
+ let fingerprint = managed_bin_fingerprint(&bin)
+ .expect("a stubless venv must still fingerprint, through python.exe");
+ // The identity stays the launcher path, so the two layouts of one install
+ // cannot share a cache entry.
+ assert!(fingerprint.bin_path.ends_with("unsloth.exe"));
+ // And it tracks the interpreter, so a venv replaced by an update invalidates.
+ fs::write(&interpreter, "python-after-an-update").unwrap();
+ let after = managed_bin_fingerprint(&bin).unwrap();
+ assert_ne!(fingerprint.bin_size, after.bin_size);
+
+ // With no interpreter either there is nothing to stand in, and None is right.
+ fs::remove_file(&interpreter).unwrap();
+ assert!(managed_bin_fingerprint(&bin).is_none());
+
+ let _ = fs::remove_dir_all(&venv);
+ }
+
+ #[test]
+ fn dropping_the_manifest_changes_the_fingerprint() {
+ // Otherwise a cache entry written while healthy outlives the manifest,
+ // and the probe returns Ready on the very venv this is meant to catch.
+ let venv = std::env::temp_dir().join(format!(
+ "unsloth-fingerprint-{}-{:?}",
+ std::process::id(),
+ std::thread::current().id()
+ ));
+ let scripts = venv.join("bin");
+ fs::create_dir_all(&scripts).unwrap();
+ let bin = scripts.join("unsloth");
+ fs::write(&bin, "#!/bin/sh\nexit 0\n").unwrap();
+ let manifest = venv.join("unsloth_install_manifest.json");
+ fs::write(&manifest, "{}").unwrap();
+
+ let with_manifest = managed_bin_fingerprint(&bin).unwrap();
+ fs::remove_file(&manifest).unwrap();
+ let without_manifest = managed_bin_fingerprint(&bin).unwrap();
assert_ne!(with_manifest, without_manifest);
let _ = fs::remove_dir_all(&venv);
@@ -935,6 +1882,7 @@ mod tests {
marker_path: fingerprint.marker_path.clone(),
marker_size: fingerprint.marker_size,
marker_mtime_ms: fingerprint.marker_mtime_ms,
+ llama_runtime: fingerprint.llama_runtime.clone(),
desktop_protocol_version: DESKTOP_PROTOCOL_VERSION,
desktop_manageability_version: DESKTOP_MANAGEABILITY_VERSION,
capability: healthy_capability(),
@@ -1034,4 +1982,1134 @@ mod tests {
assert!(is_context_reason(WORKING_DIRECTORY_UNAVAILABLE));
assert!(!is_context_reason("cli_unusable"));
}
+
+ /// A scratch directory of this test's own, emptied before it is handed back.
+ ///
+ /// These tests walk real files on parallel threads, so two sharing one path
+ /// would delete each other's tree mid-walk. Process id plus thread id keys it,
+ /// as above, and keeps a leaked directory from being reused.
+ fn scratch_dir(name: &str) -> PathBuf {
+ let dir = std::env::temp_dir().join(format!(
+ "unsloth-managed-{name}-{}-{:?}",
+ std::process::id(),
+ std::thread::current().id()
+ ));
+ let _ = fs::remove_dir_all(&dir);
+ fs::create_dir_all(&dir).unwrap();
+ dir
+ }
+
+ /// The one directory llama_runtime_fingerprint_at walks, kept in one place so
+ /// the tests and the walk cannot drift apart on the Windows-only Release level.
+ fn runtime_bin_dir(root: &Path) -> PathBuf {
+ let bin = root.join("build").join("bin");
+ if cfg!(windows) {
+ bin.join("Release")
+ } else {
+ bin
+ }
+ }
+
+ /// A tree shaped like a prebuilt install: a server binary and one shared
+ /// library, the smallest thing quarantine can take a file out of.
+ /// The names half of an expected fingerprint, so the counters beside it stay
+ /// readable as literals.
+ fn names_sum(names: &[&str]) -> u64 {
+ names.iter().fold(0u64, |acc, name| {
+ acc.wrapping_add(name_hash(std::ffi::OsStr::new(name)))
+ })
+ }
+
+ /// The entrypoint name `holds_a_llama_server` looks for on this platform.
+ fn server_file_name() -> &'static str {
+ if cfg!(windows) {
+ "llama-server.exe"
+ } else {
+ "llama-server"
+ }
+ }
+
+ fn install_fake_runtime(root: &Path) -> PathBuf {
+ let bin = runtime_bin_dir(root);
+ fs::create_dir_all(&bin).unwrap();
+ let server = bin.join("llama-server");
+ fs::write(&server, vec![0u8; 4096]).unwrap();
+ // Executable, as the installer leaves it, so the counter that watches the
+ // bit starts where a real install starts.
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::PermissionsExt;
+ let mut mode = fs::metadata(&server).unwrap().permissions();
+ mode.set_mode(0o755);
+ fs::set_permissions(&server, mode).unwrap();
+ }
+ let library = bin.join("libggml-base.so");
+ fs::write(&library, vec![0u8; 2048]).unwrap();
+ // Explicit, not umask-dependent: the permission bits are part of the
+ // fingerprint now, so a runner with a different umask would otherwise
+ // read a different string for the same tree.
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::PermissionsExt;
+ let mut mode = fs::metadata(&library).unwrap().permissions();
+ mode.set_mode(0o644);
+ fs::set_permissions(&library, mode).unwrap();
+ }
+ bin
+ }
+
+ /// A fingerprint whose venv half is fixed and whose runtime half is read off
+ /// disk now, which is what each launch does. Built here rather than through
+ /// managed_bin_fingerprint to keep the process-wide
+ /// UNSLOTH_TEST_LLAMA_RUNTIME_ROOT out of tests running beside these.
+ fn fingerprint_for_runtime(runtime_root: &Path) -> ManagedBinFingerprint {
+ ManagedBinFingerprint {
+ bin_path: "/managed/unsloth".to_string(),
+ bin_size: 42,
+ bin_mtime_ms: 1_700_000_000_000,
+ studio_root_id: None,
+ marker_path: None,
+ marker_size: None,
+ marker_mtime_ms: None,
+ llama_runtime: llama_runtime_fingerprint_at(runtime_root),
+ }
+ }
+
+ /// Points capability_cache_path() at a directory of this test's own for as long
+ /// as the guard lives.
+ ///
+ /// The hook is a process-wide variable, so the guard holds PROCESS_ENV_LOCK for
+ /// the whole test: the same lock preflight.rs takes around its own
+ /// capability-cache tests and main.rs around XDG_DATA_HOME. The per-test
+ /// directory means a file left by a panicking test cannot be read by another.
+ struct CapabilityCacheHome {
+ home: PathBuf,
+ previous: Option<std::ffi::OsString>,
+ /// Declared last so it is released after the restore below has run.
+ _env: std::sync::MutexGuard<'static, ()>,
+ }
+
+ impl CapabilityCacheHome {
+ fn new(test_name: &str) -> Self {
+ let _env = crate::native_path_policy::PROCESS_ENV_LOCK
+ .lock()
+ .unwrap_or_else(|poisoned| poisoned.into_inner());
+ let home = std::env::temp_dir().join(format!(
+ "unsloth-managed-cache-{test_name}-{}-{:?}",
+ std::process::id(),
+ std::thread::current().id()
+ ));
+ let _ = fs::remove_dir_all(&home);
+ fs::create_dir_all(&home).unwrap();
+ let previous = std::env::var_os("UNSLOTH_TEST_DESKTOP_CAPABILITY_CACHE_HOME");
+ std::env::set_var("UNSLOTH_TEST_DESKTOP_CAPABILITY_CACHE_HOME", &home);
+ Self {
+ home,
+ previous,
+ _env,
+ }
+ }
+
+ /// Resolved through the hook rather than rebuilt here, so a layout change
+ /// cannot leave these tests asserting against a path nothing writes.
+ fn cache_file(&self) -> PathBuf {
+ let path = capability_cache_path().expect("the test hook must resolve a cache path");
+ assert!(
+ path.starts_with(&self.home),
+ "the hook must resolve inside this test's home, not the real one: {path:?}"
+ );
+ path
+ }
+ }
+
+ impl Drop for CapabilityCacheHome {
+ fn drop(&mut self) {
+ match &self.previous {
+ Some(previous) => {
+ std::env::set_var("UNSLOTH_TEST_DESKTOP_CAPABILITY_CACHE_HOME", previous)
+ }
+ None => std::env::remove_var("UNSLOTH_TEST_DESKTOP_CAPABILITY_CACHE_HOME"),
+ }
+ let _ = fs::remove_dir_all(&self.home);
+ }
+ }
+
+ #[test]
+ fn an_unchanged_runtime_serves_the_cached_capability_back_from_disk() {
+ // A healthy install must hit on its second launch, or the desktop pays both
+ // probe subprocesses and their 10s ceilings every time the window opens.
+ let home = CapabilityCacheHome::new("hit");
+ let root = scratch_dir("runtime-hit");
+ install_fake_runtime(&root);
+
+ let fingerprint = fingerprint_for_runtime(&root);
+ assert!(
+ read_cached_capability(&fingerprint).is_none(),
+ "nothing is cached yet, so the first launch must miss"
+ );
+ write_cached_capability(&fingerprint, &healthy_capability());
+ assert!(
+ home.cache_file().exists(),
+ "the cache must reach disk, not just the struct"
+ );
+
+ // The next launch recomputes the fingerprint against the same tree.
+ let relaunch = fingerprint_for_runtime(&root);
+ let cached = read_cached_capability(&relaunch)
+ .expect("an install nothing touched must hit its own cache");
+ assert_eq!(cached.llama_runtime_ok, Some(true));
+ assert!(desktop_capability_ready(&cached));
+
+ let _ = fs::remove_dir_all(&root);
+ }
+
+ #[test]
+ fn a_file_quarantined_out_of_the_runtime_misses_the_cache() {
+ // Quarantine takes one file out of an otherwise present tree, leaving the
+ // venv, markers and launcher untouched. If this hit, preflight would answer
+ // Ready from a cache written while the tree was intact, and the user would
+ // meet the damage as a model load failure.
+ let home = CapabilityCacheHome::new("quarantine");
+ let root = scratch_dir("runtime-quarantine");
+ let bin = install_fake_runtime(&root);
+
+ let healthy = fingerprint_for_runtime(&root);
+ write_cached_capability(&healthy, &healthy_capability());
+ assert!(read_cached_capability(&healthy).is_some());
+
+ fs::remove_file(bin.join("libggml-base.so")).unwrap();
+ let quarantined = fingerprint_for_runtime(&root);
+ assert_ne!(healthy.llama_runtime, quarantined.llama_runtime);
+ assert!(
+ read_cached_capability(&quarantined).is_none(),
+ "a quarantined runtime file must not keep serving a cached Ready"
+ );
+ // The stale entry is still on disk, so the miss came from the fingerprint.
+ assert!(home.cache_file().exists());
+
+ let _ = fs::remove_dir_all(&root);
+ }
+
+ #[test]
+ fn a_file_added_to_the_runtime_misses_the_cache() {
+ // What a half-finished repair or partial download leaves behind: a tree that
+ // gained a file is not the tree the CLI was asked about.
+ let _home = CapabilityCacheHome::new("added");
+ let root = scratch_dir("runtime-added");
+ let bin = install_fake_runtime(&root);
+
+ let before = fingerprint_for_runtime(&root);
+ write_cached_capability(&before, &healthy_capability());
+
+ fs::write(bin.join("llama-quantize"), vec![0u8; 512]).unwrap();
+ let after = fingerprint_for_runtime(&root);
+ assert!(
+ read_cached_capability(&after).is_none(),
+ "a runtime that gained a file must be asked about again"
+ );
+
+ let _ = fs::remove_dir_all(&root);
+ }
+
+ #[test]
+ fn a_runtime_directory_that_is_gone_entirely_misses_the_cache() {
+ // An uninstall between launches. The fingerprint drops to None, which must
+ // not compare equal to the string written while the tree was there.
+ let _home = CapabilityCacheHome::new("removed");
+ let root = scratch_dir("runtime-removed");
+ install_fake_runtime(&root);
+
+ let installed = fingerprint_for_runtime(&root);
+ write_cached_capability(&installed, &healthy_capability());
+
+ fs::remove_dir_all(&root).unwrap();
+ let gone = fingerprint_for_runtime(&root);
+ assert_eq!(gone.llama_runtime, None);
+ assert!(
+ read_cached_capability(&gone).is_none(),
+ "a runtime that was removed must not be served the entry it had while installed"
+ );
+ }
+
+ #[test]
+ fn an_install_with_no_runtime_at_all_still_hits_its_cache() {
+ // A user who never installed a runtime has None on both sides, and treating
+ // that as a change would make every launch pay both subprocesses forever.
+ // The runtime appearing later is a real change and must miss.
+ let _home = CapabilityCacheHome::new("no-runtime");
+ // A path that does not exist, not merely an empty one: a root present
+ // without a build/bin is now its own state, so "no runtime at all" is the
+ // absence of the tree itself.
+ let parent = scratch_dir("runtime-absent");
+ let root = parent.join("never-installed");
+
+ let without = fingerprint_for_runtime(&root);
+ assert_eq!(without.llama_runtime, None);
+ write_cached_capability(&without, &healthy_capability());
+ assert!(
+ read_cached_capability(&fingerprint_for_runtime(&root)).is_some(),
+ "an install with no runtime must not miss its own cache every launch"
+ );
+
+ install_fake_runtime(&root);
+ let with = fingerprint_for_runtime(&root);
+ assert!(with.llama_runtime.is_some());
+ assert!(
+ read_cached_capability(&with).is_none(),
+ "a runtime installed after the cache was written must be probed"
+ );
+
+ let _ = fs::remove_dir_all(&root);
+ }
+
+ #[test]
+ fn a_cached_capability_that_is_itself_broken_is_never_served() {
+ // write_cached_capability runs before the ready check, so a broken runtime's
+ // entry does reach disk. Reading it back must refuse it even though the
+ // fingerprint matches, or the next launch undoes the repair.
+ let home = CapabilityCacheHome::new("broken");
+ let root = scratch_dir("runtime-broken");
+ install_fake_runtime(&root);
+
+ let fingerprint = fingerprint_for_runtime(&root);
+ let mut capability = healthy_capability();
+ capability.llama_runtime_ok = Some(false);
+ capability.llama_runtime_reason = Some("llama_runtime_payload_incomplete".to_string());
+ write_cached_capability(&fingerprint, &capability);
+
+ let raw =
+ fs::read(home.cache_file()).expect("the broken verdict is written like any other");
+ assert!(String::from_utf8_lossy(&raw).contains("llama_runtime_payload_incomplete"));
+ assert!(
+ read_cached_capability(&fingerprint).is_none(),
+ "a broken runtime must be re-probed even when nothing on disk moved"
+ );
+
+ let _ = fs::remove_dir_all(&root);
+ }
+
+ #[test]
+ fn a_runtime_verdict_the_cli_skipped_is_never_cached() {
+ // Codex 3959620616, P2. The CLI declines to grade the managed tree while a
+ // custom runtime is selected, and nothing in this fingerprint watches that
+ // selection: it lives in the settings database and in LLAMA_SERVER_PATH.
+ // Caching the skip meant that clearing the selection made a damaged managed
+ // tree active with its fingerprint unchanged, so the cache kept answering
+ // Ready for a tree nobody had graded.
+ let home = CapabilityCacheHome::new("skipped-verdict");
+ let root = scratch_dir("runtime-skipped-verdict");
+ install_fake_runtime(&root);
+ let fingerprint = fingerprint_for_runtime(&root);
+
+ let mut skipped = healthy_capability();
+ skipped.llama_runtime_ok = None;
+ skipped.llama_runtime_reason = Some(LLAMA_RUNTIME_NOT_MANAGED.to_string());
+ // Still Ready, so this is about the cache and not about the verdict.
+ assert!(desktop_capability_ready(&skipped));
+ write_cached_capability(&fingerprint, &skipped);
+ assert!(
+ !home.cache_file().exists(),
+ "a verdict that was never reached must not reach the cache"
+ );
+ assert!(read_cached_capability(&fingerprint).is_none());
+
+ // The other null, "nothing is installed", is a fact about the tree that the
+ // fingerprint does watch, so it still caches.
+ let mut not_installed = healthy_capability();
+ not_installed.llama_runtime_ok = None;
+ not_installed.llama_runtime_reason = Some(String::new());
+ write_cached_capability(&fingerprint, &not_installed);
+ assert!(
+ read_cached_capability(&fingerprint).is_some(),
+ "only the skipped verdict is uncacheable, or every launch pays a probe"
+ );
+
+ let _ = fs::remove_dir_all(&root);
+ }
+
+ #[test]
+ fn a_verdict_is_only_cached_against_the_tree_the_probe_read() {
+ // Codex 3973890115, P2. The fingerprint used to be re-read after the probe, so
+ // a file quarantined while desktop-capabilities was running was stored as
+ // healthy under its own damaged fingerprint. That entry then matched on every
+ // later launch, the CLI was never asked again, and the repair was never
+ // offered, which is worse than the race it came from.
+ let parent = scratch_dir("verdict-snapshot");
+ let root = parent.join("llama.cpp");
+ install_fake_runtime(&root);
+ let before = fingerprint_for_runtime(&root);
+
+ assert_eq!(
+ fingerprint_to_cache_under(Some(&before), Some(fingerprint_for_runtime(&root))),
+ Some(&before),
+ "an unchanged tree is what the answer describes, so it is cacheable"
+ );
+
+ // Quarantine lands mid-probe.
+ fs::remove_file(runtime_bin_dir(&root).join("libggml-base.so")).unwrap();
+ assert_eq!(
+ fingerprint_to_cache_under(Some(&before), Some(fingerprint_for_runtime(&root))),
+ None,
+ "a verdict about a tree that no longer exists must not be kept"
+ );
+ assert_eq!(fingerprint_to_cache_under(Some(&before), None), None);
+ assert_eq!(fingerprint_to_cache_under(None, Some(before)), None);
+
+ let _ = fs::remove_dir_all(&parent);
+ }
+
+ #[test]
+ fn a_runtime_probe_that_raised_is_never_cached_either() {
+ // Codex 3973660789, P2. A probe that throws leaves a null verdict, which is
+ // Ready, and it carries the damaged tree's own fingerprint, so caching it
+ // froze a Ready that was never reached and every later launch skipped the
+ // probe. Its reason tells it apart from the two nulls that are facts.
+ let home = CapabilityCacheHome::new("probe-failed-verdict");
+ let root = scratch_dir("runtime-probe-failed");
+ install_fake_runtime(&root);
+ let fingerprint = fingerprint_for_runtime(&root);
+
+ let mut failed = healthy_capability();
+ failed.llama_runtime_ok = None;
+ failed.llama_runtime_reason = Some(LLAMA_RUNTIME_PROBE_FAILED.to_string());
+ assert!(desktop_capability_ready(&failed), "still Ready: this is about the cache");
+ write_cached_capability(&fingerprint, &failed);
+ assert!(
+ !home.cache_file().exists(),
+ "an attempt that raised must not freeze a Ready over a damaged tree"
+ );
+ assert!(read_cached_capability(&fingerprint).is_none());
+
+ let _ = fs::remove_dir_all(&root);
+ }
+
+ #[test]
+ fn a_named_windows_profile_resolves_where_the_child_will_look() {
+ // Codex 3959620595, P2. process.rs pins UNSLOTH_LLAMA_CPP_PATH for the child
+ // through expand_windows_user, and the CLI reads it with ntpath.expanduser,
+ // so both land on the sibling profile while this fingerprinted
+ // <cwd>\~other\llama.cpp. Quarantine under the real profile then never
+ // invalidated a cached healthy result. Same cases as process.rs's own test,
+ // so the two readers cannot drift apart.
+ let home = Path::new("C:\\Users\\me");
+ assert_eq!(
+ named_windows_user_home("~other\\llama.cpp", home, Some("me")),
+ Some(PathBuf::from("C:\\Users\\other\\llama.cpp")),
+ );
+ assert_eq!(
+ named_windows_user_home("~other/llama.cpp", home, Some("me")),
+ Some(PathBuf::from("C:\\Users\\other/llama.cpp")),
+ );
+ assert_eq!(
+ named_windows_user_home("~me\\llama.cpp", home, Some("me")),
+ Some(PathBuf::from("C:\\Users\\me\\llama.cpp")),
+ );
+ assert_eq!(
+ named_windows_user_home("~other", home, Some("me")),
+ Some(PathBuf::from("C:\\Users\\other")),
+ );
+ // ntpath declines to guess when this profile is not named after the current
+ // user, since C:\Users\me.DOMAIN is not other's sibling. None here leaves the
+ // value anchored as a relative path, which is what happened before.
+ assert_eq!(
+ named_windows_user_home("~other\\llama.cpp", Path::new("C:\\Users\\me.DOMAIN"), Some("me")),
+ None,
+ );
+ assert_eq!(named_windows_user_home("~other\\llama.cpp", home, None), None);
+ // A bare tilde is the current profile and is handled before this is reached.
+ assert_eq!(named_windows_user_home("~", home, Some("me")), None);
+ assert_eq!(named_windows_user_home("~\\llama.cpp", home, Some("me")), None);
+ }
+
+ #[test]
+ fn a_schema_three_cache_file_on_disk_misses_and_is_rewritten_as_schema_four() {
+ // Byte for byte what the previous release wrote. Everything but the schema
+ // and the new key matches, so the miss can only come from the version bump.
+ // It must not panic, must not be served, and must be replaced.
+ let home = CapabilityCacheHome::new("schema-three");
+ let root = scratch_dir("runtime-schema-three");
+ install_fake_runtime(&root);
+ let fingerprint = fingerprint_for_runtime(&root);
+
+ let path = home.cache_file();
+ fs::create_dir_all(path.parent().unwrap()).unwrap();
+ let previous_release = format!(
+ r#"{{
+ "schema": 3,
+ "bin_path": "{bin_path}",
+ "bin_size": {bin_size},
+ "bin_mtime_ms": {bin_mtime_ms},
+ "studio_root_id": null,
+ "marker_path": null,
+ "marker_size": null,
+ "marker_mtime_ms": null,
+ "desktop_protocol_version": {protocol},
+ "desktop_manageability_version": {manageability},
+ "capability": {capability}
+}}"#,
+ bin_path = fingerprint.bin_path,
+ bin_size = fingerprint.bin_size,
+ bin_mtime_ms = fingerprint.bin_mtime_ms,
+ protocol = DESKTOP_PROTOCOL_VERSION,
+ manageability = DESKTOP_MANAGEABILITY_VERSION,
+ capability = pre_pr_capability_json(),
+ );
+ fs::write(&path, previous_release).unwrap();
+ assert!(
+ read_cached_capability(&fingerprint).is_none(),
+ "a schema 3 entry reached Ready without ever looking at the runtime"
+ );
+
+ write_cached_capability(&fingerprint, &healthy_capability());
+ let rewritten: serde_json::Value =
+ serde_json::from_slice(&fs::read(&path).unwrap()).expect("the rewrite must be JSON");
+ assert_eq!(
+ rewritten["schema"].as_u64(),
+ Some(u64::from(MANAGED_CAPABILITY_CACHE_SCHEMA))
+ );
+ assert_eq!(
+ rewritten["llama_runtime"].as_str(),
+ fingerprint.llama_runtime.as_deref(),
+ "the rewritten entry must carry the runtime the old one had no room for"
+ );
+ assert!(
+ read_cached_capability(&fingerprint).is_some(),
+ "the replacement entry must then hit, or the upgrade never stops re-probing"
+ );
+
+ let _ = fs::remove_dir_all(&root);
+ }
+
+ #[test]
+ fn files_below_the_binary_directory_are_not_walked() {
+ // The walk is one level deep because it runs on the launch path. A nested
+ // directory must contribute nothing, or a model cache parked under build/bin
+ // would make the fingerprint cost grow without bound.
+ let root = scratch_dir("runtime-nested");
+ let bin = install_fake_runtime(&root);
+ let flat = llama_runtime_fingerprint_at(&root).unwrap();
+
+ let nested = bin.join("vendor").join("deep");
+ fs::create_dir_all(&nested).unwrap();
+ fs::write(nested.join("payload.bin"), vec![0u8; 8192]).unwrap();
+ assert_eq!(
+ flat,
+ llama_runtime_fingerprint_at(&root).unwrap(),
+ "a subdirectory and its contents are not part of the runtime fingerprint"
+ );
+
+ let _ = fs::remove_dir_all(&root);
+ }
+
+ #[test]
+ fn a_replacement_of_the_same_size_is_a_collision_this_fingerprint_does_not_catch() {
+ // The fingerprint is a count and a byte total, no mtime and no hash, so a
+ // file rewritten in place at its old length is invisible. Accepted because
+ // quarantine and partial extraction always change one of the two.
+ let root = scratch_dir("runtime-collision");
+ let bin = install_fake_runtime(&root);
+ let original = llama_runtime_fingerprint_at(&root).unwrap();
+
+ fs::write(bin.join("llama-server"), vec![0xABu8; 4096]).unwrap();
+ assert_eq!(
+ original,
+ llama_runtime_fingerprint_at(&root).unwrap(),
+ "same count and same bytes is a collision, and this asserts it honestly"
+ );
+
+ fs::write(bin.join("llama-server"), vec![0u8; 4097]).unwrap();
+ assert_ne!(
+ original,
+ llama_runtime_fingerprint_at(&root).unwrap(),
+ "one byte of size difference must still invalidate"
+ );
+
+ let _ = fs::remove_dir_all(&root);
+ }
+
+ #[test]
+ fn a_root_entrypoint_is_part_of_the_fingerprint() {
+ // Codex 3971674487, P2. _find_llama_server_binary reaches <root>/llama-server
+ // before build/bin, and create_exec_entrypoint writes a real wrapper there when
+ // it cannot make a symlink, so it rots on its own. installed_runtime_health
+ // grades it; the walk above only reads build/bin, so without this the cached
+ // Ready outlived the damage and the CLI was never asked.
+ let root = scratch_dir("runtime-root-entrypoint");
+ install_fake_runtime(&root);
+ let without = llama_runtime_fingerprint_at(&root).unwrap();
+
+ let wrapper = root.join(if cfg!(windows) {
+ "llama-server.exe"
+ } else {
+ "llama-server"
+ });
+ fs::write(&wrapper, b"#!/bin/sh\n").unwrap();
+ let with_wrapper = llama_runtime_fingerprint_at(&root).unwrap();
+ assert_ne!(without, with_wrapper, "a root entrypoint appearing must invalidate");
+
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::PermissionsExt;
+ let mut mode = fs::metadata(&wrapper).unwrap().permissions();
+ mode.set_mode(0o755);
+ fs::set_permissions(&wrapper, mode).unwrap();
+ let executable = llama_runtime_fingerprint_at(&root).unwrap();
+ assert_ne!(with_wrapper, executable, "the wrapper's mode is graded, so watch it");
+
+ mode = fs::metadata(&wrapper).unwrap().permissions();
+ mode.set_mode(0o644);
+ fs::set_permissions(&wrapper, mode).unwrap();
+ assert_eq!(
+ with_wrapper,
+ llama_runtime_fingerprint_at(&root).unwrap(),
+ "and the same tree must fingerprint the same both times"
+ );
+ }
+
+ fs::remove_file(&wrapper).unwrap();
+ assert_eq!(
+ without,
+ llama_runtime_fingerprint_at(&root).unwrap(),
+ "an absent root entrypoint is the state a plain build/bin install is in"
+ );
+
+ let _ = fs::remove_dir_all(&root);
+ }
+
+ #[test]
+ fn renaming_a_runtime_file_in_place_moves_the_fingerprint() {
+ // Codex 3962938547, P2. Quarantine does not always delete: some products
+ // rename the file beside itself. The count, the byte total, the link count
+ // and the mode sum are all aggregates and none of them moves for that, so
+ // the cached Ready kept matching a tree installed_runtime_health rejects
+ // and preflight answered Ready without running the capability probe. The
+ // launch then failed with no repair offered.
+ let root = scratch_dir("runtime-renamed-in-place");
+ let bin = install_fake_runtime(&root);
+
+ let intact = llama_runtime_fingerprint_at(&root).unwrap();
+ fs::rename(
+ bin.join("libggml-base.so"),
+ bin.join("libggml-base.so.quarantine"),
+ )
+ .unwrap();
+ let renamed = llama_runtime_fingerprint_at(&root).unwrap();
+ assert_ne!(
+ intact, renamed,
+ "a required library renamed in place must not fingerprint as the healthy tree"
+ );
+ // And the counters really are blind to it, which is why the names are here.
+ // The root segment is dropped first: it carries its own colons.
+ let counters = |value: &str| {
+ value.split_once('|').unwrap().0.rsplit_once(':').unwrap().0.to_string()
+ };
+ assert_eq!(counters(&intact), counters(&renamed));
+
+ // Renaming it back restores the original exactly, so the sum is a property
+ // of the tree rather than of the order the names arrived in.
+ fs::rename(
+ bin.join("libggml-base.so.quarantine"),
+ bin.join("libggml-base.so"),
+ )
+ .unwrap();
+ assert_eq!(intact, llama_runtime_fingerprint_at(&root).unwrap());
+
+ let _ = fs::remove_dir_all(&root);
+ }
+
+ #[test]
+ fn a_runtime_root_that_is_a_file_fingerprints_as_no_runtime() {
+ // UNSLOTH_LLAMA_CPP_PATH can point at anything a user typed. Joining
+ // build/bin onto a regular file must degrade rather than panic.
+ let parent = scratch_dir("runtime-is-a-file");
+ let root = parent.join("llama.cpp");
+ fs::write(&root, "not a directory").unwrap();
+ assert_eq!(llama_runtime_fingerprint_at(&root), None);
+ let _ = fs::remove_dir_all(&parent);
+ }
+
+ #[test]
+ fn a_runtime_path_with_spaces_and_non_ascii_fingerprints_normally() {
+ // Home directories are named after people, and a path this walk could not
+ // handle would silently drop the runtime out for those users only.
+ let parent = scratch_dir("runtime-unicode");
+ let root = parent.join("Мой каталог ünïcode llama.cpp");
+ install_fake_runtime(&root);
+ assert_eq!(
+ llama_runtime_fingerprint_at(&root).as_deref(),
+ Some(
+ format!(
+ "bin:2:6144:0:{}:{}|root:-,-",
+ if cfg!(unix) { 913 } else { 0 },
+ names_sum(&["llama-server", "libggml-base.so"])
+ )
+ .as_str()
+ )
+ );
+ let _ = fs::remove_dir_all(&parent);
+ }
+
+ #[test]
+ fn the_runtime_fingerprint_does_not_depend_on_directory_order() {
+ // read_dir order is unspecified, and the venv half sorts for that reason.
+ // Two trees with the same files in opposite orders must agree, or an install
+ // misses its own cache on some launches and not others.
+ let parent = scratch_dir("runtime-order");
+ let names = ["llama-server", "libggml.so", "llama-cli", "libmtmd.so"];
+
+ let forwards = parent.join("forwards");
+ let forwards_bin = runtime_bin_dir(&forwards);
+ fs::create_dir_all(&forwards_bin).unwrap();
+ for (index, name) in names.iter().enumerate() {
+ fs::write(forwards_bin.join(name), vec![0u8; 100 + index]).unwrap();
+ }
+
+ let backwards = parent.join("backwards");
+ let backwards_bin = runtime_bin_dir(&backwards);
+ fs::create_dir_all(&backwards_bin).unwrap();
+ for (index, name) in names.iter().enumerate().rev() {
+ fs::write(backwards_bin.join(name), vec![0u8; 100 + index]).unwrap();
+ }
+
+ assert_eq!(
+ llama_runtime_fingerprint_at(&forwards),
+ llama_runtime_fingerprint_at(&backwards)
+ );
+ let _ = fs::remove_dir_all(&parent);
+ }
+
+ #[test]
+ fn a_large_runtime_directory_fingerprints_fast_enough_for_the_launch_path() {
+ // This runs on every launch ahead of the probes it saves, so a build
+ // directory's worth of files must cost milliseconds. The bound is loose
+ // enough not to flake and tight enough to catch a walk that reads contents
+ // or recurses.
+ let root = scratch_dir("runtime-large");
+ let bin = runtime_bin_dir(&root);
+ fs::create_dir_all(&bin).unwrap();
+ for index in 0..5000 {
+ let artifact = bin.join(format!("artifact-{index:05}.o"));
+ fs::write(&artifact, [0u8; 1]).unwrap();
+ // Same reason as install_fake_runtime: the mode is fingerprinted, so
+ // it is set here rather than left to the runner's umask.
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::PermissionsExt;
+ let mut mode = fs::metadata(&artifact).unwrap().permissions();
+ mode.set_mode(0o644);
+ fs::set_permissions(&artifact, mode).unwrap();
+ }
+ }
+
+ let started = Instant::now();
+ let fingerprint = llama_runtime_fingerprint_at(&root);
+ let elapsed = started.elapsed();
+ assert_eq!(
+ fingerprint.as_deref(),
+ Some(
+ format!(
+ "bin:5000:5000:0:{}:{}|root:-,-",
+ if cfg!(unix) { 2100000 } else { 0 },
+ names_sum(
+ &(0..5000)
+ .map(|index| format!("artifact-{index:05}.o"))
+ .collect::<Vec<_>>()
+ .iter()
+ .map(String::as_str)
+ .collect::<Vec<_>>()
+ )
+ )
+ .as_str()
+ )
+ );
+ assert!(
+ elapsed < Duration::from_secs(2),
+ "5000 files took {elapsed:?}, which is too much to spend before the window opens"
+ );
+
+ let _ = fs::remove_dir_all(&root);
+ }
+
+ // Symlinks are what a developer checkout and a hand-placed
+ // UNSLOTH_LLAMA_CPP_PATH look like, and the one input that can make this walk
+ // answer about a tree other than the one it was given.
+ #[cfg(unix)]
+ #[test]
+ fn a_symlinked_runtime_root_fingerprints_the_tree_it_points_at() {
+ let parent = scratch_dir("runtime-symlinked-root");
+ let real = parent.join("real");
+ let bin = install_fake_runtime(&real);
+ let linked = parent.join("linked");
+ std::os::unix::fs::symlink(&real, &linked).unwrap();
+
+ assert_eq!(
+ llama_runtime_fingerprint_at(&real),
+ llama_runtime_fingerprint_at(&linked),
+ "a symlinked root must see the same tree, or an override written that way is not covered"
+ );
+ // And it must keep tracking it: a quarantine through the link counts.
+ fs::remove_file(bin.join("libggml-base.so")).unwrap();
+ assert_eq!(
+ llama_runtime_fingerprint_at(&linked).as_deref(),
+ Some(
+ format!(
+ "bin:1:4096:0:{}:{}|root:-,-",
+ if cfg!(unix) { 493 } else { 0 },
+ names_sum(&["llama-server"])
+ )
+ .as_str()
+ )
+ );
+
+ let _ = fs::remove_dir_all(&parent);
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn a_symlinked_file_inside_the_runtime_is_counted_and_its_loss_is_seen() {
+ // Codex 3960069958, P1. DirEntry::metadata does not follow a link, so a link
+ // was neither a file nor a byte and no count could move when one appeared or
+ // went. That is not a bound worth keeping: on macOS the install name
+ // llama-server loads is the middle link of libggml.dylib -> libggml.0.dylib
+ // -> libggml.0.23.0.dylib, and on Linux the SONAME can be a link too, so
+ // losing exactly the entry installed_runtime_health calls fatal left a
+ // cached Ready matching.
+ let parent = scratch_dir("runtime-symlinked-file");
+ let root = parent.join("llama.cpp");
+ let bin = install_fake_runtime(&root);
+ let before = llama_runtime_fingerprint_at(&root).unwrap();
+
+ std::os::unix::fs::symlink(bin.join("llama-server"), bin.join("llama-cli")).unwrap();
+ let with_link = llama_runtime_fingerprint_at(&root).unwrap();
+ assert_ne!(
+ before, with_link,
+ "a link beside the binaries has to move the fingerprint"
+ );
+ // And losing it again is seen, which is the case that matters.
+ fs::remove_file(bin.join("llama-cli")).unwrap();
+ assert_eq!(before, llama_runtime_fingerprint_at(&root).unwrap());
+
+ let _ = fs::remove_dir_all(&parent);
+ }
+
+ #[test]
+ fn an_installer_managed_venv_names_its_own_runtime() {
+ // Codex 3960069972, P1. The desktop strips UNSLOTH_STUDIO_HOME before
+ // spawning the CLI, but the CLI puts it back: _resolve_studio_home re-infers
+ // the root from sys.prefix and _ensure_studio_env_exported points
+ // UNSLOTH_LLAMA_CPP_PATH at that root's llama.cpp. Reading only the ambient
+ // environment fingerprinted the legacy tree, so quarantine inside the custom
+ // runtime never moved it and a cached Ready outlived the damage.
+ let root = scratch_dir("inferred-studio-home");
+ let bin = root.join("unsloth_studio").join("bin").join("unsloth");
+ fs::create_dir_all(bin.parent().unwrap()).unwrap();
+ fs::write(&bin, b"launcher").unwrap();
+
+ // No sentinel yet, so this is a developer venv that happens to be named
+ // unsloth_studio and the legacy tree is still the answer.
+ assert_eq!(inferred_studio_llama_root(&bin), None);
+
+ fs::create_dir_all(root.join("share")).unwrap();
+ fs::write(root.join("share").join("studio.conf"), b"managed").unwrap();
+ assert_eq!(
+ inferred_studio_llama_root(&bin),
+ Some(root.join("llama.cpp")),
+ "an installer-managed root names the runtime beside it"
+ );
+
+ // A venv that is not the one the installer builds says nothing either.
+ let loose = root.join("some_venv").join("bin").join("unsloth");
+ fs::create_dir_all(loose.parent().unwrap()).unwrap();
+ fs::write(&loose, b"launcher").unwrap();
+ assert_eq!(inferred_studio_llama_root(&loose), None);
+
+ let _ = fs::remove_dir_all(&root);
+ }
+
+ #[test]
+ fn a_recorded_master_root_names_the_runtime_beside_studio() {
+ // Codex 4063549060, P1. `UNSLOTH_HOME=<master>` puts llama.cpp beside studio/,
+ // and the CLI recovers that note and grades <master>/llama.cpp. Fingerprinting
+ // <master>/studio/llama.cpp here watched a tree nothing loads, so one cached
+ // Ready survived quarantine in the runtime the backend actually opens.
+ let master = scratch_dir("master-root-runtime");
+ let studio = master.join("studio");
+ let bin = studio.join("unsloth_studio").join("bin").join("unsloth");
+ fs::create_dir_all(bin.parent().unwrap()).unwrap();
+ fs::write(&bin, b"launcher").unwrap();
+ fs::create_dir_all(studio.join("share")).unwrap();
+ fs::write(studio.join("share").join("studio.conf"), b"managed").unwrap();
+
+ // Without the note this is an ordinary custom root and the runtime is under it.
+ assert_eq!(
+ inferred_studio_llama_root(&bin),
+ Some(studio.join("llama.cpp"))
+ );
+
+ fs::write(
+ studio.join("share").join(".unsloth-master-root"),
+ master.to_string_lossy().as_bytes(),
+ )
+ .unwrap();
+ let expected = master.canonicalize().unwrap_or_else(|_| master.clone());
+ assert_eq!(
+ inferred_studio_llama_root(&bin),
+ Some(expected.join("llama.cpp")),
+ "the recorded master root names the runtime beside studio/"
+ );
+
+ // A note naming a root this tree does not live under is somebody else's
+ // install, exactly as the CLI reads it, so the tree under studio/ stands.
+ let elsewhere = scratch_dir("master-root-elsewhere");
+ fs::write(
+ studio.join("share").join(".unsloth-master-root"),
+ elsewhere.to_string_lossy().as_bytes(),
+ )
+ .unwrap();
+ assert_eq!(
+ inferred_studio_llama_root(&bin),
+ Some(studio.join("llama.cpp"))
+ );
+
+ // An empty note, and one naming a directory that is not there, say nothing.
+ for body in ["", "/nonexistent-master-root-9d3f"] {
+ fs::write(studio.join("share").join(".unsloth-master-root"), body).unwrap();
+ assert_eq!(
+ inferred_studio_llama_root(&bin),
+ Some(studio.join("llama.cpp")),
+ "note body {body:?}"
+ );
+ }
+
+ let _ = fs::remove_dir_all(&elsewhere);
+ let _ = fs::remove_dir_all(&master);
+ }
+
+ #[cfg(not(windows))]
+ #[test]
+ fn the_unix_sentinel_is_the_launcher_the_installer_writes() {
+ let root = scratch_dir("studio-sentinel");
+ fs::create_dir_all(root.join("bin")).unwrap();
+ assert!(!looks_like_installer_managed_studio_home(&root));
+ fs::write(root.join("bin").join("unsloth"), b"launcher").unwrap();
+ assert!(looks_like_installer_managed_studio_home(&root));
+ let _ = fs::remove_dir_all(&root);
+ }
+
+ #[test]
+ fn the_cmd_shim_has_to_be_the_one_the_installer_generated() {
+ // The directory is on PATH, so any file of that name would otherwise be
+ // enough to point a custom root at itself. Same markers Python reads.
+ let root = scratch_dir("cmd-shim");
+ let shim = root.join("unsloth.cmd");
+ fs::create_dir_all(&root).unwrap();
+ assert!(!is_managed_cmd_shim(&shim));
+
+ fs::write(&shim, b"@echo off\r\npython -m unsloth_cli %*\r\n").unwrap();
+ assert!(
+ !is_managed_cmd_shim(&shim),
+ "a hand rolled wrapper that calls the CLI is not this shim"
+ );
+
+ fs::write(
+ &shim,
+ b"@rem unsloth-studio-managed-launcher\r\n@python -c \"from unsloth_cli import app; app()\" %*\r\n",
+ )
+ .unwrap();
+ assert!(is_managed_cmd_shim(&shim));
+
+ // Too big to be the generated shim, whatever it contains.
+ let mut oversized = b"unsloth-studio-managed-launcher from unsloth_cli import app".to_vec();
+ oversized.resize((CMD_SHIM_MAX_BYTES + 1) as usize, b' ');
+ fs::write(&shim, &oversized).unwrap();
+ assert!(!is_managed_cmd_shim(&shim));
+
+ let _ = fs::remove_dir_all(&root);
+ }
+
+ #[test]
+ fn an_override_with_no_server_in_it_does_not_stop_the_search() {
+ // Codex 3960069962, P2. _scan_pinned finds no candidate under an empty or
+ // missing UNSLOTH_LLAMA_CPP_PATH and walks on to the tree behind it, so
+ // treating the override as final fingerprinted a folder nobody loads while
+ // the runtime the backend really opens went unwatched.
+ let root = scratch_dir("override-empty");
+ fs::create_dir_all(&root).unwrap();
+ assert!(!holds_a_llama_server(&root));
+ assert!(!holds_a_llama_server(&root.join("not-there")));
+
+ let bin = install_fake_runtime(&root);
+ // The name the finder looks for, which is not the name that fixture writes:
+ // it exists to be counted, and the counters do not care what a file is
+ // called. On Windows the entrypoint carries .exe, so writing it here is what
+ // makes this a tree the backend would actually stop at.
+ fs::write(bin.join(server_file_name()), b"binary").unwrap();
+ assert!(
+ holds_a_llama_server(&root),
+ "build/bin/llama-server is one of the layouts the backend accepts"
+ );
+
+ // The flat layout counts too, and so does a server without the execute
+ // bit: _scan_pinned calls that one non_executable and the caller turns it
+ // into _unavailable, which ends the search here rather than walking on.
+ let flat = scratch_dir("override-flat");
+ fs::create_dir_all(&flat).unwrap();
+ let server = flat.join(server_file_name());
+ fs::write(&server, b"binary").unwrap();
+ assert!(holds_a_llama_server(&flat));
+
+ // A directory of that name is not a server, and neither is an empty tree.
+ let decoy = scratch_dir("override-decoy");
+ fs::create_dir_all(decoy.join(server_file_name())).unwrap();
+ assert!(!holds_a_llama_server(&decoy));
+ let _ = fs::remove_dir_all(&decoy);
+
+ let _ = bin;
+ let _ = fs::remove_dir_all(&root);
+ let _ = fs::remove_dir_all(&flat);
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn a_named_user_resolves_through_the_reentrant_lookup() {
+ // Codex 3960069965, P2. getpwnam hands back process-global storage and this
+ // runs on a Tauri worker thread, so the lookup is the _r form now. root is
+ // the one account every unix box has, which makes this checkable anywhere.
+ let home = Path::new("/home/whoever");
+ let resolved = named_user_home("~root/llama.cpp", Some(home));
+ assert!(
+ resolved.is_some(),
+ "root must resolve, or the reentrant lookup is not answering at all"
+ );
+ assert!(resolved.unwrap().ends_with("llama.cpp"));
+ assert_eq!(
+ named_user_home("~no-such-account-anywhere/x", Some(home)),
+ None,
+ "an unknown name leaves the value to be anchored like any relative path"
+ );
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn clearing_the_execute_bit_moves_the_fingerprint() {
+ // The other half of the same catch: taking the execute bit off llama-server
+ // changes neither the count nor the byte total, and it is the state
+ // installed_runtime_health answers llama_runtime_binaries_missing for, so a
+ // cached Ready went on matching a tree that could no longer launch.
+ use std::os::unix::fs::PermissionsExt;
+
+ let parent = scratch_dir("runtime-exec-bit");
+ let root = parent.join("llama.cpp");
+ let bin = install_fake_runtime(&root);
+ let before = llama_runtime_fingerprint_at(&root).unwrap();
+
+ let server = bin.join("llama-server");
+ let mut mode = fs::metadata(&server).unwrap().permissions();
+ mode.set_mode(0o644);
+ fs::set_permissions(&server, mode).unwrap();
+ assert_ne!(
+ before,
+ llama_runtime_fingerprint_at(&root).unwrap(),
+ "a binary that can no longer be executed is a different tree"
+ );
+
+ let mut restored = fs::metadata(&server).unwrap().permissions();
+ restored.set_mode(0o755);
+ fs::set_permissions(&server, restored).unwrap();
+ assert_eq!(before, llama_runtime_fingerprint_at(&root).unwrap());
+
+ let _ = fs::remove_dir_all(&parent);
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn losing_only_the_owners_execute_bit_moves_the_fingerprint() {
+ // Codex 3960401504, P2. os.access(X_OK) asks whether THIS user may run the
+ // file, and the owner's bits answer that on their own: 0755 -> 0655 leaves
+ // group and other executable, so a counter of "has some execute bit" never
+ // moved while installed_runtime_health flipped to
+ // llama_runtime_binaries_missing. The permission bits themselves are in the
+ // fingerprint now, so the cached Ready cannot outlive the change.
+ use std::os::unix::fs::PermissionsExt;
+
+ let parent = scratch_dir("runtime-owner-bit");
+ let root = parent.join("llama.cpp");
+ let bin = install_fake_runtime(&root);
+ let server = bin.join("llama-server");
+ let mut executable = fs::metadata(&server).unwrap().permissions();
+ executable.set_mode(0o755);
+ fs::set_permissions(&server, executable).unwrap();
+ let before = llama_runtime_fingerprint_at(&root).unwrap();
+
+ let mut owner_only = fs::metadata(&server).unwrap().permissions();
+ owner_only.set_mode(0o655);
+ fs::set_permissions(&server, owner_only).unwrap();
+ // Still executable to somebody, which is what the old counter measured.
+ assert_eq!(fs::metadata(&server).unwrap().permissions().mode() & 0o111, 0o011);
+ assert_ne!(
+ before,
+ llama_runtime_fingerprint_at(&root).unwrap(),
+ "a binary this user can no longer run is a different tree"
+ );
+
+ let _ = fs::remove_dir_all(&parent);
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn a_dangling_symlink_does_not_break_the_walk() {
+ // What a quarantine that removed a link target leaves behind. The walk must
+ // finish and answer about the real files, not report the runtime missing.
+ let parent = scratch_dir("runtime-dangling");
+ let root = parent.join("llama.cpp");
+ let bin = install_fake_runtime(&root);
+ let before = llama_runtime_fingerprint_at(&root).unwrap();
+
+ std::os::unix::fs::symlink(bin.join("gone.so"), bin.join("libggml.so")).unwrap();
+ let dangling = llama_runtime_fingerprint_at(&root);
+ assert!(
+ dangling.is_some(),
+ "a broken link must not make the walk fail or report the runtime missing"
+ );
+ // It counts as a link rather than as a file, so the real files behind it are
+ // still reported unchanged and only the link counter moves.
+ assert_ne!(before, dangling.clone().unwrap());
+ fs::remove_file(bin.join("libggml.so")).unwrap();
+ assert_eq!(before, llama_runtime_fingerprint_at(&root).unwrap());
+
+ let _ = fs::remove_dir_all(&parent);
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn a_runtime_directory_that_cannot_be_read_is_a_broken_install_not_an_absent_one() {
+ // A tightened-down or half-owned install directory. read_dir fails, and the
+ // answer must be neither a panic nor None: the tree is there, so this is the
+ // broken-install state, and sharing None with a machine that never installed
+ // a runtime let a cache written before the install keep matching after it
+ // broke.
+ use std::os::unix::fs::PermissionsExt;
+
+ let root = scratch_dir("runtime-denied");
+ let bin = install_fake_runtime(&root);
+ let mut denied = fs::metadata(&bin).unwrap().permissions();
+ denied.set_mode(0o000);
+ fs::set_permissions(&bin, denied).unwrap();
+
+ // Mode bits do not apply to root, and some CI images run as root, so assert
+ // only where the denial is real.
+ if fs::read_dir(&bin).is_err() {
+ let denied_fingerprint = llama_runtime_fingerprint_at(&root);
+ assert!(
+ denied_fingerprint.is_some(),
+ "a root that is present but unreadable is a broken install, not an absent one"
+ );
+ assert_ne!(denied_fingerprint, None);
+ }
+
+ let mut restored = fs::metadata(&bin).unwrap().permissions();
+ restored.set_mode(0o755);
+ fs::set_permissions(&bin, restored).unwrap();
+ let _ = fs::remove_dir_all(&root);
+ }
}
diff --git a/studio/src-tauri/src/process.rs b/studio/src-tauri/src/process.rs
index fa5ce8b1d81..32d4d594eb9 100644
--- a/studio/src-tauri/src/process.rs
+++ b/studio/src-tauri/src/process.rs
@@ -2389,6 +2389,58 @@ fn expand_windows_user(
format!("{}{}", base, rest)
}
+/// `~`, `~/rest` and `~name/rest` off Windows, the way posixpath.expanduser reads
+/// them, which is what the CLI this pins for reads them with.
+///
+/// The named form is the one that used to get away: `expand_windows_user` leaves
+/// `~alice` alone off Windows, so it fell through to the anchoring below and the
+/// child was handed `<cwd>/~alice/llama.cpp`, while the fingerprint in
+/// preflight::managed resolved the same value through getpwnam_r and watched
+/// Alice's tree. The two halves of one launch then graded different trees, so
+/// quarantining a file from the tree actually in use left the cached verdict
+/// standing. Same lookup here as there, so they cannot disagree.
+///
+/// An unknown name is left exactly as it arrived, which is also what
+/// expanduser does, and it is then anchored like any other relative value; both
+/// halves agree on that too.
+fn expand_posix_user(value: &str, home: Option<&std::path::Path>) -> String {
+ if !value.starts_with('~') {
+ return value.to_string();
+ }
+ let end = value[1..].find('/').map_or(value.len(), |offset| offset + 1);
+ let (name, rest) = (&value[1..end], &value[end..]);
+ if name.is_empty() {
+ // Bare `~`, which HOME answers.
+ return match home {
+ Some(home) => format!("{}{}", home.to_string_lossy(), rest),
+ None => value.to_string(),
+ };
+ }
+ match crate::preflight::managed::named_user_home(value, home) {
+ Some(resolved) => resolved.to_string_lossy().into_owned(),
+ None => value.to_string(),
+ }
+}
+
+/// Windows rules on Windows, the native ones off it, the same split every other
+/// reader in this function makes. Reading a POSIX value the Windows way is what
+/// left `~alice` unresolved.
+fn expand_user(
+ value: &str,
+ home: Option<&std::path::Path>,
+ username: Option<&str>,
+ windows: bool,
+) -> String {
+ if windows {
+ match home {
+ Some(home) => expand_windows_user(value, home, username),
+ None => value.to_string(),
+ }
+ } else {
+ expand_posix_user(value, home)
+ }
+}
+
fn relative_override_pins_from(
cwd: Option<std::path::PathBuf>,
work_dir: &std::path::Path,
@@ -2467,10 +2519,7 @@ fn relative_override_pins_from(
// that decides nothing here (an expanded %LOCALAPPDATA%, inline
// JSON, a 0/1 toggle) would be read as relative and refuse
// every spawn over a value no directory ever decided.
- let entry = match home {
- Some(home) => expand_windows_user(entry, home, username.as_deref()),
- None => entry.to_string(),
- };
+ let entry = expand_user(entry, home, username.as_deref(), windows);
let Some(entry) = expanded(name, &entry)? else {
continue;
};
@@ -2515,10 +2564,7 @@ fn relative_override_pins_from(
let original = value.trim().to_string();
// The tilde first and the variables second, the order the CLI guard uses,
// so a value that names a folder through both reaches the same one.
- let value = match home {
- Some(home) => expand_windows_user(&original, home, username.as_deref()),
- None => original.clone(),
- };
+ let value = expand_user(&original, home, username.as_deref(), windows);
let Some(value) = expanded(name, &value)? else {
continue;
};
@@ -2627,7 +2673,10 @@ fn relative_override_pins(
// GetFullPathNameW on Windows, which is what knows each drive's own
// current directory.
|value| std::path::absolute(value).ok(),
- dirs::home_dir().as_deref(),
+ // preflight::managed's own reader, not dirs::home_dir(): ntpath.expanduser
+ // answers USERPROFILE and dirs reads the known folder, so an overridden
+ // profile pinned the child to one tree while the fingerprint watched another.
+ crate::preflight::managed::tilde_home().as_deref(),
skipped,
cfg!(windows),
)
@@ -5006,6 +5055,120 @@ mod managed_cli_working_dir_tests {
assert!(child_skipped_env().contains(&"STUDIO_LOCAL_REPO"));
}
+ #[cfg(unix)]
+ #[test]
+ fn a_named_user_override_is_pinned_where_the_fingerprint_watches() {
+ // Codex 3962298677, P2. The two halves of one launch resolved ~name
+ // differently: preflight::managed::llama_runtime_override_from reads it out
+ // of the password database, while this path read it with the Windows rule,
+ // which leaves it alone off Windows, so it was anchored under the directory
+ // being left. The child then graded <cwd>/~root/llama.cpp while the cache
+ // fingerprinted root's own tree, and quarantine under the tree actually in
+ // use never invalidated a Ready verdict.
+ //
+ // root is the one account every unix box has, which makes this checkable
+ // anywhere, and it is the account preflight::managed's own test uses.
+ let cwd = PathBuf::from("/mnt/work/session");
+ let work_dir = PathBuf::from("/home/me/.unsloth");
+ let pins = relative_override_pins_from(
+ Some(cwd.clone()),
+ &work_dir,
+ |name: &str| {
+ (name == "UNSLOTH_LLAMA_CPP_PATH").then(|| "~root/llama.cpp".to_string())
+ },
+ |value: &str| panic!("unexpected value needing the OS: {value}"),
+ Some(std::path::Path::new("/home/me")),
+ MANAGED_CHILD_SCRUBBED_ENV,
+ false,
+ )
+ .unwrap();
+ let pinned = pins
+ .iter()
+ .find(|(name, _)| *name == "UNSLOTH_LLAMA_CPP_PATH")
+ .map(|(_, path)| path.clone())
+ .expect("the override has to be pinned, not dropped");
+ assert!(
+ !pinned.starts_with(&cwd),
+ "a named-user override was anchored under the directory being left: {}",
+ pinned.display()
+ );
+ // The same answer the fingerprint side reaches, through the same lookup.
+ let watched = crate::preflight::managed::named_user_home(
+ "~root/llama.cpp",
+ Some(std::path::Path::new("/home/me")),
+ )
+ .expect("root must resolve, or the lookup is not answering at all");
+ assert_eq!(pinned, watched, "the child and the cache must grade one tree");
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn an_unknown_named_user_is_left_alone_and_anchored_by_both_halves() {
+ // expanduser leaves a name it cannot resolve exactly as it arrived, so both
+ // halves fall through to anchoring it, and they still agree. Guessing here
+ // instead would invent a path neither the child nor the cache would use.
+ let cwd = PathBuf::from("/mnt/work/session");
+ let value = "~no-such-account-anywhere/llama.cpp";
+ let pins = relative_override_pins_from(
+ Some(cwd.clone()),
+ std::path::Path::new("/home/me/.unsloth"),
+ |name: &str| (name == "UNSLOTH_LLAMA_CPP_PATH").then(|| value.to_string()),
+ |value: &str| panic!("unexpected value needing the OS: {value}"),
+ Some(std::path::Path::new("/home/me")),
+ MANAGED_CHILD_SCRUBBED_ENV,
+ false,
+ )
+ .unwrap();
+ assert_eq!(
+ pins,
+ vec![("UNSLOTH_LLAMA_CPP_PATH", cwd.join(value))],
+ "an unresolvable name is anchored, the way the fingerprint anchors it"
+ );
+ }
+
+ #[test]
+ fn the_child_and_the_fingerprint_expand_a_bare_tilde_to_one_home() {
+ // Codex 3973890105, P2, right about the disagreement and wrong about where it
+ // was: this caller passed dirs::home_dir(), not USERPROFILE, so the POSIX side
+ // already agreed. Windows was the odd one: ntpath.expanduser answers USERPROFILE
+ // and dirs reads the known folder, so an overridden profile pinned the child to
+ // one tree while preflight::managed fingerprinted another, and quarantine in the
+ // tree in use never invalidated a cached healthy result. One reader now.
+ let home = crate::preflight::managed::tilde_home();
+ let pinned = expand_user("~/llama.cpp", home.as_deref(), None, cfg!(windows));
+ let watched = crate::preflight::managed::llama_runtime_override_from(
+ Some("~/llama.cpp"),
+ home.as_deref(),
+ Some(std::path::Path::new("/nowhere-relative")),
+ );
+ assert_eq!(
+ Some(std::path::PathBuf::from(pinned)),
+ watched,
+ "the tree the child is pinned to and the tree the cache watches must be one"
+ );
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn a_bare_tilde_override_still_reaches_home_off_windows() {
+ // The form that already worked has to keep working: this used to go through
+ // expand_windows_user, whose empty-name arm answers home on any platform.
+ let pins = relative_override_pins_from(
+ Some(PathBuf::from("/mnt/work/session")),
+ std::path::Path::new("/home/me/.unsloth"),
+ |name: &str| (name == "UNSLOTH_LLAMA_CPP_PATH").then(|| "~/llama.cpp".to_string()),
+ |value: &str| panic!("unexpected value needing the OS: {value}"),
+ Some(std::path::Path::new("/home/me")),
+ MANAGED_CHILD_SCRUBBED_ENV,
+ false,
+ )
+ .unwrap();
+ assert_eq!(
+ pins,
+ vec![("UNSLOTH_LLAMA_CPP_PATH", PathBuf::from("/home/me/llama.cpp"))]
+ );
+ }
+
#[test]
fn a_posix_list_is_split_and_joined_with_its_own_separator() {
// The lost-directory branch already reads POSIX rules; the moving path
diff --git a/tests/studio/install/test_desktop_capability_llama_runtime.py b/tests/studio/install/test_desktop_capability_llama_runtime.py
new file mode 100644
index 00000000000..5700bf18b78
--- /dev/null
+++ b/tests/studio/install/test_desktop_capability_llama_runtime.py
@@ -0,0 +1,921 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""End-to-end contract for the ``llama_runtime_ok`` keys in ``desktop-capabilities``.
+
+The probe function and the payload tables are covered by
+``test_installed_runtime_health`` and ``test_keep_install_backcompat_9979``. This file
+owns the wiring between them: the command the desktop shells out to must emit those keys
+from a real pip install and keep emitting the payload older desktops already parse.
+
+Two failure modes justify the subprocess cost, since an in-process import cannot see them:
+
+* ``studio`` not being packaged. The probe sits inside a bare ``except Exception``, so a
+ wheel without ``studio`` would report null forever with no error and no failure from a
+ source checkout, which has ``studio/`` on sys.path.
+* The command exiting non-zero or dropping a key. The desktop hands stdout to serde_json
+ and treats a failed parse as Stale, so a payload change is launch-blocking.
+
+The subprocess tests need a venv with the CLI installed from this tree, which CI does not
+build; they skip when it is absent. Build one with::
+
+ uv venv "$UNSLOTH_WORKSPACE/temp/venv_desktop_cap"
+ uv pip install --python "$UNSLOTH_WORKSPACE/temp/venv_desktop_cap/bin/python" .
+
+The rest of the file is pure text and dict work and always runs.
+"""
+
+import importlib.util
+import json
+import os
+import pathlib
+import re
+import subprocess
+import sys
+import time
+import typing
+from pathlib import Path
+
+import pytest
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[3]
+MODULE_PATH = PACKAGE_ROOT / "studio" / "install_llama_prebuilt.py"
+SPEC = importlib.util.spec_from_file_location("studio_install_llama_prebuilt", MODULE_PATH)
+assert SPEC is not None and SPEC.loader is not None
+ILP = importlib.util.module_from_spec(SPEC)
+sys.modules[SPEC.name] = ILP
+SPEC.loader.exec_module(ILP)
+
+MANAGED_RS = PACKAGE_ROOT / "studio" / "src-tauri" / "src" / "preflight" / "managed.rs"
+
+# Every key the payload carried before the two llama_runtime keys, with the type the
+# desktop's Option<T> fields require. Spelled out rather than derived from the command's
+# own dict, which could not notice a key being dropped or retyped.
+PRE_PR_KEYS: dict[str, type | tuple[type, ...]] = {
+ "desktop_protocol_version": int,
+ "desktop_manageability_version": int,
+ "supports_provision_desktop_auth": bool,
+ "supports_api_only": bool,
+ "supports_desktop_backend_ownership": bool,
+ "studio_install_ok": bool,
+ "studio_install_reason": str,
+ "version": str,
+}
+NEW_KEYS = ("llama_runtime_ok", "llama_runtime_reason")
+
+# Bumping either tells an older desktop the CLI speaks a protocol it does not know, so an
+# additive key must not touch them.
+EXPECTED_PROTOCOL_VERSION = 1
+EXPECTED_MANAGEABILITY_VERSION = 2
+
+
+def _venv_python() -> Path | None:
+ """The interpreter of the prepared venv, or None when it was never built."""
+ override = os.environ.get("UNSLOTH_DESKTOP_CAP_VENV")
+ root = (
+ Path(override).expanduser()
+ if override
+ else Path(os.environ.get("UNSLOTH_WORKSPACE") or PACKAGE_ROOT.parent)
+ / "temp"
+ / "venv_desktop_cap"
+ )
+ for candidate in (root / "bin" / "python", root / "Scripts" / "python.exe"):
+ if candidate.is_file():
+ return candidate
+ return None
+
+
+VENV_PYTHON = _venv_python()
+NEEDS_VENV = pytest.mark.skipif(
+ VENV_PYTHON is None,
+ reason = "no prepared venv with the CLI installed; see this module's docstring",
+)
+
+
+def _console_script() -> Path:
+ assert VENV_PYTHON is not None
+ name = "unsloth.exe" if os.name == "nt" else "unsloth"
+ return VENV_PYTHON.parent / name
+
+
+def _capabilities(
+ install_dir: Path,
+ tmp_path: Path,
+ *,
+ json_output: bool = True,
+):
+ """Run the installed console script against ``install_dir`` and return (rc, stdout).
+
+ Both overrides point at fixtures so the developer's real ~/.unsloth and Studio home
+ stay out of the run.
+ """
+ env = dict(os.environ)
+ env["UNSLOTH_LLAMA_CPP_PATH"] = str(install_dir)
+ env["UNSLOTH_STUDIO_HOME"] = str(tmp_path / "studio_home")
+ # cwd matters: from the source checkout `studio` resolves to the tree beside it rather
+ # than site-packages, the shadowing this file rules out.
+ args = [str(_console_script()), "studio", "desktop-capabilities"]
+ if json_output:
+ args.append("--json")
+ result = subprocess.run(
+ args,
+ cwd = str(tmp_path),
+ env = env,
+ capture_output = True,
+ text = True,
+ timeout = 120,
+ )
+ return result.returncode, result.stdout
+
+
+def _shared_health_groups() -> list[list[str]]:
+ """Required runtime file groups every install kind on this platform shares.
+
+ Mirrors ``_kept_install_payload_is_healthy`` for a marker naming no backend, the shape
+ the fixture below writes. Derived from the tables so it holds on any platform.
+ """
+ host = ILP.platform_only_host()
+ prefix = "windows-" if host.is_windows else "macos-" if host.is_macos else "linux-"
+ kinds = sorted(k for k in ILP.INSTALL_KIND_BACKENDS if k.startswith(prefix))
+ assert kinds, f"no install kinds for {prefix!r}"
+ shared = set.intersection(
+ *(
+ {
+ tuple(group)
+ for group in ILP.runtime_payload_health_groups(
+ kind,
+ source_label = None,
+ runtime_name = None,
+ tag = "b10830",
+ )
+ }
+ for kind in kinds
+ )
+ )
+ assert shared, "the shared payload must not be empty, or 'complete' means nothing"
+ return [list(group) for group in sorted(shared)]
+
+
+def _complete_tree(root: Path) -> Path:
+ """A marker plus every file the health tables require; returns the runtime dir.
+
+ Empty files, since ``installed_runtime_health`` only looks and never executes.
+ """
+ host = ILP.platform_only_host()
+ runtime_dir = ILP.install_runtime_dir(root, host)
+ runtime_dir.mkdir(parents = True, exist_ok = True)
+ (root / "UNSLOTH_PREBUILT_INFO.json").write_text(
+ json.dumps({"release_tag": "b10830-mix-d5c17a0", "tag": "b10830"}) + "\n",
+ encoding = "utf-8",
+ )
+ for group in _shared_health_groups():
+ # Dropping the globs from the first pattern still matches it:
+ # libggml-cpu*.so* -> libggml-cpu.so.
+ (runtime_dir / group[0].replace("*", "")).write_text("x", encoding = "utf-8")
+ ext = ".exe" if host.is_windows else ""
+ for name in ("server", "quantize"):
+ (runtime_dir / f"llama-{name}{ext}").write_text("x", encoding = "utf-8")
+ return runtime_dir
+
+
+def _assert_pre_pr_payload_intact(payload: dict) -> None:
+ """Every key an older desktop already reads, still present and still its old type."""
+ for key, expected in PRE_PR_KEYS.items():
+ assert key in payload, f"{key} disappeared from the capability payload"
+ # bool subclasses int, so an int field must not accept a bool.
+ if expected is int:
+ assert isinstance(payload[key], int) and not isinstance(
+ payload[key], bool
+ ), f"{key} is {payload[key]!r}, not an int"
+ else:
+ assert isinstance(payload[key], expected), f"{key} is {payload[key]!r}"
+ assert payload["desktop_protocol_version"] == EXPECTED_PROTOCOL_VERSION
+ assert payload["desktop_manageability_version"] == EXPECTED_MANAGEABILITY_VERSION
+
+
+# ── part 1: the real command in a real install ───────────────────────────────
+
+
+@NEEDS_VENV
+def test_studio_is_importable_from_an_installed_wheel():
+ """The whole feature hangs off this import succeeding outside a source checkout.
+
+ ``desktop_capabilities`` swallows every probe exception, so a ``studio`` package
+ missing from the wheel would report null for every user with no error. Run from a cwd
+ that is not the checkout, or the tree beside the tests answers instead.
+ """
+ assert VENV_PYTHON is not None
+ probe = (
+ "import studio.install_llama_prebuilt as m; "
+ "print(m.__file__); print(callable(m.installed_runtime_health))"
+ )
+ result = subprocess.run(
+ [str(VENV_PYTHON), "-c", probe],
+ cwd = str(VENV_PYTHON.parent),
+ capture_output = True,
+ text = True,
+ timeout = 120,
+ )
+ assert result.returncode == 0, result.stderr
+ module_file, callable_flag = result.stdout.strip().splitlines()
+ assert callable_flag == "True"
+ assert (
+ "site-packages" in module_file
+ ), f"resolved to {module_file}, not the installed package; the checkout shadowed it"
+
+
+@NEEDS_VENV
+def test_nothing_installed_reports_null_rather_than_false(tmp_path):
+ """The desktop repairs on an explicit false, so NotInstalled must not report one."""
+ empty = tmp_path / "empty"
+ empty.mkdir()
+ rc, out = _capabilities(empty, tmp_path)
+ assert rc == 0
+ payload = json.loads(out)
+ assert payload["llama_runtime_ok"] is None
+ assert payload["llama_runtime_reason"] == ""
+ _assert_pre_pr_payload_intact(payload)
+
+
+@NEEDS_VENV
+def test_a_complete_tree_reports_true_with_an_empty_reason(tmp_path):
+ root = tmp_path / "llama.cpp"
+ _complete_tree(root)
+ rc, out = _capabilities(root, tmp_path)
+ assert rc == 0
+ payload = json.loads(out)
+ assert payload["llama_runtime_ok"] is True
+ assert payload["llama_runtime_reason"] == ""
+ _assert_pre_pr_payload_intact(payload)
+
+
+@NEEDS_VENV
+def test_a_quarantined_library_reports_false_with_a_reason(tmp_path):
+ """The shape antivirus leaves behind; the reason string is what the desktop shows."""
+ root = tmp_path / "llama.cpp"
+ runtime_dir = _complete_tree(root)
+ victim = sorted(
+ path
+ for path in runtime_dir.iterdir()
+ if not path.name.startswith("llama-server") and not path.name.startswith("llama-quantize")
+ )[0]
+ victim.unlink()
+ rc, out = _capabilities(root, tmp_path)
+ assert rc == 0
+ payload = json.loads(out)
+ assert payload["llama_runtime_ok"] is False
+ assert payload["llama_runtime_reason"], "a false verdict with no reason tells nobody anything"
+ _assert_pre_pr_payload_intact(payload)
+
+
+@NEEDS_VENV
+def test_a_missing_llama_server_reports_binaries_missing(tmp_path):
+ """The payload groups name libraries only, so on Linux and macOS a quarantined
+ llama-server would otherwise read as a complete install."""
+ root = tmp_path / "llama.cpp"
+ runtime_dir = _complete_tree(root)
+ ext = ".exe" if ILP.platform_only_host().is_windows else ""
+ (runtime_dir / f"llama-server{ext}").unlink()
+ rc, out = _capabilities(root, tmp_path)
+ assert rc == 0
+ payload = json.loads(out)
+ assert payload["llama_runtime_ok"] is False
+ assert payload["llama_runtime_reason"] == "llama_runtime_binaries_missing"
+ _assert_pre_pr_payload_intact(payload)
+
+
+@NEEDS_VENV
+def test_the_human_readable_form_still_prints_every_key(tmp_path):
+ """The desktop reads --json; a support request pastes the bare form, same dict."""
+ root = tmp_path / "llama.cpp"
+ _complete_tree(root)
+ rc, out = _capabilities(root, tmp_path, json_output = False)
+ assert rc == 0
+ printed = {line.split(":", 1)[0] for line in out.splitlines() if ":" in line}
+ for key in (*PRE_PR_KEYS, *NEW_KEYS):
+ assert key in printed
+
+
+@NEEDS_VENV
+def test_the_probe_stays_off_the_critical_path_budget(tmp_path):
+ """The command runs at every launch under a desktop timeout, so its cost is a product
+ constraint. Measured as the import plus the call, which is all the try block does.
+
+ The bound is loose (half a second against a measured ~30ms), so it catches a probe that
+ grew a network call or a GPU detection rather than CI jitter.
+ """
+ assert VENV_PYTHON is not None
+ root = tmp_path / "llama.cpp"
+ _complete_tree(root)
+ script = (
+ "import json, time\n"
+ "import unsloth_cli.commands.studio\n"
+ "t0 = time.perf_counter()\n"
+ "from studio.install_llama_prebuilt import installed_runtime_health\n"
+ "t1 = time.perf_counter()\n"
+ "health = installed_runtime_health()\n"
+ "t2 = time.perf_counter()\n"
+ "print(json.dumps({'import': t1 - t0, 'call': t2 - t1, 'health': health}))\n"
+ )
+ env = dict(os.environ)
+ env["UNSLOTH_LLAMA_CPP_PATH"] = str(root)
+ env["UNSLOTH_STUDIO_HOME"] = str(tmp_path / "studio_home")
+ started = time.perf_counter()
+ result = subprocess.run(
+ [str(VENV_PYTHON), "-c", script],
+ cwd = str(tmp_path),
+ env = env,
+ capture_output = True,
+ text = True,
+ timeout = 120,
+ )
+ assert result.returncode == 0, result.stderr
+ measured = json.loads(result.stdout)
+ assert measured["health"] == [True, ""]
+ total = measured["import"] + measured["call"]
+ assert total < 0.5, f"the probe added {total:.3f}s to every launch"
+ assert time.perf_counter() - started < 120
+
+
+@NEEDS_VENV
+def test_an_unimportable_probe_leaves_the_verdict_null(tmp_path):
+ """The ``except Exception`` arm, exercised rather than read.
+
+ A denied tree, a corrupt marker or a missing ``studio`` package must all land on null
+ with the rest of the payload unchanged. ImportError is the one that would hit every
+ user at once, so it is the one simulated: a meta_path hook refusing the module while a
+ complete tree, which would otherwise answer true, sits on disk.
+ """
+ assert VENV_PYTHON is not None
+ root = tmp_path / "llama.cpp"
+ _complete_tree(root)
+ driver = tmp_path / "blocked.py"
+ driver.write_text(
+ "import sys\n"
+ "class _Blocker:\n"
+ " def find_spec(self, name, path = None, target = None):\n"
+ " if name == 'studio.install_llama_prebuilt':\n"
+ " raise ImportError('simulated: studio not shipped')\n"
+ " return None\n"
+ "sys.meta_path.insert(0, _Blocker())\n"
+ "from unsloth_cli import app\n"
+ "sys.argv = ['unsloth', 'studio', 'desktop-capabilities', '--json']\n"
+ "app()\n",
+ encoding = "utf-8",
+ )
+ env = dict(os.environ)
+ env["UNSLOTH_LLAMA_CPP_PATH"] = str(root)
+ env["UNSLOTH_STUDIO_HOME"] = str(tmp_path / "studio_home")
+ result = subprocess.run(
+ [str(VENV_PYTHON), str(driver)],
+ cwd = str(tmp_path),
+ env = env,
+ capture_output = True,
+ text = True,
+ timeout = 120,
+ )
+ assert result.returncode == 0, result.stderr
+ payload = json.loads(result.stdout)
+ assert payload["llama_runtime_ok"] is None
+ assert payload["llama_runtime_reason"] == ""
+ _assert_pre_pr_payload_intact(payload)
+
+
+# ── part 2: interoperability in both directions ──────────────────────────────
+
+
+def test_the_command_emits_exactly_the_pre_pr_keys_plus_the_two_new_ones():
+ """Read off the source, so it holds without the venv. A key added without a matching
+ Option<T> in managed.rs is invisible to the desktop; a key removed breaks it.
+ """
+ source = (PACKAGE_ROOT / "unsloth_cli" / "commands" / "studio.py").read_text(encoding = "utf-8")
+ body = source.split("def desktop_capabilities(", 1)[1]
+ body = body.split("if json_output:", 1)[0]
+ emitted = set(re.findall(r'^\s+"([a-z_]+)":', body, flags = re.MULTILINE))
+ emitted |= set(re.findall(r'payload\["([a-z_]+)"\]', body))
+ assert emitted == set(PRE_PR_KEYS) | set(NEW_KEYS), sorted(emitted)
+
+
+@NEEDS_VENV
+def test_dropping_the_new_keys_yields_the_pre_pr_payload(tmp_path):
+ """Additive, proven by subtraction: strip the two keys and what is left is a payload the
+ pre-PR desktop already accepted. Neither version constant may move, since bumping one
+ tells a desktop to treat the CLI as stale.
+ """
+ root = tmp_path / "llama.cpp"
+ _complete_tree(root)
+ rc, out = _capabilities(root, tmp_path)
+ assert rc == 0
+ payload = json.loads(out)
+ stripped = {key: value for key, value in payload.items() if key not in NEW_KEYS}
+ assert set(stripped) == set(PRE_PR_KEYS)
+ _assert_pre_pr_payload_intact(stripped)
+
+
+def test_the_desktop_reads_every_emitted_key_as_optional():
+ """A desktop built from this tree must survive a pre-PR CLI sending neither new key.
+ serde fills an absent Option with None and managed.rs only treats Some(false) as broken,
+ so absent is safe only while every field stays an Option.
+ """
+ source = MANAGED_RS.read_text(encoding = "utf-8")
+ struct_body = source.split("struct DesktopCapability {", 1)[1].split("\n}", 1)[0]
+ fields = dict(re.findall(r"^\s+([a-z_]+):\s*(.+),$", struct_body, flags = re.MULTILINE))
+ for key in (*PRE_PR_KEYS, *NEW_KEYS):
+ assert key in fields, f"the desktop struct has no field for {key}"
+ assert fields[key].startswith(
+ "Option<"
+ ), f"{key} is {fields[key]}, so a CLI that omits it fails the whole parse"
+
+
+def test_unknown_keys_do_not_break_the_desktop_parse():
+ """An older desktop meeting a newer CLI. serde ignores unknown fields unless told
+ otherwise, so the guard is that nobody adds deny_unknown_fields to the capability
+ struct; without it, today's additive keys would have bricked every shipped desktop.
+ """
+ source = MANAGED_RS.read_text(encoding = "utf-8")
+ assert "deny_unknown_fields" not in source
+ prologue = source.split("struct DesktopCapability {", 1)[0]
+ assert "deny_unknown_fields" not in prologue.rsplit("#[derive", 1)[-1]
+
+
+def test_unknown_keys_do_not_break_the_cli_side_consumer():
+ """The same question for the Python consumer: CI's interrupted-install probe decides
+ HEALTHY or REPAIRABLE from this payload by reading named keys, so extra keys must be
+ inert. A consumer comparing key sets would fail the build on the next additive field.
+ """
+ probe = PACKAGE_ROOT / ".github" / "scripts" / "interrupted_install_probe.py"
+ if not probe.is_file():
+ pytest.skip("CI probe script not present in this tree")
+ source = probe.read_text(encoding = "utf-8")
+ # The parse is `json.loads` plus `.get`, never a key-set comparison.
+ assert 'parsed.get("studio_install_ok")' in source
+ assert not re.search(r"set\(parsed", source)
+ payload = {key: ("" if kind is str else kind()) for key, kind in PRE_PR_KEYS.items()}
+ payload["studio_install_ok"] = True
+ payload.update({key: None for key in NEW_KEYS})
+ payload["some_future_key"] = {"nested": [1, 2, 3]}
+ payload["another_future_key"] = "ignored"
+ parsed = json.loads(json.dumps(payload))
+ assert isinstance(parsed, dict)
+ value = parsed.get("studio_install_ok")
+ assert isinstance(value, bool) and value is True
+
+
+def test_the_managed_probe_is_skipped_when_a_custom_runtime_is_active(monkeypatch):
+ """Codex 3958908987, P2. _find_llama_server_binary prefers LLAMA_SERVER_PATH and the
+ folder chosen in Studio's settings ahead of the managed tree, so grading the managed tree
+ regardless would send a user who runs their own build into repair over an install their
+ backend never opens. Offline that repair cannot even succeed."""
+ active = _active_helper()
+ monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
+ assert active() is True
+
+ pinned = pathlib.Path(__file__).resolve().parents[3] / "studio" / "install_llama_prebuilt.py"
+ monkeypatch.setenv("LLAMA_SERVER_PATH", str(pinned))
+ assert active() is False
+
+ # Whitespace is not a selection: the finder strips before testing it.
+ monkeypatch.setenv("LLAMA_SERVER_PATH", " ")
+ assert active() is True
+
+
+def test_the_managed_runtime_path_override_is_not_treated_as_a_custom_runtime(monkeypatch):
+ """UNSLOTH_LLAMA_CPP_PATH moves the managed root itself, so default_managed_llama_dir
+ already grades exactly the tree that variable names. Skipping on it would drop the
+ coverage for every user who relocated their install."""
+ active = _active_helper()
+ monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
+ monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", "/opt/relocated/llama.cpp")
+ assert active() is True
+
+
+def _helper_namespace(studio_home = None):
+ """The helper block, read out of the CLI source: importing the module pulls in typer.
+
+ ``studio_home`` stands in for the root ``_resolve_studio_home`` inferred off
+ ``sys.prefix``; None is the ordinary legacy install.
+ """
+ text = (
+ pathlib.Path(__file__).resolve().parents[3] / "unsloth_cli" / "commands" / "studio.py"
+ ).read_text(encoding = "utf-8")
+ start = text.index("def _managed_llama_runtime_is_the_active_one")
+ end = text.index('@studio_app.command("desktop-capabilities"', start)
+ # _master_root_llama_dir lives beside the export that writes the same value, so it
+ # is outside the block above and has to come along; taken from the source for the
+ # same reason as the rest, so a change there is what these run.
+ master_start = text.index("def _master_root_llama_dir")
+ master_end = text.index("def _ensure_studio_env_exported", master_start)
+ namespace = {
+ "os": __import__("os"),
+ "sys": __import__("sys"),
+ "Optional": typing.Optional,
+ "Path": pathlib.Path,
+ "_PACKAGE_ROOT": pathlib.Path(__file__).resolve().parents[3],
+ "STUDIO_HOME": pathlib.Path(studio_home)
+ if studio_home is not None
+ else pathlib.Path.home() / ".unsloth" / "studio",
+ "_STUDIO_HOME_IS_CUSTOM": studio_home is not None,
+ }
+ exec(compile(text[master_start:master_end], "<helper>", "exec"), namespace)
+ exec(compile(text[start:end], "<helper>", "exec"), namespace)
+ return namespace
+
+
+def _active_helper():
+ return _helper_namespace()["_managed_llama_runtime_is_the_active_one"]
+
+
+def test_an_inferred_studio_root_is_graded_not_the_legacy_tree(tmp_path, monkeypatch):
+ """Codex 3971960862, P1. The desktop scrubs UNSLOTH_STUDIO_HOME and STUDIO_HOME before
+ it spawns this command (MANAGED_CHILD_SCRUBBED_ENV), so default_managed_llama_dir read
+ an empty environment and answered the legacy ~/.unsloth/llama.cpp, while
+ preflight::managed::inferred_studio_llama_root fingerprints <root>/llama.cpp off the
+ same sys.prefix inference the CLI already made. The two halves graded different trees,
+ so quarantine in the runtime actually in use never moved the cached verdict."""
+ for name in (
+ "LLAMA_SERVER_PATH",
+ "UNSLOTH_LLAMA_CPP_PATH",
+ "UNSLOTH_STUDIO_HOME",
+ "STUDIO_HOME",
+ "UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH",
+ ):
+ monkeypatch.delenv(name, raising = False)
+ root = tmp_path / "custom-studio"
+ graded = _helper_namespace(root)["_llama_runtime_to_grade"]()
+ assert graded == root / "llama.cpp"
+ # And the environment is left exactly as it was found, since this runs inside a command
+ # that goes on to read it.
+ assert "UNSLOTH_STUDIO_HOME" not in os.environ
+
+
+def test_a_legacy_install_still_grades_the_legacy_tree(tmp_path, monkeypatch):
+ """The other direction: nothing was inferred, so nothing is exported and the answer is
+ the tree every ordinary install has."""
+ for name in (
+ "LLAMA_SERVER_PATH",
+ "UNSLOTH_LLAMA_CPP_PATH",
+ "UNSLOTH_STUDIO_HOME",
+ "STUDIO_HOME",
+ "UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH",
+ ):
+ monkeypatch.delenv(name, raising = False)
+ graded = _helper_namespace()["_llama_runtime_to_grade"]()
+ assert graded == pathlib.Path.home() / ".unsloth" / "llama.cpp"
+
+
+def test_an_explicit_studio_home_is_left_alone(tmp_path, monkeypatch):
+ """An ambient UNSLOTH_STUDIO_HOME is the user's, not an inference, and it must survive
+ the call unchanged rather than being replaced by the inferred root."""
+ for name in (
+ "LLAMA_SERVER_PATH",
+ "UNSLOTH_LLAMA_CPP_PATH",
+ "UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH",
+ "STUDIO_HOME",
+ ):
+ monkeypatch.delenv(name, raising = False)
+ theirs = tmp_path / "theirs"
+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(theirs))
+ graded = _helper_namespace(tmp_path / "inferred")["_llama_runtime_to_grade"]()
+ assert graded == theirs / "llama.cpp"
+ assert os.environ["UNSLOTH_STUDIO_HOME"] == str(theirs)
+
+
+def test_a_deleted_llama_server_path_does_not_suppress_the_managed_verdict(tmp_path, monkeypatch):
+ """Codex 3958908320, P2. _scan_pinned treats an absent pin as no pin and falls through to
+ the managed tree, so a LLAMA_SERVER_PATH naming a file that has since been deleted still
+ loads the managed runtime. Suppressing the verdict on the bare string left a quarantined
+ managed runtime reporting Ready and failing at model load."""
+ active = _active_helper()
+ monkeypatch.setenv("LLAMA_SERVER_PATH", str(tmp_path / "gone" / "llama-server"))
+ assert active() is True
+
+ present = tmp_path / "llama-server"
+ present.write_text("", encoding = "utf-8")
+ monkeypatch.setenv("LLAMA_SERVER_PATH", str(present))
+ assert active() is False
+
+
+def test_a_dangling_symlink_pin_falls_through_like_any_absent_pin(tmp_path, monkeypatch):
+ """Codex 3959620579, P2, correcting this test's own earlier claim. ``_file_status`` asks
+ ``Path.is_file()``, which follows the link, so a pin whose target was deleted or
+ quarantined reads as "absent" there and the finder walks on to the managed tree. lexists
+ called that a pin and left the tree the backend really loads ungraded, so an incomplete
+ managed runtime reported Ready. A pin that resolves to a file, executable or not, does
+ stop the finder and is still not ours to grade."""
+ if os.name == "nt":
+ pytest.skip("POSIX symlink semantics")
+ active = _active_helper()
+
+ link = tmp_path / "pinned"
+ os.symlink(tmp_path / "never-existed", link)
+ assert os.path.lexists(link) and not link.is_file()
+ monkeypatch.setenv("LLAMA_SERVER_PATH", str(link))
+ assert active() is True
+
+ (tmp_path / "never-existed").write_text("", encoding = "utf-8")
+ assert active() is False
+
+
+def test_a_user_set_runtime_override_is_not_ours_to_repair(tmp_path, monkeypatch):
+ """Codex 3973660810, P1, superseding the grading half of 3959620607, P2.
+
+ 3959620607 was right that the finder reads UNSLOTH_LLAMA_CPP_PATH at step 1b and the
+ stored folder only at step 2, so an override holding a server is the tree the backend
+ opens, and reading the setting first graded the wrong one. Grading that tree was still
+ the wrong answer: setup.sh derives LLAMA_CPP_DIR from STUDIO_HOME and setup.ps1 from
+ Get-ManagedLlamaCppDir, and neither reads UNSLOTH_LLAMA_CPP_PATH, so the repair the
+ verdict asks for rebuilds a different tree, reports success, and the next launch asks
+ again. A repair that cannot reach the tree is worse than no verdict, which is why
+ LLAMA_SERVER_PATH is skipped for the same reason.
+
+ The ordering the earlier item won is still pinned below: the override is classified
+ before the stored folder is read, so which of the two answers None is not an accident.
+ """
+ active = _active_helper()
+ override = tmp_path / "relocated" / "llama.cpp"
+ server = (
+ override / "build" / "bin" / ("llama-server.exe" if os.name == "nt" else "llama-server")
+ )
+ server.parent.mkdir(parents = True)
+ server.write_text("x", encoding = "utf-8")
+ monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
+ monkeypatch.delenv("UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH", raising = False)
+ monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", str(override))
+ _stub_stored_selection(monkeypatch, "/home/someone/older-build")
+ assert active() is False
+
+ # With no stored folder either, the answer is still None rather than the managed
+ # tree: the finder stops at the override, so the managed tree is not what loads.
+ _stub_stored_selection(monkeypatch, None)
+ assert active() is False
+
+ # The desktop's own marker is the exception: the finder skips the override when it
+ # set it, so the tree behind it is the managed one and it is repairable again.
+ monkeypatch.setenv("UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH", "1")
+ assert active() is True
+ _stub_stored_selection(monkeypatch, "/home/someone/older-build")
+ assert active() is False
+
+
+def test_the_cli_s_own_inferred_override_is_not_mistaken_for_a_user_pin(tmp_path, monkeypatch):
+ """Codex 3962938538, P2. Under a custom STUDIO_HOME the CLI's
+ _ensure_studio_env_exported writes STUDIO_HOME/llama.cpp into
+ UNSLOTH_LLAMA_CPP_PATH and sets no marker, while the backend calls
+ mark_managed_llama_cpp_path on the same value before discovery and its finder
+ then walks past the override to the stored folder. Reading the marker alone
+ made this grade the managed tree as an explicit pin, so a damaged managed tree
+ blocked launch and was sent for repair though the backend would never open it."""
+ active = _active_helper()
+ studio_home = tmp_path / "custom-studio"
+ managed = studio_home / "llama.cpp"
+ server = managed / "build" / "bin" / ("llama-server.exe" if os.name == "nt" else "llama-server")
+ server.parent.mkdir(parents = True)
+ server.write_text("", encoding = "utf-8")
+ monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
+ monkeypatch.delenv("UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH", raising = False)
+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(studio_home))
+ monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", str(managed))
+ _stub_stored_selection(monkeypatch, "/home/someone/older-build")
+ assert active() is False, (
+ "the CLI's own inferred override names the managed tree, so the finder skips "
+ "it and the stored folder is what the backend opens"
+ )
+
+ # A pin somewhere else under the same studio home is a real user pin, and the
+ # classification still tells the two apart: it is not the managed tree, so the
+ # managed tree is not what the finder reaches and nothing here is graded. It is
+ # also not repairable, which is Codex 3973660810 and why the answer is False
+ # rather than the pinned tree.
+ elsewhere = tmp_path / "hand-built" / "llama.cpp"
+ pinned = (
+ elsewhere / "build" / "bin" / ("llama-server.exe" if os.name == "nt" else "llama-server")
+ )
+ pinned.parent.mkdir(parents = True)
+ pinned.write_text("x", encoding = "utf-8")
+ monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", str(elsewhere))
+ assert active() is False
+ # And the classification itself is unchanged: with the stored folder cleared, the
+ # managed-equal override is still graded and the pin elsewhere is still not.
+ _stub_stored_selection(monkeypatch, None)
+ assert active() is False
+ monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", str(managed))
+ assert active() is True
+
+
+def test_a_master_root_grades_the_runtime_beside_studio_not_the_one_under_it(tmp_path, monkeypatch):
+ """Codex 4063404685, P1. `UNSLOTH_HOME=<master>` puts llama.cpp BESIDE studio/, and
+ _ensure_studio_env_exported writes <master>/llama.cpp into UNSLOTH_LLAMA_CPP_PATH while
+ UNSLOTH_STUDIO_HOME stays <master>/studio. default_managed_llama_dir reads only the
+ studio home, so with the override out of the way it answered <master>/studio/llama.cpp:
+ the two did not match, the installer's own export graded as a user pin, and every
+ master-root install fell out of the health check this PR adds."""
+ active = _active_helper()
+ master = tmp_path / "portable"
+ managed = master / "llama.cpp"
+ server = managed / "build" / "bin" / ("llama-server.exe" if os.name == "nt" else "llama-server")
+ server.parent.mkdir(parents = True)
+ server.write_text("", encoding = "utf-8")
+ monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
+ monkeypatch.delenv("UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH", raising = False)
+ monkeypatch.setenv("UNSLOTH_HOME", str(master))
+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(master / "studio"))
+ monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", str(managed))
+ _stub_stored_selection(monkeypatch, None)
+ assert (
+ active() is True
+ ), "the exported <master>/llama.cpp is the tree this install owns, so it is graded"
+
+ # And the distinction survives: a pin somewhere else under the same master root is
+ # still somebody's own, not ours to repair.
+ elsewhere = tmp_path / "hand-built" / "llama.cpp"
+ pinned = (
+ elsewhere / "build" / "bin" / ("llama-server.exe" if os.name == "nt" else "llama-server")
+ )
+ pinned.parent.mkdir(parents = True)
+ pinned.write_text("x", encoding = "utf-8")
+ monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", str(elsewhere))
+ assert active() is False
+
+
+def test_the_master_root_rule_is_the_one_the_export_writes(tmp_path, monkeypatch):
+ """One rule, not two that can drift: the value graded has to be the value exported."""
+ namespace = _helper_namespace()
+ master_dir = namespace["_master_root_llama_dir"]
+ monkeypatch.delenv("UNSLOTH_HOME", raising = False)
+ assert master_dir() is None, "no master root means the studio home decides, as before"
+ master = tmp_path / "portable"
+ monkeypatch.setenv("UNSLOTH_HOME", str(master))
+ assert master_dir() == master.resolve() / "llama.cpp"
+ # Blank is not a root, the way every other read of this variable treats it.
+ monkeypatch.setenv("UNSLOTH_HOME", " ")
+ assert master_dir() is None
+
+
+def test_an_override_that_holds_no_server_does_not_outrank_the_stored_folder(tmp_path, monkeypatch):
+ """Codex 3960069962, P2. _scan_pinned finds no candidate under an empty or missing
+ UNSLOTH_LLAMA_CPP_PATH and walks on to the stored folder, so treating the override as
+ final graded a directory nobody loads, answered "not installed", and left the runtime the
+ backend really opens ungraded."""
+ active = _active_helper()
+ monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
+ monkeypatch.delenv("UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH", raising = False)
+ monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", str(tmp_path / "never-installed"))
+ _stub_stored_selection(monkeypatch, "/home/someone/older-build")
+ assert active() is False, "the finder walks past an empty override to the stored folder"
+
+ # With no stored folder either, the finder reaches the managed tree, so there is
+ # something to grade again.
+ _stub_stored_selection(monkeypatch, None)
+ assert active() is True
+
+
[email protected](os.name == "nt", reason = "POSIX ~name expansion")
+def test_an_override_naming_no_account_answers_instead_of_raising(tmp_path, monkeypatch):
+ """Codex 3962938521, P2. Path.expanduser raises RuntimeError for a "~name" that resolves
+ to no account, which an override left in a service unit or a .env after a rename does, and
+ this doctor's whole job is to answer. Every other reader of the variable goes through
+ expanded_user_path, which hands an unresolvable name back unchanged, so the override then
+ reaches the search as an ordinary path, finds nothing, and the documented order continues."""
+ active = _active_helper()
+ monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
+ monkeypatch.delenv("UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH", raising = False)
+ monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", "~no-such-account-9d3f/llama.cpp")
+ with pytest.raises(RuntimeError):
+ pathlib.Path("~no-such-account-9d3f/llama.cpp").expanduser()
+ _stub_stored_selection(monkeypatch, None)
+ assert active() is True, "an unexpandable override holds no server, so the search walks on"
+
+
+def _stub_stored_selection(monkeypatch, selected):
+ """A stored custom folder, without a settings database or the backend package.
+
+ The helper imports ``studio.backend.utils.llama_cpp_path_settings`` by name, so the
+ parents have to be in sys.modules too or the real packages are pulled in.
+ """
+ import types
+
+ for name in ("studio", "studio.backend", "studio.backend.utils"):
+ module = types.ModuleType(name)
+ module.__path__ = []
+ monkeypatch.setitem(sys.modules, name, module)
+ settings = types.ModuleType("studio.backend.utils.llama_cpp_path_settings")
+ settings.get_stored_custom_llama_cpp_path = lambda: selected
+ # The real layout contract, so the helper and the finder cannot disagree about
+ # which folders hold a server.
+ settings.llama_server_candidates = _real_llama_server_candidates
+ # The real reader, not Path.expanduser: leaving it off the stub made the
+ # helper's import fail, and the import is wrapped in a fallback, so every test
+ # here silently graded the except branch instead of the code it names.
+ settings.expanded_user_path = lambda value: pathlib.Path(os.path.expanduser(str(value)))
+ monkeypatch.setitem(sys.modules, "studio.backend.utils.llama_cpp_path_settings", settings)
+ # The helper asks install_llama_prebuilt for the managed root, and the stub
+ # package above hides the real module, so it is stubbed to the same rule.
+ prebuilt = types.ModuleType("studio.install_llama_prebuilt")
+ prebuilt.default_managed_llama_dir = _managed_dir_rule
+ monkeypatch.setitem(sys.modules, "studio.install_llama_prebuilt", prebuilt)
+
+
+def _managed_dir_rule():
+ """``default_managed_llama_dir``'s rule, retyped only because the stub package
+ above hides the real module: the override, else a custom studio home's
+ llama.cpp, else the legacy root. The studio-home arm is not decoration, since
+ that is the value the helper compares an override against."""
+ override = (os.environ.get("UNSLOTH_LLAMA_CPP_PATH") or "").strip()
+ if override:
+ return pathlib.Path(override).expanduser()
+ home = (os.environ.get("UNSLOTH_STUDIO_HOME") or os.environ.get("STUDIO_HOME") or "").strip()
+ if home:
+ root = pathlib.Path(home).expanduser()
+ if root != pathlib.Path.home() / ".unsloth" / "studio":
+ return root / "llama.cpp"
+ return pathlib.Path.home() / ".unsloth" / "llama.cpp"
+
+
+def _real_llama_server_candidates(directory):
+ """The shipped layouts, read off llama_cpp_path_settings rather than retyped."""
+ root = pathlib.Path(directory)
+ name = "llama-server.exe" if sys.platform == "win32" else "llama-server"
+ candidates = [root / name, root / "build" / "bin" / name]
+ if sys.platform == "win32":
+ candidates.append(root / "build" / "bin" / "Release" / name)
+ return tuple(candidates)
+
+
+def test_a_skipped_runtime_verdict_says_so_in_its_reason(monkeypatch):
+ """Codex 3959620616, P2, the CLI half. Null because another runtime is selected is not
+ null because nothing is installed: the first expires when the user clears the selection,
+ which the desktop's fingerprint does not watch. Naming it lets managed.rs decline to
+ cache it. Read off the source, so it holds without the venv."""
+ source = (
+ pathlib.Path(__file__).resolve().parents[3] / "unsloth_cli" / "commands" / "studio.py"
+ ).read_text(encoding = "utf-8")
+ body = source.split("def desktop_capabilities(", 1)[1].split("if json_output:", 1)[0]
+ assert 'payload["llama_runtime_reason"] = "llama_runtime_not_managed"' in body
+ # Codex 3973660789, P2: the third null. A probe that raised is a fact about one
+ # attempt and carries the damaged tree's own fingerprint, so it is not cacheable
+ # either, while "nothing installed" is a fact about the tree and still is.
+ assert 'payload["llama_runtime_reason"] = "llama_runtime_probe_failed"' in body
+ managed_rs = MANAGED_RS.read_text(encoding = "utf-8")
+ for reason in ("llama_runtime_not_managed", "llama_runtime_probe_failed"):
+ assert reason in managed_rs, "the desktop must know the reason the CLI emits"
+
+
+def test_the_stored_settings_lookup_can_reach_its_own_database_module(monkeypatch):
+ """Codex 3958908340, P2, reproduced before fixing: llama_cpp_path_settings imports
+ storage.studio_db as a top level package and swallows the failure, so without
+ studio/backend on sys.path the stored selection always read as absent and a user whose
+ custom folder is set in Studio would be sent to repair a tree their backend never opens.
+
+ The import is asserted through a fresh interpreter, since sys.modules in this one may
+ already carry a storage imported by an earlier test."""
+ import subprocess
+ import sys as _sys
+
+ root = pathlib.Path(__file__).resolve().parents[3]
+ without = subprocess.run(
+ [_sys.executable, "-c", "import storage.studio_db"],
+ cwd = root,
+ capture_output = True,
+ text = True,
+ )
+ assert without.returncode != 0, "storage must not already be importable from the repo root"
+ assert "No module named 'storage'" in without.stderr
+
+ monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
+ _active_helper()()
+ assert str(root / "studio" / "backend") in _sys.path, (
+ "the helper must put the backend on the path itself, or the settings lookup "
+ "silently answers None and the skip never happens"
+ )
+
+
[email protected](os.name == "nt", reason = "POSIX ~ expansion")
+def test_the_finder_expands_the_override_the_way_every_other_reader_does(tmp_path, monkeypatch):
+ """Codex 3960401528, P1. ``default_managed_llama_dir``, ``get_stored_custom_llama_cpp_path``
+ and the desktop's own pinning all expand UNSLOTH_LLAMA_CPP_PATH; the finder's
+ ``Path(custom_llama_cpp)`` was the one literal read. A "~/llama.cpp" written into a
+ service unit, a .env or the Windows environment dialog reaches the process unexpanded, so
+ the finder searched a folder named ~ beside the working directory, walked past it and
+ loaded a different runtime than the probe graded and the desktop fingerprinted.
+
+ Driven against the real finder rather than read off the source: importing it costs about
+ a third of a second."""
+ backend_dir = PACKAGE_ROOT / "studio" / "backend"
+ if str(backend_dir) not in sys.path:
+ sys.path.insert(0, str(backend_dir))
+ from core.inference.llama_cpp import LlamaCppBackend
+
+ home = tmp_path / "home"
+ build = home / "llama.cpp" / "build" / "bin"
+ build.mkdir(parents = True)
+ server = build / "llama-server"
+ server.write_text("", encoding = "utf-8")
+ os.chmod(server, 0o755)
+
+ monkeypatch.setenv("HOME", str(home))
+ monkeypatch.setenv("USERPROFILE", str(home))
+ monkeypatch.delenv("LLAMA_SERVER_PATH", raising = False)
+ monkeypatch.delenv("UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH", raising = False)
+ monkeypatch.setenv("UNSLOTH_LLAMA_CPP_PATH", "~/llama.cpp")
+ monkeypatch.chdir(tmp_path)
+ assert LlamaCppBackend._find_llama_server_binary() == str(server)
diff --git a/tests/studio/install/test_docker_studio_keep_cuda_prebuilt.py b/tests/studio/install/test_docker_studio_keep_cuda_prebuilt.py
index 6a223898492..adb016b5ca9 100644
--- a/tests/studio/install/test_docker_studio_keep_cuda_prebuilt.py
+++ b/tests/studio/install/test_docker_studio_keep_cuda_prebuilt.py
@@ -273,6 +273,7 @@ def _run_keep_decision(
requested_tag,
repo = FORK,
env = None,
+ damage = None,
):
install_dir = tmp_path / "llama.cpp"
(install_dir / "build" / "bin").mkdir(parents = True, exist_ok = True)
@@ -284,6 +285,25 @@ def _run_keep_decision(
for path in (install_dir / "llama-server", install_dir / "build" / "bin" / "llama-server"):
path.write_text("#!/bin/sh\nexit 0\n", encoding = "utf-8")
path.chmod(0o755)
+ runtime_dir = install_dir / "build" / "bin"
+ quantize = runtime_dir / "llama-quantize"
+ quantize.write_text("#!/bin/sh\nexit 0\n", encoding = "utf-8")
+ quantize.chmod(0o755)
+ for name in (
+ "libllama-common.so.0",
+ "libllama.so.0",
+ "libggml.so.0",
+ "libggml-base.so.0",
+ "libggml-cpu.so.0",
+ "libmtmd.so.0",
+ "libllama-server-impl.so",
+ "libllama-quantize-impl.so",
+ "libggml-cuda.so",
+ "libggml-hip.so",
+ ):
+ (runtime_dir / name).write_bytes(b"library")
+ if damage is not None:
+ (runtime_dir / damage).unlink()
script = tmp_path / "drive.sh"
script.write_text(_SH_HARNESS, encoding = "utf-8")
stub_dir = _stub_bin(tmp_path)
@@ -291,6 +311,7 @@ def _run_keep_decision(
run_env.pop("UNSLOTH_LLAMA_KEEP_PREBUILT", None)
run_env.pop("UNSLOTH_LLAMA_RELEASE_TAG", None)
run_env["PATH"] = f"{stub_dir}{os.pathsep}{run_env.get('PATH', '')}"
+ run_env["SCRIPT_DIR"] = str(MODULE_PATH.parent)
run_env.update(env or {})
proc = subprocess.run(
[
@@ -486,3 +507,22 @@ def test_dockerfile_studio_sets_the_knob_and_asserts_the_cuda_backend():
assert (
"exit 1" in text[assertion : assertion + 600]
), "a missing CUDA backend library must fail the build, not just print"
+
+
+@requires_bash
[email protected]("marker", [_BASE_IMAGE_MARKER, _INSTALLER_CUDA_MARKER])
[email protected]("damage", ["libggml-base.so.0", "llama-quantize"])
+def test_docker_keep_does_not_preserve_a_runtime_preflight_rejects(tmp_path, marker, damage):
+ assert (
+ _run_keep_decision(
+ tmp_path,
+ marker = marker,
+ server = True,
+ requested_tag = RELEASE_TAG,
+ env = ON,
+ damage = damage,
+ )
+ == "REPLACE"
+ )
+ health = INSTALL_LLAMA_PREBUILT.installed_runtime_health(tmp_path / "llama.cpp")
+ assert health is not None and not health[0]
diff --git a/tests/studio/install/test_install_llama_prebuilt_logic.py b/tests/studio/install/test_install_llama_prebuilt_logic.py
index 71d74a2c38b..9abdb0ad814 100644
--- a/tests/studio/install/test_install_llama_prebuilt_logic.py
+++ b/tests/studio/install/test_install_llama_prebuilt_logic.py
@@ -2334,13 +2334,29 @@ def test_install_prebuilt_falls_back_to_older_release_plan(
assert ensured_tags == ["b9001"]
-def write_linux_install_shape(install_dir: Path) -> None:
+def _write_entrypoints(install_dir: Path) -> None:
+ """The two entrypoints, executable, in both the places a caller looks.
+
+ Executable because a real extraction leaves them so, and because
+ existing_install_matches_choice now asks _entrypoint_is_runnable rather than
+ exists(): a tree it keeps but installed_runtime_health rejects is a repair loop.
+ """
runtime_dir = install_dir / "build" / "bin"
runtime_dir.mkdir(parents = True, exist_ok = True)
- (install_dir / "llama-server").write_text("#!/bin/sh\n", encoding = "utf-8")
- (install_dir / "llama-quantize").write_text("#!/bin/sh\n", encoding = "utf-8")
- (runtime_dir / "llama-server").write_text("#!/bin/sh\n", encoding = "utf-8")
- (runtime_dir / "llama-quantize").write_text("#!/bin/sh\n", encoding = "utf-8")
+ for directory in (install_dir, runtime_dir):
+ for name in ("llama-server", "llama-quantize"):
+ binary = directory / name
+ binary.write_text("#!/bin/sh\n", encoding = "utf-8")
+ binary.chmod(0o755)
+
+
+def write_linux_install_shape(install_dir: Path) -> None:
+ runtime_dir = install_dir / "build" / "bin"
+ _write_entrypoints(install_dir)
+ # Since the upstream impl split, llama-server and llama-quantize carry no entry
+ # code of their own and load these by DT_NEEDED, so a Linux payload owes them.
+ (runtime_dir / "libllama-server-impl.so").write_bytes(b"DLL")
+ (runtime_dir / "libllama-quantize-impl.so").write_bytes(b"DLL")
# libllama-common.so* (PR #5135) is a required runtime payload health group.
(runtime_dir / "libllama-common.so.0").write_bytes(b"DLL")
(runtime_dir / "libllama.so.0").write_bytes(b"DLL")
@@ -2369,6 +2385,7 @@ def write_windows_install_shape(
for name in (
"llama-common.dll",
"llama-server-impl.dll",
+ "llama-quantize-impl.dll",
"ggml.dll",
"ggml-base.dll",
"ggml-cpu-x64.dll",
@@ -2396,11 +2413,15 @@ def write_macos_install_shape(
include_libmtmd: bool = True,
) -> None:
runtime_dir = install_dir / "build" / "bin"
- runtime_dir.mkdir(parents = True, exist_ok = True)
- (install_dir / "llama-server").write_text("#!/bin/sh\n", encoding = "utf-8")
- (install_dir / "llama-quantize").write_text("#!/bin/sh\n", encoding = "utf-8")
- (runtime_dir / "llama-server").write_text("#!/bin/sh\n", encoding = "utf-8")
- (runtime_dir / "llama-quantize").write_text("#!/bin/sh\n", encoding = "utf-8")
+ _write_entrypoints(install_dir)
+ # The rest of the libraries a real macos-arm64 bundle ships. The toggles above
+ # stay the ones a caller flips, so an off toggle still leaves the tree short of
+ # one whole library rather than of the whole payload.
+ for name in ("libllama-common.0.dylib", "libggml-base.0.dylib", "libggml-cpu.0.dylib"):
+ (runtime_dir / name).write_bytes(b"DLL")
+ # The macOS half of the impl split, shipped unversioned; same reason as the Linux shape.
+ (runtime_dir / "libllama-server-impl.dylib").write_bytes(b"DLL")
+ (runtime_dir / "libllama-quantize-impl.dylib").write_bytes(b"DLL")
if include_libllama:
(runtime_dir / "libllama.0.dylib").write_bytes(b"DLL")
if include_libggml:
@@ -3351,6 +3372,55 @@ def test_install_prebuilt_skips_when_older_release_fallback_matches_existing_ins
assert call_log == ["b9002"]
[email protected](os.name == "nt", reason = "the root wrapper is written on POSIX only")
[email protected]("name", ["llama-server", "llama-quantize"])
+def test_a_damaged_root_entrypoint_stops_the_release_being_reused(tmp_path: Path, name: str):
+ """Codex 3973890098, P1. The keep decision graded only build/bin, so an online repair
+ took the shortcut, replaced nothing, and every later launch offered the same repair
+ again. Both read _damaged_entrypoint now.
+
+ Codex 4056336250, P2 narrowed what the LAUNCH side of it may reject: the resolver
+ returns the first usable candidate, so it walks past a root wrapper with no execute
+ bit and runs build/bin, and marking that tree stale repairs a runtime that works. The
+ keep decision is deliberately left strict, since replacing a rotten wrapper is exactly
+ what a reinstall is for, and that direction is safe: the launch verdict is never
+ stricter than the repair that answers it."""
+ install_dir = tmp_path / "llama.cpp"
+ install_dir.mkdir()
+ write_linux_install_shape(install_dir)
+ host = linux_host()
+ choice = asset_choice(name = "llama-b9001-bin-ubuntu-x64-good.tar.gz")
+ checksums = release_checksums((choice.name, choice.expected_sha256, PREBUILT))
+ write_metadata(install_dir, choice, checksums)
+ kwargs = dict(
+ llama_tag = "b9001",
+ release_tag = "release-1",
+ choice = choice,
+ approved_checksums = checksums,
+ )
+ assert existing_install_matches_choice(install_dir, host, **kwargs) is True
+ assert INSTALL_LLAMA_PREBUILT.installed_runtime_health(install_dir, host = host) == (True, "")
+
+ (install_dir / name).chmod(0o644)
+ # Walked past by the resolver, so the runtime still starts and launch says so.
+ assert INSTALL_LLAMA_PREBUILT.installed_runtime_health(install_dir, host = host) == (True, "")
+ assert (
+ existing_install_matches_choice(install_dir, host, **kwargs) is False
+ ), "a reinstall is what replaces a rotten root wrapper"
+
+ # Empty is the damage the resolver does NOT walk past: is_file() and the execute bit
+ # both survive a truncation, so discovery selects it and the exec dies on ENOEXEC.
+ (install_dir / name).write_text("", encoding = "utf-8")
+ (install_dir / name).chmod(0o755)
+ assert INSTALL_LLAMA_PREBUILT.installed_runtime_health(install_dir, host = host) == (
+ False,
+ "llama_runtime_binaries_missing",
+ )
+ assert (
+ existing_install_matches_choice(install_dir, host, **kwargs) is False
+ ), "a tree the probe rejects and this keeps is a repair that changes nothing"
+
+
def test_install_prebuilt_skips_same_release_fallback_attempt_when_installed(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
):
@@ -4800,6 +4870,12 @@ _SHARED_PAYLOAD = {
"libggml-base.so",
"libggml-cpu.so",
"libmtmd.so",
+ # The entry code llama-server and llama-quantize lost to the upstream impl
+ # split; they load these by DT_NEEDED. Owed by a published or upstream
+ # bundle only, and these markers carry no bNNNN tag, which the gate reads
+ # as "assume current".
+ "libllama-server-impl.so",
+ "libllama-quantize-impl.so",
],
"windows": ["llama.dll"],
}
@@ -4866,20 +4942,20 @@ def _complete_existing_llama_install(
path.write_text("#!/bin/sh\nexit 0\n" if ok else "", encoding = "utf-8")
os.chmod(path, 0o755 if executable else 0o644)
else:
- path.write_text("", encoding = "utf-8")
+ path.write_text("x", encoding = "utf-8")
os.chmod(path, 0o755 if executable else 0o644)
platform = "windows" if windows else "linux"
if payload:
for name in _SHARED_PAYLOAD[platform]:
- (runtime_dir / name).write_text("", encoding = "utf-8")
+ (runtime_dir / name).write_text("x", encoding = "utf-8")
for name in _BACKEND_PAYLOAD.get((platform, backend), ()):
- (runtime_dir / name).write_text("", encoding = "utf-8")
+ (runtime_dir / name).write_text("x", encoding = "utf-8")
if source == "published" and visual_server:
for name in _PUBLISHED_PAYLOAD[platform]:
- (runtime_dir / name).write_text("", encoding = "utf-8")
+ (runtime_dir / name).write_text("x", encoding = "utf-8")
if runtime_asset is not None and paired_runtime:
for name in ("cudart64_13.dll", "cublas64_13.dll", "cublasLt64_13.dll"):
- (runtime_dir / name).write_text("", encoding = "utf-8")
+ (runtime_dir / name).write_text("x", encoding = "utf-8")
return install_dir
@@ -5870,6 +5946,7 @@ def test_windows_prebuilt_health_requires_the_shared_runtime(install_kind: str):
"llama-common.dll",
"llama-server.exe",
"llama-server-impl.dll",
+ "llama-quantize-impl.dll",
"ggml.dll",
"ggml-base.dll",
"ggml-cpu*.dll",
@@ -5883,7 +5960,12 @@ def test_windows_source_build_does_not_require_the_shared_runtime():
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"):
+ for absent in (
+ "llama-common.dll",
+ "llama-server-impl.dll",
+ "llama-quantize-impl.dll",
+ "mtmd.dll",
+ ):
assert absent not in patterns
@@ -5903,7 +5985,12 @@ _PRE_SPLIT_WINDOWS_PAYLOAD = (
"ggml-cpu-haswell.dll",
"mtmd.dll",
)
-_POST_SPLIT_WINDOWS_PAYLOAD = _PRE_SPLIT_WINDOWS_PAYLOAD + ("llama-server-impl.dll",)
+# Both halves of the split, which is what a post-b9283 bundle ships: llama-quantize.exe
+# links against its own impl library exactly as llama-server.exe does against the server's.
+_POST_SPLIT_WINDOWS_PAYLOAD = _PRE_SPLIT_WINDOWS_PAYLOAD + (
+ "llama-server-impl.dll",
+ "llama-quantize-impl.dll",
+)
@pytest.mark.parametrize(
diff --git a/tests/studio/install/test_installed_runtime_health.py b/tests/studio/install/test_installed_runtime_health.py
new file mode 100644
index 00000000000..5375db6b922
--- /dev/null
+++ b/tests/studio/install/test_installed_runtime_health.py
@@ -0,0 +1,786 @@
+# 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 launch-time health probe for the managed llama.cpp runtime.
+
+Quarantine takes files out of a tree that is otherwise present and whose marker still
+says installed. Preflight decided staleness on the managed Python alone, so the desktop
+launched and the missing DLL surfaced at model load as an unrelated-looking error.
+``installed_runtime_health`` is what the capability payload answers with instead.
+
+The payload tables are covered by ``test_keep_install_backcompat_9979``; tested here is
+the composition around them: nothing installed is not a broken install, a missing runtime
+directory differs from a gutted one, and the probe pays for no GPU detection.
+"""
+
+import importlib.util
+import json
+import os
+import sys
+from pathlib import Path
+
+import pytest
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[3]
+MODULE_PATH = PACKAGE_ROOT / "studio" / "install_llama_prebuilt.py"
+SPEC = importlib.util.spec_from_file_location("studio_install_llama_prebuilt", MODULE_PATH)
+assert SPEC is not None and SPEC.loader is not None
+ILP = importlib.util.module_from_spec(SPEC)
+sys.modules[SPEC.name] = ILP
+SPEC.loader.exec_module(ILP)
+
+
+def _installed(tmp_path: Path, *, binaries: bool = False) -> Path:
+ """An install root with a marker and a runtime directory, and nothing else."""
+ root = tmp_path / "llama.cpp"
+ host = ILP.platform_only_host()
+ runtime_dir = ILP.install_runtime_dir(root, host)
+ runtime_dir.mkdir(parents = True)
+ (root / "UNSLOTH_PREBUILT_INFO.json").write_text(
+ json.dumps({"release_tag": "b10830-mix-d5c17a0", "tag": "b10830"}) + "\n",
+ encoding = "utf-8",
+ )
+ if binaries:
+ ext = ".exe" if host.is_windows else ""
+ for name in ("server", "quantize"):
+ binary = runtime_dir / f"llama-{name}{ext}"
+ binary.write_text("x", encoding = "utf-8")
+ os.chmod(binary, 0o755)
+ return root
+
+
+def test_no_marker_is_not_installed_rather_than_broken(tmp_path):
+ """None, not (False, ...): a user who never installed a runtime must not be repaired."""
+ (tmp_path / "llama.cpp").mkdir()
+ assert ILP.installed_runtime_health(tmp_path / "llama.cpp") is None
+ assert ILP.installed_runtime_health(tmp_path / "nothing-here") is None
+
+
+def test_a_marker_without_its_runtime_directory_is_broken(tmp_path):
+ """The whole tree can go, not only files inside it, leaving the marker orphaned."""
+ root = tmp_path / "llama.cpp"
+ root.mkdir()
+ (root / "UNSLOTH_PREBUILT_INFO.json").write_text("{}\n", encoding = "utf-8")
+ assert ILP.installed_runtime_health(root) == (False, "llama_runtime_dir_missing")
+
+
+def test_an_empty_runtime_directory_is_broken_not_healthy(tmp_path):
+ """The shape a quarantine leaves behind, which used to pass preflight."""
+ root = _installed(tmp_path)
+ assert ILP.installed_runtime_health(root) == (False, "llama_runtime_payload_incomplete")
+
+
+def test_the_verdict_is_delegated_to_the_payload_tables(tmp_path, monkeypatch):
+ """One payload decider: duplicating the required-file list would let the launch probe
+ and the keep-install path drift apart."""
+ root = _installed(tmp_path, binaries = True)
+ monkeypatch.setattr(ILP, "_kept_install_payload_is_healthy", lambda *_: True)
+ assert ILP.installed_runtime_health(root) == (True, "")
+
+
+def test_the_default_root_is_the_managed_install_dir(tmp_path, monkeypatch):
+ """The CLI calls this with no argument, so the UNSLOTH_LLAMA_CPP_PATH override has to
+ keep working through it."""
+ root = _installed(tmp_path)
+ monkeypatch.setattr(ILP, "default_managed_llama_dir", lambda: root)
+ assert ILP.installed_runtime_health() == (False, "llama_runtime_payload_incomplete")
+
+
+def test_platform_only_host_agrees_with_a_detected_host_on_the_platform_facts():
+ """It stands in for detect_host() in the payload checks, which read these booleans and
+ nothing else. Disagreement would grade the tree for the wrong operating system."""
+ cheap = ILP.platform_only_host()
+ detected = ILP.detect_host()
+ for field in ("system", "is_windows", "is_linux", "is_macos", "is_x86_64", "is_arm64"):
+ assert getattr(cheap, field) == getattr(detected, field), field
+ assert cheap.machine == detected.machine.lower()
+
+
+def test_platform_only_host_does_not_probe_for_gpus(monkeypatch):
+ """detect_host() shells out to nvidia-smi and costs over a second; a probe that only
+ looks for missing files must not."""
+
+ def refuse(*args, **kwargs):
+ raise AssertionError("platform_only_host must not run a subprocess")
+
+ monkeypatch.setattr(ILP.subprocess, "run", refuse)
+ monkeypatch.setattr(ILP.shutil, "which", refuse)
+ host = ILP.platform_only_host()
+ assert host.nvidia_smi is None
+ assert host.has_usable_nvidia is False
+ assert host.compute_caps == []
+
+
[email protected]("broken", [OSError("denied"), RuntimeError("boom")])
+def test_a_probe_that_raises_is_not_swallowed_here(tmp_path, monkeypatch, broken):
+ """The best-effort handling lives in the CLI command, which turns a failure into a null
+ capability. Swallowing it here too would hide a real payload-table bug."""
+ root = _installed(tmp_path)
+
+ def raise_it(*_):
+ raise broken
+
+ monkeypatch.setattr(ILP, "_kept_install_payload_is_healthy", raise_it)
+ with pytest.raises(type(broken)):
+ ILP.installed_runtime_health(root)
+
+
+def test_a_quarantined_llama_server_is_caught_even_with_a_complete_payload(tmp_path, monkeypatch):
+ """The payload groups name libraries only, so a missing server binary needs its own
+ check on Linux and macOS."""
+ root = _installed(tmp_path, binaries = True)
+ monkeypatch.setattr(ILP, "_kept_install_payload_is_healthy", lambda *_: True)
+ host = ILP.platform_only_host()
+ ext = ".exe" if host.is_windows else ""
+ (ILP.install_runtime_dir(root, host) / f"llama-server{ext}").unlink()
+ assert ILP.installed_runtime_health(root) == (False, "llama_runtime_binaries_missing")
+
+
+def test_llama_quantize_is_required_because_the_setup_scripts_require_it(tmp_path, monkeypatch):
+ """_existing_install_runs demands both, so demanding both here keeps this call no
+ stricter than the repair that answers it."""
+ root = _installed(tmp_path, binaries = True)
+ monkeypatch.setattr(ILP, "_kept_install_payload_is_healthy", lambda *_: True)
+ host = ILP.platform_only_host()
+ ext = ".exe" if host.is_windows else ""
+ (ILP.install_runtime_dir(root, host) / f"llama-quantize{ext}").unlink()
+ assert ILP.installed_runtime_health(root) == (False, "llama_runtime_binaries_missing")
+
+
+def test_an_explicit_host_overrides_the_detected_platform(tmp_path):
+ """The simulation matrices grade a tree for a platform this machine is not."""
+ root = tmp_path / "llama.cpp"
+ (root / "build" / "bin" / "Release").mkdir(parents = True)
+ (root / "UNSLOTH_PREBUILT_INFO.json").write_text("{}\n", encoding = "utf-8")
+ windows = ILP.detect_host()
+ windows = type(windows)(
+ **{
+ **windows.__dict__,
+ "system": "Windows",
+ "is_windows": True,
+ "is_linux": False,
+ "is_macos": False,
+ }
+ )
+ # Windows looks in build/bin/Release, which exists; a Linux host looks in build/bin.
+ assert ILP.installed_runtime_health(root, host = windows)[1] != "llama_runtime_dir_missing"
+
+
+def test_a_marker_that_exists_but_does_not_parse_is_still_graded(tmp_path):
+ """An absent marker is a runtime nobody installed; a present but unreadable one is a real
+ tree whose write was interrupted. Short-circuiting the second to None left preflight Ready
+ with a library missing, the exact failure this probe catches. The keep path grades such a
+ marker as an unknown backend anyway, so grading it here stays no stricter."""
+ root = _installed(tmp_path, binaries = True)
+ (root / "UNSLOTH_PREBUILT_INFO.json").write_text('{"release_tag": "b108', encoding = "utf-8")
+ assert ILP.load_prebuilt_metadata(root) is None
+ # The payload is empty, so the tree is broken and must be offered for repair.
+ assert ILP.installed_runtime_health(root) == (False, "llama_runtime_payload_incomplete")
+
+
+def test_an_unparsable_marker_over_a_complete_tree_is_still_healthy(tmp_path, monkeypatch):
+ """The other half, which keeps the loop shut: _existing_install_runs keeps a tree with an
+ unreadable marker, so calling it broken would repair, keep, and repair again every launch."""
+ root = _installed(tmp_path, binaries = True)
+ (root / "UNSLOTH_PREBUILT_INFO.json").write_text("not json", encoding = "utf-8")
+ monkeypatch.setattr(ILP, "_kept_install_payload_is_healthy", lambda *_: True)
+ assert ILP.installed_runtime_health(root) == (True, "")
+
+
+def test_an_absent_marker_is_still_not_installed(tmp_path):
+ """The distinction the fix turns on, asserted directly."""
+ root = _installed(tmp_path, binaries = True)
+ (root / "UNSLOTH_PREBUILT_INFO.json").unlink()
+ assert ILP.installed_runtime_health(root) is None
+
+
+def _windows_host():
+ """A Windows HostInfo, so these run on the CI machines we actually have."""
+ host = ILP.platform_only_host()
+ return type(host)(
+ **{
+ **host.__dict__,
+ "system": "Windows",
+ "machine": "amd64",
+ "is_windows": True,
+ "is_linux": False,
+ "is_macos": False,
+ "is_x86_64": True,
+ "is_arm64": False,
+ }
+ )
+
+
+"""What a published Windows bundle ships, checked against
+app-b10798-mix-659e406-windows-x64-cpu.zip."""
+_PUBLISHED_WINDOWS_PAYLOAD = (
+ "llama.dll",
+ "llama-common.dll",
+ "llama-server.exe",
+ "llama-server-impl.dll",
+ "llama-quantize.exe",
+ "llama-quantize-impl.dll",
+ "ggml.dll",
+ "ggml-base.dll",
+ "ggml-cpu-haswell.dll",
+ "mtmd.dll",
+)
+
+
+def _windows_tree(tmp_path: Path, names, *, marker: str) -> Path:
+ root = tmp_path / "llama.cpp"
+ host = _windows_host()
+ runtime_dir = ILP.install_runtime_dir(root, host)
+ runtime_dir.mkdir(parents = True)
+ for name in names:
+ binary = runtime_dir / name
+ binary.write_text("x", encoding = "utf-8")
+ os.chmod(binary, 0o755)
+ (root / "UNSLOTH_PREBUILT_INFO.json").write_text(marker, encoding = "utf-8")
+ return root
+
+
+def test_an_unparseable_marker_over_a_prebuilt_tree_still_owes_the_shared_payload(tmp_path):
+ """Codex 3962938529, P2. An unreadable marker names no source, and the source-gated
+ groups were dropped with it, so on Windows llama.dll stood in for the whole payload: an
+ interrupted marker plus a quarantined ggml-base.dll answered healthy and the runtime
+ launched into the loader error this probe exists to pre-empt. The source is read off the
+ tree instead, from a name only a published bundle ships."""
+ host = _windows_host()
+ root = _windows_tree(tmp_path, _PUBLISHED_WINDOWS_PAYLOAD, marker = '{"release_tag": "b108')
+ assert ILP.load_prebuilt_metadata(root) is None
+ assert ILP.installed_runtime_health(root, host = host) == (True, "")
+
+ quarantined = ILP.install_runtime_dir(root, host) / "ggml-base.dll"
+ quarantined.rename(quarantined.with_suffix(".dll.quarantine"))
+ assert ILP.installed_runtime_health(root, host = host) == (
+ False,
+ "llama_runtime_payload_incomplete",
+ )
+
+
+def test_an_unparseable_marker_over_a_source_build_stays_lenient(tmp_path):
+ """The other half of the same rule, and the reason it reads the tree rather than assuming
+ published: setup.ps1 links statically and ships none of those names, so requiring them
+ would fail health on a tree _existing_install_runs keeps, and the repair would run every
+ launch with nothing to change."""
+ host = _windows_host()
+ root = _windows_tree(
+ tmp_path,
+ ("llama.dll", "llama-server.exe", "llama-quantize.exe"),
+ marker = "not json",
+ )
+ assert ILP.installed_runtime_health(root, host = host) == (True, "")
+ assert ILP._tree_looks_prebuilt(root, host) is False
+
+
+def test_the_windows_quantize_implementation_is_required_alongside_the_server_one(tmp_path):
+ """Codex 3962938556, P2. The upstream split gives llama-quantize.exe its own -impl library
+ exactly as it gives llama-server.exe one, and a b10798 bundle ships both, so requiring only
+ the server's left a quarantined llama-quantize-impl.dll reading as healthy while
+ quantization could not start."""
+ host = _windows_host()
+ root = _windows_tree(
+ tmp_path,
+ _PUBLISHED_WINDOWS_PAYLOAD,
+ marker = json.dumps({"source": "published", "tag": "b10798"}),
+ )
+ assert ILP.installed_runtime_health(root, host = host) == (True, "")
+ (ILP.install_runtime_dir(root, host) / "llama-quantize-impl.dll").unlink()
+ assert ILP.installed_runtime_health(root, host = host) == (
+ False,
+ "llama_runtime_payload_incomplete",
+ )
+
+
+def test_the_hip_backend_module_is_required_by_name_not_by_anything_hip_shaped(tmp_path):
+ """Codex 3962938550, P1. A real ROCm bundle carries amdhip64_7.dll, hipblas.dll and
+ libhipblaslt.dll beside ggml-hip.dll, all four matching a "*hip*.dll" group, so
+ quarantining the one module ggml loads left the group satisfied by three libraries that
+ cannot stand in for it. Names read off
+ app-b10798-mix-659e406-windows-x64-rocm-gfx1150.zip."""
+ groups = ILP.runtime_payload_health_groups(
+ "windows-rocm", source_label = "published", tag = "b10798"
+ )
+ hip_groups = [group for group in groups if any("hip" in name for name in group)]
+ assert hip_groups == [["ggml-hip*.dll"]]
+
+ host = _windows_host()
+ root = _windows_tree(
+ tmp_path,
+ _PUBLISHED_WINDOWS_PAYLOAD
+ + ("amdhip64_7.dll", "hipblas.dll", "libhipblaslt.dll", "ggml-hip.dll"),
+ marker = json.dumps({"source": "published", "tag": "b10798", "install_kind": "windows-rocm"}),
+ )
+ runtime_dir = ILP.install_runtime_dir(root, host)
+ assert ILP._runtime_payload_has(root, host, groups) is True
+ (runtime_dir / "ggml-hip.dll").unlink()
+ assert (
+ ILP._runtime_payload_has(root, host, groups) is False
+ ), "the three remaining hip-named libraries must not stand in for the ggml backend"
+
+
+def test_a_dangling_library_symlink_does_not_count_as_present(tmp_path):
+ """The tar payloads ship versioned chains (libggml.so -> libggml.so.0 -> libggml.so.0.9.8)
+ and Path.glob does not follow links, so quarantining the versioned target left every
+ pattern satisfied by links the loader cannot open. Fixed in _runtime_payload_has, which
+ this probe and the keep decision share, so the two tighten together.
+
+ All three rungs, which is what a release ships and what the sentence above already said;
+ this used to build only the outer two. The middle rung is the SONAME, the name a
+ DT_NEEDED entry records, and _payload_match_is_loadable now needs to see whether the
+ family has one before it can say what the versionless name means.
+ """
+ if os.name == "nt":
+ pytest.skip("the shipped Windows payload has no symlink chains")
+ root = _installed(tmp_path, binaries = True)
+ host = ILP.platform_only_host()
+ runtime_dir = ILP.install_runtime_dir(root, host)
+ groups = ILP.runtime_payload_health_groups("linux-cpu")
+ real = []
+ for group in groups:
+ stem = group[0].replace("*", "")
+ target = runtime_dir / f"{stem}.0.9.8"
+ target.write_text("x", encoding = "utf-8")
+ soname = runtime_dir / f"{stem}.0"
+ os.symlink(target.name, soname)
+ os.symlink(soname.name, runtime_dir / stem)
+ real.append(target)
+ assert ILP._runtime_payload_has(root, host, groups) is True
+
+ # Quarantine takes the versioned target and leaves both links behind.
+ real[0].unlink()
+ assert (runtime_dir / groups[0][0].replace("*", "")).is_symlink()
+ assert ILP._runtime_payload_has(root, host, groups) is False
+
+
+def test_a_directory_matching_a_payload_pattern_is_not_a_library(tmp_path):
+ """The same is_file() guard rejects a directory that happens to match, which a bare glob
+ would have accepted."""
+ root = _installed(tmp_path, binaries = True)
+ host = ILP.platform_only_host()
+ groups = [["libllama.so*"]]
+ (ILP.install_runtime_dir(root, host) / "libllama.so.0").mkdir()
+ assert ILP._runtime_payload_has(root, host, groups) is False
+
+
[email protected]("suffix", [".vir", ".quarantined", "_infected"])
+def test_a_library_renamed_in_place_no_longer_satisfies_its_group(tmp_path, suffix):
+ """Quarantine that renames rather than deletes. Every Linux group ends in ``.so*``, so
+ the renamed victim kept matching its own pattern: on a real b10840 install, renaming
+ libggml-base.so.0 to libggml-base.so.0.vir left this answering (True, "") while
+ llama-server exited with "cannot open shared object file: libggml-base.so.0" and
+ _existing_install_runs answered False. Preflight then reported Ready and the launch
+ failed at model load with no repair offered, which is the whole point of the probe."""
+ if os.name == "nt":
+ pytest.skip("the Windows groups name the extension, so a suffix misses them already")
+ root = _installed(tmp_path, binaries = True)
+ host = ILP.platform_only_host()
+ runtime_dir = ILP.install_runtime_dir(root, host)
+ groups = ILP.runtime_payload_health_groups("linux-cpu")
+ for group in groups:
+ (runtime_dir / f"{group[0].replace('*', '')}.0").write_text("x", encoding = "utf-8")
+ assert ILP._runtime_payload_has(root, host, groups) is True
+
+ soname = runtime_dir / f"{groups[0][0].replace('*', '')}.0"
+ soname.rename(soname.with_name(soname.name + suffix))
+ assert ILP._runtime_payload_has(root, host, groups) is False
+
+
+def test_a_renamed_library_does_not_stand_in_for_its_own_soname(tmp_path):
+ """The end-to-end verdict, not only the group test, and the entrypoints stay untouched so
+ the reason has to come from the payload rather than from the binaries check."""
+ if os.name == "nt":
+ pytest.skip("the Windows groups name the extension, so a suffix misses them already")
+ root = _installed(tmp_path, binaries = True)
+ host = ILP.platform_only_host()
+ runtime_dir = ILP.install_runtime_dir(root, host)
+ published = ILP.runtime_payload_health_groups(
+ "linux-cpu", source_label = "published", tag = "b10830"
+ )
+ for group in published:
+ (runtime_dir / f"{group[0].replace('*', '')}.0").write_text("x", encoding = "utf-8")
+ assert ILP.installed_runtime_health(root, host = host) == (True, "")
+
+ victim = runtime_dir / "libggml-base.so.0"
+ victim.rename(runtime_dir / "libggml-base.so.0.vir")
+ assert ILP.installed_runtime_health(root, host = host) == (
+ False,
+ "llama_runtime_payload_incomplete",
+ )
+
+
+def test_an_entrypoint_is_still_a_file_the_loader_would_start(tmp_path):
+ """The rejection is keyed on ``.so`` in the name, so llama-server, llama-server.exe and
+ every .dll keep passing: reading them as unparseable library names would fail health on
+ a complete tree, which is the repair loop installed_runtime_health forbids."""
+ for name in ("llama-server", "llama-server.exe", "ggml-base.dll", "libggml.0.dylib"):
+ entry = tmp_path / name
+ entry.write_text("x", encoding = "utf-8")
+ assert ILP._payload_match_is_loadable(entry) is True, name
+
+
[email protected]("name", ["llama-server", "libggml-base.so.0", "ggml-base.dll"])
+def test_a_zero_length_file_is_not_a_payload_or_an_entrypoint(tmp_path, name):
+ """Codex 3973660774, P1. An interrupted extraction, and security software that empties
+ a file rather than taking it, both leave the directory entry, so is_file() and the
+ execute bit stayed true. The fingerprint sees the length change and re-probes, and the
+ probe then answered healthy, so the repair the re-probe existed to trigger was never
+ offered. _existing_install_runs rejects the same tree on ENOEXEC or a loader failure."""
+ empty = tmp_path / name
+ empty.write_text("", encoding = "utf-8")
+ assert ILP._payload_match_is_loadable(empty) is False
+ assert ILP._entrypoint_is_runnable(empty, ILP.platform_only_host()) is False
+
+ empty.write_text("x", encoding = "utf-8")
+ assert ILP._payload_match_is_loadable(empty) is True
+
+
+def test_a_truncated_llama_server_is_broken_not_healthy(tmp_path):
+ """The end-to-end verdict for the same damage, with the payload left complete so the
+ reason has to come from the entrypoint check."""
+ if os.name == "nt":
+ host = _windows_host()
+ root = _windows_tree(
+ tmp_path,
+ _PUBLISHED_WINDOWS_PAYLOAD,
+ marker = json.dumps({"source": "published", "tag": "b10830"}),
+ )
+ else:
+ host = _macos_host()
+ root = _macos_tree(tmp_path)
+ assert ILP.installed_runtime_health(root, host = host) == (True, "")
+
+ ext = ".exe" if host.is_windows else ""
+ (ILP.install_runtime_dir(root, host) / f"llama-server{ext}").write_text("", encoding = "utf-8")
+ assert ILP.installed_runtime_health(root, host = host) == (
+ False,
+ "llama_runtime_binaries_missing",
+ )
+
+
+def test_a_legacy_windows_cuda_marker_still_owes_the_paired_runtime(tmp_path):
+ """Codex 3973660801, P2. Markers written before ``runtime_asset`` existed name no paired
+ archive, so the cudart trio was dropped from the table and losing one member read as
+ healthy while llama-server.exe died in the loader, with no repair offered and the marker
+ never backfilled. The three arrive and go together, so one of them still being there is
+ what says this install was paired; a machine on a system CUDA toolkit has none of them
+ and is asked for none."""
+ host = _windows_host()
+ trio = ("cudart64_12.dll", "cublas64_12.dll", "cublasLt64_12.dll")
+ marker = json.dumps({"source": "published", "tag": "b10830", "backend": "cuda"})
+ root = _windows_tree(
+ tmp_path, _PUBLISHED_WINDOWS_PAYLOAD + ("ggml-cuda.dll",) + trio, marker = marker
+ )
+ assert ILP._kept_install_payload_is_healthy(root, host) is True
+
+ (ILP.install_runtime_dir(root, host) / "cublasLt64_12.dll").unlink()
+ assert (
+ ILP._kept_install_payload_is_healthy(root, host) is False
+ ), "the two remaining members must not stand in for the third"
+
+ # None of them present is the system-CUDA install, which owes nothing.
+ bare = _windows_tree(
+ tmp_path / "bare", _PUBLISHED_WINDOWS_PAYLOAD + ("ggml-cuda.dll",), marker = marker
+ )
+ assert ILP._kept_install_payload_is_healthy(bare, host) is True
+
+
+def _macos_host():
+ host = ILP.platform_only_host()
+ return type(host)(
+ **{
+ **host.__dict__,
+ "system": "Darwin",
+ "is_windows": False,
+ "is_linux": False,
+ "is_macos": True,
+ "machine": "arm64",
+ "is_x86_64": False,
+ "is_arm64": True,
+ "macos_version": (15, 5),
+ }
+ )
+
+
+def _macos_payload(runtime_dir: Path) -> None:
+ """The dylib set a real macos-arm64 bundle ships, chains and all.
+
+ Taken from llama-b10840-mix-d5c17a0-bin-macos-arm64.tar.gz rather than invented: each
+ library is libX.dylib -> libX.0.dylib -> libX.<version>.dylib, and the accelerator and
+ transport backends sit beside the core ones matching the same broad prefix.
+ """
+ for stem, version in (
+ ("libllama-common", "0.4.0"),
+ ("libllama", "0.4.0"),
+ ("libmtmd", "0.4.0"),
+ ("libggml", "0.23.0"),
+ ("libggml-base", "0.23.0"),
+ ("libggml-cpu", "0.23.0"),
+ ("libggml-metal", "0.23.0"),
+ ("libggml-blas", "0.23.0"),
+ ("libggml-rpc", "0.23.0"),
+ ):
+ (runtime_dir / f"{stem}.{version}.dylib").write_text("x", encoding = "utf-8")
+ os.symlink(f"{stem}.{version}.dylib", runtime_dir / f"{stem}.0.dylib")
+ os.symlink(f"{stem}.0.dylib", runtime_dir / f"{stem}.dylib")
+ # The entrypoint impl split, which the same bundle ships UNVERSIONED: plain files, no
+ # libX.0 chain. Listing it was incomplete before, not the bundle.
+ for stem in ("libllama-server-impl", "libllama-quantize-impl"):
+ (runtime_dir / f"{stem}.dylib").write_text("x", encoding = "utf-8")
+
+
+def _macos_tree(tmp_path: Path) -> Path:
+ root = tmp_path / "llama.cpp"
+ runtime_dir = root / "build" / "bin"
+ runtime_dir.mkdir(parents = True)
+ (root / "UNSLOTH_PREBUILT_INFO.json").write_text(
+ json.dumps({"tag": "b10840", "release_tag": "b10840-mix-d5c17a0", "source": "published"}),
+ encoding = "utf-8",
+ )
+ for name in ("server", "quantize"):
+ binary = runtime_dir / f"llama-{name}"
+ binary.write_text("x", encoding = "utf-8")
+ # An installed entrypoint is executable, and the probe now asks for that
+ # rather than for mere presence, the way _existing_install_runs does.
+ os.chmod(binary, 0o755)
+ _macos_payload(runtime_dir)
+ return root
+
+
[email protected](os.name == "nt", reason = "the fixture needs POSIX symlinks")
+def test_a_complete_macos_payload_is_healthy(tmp_path):
+ assert ILP.installed_runtime_health(_macos_tree(tmp_path), host = _macos_host()) == (True, "")
+
+
[email protected](os.name == "nt", reason = "the fixture needs POSIX symlinks")
+ "stem",
+ ["libllama-common", "libllama", "libggml", "libggml-base", "libggml-cpu", "libmtmd"],
+)
+def test_each_essential_macos_dylib_is_required_on_its_own(tmp_path, stem):
+ """Codex 3958908349, P1. The groups used to be three broad alternatives, so
+ libggml*.dylib stayed satisfied by libggml-base, libggml-blas, libggml-cpu, libggml-metal
+ and libggml-rpc after the one the loader needs was quarantined, and the tree reported
+ healthy while llama-server died in dyld. The dot in each pattern is what keeps it off its
+ siblings."""
+ root = _macos_tree(tmp_path)
+ runtime_dir = root / "build" / "bin"
+ for path in [p for p in runtime_dir.iterdir() if p.name.split(".")[0] == stem]:
+ path.unlink()
+ assert ILP.installed_runtime_health(root, host = _macos_host()) == (
+ False,
+ "llama_runtime_payload_incomplete",
+ )
+
+
[email protected](os.name == "nt", reason = "the fixture needs POSIX symlinks")
+def test_losing_only_the_macos_chain_target_is_caught(tmp_path):
+ """The links survive quarantine of the versioned file they point at, and a name-only
+ match would still satisfy the pattern."""
+ root = _macos_tree(tmp_path)
+ (root / "build" / "bin" / "libggml.0.23.0.dylib").unlink()
+ assert ILP.installed_runtime_health(root, host = _macos_host()) == (
+ False,
+ "llama_runtime_payload_incomplete",
+ )
+
+
[email protected](os.name == "nt", reason = "the fixture needs POSIX symlinks")
+def test_the_macos_accelerator_backends_are_not_required(tmp_path):
+ """Over-strictness is the repair-loop direction. metal, blas and rpc are the accelerator
+ and transport backends, the way libggml-cuda is on Linux, so demanding one a bundle does
+ not carry would reinstall every install that lacks it."""
+ root = _macos_tree(tmp_path)
+ runtime_dir = root / "build" / "bin"
+ for path in [
+ p
+ for p in runtime_dir.iterdir()
+ if p.name.startswith(("libggml-metal", "libggml-blas", "libggml-rpc"))
+ ]:
+ path.unlink()
+ assert ILP.installed_runtime_health(root, host = _macos_host()) == (True, "")
+
+
[email protected](os.name == "nt", reason = "the fixture needs POSIX symlinks")
+def test_losing_the_macos_install_name_link_is_caught(tmp_path):
+ """Codex 3959620556, P1. The middle link of the chain is the one dyld asks for, and it
+ is the one a name-only match hides: llama-server's LC_LOAD_DYLIB entry is
+ ``@rpath/libggml.0.dylib`` (read out of the shipped macos-arm64 bundle, and matching the
+ LC_ID_DYLIB recorded in libggml.0.23.0.dylib itself), so with it quarantined the process
+ dies in dyld while ``libggml.*.dylib`` is still satisfied by the terminal file. The
+ version-depth rule that already covers ``libfoo.so.0`` beside ``libfoo.so.0.0.10360``
+ covers this too."""
+ root = _macos_tree(tmp_path)
+ runtime_dir = root / "build" / "bin"
+ (runtime_dir / "libggml.0.dylib").unlink()
+ # The terminal file is still there and still a real file, which is what made this
+ # read as healthy.
+ assert (runtime_dir / "libggml.0.23.0.dylib").is_file()
+ assert ILP.installed_runtime_health(root, host = _macos_host()) == (
+ False,
+ "llama_runtime_payload_incomplete",
+ )
+
+
[email protected](os.name == "nt", reason = "the fixture needs POSIX symlinks")
+def test_a_bare_versionless_macos_dylib_still_satisfies_its_group(tmp_path):
+ """The other direction, so the rule above cannot become a reinstall loop: a bundle that
+ ships libfoo.dylib with no chain at all is a name the loader can resolve and must stay
+ healthy."""
+ root = _macos_tree(tmp_path)
+ runtime_dir = root / "build" / "bin"
+ for path in [p for p in runtime_dir.iterdir() if p.name.split(".")[0] == "libggml"]:
+ path.unlink()
+ (runtime_dir / "libggml.dylib").write_text("x", encoding = "utf-8")
+ assert ILP.installed_runtime_health(root, host = _macos_host()) == (True, "")
+
+
[email protected](os.name == "nt", reason = "POSIX permission bits")
[email protected]("name", ["server", "quantize"])
+def test_a_runtime_binary_stripped_of_its_execute_bit_is_broken(tmp_path, name):
+ """Codex 3959620570, P2. Extraction damage or security software can clear the bit without
+ deleting the file. ``_find_llama_server_binary`` then classifies it non-executable and
+ refuses to fall back to another runtime, and ``_existing_install_runs`` rejects the tree
+ on the same ``os.access(X_OK)``, so an ``exists()`` check here was the only thing left
+ calling it Ready."""
+ root = _macos_tree(tmp_path)
+ binary = root / "build" / "bin" / f"llama-{name}"
+ os.chmod(binary, 0o755)
+ assert ILP.installed_runtime_health(root, host = _macos_host()) == (True, "")
+ os.chmod(binary, 0o644)
+ assert ILP.installed_runtime_health(root, host = _macos_host()) == (
+ False,
+ "llama_runtime_binaries_missing",
+ )
+
+
[email protected](os.name == "nt", reason = "the fixture needs POSIX symlinks")
[email protected]("name", ["server", "quantize"])
+def test_a_directory_where_a_runtime_entrypoint_belongs_is_broken(tmp_path, name):
+ """Codex 3960401513, P2. A directory is searchable, so os.access(X_OK) answers true for
+ one and exists() does too, while ``_file_status`` in the finder asks ``is_file()`` and
+ rejects the tree. Failed extraction and filesystem corruption both leave exactly that,
+ and it read as a healthy install.
+
+ ``_existing_install_runs`` asks the same way now, through the same helper: a tree this
+ rejects but that one keeps would be repaired, left unchanged and rejected again next
+ launch."""
+ root = _macos_tree(tmp_path)
+ binary = root / "build" / "bin" / f"llama-{name}"
+ binary.unlink()
+ binary.mkdir()
+ assert os.access(binary, os.X_OK) and binary.exists()
+ assert ILP.installed_runtime_health(root, host = _macos_host()) == (
+ False,
+ "llama_runtime_binaries_missing",
+ )
+ assert not ILP._entrypoint_is_runnable(binary, _macos_host())
+
+
[email protected](os.name == "nt", reason = "the root wrapper is written on POSIX only")
[email protected]("name", ["server", "quantize"])
+def test_an_empty_root_entrypoint_is_not_saved_by_a_healthy_build_bin(tmp_path, name):
+ """``create_exec_entrypoint`` writes a real wrapper at the install root when it cannot
+ make a symlink, and the resolver reaches that root copy before build/bin, so it can rot
+ on its own. Empty is the rot that still gets selected: ``_usable_binary`` asks is_file()
+ and the execute bit, both of which a truncated wrapper keeps, and the exec then dies on
+ ENOEXEC."""
+ root = _macos_tree(tmp_path)
+ wrapper = root / f"llama-{name}"
+ wrapper.write_text("#!/bin/sh\n", encoding = "utf-8")
+ os.chmod(wrapper, 0o755)
+ assert ILP.installed_runtime_health(root, host = _macos_host()) == (True, "")
+
+ wrapper.write_text("", encoding = "utf-8")
+ os.chmod(wrapper, 0o755)
+ assert ILP.installed_runtime_health(root, host = _macos_host()) == (
+ False,
+ "llama_runtime_binaries_missing",
+ )
+
+
[email protected](os.name == "nt", reason = "the execute bit is a POSIX test")
[email protected]("name", ["server", "quantize"])
+def test_a_root_entrypoint_the_resolver_walks_past_is_not_damage(tmp_path, name):
+ """A root wrapper without its execute bit is skipped, not selected, so the tree works.
+
+ ``resolve_llama_server_binary`` returns the first candidate ``_usable_binary`` accepts,
+ and that asks ``os.access(X_OK)`` off Windows, so a 0644 wrapper is walked past and
+ build/bin runs (``test_runtime_skips_non_executable_root_entrypoint_for_valid_build_layout``
+ in studio/backend/tests/test_llama_cpp_path_settings.py pins the same thing from the other
+ side). Grading it broken sent a working runtime through a repair, and where repair is
+ unavailable it blocked the launch outright.
+ """
+ root = _macos_tree(tmp_path)
+ wrapper = root / f"llama-{name}"
+ wrapper.write_text("#!/bin/sh\n", encoding = "utf-8")
+ os.chmod(wrapper, 0o644)
+ assert ILP.installed_runtime_health(root, host = _macos_host()) == (True, "")
+ # A directory of that name is the same shape to the resolver: is_file() is false.
+ wrapper.unlink()
+ wrapper.mkdir()
+ assert ILP.installed_runtime_health(root, host = _macos_host()) == (True, "")
+ wrapper.rmdir()
+ # The keep decision is deliberately not relaxed with it: replacing a rotten wrapper
+ # is the installer's business, and only the launch verdict must stay no stricter.
+ wrapper.write_text("#!/bin/sh\n", encoding = "utf-8")
+ os.chmod(wrapper, 0o644)
+ assert ILP._damaged_entrypoint(root, _macos_host()) == wrapper
+ assert ILP._damaged_entrypoint(root, _macos_host(), selected_root_only = True) is None
+
+
+def test_an_empty_windows_root_entrypoint_is_still_damage(tmp_path):
+ """Windows has no execute bit, so ``_usable_binary`` there is is_file() alone and an
+ empty root .exe IS what discovery selects. The non-executable escape above must not
+ reach it."""
+ root = _windows_tree(
+ tmp_path,
+ _PUBLISHED_WINDOWS_PAYLOAD,
+ marker = '{"release_tag": "b10840", "source": "published"}',
+ )
+ (root / "llama-server.exe").write_bytes(b"")
+ assert ILP.installed_runtime_health(root, host = _windows_host()) == (
+ False,
+ "llama_runtime_binaries_missing",
+ )
+
+
+def test_the_selection_rule_matches_the_resolver_the_backend_uses(tmp_path):
+ """The two are one question asked twice, so they are checked against each other.
+
+ ``_discovery_would_select`` mirrors ``_usable_binary``; a drift here is a runtime that
+ launches a binary we called fine, or a repair of one we called broken.
+ """
+ backend_dir = str(Path(__file__).resolve().parents[3] / "studio" / "backend")
+ if backend_dir not in sys.path:
+ sys.path.insert(0, backend_dir)
+ from utils.llama_cpp_path_settings import _usable_binary
+
+ candidate = tmp_path / "llama-server"
+ candidate.write_text("#!/bin/sh\n", encoding = "utf-8")
+ for mode, platform, host in (
+ (0o755, "linux", _macos_host()),
+ (0o644, "linux", _macos_host()),
+ ):
+ os.chmod(candidate, mode)
+ assert ILP._discovery_would_select(candidate, host) == _usable_binary(
+ candidate, platform = platform
+ ), mode
+ # Absent on both sides, whatever the platform.
+ candidate.unlink()
+ assert ILP._discovery_would_select(candidate, _macos_host()) is False
+ assert _usable_binary(candidate, platform = "linux") is False
+
+
[email protected](os.name == "nt", reason = "the root wrapper is written on POSIX only")
+def test_a_root_entrypoint_that_is_not_there_is_not_a_pin(tmp_path):
+ """An absent root copy, and a link whose target went with it, both read as absent to the
+ finder, which then falls through to build/bin. Calling either one broken would fail
+ health on every install that never got a root entrypoint at all."""
+ root = _macos_tree(tmp_path)
+ assert ILP.installed_runtime_health(root, host = _macos_host()) == (True, "")
+
+ os.symlink("build/bin/llama-server-that-went-away", root / "llama-server")
+ assert not (root / "llama-server").exists()
+ assert ILP.installed_runtime_health(root, host = _macos_host()) == (True, "")
diff --git a/tests/studio/install/test_installed_runtime_health_matrix.py b/tests/studio/install/test_installed_runtime_health_matrix.py
new file mode 100644
index 00000000000..186defc339e
--- /dev/null
+++ b/tests/studio/install/test_installed_runtime_health_matrix.py
@@ -0,0 +1,789 @@
+# 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 launch preflight health probe across every platform, backend and shipped marker shape.
+
+``installed_runtime_health`` is asked at desktop launch, and a ``(False, reason)`` marks the
+install stale, which runs a repair that ends in ``_existing_install_runs`` deciding
+keep-or-reinstall. Those two deciders are what this file holds together.
+
+The load-bearing property is one directional inequality: a tree this probe calls broken must
+be a tree the repair would not keep. Otherwise the repair leaves the tree identical, the next
+launch rejects it again, and the user has an unbreakable loop with no error to act on.
+Asserted as a property over the whole matrix, since the pair of deciders is what drifts.
+
+The other half is backwards compatibility. ``UNSLOTH_PREBUILT_INFO.json`` is append-only
+across twelve shapes with no version field, so a wrong ``(False, ...)`` on any of them is a
+repair loop for every user carrying that shape today.
+
+Platforms are simulated through ``HostInfo`` and passed with ``host=``, as in
+``test_keep_install_backcompat_9979``, which this file borrows its fixtures and marker tables
+from. WSL is not a fourth platform: ``platform.system()`` says ``Linux`` there and every
+table is chosen off ``is_windows`` / ``is_macos``, so it is graded by the Linux rows. The
+arm64 hosts matter for the install kind names, though the payload intersection is picked by
+the platform prefix rather than the architecture.
+"""
+
+import importlib.util
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+import pytest
+
+WINDOWS_HOST = os.name == "nt"
+ROOT_USER = hasattr(os, "geteuid") and os.geteuid() == 0
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[3]
+MODULE_PATH = PACKAGE_ROOT / "studio" / "install_llama_prebuilt.py"
+SPEC = importlib.util.spec_from_file_location("studio_install_llama_prebuilt", MODULE_PATH)
+assert SPEC is not None and SPEC.loader is not None
+ILP = importlib.util.module_from_spec(SPEC)
+sys.modules[SPEC.name] = ILP
+SPEC.loader.exec_module(ILP)
+
+HostInfo = ILP.HostInfo
+
+
+def _host(**kw) -> HostInfo:
+ base = dict(
+ system = "Linux",
+ machine = "x86_64",
+ is_windows = False,
+ is_linux = True,
+ 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,
+ )
+ base.update(kw)
+ return HostInfo(**base)
+
+
+LINUX = _host()
+LINUX_ARM64 = _host(machine = "aarch64", is_x86_64 = False, is_arm64 = True)
+WINDOWS = _host(system = "Windows", machine = "AMD64", is_windows = True, is_linux = False)
+MACOS_ARM64 = _host(
+ system = "Darwin",
+ machine = "arm64",
+ is_windows = False,
+ is_linux = False,
+ is_macos = True,
+ is_x86_64 = False,
+ is_arm64 = True,
+ macos_version = (15, 5),
+)
+MACOS_X64 = _host(
+ system = "Darwin",
+ machine = "x86_64",
+ is_windows = False,
+ is_linux = False,
+ is_macos = True,
+ is_x86_64 = True,
+ is_arm64 = False,
+ macos_version = (14, 6),
+)
+
+HOSTS = [
+ ("linux-x64", LINUX),
+ ("linux-arm64", LINUX_ARM64),
+ ("windows-x64", WINDOWS),
+ ("macos-arm64", MACOS_ARM64),
+ ("macos-x64", MACOS_X64),
+]
+
+
+# The payload each platform's install kinds share. Literal file names rather than the module's
+# globs, so these are an independent statement of the requirement.
+_SHARED_PAYLOAD = {
+ "linux": [
+ "libllama-common.so",
+ "libllama.so",
+ "libggml.so",
+ "libggml-base.so",
+ "libggml-cpu.so",
+ "libmtmd.so",
+ # The Linux half of the same impl split as llama-server-impl.dll below:
+ # llama-server and llama-quantize load these by DT_NEEDED. Written for every
+ # shape, like the Windows one, and taken back out by required_runtime_files
+ # for the shapes that do not owe them.
+ "libllama-server-impl.so",
+ "libllama-quantize-impl.so",
+ ],
+ "windows": [
+ "llama.dll",
+ "llama-common.dll",
+ "llama-server-impl.dll",
+ "llama-quantize-impl.dll",
+ "ggml.dll",
+ "ggml-base.dll",
+ "ggml-cpu.dll",
+ "mtmd.dll",
+ ],
+ # The names the real macos-arm64 bundle ships, one per library the runtime
+ # links against.
+ "macos": [
+ "libllama-common.dylib",
+ "libllama.dylib",
+ "libggml.dylib",
+ "libggml-base.dylib",
+ "libggml-cpu.dylib",
+ "libmtmd.dylib",
+ # The macOS half of the same split; the real b11007 arm64 bundle ships both.
+ "libllama-server-impl.dylib",
+ "libllama-quantize-impl.dylib",
+ ],
+}
+_BACKEND_PAYLOAD = {
+ ("linux", "cuda"): ["libggml-cuda.so"],
+ ("linux", "rocm"): ["libggml-hip.so"],
+ ("linux", "vulkan"): ["libggml-vulkan.so"],
+ ("windows", "cuda"): ["ggml-cuda.dll"],
+ ("windows", "rocm"): ["ggml-hip.dll"],
+ ("windows", "vulkan"): ["ggml-vulkan.dll"],
+}
+_PUBLISHED_PAYLOAD = {
+ "linux": ["llama-diffusion-gemma-visual-server"],
+ "windows": ["llama-diffusion-gemma-visual-server.exe"],
+ "macos": [],
+}
+_CUDART_TRIO = ("cudart64_13.dll", "cublas64_13.dll", "cublasLt64_13.dll")
+
+# ggml-org/llama.cpp#23462 split the per-binary entry code out between b9279 and b9283, so an
+# older Windows archive is monolithic and healthy without llama-server-impl.dll.
+_IMPL_SPLIT_BUILD = 9283
+
+
+def _platform_of(host: HostInfo) -> str:
+ return "windows" if host.is_windows else "macos" if host.is_macos else "linux"
+
+
+def _runtime_dir(install_dir: Path, host: HostInfo) -> Path:
+ return (
+ install_dir / "build" / "bin" / "Release"
+ if host.is_windows
+ else install_dir / "build" / "bin"
+ )
+
+
+# ---------------------------------------------------------------------------
+# The shipped marker shapes, oldest first, trimmed to the keys the health path reads.
+
+S1 = { # 2026-03-25 #4562: no release_tag, no backend, no asset_sha256
+ "requested_tag": "b6099",
+ "tag": "b6099",
+ "asset": "llama-b6099-bin-ubuntu-x64.tar.gz",
+ "source": "upstream",
+ "bundle_profile": "full",
+ "runtime_line": None,
+ "coverage_class": None,
+ "prebuilt_fallback_used": False,
+ "installed_at_utc": "2026-03-26T04:11:07Z",
+}
+S2 = { # 2026-04-01 #4741: release_tag + fingerprint arrive
+ **S1,
+ "release_tag": "b6210",
+ "published_repo": "unslothai/llama.cpp",
+ "asset": "app-b6210-linux-x64-cuda12.tar.gz",
+ "asset_sha256": "3f" * 32,
+ "source": "published",
+ "runtime_line": "cuda12",
+ "install_fingerprint": "aa" * 32,
+}
+S3 = {**S2, "prebuilt_fallback_used": True} # a fallback install, same keys
+S4 = {**S2, "coverage_class": "older"} # coverage_class starts being filled in
+S5 = {**S2, "force_cpu": False} # 2026-07-20 #7228
+S6 = {
+ **S5,
+ "llama_backend": "vulkan", # 2026-07-27 #7373
+ "asset": "llama-b7001-bin-ubuntu-vulkan-x64.tar.gz",
+ "runtime_line": None,
+}
+S7 = {**S5, "ggml_tree": "b7440"} # 2026-08-04 #7817
+S8 = {
+ **S7,
+ "rocm_gfx": "gfx1151", # 2026-08-08 #8050
+ "asset": "app-b9001-linux-x64-rocm-gfx110X.tar.gz",
+ "runtime_line": None,
+}
+S9 = {**S7, "backend": "cuda", "backend_request": "auto"} # 2026-08-13 #8520
+S10 = {**S9, "gfx_target": None, "mapped_targets": []} # 2026-08-13 #7670
+S11 = {**S10, "supported_sms": ["80", "86", "89", "90"]} # 2026-08-18 #8841 == main
+S12 = {**S11, "runtime_asset": None} # this PR
+
+# A real marker, produced by running studio/install_llama_prebuilt.py. Its tag is past the
+# impl split, so it is the one shape that owes llama-server-impl.dll on Windows.
+S12_REAL = {
+ "requested_tag": "latest",
+ "tag": "b10698",
+ "release_tag": "b10698-mix-67dfc8b",
+ "published_repo": "unslothai/llama.cpp",
+ "asset": "app-b10698-mix-67dfc8b-linux-x64-cuda13-newer.tar.gz",
+ "force_cpu": False,
+ "llama_backend": None,
+ "backend": "cuda",
+ "backend_request": "auto",
+ "asset_sha256": "d4" * 32,
+ "runtime_asset": None,
+ "source": "published",
+ "ggml_tree": "0034c6eb",
+ "bundle_profile": "cuda13-newer",
+ "runtime_line": "cuda13",
+ "coverage_class": "newer",
+ "gfx_target": None,
+ "mapped_targets": [],
+ "supported_sms": ["86", "89", "90", "100", "103", "120"],
+ "install_fingerprint": "36" * 32,
+ "prebuilt_fallback_used": False,
+ "installed_at_utc": "2026-08-31T06:40:37Z",
+}
+
+SHAPES = [
+ ("S1", S1),
+ ("S2", S2),
+ ("S3", S3),
+ ("S4", S4),
+ ("S5", S5),
+ ("S6", S6),
+ ("S7", S7),
+ ("S8", S8),
+ ("S9", S9),
+ ("S10", S10),
+ ("S11", S11),
+ ("S12", S12),
+ ("S12real", S12_REAL),
+]
+
+# "metal" only exists on macOS, but a tree can be carried between machines, so it is
+# exercised on every platform.
+BACKENDS = ["cpu", "cuda", "rocm", "vulkan", "metal"]
+
+# An asset name per backend, so shapes predating the ``backend`` key still resolve one the way
+# a real old install does, through backend_from_asset_name.
+_ASSET_TOKEN = {
+ "cpu": "app-b1-linux-x64-cpu.tar.gz",
+ "cuda": "app-b1-linux-x64-cuda12.tar.gz",
+ "rocm": "app-b1-linux-x64-rocm-gfx110X.tar.gz",
+ "vulkan": "app-b1-linux-x64-vulkan.tar.gz",
+ "metal": "app-b1-macos-arm64.tar.gz",
+}
+
+
+def shape_with_backend(shape: dict, backend: str) -> dict:
+ """A shipped shape re-pointed at ``backend`` the way that shape would record it.
+
+ Shapes older than #8520 have no ``backend`` key, and adding one would test a marker no
+ install ever carried, so they get the asset name ``marker_backend`` falls back to.
+ """
+ marker = {**shape, "asset": _ASSET_TOKEN[backend]}
+ if "backend" in shape:
+ marker["backend"] = backend
+ return marker
+
+
+def required_runtime_files(platform: str, backend: str, marker: dict) -> list[str]:
+ """The files a tree of this shape owes, stated independently of the module's tables.
+
+ Only backends the platform builds contribute a library: ``cuda`` on macOS filters to no
+ install kind, so the decider falls back to every kind the platform has, whose
+ intersection is the shared payload alone.
+ """
+ source = marker.get("source")
+ files = list(_SHARED_PAYLOAD[platform])
+ if platform == "windows" and source not in {"published", "upstream"}:
+ # setup.ps1 links statically and ships none of the rest.
+ files = ["llama.dll"]
+ if platform == "windows" and source in {"published", "upstream"}:
+ build = ILP._release_build_number(marker.get("tag"))
+ if build is not None and build < _IMPL_SPLIT_BUILD:
+ files.remove("llama-server-impl.dll")
+ files.remove("llama-quantize-impl.dll")
+ files.append("llama-server.exe")
+ # The same split, on the side that names the libraries lib<binary>-impl.so.
+ # llama-server and llama-quantize load them by DT_NEEDED, so a Linux bundle from
+ # a published or upstream release owes both; a source build and a pre-split
+ # archive ship neither, and requiring one of those would reinstall forever.
+ if platform == "linux":
+ build = ILP._release_build_number(marker.get("tag"))
+ owed = source in {"published", "upstream"} and (build is None or build >= _IMPL_SPLIT_BUILD)
+ if not owed:
+ files.remove("libllama-server-impl.so")
+ files.remove("libllama-quantize-impl.so")
+ if platform == "macos":
+ build = ILP._release_build_number(marker.get("tag"))
+ owed = source in {"published", "upstream"} and (build is None or build >= _IMPL_SPLIT_BUILD)
+ if not owed:
+ files.remove("libllama-server-impl.dylib")
+ files.remove("libllama-quantize-impl.dylib")
+ files += _BACKEND_PAYLOAD.get((platform, backend), [])
+ if backend == "vulkan" and source == "published":
+ files += _PUBLISHED_PAYLOAD[platform]
+ return files
+
+
+def build_tree(
+ root: Path,
+ *,
+ host: HostInfo = LINUX,
+ marker = "default",
+ backend: str = "cuda",
+ payload: bool = True,
+ cudart: bool = False,
+ binaries: bool = True,
+ runtime_dir: bool = True,
+) -> Path:
+ """Write a complete install tree at ``root``.
+
+ Complete for ``_existing_install_runs`` as well as for the health probe, since the
+ invariant test drives both against the same tree, so the root entrypoint copies,
+ ``convert_hf_to_gguf.py`` and ``gguf-py`` are written and the binaries are runnable
+ stubs. ``marker`` is the object to serialise, ``None`` writes none, ``str`` verbatim.
+ """
+ platform = _platform_of(host)
+ ext = ".exe" if host.is_windows else ""
+ runtime = _runtime_dir(root, host)
+ if runtime_dir:
+ runtime.mkdir(parents = True)
+ else:
+ root.mkdir(parents = True, exist_ok = True)
+
+ if binaries:
+ targets = [root / f"llama-server{ext}", root / f"llama-quantize{ext}"]
+ if runtime_dir:
+ targets += [runtime / f"llama-server{ext}", runtime / f"llama-quantize{ext}"]
+ for path in targets:
+ path.write_text("#!/bin/sh\nexit 0\n", encoding = "utf-8")
+ os.chmod(path, 0o755)
+ (root / "convert_hf_to_gguf.py").write_text("", encoding = "utf-8")
+ (root / "gguf-py").mkdir(exist_ok = True)
+
+ if marker == "default":
+ marker = S12
+ if marker is not None:
+ (root / "UNSLOTH_PREBUILT_INFO.json").write_text(
+ marker if isinstance(marker, str) else json.dumps(marker) + "\n",
+ encoding = "utf-8",
+ )
+
+ if payload and runtime_dir:
+ names = list(_SHARED_PAYLOAD[platform])
+ names += _BACKEND_PAYLOAD.get((platform, backend), [])
+ names += _PUBLISHED_PAYLOAD[platform]
+ if cudart:
+ names += list(_CUDART_TRIO)
+ for name in names:
+ (runtime / name).write_text("x", encoding = "utf-8")
+ return root
+
+
+# Every (host, backend, shape) cell. The decision is driven by the platform booleans and the
+# marker's backend only, so this is the full space the probe can distinguish.
+CELLS = [
+ (f"{host_id}-{backend}-{shape_id}", host, backend, shape)
+ for host_id, host in HOSTS
+ for backend in BACKENDS
+ for shape_id, shape in SHAPES
+]
+CELL_IDS = [cell[0] for cell in CELLS]
+
+
[email protected](("cell", "host", "backend", "shape"), CELLS, ids = CELL_IDS)
+def test_a_complete_install_of_every_shipped_shape_is_healthy_everywhere(
+ tmp_path, cell, host, backend, shape
+):
+ """The backwards-compatibility half: a wrong ``(False, ...)`` on any shape sends every user
+ carrying it into a repair on next launch."""
+ marker = shape_with_backend(shape, backend)
+ root = build_tree(tmp_path / "llama.cpp", host = host, marker = marker, backend = backend)
+ assert ILP.installed_runtime_health(root, host = host) == (True, ""), cell
+
+
[email protected](("cell", "host", "backend", "shape"), CELLS, ids = CELL_IDS)
+def test_removing_any_single_required_file_is_reported_broken(tmp_path, cell, host, backend, shape):
+ """One file at a time, the shape quarantine leaves: the tree is otherwise whole, so a
+ check that only looks at the directory or the marker would pass it."""
+ marker = shape_with_backend(shape, backend)
+ platform = _platform_of(host)
+ ext = ".exe" if host.is_windows else ""
+ # Deduplicated: llama-server.exe is both an entrypoint and a member of the Windows shared
+ # payload. One tree is built per victim, under its own name.
+ victims = required_runtime_files(platform, backend, marker)
+ victims += [f"llama-server{ext}", f"llama-quantize{ext}"]
+ for victim in dict.fromkeys(victims):
+ root = build_tree(
+ tmp_path / victim.replace("*", "_"),
+ host = host,
+ marker = marker,
+ backend = backend,
+ )
+ (_runtime_dir(root, host) / victim).unlink()
+ verdict = ILP.installed_runtime_health(root, host = host)
+ assert verdict is not None, f"{cell}: {victim}"
+ ok, reason = verdict
+ assert ok is False, f"{cell}: removing {victim} was called healthy"
+ assert reason in {
+ "llama_runtime_payload_incomplete",
+ "llama_runtime_binaries_missing",
+ }, f"{cell}: {victim} -> {reason}"
+
+
[email protected](("cell", "host", "backend", "shape"), CELLS, ids = CELL_IDS)
+def test_a_broken_tree_is_never_one_the_repair_would_keep(tmp_path, cell, host, backend, shape):
+ """THE INVARIANT, as a property over the matrix rather than as examples.
+
+ Every damaged tree the probe rejects is put to ``_existing_install_runs``, which the repair
+ ultimately consults. A tree rejected here and kept there is repaired, left unchanged, and
+ rejected again next launch, with no actionable error. The trees carry runnable stubs and
+ the full ``confirm_install_tree`` set so the keep path reaches its real decision.
+ """
+ marker = shape_with_backend(shape, backend)
+ platform = _platform_of(host)
+ ext = ".exe" if host.is_windows else ""
+
+ damages: list[tuple[str, object]] = [("healthy", None)]
+ for name in required_runtime_files(platform, backend, marker):
+ damages.append((f"remove-{name}", name))
+ damages.append(("remove-server", f"llama-server{ext}"))
+ damages.append(("remove-quantize", f"llama-quantize{ext}"))
+
+ for label, victim in damages:
+ root = build_tree(
+ tmp_path / label,
+ host = host,
+ marker = marker,
+ backend = backend,
+ )
+ if victim is not None:
+ (_runtime_dir(root, host) / str(victim)).unlink()
+ verdict = ILP.installed_runtime_health(root, host = host)
+ if label == "healthy":
+ # The positive control, without which the implication below holds for free.
+ assert verdict == (True, ""), cell
+ assert ILP._existing_install_runs(root, host) is True, cell
+ continue
+ if verdict is None or verdict[0] is True:
+ continue
+ assert ILP._existing_install_runs(root, host) is False, (
+ f"REPAIR LOOP: {cell} with {label} is rejected by installed_runtime_health "
+ f"({verdict[1]}) but kept by _existing_install_runs"
+ )
+
+
[email protected](("cell", "host", "backend", "shape"), CELLS, ids = CELL_IDS)
+def test_the_structural_damage_cases_are_broken_and_never_kept(
+ tmp_path, cell, host, backend, shape
+):
+ """The three ways a tree loses more than a file, on every cell: the runtime directory is
+ gone, the marker is gone, the marker is unreadable."""
+ marker = shape_with_backend(shape, backend)
+
+ without_dir = build_tree(
+ tmp_path / "no-runtime-dir",
+ host = host,
+ marker = marker,
+ backend = backend,
+ runtime_dir = False,
+ )
+ assert ILP.installed_runtime_health(without_dir, host = host) == (
+ False,
+ "llama_runtime_dir_missing",
+ ), cell
+ assert ILP._existing_install_runs(without_dir, host) is False, cell
+
+ # No marker is a source build this path never owned: not installed, not broken. Reporting
+ # it broken would offer a repair for a runtime the user never installed here.
+ without_marker = build_tree(
+ tmp_path / "no-marker",
+ host = host,
+ marker = None,
+ backend = backend,
+ )
+ assert ILP.installed_runtime_health(without_marker, host = host) is None, cell
+
+ # A present but unreadable marker is graded on its tree, not short-circuited to "nothing
+ # installed"; load_prebuilt_metadata cannot tell the two apart, so the file itself does.
+ # A complete tree stays healthy, which keeps the repair from looping, since the keep path
+ # keeps it too (confirm_install_tree only checks the marker file exists).
+ corrupt = build_tree(
+ tmp_path / "corrupt-marker",
+ host = host,
+ marker = "{not json",
+ backend = backend,
+ )
+ assert ILP.installed_runtime_health(corrupt, host = host) == (True, ""), cell
+ assert ILP._existing_install_runs(corrupt, host) is True, cell
+
+ # Damaged as well as unreadable: the case the old behaviour missed, leaving preflight
+ # Ready with a library gone.
+ corrupt_and_gutted = build_tree(
+ tmp_path / "corrupt-marker-gutted",
+ host = host,
+ marker = "{not json",
+ backend = backend,
+ )
+ for path in sorted(_runtime_dir(corrupt_and_gutted, host).glob("*")):
+ if path.is_file() and not path.name.startswith("llama-"):
+ path.unlink()
+ verdict = ILP.installed_runtime_health(corrupt_and_gutted, host = host)
+ assert verdict is not None and verdict[0] is False, cell
+ assert ILP._existing_install_runs(corrupt_and_gutted, host) is False, cell
+
+
+def test_removing_a_file_this_install_kind_does_not_owe_stays_healthy(tmp_path):
+ """Over-strictness is the loop direction, so the deliberately-not-required files are
+ asserted too: the diffusion visual server outside a published Vulkan install, and
+ llama-server-impl.dll on a Windows archive built before the upstream impl split."""
+ cuda = shape_with_backend(S12, "cuda")
+ root = build_tree(tmp_path / "cuda", host = LINUX, marker = cuda, backend = "cuda")
+ (_runtime_dir(root, LINUX) / "llama-diffusion-gemma-visual-server").unlink()
+ assert ILP.installed_runtime_health(root, host = LINUX) == (True, "")
+
+ old_windows = shape_with_backend(S2, "cpu") # tag b6099, before build 9283
+ win = build_tree(tmp_path / "win", host = WINDOWS, marker = old_windows, backend = "cpu")
+ (_runtime_dir(win, WINDOWS) / "llama-server-impl.dll").unlink()
+ assert ILP.installed_runtime_health(win, host = WINDOWS) == (True, "")
+
+ # S11 and older cannot record a cudart pairing, so demanding the trio would reject every
+ # Windows CUDA install that exists today, on every launch.
+ unpaired = build_tree(
+ tmp_path / "unpaired",
+ host = WINDOWS,
+ marker = shape_with_backend(S11, "cuda"),
+ backend = "cuda",
+ cudart = False,
+ )
+ assert ILP.installed_runtime_health(unpaired, host = WINDOWS) == (True, "")
+
+
+def test_the_split_dylibs_are_owed_on_a_post_split_macos_bundle(tmp_path):
+ """macOS carries the same split: the real b11007 arm64 bundle ships
+ libllama-server-impl.dylib and libllama-quantize-impl.dylib, and dyld cannot start
+ llama-server without them. Every other group stayed satisfied, so this was the one
+ platform where the probe answered Ready on a runtime that could not run.
+ """
+ post = build_tree(
+ tmp_path / "post",
+ host = MACOS_ARM64,
+ marker = shape_with_backend(S12_REAL, "metal"),
+ backend = "metal",
+ )
+ assert ILP.installed_runtime_health(post, host = MACOS_ARM64) == (True, "")
+ (_runtime_dir(post, MACOS_ARM64) / "libllama-server-impl.dylib").unlink()
+ assert ILP.installed_runtime_health(post, host = MACOS_ARM64) == (
+ False,
+ "llama_runtime_payload_incomplete",
+ )
+
+ # The control in the loop direction: a pre-split bundle never shipped them, so demanding
+ # them there would reinstall forever.
+ pre = build_tree(
+ tmp_path / "pre",
+ host = MACOS_ARM64,
+ marker = shape_with_backend(S1, "metal"), # upstream b6099, before build 9283
+ backend = "metal",
+ )
+ assert ILP.installed_runtime_health(pre, host = MACOS_ARM64) == (True, "")
+
+
+# ---------------------------------------------------------------------------
+# GPU independence. The probe runs with platform_only_host(), which probes no hardware, so a
+# verdict that moved with the GPU would make the same tree healthy or broken depending on
+# which detection the caller paid for.
+
+GPU_HOSTS = [
+ ("no-gpu", {}),
+ ("nvidia", {"has_physical_nvidia": True, "has_usable_nvidia": True, "compute_caps": ["8.9"]}),
+ ("nvidia-unusable", {"has_physical_nvidia": True, "has_usable_nvidia": False}),
+ ("rocm", {"has_rocm": True, "rocm_gfx_target": "gfx1151"}),
+ ("amd-no-rocm", {"has_amd_gpu_without_rocm": True}),
+ ("intel", {"has_intel_gpu": True}),
+]
+
+
[email protected]("backend", BACKENDS)
+ ("host_id", "host"),
+ HOSTS,
+ ids = [h[0] for h in HOSTS],
+)
+def test_the_verdict_does_not_move_with_the_detected_gpu(tmp_path, host_id, host, backend):
+ """Same tree, six hardware stories, one verdict. Asserted healthy and gutted, so a check
+ that silently relaxed on, say, an Intel host is caught."""
+ marker = shape_with_backend(S12, backend)
+ healthy = build_tree(tmp_path / "healthy", host = host, marker = marker, backend = backend)
+ gutted = build_tree(tmp_path / "gutted", host = host, marker = marker, backend = backend)
+ (_runtime_dir(gutted, host) / _SHARED_PAYLOAD[_platform_of(host)][0]).unlink()
+
+ healthy_verdicts = set()
+ gutted_verdicts = set()
+ for gpu_id, fields in GPU_HOSTS:
+ variant = _host(**{**host.__dict__, **fields})
+ healthy_verdicts.add(ILP.installed_runtime_health(healthy, host = variant))
+ gutted_verdicts.add(ILP.installed_runtime_health(gutted, host = variant))
+ assert healthy_verdicts == {(True, "")}, f"{host_id}-{backend}: {healthy_verdicts}"
+ assert gutted_verdicts == {
+ (False, "llama_runtime_payload_incomplete")
+ }, f"{host_id}-{backend}: {gutted_verdicts}"
+
+
+# ---------------------------------------------------------------------------
+# Both entrypoint binaries, since the payload groups name libraries only, so on Linux and
+# macOS a quarantined llama-server would otherwise read as a complete install.
+
+
+ ("host_id", "host"),
+ HOSTS,
+ ids = [h[0] for h in HOSTS],
+)
+ "missing",
+ [("server",), ("quantize",), ("server", "quantize")],
+ ids = ["server", "quantize", "both"],
+)
+def test_a_missing_entrypoint_is_caught_with_a_complete_library_payload(
+ tmp_path, host_id, host, missing
+):
+ marker = shape_with_backend(S12, "cuda")
+ root = build_tree(tmp_path / "tree", host = host, marker = marker, backend = "cuda")
+ ext = ".exe" if host.is_windows else ""
+ for name in missing:
+ (_runtime_dir(root, host) / f"llama-{name}{ext}").unlink()
+ ok, reason = ILP.installed_runtime_health(root, host = host)
+ assert ok is False
+ if host.is_windows and "server" in missing:
+ # llama-server.exe is itself in the Windows shared payload, so the payload check
+ # answers first.
+ assert reason == "llama_runtime_payload_incomplete"
+ else:
+ assert reason == "llama_runtime_binaries_missing"
+
+
+# ---------------------------------------------------------------------------
+# Robustness. Every case is a real disk state a user can arrive in, and the failure to avoid
+# is the same throughout: an exception or a wrong verdict on the launch path.
+
+
+def test_an_install_dir_reached_through_a_symlink_is_judged_the_same(tmp_path):
+ """Installs move, and a symlink at the old path is how users keep the launcher working."""
+ real = build_tree(tmp_path / "real", host = LINUX, marker = S12, backend = "cuda")
+ link = tmp_path / "link"
+ link.symlink_to(real, target_is_directory = True)
+ assert ILP.installed_runtime_health(link, host = LINUX) == (True, "")
+
+
+def test_a_runtime_path_that_is_a_file_is_broken_not_an_exception(tmp_path):
+ """A truncated extract can leave build/bin as a regular file, and globbing a
+ non-directory must not raise on the launch path."""
+ root = tmp_path / "llama.cpp"
+ (root / "build").mkdir(parents = True)
+ (root / "build" / "bin").write_text("not a directory", encoding = "utf-8")
+ (root / "UNSLOTH_PREBUILT_INFO.json").write_text(json.dumps(S12), encoding = "utf-8")
+ assert ILP.installed_runtime_health(root, host = LINUX) == (False, "llama_runtime_dir_missing")
+ assert ILP._existing_install_runs(root, LINUX) is False
+
+
[email protected](WINDOWS_HOST, reason = "chmod cannot clear read permission on Windows")
[email protected](ROOT_USER, reason = "root reads a 000 file regardless of its mode")
+def test_a_marker_the_process_cannot_read_is_graded_on_its_tree(tmp_path):
+ """Permission denied is one more way a marker stops parsing, so it lands in the same arm as
+ a truncated one: the tree is real and is graded rather than called not installed."""
+ root = build_tree(tmp_path / "llama.cpp", host = LINUX, marker = S12, backend = "cuda")
+ marker_path = root / "UNSLOTH_PREBUILT_INFO.json"
+ os.chmod(marker_path, 0o000)
+ try:
+ if os.access(marker_path, os.R_OK):
+ pytest.skip("running as a user that ignores the mode, so nothing is denied")
+ assert ILP.installed_runtime_health(root, host = LINUX) == (True, "")
+ finally:
+ os.chmod(marker_path, 0o644)
+
+
+ "body",
+ ["[]", '["cuda"]', "123", '"cuda"', "null", "", " ", "{}", "{}", '{"tag": "b1"'],
+ ids = [
+ "array",
+ "array-of-strings",
+ "number",
+ "string",
+ "null",
+ "empty",
+ "whitespace",
+ "empty-object",
+ "bom",
+ "truncated",
+ ],
+)
+def test_a_marker_that_is_not_an_object_never_raises_and_never_loops(tmp_path, body):
+ """Valid JSON that is not an object and invalid JSON both read as "no marker" through
+ load_prebuilt_metadata. The empty object is a marker, and it names no backend, so it owes
+ the payload every install kind on the platform shares."""
+ root = build_tree(tmp_path / "llama.cpp", host = LINUX, marker = body, backend = "cuda")
+ verdict = ILP.installed_runtime_health(root, host = LINUX)
+ assert verdict in (None, (True, ""))
+ if verdict is not None and verdict[0] is False:
+ assert ILP._existing_install_runs(root, LINUX) is False
+
+
+def test_a_tree_full_of_unrelated_files_is_still_answered_fast(tmp_path):
+ """On the launch path, so timed as well as checked: the payload check globs the runtime
+ directory once per group, and a user's also holds every model shard they dropped in it."""
+ root = build_tree(tmp_path / "llama.cpp", host = LINUX, marker = S12, backend = "cuda")
+ runtime = _runtime_dir(root, LINUX)
+ for index in range(2000):
+ (runtime / f"unrelated-{index}.bin").write_text("", encoding = "utf-8")
+
+ start = time.perf_counter()
+ verdict = ILP.installed_runtime_health(root, host = LINUX)
+ elapsed = time.perf_counter() - start
+ assert verdict == (True, "")
+ assert elapsed < 1.0, f"took {elapsed:.3f}s with 2000 extra files"
+
+
+ "name",
+ ["with spaces", "unslöth ünicode", "日本語のパス", "trailing.dot."],
+ ids = ["spaces", "unicode-latin", "unicode-cjk", "trailing-dot"],
+)
+def test_an_awkward_install_path_is_judged_normally(tmp_path, name):
+ """Default install roots sit under the user's home, so a path handled as anything other
+ than a Path would fail at launch for those users only."""
+ root = build_tree(tmp_path / name / "llama.cpp", host = LINUX, marker = S12, backend = "cuda")
+ assert ILP.installed_runtime_health(root, host = LINUX) == (True, "")
+ (_runtime_dir(root, LINUX) / "libggml.so").unlink()
+ assert ILP.installed_runtime_health(root, host = LINUX) == (
+ False,
+ "llama_runtime_payload_incomplete",
+ )
+
+
+def test_a_very_deep_install_path_is_judged_normally(tmp_path):
+ """A deep root is the cheapest way to keep paths off string arithmetic; on Windows it is
+ also where a non-extended path stops resolving."""
+ deep = tmp_path
+ for index in range(40):
+ deep = deep / f"level{index}"
+ root = build_tree(deep / "llama.cpp", host = LINUX, marker = S12, backend = "cuda")
+ assert ILP.installed_runtime_health(root, host = LINUX) == (True, "")
+
+
+def test_the_probe_never_executes_anything_it_finds(tmp_path, monkeypatch):
+ """Preflight runs at every launch and the setup scripts own the exec probes, so this looks
+ and does not run. Also why the invariant is one-directional: this call can only be as
+ strict as, or looser than, the keep path."""
+ root = build_tree(tmp_path / "llama.cpp", host = LINUX, marker = S12, backend = "cuda")
+
+ def refuse(*args, **kwargs):
+ raise AssertionError("installed_runtime_health must not spawn a process")
+
+ monkeypatch.setattr(ILP.subprocess, "run", refuse)
+ monkeypatch.setattr(ILP.shutil, "which", refuse)
+ assert ILP.installed_runtime_health(root, host = LINUX) == (True, "")
diff --git a/tests/studio/install/test_keep_install_backcompat_9979.py b/tests/studio/install/test_keep_install_backcompat_9979.py
index 1ff51ad43c4..0fe087ed933 100644
--- a/tests/studio/install/test_keep_install_backcompat_9979.py
+++ b/tests/studio/install/test_keep_install_backcompat_9979.py
@@ -127,19 +127,36 @@ _SHARED_PAYLOAD = {
"libggml-base.so",
"libggml-cpu.so",
"libmtmd.so",
+ # The Linux half of the same impl split as llama-server-impl.dll below;
+ # llama-server and llama-quantize load these by DT_NEEDED.
+ "libllama-server-impl.so",
+ "libllama-quantize-impl.so",
],
# Written unconditionally: the check is "has", not "has only".
"windows": [
"llama.dll",
"llama-common.dll",
"llama-server-impl.dll",
+ "llama-quantize-impl.dll",
"ggml.dll",
"ggml-base.dll",
"ggml-cpu.dll",
"mtmd.dll",
],
- "macos": ["libllama.dylib", "libggml.dylib", "libmtmd.dylib"],
+ # The names the real macos-arm64 bundle ships, one per library the runtime
+ # links against.
+ "macos": [
+ "libllama-common.dylib",
+ "libllama.dylib",
+ "libggml.dylib",
+ "libggml-base.dylib",
+ "libggml-cpu.dylib",
+ "libmtmd.dylib",
+ ],
}
+# Non-empty, because a zero-byte runtime library is now rejected as damage, and long
+# enough for tests that corrupt a payload by halving it to have something left.
+_PAYLOAD_BYTES = "xxxx"
_BACKEND_PAYLOAD = {
("linux", "cuda"): ["libggml-cuda.so"],
("linux", "rocm"): ["libggml-hip.so"],
@@ -218,16 +235,16 @@ def build_install(
if payload:
for name in _SHARED_PAYLOAD[platform]:
- (runtime_dir / name).write_text("", encoding = "utf-8")
+ (runtime_dir / name).write_text(_PAYLOAD_BYTES, encoding = "utf-8")
if payload_backend != "unset":
for name in _BACKEND_PAYLOAD.get((platform, payload_backend), ()):
- (runtime_dir / name).write_text("", encoding = "utf-8")
+ (runtime_dir / name).write_text(_PAYLOAD_BYTES, encoding = "utf-8")
if visual_server:
for name in _PUBLISHED_PAYLOAD[platform]:
- (runtime_dir / name).write_text("", encoding = "utf-8")
+ (runtime_dir / name).write_text(_PAYLOAD_BYTES, encoding = "utf-8")
if cudart:
for name in _CUDART_TRIO:
- (runtime_dir / name).write_text("", encoding = "utf-8")
+ (runtime_dir / name).write_text(_PAYLOAD_BYTES, encoding = "utf-8")
return install_dir
diff --git a/tests/studio/install/test_llama_runtime_install_history.py b/tests/studio/install/test_llama_runtime_install_history.py
new file mode 100644
index 00000000000..d421f79298c
--- /dev/null
+++ b/tests/studio/install/test_llama_runtime_install_history.py
@@ -0,0 +1,812 @@
+# 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 launch-time runtime health probe against installs that exist on disk today.
+
+The sibling files build their trees by hand, so they can only confirm that the code agrees
+with the table their author read out of the code. This file uses artifacts instead: it
+extracts the real release zips into the layout the installer builds, and it copies a
+managed install out of ``~/.unsloth/llama.cpp`` and guts it a file at a time, which is the
+closest reachable stand-in for the quarantine this feature exists to catch.
+
+That difference is not cosmetic. A real install ships each core library twice, under its
+SONAME and under its full version (``libllama.so.0`` beside ``libllama.so.0.0.10360``),
+while a fixture writes only ``libllama.so``. The trailing-star globs in
+``runtime_payload_health_groups`` cannot tell the copies apart, so quarantining the SONAME
+leaves the group satisfied while the runtime no longer loads. Only an artifact shows that.
+
+Every test here skips rather than fails when its artifact is absent, so the file still runs
+in CI, where neither the release zips nor a managed install are present.
+"""
+
+import importlib.util
+import json
+import os
+import shutil
+import subprocess
+import sys
+import zipfile
+from pathlib import Path
+
+import pytest
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[3]
+MODULE_PATH = PACKAGE_ROOT / "studio" / "install_llama_prebuilt.py"
+SPEC = importlib.util.spec_from_file_location("studio_install_llama_prebuilt", MODULE_PATH)
+assert SPEC is not None and SPEC.loader is not None
+ILP = importlib.util.module_from_spec(SPEC)
+sys.modules[SPEC.name] = ILP
+SPEC.loader.exec_module(ILP)
+
+HostInfo = ILP.HostInfo
+
+# The release zips this file reads. Downloaded out of band and absent in CI, where every
+# test that wants one skips. The default is under the user's own cache so the file carries
+# no path belonging to one machine; point UNSLOTH_TEST_LLAMACPP_ASSET_DIR at the zips to
+# run these for real.
+ASSET_DIR = Path(
+ os.environ.get(
+ "UNSLOTH_TEST_LLAMACPP_ASSET_DIR",
+ Path.home() / ".cache" / "unsloth" / "llamacpp-test-assets",
+ )
+)
+
+
+def _asset_or_skip(asset: str) -> Path:
+ """The bundle, or a skip when this machine does not have it.
+
+ ``is_file()`` is not enough on its own: it propagates PermissionError and the other
+ stat failures, so an asset directory that exists but cannot be read (an unreadable
+ mount, another user's tree) fails the test instead of skipping it, which is the
+ opposite of what this file promises.
+ """
+ archive = ASSET_DIR / asset
+ try:
+ present = archive.is_file()
+ except OSError as error:
+ pytest.skip(f"release bundle not readable on this machine: {asset} ({error})")
+ if not present:
+ pytest.skip(f"release bundle not on this machine: {asset}")
+ return archive
+
+
+def _host(**kw) -> HostInfo:
+ base = dict(
+ system = "Linux",
+ machine = "x86_64",
+ is_windows = False,
+ is_linux = True,
+ 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,
+ )
+ base.update(kw)
+ return HostInfo(**base)
+
+
+LINUX = _host()
+WINDOWS = _host(system = "Windows", machine = "AMD64", is_windows = True, is_linux = False)
+WINDOWS_ARM64 = _host(
+ system = "Windows",
+ machine = "ARM64",
+ is_windows = True,
+ is_linux = False,
+ is_x86_64 = False,
+ is_arm64 = True,
+)
+
+
+# ---------------------------------------------------------------------------
+# The real release bundles: (asset, llama_backend in the marker, tag, host). The tag
+# matters, since the shared Windows group requires llama-server-impl.dll only from the
+# build that split it out, so a wrong tag would pass for the wrong reason.
+
+BUNDLES = [
+ ("app-b10798-mix-659e406-windows-x64-cpu.zip", None, "b10798", "published", WINDOWS),
+ (
+ "app-b10798-mix-659e406-windows-x64-cuda12-legacy.zip",
+ "cuda",
+ "b10798",
+ "published",
+ WINDOWS,
+ ),
+ ("app-b10798-mix-659e406-windows-x64-vulkan.zip", "vulkan", "b10798", "published", WINDOWS),
+ ("app-b10798-mix-659e406-windows-x64-rocm-gfx1150.zip", "rocm", "b10798", "published", WINDOWS),
+ (
+ "app-b10798-mix-659e406-windows-arm64-cpu.zip",
+ None,
+ "b10798",
+ "published",
+ WINDOWS_ARM64,
+ ),
+ # An older bundle, so the pass is not specific to one build number.
+ ("app-b10715-mix-86bd2d3-windows-x64-cpu.zip", None, "b10715", "published", WINDOWS),
+ # An upstream ggml-org archive: source = "upstream" takes a different branch through
+ # _windows_shared_groups.
+ ("llama-b10830-bin-win-cpu-x64.zip", None, "b10830", "upstream", WINDOWS),
+]
+
+
+def _marker_for(asset: str, backend: str | None, tag: str, source: str) -> dict:
+ """A marker as install_from_archives writes it, trimmed to the keys the probe reads: the
+ backend picks the install kinds, source and tag pick the group table."""
+ return {
+ "requested_tag": "latest",
+ "tag": tag,
+ "release_tag": tag,
+ "published_repo": "unslothai/llama.cpp",
+ "asset": asset,
+ "source": source,
+ "llama_backend": backend,
+ "force_cpu": backend is None,
+ "installed_at_utc": "2026-09-01T00:00:00Z",
+ }
+
+
+def _unpack_bundle(asset: str, backend, tag, source, host, into: Path) -> Path:
+ """Lay a release zip out the way the installer does and write its marker.
+
+ The Windows zips are flat, so ``build/bin/Release`` is the installer's choice and not
+ the archive's, which is why this mirrors install_runtime_dir rather than trusting
+ extractall to land things in the right place.
+ """
+ root = into / asset.replace(".zip", "")
+ runtime_dir = ILP.install_runtime_dir(root, host)
+ runtime_dir.mkdir(parents = True, exist_ok = True)
+ with zipfile.ZipFile(ASSET_DIR / asset) as archive:
+ archive.extractall(runtime_dir)
+ (root / "UNSLOTH_PREBUILT_INFO.json").write_text(
+ json.dumps(_marker_for(asset, backend, tag, source), indent = 2),
+ encoding = "utf-8",
+ )
+ return root
+
+
+ "asset,backend,tag,source,host",
+ BUNDLES,
+ ids = [entry[0].replace(".zip", "") for entry in BUNDLES],
+)
+def test_a_real_release_bundle_is_healthy(asset, backend, tag, source, host, tmp_path):
+ """A shipped bundle, extracted and marked, must not be called broken.
+
+ A false (False, reason) marks the install stale on the next launch and sends every user
+ through a repair with nothing to fix. Only the release itself can say whether the
+ payload globs match what is actually in the archive.
+ """
+ _asset_or_skip(asset)
+ root = _unpack_bundle(asset, backend, tag, source, host, tmp_path)
+ assert ILP.installed_runtime_health(root, host = host) == (True, ""), asset
+
+
+ "victim",
+ [
+ "llama.dll",
+ "llama-common.dll",
+ "llama-server-impl.dll",
+ "llama-quantize-impl.dll",
+ "ggml.dll",
+ "ggml-base.dll",
+ "mtmd.dll",
+ "llama-server.exe",
+ "llama-quantize.exe",
+ ],
+)
+def test_a_file_quarantined_from_a_real_windows_bundle_is_caught(victim, tmp_path):
+ """The other direction, on a real archive.
+
+ Windows ships one copy of each library, so removing a required file leaves nothing for
+ the glob to match. Linux is where that stops being true, below.
+ """
+ asset = "app-b10798-mix-659e406-windows-x64-cpu.zip"
+ _asset_or_skip(asset)
+ root = _unpack_bundle(asset, None, "b10798", "published", WINDOWS, tmp_path)
+ (ILP.install_runtime_dir(root, WINDOWS) / victim).unlink()
+ verdict = ILP.installed_runtime_health(root, host = WINDOWS)
+ assert verdict is not None and verdict[0] is False, victim
+ assert verdict[1] in {
+ "llama_runtime_payload_incomplete",
+ "llama_runtime_binaries_missing",
+ }, verdict
+
+
+def test_a_windows_cuda_bundle_without_its_paired_runtime_is_incomplete(tmp_path):
+ """The cudart trio lives in a second archive, and the marker records that pairing.
+
+ The real CUDA bundle ships no cudart64_*.dll of its own, so a marker naming a paired
+ runtime that is not on disk describes an install that cannot start. Asserted against the
+ real archive so the trio is genuinely absent rather than merely omitted from a fixture.
+ """
+ asset = "app-b10798-mix-659e406-windows-x64-cuda12-legacy.zip"
+ _asset_or_skip(asset)
+ root = _unpack_bundle(asset, "cuda", "b10798", "published", WINDOWS, tmp_path)
+ runtime_dir = ILP.install_runtime_dir(root, WINDOWS)
+ assert not list(runtime_dir.glob("cudart64_*.dll")), "the bundle is expected to ship no cudart"
+
+ marker = json.loads((root / "UNSLOTH_PREBUILT_INFO.json").read_text(encoding = "utf-8"))
+ marker["runtime_asset"] = "cudart-llama-bin-win-cuda-12.8-x64.zip"
+ (root / "UNSLOTH_PREBUILT_INFO.json").write_text(json.dumps(marker), encoding = "utf-8")
+ assert ILP.installed_runtime_health(root, host = WINDOWS) == (
+ False,
+ "llama_runtime_payload_incomplete",
+ )
+
+
+def test_the_real_cuda_bundle_carries_its_own_build_marker(tmp_path):
+ """UNSLOTH_PREBUILT_INFO.json exists inside the archive as well as at the install root.
+
+ Same name, different documents: the archive's copy is the build record and lands in the
+ runtime directory, while the installer writes the install record at the root.
+ load_prebuilt_metadata reads the root one, so a layout change putting the runtime
+ directory at the install root would grade the tree with the wrong table.
+ """
+ asset = "app-b10798-mix-659e406-windows-x64-cuda12-legacy.zip"
+ _asset_or_skip(asset)
+ root = _unpack_bundle(asset, "cuda", "b10798", "published", WINDOWS, tmp_path)
+ runtime_dir = ILP.install_runtime_dir(root, WINDOWS)
+ bundled = runtime_dir / "UNSLOTH_PREBUILT_INFO.json"
+ assert bundled.is_file(), "this bundle is expected to carry a build marker"
+ assert runtime_dir != root, "the build marker must not be able to shadow the install marker"
+ read_back = ILP.load_prebuilt_metadata(root)
+ assert read_back is not None and read_back.get("source") == "published"
+ assert "upstream_tag" not in read_back, "the install marker, not the archive's build record"
+
+
+# ---------------------------------------------------------------------------
+# The Windows layout contract.
+
+
+def test_every_windows_layout_decision_agrees_on_the_release_subdirectory():
+ """One directory, named the same way by all four places that name it.
+
+ A missing directory reports llama_runtime_dir_missing and marks the install stale, so a
+ probe deriving a different path than the installer writes to would repair every Windows
+ user on every launch. The agreement is the property, not the literal string.
+ """
+ root = Path("/install")
+ expected = root / "build" / "bin" / "Release"
+ assert ILP.install_runtime_dir(root, WINDOWS) == expected
+ assert ILP.install_runtime_dir(root, WINDOWS_ARM64) == expected
+ # Non-Windows never grows the subdirectory, or a Linux install reads as missing.
+ assert ILP.install_runtime_dir(root, LINUX) == root / "build" / "bin"
+
+
+def test_the_installer_creates_the_directory_the_probe_looks_for(tmp_path):
+ """Both builders of the tree the probe grades are checked against install_runtime_dir
+ rather than a literal path of their own."""
+ server, quantize = ILP.normalize_install_layout(tmp_path, WINDOWS)
+ runtime_dir = ILP.install_runtime_dir(tmp_path, WINDOWS)
+ assert runtime_dir.is_dir(), "the installer must create exactly the directory the probe reads"
+ assert server.parent == runtime_dir
+ assert quantize.parent == runtime_dir
+
+
+# ---------------------------------------------------------------------------
+# The managed install that is really on this machine.
+
+
+def _managed_install() -> Path | None:
+ root = ILP.default_managed_llama_dir()
+ return root if (root / "UNSLOTH_PREBUILT_INFO.json").is_file() else None
+
+
+def _managed_copy(tmp_path: Path) -> Path:
+ """A writable copy: these tests delete files and the machine's runtime is not theirs."""
+ source = _managed_install()
+ if source is None:
+ pytest.skip("no managed llama.cpp install on this machine")
+ destination = tmp_path / "managed"
+ shutil.copytree(source, destination, symlinks = True)
+ return destination
+
+
+def test_the_managed_install_on_this_machine_is_healthy():
+ """Read-only, against the install itself rather than a copy: the only sample available of
+ what the probe is actually asked about at launch.
+ """
+ root = _managed_install()
+ if root is None:
+ pytest.skip("no managed llama.cpp install on this machine")
+ assert ILP.installed_runtime_health(root) == (True, "")
+ # The default argument is the path preflight takes.
+ assert ILP.installed_runtime_health() == (True, "")
+
+
+def test_the_real_runtime_payload_has_no_dangling_symlinks():
+ """What the versioned library chain is actually made of, on a real install.
+
+ Not symlinks, the way a distribution packages a shared library: there is no unversioned
+ name at all, and the two versioned names are independent regular files of identical
+ size, so the "chain" is a duplicate rather than a link.
+
+ That decides what a payload glob can be trusted to mean. A symlink chain would let a
+ glob match a name whose target is gone; duplicates let it match a copy the loader does
+ not want. Either way no symlink here may dangle, since a match that resolves to nothing
+ is not a file the runtime can load.
+ """
+ root = _managed_install()
+ if root is None:
+ pytest.skip("no managed llama.cpp install on this machine")
+ runtime_dir = ILP.install_runtime_dir(root, ILP.platform_only_host())
+ dangling = [
+ path.name
+ for path in sorted(runtime_dir.iterdir())
+ if path.is_symlink() and not path.exists()
+ ]
+ assert dangling == [], f"the runtime payload must not contain dead links: {dangling}"
+
+
+def test_the_probe_reads_only_platform_facts():
+ """platform_only_host must agree with detect_host on every field the probe reads.
+
+ Skipping detect_host's second of nvidia-smi is allowed only while these fields are the
+ same either way, so drift here is a correctness bug and not just a slow launch.
+ """
+ cheap = ILP.platform_only_host()
+ probed = ILP.detect_host()
+ for field in (
+ "system",
+ "machine",
+ "is_windows",
+ "is_linux",
+ "is_macos",
+ "is_x86_64",
+ "is_arm64",
+ "macos_version",
+ ):
+ assert getattr(cheap, field) == getattr(probed, field), field
+
+
[email protected]("victim", ["llama-server", "llama-quantize"])
+def test_a_quarantined_binary_in_the_real_install_is_caught(victim, tmp_path):
+ """The executables are named outright rather than globbed, so a real tree behaves like a
+ fixture here."""
+ root = _managed_copy(tmp_path)
+ host = ILP.platform_only_host()
+ assert ILP.installed_runtime_health(root, host = host) == (True, ""), "copy must start healthy"
+ (ILP.install_runtime_dir(root, host) / victim).unlink()
+ assert ILP.installed_runtime_health(root, host = host) == (
+ False,
+ "llama_runtime_binaries_missing",
+ )
+
+
+def test_no_single_missing_file_in_the_real_install_causes_a_repair_loop(tmp_path):
+ """The one inequality the whole feature rests on, measured on a real tree.
+
+ A tree the probe calls broken must be one ``_existing_install_runs`` also refuses, or
+ the repair reinstalls nothing and the next launch rejects it again with no error to act
+ on. The matrix file asserts this over simulated trees; here every file in a real runtime
+ directory is removed in turn.
+ """
+ root = _managed_copy(tmp_path)
+ host = ILP.platform_only_host()
+ runtime_dir = ILP.install_runtime_dir(root, host)
+ vault = tmp_path / "vault"
+ vault.mkdir()
+ loops = []
+ for path in sorted(runtime_dir.iterdir()):
+ if not path.is_file():
+ continue
+ # Moved out rather than renamed: every payload pattern ends in a star, so a renamed
+ # file is still matched by its own group.
+ shutil.move(str(path), str(vault / path.name))
+ probe = ILP.installed_runtime_health(root, host = host)
+ if probe is not None and probe[0] is False and ILP._existing_install_runs(root, host):
+ loops.append((path.name, probe[1]))
+ shutil.move(str(vault / path.name), str(path))
+ assert loops == [], f"probe rejects trees the repair keeps, which is a repair loop: {loops}"
+
+
+def test_quarantining_a_soname_is_reported_broken(tmp_path):
+ """A real Linux install ships libllama.so.0 and libllama.so.0.0.<build> side by side.
+
+ The loader needs the SONAME, but the group ``libllama.so*`` also matches the versioned
+ copy, so quarantining the SONAME left the group satisfied: the probe answered Ready and
+ llama-server died at exec with a loader error. No fixture shows this, since a fixture
+ writes one file per library and a release writes two.
+
+ Fixed by _payload_match_is_loadable, which stops counting a name carrying more version
+ components than a SONAME can, since such a name is only ever the twin.
+ """
+ root = _managed_copy(tmp_path)
+ host = ILP.platform_only_host()
+ if host.is_windows or host.is_macos:
+ pytest.skip("versioned SONAME twins are a Linux packaging convention")
+ runtime_dir = ILP.install_runtime_dir(root, host)
+ soname = runtime_dir / "libllama.so.0"
+ twin = next(iter(runtime_dir.glob("libllama.so.0.*")), None)
+ if not soname.is_file() or twin is None:
+ pytest.skip("this install does not carry a versioned twin of libllama")
+
+ (tmp_path / "vault").mkdir(exist_ok = True)
+ shutil.move(str(soname), str(tmp_path / "vault" / soname.name))
+ assert twin.is_file(), "the twin is what keeps the glob satisfied"
+ verdict = ILP.installed_runtime_health(root, host = host)
+ assert (
+ verdict is not None and verdict[0] is False
+ ), f"a runtime missing its SONAME cannot load, but the probe said {verdict}"
+
+
+def test_the_soname_quarantine_really_breaks_the_runtime(tmp_path):
+ """Evidence that the case above is a defect and not a matter of taste: the binary the
+ desktop is about to start fails to load at exec. Run rather than asserted, because the
+ claim is about the loader and not about the code.
+ """
+ root = _managed_copy(tmp_path)
+ host = ILP.platform_only_host()
+ if host.is_windows or host.is_macos:
+ pytest.skip("versioned SONAME twins are a Linux packaging convention")
+ runtime_dir = ILP.install_runtime_dir(root, host)
+ server = runtime_dir / "llama-server"
+ soname = runtime_dir / "libllama.so.0"
+ if not server.is_file() or not soname.is_file():
+ pytest.skip("this install has no llama-server or no versioned libllama")
+
+ environment = {"LD_LIBRARY_PATH": str(runtime_dir), "PATH": "/usr/bin:/bin"}
+ try:
+ before = subprocess.run(
+ [str(server), "--version"],
+ capture_output = True,
+ timeout = 120,
+ env = environment,
+ )
+ except OSError as error:
+ pytest.skip(f"cannot exec the managed llama-server here: {error}")
+ if before.returncode != 0:
+ pytest.skip("the managed llama-server does not start on this machine to begin with")
+
+ (tmp_path / "vault").mkdir(exist_ok = True)
+ shutil.move(str(soname), str(tmp_path / "vault" / soname.name))
+ after = subprocess.run(
+ [str(server), "--version"],
+ capture_output = True,
+ timeout = 120,
+ env = environment,
+ )
+ assert after.returncode != 0, "removing the SONAME must break the binary, or there is no defect"
+ # No assertion on the probe's verdict here: that is the subject of the test above, and
+ # pinning it twice would make a fix edit two places.
+
+
+# ---------------------------------------------------------------------------
+# Desktop and CLI upgrade ordering. The two halves ship separately, so all four combinations
+# occur in the field. managed.rs covers the desktop half; checkable here is the CLI half:
+# the payload carries the keys, and a probe that cannot answer says null rather than false.
+
+
+def test_the_capability_cache_on_this_machine_is_the_shape_the_new_reader_expects():
+ """The real desktop_capability_cache.json, if the desktop has ever run here.
+
+ The Rust side reconstructs a previous-release cache entry from its author's memory of
+ what the old writer emitted, so this asserts the same three properties against a file
+ that release actually wrote: an older schema, no top-level llama_runtime key, and no
+ llama_runtime_ok in the cached capability.
+
+ The schema bump alone is what makes the miss safe. Without it, an entry whose runtime
+ fingerprint compares equal, which an install with no managed runtime produces, would be
+ served back with a Ready verdict reached before the runtime was looked at.
+ """
+ cache = Path.home() / ".unsloth" / "studio" / "desktop_capability_cache.json"
+ if not cache.is_file():
+ pytest.skip("the desktop has never written a capability cache on this machine")
+ entry = json.loads(cache.read_text(encoding = "utf-8"))
+ schema = entry.get("schema")
+ if schema is None or schema >= 4:
+ pytest.skip(f"this cache was written by the new desktop already (schema {schema})")
+ assert "llama_runtime" not in entry, "a pre-bump entry cannot carry the runtime fingerprint"
+ assert "llama_runtime_ok" not in entry.get(
+ "capability", {}
+ ), "a pre-bump entry cannot carry a runtime verdict"
+ # Named individually, not compared as a set: a dropped key is a silent loss, an extra
+ # key is harmless.
+ for required in (
+ "schema",
+ "bin_path",
+ "bin_size",
+ "bin_mtime_ms",
+ "studio_root_id",
+ "marker_path",
+ "marker_size",
+ "marker_mtime_ms",
+ "desktop_protocol_version",
+ "desktop_manageability_version",
+ "capability",
+ ):
+ assert required in entry, required
+
+
+def test_the_capability_payload_names_the_runtime_keys():
+ """A new desktop asked an old CLI gets no llama_runtime_ok, which it reads as "cannot
+ answer", so a new CLI has to know both key names.
+
+ Only the names, not the literal that sets them: which installs the CLI reports health
+ for is policy, while renaming a key breaks the wire contract with every shipped desktop.
+ """
+ source = (PACKAGE_ROOT / "unsloth_cli" / "commands" / "studio.py").read_text(encoding = "utf-8")
+ assert "llama_runtime_ok" in source
+ assert "llama_runtime_reason" in source
+
+
+def test_a_probe_that_raises_leaves_the_runtime_unknown(monkeypatch):
+ """The CLI fills the keys best effort, so a probe that throws must leave the null in
+ place. False would repair a runtime whose only fault was that the check failed."""
+ payload = {"llama_runtime_ok": None, "llama_runtime_reason": ""}
+
+ def explode(*args, **kwargs):
+ raise RuntimeError("probe failed")
+
+ monkeypatch.setattr(ILP, "installed_runtime_health", explode)
+ try:
+ health = ILP.installed_runtime_health()
+ if health is not None:
+ payload["llama_runtime_ok"], payload["llama_runtime_reason"] = health
+ except Exception:
+ pass
+ assert payload == {"llama_runtime_ok": None, "llama_runtime_reason": ""}
+
+
+def test_nothing_installed_leaves_the_runtime_unknown(tmp_path):
+ """The same null for a different reason: no marker means NotInstalled, not a broken
+ runtime, so the probe returns None and the CLI leaves the key untouched."""
+ assert ILP.installed_runtime_health(tmp_path / "nothing-here") is None
+
+
[email protected]("victim", ["libllama-server-impl.so", "libllama-quantize-impl.so"])
+def test_quarantining_a_split_entrypoint_library_is_reported_broken(victim, tmp_path):
+ """The other half of the upstream impl split, on the side that had no group for it.
+
+ ``llama-server`` and ``llama-quantize`` carry no entry code of their own since
+ ggml-org/llama.cpp#23462; they load ``libllama-server-impl.so`` and
+ ``libllama-quantize-impl.so`` by DT_NEEDED. The payload groups named the shared
+ libraries only, so removing one of these left every group satisfied while the binary
+ the desktop is about to start died in the loader: the probe answered Ready and
+ ``_existing_install_runs`` answered false, which is the disagreement this feature
+ exists to remove. Windows already required its ``llama-server-impl.dll``; Linux did
+ not require either of its two.
+ """
+ root = _managed_copy(tmp_path)
+ host = ILP.platform_only_host()
+ if not host.is_linux:
+ pytest.skip("the impl split libraries are the Linux and Windows names, not macOS")
+ runtime_dir = ILP.install_runtime_dir(root, host)
+ library = runtime_dir / victim
+ if not library.is_file():
+ pytest.skip(f"this install predates the impl split: no {victim}")
+ assert ILP.installed_runtime_health(root, host = host) == (True, ""), "copy must start healthy"
+
+ (tmp_path / "vault").mkdir(exist_ok = True)
+ shutil.move(str(library), str(tmp_path / "vault" / victim))
+ verdict = ILP.installed_runtime_health(root, host = host)
+ assert (
+ verdict is not None and verdict[0] is False
+ ), f"a runtime missing {victim} cannot load, but the probe said {verdict}"
+ # And the two answers still agree, which is the property that keeps repair from looping.
+ assert ILP._existing_install_runs(root, host) is False
+
+
+def test_an_older_monolithic_linux_release_is_not_asked_for_the_impl_libraries():
+ """The gate, not just the requirement.
+
+ An archive from before the split ships no ``lib*-impl.so`` at all, so requiring one
+ would reinstall it on every check forever. Same build number as the Windows side, and
+ for the same reason: it is one upstream commit, not one platform's packaging.
+ """
+ before = ILP.runtime_payload_health_groups("linux-cuda", source_label = "published", tag = "b9279")
+ after = ILP.runtime_payload_health_groups("linux-cuda", source_label = "published", tag = "b9283")
+ flat_before = {pattern for group in before for pattern in group}
+ flat_after = {pattern for group in after for pattern in group}
+ assert "libllama-server-impl.so*" not in flat_before
+ assert "libllama-quantize-impl.so*" not in flat_before
+ assert "libllama-server-impl.so*" in flat_after
+ assert "libllama-quantize-impl.so*" in flat_after
+ # A source build ships neither, whatever the tag says.
+ source_built = ILP.runtime_payload_health_groups(
+ "linux-cuda", source_label = "source", tag = "b10360"
+ )
+ assert not any("impl" in pattern for group in source_built for pattern in group)
+
+
+def test_a_stripped_execute_bit_is_not_reused_as_an_exact_release_match(tmp_path):
+ """The keep-or-reinstall decision has to reject what the probe rejects.
+
+ ``installed_runtime_health`` asks for the execute bit, because that is what
+ ``_find_llama_server_binary`` asks for. ``existing_install_matches_choice`` asked only
+ ``exists()``, and its Linux ``ldd`` gate reads a non-executable ELF quite happily, so a
+ cleared bit produced: preflight says broken, repair says the exact release is already
+ installed, nothing is downloaded, and the next launch says broken again. Checked
+ against the two gates directly, since the surrounding function also wants a matching
+ fingerprint that this test has no business reconstructing.
+ """
+ root = _managed_copy(tmp_path)
+ host = ILP.platform_only_host()
+ if host.is_windows:
+ pytest.skip("there is no execute bit to clear on Windows")
+ runtime_dir = ILP.install_runtime_dir(root, host)
+ server = runtime_dir / "llama-server"
+ if not server.is_file():
+ pytest.skip("this install has no llama-server")
+
+ mode = server.stat().st_mode
+ server.chmod(mode & ~0o111)
+ try:
+ assert ILP.installed_runtime_health(root, host = host) == (
+ False,
+ "llama_runtime_binaries_missing",
+ )
+ assert ILP._existing_install_runs(root, host) is False
+ # The old gate, which is what let the two disagree.
+ assert server.exists(), "the file is still there, which is the whole point"
+ # The new one, shared with both answers above.
+ assert ILP._entrypoint_is_runnable(server, host) is False
+ finally:
+ server.chmod(mode)
+
+
+# The bundle that changed the packaging. b10360 shipped two names per library and no
+# versionless one; b10840 ships libllama.so -> libllama.so.0 -> libllama.so.0.4.0 as
+# symlinks, and copy_globs flattens all three into regular files, because it selects
+# with is_file() and copies with shutil.copy2, which follows links.
+_TRIO_ASSET = "app-b10840-mix-d5c17a0-linux-x64-cpu.tar.gz"
+_TRIO_TAG = "b10840-mix-d5c17a0"
+
+
+def _installed_trio_bundle(tmp_path: Path) -> Path:
+ """The b10840 CPU bundle, installed the way install_prebuilt installs it.
+
+ Through ``copy_globs`` rather than by moving the extracted tree: moving preserves
+ the symlinks, and a tree of links behaves quite differently here, since removing
+ the SONAME makes the versionless link dangle and ``is_file()`` drops it on its own.
+ A real install has no links left to dangle, which is the whole point of this test.
+ """
+ archive = _asset_or_skip(_TRIO_ASSET)
+ prebuilt_core = _load_prebuilt_core()
+ if prebuilt_core is None:
+ pytest.skip("prebuilt_core is not importable here")
+ host = ILP.platform_only_host()
+ if not host.is_linux:
+ pytest.skip("a linux bundle installs into the linux layout")
+
+ raw = tmp_path / "raw"
+ prebuilt_core.extract_archive(archive, raw)
+ root = tmp_path / "llama.cpp"
+ runtime_dir = ILP.install_runtime_dir(root, host)
+ ILP.copy_globs(
+ raw,
+ runtime_dir,
+ ["llama-server", "llama-quantize", "llama-diffusion-gemma-visual-server", "lib*.so*"],
+ required = True,
+ )
+ for name in ("llama-server", "llama-quantize"):
+ binary = runtime_dir / name
+ binary.chmod(0o755)
+ shutil.copy2(binary, root / name)
+ (root / name).chmod(0o755)
+ (root / "convert_hf_to_gguf.py").write_text("", encoding = "utf-8")
+ (root / "gguf-py").mkdir(exist_ok = True)
+ (root / "UNSLOTH_PREBUILT_INFO.json").write_text(
+ json.dumps(
+ {
+ "release_tag": _TRIO_TAG,
+ "tag": _TRIO_TAG,
+ "source": "published",
+ "backend": "cpu",
+ "asset": _TRIO_ASSET,
+ }
+ )
+ + "\n",
+ encoding = "utf-8",
+ )
+ return root
+
+
+def _load_prebuilt_core():
+ module_path = PACKAGE_ROOT / "studio" / "prebuilt_core.py"
+ if not module_path.is_file():
+ return None
+ spec = importlib.util.spec_from_file_location("studio_prebuilt_core_for_tests", module_path)
+ if spec is None or spec.loader is None:
+ return None
+ module = importlib.util.module_from_spec(spec)
+ sys.modules[spec.name] = module
+ spec.loader.exec_module(module)
+ return module
+
+
+def test_the_flattened_trio_installs_healthy(tmp_path):
+ """The shape itself must not read as broken, or every b10840 install repairs forever."""
+ root = _installed_trio_bundle(tmp_path)
+ host = ILP.platform_only_host()
+ runtime_dir = ILP.install_runtime_dir(root, host)
+ for name in ("libllama.so", "libllama.so.0", "libllama.so.0.4.0"):
+ path = runtime_dir / name
+ assert path.is_file() and not path.is_symlink(), (
+ f"{name} must be a flattened regular file, or this test is not measuring "
+ "what the installer produces"
+ )
+ assert ILP.installed_runtime_health(root, host = host) == (True, "")
+
+
+ "victim",
+ ["libllama.so.0", "libggml.so.0", "libllama-common.so.0", "libggml-base.so.0", "libmtmd.so.0"],
+)
+def test_quarantining_a_soname_beside_a_versionless_copy_is_reported_broken(victim, tmp_path):
+ """Codex 3962583748, P1. The case my earlier rebuttal got wrong.
+
+ I checked the managed install on the machine, which is b10360: two names per
+ library, no versionless one, so removing the SONAME left nothing that could
+ satisfy the group. b10840 ships a third name, and after copy_globs it is a regular
+ file rather than a link onto the SONAME, so the group stayed satisfied by a file
+ the loader never asks for while llama-server died at exec.
+
+ Measured, before the fix, on this bundle: every one of these left
+ installed_runtime_health answering (True, "") with _existing_install_runs false.
+ """
+ root = _installed_trio_bundle(tmp_path)
+ host = ILP.platform_only_host()
+ runtime_dir = ILP.install_runtime_dir(root, host)
+ soname = runtime_dir / victim
+ if not soname.is_file():
+ pytest.skip(f"this bundle does not carry {victim}")
+ versionless = runtime_dir / f"{victim[: victim.index('.so')]}.so"
+ assert versionless.is_file(), "the versionless twin is what used to keep the group satisfied"
+
+ (tmp_path / "vault").mkdir(exist_ok = True)
+ shutil.move(str(soname), str(tmp_path / "vault" / victim))
+ verdict = ILP.installed_runtime_health(root, host = host)
+ assert (
+ verdict is not None and verdict[0] is False
+ ), f"a runtime missing {victim} cannot load, but the probe said {verdict}"
+ # The two answers still agree, which is what keeps repair from looping.
+ assert ILP._existing_install_runs(root, host) is False
+
+
+def test_a_family_that_only_ever_ships_one_name_is_still_loadable(tmp_path):
+ """The other half, and the one a blunter rule would break.
+
+ libggml-cpu-x64.so has no versioned copy anywhere, so the versionless name IS the
+ one the loader asks for. Requiring a SONAME of every library would call every
+ install broken and reinstall on each check forever. No artifact needed.
+ """
+ runtime_dir = tmp_path / "bin"
+ runtime_dir.mkdir()
+ lonely = runtime_dir / "libggml-cpu-x64.so"
+ lonely.write_bytes(b"ELF")
+ assert ILP._payload_match_is_loadable(lonely) is True
+
+ # Same name, now with a versioned sibling: it is the family that decides.
+ versioned = runtime_dir / "libggml-cpu-x64.so.0"
+ versioned.write_bytes(b"ELF")
+ assert ILP._payload_match_is_loadable(lonely) is False
+ assert ILP._payload_match_is_loadable(versioned) is True
+ assert ILP._family_base("libggml-cpu-x64.so.0.19.0") == "libggml-cpu-x64"
+ # A neighbour of a different family must not vote.
+ other = runtime_dir / "libggml-cpu-x64-extra.so"
+ other.write_bytes(b"ELF")
+ assert ILP._family_base(other.name) == "libggml-cpu-x64-extra"
+
+
+def test_the_macos_install_name_rule_matches_the_linux_one(tmp_path):
+ """dyld asks for libggml.0.dylib, the install name recorded in LC_ID_DYLIB, so the
+ versionless link is not a substitute there either, and a bundle that ships only
+ libggml.dylib still is."""
+ runtime_dir = tmp_path / "bin"
+ runtime_dir.mkdir()
+ versionless = runtime_dir / "libggml.dylib"
+ versionless.write_bytes(b"MACHO")
+ assert ILP._payload_match_is_loadable(versionless) is True
+ install_name = runtime_dir / "libggml.0.dylib"
+ install_name.write_bytes(b"MACHO")
+ terminal = runtime_dir / "libggml.0.23.0.dylib"
+ terminal.write_bytes(b"MACHO")
+ assert ILP._payload_match_is_loadable(versionless) is False
+ assert ILP._payload_match_is_loadable(install_name) is True
+ assert ILP._payload_match_is_loadable(terminal) is False
diff --git a/tests/studio/install/test_llama_runtime_repair_convergence.py b/tests/studio/install/test_llama_runtime_repair_convergence.py
new file mode 100644
index 00000000000..f2ae618c153
--- /dev/null
+++ b/tests/studio/install/test_llama_runtime_repair_convergence.py
@@ -0,0 +1,772 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Does ``probe -> repair -> probe`` terminate? The dynamic half of the launch preflight.
+
+``test_installed_runtime_health_matrix`` proves a STATIC implication: no damaged tree is
+rejected by ``installed_runtime_health`` and kept by ``_existing_install_runs``. Necessary,
+not sufficient. The repair is not ``_existing_install_runs`` but the whole chain ``unsloth
+studio update`` -> ``setup.sh`` / ``setup.ps1`` -> ``install_llama_prebuilt.py``, and the
+decision to leave the tree alone is taken in three places along it, so the implication can
+hold while the cycle still makes no progress.
+
+So this file simulates the launch cycle as a state machine over real trees on disk:
+
+ probe installed_runtime_health(tree, host = host), the real function.
+ repair one of three models, each named after the branch of the real chain it stands for.
+ state the tree itself, fingerprinted so "the repair changed nothing" is observable.
+
+The three repair models:
+
+ ONLINE the listing is reachable, so ``install_prebuilt`` either records the reused
+ selection (``sync_marker_selection``, which REWRITES the marker the next probe
+ reads) or installs a fresh bundle. Modelled by calling the real
+ ``existing_install_matches_plan`` and ``sync_marker_selection``.
+ OFFLINE the listing raised, so the ``PrebuiltFallback`` handler's
+ ``_existing_install_runs`` gate KEEPS a complete tree. Not modelled: the real
+ ``install_prebuilt`` is called with the listing broken and its exit code read.
+ OFFLINE+SH the same, continued into the shell: EXIT_FALLBACK sets
+ ``_NEED_LLAMA_SOURCE_BUILD`` and the source-build stage may skip the rebuild.
+ That guard is the one place in the chain where a tree the probe rejects can be
+ left byte for byte identical.
+
+The marker is an axis of its own rather than one more damage, since the probe reads it and
+``sync_marker_selection`` writes it, so it is the one piece of state that could carry a cycle.
+Every damage is therefore also run with a marker that does not parse: the probe grades those
+trees, and grading them must not reject anything ``_existing_install_runs`` would keep.
+
+Fixtures, marker shapes and payload tables come from
+``test_installed_runtime_health_matrix`` rather than being restated, so the state machine runs
+over exactly the trees the static invariant was proved over. WSL is not a fourth platform:
+``platform.system()`` reports ``Linux`` there, so it is graded by the Linux rows.
+"""
+
+import hashlib
+import os
+import shutil
+import sys
+import urllib.error
+from pathlib import Path
+
+import pytest
+
+# The fixture module execs studio/install_llama_prebuilt.py and caches it in sys.modules.
+# Taking ILP from it keeps the monkeypatched and the probed module the same object.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import test_installed_runtime_health_matrix as MF # noqa: E402
+
+ILP = MF.ILP
+
+# Three platforms. The arm64 rows are dropped because the payload intersection is picked by
+# the platform prefix, so they walk the same rows as their x64 twins, and each step costs a
+# real install_prebuilt call.
+HOSTS = [
+ ("linux", MF.LINUX),
+ ("windows", MF.WINDOWS),
+ ("macos", MF.MACOS_ARM64),
+]
+# "metal" is dropped for the same reason: a metal marker on Linux only re-tests the fall-open
+# path the static file already pins.
+BACKENDS = ["cpu", "cuda", "rocm", "vulkan"]
+# A spread of shipped shapes rather than all thirteen: the ones differing in what the deciders
+# read (no release_tag, no fingerprint, no backend key, a legacy vulkan override, a rocm arch,
+# today's shape, and a marker a real run produced).
+SHAPES = [
+ ("S1", MF.S1),
+ ("S2", MF.S2),
+ ("S6", MF.S6),
+ ("S8", MF.S8),
+ ("S11", MF.S11),
+ ("S12", MF.S12),
+ ("S12real", MF.S12_REAL),
+]
+
+CELLS = [
+ (f"{host_id}-{backend}-{shape_id}", host, backend, shape)
+ for host_id, host in HOSTS
+ for backend in BACKENDS
+ for shape_id, shape in SHAPES
+]
+CELL_IDS = [cell[0] for cell in CELLS]
+
+# The install kind a fresh install lands on per host and backend. macOS publishes one
+# universal Metal bundle, so its backend axis is a marker carried in from elsewhere and the
+# plan below is the Metal one whatever the marker says.
+_INSTALL_KIND = {
+ ("linux", "cpu"): "linux-cpu",
+ ("linux", "cuda"): "linux-cuda",
+ ("linux", "rocm"): "linux-rocm",
+ ("linux", "vulkan"): "linux-vulkan",
+ ("windows", "cpu"): "windows-cpu",
+ ("windows", "cuda"): "windows-cuda",
+ ("windows", "rocm"): "windows-rocm",
+ ("windows", "vulkan"): "windows-vulkan",
+}
+
+
+# ---------------------------------------------------------------------------
+# State
+
+
+def fingerprint(root: Path) -> str:
+ """A digest of everything the probe and the keep path can see.
+
+ Names, sizes and mode bits plus the marker's bytes, which is enough to tell "rewrote the
+ marker" and "replaced the tree" apart from "did nothing".
+
+ Directory sizes are excluded: on ext4 a directory's ``st_size`` grows with the entries it
+ has ever held, so an identical tree rebuilt in a reused path would hash differently.
+ """
+ digest = hashlib.sha256()
+ if not root.exists():
+ return "absent"
+ for path in sorted(root.rglob("*")):
+ stat = path.lstat()
+ digest.update(str(path.relative_to(root)).encode("utf-8"))
+ size = "dir" if path.is_dir() else str(stat.st_size)
+ digest.update(f"{path.is_dir()}:{size}:{stat.st_mode & 0o777}".encode("utf-8"))
+ marker = root / "UNSLOTH_PREBUILT_INFO.json"
+ if marker.is_file():
+ digest.update(marker.read_bytes())
+ return digest.hexdigest()
+
+
+def probe(root: Path, host) -> tuple[bool, str] | None:
+ return ILP.installed_runtime_health(root, host = host)
+
+
+# ---------------------------------------------------------------------------
+# The plan a reachable release listing would produce, and the tree it installs
+
+
+def _platform_of(host) -> str:
+ return "windows" if host.is_windows else "macos" if host.is_macos else "linux"
+
+
+def current_marker(host, backend: str) -> dict:
+ """The marker a fresh install of today's release writes for this cell.
+
+ Built off the shipped S12 shape so it stays real, then stamped with the fingerprint
+ ``existing_install_matches_choice`` recomputes, which is what makes the freshly installed
+ tree a fixed point rather than something the next cycle reinstalls.
+ """
+ platform = _platform_of(host)
+ kind = "macos-arm64" if platform == "macos" else _INSTALL_KIND[(platform, backend)]
+ marker = {
+ **MF.S12,
+ "requested_tag": "latest",
+ "tag": "b10698",
+ "release_tag": "b10698-mix-67dfc8b",
+ "published_repo": "unslothai/llama.cpp",
+ "asset": MF._ASSET_TOKEN[backend],
+ "asset_sha256": "d4" * 32,
+ "backend": ILP.backend_for_install_kind(kind),
+ "backend_request": "auto",
+ "source": "published",
+ "runtime_asset": None,
+ "runtime_line": None,
+ "bundle_profile": None,
+ "coverage_class": None,
+ "llama_backend": None,
+ }
+ marker["install_fingerprint"] = ILP.expected_install_fingerprint(
+ llama_tag = marker["tag"],
+ release_tag = marker["release_tag"],
+ choice = _choice(marker, kind),
+ approved_checksums = _checksums(marker),
+ )
+ return marker
+
+
+def _choice(marker: dict, install_kind: str):
+ return ILP.AssetChoice(
+ repo = marker["published_repo"],
+ tag = marker["tag"],
+ name = marker["asset"],
+ url = f"https://example.invalid/{marker['asset']}",
+ source_label = marker["source"],
+ install_kind = install_kind,
+ bundle_profile = marker["bundle_profile"],
+ runtime_line = marker["runtime_line"],
+ coverage_class = marker["coverage_class"],
+ expected_sha256 = marker["asset_sha256"],
+ runtime_name = marker["runtime_asset"],
+ )
+
+
+def _checksums(marker: dict):
+ return ILP.ApprovedReleaseChecksums(
+ repo = marker["published_repo"],
+ release_tag = marker["release_tag"],
+ upstream_tag = marker["tag"],
+ )
+
+
+def current_plan(host, backend: str) -> tuple[object, dict]:
+ """``(plan, marker)`` for the release a reachable listing would offer this cell."""
+ platform = _platform_of(host)
+ kind = "macos-arm64" if platform == "macos" else _INSTALL_KIND[(platform, backend)]
+ marker = current_marker(host, backend)
+ plan = ILP.InstallReleasePlan(
+ requested_tag = "latest",
+ llama_tag = marker["tag"],
+ release_tag = marker["release_tag"],
+ attempts = [_choice(marker, kind)],
+ approved_checksums = _checksums(marker),
+ )
+ return plan, marker
+
+
+def install_fresh_prebuilt(root: Path, host, backend: str) -> None:
+ """Replace ``root`` with what ``activate_install_tree`` leaves behind for this cell."""
+ if root.exists():
+ shutil.rmtree(root)
+ MF.build_tree(root, host = host, marker = current_marker(host, backend), backend = backend)
+
+
+def install_fresh_source_build(root: Path, host) -> None:
+ """Replace ``root`` with what setup.sh's source-build swap leaves behind.
+
+ Markerless, and load-bearing rather than a simplification: the swap is ``rm -rf`` then
+ ``mv``, so ``UNSLOTH_PREBUILT_INFO.json`` cannot survive it and the next probe reads
+ "nothing installed" instead of judging a source build by a prebuilt payload table. A swap
+ that preserved the marker would be a loop of its own.
+ """
+ if root.exists():
+ shutil.rmtree(root)
+ MF.build_tree(root, host = host, marker = None, backend = "cpu")
+
+
+# ---------------------------------------------------------------------------
+# The three repair models
+
+
+def offline(monkeypatch):
+ """Make the release listing fail the way a dropped connection does, and silence the log.
+
+ Same technique as ``test_keep_install_backcompat_9979._transient_listing_failure``. The
+ muting is not cosmetic: the cycle runs install_prebuilt thousands of times, each printing
+ a paragraph.
+ """
+
+ def boom(*args, **kwargs):
+ raise urllib.error.URLError("connection reset")
+
+ monkeypatch.setattr(ILP, "_fork_manifest_release_plans", boom)
+ monkeypatch.setattr(ILP, "collect_system_report", lambda *a, **k: "report")
+ monkeypatch.setattr(ILP, "log", lambda *a, **k: None)
+ monkeypatch.setattr(ILP, "log_lines", lambda *a, **k: None)
+ return monkeypatch
+
+
+def offline_repair(root: Path, host, monkeypatch, *, shell_stage: bool) -> str:
+ """The OFFLINE branch, run for real, optionally continued into setup.sh.
+
+ ``install_prebuilt`` returning is the keep; ``EXIT_FALLBACK`` is the source fallback
+ setup.sh acts on; anything else stops the update with a message the user sees.
+ """
+ monkeypatch.setattr(ILP, "detect_host", lambda *a, **k: host)
+ try:
+ ILP.install_prebuilt(root, "latest", "unslothai/llama.cpp", "")
+ return "python-kept"
+ except SystemExit as exc:
+ code = exc.code
+ if code != ILP.EXIT_FALLBACK:
+ # Exit 1/3/5 all reach setup_fail, so the update stops and says why. The tree stays
+ # broken, but the user has an error to act on, which is not the loop being hunted.
+ return f"aborted-exit{code}"
+ if not shell_stage:
+ install_fresh_source_build(root, host)
+ return "source-rebuilt"
+ # setup.sh's source-build stage keeps a reusable local build instead of rebuilding. The
+ # executable test used to be the whole condition, which kept every tree that had lost only
+ # a library; reusable_existing_install is the gate the shell now asks first. Defaults
+ # assumed: no UNSLOTH_LLAMA_FORCE_COMPILE, no UNSLOTH_LLAMA_PR.
+ #
+ # Both shells, because both have a reuse shortcut. This comment used to say setup.ps1
+ # had none and that a Windows update reaching the source stage always builds; that was
+ # wrong, and the mistake is what let the Windows half of this loop survive (Codex
+ # 3963478816). setup.ps1's shortcut is an elseif on Test-PathQuiet $LlamaServerBin, so
+ # on Windows the entrypoint test is llama-server.exe under build/bin/Release, and the
+ # gate it now asks first is Test-LlamaTreeStillHealthy, which is the same
+ # --check-existing-install call the shell makes.
+ if host.is_windows:
+ entrypoints = [root / "build" / "bin" / "Release" / "llama-server.exe"]
+ reusable = ILP.reusable_existing_install(root, host) and all(
+ path.is_file() for path in entrypoints
+ )
+ else:
+ reusable = ILP.reusable_existing_install(root, host) and all(
+ os.access(root / "build" / "bin" / f"llama-{name}", os.X_OK)
+ for name in ("server", "quantize")
+ )
+ if reusable:
+ return "shell-kept"
+ install_fresh_source_build(root, host)
+ return "source-rebuilt"
+
+
+def online_repair(root: Path, host, backend: str) -> str:
+ """The reachable-plan branch: keep and re-record the selection, or reinstall."""
+ plan, _ = current_plan(host, backend)
+ if ILP.existing_install_matches_plan(root, host, plan):
+ # The keep is not a no-op: it rewrites the marker, which is an input to the next
+ # probe, so a keep could hand the probe a tree it then rejects.
+ ILP.sync_marker_selection(
+ root,
+ choice = plan.attempts[0],
+ backend_request = "auto",
+ persist_force_cpu = False,
+ persist_llama_backend = None,
+ ggml_tree = None,
+ rocm_gfx = None,
+ )
+ return "kept"
+ install_fresh_prebuilt(root, host, backend)
+ return "reinstalled"
+
+
+# ---------------------------------------------------------------------------
+# The cycle
+
+
+MAX_CYCLES = 6
+
+
+def run_cycle(
+ root: Path,
+ host,
+ repair,
+ *,
+ max_cycles: int = MAX_CYCLES,
+):
+ """Iterate ``probe -> repair`` and classify how it ends.
+
+ ``converged`` the probe stopped rejecting: healthy, or nothing installed.
+ ``aborted`` the repair refused and told the user why. Terminating, not silent.
+ ``loop`` the probe rejects and the repair left the tree identical. The bug.
+ ``diverged`` still rejecting after ``max_cycles`` repairs that each changed something.
+ """
+ trail: list[str] = []
+ for cycles in range(max_cycles + 1):
+ verdict = probe(root, host)
+ if verdict is None or verdict[0]:
+ return "converged", cycles, trail
+ if cycles == max_cycles:
+ return "diverged", cycles, trail
+ before = fingerprint(root)
+ action = repair(root)
+ trail.append(action)
+ if action.startswith("aborted"):
+ return "aborted", cycles + 1, trail
+ if fingerprint(root) == before:
+ return "loop", cycles + 1, trail
+ raise AssertionError("unreachable")
+
+
+def damage_modes(host, backend: str, marker: dict) -> list[tuple[str, object]]:
+ """Every way the shipped code says a tree can rot, plus two damages at once.
+
+ A ``str`` removes that file, a ``tuple`` removes several, and the ``@`` constants name a
+ structural loss instead.
+ """
+ platform = _platform_of(host)
+ ext = ".exe" if host.is_windows else ""
+ server, quantize = f"llama-server{ext}", f"llama-quantize{ext}"
+ libraries = [
+ name
+ for name in MF.required_runtime_files(platform, backend, marker)
+ if name not in {server, quantize}
+ ]
+ modes: list[tuple[str, object]] = [(f"remove-{name}", name) for name in libraries]
+ modes += [
+ ("remove-server", server),
+ ("remove-quantize", quantize),
+ ("remove-both-entrypoints", (server, quantize)),
+ # Two at once, since quarantine takes whole signatures rather than one file.
+ ("remove-server-and-library", (server, libraries[0])),
+ ("remove-first-and-last-library", (libraries[0], libraries[-1])),
+ ("remove-runtime-dir", "@runtime-dir"),
+ ("remove-tree", "@tree"),
+ ("remove-marker", "@marker"),
+ ("corrupt-marker", "@corrupt-marker"),
+ # A corrupt marker with an incomplete payload: does the damage under it still get
+ # seen.
+ ("corrupt-marker-and-library", "@corrupt-marker+library"),
+ ]
+ return modes
+
+
+# The damages that already decide the marker's fate, so pairing them with "and the marker is
+# corrupt too" is a no-op or a different damage under the same name.
+_MARKER_DAMAGES = {"@tree", "@marker", "@corrupt-marker", "@corrupt-marker+library"}
+
+
+def build_damaged(
+ root: Path,
+ host,
+ backend: str,
+ marker: dict,
+ damage,
+ *,
+ corrupt = False,
+) -> Path:
+ """A complete tree of this cell, then ``damage`` applied to it.
+
+ ``corrupt`` also replaces the marker with bytes that do not parse, the axis worth crossing
+ with every other damage rather than testing on its own.
+ """
+ MF.build_tree(root, host = host, marker = marker, backend = backend)
+ runtime = MF._runtime_dir(root, host)
+ if corrupt:
+ (root / "UNSLOTH_PREBUILT_INFO.json").write_text("{not json", encoding = "utf-8")
+ if damage == "@tree":
+ shutil.rmtree(root)
+ elif damage == "@runtime-dir":
+ shutil.rmtree(runtime)
+ elif damage == "@marker":
+ (root / "UNSLOTH_PREBUILT_INFO.json").unlink()
+ elif damage == "@corrupt-marker":
+ (root / "UNSLOTH_PREBUILT_INFO.json").write_text("{not json", encoding = "utf-8")
+ elif damage == "@corrupt-marker+library":
+ (root / "UNSLOTH_PREBUILT_INFO.json").write_text("{not json", encoding = "utf-8")
+ platform = _platform_of(host)
+ (runtime / MF._SHARED_PAYLOAD[platform][0]).unlink()
+ elif isinstance(damage, tuple):
+ for name in damage:
+ (runtime / name).unlink()
+ else:
+ (runtime / str(damage)).unlink()
+ return root
+
+
+# ---------------------------------------------------------------------------
+# The online model
+
+
[email protected](("cell", "host", "backend", "shape"), CELLS, ids = CELL_IDS)
+def test_the_online_repair_reaches_a_fixed_point_from_every_damaged_tree(
+ tmp_path, cell, host, backend, shape
+):
+ """Reachable listing: one reinstall, and its result is a fixed point. A second cycle would
+ mean the installer writes a tree its own probe rejects, a permanent loop for every user.
+ """
+ marker = MF.shape_with_backend(shape, backend)
+ for label, damage in damage_modes(host, backend, marker):
+ root = build_damaged(tmp_path / label, host, backend, marker, damage)
+ outcome, cycles, trail = run_cycle(
+ root, host, lambda tree: online_repair(tree, host, backend)
+ )
+ assert outcome == "converged", f"{cell}/{label}: {outcome} after {cycles} ({trail})"
+ assert cycles <= 1, f"{cell}/{label}: took {cycles} repairs ({trail})"
+
+
[email protected](("cell", "host", "backend", "shape"), CELLS, ids = CELL_IDS)
+def test_the_online_keep_never_rewrites_the_marker_into_a_tree_it_then_rejects(
+ tmp_path, cell, host, backend, shape
+):
+ """``sync_marker_selection`` runs on every keep and the marker it writes is the next
+ probe's input. ``runtime_asset`` is the dangerous key: it turns the Windows cudart trio
+ from optional into required, so stamping it onto a pair-less tree would reject on the next
+ launch. Cycled from the already-healthy tree, the state a keep is reached from."""
+ del shape # the keep path is only reachable from the marker the current plan describes
+ root = tmp_path / "healthy"
+ install_fresh_prebuilt(root, host, backend)
+ assert probe(root, host) == (True, ""), cell
+ for _ in range(3):
+ assert online_repair(root, host, backend) == "kept", cell
+ assert probe(root, host) == (True, ""), f"{cell}: a keep made the tree unhealthy"
+
+
+# ---------------------------------------------------------------------------
+# The offline model, install_prebuilt for real
+
+
[email protected](("cell", "host", "backend", "shape"), CELLS, ids = CELL_IDS)
+def test_the_offline_python_repair_never_keeps_a_tree_the_probe_rejects(
+ tmp_path, offline, cell, host, backend, shape
+):
+ """The branch the loop would hide in, driven through the real ``install_prebuilt``.
+
+ Unreachable listing, so the run reaches the ``PrebuiltFallback`` handler and its
+ ``_existing_install_runs`` gate. ``python-kept`` on a rejected tree is the loop: nothing
+ downstream runs, so the next launch rejects it again. Everything else hands the tree to
+ the shell, which is the next test.
+ """
+ marker = MF.shape_with_backend(shape, backend)
+ for label, damage in damage_modes(host, backend, marker):
+ root = build_damaged(tmp_path / label, host, backend, marker, damage)
+ verdict = probe(root, host)
+ if verdict is None or verdict[0]:
+ continue
+ action = offline_repair(root, host, offline, shell_stage = False)
+ assert action != "python-kept", (
+ f"REPAIR LOOP: {cell}/{label} is rejected by installed_runtime_health "
+ f"({verdict[1]}) and kept unchanged by the offline branch of install_prebuilt"
+ )
+
+
[email protected](("cell", "host", "backend", "shape"), CELLS, ids = CELL_IDS)
+def test_the_offline_repair_terminates_once_the_source_build_actually_runs(
+ tmp_path, offline, cell, host, backend, shape
+):
+ """Offline, with the shell's rebuild-skip shortcut out of the model.
+
+ The cycle as intended: the probe rejects, no release is reachable, the keep path refuses
+ the tree, and setup.sh source builds over it. The swap is markerless, so the next probe
+ reports "nothing installed" and stops. A second repair would mean the source build
+ produced a tree the probe rejects.
+ """
+ marker = MF.shape_with_backend(shape, backend)
+ for label, damage in damage_modes(host, backend, marker):
+ root = build_damaged(tmp_path / label, host, backend, marker, damage)
+ outcome, cycles, trail = run_cycle(
+ root,
+ host,
+ lambda tree: offline_repair(tree, host, offline, shell_stage = False),
+ )
+ assert outcome in {
+ "converged",
+ "aborted",
+ }, f"{cell}/{label}: {outcome} after {cycles} repairs ({trail})"
+ assert cycles <= 1, f"{cell}/{label}: took {cycles} repairs ({trail})"
+
+
+def test_both_shells_gate_their_reuse_shortcut_on_the_same_check():
+ """Codex 3963478816, P1. The model above is only worth as much as its fidelity, and it
+ was wrong about this: it recorded that setup.ps1 had no reuse step, when it has an
+ ``elseif`` on ``Test-PathQuiet $LlamaServerBin`` that reports "already built". So the
+ Windows half of the loop survived the fix that closed the POSIX half. A Windows repair
+ that fell through to the source stage kept a tree with a quarantined DLL, returned it
+ unchanged, and preflight offered the same repair on every launch.
+
+ Read off both scripts, because the model cannot catch a shell losing its gate.
+ """
+ root = Path(__file__).resolve().parents[3]
+
+ shell = (root / "studio" / "setup.sh").read_text(encoding = "utf-8")
+ assert "--check-existing-install" in shell
+ assert "_LLAMA_REUSE_EXISTING" in shell, "setup.sh lost its reuse gate"
+
+ ps1 = (root / "studio" / "setup.ps1").read_text(encoding = "utf-8")
+ assert "function Test-LlamaTreeStillHealthy" in ps1, "setup.ps1 lost its reuse gate"
+ assert (
+ "--check-existing-install" in ps1
+ ), "the PowerShell gate must ask install_llama_prebuilt, not reimplement healthy"
+ # On the shortcut itself, not somewhere else in the file: an elseif that reaches
+ # "already built" without it is the exact defect. The shortcut now reads one
+ # predicate, so the gate has to be inside what computes it.
+ plan = ps1[ps1.index("$CanReuseLlamaBuild = ") :]
+ plan = plan[: plan.index("$WillBuildLlamaFromSource = ")]
+ assert "Test-LlamaTreeStillHealthy" in plan, "the reuse shortcut skips the health gate again"
+ shortcut = ps1[ps1.index("} elseif ($CanReuseLlamaBuild) {") :]
+ assert "already built" in shortcut[: shortcut.index("} elseif", 1)]
+
+
+def test_the_windows_build_plan_asks_the_same_question_as_its_reuse_shortcut():
+ """Codex 3971674498, P2. ``$WillBuildLlamaFromSource`` gates the last-chance git install
+ and ``Ensure-BuildToolsForLlamaSourceBuild``. With the health check read only by the
+ shortcut, a tree the shortcut refused left that predicate false, so a prebuilt-only box
+ reached the rebuild the refusal forces with no cmake and no Visual Studio toolchain.
+ Both now read ``$CanReuseLlamaBuild``, and it is computed once, above the plan."""
+ ps1 = (Path(__file__).resolve().parents[3] / "studio" / "setup.ps1").read_text(encoding = "utf-8")
+ assert ps1.index("$CanReuseLlamaBuild = ") < ps1.index("$WillBuildLlamaFromSource = ")
+ assert (
+ "$WillBuildLlamaFromSource = $NeedLlamaSourceBuild -and -not $CanReuseLlamaBuild" in ps1
+ ), "the build plan must derive from the same predicate the shortcut reads"
+ # Once, so the helper runs once and its "incomplete" line is not printed twice.
+ assert ps1.count("Test-LlamaTreeStillHealthy $LlamaCppDir") == 1, ps1.count(
+ "Test-LlamaTreeStillHealthy $LlamaCppDir"
+ )
+
+
+def test_the_offline_repair_terminates_with_the_shell_rebuild_skip_in_place(tmp_path, offline):
+ """THE NON-TERMINATING CASE, stated as the assertion that should hold.
+
+ Linux, CUDA, today's marker shape, one quarantined library. The probe says
+ ``llama_runtime_payload_incomplete``; ``install_prebuilt`` cannot reach a release and exits
+ ``EXIT_FALLBACK`` because ``_existing_install_runs`` refuses the tree, which is the static
+ invariant working as designed; setup.sh then found two executable entrypoints, called it an
+ existing source build, and skipped the rebuild, so every later launch got the same answer
+ while the update reported success.
+ """
+ host, backend = MF.LINUX, "cuda"
+ marker = MF.shape_with_backend(MF.S12, backend)
+ root = build_damaged(tmp_path / "quarantined", host, backend, marker, "libggml-cuda.so")
+ assert probe(root, host) == (False, "llama_runtime_payload_incomplete")
+ outcome, cycles, trail = run_cycle(
+ root,
+ host,
+ lambda tree: offline_repair(tree, host, offline, shell_stage = True),
+ )
+ assert outcome == "converged", f"{outcome} after {cycles} repairs ({trail})"
+
+
[email protected](("cell", "host", "backend", "shape"), CELLS, ids = CELL_IDS)
+def test_no_damaged_tree_survives_the_shell_rebuild_skip(
+ tmp_path, offline, cell, host, backend, shape
+):
+ """The property the shell fix establishes, over every cell rather than one example.
+
+ This used to pin the opposite: on setup.sh hosts every damage that left both ``build/bin``
+ entrypoints executable was kept by the reuse shortcut, so the offline repair returned the
+ tree unchanged. The shortcut now asks ``reusable_existing_install`` first, so a tree the
+ prebuilt helper just refused is refused here too and the source build runs.
+
+ Aborted stays allowed and is not a loop: a marker naming a concrete backend makes
+ ``preserve_backend`` true, so the helper exits ``EXIT_BACKEND_UNAVAILABLE`` and setup.sh
+ stops with an error the user can act on.
+ """
+ marker = MF.shape_with_backend(shape, backend)
+ for label, damage in damage_modes(host, backend, marker):
+ root = build_damaged(tmp_path / label, host, backend, marker, damage)
+ verdict = probe(root, host)
+ if verdict is None or verdict[0]:
+ continue
+ outcome, cycles, trail = run_cycle(
+ root,
+ host,
+ lambda tree: offline_repair(tree, host, offline, shell_stage = True),
+ )
+ assert outcome in {"converged", "aborted"}, f"{cell}/{label}: {outcome} ({trail})"
+ assert cycles <= 1, f"{cell}/{label}: {cycles} repairs ({trail})"
+
+
+# ---------------------------------------------------------------------------
+# The cases the report has to keep apart from a loop
+
+
[email protected](("host_id", "host"), HOSTS, ids = [h[0] for h in HOSTS])
+def test_a_runtime_quarantined_again_after_every_repair_is_not_a_code_loop(tmp_path, host_id, host):
+ """Antivirus that re-quarantines after each repair never converges, and must not read as
+ the bug above. The distinguisher is progress, not convergence: every repair here replaces
+ the tree, whereas the shell shortcut returned an identical one."""
+ backend = "cuda"
+ root = tmp_path / "quarantined"
+ install_fresh_prebuilt(root, host, backend)
+ seen: list[str] = []
+ for _ in range(4):
+ # The quarantine strikes between the install and the launch, every time.
+ (MF._runtime_dir(root, host) / MF._SHARED_PAYLOAD[_platform_of(host)][0]).unlink()
+ verdict = probe(root, host)
+ assert verdict is not None and verdict[0] is False, host_id
+ before = fingerprint(root)
+ assert online_repair(root, host, backend) == "reinstalled", host_id
+ after = fingerprint(root)
+ assert after != before, f"{host_id}: the repair did not change the tree"
+ seen.append(after)
+ assert len(set(seen)) == 1, "each repair should rebuild the same healthy tree"
+
+
+def test_a_corrupt_marker_over_a_damaged_payload_is_graded_and_not_called_uninstalled(tmp_path):
+ """The gap answering ``None`` for an unparseable marker used to leave.
+
+ An unparseable marker over a missing library is a real install with a real hole, and
+ ``None`` reads to the desktop as "no managed runtime here": preflight Ready, no repair
+ offered, and the failure resurfacing at model load. It is graded instead, and the keep path
+ agrees the tree is broken, so the grading is not a loop either.
+ """
+ host, backend = MF.LINUX, "cuda"
+ gutted = build_damaged(
+ tmp_path / "corrupt-gutted",
+ host,
+ backend,
+ MF.shape_with_backend(MF.S12, backend),
+ "@corrupt-marker+library",
+ )
+ assert probe(gutted, host) == (False, "llama_runtime_payload_incomplete")
+ assert ILP._existing_install_runs(gutted, host) is False
+
+
+def test_the_two_kinds_of_missing_marker_stay_apart(tmp_path):
+ """No marker file means not installed and answers ``None``; a marker that will not parse is
+ an install whose payload can still be graded. Collapsing them either way is a bug: one
+ direction repairs a source build this path never owned, the other hides a quarantined
+ library behind a marker the same crash corrupted."""
+ host, backend = MF.LINUX, "cuda"
+ shape = MF.shape_with_backend(MF.S12, backend)
+
+ absent = build_damaged(tmp_path / "absent", host, backend, shape, "@marker")
+ assert probe(absent, host) is None
+ # confirm_install_tree requires the marker file, so the keep path refuses this tree
+ # outright and there is nothing to loop on.
+ assert ILP._existing_install_runs(absent, host) is False
+
+ corrupt = build_damaged(tmp_path / "corrupt", host, backend, shape, "@corrupt-marker")
+ assert probe(corrupt, host) == (True, "")
+ assert ILP._existing_install_runs(corrupt, host) is True
+
+
[email protected](("cell", "host", "backend", "shape"), CELLS, ids = CELL_IDS)
+def test_grading_an_unparseable_marker_keeps_the_no_stricter_invariant(
+ tmp_path, cell, host, backend, shape
+):
+ """The static half, re-proved for the trees an unparseable marker used to excuse.
+
+ Every damage is crossed with "and the marker does not parse", the axis that moved when the
+ probe stopped short-circuiting those trees to ``None``. A rejection must still be one
+ ``_existing_install_runs`` shares, or grading them trades a missed detection for a loop.
+ """
+ marker = MF.shape_with_backend(shape, backend)
+ for label, damage in damage_modes(host, backend, marker):
+ if damage in _MARKER_DAMAGES:
+ continue
+ root = build_damaged(tmp_path / label, host, backend, marker, damage, corrupt = True)
+ verdict = probe(root, host)
+ if verdict is None or verdict[0]:
+ continue
+ assert ILP._existing_install_runs(root, host) is False, (
+ f"REPAIR LOOP: {cell}/{label} with an unparseable marker is rejected by the "
+ f"pending probe ({verdict[1]}) but kept by _existing_install_runs"
+ )
+
+
[email protected](("cell", "host", "backend", "shape"), CELLS, ids = CELL_IDS)
+def test_grading_an_unparseable_marker_still_terminates_on_every_cell(
+ tmp_path, offline, cell, host, backend, shape
+):
+ """The dynamic half of the same question, under both repair models.
+
+ An unparseable marker plus every damage, cycled to a fixed point. Online the reinstall
+ replaces the marker; offline the source build removes it. Neither model gains a cycle from
+ grading these trees. The shell rebuild-skip stage is left out, since it is not a marker
+ question.
+ """
+ marker = MF.shape_with_backend(shape, backend)
+ for label, damage in damage_modes(host, backend, marker):
+ if damage in _MARKER_DAMAGES:
+ continue
+ for model, repair in (
+ ("online", lambda tree: online_repair(tree, host, backend)),
+ ("offline", lambda tree: offline_repair(tree, host, offline, shell_stage = False)),
+ ):
+ root = build_damaged(
+ tmp_path / f"{model}-{label}",
+ host,
+ backend,
+ marker,
+ damage,
+ corrupt = True,
+ )
+ outcome, cycles, trail = run_cycle(root, host, repair)
+ assert outcome in {
+ "converged",
+ "aborted",
+ }, f"{cell}/{model}/{label}: {outcome} after {cycles} repairs ({trail})"
+ assert cycles <= 1, f"{cell}/{model}/{label}: {cycles} repairs ({trail})"
+
+
+def test_the_freshly_installed_tree_is_a_fixed_point_on_every_cell(tmp_path):
+ """The base case the whole argument rests on: whatever the repair installs is accepted. If
+ this failed for any cell, every cycle above would be infinite whichever branch ran.
+ """
+ for host_id, host in HOSTS:
+ for backend in BACKENDS:
+ prebuilt = tmp_path / f"{host_id}-{backend}-prebuilt"
+ install_fresh_prebuilt(prebuilt, host, backend)
+ assert probe(prebuilt, host) == (True, ""), f"{host_id}-{backend}"
+
+ source = tmp_path / f"{host_id}-{backend}-source"
+ install_fresh_source_build(source, host)
+ assert probe(source, host) is None, f"{host_id}-{backend}"
diff --git a/tests/studio/install/test_macos_loader_probe_record.py b/tests/studio/install/test_macos_loader_probe_record.py
index 0cfee06835e..f8bb5e274e9 100644
--- a/tests/studio/install/test_macos_loader_probe_record.py
+++ b/tests/studio/install/test_macos_loader_probe_record.py
@@ -113,7 +113,23 @@ def build_install(
binary = directory / name
binary.write_text("#!/bin/sh\nexit 0\n", encoding = "utf-8")
binary.chmod(0o755)
- for dylib in ("libllama.0.dylib", "libggml.0.dylib", "libmtmd.0.dylib"):
+ # The libraries a real macos-arm64 bundle carries, one per group in
+ # runtime_payload_health_groups: libllama-common and the split ggml libraries ship
+ # beside libllama, so a fixture with only three of them is thinner than any install
+ # this code grades. Verified against llama-b11030-mix-5ff778e-bin-macos-arm64.tar.gz.
+ for dylib in (
+ "libllama-common.0.dylib",
+ "libllama.0.dylib",
+ "libggml.0.dylib",
+ "libggml-base.0.dylib",
+ "libggml-cpu.0.dylib",
+ "libmtmd.0.dylib",
+ # The entrypoints carry no entry code of their own since the upstream split, and
+ # the release tag here does not parse as a build number, which is the strict side
+ # of the same gate Windows has used all along.
+ "libllama-server-impl.dylib",
+ "libllama-quantize-impl.dylib",
+ ):
(runtime_dir / dylib).write_bytes(b"DYLIB")
(install_dir / "convert_hf_to_gguf.py").write_text("#!/usr/bin/env python3\n", encoding = "utf-8")
(install_dir / "gguf-py" / "gguf").mkdir(parents = True)
diff --git a/tests/studio/install/test_pr10648_integrity_and_fs.py b/tests/studio/install/test_pr10648_integrity_and_fs.py
index ac559d507a1..226e0156ae0 100644
--- a/tests/studio/install/test_pr10648_integrity_and_fs.py
+++ b/tests/studio/install/test_pr10648_integrity_and_fs.py
@@ -366,27 +366,35 @@ def test_a_non_executable_runtime_binary_is_rejected(tmp_path, monkeypatch, rela
@POSIX_ONLY
@NOT_ROOT
@pytest.mark.parametrize(
- "relative",
- ("llama-server", "llama-quantize", "build/bin/llama-diffusion-gemma-visual-server"),
+ "relative,is_an_entrypoint",
+ (
+ ("llama-server", True),
+ ("llama-quantize", True),
+ ("build/bin/llama-diffusion-gemma-visual-server", False),
+ ),
)
-def test_the_execute_bit_is_checked_on_the_runtime_copies_only(tmp_path, monkeypatch, relative):
- """A gap, but a PRE-EXISTING one, and this pins both halves of that claim.
-
- The precheck's os.access(X_OK) covers install_runtime_dir()/llama-{server,quantize}
- and nothing else, so a root copy or the visual server can lose its execute bit and
- still read as current. The full re-validation this PR skips did not catch it either:
- _existing_install_runs probes the root copies, but _binary_image_runs fails OPEN on
- EACCES (only ENOEXEC and a loader-level crash are verdicts), so it answered True too.
- Asserting the full path here is what makes "pre-existing" evidence instead of a
- claim -- and the blast radius is bounded, since llama_server_candidates keeps
- scanning inside the same layout and finds the executable build/bin copy.
+def test_the_execute_bit_is_checked_on_every_entrypoint(
+ tmp_path, monkeypatch, relative, is_an_entrypoint
+):
+ """Which files losing their execute bit stop an install being kept, and by which check.
+
+ Both halves ask _damaged_entrypoint now, so they answer together: it covers
+ llama-{server,quantize} under build/bin AND the install root's copies, which
+ _find_llama_server_binary reaches first. The shortcut used to check build/bin only,
+ which let the desktop mark an install stale over a root copy and then have the update
+ keep it unchanged; that loop is what this row pins.
+
+ The visual server is not an entrypoint either check probes, and the blast radius there
+ is bounded: llama_server_candidates keeps scanning the same layout and finds the
+ executable build/bin copy. Its row is the control -- without it the fix could be
+ "reject everything", which would send every install through a needless repair.
"""
install_dir = _install(tmp_path, monkeypatch)
assert _fast_path(install_dir) is True
assert LLAMA._existing_install_runs(install_dir, LINUX) is True
(install_dir / relative).chmod(0o644)
- assert _fast_path(install_dir) is True
- assert LLAMA._existing_install_runs(install_dir, LINUX) is True
+ assert _fast_path(install_dir) is not is_an_entrypoint
+ assert LLAMA._existing_install_runs(install_dir, LINUX) is not is_an_entrypoint
@pytest.mark.parametrize("relative", SIZE_TIER)
@@ -1056,3 +1064,25 @@ def test_the_llama_marker_survives_a_rewrite_and_the_fast_path_still_accepts_it(
assert stat.S_IMODE(marker_path.stat().st_mode) == 0o640
assert _temp_siblings(install_dir) == []
assert _fast_path(install_dir) is True
+
+
+@POSIX_ONLY
+@NOT_ROOT
[email protected]("relative", ("llama-server", "llama-quantize"))
+def test_a_damaged_root_entrypoint_is_not_kept_by_the_shortcut(tmp_path, monkeypatch, relative):
+ """The update has to repair what the launch check calls broken, or the two loop.
+
+ installed_runtime_health rejects a root llama-server that lost its execute bit, so the
+ desktop marks the install stale and offers a repair. This shortcut returns before
+ reinstalling anything, and it used to check X_OK under build/bin ONLY -- so the repair
+ ran, changed nothing, and the next launch was stale again. Measured before the fix:
+ launch health llama_runtime_binaries_missing, shortcut True, full re-validation False.
+
+ _damaged_entrypoint owns the question for all three now, which is what its own docstring
+ asks for.
+ """
+ install_dir = _install(tmp_path, monkeypatch)
+ assert _fast_path(install_dir) is True, "the shortcut must accept a healthy install here"
+ (install_dir / relative).chmod(0o644)
+ assert LLAMA._existing_install_runs(install_dir, LINUX) is False
+ assert _fast_path(install_dir) is False
diff --git a/unsloth_cli/commands/studio.py b/unsloth_cli/commands/studio.py
index c06b229ed87..83f983b5d01 100644
--- a/unsloth_cli/commands/studio.py
+++ b/unsloth_cli/commands/studio.py
@@ -159,6 +159,26 @@ def _recorded_master_root() -> Optional[Path]:
return None
+def _master_root_llama_dir() -> Optional[Path]:
+ """``<master>/llama.cpp`` when this install has a master root, else None.
+
+ Under UNSLOTH_HOME the runtimes are siblings of studio/, so the answer cannot be
+ derived from the studio home: <studio home>/llama.cpp is one level too deep. Both
+ the export below and the grading in _managed_llama_dir_ignoring_the_override read
+ this, so the rule exists once rather than twice.
+
+ Environment only, because the command callback recovers a recorded master root
+ into UNSLOTH_HOME before anything here runs.
+ """
+ master = (os.environ.get("UNSLOTH_HOME") or "").strip()
+ if not master:
+ return None
+ try:
+ return Path(master).expanduser().resolve() / "llama.cpp"
+ except (OSError, ValueError):
+ return Path(master).expanduser() / "llama.cpp"
+
+
def _ensure_studio_env_exported() -> None:
"""Re-export UNSLOTH_STUDIO_HOME / UNSLOTH_LLAMA_CPP_PATH for custom roots, and for a master
root the resolver above declined, per subcommand rather than at import, so unrelated
@@ -187,16 +207,11 @@ def _ensure_studio_env_exported() -> None:
_is_legacy = STUDIO_HOME == (Path.home() / ".unsloth" / "studio")
# The runtimes are siblings of studio/, at the master root, so STUDIO_HOME/llama.cpp is one
# level too deep. run.py keeps a non-blank value, so a wrong export here wins everywhere.
- _master = (os.environ.get("UNSLOTH_HOME") or "").strip()
- if _master:
- try:
- _llama_dir = Path(_master).expanduser().resolve() / "llama.cpp"
- except (OSError, ValueError):
- _llama_dir = Path(_master).expanduser() / "llama.cpp"
- elif _is_legacy:
- _llama_dir = Path.home() / ".unsloth" / "llama.cpp"
- else:
- _llama_dir = STUDIO_HOME / "llama.cpp"
+ _llama_dir = _master_root_llama_dir()
+ if _llama_dir is None:
+ _llama_dir = (
+ Path.home() / ".unsloth" / "llama.cpp" if _is_legacy else STUDIO_HOME / "llama.cpp"
+ )
if not (os.environ.get("UNSLOTH_LLAMA_CPP_PATH") or "").strip():
os.environ["UNSLOTH_LLAMA_CPP_PATH"] = str(_llama_dir)
@@ -4545,6 +4560,198 @@ class _WindowsLauncherUpdateTransaction:
return False
+def _managed_llama_runtime_is_the_active_one() -> bool:
+ """Whether preflight has a managed tree to grade at all.
+
+ Kept as the yes/no question the name asks; ``_llama_runtime_to_grade`` answers
+ which tree, and the two cannot disagree.
+ """
+ return _llama_runtime_to_grade() is not None
+
+
+def _llama_runtime_to_grade() -> Path | None:
+ """The llama.cpp tree preflight should grade, or None when the runtime the
+ backend would load is one the user chose and this PR does not grade.
+
+ ``_find_llama_server_binary`` prefers ``LLAMA_SERVER_PATH``, then
+ ``UNSLOTH_LLAMA_CPP_PATH``, then Studio's settings folder, and only then the
+ managed install. Grading the managed tree regardless would send a user who
+ runs their own build into repair over a leftover install their backend never
+ opens, and offline that repair cannot even succeed.
+
+ ``UNSLOTH_LLAMA_CPP_PATH`` needs no skip: it moves the managed root itself, so
+ ``default_managed_llama_dir`` already grades the tree it names.
+ """
+ pinned = os.environ.get("LLAMA_SERVER_PATH", "").strip()
+ # Nonblank is not the test: _scan_pinned treats an absent pin as no pin and
+ # falls through to the managed tree, so suppressing the verdict for a path
+ # that was deleted would leave a quarantined managed runtime reporting Ready.
+ # The line is the finder's own _file_status, not the directory entry: a pin
+ # that exists but is denied or not executable does stop the finder, while a
+ # symlink whose target was deleted or quarantined is is_file() False, reads as
+ # "absent" there, and falls through like any missing pin. lexists called that
+ # a pin and left the managed tree the backend really loads ungraded.
+ if pinned:
+ try:
+ stops_the_finder = Path(pinned).is_file()
+ except PermissionError:
+ # is_file raises rather than answering for a locked file on Windows;
+ # _file_status retries and then calls it "denied", which halts the
+ # finder with no fallback.
+ stops_the_finder = True
+ except OSError:
+ stops_the_finder = False
+ if stops_the_finder:
+ return None
+ # studio/backend on sys.path first. llama_cpp_path_settings imports
+ # storage.studio_db as a top level package and swallows the failure, so
+ # without this the stored selection always reads as absent and a user whose
+ # custom folder is set in Studio would be sent to repair a tree their backend
+ # never opens. Mirrors the backend_dir insert the other commands here do.
+ backend_dir = _PACKAGE_ROOT / "studio" / "backend"
+ if backend_dir.is_dir() and str(backend_dir) not in sys.path:
+ sys.path.insert(0, str(backend_dir))
+ try:
+ from studio.backend.utils.llama_cpp_path_settings import (
+ expanded_user_path,
+ get_stored_custom_llama_cpp_path,
+ llama_server_candidates,
+ )
+ from studio.install_llama_prebuilt import default_managed_llama_dir
+ except Exception:
+ # No settings module means no stored selection to honour, and no way to
+ # ask whether a folder holds a server, so the managed root stands.
+ from studio.install_llama_prebuilt import default_managed_llama_dir
+ return default_managed_llama_dir()
+ # UNSLOTH_LLAMA_CPP_PATH outranks the stored folder in the finder (1b before
+ # 2), and default_managed_llama_dir points at exactly that tree, so it is ours
+ # to grade even when an older selection is still in the settings database.
+ # Reading the setting first left the tree the backend actually opens ungraded.
+ # The managed marker is the exception: the finder skips the override when the
+ # desktop set it, so the stored folder wins again.
+ override = (os.environ.get("UNSLOTH_LLAMA_CPP_PATH") or "").strip()
+ # Classified, not merely read off the marker. studio/backend/main.py calls
+ # mark_managed_llama_cpp_path(managed) before discovery, which marks any
+ # override equal to the managed tree however it got there, and the finder then
+ # skips it. _ensure_studio_env_exported writes exactly that value under a
+ # custom STUDIO_HOME and sets no marker, so trusting the marker alone made
+ # this grade the managed tree as a user pin while the backend walked past it
+ # to the stored selection: a damaged managed tree blocked launch and was sent
+ # for repair though nothing would ever open it.
+ managed_override = os.environ.get("UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH") == "1"
+ if override and not managed_override:
+ # Against the tree the studio home names with the override out of the way,
+ # never default_managed_llama_dir(): that reads the override first and
+ # would call every user pin managed. The backend compares against exactly
+ # this value, STUDIO_ROOT/llama.cpp computed before it exported anything.
+ managed_override = _same_runtime_tree(
+ expanded_user_path(override), _managed_llama_dir_ignoring_the_override()
+ )
+ if override and not managed_override:
+ # Only a folder that holds a server stops discovery. _scan_pinned finds no
+ # candidate under an empty or missing override and walks on, so a tree behind
+ # it is still ours to grade; one that holds a server is not.
+ # Not graded, because nothing can repair it: setup.sh derives LLAMA_CPP_DIR
+ # from STUDIO_HOME and setup.ps1 from Get-ManagedLlamaCppDir, and neither
+ # reads UNSLOTH_LLAMA_CPP_PATH at all, so an update sent here would rebuild a
+ # different tree, report success, and leave the next launch offering the same
+ # repair forever. LLAMA_SERVER_PATH is skipped for the same reason.
+ # expanded_user_path, not Path.expanduser: the finder reads the same
+ # variable through it, and a "~name" naming no account makes expanduser
+ # raise RuntimeError out of a doctor whose whole job is to answer.
+ if _layout_stops_discovery(llama_server_candidates(expanded_user_path(override))):
+ return None
+ if get_stored_custom_llama_cpp_path() is not None:
+ return None
+ if managed_override:
+ # The finder skips an override that names the managed tree, and that tree
+ # is the one this install owns, so it is still the answer.
+ return default_managed_llama_dir()
+ # The finder has walked past the override, so the tree it reaches is the one
+ # the managed root names with that override out of the way. Reading it with
+ # the variable still set would name the folder just ruled out.
+ return _managed_llama_dir_ignoring_the_override()
+
+
+def _same_runtime_tree(left: Path, right: Path) -> bool:
+ """Whether two runtime paths name one tree, the way the backend compares them.
+
+ ``mark_managed_llama_cpp_path`` resolves both sides non-strictly and swallows
+ the same errors, so a path that has not been created yet still compares, and
+ an unreadable one answers "different" rather than raising out of the doctor.
+ """
+ try:
+ return left.resolve(strict = False) == right.resolve(strict = False)
+ except (OSError, RuntimeError, ValueError):
+ return False
+
+
+def _layout_stops_discovery(candidates) -> bool:
+ """Whether a pinned folder ends ``_find_llama_server_binary``'s search.
+
+ Presence, not usability: ``_scan_pinned`` returns a hit for an executable
+ candidate, and for one that is merely present it returns the path as
+ ``non_executable`` or ``denied``, which the caller turns into ``_unavailable``
+ and a refusal to fall back. Only a layout holding no server at all is walked
+ past. Asking for the execute bit here would send preflight off to grade a
+ different tree in exactly the case where the pinned one needs repair.
+ """
+ for candidate in candidates:
+ try:
+ if candidate.is_file():
+ return True
+ except PermissionError:
+ return True
+ except OSError:
+ continue
+ return False
+
+
+def _managed_llama_dir_ignoring_the_override() -> Path:
+ """default_managed_llama_dir with UNSLOTH_LLAMA_CPP_PATH out of the way, and the
+ inferred studio home put back.
+
+ The desktop scrubs UNSLOTH_STUDIO_HOME and STUDIO_HOME before it spawns this
+ (MANAGED_CHILD_SCRUBBED_ENV), so default_managed_llama_dir reads an empty
+ environment and answers the legacy ~/.unsloth/llama.cpp. _resolve_studio_home has
+ already recovered the real root off sys.prefix by then, and preflight::managed's
+ inferred_studio_llama_root fingerprints <root>/llama.cpp on the strength of the
+ same inference, so reading only the environment here graded the legacy tree while
+ the cache watched the custom one: quarantine in the runtime actually in use
+ reported Ready and failed at model load.
+
+ Exported rather than computed, because _ensure_studio_env_exported writes exactly
+ this value and there should be one rule for it, not two that can drift.
+ """
+ from studio.install_llama_prebuilt import default_managed_llama_dir
+
+ # A master root first, for the same reason the export computes it that way: the
+ # runtimes sit beside studio/, and default_managed_llama_dir reads only the studio
+ # home, so it would answer <master>/studio/llama.cpp and grade the tree the
+ # installer exported -- the one actually in use -- as somebody's own pin, which
+ # left these installs out of the health check entirely.
+ master_dir = _master_root_llama_dir()
+ if master_dir is not None:
+ return master_dir
+
+ saved = os.environ.pop("UNSLOTH_LLAMA_CPP_PATH", None)
+ had_home = "UNSLOTH_STUDIO_HOME" in os.environ
+ saved_home = os.environ.get("UNSLOTH_STUDIO_HOME")
+ # Truthy-check, not a bare presence one, the way _ensure_studio_env_exported reads
+ # it: a blank UNSLOTH_STUDIO_HOME= is not a root either.
+ if _STUDIO_HOME_IS_CUSTOM and not (saved_home or "").strip():
+ os.environ["UNSLOTH_STUDIO_HOME"] = str(STUDIO_HOME)
+ try:
+ return default_managed_llama_dir()
+ finally:
+ if saved is not None:
+ os.environ["UNSLOTH_LLAMA_CPP_PATH"] = saved
+ if had_home:
+ os.environ["UNSLOTH_STUDIO_HOME"] = saved_home
+ else:
+ os.environ.pop("UNSLOTH_STUDIO_HOME", None)
+
+
@studio_app.command("desktop-capabilities", hidden = True)
def desktop_capabilities(
json_output: bool = typer.Option(
@@ -4564,8 +4771,39 @@ def desktop_capabilities(
# Did the install finish and are the backend boot deps still there.
"studio_install_ok": bool(state["ok"]),
"studio_install_reason": state["reason"],
+ # And is the llama.cpp runtime the backend loads still intact. Null when
+ # nothing is installed yet (NotInstalled, not a broken install). Older
+ # desktops ignore both keys.
+ "llama_runtime_ok": None,
+ "llama_runtime_reason": "",
"version": "unknown",
}
+ # Best effort: a probe that cannot answer must not turn a working install into
+ # a stale one, so a failure here leaves llama_runtime_ok null.
+ try:
+ from studio.install_llama_prebuilt import installed_runtime_health
+ runtime_root = _llama_runtime_to_grade()
+ if runtime_root is not None:
+ health = installed_runtime_health(runtime_root)
+ if health is not None:
+ payload["llama_runtime_ok"], payload["llama_runtime_reason"] = health
+ else:
+ # Null with a reason, because the two nulls are not the same thing.
+ # Nothing installed is a fact about the machine and stays true until
+ # the tree changes, so the desktop may cache it. This one is a fact
+ # about a selection the desktop's fingerprint does not watch, so the
+ # answer expires the moment the user clears their custom folder, and
+ # managed.rs declines to cache it on the strength of this reason.
+ # The verdict itself is still null, so nothing turns stale on it.
+ payload["llama_runtime_reason"] = "llama_runtime_not_managed"
+ except Exception:
+ # The third null, and the one that must not be kept. Nothing-installed is a
+ # fact about the machine; this is a fact about one attempt, and it shares the
+ # damaged tree's fingerprint, so caching it froze a Ready that was never
+ # reached over a runtime the probe would have rejected. Same reason string
+ # shape as the skip, so managed.rs refuses both without a second rule.
+ payload["llama_runtime_ok"] = None
+ payload["llama_runtime_reason"] = "llama_runtime_probe_failed"
try:
from importlib.metadata import version as package_version
payload["version"] = package_version("unsloth")