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
Cover the restore of every variable the install.ps1 handoff block saves (#10566)
Daniel Han2bd5dabb20ca
diff --git a/tests/test_windows_amd_gpu_scan_fallback.py b/tests/test_windows_amd_gpu_scan_fallback.pyindex 0d6ab365921..cf2ea118e41 100644--- a/tests/test_windows_amd_gpu_scan_fallback.py+++ b/tests/test_windows_amd_gpu_scan_fallback.py@@ -524,10 +524,131 @@ def test_the_installer_and_setup_agree_on_which_adapter_is_active(tmp_path):# ── runtime: install.ps1 leaves the caller's environment as it found it ───────────────────────+# The block's fifteen save/restore pairs bar the ROCm handoff, which the arch parametrisation drives.+_CALLER_ENV_NAMES = (+ "SKIP_STUDIO_BASE",+ "UNSLOTH_STUDIO_HOME",+ "UNSLOTH_TAURI_MODE",+ "_UNSLOTH_STUDIO_RUNTIME_GATE_HANDOFF",+ "_UNSLOTH_PS_PROXY_DEFAULTS",+ "STUDIO_PACKAGE_NAME",+ "UNSLOTH_NO_TORCH",+ "UNSLOTH_INSTALLER_TORCH_TAG",+ "SKIP_STUDIO_FRONTEND",+ "STUDIO_LOCAL_INSTALL",+ "STUDIO_LOCAL_REPO",+ "UNSLOTH_LOCAL_LLAMA_CPP_DIR",+ "UNSLOTH_INSTALL_ROLLBACK_MANAGED",+ "UNSLOTH_SETUP_PYTHON",+)++# Distinct per variable, or a finally restoring everything from the wrong save reads as a pass.+_CALLER_ENV = tuple(+ (name, "outer-" + name.strip("_").lower().replace("_", "-")) for name in _CALLER_ENV_NAMES+)+assert len({sentinel for _, sentinel in _CALLER_ENV}) == len(_CALLER_ENV), "sentinels must differ"++# Which variables the caller already has. Presence has to vary PER variable: all-present and+# all-absent give every $hadPrevious* flag the same value, so a wrong-flag restore passes by luck.+_PRESENCE_MASK_BITS = max((len(_CALLER_ENV_NAMES) - 1).bit_length(), 1)+_PRESENCE_PATTERNS = {+ "all": lambda i: True,+ "none": lambda i: False,+ **{f"mask{k}": (lambda i, k = k: bool((i >> k) & 1)) for k in range(_PRESENCE_MASK_BITS)},+ **{f"cmask{k}": (lambda i, k = k: not ((i >> k) & 1)) for k in range(_PRESENCE_MASK_BITS)},+}+++def _present_names(pattern: str) -> tuple[str, ...]:+ keep = _PRESENCE_PATTERNS[pattern]+ return tuple(name for i, name in enumerate(_CALLER_ENV_NAMES) if keep(i))+++def test_the_presence_masks_separate_every_ordered_pair():+ """ORDERED, not unordered: a restore of A reading B's $hadPrevious flag only shows where A is+ present and B is absent, since the other direction assigns A's saved $null, which removes the+ variable exactly as the correct code does. Under the unordered form 43 of the 182 directed+ substitutions survived."""+ patterns = [_present_names(p) for p in _PRESENCE_PATTERNS]+ for a in _CALLER_ENV_NAMES:+ for b in _CALLER_ENV_NAMES:+ if a == b:+ continue+ assert any(a in p and b not in p for p in patterns), (+ f"no pattern has {a} present while {b} is absent, so a restore of {a} reading "+ f"{b}'s $hadPrevious flag is invisible"+ )+++def _assert_caller_env_restored(out: dict, present: tuple[str, ...], what: str) -> None:+ """The caller's shell as it was: same value, or still no variable at all.++ Absence is `Test-Path Env:NAME` being false, not an empty value: 7.5+ keeps a variable present+ when assigned "", so a restore writing "" instead of removing would pass a value check.+ Present-but-EMPTY is unasserted: `$null -ne $previous` cannot tell "" from unset, so the answer+ is engine-dependent."""+ for name, sentinel in _CALLER_ENV:+ key = name.lower()+ if name in present:+ assert out[key + "_set"] is True, f"{what} removed {name}, which the caller had set"+ assert out[key] == sentinel, f"{what} left {name} as install.ps1 set it"+ else:+ assert (+ out[key + "_set"] is False+ ), f"{what} left {name} behind in a shell that never had it, as {out[key]!r}"+++def _existing_llama_dir(tmp_path: Path) -> Path:+ path = tmp_path / "llama.cpp"+ path.mkdir(exist_ok = True)+ return path+++def _studio_home_dir(tmp_path: Path) -> Path:+ path = tmp_path / "studio-home"+ path.mkdir(exist_ok = True)+ return path+++def _studio_repo_dir(tmp_path: Path) -> Path:+ """DISTINCT from the studio home, so a restore that swapped the two shows rather than passing."""+ path = tmp_path / "studio-local-repo"+ path.mkdir(exist_ok = True)+ return path+++# UNSLOTH_STUDIO_HOME and STUDIO_LOCAL_REPO are the only two the try does not always assign, so+# only `env_redirect_local` makes their else-arm restores load-bearing.+_STUDIO_MODES = ("default", "env_redirect_local")+++def _studio_mode_lines(tmp_path: Path, studio_mode: str) -> list[str]:+ if studio_mode == "default":+ return [+ "$StudioLocalInstall = $false; $RepoRoot = $null",+ "$StudioRedirectMode = 'none'; $StudioHome = $null",+ ]+ return [+ f"$StudioLocalInstall = $true; $RepoRoot = '{_studio_repo_dir(tmp_path)}'",+ f"$StudioRedirectMode = 'env'; $StudioHome = '{_studio_home_dir(tmp_path)}'",+ ]+++def _caller_env_report() -> str:+ return "\n".join(+ f" {name.lower()} = $(if (Test-Path Env:{name}) {{ $env:{name} }} else {{ $null }})\n"+ f" {name.lower()}_set = [bool](Test-Path Env:{name})"+ for name, _ in _CALLER_ENV+ )++def _handoff_lifecycle_block() -> str:- """install.ps1's save / set / try / finally around the setup call, as shipped."""+ """install.ps1's save / set / try / finally around the setup call, as shipped.++ Anchored on the FIRST save, not the ROCm one: slicing below the five pairs above it left the+ harness supplying their $previous*, so those restores were measured against harness constants."""src = INSTALL_PS1.read_text(encoding = "utf-8")- start = src.index(" $previousRocmGfxHandoff = $env:")+ start = src.index(" $previousSkipStudioBase = $env:SKIP_STUDIO_BASE")end = src.index(" if ($setupExit -ne 0) {", start)return src[start:end]@@ -539,38 +660,46 @@ def _run_handoff_lifecycle(inherited: str | None,fails: bool,bails: bool = False,+ with_llama_cpp_dir: bool = False,+ caller_env: str = "all",+ studio_mode: str = "default",) -> dict:+ assert not (bails and with_llama_cpp_dir), "the bail and the success path are exclusive"+ assert studio_mode in _STUDIO_MODES, studio_mode+ present = _present_names(caller_env)call = "Invoke-ManagedUnslothCli -Python $VenvPython -Arguments $studioArgs"block = _handoff_lifecycle_block()# Loudly: a silent miss leaves the probe unrun and every assertion reading# "<never ran>" with nothing saying why.assert call in block, "install.ps1 no longer makes the setup call this harness replaces"- body = block.replace(- call,- "throw 'setup exploded'"- if fails- else "$script:SeenByChild = $env:_UNSLOTH_ROCM_GFX_ARCH_HANDOFF",+ # Read at the point of the call: what the child would inherit, not what the finally leaves.+ probe = (+ "$script:SeenByChild = $env:_UNSLOTH_ROCM_GFX_ARCH_HANDOFF; "+ "$script:SeenLlamaCppDir = $env:UNSLOTH_LOCAL_LLAMA_CPP_DIR; "+ # Test-Path, not the bare value: the default modes REMOVE these two.+ "$script:SeenStudioHome = $(if (Test-Path Env:UNSLOTH_STUDIO_HOME) "+ "{ $env:UNSLOTH_STUDIO_HOME } else { $null }); "+ "$script:SeenLocalRepo = $(if (Test-Path Env:STUDIO_LOCAL_REPO) "+ "{ $env:STUDIO_LOCAL_REPO } else { $null })")+ body = block.replace(call, probe + ("; throw 'setup exploded'" if fails else ""))script = tmp_path / "handoff.ps1"script.write_text("\n".join(["$ErrorActionPreference = 'Stop'",- # Not under test, but the shipped finally restores these too and needs them bound.- "$previousUnslothStudioHome = $null; $hadPreviousUnslothStudioHome = $false",- "$previousTauriMode = $null; $hadPreviousTauriMode = $false",- "$previousSetupRuntimeGateHandoff = $null; $hadPreviousSetupRuntimeGateHandoff = $false",- "$previousProxyHandoff = $null; $hadPreviousProxyHandoff = $false","$UnslothProxyHandoffJson = $null","$UnslothExe = 'stub'; $studioArgs = @(); $setupExit = 0",# Installer inputs the block reads. Undefined, they throw under# ErrorActionPreference Stop, the catch swallows it, and the probe never runs."$PackageName = 'unsloth'; $SkipTorch = $false; $TauriMode = $false",- "$StudioLocalInstall = $false; $RepoRoot = $null",- "$StudioRedirectMode = 'none'; $StudioHome = $null",+ *_studio_mode_lines(tmp_path, studio_mode),(f"$WithLlamaCppDir = '{tmp_path / 'no-such-llama.cpp'}'"if bails+ # A directory that EXISTS reaches the block's only write to that variable.+ else f"$WithLlamaCppDir = '{_existing_llama_dir(tmp_path)}'"+ if with_llama_cpp_direlse "$WithLlamaCppDir = $null")+ "; $VenvPython = 'stub-python'; $VenvDir = 'stub-venv'",@@ -582,7 +711,8 @@ def _run_handoff_lifecycle("function Write-StudioLine { param($Message, $ForegroundColor) }","function Write-ApplicationControlBlocked { param($Message, $Detail) }","function Exit-InstallFailure { param($Message) 1 }",- "$script:SeenByChild = '<never ran>'",+ "$script:SeenByChild = '<never ran>'; $script:SeenLlamaCppDir = '<never ran>'",+ "$script:SeenStudioHome = '<never ran>'; $script:SeenLocalRepo = '<never ran>'","$script:BlockError = $null",# Read right after the setup call; null makes the block return early."$script:ManagedUnslothCliExit = 0",@@ -598,20 +728,24 @@ def _run_handoff_lifecycle("Invoke-HandoffBlock | Out-Null","@{"," seen_by_child = $script:SeenByChild",+ " seen_llama_cpp_dir = $script:SeenLlamaCppDir",+ " seen_studio_home = $script:SeenStudioHome",+ " seen_local_repo = $script:SeenLocalRepo"," block_error = $script:BlockError"," after = $(if (Test-Path Env:_UNSLOTH_ROCM_GFX_ARCH_HANDOFF) { $env:_UNSLOTH_ROCM_GFX_ARCH_HANDOFF } else { $null })"," after_set = [bool](Test-Path Env:_UNSLOTH_ROCM_GFX_ARCH_HANDOFF)"," public = $(if (Test-Path Env:UNSLOTH_ROCM_GFX_ARCH) { $env:UNSLOTH_ROCM_GFX_ARCH } else { $null })",- # Set at the top of the block's try, above the bail: gone afterwards- # is what says the finally ran.- " package_name = $(if (Test-Path Env:STUDIO_PACKAGE_NAME) { $env:STUDIO_PACKAGE_NAME } else { $null })",- " skip_base = $(if (Test-Path Env:SKIP_STUDIO_BASE) { $env:SKIP_STUDIO_BASE } else { $null })",+ # Value AND presence: a variable assigned "" is still present on 7.5+, so only+ # Test-Path separates "put back as it was" from "recreated empty".+ _caller_env_report(),"} | ConvertTo-Json -Compress",]),encoding = "utf-8",)env = {"PATH": "/usr/bin:/bin", "HOME": str(tmp_path), "UNSLOTH_ROCM_GFX_ARCH": "gfx90a"}+ # Built from scratch, so a name simply not added reads back $null: the finally's remove arm.+ env.update({name: sentinel for name, sentinel in _CALLER_ENV if name in present})if inherited is not None:env[HANDOFF] = inheritedproc = subprocess.run(@@ -639,39 +773,165 @@ def _run_handoff_lifecycle(@requires_pwsh+ "caller_env", list(_PRESENCE_PATTERNS), ids = [f"caller_env_{p}" for p in _PRESENCE_PATTERNS]+)@pytest.mark.parametrize("fails", [False, True], ids = ["setup_ok", "setup_throws"])@pytest.mark.parametrize("arch, inherited",[(None, None), ("gfx1151", None), (None, "gfx1030"), ("gfx1151", "gfx1030")],ids = ["nothing", "resolved", "inherited", "resolved_over_inherited"],)-def test_the_caller_environment_survives_the_setup_call(tmp_path, arch, inherited, fails):+def test_the_caller_environment_survives_the_setup_call(+ tmp_path, arch, inherited, fails, caller_env+):"""`irm ... | iex` runs install.ps1 in the caller's own shell, so anything set for the child- has to be put back -- on the failure path too, which is the one that rolls back and retries."""- out = _run_handoff_lifecycle(tmp_path, arch = arch, inherited = inherited, fails = fails)+ has to be put back -- on the failure path too, which is the one that rolls back and retries,+ and whether or not the caller had the variable to begin with."""+ out = _run_handoff_lifecycle(+ tmp_path,+ arch = arch,+ inherited = inherited,+ fails = fails,+ caller_env = caller_env,+ )assert out["after_set"] is (inherited is not None), "the handoff outlived the setup call"assert out["after"] == inheritedassert out["public"] == "gfx90a", "a user's own override must come back untouched"+ _assert_caller_env_restored(out, _present_names(caller_env), "the setup call")+++@requires_pwsh+ "caller_env", list(_PRESENCE_PATTERNS), ids = [f"caller_env_{p}" for p in _PRESENCE_PATTERNS]+)[email protected]("fails", [False, True], ids = ["setup_ok", "setup_throws"])+def test_the_optional_handoffs_are_restored_when_this_run_sets_them(tmp_path, fails, caller_env):+ """UNSLOTH_STUDIO_HOME and STUDIO_LOCAL_REPO are the two the try does not always assign.++ The case above hard-codes redirect mode 'none' and no local install, so the try left these two+ ABSENT and deleting the finally's else arm was invisible; every other saved variable is+ assigned unconditionally, so the same deletion shows there at once."""+ out = _run_handoff_lifecycle(+ tmp_path,+ arch = "gfx1151",+ inherited = None,+ fails = fails,+ caller_env = caller_env,+ studio_mode = "env_redirect_local",+ )+ assert out["seen_studio_home"] == str(+ _studio_home_dir(tmp_path)+ ), "the env-redirect install did not hand its studio home to the child"+ assert out["seen_local_repo"] == str(+ _studio_repo_dir(tmp_path)+ ), "the --local install did not hand its repo to the child"+ _assert_caller_env_restored(out, _present_names(caller_env), "the env-redirect local install")+++def test_every_save_sits_above_the_handoff_try():+ """Ordering, not just membership: a save that drifts INSIDE the try is a live hazard.++ A set comparison still matches, and no runtime case catches it either, since both injected+ failures sit BELOW where such a save would land. What bites is a throw ABOVE it, leaving+ $hadPrevious* unbound, hence $null, hence the finally removing a value the caller owned."""+ block = _handoff_lifecycle_block()+ assert block.count("\n try {") == 1, "the block no longer has exactly one handoff try"+ try_at = block.index("\n try {")+ saves = list(re.finditer(r"\$previous(\w+) = \$env:(\w+)", block))+ flags = list(re.finditer(r"\$hadPrevious(\w+) = \(\$null -ne \$previous\w+\)", block))+ assert {m.group(2) for m in saves} == {name for name, _ in _CALLER_ENV} | {HANDOFF}+ assert len(flags) == len(saves), (+ f"{len(saves)} saves but {len(flags)} $hadPrevious flags; a save without its flag "+ "restores through an unbound $null and takes the remove arm"+ )+ for m in saves:+ assert m.start() < try_at, (+ f"the save of {m.group(2)} sits inside the try, so anything that throws above it "+ "leaves $hadPrevious unbound and the finally removes a value the caller owned"+ )+ for m in flags:+ assert m.start() < try_at, (+ f"$hadPrevious{m.group(1)} is bound inside the try, so a throw above it leaves the "+ "flag $null and the finally takes the remove arm against a caller that had a value"+ )+++def test_every_saved_variable_in_the_block_is_covered():+ """_CALLER_ENV checked against the source, so a save added to the block names the variable+ whose restore nothing exercises. UV_CACHE_DIR, TMP and TEMP are out of scope by construction:+ saved and restored hundreds of lines outside this block, so covering them means slicing most+ of install.ps1 and stubbing the venv build, the torch install and the llama.cpp fetch."""+ block = _handoff_lifecycle_block()+ covered = {name for name, _ in _CALLER_ENV} | {HANDOFF}+ saved = set(re.findall(r"\$previous\w+ = \$env:(\w+)", block))+ # The restore side closes the anchor hole: a save PREPENDED above the anchor is invisible to+ # any save-side check, but its restore cannot escape the finally.+ restored = set(re.findall(r"\$env:(\w+) = \$previous\w+", block))+ assert restored == covered, (+ "the block restores variables this file does not claim to cover: "+ f"{sorted(restored - covered)} (a save prepended above the slice anchor looks like this); "+ f"and claims ones it no longer restores: {sorted(covered - restored)}"+ )+ assert saved == restored, (+ "saves and restores in the block disagree: saved but never restored "+ f"{sorted(saved - restored)}; restored but not saved inside the slice "+ f"{sorted(restored - saved)}"+ )@requires_pwsh-def test_the_bail_restores_the_caller_environment(tmp_path):+ "caller_env", list(_PRESENCE_PATTERNS), ids = [f"caller_env_{p}" for p in _PRESENCE_PATTERNS]+)+def test_the_bail_restores_the_caller_environment(tmp_path, caller_env):"""The --with-llama-cpp-dir bail returns from inside the try, so the finally still runs.Textual ordering cannot show that: move the try below the bail and `saved < bail <restored` still holds while the return walks out past the restore. So this takes thebail, with a directory that does not exist, and reads the environment afterwards.- """++ STUDIO_PACKAGE_NAME and SKIP_STUDIO_BASE, asserted individually here before, are now two of the+ fifteen the helper checks, in both directions rather than only for removal."""out = _run_handoff_lifecycle(- tmp_path, arch = "gfx1151", inherited = "gfx1030", fails = False, bails = True+ tmp_path,+ arch = "gfx1151",+ inherited = "gfx1030",+ fails = False,+ bails = True,+ caller_env = caller_env,)assert out["seen_by_child"] == "<never ran>", "the bail did not happen before the setup call"assert out["after"] == "gfx1030", "the caller's inherited handoff was not restored by the bail"assert out["after_set"] is True- # Set above the bail and removed only by the finally, so still set in the caller- # would mean the bail escaped the try.- assert out["package_name"] is None, "STUDIO_PACKAGE_NAME leaked past the bail"- assert out["skip_base"] is None, "SKIP_STUDIO_BASE leaked past the bail"+ # Put back only by the finally, so install.ps1's value still showing means the bail escaped.+ _assert_caller_env_restored(out, _present_names(caller_env), "the bail")+++@requires_pwsh+ "caller_env", list(_PRESENCE_PATTERNS), ids = [f"caller_env_{p}" for p in _PRESENCE_PATTERNS]+)+def test_a_real_llama_cpp_dir_is_handed_over_and_then_put_back(tmp_path, caller_env):+ """The other side of the bail: --with-llama-cpp-dir naming a directory that is there.++ Nothing reached the block's only write to UNSLOTH_LOCAL_LLAMA_CPP_DIR, so its restore was+ satisfied by never being dirtied, which is not the same as being correct."""+ out = _run_handoff_lifecycle(+ tmp_path,+ arch = "gfx1151",+ inherited = "gfx1030",+ fails = False,+ with_llama_cpp_dir = True,+ caller_env = caller_env,+ )+ assert out["seen_by_child"] == "gfx1151", "the block did not reach the setup call"+ # The RESOLVED path, since that is what the block writes and what setup.ps1 goes on to read.+ assert out["seen_llama_cpp_dir"] == str(+ _existing_llama_dir(tmp_path).resolve()+ ), "the child did not inherit the --with-llama-cpp-dir directory"+ assert out["after"] == "gfx1030", "the caller's inherited handoff was not restored"+ _assert_caller_env_restored(out, _present_names(caller_env), "the llama.cpp handoff")@requires_pwsh@@ -680,10 +940,21 @@ def test_the_bail_restores_the_caller_environment(tmp_path):[("gfx1151", None, "gfx1151"), ("gfx1151", "gfx1030", "gfx1151"), (None, "gfx1030", None)],ids = ["resolved", "resolved_over_inherited", "stale_only"],)-def test_only_this_runs_arch_is_handed_to_the_child(tmp_path, arch, inherited, expected):[email protected]("caller_env", sorted(_PRESENCE_PATTERNS), ids = sorted(_PRESENCE_PATTERNS))+def test_only_this_runs_arch_is_handed_to_the_child(+ tmp_path, arch, inherited, expected, caller_env+):"""A value inherited from an outer process is not this run's answer, so it is cleared rather- than forwarded as though the scan had produced it."""- out = _run_handoff_lifecycle(tmp_path, arch = arch, inherited = inherited, fails = False)+ than forwarded as though the scan had produced it.++ Parametrised over the caller patterns, not left on the helper's default. The default is+ `all`, which sets every caller variable, and a clear that wrongly keyed itself off some+ other variable's $hadPrevious flag would then find that flag true and clear anyway. The+ empty-caller case is the one that catches it, and running only the default lost it.+ """+ out = _run_handoff_lifecycle(+ tmp_path, arch = arch, inherited = inherited, fails = False, caller_env = caller_env+ )assert out["seen_by_child"] == expected