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
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
"""Installer must survive without an exact path resolver; no compiler runs and a lexical path is used."""
from __future__ import annotations
import os
import re
import shutil
import subprocess
import tempfile
import time
from pathlib import Path
import pytest
from unsloth_pwsh_runner import run_pwsh
def _shared_setup_1(root):
result = _run_powershell(
_script(
f"Remove-StudioStalePrivateTempDirectories -Root '{root}'",
sabotage = False,
names = ("Remove-StudioStalePrivateTempDirectories",),
)
)
assert result.returncode == 0, result.stderr
def _shared_setup_2():
uninstall = (REPO_ROOT / "scripts" / "uninstall.ps1").read_text(encoding = "utf-8")
block = _extract(r" function _RemoveStudioPrivateTempTrees \{.*?\n \}\n", uninstall)
preamble = (
'$ErrorActionPreference = "Stop"\nfunction _Substep { param([string]$Msg, [string]$Color) }'
)
return block, preamble, uninstall
REPO_ROOT = Path(__file__).resolve().parents[2]
INSTALL_PS1 = REPO_ROOT / "install.ps1"
requires_pwsh = pytest.mark.skipif(shutil.which("pwsh") is None, reason = "PowerShell is unavailable")
# A compiler that always fails: install.ps1 no longer calls Add-Type, so tests prove its absence.
SABOTAGE = (
"""function Add-Type { throw "(0) : error CS2001: Source file 'a.0.cs' could not be found" }"""
)
NO_NATIVE = '$env:UNSLOTH_EARLY_PYTHON_PROBE = "0"'
def _extract(pattern: str, source: str) -> str:
match = re.search(pattern, source, flags = re.DOTALL)
assert match is not None, f"install.ps1 block not found: {pattern}"
return match.group(0)
def _helpers(*names: str) -> str:
source = INSTALL_PS1.read_text(encoding = "utf-8")
return "\n".join(_extract(rf" function {name} \{{.*?\n \}}\n", source) for name in names)
LOCK_CHAIN = (
"Write-StudioLine",
"Test-StudioDirectoryUsable",
"Remove-StudioStalePrivateTempDirectories",
"Get-StudioPrivateTempRoots",
"New-StudioPrivateTempDirectory",
"Initialize-StudioTempEnvironment",
"Restore-StudioTempEnvironment",
"Write-StudioFinalPathDegraded",
"Resolve-StudioLinkTarget",
"Get-StudioSubstTarget",
"Get-ElevationState",
"Get-StudioEarlyPython",
"Invoke-StudioEarlyPythonScript",
"New-StudioChildScriptDirectory",
"Test-StudioChildScriptDirectoryElevated",
"Invoke-StudioSystem32ToolBounded",
"Get-StudioSystem32Tool",
"Test-StudioPathUnderAdminRoot",
"Test-StudioSddlRightsAreWrite",
"Test-StudioSddlPrincipalIsAdminOnly",
"Test-StudioSddlWritableByNonAdmin",
"Test-StudioDirectoryIsAdminOnly",
"Test-StudioInterpreterFileIsAdminOnly",
"Get-StudioLexicalParent",
"Test-StudioPlainFile",
"Test-UnslothCmdShimFile",
"Invoke-StudioEarlyPython",
"Get-StudioPythonFinalPath",
"Get-StudioLexicalPath",
"Resolve-StudioFinalPathInfo",
"Get-StudioFinalPath",
"Get-StudioPathHash",
"Get-StudioInstallMutexName",
"Test-StudioPathEqual",
"Enter-StudioNamedMutex",
"Enter-StudioInstallMutex",
"Exit-StudioInstallMutex",
)
def _run_powershell(script: str, env: dict[str, str] | None = None) -> subprocess.CompletedProcess:
# Through a FILE: Windows caps command lines at 32767 chars. utf-8-sig because PS 5.1
# reads a BOM-less .ps1 as ANSI; replacement on decode for the console codepage.
handle, name = tempfile.mkstemp(suffix = ".ps1")
os.close(handle)
try:
Path(name).write_text(script, encoding = "utf-8-sig")
# run_pwsh, not subprocess.run: a pwsh dead at startup gives the same empty stdout.
return run_pwsh(
["pwsh", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-File", name],
capture_output = True,
text = True,
encoding = "utf-8",
errors = "replace",
timeout = 120,
env = env if env is not None else os.environ.copy(),
)
finally:
try:
os.unlink(name)
except OSError:
pass
NOT_ELEVATED = "function Test-StudioChildScriptDirectoryElevated { return $false }"
def _script(
body: str,
*,
sabotage: bool = True,
names: tuple[str, ...] = LOCK_CHAIN,
elevated: bool = False,
) -> str:
return "\n".join(
[
'$ErrorActionPreference = "Stop"',
# Unset, Write-StudioLine falls back to Write-Host, which the caller cannot capture.
"$script:StudioStdoutRedirected = $true",
_helpers(*names),
SABOTAGE if sabotage else "",
"function Test-StudioChildScriptDirectoryElevated { return $true }"
if elevated
else NOT_ELEVATED,
body,
]
)
def _lines(result: subprocess.CompletedProcess, prefix: str) -> list[str]:
return [line for line in result.stdout.splitlines() if line.startswith(prefix)]
@requires_pwsh
def test_install_lock_is_acquired_when_the_native_helper_is_unavailable(tmp_path: Path):
"""Regression for issue 9140: with the native helper unavailable (throwing Add-Type, no type
support, or no interpreter), the install lock is still taken and the reason printed once."""
studio_home = tmp_path / "studio"
studio_home.mkdir()
result = _run_powershell(
_script(
f"""
{NO_NATIVE}
$name = Get-StudioInstallMutexName -Path '{studio_home}'
Write-Output "NAME:$name"
$mutex = Enter-StudioInstallMutex -Path '{studio_home}'
Write-Output "LOCK:$($null -ne $mutex)"
Exit-StudioInstallMutex -Mutex $mutex
""",
sabotage = False,
)
)
assert result.returncode == 0, result.stderr
assert _lines(result, "LOCK:") == ["LOCK:True"]
assert re.fullmatch(
r"NAME:Global\\UnslothStudioInstall-[0-9a-f]{64}", _lines(result, "NAME:")[0]
)
warnings = [
line for line in result.stdout.splitlines() if "Could not resolve a path exactly" in line
]
assert len(warnings) == 1
assert "using System" not in result.stdout
def _fresh_install_statement() -> str:
source = INSTALL_PS1.read_text(encoding = "utf-8")
return _extract(r" \$script:StudioInstallIsFresh = -not \(.*?\)\)\n", source)
def test_the_first_install_verdict_is_taken_before_anything_is_created() -> None:
"""Read the fresh-install verdict where $VenvDir is first computed, before the install lock and
path resolution; read later, this run's own venv makes every install look like an update."""
source = INSTALL_PS1.read_text(encoding = "utf-8")
verdict = source.index(_fresh_install_statement())
assert source.index(' $VenvDir = Join-Path $StudioHome "unsloth_studio"') < verdict
assert verdict < source.index("$studioInstallLock = Enter-StudioInstallLock -Path $StudioHome")
# Reset with the resolver state so a second `irm | iex` in one session gets a fresh verdict.
assert " $script:StudioInstallIsFresh = $null\n" in source
@requires_pwsh
@pytest.mark.parametrize(
"existing, warns",
[
pytest.param(None, False, id = "first_install_is_quiet"),
pytest.param("unsloth_studio", True, id = "existing_venv_warns"),
pytest.param("bin/unsloth.exe", True, id = "existing_launcher_warns"),
pytest.param(".venv", True, id = "legacy_venv_warns"),
],
)
def test_a_python_less_first_install_prints_no_degraded_warning(
tmp_path: Path, existing: str | None, warns: bool
):
"""A first install with no Python prints no degraded warning, as the interpreter rung has
nothing to run; existing installs keep it, since two spellings can escape one another's lock."""
studio_home = tmp_path / "studio"
studio_home.mkdir()
profile = tmp_path / "profile"
profile.mkdir()
if existing is not None:
target = studio_home / existing
if existing.endswith(".exe"):
target.parent.mkdir(parents = True)
target.write_text("")
else:
target.mkdir(parents = True)
result = _run_powershell(
_script(
f"""
{NO_NATIVE}
$env:USERPROFILE = '{profile}'
$script:StudioInstallIsFresh = $null
$StudioHome = '{studio_home}'
$VenvDir = Join-Path $StudioHome "unsloth_studio"
{_fresh_install_statement()}
Write-Output "FRESH:$script:StudioInstallIsFresh"
$info = Resolve-StudioFinalPathInfo -Path '{studio_home}'
Write-Output "EXACT:$($info.Exact)"
$other = Join-Path '{tmp_path}' 'elsewhere'
Write-Output "EQUAL:$([string](Test-StudioPathEqual -Left '{studio_home}' -Right $other) -eq '')"
$mutex = Enter-StudioInstallMutex -Path '{studio_home}'
Write-Output "LOCK:$($null -ne $mutex)"
Exit-StudioInstallMutex -Mutex $mutex
""",
sabotage = False,
)
)
assert result.returncode == 0, result.stderr
assert _lines(result, "FRESH:") == [f"FRESH:{not warns}"]
assert _lines(result, "EXACT:") == ["EXACT:False"]
assert _lines(result, "EQUAL:") == ["EQUAL:True"], result.stdout
assert _lines(result, "LOCK:") == ["LOCK:True"]
degraded = [l for l in result.stdout.splitlines() if "Could not resolve a path exactly" in l]
identity = [
l for l in result.stdout.splitlines() if "Could not resolve Unsloth path identity" in l
]
if warns:
assert len(degraded) == 1, result.stdout
assert len(identity) == 1, result.stdout
else:
assert not degraded, result.stdout
assert not identity, result.stdout
assert "[WARN]" not in result.stdout, result.stdout
@requires_pwsh
def test_a_dead_compiler_is_not_something_the_installer_can_notice(tmp_path: Path):
"""install.ps1 reaches no compiler, so an Add-Type that always throws must change nothing: the
lock is taken, the path resolves exactly, no warning prints; a failure means a compile came
back."""
studio_home = tmp_path / "studio"
studio_home.mkdir()
result = _run_powershell(
_script(
f"""
$mutex = Enter-StudioInstallMutex -Path '{studio_home}'
Write-Output "LOCK:$($null -ne $mutex)"
Exit-StudioInstallMutex -Mutex $mutex
Write-Output "EXACT:$((Resolve-StudioFinalPathInfo -Path '{studio_home}').Exact)"
"""
)
)
assert result.returncode == 0, result.stderr
assert _lines(result, "LOCK:") == ["LOCK:True"]
assert _lines(result, "EXACT:") == ["EXACT:True"]
assert not [
line for line in result.stdout.splitlines() if "Could not resolve a path exactly" in line
]
@requires_pwsh
def test_the_compiler_is_never_called_however_many_paths_are_resolved(tmp_path: Path):
"""The compiler must never be called (zero, not few): the old attempt and private-%TEMP% retry
both launched csc.exe, which behavioural antivirus blocked."""
result = _run_powershell(
_script(
f"""
$global:AddTypeCalls = 0
function Add-Type {{
$global:AddTypeCalls++
throw "(0) : error CS2001: Source file 'a.0.cs' could not be found"
}}
foreach ($i in 1..5) {{ Get-StudioFinalPath -Path '{tmp_path}' | Out-Null }}
Write-Output "CALLS:$global:AddTypeCalls"
""",
sabotage = False,
)
)
assert result.returncode == 0, result.stderr
assert _lines(result, "CALLS:") == ["CALLS:0"]
@requires_pwsh
def test_the_interpreter_is_looked_for_once_however_many_paths_are_resolved(tmp_path: Path):
"""The interpreter search is latched: five different paths cost five child probes plus one
search, six calls not ten; repeating one path would hit the per-path answer cache."""
paths = []
for i in range(5):
(tmp_path / f"p{i}").mkdir()
paths.append(f"'{tmp_path / f'p{i}'}'")
result = _run_powershell(
_script(
f"""
$global:Probes = 0
# A scriptblock copy, not Get-Item function:. A FunctionInfo re-resolves by NAME when
# it is invoked, so calling it from the replacement calls the replacement.
$global:RealProbe = ${{function:Invoke-StudioEarlyPython}}
function Invoke-StudioEarlyPython {{
param([string]$Exe, [string]$Path, [int]$TimeoutMs = 10000)
$global:Probes++
& $global:RealProbe -Exe $Exe -Path $Path -TimeoutMs $TimeoutMs
}}
foreach ($p in @({', '.join(paths)})) {{ Get-StudioFinalPath -Path $p | Out-Null }}
Write-Output "PROBES:$global:Probes"
""",
sabotage = False,
)
)
assert result.returncode == 0, result.stderr
if _lines(result, "PROBES:") == ["PROBES:0"]:
pytest.skip("no interpreter on this host, so there is no search to latch")
assert _lines(result, "PROBES:") == ["PROBES:6"]
@requires_pwsh
def test_a_path_still_resolves_with_no_usable_temp_at_all(tmp_path: Path):
"""An unusable %TEMP% may still cost the exact answer, since the child gets its script via a
file, but never the install: the ladder falls to the lexical rung, says so, and returns the
caller's broken variables unrepaired (issue 9140)."""
blocker = tmp_path / "blocker"
blocker.write_text("not a directory", encoding = "utf-8")
dead = str(blocker / "temp")
local_app_data = tmp_path / "localappdata"
local_app_data.mkdir()
studio_home = tmp_path / "studio"
studio_home.mkdir()
env = os.environ.copy()
env.update({"TMP": dead, "TEMP": dead, "LOCALAPPDATA": str(local_app_data)})
env.pop("USERPROFILE", None)
result = _run_powershell(
_script(
f"""
# Skip the session-wide temp fix, so nothing but the emit itself can save this.
$script:StudioTempChecked = $true
$info = Resolve-StudioFinalPathInfo -Path '{studio_home}'
Write-Output "PATH:$($info.Path)"
Write-Output "TMP:$env:TMP"
Write-Output "TEMP:$env:TEMP"
""",
sabotage = False,
),
env = env,
)
assert result.returncode == 0, result.stderr
assert _lines(result, "TMP:") == [f"TMP:{dead}"]
assert _lines(result, "TEMP:") == [f"TEMP:{dead}"]
assert list((local_app_data / "Unsloth Studio" / "temp").glob("ust-*")) == []
assert _lines(result, "PATH:")[0].startswith("PATH:")
assert _lines(result, "PATH:") != ["PATH:"]
@requires_pwsh
def test_resolver_follows_a_linked_ancestor(tmp_path: Path):
physical = tmp_path / "physical" / "studio"
physical.mkdir(parents = True)
alias = tmp_path / "alias"
try:
alias.symlink_to(tmp_path / "physical", target_is_directory = True)
except (OSError, NotImplementedError):
pytest.skip("creating a symlink requires privilege on this host")
result = _run_powershell(
_script(
f"""
Write-Output "PATH:$(Get-StudioFinalPath -Path '{alias / "studio"}')"
Write-Output "EQUAL:$(Test-StudioPathEqual -Left '{alias / "studio"}' -Right '{physical}')"
Write-Output "MISSING:$(Get-StudioFinalPath -Path '{alias / "studio" / "not" / "there"}')"
"""
)
)
assert result.returncode == 0, result.stderr
assert _lines(result, "PATH:") == [f"PATH:{physical}"]
assert _lines(result, "EQUAL:") == ["EQUAL:True"]
assert _lines(result, "MISSING:") == [f"MISSING:{physical / 'not' / 'there'}"]
@requires_pwsh
def test_resolver_terminates_on_a_link_loop(tmp_path: Path):
left = tmp_path / "left"
right = tmp_path / "right"
try:
left.symlink_to(right, target_is_directory = True)
right.symlink_to(left, target_is_directory = True)
except (OSError, NotImplementedError):
pytest.skip("creating a symlink requires privilege on this host")
result = _run_powershell(
_script(
f"""
Write-Output "PATH:$(Get-StudioFinalPath -Path '{left}')"
"""
)
)
assert result.returncode == 0, result.stderr
assert len(_lines(result, "PATH:")) == 1
@requires_pwsh
def test_unequal_paths_are_unknown_rather_than_different_when_inexact(tmp_path: Path):
"""Uses NO_NATIVE rather than sabotaging Add-Type, which the installer no longer calls; the
capability gate is now the only route to an inexact answer, where unequal paths are unknown."""
left = tmp_path / "left"
right = tmp_path / "right"
left.mkdir()
right.mkdir()
result = _run_powershell(
_script(
f"""
{NO_NATIVE}
$answer = Test-StudioPathEqual -Left '{left}' -Right '{right}'
Write-Output "NULL:$($null -eq $answer)"
"""
)
)
assert result.returncode == 0, result.stderr
# $null makes the caller take BOTH runtime locks; $false would silently drop one.
assert _lines(result, "NULL:") == ["NULL:True"]
@requires_pwsh
def test_a_directory_that_will_not_give_a_file_back_is_not_usable(tmp_path: Path):
"""A temp directory must also allow deleting a file, not just create and read one: a denied
Delete ACE passes a create-and-read probe yet broke csc.exe cleanup."""
good = tmp_path / "good"
good.mkdir()
result = _run_powershell(
_script(
f"""
Write-Output "BEFORE:$(Test-StudioDirectoryUsable -Path '{good}')"
# Every delete is a no-op from here, which is what a denied Delete ACE looks
# like to the caller: no exception, the file simply stays.
function Remove-Item {{ param([string]$LiteralPath, [switch]$Force, [string]$ErrorAction) }}
Write-Output "AFTER:$(Test-StudioDirectoryUsable -Path '{good}')"
""",
sabotage = False,
names = ("Write-StudioLine", "Test-StudioDirectoryUsable"),
)
)
assert result.returncode == 0, result.stderr
assert _lines(result, "BEFORE:") == ["BEFORE:True"]
assert _lines(result, "AFTER:") == ["AFTER:False"]
assert len(list(good.glob("unsloth-probe-*.tmp"))) == 1
@requires_pwsh
def test_unusable_temp_is_replaced_and_then_restored(tmp_path: Path):
blocker = tmp_path / "blocker"
blocker.write_text("not a directory")
env = os.environ.copy()
env["TMP"] = str(blocker / "temp")
env.pop("TEMP", None)
result = _run_powershell(
_script(
"""
Initialize-StudioTempEnvironment
Write-Output "USABLE:$(Test-StudioDirectoryUsable -Path $env:TMP)"
Write-Output "MATCHED:$($env:TMP -eq $env:TEMP)"
$replacement = $env:TMP
Restore-StudioTempEnvironment
Write-Output "TMP:$env:TMP"
Write-Output "TEMPSET:$($null -ne $env:TEMP)"
Write-Output "KEPT:$(Test-Path -LiteralPath $replacement)"
""",
names = (
"Write-StudioLine",
"Test-StudioDirectoryUsable",
"Remove-StudioStalePrivateTempDirectories",
"Get-StudioPrivateTempRoots",
"New-StudioPrivateTempDirectory",
"Initialize-StudioTempEnvironment",
"Restore-StudioTempEnvironment",
),
),
env = env,
)
assert result.returncode == 0, result.stderr
assert _lines(result, "USABLE:") == ["USABLE:True"]
# Both, because Windows reads TMP before TEMP.
assert _lines(result, "MATCHED:") == ["MATCHED:True"]
assert _lines(result, "TMP:") == [f"TMP:{env['TMP']}"]
assert _lines(result, "TEMPSET:") == ["TEMPSET:False"]
assert _lines(result, "KEPT:") == ["KEPT:True"]
def _same_path(got: str, expected: str) -> bool:
"""Compare paths ignoring spelling; GetFullPath re-roots POSIX fixtures onto the current drive."""
def norm(value: str) -> str:
value = value.replace("\\", "/")
if len(value) > 1 and value[1] == ":":
value = value[2:]
return value.rstrip("/").lower()
return norm(got) == norm(expected)
_NT_DEVICE_PREFIX = "\\??\\"
_LIST = "$l=[System.Collections.Generic.List[string]]::new(); {0}; $l"
# Shapes (Get-Item).Target really returns: 5.1 gives a collection, junctions use NT device
# form, system links report nothing. Stubbed since Linux cannot produce them.
_TARGET_SHAPES = [
("generic collection", _LIST.format('$l.Add("/real/target")'), "/real/target"),
(
"generic collection, several entries",
_LIST.format('$l.Add("/first"); $l.Add("/second")'),
"/first",
),
("array", '@("/real/target")', "/real/target"),
("bare string", '"/real/target"', "/real/target"),
("nt device prefix", f'"{_NT_DEVICE_PREFIX}/real/target"', "/real/target"),
(
"nt device prefix in a collection",
_LIST.format(f'$l.Add("{_NT_DEVICE_PREFIX}/real/target")'),
"/real/target",
),
("relative to the link", '"sibling"', "/some/sibling"),
("pointing at itself", '"/some/link"', ""),
("null (system junction, AppExecLink)", "$null", ""),
("empty", '""', ""),
("whitespace", '" "', ""),
("throws (access denied)", '$(throw "access denied")', ""),
]
@requires_pwsh
@pytest.mark.parametrize(
"shape,expression,expected",
_TARGET_SHAPES,
ids = [shape.replace(" ", "-") for shape, _, _ in _TARGET_SHAPES],
)
def test_link_targets_of_every_windows_powershell_5_1_shape(
shape: str, expression: str, expected: str
):
result = _run_powershell(
"\n".join(
[
'$ErrorActionPreference = "Stop"',
_helpers("Resolve-StudioLinkTarget"),
"function Get-Item {",
" param([string]$LiteralPath, [switch]$Force, [string]$ErrorAction)",
" $target = $null",
f" try {{ $target = {expression} }} catch {{ $target = $null }}",
" $item = New-Object psobject",
" $item | Add-Member -MemberType NoteProperty -Name Target -Value $target",
" Write-Output $item",
"}",
"Write-Output \"TARGET:[$(Resolve-StudioLinkTarget -Path '/some/link')]\"",
]
)
)
assert result.returncode == 0, result.stderr
got = _lines(result, "TARGET:")
assert len(got) == 1, got
assert _same_path(got[0][len("TARGET:[") : -1], expected)
def _dead_pid(start: int = 4_000_000) -> int:
"""A PID that is not running, so a ust-<pid>- directory reads as abandoned."""
for candidate in range(start, start + 400):
try:
os.kill(candidate, 0)
except ProcessLookupError:
return candidate
except (OSError, PermissionError):
continue
return start
_DEAD_PID = _dead_pid()
# Cannot reuse _DEAD_PID with other hex case: case-insensitive filesystems merge the names.
_OTHER_DEAD_PID = _dead_pid(_DEAD_PID + 1)
@requires_pwsh
@pytest.mark.parametrize(
"raw,expected",
[
("\\??\\UNC\\server\\share\\dir", "\\\\server\\share\\dir"),
("\\??\\unc\\server\\share", "\\\\server\\share"),
("\\??\\C:\\real\\target", "C:\\real\\target"),
(
"\\??\\Volume{11111111-2222-3333-4444-555555555555}\\dir",
"\\\\?\\Volume{11111111-2222-3333-4444-555555555555}\\dir",
),
],
ids = [
"unc-device-form",
"lowercase-unc",
"ordinary-device-form",
"mounted-folder-volume-guid",
],
)
def test_the_nt_device_prefix_becomes_a_usable_path(raw: str, expected: str):
"""\\??\\UNC\\server\\share is the device spelling of \\\\server\\share.
Dropping the first four characters leaves "UNC\\server\\share", which reads as
a RELATIVE path and gets combined with the link's own parent, inventing an
identity that matches nothing real -- and a wrong identity here is a wrong
mutex. Whether the rewritten form counts as rooted is platform-dependent, so
what is asserted is the rewrite; the Windows end of it is covered on the 5.1
probe.
"""
result = _run_powershell(
"\n".join(
[
'$ErrorActionPreference = "Stop"',
_helpers("Resolve-StudioLinkTarget"),
"function Get-Item {",
" param([string]$LiteralPath, [switch]$Force, [string]$ErrorAction)",
" $item = New-Object psobject",
f' $item | Add-Member -MemberType NoteProperty -Name Target -Value "{raw}"',
" Write-Output $item",
"}",
"Write-Output \"TARGET:[$(Resolve-StudioLinkTarget -Path '/some/link')]\"",
]
)
)
assert result.returncode == 0, result.stderr
got = _lines(result, "TARGET:")[0]
assert expected in got
assert "UNC\\" not in got and "unc\\" not in got
@requires_pwsh
def test_a_drive_less_rooted_target_lands_on_the_link_own_root(tmp_path: Path):
"""A symlink may store "\\real", which is rooted but names no drive.
IsPathRooted says true, so anchoring against the link is skipped and
GetFullPath then resolves the target against whatever drive the PROCESS
happens to be sitting on. Windows resolves it on the LINK's volume, so a
link on D: must never normalize to C:\\real: that is a different directory,
and it would be the one the fallback mutex and the in-use scan protect.
"""
link = tmp_path / "nested" / "link"
link.parent.mkdir(parents = True)
result = _run_powershell(
"\n".join(
[
'$ErrorActionPreference = "Stop"',
_helpers("Resolve-StudioLinkTarget"),
"function Get-Item {",
" param([string]$LiteralPath, [switch]$Force, [string]$ErrorAction)",
" $item = New-Object psobject",
' $item | Add-Member -MemberType NoteProperty -Name Target -Value "\\real"',
" Write-Output $item",
"}",
f"$root = [System.IO.Path]::GetPathRoot('{link}')",
f"Write-Output \"TARGET:[$(Resolve-StudioLinkTarget -Path '{link}')]\"",
'Write-Output "ROOT:[$root]"',
]
)
)
assert result.returncode == 0, result.stderr
got = _lines(result, "TARGET:")[0].split("[", 1)[1].rstrip("]")
root = _lines(result, "ROOT:")[0].split("[", 1)[1].rstrip("]")
assert got.startswith(root), f"{got} is not on the link's own root {root}"
assert got.rstrip("\\/").endswith("real")
assert "nested" not in got
@requires_pwsh
@pytest.mark.parametrize(
"tmp,expect_override",
[
(" ", True),
("\t", True),
("", False),
(None, False),
],
ids = ["whitespace-tmp", "tab-tmp", "empty-tmp", "absent-tmp"],
)
def test_a_whitespace_only_tmp_is_set_as_far_as_windows_is_concerned(
tmp_path: Path, tmp: str | None, expect_override: bool
):
"""GetTempPath uses the first non-empty of TMP/TEMP, so a whitespace-only TMP is what Windows
and child processes use; treating it as unset probes a healthy TEMP and leaves every later
step pointed at a path that cannot exist."""
good = tmp_path / "good"
good.mkdir()
local_app_data = tmp_path / "localappdata"
local_app_data.mkdir()
env = os.environ.copy()
env.pop("TMP", None)
if tmp is not None:
env["TMP"] = tmp
env["TEMP"] = str(good)
env["LOCALAPPDATA"] = str(local_app_data)
env["USERPROFILE"] = str(tmp_path / "profile")
result = _run_powershell(
_script(
"""
Initialize-StudioTempEnvironment
Write-Output "TMP:[$env:TMP]"
""",
sabotage = False,
names = (
"Write-StudioLine",
"Test-StudioDirectoryUsable",
"Remove-StudioStalePrivateTempDirectories",
"Set-StudioPrivateTempOwner",
"Get-StudioPrivateTempRoots",
"New-StudioPrivateTempDirectory",
"Initialize-StudioTempEnvironment",
"Restore-StudioTempEnvironment",
),
),
env = env,
)
assert result.returncode == 0, result.stderr
got = _lines(result, "TMP:")[0][len("TMP:[") : -1]
if expect_override:
assert got not in ("", tmp)
assert "ust-" in got
else:
assert "ust-" not in got
@requires_pwsh
def test_final_normalization_strips_every_extended_prefix():
r"""This string is hashed into the runtime mutex, so Python decides its shape.
unsloth_cli/_studio_runtime_gate.py::_resolved_windows_path strips \\?\
unconditionally, after one special case for \\?\UNC\. A volume GUID kept its
prefix here for a while, on the reasoning that the bare "Volume{GUID}\x" is
not rooted. That is true, and it matters while a LINK TARGET is being
anchored, which is why Resolve-StudioLinkTarget still keeps the extended
form. It does not matter here, and keeping it made the installer and a
running Unsloth compute different names for one directory.
"""
source = INSTALL_PS1.read_text(encoding = "utf-8")
body = _extract(r" function Resolve-StudioFinalPathInfo \{.*?\n \}\n", source)
assert "'\\\\?\\Volume{'" not in body
assert "$resolved.Substring(4)" in body
gate = (REPO_ROOT / "unsloth_cli" / "_studio_runtime_gate.py").read_text(encoding = "utf-8")
assert 'resolved.startswith("\\\\\\\\?\\\\UNC\\\\")' in gate
assert "resolved = resolved[4:]" in gate
assert "Volume{" not in gate
@requires_pwsh
@pytest.mark.parametrize(
"resolved,expected",
[
("\\\\?\\C:\\Users\\bob\\studio", "C:\\Users\\bob\\studio"),
("\\\\?\\UNC\\server\\share\\studio", "\\\\server\\share\\studio"),
(
"\\\\?\\Volume{11111111-2222-3333-4444-555555555555}\\data\\studio",
"Volume{11111111-2222-3333-4444-555555555555}\\data\\studio",
),
],
ids = ["extended-dos", "extended-unc", "volume-guid"],
)
def test_the_installer_and_the_runtime_gate_normalize_alike(resolved: str, expected: str):
"""Byte-for-byte agreement, or the two sides key their lock on different names."""
source = INSTALL_PS1.read_text(encoding = "utf-8")
body = _extract(r" function Resolve-StudioFinalPathInfo \{.*?\n \}\n", source)
branch = _extract(
r" if \(\$resolved\.StartsWith\('\\\\\?\\UNC\\'.*?\n \}\n", body
)
result = _run_powershell(
"\n".join(
[
'$ErrorActionPreference = "Stop"',
f"$resolved = '{resolved}'",
branch,
'Write-Output "OUT:$resolved"',
]
)
)
assert result.returncode == 0, result.stderr
got = _lines(result, "OUT:")[0][len("OUT:") :]
assert got == expected
import importlib.util
spec = importlib.util.spec_from_file_location(
"_studio_runtime_gate", REPO_ROOT / "unsloth_cli" / "_studio_runtime_gate.py"
)
gate = importlib.util.module_from_spec(spec)
spec.loader.exec_module(gate)
python_side = resolved
if python_side.startswith("\\\\?\\UNC\\"):
python_side = "\\\\" + python_side[8:]
elif python_side.startswith("\\\\?\\"):
python_side = python_side[4:]
assert got == python_side
@requires_pwsh
@pytest.mark.parametrize(
"path,expected",
[
("X:\\", "D:\\real\\dir"),
("X:", "D:\\real\\dir"),
("x:\\venv", "D:\\real\\dir"),
("C:\\other", ""),
],
ids = ["drive-root", "bare-drive", "lowercase-letter", "unmapped-drive"],
)
def test_a_subst_drive_folds_onto_its_target(path: str, expected: str):
"""The runtime gate resolves SUBST drives (Path.resolve does this), so one directory under two
spellings gets one mutex; subst.exe is the only compiler-free source; Get-PSDrive,
Win32_LogicalDisk, GetFullPath and Resolve-Path reveal nothing."""
result = _run_powershell(
"\n".join(
[
'$ErrorActionPreference = "Stop"',
_helpers("Get-StudioSubstTarget"),
'$script:StudioSubstMap = @{ "X" = "D:\\real\\dir" }',
f"Write-Output \"SUBST:[$(Get-StudioSubstTarget -Path '{path}')]\"",
]
)
)
assert result.returncode == 0, result.stderr
got = _lines(result, "SUBST:")[0][len("SUBST:[") : -1]
if expected:
assert got.startswith(expected)
else:
assert got == ""
@requires_pwsh
def test_the_recorded_owner_outranks_the_name(tmp_path: Path):
"""The PID in the name is the installer's and exits; the live user is the Unsloth it
autostarted, which owner.pid records, so the name alone must not clear its %TEMP%."""
root = tmp_path / "root"
root.mkdir()
keep = root / f"ust-{_DEAD_PID}-000000aa"
keep.mkdir()
(keep / "owner.pid").write_text(str(os.getpid()), encoding = "utf-8")
drop = root / f"ust-{os.getpid()}-000000bb"
drop.mkdir()
(drop / "owner.pid").write_text(str(_DEAD_PID), encoding = "utf-8")
aged = time.time() - 3 * 24 * 3600
for d in (keep, drop):
os.utime(d, (aged, aged))
_shared_setup_1(root)
assert keep.exists()
assert not drop.exists()
@requires_pwsh
def test_the_sweep_keeps_a_directory_whose_owner_is_still_running(tmp_path: Path):
"""An Unsloth autostarted by an earlier install owns one of these as its %TEMP% and can outlive
the one-day cutoff unwritten; the sweep runs before the runtime mutex is taken, so age alone
must not prove it unused."""
root = tmp_path / "root"
root.mkdir()
live = root / f"ust-{os.getpid()}-01d01d01"
live.mkdir()
(live / "in-use.txt").write_text("a live process owns this", encoding = "utf-8")
abandoned = root / f"ust-{_DEAD_PID}-01d01d01"
abandoned.mkdir()
(abandoned / "owner.pid").write_text(str(_DEAD_PID), encoding = "utf-8")
aged = time.time() - 3 * 24 * 3600
os.utime(live, (aged, aged))
os.utime(abandoned, (aged, aged))
_shared_setup_1(root)
assert (live / "in-use.txt").exists()
assert not abandoned.exists()
@requires_pwsh
def test_a_healthy_temp_still_sweeps_what_an_earlier_degraded_run_left(tmp_path: Path):
"""Only the allocator sweeps and a healthy host skips it, so leftovers of degraded runs would
age in place; a healthy temp must still sweep them."""
good = tmp_path / "good"
good.mkdir()
local_app_data = tmp_path / "localappdata"
root = local_app_data / "Unsloth Studio" / "temp"
root.mkdir(parents = True)
abandoned = root / f"ust-{_DEAD_PID}-01d01d01"
abandoned.mkdir()
(abandoned / "owner.pid").write_text(str(_DEAD_PID), encoding = "utf-8")
(abandoned / "leftover.bin").write_text("half a download", encoding = "utf-8")
aged = time.time() - 3 * 24 * 3600
os.utime(abandoned, (aged, aged))
env = os.environ.copy()
env.update({"TMP": str(good), "TEMP": str(good), "LOCALAPPDATA": str(local_app_data)})
env.pop("USERPROFILE", None)
result = _run_powershell(
_script(
"""
Initialize-StudioTempEnvironment
Write-Output "TMP:$env:TMP"
Write-Output "OVERRIDE:$($null -ne $script:StudioTempOverride)"
""",
sabotage = False,
),
env = env,
)
assert result.returncode == 0, result.stderr
assert not abandoned.exists()
assert _lines(result, "TMP:") == [f"TMP:{good}"]
assert _lines(result, "OVERRIDE:") == ["OVERRIDE:False"]
@requires_pwsh
def test_probing_the_host_temp_never_creates_it(tmp_path: Path):
"""An inherited TMP naming nothing is unusable: New-Item -Force builds the whole parent chain,
so probing the host temp must never create it, even on a stale or mistyped value."""
ghost = tmp_path / "ghost" / "deeper"
result = _run_powershell(
_script(
f"""
Write-Output "USABLE:$(Test-StudioDirectoryUsable -Path '{ghost}')"
Write-Output "EXISTS:$(Test-Path -LiteralPath '{ghost}')"
""",
sabotage = False,
names = ("Write-StudioLine", "Test-StudioDirectoryUsable"),
)
)
assert result.returncode == 0, result.stderr
assert _lines(result, "USABLE:") == ["USABLE:False"]
assert _lines(result, "EXISTS:") == ["EXISTS:False"]
assert not ghost.exists()
owned = tmp_path / "owned" / "ust-1-aaaaaaaa"
result = _run_powershell(
_script(
f"Write-Output \"USABLE:$(Test-StudioDirectoryUsable -Path '{owned}' -CreateIfMissing)\"",
sabotage = False,
names = ("Write-StudioLine", "Test-StudioDirectoryUsable"),
)
)
assert result.returncode == 0, result.stderr
assert _lines(result, "USABLE:") == ["USABLE:True"]
assert owned.is_dir()
@requires_pwsh
def test_an_undeletable_probe_file_is_reclaimed_next_time(tmp_path: Path):
"""A probe whose deletion failed is reclaimed by a later sweep, else each run leaves one more
file in the host temp; only aged probes go, sparing concurrent ones."""
good = tmp_path / "good"
good.mkdir()
stale = good / "unsloth-probe-deadbeef.tmp"
stale.write_text("left by a run that could not delete it", encoding = "utf-8")
fresh = good / "unsloth-probe-cafebabe.tmp"
fresh.write_text("another process is using this right now", encoding = "utf-8")
theirs = good / "unsloth-probe-report.tmp"
theirs.write_text("not ours", encoding = "utf-8")
theirs_long = good / "unsloth-probe-deadbeefcafe.tmp"
theirs_long.write_text("not ours either", encoding = "utf-8")
aged = time.time() - 3 * 24 * 3600
for path in (stale, theirs, theirs_long):
os.utime(path, (aged, aged))
result = _run_powershell(
_script(
f"Write-Output \"USABLE:$(Test-StudioDirectoryUsable -Path '{good}')\"",
sabotage = False,
names = ("Write-StudioLine", "Test-StudioDirectoryUsable"),
)
)
assert result.returncode == 0, result.stderr
assert _lines(result, "USABLE:") == ["USABLE:True"]
assert not stale.exists()
assert fresh.exists()
assert theirs.exists(), "the sweep took a file that only shares the prefix"
assert theirs_long.exists(), "the sweep took a file that only shares the prefix"
@requires_pwsh
def test_a_root_that_fails_its_probe_is_not_left_behind(tmp_path: Path):
"""A failed install must not conjure the data directory tree.
The probe creates each candidate before testing it, so on a host where
every root fails, giving up used to leave a "Unsloth Studio" tree on a
machine Unsloth was never installed on.
"""
local_app_data = tmp_path / "localappdata"
local_app_data.mkdir()
user_profile = tmp_path / "userprofile"
user_profile.mkdir()
keep = local_app_data / "Unsloth Studio" / "studio.port"
keep.parent.mkdir(parents = True)
keep.write_text("41343", encoding = "utf-8")
env = os.environ.copy()
env["LOCALAPPDATA"] = str(local_app_data)
env["USERPROFILE"] = str(user_profile)
result = _run_powershell(
_script(
"""
# Every candidate fails its probe, whatever the filesystem says.
function Test-StudioDirectoryUsable {
param([string]$Path, [switch]$CreateIfMissing)
# Creates unconditionally, the way the real probe did before it took the
# switch, so this measures the caller rather than the stub.
New-Item -ItemType Directory -Path $Path -Force | Out-Null
return $false
}
Write-Output "PRIVATE:$(New-StudioPrivateTempDirectory)"
""",
sabotage = False,
names = (
"Write-StudioLine",
"Remove-StudioStalePrivateTempDirectories",
"Get-StudioPrivateTempRoots",
"New-StudioPrivateTempDirectory",
),
),
env = env,
)
assert result.returncode == 0, result.stderr
assert _lines(result, "PRIVATE:") == ["PRIVATE:"]
assert not (user_profile / ".unsloth" / ".cache").exists()
assert not list(user_profile.rglob("ust-*")), list(user_profile.rglob("*"))
assert keep.exists()
assert not list(local_app_data.rglob("ust-*")), list(local_app_data.rglob("*"))
assert not (local_app_data / "Unsloth Studio" / "temp").exists()
@requires_pwsh
def test_the_sweep_only_takes_directories_the_allocator_could_have_made(tmp_path: Path):
"""Shape, not prefix. The delete is recursive and this is the only owner test.
A prefix match takes "ust-legacy" and "ust-user-cache" as well, and neither
has a parseable PID, so the liveness check is skipped for exactly the names
least likely to be ours. scripts/uninstall.ps1 already required the shape;
the installer sweep had drifted away from it.
"""
root = tmp_path / "root"
root.mkdir()
aged = time.time() - 3 * 24 * 3600
ours = root / f"ust-{_DEAD_PID}-abcdef01"
ours.mkdir()
(ours / "owner.pid").write_text(str(_DEAD_PID), encoding = "utf-8")
(ours / "scratch.bin").write_text("x", encoding = "utf-8")
keep = []
# Windows names are case-insensitive, so uppercase must count as ours; a second dead PID
# avoids colliding with the lowercase directory on case-insensitive filesystems.
upper = root / f"ust-{_OTHER_DEAD_PID}-ABCDEF01"
upper.mkdir()
(upper / "owner.pid").write_text(str(_OTHER_DEAD_PID), encoding = "utf-8")
for name in ("ust-legacy", "ust-user-cache", "ust-notapid-abcdef01", "ust-", "ust-12-abcdefg1"):
victim = root / name
victim.mkdir()
(victim / "keep.txt").write_text("not ours", encoding = "utf-8")
keep.append(victim)
for path in [ours, upper] + keep:
os.utime(path, (aged, aged))
_shared_setup_1(root)
assert not ours.exists()
assert not upper.exists()
for victim in keep:
assert (victim / "keep.txt").exists(), f"{victim.name} was swept"
@requires_pwsh
def test_a_resolver_that_runs_and_fails_says_so_once(tmp_path: Path):
"""A resolver child that runs but returns nothing (sandbox, symlink loop, AV kill) must print
the degraded warning; Exact = $false already fails the lock closed but was silent."""
studio = tmp_path / "studio"
studio.mkdir()
result = _run_powershell(
_script(
f"""
# Present and useless, which is the state under test. Counted, because a stub the
# resolver never reaches produces the same outward fallback as one that answered
# nothing: without the counter this test passes while proving nothing.
$global:Calls = 0
function Get-StudioPythonFinalPath {{
param([string]$Path)
$global:Calls++
return $null
}}
foreach ($i in 1..3) {{ $null = Resolve-StudioFinalPathInfo -Path '{studio}' }}
$info = Resolve-StudioFinalPathInfo -Path '{studio}'
Write-Output "EXACT:$($info.Exact)"
Write-Output "PATH:$($info.Path)"
Write-Output "CALLS:$global:Calls"
""",
sabotage = False,
)
)
assert result.returncode == 0, result.stderr
assert _lines(result, "EXACT:") == ["EXACT:False"]
assert _lines(result, "PATH:")[0].endswith("studio")
warnings = [
line for line in result.stdout.splitlines() if "Could not resolve a path exactly" in line
]
assert len(warnings) == 1, warnings
assert _lines(result, "CALLS:") == ["CALLS:4"]
@requires_pwsh
def test_an_unrecorded_owner_is_unknown_rather_than_abandoned(tmp_path: Path):
"""The name's PID is the installer's, and it can be dead while Unsloth is not.
An installer killed between Start-Process and the owner.pid write leaves a
directory whose only owner evidence is a dead installer PID, while the
Unsloth it started is using that directory as its own %TEMP%. Reading is
proof; guessing from the name is not, so the two get different patience.
"""
root = tmp_path / "root"
root.mkdir()
two_days = time.time() - 2 * 24 * 3600
eight_days = time.time() - 8 * 24 * 3600
unknown = root / f"ust-{_DEAD_PID}-aaaaaaaa"
unknown.mkdir()
(unknown / "in-use.txt").write_text("a live Unsloth may own this", encoding = "utf-8")
os.utime(unknown, (two_days, two_days))
ancient = root / f"ust-{_DEAD_PID}-bbbbbbbb"
ancient.mkdir()
os.utime(ancient, (eight_days, eight_days))
recorded = root / f"ust-{_DEAD_PID}-cccccccc"
recorded.mkdir()
(recorded / "owner.pid").write_text(str(_DEAD_PID), encoding = "utf-8")
os.utime(recorded, (two_days, two_days))
_shared_setup_1(root)
assert (unknown / "in-use.txt").exists(), "an unrecorded owner was read as abandoned"
assert not ancient.exists(), "an unrecorded owner is never collected at all"
assert not recorded.exists(), "a recorded dead owner should still go at one day"
@requires_pwsh
def test_the_stale_sweep_never_deletes_through_a_link(tmp_path: Path):
root = tmp_path / "root"
root.mkdir()
precious = tmp_path / "precious"
precious.mkdir()
(precious / "keepme.txt").write_text("do not delete", encoding = "utf-8")
stale = root / f"ust-{_DEAD_PID}-01d01d01"
stale.mkdir()
(stale / "owner.pid").write_text(str(_DEAD_PID), encoding = "utf-8")
(stale / "junk").write_text("x", encoding = "utf-8")
fresh = root / f"ust-{_DEAD_PID}-0e0e0e0e"
fresh.mkdir()
(fresh / "owner.pid").write_text(str(_DEAD_PID), encoding = "utf-8")
link = root / f"ust-{_DEAD_PID}-11111111"
try:
link.symlink_to(precious, target_is_directory = True)
except (OSError, NotImplementedError):
pytest.skip("creating a symlink requires privilege on this host")
aged = time.time() - 3 * 24 * 3600
os.utime(stale, (aged, aged))
try:
os.utime(link, (aged, aged), follow_symlinks = False)
except (NotImplementedError, OSError):
# Windows has no follow_symlinks=False for utime; aging the link otherwise writes through it.
pytest.skip("this host cannot age a link without writing through it")
_shared_setup_1(root)
assert not stale.exists()
assert fresh.exists()
assert not link.is_symlink()
# 5.1's Remove-Item -Recurse follows a junction and empties its target.
assert (precious / "keepme.txt").exists()
@requires_pwsh
def test_a_failure_before_the_lock_still_restores_temp(tmp_path: Path):
"""Most install failures return long before the finally that frees the locks."""
blocker = tmp_path / "blocker"
blocker.write_text("not a directory", encoding = "utf-8")
env = os.environ.copy()
env["TMP"] = str(blocker / "temp")
env["TEMP"] = str(blocker / "temp")
result = _run_powershell(
_script(
"""
$TauriMode = $false
function Write-TauriLog { param([string]$Tag, [string]$Message) }
Initialize-StudioTempEnvironment
Write-Output "REDIRECTED:$($env:TMP -ne $env:ORIGINAL_TMP)"
try { Exit-InstallFailure -Message "preflight failed" } catch {}
Write-Output "TMP:$env:TMP"
Write-Output "TEMP:$env:TEMP"
""",
names = (
"Write-StudioLine",
"Exit-InstallFailure",
"Test-StudioDirectoryUsable",
"Remove-StudioStalePrivateTempDirectories",
"Get-StudioPrivateTempRoots",
"New-StudioPrivateTempDirectory",
"Initialize-StudioTempEnvironment",
"Restore-StudioTempEnvironment",
),
),
env = {**env, "ORIGINAL_TMP": str(blocker / "temp")},
)
assert result.returncode == 0, result.stderr
assert _lines(result, "REDIRECTED:") == ["REDIRECTED:True"]
assert _lines(result, "TMP:") == [f"TMP:{env['TMP']}"]
assert _lines(result, "TEMP:") == [f"TEMP:{env['TEMP']}"]
def test_the_private_temp_directory_is_somewhere_uninstall_reclaims():
"""It outlives the install, so it has to sit where the uninstaller looks."""
source = INSTALL_PS1.read_text(encoding = "utf-8")
uninstall = (REPO_ROOT / "scripts" / "uninstall.ps1").read_text(encoding = "utf-8")
roots = _extract(r" function Get-StudioPrivateTempRoots \{.*?\n \}\n", source)
assert 'Join-Path $env:LOCALAPPDATA "Unsloth Studio\\temp"' in roots
assert '"Unsloth Studio"' in uninstall
assert 'Join-Path $env:USERPROFILE ".unsloth\\.cache\\temp"' in roots
assert (
'$defaultCache = if ($defaultUnslothHome) { Join-Path $defaultUnslothHome ".cache" }'
in uninstall
)
assert ".unsloth\\temp" not in roots
# LOCALAPPDATA is dropped in service/CI contexts; the uninstaller must resolve the same fallback.
assert '[Environment]::GetFolderPath("LocalApplicationData")' in roots
assert "foreach ($root in @($env:LOCALAPPDATA, $knownLocalAppData)) {" in uninstall
# The second root gets the temp tree only: it may name another user's profile.
assert 'Join-Path $root "Unsloth Studio\\temp"' in uninstall
assert "_RemoveStudioPrivateTempTrees -Paths $privateTempDirs" in uninstall
assert "foreach ($d in $defaultDataDirs)" not in uninstall
@requires_pwsh
def test_the_uninstall_sweep_leaves_a_live_owner_and_never_follows_a_link(tmp_path: Path):
"""The uninstall sweep preserves live owners from other roots or users, as install.ps1 does, and
never walks a temp link: the target's children lack ReparsePoint, so recursion would hit an
unrelated tree."""
block, preamble, uninstall = _shared_setup_2()
temp = tmp_path / "Unsloth Studio" / "temp"
temp.mkdir(parents = True)
live = temp / "ust-1234-abcdef01"
live.mkdir()
(live / "owner.pid").write_text(str(os.getpid()), encoding = "utf-8")
dead = temp / "ust-1234-abcdef02"
dead.mkdir()
(dead / "owner.pid").write_text(str(_DEAD_PID), encoding = "utf-8")
result = _run_powershell(
"\n".join(
[
preamble,
block,
f"_RemoveStudioPrivateTempTrees -Paths @('{temp}') -PrimaryPath '{temp}'",
'Write-Output "DONE:1"',
]
)
)
assert result.returncode == 0, result.stderr
assert _lines(result, "DONE:") == ["DONE:1"]
assert (live / "owner.pid").exists(), "a live owner's temp was removed"
assert not dead.exists()
victim = tmp_path / "victim"
victim.mkdir()
(victim / "ust-1234-abcdef03").mkdir()
(victim / "ust-1234-abcdef03" / "precious.txt").write_text("not ours", encoding = "utf-8")
linked = tmp_path / "Linked Unsloth" / "temp"
linked.parent.mkdir()
try:
linked.symlink_to(victim, target_is_directory = True)
except (OSError, NotImplementedError):
pytest.skip("creating a symlink requires privilege on this host")
result = _run_powershell(
"\n".join(
[
preamble,
block,
f"_RemoveStudioPrivateTempTrees -Paths @('{linked}') -PrimaryPath '{linked}'",
'Write-Output "DONE:2"',
]
)
)
assert result.returncode == 0, result.stderr
assert _lines(result, "DONE:") == ["DONE:2"]
assert (
victim / "ust-1234-abcdef03" / "precious.txt"
).exists(), "the sweep walked through a link"
@requires_pwsh
def test_a_live_owner_survives_the_data_directory_removal(tmp_path: Path):
"""The sweep must run before the data directory is removed wholesale, and the removal must skip
what the sweep kept, since a live Unsloth from another root may use that temp."""
uninstall = (REPO_ROOT / "scripts" / "uninstall.ps1").read_text(encoding = "utf-8")
body = uninstall[uninstall.index("function Uninstall-UnslothStudio") :]
calls = [
line.strip()
for line in body.splitlines()
if (
"_RemoveDataDirKeepingWslIcon $defaultDataDir" in line
or "_RemoveStudioPrivateTempTrees -Paths" in line
)
]
assert calls, "neither call is in the script body"
for index, line in enumerate(calls):
if "_RemoveDataDirKeepingWslIcon" not in line:
continue
assert "-Preserve" in line, f"data dir removed without the preserved list: {line}"
assert (
index > 0 and "_RemoveStudioPrivateTempTrees" in calls[index - 1]
), f"the data dir is removed before the temp sweep runs: {line}"
blocks = "\n".join(
_extract(rf" function {name} \{{.*?\n \}}\n", uninstall)
for name in (
"_RemoveStudioPrivateTempTrees",
"_RemoveTreeKeeping",
"_RemoveDataDirKeepingWslIcon",
)
)
data = tmp_path / "Unsloth Studio"
temp = data / "temp"
temp.mkdir(parents = True)
live = temp / "ust-4321-abcdef05"
live.mkdir()
(live / "owner.pid").write_text(str(os.getpid()), encoding = "utf-8")
(live / "scratch.bin").write_text("in use", encoding = "utf-8")
dead = temp / "ust-4321-abcdef06"
dead.mkdir()
(dead / "owner.pid").write_text(str(_DEAD_PID), encoding = "utf-8")
other = data / "launcher.db"
other.write_text("data", encoding = "utf-8")
result = _run_powershell(
"\n".join(
[
'$ErrorActionPreference = "Stop"',
"function _Substep { param([string]$Msg, [string]$Color) }",
"function _RemovePath { param([string]$Path)"
" Remove-Item -LiteralPath $Path -Recurse -Force -ErrorAction SilentlyContinue }",
blocks,
f"$kept = @(_RemoveStudioPrivateTempTrees -Paths @('{temp}') -PrimaryPath '{temp}')",
'Write-Output ("KEPT:" + @($kept).Count)',
f"_RemoveDataDirKeepingWslIcon -DataDir '{data}' -ShortcutDirs @() -Preserve $kept",
'Write-Output "DONE:1"',
]
)
)
assert result.returncode == 0, result.stderr
assert _lines(result, "DONE:") == ["DONE:1"]
assert _lines(result, "KEPT:") == ["KEPT:1"]
assert (live / "scratch.bin").exists(), "a live Unsloth's %TEMP% went with the data dir"
assert not dead.exists()
assert not other.exists(), "the rest of the data dir was left behind"
@requires_pwsh
def test_a_link_high_above_another_profile_is_still_a_link(tmp_path: Path):
r"""A junction does not have to sit next to the temp directory to redirect it.
LocalAppData itself, the profile, or the drive root can be the reparse
point, and then "<root>\Unsloth Studio\temp" and its parent both look like
perfectly ordinary directories while the enumeration lands somewhere else
entirely. For a spelling that is not the profile being uninstalled, that
somewhere else can be another user, so every ancestor has to be ordinary.
The profile this uninstall IS for is deliberately not held to that: a
redirected LocalAppData there is the same user's own storage, and refusing
would leave the installer's own temp tree behind on every host that uses
folder redirection.
"""
if os.path.realpath(tmp_path) != str(tmp_path):
pytest.skip("the temp root itself is a link, which is what this test plants")
block, preamble, uninstall = _shared_setup_2()
real = tmp_path / "real profile"
real_temp = real / "localappdata" / "Unsloth Studio" / "temp"
real_temp.mkdir(parents = True)
stale = real_temp / "ust-1234-abcdef04"
stale.mkdir()
(stale / "owner.pid").write_text(str(_DEAD_PID), encoding = "utf-8")
(stale / "precious.txt").write_text("another profile", encoding = "utf-8")
redirected = tmp_path / "redirected profile"
try:
redirected.symlink_to(real, target_is_directory = True)
except (OSError, NotImplementedError):
pytest.skip("creating a symlink requires privilege on this host")
aliased = redirected / "localappdata" / "Unsloth Studio" / "temp"
other = tmp_path / "mine" / "Unsloth Studio" / "temp"
other.mkdir(parents = True)
result = _run_powershell(
"\n".join(
[
preamble,
block,
f"_RemoveStudioPrivateTempTrees -Paths @('{aliased}') -PrimaryPath '{other}'",
'Write-Output "DONE:1"',
]
)
)
assert result.returncode == 0, result.stderr
assert _lines(result, "DONE:") == ["DONE:1"]
assert (stale / "precious.txt").exists(), "the sweep walked through a link high above the root"
result = _run_powershell(
"\n".join(
[
preamble,
block,
f"_RemoveStudioPrivateTempTrees -Paths @('{aliased}') -PrimaryPath '{aliased}'",
'Write-Output "DONE:2"',
]
)
)
assert result.returncode == 0, result.stderr
assert _lines(result, "DONE:") == ["DONE:2"]
assert not stale.exists(), "a redirected profile cannot clean its own temp tree"
@requires_pwsh
def test_a_pre_existing_fallback_parent_is_not_unwound(tmp_path: Path):
"""Only what the probe created may be taken back.
A pre-provisioned "Unsloth Studio\temp" with its own ACLs, or an empty
relocation junction, is configuration this installer did not create. Empty
and correctly named is not the same as ours.
"""
local_app_data = tmp_path / "localappdata"
provisioned = local_app_data / "Unsloth Studio" / "temp"
provisioned.mkdir(parents = True)
user_profile = tmp_path / "userprofile"
user_profile.mkdir()
env = os.environ.copy()
env["LOCALAPPDATA"] = str(local_app_data)
env["USERPROFILE"] = str(user_profile)
result = _run_powershell(
_script(
"""
function Test-StudioDirectoryUsable {
param([string]$Path, [switch]$CreateIfMissing)
New-Item -ItemType Directory -Path $Path -Force | Out-Null
return $false
}
Write-Output "PRIVATE:$(New-StudioPrivateTempDirectory)"
""",
sabotage = False,
names = (
"Write-StudioLine",
"Remove-StudioStalePrivateTempDirectories",
"Get-StudioPrivateTempRoots",
"New-StudioPrivateTempDirectory",
),
),
env = env,
)
assert result.returncode == 0, result.stderr
assert _lines(result, "PRIVATE:") == ["PRIVATE:"]
assert not list(provisioned.glob("ust-*"))
assert provisioned.is_dir(), "a pre-existing temp directory was unwound"
assert not (user_profile / ".unsloth" / ".cache").exists()
@requires_pwsh
def test_the_uninstall_sweep_needs_a_recorded_owner_outside_its_own_profile(tmp_path: Path):
"""The alternate LocalAppData may be another user's profile, so its sweep needs a recorded
owner.pid (a missing one reads as unknown, not abandoned); our own profile needs only the
shape."""
block, preamble, uninstall = _shared_setup_2()
mine = tmp_path / "mine" / "Unsloth Studio" / "temp"
theirs = tmp_path / "theirs" / "Unsloth Studio" / "temp"
for root in (mine, theirs):
root.mkdir(parents = True)
(root / "ust-1234-abcdef01").mkdir()
result = _run_powershell(
"\n".join(
[
preamble,
block,
f"_RemoveStudioPrivateTempTrees -Paths @('{mine}','{theirs}') -PrimaryPath '{mine}'",
'Write-Output "DONE:1"',
]
)
)
assert result.returncode == 0, result.stderr
assert _lines(result, "DONE:") == ["DONE:1"]
assert not (mine / "ust-1234-abcdef01").exists(), "our own profile should be reclaimed"
assert (
theirs / "ust-1234-abcdef01"
).is_dir(), "another profile was swept without a recorded owner"
@requires_pwsh
def test_the_uninstaller_reclaims_the_temp_tree_at_both_spellings(tmp_path: Path):
"""A set but unusable LOCALAPPDATA produces two roots, so the uninstaller must reach both; the
second gets no recursive sentinel-free delete, since it may name another user's profile."""
uninstall = (REPO_ROOT / "scripts" / "uninstall.ps1").read_text(encoding = "utf-8")
block = _extract(r" # The SECOND LocalAppData spelling.*?\n \}\n", uninstall)
dead = str(tmp_path / "gone" / "localappdata")
env = os.environ.copy()
env["LOCALAPPDATA"] = dead
result = _run_powershell(
"\n".join(
[
'$ErrorActionPreference = "Stop"',
block,
'$privateTempDirs | ForEach-Object { Write-Output "DIR:$_" }',
]
),
env = env,
)
assert result.returncode == 0, result.stderr
dirs = [line[len("DIR:") :] for line in _lines(result, "DIR:")]
assert len(dirs) == 2, dirs
assert any(d.startswith(dead) for d in dirs), dirs
assert all(d.rstrip("\\/").endswith("temp") for d in dirs), dirs
assert len(set(dirs)) == len(dirs)
@requires_pwsh
def test_the_private_temp_removal_only_takes_what_it_created(tmp_path: Path):
"""Deliberately narrow, as the root may belong to another user: only ust-<pid>-<hex> directories
are removed, matched by shape, and parents only when left empty."""
uninstall = (REPO_ROOT / "scripts" / "uninstall.ps1").read_text(encoding = "utf-8")
block = _extract(r" function _RemoveStudioPrivateTempTrees \{.*?\n \}\n", uninstall)
data = tmp_path / "Unsloth Studio"
temp = data / "temp"
temp.mkdir(parents = True)
(temp / "ust-1234-abcdef01").mkdir()
(temp / "ust-1234-abcdef01" / "scratch.bin").write_text("x", encoding = "utf-8")
(temp / "ust-legacy").mkdir()
(temp / "ust-notapid-abcdef01").mkdir()
(temp / "somebody-elses").mkdir()
(data / "studio.port").write_text("41343", encoding = "utf-8")
result = _run_powershell(
"\n".join(
[
'$ErrorActionPreference = "Stop"',
"function _Substep { param([string]$Msg, [string]$Color) }",
block,
f"_RemoveStudioPrivateTempTrees -Paths @('{temp}') -PrimaryPath '{temp}'",
'Write-Output "DONE:1"',
]
)
)
assert result.returncode == 0, result.stderr
assert _lines(result, "DONE:") == ["DONE:1"]
assert not (temp / "ust-1234-abcdef01").exists()
assert (temp / "ust-legacy").is_dir()
assert (temp / "ust-notapid-abcdef01").is_dir()
assert (temp / "somebody-elses").is_dir()
assert temp.is_dir()
assert (data / "studio.port").exists()
# Split-Path -LiteralPath with -Parent throws AmbiguousParameterSet at runtime on PS 5.1.
# Checked statically because CI has no Windows PowerShell 5.1.
_SPLIT_PATH_LITERAL_PARENT = re.compile(
r"Split-Path\b[^\r\n|;]*?-LiteralPath\b[^\r\n|;]*?-Parent\b"
r"|Split-Path\b[^\r\n|;]*?-Parent\b[^\r\n|;]*?-LiteralPath\b"
)
# scripts/uninstall.ps1 has its own occurrences, fixed separately.
@pytest.mark.parametrize("name", ("install.ps1", "studio/setup.ps1"))
def test_split_path_never_pairs_literalpath_with_parent(name: str) -> None:
text = (REPO_ROOT / name).read_text(encoding = "utf-8")
offenders = [
f"{name}:{number}: {line.strip()}"
for number, line in enumerate(text.splitlines(), start = 1)
if not line.strip().startswith("#") and _SPLIT_PATH_LITERAL_PARENT.search(line)
]
assert not offenders, (
"Split-Path -LiteralPath cannot be combined with -Parent: Windows PowerShell 5.1 "
"resolves no parameter set for the pair and the call throws at runtime. Drop "
"-Parent -- -LiteralPath alone already returns the parent, and unlike -Path it does "
"not treat [ ] in an install root as a wildcard.\n " + "\n ".join(offenders)
)
def test_the_lock_chain_defines_everything_it_reaches() -> None:
"""LOCK_CHAIN is hand-written, so a helper split out of a body must be listed or every case breaks."""
source = INSTALL_PS1.read_text(encoding = "utf-8")
extracted = _helpers(*LOCK_CHAIN)
installer_functions = set(re.findall(r"^ function ([\w-]+) \{", source, flags = re.M))
provided = set(re.findall(r"^ function ([\w-]+) \{", extracted, flags = re.M))
assert provided, "the helper extraction produced nothing"
assert len(installer_functions) > 50, (
f"only {len(installer_functions)} installer functions found, so the scan is not reading "
"install.ps1 and this test would pass on an empty set"
)
# Whole-line comments dropped: a helper named in prose is not a call.
code = "\n".join(line for line in extracted.splitlines() if not line.lstrip().startswith("#"))
called = set(re.findall(r"(?<![\w-])([A-Z][\w]*-[\w-]+)", code))
missing = sorted((called & installer_functions) - provided)
assert not missing, (
f"LOCK_CHAIN extracts functions that call {missing}, which nothing here defines. "
"Add them to LOCK_CHAIN, or the scripts in this file die on the first call."
)
@requires_pwsh
def test_an_elevated_run_declines_a_user_writable_interpreter(tmp_path: Path):
"""An elevated run launches the resolved interpreter with the administrator token, so a
user-writable interpreter must be declined: the answer goes inexact and the reason is
printed."""
studio_home = tmp_path / "studio"
studio_home.mkdir()
result = _run_powershell(
_script(
f"""
# The gate is Windows-only, and the point of this case is the gate. Named here so the row
# means the same thing on the Linux parity runner as on the Windows one.
$env:OS = "Windows_NT"
Write-Output "EXACT:$((Resolve-StudioFinalPathInfo -Path '{studio_home}').Exact)"
""",
elevated = True,
)
)
assert result.returncode == 0, result.stderr
assert _lines(result, "EXACT:") == ["EXACT:False"]
assert [
line for line in result.stdout.splitlines() if "Could not resolve a path exactly" in line
], result.stdout
_INTEGRITY_REPRO = r"""
param($Source, $FakePython, $TimeoutMs)
$ErrorActionPreference = 'Stop'
$t = $null; $e = $null
$ast = [System.Management.Automation.Language.Parser]::ParseFile($Source, [ref]$t, [ref]$e)
foreach ($name in @('Get-StudioSystem32Tool', 'Invoke-StudioSystem32ToolBounded',
'Test-StudioChildScriptDirectoryElevated', 'New-StudioChildScriptDirectory',
'Get-NvidiaNvmlLibraryPath', 'Get-NvidiaSystem32Dir', 'Read-NvidiaLibraryRawViaPython')) {
$fn = @($ast.FindAll({ param($n)
$n -is [System.Management.Automation.Language.FunctionDefinitionAst] -and $n.Name -eq $name }, $true))
if ($fn.Count) { Invoke-Expression $fn[0].Extent.Text }
}
if (-not (Get-Command Read-NvidiaLibraryRawViaPython -ErrorAction SilentlyContinue)) { throw "no Python rung in $Source" }
function Get-NvidiaProbePythonExe { return $FakePython }
Write-Output "ANSWER:$(Read-NvidiaLibraryRawViaPython -TimeoutMs ([int]$TimeoutMs))"
"""
@requires_pwsh
@pytest.mark.skipif(os.name == "nt", reason = "the fake System32 tools are POSIX shell scripts")
@pytest.mark.parametrize(
"source, hung",
[
("install.ps1", None),
("install.ps1", "icacls.exe"),
("install.ps1", "whoami.exe"),
("studio/setup.ps1", "icacls.exe"),
],
)
def test_a_hung_integrity_tool_cannot_stall_the_nvidia_probe(tmp_path: Path, source, hung):
"""whoami and icacls run before the bounded child, so a utility that never exits
(an antivirus hold, a wedged token lookup) must cost a deadline, not the install."""
system32 = tmp_path / "Windows" / "System32"
system32.mkdir(parents = True)
tools = {"icacls.exe": "exit 0", "whoami.exe": 'printf "S-1-16-8192"'}
if hung == "whoami.exe":
tools["icacls.exe"] = "exit 1"
if hung:
tools[hung] = "exec sleep 60"
for name, body in tools.items():
tool = system32 / name
tool.write_text(f"#!/bin/sh\n{body}\n")
tool.chmod(0o755)
python = tmp_path / "python"
python.write_text('#!/bin/sh\ncat >/dev/null\nprintf "nvml;12;8;8.9"\n')
python.chmod(0o755)
script = tmp_path / "repro.ps1"
script.write_text(_INTEGRITY_REPRO)
env = dict(
os.environ,
OS = "Windows_NT",
SystemRoot = str(tmp_path / "Windows"),
TEMP = str(tmp_path),
TMP = str(tmp_path),
TMPDIR = str(tmp_path),
)
def attempt():
started = time.monotonic()
result = run_pwsh(
[
"pwsh",
"-NoProfile",
"-File",
str(script),
str(REPO_ROOT / source),
str(python),
# Hung cases need a 1 s budget; the control gets 10 s so only a truly hung child fails.
"1000" if hung else "10000",
],
env = env,
capture_output = True,
text = True,
timeout = 30,
)
assert result.returncode == 0, result.stderr
assert time.monotonic() - started < 20, "a hung integrity utility outlived its deadline"
return result
result = attempt()
if hung is None:
# On Linux pwsh copies redirected stdout asynchronously, so the answer can rarely be missing;
# retry once (Windows does not race). A truly lost answer is empty every time.
for _ in range(2):
if _lines(result, "ANSWER:") != ["ANSWER:"]:
break
result = attempt()
assert _lines(result, "ANSWER:") == ["ANSWER:nvml;12;8;8.9"], result.stdout
def _fake_system32(tmp_path: Path, tools: dict[str, str]) -> dict[str, str]:
system32 = tmp_path / "Windows" / "System32"
system32.mkdir(parents = True, exist_ok = True)
for name, body in tools.items():
tool = system32 / name
tool.write_text(f"#!/bin/sh\n{body}\n")
tool.chmod(0o755)
return dict(
os.environ,
OS = "Windows_NT",
SystemRoot = str(tmp_path / "Windows"),
TEMP = str(tmp_path),
TMP = str(tmp_path),
TMPDIR = str(tmp_path),
)
@requires_pwsh
@pytest.mark.skipif(os.name == "nt", reason = "the fake System32 tools are POSIX shell scripts")
def test_an_elevated_run_without_a_private_directory_does_not_probe_from_a_shared_root(
tmp_path: Path,
):
"""The fallback writes its redirect files into %TEMP%, where a standard user can plant or swap them."""
env = _fake_system32(tmp_path, {"icacls.exe": "exit 1", "whoami.exe": 'printf "S-1-16-12288"'})
python = tmp_path / "python"
python.write_text('#!/bin/sh\ncat >/dev/null\nprintf "nvml;12;8;8.9"\n')
python.chmod(0o755)
script = tmp_path / "repro.ps1"
script.write_text(_INTEGRITY_REPRO)
result = run_pwsh(
["pwsh", "-NoProfile", "-File", str(script), str(REPO_ROOT / "install.ps1"), str(python)],
env = env,
capture_output = True,
text = True,
timeout = 60,
)
assert result.returncode == 0, result.stderr
assert _lines(result, "ANSWER:") == ["ANSWER:"], result.stdout
@requires_pwsh
@pytest.mark.skipif(os.name == "nt", reason = "the fake System32 tools are POSIX shell scripts")
@pytest.mark.parametrize("source", ["install.ps1", "studio/setup.ps1"])
def test_a_child_directory_swapped_for_a_link_before_labelling_is_refused(tmp_path: Path, source):
"""A standard user can replace the new directory with a link until the label lands."""
victim = tmp_path / "victim"
victim.mkdir()
swap = f'case "$2" in /setintegritylevel) rm -rf "$1"; ln -s "{victim}" "$1";; esac; exit 0'
env = _fake_system32(tmp_path, {"icacls.exe": swap, "whoami.exe": 'printf "S-1-16-12288"'})
script = tmp_path / "mkdir.ps1"
script.write_text(
_INTEGRITY_REPRO.split("function Get-NvidiaProbePythonExe")[0].replace(
"if (-not (Get-Command Read-NvidiaLibraryRawViaPython",
"if (-not (Get-Command New-StudioChildScriptDirectory",
)
+ 'Write-Output "DIR:$(New-StudioChildScriptDirectory)"\n'
)
result = run_pwsh(
["pwsh", "-NoProfile", "-File", str(script), str(REPO_ROOT / source), "unused"],
env = env,
capture_output = True,
text = True,
timeout = 60,
)
assert result.returncode == 0, result.stderr
assert _lines(result, "DIR:") == ["DIR:"], result.stdout
assert victim.is_dir()