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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
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.pyindex 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.pyindex 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, tmf"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.pyindex 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 Falsetry:- 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 == managedexcept (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 excif 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 Noneelse:diff --git a/studio/frontend/src/hooks/backend-preflight-message.ts b/studio/frontend/src/hooks/backend-preflight-message.tsindex 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.tsindex 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.pyindex 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 groupsif 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[stfor pattern_group in groups:matched = Falsefor 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 = Truebreakif not matched:@@ -7877,10 +8096,48 @@ def runtime_payload_is_healthy(install_dir: Path, host: HostInfo, choice: AssetCsource_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 Nonemarker_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.ps1index 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 $CanReuseLlamaBuildif ($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.shindex 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/nullimport jsonimport reimport 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" ]; thenstep "llama.cpp" "existing source build found; skipping rebuild"diff --git a/studio/src-tauri/src/preflight.rs b/studio/src-tauri/src/preflight.rsindex 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.rsindex 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: &Desmarker_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, ¬_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.rsindex 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 pathdiff --git a/tests/studio/install/test_desktop_capability_llama_runtime.py b/tests/studio/install/test_desktop_capability_llama_runtime.pynew file mode 100644index 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.pyindex 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.pyindex 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_insassert 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pyindex 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_dirdiff --git a/tests/studio/install/test_llama_runtime_install_history.py b/tests/studio/install/test_llama_runtime_install_history.pynew file mode 100644index 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 Falsediff --git a/tests/studio/install/test_llama_runtime_repair_convergence.py b/tests/studio/install/test_llama_runtime_repair_convergence.pynew file mode 100644index 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.pyindex 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 / namebinary.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.pyindex 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 Trueassert 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) == 0o640assert _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 Falsediff --git a/unsloth_cli/commands/studio.py b/unsloth_cli/commands/studio.pyindex 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 masterroot 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_versionpayload["version"] = package_version("unsloth")