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
Keep the regenerable caches inside the Studio root (#10597)
Daniel Han922e62297ed6
diff --git a/install.ps1 b/install.ps1index 17834d14437..07ea7613f3f 100644--- a/install.ps1+++ b/install.ps1@@ -3966,13 +3966,32 @@ exit 1(Get-CanonicalDir -Path (Join-Path $env:USERPROFILE ".unsloth\studio")))}- # Explicit staging root, shared default cache, or the custom Unsloth home's tree.+ # The master root storage_roots.unsloth_home() reads. llama.cpp, node and whisper.cpp sit+ # BESIDE studio\ under it, so deriving them from $StudioHome would put them one level below+ # where every runtime resolver looks.+ function Get-MasterRootOverride {+ if ([string]::IsNullOrWhiteSpace($env:UNSLOTH_HOME)) { return $null }+ $value = $env:UNSLOTH_HOME.Trim()+ if ($value -eq "~") {+ $value = $env:USERPROFILE+ } elseif ($value -like "~/*" -or $value -like "~\*") {+ $value = (Join-Path $env:USERPROFILE $value.Substring(1).TrimStart('/', '\'))+ }+ return (Get-CanonicalDir -Path $value)+ }++ # Explicit staging root, the master root, the shared default cache, or the custom Unsloth+ # home's tree.function Get-ManagedLlamaCppDir {param([AllowNull()][string]$StagingRoot = $null)if ($StagingRoot) {return (Join-Path $StagingRoot "llama.cpp")}+ $masterRoot = Get-MasterRootOverride+ if ($masterRoot) {+ return (Join-Path $masterRoot "llama.cpp")+ }if (-not (Test-StudioHomeIsCustom)) {return (Join-Path $env:USERPROFILE ".unsloth\llama.cpp")}@@ -3988,8 +4007,9 @@ exit 1$dir = Get-ManagedLlamaCppDir -StagingRoot $StagingRootif ((Get-LlamaCppInstallReadState -Path $dir) -ne "Denied") { return $null }Write-StudioLine ""- # A denied custom home cannot be claimed as an Unsloth-managed cache.- $homeIsCustom = Test-StudioHomeIsCustom+ # A denied custom home cannot be claimed as an Unsloth-managed cache. Computed rather+ # than read off $RuntimeRootIsCustom: this runs beside the line that defines it.+ $homeIsCustom = (Test-StudioHomeIsCustom) -or [bool](Get-MasterRootOverride)# Preserve user-supplied wording when either override names this tree, or# names a build inside it: moving or deleting this folder takes that build# with it, and the later --with-llama-cpp-dir check then aborts on a pathdiff --git a/scripts/build_whisper_cpp.sh b/scripts/build_whisper_cpp.shindex 19fe6d9605d..775e939b84e 100755--- a/scripts/build_whisper_cpp.sh+++ b/scripts/build_whisper_cpp.sh@@ -2,6 +2,7 @@# Build whisper.cpp's whisper-server for Unsloth's GGUF dictation engine.# Installs into the managed Unsloth home so the backend's binary discovery# (core/inference/stt_ggml_sidecar.py::find_whisper_server_binary) picks it up:+# <UNSLOTH_HOME>/whisper.cpp/build/bin/whisper-server (master root)# <UNSLOTH_STUDIO_HOME>/whisper.cpp/build/bin/whisper-server (custom home)# ~/.unsloth/whisper.cpp/build/bin/whisper-server (default)# Usage:@@ -16,7 +17,25 @@ set -euWHISPER_CPP_SOURCE="${WHISPER_CPP_SOURCE:-https://github.com/ggml-org/whisper.cpp}"WHISPER_CPP_TAG="${WHISPER_CPP_TAG:-v1.9.1}"-STUDIO_HOME="${UNSLOTH_STUDIO_HOME:-${STUDIO_HOME:-${UNSLOTH_HOME:-}}}"+# Stripped and tilde-expanded before it can outrank anything, as setup.sh and the Python+# resolvers do: ${VAR:-} only treats the EMPTY string as unset, so a whitespace-only value+# would win here and name a relative " /whisper.cpp" the backend never looks in.+_root_value() {+ _rv=$(printf '%s' "${1:-}" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')+ case "$_rv" in+ "~") _rv="$HOME" ;;+ "~/"*) _rv="$HOME/${_rv#'~/'}" ;;+ esac+ printf '%s' "$_rv"+}++# UNSLOTH_HOME first: whisper.cpp is a SIBLING of studio/ under the master root, and the CLI+# exports UNSLOTH_STUDIO_HOME=<root>/studio beside it, so taking that one would install a level+# below where stt_ggml_sidecar._managed_whisper_cpp_dir() looks.+_STUDIO_HOME_ALIAS="${STUDIO_HOME:-}" # read before the name below is reassigned+STUDIO_HOME="$(_root_value "${UNSLOTH_HOME:-}")"+[ -n "$STUDIO_HOME" ] || STUDIO_HOME="$(_root_value "${UNSLOTH_STUDIO_HOME:-}")"+[ -n "$STUDIO_HOME" ] || STUDIO_HOME="$(_root_value "$_STUDIO_HOME_ALIAS")"CUSTOM_STUDIO_HOME=falseif [ -n "$STUDIO_HOME" ]; thenCUSTOM_STUDIO_HOME=truediff --git a/scripts/uninstall.ps1 b/scripts/uninstall.ps1index fd9c0e41fec..a811cbed350 100644--- a/scripts/uninstall.ps1+++ b/scripts/uninstall.ps1@@ -124,6 +124,48 @@ Environment:}}+ # rmdir, as uninstall.sh uses for the same two paths: empty or not at all, never recursed+ # into. Not "list it, then _RemovePath": -ErrorAction SilentlyContinue makes an enumeration+ # failure look like an empty directory, so a master root whose ACL denies listing was deleted+ # recursively with the user's files in it, and a separate check and delete let a file+ # arriving in between be taken by the -Recurse. Directory.Delete($path, $false) is one call.+ function _RemoveDirIfEmpty {+ param([string]$Path)+ if ([string]::IsNullOrWhiteSpace($Path)) { return }+ try {+ if (-not (Test-Path -LiteralPath $Path -PathType Container)) { return }+ [System.IO.Directory]::Delete($Path, $false)+ _Substep "removed: $Path" "Green"+ } catch {+ # Non-empty, unreadable or held open. All three mean "not ours to take".+ _Substep "keeping non-empty directory: $Path" "Yellow"+ }+ }++ # The exact shape prebuilt_core.py leaves: a component lock name, ".stale.", and the pid it+ # moved aside. The leading dot alone also matched ".backup.install.lock.stale.copy", which in+ # a user-chosen master root is theirs. uninstall.sh applies the same shape.+ $script:StaleLockPattern = '^\.(llama\.cpp|node|whisper\.cpp|sd\.cpp)\.install\.lock\.stale\.[0-9]+$'++ # An install lock, and only an install lock. prebuilt_core.install_lock creates these with+ # O_CREAT | O_EXCL, so a lock is always a regular file, while _RemovePath deletes recursively+ # and in a user-chosen master root would take a whole tree carrying one of these fixed names+ # with none of the owner-marker proof its neighbours require. Same rule as uninstall.sh.+ function _RemoveLockFile {+ param([string]$Path)+ if ([string]::IsNullOrWhiteSpace($Path)) { return }+ if (-not (Test-Path -LiteralPath $Path)) { return }+ # A reparse point at a lock name is not a lock either, and following one would delete+ # whatever it points at.+ $item = Get-Item -LiteralPath $Path -Force -ErrorAction SilentlyContinue+ if ($null -ne $item -and -not $item.PSIsContainer -and+ -not ($item.Attributes -band [IO.FileAttributes]::ReparsePoint)) {+ _RemovePath $Path+ } else {+ _Substep "keeping non-file at an install-lock path: $Path" "Yellow"+ }+ }+# LOCALAPPDATA / APPDATA are dropped in service and CI contexts, so fall back to the known# folder; $null only if that fails too, which callers treat as incomplete cleanup.function _AppDataRoot {@@ -567,6 +609,122 @@ Environment:# Discover non-default Unsloth roots from env vars + studio.conf files. Mirrors install.ps1's# precedence: UNSLOTH_STUDIO_HOME wins and STUDIO_HOME is ignored when both are set, or# uninstalling install A would also delete install B from a stale STUDIO_HOME.+ # The master root UNSLOTH_HOME names, or $null. studio\ is its child and llama.cpp, node and+ # whisper.cpp are its other children, so removing the Studio root alone strands them. Trimmed+ # and tilde-expanded like storage_roots.unsloth_home() and studio\setup.ps1.+ function _MasterRoot {+ $noteStudio = $null+ $raw = $env:UNSLOTH_HOME+ if ([string]::IsNullOrWhiteSpace($raw)) {+ # The note setup.ps1 leaves in the Studio tree, when this run has no UNSLOTH_HOME of+ # its own: a one-command `$env:UNSLOTH_HOME = 'D:\portable'` leaves nothing in a+ # later environment, so without it an uninstall stranded the runtimes. The deny list+ # and the marker gates still apply, so a stale note licenses nothing.+ #+ # Only the Studio root this run is about, in studio_root()'s precedence and with no+ # falling through: with two installs on one box, a legacy note otherwise won here+ # while the removal worked on the named tree, so the run deleted one Studio and the+ # OTHER install's runtime children. Mirrors _master_root in uninstall.sh.+ $noteRoots = @()+ foreach ($override in @($env:UNSLOTH_STUDIO_HOME, $env:STUDIO_HOME)) {+ if (-not [string]::IsNullOrWhiteSpace($override)) {+ $noteRoots = @(_ExpandTilde $override.Trim())+ break+ }+ }+ if (-not $noteRoots) {+ # No override names one, so the root install.ps1 recorded in the default-mode+ # studio.conf, then the legacy tree. A master-root install puts Studio at+ # <master>\studio, and that conf is how this script finds it with a bare+ # environment. Read directly rather than through _CustomStudioRoots, which calls+ # back into this function.+ if ($env:LOCALAPPDATA) {+ $confRoot = _RootFromConf (Join-Path $env:LOCALAPPDATA "Unsloth Studio\studio.conf")+ if ($confRoot) { $noteRoots += $confRoot }+ }+ if ($env:USERPROFILE) {+ $noteRoots += (Join-Path $env:USERPROFILE ".unsloth\studio")+ }+ }+ foreach ($noteRoot in $noteRoots) {+ $notePath = Join-Path $noteRoot "share\.unsloth-master-root"+ if (-not (Test-Path -LiteralPath $notePath -PathType Leaf)) { continue }+ try {+ # One line, and REFUSED when there is a second: storage_roots.py and the CLI+ # strip the WHOLE file, so a two-line note is not a directory to them and+ # they decline it, while accepting line 1 here let a note no runtime reader+ # honours authorise removing the master root's runtime children. Two lines+ # are read so the second can be seen; a trailing newline is not one.+ # -Encoding UTF8: 5.1 decodes BOM-less input with the ANSI code page, so a+ # master root holding non-ASCII came back mangled and its runtime siblings+ # were never found.+ $noteLines = @(Get-Content -LiteralPath $notePath -TotalCount 2 -Encoding UTF8 -ErrorAction Stop)+ } catch { continue }+ if ($noteLines.Count -gt 1 -and -not [string]::IsNullOrWhiteSpace($noteLines[1])) { continue }+ $line = if ($noteLines.Count -ge 1) { $noteLines[0] } else { $null }+ if (-not [string]::IsNullOrWhiteSpace($line)) {+ $raw = $line+ $noteStudio = $noteRoot+ break+ }+ }+ }+ if ([string]::IsNullOrWhiteSpace($raw)) { return $null }+ $expanded = _ExpandTilde $raw.Trim()+ $norm = $null+ # The provider path first, exactly as setup.ps1's Get-CanonicalDir resolves it.+ # [IO.Path]::GetFullPath anchors a RELATIVE root at [Environment]::CurrentDirectory,+ # which PowerShell does not keep in step with its own location, so after a Set-Location+ # a relative UNSLOTH_HOME named one install to setup and another here. Nothing downstream+ # notices: the marker spares trees that are not Unsloth's, not another Unsloth install.+ try {+ $norm = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($expanded)+ } catch { $norm = $null }+ try { $norm = [System.IO.Path]::GetFullPath($(if ($norm) { $norm } else { $expanded })).TrimEnd('\','/') }+ catch { return $null }+ if (-not $norm) { return $null }+ # A note must describe the tree it was found in: copy a Studio tree from master root A to+ # B and uninstall B, and the copied note still names A, whose runtimes carry the same+ # owner markers -- so the gates below would delete the ORIGINAL install's. Containment,+ # not an exact <root>\studio match, since the flat layout is supported. An explicit+ # UNSLOTH_HOME skips the check: that is the user speaking, not a file on disk. Mirrors+ # uninstall.sh and storage_roots._recorded_master_root().+ if ($noteStudio) {+ $here = $null+ try {+ $here = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($noteStudio)+ } catch { $here = $null }+ try { $here = [System.IO.Path]::GetFullPath($(if ($here) { $here } else { $noteStudio })).TrimEnd('\','/') }+ catch { $here = $null }+ if (-not $here) { return $null }+ # A note found in the ordinary %USERPROFILE%\.unsloth\studio install is declined+ # outright, whatever it records, which is the rule storage_roots'+ # _is_legacy_studio_tree and the CLI already apply. Containment alone is not enough:+ # the profile directory CONTAINS the legacy tree, so a note naming it passed,+ # _CustomStudioRoots then derived "<profile>\studio", and uninstalling the legacy+ # install accepted a SECOND marked install there as a root to remove. The deny list+ # below refuses the profile as a MASTER root, not the Studio candidate derived from+ # it. Mirrors uninstall.sh.+ if ($env:USERPROFILE) {+ $legacyStudio = $null+ try {+ $legacyStudio = [System.IO.Path]::GetFullPath(+ (Join-Path $env:USERPROFILE ".unsloth\studio")).TrimEnd('\','/')+ } catch { $legacyStudio = $null }+ if ($legacyStudio -and ($here -ieq $legacyStudio)) { return $null }+ }+ if (-not ($here -ieq $norm -or $here.StartsWith($norm + [System.IO.Path]::DirectorySeparatorChar,+ [System.StringComparison]::OrdinalIgnoreCase))) {+ return $null+ }+ }+ # The default root is left to the blocks that own it, which remove it unconditionally.+ if ($env:USERPROFILE -and ($norm -ieq (Join-Path $env:USERPROFILE ".unsloth").TrimEnd('\','/'))) {+ return $null+ }+ return $norm+ }+function _CustomStudioRoots {$seen = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::OrdinalIgnoreCase)$defaultRoot = $null@@ -586,10 +744,18 @@ Environment:}$envRoot = $null- if ($env:UNSLOTH_STUDIO_HOME) {- $envRoot = $env:UNSLOTH_STUDIO_HOME- } elseif ($env:STUDIO_HOME) {- $envRoot = $env:STUDIO_HOME+ # IsNullOrWhiteSpace, not truthiness: storage_roots.studio_root() trims these, so a+ # whitespace-only override is unset to every resolver, while a bare truthy test called it+ # present and suppressed the master-root branch below, leaving <UNSLOTH_HOME>\studio.+ if (-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_STUDIO_HOME)) {+ $envRoot = $env:UNSLOTH_STUDIO_HOME.Trim()+ } elseif (-not [string]::IsNullOrWhiteSpace($env:STUDIO_HOME)) {+ $envRoot = $env:STUDIO_HOME.Trim()+ } else {+ # Last, as in storage_roots.studio_root(): UNSLOTH_HOME names the tree, and the two+ # above name this exact directory, so either of them wins outright.+ $master = _MasterRoot+ if ($master) { $envRoot = (Join-Path $master "studio") }}if ($envRoot) {$expandedEnv = _ExpandTilde $envRoot@@ -918,7 +1084,23 @@ Environment:}# Also stop anything holding a handle on the exact paths we delete (llama-server,# the CLI shim, an mp-fork python with a venv DLL) so the dir delete isn't refused.- $stopRoots = @($ownedRoots) + @($defaultDataDir, $defaultLlamaCpp, $defaultCache, $defaultNode, $defaultWhisperCpp) + @($defaultSdCppToStop | Where-Object { $_ }) + @($customSdCppToStop)+ # Resolved here, before the stop pass: a loaded llama-server.exe under the master root keeps+ # its own tree locked, and the removal below would exhaust its retries and leave it installed.+ $masterRootToStop = _MasterRoot+ $masterChildrenToStop = @()+ if ($masterRootToStop -and -not (_IsUnsafeRoot $masterRootToStop)) {+ foreach ($childName in @("llama.cpp", "node", "whisper.cpp", "stable-diffusion.cpp")) {+ $childPath = Join-Path $masterRootToStop $childName+ # Only the trees this uninstall is going to delete, so an unmarked neighbour's+ # process is never killed.+ if (Test-Path -LiteralPath (Join-Path $childPath ".unsloth-studio-owned") -PathType Leaf) {+ $masterChildrenToStop += $childPath+ }+ }+ }+ # $ownedRoots, not $knownRoots: see the note where the two lists are built. The master+ # children are already marker-gated above, so they carry their own proof of ownership.+ $stopRoots = @($ownedRoots) + @($defaultDataDir, $defaultLlamaCpp, $defaultCache, $defaultNode, $defaultWhisperCpp) + @($defaultSdCppToStop | Where-Object { $_ }) + @($customSdCppToStop) + @($masterChildrenToStop)# The reparse expansion turns one path into generic subdirectories of wherever it points# (node, bin, unsloth_studio), so it is gated for the same reason._StopProcessesLockingRoots -Roots ($stopRoots + @(_ManagedPathsUnderReparseTargets $ownedRoots))@@ -937,6 +1119,18 @@ Environment:_Substep "refusing to remove non-Unsloth path: $r" "Yellow"continue}+ # The flat layout, both variables naming one directory: _RemoveRootRecordingDb takes a+ # marked Studio root WHOLE, so without this the user-chosen master root went with the+ # install, which is the hole in the rule every other child below is marker-gated for.+ # Kept rather than pruned, since data left behind is recoverable. Mirrors uninstall.sh.+ $flatMaster = $masterRootToStop+ if ($flatMaster -and ($r.TrimEnd('\', '/') -ieq $flatMaster.TrimEnd('\', '/'))) {+ _Substep "keeping $r`: UNSLOTH_HOME and the Studio root name the same directory," "Yellow"+ _Substep "so removing it would take whatever else you keep there. Delete it by hand" "Yellow"+ _Substep "once you have checked what is in it." "Yellow"+ $script:RemoveFailed = $true+ continue+ }_RemoveRootRecordingDb $r# Native diffusion now installs UNDER the custom root, so the removal above already took# it. Older builds put it BESIDE the root at <parent>\stable-diffusion.cpp, which removing@@ -971,6 +1165,45 @@ Environment:# Unsloth's %TEMP% before the sweep ever looked at its owner.pid.$preservedTemp = @(_RemoveStudioPrivateTempTrees -Paths $privateTempDirs -PrimaryPath $primaryPrivateTemp)if ($defaultDataDir) { _RemoveDataDirKeepingWslIcon $defaultDataDir -Preserve $preservedTemp }+ # The master root's own children, marker-gated rather than removed outright like the+ # ~/.unsloth ones below: <master> is a directory the user chose. The locks and .staging are+ # ours by name (prebuilt_core.py) and carry no marker. Mirrors scripts/uninstall.sh.+ # $masterRootToStop, not a fresh _MasterRoot: that resolver can read its answer from a note+ # inside a Studio tree the loop above has already removed, after which a second call returns+ # nothing and the runtime siblings are stranded.+ $masterRoot = $masterRootToStop+ if ($masterRoot -and (_IsUnsafeRoot $masterRoot)) {+ _Substep "refusing to remove unsafe path: $masterRoot" "Yellow"+ $masterRoot = $null+ }+ if ($masterRoot) {+ foreach ($childName in @("llama.cpp", "node", "whisper.cpp", "stable-diffusion.cpp")) {+ $childPath = Join-Path $masterRoot $childName+ if ((Test-Path -LiteralPath $childPath) -and+ -not (Test-Path -LiteralPath (Join-Path $childPath ".unsloth-studio-owned") -PathType Leaf)) {+ _Substep "keeping $childName without Unsloth owner marker: $childPath" "Yellow"+ } else {+ _RemovePath $childPath+ }+ }+ foreach ($lockName in @(".llama.cpp.install.lock", ".node.install.lock",+ ".whisper.cpp.install.lock", ".sd.cpp.install.lock")) {+ _RemoveLockFile (Join-Path $masterRoot $lockName)+ }+ # The prebuilt installers SHARE <root>\.staging and prune it only when empty, so+ # anything left in it here is not ours: remove the directory only, never its contents.+ _RemoveDirIfEmpty (Join-Path $masterRoot ".staging")+ if (Test-Path -LiteralPath $masterRoot) {+ # $script:StaleLockPattern, not a glob: the shape has to be the installer's own,+ # name and numeric pid both, or a user's file in their own root is taken.+ foreach ($stale in @(Get-ChildItem -LiteralPath $masterRoot -Force -ErrorAction SilentlyContinue |+ Where-Object { $_.Name -match $script:StaleLockPattern })) {+ _RemoveLockFile $stale.FullName+ }+ }+ # Only when nothing of the user's is left.+ _RemoveDirIfEmpty $masterRoot+ }# Shared llama.cpp build + cache, siblings of studio under ~/.unsloth in default mode.if ($defaultLlamaCpp) { _RemovePath $defaultLlamaCpp }# "stable-diffusion.cpp" is exactly what a git clone of leejet/stable-diffusion.cpp produces@@ -992,15 +1225,16 @@ Environment:# (prebuilt_core.py), and a stray lock keeps ~/.unsloth from being pruned below.if ($defaultUnslothHome) {foreach ($lockName in @(".llama.cpp.install.lock", ".node.install.lock", ".whisper.cpp.install.lock")) {- _RemovePath (Join-Path $defaultUnslothHome $lockName)+ _RemoveLockFile (Join-Path $defaultUnslothHome $lockName)}# Taking over an abandoned lock renames it to .stale.<pid> before unlinking; a crash# between the two strands the rename, so sweep any leftovers. -Force sees dotted names.if (Test-Path -LiteralPath $defaultUnslothHome) {- # -like, not -Filter: the Win32 filter is unreliable for names with several dots.+ # -match, not -Filter: the Win32 filter is unreliable for names with several dots,+ # and only the installer's exact shape is ours to remove.foreach ($stale in @(Get-ChildItem -LiteralPath $defaultUnslothHome -Force -ErrorAction SilentlyContinue |- Where-Object { $_.Name -like "*.install.lock.stale.*" })) {- _RemovePath $stale.FullName+ Where-Object { $_.Name -match $script:StaleLockPattern })) {+ _RemoveLockFile $stale.FullName}}}@@ -1105,6 +1339,27 @@ Environment:} catch {_Substep "could not update user PATH: $($_.Exception.Message)" "Yellow"}+ # Clear the persisted Inductor cache path when it still names a tree this run deleted:+ # setup.ps1 writes TORCHINDUCTOR_CACHE_DIR to the USER environment, so every later PyTorch+ # process on this account inherits it and compiles into the removed directory. Only a value+ # inside a root this run owned; a user's own directory and the shared C:\tc fallback stay.+ try {+ $persistedCache = [Environment]::GetEnvironmentVariable('TORCHINDUCTOR_CACHE_DIR', 'User')+ if (-not [string]::IsNullOrWhiteSpace($persistedCache)) {+ $expandedCache = [Environment]::ExpandEnvironmentVariables($persistedCache).TrimEnd('\', '/')+ foreach ($r in $ownedRoots) {+ if (-not $r) { continue }+ $rNorm = $r.TrimEnd('\', '/')+ if ($expandedCache -ieq $rNorm -or $expandedCache -ilike "$rNorm\*") {+ [Environment]::SetEnvironmentVariable('TORCHINDUCTOR_CACHE_DIR', [NullString]::Value, 'User')+ _Substep "cleared TORCHINDUCTOR_CACHE_DIR: $persistedCache" "Green"+ break+ }+ }+ }+ } catch {+ _Substep "could not clear TORCHINDUCTOR_CACHE_DIR: $($_.Exception.Message)" "Yellow"+ }# Remove HKCU\Software\Unsloth (PathBackup lives here; install.ps1 owns it).try {Remove-Item -LiteralPath 'HKCU:\Software\Unsloth' -Recurse -Force -ErrorAction SilentlyContinuediff --git a/scripts/uninstall.sh b/scripts/uninstall.shindex 93e5cb0fec0..bf391ee9ec6 100755--- a/scripts/uninstall.sh+++ b/scripts/uninstall.sh@@ -341,6 +341,22 @@ _remove_path() {fi}+# An install lock, and only an install lock. prebuilt_core.install_lock creates these with+# O_CREAT | O_EXCL, so a lock is always a regular file: a directory or a link at that name is+# the user's, and in a master root they chose _remove_path would rm -rf it. -L before -f, which+# is true for a link to a file. uninstall.ps1's _RemoveLockFile excludes reparse points for the+# same reason, and the two halves of one rule have to agree.+_remove_lock_file() {+ _rlf="$1"+ if [ -L "$_rlf" ]; then+ echo " keeping link at an install-lock path: $_rlf" >&2+ elif [ -f "$_rlf" ]; then+ _remove_path "$_rlf"+ elif [ -e "$_rlf" ]; then+ echo " keeping non-file at an install-lock path: $_rlf" >&2+ fi+}+# $1 override, $2 default. A relative override is invalid per XDG and dropped by dirs (which# Tauri resolves through), so honouring one would spare the real data and rm -rf under our cwd._xdg_dir() {@@ -462,6 +478,112 @@ _custom_studio_data_dirs() {# 3. Env-mode studio.conf at $<root>/share/studio.conf (discovered via 1)# install.sh writes UNSLOTH_EXE='<root>/unsloth_studio/bin/unsloth', so the install root is three# dirnames up. Each discovered non-default root is printed on its own line, de-duplicated.+# The master root UNSLOTH_HOME names, or empty. studio/ is its child and llama.cpp, node and+# whisper.cpp are its other children, so removing the Studio root alone strands them. Stripped+# and tilde-expanded like storage_roots.unsloth_home() and studio/setup.sh, or a padded value+# would name a directory neither install nor uninstall agrees on.+_master_root() {+ _mr_from_note=+ _mr=$(printf '%s' "${UNSLOTH_HOME:-}" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')+ # The note setup.sh leaves in the Studio tree, when this run has no UNSLOTH_HOME of its own:+ # `UNSLOTH_HOME=/mnt/portable unsloth studio update` leaves nothing in the environment, so+ # without it an uninstall stranded the runtimes. The deny list and the marker gate still+ # apply, so a stale note licenses nothing the environment could not.+ #+ # Only the Studio root this run is about, in studio_root()'s precedence and with no falling+ # through: with two installs on one box, a legacy note otherwise won here while the removal+ # worked on the named tree, so the run deleted one Studio and the OTHER install's runtimes.+ if [ -z "$_mr" ]; then+ # Trimmed as setup.sh trimmed them when it chose where to write the note: appending to+ # a padded UNSLOTH_STUDIO_HOME looked somewhere that does not exist, so the note was+ # never found while the loop below still removed the tree.+ _mr_ush=$(printf '%s' "${UNSLOTH_STUDIO_HOME:-}" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')+ _mr_sh=$(printf '%s' "${STUDIO_HOME:-}" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')+ if [ -n "$_mr_ush" ]; then+ _mr_roots="$_mr_ush"+ elif [ -n "$_mr_sh" ]; then+ _mr_roots="$_mr_sh"+ else+ # No override, so the root install.sh recorded in the default-mode studio.conf, then+ # the legacy tree: with a bare environment that conf is the only way to find a+ # <master>/studio at all. Read here, not through _custom_studio_roots, which calls+ # back into this function. UNSLOTH_EXE='<root>/unsloth_studio/bin/unsloth', so the+ # root is three dirnames up; apostrophes arrive escaped as '\''.+ _mr_roots=""+ _mr_dconf="$HOME/.local/share/unsloth/studio.conf"+ if [ -f "$_mr_dconf" ]; then+ _mr_exe=$(sed -n "s/^UNSLOTH_EXE='\(.*\)'\$/\1/p" "$_mr_dconf" | head -n1)+ _mr_exe=$(printf '%s' "$_mr_exe" | sed "s/'\\\\''/'/g")+ [ -n "$_mr_exe" ] && _mr_roots=$(dirname "$(dirname "$(dirname "$_mr_exe")")")+ fi+ _mr_roots="$_mr_roots+$HOME/.unsloth/studio"+ fi+ _mr_saved_ifs=$IFS+ IFS='+'+ for _mr_studio in $_mr_roots; do+ IFS=$_mr_saved_ifs+ [ -n "$_mr_studio" ] || continue+ _mr_conf="${_mr_studio}/share/.unsloth-master-root"+ [ -f "$_mr_conf" ] || continue+ # One line, and REFUSED when there is a second. storage_roots.py and the CLI both+ # strip the WHOLE file, so a two-line note is not a directory to them and they+ # decline it, while taking line 1 here authorised removing <master>/llama.cpp, node,+ # whisper.cpp and stable-diffusion.cpp: a note no runtime reader honours must not+ # license a delete. A trailing newline is not a second line.+ if [ -n "$(sed -n '2,$p' "$_mr_conf" 2>/dev/null | tr -d '[:space:]')" ]; then+ continue+ fi+ _mr=$(head -n 1 "$_mr_conf" 2>/dev/null | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//') \+ || _mr=""+ if [ -n "$_mr" ]; then+ _mr_from_note=1+ break+ fi+ done+ IFS=$_mr_saved_ifs+ fi+ [ -n "$_mr" ] || return 0+ # shellcheck disable=SC2088+ case "$_mr" in+ "~") _mr="$HOME" ;;+ "~/"*) _mr="$HOME/${_mr#'~/'}" ;;+ esac+ # shellcheck disable=SC1007+ # || _mr_canon="": a bare assignment takes the substitution's exit status under set -e, and+ # a root already gone or on a disconnected drive is the ordinary case here, which killed the+ # whole run. bash hides this by clearing errexit inside command substitution; dash and POSIX+ # `sh`, which the advertised `| sh` one-liner uses, do not.+ _mr_canon=$(CDPATH= cd -P -- "$_mr" 2>/dev/null && pwd -P) || _mr_canon=""+ [ -n "$_mr_canon" ] && _mr="$_mr_canon"+ # A note must describe the tree it was found in: copy a Studio tree from master root A to B+ # and uninstall B, and the copied note still names A, whose runtimes carry the same owner+ # markers -- so the gates below would delete the ORIGINAL install's. Containment, not an+ # exact <root>/studio match, since the flat layout is supported. An explicit UNSLOTH_HOME+ # skips all of this: that is the user speaking, not a file on disk.+ if [ "${_mr_from_note:-}" = 1 ]; then+ _mr_here=$(CDPATH= cd -P -- "$_mr_studio" 2>/dev/null && pwd -P) || _mr_here=""+ # A note found in the ordinary ~/.unsloth/studio install is declined outright, whatever+ # it records, which is the rule storage_roots._is_legacy_studio_tree and the CLI already+ # apply. Containment alone is not enough here: $HOME contains the legacy tree, so a note+ # naming it passed, _custom_studio_roots then emitted "$HOME/studio", and uninstalling+ # the legacy install accepted a SECOND marked install there as a root to remove, taking+ # its database and outputs with it. The deny list does not catch that -- it refuses+ # $HOME as a master root, not the separate Studio candidate derived from it.+ _mr_legacy_studio=$(CDPATH= cd -P -- "$HOME/.unsloth/studio" 2>/dev/null && pwd -P) \+ || _mr_legacy_studio="$HOME/.unsloth/studio"+ [ "$_mr_here" != "$_mr_legacy_studio" ] || return 0+ case "$_mr_here" in+ "$_mr") : ;;+ "$_mr"/*) : ;;+ *) return 0 ;;+ esac+ fi+ case "$_mr" in "$HOME/.unsloth"|/|"") return 0 ;; esac+ printf '%s\n' "$_mr"+}+_custom_studio_roots() {# $1 = "lexical": skip the canonicalization (see the legacy sd.cpp sibling below). Reset on# every call, so a plain call is never affected by a preceding lexical one.@@ -500,12 +622,22 @@ _custom_studio_roots() {}# Mirror install.sh's precedence: UNSLOTH_STUDIO_HOME wins, STUDIO_HOME is ignored when both# are set, or uninstalling install A could also delete install B from a leftover STUDIO_HOME.- if [ -n "${UNSLOTH_STUDIO_HOME:-}" ]; then- _emit "$UNSLOTH_STUDIO_HOME"- _from_conf "$UNSLOTH_STUDIO_HOME/share/studio.conf"- elif [ -n "${STUDIO_HOME:-}" ]; then- _emit "$STUDIO_HOME"- _from_conf "$STUDIO_HOME/share/studio.conf"+ # Trimmed, as storage_roots.studio_root() trims them: a whitespace-only override is unset to+ # every resolver, but a bare -n test called it present and suppressed the master-root branch+ # below, leaving <UNSLOTH_HOME>/studio installed.+ _ush=$(printf '%s' "${UNSLOTH_STUDIO_HOME:-}" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')+ _sh=$(printf '%s' "${STUDIO_HOME:-}" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')+ if [ -n "$_ush" ]; then+ _emit "$_ush"+ _from_conf "$_ush/share/studio.conf"+ elif [ -n "$_sh" ]; then+ _emit "$_sh"+ _from_conf "$_sh/share/studio.conf"+ elif [ -n "$(_master_root)" ]; then+ # Last, as in storage_roots.studio_root(): UNSLOTH_HOME names the tree, and the two+ # above name this exact directory, so either of them wins outright.+ _emit "$(_master_root)/studio"+ _from_conf "$(_master_root)/studio/share/studio.conf"fi# Default-mode conf._from_conf "$HOME/.local/share/unsloth/studio.conf"@@ -593,6 +725,9 @@ _unsloth_uninstall_main() {_pkill_studioecho "Removing data and install directories..."+ # Resolved ONCE, before anything is deleted: _master_root can read its answer from a note+ # inside a Studio tree the loop below removes, after which the runtime siblings are stranded.+ _MASTER_ROOT_SAVED="$(_master_root)"_custom_studio_roots | while IFS= read -r _custom_root; do[ -n "$_custom_root" ] || continueif _is_unsafe_root "$_custom_root"; then@@ -607,6 +742,23 @@ _unsloth_uninstall_main() {echo " refusing to remove non-Unsloth path: $_custom_root" >&2continuefi+ # The flat layout, both variables naming one directory: _remove_root_recording_db takes+ # a marked Studio root WHOLE, so without this the user-chosen master root went with the+ # install, which is the hole in the rule that every other child below is marker-gated+ # for. Kept rather than pruned, since data left behind is recoverable and printed.+ # Canonicalised on both sides, or a symlinked path compares unequal to itself.+ _crf_canon=$(CDPATH= cd -P -- "$_custom_root" 2>/dev/null && pwd -P) || _crf_canon=""+ [ -n "$_crf_canon" ] || _crf_canon="$_custom_root"+ _crf_master="$_MASTER_ROOT_SAVED"+ if [ -n "$_crf_master" ] && [ "$_crf_canon" = "$_crf_master" ]; then+ echo " keeping $_custom_root: UNSLOTH_HOME and the Studio root name the same" >&2+ echo " directory, so removing it would take whatever else you keep there." >&2+ echo " Delete it by hand once you have checked what is in it." >&2+ _set_marker "$_REMOVE_FAILED_FLAG"+ unset _crf_canon _crf_master+ continue+ fi+ unset _crf_canon _crf_master_remove_root_recording_db "$_custom_root"# Native diffusion now installs UNDER the custom root, so the removal above already took# it. Older builds put it BESIDE the root at <parent>/stable-diffusion.cpp, which removing@@ -645,6 +797,52 @@ _unsloth_uninstall_main() {_remove_path "$_lex_sd_cpp"fidone+ # The master root's own children, marker-gated and deny-listed rather than removed outright+ # like the ~/.unsloth ones below: <master> is a directory the user chose. The locks and+ # .staging are ours by name (prebuilt_core.py) and carry no marker.+ _mr_root="$_MASTER_ROOT_SAVED"+ if [ -n "$_mr_root" ]; then+ if _is_unsafe_root "$_mr_root"; then+ echo " refusing to remove unsafe path: $_mr_root" >&2+ else+ for _mr_child in llama.cpp node whisper.cpp stable-diffusion.cpp; do+ _mr_path="$_mr_root/$_mr_child"+ if _is_unsafe_root "$_mr_path"; then+ echo " refusing to remove unsafe path: $_mr_path" >&2+ # -L as well as -e: -e is false for a dangling symlink, so one named llama.cpp+ # with its target volume unmounted fell through to _remove_path, which treats+ # -L as present and unlinks it. In a root the user chose, that link is theirs.+ elif { [ -e "$_mr_path" ] || [ -L "$_mr_path" ]; } \+ && [ ! -f "$_mr_path/.unsloth-studio-owned" ]; then+ echo " keeping $_mr_child without Unsloth owner marker: $_mr_path" >&2+ else+ _remove_path "$_mr_path"+ fi+ done+ for _mr_lock in .llama.cpp.install.lock .node.install.lock \+ .whisper.cpp.install.lock .sd.cpp.install.lock; do+ _remove_lock_file "$_mr_root/$_mr_lock"+ done+ # The prebuilt installers SHARE <root>/.staging and prune it only when empty, so+ # anything left in it here is not ours. rmdir, not _remove_path: in a user-chosen+ # root a recursive delete would take files an install was content to leave.+ rmdir "$_mr_root/.staging" 2>/dev/null || true+ # The exact shape prebuilt_core.py leaves: a component lock name, ".stale.", and the+ # pid. A bare .*.install.lock.stale.* also matched .backup.install.lock.stale.copy.+ for _mr_lock in .llama.cpp.install.lock .node.install.lock \+ .whisper.cpp.install.lock .sd.cpp.install.lock; do+ for _mr_stale in "$_mr_root/$_mr_lock".stale.*; do+ case "${_mr_stale##*.stale.}" in+ ''|*[!0-9]*) continue ;;+ esac+ { [ -e "$_mr_stale" ] || [ -L "$_mr_stale" ]; } && _remove_lock_file "$_mr_stale"+ done+ done+ # Only when nothing of the user's is left; rmdir refuses a non-empty directory.+ rmdir "$_mr_root" 2>/dev/null || true+ fi+ fi+ # end master-root children# Same gate as a custom root: an ungated run takes a hand-made ~/.unsloth/studio, and then# ~/.unsloth via the empty-dir prune below.# -e OR -L: -e follows a link and misses a dangling one, which _remove_path would still@@ -685,14 +883,23 @@ _unsloth_uninstall_main() {_remove_path "$HOME/.unsloth/whisper.cpp"# Prebuilt install locks: every prebuilt serializes on <parent>/.<name>.install.lock# (prebuilt_core.py), and a stray lock keeps ~/.unsloth from being pruned below.- _remove_path "$HOME/.unsloth/.llama.cpp.install.lock"- _remove_path "$HOME/.unsloth/.node.install.lock"- _remove_path "$HOME/.unsloth/.whisper.cpp.install.lock"+ _remove_lock_file "$HOME/.unsloth/.llama.cpp.install.lock"+ _remove_lock_file "$HOME/.unsloth/.node.install.lock"+ _remove_lock_file "$HOME/.unsloth/.whisper.cpp.install.lock"# Taking over an abandoned lock renames it to .stale.<pid> before unlinking# (install_node_prebuilt.py); a crash between the two strands the rename, and a stranded one# blocks the rmdir below. Unmatched globs stay literal, hence the existence test.- for _stale in "$HOME"/.unsloth/.*.install.lock.stale.*; do- [ -e "$_stale" ] && _remove_path "$_stale"+ # Same shape restriction as the master-root sweep above: the help text promises that+ # anything else kept under ~/.unsloth is left in place, and .backup.install.lock.stale.copy+ # is dotted too.+ for _lock in .llama.cpp.install.lock .node.install.lock \+ .whisper.cpp.install.lock .sd.cpp.install.lock; do+ for _stale in "$HOME/.unsloth/$_lock".stale.*; do+ case "${_stale##*.stale.}" in+ ''|*[!0-9]*) continue ;;+ esac+ { [ -e "$_stale" ] || [ -L "$_stale" ]; } && _remove_lock_file "$_stale"+ donedone# ROCm-on-WSL helper artifacts (librocdxg clone, smoke-test venv); removing them frees the rmdir._remove_path "$HOME/.unsloth/librocdxg"diff --git a/studio/backend/core/inference/diffusion_compile_cache.py b/studio/backend/core/inference/diffusion_compile_cache.pyindex a5a416882fc..b10bcae615b 100644--- a/studio/backend/core/inference/diffusion_compile_cache.py+++ b/studio/backend/core/inference/diffusion_compile_cache.py@@ -57,6 +57,7 @@ import dataclassesimport hashlibimport jsonimport os+import shutilimport tempfileimport threadingimport time@@ -75,7 +76,7 @@ _ENV_DIR = "UNSLOTH_DIFFUSION_COMPILE_CACHE_DIR"_ENV_SAVE = "UNSLOTH_DIFFUSION_COMPILE_CACHE_SAVE"_ENV_SYNC = "UNSLOTH_DIFFUSION_COMPILE_CACHE_SYNC"-_DEFAULT_ROOT = Path.home() / ".cache" / "unsloth" / "diffusion_compile_cache"+_LEGACY_ROOT = Path.home() / ".cache" / "unsloth" / "diffusion_compile_cache"_MANIFEST_NAME = "manifest.json"# The pre-content-addressing bundle name. Still read (a manifest without a "bundle" key names it, which is every@@ -133,14 +134,61 @@ def _save_enabled(mode: str) -> bool:return (os.environ.get(_ENV_SAVE) or "").strip().lower() not in ("0", "off", "false", "no")+def _portable_mode() -> bool:+ try:+ from utils.paths.storage_roots import portable_mode+ except ImportError:+ return False+ try:+ return bool(portable_mode())+ except Exception: # noqa: BLE001 - never fail a cache lookup over this+ return False+++def _default_root() -> Path:+ """Resolved per call, not a module constant: this module is imported before startup sets+ UNSLOTH_STUDIO_HOME, which storage_roots reads."""+ try:+ from utils.paths.storage_roots import cache_root as studio_cache_root+ except ImportError:+ return _LEGACY_ROOT+ return studio_cache_root() / "diffusion_compile_cache"++def sync_saves() -> bool:"""Whether ``save_async`` must write inline instead of handing off to the worker."""return (os.environ.get(_ENV_SYNC) or "").strip().lower() in ("1", "on", "true", "yes")def cache_root() -> Path:+ """The root every bundle, manifest and inductor artifact is WRITTEN under."""root = os.environ.get(_ENV_DIR)- return Path(root) if root else _DEFAULT_ROOT+ if root:+ return Path(root)+ return _default_root()+++def legacy_cache_root() -> Optional[Path]:+ """The pre-relocation root, when it is still worth READING old bundles from.++ Read-only on purpose: returning it as the write root would pin an upgraded install to the home+ directory forever. Skipped under an explicit dir override (it names one exact directory) and+ in portable mode (the host's home is not part of the install).+ """+ if os.environ.get(_ENV_DIR) or _portable_mode():+ return None+ # Equal when storage_roots is unavailable and the default IS the legacy root.+ if _LEGACY_ROOT == _default_root():+ return None+ # This root is the HOST's home, not the install, so it is the one that may be on a mount the+ # new cache does not depend on. Path.exists raises for EACCES and EIO before 3.14, and an+ # optional migration source we cannot inspect is a miss, never a failed generation.+ try:+ if not _LEGACY_ROOT.exists():+ return None+ except OSError:+ return None+ return _LEGACY_ROOTdef _triton_version() -> Optional[str]:@@ -339,17 +387,70 @@ def begin(_collect_superseded(cdir, logger)# Try an exact-match load. A miss/mismatch is normal and non-fatal.- if published is not None and ctx.bundle.exists():+ # Guarded like _load_from_legacy's probe: Path.exists() raises rather than returning False when a parent denies+ # traversal, and this branch moves the write root to a directory the process may not own. Unguarded, that+ # exception left begin() before the legacy fallback below could run.+ try:+ pair_present = published is not None and ctx.bundle.exists()+ except OSError as exc:+ _warn(logger, f"compile-cache: cannot check the bundle at {ctx.dir}: {exc}")+ pair_present = False+ if pair_present:ctx.hit = _try_load(ctx, logger)- if ctx.hit and mode != "on":- # Loaded artifacts == on-disk artifacts, so nothing to save. A new static-compile shape re-dirties via- # register_shape; mode "on" keeps saving.- ctx.saved = True- else:+ if not ctx.hit:+ # An install that predates the relocation may still hold this key under the old root.+ ctx.hit = _load_from_legacy(ctx, logger)+ if not ctx.hit:_info(logger, f"compile-cache: no bundle for key {key} (will compile locally)")+ elif mode != "on":+ # Loaded artifacts == on-disk artifacts, so nothing to save. A new static-compile shape+ # re-dirties via register_shape; mode "on" keeps saving.+ ctx.saved = Truereturn ctx+def _load_from_legacy(ctx: CacheContext, logger: Any) -> bool:+ """Load the same key's bundle from the pre-relocation root, then migrate it.++ The key already covers every portability dimension, so a legacy bundle under it is the same+ artifact this run would have written. The copy stops the read fallback becoming permanent.+ Best-effort, and skipped when saving is off, since that mode promises a read-only cache."""+ root = legacy_cache_root()+ if root is None:+ return False+ ldir = root / ctx.key+ manifest_path = ldir / _MANIFEST_NAME+ # The manifest is the commit point here too, so it decides which legacy bundle is live; a+ # pre-content-addressing one names cache.bin.+ published = _read_manifest(manifest_path)+ if published is None:+ return False+ bundle = _manifest_bundle(ldir, published)+ try:+ if not bundle.exists():+ return False+ except OSError:+ # Same reason as legacy_cache_root: a pair we cannot even stat is a miss.+ return False+ if not _try_load(ctx, logger, bundle = bundle, manifest_path = manifest_path):+ return False+ if _save_enabled(ctx.mode):+ try:+ ctx.dir.mkdir(parents = True, exist_ok = True)+ # Under the name the copied manifest names, which is not ctx.bundle unless the legacy+ # pair predates content addressing. Published like begin() does, so the context goes+ # on naming the live bundle in the write root.+ migrated = _manifest_bundle(ctx.dir, published)+ _atomic_copy(bundle, migrated)+ # Bundle first: a manifest without one reads as a miss, not an unservable hit.+ _atomic_copy(manifest_path, ctx.manifest_path)+ ctx.bundle = migrated+ _info(logger, f"compile-cache: migrated legacy bundle for key {ctx.key}")+ except OSError as exc:+ _warn(logger, f"compile-cache: could not migrate legacy bundle: {exc}")+ return True++def register_shape(ctx: Optional[CacheContext], shape: Any, *, static: bool) -> None:"""Record a generation's (width, height, batch) against the bundle coverage.@@ -372,20 +473,37 @@ def register_shape(ctx: Optional[CacheContext], shape: Any, *, static: bool) ->pass-def _try_load(ctx: CacheContext, logger: Any) -> bool:+def _try_load(+ ctx: CacheContext,+ logger: Any,+ *,+ bundle: Optional[Path] = None,+ manifest_path: Optional[Path] = None,+) -> bool:+ """Validate and load a bundle pair, defaulting to the context's own (write-root) one."""+ bundle = bundle if bundle is not None else ctx.bundle+ manifest_path = manifest_path if manifest_path is not None else ctx.manifest_pathtry:- manifest = json.loads(ctx.manifest_path.read_text(encoding = "utf-8"))+ manifest = json.loads(manifest_path.read_text(encoding = "utf-8"))except Exception as exc: # noqa: BLE001_warn(logger, f"compile-cache: unreadable manifest: {exc}")return False+ # A manifest that decoded but is not an object. json.loads happily returns [] or null, and+ # the .get() below would then raise AttributeError out of a function whose whole contract is+ # that a bad cache entry is a miss. The legacy root makes this reachable: the bundle being+ # validated was written by an older build, on a disk this run has never checked.+ if not isinstance(manifest, dict):+ _warn(logger, "compile-cache: manifest is not an object; ignoring")+ return False+# Exact-match guard (defence in depth: torch also validates internally on load).if manifest.get("env") != ctx.env_fp or manifest.get("model") != ctx.model_fp:_warn(logger, "compile-cache: fingerprint mismatch; falling back to local compile")return Falsetry:- data = ctx.bundle.read_bytes()+ data = bundle.read_bytes()except Exception as exc: # noqa: BLE001_warn(logger, f"compile-cache: cannot read bundle: {exc}")return False@@ -443,6 +561,30 @@ def _atomic_write(path: Path, data: bytes) -> None:pass+def _atomic_copy(src: Path, dst: Path) -> None:+ """``shutil.copyfile`` into a temp file in *dst*'s directory, then ``os.replace``.++ Same rule and same reason as _atomic_write: a plain copyfile onto the live name is visible+ while it is still partial, and the migration below runs on the same interruptible path as a+ save. A torn manifest costs only a miss, but a miss here means the cold compile the migration+ exists to avoid, and two backends migrating one key would otherwise interleave their writes+ into a single destination file.+ """+ tmp: Optional[str] = None+ try:+ fd, tmp = tempfile.mkstemp(dir = str(dst.parent), prefix = f".{dst.name}.", suffix = _TEMP_SUFFIX)+ os.close(fd)+ shutil.copyfile(src, tmp)+ os.replace(tmp, dst)+ tmp = None+ finally:+ if tmp is not None:+ try:+ os.unlink(tmp)+ except OSError:+ pass++def _collect_superseded(cdir: Path, logger: Any) -> list[str]:"""Delete bundles no manifest names any more. Returns the names removed. Never raises.diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.pyindex e7f8a4ff295..5983cdc0a31 100644--- a/studio/backend/core/inference/llama_cpp.py+++ b/studio/backend/core/inference/llama_cpp.py@@ -8478,8 +8478,8 @@ class LlamaCppBackend:@staticmethoddef _resolved_studio_root_and_is_legacy() -> "tuple[Optional[Path], bool]":- """Resolve the Unsloth install root and classify it as the legacy- ~/.unsloth/studio root vs. a custom (env/venv-inferred) root.+ """Resolve the directory llama.cpp hangs off and classify it as the+ legacy ~/.unsloth/studio root vs. a custom (env/venv-inferred) root.Returns (resolved_root, is_legacy). On any import/resolution failure theroot is treated as legacy and resolved_root is None -- callers must read@@ -8488,8 +8488,16 @@ class LlamaCppBackend:(cleanup) so the two never disagree on which root is legacy."""try:- from utils.paths.storage_roots import studio_root as _sr # noqa: WPS433+ from utils.paths.storage_roots import ( # noqa: WPS433+ studio_root as _sr,+ unsloth_home as _uh,+ )+ # llama.cpp is a sibling of studio/ under the master root, the path run.py and+ # main.py export, so a portable install is never the legacy layout.+ master = _uh()+ if master is not None:+ return master, Falseresolved = _sr()legacy_studio = Path.home() / ".unsloth" / "studio"try:diff --git a/studio/backend/core/inference/stt_ggml_sidecar.py b/studio/backend/core/inference/stt_ggml_sidecar.pyindex 960f64115f5..7c3be289550 100644--- a/studio/backend/core/inference/stt_ggml_sidecar.py+++ b/studio/backend/core/inference/stt_ggml_sidecar.py@@ -120,15 +120,20 @@ def resolve_ggml_model_id(model: Optional[str]) -> str:def _managed_whisper_cpp_dir() -> Path:- """`<STUDIO_HOME>/whisper.cpp` in custom mode, else `~/.unsloth/whisper.cpp`.+ """`<UNSLOTH_HOME>/whisper.cpp` when set, else `<STUDIO_HOME>/whisper.cpp` in custom mode,+ else `~/.unsloth/whisper.cpp`.Mirrors `managed_node_dir` / `_find_llama_server_binary` so managed runtimesshare one parent directory."""legacy = Path.home() / ".unsloth" / "whisper.cpp"try:- from utils.paths.storage_roots import studio_root+ from utils.paths.storage_roots import studio_root, unsloth_home+ # setup.sh installs whisper.cpp at <master root>, beside studio/. No env var bridges it.+ master = unsloth_home()+ if master is not None:+ return master / "whisper.cpp"resolved = studio_root()legacy_studio = Path.home() / ".unsloth" / "studio"try:diff --git a/studio/backend/main.py b/studio/backend/main.pyindex ef471ebf307..794b66949a7 100644--- a/studio/backend/main.py+++ b/studio/backend/main.py@@ -230,10 +230,18 @@ try:_STUDIO_ROOT_RESOLVED = _studio_root().resolve()except (OSError, ValueError):_STUDIO_ROOT_RESOLVED = _studio_root()-if _STUDIO_ROOT_RESOLVED != _LEGACY_STUDIO_ROOT:+from utils.paths.storage_roots import unsloth_home as _unsloth_home++_MASTER_ROOT = _unsloth_home()+# A master root pointed at the legacy path still owns runtimes beside it, so the equality alone+# would skip the export and leave unsloth_zoo on ~/.unsloth/llama.cpp.+if _STUDIO_ROOT_RESOLVED != _LEGACY_STUDIO_ROOT or _MASTER_ROOT is not None:if not os.environ.get("UNSLOTH_STUDIO_HOME"):os.environ["UNSLOTH_STUDIO_HOME"] = str(_STUDIO_ROOT_RESOLVED)- _MANAGED_LLAMA_CPP_PATH = _STUDIO_ROOT_RESOLVED / "llama.cpp"+ # Same derivation as run.py: the runtimes sit at the master root, beside studio/, and marking+ # the wrong directory managed would make the bundled path look like an immutable override.+ _MANAGED_ROOT = _MASTER_ROOT or _STUDIO_ROOT_RESOLVED+ _MANAGED_LLAMA_CPP_PATH = _MANAGED_ROOT / "llama.cpp"if not os.environ.get("UNSLOTH_LLAMA_CPP_PATH"):os.environ["UNSLOTH_LLAMA_CPP_PATH"] = str(_MANAGED_LLAMA_CPP_PATH)# A CLI/desktop launcher may already have exported Unsloth's own install path.diff --git a/studio/backend/run.py b/studio/backend/run.pyindex 4526304b6a6..d3da78db36a 100644--- a/studio/backend/run.py+++ b/studio/backend/run.py@@ -1241,10 +1241,18 @@ try:_STUDIO_ROOT_RESOLVED = _studio_root().resolve()except (OSError, ValueError):_STUDIO_ROOT_RESOLVED = _studio_root()-if _STUDIO_ROOT_RESOLVED != _LEGACY_STUDIO_ROOT:+from utils.paths.storage_roots import unsloth_home as _unsloth_home++_MASTER_ROOT = _unsloth_home()+# A master root pointed at the legacy path still owns runtimes beside it, so the equality alone+# would skip the export and leave unsloth_zoo on ~/.unsloth/llama.cpp.+if _STUDIO_ROOT_RESOLVED != _LEGACY_STUDIO_ROOT or _MASTER_ROOT is not None:if not os.environ.get("UNSLOTH_STUDIO_HOME"):os.environ["UNSLOTH_STUDIO_HOME"] = str(_STUDIO_ROOT_RESOLVED)- _MANAGED_LLAMA_CPP_PATH = _STUDIO_ROOT_RESOLVED / "llama.cpp"+ # The runtimes sit at the master root, beside studio/; deriving from the Studio root would+ # pin a path one level too deep for every worker.+ _MANAGED_ROOT = _MASTER_ROOT or _STUDIO_ROOT_RESOLVED+ _MANAGED_LLAMA_CPP_PATH = _MANAGED_ROOT / "llama.cpp"if not os.environ.get("UNSLOTH_LLAMA_CPP_PATH"):os.environ["UNSLOTH_LLAMA_CPP_PATH"] = str(_MANAGED_LLAMA_CPP_PATH)# The CLI and generated launchers can export this path before run.py starts.diff --git a/studio/backend/tests/test_diffusion_compile_cache.py b/studio/backend/tests/test_diffusion_compile_cache.pyindex 6665490935d..988ed675c36 100644--- a/studio/backend/tests/test_diffusion_compile_cache.py+++ b/studio/backend/tests/test_diffusion_compile_cache.py@@ -14,6 +14,7 @@ from __future__ import annotationsimport hashlibimport jsonimport types+from pathlib import Pathimport pytest@@ -342,6 +343,227 @@ def test_restore_inductor_dir(monkeypatch, tmp_path, fake_megacache):assert os.environ["TORCHINDUCTOR_CACHE_DIR"] == "/tmp/prior-inductor" # restored+# -------------------------------------------------------------------------- legacy root+def _seed_legacy_bundle(monkeypatch, tmp_path, fake_megacache) -> tuple:+ """Write a bundle under a fake pre-relocation root, then hand back an upgraded install:+ ``(legacy_root, studio_home, legacy_bundle)``, with the environment already pointing at a+ non-portable install whose new default root is empty. The bundle is content-addressed, so its+ name comes from the seeding save rather than from a constant."""+ legacy = tmp_path / "legacy" / "diffusion_compile_cache"+ studio_home = tmp_path / "studio"+ monkeypatch.setenv(cc._ENV_MODE, "auto")+ monkeypatch.delenv(cc._ENV_SAVE, raising = False)+ monkeypatch.setenv(cc._ENV_DIR, str(legacy))+ seeded = cc.begin(transformer = _transformer(), **_BEGIN_KW)+ assert cc.save(seeded) is True++ monkeypatch.delenv(cc._ENV_DIR, raising = False)+ monkeypatch.delenv("UNSLOTH_HOME", raising = False)+ monkeypatch.delenv("UNSLOTH_PORTABLE", raising = False)+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(studio_home))+ monkeypatch.setattr(cc, "_LEGACY_ROOT", legacy)+ return legacy, studio_home, seeded.bundle+++def test_legacy_bundle_is_read_but_the_new_root_takes_the_writes(+ monkeypatch, tmp_path, fake_megacache+):+ # An upgraded install stays warm without the home directory becoming the write root:+ # begin() points TORCHINDUCTOR_CACHE_DIR at ctx.dir and save() writes every later bundle.+ legacy, studio_home, legacy_bundle = _seed_legacy_bundle(monkeypatch, tmp_path, fake_megacache)+ import os++ ctx = cc.begin(transformer = _transformer(), **_BEGIN_KW)++ assert ctx.hit is True # warm: the legacy bundle still counts+ assert str(ctx.dir).startswith(str(studio_home))+ assert str(os.environ["TORCHINDUCTOR_CACHE_DIR"]).startswith(str(studio_home))+ assert legacy not in ctx.dir.parents+ # The read fallback migrates: the pair now lives in the write root, byte-identical.+ assert ctx.bundle.read_bytes() == legacy_bundle.read_bytes()+ assert ctx.bundle.parent == ctx.dir+ assert ctx.manifest_path.exists()+++def test_an_interrupted_migration_leaves_no_partial_pair(monkeypatch, tmp_path, fake_megacache):+ """The migration copies through a temp file and renames, as every other write here does.++ A plain copyfile onto the live name is visible while it is still partial. The manifest is the+ commit point, so a torn one is read as a miss and costs the cold compile the migration exists+ to avoid; a second backend migrating the same key would interleave its writes into the same+ destination. Interruption is injected at the manifest copy, the later of the two.+ """+ legacy, studio_home, legacy_bundle = _seed_legacy_bundle(monkeypatch, tmp_path, fake_megacache)++ import shutil as _shutil++ real_copyfile = _shutil.copyfile+ calls = {"n": 0}++ def exploding_copyfile(src, dst, *args, **kwargs):+ calls["n"] += 1+ if calls["n"] == 2:+ # Half a manifest on disk, then death, exactly as interpreter exit kills the thread.+ Path(dst).write_bytes(Path(src).read_bytes()[:3])+ raise OSError("interrupted")+ return real_copyfile(src, dst, *args, **kwargs)++ monkeypatch.setattr(cc.shutil, "copyfile", exploding_copyfile)++ ctx = cc.begin(transformer = _transformer(), **_BEGIN_KW)++ # The read still served this run from the legacy pair.+ assert ctx.hit is True+ # Nothing partial is published under a name a later run reads: the temp file the copy died+ # inside is not the live manifest.+ if ctx.manifest_path.exists():+ assert ctx.manifest_path.read_bytes() == (legacy / ctx.key / cc._MANIFEST_NAME).read_bytes()+ leftovers = [q.name for q in ctx.dir.iterdir() if q.name.endswith(cc._TEMP_SUFFIX)]+ assert leftovers == [], leftovers+++def test_migrated_bundle_serves_the_next_run_without_the_legacy_root(+ monkeypatch, tmp_path, fake_megacache+):+ legacy, _, legacy_bundle = _seed_legacy_bundle(monkeypatch, tmp_path, fake_megacache)+ assert cc.begin(transformer = _transformer(), **_BEGIN_KW).hit is True++ import shutil++ shutil.rmtree(legacy) # the old cache gets cleaned up: the warm start must survive+ ctx = cc.begin(transformer = _transformer(), **_BEGIN_KW)+ assert ctx.hit is True+++def test_load_only_mode_reads_legacy_without_writing_to_it(monkeypatch, tmp_path, fake_megacache):+ legacy, _, legacy_bundle = _seed_legacy_bundle(monkeypatch, tmp_path, fake_megacache)+ monkeypatch.setenv(cc._ENV_SAVE, "0")++ ctx = cc.begin(transformer = _transformer(), **_BEGIN_KW)++ assert ctx.hit is True+ assert not (+ ctx.dir / legacy_bundle.name+ ).exists() # a read-only cache stays read-only, both roots+ assert legacy_bundle.exists()+++def test_key_absent_from_legacy_never_writes_into_it(monkeypatch, tmp_path, fake_megacache):+ # The old fallback swapped the WHOLE root, so even an unheld key wrote into the home dir.+ legacy, studio_home, legacy_bundle = _seed_legacy_bundle(monkeypatch, tmp_path, fake_megacache)+ before = {p.name for p in legacy.iterdir()}++ other = dict(_BEGIN_KW, family = "qwen-image")+ ctx = cc.begin(transformer = _transformer(("QwenImageTransformerBlock",)), **other)++ assert ctx.hit is False+ assert cc.save(ctx) is True+ assert str(ctx.bundle).startswith(str(studio_home))+ assert {p.name for p in legacy.iterdir()} == before+++def test_portable_mode_never_falls_back_to_the_home_directory(monkeypatch, tmp_path):+ # begin() points TORCHINDUCTOR_CACHE_DIR inside this root, so a fallback here would write+ # GBs into the host machine's home directory.+ monkeypatch.delenv(cc._ENV_DIR, raising = False)+ monkeypatch.delenv("UNSLOTH_STUDIO_HOME", raising = False)+ monkeypatch.setenv("UNSLOTH_HOME", str(tmp_path / "portable"))+ legacy = tmp_path / "legacy" / "diffusion_compile_cache"+ legacy.mkdir(parents = True)+ monkeypatch.setattr(cc, "_LEGACY_ROOT", legacy)++ root = cc.cache_root()++ assert root != legacy+ assert str(root).startswith(str(tmp_path / "portable"))+ assert cc.legacy_cache_root() is None # not even read: not part of the install+++def test_explicit_dir_override_ignores_the_legacy_root(monkeypatch, tmp_path):+ monkeypatch.setenv(cc._ENV_DIR, str(tmp_path / "chosen"))+ legacy = tmp_path / "legacy" / "diffusion_compile_cache"+ legacy.mkdir(parents = True)+ monkeypatch.setattr(cc, "_LEGACY_ROOT", legacy)++ assert cc.cache_root() == tmp_path / "chosen"+ assert cc.legacy_cache_root() is None+++def test_an_unreadable_legacy_root_is_a_miss_not_a_failure(monkeypatch, tmp_path):+ # The legacy root is the HOST's home, so it can be on a mount the new cache does not need.+ # Path.exists raises for EACCES and EIO before 3.14, and begin() does not catch around here.+ monkeypatch.delenv(cc._ENV_DIR, raising = False)+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "studio"))+ monkeypatch.delenv("UNSLOTH_HOME", raising = False)+ monkeypatch.delenv("UNSLOTH_PORTABLE", raising = False)+ legacy = tmp_path / "legacy" / "diffusion_compile_cache"+ monkeypatch.setattr(cc, "_LEGACY_ROOT", legacy)++ def _raise(self, *a, **k):+ raise PermissionError(13, "Permission denied")++ monkeypatch.setattr(Path, "exists", _raise)++ assert cc.legacy_cache_root() is None+++def test_an_unreadable_legacy_bundle_pair_is_a_miss_not_a_failure(monkeypatch, tmp_path):+ legacy = tmp_path / "legacy" / "diffusion_compile_cache"+ legacy.mkdir(parents = True)+ monkeypatch.setattr(cc, "legacy_cache_root", lambda: legacy)+ ctx = cc.CacheContext(+ key = "abc",+ dir = tmp_path / "new" / "abc",+ bundle = tmp_path / "new" / "abc" / "cache.bin",+ manifest_path = tmp_path / "new" / "abc" / "manifest.json",+ env_fp = "e",+ model_fp = "m",+ mode = "auto",+ )++ def _raise(self, *a, **k):+ raise OSError(5, "Input/output error")++ monkeypatch.setattr(Path, "exists", _raise)++ assert cc._load_from_legacy(ctx, None) is False+++def test_a_manifest_that_is_not_an_object_is_a_miss(monkeypatch, tmp_path, fake_megacache):+ """json.loads returns [] for "[]" and None for "null", and .get() on either raises.++ _try_load's whole contract is that a bad cache entry is a miss, and the legacy root makes+ this reachable in a way it was not before: the manifest being validated was written by an+ older build, on a disk this run has never checked.+ """+ legacy, _, legacy_bundle = _seed_legacy_bundle(monkeypatch, tmp_path, fake_megacache)+ for payload in ("[]", "null", '"a string"', "42"):+ for key_dir in legacy.iterdir():+ (key_dir / cc._MANIFEST_NAME).write_text(payload, encoding = "utf-8")+ ctx = cc.begin(transformer = _transformer(), **_BEGIN_KW)+ assert ctx.hit is False, payload+++def test_an_unreadable_write_root_falls_back_to_legacy(monkeypatch, tmp_path, fake_megacache):+ """Path.exists() raises rather than answering False when a parent denies traversal.++ This branch moves the write root, so it can land on a directory the process does not own on+ some machine. Unguarded, that exception left begin() before the legacy fallback could run,+ which is the fallback the relocation depends on for a warm start.+ """+ legacy, studio_home, legacy_bundle = _seed_legacy_bundle(monkeypatch, tmp_path, fake_megacache)+ real_exists = Path.exists++ def _raise_under_studio(self, *a, **k):+ if str(self).startswith(str(studio_home)):+ raise PermissionError(13, "Permission denied")+ return real_exists(self, *a, **k)++ monkeypatch.setattr(Path, "exists", _raise_under_studio)+ ctx = cc.begin(transformer = _transformer(), **_BEGIN_KW)+ assert ctx.hit is True++# ------------------------------------------------------------------ background save worker# save_async hands the write to a single module-level daemon worker so a generation stops paying for it. These drive# the worker directly, gating the fake save_cache_artifacts on Events so ordering is asserted, never slept on.diff --git a/studio/backend/tests/test_hf_cache_settings.py b/studio/backend/tests/test_hf_cache_settings.pyindex 506b552a4cf..2874e0f64ac 100644--- a/studio/backend/tests/test_hf_cache_settings.py+++ b/studio/backend/tests/test_hf_cache_settings.py@@ -3,7 +3,9 @@from __future__ import annotations+import jsonimport os+import subprocessimport sysimport threadingimport time@@ -315,3 +317,174 @@ def test_diffusion_loader_calls_pin_the_cache_dir():assert ("cache_dir" in window or "kwargs" in window), f"{rel}:{index} calls {call} without a pinned cache_dir"+++# _stored_cache_home skips the database read when nothing uses one, so `unsloth train` does not+# build a studio.db on a machine that never opened Studio. Only a positively observed absence may+# license that skip. Driven in a subprocess: the skip needs storage.studio_db out of sys.modules.+_GUARD_PROBE = """+import json, os, sys++sys.path.insert(0, os.environ["FAKE_STORAGE"])+sys.path.insert(1, os.environ["BACKEND_DIR"])+from utils import hf_cache_settings++assert "storage.studio_db" not in sys.modules, "the probe must exercise the skip"+stored = hf_cache_settings._stored_cache_home()+print(json.dumps({"stored": None if stored is None else str(stored)}))+"""++_FAKE_STUDIO_DB = """+import os+from pathlib import Path+++def get_app_setting(key, fallback = None):+ Path(os.environ["READ_WITNESS"]).write_text("read", encoding = "utf-8")+ if key == "hugging_face_cache_home":+ return os.environ["STORED_CACHE_HOME"]+ return fallback+"""+++def _run_guard_probe(+ tmp_path,+ studio_home: Path,+ stored: Path,+ *,+ probe: str | None = None,+ extra_env: dict[str, str] | None = None,+) -> tuple[str | None, bool]:+ """Return (_stored_cache_home() answer, whether the database was read)."""+ fake = tmp_path / "fake_storage"+ (fake / "storage").mkdir(parents = True, exist_ok = True)+ (fake / "storage" / "__init__.py").write_text("", encoding = "utf-8")+ (fake / "storage" / "studio_db.py").write_text(_FAKE_STUDIO_DB, encoding = "utf-8")+ witness = tmp_path / "read_witness"+ witness.unlink(missing_ok = True)++ environment = dict(os.environ)+ environment.update(+ BACKEND_DIR = _BACKEND_DIR,+ FAKE_STORAGE = str(fake),+ READ_WITNESS = str(witness),+ STORED_CACHE_HOME = str(stored),+ UNSLOTH_STUDIO_HOME = str(studio_home),+ PYTHONPATH = "",+ )+ environment.update(extra_env or {})+ for key in ("HF_HOME", "HF_HUB_CACHE", "HUGGINGFACE_HUB_CACHE", "HF_XET_CACHE"):+ environment.pop(key, None)+ result = subprocess.run(+ [sys.executable, "-c", probe if probe is not None else _GUARD_PROBE],+ capture_output = True,+ text = True,+ env = environment,+ timeout = 120,+ )+ assert result.returncode == 0, result.stderr+ return json.loads(result.stdout.strip().splitlines()[-1])["stored"], witness.exists()+++def test_absent_studio_db_skips_the_database_read(tmp_path):+ # The skip 912024e84 added must survive the tightening below: no studio.db answers None+ # WITHOUT a connection, which is what stops the CLI creating a 250 KB database.+ studio_home = tmp_path / "root" / "studio"+ studio_home.mkdir(parents = True)++ answer, was_read = _run_guard_probe(tmp_path, studio_home, tmp_path / "chosen")++ assert answer is None+ assert not was_read, "an absent database must not be opened"++[email protected]("fixture", ["not_a_directory", "symlink_loop", "unreadable_parent"])+def test_uninspectable_studio_db_keeps_the_stored_cache_home(tmp_path, fixture):+ # Path.exists reports ENOTDIR and ELOOP as absence on every release, and swallows EACCES+ # from 3.14. Reading any as "no database" discards the cache home chosen in Settings.+ chosen = tmp_path / "chosen"+ studio_home = tmp_path / "root" / "studio"+ if fixture == "not_a_directory":+ studio_home.parent.mkdir(parents = True)+ studio_home.write_text("", encoding = "utf-8")+ elif fixture == "symlink_loop":+ studio_home.parent.mkdir(parents = True)+ studio_home.symlink_to(studio_home)+ else:+ studio_home.mkdir(parents = True)+ (studio_home / "studio.db").write_bytes(b"")+ os.chmod(studio_home, 0o000)++ try:+ answer, was_read = _run_guard_probe(tmp_path, studio_home, chosen)+ finally:+ if fixture == "unreadable_parent":+ os.chmod(studio_home, 0o755)++ # unreadable_parent is the case 3.14 newly breaks; the other two hold on every release.+ assert was_read, "a database we could not inspect must still be read"+ assert answer == str(chosen)+++_WINDOWS_SHAPED_GUARD_PROBE = """+import errno, json, os, sys++# Windows reports a path whose PARENT is a file as ERROR_PATH_NOT_FOUND, which Python raises as+# FileNotFoundError; POSIX raises NotADirectoryError. Reproduce the error shape, since the Linux+# runners cannot produce it, and do it before hf_cache_settings is imported.+_NOT_A_DIR = os.environ["NOT_A_DIRECTORY"]+_real_stat = os.stat+++def _stat(path, *args, **kwargs):+ text = os.fspath(path)+ if text != _NOT_A_DIR and text.startswith(_NOT_A_DIR + os.sep):+ raise FileNotFoundError(errno.ENOENT, "The system cannot find the path specified", text)+ return _real_stat(path, *args, **kwargs)+++os.stat = _stat+sys.path.insert(0, os.environ["FAKE_STORAGE"])+sys.path.insert(1, os.environ["BACKEND_DIR"])+from utils import hf_cache_settings++assert "storage.studio_db" not in sys.modules, "the probe must exercise the skip"+stored = hf_cache_settings._stored_cache_home()+print(json.dumps({"stored": None if stored is None else str(stored)}))+"""+++def test_a_studio_home_that_is_a_file_still_reads_the_database_on_windows(tmp_path):+ """The POSIX arm of this is test_uninspectable_studio_db_keeps_the_stored_cache_home+ [not_a_directory], which passes there because ENOTDIR is its own exception type. Windows+ reports the same situation as FileNotFoundError, so the skip read it as "no database stored"+ and discarded the cache home chosen in Settings -- on Windows and nowhere else. Caught by the+ cross-platform leg, held here by reproducing the error shape rather than the platform.+ """+ studio_home = tmp_path / "root" / "studio"+ studio_home.parent.mkdir(parents = True)+ studio_home.write_text("", encoding = "utf-8")+ chosen = tmp_path / "chosen"++ answer, was_read = _run_guard_probe(+ tmp_path,+ studio_home,+ chosen,+ probe = _WINDOWS_SHAPED_GUARD_PROBE,+ extra_env = {"NOT_A_DIRECTORY": str(studio_home)},+ )++ assert was_read, "a studio home we could not inspect was read as no database"+ assert answer == str(chosen)+++def test_a_studio_home_that_does_not_exist_still_skips_the_database_read(tmp_path):+ """The other half. The fix above must not widen the skip into the case it exists for: a+ machine that has never opened Studio has no studio/ directory at all, and falling through+ there builds the 250 KB database this guard was added to avoid."""+ studio_home = tmp_path / "never-created" / "studio"++ answer, was_read = _run_guard_probe(tmp_path, studio_home, tmp_path / "chosen")++ assert answer is None+ assert not was_read, "an absent studio home must not open a database"diff --git a/studio/backend/tests/test_setup_cache_env_containment.py b/studio/backend/tests/test_setup_cache_env_containment.pynew file mode 100644index 00000000000..3d0894d65cf--- /dev/null+++ b/studio/backend/tests/test_setup_cache_env_containment.py@@ -0,0 +1,1446 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Everything Unsloth writes should sit under one directory (issue #8865)."""++import contextlib+import errno+import importlib.util+import json+import os+import platform+import re+import shutil+import subprocess+import sys+from pathlib import Path++import pytest++_BACKEND_DIR = str(Path(__file__).resolve().parent.parent)+if _BACKEND_DIR not in sys.path:+ sys.path.insert(0, _BACKEND_DIR)++_STORAGE_ROOTS_PATH = Path(__file__).resolve().parent.parent / "utils/paths/storage_roots.py"++_ALWAYS_PINNED = (+ "UV_CACHE_DIR",+ "VLLM_CACHE_ROOT",+ "UNSLOTH_COMPILE_LOCATION",+ "TORCHINDUCTOR_CACHE_DIR",+ "TRITON_CACHE_DIR",+ "TRITON_DUMP_DIR",+ "TORCH_EXTENSIONS_DIR",+ "CUDA_CACHE_PATH",+ "MPLCONFIGDIR",+ "NUMBA_CACHE_DIR",+ "DATA_DESIGNER_HOME",+ "DATA_DESIGNER_MANAGED_ASSETS_PATH",+)++# Shared user data / large re-downloads: portable mode only.+_PORTABLE_ONLY = ("HF_DATASETS_CACHE", "HF_ASSETS_CACHE", "TORCH_HOME")++_HF_ENV = ("HF_HOME", "HF_HUB_CACHE", "HF_XET_CACHE", "HUGGINGFACE_HUB_CACHE")++[email protected](autouse = True)+def _clean_env(monkeypatch, tmp_path):+ for key in _ALWAYS_PINNED + _PORTABLE_ONLY + _HF_ENV:+ monkeypatch.delenv(key, raising = False)+ for key in ("UNSLOTH_HOME", "UNSLOTH_PORTABLE", "STUDIO_HOME"):+ monkeypatch.delenv(key, raising = False)+ # Not pinned, but both change what Triton resolves under the test home.+ for key in ("TRITON_HOME", "TRITON_OVERRIDE_DIR"):+ monkeypatch.delenv(key, raising = False)+ # _default_cache_home reads this before ~/.cache, and CI runners set it.+ monkeypatch.delenv("XDG_CACHE_HOME", raising = False)+ # Same for matplotlib's config dir, whose contents decide whether MPLCONFIGDIR is ours.+ monkeypatch.delenv("XDG_CONFIG_HOME", raising = False)+ # Empty home: a real ~/.data-designer would change what the resolver pins.+ monkeypatch.setenv("HOME", str(tmp_path / "home"))+ monkeypatch.setenv("USERPROFILE", str(tmp_path / "home"))+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "studio"))++[email protected](autouse = True)+def _restore_hf_cache_settings_module():+ # Left popped, the next import builds a second module object for a later test to read.+ import utils++ name = "utils.hf_cache_settings"+ saved = sys.modules.get(name)+ saved_attr = getattr(utils, "hf_cache_settings", None)+ try:+ yield+ finally:+ if saved is not None:+ sys.modules[name] = saved+ else:+ sys.modules.pop(name, None)+ if saved_attr is not None:+ utils.hf_cache_settings = saved_attr+ else:+ with contextlib.suppress(AttributeError):+ del utils.hf_cache_settings+++def _load_storage_roots():+ # The resolver snapshots explicit env vars once per process.+ sys.modules.pop("utils.hf_cache_settings", None)+ spec = importlib.util.spec_from_file_location("storage_roots_under_test", _STORAGE_ROOTS_PATH)+ module = importlib.util.module_from_spec(spec)+ spec.loader.exec_module(module)+ return module+++def test_regenerable_caches_are_pinned_under_the_studio_root(tmp_path):+ sr = _load_storage_roots()++ sr._setup_cache_env()++ root = str(tmp_path / "studio")+ for key in _ALWAYS_PINNED:+ value = os.environ.get(key)+ assert value, f"{key} was not pinned"+ assert value.startswith(root), f"{key} escaped the studio root: {value}"+++# Pinned to a path a compiler is handed on a command line: cpp_builder.py joins with spaces,+# interpolates unquoted and reparses with shlex.split, so a root containing a space splits+# mid-path and the C++ build fails outright.+_TOOLCHAIN_PINNED = (+ "TORCHINDUCTOR_CACHE_DIR",+ "TORCH_EXTENSIONS_DIR",+ "TRITON_CACHE_DIR",+ "TRITON_DUMP_DIR",+ "CUDA_CACHE_PATH",+)+++def test_a_spaced_root_leaves_the_compiler_caches_to_their_own_defaults(monkeypatch, tmp_path):+ """ "C:\\Users\\First Last" is an ordinary Windows account name, so the DEFAULT Studio root+ contains a space for a large share of installs. Before this file pinned these, Inductor used+ its own whitespace-free temporary directory and the build worked; pinning it into a spaced+ root broke torch.compile outright. Unset is the behaviour that shipped, so that is the+ fallback: the rest of the caches, which nobody pastes into a command line, still move."""+ spaced = tmp_path / "my home" / "studio"+ spaced.mkdir(parents = True)+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(spaced))+ sr = _load_storage_roots()++ sr._setup_cache_env()++ for key in _TOOLCHAIN_PINNED:+ assert key not in os.environ, f"{key} was pinned to a path with a space"+ # Non-vacuity, and the point of the guard being narrow: everything else is still contained.+ for key in ("UV_CACHE_DIR", "NUMBA_CACHE_DIR", "MPLCONFIGDIR", "UNSLOTH_COMPILE_LOCATION"):+ assert os.environ[key].startswith(str(spaced.parent)), key+++def test_a_root_without_spaces_still_pins_the_compiler_caches(monkeypatch, tmp_path):+ """The other half of the guard: it must fire on whitespace and nothing else."""+ plain = tmp_path / "plain_home" / "studio"+ plain.mkdir(parents = True)+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(plain))+ sr = _load_storage_roots()++ sr._setup_cache_env()++ for key in _TOOLCHAIN_PINNED:+ assert os.environ.get(key, "").startswith(str(plain)), key+++def test_an_explicit_spaced_compiler_cache_is_left_alone(monkeypatch, tmp_path):+ """Only a default we invented is ours to withhold. A caller who set the variable chose it,+ and silently dropping it would send their cache somewhere they did not ask for."""+ chosen = tmp_path / "their choice"+ monkeypatch.setenv("TORCHINDUCTOR_CACHE_DIR", str(chosen))+ sr = _load_storage_roots()++ sr._setup_cache_env()++ assert os.environ["TORCHINDUCTOR_CACHE_DIR"] == str(chosen)+++def test_default_install_leaves_the_shared_hf_cache_alone(monkeypatch, tmp_path):+ home = tmp_path / "home"+ monkeypatch.setenv("HOME", str(home))+ sr = _load_storage_roots()++ sr._setup_cache_env()++ assert os.environ["HF_HUB_CACHE"] == str(home / ".cache" / "huggingface" / "hub")+ for key in _PORTABLE_ONLY:+ assert key not in os.environ+++def test_portable_mode_moves_the_hf_and_torch_caches_under_the_root(monkeypatch, tmp_path):+ monkeypatch.delenv("UNSLOTH_STUDIO_HOME", raising = False)+ master = tmp_path / "portable"+ monkeypatch.setenv("UNSLOTH_HOME", str(master))+ sr = _load_storage_roots()++ assert sr.portable_mode() is True+ assert sr.studio_root() == master / "studio"+ sr._setup_cache_env()++ root = str(master)+ for key in _ALWAYS_PINNED + _PORTABLE_ONLY + ("HF_HUB_CACHE", "HF_XET_CACHE"):+ value = os.environ.get(key)+ assert value, f"{key} was not pinned"+ assert value.startswith(root), f"{key} escaped the portable root: {value}"+++def test_portable_mode_still_leaves_hf_home_alone(monkeypatch, tmp_path):+ # HF_HOME owns the token path; credentials stay off a removable volume.+ home = tmp_path / "home"+ monkeypatch.setenv("HOME", str(home))+ monkeypatch.delenv("UNSLOTH_STUDIO_HOME", raising = False)+ monkeypatch.setenv("UNSLOTH_HOME", str(tmp_path / "portable"))+ sr = _load_storage_roots()++ sr._setup_cache_env()++ assert os.environ["HF_HOME"] == str(home / ".cache" / "huggingface")+++def test_unsloth_portable_alone_enables_portable_mode(monkeypatch, tmp_path):+ monkeypatch.setenv("UNSLOTH_PORTABLE", "1")+ sr = _load_storage_roots()++ assert sr.portable_mode() is True+ sr._setup_cache_env()++ assert os.environ["TORCH_HOME"].startswith(str(tmp_path / "studio"))+++ "value",+ ("0", "false", "False", "FALSE", "off", "OFF", "no", "No", " false ", ""),+)+def test_unsloth_portable_off_values_do_not_enable_portable_mode(monkeypatch, value):+ monkeypatch.setenv("UNSLOTH_PORTABLE", value)+ sr = _load_storage_roots()++ assert sr.portable_mode() is False+++# Every spelling the installers refuse: an intent the shell never acted on, and a typo.+_UNRECOGNIZED_PORTABLE = ("enabled", "flase", "2", "bogus", "y", "n", "disabled", "-1")++[email protected]("value", _UNRECOGNIZED_PORTABLE)+def test_unrecognized_unsloth_portable_does_not_enable_portable_mode(monkeypatch, tmp_path, value):+ # A rejected value must not turn portable mode on: the caches would move for this launch+ # and move back on the next one.+ monkeypatch.setenv("UNSLOTH_PORTABLE", value)+ sr = _load_storage_roots()++ assert sr.portable_mode() is False+ sr._setup_cache_env()++ for key in _PORTABLE_ONLY:+ assert key not in os.environ, f"{key} was redirected by UNSLOTH_PORTABLE={value!r}"++[email protected]("value", _UNRECOGNIZED_PORTABLE + ("0", "false", "off", "no"))+def test_a_portable_root_stays_portable_whatever_unsloth_portable_says(+ monkeypatch, tmp_path, value+):+ # The root is what makes an install portable; no UNSLOTH_PORTABLE value may veto it.+ monkeypatch.delenv("UNSLOTH_STUDIO_HOME", raising = False)+ master = tmp_path / "portable"+ monkeypatch.setenv("UNSLOTH_HOME", str(master))+ monkeypatch.setenv("UNSLOTH_PORTABLE", value)+ sr = _load_storage_roots()++ assert sr.portable_mode() is True+ assert sr.studio_root() == master / "studio"+ sr._setup_cache_env()++ for key in _PORTABLE_ONLY:+ assert os.environ[key].startswith(str(master)), f"{key} escaped the portable root"++[email protected]("value", _UNRECOGNIZED_PORTABLE)+def test_an_on_disk_portable_root_outranks_an_unrecognized_value(monkeypatch, value):+ # unsloth_home() also resolves from install.sh's root marker, which a venv-activated+ # launch has instead of an environment.+ monkeypatch.setenv("UNSLOTH_PORTABLE", value)+ sr = _load_storage_roots()+ monkeypatch.setattr(sr, "unsloth_home", lambda: Path("/opt/unsloth-portable"))++ assert sr.portable_mode() is True+++class _RecordingLogger:+ def __init__(self):+ self.warnings = []++ def warning(self, message, *args):+ self.warnings.append(message % args if args else message)+++def test_an_unrecognized_value_is_reported_once_not_once_per_call(monkeypatch):+ # portable_mode() runs on every cache-var lookup, so a per-call warning floods the log.+ monkeypatch.setenv("UNSLOTH_PORTABLE", "enabled")+ sr = _load_storage_roots()+ recorder = _RecordingLogger()+ monkeypatch.setattr(sr, "logger", recorder)++ for _ in range(200):+ assert sr.portable_mode() is False++ assert len(recorder.warnings) == 1+ warning = recorder.warnings[0]+ assert "enabled" in warning+ # Naming only the rejection leaves the user guessing at the spelling.+ for accepted in ("1", "true", "yes", "on", "0", "false", "off", "no"):+ assert accepted in warning++[email protected]("value", ("1", "true", "TRUE", " on ", "0", "false", "off", "no", ""))+def test_accepted_spellings_are_silent(monkeypatch, value):+ monkeypatch.setenv("UNSLOTH_PORTABLE", value)+ sr = _load_storage_roots()+ recorder = _RecordingLogger()+ monkeypatch.setattr(sr, "logger", recorder)++ sr.portable_mode()++ assert recorder.warnings == []+++def test_conflicting_roots_are_reported_once_per_conflict(monkeypatch, tmp_path):+ # studio_root() runs many times per request, so a per-call warning floods the log and+ # adds synchronous log I/O for the life of the backend.+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "elsewhere" / "studio"))+ monkeypatch.setenv("UNSLOTH_HOME", str(tmp_path / "portable"))+ sr = _load_storage_roots()+ recorder = _RecordingLogger()+ monkeypatch.setattr(sr, "logger", recorder)++ for _ in range(200):+ sr.studio_root()++ assert len(recorder.warnings) == 1+ assert str(tmp_path / "elsewhere" / "studio") in recorder.warnings[0]+ assert str(tmp_path / "portable") in recorder.warnings[0]++ # A different pair of roots is a different mistake and must still be heard.+ monkeypatch.setenv("UNSLOTH_HOME", str(tmp_path / "other-portable"))+ for _ in range(200):+ sr.studio_root()++ assert len(recorder.warnings) == 2+ assert str(tmp_path / "other-portable") in recorder.warnings[1]++[email protected]("layout", ("nested", "flat"))+def test_a_self_contained_layout_never_warns(monkeypatch, tmp_path, layout):+ # Both supported shapes; silencing the repeat must not silence the whole diagnostic.+ master = tmp_path / "portable"+ monkeypatch.setenv("UNSLOTH_HOME", str(master))+ monkeypatch.setenv(+ "UNSLOTH_STUDIO_HOME",+ str(master / "studio") if layout == "nested" else str(master),+ )+ sr = _load_storage_roots()+ recorder = _RecordingLogger()+ monkeypatch.setattr(sr, "logger", recorder)++ for _ in range(50):+ sr.studio_root()++ assert recorder.warnings == []+++def test_explicit_env_beats_the_pinned_default(monkeypatch, tmp_path):+ chosen = tmp_path / "elsewhere" / "inductor"+ monkeypatch.setenv("TORCHINDUCTOR_CACHE_DIR", str(chosen))+ sr = _load_storage_roots()++ sr._setup_cache_env()++ assert os.environ["TORCHINDUCTOR_CACHE_DIR"] == str(chosen)+++def test_blank_inherited_value_counts_as_unset(monkeypatch, tmp_path):+ # "" would send the library to the working directory or the system temp dir.+ monkeypatch.setenv("MPLCONFIGDIR", " ")+ sr = _load_storage_roots()++ sr._setup_cache_env()++ assert os.environ["MPLCONFIGDIR"] == str(tmp_path / "studio" / "cache" / "matplotlib")+++def test_studio_home_outranks_unsloth_home(monkeypatch, tmp_path):+ explicit = tmp_path / "explicit"+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(explicit))+ monkeypatch.setenv("UNSLOTH_HOME", str(tmp_path / "portable"))+ sr = _load_storage_roots()++ assert sr.studio_root() == explicit.resolve()+++def _use_data_designer(home: Path) -> None:+ """Write what a Studio Data Designer session leaves behind."""+ (home / "managed-assets").mkdir(parents = True, exist_ok = True)+ (home / "model_configs.yaml").write_text("models: []\n", encoding = "utf-8")+ (home / "managed-assets" / "seeds.parquet").write_bytes(b"PAR1")+++def test_a_used_managed_home_does_not_flip_when_the_legacy_dir_is_deleted(tmp_path):+ # Deleting and recreating ~/.data-designer used to toggle which home a run read.+ managed = tmp_path / "studio" / "data-designer"+ _use_data_designer(managed)+ legacy = tmp_path / "home" / ".data-designer"++ seen = []+ for exists in (False, True, False, True):+ if exists:+ legacy.mkdir(parents = True, exist_ok = True)+ elif legacy.exists():+ shutil.rmtree(legacy)+ for key in ("DATA_DESIGNER_HOME", "DATA_DESIGNER_MANAGED_ASSETS_PATH"):+ os.environ.pop(key, None)+ sr = _load_storage_roots()+ sr._setup_cache_env()+ seen.append(os.environ.get("DATA_DESIGNER_HOME"))++ assert seen == [str(managed)] * 4+++def _fail_stat_on(monkeypatch, target: Path, error: OSError) -> None:+ """Make every stat of *target* raise *error*, and leave every other path alone.++ chmod covers EACCES; a failing mount answering EIO has no on-disk equivalent an unprivileged+ user can set up. Both os.stat and os.lstat are patched so the predicates this replaced see+ the same failure the fix does.+ """++ def denying(real):+ def deny(path, *args, **kwargs):+ if isinstance(path, (str, os.PathLike)) and Path(path) == target:+ raise error+ return real(path, *args, **kwargs)++ return deny++ for name in ("stat", "lstat"):+ monkeypatch.setattr(os, name, denying(getattr(os, name)))+++def _assert_the_resolver_really_ran(tmp_path: Path) -> None:+ """A decline only means something beside a pin that still happened.++ "MPLCONFIGDIR is absent" is equally true when no pinning code exists at all, so on its own+ every decline case passed against a reverted implementation. Naming a sibling that is pinned+ unconditionally makes the whole family falsifiable without a control test per case.+ """+ assert os.environ["TORCHINDUCTOR_CACHE_DIR"].startswith(str(tmp_path / "studio"))+ assert os.environ["NUMBA_CACHE_DIR"].startswith(str(tmp_path / "studio"))+++def _mpl_managed(tmp_path: Path) -> Path:+ return tmp_path / "studio" / "cache" / "matplotlib"+++def _write_rc(directory: Path) -> None:+ directory.mkdir(parents = True, exist_ok = True)+ (directory / "matplotlibrc").write_text("figure.dpi: 222\n", encoding = "utf-8")+++def _write_style(stylelib: Path) -> None:+ stylelib.mkdir(parents = True, exist_ok = True)+ (stylelib / "house.mplstyle").write_text("axes.facecolor: black\n", encoding = "utf-8")+++def _denied(*paths: Path):+ """chmod 000 for the duration of the call under test, restored however it ends."""+ for path in paths:+ path.chmod(0o000)+ try:+ yield+ finally:+ for path in paths:+ path.chmod(0o755)+++_NEEDS_CHMOD = pytest.mark.skipif(+ os.name == "nt" or os.geteuid() == 0,+ reason = "chmod 000 denies neither root nor Windows",+)+_XDG_ONLY = pytest.mark.skipif(+ not sys.platform.startswith(("linux", "freebsd")),+ reason = "XDG config base is the Linux/FreeBSD branch",+)+++def _mpl_user_rc(tmp_path, monkeypatch):+ _write_rc(_matplotlib_config_dir(tmp_path / "home"))+++def _mpl_user_styles(tmp_path, monkeypatch):+ _write_style(_matplotlib_config_dir(tmp_path / "home") / "stylelib")+++def _mpl_empty_config(tmp_path, monkeypatch):+ _matplotlib_config_dir(tmp_path / "home").mkdir(parents = True)+++def _mpl_xdg_rc(tmp_path, monkeypatch):+ _write_rc(tmp_path / "xdg" / "matplotlib")+ monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg"))+++def _mpl_denied_config(tmp_path, monkeypatch):+ config = _matplotlib_config_dir(tmp_path / "home")+ _write_rc(config)+ return _denied(config.parent)+++def _mpl_denied_styles(tmp_path, monkeypatch):+ styles = _matplotlib_config_dir(tmp_path / "home") / "stylelib"+ _write_style(styles)++ @contextlib.contextmanager+ def guard():+ with _denied(styles):+ # Path.glob suppresses the scandir error, which is what read an unreadable stylelib+ # as empty; without this the case could pass while chmod did nothing.+ assert list(styles.glob("*.mplstyle")) == []+ yield++ return guard()+++def _mpl_failing_volume(tmp_path, monkeypatch):+ config = _matplotlib_config_dir(tmp_path / "home")+ _write_rc(config)+ _fail_stat_on(monkeypatch, config / "matplotlibrc", OSError(errno.EIO, "Input/output error"))+++def _mpl_managed_styles_and_user_rc(tmp_path, monkeypatch):+ _write_style(_mpl_managed(tmp_path) / "stylelib")+ _write_rc(_matplotlib_config_dir(tmp_path / "home"))+++def _mpl_empty_managed_and_user_rc(tmp_path, monkeypatch):+ (_mpl_managed(tmp_path) / "stylelib").mkdir(parents = True)+ _write_rc(_matplotlib_config_dir(tmp_path / "home"))+++def _mpl_linked_styles(tmp_path, monkeypatch):+ config = _matplotlib_config_dir(tmp_path / "home")+ config.mkdir(parents = True)+ elsewhere = tmp_path / "styles-volume"+ elsewhere.mkdir() # empty, which is the whole point+ (config / "stylelib").symlink_to(elsewhere, target_is_directory = True)+++def _mpl_dangling_styles(tmp_path, monkeypatch):+ config = _matplotlib_config_dir(tmp_path / "home")+ config.mkdir(parents = True)+ (config / "stylelib").symlink_to(tmp_path / "never-mounted", target_is_directory = True)+++def _mpl_plain_empty_styles(tmp_path, monkeypatch):+ (_matplotlib_config_dir(tmp_path / "home") / "stylelib").mkdir(parents = True)+++ "prepare, pinned",+ [+ # MPLCONFIGDIR moves the CONFIG directory as well as the cache, so a pin wins only when+ # there is nothing of the user's at matplotlib's own directory to hide. Each "must still+ # pin" row is the control for the row above it: matplotlib creates the config dir and+ # stylelib on import, so existence alone must never count as configuration.+ pytest.param(_mpl_user_rc, False, id = "a user matplotlibrc"),+ pytest.param(_mpl_user_styles, False, id = "a user style library"),+ pytest.param(_mpl_empty_config, True, id = "an empty config dir"),+ pytest.param(_mpl_xdg_rc, False, id = "an rc under XDG_CONFIG_HOME", marks = _XDG_ONLY),+ pytest.param(+ _mpl_denied_config, False, id = "a config dir we may not read", marks = _NEEDS_CHMOD+ ),+ pytest.param(+ _mpl_denied_styles, False, id = "a stylelib we may not read", marks = _NEEDS_CHMOD+ ),+ pytest.param(_mpl_failing_volume, False, id = "an rc on a failing volume"),+ pytest.param(_mpl_managed_styles_and_user_rc, True, id = "our own styles, already ours"),+ pytest.param(_mpl_empty_managed_and_user_rc, False, id = "an empty managed dir"),+ pytest.param(_mpl_linked_styles, False, id = "a stylelib linked to an empty volume"),+ pytest.param(_mpl_dangling_styles, False, id = "a dangling stylelib link"),+ pytest.param(_mpl_plain_empty_styles, True, id = "a plain empty stylelib"),+ ],+)+def test_mplconfigdir_is_pinned_only_when_it_would_hide_nothing(+ tmp_path, monkeypatch, prepare, pinned+):+ guard = prepare(tmp_path, monkeypatch) or contextlib.nullcontext()+ sr = _load_storage_roots()++ with guard:+ sr._setup_cache_env()++ if pinned:+ assert os.environ["MPLCONFIGDIR"] == str(_mpl_managed(tmp_path))+ else:+ assert "MPLCONFIGDIR" not in os.environ+ _assert_the_resolver_really_ran(tmp_path)+++def _dd_managed(tmp_path: Path) -> Path:+ return tmp_path / "studio" / "data-designer"+++def _dd_legacy(tmp_path: Path) -> Path:+ return tmp_path / "home" / ".data-designer"+++def _dd_nothing(tmp_path, monkeypatch):+ (tmp_path / "home").mkdir(parents = True, exist_ok = True)+++def _dd_legacy_in_use(tmp_path, monkeypatch):+ _use_data_designer(_dd_legacy(tmp_path))+++def _dd_managed_in_use(tmp_path, monkeypatch):+ _use_data_designer(_dd_managed(tmp_path))+ _dd_legacy(tmp_path).mkdir(parents = True)+++def _dd_managed_untouched(tmp_path, monkeypatch):+ (_dd_managed(tmp_path) / "managed-assets").mkdir(parents = True)+ _dd_legacy(tmp_path).mkdir(parents = True)+++def _dd_managed_untouched_legacy_in_use(tmp_path, monkeypatch):+ (_dd_managed(tmp_path) / "managed-assets").mkdir(parents = True)+ _use_data_designer(_dd_legacy(tmp_path))+++def _dd_managed_unlistable(tmp_path, monkeypatch):+ managed = _dd_managed(tmp_path)+ _use_data_designer(managed)+ _dd_legacy(tmp_path).mkdir(parents = True)+ real_iterdir = Path.iterdir++ def deny(self):+ if self in (managed, managed / "managed-assets"):+ raise PermissionError(13, "Permission denied")+ return real_iterdir(self)++ monkeypatch.setattr(Path, "iterdir", deny)+++def _dd_managed_assets_denied(tmp_path, monkeypatch):+ managed = _dd_managed(tmp_path)+ _use_data_designer(managed)+ _dd_legacy(tmp_path).mkdir(parents = True)+ return _denied(managed / "managed-assets")+++def _dd_redirected_assets(tmp_path, monkeypatch):+ managed = _dd_managed(tmp_path)+ managed.mkdir(parents = True)+ elsewhere = tmp_path / "big-disk" / "assets"+ elsewhere.mkdir(parents = True) # empty, which is the whole point+ (managed / "managed-assets").symlink_to(elsewhere, target_is_directory = True)+ _use_data_designer(_dd_legacy(tmp_path))+++def _dd_legacy_denied(tmp_path, monkeypatch):+ _use_data_designer(_dd_legacy(tmp_path))+ return _denied(tmp_path / "home")+++def _dd_legacy_failing_volume(tmp_path, monkeypatch):+ legacy = _dd_legacy(tmp_path)+ _use_data_designer(legacy)+ _fail_stat_on(monkeypatch, legacy, OSError(errno.EIO, "Input/output error"))+++def _dd_legacy_symlink_loop(tmp_path, monkeypatch):+ legacy = _dd_legacy(tmp_path)+ legacy.parent.mkdir(parents = True, exist_ok = True)+ legacy.symlink_to(legacy)+ # ELOOP reads as absence through Path.exists() on every release, which is the bug.+ assert Path(legacy).exists() is False+++ "prepare, pinned",+ [+ # Data Designer's home is not a cache: repointing one that holds yaml configs and+ # multi-GB parquet hides them behind a re-seeded default. Our own home wins once it has+ # been USED, since the legacy probe re-runs every launch and a standalone run creating+ # ~/.data-designer would otherwise take the work written under the Studio root.+ pytest.param(_dd_nothing, True, id = "no legacy home at all"),+ pytest.param(_dd_legacy_in_use, False, id = "a legacy home in use"),+ pytest.param(_dd_managed_in_use, True, id = "our home in use, legacy empty"),+ pytest.param(_dd_managed_untouched, False, id = "our home untouched, legacy empty"),+ pytest.param(+ _dd_managed_untouched_legacy_in_use, False, id = "our home untouched, legacy in use"+ ),+ pytest.param(_dd_managed_unlistable, True, id = "our home we may not list"),+ pytest.param(+ _dd_managed_assets_denied, True, id = "our managed-assets denied", marks = _NEEDS_CHMOD+ ),+ pytest.param(_dd_redirected_assets, True, id = "managed-assets redirected by a link"),+ pytest.param(+ _dd_legacy_denied, False, id = "a legacy home we may not read", marks = _NEEDS_CHMOD+ ),+ pytest.param(_dd_legacy_failing_volume, False, id = "a legacy home on a failing volume"),+ pytest.param(_dd_legacy_symlink_loop, False, id = "a legacy home that is a symlink loop"),+ ],+)+def test_the_data_designer_home_is_pinned_only_when_it_would_hide_nothing(+ tmp_path, monkeypatch, prepare, pinned+):+ guard = prepare(tmp_path, monkeypatch) or contextlib.nullcontext()+ sr = _load_storage_roots()++ with guard:+ sr._setup_cache_env()++ managed = _dd_managed(tmp_path)+ if pinned:+ assert os.environ["DATA_DESIGNER_HOME"] == str(managed)+ assert os.environ["DATA_DESIGNER_MANAGED_ASSETS_PATH"] == str(managed / "managed-assets")+ else:+ assert "DATA_DESIGNER_HOME" not in os.environ+ assert "DATA_DESIGNER_MANAGED_ASSETS_PATH" not in os.environ+ _assert_the_resolver_really_ran(tmp_path)+++def test_managed_assets_follow_an_explicit_data_designer_home(monkeypatch, tmp_path):+ chosen = tmp_path / "mine" / ".data-designer"+ monkeypatch.setenv("DATA_DESIGNER_HOME", str(chosen))+ sr = _load_storage_roots()++ sr._setup_cache_env()++ assert os.environ["DATA_DESIGNER_HOME"] == str(chosen)+ assert "DATA_DESIGNER_MANAGED_ASSETS_PATH" not in os.environ+++def test_an_explicit_triton_home_keeps_its_own_cache_dir(monkeypatch, tmp_path):+ chosen = tmp_path / "mine" / "triton-home"+ monkeypatch.setenv("TRITON_HOME", str(chosen))+ sr = _load_storage_roots()++ sr._setup_cache_env()++ assert os.environ["TRITON_HOME"] == str(chosen)+ assert "TRITON_CACHE_DIR" not in os.environ+++def test_triton_keeps_reading_the_default_override_dir(tmp_path):+ # TRITON_HOME would move ~/.triton/override, which holds user files, along with the cache,+ # so a TRITON_KERNEL_OVERRIDE=1 run would compile something else instead.+ pytest.importorskip("triton")+ override = tmp_path / "home" / ".triton" / "override" / "0123456789abcdef"+ override.mkdir(parents = True)+ (override / "kernel.ttir").write_text("// hand-tuned\n", encoding = "utf-8")+ sr = _load_storage_roots()++ sr._setup_cache_env()++ # A fresh interpreter: torch may have imported Triton and pinned a cache dir already.+ probe = subprocess.run(+ [+ sys.executable,+ "-c",+ "import json; from triton import knobs;"+ "print(json.dumps({'cache': knobs.cache.dir,"+ "'dump': knobs.cache.dump_dir,"+ "'override': knobs.cache.override_dir}))",+ ],+ env = dict(os.environ),+ capture_output = True,+ text = True,+ check = True,+ )+ result = json.loads(probe.stdout.strip().splitlines()[-1])++ assert Path(result["override"]) == override.parent+ assert (Path(result["override"]) / override.name / "kernel.ttir").is_file()+ assert result["cache"] == str(tmp_path / "studio" / "cache" / "triton")+ assert result["dump"] == str(tmp_path / "studio" / "cache" / "triton-dump")+++def test_the_macos_matplotlib_config_dir_matches_matplotlibs_own(monkeypatch, tmp_path):+ # macOS is matplotlib's "other platforms" branch: ~/.matplotlib, not Application Support.+ pytest.importorskip("matplotlib")+ monkeypatch.setattr(sys, "platform", "darwin")+ sr = _load_storage_roots()++ ours = sr._matplotlib_config_dir()++ # sys.platform is read inside _get_config_or_cache_dir, so a fresh interpreter can be+ # asked what it would do on a Mac.+ probe = subprocess.run(+ [+ sys.executable,+ "-c",+ "import sys, matplotlib; sys.platform = 'darwin';"+ "print(matplotlib._get_config_or_cache_dir(matplotlib._get_xdg_config_dir))",+ ],+ env = {**os.environ, "HOME": str(tmp_path / "home"), "MPLCONFIGDIR": ""},+ capture_output = True,+ text = True,+ check = True,+ )+ theirs = Path(probe.stdout.strip().splitlines()[-1])++ assert ours is not None+ assert ours.resolve() == theirs.resolve()+++def _matplotlib_config_dir(home: Path) -> Path:+ """Where matplotlib on THIS platform would look for a user matplotlibrc.++ _get_config_or_cache_dir: XDG on Linux and FreeBSD, a non-empty ~/.matplotlib ahead of+ %LOCALAPPDATA% on Windows, ~/.matplotlib everywhere else. The Linux branch alone was hardcoded+ here, so on a mac runner these tests wrote the rc into a directory matplotlib never reads: the+ guard correctly found nothing to strand, pinned MPLCONFIGDIR, and nine tests failed for a+ reason that was in them rather than in the code they cover. The two tests above hold this+ derivation against real matplotlib on each spoofed platform, so it cannot quietly drift into+ agreeing with storage_roots.py and nothing else.++ Windows resolves to ~/.matplotlib rather than %LOCALAPPDATA%: the callers write a file into+ whatever this returns, LOCALAPPDATA on a runner is outside tmp_path, and a non-empty+ ~/.matplotlib is the branch matplotlib itself prefers.+ """+ if sys.platform.startswith(("linux", "freebsd")):+ base = (os.environ.get("XDG_CONFIG_HOME") or "").strip()+ return (Path(base) if base else home / ".config") / "matplotlib"+ return home / ".matplotlib"+++def test_matplotlib_reads_the_config_the_pin_would_have_hidden(tmp_path):+ pytest.importorskip("matplotlib")+ config = _matplotlib_config_dir(tmp_path / "home")+ (config / "stylelib").mkdir(parents = True)+ (config / "matplotlibrc").write_text("figure.dpi: 222\n", encoding = "utf-8")+ (config / "stylelib" / "house.mplstyle").write_text("axes.facecolor: black\n", encoding = "utf-8")+ sr = _load_storage_roots()++ sr._setup_cache_env()++ # A fresh interpreter: matplotlib caches the config dir on first read.+ probe = subprocess.run(+ [+ sys.executable,+ "-c",+ "import json, matplotlib, matplotlib.style;"+ "print(json.dumps({'rc': matplotlib.matplotlib_fname(),"+ "'dpi': matplotlib.rcParams['figure.dpi'],"+ "'style': 'house' in matplotlib.style.available}))",+ ],+ env = dict(os.environ),+ capture_output = True,+ text = True,+ check = True,+ )+ result = json.loads(probe.stdout.strip().splitlines()[-1])++ assert result["rc"] == str(config / "matplotlibrc")+ assert result["dpi"] == 222.0+ assert result["style"] is True+++ not sys.platform.startswith(("linux", "freebsd")),+ reason = "XDG config base is the Linux/FreeBSD branch",+)+def test_an_xdg_config_dir_is_read_without_a_resolvable_home(monkeypatch, tmp_path):+ # _get_xdg_config_dir reads XDG_CONFIG_HOME before it needs a home, so bailing out on+ # Path.home() pinned over a real matplotlibrc.+ config = tmp_path / "xdg" / "matplotlib"+ config.mkdir(parents = True)+ (config / "matplotlibrc").write_text("figure.dpi: 222\n", encoding = "utf-8")+ monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg"))+ sr = _load_storage_roots()++ def no_home():+ raise RuntimeError("Could not determine home directory.")++ monkeypatch.setattr(Path, "home", staticmethod(no_home))++ assert sr._matplotlib_defaults(tmp_path / "studio" / "cache") == {}+++def test_only_a_positive_absence_counts_as_nothing_at_a_path(tmp_path):+ # The one rule every "pin only when there is nothing to strand" probe shares.+ sr = _load_storage_roots()+ present = tmp_path / "present"+ present.write_text("x", encoding = "utf-8")+ loop = tmp_path / "loop"+ loop.symlink_to(loop)+ dangling = tmp_path / "dangling"+ dangling.symlink_to(tmp_path / "not-mounted-yet" / "data")++ assert sr._nothing_at(tmp_path / "absent") is True+ assert sr._nothing_at(present) is False+ # Both of these answer False through Path.exists(), which is the bug.+ assert Path(loop).exists() is False and sr._nothing_at(loop) is False+ assert Path(dangling).exists() is False and sr._nothing_at(dangling) is False+++def test_nothing_at_reports_an_uninspectable_directory_as_holding_something(monkeypatch, tmp_path):+ sr = _load_storage_roots()+ styles = tmp_path / "stylelib"+ styles.mkdir()+ real_scandir = os.scandir++ def deny(+ path = ".",+ *args,+ **kwargs,+ ):+ if isinstance(path, (str, os.PathLike)) and Path(path) == styles:+ raise OSError(errno.EIO, "Input/output error")+ return real_scandir(path, *args, **kwargs)++ monkeypatch.setattr(os, "scandir", deny)++ assert sr._nothing_at(styles, ending = ".mplstyle") is False+ assert sr._nothing_at(tmp_path / "absent", ending = ".mplstyle") is True+++def _fake_torch_on_path(+ tmp_path,+ label,+ version,+ cuda = None,+ hip = None,+ debug = False,+):+ """A torch that has a version.py and explodes if anything imports it. version.py is written+ the way recent torch generates it, annotations and all, so the parser meets the real shape."""+ pkg = tmp_path / label / "torch"+ pkg.mkdir(parents = True)+ (pkg / "__init__.py").write_text("raise AssertionError('torch was imported')\n")+ (pkg / "version.py").write_text(+ "from typing import Optional\n\n"+ f"__version__ = {version!r}\n"+ f"debug = {debug!r}\n"+ f"cuda: Optional[str] = {cuda!r}\n"+ "git_version = '5811a8d7da873dd699ff6687092c225caffcf1bb'\n"+ f"hip: Optional[str] = {hip!r}\n"+ "xpu: Optional[str] = None\n"+ )+ return str(tmp_path / label)+++def _only_torch(entry):+ saved_path = list(sys.path)+ saved_module = sys.modules.pop("torch", None)+ sys.path.insert(0, entry)+ importlib.invalidate_caches()+ try:+ yield+ finally:+ sys.path[:] = saved_path+ if saved_module is not None:+ sys.modules["torch"] = saved_module+ importlib.invalidate_caches()+++def test_torch_extension_cache_keeps_an_abi_folder(tmp_path):+ # torch appends py<ver>_<accelerator> to its DEFAULT root only, so a pin carries it.+ sr = _load_storage_roots()++ sr._setup_cache_env()++ pinned = Path(os.environ["TORCH_EXTENSIONS_DIR"])+ assert str(pinned).startswith(str(tmp_path / "studio"))+ assert pinned.parent.name == "torch-extensions"+ assert pinned.name != "torch-extensions", "extension cache is shared across runtimes"+ assert pinned.name.startswith(f"py{sys.version_info.major}{sys.version_info.minor}")+++def _interpreter_prefix() -> str:+ """The interpreter-and-ABI part of the tag, spelled out here rather than imported.++ Reusing storage_roots' own helper would make every assertion below agree with whatever+ it happens to produce, so the exact-string tests would stop being able to catch a change+ in the tag at all.+ """+ abi = getattr(sys, "abiflags", "")+ host = re.sub(r"[^A-Za-z0-9.]+", "-", f"{sys.platform}-{platform.machine() or 'unknown'}")+ return f"py{sys.version_info.major}{sys.version_info.minor}{abi}_{host}"+++def test_torch_extension_cache_separates_incompatible_builds(tmp_path):+ sr = _load_storage_roots()++ tags = []+ for label, version, cuda in (("a", "2.9.1+cu128", "12.8"), ("b", "2.9.1+cu126", "12.6")):+ with _only_torch(_fake_torch_on_path(tmp_path, label, version, cuda = cuda)):+ tags.append(sr._torch_runtime_tag())++ assert tags[0] != tags[1], f"two torch builds shared one extension dir: {tags[0]}"+ assert "cu128" in tags[0] and "cu126" in tags[1]+ # Path-safe: no '+' or other separators survive into the directory name.+ assert all(part.replace(".", "").replace("-", "").replace("_", "").isalnum() for part in tags)+++def test_torch_extension_tag_survives_a_missing_torch(tmp_path):+ # First launch, before the venv has torch: still isolated by interpreter.+ sr = _load_storage_roots()+ empty = tmp_path / "empty"+ empty.mkdir()++ with _only_torch(str(empty)):+ saved = list(sys.path)+ try:+ sys.path[:] = [str(empty)]+ tag = sr._torch_runtime_tag()+ finally:+ sys.path[:] = saved++ assert tag == _interpreter_prefix()+++def test_torch_extension_cache_separates_builds_sharing_one_version_string(tmp_path):+ # conda-forge's CPU and CUDA packages of one release share a __version__, differing only+ # in a conda build string.+ sr = _load_storage_roots()++ tags = []+ for label, cuda in (("cpu", None), ("cu126", "12.6"), ("cu128", "12.8")):+ with _only_torch(_fake_torch_on_path(tmp_path, label, "2.9.1", cuda = cuda)):+ tags.append(sr._torch_runtime_tag())++ assert len(set(tags)) == 3, f"builds with different CUDA ABIs shared one dir: {tags}"+ prefix = _interpreter_prefix()+ assert tags[0] == f"{prefix}_cpu_2.9.1"+ assert tags[1] == f"{prefix}_cu126_2.9.1"+ assert tags[2] == f"{prefix}_cu128_2.9.1"+++def test_torch_extension_cache_separates_a_rocm_build_from_a_cpu_build(tmp_path):+ # torch names a ROCm build 'cpu', since version.cuda is unset; hip is read first.+ sr = _load_storage_roots()++ tags = []+ for label, hip in (("cpu", None), ("rocm", "6.4.43484-123eb5128")):+ with _only_torch(_fake_torch_on_path(tmp_path, label, "2.9.1", hip = hip)):+ tags.append(sr._torch_runtime_tag())++ assert tags[0] != tags[1], f"a ROCm build shared the CPU extension dir: {tags[0]}"+ assert "rocm6.4.43484-123eb5128" in tags[1]+++def test_torch_extension_cache_separates_two_host_architectures(tmp_path, monkeypatch):+ # An arm64 python and a Rosetta x86_64 python on ONE Mac agree on every other field, so+ # torch's py<ver>_<cu_str> folder gives them one directory and the .so fails to load.+ sr = _load_storage_roots()++ tags = []+ for machine in ("arm64", "x86_64"):+ monkeypatch.setattr(platform, "machine", lambda m = machine: m)+ with _only_torch(_fake_torch_on_path(tmp_path, machine, "2.9.1")):+ tags.append(sr._torch_runtime_tag())++ assert tags[0] != tags[1], f"two host architectures shared one extension dir: {tags[0]}"+ assert "arm64" in tags[0] and "x86-64" in tags[1]+++def test_torch_extension_cache_survives_an_unnameable_architecture(tmp_path, monkeypatch):+ # platform.machine() returns "" when the platform cannot answer; no empty segment.+ sr = _load_storage_roots()++ monkeypatch.setattr(platform, "machine", lambda: "")+ with _only_torch(_fake_torch_on_path(tmp_path, "blank", "2.9.1")):+ tag = sr._torch_runtime_tag()++ assert "__" not in tag and not tag.endswith("_")+ assert "unknown" in tag+++def test_torch_extension_cache_separates_a_debug_build(tmp_path):+ # A debug build keeps the soname of a release one but not its ABI.+ sr = _load_storage_roots()++ tags = []+ for label, debug in (("release", False), ("debug", True)):+ entry = _fake_torch_on_path(tmp_path, label, "2.9.1+cu128", cuda = "12.8", debug = debug)+ with _only_torch(entry):+ tags.append(sr._torch_runtime_tag())++ assert tags[0] != tags[1], f"a debug build shared the release extension dir: {tags[0]}"+ assert tags[1].endswith("_debug")+++def test_torch_runtime_tag_never_imports_torch(tmp_path):+ # Runs before torch exists in a fresh venv, and importing it on the startup path would cost+ # seconds. The fake package raises on import, so a skip is a failure.+ sr = _load_storage_roots()+ entry = _fake_torch_on_path(tmp_path, "guard", "2.9.1+cu128", cuda = "12.8")++ with _only_torch(entry):+ tag = sr._torch_runtime_tag()+ assert "torch" not in sys.modules, "torch was imported to build the cache tag"++ assert "cu128" in tag+++def test_a_managed_matplotlibrc_is_not_displaced_by_a_later_legacy_one(tmp_path):+ """The legacy probe re-runs every launch, so on its own it hands a matplotlibrc written+ HERE to a ~/.config/matplotlib created later by some other tool.++ Measured across four launches before the fix: dpi 177 from the managed config, then 222 once+ a legacy rc appeared, then 177 again when it was removed, with the managed rc present+ throughout. A style that changes on a later launch and changes back is worse than either+ choice made once. _data_designer_defaults already applies this rule to its own home.+ """+ managed = tmp_path / "studio" / "cache" / "matplotlib"+ managed.mkdir(parents = True)+ (managed / "matplotlibrc").write_text("figure.dpi: 177\n", encoding = "utf-8")+ config = _matplotlib_config_dir(tmp_path / "home")+ config.mkdir(parents = True)+ (config / "matplotlibrc").write_text("figure.dpi: 222\n", encoding = "utf-8")+ sr = _load_storage_roots()++ sr._setup_cache_env()++ assert os.environ["MPLCONFIGDIR"] == str(managed)+++def test_a_blank_toolchain_override_is_dropped_on_a_spaced_root(monkeypatch, tmp_path):+ """ "blank counts as unset" has to hold for a root we refuse to pin, too.++ Inductor distinguishes an absent TORCHINDUCTOR_CACHE_DIR from a present one, so a leftover+ " " becomes a relative compiler path and is then split by the very unquoted command+ construction the whitespace refusal exists to avoid.+ """+ spaced = tmp_path / "My Studio"+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(spaced))+ monkeypatch.setenv("TORCHINDUCTOR_CACHE_DIR", " ")+ sr = _load_storage_roots()++ sr._setup_cache_env()++ assert "TORCHINDUCTOR_CACHE_DIR" not in os.environ+++def test_an_unusable_managed_inductor_path_is_not_published(monkeypatch, tmp_path):+ """torch treats the value as authoritative, so a path it cannot use fails every compile.++ Unset, it would have used its own temporary cache instead. The placement error is swallowed+ on purpose so startup survives, which is what let an unusable path stay published.+ """+ cache = tmp_path / "studio" / "cache"+ cache.mkdir(parents = True)+ # A regular file where the directory should go: mkdir raises FileExistsError, which the+ # best-effort handler treats as "already there".+ (cache / "torchinductor").write_text("not a directory", encoding = "utf-8")+ sr = _load_storage_roots()++ sr._setup_cache_env()++ assert "TORCHINDUCTOR_CACHE_DIR" not in os.environ+ # The other pins are unaffected: only the one that could not be made is withheld.+ assert os.environ["CUDA_CACHE_PATH"] == str(cache / "cuda")+++ os.name == "nt" or os.geteuid() == 0, reason = "chmod 555 denies neither root nor Windows"+)+def test_a_read_only_managed_cache_is_not_published(tmp_path):+ """A directory that exists but cannot be written to is the same defect as a missing one.++ mkdir passes exist_ok = False, so an existing directory takes the FileExistsError path and+ proves nothing about writability. torch only falls back to its own temporary cache when the+ variable is UNSET (torch/_inductor/runtime/cache_dir_utils.py), so a read-only pin fails+ every compile.+ """+ cache = tmp_path / "studio" / "cache"+ for name in ("torchinductor", "triton", "cuda"):+ (cache / name).mkdir(parents = True)+ (cache / name).chmod(0o555)+ sr = _load_storage_roots()+ try:+ sr._setup_cache_env()++ for key in ("TORCHINDUCTOR_CACHE_DIR", "TRITON_CACHE_DIR", "CUDA_CACHE_PATH"):+ assert key not in os.environ, key+ # Withheld, not blanked: an empty value is a relative path to the library reading it.+ assert os.environ["NUMBA_CACHE_DIR"] == str(cache / "numba")+ finally:+ for name in ("torchinductor", "triton", "cuda"):+ (cache / name).chmod(0o755)+++def test_the_write_probe_leaves_nothing_behind(tmp_path):+ """The probe creates a file in the directory it is testing; it must not accumulate."""+ sr = _load_storage_roots()++ sr._setup_cache_env()++ inductor = Path(os.environ["TORCHINDUCTOR_CACHE_DIR"])+ assert inductor.is_dir()+ assert list(inductor.iterdir()) == []+++def test_a_usable_managed_inductor_path_is_still_published(tmp_path):+ """The rule above must not withhold the ordinary case."""+ sr = _load_storage_roots()++ sr._setup_cache_env()++ assert os.environ["TORCHINDUCTOR_CACHE_DIR"] == str(+ tmp_path / "studio" / "cache" / "torchinductor"+ )++[email protected](os.name == "nt" or os.geteuid() == 0, reason = "chmod 000 denies neither")+def test_a_note_that_could_not_be_read_is_not_cached_as_a_missing_one(monkeypatch, tmp_path):+ """A miss is a fact about the install; a failure to LOOK is a fact about one instant.++ _recorded_master_root() memoises per studio path, and the backend is a long-lived process.+ Caching an EACCES on share/ -- a mount that came back, a permission fixed a second later --+ pinned that process to the legacy runtime paths for its whole lifetime with the trees it+ should have found sitting right beside it, and nothing in production calls+ forget_recorded_master_root() to get back out.+ """+ master = tmp_path / "root"+ studio = master / "studio"+ share = studio / "share"+ share.mkdir(parents = True)+ (share / ".unsloth-master-root").write_text(str(master) + "\n", encoding = "utf-8")+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(studio))+ sr = _load_storage_roots()++ share.chmod(0o000)+ try:+ assert sr.unsloth_home() is None+ finally:+ share.chmod(0o755)++ assert sr.unsloth_home() == master, "a transient read failure was cached as a missing note"+++def test_a_genuinely_absent_note_is_still_cached(monkeypatch, tmp_path):+ """The other half: the fix must not turn the memo off. unsloth_home() runs on every+ cache-var lookup, so re-stat'ing a note that is simply not there is a syscall per call."""+ studio = tmp_path / "root" / "studio"+ (studio / "share").mkdir(parents = True)+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(studio))+ sr = _load_storage_roots()++ assert sr.unsloth_home() is None+ # Written after the miss was cached: a cached answer is the point, and+ # forget_recorded_master_root() is the way back out for an installer that writes one later.+ (studio / "share" / ".unsloth-master-root").write_text(+ str(tmp_path / "root") + "\n",+ encoding = "utf-8",+ )+ assert sr.unsloth_home() is None+ sr.forget_recorded_master_root()+ assert sr.unsloth_home() == tmp_path / "root"+++def test_a_write_probe_that_cannot_close_its_handle_is_a_no_not_a_crash(monkeypatch, tmp_path):+ """_usable_dir answers yes or no. Every other failure in it returns False; an OSError from+ os.close escaping instead would take the whole _setup_cache_env() -- and the backend start+ that called it -- down with it."""+ sr = _load_storage_roots()++ real_close = os.close++ def _failing_close(fd):+ real_close(fd)+ raise OSError(errno.EIO, "close failed")++ monkeypatch.setattr(sr.os, "close", _failing_close)+ assert sr._usable_dir(str(tmp_path)) is False++ monkeypatch.setattr(sr.os, "close", real_close)+ assert sr._usable_dir(str(tmp_path)) is True+++def _note_ancestor_of_a_legacy_tree(tmp_path, monkeypatch):+ """A note naming $HOME, which passes containment because ~/.unsloth/studio is inside it.++ process.rs scrubs UNSLOTH_HOME and UNSLOTH_PORTABLE from every managed spawn so Tauri uses+ the legacy root whatever the environment says. A note is a FILE, which no env_remove reaches,+ so this is how both variables came back and moved the packaged app's caches.+ """+ home = tmp_path / "home"+ studio = home / ".unsloth" / "studio"+ _write_note(studio, home)+ monkeypatch.setenv("HOME", str(home))+ monkeypatch.setenv("USERPROFILE", str(home))+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(studio))+ for scrubbed in ("UNSLOTH_HOME", "UNSLOTH_PORTABLE", "STUDIO_HOME"):+ monkeypatch.delenv(scrubbed, raising = False)+ return None+++def _note_naming_the_legacy_default(tmp_path, monkeypatch):+ """The reader has to decline it, not just the writer: setup only sweeps an old note when it+ runs again, and the user who hit this set UNSLOTH_HOME once, for one command."""+ home = tmp_path / "home"+ studio = home / ".unsloth" / "studio"+ _write_note(studio, home / ".unsloth")+ monkeypatch.setenv("HOME", str(home))+ monkeypatch.setenv("USERPROFILE", str(home))+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(studio))+ return None+++def _note_naming_a_real_master_root(tmp_path, monkeypatch):+ """The other side of the rule: a recorded root that is not the legacy default and that+ contains this Studio tree is exactly what the note is for."""+ master = tmp_path / "portable"+ _write_note(master / "studio", master)+ monkeypatch.setenv("HOME", str(tmp_path / "home"))+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(master / "studio"))+ return master+++def _an_explicit_legacy_unsloth_home(tmp_path, monkeypatch):+ """Only the RECORDED root is declined. unsloth_home() returns an explicit UNSLOTH_HOME before+ it reads any note, and narrowing that would change what the variable means."""+ home = tmp_path / "home"+ (home / ".unsloth" / "studio" / "share").mkdir(parents = True)+ monkeypatch.setenv("HOME", str(home))+ monkeypatch.setenv("USERPROFILE", str(home))+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(home / ".unsloth" / "studio"))+ monkeypatch.setenv("UNSLOTH_HOME", str(home / ".unsloth"))+ return home / ".unsloth"+++def _write_note(studio: Path, root: Path) -> None:+ (studio / "share").mkdir(parents = True, exist_ok = True)+ (studio / "share" / ".unsloth-master-root").write_text(str(root) + "\n", encoding = "utf-8")+++ "prepare",+ [+ pytest.param(_note_ancestor_of_a_legacy_tree, id = "a note naming an ancestor"),+ pytest.param(_note_naming_the_legacy_default, id = "a note naming the legacy default"),+ pytest.param(_note_naming_a_real_master_root, id = "a note naming a real master root"),+ pytest.param(_an_explicit_legacy_unsloth_home, id = "an explicit legacy UNSLOTH_HOME"),+ ],+)+def test_a_master_root_is_honoured_only_when_a_reader_should_honour_it(+ tmp_path, monkeypatch, prepare+):+ """`prepare` returns the root that must be honoured, or None when it must be declined.++ The hub cache is asserted either way, since declining is only meaningful if the shared cache+ really stays shared, and honouring is only meaningful if the caches really move.+ """+ expected = prepare(tmp_path, monkeypatch)+ sr = _load_storage_roots()++ assert sr.unsloth_home() == expected+ assert sr.portable_mode() is (expected is not None)++ sr._setup_cache_env()++ hub = Path(os.environ["HF_HUB_CACHE"])+ if expected is None:+ assert hub == Path(os.environ["HOME"]) / ".cache" / "huggingface" / "hub"+ assert "TORCH_HOME" not in os.environ+ else:+ assert expected in hub.parents+ assert Path(os.environ["TORCH_HOME"]).is_relative_to(expected)+++# 25 of 113 cases stayed green with the production hunks reverted: each asserts a variable is+# ABSENT, which is equally true when no pinning code exists, so they were assertions rather than+# negative controls. Pairing a decline with the pins that must STILL happen makes them falsifiable.+_DECLINE_SIBLINGS = (+ "TORCHINDUCTOR_CACHE_DIR",+ "NUMBA_CACHE_DIR",+ "CUDA_CACHE_PATH",+ "UV_CACHE_DIR",+ "UNSLOTH_COMPILE_LOCATION",+)++[email protected]("declined", ["MPLCONFIGDIR", "DATA_DESIGNER_HOME"])+def test_declining_one_pin_never_means_the_resolver_did_nothing(tmp_path, declined):+ """A decline is only meaningful next to a pin. If the resolver were absent, or returned early,+ the sibling assertions below would fail and the decline would stop proving anything."""+ home = tmp_path / "home"+ if declined == "MPLCONFIGDIR":+ config = _matplotlib_config_dir(home)+ config.mkdir(parents = True)+ (config / "matplotlibrc").write_text("figure.dpi: 123\n", encoding = "utf-8")+ else:+ (home / ".data-designer" / "recipes").mkdir(parents = True)+ sr = _load_storage_roots()++ sr._setup_cache_env()++ assert declined not in os.environ, f"{declined} displaced user files"+ root = str(tmp_path / "studio")+ for sibling in _DECLINE_SIBLINGS:+ value = os.environ.get(sibling)+ assert value, f"{sibling} unpinned: the decline of {declined} proves nothing"+ assert value.startswith(root), f"{sibling} escaped the studio root: {value}"+++def test_an_uninspectable_probe_declines_and_still_pins_everything_else(tmp_path):+ """Same rule for the os.lstat/os.scandir failure paths, which are the subtlest of the 25:+ an unreadable matplotlib config must leave MPLCONFIGDIR alone AND leave the rest pinned."""+ config = _matplotlib_config_dir(tmp_path / "home")+ config.parent.mkdir(parents = True, exist_ok = True)+ config.write_text("", encoding = "utf-8") # a file where a directory belongs: ENOTDIR+ sr = _load_storage_roots()++ sr._setup_cache_env()++ assert "MPLCONFIGDIR" not in os.environ+ for sibling in _DECLINE_SIBLINGS:+ assert os.environ.get(sibling, "").startswith(str(tmp_path / "studio")), sibling+++def test_a_file_where_the_config_dir_belongs_declines_the_pin_on_windows_too(monkeypatch, tmp_path):+ """_nothing_at reads a FileNotFoundError as absence, and on Windows that error also means+ "a parent component is a file" -- the case POSIX reports as NotADirectoryError and declines.+ So with a file where ~/.matplotlib belongs, POSIX declined the pin and Windows took it,+ hiding whatever the user had underneath. Caught by the windows-latest leg.++ Reproduced by the error shape rather than the platform, since the Linux runners cannot raise+ it; the POSIX arm of the same fixture is the test directly above.+ """+ sr = _load_storage_roots()+ config = _matplotlib_config_dir(tmp_path / "home")+ config.parent.mkdir(parents = True, exist_ok = True)+ config.write_text("", encoding = "utf-8")++ real_lstat = sr.os.lstat++ def windows_shaped_lstat(p, *a, **k):+ text = os.fspath(p)+ if text != str(config) and text.startswith(str(config) + os.sep):+ raise FileNotFoundError(2, "The system cannot find the path specified", text)+ return real_lstat(p, *a, **k)++ monkeypatch.setattr(sr.os, "lstat", windows_shaped_lstat)++ assert (+ sr._nothing_at(config / "matplotlibrc") is False+ ), "a file where the config dir belongs read as 'nothing there'"+ # A genuinely empty, genuinely present directory must still read as empty, or the fix above+ # would decline every pin and the guard would stop guarding anything.+ empty = tmp_path / "really-empty"+ empty.mkdir()+ assert sr._nothing_at(empty / "matplotlibrc") is True+ # And a path with nothing along it at all is still absence, which is the default install.+ assert sr._nothing_at(tmp_path / "never" / "created" / "matplotlibrc") is Truediff --git a/studio/backend/tests/test_setup_cache_env_hf_home.py b/studio/backend/tests/test_setup_cache_env_hf_home.pyindex c0bf61d914e..b3ea8e90d8f 100644--- a/studio/backend/tests/test_setup_cache_env_hf_home.py+++ b/studio/backend/tests/test_setup_cache_env_hf_home.py@@ -37,6 +37,9 @@ _STORAGE_ROOTS_PATH = Path(__file__).resolve().parent.parent / "utils/paths/stordef _isolate_studio_home(monkeypatch, tmp_path):# Keep _setup_cache_env's UV/VLLM mkdirs out of the real ~/.unsloth/studio.monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "studio"))+ # _setup_cache_env writes os.environ directly, so a portable test would leak these forward.+ for key in ("UNSLOTH_HOME", "UNSLOTH_PORTABLE", "TORCH_HOME"):+ monkeypatch.delenv(key, raising = False)@pytest.fixture(autouse = True)@@ -73,10 +76,27 @@ def _load_storage_roots():def _clear_hf_env(monkeypatch):- for key in ("HF_HOME", "HF_HUB_CACHE", "HF_XET_CACHE", "HUGGINGFACE_HUB_CACHE"):+ for key in (+ "HF_HOME",+ "HF_HUB_CACHE",+ "HF_XET_CACHE",+ "HUGGINGFACE_HUB_CACHE",+ "HF_DATASETS_CACHE",+ "HF_ASSETS_CACHE",+ "HF_MODULES_CACHE",+ ):monkeypatch.delenv(key, raising = False)+def _portable_install(monkeypatch, tmp_path):+ """Turn the fixture's studio home into a portable one and return its root."""+ monkeypatch.delenv("UNSLOTH_STUDIO_HOME", raising = False)+ monkeypatch.delenv("UNSLOTH_PORTABLE", raising = False)+ master = tmp_path / "portable"+ monkeypatch.setenv("UNSLOTH_HOME", str(master))+ return master++def test_custom_hf_home_seeds_hub_and_xet(monkeypatch, tmp_path):_clear_hf_env(monkeypatch)custom = tmp_path / "shared" / "huggingface"@@ -127,6 +147,179 @@ def test_whitespace_hf_home_falls_back_to_default(monkeypatch, tmp_path):assert os.environ["HF_HUB_CACHE"] == str(tmp_path / "xdg" / "huggingface" / "hub")+def test_explicit_hf_home_keeps_the_datasets_and_assets_caches(monkeypatch, tmp_path):+ # A user who names one HF_HOME gets one Hugging Face cache: assets and datasets derive+ # from it, so pinning either under the portable root splits it across two volumes.+ _clear_hf_env(monkeypatch)+ master = _portable_install(monkeypatch, tmp_path)+ chosen = tmp_path / "bigdisk" / "huggingface"+ monkeypatch.setenv("HF_HOME", str(chosen))+ sr = _load_storage_roots()++ sr._setup_cache_env()++ import os++ assert os.environ["HF_HUB_CACHE"] == str(chosen / "hub")+ assert os.environ["HF_XET_CACHE"] == str(chosen / "xet")+ assert "HF_DATASETS_CACHE" not in os.environ+ assert "HF_ASSETS_CACHE" not in os.environ+ assert "HF_MODULES_CACHE" not in os.environ+ # Containment is only given up for the root the user named.+ assert os.environ["TORCH_HOME"].startswith(str(master))+++def test_a_dedicated_cache_var_still_outranks_an_explicit_hf_home(monkeypatch, tmp_path):+ _clear_hf_env(monkeypatch)+ _portable_install(monkeypatch, tmp_path)+ monkeypatch.setenv("HF_HOME", str(tmp_path / "bigdisk" / "huggingface"))+ mine = tmp_path / "mine" / "datasets"+ monkeypatch.setenv("HF_DATASETS_CACHE", str(mine))+ sr = _load_storage_roots()++ sr._setup_cache_env()++ import os++ assert os.environ["HF_DATASETS_CACHE"] == str(mine)+++def test_portable_mode_without_an_explicit_hf_home_still_contains_them(monkeypatch, tmp_path):+ # The other side: with no HF_HOME of the user's own, both derive from the host copy+ # Unsloth leaves behind and would still write outside the volume.+ _clear_hf_env(monkeypatch)+ monkeypatch.setenv("HOME", str(tmp_path / "home"))+ master = _portable_install(monkeypatch, tmp_path)+ sr = _load_storage_roots()++ sr._setup_cache_env()++ import os++ assert os.environ["HF_DATASETS_CACHE"].startswith(str(master))+ assert os.environ["HF_ASSETS_CACHE"].startswith(str(master))+ # transformers derives this from HF_HOME, which stays on the host, and appends it to+ # sys.path, so a trust_remote_code load would leave generated modules outside the volume.+ assert os.environ["HF_MODULES_CACHE"].startswith(str(master))+++def test_a_normal_install_leaves_the_modules_cache_where_transformers_looks(monkeypatch, tmp_path):+ _clear_hf_env(monkeypatch)+ monkeypatch.setenv("HOME", str(tmp_path / "home"))+ monkeypatch.delenv("UNSLOTH_HOME", raising = False)+ monkeypatch.delenv("UNSLOTH_PORTABLE", raising = False)+ sr = _load_storage_roots()++ sr._setup_cache_env()++ import os++ assert "HF_MODULES_CACHE" not in os.environ+++def test_an_explicit_modules_cache_outranks_the_portable_default(monkeypatch, tmp_path):+ _clear_hf_env(monkeypatch)+ monkeypatch.setenv("HOME", str(tmp_path / "home"))+ _portable_install(monkeypatch, tmp_path)+ mine = tmp_path / "mine" / "modules"+ monkeypatch.setenv("HF_MODULES_CACHE", str(mine))+ sr = _load_storage_roots()++ sr._setup_cache_env()++ import os++ assert os.environ["HF_MODULES_CACHE"] == str(mine)++[email protected]("hub_variable", ["HF_HUB_CACHE", "HUGGINGFACE_HUB_CACHE"])+def test_a_hub_only_override_still_contains_the_xet_cache(monkeypatch, tmp_path, hub_variable):+ # huggingface_hub derives HF_XET_CACHE from HF_HOME, never from HF_HUB_CACHE, so a hub-only+ # override would keep a portable install writing Xet data outside the volume.+ _clear_hf_env(monkeypatch)+ monkeypatch.setenv("HOME", str(tmp_path / "home"))+ monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "home" / ".cache"))+ master = _portable_install(monkeypatch, tmp_path)+ chosen = tmp_path / "bigdisk" / "hub"+ monkeypatch.setenv(hub_variable, str(chosen))+ sr = _load_storage_roots()++ sr._setup_cache_env()++ import os++ assert os.environ["HF_HUB_CACHE"] == str(chosen)+ assert os.environ["HF_XET_CACHE"].startswith(str(master))+++def test_an_explicit_xet_cache_outranks_the_portable_default(monkeypatch, tmp_path):+ # Containment must not collapse into "always redirect": a named Xet cache is what was asked.+ _clear_hf_env(monkeypatch)+ monkeypatch.setenv("HOME", str(tmp_path / "home"))+ _portable_install(monkeypatch, tmp_path)+ mine = tmp_path / "bigdisk" / "xet"+ monkeypatch.setenv("HF_HUB_CACHE", str(tmp_path / "bigdisk" / "hub"))+ monkeypatch.setenv("HF_XET_CACHE", str(mine))+ sr = _load_storage_roots()++ sr._setup_cache_env()++ import os++ assert os.environ["HF_XET_CACHE"] == str(mine)+++def test_a_normal_install_leaves_the_xet_cache_in_the_host_home(monkeypatch, tmp_path):+ # Portable mode's promise alone: a normal install keeps the platform default so chunks+ # shared with plain huggingface_hub still hit.+ _clear_hf_env(monkeypatch)+ monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "xdg"))+ monkeypatch.setenv("HF_HUB_CACHE", str(tmp_path / "bigdisk" / "hub"))+ sr = _load_storage_roots()++ sr._setup_cache_env()++ import os++ assert os.environ["HF_XET_CACHE"] == str(tmp_path / "xdg" / "huggingface" / "xet")+++def test_the_libraries_really_derive_these_caches_from_hf_home(monkeypatch, tmp_path):+ # Leaving them unset is only correct if huggingface_hub and datasets derive them from+ # HF_HOME. Asked of a fresh interpreter: both snapshot their constants at import.+ pytest.importorskip("datasets")+ _clear_hf_env(monkeypatch)+ _portable_install(monkeypatch, tmp_path)+ chosen = tmp_path / "bigdisk" / "huggingface"+ monkeypatch.setenv("HF_HOME", str(chosen))+ sr = _load_storage_roots()++ sr._setup_cache_env()++ import json+ import os+ import subprocess++ probe = subprocess.run(+ [+ sys.executable,+ "-c",+ "import json, huggingface_hub.constants as c, datasets.config as d;"+ "print(json.dumps({'assets': c.HF_ASSETS_CACHE, 'hub': c.HF_HUB_CACHE,"+ "'datasets': str(d.HF_DATASETS_CACHE)}))",+ ],+ env = dict(os.environ),+ capture_output = True,+ text = True,+ check = True,+ )+ result = json.loads(probe.stdout.strip().splitlines()[-1])++ assert Path(result["assets"]) == chosen / "assets"+ assert Path(result["datasets"]) == chosen / "datasets"+ assert Path(result["hub"]) == chosen / "hub"++def test_unwritable_hf_home_does_not_crash(monkeypatch, tmp_path):# HF_HOME under a regular file -> mkdir fails; startup must not crash and the# env var is still set (HF surfaces a clear error later, at download time).diff --git a/studio/backend/utils/hf_cache_settings.py b/studio/backend/utils/hf_cache_settings.pyindex 62effd8e311..73a72e00846 100644--- a/studio/backend/utils/hf_cache_settings.py+++ b/studio/backend/utils/hf_cache_settings.py@@ -11,6 +11,8 @@ owns an explicit cache snapshot for each operation instead of trying to refreshfrom __future__ import annotationsimport os+import stat+import sysimport shutilimport tempfileimport threading@@ -91,7 +93,10 @@ def _environment_paths() -> Optional[HuggingFaceCachePaths]:default_home = _default_cache_home()hf_home = _canonical(explicit_home) if explicit_home else default_homehub = _canonical(explicit_hub) if explicit_hub else hf_home / "hub"- xet = _canonical(explicit_xet) if explicit_xet else hf_home / "xet"+ # huggingface_hub derives HF_XET_CACHE from HF_HOME, never from HF_HUB_CACHE, so a hub-only+ # override would leave the chunk and shard caches in the host home.+ xet_home = hf_home if explicit_home else (_portable_cache_home() or hf_home)+ xet = _canonical(explicit_xet) if explicit_xet else xet_home / "xet"controlling = next(keyfor key in ("HF_HUB_CACHE", "HUGGINGFACE_HUB_CACHE", "HF_HOME")@@ -108,7 +113,54 @@ def _environment_paths() -> Optional[HuggingFaceCachePaths]:return HuggingFaceCachePaths(display_home, hub, xet, "environment", controlling)+def _absence_is_real(path: Path) -> bool:+ """Whether a FileNotFoundError for *path* proves the file is not there.++ On POSIX it always does: a parent component that is a file raises NotADirectoryError, and a+ parent that cannot be traversed raises PermissionError, both of which are their own types.+ Windows collapses every one of those into ERROR_PATH_NOT_FOUND, which Python surfaces as+ FileNotFoundError, so on Windows the exception means "not there, OR somewhere above it is not+ a directory, OR I could not look" -- and the caller must only skip its read for the first.++ Decided by the nearest ancestor that can actually be stat'ed: a directory means the tree is+ real and the file genuinely is not in it; anything else means a component is a file or a+ reparse point and the path could never have existed; an ancestor that cannot be inspected at+ all is not proof either way, so it reads as "not proven". Running out of ancestors means+ nothing along the path exists, which is the machine that has never opened Studio -- the case+ the skip is FOR, so the absence is real there.+ """+ current = os.path.dirname(os.fspath(path))+ while current:+ try:+ info = os.stat(current)+ except FileNotFoundError:+ parent = os.path.dirname(current)+ if parent == current:+ return True+ current = parent+ continue+ except OSError:+ return False+ return stat.S_ISDIR(info.st_mode)+ return True++def _stored_cache_home() -> Optional[Path]:+ # get_app_setting CREATES and migrates studio.db, so an unconditional read built one on+ # machines that had never opened Studio. os.stat, not Path.exists: only a positively observed+ # absence may skip the read, and from 3.14 the predicates report EACCES and EIO as False.+ # stat, not lstat: sqlite follows symlinks.+ try:+ if "storage.studio_db" not in sys.modules:+ from utils.paths.storage_roots import studio_db_path+ database = studio_db_path()+ try:+ os.stat(database)+ except FileNotFoundError:+ if _absence_is_real(database):+ return None+ except Exception: # noqa: BLE001 - fall through to the read on any doubt+ passtry:from storage.studio_db import get_app_settingfrom utils.account_context import OWNER, run_as@@ -147,6 +199,22 @@ def configured_cache_key() -> str:return "default"+def _portable_cache_home() -> Optional[Path]:+ """The HF cache home a portable install uses, else None: a normal install keeps the platform+ default so models shared with other tools are not re-downloaded. Lazy import, since+ storage_roots reaches into this module during startup."""+ try:+ from utils.paths.storage_roots import cache_root, portable_mode+ except ImportError:+ return None+ if not portable_mode():+ return None+ try:+ return _canonical(cache_root() / "huggingface")+ except (OSError, RuntimeError, ValueError):+ return None++def get_hf_cache_paths() -> HuggingFaceCachePaths:env_paths = _environment_paths()if env_paths is not None:@@ -160,7 +228,8 @@ def get_hf_cache_paths() -> HuggingFaceCachePaths:_canonical(xet) if xet else stored / "xet","studio",)- home = _default_cache_home()+ # Ranks below env vars and Settings: portable mode is a default, not an override.+ home = _portable_cache_home() or _default_cache_home()xet = _EXPLICIT_CACHE_ENV.get("HF_XET_CACHE")return HuggingFaceCachePaths(home,diff --git a/studio/backend/utils/node_runtime.py b/studio/backend/utils/node_runtime.pyindex 6283125ce43..5cb136edf24 100644--- a/studio/backend/utils/node_runtime.py+++ b/studio/backend/utils/node_runtime.py@@ -38,12 +38,16 @@ def _version_meets_floor(version: str) -> bool:def managed_node_dir() -> Path:- """Isolated Node install dir. Mirrors ``_find_llama_server_binary``: shares a parent with llama.cpp, ``<STUDIO_HOME>`` in custom mode, else legacy ``~/.unsloth``."""+ """Isolated Node install dir. Mirrors ``_find_llama_server_binary``: shares a parent with llama.cpp, ``UNSLOTH_HOME`` when set, else ``<STUDIO_HOME>`` in custom mode, else legacy ``~/.unsloth``."""legacy_node = Path.home() / ".unsloth" / "node"try:# Lazy import (mirrors _find_llama_server_binary) so this module stays importable even if utils.paths cannot be loaded.- from utils.paths.storage_roots import studio_root+ from utils.paths.storage_roots import studio_root, unsloth_home+ # setup.sh installs Node at <master root>/node, beside studio/.+ master = unsloth_home()+ if master is not None:+ return master / "node"resolved = studio_root()legacy_studio = Path.home() / ".unsloth" / "studio"try:diff --git a/studio/backend/utils/paths/storage_roots.py b/studio/backend/utils/paths/storage_roots.pyindex 7edcb09ba1e..05ab40da79a 100644--- a/studio/backend/utils/paths/storage_roots.py+++ b/studio/backend/utils/paths/storage_roots.py@@ -3,10 +3,13 @@from __future__ import annotations+import importlib.utilimport jsonimport ntpathimport os+import platformimport re+import stat as stat_moduleimport sysimport threadingfrom pathlib import Path, PurePosixPath, PureWindowsPath@@ -53,21 +56,196 @@ def _infer_studio_home_from_venv() -> Path | None:return candidate-def studio_root() -> Path:- """Unsloth install root.+def _resolved(value: str) -> Path:+ try:+ return Path(value).expanduser().resolve()+ except (OSError, ValueError):+ return Path(value).expanduser()+- Priority: UNSLOTH_STUDIO_HOME, then STUDIO_HOME alias, then sys.prefix- inference, then legacy ~/.unsloth/studio. UNSLOTH_STUDIO_HOME wins if- both are set (specific signal beats generic alias).+MASTER_ROOT_NOTE = ".unsloth-master-root"++_recorded_master_roots: dict[str, Path | None] = {}+_recorded_master_lock = threading.Lock()+++def _studio_root_without_master() -> Path:+ """The studio root as studio_root() would give it with the master root out of the picture.++ studio_root() asks unsloth_home(), so the note reader cannot ask studio_root() back."""override = (os.environ.get("UNSLOTH_STUDIO_HOME") or "").strip()if not override:override = (os.environ.get("STUDIO_HOME") or "").strip()if override:+ return _resolved(override)+ inferred = _infer_studio_home_from_venv()+ if inferred is not None:+ return inferred+ return Path.home() / ".unsloth" / "studio"+++def _is_legacy_studio_tree(studio: Path) -> bool:+ """Whether the tree a note was read from is the ordinary `~/.unsloth/studio` install.++ A legacy-rooted install has no master root, so a note there says something no reader needs;+ both uninstallers already refuse the value it produces. Two things it broke: a one-command+ `UNSLOTH_HOME=$HOME/.unsloth` left a note that kept `portable_mode()` true for good, moving+ the one cache this module promises not to move; and a note naming any ANCESTOR of the tree+ (`$HOME` passes containment) reintroduced through the filesystem what `process.rs` scrubs+ from every managed spawn, which no `env_remove` can reach. Hence keyed on the TREE, not on+ the recorded value. An explicit UNSLOTH_HOME never gets here: unsloth_home() returns the+ override first.+ """+ try:+ return studio.resolve() == (Path.home() / ".unsloth" / "studio").resolve()+ except (OSError, RuntimeError, ValueError):+ return False+++def _recorded_master_root() -> Path | None:+ """The master root setup recorded inside the studio tree, or None.++ UNSLOTH_HOME is settable for a single command (`UNSLOTH_HOME=/mnt/portable unsloth studio+ update`) and nothing persists it, so without this every later launch resolved node, llama.cpp+ and whisper.cpp somewhere other than the siblings of studio/ setup created. setup already+ writes the root to share/.unsloth-master-root for the uninstallers.++ Honoured only while it still describes reality: the root must exist, the Studio directory the+ note was read from must lie INSIDE it, and it must not be the legacy default. Containment+ rather than an exact <root>/studio match, since the flat layout (both variables naming one+ directory) is supported; the uninstallers apply the same rule.+ """+ studio = _studio_root_without_master()+ key = str(studio)+ with _recorded_master_lock:+ if key in _recorded_master_roots:+ return _recorded_master_roots[key]+ found: Path | None = None+ # A miss is cached; a failure to LOOK is not. EACCES on share/ or EIO off a mount that came+ # back is a fact about one instant, and cached it pinned the backend to the legacy runtime+ # paths for its whole lifetime, with forget_recorded_master_root() the only way out and+ # nothing calling it in production.+ definitive = True+ try:+ recorded = (studio / "share" / MASTER_ROOT_NOTE).read_text(encoding = "utf-8").strip()+ except (FileNotFoundError, NotADirectoryError, ValueError, UnicodeDecodeError):+ recorded = ""+ except OSError:+ recorded = ""+ definitive = False+ if recorded:+ master = _resolved(recorded)try:- return Path(override).expanduser().resolve()+ here = studio.resolve()+ if (+ master.is_dir()+ and (here == master or master in here.parents)+ and not _is_legacy_studio_tree(studio)+ ):+ found = masterexcept (OSError, ValueError):- return Path(override).expanduser()+ found = None+ if definitive:+ with _recorded_master_lock:+ _recorded_master_roots[key] = found+ return found+++def forget_recorded_master_root() -> None:+ """Drop the cached note reading. For tests, and for an installer that writes the note into+ a tree this process has already looked at."""+ with _recorded_master_lock:+ _recorded_master_roots.clear()+++def unsloth_home() -> Path | None:+ """The master root, or None. STUDIO_HOME is its studio/ child; llama.cpp, node and+ whisper.cpp are SIBLINGS of studio/, the layout setup.sh already gives UNSLOTH_HOME."""+ override = (os.environ.get("UNSLOTH_HOME") or "").strip()+ if override:+ return _resolved(override)+ return _recorded_master_root()+++_PORTABLE_ON_VALUES = ("1", "true", "yes", "on")+_PORTABLE_OFF_VALUES = ("0", "false", "off", "no")++# portable_mode() runs on every cache-var lookup, so warn once per process, not once per call.+_warned_unrecognized_portable = False+++def _warn_unrecognized_portable(raw: str) -> None:+ global _warned_unrecognized_portable+ if _warned_unrecognized_portable:+ return+ _warned_unrecognized_portable = True+ # Not "to leave it off": an off value declines to turn portable mode on by itself, it does+ # not veto the master root that carries it.+ logger.warning(+ "Ignoring UNSLOTH_PORTABLE=%r: expected one of %s to turn portable mode on, or one of "+ "%s to leave that choice to UNSLOTH_HOME, which turns it on when it names a master root.",+ raw,+ "/".join(_PORTABLE_ON_VALUES),+ "/".join(_PORTABLE_OFF_VALUES),+ )+++def portable_mode() -> bool:+ """Whether this install keeps everything under one directory. Implied by UNSLOTH_HOME, and+ settable on its own so an existing install can opt in."""+ # Case-folded: UNSLOTH_PORTABLE=FALSE read as "on" moves the caches out from under a user+ # who asked for the opposite.+ raw = (os.environ.get("UNSLOTH_PORTABLE") or "").strip()+ value = raw.lower()+ if value in _PORTABLE_ON_VALUES:+ return True+ if value and value not in _PORTABLE_OFF_VALUES:+ _warn_unrecognized_portable(raw)+ # Unrecognized means no opinion, as an off value does: neither vetoes a real master root.+ return unsloth_home() is not None+++# Warned once per distinct pair rather than per call: studio_root() runs many times a request,+# and both variables can be rebound inside one process.+_warned_root_conflicts: set[tuple[str, str]] = set()+++def _warn_root_conflict(resolved: Path, master: Path) -> None:+ key = (str(resolved), str(master))+ if key in _warned_root_conflicts:+ return+ _warned_root_conflicts.add(key)+ # Not fatal: failing here would break a resolver called at import time.+ logger.warning(+ "UNSLOTH_STUDIO_HOME (%s) is outside UNSLOTH_HOME (%s); this "+ "install is not self-contained.",+ resolved,+ master,+ )+++def studio_root() -> Path:+ """Unsloth install root.++ Priority: UNSLOTH_STUDIO_HOME, then STUDIO_HOME alias, then UNSLOTH_HOME's studio/ child, then+ sys.prefix inference, then legacy ~/.unsloth/studio. UNSLOTH_STUDIO_HOME outranks both: it+ names this exact directory, while the others only name the tree it sits in.+ """+ override = (os.environ.get("UNSLOTH_STUDIO_HOME") or "").strip()+ if not override:+ override = (os.environ.get("STUDIO_HOME") or "").strip()+ if override:+ resolved = _resolved(override)+ master = unsloth_home()+ # Path.parents excludes the path itself, so a flat layout (both naming one root) would+ # otherwise warn on every call.+ if master is not None and master != resolved and master not in resolved.parents:+ _warn_root_conflict(resolved, master)+ return resolved+ master = unsloth_home()+ if master is not None:+ return master / "studio"inferred = _infer_studio_home_from_venv()if inferred is not None:return inferred@@ -510,6 +688,367 @@ def well_known_model_dirs() -> list[Path]:return _existing_dirs(candidates, resolve = True)+def _user_set_hf_home() -> bool:+ """Whether HF_HOME was set by the user rather than seeded by Unsloth.++ initialize_hf_cache_environment fills a blank HF_HOME first, so the import-time snapshot is+ the only record of who chose it.+ """+ try:+ from utils.hf_cache_settings import _EXPLICIT_CACHE_ENV+ except ImportError:+ return False+ return bool(_EXPLICIT_CACHE_ENV.get("HF_HOME"))+++def _portable_cache_defaults(root: Path) -> dict[str, str]:+ """Cache vars that only move under the root in portable mode, since they hold shared user data+ or large re-downloads. The hub and xet caches are handled inside hf_cache_settings, which must+ agree with the Settings UI. HF_HOME never moves: credentials should not follow a cache onto a+ removable volume.+ """+ if not portable_mode():+ return {}+ if _user_set_hf_home():+ # Assets, datasets and modules derive from an explicit HF_HOME: pinning them splits one+ # deliberately chosen cache across two volumes.+ return {"TORCH_HOME": str(root / "torch")}+ return {+ "HF_DATASETS_CACHE": str(root / "huggingface" / "datasets"),+ "HF_ASSETS_CACHE": str(root / "huggingface" / "assets"),+ # transformers.utils.hub reads this at import and appends it to sys.path, so a+ # trust_remote_code load leaves generated modules on the host without it.+ "HF_MODULES_CACHE": str(root / "huggingface" / "modules"),+ "TORCH_HOME": str(root / "torch"),+ }+++def _triton_cache_defaults(root: Path) -> dict[str, str]:+ """Triton's regenerable directories, named one at a time.++ Not TRITON_HOME (triton-lang/triton#4265): it would take ~/.triton/override with it, and a+ TRITON_KERNEL_OVERRIDE=1 run would silently fall back to the compiler's own output. The+ dedicated variables outrank the derivation (triton/knobs.py cache_knobs).+ """+ if (os.environ.get("TRITON_HOME") or "").strip():+ # Whoever moved the whole tree meant the cache with it; TRITON_CACHE_DIR would outrank it.+ return {}+ return {+ "TRITON_CACHE_DIR": str(root / "triton"),+ # A sibling, not a child: dumps are asked for by hand and should outlive a cache wipe.+ "TRITON_DUMP_DIR": str(root / "triton-dump"),+ }+++def _nothing_at(path: Path, *, ending: str = "") -> bool:+ """Whether *path* positively holds nothing, the only state that licenses a pin.++ Not Path.exists/is_dir/glob: they report ENOTDIR, ELOOP, EBADF (and from 3.14 EACCES and EIO)+ as absence, so a directory we merely cannot inspect would read as empty and the redirect would+ hide the user's files. os.lstat and os.scandir raise on all of it. lstat rather than stat: a+ dangling symlink is still something the user put there. *ending* asks instead whether the+ DIRECTORY holds no entry with that suffix; pass it lowercase, as Windows glob matched+ case-insensitively.+ """+ try:+ if not ending:+ os.lstat(path)+ return False+ # lstat, not scandir, at the directory itself: scandir follows a link, so an empty or+ # unmounted target would read as an empty directory and hide what is placed there.+ if stat_module.S_ISLNK(os.lstat(path).st_mode) or _is_reparse_point(path):+ return False+ with os.scandir(path) as entries:+ return not any(entry.name.lower().endswith(ending) for entry in entries)+ except FileNotFoundError:+ # Not absence on its own: Windows collapses NotADirectoryError and PermissionError into+ # ERROR_PATH_NOT_FOUND, so with a FILE where ~/.matplotlib belongs POSIX declined the pin+ # and Windows took it.+ return _nothing_above(path)+ except (OSError, ValueError):+ # Could not look. Declining a pin costs a shared cache directory; taking one wrongly+ # hides the configuration or datasets underneath it.+ return False+++def _nothing_above(path: Path) -> bool:+ """Whether a FileNotFoundError for *path* really means nothing is there.++ Decided by the nearest ancestor that can be stat'ed: a directory means real absence, anything+ else means a component is a file or a reparse point, and an ancestor that cannot be inspected+ is proof of neither. Same rule as hf_cache_settings._absence_is_real.+ """+ current = os.path.dirname(os.fspath(path))+ while current:+ try:+ info = os.stat(current)+ except FileNotFoundError:+ parent = os.path.dirname(current)+ if parent == current:+ return True+ current = parent+ continue+ except OSError:+ return False+ return stat_module.S_ISDIR(info.st_mode)+ return True+++def _matplotlib_config_dir() -> Path | None:+ """Where matplotlib reads matplotlibrc and stylelib/ from when MPLCONFIGDIR is unset, or None+ when this machine has no such directory. Mirrors _get_config_or_cache_dir: XDG config base on+ Linux/FreeBSD, %LOCALAPPDATA% on Windows but keeping a pre-existing ~/.matplotlib there.++ None means matplotlib falls back to a temporary directory, so a pin can strand nothing. The+ Windows branch is matplotlib 3.11's and the pinned 3.10.9 uses ~/.matplotlib; that+ disagreement only ever costs us the pin, it never hides a file matplotlib reads.+ """+ # XDG_CONFIG_HOME ahead of Path.home(), as _get_xdg_config_dir does: an install that sets it+ # has a config dir even with no resolvable home.+ if sys.platform.startswith(("linux", "freebsd")):+ base = (os.environ.get("XDG_CONFIG_HOME") or "").strip()+ if base:+ return Path(base) / "matplotlib"+ try:+ home = Path.home()+ except (OSError, RuntimeError):+ return None+ if sys.platform.startswith(("linux", "freebsd")):+ return home / ".config" / "matplotlib"+ if sys.platform == "win32":+ legacy = home / ".matplotlib"+ # Not is_dir(): an unreadable ~/.matplotlib raises before 3.14 and reads as absent from+ # 3.14, which sends the probe to a %LOCALAPPDATA% that is empty on exactly the machines+ # where the old directory holds the rc.+ if not _nothing_at(legacy):+ return legacy+ local_app_data = (os.environ.get("LOCALAPPDATA") or "").strip()+ return Path(local_app_data) / "matplotlib" if local_app_data else legacy+ return home / ".matplotlib"+++def _matplotlib_defaults(root: Path) -> dict[str, str]:+ """MPLCONFIGDIR, unless matplotlib's own directory holds user configuration.++ The one variable moves the CONFIG directory as well as the cache, so pinning it would drop a+ user matplotlibrc and every custom style, silently changing the loss plots+ core/training/training.py draws. matplotlib creates the directory on import, so contents+ decide, not existence.+ """+ managed = root / "matplotlib"+ pinned = {"MPLCONFIGDIR": str(managed)}+ # Our own configuration first: the legacy probe re-runs every launch, so on its own a+ # ~/.config/matplotlib created later by another tool takes over a matplotlibrc written HERE,+ # and the plot style flips back and forth across launches.+ if not (+ _nothing_at(managed / "matplotlibrc")+ and _nothing_at(managed / "stylelib", ending = ".mplstyle")+ ):+ return pinned+ config_dir = _matplotlib_config_dir()+ if config_dir is not None and not (+ _nothing_at(config_dir / "matplotlibrc")+ and _nothing_at(config_dir / "stylelib", ending = ".mplstyle")+ ):+ return {}+ return pinned+++def _is_reparse_point(path: Path) -> bool:+ """A Windows junction, which is_symlink() answers False for.++ os.path.isjunction arrived in 3.12 and the Studio venv can be 3.11, so its absence means+ "no junctions to worry about" rather than an error.+ """+ isjunction = getattr(os.path, "isjunction", None)+ if isjunction is None:+ return False+ try:+ return bool(isjunction(path))+ except (OSError, ValueError):+ return False+++def _data_designer_in_use(home: Path) -> bool:+ """Whether the managed Data Designer home holds work worth keeping.++ _setup_cache_env creates this directory and its managed-assets child on the first launch, so+ existence alone would pin a home nobody has written to. A home we cannot list counts as in+ use: dropping the pin would hide the recipes here behind a re-seeded ~/.data-designer.+ """+ try:+ entries = list(home.iterdir())+ except FileNotFoundError:+ return False+ except (OSError, ValueError):+ return True+ for entry in entries:+ try:+ if entry.name != "managed-assets":+ return True+ # A link here is the user redirecting their assets, which is state; is_dir() follows+ # it, so an empty target read as the untouched layout and took the redirect with it.+ if entry.is_symlink() or _is_reparse_point(entry):+ return True+ if not entry.is_dir():+ return True+ if any(entry.iterdir()):+ return True+ except FileNotFoundError:+ continue+ except (OSError, ValueError):+ return True+ return False+++def _data_designer_defaults(root: Path) -> dict[str, str]:+ """Data Designer's home, unless the user already has one.++ Not a cache: repointing an existing ~/.data-designer hides its yaml configs and multi-GB+ parquet behind a re-seeded default. MANAGED_ASSETS_PATH derives from the home, so it is only+ ours to set when the home is. data_designer.config.utils.constants reads both at IMPORT time.+ """+ if (os.environ.get("DATA_DESIGNER_HOME") or "").strip():+ return {}+ home = root.parent / "data-designer"+ pinned = {+ "DATA_DESIGNER_HOME": str(home),+ "DATA_DESIGNER_MANAGED_ASSETS_PATH": str(home / "managed-assets"),+ }+ # Our own populated home first: the legacy probe re-runs every launch, so a ~/.data-designer+ # created later by a standalone run would otherwise take over the recipes written here.+ if _data_designer_in_use(home):+ return pinned+ try:+ legacy = Path.home() / ".data-designer"+ except (OSError, RuntimeError):+ # No home, so the pin can hide nothing: data_designer's default is off the same call.+ return pinned+ return pinned if _nothing_at(legacy) else {}+++def _path_safe(value: str) -> str:+ """A directory-name-safe rendering of a build field."""+ return re.sub(r"[^A-Za-z0-9.]+", "-", value)+++def _torch_version_fields() -> dict[str, str]:+ """The build identity torch.version exposes, read without importing torch.++ Runs on a startup path that executes before torch exists in a fresh venv, so it stays a file+ read. torch/version.py assigns only literals, but whether it annotates them+ (``cuda: Optional[str] = ...``) varies by release, hence a regex rather than ast or exec.+ """+ origin = getattr(importlib.util.find_spec("torch"), "origin", None)+ if not origin:+ return {}+ text = (Path(origin).parent / "version.py").read_text(encoding = "utf-8")+ found = re.findall(+ r"""^(__version__|debug|cuda|hip|xpu)\s*(?::[^=\n]+)?=\s*([^\s#]+)""",+ text,+ re.MULTILINE,+ )+ return {name: value.strip("'\"") for name, value in found}+++def _torch_accelerator_tag(fields: dict[str, str]) -> str:+ """torch's own cu_str, widened to the runtimes it declines to name: cpp_extension picks 'cpu'+ whenever version.cuda is unset, filing a ROCm build beside a real CPU one. hip first, as+ torch main prioritises ROCm."""+ for field, prefix in (("hip", "rocm"), ("cuda", "cu"), ("xpu", "xpu")):+ value = fields.get(field)+ if not value or value == "None":+ continue+ # torch spells the CUDA version without dots: 12.8 -> cu128.+ return prefix + _path_safe(value.replace(".", "") if field == "cuda" else value)+ return "cpu"+++def _torch_runtime_tag() -> str:+ """Name the extension cache after the runtime that builds into it.++ torch.utils.cpp_extension._get_build_directory appends a ``py<ver>_<accelerator>`` folder to+ the DEFAULT root only, never to a TORCH_EXTENSIONS_DIR we supply, so pinning a flat path drops+ the isolation that keeps a py313/cu128 build from being loaded by a py312/cu126 one. The+ accelerator comes from the generated cuda/hip fields, not from a local version segment:+ conda-forge's CPU and CUDA packages of one release share a __version__. __version__ stays in+ the tag anyway, since segments like +cpu.cxx11.abi mark ABI splits no other field records.+ """+ tag = f"py{sys.version_info.major}{sys.version_info.minor}{getattr(sys, 'abiflags', '')}"+ # Architecture too, which torch's py<ver>_<cu_str> omits: an arm64 and a Rosetta x86_64+ # python agree on every other field, so ninja reads the other's build as up to date.+ tag += "_" + _path_safe(f"{sys.platform}-{platform.machine() or 'unknown'}")+ try:+ fields = _torch_version_fields()+ except (ImportError, OSError, ValueError, AttributeError):+ # No torch yet, or a half-built tree; the interpreter tag alone still isolates.+ return tag+ if not fields:+ return tag+ tag += "_" + _torch_accelerator_tag(fields)+ version = fields.get("__version__")+ if version:+ tag += "_" + _path_safe(version)+ if fields.get("debug") == "True":+ # A debug build keeps the soname of a release one but not its ABI.+ tag += "_debug"+ return tag+++# Caches whose path is pasted into a compiler command line, unquoted, by somebody else's code:+# torch/_inductor/cpp_builder.py joins the g++ invocation with spaces and reparses it with+# shlex.split, so a root containing a space splits in two and the build fails outright+# ("g++: fatal error: input file .../my is the same as output file"). The quoting is PyTorch's+# to fix; skipping the pin just returns to the temporary directory Inductor used before. Not a+# rare shape: "C:\Users\First Last" is an ordinary Windows account name.+_TOOLCHAIN_PATH_KEYS = frozenset(+ {+ "TORCHINDUCTOR_CACHE_DIR",+ "TORCH_EXTENSIONS_DIR",+ "TRITON_CACHE_DIR",+ "TRITON_DUMP_DIR",+ "TRITON_HOME",+ "CUDA_CACHE_PATH",+ }+)+++def _usable_dir(value: str) -> bool:+ """Whether a path we generated is actually a directory the toolchain can compile into.++ A real create, not is_dir() alone. torch falls back to its own temporary directory only when+ the variable is UNSET, then calls os.makedirs(exist_ok = True), which succeeds on an existing+ read-only directory and leaves every later write to fail+ (torch/_inductor/runtime/cache_dir_utils.py), so publishing an unwritable path is worse than+ publishing none. Same rule install.sh states for the uv cache probe.+ """+ try:+ if not Path(value).is_dir():+ return False+ except (OSError, ValueError):+ return False+ try:+ handle, probe = tempfile.mkstemp(dir = value, prefix = ".unsloth-write-probe.")+ except (OSError, ValueError):+ return False+ # Guarded like the unlink below: an EIO or ENOSPC on close escaping here would take the+ # whole backend start with it, for a probe whose job is to answer yes or no.+ try:+ os.close(handle)+ except OSError:+ return False+ try:+ os.unlink(probe)+ except OSError:+ pass+ return True+++def _toolchain_unsafe(key: str, value: str) -> bool:+ """Whether pinning *key* to *value* would hand a compiler a path it cannot parse."""+ return key in _TOOLCHAIN_PATH_KEYS and any(ch.isspace() for ch in value)++def _setup_cache_env() -> None:"""Set cache env vars for HuggingFace, uv, and vLLM.@@ -529,11 +1068,37 @@ def _setup_cache_env() -> None:# cache landed in the user home. Must be set before unsloth_zoo.compiler imports: it reads the value at import# time and puts it on sys.path."UNSLOTH_COMPILE_LOCATION": str(root.parent / "compiled_cache"),+ # Regenerable and process-scoped. Shared user data (HF hub cache, torch.hub checkpoints)+ # stays where the other tools look, except in portable mode.+ "TORCHINDUCTOR_CACHE_DIR": str(root / "torchinductor"),+ # Tagged: torch only inserts its own ABI folder when TORCH_EXTENSIONS_DIR is unset, so a+ # flat pin would let two runtimes sharing this root import each other's .so.+ "TORCH_EXTENSIONS_DIR": str(root / "torch-extensions" / _torch_runtime_tag()),+ # NVIDIA's JIT compile cache; ~/.nv/ComputeCache otherwise.+ "CUDA_CACHE_PATH": str(root / "cuda"),+ "NUMBA_CACHE_DIR": str(root / "numba"),}+ defaults.update(_matplotlib_defaults(root))+ defaults.update(_triton_cache_defaults(root))+ defaults.update(_data_designer_defaults(root))+ defaults.update(_portable_cache_defaults(root))for key, value in defaults.items():# Blank counts as unset: an inherited KEY= would otherwise pin the cache to "", which puts an empty entry on# sys.path and sends the compiler to the system temp directory instead.if not (os.environ.get(key) or "").strip():+ # An explicit value is still honoured above: the caller chose it, and only a default+ # we invented is ours to withhold.+ if _toolchain_unsafe(key, value):+ logger.debug(+ "leaving %s unset: %s contains whitespace, which the C++ builders "+ "paste into a command line unquoted",+ key,+ value,+ )+ # Popped, not blanked: Inductor reads " " as a relative path and hands it to+ # the very command line being refused here.+ os.environ.pop(key, None)+ continueos.environ[key] = value# Best-effort: a non-writable custom HF_HOME must not crash startuptry:@@ -550,6 +1115,14 @@ def _setup_cache_env() -> None:(Path(value) / CACHE_MARKER).touch(exist_ok = True)except (OSError, ImportError):pass+ # A toolchain path we invented and could not make is worse than none: torch treats+ # it as authoritative and every compile fails, where unset would have used the+ # library's temporary cache. Only these keys -- UNSLOTH_COMPILE_LOCATION unset falls+ # back to a CWD-relative name, the bug that pin exists to fix, and the data roots+ # have no library default to fall back to.+ if key in _TOOLCHAIN_PATH_KEYS and not _usable_dir(value):+ logger.debug("leaving %s unset: %s is not a usable directory", key, value)+ os.environ.pop(key, None)def setup_cache_env() -> None:diff --git a/studio/setup.ps1 b/studio/setup.ps1index 99044e7deba..73cde3c11ce 100644--- a/studio/setup.ps1+++ b/studio/setup.ps1@@ -763,13 +763,32 @@ function Test-UnslothCmdShimFile {return ($text -like "*unsloth-studio-managed-launcher*" -and $text -like "*from unsloth_cli import app*")}-# Explicit staging root, shared default cache, or the custom Unsloth home's tree.+# The master root storage_roots.unsloth_home() reads. llama.cpp, node and whisper.cpp sit+# BESIDE studio\ under it, so deriving them from $StudioHome would put them one level below+# where every runtime resolver looks.+function Get-MasterRootOverride {+ if ([string]::IsNullOrWhiteSpace($env:UNSLOTH_HOME)) { return $null }+ $value = $env:UNSLOTH_HOME.Trim()+ if ($value -eq "~") {+ $value = $env:USERPROFILE+ } elseif ($value -like "~/*" -or $value -like "~\*") {+ $value = (Join-Path $env:USERPROFILE $value.Substring(1).TrimStart('/', '\'))+ }+ return (Get-CanonicalDir -Path $value)+}++# Explicit staging root, the master root, the shared default cache, or the custom Unsloth+# home's tree.function Get-ManagedLlamaCppDir {param([AllowNull()][string]$StagingRoot = $null)if ($StagingRoot) {return (Join-Path $StagingRoot "llama.cpp")}+ $masterRoot = Get-MasterRootOverride+ if ($masterRoot) {+ return (Join-Path $masterRoot "llama.cpp")+ }if (-not (Test-StudioHomeIsCustom)) {return (Join-Path $env:USERPROFILE ".unsloth\llama.cpp")}@@ -785,8 +804,9 @@ function Invoke-ManagedLlamaCppPreflight {$dir = Get-ManagedLlamaCppDir -StagingRoot $StagingRootif ((Get-LlamaCppInstallReadState -Path $dir) -ne "Denied") { return $null }Write-StudioLine ""- # A denied custom home cannot be claimed as an Unsloth-managed cache.- $homeIsCustom = Test-StudioHomeIsCustom+ # A denied custom home cannot be claimed as an Unsloth-managed cache. Computed rather+ # than read off $RuntimeRootIsCustom: this runs beside the line that defines it.+ $homeIsCustom = (Test-StudioHomeIsCustom) -or [bool](Get-MasterRootOverride)# Preserve user-supplied wording when either override names this tree, or# names a build inside it: moving or deleting this folder takes that build# with it, and the later --with-llama-cpp-dir check then aborts on a path@@ -2792,9 +2812,170 @@ $StudioStaleMarker = ".unsloth-studio-stale"$NoTorchMarker = ".unsloth-no-torch"$LegacyStudioHome = Join-Path $env:USERPROFILE ".unsloth\studio"$StudioHomeIsCustom = Test-StudioHomeIsCustom+# Ownership applies to node\, llama.cpp\ and whisper.cpp\ whenever a master root moves them,+# even with $StudioHome left at the legacy path: $StudioHomeIsCustom is false there, and false+# is what licenses the installers to replace and delete without the Unsloth-owned marker. The+# Studio home itself, and the venvs under it, keep the other flag. Mirrors setup.sh.+$RuntimeRootIsCustom = $StudioHomeIsCustom+# Keyed on where the runtimes LAND, not on whether a master root was named: UNSLOTH_HOME set to+# the root an install already uses moves nothing, and calling that custom would demand an owner+# marker from a legacy source-built .unsloth\llama.cpp that predates markers. The comparison+# setup.sh makes; taking any non-empty master root instead was a real divergence.+#+# Staging is excluded for the same reason, not as an exception to it: Get-ManagedLlamaCppDir+# gives $StageRoot precedence over the master root, so during a staged update the master root is+# not where anything lands. ASSIGNED, not merely raised, or a custom Studio home whose runtimes+# land in the legacy root keeps the flag true and demands markers from exactly the pre-marker+# tree this comparison exists to spare.+$_masterRootForOwnership = Get-MasterRootOverride+if ($_masterRootForOwnership -and -not $StageRoot) {+ # Canonicalised the same way Get-MasterRootOverride canonicalises its answer, or a+ # junctioned profile compares unequal to itself. Case-insensitively, since two Windows+ # paths differing only in case are one directory.+ $_legacyRuntimeRoot = Get-CanonicalDir -Path (Join-Path $env:USERPROFILE ".unsloth")+ $RuntimeRootIsCustom = ($_masterRootForOwnership -ine $_legacyRuntimeRoot)+}$LlamaCppDir = Get-ManagedLlamaCppDir -StagingRoot $StageRoot$UnslothHome = Split-Path -Parent $LlamaCppDir+# Record the master root inside the Studio tree, for the uninstaller: UNSLOTH_HOME can be set+# for a single command, and without the note a later uninstall removed the Studio tree and+# stranded multi-gigabyte runtimes beside it.+#+# Only for a master root (the other branches derive the root from paths the uninstaller already+# knows), and only when a reader will honour it. setup.sh's _master_root_note_is_honoured holds+# the same two rules for the same reasons; keep them together.+function Test-MasterRootNoteIsHonoured {+ param([string]$Root, [string]$StudioRoot)+ $norm = Get-CanonicalDir -Path $Root+ if (-not $norm) { return $false }+ $here = Get-CanonicalDir -Path $StudioRoot+ if (-not $here) { return $false }+ # The legacy default is the one root every reader finds without help, and both uninstallers+ # refuse it outright. Recording it turned a one-command UNSLOTH_HOME=%USERPROFILE%\.unsloth+ # into a permanent portable install: every later bare launch read it back and HF_HUB_CACHE+ # moved off the shared Hugging Face cache this change promises not to move.+ $legacy = Get-CanonicalDir -Path (Join-Path $env:USERPROFILE ".unsloth")+ if ($legacy -and ($norm -ieq $legacy)) { return $false }+ # Keyed on the TREE as well, because that is what the readers key on: storage_roots'+ # _is_legacy_studio_tree and the CLI both decline ANY note found in the legacy Studio tree,+ # whatever it records. Without this, UNSLOTH_HOME=%USERPROFILE% passed containment (the+ # legacy tree is inside the profile) and is not the legacy root, so the note was written,+ # warned about nothing, and was then honoured by nobody.+ $legacyStudio = Get-CanonicalDir -Path (Join-Path $env:USERPROFILE ".unsloth\studio")+ if ($legacyStudio -and ($here -ieq $legacyStudio)) {+ Write-StudioLine " note: the managed runtimes were installed under $norm, but Studio is the" -ForegroundColor Yellow+ Write-StudioLine " default install at $here, where no reader honours a recorded root." -ForegroundColor Yellow+ Write-StudioLine " That root cannot be recorded, so a later launch or uninstall will" -ForegroundColor Yellow+ Write-StudioLine " not find them. Set UNSLOTH_STUDIO_HOME to $norm\studio, or re-set" -ForegroundColor Yellow+ Write-StudioLine " UNSLOTH_HOME whenever you run Unsloth." -ForegroundColor Yellow+ return $false+ }+ # A note must describe the tree it is written into: every reader requires the Studio+ # directory to lie INSIDE the root it names, so a tree copied between master roots cannot aim+ # a removal at the original install. install.ps1 does not read UNSLOTH_HOME yet, so a master+ # root on an ordinary install leaves Studio at the legacy path with the runtimes elsewhere,+ # which is that shape: say so, rather than leave a file that behaves as no note at all.+ $sep = [System.IO.Path]::DirectorySeparatorChar+ if (($here -ieq $norm) -or $here.StartsWith($norm + $sep, [System.StringComparison]::OrdinalIgnoreCase)) {+ return $true+ }+ Write-StudioLine " note: the managed runtimes were installed under $norm, but Studio lives at" -ForegroundColor Yellow+ Write-StudioLine " $here, which is outside it. That root cannot be recorded, so a later" -ForegroundColor Yellow+ Write-StudioLine " launch or uninstall will not find them. Set UNSLOTH_STUDIO_HOME to" -ForegroundColor Yellow+ Write-StudioLine " $norm\studio, or re-set UNSLOTH_HOME whenever you run Unsloth." -ForegroundColor Yellow+ return $false+}+if ((Get-MasterRootOverride) -and -not $StageRoot -and+ (Test-MasterRootNoteIsHonoured -Root $UnslothHome -StudioRoot $StudioHome)) {+ try {+ $noteDir = Join-Path $StudioHome "share"+ if (-not (Test-Path -LiteralPath $noteDir -PathType Container)) {+ [void][System.IO.Directory]::CreateDirectory($noteDir)+ }+ # Staged then renamed: a reader that caught a half-written note would name a truncated+ # path, and this note licenses deletions.+ $notePath = Join-Path $noteDir ".unsloth-master-root"+ $noteBytes = [System.Text.Encoding]::UTF8.GetBytes($UnslothHome + [Environment]::NewLine)+ # Nothing to do when the note already says this, which is every run after the first.+ # Move-Item -Force is NOT an atomic replace: the provider deletes the destination then+ # moves the source, so an interruption leaves NO note and a backend that looks next+ # caches "no master root". Re-entering that window to rewrite identical bytes is the+ # avoidable half.+ $noteCurrent = $null+ try {+ if (Test-Path -LiteralPath $notePath -PathType Leaf) {+ $noteCurrent = [System.IO.File]::ReadAllBytes($notePath)+ }+ } catch { $noteCurrent = $null }+ $noteSame = $false+ if ($null -ne $noteCurrent -and $noteCurrent.Length -eq $noteBytes.Length) {+ $noteSame = $true+ for ($i = 0; $i -lt $noteBytes.Length; $i++) {+ if ($noteCurrent[$i] -ne $noteBytes[$i]) { $noteSame = $false; break }+ }+ }+ if (-not $noteSame) {+ # An unpredictable name opened CreateNew, not "$notePath.$PID" through WriteAllText:+ # the predictable pair lets anyone who can write share/ precreate that name as a link+ # and have this write land on its target. Move-Item -Force replaces a link at the+ # final path rather than following it.+ $noteTmp = Join-Path $noteDir (".unsloth-master-root." + [System.IO.Path]::GetRandomFileName())+ try {+ $noteStream = [System.IO.File]::Open(+ $noteTmp,+ [System.IO.FileMode]::CreateNew,+ [System.IO.FileAccess]::Write,+ [System.IO.FileShare]::None+ )+ try {+ $noteStream.Write($noteBytes, 0, $noteBytes.Length)+ } finally {+ $noteStream.Dispose()+ }+ # Move-Item -Force, not [IO.File]::Move with an overwrite flag: that overload is+ # .NET Core only and setup.ps1 still runs under Windows PowerShell 5.1.+ Move-Item -LiteralPath $noteTmp -Destination $notePath -Force+ $noteTmp = $null+ } finally {+ # The staging file is unreadable to every reader but still occupies share/, and+ # nothing else ever removes it. Cleared whether the move threw or not.+ if ($noteTmp) { Remove-Item -LiteralPath $noteTmp -Force -ErrorAction SilentlyContinue }+ }+ }+ } catch {+ Write-StudioLine " note: could not record the master root for uninstall: $($_.Exception.Message)" -ForegroundColor DarkGray+ }+}++# Clear a note an earlier run left naming the legacy default root, whatever this run was asked+# to do: the gate above stops new ones, but an install that already has one keeps reading it+# back and no later update would reach the write block to correct it. Narrow on purpose -- both+# uninstallers already refuse this value, so removing it takes nothing a reader could act on.+try {+ $staleNote = Join-Path (Join-Path $StudioHome "share") ".unsloth-master-root"+ if (Test-Path -LiteralPath $staleNote -PathType Leaf) {+ # -Encoding UTF8: the writer emits BOM-less UTF-8 and Windows PowerShell 5.1 decodes+ # BOM-less input with the ANSI code page, so a root holding non-ASCII read back+ # mangled and never matched the value this sweep exists to clear.+ $staleValue = (Get-Content -LiteralPath $staleNote -TotalCount 1 -Encoding UTF8 -ErrorAction Stop)+ if ($staleValue) { $staleValue = $staleValue.Trim() }+ if ($staleValue) {+ if ($staleValue -eq "~") { $staleValue = $env:USERPROFILE }+ elseif ($staleValue -like "~/*" -or $staleValue -like "~\*") {+ $staleValue = (Join-Path $env:USERPROFILE $staleValue.Substring(1).TrimStart('/', '\'))+ }+ $staleNorm = Get-CanonicalDir -Path $staleValue+ $legacyNorm = Get-CanonicalDir -Path (Join-Path $env:USERPROFILE ".unsloth")+ if ($staleNorm -and $legacyNorm -and ($staleNorm -ieq $legacyNorm)) {+ Remove-Item -LiteralPath $staleNote -Force -ErrorAction SilentlyContinue+ }+ }+ }+} catch {+ # A note this run cannot read is one it has no business deleting.+}+$WithLlamaCppDir = $null$llamaPreflightFailure = Invoke-ManagedLlamaCppPreflight -StagingRoot $StageRootif ($llamaPreflightFailure) {@@ -4434,8 +4615,12 @@ $NodeSource = $nullif (-not $IsPipInstall) {# Put Node beside the Unsloth root. OXC can still need npm when the# frontend build is skipped.+ $_masterRoot = Get-MasterRootOverrideif ($StageRoot) {$NodeParent = $StageRoot+ } elseif ($_masterRoot) {+ # Same derivation as Get-ManagedLlamaCppDir: beside studio\, not inside it.+ $NodeParent = $_masterRoot} else {if (-not [string]::IsNullOrWhiteSpace($env:UNSLOTH_STUDIO_HOME)) { $NodeOverride = $env:UNSLOTH_STUDIO_HOME.Trim() }elseif (-not [string]::IsNullOrWhiteSpace($env:STUDIO_HOME)) { $NodeOverride = $env:STUDIO_HOME.Trim() }@@ -4701,11 +4886,34 @@ if ($NeedNodeForSetup) {} elseif ($NodeSource -eq "bundled") {New-Item -ItemType Directory -Force -Path $NodeParent -ErrorAction SilentlyContinue | Out-Null# Minimal ownership guard; never os.replace over a user-owned dir.- if ($NodeOverride -and (Test-Path -LiteralPath $NodeDir -PathType Container)) {+ # $RuntimeRootIsCustom as well as $NodeOverride: the master-root branch above leaves+ # $NodeOverride null, so <master>\node reached install_node_prebuilt.py's whole-directory+ # replacement with none of the ownership evidence a custom UNSLOTH_STUDIO_HOME requires,+ # and the master root is the user's directory too. Or, not replacing: a custom Studio+ # home keeps the guard it had.+ #+ # Anything at the path counts as occupied, not just a directory: _swap_into_place renames+ # whatever it finds out of the way, so a file or symlink named `node` was displaced by a+ # guard that only asked about containers. Ownership evidence lives inside a directory, so+ # a non-directory can never carry it and is refused outright.+ # Get-Item -Force, not Test-Path: under Windows PowerShell 5.1 Test-Path reports whether+ # the TARGET resolves, so a dangling link named `node` reads as absent and+ # install_node_prebuilt.py installs through it.+ $nodeEntry = if ($NodeOverride -or $RuntimeRootIsCustom) {+ Get-Item -LiteralPath $NodeDir -Force -ErrorAction SilentlyContinue+ } else { $null }+ if ($nodeEntry) {$nodeOwnedMarker = Join-Path $NodeDir ".unsloth-studio-owned"$nodeMeta = Join-Path $NodeDir "UNSLOTH_NODE_PREBUILT_INFO.json"- if (-not (Test-Path -LiteralPath $nodeOwnedMarker) -and -not (Test-Path -LiteralPath $nodeMeta)) {- Write-StudioLine "[ERROR] $NodeDir already exists and is not an Unsloth-owned Node install." -ForegroundColor Red+ # From the entry, not a second probe: a dangling link is a container to neither, and+ # a reparse point carrying no ownership evidence is not an install of ours.+ $nodeIsDir = $nodeEntry.PSIsContainer -and+ -not ($nodeEntry.Attributes -band [IO.FileAttributes]::ReparsePoint)+ if (-not $nodeIsDir -or (+ -not (Test-Path -LiteralPath $nodeOwnedMarker) -and+ -not (Test-Path -LiteralPath $nodeMeta))) {+ $what = if ($nodeIsDir) { "an Unsloth-owned Node install" } else { "a directory" }+ Write-StudioLine "[ERROR] $NodeDir already exists and is not $what." -ForegroundColor RedWrite-StudioLine " Move it aside or choose an empty UNSLOTH_STUDIO_HOME before re-running." -ForegroundColor YellowExit-SetupFailure "$NodeDir is not an Unsloth-owned Node install"}@@ -4742,7 +4950,9 @@ if ($NeedNodeForSetup) {Write-StudioLine " Install Node >= 20.19 (with npm >= 11) from https://nodejs.org/ and re-run, or check your network." -ForegroundColor YellowExit-SetupFailure "Could not install an isolated Node runtime"}- if ($NodeOverride -and (Test-Path -LiteralPath $NodeDir -PathType Container)) {+ # Same condition as the guard above, or the tree this run just created under a master+ # root stays unmarked and the uninstaller declines to remove it as somebody else's.+ if (($NodeOverride -or $RuntimeRootIsCustom) -and (Test-Path -LiteralPath $NodeDir -PathType Container)) {New-Item -ItemType File -Force -Path (Join-Path $NodeDir ".unsloth-studio-owned") -ErrorAction SilentlyContinue | Out-Null}$env:PATH = "$NodeDir;" + $env:PATH@@ -5023,26 +5233,41 @@ function Assert-StudioOwnedOrAbsent {[Parameter(Mandatory = $true)][string]$Label,# whisper.cpp is non-fatal by contract, so it needs the denial handed back# rather than exited on. Only this mode returns a value.- [switch]$NonFatal+ [switch]$NonFatal,+ # The runtime children pass $RuntimeRootIsCustom; everything under the+ # Studio home keeps $StudioHomeIsCustom.+ [AllowNull()][object]$IsCustom = $null)+ $isCustomRoot = $StudioHomeIsCustom+ if ($null -ne $IsCustom) { $isCustomRoot = [bool]$IsCustom }# Denied is not Absent: a root we cannot read cannot be proven ours, and- # returning here would let the caller replace it. Both stops stay gated on- # $StudioHomeIsCustom, as before; a default-home denial is reported by the- # phase that owns the path.+ # returning here would let the caller replace it; a default-home denial is+ # reported by the phase that owns the path.$pathState = Get-PathState -Path $Path -PathType Containerif ($pathState -ne "Present") {- if ($StudioHomeIsCustom -and $pathState -eq "Denied") {+ if ($isCustomRoot -and $pathState -eq "Denied") {if ($NonFatal) { return "Denied" }Exit-PathAccessDenied -Path $Path -Label $Label -OwnershipUnverified}- return+ # A Container probe answers false for a regular file and for a link whose target is gone,+ # and the caller then deleted the path or let install_*_prebuilt.py replace it; both+ # shapes are things the user put in a directory they chose. Get-Item -Force still sees+ # the directory entry where Test-Path does not, which is the dangling link under 5.1.+ if (-not $isCustomRoot) { return }+ if (-not (Get-Item -LiteralPath $Path -Force -ErrorAction SilentlyContinue)) { return }+ # Ownership evidence lives inside a directory, so a non-directory can never carry it+ # and is refused outright rather than asked for markers. Fatal even under -NonFatal:+ # that mode rescues a denial, not somebody else's file.+ Write-StudioLine "[ERROR] $Path already exists and is not a directory." -ForegroundColor Red+ Write-StudioLine " Move it aside or choose an empty UNSLOTH_STUDIO_HOME before re-running." -ForegroundColor Yellow+ Exit-SetupFailure "$Label path is not an Unsloth-owned install: $Path"}$markerState = Get-PathState -Path (Join-Path $Path $StudioOwnedMarker) -PathType Leaf- if ($StudioHomeIsCustom -and $markerState -eq "Denied") {+ if ($isCustomRoot -and $markerState -eq "Denied") {if ($NonFatal) { return "Denied" }Exit-PathAccessDenied -Path $Path -Label $Label -OwnershipUnverified}- if ($StudioHomeIsCustom -and $markerState -ne "Present") {+ if ($isCustomRoot -and $markerState -ne "Present") {$adoptState = Get-StudioAdoptableState -Path $Pathif ($adoptState -eq "Denied") {if ($NonFatal) { return "Denied" }@@ -7221,9 +7446,24 @@ if ($script:UnslothVerbose) {# Triton/inductor filenames are long and can hit Windows MAX_PATH (260). With long# paths on, cache under Unsloth home; else use a short drive-root dir for headroom.-if ($StageRoot -or $LongPathsEnabled) {+#+# Persisted to the USER environment below, so every later Studio process inherits it and+# _setup_cache_env's fill-if-unset default never applies on Windows: it has to name the+# directory the resolver would have chosen, or the containment does not happen here at all.+#+# Two things outrank that. Long paths off keeps the short drive-root directory, since Inductor's+# filenames hit MAX_PATH and a contained cache that cannot be written is worse than an+# uncontained one. And a path containing a space is refused as+# storage_roots._TOOLCHAIN_PATH_KEYS refuses one: cpp_builder.py pastes it into a compiler+# command line unquoted, and "C:\Users\First Last" is an ordinary account name.+$TorchCacheDir = $null+if ($StageRoot) {$TorchCacheDir = Join-Path $RuntimeRoot "TORCHINDUCTOR_CACHE_DIR"-} else {+} elseif ($LongPathsEnabled) {+ $candidate = Join-Path (Join-Path $StudioHome "cache") "torchinductor"+ if ($candidate -notmatch '\s') { $TorchCacheDir = $candidate }+}+if (-not $TorchCacheDir) {$TorchCacheDir = "C:\tc"}if (-not (Test-Path -LiteralPath $TorchCacheDir)) { [System.IO.Directory]::CreateDirectory($TorchCacheDir) | Out-Null }@@ -8465,8 +8705,8 @@ if ($LocalLlamaCppSrc) {throw}}- if ($StudioHomeIsCustom) {- Assert-StudioOwnedOrAbsent -Path $LlamaCppDir -Label "llama.cpp install"+ if ($RuntimeRootIsCustom) {+ Assert-StudioOwnedOrAbsent -Path $LlamaCppDir -Label "llama.cpp install" -IsCustom $RuntimeRootIsCustom}# The destination is about to be deleted and replaced, so a denial here# must stop rather than throw raw: under a default home nothing above@@ -8519,7 +8759,7 @@ if ($LocalLlamaCppLinked) {# Keep this late guard as defense in depth before the prebuilt installer.$llamaDirState = Get-LlamaCppInstallReadState -Path $LlamaCppDirif ($llamaDirState -eq "Denied") {- Exit-PathAccessDenied -Path $LlamaCppDir -Label "llama.cpp install" -OwnershipUnverified:$StudioHomeIsCustom+ Exit-PathAccessDenied -Path $LlamaCppDir -Label "llama.cpp install" -OwnershipUnverified:$RuntimeRootIsCustom}if ($llamaDirState -eq "Readable") {substep "Existing llama.cpp install detected -- validating staged prebuilt update before replacement"@@ -8563,8 +8803,8 @@ if ($LocalLlamaCppLinked) {}substep "installing prebuilt llama.cpp bundle (preferred path)..."# install_llama_prebuilt.py's os.replace() would displace a custom-home llama.cpp first.- if ($StudioHomeIsCustom) {- Assert-StudioOwnedOrAbsent -Path $LlamaCppDir -Label "llama.cpp install"+ if ($RuntimeRootIsCustom) {+ Assert-StudioOwnedOrAbsent -Path $LlamaCppDir -Label "llama.cpp install" -IsCustom $RuntimeRootIsCustom}$prebuiltArgs = @("$PSScriptRoot\install_llama_prebuilt.py",@@ -8643,7 +8883,7 @@ if ($LocalLlamaCppLinked) {} else {step "llama.cpp" "prebuilt installed and validated"}- if ($StudioHomeIsCustom -and (Test-Path -LiteralPath $LlamaCppDir -PathType Container)) {+ if ($RuntimeRootIsCustom -and (Test-Path -LiteralPath $LlamaCppDir -PathType Container)) {Mark-StudioOwned -Path $LlamaCppDir}$installedRelease = Get-InstalledLlamaPrebuiltRelease -InstallDir $LlamaCppDir@@ -8730,8 +8970,8 @@ if ($env:WHISPER_SERVER_PATH -or $env:UNSLOTH_WHISPER_CPP_PATH) {substep "whisper.cpp: using a user-configured binary/dir; skipping managed install"} elseif ($env:UNSLOTH_SKIP_WHISPER_INSTALL -eq "1") {substep "whisper.cpp: install skipped (UNSLOTH_SKIP_WHISPER_INSTALL=1)"-} elseif ($StudioHomeIsCustom -and (Test-Path -LiteralPath $WhisperInstaller) -and- (Assert-StudioOwnedOrAbsent -Path $WhisperCppDir -Label "whisper.cpp install" -NonFatal) -eq "Denied") {+} elseif ($RuntimeRootIsCustom -and (Test-Path -LiteralPath $WhisperInstaller) -and+ (Assert-StudioOwnedOrAbsent -Path $WhisperCppDir -Label "whisper.cpp install" -NonFatal -IsCustom $RuntimeRootIsCustom) -eq "Denied") {# Never fatal, per the phase header: the guard below would exit the whole run# on an unreadable tree, taking llama.cpp down with it. Only the denial is# caught here; an unowned tree still stops.@@ -8739,8 +8979,8 @@ if ($env:WHISPER_SERVER_PATH -or $env:UNSLOTH_WHISPER_CPP_PATH) {} elseif (Test-Path -LiteralPath $WhisperInstaller) {# The installer's atomic activation replaces the whole directory, so the# custom-home ownership guard must run first (mirrors the llama block).- if ($StudioHomeIsCustom) {- Assert-StudioOwnedOrAbsent -Path $WhisperCppDir -Label "whisper.cpp install"+ if ($RuntimeRootIsCustom) {+ Assert-StudioOwnedOrAbsent -Path $WhisperCppDir -Label "whisper.cpp install" -IsCustom $RuntimeRootIsCustom}$whisperArgs = @($WhisperInstaller, "--install-dir", $WhisperCppDir)if ($env:UNSLOTH_WHISPER_RELEASE_TAG) {@@ -8780,7 +9020,7 @@ if ($env:WHISPER_SERVER_PATH -or $env:UNSLOTH_WHISPER_CPP_PATH) {} else {step "whisper.cpp" "prebuilt installed"}- if ($StudioHomeIsCustom -and (Test-PathQuiet $WhisperCppDir "Container")) {+ if ($RuntimeRootIsCustom -and (Test-PathQuiet $WhisperCppDir "Container")) {Mark-StudioOwned -Path $WhisperCppDir}} elseif ($whisperExit -eq 3) {@@ -8873,7 +9113,7 @@ $NeedRebuild = $false$llamaBinState = if ($LocalLlamaCppLinked) { "Absent" } else { Get-PathState -Path $LlamaServerBin -PathType Leaf }if ($llamaBinState -eq "Denied") {# Nothing proved this tree is ours here, so do not advise deleting it.- Exit-PathAccessDenied -Path $LlamaCppDir -Label "llama.cpp install" -OwnershipUnverified:$StudioHomeIsCustom+ Exit-PathAccessDenied -Path $LlamaCppDir -Label "llama.cpp install" -OwnershipUnverified:$RuntimeRootIsCustom}if ($llamaBinState -eq "Present") {$CmakeCacheFile = Join-Path $BuildDir "CMakeCache.txt"@@ -8883,7 +9123,7 @@ if ($llamaBinState -eq "Present") {$cachedCuda = Select-String -LiteralPath $CmakeCacheFile -Pattern 'GGML_CUDA:BOOL=ON' -Quiet} catch {if (-not (Test-AccessDeniedError $_)) { throw }- Exit-PathAccessDenied -Path $LlamaCppDir -Label "llama.cpp install" -OwnershipUnverified:$StudioHomeIsCustom+ Exit-PathAccessDenied -Path $LlamaCppDir -Label "llama.cpp install" -OwnershipUnverified:$RuntimeRootIsCustom}if ($HasNvidiaSmi -and -not $cachedCuda) {Write-StudioLine " Existing llama-server is CPU-only but GPU is available -- rebuilding" -ForegroundColor Yellow@@ -9098,8 +9338,8 @@ if ($LocalLlamaCppLinked) {# why: in-place git mutation (remote set-url, checkout -B, clean -fdx)# rewrites $LlamaCppDir; mirror the prebuilt and temp-dir-swap guards# so an unrelated workspace .git tree is never silently overwritten.- if ($StudioHomeIsCustom) {- Assert-StudioOwnedOrAbsent -Path $LlamaCppDir -Label "llama.cpp install"+ if ($RuntimeRootIsCustom) {+ Assert-StudioOwnedOrAbsent -Path $LlamaCppDir -Label "llama.cpp install" -IsCustom $RuntimeRootIsCustom}Write-StudioLine " Syncing llama.cpp to $ResolvedSourceRef..." -ForegroundColor Gray# Always sync the remote URL so switching between default/fork sources works@@ -9172,7 +9412,7 @@ if ($LocalLlamaCppLinked) {}}# In-place git-sync must mark the tree, else a later Assert-StudioOwnedOrAbsent exits.- if ($BuildOk -and $StudioHomeIsCustom) {+ if ($BuildOk -and $RuntimeRootIsCustom) {Mark-StudioOwned -Path $LlamaCppDir}} else {@@ -9398,7 +9638,7 @@ if ($LocalLlamaCppLinked) {# Swap temp build dir into final location (only if we built in a temp dir)if ($BuildOk -and $LlamaCppDir -ne $OriginalLlamaCppDir) {- Assert-StudioOwnedOrAbsent -Path $OriginalLlamaCppDir -Label "llama.cpp install"+ Assert-StudioOwnedOrAbsent -Path $OriginalLlamaCppDir -Label "llama.cpp install" -IsCustom $RuntimeRootIsCustomif ((Get-PathState -Path $OriginalLlamaCppDir) -ne "Absent") {Remove-Item -LiteralPath $OriginalLlamaCppDir -Recurse -Force -ErrorAction SilentlyContinue# Any unreadable or locked child survives the removal, and Move-Item@@ -9467,7 +9707,7 @@ if ($LocalLlamaCppLinked) {$llamaCppItem = Get-Item -LiteralPath $LlamaCppDir -Force -ErrorAction SilentlyContinue$llamaCppIsLink = $llamaCppItem -and ($llamaCppItem.Attributes -band [System.IO.FileAttributes]::ReparsePoint)if (-not $llamaCppIsLink -and (- -not $StudioHomeIsCustom -or+ -not $RuntimeRootIsCustom -or(Test-PathQuiet (Join-Path $LlamaCppDir $StudioOwnedMarker) "Leaf") -or(Test-StudioOwnedAdoptable $LlamaCppDir))) {diff --git a/studio/setup.sh b/studio/setup.shindex 2747c9565ff..72e52b5deb2 100755--- a/studio/setup.sh+++ b/studio/setup.sh@@ -1443,6 +1443,63 @@ _STUDIO_HOME_IS_CUSTOM=falseif [ "$_studio_home_canon" != "$_LEGACY_STUDIO_HOME" ]; then_STUDIO_HOME_IS_CUSTOM=truefi+# The master root storage_roots.unsloth_home() reads. llama.cpp, node and whisper.cpp sit BESIDE+# studio/ under it, so installing them under $STUDIO_HOME would put them one level below where+# every runtime resolver looks. Captured here because section 7 assigns over UNSLOTH_HOME.+# Stripped before anything else, like _studio_override above: " " counts as unset and " /opt/uns "+# names /opt/uns, which is what the Python resolver and the CLI both see.+_MASTER_ROOT=$(printf '%s' "${UNSLOTH_HOME:-}" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')+if [ -n "$_MASTER_ROOT" ]; then+ case "$_MASTER_ROOT" in+ "~") _MASTER_ROOT="$HOME" ;;+ "~/"*) _MASTER_ROOT="$HOME/${_MASTER_ROOT#'~/'}" ;;+ esac+ # Absolute against the CALLER's directory even when it does not exist yet, as Path.resolve()+ # does: node is chosen before the first `cd "$SCRIPT_DIR"` and llama.cpp after it, so a+ # relative value names two different directories and matches the backend's neither.+ case "$_MASTER_ROOT" in+ /*) ;;+ *) _MASTER_ROOT="$PWD/$_MASTER_ROOT" ;;+ esac+ if [ -d "$_MASTER_ROOT" ]; then+ # Keep the expanded value when it cannot be canonicalized, as the Python resolver does:+ # dropping it here would send the runtimes to a root nothing else agrees on.+ _master_root_canon=$(CDPATH= cd -P -- "$_MASTER_ROOT" 2>/dev/null && pwd -P) || _master_root_canon=""+ [ -z "$_master_root_canon" ] || _MASTER_ROOT="$_master_root_canon"+ unset _master_root_canon+ fi+fi++# Ownership applies to node/, llama.cpp/ and whisper.cpp/ whenever a master root moves them,+# even with STUDIO_HOME left at the legacy path, where _STUDIO_HOME_IS_CUSTOM is false and+# "false" licenses the installers to os.replace() and rm -rf unmarked trees. The Studio home+# and its venvs keep the other flag.+_RUNTIME_ROOT_IS_CUSTOM="$_STUDIO_HOME_IS_CUSTOM"+# Keyed on where the runtimes LAND, not on whether a master root was named: UNSLOTH_HOME set to+# the root an install already uses moves nothing, and calling that custom would demand an owner+# marker from a legacy source-built ~/.unsloth/llama.cpp that predates markers.+#+# Staging is excluded for the same reason, not as an exception to it: the placement below gives+# STAGE_ROOT precedence over the master root, so during a staged update the master root is not+# where anything lands and must not decide ownership. Assigned rather than raised, or a custom+# STUDIO_HOME kept the flag true while the runtimes went to the legacy root, which demanded+# markers from exactly the pre-marker trees this comparison exists to spare.+if [ -z "${STAGE_ROOT:-}" ] && [ -n "$_MASTER_ROOT" ]; then+ # Canonicalised like _MASTER_ROOT, or a symlinked $HOME compares unequal to itself and the+ # legacy root reads as custom after all.+ _rrc_legacy="$HOME/.unsloth"+ if [ -d "$_rrc_legacy" ]; then+ _rrc_canon=$(CDPATH= cd -P -- "$_rrc_legacy" 2>/dev/null && pwd -P) || _rrc_canon=""+ [ -z "$_rrc_canon" ] || _rrc_legacy="$_rrc_canon"+ unset _rrc_canon+ fi+ if [ "$_MASTER_ROOT" = "$_rrc_legacy" ]; then+ _RUNTIME_ROOT_IS_CUSTOM=false+ else+ _RUNTIME_ROOT_IS_CUSTOM=true+ fi+ unset _rrc_legacy+fi# Directory-local evidence Unsloth created "$1": only prebuilt-installer metadata# counts (UNSLOTH_PREBUILT_INFO.json for llama.cpp, UNSLOTH_NODE_PREBUILT_INFO.json# for Node, UNSLOTH_WHISPER_PREBUILT_INFO.json for whisper.cpp), all written only@@ -1527,11 +1584,37 @@ _report_denied_ancestor() {fi}+# What is at "$1", for the refusal message. A user told the path is "not an Unsloth install"+# when it is their own dangling symlink has no idea what to move aside.+_studio_path_shape() {+ if [ -L "$1" ]; then+ if [ -e "$1" ]; then printf 'a symlink'; else printf 'a dangling symlink'; fi+ elif [ -f "$1" ]; then printf 'a regular file'+ elif [ -d "$1" ]; then printf 'a directory'+ else printf 'an existing path'+ fi+}++# $3 is the ownership flag: the runtime children pass _RUNTIME_ROOT_IS_CUSTOM, everything+# under the Studio home keeps _STUDIO_HOME_IS_CUSTOM._assert_studio_owned_or_absent() {_aso_dir="$1"_aso_label="$2"- [ -d "$_aso_dir" ] || return 0- if [ "$_STUDIO_HOME_IS_CUSTOM" = true ] && [ ! -f "$_aso_dir/$_STUDIO_OWNED_MARKER" ]; then+ _aso_custom="${3:-$_STUDIO_HOME_IS_CUSTOM}"+ # -d alone read a dangling symlink or a regular file as "nothing is here", and the caller+ # then rm -rf'd it or os.replace()d over it. A dangling link is the ordinary case: its+ # volume is simply not mounted, and following it later installs onto somebody's other disk.+ if [ ! -d "$_aso_dir" ] && [ ! -e "$_aso_dir" ] && [ ! -L "$_aso_dir" ]; then+ return 0+ fi+ if [ "$_aso_custom" = true ] && [ ! -f "$_aso_dir/$_STUDIO_OWNED_MARKER" ]; then+ # Only a directory can carry the marker or the prebuilt metadata, so anything else here+ # is unowned by construction and the adoption path below cannot apply to it.+ if [ ! -d "$_aso_dir" ]; then+ echo "ERROR: $_aso_dir already exists and is not an Unsloth-owned $_aso_label." >&2+ echo " It is $(_studio_path_shape "$_aso_dir"). Move it aside before re-running." >&2+ setup_fail 1 "$_aso_label path is not an Unsloth-owned install: $_aso_dir"+ fiif _studio_owned_adoptable "$_aso_dir"; then: > "$_aso_dir/$_STUDIO_OWNED_MARKER" 2>/dev/null || truereturn 0@@ -1641,6 +1724,8 @@ decide_node_source() {# Mirror the llama.cpp UNSLOTH_HOME derivation; the frontend build runs first.if [ -n "$STAGE_ROOT" ]; then_NODE_PARENT="$RUNTIME_ROOT"+elif [ -n "$_MASTER_ROOT" ]; then+ _NODE_PARENT="$_MASTER_ROOT"elif [ "$_STUDIO_HOME_IS_CUSTOM" = true ]; then_NODE_PARENT="$STUDIO_HOME"else@@ -1659,8 +1744,8 @@ elif [ "$NODE_SOURCE" = bundled ]; thenmkdir -p "$_NODE_PARENT"# install_node_prebuilt.py uses os.replace(); guard a custom-home dir so we# never displace a user-owned $UNSLOTH_STUDIO_HOME/node.- if [ "$_STUDIO_HOME_IS_CUSTOM" = true ]; then- _assert_studio_owned_or_absent "$NODE_DIR" "Node install"+ if [ "$_RUNTIME_ROOT_IS_CUSTOM" = true ]; then+ _assert_studio_owned_or_absent "$NODE_DIR" "Node install" "$_RUNTIME_ROOT_IS_CUSTOM"fisubstep "installing isolated Node (system Node/npm left untouched)..."# Runs before the venv is activated, so bare `python` may be absent; resolve@@ -1695,7 +1780,7 @@ elif [ "$NODE_SOURCE" = bundled ]; thenfigrep -Fq "already matches" "$_NODE_LOG" && verbose_substep "isolated Node already up to date"rm -f "$_NODE_LOG"- if [ "$_STUDIO_HOME_IS_CUSTOM" = true ] && [ -d "$NODE_DIR" ]; then+ if [ "$_RUNTIME_ROOT_IS_CUSTOM" = true ] && [ -d "$NODE_DIR" ]; then: > "$NODE_DIR/$_STUDIO_OWNED_MARKER" 2>/dev/null || truefi# Prepend the isolated bin (this process only) so node/npm/bun resolve here.@@ -3664,12 +3749,107 @@ fi# default keeps ~/.unsloth/llama.cpp so pre-PR builds are still discovered.if [ -n "$STAGE_ROOT" ]; thenUNSLOTH_HOME="$RUNTIME_ROOT"+elif [ -n "$_MASTER_ROOT" ]; then+ UNSLOTH_HOME="$_MASTER_ROOT"elif [ "$_STUDIO_HOME_IS_CUSTOM" = true ]; thenUNSLOTH_HOME="$STUDIO_HOME"elseUNSLOTH_HOME="$HOME/.unsloth"fimkdir -p "$UNSLOTH_HOME"+# Record the master root inside the Studio tree, for the uninstaller: UNSLOTH_HOME can be set+# for a single command, and without the note the uninstaller removed the Studio tree and+# stranded multi-gigabyte llama.cpp, node and whisper.cpp trees beside it.+#+# Only for a master root (the other branches derive UNSLOTH_HOME from paths the uninstaller+# already knows), and only when a reader will honour it: both rejected shapes were being+# written, so the file on disk claimed a recorded root while every reader refused it.+_master_root_note_is_honoured() {+ # Canonicalised here rather than trusting the value from the top of the script: that one was+ # resolved before the mkdir above, so a root created by this run kept its uncanonical+ # spelling, and the containment test below is textual.+ _mrn_root=$(CDPATH= cd -P -- "$1" 2>/dev/null && pwd -P) || _mrn_root=""+ [ -n "$_mrn_root" ] || return 1+ # The legacy default is the one root every reader finds without help, and both uninstallers+ # refuse it outright. Writing it turned a one-command `UNSLOTH_HOME=$HOME/.unsloth` into a+ # permanent portable install: every later bare launch read the note back and HF_HUB_CACHE+ # moved off ~/.cache/huggingface, the one cache this change promises not to move.+ _mrn_legacy=$(CDPATH= cd -P -- "${HOME:-}/.unsloth" 2>/dev/null && pwd -P) || _mrn_legacy="${HOME:-}/.unsloth"+ [ "$_mrn_root" != "$_mrn_legacy" ] || return 1+ # Keyed on the TREE as well, because that is what the readers key on: storage_roots'+ # _is_legacy_studio_tree and the CLI both decline ANY note found in ~/.unsloth/studio,+ # whatever it records. Without this, UNSLOTH_HOME=$HOME passed containment (the legacy tree+ # is inside $HOME) and the value is not the legacy root, so the note was written, warned+ # about nothing, and then honoured by nobody.+ _mrn_studio=$(CDPATH= cd -P -- "$STUDIO_HOME" 2>/dev/null && pwd -P) || _mrn_studio="$STUDIO_HOME"+ _mrn_legacy_studio=$(CDPATH= cd -P -- "${HOME:-}/.unsloth/studio" 2>/dev/null && pwd -P) \+ || _mrn_legacy_studio="${HOME:-}/.unsloth/studio"+ if [ "$_mrn_studio" = "$_mrn_legacy_studio" ]; then+ echo "NOTE: the managed runtimes were installed under $_mrn_root, but Studio itself is the" >&2+ echo " default install at $_mrn_studio, where no reader honours a recorded root. That" >&2+ echo " root cannot be recorded, so a later launch or uninstall will not find them." >&2+ echo " Set UNSLOTH_STUDIO_HOME=$_mrn_root/studio, or re-export UNSLOTH_HOME whenever" >&2+ echo " you run Unsloth." >&2+ return 1+ fi+ # A note must describe the tree it is written into: all four readers require the Studio+ # directory to lie INSIDE the root it names, so a tree copied between master roots cannot+ # aim a removal at the original install. install.sh and install.ps1 do not read UNSLOTH_HOME+ # yet, so `UNSLOTH_HOME=/mnt/portable unsloth studio update` leaves Studio at+ # ~/.unsloth/studio with the runtimes at /mnt/portable, which is exactly that shape: warn,+ # rather than leave a file that reads as a recorded root and behaves as none.+ case "$STUDIO_HOME" in+ "$_mrn_root"|"$_mrn_root"/*) return 0 ;;+ esac+ echo "NOTE: the managed runtimes were installed under $_mrn_root, but Studio itself lives at" >&2+ echo " $STUDIO_HOME, which is outside it. That root cannot be recorded, so a later launch" >&2+ echo " or uninstall will not find them. Set UNSLOTH_STUDIO_HOME=$_mrn_root/studio, or" >&2+ echo " re-export UNSLOTH_HOME whenever you run Unsloth." >&2+ return 1+}+if [ -n "$_MASTER_ROOT" ] && [ -z "$STAGE_ROOT" ] && _master_root_note_is_honoured "$UNSLOTH_HOME"; then+ if mkdir -p "$STUDIO_HOME/share" 2>/dev/null; then+ # Staged then renamed: a reader catching a half-written note would name a truncated+ # path, and this note licenses deletions. mktemp rather than "$$", as+ # _uv_cache_root_is_writable states above: a redirection into a predictable name follows+ # a symlink anyone who can write share/ could have precreated there.+ if ! _mrn_tmp=$(mktemp "$STUDIO_HOME/share/.unsloth-master-root.XXXXXX" 2>/dev/null); then+ _mrn_tmp=""+ fi+ if [ -n "$_mrn_tmp" ] && printf '%s\n' "$UNSLOTH_HOME" > "$_mrn_tmp" 2>/dev/null; then+ mv -f "$_mrn_tmp" "$STUDIO_HOME/share/.unsloth-master-root" 2>/dev/null \+ || rm -f "$_mrn_tmp" 2>/dev/null || true+ elif [ -n "$_mrn_tmp" ]; then+ rm -f "$_mrn_tmp" 2>/dev/null || true+ fi+ unset _mrn_tmp+ fi+fi+# Clear a note an earlier run left naming the legacy default root, whatever this run was asked+# to do. The gate above stops new ones, but an install that already has one keeps reading it+# back on every bare launch -- portable mode on, the Hugging Face hub cache moved off+# ~/.cache/huggingface -- and no later `unsloth studio update` would ever pass through the write+# block to correct it, since that block only runs when UNSLOTH_HOME is set again. Narrow on+# purpose: this is the single value both uninstallers already refuse, so removing it takes+# nothing any reader was entitled to act on. A note naming any other root is left alone, since+# an unreadable or unexpected one may simply describe an install this run cannot see.+if [ -f "$STUDIO_HOME/share/.unsloth-master-root" ]; then+ _mrn_old=$(head -n 1 "$STUDIO_HOME/share/.unsloth-master-root" 2>/dev/null \+ | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//') || _mrn_old=""+ if [ -n "$_mrn_old" ]; then+ case "$_mrn_old" in+ "~") _mrn_old="${HOME:-}" ;;+ "~/"*) _mrn_old="${HOME:-}/${_mrn_old#'~/'}" ;;+ esac+ _mrn_old_canon=$(CDPATH= cd -P -- "$_mrn_old" 2>/dev/null && pwd -P) || _mrn_old_canon=""+ [ -n "$_mrn_old_canon" ] && _mrn_old="$_mrn_old_canon"+ _mrn_legacy=$(CDPATH= cd -P -- "${HOME:-}/.unsloth" 2>/dev/null && pwd -P) || _mrn_legacy="${HOME:-}/.unsloth"+ if [ "$_mrn_old" = "$_mrn_legacy" ]; then+ rm -f "$STUDIO_HOME/share/.unsloth-master-root" 2>/dev/null || true+ fi+ fi+ unset _mrn_old _mrn_old_canon+fiLLAMA_CPP_DIR="$UNSLOTH_HOME/llama.cpp"LLAMA_SERVER_BIN="$LLAMA_CPP_DIR/build/bin/llama-server"_NEED_LLAMA_SOURCE_BUILD=false@@ -4014,8 +4194,8 @@ if [ -n "${UNSLOTH_LOCAL_LLAMA_CPP_DIR:-}" ]; then# for a custom UNSLOTH_STUDIO_HOME (the assert would otherwise follow the# link into the user's dir and reject it as unowned).[ -L "$LLAMA_CPP_DIR" ] && rm -f "$LLAMA_CPP_DIR"- if [ "$_STUDIO_HOME_IS_CUSTOM" = true ]; then- _assert_studio_owned_or_absent "$LLAMA_CPP_DIR" "llama.cpp install"+ if [ "$_RUNTIME_ROOT_IS_CUSTOM" = true ]; then+ _assert_studio_owned_or_absent "$LLAMA_CPP_DIR" "llama.cpp install" "$_RUNTIME_ROOT_IS_CUSTOM"firm -rf "$LLAMA_CPP_DIR" || trueif [ -e "$LLAMA_CPP_DIR" ]; then@@ -4040,8 +4220,8 @@ fi# swap only reaches its own guards after the whole build, so check here instead.# Local-link paths are excluded: they already replaced or reused the tree above.if [ "$_LOCAL_LLAMA_CPP_LINKED" != true ]; then- if [ "$_STUDIO_HOME_IS_CUSTOM" = true ]; then- _assert_studio_owned_or_absent "$LLAMA_CPP_DIR" "llama.cpp install"+ if [ "$_RUNTIME_ROOT_IS_CUSTOM" = true ]; then+ _assert_studio_owned_or_absent "$LLAMA_CPP_DIR" "llama.cpp install" "$_RUNTIME_ROOT_IS_CUSTOM"fiif _studio_dir_unreadable "$LLAMA_CPP_DIR"; then_path_access_denied "$LLAMA_CPP_DIR" "llama.cpp install"@@ -4071,8 +4251,8 @@ else# why: install_llama_prebuilt.py uses os.replace(), which would displace# an unrelated $UNSLOTH_STUDIO_HOME/llama.cpp before the source-build# ownership check below ever runs.- if [ "$_STUDIO_HOME_IS_CUSTOM" = true ]; then- _assert_studio_owned_or_absent "$LLAMA_CPP_DIR" "llama.cpp install"+ if [ "$_RUNTIME_ROOT_IS_CUSTOM" = true ]; then+ _assert_studio_owned_or_absent "$LLAMA_CPP_DIR" "llama.cpp install" "$_RUNTIME_ROOT_IS_CUSTOM"fi# The ownership check above misses the default cache; stop before pathlib# turns an unreadable one into a traceback.@@ -4145,7 +4325,7 @@ elseelsestep "llama.cpp" "prebuilt installed and validated"fi- if [ "$_STUDIO_HOME_IS_CUSTOM" = true ] && [ -d "$LLAMA_CPP_DIR" ]; then+ if [ "$_RUNTIME_ROOT_IS_CUSTOM" = true ] && [ -d "$LLAMA_CPP_DIR" ]; then: > "$LLAMA_CPP_DIR/$_STUDIO_OWNED_MARKER" 2>/dev/null || truefiprint_installed_llama_prebuilt_release "$LLAMA_CPP_DIR"@@ -4223,7 +4403,7 @@ if [ "$_NEED_LLAMA_SOURCE_BUILD" = true ] && \[ -x "$LLAMA_CPP_DIR/build/bin/llama-quantize" ]; thenstep "llama.cpp" "existing source build found; skipping rebuild"ln -sf build/bin/llama-quantize "$LLAMA_CPP_DIR/llama-quantize"- if [ "$_STUDIO_HOME_IS_CUSTOM" = true ]; then+ if [ "$_RUNTIME_ROOT_IS_CUSTOM" = true ]; then: > "$LLAMA_CPP_DIR/$_STUDIO_OWNED_MARKER" 2>/dev/null || truefi_NEED_LLAMA_SOURCE_BUILD=false@@ -4784,7 +4964,7 @@ elsefi# Swap only after build succeeds -- preserves existing install on failureif [ "$BUILD_OK" = true ]; then- _assert_studio_owned_or_absent "$LLAMA_CPP_DIR" "llama.cpp install"+ _assert_studio_owned_or_absent "$LLAMA_CPP_DIR" "llama.cpp install" "$_RUNTIME_ROOT_IS_CUSTOM"# || true: without it a raw rm error aborts under errexit to a bare exit# code, build stranded. Keep stderr: rm names the exact subpath, we cannot.rm -rf "$LLAMA_CPP_DIR" || true@@ -4862,7 +5042,7 @@ if [ "$_LLAMA_CPP_DEGRADED" = true ] \fiif [ ! -L "$LLAMA_CPP_DIR" ] && {- [ "$_STUDIO_HOME_IS_CUSTOM" != true ] ||+ [ "$_RUNTIME_ROOT_IS_CUSTOM" != true ] ||[ -f "$LLAMA_CPP_DIR/$_STUDIO_OWNED_MARKER" ] ||_studio_owned_adoptable "$LLAMA_CPP_DIR"}; then@@ -4881,8 +5061,8 @@ if [ -n "${WHISPER_SERVER_PATH:-}" ] || [ -n "${UNSLOTH_WHISPER_CPP_PATH:-}" ];elif [ "${UNSLOTH_SKIP_WHISPER_INSTALL:-0}" = "1" ]; thenverbose_substep "whisper.cpp: install skipped (UNSLOTH_SKIP_WHISPER_INSTALL=1)"else- if [ "$_STUDIO_HOME_IS_CUSTOM" = true ]; then- _assert_studio_owned_or_absent "$WHISPER_CPP_DIR" "whisper.cpp install"+ if [ "$_RUNTIME_ROOT_IS_CUSTOM" = true ]; then+ _assert_studio_owned_or_absent "$WHISPER_CPP_DIR" "whisper.cpp install" "$_RUNTIME_ROOT_IS_CUSTOM"fi_WHISPER_CMD=(python "$SCRIPT_DIR/install_whisper_prebuilt.py" --install-dir "$WHISPER_CPP_DIR")if [ -n "${UNSLOTH_WHISPER_RELEASE_TAG:-}" ]; then@@ -4914,7 +5094,7 @@ elseelsestep "whisper.cpp" "prebuilt installed"fi- if [ "$_STUDIO_HOME_IS_CUSTOM" = true ] && [ -d "$WHISPER_CPP_DIR" ]; then+ if [ "$_RUNTIME_ROOT_IS_CUSTOM" = true ] && [ -d "$WHISPER_CPP_DIR" ]; then: > "$WHISPER_CPP_DIR/$_STUDIO_OWNED_MARKER" 2>/dev/null || truefirm -f "$_WHISPER_LOG"@@ -4940,7 +5120,7 @@ elseenv UNSLOTH_HOME="$UNSLOTH_HOME" sh "$_WHISPER_BUILD"; then_WHISPER_RECOVERED=truestep "whisper.cpp" "source build installed"- if [ "$_STUDIO_HOME_IS_CUSTOM" = true ] && [ -d "$WHISPER_CPP_DIR" ]; then+ if [ "$_RUNTIME_ROOT_IS_CUSTOM" = true ] && [ -d "$WHISPER_CPP_DIR" ]; then: > "$WHISPER_CPP_DIR/$_STUDIO_OWNED_MARKER" 2>/dev/null || truefielsediff --git a/studio/src-tauri/src/install.rs b/studio/src-tauri/src/install.rsindex e90b3d639b9..ece3c7cbf58 100644--- a/studio/src-tauri/src/install.rs+++ b/studio/src-tauri/src/install.rs@@ -580,8 +580,12 @@ fn spawn_script(// Tauri only does default-root installs; install.sh / install.ps1 reject// these under --tauri. Scrub so an inherited value can't trip the guard.- cmd.env_remove("UNSLOTH_STUDIO_HOME");- cmd.env_remove("STUDIO_HOME");+ // Applied by hand here, the one managed spawn outside+ // apply_managed_cli_context: the Python setup.sh starts reads whatever is+ // exported, even though setup.sh assigns UNSLOTH_HOME itself.+ for name in crate::process::MANAGED_CHILD_SCRUBBED_ENV {+ cmd.env_remove(name);+ }cmd.env("UNSLOTH_DESKTOP_BACKEND_VERSION",crate::preflight::expected_backend_version(),diff --git a/studio/src-tauri/src/process.rs b/studio/src-tauri/src/process.rsindex b617cdad35a..fa5ce8b1d81 100644--- a/studio/src-tauri/src/process.rs+++ b/studio/src-tauri/src/process.rs@@ -1964,6 +1964,7 @@ fn windows_roots_from(/// PATH are absent: they are not single paths. Mirrors `_RELATIVE_PATH_ENV` in/// unsloth_cli/_system_dir_guard.py, held identical by a parity test.pub(crate) const RELATIVE_PATH_ENV: &[&str] = &[+ "UNSLOTH_HOME","UNSLOTH_STUDIO_HOME","STUDIO_HOME","UNSLOTH_STUDIO_DOCUMENTS_HOME",@@ -1997,6 +1998,18 @@ pub(crate) const RELATIVE_PATH_ENV: &[&str] = &["UNSLOTH_DG_SHIM","UNSLOTH_COMPILE_LOCATION","TORCHINDUCTOR_CACHE_DIR",+ // storage_roots.py fills these only when blank, so a relative value the user set is kept as+ // written and would name a different folder after the move.+ "TORCH_EXTENSIONS_DIR",+ "TORCH_HOME",+ "TRITON_HOME",+ "TRITON_CACHE_DIR",+ "TRITON_DUMP_DIR",+ "CUDA_CACHE_PATH",+ "MPLCONFIGDIR",+ "NUMBA_CACHE_DIR",+ "DATA_DESIGNER_HOME",+ "DATA_DESIGNER_MANAGED_ASSETS_PATH","UNSLOTH_DIFFUSION_COMPILE_CACHE_DIR","UNSLOTH_DIFFUSION_COND_CACHE_DIR","HF_HOME",@@ -2005,6 +2018,9 @@ pub(crate) const RELATIVE_PATH_ENV: &[&str] = &["HF_XET_CACHE","HF_DATASETS_CACHE","HF_ASSETS_CACHE",+ // transformers appends this to sys.path, so a relative value would import a+ // different generated module after the move.+ "HF_MODULES_CACHE",// huggingface_hub resolves the credential file from here; a relative value// would follow the child and silently lose access to gated repos."HF_TOKEN_PATH",@@ -2315,7 +2331,17 @@ fn names_a_path(name: &str, value: &str) -> bool {/// Names every managed spawn removes before starting the child: Tauri uses the/// legacy Unsloth root whatever the environment says. Resolving one can only/// invent a failure for a value the child is never going to see.-const MANAGED_CHILD_SCRUBBED_ENV: &[&str] = &["UNSLOTH_STUDIO_HOME", "STUDIO_HOME"];+///+/// UNSLOTH_HOME moves the databases, assets and caches exactly as+/// UNSLOTH_STUDIO_HOME does, plus the managed llama.cpp, node and whisper.cpp+/// dirs. UNSLOTH_PORTABLE names no root but portable_mode() reads it on its own,+/// repointing the Hugging Face and torch caches away from the shared user ones.+pub(crate) const MANAGED_CHILD_SCRUBBED_ENV: &[&str] = &[+ "UNSLOTH_HOME",+ "UNSLOTH_STUDIO_HOME",+ "STUDIO_HOME",+ "UNSLOTH_PORTABLE",+];/// Read only by the update and installer path (install_python_stack.py), so a/// stale value must not be able to fail a probe, a backend start or an auth@@ -3566,11 +3592,13 @@ pub fn start_backend(#[cfg(target_os = "linux")]scrub_appimage_python_env(&mut cmd);- // Tauri uses the legacy root regardless of UNSLOTH_STUDIO_HOME / STUDIO_HOME;- // scrub so the spawned Python backend can't diverge. UNSLOTH_LLAMA_CPP_PATH- // is a pre-existing user-controlled llama.cpp dir override; keep it.- cmd.env_remove("UNSLOTH_STUDIO_HOME");- cmd.env_remove("STUDIO_HOME");+ // Tauri uses the legacy root whatever the environment says; scrub so the+ // spawned Python backend can't diverge. Off the shared list, so a name added+ // there cannot be honoured by the backend and missed here.+ // UNSLOTH_LLAMA_CPP_PATH is a pre-existing user-controlled override; keep it.+ for name in MANAGED_CHILD_SCRUBBED_ENV {+ cmd.env_remove(name);+ }// read_output_stream decodes as UTF-8; without these, Python encodes its// redirected streams with the locale code page and non-ASCII lands as U+FFFD.diff --git a/tests/sh/test_portable_isolated_venv.sh b/tests/sh/test_portable_isolated_venv.shnew file mode 100755index 00000000000..36bd485c6bd--- /dev/null+++ b/tests/sh/test_portable_isolated_venv.sh@@ -0,0 +1,101 @@+#!/usr/bin/env bash+# The path resolver must work in a clean interpreter with only structlog, and+# seeding must create no studio.db (get_app_setting CREATES one). Needs uv.+set -u+REPO="${1:-$(CDPATH= cd -P -- "$(dirname "$0")/../.." && pwd -P)}"+if ! command -v uv >/dev/null 2>&1; then+ echo "SKIP: uv not on PATH, cannot build an isolated venv"+ exit 0+fi+WORK="$(mktemp -d)"+trap 'rm -rf "$WORK"' EXIT+fails=0+check() { if [ "$2" = 0 ]; then echo " PASS $1"; else echo " FAIL $1 ${3:-}"; fails=$((fails+1)); fi; }++echo "[1] build an isolated venv (uv, no site packages from the workspace)"+uv venv --python 3.13 "$WORK/venv" >/dev/null 2>&1 || { echo "FAIL: uv venv"; exit 1; }+PY="$WORK/venv/bin/python"+# structlog is the only thing storage_roots pulls in via loggers/path_utils.+uv pip install --python "$PY" structlog >/dev/null 2>&1 || { echo "FAIL: pip install"; exit 1; }+echo " venv: $("$PY" -V), packages: $(uv pip list --python "$PY" 2>/dev/null | wc -l)"++echo+echo "[2] resolver imports and runs with only structlog installed"+HOME_A="$WORK/home_a"; mkdir -p "$HOME_A"+out="$(env -i HOME="$HOME_A" PATH="/usr/bin:/bin" UNSLOTH_HOME="$WORK/root_a" \+ "$PY" -c "+import sys, os, json+sys.path.insert(0, '$REPO/studio/backend')+from utils.paths import storage_roots as sr+sr.setup_cache_env()+print(json.dumps({+ 'studio_root': str(sr.studio_root()),+ 'portable': sr.portable_mode(),+ 'compile': os.environ.get('UNSLOTH_COMPILE_LOCATION'),+ 'triton_home': os.environ.get('TRITON_HOME'),+}))+" 2>&1)"+case "$out" in+ *studio_root*) check "resolver runs on a bare interpreter" 0; echo " $out" ;;+ *) check "resolver runs on a bare interpreter" 1 "$out" ;;+esac++echo+echo "[3] no torch, transformers or other heavy import is required"+heavy="$(env -i HOME="$HOME_A" PATH="/usr/bin:/bin" "$PY" -c "+import sys+sys.path.insert(0, '$REPO/studio/backend')+from utils.paths import storage_roots as sr+sr.setup_cache_env()+bad = [m for m in ('torch','transformers','numpy','huggingface_hub','fastapi') if m in sys.modules]+print(','.join(bad) if bad else 'NONE')+" 2>&1 | tail -1)"+[ "$heavy" = "NONE" ] && check "seeding pulls in no heavy modules" 0 \+ || check "seeding pulls in no heavy modules" 1 "imported: $heavy"++echo+echo "[4] CLI seeding side effects: must not create a studio DB or leak outside the root"+HOME_B="$WORK/home_b"; mkdir -p "$HOME_B"+ROOT_B="$WORK/root_b"+env -i HOME="$HOME_B" PATH="/usr/bin:/bin" UNSLOTH_HOME="$ROOT_B" "$PY" -c "+import sys+sys.path.insert(0, '$REPO/studio/backend')+from utils.paths.storage_roots import setup_cache_env+setup_cache_env()+" >/dev/null 2>&1+dbs="$(find "$ROOT_B" "$HOME_B" -name '*.db' 2>/dev/null | wc -l)"+[ "$dbs" = 0 ] && check "seeding creates no database" 0 || check "seeding creates no database" 1 "found $dbs"+outside="$(find "$HOME_B" -mindepth 1 2>/dev/null | wc -l)"+[ "$outside" = 0 ] && check "seeding writes nothing to HOME" 0 \+ || check "seeding writes nothing to HOME" 1 "$(find "$HOME_B" -mindepth 1 | head -5 | tr '\n' ' ')"++echo+echo "[5] seeding is idempotent and cheap on repeat"+t0=$(date +%s%N)+env -i HOME="$HOME_B" PATH="/usr/bin:/bin" UNSLOTH_HOME="$ROOT_B" "$PY" -c "+import sys+sys.path.insert(0, '$REPO/studio/backend')+from utils.paths.storage_roots import setup_cache_env+for _ in range(50):+ setup_cache_env()+" >/dev/null 2>&1+t1=$(date +%s%N)+ms=$(( (t1 - t0) / 1000000 ))+[ "$ms" -lt 20000 ] && check "50 repeat seedings in ${ms}ms" 0 || check "50 repeat seedings too slow (${ms}ms)" 1++echo+echo "[6] resolver survives a missing HOME entirely"+out6="$(env -i PATH="/usr/bin:/bin" UNSLOTH_HOME="$WORK/root_c" "$PY" -c "+import sys+sys.path.insert(0, '$REPO/studio/backend')+from utils.paths import storage_roots as sr+print(sr.studio_root())+" 2>&1 | tail -1)"+case "$out6" in+ "$WORK/root_c/studio") check "no HOME set still resolves the portable root" 0 ;;+ *) check "no HOME set still resolves the portable root" 1 "$out6" ;;+esac++echo+if [ "$fails" -ne 0 ]; then echo "$fails check(s) failed"; exit 1; fi+echo "All isolated-venv checks passed"diff --git a/tests/sh/test_setup_staged_root.sh b/tests/sh/test_setup_staged_root.shindex bb8edb54511..3a89216a109 100755--- a/tests/sh/test_setup_staged_root.sh+++ b/tests/sh/test_setup_staged_root.sh@@ -98,8 +98,18 @@ check "setup.ps1 does not install Git while staging" \"$(has "$SETUP_PS1" 'Background staging cannot install Git; retry with the foreground updater.')"check "setup.ps1 preserves foreground Git bootstrap" \"$(has "$SETUP_PS1" 'if ($gitNeeded -or -not $StageRoot) {')"+# The branch that decides TORCHINDUCTOR_CACHE_DIR, by what it does rather than by its old+# spelling: a staged run must take the stage root and must be asked FIRST, ahead of the Studio+# cache and the short drive-root fallback that a normal install chooses between.+_tcd="$(awk '/^\$TorchCacheDir = \$null$/{g=1} g{print} g && /^\$env:TORCHINDUCTOR_CACHE_DIR/{exit}' "$SETUP_PS1")"check "setup.ps1 keeps the staging compiler cache under the stage root" \- "$(has "$SETUP_PS1" 'if ($StageRoot -or $LongPathsEnabled) {')"+ "$(printf '%s' "$_tcd" | grep -qF 'if ($StageRoot) {' \+ && printf '%s' "$_tcd" | grep -qF '$TorchCacheDir = Join-Path $RuntimeRoot "TORCHINDUCTOR_CACHE_DIR"' \+ && echo 0 || echo 1)"+check "setup.ps1 asks about staging before anything else" \+ "$([ "$(printf '%s' "$_tcd" | grep -n 'if ($StageRoot) {' | cut -d: -f1)" -lt \+ "$(printf '%s' "$_tcd" | grep -n 'LongPathsEnabled' | head -1 | cut -d: -f1)" ] \+ && echo 0 || echo 1)"# ── the staged activation cannot dot-source a copied Activate script ──# A venv copied out of $STUDIO_HOME still names the original root in its activatediff --git a/tests/sh/test_uninstall_master_root.sh b/tests/sh/test_uninstall_master_root.shnew file mode 100755index 00000000000..e642818f4fb--- /dev/null+++ b/tests/sh/test_uninstall_master_root.sh@@ -0,0 +1,320 @@+#!/bin/bash+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0+# Unit test for UNSLOTH_HOME master-root removal in scripts/uninstall.sh.+#+# setup.sh and setup.ps1 install llama.cpp, node and whisper.cpp as CHILDREN of the master+# root, beside studio/, so removing the Studio root alone strands multi-gigabyte trees. The+# root is user-chosen, so only a tree carrying the Unsloth owner marker may be deleted.+# Hermetic, following test_uninstall_sd_cpp_custom_root.sh: the real helpers and the real+# removal block are extracted from uninstall.sh and run against per-test fixtures.+set -e++SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"+UNINSTALL_SH="$SCRIPT_DIR/../../scripts/uninstall.sh"+PASS=0+FAIL=0++_TMP_ROOT=$(mktemp -d)+trap 'rm -rf "$_TMP_ROOT"' EXIT+HOME="$_TMP_ROOT/home"+mkdir -p "$HOME"++assert_nodir() { _l="$1"; [ -e "$2" ] && { echo " FAIL: $_l (still present: $2)"; FAIL=$((FAIL+1)); } || { echo " PASS: $_l"; PASS=$((PASS+1)); }; }+assert_dir() { _l="$1"; [ -e "$2" ] && { echo " PASS: $_l"; PASS=$((PASS+1)); } || { echo " FAIL: $_l (missing $2)"; FAIL=$((FAIL+1)); }; }+assert_link() { _l="$1"; [ -L "$2" ] && { echo " PASS: $_l"; PASS=$((PASS+1)); } || { echo " FAIL: $_l (link missing $2)"; FAIL=$((FAIL+1)); }; }+# -e is false for a dangling symlink, which is exactly the shape one case below is about.+assert_present() { _l="$1"; { [ -e "$2" ] || [ -L "$2" ]; } && { echo " PASS: $_l"; PASS=$((PASS+1)); } || { echo " FAIL: $_l (missing $2)"; FAIL=$((FAIL+1)); }; }+assert_eq() { _l="$1"; [ "$2" = "$3" ] && { echo " PASS: $_l"; PASS=$((PASS+1)); } || { echo " FAIL: $_l (got '$2', want '$3')"; FAIL=$((FAIL+1)); }; }++HELPERS_FILE=$(mktemp -p "$_TMP_ROOT")+{+ sed -n '/^_remove_path() {/,/^}/p' "$UNINSTALL_SH"+ sed -n '/^_remove_lock_file() {/,/^}/p' "$UNINSTALL_SH"+ sed -n '/^_is_unsafe_root() {/,/^}/p' "$UNINSTALL_SH"+ sed -n '/^_master_root() {/,/^}/p' "$UNINSTALL_SH"+ sed -n '/^_set_marker() {/,/^}/p' "$UNINSTALL_SH"+} > "$HELPERS_FILE"+# Every helper the block calls, by name. A helper that stops being extracted goes "command not+# found" inside a subshell the harness already swallows, which reads as "nothing was removed"+# and passes the keep-assertions while failing the remove-assertions for the wrong reason.+for _h in _remove_path _remove_lock_file _is_unsafe_root _master_root _set_marker; do+ grep -q "^$_h() {" "$HELPERS_FILE" || { echo "FAIL: helpers missing $_h"; exit 1; }+done++# The real block, anchored on its own first line so a rename fails loudly instead of vacuously.+BLOCK_FILE=$(mktemp -p "$_TMP_ROOT")+sed -n '/^[[:space:]]*_mr_root="\$_MASTER_ROOT_SAVED"/,/^[[:space:]]*# end master-root children$/p' "$UNINSTALL_SH" > "$BLOCK_FILE"+[ -s "$BLOCK_FILE" ] || { echo "FAIL: master-root removal block not extracted"; exit 1; }+grep -q 'unsloth-studio-owned' "$BLOCK_FILE" || { echo "FAIL: extracted block lost the marker gate"; exit 1; }++run_block() {+ # The real script resolves the master root ONCE before anything is removed, because the note+ # it can read lives inside a tree the custom-root loop deletes. The block takes that saved+ # value, so the harness has to seed it the same way.+ ( set -e; HOME="$1"; UNSLOTH_HOME="$2"; export HOME UNSLOTH_HOME+ . "$HELPERS_FILE"; _MASTER_ROOT_SAVED="$(_master_root)"; . "$BLOCK_FILE" ) || true+}++echo "== an owned master root loses its runtime children =="+MR="$_TMP_ROOT/portable"+mkdir -p "$MR"/{studio,llama.cpp,node,whisper.cpp}+for d in llama.cpp node whisper.cpp; do : > "$MR/$d/.unsloth-studio-owned"; done+: > "$MR/.llama.cpp.install.lock"+: > "$MR/.node.install.lock"+run_block "$HOME" "$MR"+assert_nodir "llama.cpp removed" "$MR/llama.cpp"+assert_nodir "node removed" "$MR/node"+assert_nodir "whisper.cpp removed" "$MR/whisper.cpp"+assert_nodir "llama lock removed" "$MR/.llama.cpp.install.lock"+assert_nodir "node lock removed" "$MR/.node.install.lock"+assert_dir "studio root left to the Studio removal" "$MR/studio"++echo "== only a FILE is removed from an install-lock path =="+# prebuilt_core.install_lock creates the lock with os.open(O_CREAT | O_EXCL), so it is always a+# regular file. The names are fixed, so in a user-chosen root a directory here is the user's:+# rm -rf on it would take a tree that never carried the owner marker the children above need.+MRL="$_TMP_ROOT/lockshapes"+mkdir -p "$MRL/studio" "$MRL/.node.install.lock/keep"+: > "$MRL/.node.install.lock/keep/user-file"+: > "$MRL/.llama.cpp.install.lock"+# A link at a lock name is the user's too: O_CREAT | O_EXCL never makes one, and+# uninstall.ps1 already excluded reparse points, so unlinking it here was the two halves of+# one rule disagreeing. Two shapes, since a link to a file is -f and a dangling one is not.+ln -s "$MRL/.llama.cpp.install.lock" "$MRL/.whisper.cpp.install.lock"+ln -s "$MRL/nowhere" "$MRL/.sd.cpp.install.lock"+: > "$MRL/.sd.cpp.install.lock.stale.4242"+run_block "$HOME" "$MRL"+assert_nodir "a real lock file is removed" "$MRL/.llama.cpp.install.lock"+assert_nodir "a stale lock file is removed" "$MRL/.sd.cpp.install.lock.stale.4242"+assert_link "a linked lock is kept" "$MRL/.whisper.cpp.install.lock"+assert_link "a dangling linked lock is kept too" "$MRL/.sd.cpp.install.lock"+assert_dir "a directory at a lock path is kept" "$MRL/.node.install.lock"+assert_dir "and so is everything under it" "$MRL/.node.install.lock/keep/user-file"++echo "== an unmarked tree is somebody else's and is kept =="+MR2="$_TMP_ROOT/mixed"+mkdir -p "$MR2"/{llama.cpp,node}+: > "$MR2/node/.unsloth-studio-owned"+: > "$MR2/llama.cpp/my-own-build"+run_block "$HOME" "$MR2"+assert_dir "unmarked llama.cpp kept" "$MR2/llama.cpp"+assert_dir "its contents kept" "$MR2/llama.cpp/my-own-build"+assert_nodir "marked node removed" "$MR2/node"++echo "== an emptied master root is pruned, a used one is not =="+MR3="$_TMP_ROOT/empty-after"+mkdir -p "$MR3/node"+: > "$MR3/node/.unsloth-studio-owned"+run_block "$HOME" "$MR3"+assert_nodir "empty master root pruned" "$MR3"+MR4="$_TMP_ROOT/still-used"+mkdir -p "$MR4/node" "$MR4/my-datasets"+: > "$MR4/node/.unsloth-studio-owned"+run_block "$HOME" "$MR4"+assert_dir "master root with user files kept" "$MR4"+assert_dir "the user's files kept" "$MR4/my-datasets"++echo "== the value is stripped and tilde-expanded, like the installers =="+MR5="$HOME/tilde-root"+mkdir -p "$MR5/node"+: > "$MR5/node/.unsloth-studio-owned"+run_block "$HOME" " ~/tilde-root "+assert_nodir "padded tilde value resolved" "$MR5/node"++echo "== a shared .staging keeps whatever is not ours =="+MR6="$_TMP_ROOT/staged"+mkdir -p "$MR6/node" "$MR6/.staging/somebody-elses"+: > "$MR6/node/.unsloth-studio-owned"+run_block "$HOME" "$MR6"+assert_dir "a non-empty .staging is kept whole" "$MR6/.staging/somebody-elses"+MR7="$_TMP_ROOT/staged-empty"+mkdir -p "$MR7/node" "$MR7/.staging"+: > "$MR7/node/.unsloth-studio-owned"+run_block "$HOME" "$MR7"+assert_nodir "an empty .staging is pruned" "$MR7/.staging"++echo "== an unset or default root selects nothing =="+got=$( ( HOME="$HOME"; export HOME; unset UNSLOTH_HOME; . "$HELPERS_FILE"; _master_root ) )+assert_eq "unset UNSLOTH_HOME yields nothing" "$got" ""+got=$( ( HOME="$HOME"; UNSLOTH_HOME=" "; export HOME UNSLOTH_HOME; . "$HELPERS_FILE"; _master_root ) )+assert_eq "blank UNSLOTH_HOME yields nothing" "$got" ""+mkdir -p "$HOME/.unsloth"+got=$( ( HOME="$HOME"; UNSLOTH_HOME="$HOME/.unsloth"; export HOME UNSLOTH_HOME; . "$HELPERS_FILE"; _master_root ) )+assert_eq "the default root is left to the blocks that own it" "$got" ""++echo "== a deny-listed root is refused =="+got=$( ( HOME="$HOME"; UNSLOTH_HOME="/"; export HOME UNSLOTH_HOME; . "$HELPERS_FILE"; _master_root ) )+assert_eq "/ yields nothing" "$got" ""++echo "== a root that is gone does not end the uninstall =="+# Under set -e the canonicalizing `cd` fails whenever the root is absent (a second uninstall, a+# portable install on an unplugged drive) and a bare assignment takes that exit status. bash+# hides it by clearing errexit inside command substitution, so this runs the shells the+# advertised `| sh` one-liner reaches. REACHED_END is the assertion, not the value returned.+for _shell in dash "bash --posix" sh; do+ command -v ${_shell%% *} > /dev/null 2>&1 || continue+ # || true: this harness runs under set -e too, so without it the failing child takes the+ # whole test file down and the check below never reports which shell broke.+ out=$( env -i HOME="$HOME" PATH="$PATH" UNSLOTH_HOME="$_TMP_ROOT/never-existed" \+ $_shell -c "set -e; . \"$HELPERS_FILE\"; r=\$(_master_root); echo REACHED_END" 2>&1 \+ || true )+ assert_eq "$_shell keeps going past a missing root" "$out" "REACHED_END"+done++echo "== a dangling runtime symlink is not ours to unlink =="+# -e is false for a dangling symlink, so an unmarked one named llama.cpp fell past the marker+# gate into _remove_path, which treats -L as present and removes the link. Its target volume+# being unmounted is the ordinary reason, and the link is the user's.+MRD="$_TMP_ROOT/dangling"+mkdir -p "$MRD/studio" "$MRD/node"+: > "$MRD/node/.unsloth-studio-owned"+ln -s "$_TMP_ROOT/no-such-volume/llama.cpp" "$MRD/llama.cpp"+run_block "$HOME" "$MRD"+assert_present "an unmarked dangling link is kept" "$MRD/llama.cpp"+assert_nodir "a marked tree beside it still goes" "$MRD/node"++echo "== a whitespace-only Studio override does not suppress the master root =="+# storage_roots.studio_root() trims these, so " " is unset to every resolver. A bare -n test+# called it present, skipped the master-root branch, and then discarded the whitespace path:+# the runtime siblings went and <UNSLOTH_HOME>/studio stayed.+ROOTS_FILE=$(mktemp -p "$_TMP_ROOT")+sed -n '/^_custom_studio_roots() {/,/^}/p' "$UNINSTALL_SH" > "$ROOTS_FILE" 2>/dev/null || : > "$ROOTS_FILE"+if grep -q '_custom_studio_roots() {' "$ROOTS_FILE"; then+ MRW="$_TMP_ROOT/blankoverride"+ mkdir -p "$MRW/studio"+ got=$( ( HOME="$HOME"; UNSLOTH_HOME="$MRW"; UNSLOTH_STUDIO_HOME=" "+ export HOME UNSLOTH_HOME UNSLOTH_STUDIO_HOME+ . "$HELPERS_FILE"+ _emit() { printf '%s\n' "$1"; }+ _from_conf() { :; }+ . "$ROOTS_FILE"+ _custom_studio_roots 2>/dev/null ) | grep -c "$MRW/studio" ) || got=0+ assert_eq "a blank override still reaches the master root" "$got" "1"+else+ echo " FAIL: _custom_studio_roots could not be extracted"; FAIL=$((FAIL+1))+fi++echo "== the master root is remembered when the environment does not carry it =="+# `UNSLOTH_HOME=/mnt/portable unsloth studio update` installs the runtimes there and leaves+# nothing behind in the environment. setup.sh writes a note in the Studio tree; without it an+# uninstall later removed the Studio tree and stranded the runtimes.+# The real layout: Studio lives at <master>/studio, and with a bare environment the only thing+# that names that directory is the default-mode studio.conf install.sh wrote.+NOTED="$_TMP_ROOT/noted"+mkdir -p "$HOME/.unsloth/studio/share" "$NOTED/studio/share" "$HOME/.local/share/unsloth"+printf "UNSLOTH_EXE='%s'\n" "$NOTED/studio/unsloth_studio/bin/unsloth" \+ > "$HOME/.local/share/unsloth/studio.conf"+printf '%s\n' "$NOTED" > "$NOTED/studio/share/.unsloth-master-root"+got=$( ( HOME="$HOME"; unset UNSLOTH_HOME; export HOME; . "$HELPERS_FILE"; _master_root ) )+assert_eq "the note names the master root" "$got" "$NOTED"+# The environment still outranks it, and the deny list still applies to whatever it names.+got=$( ( HOME="$HOME"; UNSLOTH_HOME="$_TMP_ROOT/from-env"; export HOME UNSLOTH_HOME+ . "$HELPERS_FILE"; _master_root ) )+assert_eq "the environment outranks the note" "$got" "$_TMP_ROOT/from-env"+printf '%s\n' "$HOME/.unsloth" > "$NOTED/studio/share/.unsloth-master-root"+got=$( ( HOME="$HOME"; unset UNSLOTH_HOME; export HOME; . "$HELPERS_FILE"; _master_root ) )+assert_eq "a note naming the default root is still refused" "$got" ""+# A tree copied from one master root to another keeps a note naming the ORIGINAL, whose+# runtimes carry the same owner markers the copy's would, so accepting it would authorise+# deleting the original install's llama.cpp, node and whisper.cpp.+COPIED="$_TMP_ROOT/copied"+mkdir -p "$COPIED/studio/share"+printf '%s\n' "$NOTED" > "$COPIED/studio/share/.unsloth-master-root"+got=$( ( HOME="$HOME"; unset UNSLOTH_HOME; UNSLOTH_STUDIO_HOME="$COPIED/studio"+ export HOME UNSLOTH_STUDIO_HOME; . "$HELPERS_FILE"; _master_root ) )+assert_eq "a note carried in from another master root is refused" "$got" ""+rm -f "$NOTED/studio/share/.unsloth-master-root" "$HOME/.local/share/unsloth/studio.conf"++echo "== a named Studio root does not borrow another install's note =="+# Two installs on one box, the legacy tree carrying a note and the named one not: probing the+# legacy path first let its note win here while the removal worked on the named tree, so the run+# deleted one Studio and the OTHER install's runtime children.+BORROWED="$_TMP_ROOT/borrowed"+NAMED_MASTER="$_TMP_ROOT/named-master"+NAMED="$NAMED_MASTER/studio"+mkdir -p "$HOME/.unsloth/studio/share" "$BORROWED/studio" "$NAMED/share"+printf '%s\n' "$BORROWED" > "$HOME/.unsloth/studio/share/.unsloth-master-root"+got=$( ( HOME="$HOME"; unset UNSLOTH_HOME; UNSLOTH_STUDIO_HOME="$NAMED"+ export HOME UNSLOTH_STUDIO_HOME; . "$HELPERS_FILE"; _master_root ) )+assert_eq "an unrelated install's note is not adopted" "$got" ""+# The alias is the same rule, and the named root's OWN note is still read.+printf '%s\n' "$NAMED_MASTER" > "$NAMED/share/.unsloth-master-root"+got=$( ( HOME="$HOME"; unset UNSLOTH_HOME UNSLOTH_STUDIO_HOME; STUDIO_HOME="$NAMED"+ export HOME STUDIO_HOME; . "$HELPERS_FILE"; _master_root ) )+assert_eq "the named root's own note is still read" "$got" "$NAMED_MASTER"+rm -f "$HOME/.unsloth/studio/share/.unsloth-master-root" "$NAMED/share/.unsloth-master-root"++echo "== a padded Studio override still finds the note setup.sh wrote =="+# setup.sh trims UNSLOTH_STUDIO_HOME before choosing where to write, so appending to the padded+# value looked somewhere that does not exist: the note was never found, while the removal loop+# trimmed the same override and stranded the master-root runtimes.+PADDED_MASTER="$_TMP_ROOT/padded-master"+PADDED="$PADDED_MASTER/studio"+mkdir -p "$PADDED/share"+printf '%s\n' "$PADDED_MASTER" > "$PADDED/share/.unsloth-master-root"+got=$( ( HOME="$HOME"; unset UNSLOTH_HOME; UNSLOTH_STUDIO_HOME=" $PADDED "+ export HOME UNSLOTH_STUDIO_HOME; . "$HELPERS_FILE"; _master_root ) )+assert_eq "a padded override finds the note" "$got" "$PADDED_MASTER"+got=$( ( HOME="$HOME"; unset UNSLOTH_HOME UNSLOTH_STUDIO_HOME; STUDIO_HOME=" $PADDED "+ export HOME STUDIO_HOME; . "$HELPERS_FILE"; _master_root ) )+assert_eq "the padded alias finds it too" "$got" "$PADDED_MASTER"++echo "== only the installer's own stale locks are swept =="+# prebuilt_core.py moves a lock aside as <name>.stale.<pid>. A bare .*.install.lock.stale.* glob+# also matched an unrelated hidden file, and in a root the user chose that file is theirs.+STALE="$_TMP_ROOT/stale-root"+mkdir -p "$STALE"+: > "$STALE/.node.install.lock.stale.4242"+: > "$STALE/.backup.install.lock.stale.copy"+: > "$STALE/.llama.cpp.install.lock.stale.notapid"+run_block "$HOME" "$STALE"+assert_nodir "the installer's own stale lock goes" "$STALE/.node.install.lock.stale.4242"+assert_present "an unrelated hidden file stays" "$STALE/.backup.install.lock.stale.copy"+assert_present "a non-numeric suffix stays" "$STALE/.llama.cpp.install.lock.stale.notapid"++echo "== a note with a second line is refused, as the comment beside it promises =="+# The four readers have to agree, and this is the one that authorises a delete: the two Python+# readers strip the WHOLE file, so a two-line note is not a directory to them, while taking+# line 1 here licensed removing <master>/llama.cpp, node, whisper.cpp and sd.cpp.+MULTI_MASTER="$_TMP_ROOT/multiline-master"+MULTI="$MULTI_MASTER/studio"+mkdir -p "$MULTI/share" "$_TMP_ROOT/elsewhere"+printf '%s\n%s\n' "$MULTI_MASTER" "$_TMP_ROOT/elsewhere" > "$MULTI/share/.unsloth-master-root"+got=$( ( HOME="$HOME"; unset UNSLOTH_HOME; UNSLOTH_STUDIO_HOME="$MULTI"+ export HOME UNSLOTH_STUDIO_HOME; . "$HELPERS_FILE"; _master_root ) )+assert_eq "a two-line note names no master root" "$got" ""++# ... and a blank second line is just the trailing newline of an ordinary note.+printf '%s\n\n' "$MULTI_MASTER" > "$MULTI/share/.unsloth-master-root"+got=$( ( HOME="$HOME"; unset UNSLOTH_HOME; UNSLOTH_STUDIO_HOME="$MULTI"+ export HOME UNSLOTH_STUDIO_HOME; . "$HELPERS_FILE"; _master_root ) )+assert_eq "a trailing blank line is still one line" "$got" "$MULTI_MASTER"++# The ordinary note must keep working, or the check above proves only that nothing is read.+printf '%s\n' "$MULTI_MASTER" > "$MULTI/share/.unsloth-master-root"+got=$( ( HOME="$HOME"; unset UNSLOTH_HOME; UNSLOTH_STUDIO_HOME="$MULTI"+ export HOME UNSLOTH_STUDIO_HOME; . "$HELPERS_FILE"; _master_root ) )+assert_eq "a one-line note is still honoured" "$got" "$MULTI_MASTER"++echo "== a note in the legacy tree cannot aim the uninstall at a second install =="+# The legacy install carries a note naming $HOME, which setup used to accept: the profile+# CONTAINS ~/.unsloth/studio, so containment passed and the value is not the legacy root.+# _custom_studio_roots then emitted "$HOME/studio", and a SECOND marked install kept there was+# accepted as a Studio root to remove, taking its database and outputs. The deny list does not+# catch it: it refuses $HOME as a master root, not the Studio candidate derived from it.+# storage_roots._is_legacy_studio_tree and the CLI decline that note outright; so must this.+LEGACY_HOME="$_TMP_ROOT/legacy-note-home"+mkdir -p "$LEGACY_HOME/.unsloth/studio/share"+printf '%s\n' "$LEGACY_HOME" > "$LEGACY_HOME/.unsloth/studio/share/.unsloth-master-root"+mkdir -p "$LEGACY_HOME/studio/share" "$LEGACY_HOME/studio/outputs"+: > "$LEGACY_HOME/studio/.unsloth-studio-owned"+: > "$LEGACY_HOME/studio/studio.db"+got=$( ( HOME="$LEGACY_HOME"; unset UNSLOTH_HOME UNSLOTH_STUDIO_HOME STUDIO_HOME+ export HOME; . "$HELPERS_FILE"; _master_root ) )+assert_eq "a legacy-tree note names no master root" "$got" ""+assert_dir "the second install is untouched" "$LEGACY_HOME/studio/studio.db"++echo+echo "PASS=$PASS FAIL=$FAIL"+[ "$FAIL" -eq 0 ]diff --git a/tests/sh/test_uninstall_sd_cpp_custom_root.sh b/tests/sh/test_uninstall_sd_cpp_custom_root.shindex 4b06cfb5a3f..f740f1cfde5 100755--- a/tests/sh/test_uninstall_sd_cpp_custom_root.sh+++ b/tests/sh/test_uninstall_sd_cpp_custom_root.sh@@ -33,6 +33,10 @@ HELPERS_FILE=$(mktemp -p "$_TMP_ROOT")sed -n '/^_is_venv_dir() {/,/^}/p' "$UNINSTALL_SH"sed -n '/^_is_studio_root() {/,/^}/p' "$UNINSTALL_SH"sed -n '/^_is_unsafe_root() {/,/^}/p' "$UNINSTALL_SH"+ # The loop now asks whether the Studio root is also the master root before removing it+ # whole, so this helper has to come across or the block dies on "command not found" and+ # every keep-assertion passes for the wrong reason.+ sed -n '/^_master_root() {/,/^}/p' "$UNINSTALL_SH"# The loop removes roots through this wrapper; without it and its marker helper the# fragment dies with "command not found" and every assertion below is vacuous.sed -n '/^_set_marker() {/,/^}/p' "$UNINSTALL_SH"@@ -45,7 +49,7 @@ HELPERS_FILE=$(mktemp -p "$_TMP_ROOT")} > "$HELPERS_FILE"grep -q '_owned_sd_cpp_roots' "$HELPERS_FILE" || { echo "FAIL: helpers missing _owned_sd_cpp_roots"; exit 1; }# _is_studio_root's own helpers, or every root reads as foreign and nothing below is removed.-for _needed in _is_owner_marker _is_venv_dir _restore_owner_marker; do+for _needed in _is_owner_marker _is_venv_dir _restore_owner_marker _master_root; dogrep -q "^$_needed() {" "$HELPERS_FILE" || { echo "FAIL: helpers missing $_needed"; exit 1; }donegrep -q '_sd_cpp_sibling_bases() {' "$HELPERS_FILE" || { echo "FAIL: helpers missing _sd_cpp_sibling_bases"; exit 1; }diff --git a/tests/sh/test_with_llama_cpp_dir_link_behavior.sh b/tests/sh/test_with_llama_cpp_dir_link_behavior.shindex 2d87b7f5416..0e8fac1c637 100644--- a/tests/sh/test_with_llama_cpp_dir_link_behavior.sh+++ b/tests/sh/test_with_llama_cpp_dir_link_behavior.sh@@ -41,6 +41,11 @@ setup_fail() { exit "$1"; }_assert_studio_owned_or_absent() { :; }C_ERR=""_STUDIO_HOME_IS_CUSTOM=false+# The runtime children took their own ownership flag when UNSLOTH_HOME arrived: with no master+# root it carries _STUDIO_HOME_IS_CUSTOM, which is what this fixture is about. Unseeded it is an+# unbound variable under set -u, and the block dies before printing anything, which reads here as+# every state assertion getting an empty value rather than as a broken harness.+_RUNTIME_ROOT_IS_CUSTOM=false_NEED_LLAMA_SOURCE_BUILD=UNSET_SKIP_PREBUILT_INSTALL=UNSET'@@ -54,10 +59,23 @@ SNIP="$PREAMBLE"$'\n'"$block"$'\n'"$EPILOGUE"# run_link <local_dir> <canonical_llama_cpp_dir> -> prints state lines; RC in $RCrun_link() {+ # stderr kept on failure: the block runs under set -u, so a variable this preamble does not+ # seed kills it silently and every val() below returns empty. That looked like seven wrong+ # answers rather than one missing seed, so say which it is.OUT="$(env -i PATH="$PATH" HOME="$T" \UNSLOTH_LOCAL_LLAMA_CPP_DIR="$1" LLAMA_CPP_DIR="$2" \- bash -c "$SNIP" 2>/dev/null)"+ bash -c "$SNIP" 2>"$T/.stderr")"RC=$?+ # Only when the block claims it succeeded: some fixtures below expect setup_fail, and those+ # legitimately exit before the epilogue.+ if [ "$RC" -eq 0 ]; then+ case "$OUT" in+ *LINKED=*) : ;;+ *) echo "FAIL: the block exited 0 and printed no state; stderr was:" >&2+ sed 's/^/ /' "$T/.stderr" >&2+ exit 1 ;;+ esac+ fi}val() { printf '%s\n' "$OUT" | grep "^$1=" | head -1 | cut -d= -f2-; }diff --git a/tests/studio/install/test_denied_llama_cpp_preflight.py b/tests/studio/install/test_denied_llama_cpp_preflight.pyindex 0d3769c1c42..9d7f278cb27 100644--- a/tests/studio/install/test_denied_llama_cpp_preflight.py+++ b/tests/studio/install/test_denied_llama_cpp_preflight.py@@ -34,6 +34,7 @@ SHARED_FUNCTIONS = ("Write-PathAccessDenied","Get-CanonicalDir","Test-StudioHomeIsCustom",+ "Get-MasterRootOverride","Get-ManagedLlamaCppDir","Invoke-ManagedLlamaCppPreflight",)@@ -216,11 +217,12 @@ def test_a_custom_studio_home_is_never_called_a_cache_we_own() -> None:"""Do not call an unreadable custom Unsloth home a managed cache."""body = _function_source(INSTALL_PS1, "Invoke-ManagedLlamaCppPreflight")# Use the same predicate for path selection and ownership wording.- assert "$homeIsCustom = Test-StudioHomeIsCustom" in body+ # A master root counts as custom too: it moves llama.cpp out of the default location.+ assert "$homeIsCustom = (Test-StudioHomeIsCustom) -or [bool](Get-MasterRootOverride)" in bodyassert "-OwnershipUnverified:$homeIsCustom" in bodyassert ('Exit-PathAccessDenied -Path $LlamaCppDir -Label "llama.cpp install"'- " -OwnershipUnverified:$StudioHomeIsCustom" in SETUP_PS1+ " -OwnershipUnverified:$RuntimeRootIsCustom" in SETUP_PS1)diff --git a/tests/studio/install/test_install_llama_prebuilt_logic.py b/tests/studio/install/test_install_llama_prebuilt_logic.pyindex 0d69b451a95..9bebda1f0b0 100644--- a/tests/studio/install/test_install_llama_prebuilt_logic.py+++ b/tests/studio/install/test_install_llama_prebuilt_logic.py@@ -4408,6 +4408,7 @@ _LLAMA_CPP_NO_SPACE=false_LLAMA_CPP_DEGRADED=false_explicit_llama_backend=""_STUDIO_HOME_IS_CUSTOM=false+_RUNTIME_ROOT_IS_CUSTOM=false_STUDIO_OWNED_MARKER=".unsloth-owned"step() { echo "step: $2"; }substep() { echo "substep: $1"; }diff --git a/tests/studio/install/test_pr10648_offline_and_status.py b/tests/studio/install/test_pr10648_offline_and_status.pyindex ae244b0a89b..11f81226054 100644--- a/tests/studio/install/test_pr10648_offline_and_status.py+++ b/tests/studio/install/test_pr10648_offline_and_status.py@@ -720,6 +720,9 @@ _LLAMA_CPP_NO_SPACE=false_LLAMA_CPP_DEGRADED=false_explicit_llama_backend=""_STUDIO_HOME_IS_CUSTOM=false+# The flag the runtime children switched to when UNSLOTH_HOME arrived: the guards inside the+# extracted block read it, and setup.sh derives it in the section this harness stands in for.+_RUNTIME_ROOT_IS_CUSTOM=false_STUDIO_OWNED_MARKER=".unsloth-owned"_WHISPER_RECOVERED=falsestep() { echo "step|$1|$2"; }@@ -737,6 +740,8 @@ $ErrorActionPreference = "Stop"$NeedLlamaSourceBuild = $false$script:LlamaCppDegraded = $false$StudioHomeIsCustom = $false+# Same reason as _RUNTIME_ROOT_IS_CUSTOM in the shell harness above.+$RuntimeRootIsCustom = $falsefunction step { param($a, $b, $c) Write-Output "step|$a|$b" }function substep { param($a, $b) Write-Output "substep|$a" }function Write-LlamaFailureLog { param($Output) }diff --git a/tests/studio/install/test_selection_logic.py b/tests/studio/install/test_selection_logic.pyindex faa1af5a8ec..2b848b4b2bb 100644--- a/tests/studio/install/test_selection_logic.py+++ b/tests/studio/install/test_selection_logic.py@@ -94,10 +94,19 @@ def load_studio_run_module(monkeypatch):startup_banner.stdout_supports_color = lambda: Falsemonkeypatch.setitem(sys.modules, "startup_banner", startup_banner)+ # run.py exports UNSLOTH_STUDIO_HOME and UNSLOTH_LLAMA_CPP_PATH at module scope and this+ # helper execs it in-process, so without monkeypatch they outlive the test.+ for _leaked in ("UNSLOTH_STUDIO_HOME", "UNSLOTH_LLAMA_CPP_PATH"):+ monkeypatch.setenv(_leaked, os.environ.get(_leaked, ""))+ monkeypatch.delenv(_leaked)+paths = types.ModuleType("utils.paths")paths.__path__ = []storage_roots = types.ModuleType("utils.paths.storage_roots")storage_roots.studio_root = lambda: PACKAGE_ROOT / ".studio-test-root"+ # Imported at module scope too, so the stub carries it. None keeps these tests on the+ # legacy-default path they were written for.+ storage_roots.unsloth_home = lambda: Nonepaths.storage_roots = storage_rootsmonkeypatch.setitem(sys.modules, "utils.paths", paths)monkeypatch.setitem(sys.modules, "utils.paths.storage_roots", storage_roots)diff --git a/tests/studio/install/test_setup_denied_install_tree.py b/tests/studio/install/test_setup_denied_install_tree.pyindex e39f1ca64b7..a4d1d8300bd 100644--- a/tests/studio/install/test_setup_denied_install_tree.py+++ b/tests/studio/install/test_setup_denied_install_tree.py@@ -75,7 +75,9 @@ def test_every_denial_route_reports_instead_of_proceeding():assert '$llamaGitState = Get-PathState -Path (Join-Path $LlamaCppDir ".git")' in SETUP_PS1assert '$llamaGitState -eq "Denied"' in SETUP_PS1assert "$pathState = Get-PathState -Path $Path -PathType Container" in SETUP_PS1- assert '$StudioHomeIsCustom -and $pathState -eq "Denied"' in SETUP_PS1+ # $isCustomRoot is the parameter form of $StudioHomeIsCustom: the runtime children pass+ # $RuntimeRootIsCustom, which a master root widens, and it defaults to the other flag.+ assert '$isCustomRoot -and $pathState -eq "Denied"' in SETUP_PS1# The junction path replaces this destination, so it needs its own stop.assert "$destState = Get-PathState -Path $LlamaCppDir" in SETUP_PS1assert '$destState -eq "Denied"' in SETUP_PS1@@ -129,7 +131,8 @@ def test_ownership_guard_distinguishes_denied_from_unowned():# genuinely-unowned case only.assert "is not marked as an Unsloth-owned $Label" in guard# Both stops stay gated, so default-home installs behave exactly as before.- assert guard.count("$StudioHomeIsCustom -and") >= 3+ assert "$isCustomRoot = $StudioHomeIsCustom" in guard+ assert guard.count("$isCustomRoot -and") >= 3def test_no_bare_test_path_probes_inside_the_llama_install_tree():@@ -321,7 +324,7 @@ def test_the_source_build_denial_never_advises_deleting_an_unproven_tree():block = _slice("$llamaBinState = ", "$WillBuildLlamaFromSource")denials = [ln.strip() for ln in block.splitlines() if "Exit-PathAccessDenied" in ln]assert len(denials) >= 2, denials- assert all(d.endswith("-OwnershipUnverified:$StudioHomeIsCustom") for d in denials), denials+ assert all(d.endswith("-OwnershipUnverified:$RuntimeRootIsCustom") for d in denials), denialsassert all(d.startswith("Exit-PathAccessDenied -Path $LlamaCppDir ") for d in denials), denials@@ -368,10 +371,13 @@ def test_the_whisper_phase_survives_an_unreadable_whisper_tree():# Only the denial is handed back; an unowned tree must still stop.assert 'Exit-SetupFailure "$Label path is not an Unsloth-owned install' in guardwhisper = _whisper_phase()- assert '-Label "whisper.cpp install" -NonFatal) -eq "Denied"' in whisper, whisper+ assert (+ '-Label "whisper.cpp install" -NonFatal -IsCustom $RuntimeRootIsCustom) -eq "Denied"'+ in whisper+ ), whisper# Scoped to the new branch: both phrases occur elsewhere in the phase, so a# phase-wide match proves nothing about this branch.- marker = '-NonFatal) -eq "Denied") {'+ marker = '-NonFatal -IsCustom $RuntimeRootIsCustom) -eq "Denied") {'assert marker in whisper, whisperdenial = whisper.split(marker, 1)[1].split("\n} elseif", 1)[0]assert re.search(r'^\s*step "whisper\.cpp" ', denial, re.M), denial@@ -389,7 +395,7 @@ def test_the_whisper_phase_survives_an_unreadable_whisper_tree():def test_the_whisper_skip_stays_behind_the_installer_gate():"""The guard used to live inside the installer branch, so a tree without theinstaller was a no-op. Hoisting it must not make that case fatal."""- marker = "-NonFatal) -eq"+ marker = "-NonFatal -IsCustom $RuntimeRootIsCustom) -eq"whisper = _whisper_phase()assert marker in whisper, whisperhead = whisper.split(marker, 1)[0]diff --git a/tests/studio/test_path_probe_access_denied.ps1 b/tests/studio/test_path_probe_access_denied.ps1index 9f49add2d76..e1605db011f 100644--- a/tests/studio/test_path_probe_access_denied.ps1+++ b/tests/studio/test_path_probe_access_denied.ps1@@ -52,7 +52,14 @@ Check "the source-build .git probe stops on a denied checkout" ($setupText -match '\$llamaGitState -eq "Denied"')Check "the ownership guard stops on a denied root instead of returning" ($setupText -match '\$pathState = Get-PathState -Path \$Path -PathType Container' -and- $setupText -match '\$StudioHomeIsCustom -and \$pathState -eq "Denied"')+ $setupText -match '\$isCustomRoot -and \$pathState -eq "Denied"')+# The guard now takes the flag as a parameter, because the runtime children beside studio\ under+# a master root are owned even when the Studio home itself is the legacy one. With no override+# it must still be the script-level flag this file's other checks are about, or the guard would+# be reading something nothing sets.+Check "the guard's flag defaults to the script-level one" (+ $setupText -match '\$isCustomRoot = \$StudioHomeIsCustom' -and+ $setupText -match 'if \(\$null -ne \$IsCustom\) \{ \$isCustomRoot = \[bool\]\$IsCustom \}')Check "guidance says an app reinstall does not reset the folder" ($setupText -match 'reinstalling Unsloth Studio, to any drive, reuses it' -and$setupText -match 'Reinstalling the app does not reset it\.')@@ -445,6 +452,28 @@ if ($assertSrc -and $markSrc) {try { $null = Assert-StudioOwnedOrAbsent -Path $nfUnowned -Label "whisper.cpp install" -NonFatal }catch { $threw = $true; $thrownBy = $_.Exception.Message }Check "-NonFatal does not excuse an unowned tree" ($threw -and $thrownBy -eq "EXIT-SETUP")++ # A non-directory at a runtime path under a user-chosen root. install_llama_prebuilt's+ # activate_install_tree moves aside whatever Path.exists() finds, so a Container-only+ # probe let a user's file be displaced by the install that followed.+ $nfFile = Join-Path $nfRoot "llama.cpp"+ Set-Content -LiteralPath $nfFile -Value "mine"+ $nfLink = Join-Path $nfRoot "node"+ New-Item -ItemType SymbolicLink -Path $nfLink -Target (Join-Path $nfRoot "gone") -ErrorAction SilentlyContinue | Out-Null+ foreach ($shape in @(@("a regular file", $nfFile), @("a dangling link", $nfLink))) {+ if (-not (Get-Item -LiteralPath $shape[1] -Force -ErrorAction SilentlyContinue)) { continue }+ $threw = $false+ $thrownBy = $null+ try { $null = Assert-StudioOwnedOrAbsent -Path $shape[1] -Label "llama.cpp install" -NonFatal }+ catch { $threw = $true; $thrownBy = $_.Exception.Message }+ Check "$($shape[0]) at a custom runtime path stops setup" ($threw -and $thrownBy -eq "EXIT-SETUP")+ # The legacy default home keeps the behaviour it had: only a chosen root is the+ # user's directory, and setup.sh draws the line in the same place.+ $threw = $false+ try { $null = Assert-StudioOwnedOrAbsent -Path $shape[1] -Label "llama.cpp install" -IsCustom $false }+ catch { $threw = $true }+ Check "$($shape[0]) at a default runtime path is left to the caller" (-not $threw)+ }} finally {Set-NfDenied $falseRemove-Item -Recurse -Force -LiteralPath $nfRoot -ErrorAction SilentlyContinue@@ -458,7 +487,7 @@ $installPath = [System.IO.Path]::Combine($repoRoot, "install.ps1")$preflightFns = @("Test-AccessDeniedError", "Get-PathState", "Get-LlamaCppInstallReadState","Get-PathDenialDetail", "Get-SecuritySoftwareNote","Write-PathAccessDenied", "Get-CanonicalDir",- "Test-StudioHomeIsCustom", "Get-ManagedLlamaCppDir",+ "Test-StudioHomeIsCustom", "Get-MasterRootOverride", "Get-ManagedLlamaCppDir","Invoke-ManagedLlamaCppPreflight")$preflightSrc = @()foreach ($fn in $preflightFns) {@@ -466,6 +495,31 @@ foreach ($fn in $preflightFns) {Check "install.ps1 defines $fn" ($null -ne $src)if ($src) { $preflightSrc += $src }}+# Anything the lifted bodies call that install.ps1 defines and the lift then leaves behind,+# other than the stubs the harness supplies. A missing helper does not announce itself: the+# child dies on the first call, every Write-Host after it is lost, and the assertions below+# fail as though the preflight had resolved the wrong directory. This is how+# Get-MasterRootOverride was missed. The test is "install.ps1 defines it", not "this session+# can resolve it": Get-SecuritySoftwareNote reaches Get-CimInstance and Get-MpPreference, which+# exist on the Windows host that runs the preflight and on no Linux runner, so resolvability+# would report those two as unlifted helpers here and nothing at all there.+$harnessStubs = @("step", "substep", "Write-StudioLine")+$preflightCalls = @()+foreach ($src in $preflightSrc) {+ $tokens = [System.Management.Automation.PSParser]::Tokenize($src, [ref]$null)+ foreach ($t in $tokens) {+ if ($t.Type -eq "Command" -and $t.Content -match "^(Get|Test|Invoke|Write|Set|New)-[A-Za-z]+$") {+ $preflightCalls += $t.Content+ }+ }+}+$unlifted = @($preflightCalls | Sort-Object -Unique | Where-Object {+ $_ -notin $preflightFns -and $_ -notin $harnessStubs -and+ $null -ne (Get-FunctionSource -Path $installPath -Name $_)+})+Check ("the preflight lifts every install.ps1 helper it calls" ++ $(if ($unlifted.Count) { " (not lifted: " + ($unlifted -join ", ") + ")" } else { "" })) `+ ($unlifted.Count -eq 0)if ($preflightSrc.Count -eq $preflightFns.Count) {$preflightHarness = @"`$ErrorActionPreference = "Stop"diff --git a/tests/test_installer_system32_guard.py b/tests/test_installer_system32_guard.pyindex bf6f9b91379..34714ac45b2 100644--- a/tests/test_installer_system32_guard.py+++ b/tests/test_installer_system32_guard.py@@ -1036,6 +1036,8 @@ def test_cli_guard_pins_every_storage_root_override_studio_reads():source = storage_roots.read_text(encoding = "utf-8")overrides = set(re.findall(r'environ\.get\(\s*"(UNSLOTH_[A-Z_]*(?:HOME|PATH|DIR))"', source))assert overrides, "no storage root overrides found: has storage_roots.py moved?"+ # Same case: _setup_cache_env fills each only when blank, so a user's relative value survives.+ overrides |= set(re.findall(r'^\s*"([A-Z][A-Z0-9_]*)":\s*str\(', source, re.MULTILINE))missing = sorted(overrides - set(_system_dir_guard._RELATIVE_PATH_ENV))assert not missing, f"relative values of {missing} would be retargeted by the move"diff --git a/tests/test_managed_tools_master_root.py b/tests/test_managed_tools_master_root.pynew file mode 100644index 00000000000..6abdccdc342--- /dev/null+++ b/tests/test_managed_tools_master_root.py@@ -0,0 +1,340 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.++"""UNSLOTH_HOME names the tree, not the Studio directory inside it, and the native runtimes are+siblings of studio/, the spelling studio/setup.sh and scripts/build_whisper_cpp.sh already use. A+resolver deriving them from studio_root() would look in <root>/studio/<tool> for what the+installer put at <root>/<tool>, so managed Node and whisper.cpp go missing and run.py pins the+wrong llama.cpp path into every worker.++Run in a subprocess per case: these modules read the environment at import time.+"""++from __future__ import annotations++import json+import os+import subprocess+import sys+from pathlib import Path++REPO = Path(__file__).resolve().parents[1]+BACKEND = REPO / "studio" / "backend"++PROBE = """+import json, os, sys+sys.path.insert(0, os.environ["_BACKEND"])+from utils.paths import storage_roots as sr+from utils.node_runtime import managed_node_dir+from core.inference.stt_ggml_sidecar import _managed_whisper_cpp_dir++# studio_root() is called constantly, so a warning it emits for a supported+# layout is not one line, it is a flooded log.+_warnings = []+sr.logger.warning = lambda msg, *a, **k: _warnings.append(msg % a if a else msg)++print(json.dumps({+ "studio": str(sr.studio_root()),+ "master": None if sr.unsloth_home() is None else str(sr.unsloth_home()),+ "node": str(managed_node_dir()),+ "whisper": str(_managed_whisper_cpp_dir()),+ "warnings": _warnings,+}))+"""+++def _resolve(env_overrides: dict[str, str], home: Path) -> dict[str, str]:+ env = {+ "PATH": os.environ.get("PATH", "/usr/bin:/bin"),+ "HOME": str(home),+ "USERPROFILE": str(home),+ "_BACKEND": str(BACKEND),+ }+ # A hand-built environment has to carry what the interpreter needs: Windows python exits 1+ # with no usable message when SYSTEMROOT is absent, which read as "the resolver answered+ # wrongly" on every Windows runner.+ for name in ("SYSTEMROOT", "SystemRoot", "COMSPEC", "PATHEXT", "TEMP", "TMP", "WINDIR"):+ value = os.environ.get(name)+ if value:+ env.setdefault(name, value)+ env.update(env_overrides)+ out = subprocess.run([sys.executable, "-c", PROBE], env = env, capture_output = True, text = True)+ # Not check = True: the child's stderr is the only thing that says why, and swallowing it is+ # how a dead interpreter passes for a wrong answer.+ assert out.returncode == 0, f"probe failed ({out.returncode}): {out.stderr.strip()}"+ return json.loads(out.stdout.strip().splitlines()[-1])+++def test_portable_root_puts_the_tools_beside_studio(tmp_path):+ home = tmp_path / "home"+ home.mkdir()+ root = tmp_path / "portable"+ r = _resolve({"UNSLOTH_HOME": str(root)}, home)+ assert r["studio"] == str(root / "studio")+ assert r["master"] == str(root)+ assert r["node"] == str(root / "node")+ assert r["whisper"] == str(root / "whisper.cpp")+++def test_a_default_install_is_untouched(tmp_path):+ home = tmp_path / "home"+ home.mkdir()+ r = _resolve({}, home)+ assert r["master"] is None+ assert r["studio"] == str(home / ".unsloth" / "studio")+ assert r["node"] == str(home / ".unsloth" / "node")+ assert r["whisper"] == str(home / ".unsloth" / "whisper.cpp")+++def test_a_plain_custom_studio_home_is_untouched(tmp_path):+ # No UNSLOTH_HOME: the tools stay children of the Studio root, as before.+ home = tmp_path / "home"+ home.mkdir()+ custom = tmp_path / "custom"+ r = _resolve({"UNSLOTH_STUDIO_HOME": str(custom)}, home)+ assert r["master"] is None+ assert r["studio"] == str(custom)+ assert r["node"] == str(custom / "node")+ assert r["whisper"] == str(custom / "whisper.cpp")+++def test_a_flat_root_keeps_the_tools_at_that_root(tmp_path):+ # UNSLOTH_HOME == UNSLOTH_STUDIO_HOME, so "beside studio/" and "inside it" are one directory.+ home = tmp_path / "home"+ home.mkdir()+ root = tmp_path / "flat"+ r = _resolve({"UNSLOTH_HOME": str(root), "UNSLOTH_STUDIO_HOME": str(root)}, home)+ assert r["studio"] == str(root)+ assert r["node"] == str(root / "node")+ assert r["whisper"] == str(root / "whisper.cpp")+ # Path.parents excludes the path itself, so the equality check is what keeps this warning off.+ assert r["warnings"] == []+++def test_a_studio_home_outside_the_master_root_still_warns(tmp_path):+ home = tmp_path / "home"+ home.mkdir()+ r = _resolve(+ {+ "UNSLOTH_HOME": str(tmp_path / "portable"),+ "UNSLOTH_STUDIO_HOME": str(tmp_path / "elsewhere"),+ },+ home,+ )+ assert any("not self-contained" in w for w in r["warnings"])+++def test_the_builder_and_the_resolver_agree_on_the_same_directory(tmp_path):+ # build_whisper_cpp.sh installs under UNSLOTH_HOME; a resolver one level off reports+ # dictation unavailable with whisper-server sitting right there.+ home = tmp_path / "home"+ home.mkdir()+ root = tmp_path / "portable"+ built = root / "whisper.cpp"+ built.mkdir(parents = True)+ r = _resolve({"UNSLOTH_HOME": str(root)}, home)+ assert r["whisper"] == str(built)+++def _record_note(studio: Path, master: Path) -> None:+ """What setup.sh writes at the end of a master-root install."""+ (studio / "share").mkdir(parents = True, exist_ok = True)+ (studio / "share" / ".unsloth-master-root").write_text(f"{master}\n", encoding = "utf-8")+++def test_a_recorded_master_root_outlives_the_command_that_set_it(tmp_path):+ # UNSLOTH_HOME is settable for one command, which installs node and whisper.cpp BESIDE+ # studio/, and nothing persists it: the next launch resolved both one level down, at+ # <studio>/node and <studio>/whisper.cpp, with the real trees untouched next door.+ home = tmp_path / "home"+ home.mkdir()+ root = tmp_path / "portable"+ studio = root / "studio"+ studio.mkdir(parents = True)+ _record_note(studio, root)+ # UNSLOTH_STUDIO_HOME alone: what the installer's launcher actually persists.+ r = _resolve({"UNSLOTH_STUDIO_HOME": str(studio)}, home)+ assert r["master"] == str(root)+ assert r["studio"] == str(studio)+ assert r["node"] == str(root / "node")+ assert r["whisper"] == str(root / "whisper.cpp")+ assert r["warnings"] == []+++def test_a_note_whose_root_has_since_moved_is_ignored(tmp_path):+ # A note licenses this process to adopt a root for caches and runtimes both. One naming a+ # tree that is no longer there must not win over the layout in front of it.+ home = tmp_path / "home"+ home.mkdir()+ studio = tmp_path / "custom"+ studio.mkdir()+ _record_note(studio, tmp_path / "gone")+ r = _resolve({"UNSLOTH_STUDIO_HOME": str(studio)}, home)+ assert r["master"] is None+ assert r["node"] == str(studio / "node")+++def test_a_note_copied_into_an_unrelated_install_is_ignored(tmp_path):+ # The recorded root exists and has a studio/ child, but it is not THIS install's studio+ # directory, so the note travelled rather than described. Checking only is_dir() would+ # redirect this install's runtimes into someone else's tree.+ home = tmp_path / "home"+ home.mkdir()+ other = tmp_path / "other"+ (other / "studio").mkdir(parents = True)+ studio = tmp_path / "custom"+ studio.mkdir()+ _record_note(studio, other)+ r = _resolve({"UNSLOTH_STUDIO_HOME": str(studio)}, home)+ assert r["master"] is None+ assert r["node"] == str(studio / "node")+++def test_an_empty_note_is_not_a_root(tmp_path):+ # A truncated or zero-length note must read as "no record", not as the current directory.+ home = tmp_path / "home"+ home.mkdir()+ studio = tmp_path / "custom"+ (studio / "share").mkdir(parents = True)+ (studio / "share" / ".unsloth-master-root").write_text("\n", encoding = "utf-8")+ r = _resolve({"UNSLOTH_STUDIO_HOME": str(studio)}, home)+ assert r["master"] is None+ assert r["node"] == str(studio / "node")+++def test_an_explicit_studio_home_without_a_note_does_not_borrow_anothers(tmp_path):+ # Two installs on one box, only the legacy tree carrying a note: studio_root() stays on the+ # named tree, so reading past it would send the runtimes and the portable caches to the+ # OTHER install while Studio ran from here.+ home = tmp_path / "home"+ legacy_master = home / ".unsloth"+ (legacy_master / "studio").mkdir(parents = True)+ _record_note(legacy_master / "studio", legacy_master)+ named = tmp_path / "named"+ named.mkdir()+ r = _resolve({"UNSLOTH_STUDIO_HOME": str(named)}, home)+ assert r["master"] is None+ assert r["studio"] == str(named)+ assert r["node"] == str(named / "node")+ assert r["whisper"] == str(named / "whisper.cpp")+++def test_a_flat_recorded_root_is_still_honoured(tmp_path):+ # The flat layout is supported, and the note then sits in the root it names rather than in a+ # studio/ child: an exact <root>/studio match would refuse it, containment satisfies it.+ home = tmp_path / "home"+ home.mkdir()+ flat = tmp_path / "flat"+ (flat / "share").mkdir(parents = True)+ (flat / "share" / ".unsloth-master-root").write_text(f"{flat}\n", encoding = "utf-8")+ r = _resolve({"UNSLOTH_STUDIO_HOME": str(flat)}, home)+ assert r["master"] == str(flat)+ assert r["node"] == str(flat / "node")+ assert r["warnings"] == []+++def test_a_default_install_reads_no_note(tmp_path):+ # Nothing writes the note for a default install, so the legacy tree must not acquire a+ # master root by accident: this is the path every existing user is on.+ home = tmp_path / "home"+ (home / ".unsloth" / "studio" / "share").mkdir(parents = True)+ r = _resolve({}, home)+ assert r["master"] is None+ assert r["node"] == str(home / ".unsloth" / "node")+++_DISCOVERY_PROBE = """+import json, os, sys+sys.path.insert(0, os.environ["_BACKEND"])+from pathlib import Path+from utils.paths.storage_roots import studio_root, unsloth_home+from utils.llama_cpp_path_settings import mark_managed_llama_cpp_path++# Replay run.py's module-level block, which is what a real server start does+# before anything asks where llama-server is.+resolved = studio_root().resolve()+if resolved != (Path.home() / ".unsloth" / "studio"):+ os.environ.setdefault("UNSLOTH_STUDIO_HOME", str(resolved))+ managed = (unsloth_home() or resolved) / "llama.cpp"+ os.environ.setdefault("UNSLOTH_LLAMA_CPP_PATH", str(managed))+ mark_managed_llama_cpp_path(managed)++from core.inference.llama_cpp import LlamaCppBackend++print(json.dumps({+ "exported": os.environ.get("UNSLOTH_LLAMA_CPP_PATH"),+ "found": LlamaCppBackend._find_llama_server_binary(),+}))+"""+++def _install_llama_server(directory: Path) -> Path:+ # The name _find_llama_server_binary looks for on THIS platform: it appends .exe on Windows,+ # so a fixture that only ever writes the POSIX name made discovery correctly answer None and+ # all three discovery tests fail on a Windows runner for a reason in the fixture.+ name = "llama-server.exe" if sys.platform == "win32" else "llama-server"+ binary = directory / "build" / "bin" / name+ binary.parent.mkdir(parents = True, exist_ok = True)+ binary.write_text("#!/bin/sh\nexit 0\n", encoding = "utf-8")+ binary.chmod(0o755)+ return binary+++def _discover(env_overrides: dict[str, str], home: Path) -> dict[str, str]:+ env = {+ "PATH": os.environ.get("PATH", "/usr/bin:/bin"),+ "HOME": str(home),+ "USERPROFILE": str(home),+ "_BACKEND": str(BACKEND),+ }+ # Same reason as _resolve: the interpreter's own requirements travel with it.+ for name in ("SYSTEMROOT", "SystemRoot", "COMSPEC", "PATHEXT", "TEMP", "TMP", "WINDIR"):+ value = os.environ.get(name)+ if value:+ env.setdefault(name, value)+ env.update(env_overrides)+ out = subprocess.run(+ [sys.executable, "-c", _DISCOVERY_PROBE],+ env = env,+ capture_output = True,+ text = True,+ )+ assert out.returncode == 0, f"discovery probe failed ({out.returncode}): {out.stderr.strip()}"+ return json.loads(out.stdout.strip().splitlines()[-1])+++def test_discovery_finds_the_llama_server_the_master_root_holds(tmp_path):+ # The managed marker makes discovery SKIP the env var for its own derivation, so the two+ # must name one directory or every GGUF model reports no runtime.+ home = tmp_path / "home"+ home.mkdir()+ root = tmp_path / "portable"+ (root / "studio").mkdir(parents = True)+ binary = _install_llama_server(root / "llama.cpp")++ result = _discover({"UNSLOTH_HOME": str(root)}, home)++ assert result["exported"] == str(root / "llama.cpp")+ assert result["found"] == str(binary)+++def test_discovery_still_prefers_a_plain_custom_studio_root(tmp_path):+ home = tmp_path / "home"+ home.mkdir()+ custom = tmp_path / "custom"+ custom.mkdir()+ binary = _install_llama_server(custom / "llama.cpp")++ result = _discover({"UNSLOTH_STUDIO_HOME": str(custom)}, home)++ assert result["found"] == str(binary)+++def test_discovery_still_finds_a_legacy_install(tmp_path):+ home = tmp_path / "home"+ (home / ".unsloth" / "studio").mkdir(parents = True)+ binary = _install_llama_server(home / ".unsloth" / "llama.cpp")++ result = _discover({}, home)++ assert result["found"] == str(binary)diff --git a/tests/test_setup_master_root.py b/tests/test_setup_master_root.pynew file mode 100644index 00000000000..c090f219cbd--- /dev/null+++ b/tests/test_setup_master_root.py@@ -0,0 +1,1473 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""setup.sh / setup.ps1 must install the managed runtimes at the same root the resolvers read.++`llama.cpp`, `node` and `whisper.cpp` are siblings of `studio/` under `UNSLOTH_HOME`, and+`storage_roots.unsloth_home()` sends every runtime resolver there. The CLI exports+`UNSLOTH_STUDIO_HOME=<root>/studio` before running setup, so a setup that derived the runtime+parent from the Studio home alone would install them one level too deep and no GGUF model,+managed Node or dictation engine would be found. Companion to+tests/test_managed_tools_master_root.py, which holds the resolvers to each other.+"""++from __future__ import annotations++import os+import pathlib+import shutil+import subprocess+from pathlib import Path++import pytest++# tests/conftest.py puts tests/_shared on sys.path; see unsloth_pwsh_runner for why a bare+# subprocess call to pwsh is not enough under xdist.+from unsloth_pwsh_runner import PWSH, run_pwsh++REPO_ROOT = Path(__file__).resolve().parents[1]+SETUP_SH = REPO_ROOT / "studio" / "setup.sh"+SETUP_PS1 = REPO_ROOT / "studio" / "setup.ps1"+++# These execute blocks of the POSIX installer, so they need bash AND a POSIX filesystem. Git+# Bash puts bash on PATH on a Windows runner, where the blocks run against Windows path+# semantics and hand back UTF-16 (`assert '\x00' == 'ALLOWED'`). setup.ps1 is covered separately+# here and in tests/studio/, so skipping loses no coverage.+NEEDS_POSIX_BASH = pytest.mark.skipif(+ shutil.which("bash") is None or os.name == "nt",+ reason = "runs studio/setup.sh blocks: needs bash on a POSIX filesystem",+)+++def _ps_quote(value: str) -> str:+ """A PowerShell single-quoted literal: only the quote itself needs escaping."""+ return "'" + value.replace("'", "''") + "'"+++def _slice(src: str, start: str, end: str) -> str:+ begin = src.index(start)+ return src[begin : src.index(end, begin)]+++def _runtime_parent(env: dict[str, str]) -> tuple[str, str]:+ """Run the shipped setup.sh derivations and report (node parent, llama.cpp parent).++ The two blocks are executed rather than pattern-matched, so a later edit that keeps the+ words and changes the order still fails here.+ """+ src = SETUP_SH.read_text(encoding = "utf-8")+ master = _slice(src, "# Stripped before anything else", "# Directory-local evidence")+ node = _slice(src, "# Mirror the llama.cpp UNSLOTH_HOME derivation", "NODE_DIR=")+ llama = _slice(src, 'if [ -n "$STAGE_ROOT" ]; then\n UNSLOTH_HOME=', "LLAMA_CPP_DIR=")+ script = "\n".join(+ (+ "set -u",+ master,+ node,+ llama,+ 'printf "%s\\n%s\\n" "$_NODE_PARENT" "$UNSLOTH_HOME"',+ )+ )+ completed = subprocess.run(+ ["bash", "-c", script],+ env = env,+ capture_output = True,+ text = True,+ timeout = 60,+ )+ assert completed.returncode == 0, completed.stderr+ node_parent, llama_parent = completed.stdout.splitlines()+ return node_parent, llama_parent+++def _env(home: Path, **overrides: str) -> dict[str, str]:+ env = {+ "HOME": str(home),+ "PATH": "/usr/bin:/bin",+ "STAGE_ROOT": "",+ "RUNTIME_ROOT": "",+ "STUDIO_HOME": str(home / ".unsloth" / "studio"),+ "_STUDIO_HOME_IS_CUSTOM": "false",+ }+ env.update(overrides)+ return env+++@NEEDS_POSIX_BASH+def _master_root_answer(tmp_path: Path, environment: str) -> str:+ """What uninstall.ps1's own _MasterRoot answers, with *environment* run before it.++ The functions are Invoke-Expression'd straight out of the shipped script, so a rewrite that+ keeps the words and loses the behaviour fails here instead of passing against a copy.+ """+ script = tmp_path / "probe.ps1"+ script.write_text(+ f"""$txt = Get-Content -Raw "{UNINSTALL_PS1}"+foreach ($n in @("_ExpandTilde", "_MasterRoot")) {{+ $m = [regex]::Match($txt, "(?ms)^ function $n \\{{.*?^ \\}}")+ if (-not $m.Success) {{ Write-Output "EXTRACT-FAILED:$n"; exit 1 }}+ Invoke-Expression $m.Value+}}+{environment}+""",+ encoding = "utf-8",+ )+ out = run_pwsh(+ [PWSH, "-NoProfile", "-File", str(script)],+ capture_output = True,+ text = True,+ check = True,+ ).stdout.strip()+ assert "EXTRACT-FAILED" not in out, out+ return out+++def test_a_master_root_puts_the_runtimes_beside_studio(tmp_path):+ root = tmp_path / "portable"+ (root / "studio").mkdir(parents = True)+ env = _env(+ tmp_path / "home",+ UNSLOTH_HOME = str(root),+ # What unsloth_cli/commands/studio.py exports before it runs setup.+ STUDIO_HOME = str(root / "studio"),+ _STUDIO_HOME_IS_CUSTOM = "true",+ )+ node_parent, llama_parent = _runtime_parent(env)+ assert Path(node_parent) == root+ assert Path(llama_parent) == root+++@NEEDS_POSIX_BASH+def test_no_master_root_keeps_the_studio_home_layout(tmp_path):+ """The pre-existing custom-root behaviour, which the new branch must not disturb."""+ studio = tmp_path / "elsewhere" / "studio"+ studio.mkdir(parents = True)+ env = _env(+ tmp_path / "home",+ STUDIO_HOME = str(studio),+ _STUDIO_HOME_IS_CUSTOM = "true",+ )+ node_parent, llama_parent = _runtime_parent(env)+ assert Path(node_parent) == studio+ assert Path(llama_parent) == studio+++@NEEDS_POSIX_BASH+def test_a_default_install_still_uses_the_legacy_root(tmp_path):+ home = tmp_path / "home"+ (home / ".unsloth" / "studio").mkdir(parents = True)+ node_parent, llama_parent = _runtime_parent(_env(home))+ assert Path(node_parent) == home / ".unsloth"+ assert Path(llama_parent) == home / ".unsloth"+++@NEEDS_POSIX_BASH+def test_a_staging_root_still_outranks_the_master_root(tmp_path):+ stage = tmp_path / "stage"+ stage.mkdir()+ env = _env(+ tmp_path / "home",+ UNSLOTH_HOME = str(tmp_path / "portable"),+ STAGE_ROOT = str(stage),+ RUNTIME_ROOT = str(stage),+ )+ node_parent, llama_parent = _runtime_parent(env)+ assert Path(node_parent) == stage+ assert Path(llama_parent) == stage+++def test_setup_ps1_derives_both_runtimes_from_the_master_root():+ """No PowerShell on the Linux runners, so the Windows half is held structurally: both+ derivations must go through the one helper, and it must read UNSLOTH_HOME."""+ src = SETUP_PS1.read_text(encoding = "utf-8")+ assert "function Get-MasterRootOverride" in src+ helper = _slice(src, "function Get-MasterRootOverride", "function Get-ManagedLlamaCppDir")+ assert "$env:UNSLOTH_HOME" in helper+ llama = _slice(src, "function Get-ManagedLlamaCppDir", "\n# Failure reason when the managed")+ assert "Get-MasterRootOverride" in llama+ # The master root has to lose to an explicit staging root, as it does in setup.sh.+ assert llama.index("$StagingRoot") < llama.index("Get-MasterRootOverride")+ node = _slice(src, " $_masterRoot = Get-MasterRootOverride", " $NodeDir = Join-Path")+ assert "$NodeParent = $_masterRoot" in node+ assert node.index("$StageRoot") < node.index("$NodeParent = $_masterRoot")+++@NEEDS_POSIX_BASH+def test_a_padded_master_root_names_the_same_directory(tmp_path):+ """storage_roots.unsloth_home() and the CLI both .strip(), so setup has to as well: an+ unstripped value installs under a directory whose name carries the whitespace."""+ root = tmp_path / "portable"+ (root / "studio").mkdir(parents = True)+ env = _env(+ tmp_path / "home",+ UNSLOTH_HOME = f" {root} ",+ STUDIO_HOME = str(root / "studio"),+ _STUDIO_HOME_IS_CUSTOM = "true",+ )+ node_parent, llama_parent = _runtime_parent(env)+ assert Path(node_parent) == root+ assert Path(llama_parent) == root+++@NEEDS_POSIX_BASH+def test_a_blank_master_root_counts_as_unset(tmp_path):+ home = tmp_path / "home"+ (home / ".unsloth" / "studio").mkdir(parents = True)+ node_parent, llama_parent = _runtime_parent(_env(home, UNSLOTH_HOME = " "))+ assert Path(node_parent) == home / ".unsloth"+ assert Path(llama_parent) == home / ".unsloth"+++BUILD_WHISPER = REPO_ROOT / "scripts" / "build_whisper_cpp.sh"+++def _whisper_root_block() -> str:+ """The shipped root selection, from the normalizer down to the INSTALL_DIR it decides."""+ src = BUILD_WHISPER.read_text(encoding = "utf-8")+ return _slice(src, "_root_value() {", "STUDIO_OWNED_MARKER=")+++def whisper_path(tmp_path_factory):+ """PATH for the extracted whisper block, with git and cmake satisfied by stubs.++ The slice above is the shipped file verbatim, so it carries the builder's `command -v`+ preflight along with the root selection these tests are about. On a runner without cmake the+ block exits 1 before choosing anything and four tests fail for a reason that has nothing to+ do with what they assert. Stubbed rather than excised: cutting the preflight out of the slice+ would mean the tests no longer run the shipped text, which is the whole point of lifting it.+ """+ stub_bin = tmp_path_factory.mktemp("stubbin")+ for tool in ("git", "cmake"):+ path = stub_bin / tool+ path.write_text("#!/bin/sh\nexit 0\n", encoding = "utf-8")+ path.chmod(0o755)+ return f"{stub_bin}:/usr/bin:/bin"+++@NEEDS_POSIX_BASH+def test_the_whisper_builder_installs_under_the_master_root(tmp_path, whisper_path):+ """setup.sh runs this with UNSLOTH_STUDIO_HOME=<root>/studio still inherited, so a builder+ that preferred it would install a level below _managed_whisper_cpp_dir()."""+ root = tmp_path / "portable"+ src = BUILD_WHISPER.read_text(encoding = "utf-8")+ block = _whisper_root_block()+ script = "\n".join(("set -eu", block, 'printf "%s\\n" "$INSTALL_DIR"'))+ completed = subprocess.run(+ ["bash", "-c", script],+ env = {+ "HOME": str(tmp_path / "home"),+ "PATH": whisper_path,+ "UNSLOTH_HOME": str(root),+ "UNSLOTH_STUDIO_HOME": str(root / "studio"),+ },+ capture_output = True,+ text = True,+ timeout = 60,+ )+ assert completed.returncode == 0, completed.stderr+ assert Path(completed.stdout.strip()) == root / "whisper.cpp"+++@NEEDS_POSIX_BASH+def test_the_whisper_builder_still_honours_a_studio_home_alone(tmp_path, whisper_path):+ studio = tmp_path / "elsewhere" / "studio"+ src = BUILD_WHISPER.read_text(encoding = "utf-8")+ block = _whisper_root_block()+ script = "\n".join(("set -eu", block, 'printf "%s\\n" "$INSTALL_DIR"'))+ completed = subprocess.run(+ ["bash", "-c", script],+ env = {+ "HOME": str(tmp_path / "home"),+ "PATH": whisper_path,+ "UNSLOTH_STUDIO_HOME": str(studio),+ },+ capture_output = True,+ text = True,+ timeout = 60,+ )+ assert completed.returncode == 0, completed.stderr+ assert Path(completed.stdout.strip()) == studio / "whisper.cpp"+++@NEEDS_POSIX_BASH+def test_a_blank_master_root_does_not_outrank_the_whisper_studio_home(tmp_path, whisper_path):+ """${VAR:-} only treats the EMPTY string as unset, so an unstripped whitespace value would+ win the new precedence and name a relative " /whisper.cpp"."""+ studio = tmp_path / "elsewhere" / "studio"+ completed = subprocess.run(+ [+ "bash",+ "-c",+ "\n".join(+ (+ "set -eu",+ _whisper_root_block(),+ 'printf "%s\\n" "$INSTALL_DIR"',+ )+ ),+ ],+ env = {+ "HOME": str(tmp_path / "home"),+ "PATH": whisper_path,+ "UNSLOTH_HOME": " ",+ "UNSLOTH_STUDIO_HOME": str(studio),+ },+ capture_output = True,+ text = True,+ timeout = 60,+ )+ assert completed.returncode == 0, completed.stderr+ assert Path(completed.stdout.strip()) == studio / "whisper.cpp"+++@NEEDS_POSIX_BASH+def test_a_tilde_master_root_expands_for_the_whisper_builder(tmp_path, whisper_path):+ home = tmp_path / "home"+ completed = subprocess.run(+ [+ "bash",+ "-c",+ "\n".join(+ (+ "set -eu",+ _whisper_root_block(),+ 'printf "%s\\n" "$INSTALL_DIR"',+ )+ ),+ ],+ env = {"HOME": str(home), "PATH": whisper_path, "UNSLOTH_HOME": "~/portable"},+ capture_output = True,+ text = True,+ timeout = 60,+ )+ assert completed.returncode == 0, completed.stderr+ assert Path(completed.stdout.strip()) == home / "portable" / "whisper.cpp"+++@NEEDS_POSIX_BASH+def test_a_relative_master_root_resolves_against_the_caller(tmp_path):+ """Node is chosen before setup.sh's first `cd "$SCRIPT_DIR"` and llama.cpp after it, so a+ value left relative names two different directories and the backend's neither."""+ caller = tmp_path / "caller"+ caller.mkdir()+ src = SETUP_SH.read_text(encoding = "utf-8")+ script = "\n".join(+ (+ "set -u",+ _slice(src, "# Stripped before anything else", "# Directory-local evidence"),+ 'printf "%s\\n" "$_MASTER_ROOT"',+ )+ )+ completed = subprocess.run(+ ["bash", "-c", script],+ cwd = str(caller),+ env = {+ "HOME": str(tmp_path / "home"),+ "PATH": "/usr/bin:/bin",+ "PWD": str(caller),+ "UNSLOTH_HOME": "not-created-yet",+ "_STUDIO_HOME_IS_CUSTOM": "false",+ },+ capture_output = True,+ text = True,+ timeout = 60,+ )+ assert completed.returncode == 0, completed.stderr+ assert Path(completed.stdout.strip()) == caller / "not-created-yet"+++@NEEDS_POSIX_BASH+def test_a_master_root_alone_still_asserts_ownership_of_the_runtimes(tmp_path):+ """With only UNSLOTH_HOME set, STUDIO_HOME stays legacy and _STUDIO_HOME_IS_CUSTOM stays+ false, which is what licenses the installers to os.replace() and rm -rf without checking+ the Unsloth-owned marker. The runtimes moved, so the guard has to follow them."""+ root = tmp_path / "portable"+ root.mkdir()+ home = tmp_path / "home"+ (home / ".unsloth" / "studio").mkdir(parents = True)+ src = SETUP_SH.read_text(encoding = "utf-8")+ script = "\n".join(+ (+ "set -u",+ _slice(src, "# Stripped before anything else", "# Directory-local evidence"),+ 'printf "%s %s\\n" "$_STUDIO_HOME_IS_CUSTOM" "$_RUNTIME_ROOT_IS_CUSTOM"',+ )+ )+ completed = subprocess.run(+ ["bash", "-c", script],+ env = {+ "HOME": str(home),+ "PATH": "/usr/bin:/bin",+ "UNSLOTH_HOME": str(root),+ "_STUDIO_HOME_IS_CUSTOM": "false",+ },+ capture_output = True,+ text = True,+ timeout = 60,+ )+ assert completed.returncode == 0, completed.stderr+ assert completed.stdout.split() == ["false", "true"]+++@NEEDS_POSIX_BASH+ "environment, expected",+ [+ # Staging: the placement below gives STAGE_ROOT precedence over the master root, so the+ # master root is not where anything lands and must not decide ownership. Raised anyway,+ # it demanded an owner marker from a markerless tree the old updater had staged, and an+ # update that worked on the merge base exited instead.+ pytest.param(+ {"UNSLOTH_STUDIO_STAGE_ROOT": "STAGE", "_STUDIO_HOME_IS_CUSTOM": "false"},+ ["false", "false"],+ id = "a staged update ignores the master root",+ ),+ # And the flag has to be ASSIGNED, not only raised: a custom STUDIO_HOME whose runtimes+ # land in the legacy root kept it true and demanded markers from exactly the pre-marker+ # ~/.unsloth/llama.cpp this comparison exists to spare.+ pytest.param(+ {"UNSLOTH_HOME": "LEGACY", "_STUDIO_HOME_IS_CUSTOM": "true"},+ ["true", "false"],+ id = "a custom studio home whose runtimes stay legacy",+ ),+ ],+)+def test_the_ownership_flag_follows_where_the_runtimes_land(tmp_path, environment, expected):+ home = tmp_path / "home"+ (home / ".unsloth" / "studio").mkdir(parents = True)+ stage = tmp_path / "stage"+ stage.mkdir()+ resolved = {+ key: str(stage)+ if value == "STAGE"+ else str(home / ".unsloth")+ if value == "LEGACY"+ else value+ for key, value in environment.items()+ }+ if "UNSLOTH_HOME" not in resolved:+ resolved["UNSLOTH_HOME"] = str(tmp_path / "portable")+ (tmp_path / "portable").mkdir()+ src = SETUP_SH.read_text(encoding = "utf-8")+ script = "\n".join(+ (+ "set -u",+ f'STAGE_ROOT="{resolved.pop("UNSLOTH_STUDIO_STAGE_ROOT", "")}"',+ _slice(src, "# Stripped before anything else", "# Directory-local evidence"),+ 'printf "%s %s\\n" "$_STUDIO_HOME_IS_CUSTOM" "$_RUNTIME_ROOT_IS_CUSTOM"',+ )+ )+ completed = subprocess.run(+ ["bash", "-c", script],+ env = {"HOME": str(home), "PATH": "/usr/bin:/bin", **resolved},+ capture_output = True,+ text = True,+ timeout = 60,+ )+ assert completed.returncode == 0, completed.stderr+ assert completed.stdout.split() == expected+++@NEEDS_POSIX_BASH+def test_no_master_root_leaves_the_ownership_flag_alone(tmp_path):+ src = SETUP_SH.read_text(encoding = "utf-8")+ script = "\n".join(+ (+ "set -u",+ _slice(src, "# Stripped before anything else", "# Directory-local evidence"),+ 'printf "%s %s\\n" "$_STUDIO_HOME_IS_CUSTOM" "$_RUNTIME_ROOT_IS_CUSTOM"',+ )+ )+ for flag in ("false", "true"):+ completed = subprocess.run(+ ["bash", "-c", script],+ env = {+ "HOME": str(tmp_path / "home"),+ "PATH": "/usr/bin:/bin",+ "_STUDIO_HOME_IS_CUSTOM": flag,+ },+ capture_output = True,+ text = True,+ timeout = 60,+ )+ assert completed.returncode == 0, completed.stderr+ assert completed.stdout.split() == [flag, flag]+++def test_every_runtime_ownership_guard_uses_the_runtime_flag():+ """The Studio home and its venvs keep _STUDIO_HOME_IS_CUSTOM; every guard that names a+ runtime child has to move, or a master-root install loses the marker check on it."""+ src = SETUP_SH.read_text(encoding = "utf-8")+ for line in src.splitlines():+ if "_STUDIO_HOME_IS_CUSTOM" not in line:+ continue+ assert not any(+ name in line for name in ("$NODE_DIR", "$LLAMA_CPP_DIR", "$WHISPER_CPP_DIR")+ ), line+ ps = SETUP_PS1.read_text(encoding = "utf-8")+ # Seeded from the Studio flag and raised only when the master root is elsewhere, as setup.sh+ # does; test_the_windows_legacy_root_named_explicitly_is_not_custom runs the divergence.+ assert "$RuntimeRootIsCustom = $StudioHomeIsCustom\n" in ps+ assert "$_masterRootForOwnership -ine $_legacyRuntimeRoot" in ps+ for line in ps.splitlines():+ if "$StudioHomeIsCustom" not in line:+ continue+ assert not any(+ name in line for name in ("$LlamaCppDir", "$WhisperCppDir", "$NodeDir")+ ), line+++@NEEDS_POSIX_BASH+def test_the_legacy_root_named_explicitly_is_not_custom(tmp_path):+ """UNSLOTH_HOME=$HOME/.unsloth names the root a default install already uses.++ Nothing moves, so demanding an owner marker there rejects an update that used to reuse a+ legacy source-built ~/.unsloth/llama.cpp, which predates the marker entirely. Customness has+ to come from where the runtimes LAND, not from whether the variable was set.+ """+ home = tmp_path / "home"+ (home / ".unsloth" / "studio").mkdir(parents = True)+ src = SETUP_SH.read_text(encoding = "utf-8")+ block = _slice(src, "# Stripped before anything else", "# Directory-local evidence")+ script = "\n".join(+ (+ "set -u",+ "_STUDIO_HOME_IS_CUSTOM=false",+ block,+ 'printf "%s\\n" "$_RUNTIME_ROOT_IS_CUSTOM"',+ )+ )++ def flag(master: str) -> str:+ done = subprocess.run(+ ["bash", "-c", script],+ env = {"HOME": str(home), "PATH": "/usr/bin:/bin", "UNSLOTH_HOME": master},+ capture_output = True,+ text = True,+ timeout = 60,+ )+ assert done.returncode == 0, done.stderr+ return done.stdout.strip()++ assert flag(str(home / ".unsloth")) == "false"+ # Non-vacuity: a root that really is elsewhere still takes the strict path.+ assert flag(str(tmp_path / "portable")) == "true"+ assert flag("") == "false"++[email protected](PWSH is None, reason = "needs pwsh")+def test_the_windows_legacy_root_named_explicitly_is_not_custom(tmp_path):+ """The Windows half of the test above, run rather than pattern-matched.++ setup.ps1 read `$StudioHomeIsCustom -or [bool](Get-MasterRootOverride)`, so+ UNSLOTH_HOME=%USERPROFILE%\\.unsloth turned the ownership guard on for a root a default+ install is already using. Nothing moves there, and the guard then demands an owner marker+ from a markerless source-built .unsloth\\llama.cpp, so Assert-StudioOwnedOrAbsent exits an+ update that used to reuse that build. setup.sh adopts it, which made the two halves answer+ differently for one environment.+ """+ profile = tmp_path / "profile"+ (profile / ".unsloth" / "studio").mkdir(parents = True)+ ps = SETUP_PS1.read_text(encoding = "utf-8")+ # The derivation itself, from the flag it seeds to the line after it.+ block = _slice(ps, "$RuntimeRootIsCustom = $StudioHomeIsCustom", "$LlamaCppDir = ")+ script = tmp_path / "probe.ps1"+ script.write_text(+ "\n".join(+ (+ f"$txt = Get-Content -Raw '{SETUP_PS1}'",+ # The shipped helpers, so a rewrite that keeps the words and changes the+ # canonicalisation still fails here.+ 'foreach ($n in @("Get-PathState", "Test-AccessDeniedError", "Get-CanonicalDir",'+ ' "Get-MasterRootOverride")) {',+ ' $m = [regex]::Match($txt, "(?ms)^function $n \\{.*?^\\}")',+ ' if (-not $m.Success) { Write-Output "EXTRACT-FAILED:$n"; exit 1 }',+ " Invoke-Expression $m.Value",+ "}",+ # Test-StudioHomeIsCustom closes over $StudioHome, so it is stated here rather+ # than extracted: the point of this probe is the master-root comparison.+ "$StudioHomeIsCustom = $false",+ block,+ "Write-Output $RuntimeRootIsCustom",+ )+ ),+ encoding = "utf-8",+ )++ def flag(master: str) -> str:+ out = run_pwsh(+ [PWSH, "-NoProfile", "-File", str(script)],+ env = {+ "PATH": os.environ.get("PATH", ""),+ "HOME": str(profile),+ "USERPROFILE": str(profile),+ "UNSLOTH_HOME": master,+ },+ capture_output = True,+ text = True,+ check = True,+ ).stdout.strip()+ assert "EXTRACT-FAILED" not in out, out+ return out.splitlines()[-1].strip()++ assert flag(str(profile / ".unsloth")) == "False"+ # Non-vacuity, and the same two controls the bash test uses.+ assert flag(str(tmp_path / "portable")) == "True"+ assert flag("") == "False"++[email protected](PWSH is None, reason = "needs pwsh")+def test_the_windows_uninstaller_only_removes_a_root_that_is_really_empty(tmp_path):+ """The master root and its .staging go only when empty, and by an operation that cannot do+ anything else.++ Windows asked with Get-ChildItem -ErrorAction SilentlyContinue and then called _RemovePath,+ which is Remove-Item -Recurse -Force, in the one directory this branch teaches users to+ point at their own files. Two separate calls, so a file arriving between the two was taken+ by the -Recurse; and a swallowed enumeration error read as an empty directory.+ uninstall.sh uses rmdir for both paths, which is one call that refuses a non-empty+ directory, and this file's own %TEMP% prune already asks with -ErrorAction Stop.++ The behavioural halves below are what can be shown on a POSIX host: a recursive delete needs+ to enumerate too, so an unlistable directory survives either version here and the ACL shape+ that separates DELETE from LIST is Windows-only. What is checked instead is the mechanism,+ which is what removes the race as well.+ """+ ps = UNINSTALL_PS1.read_text(encoding = "utf-8")+ assert "function _RemoveDirIfEmpty" in ps+ helper = _slice(ps, " function _RemoveDirIfEmpty {", "\n # The exact shape")+ # One atomic call: no -Recurse anywhere in it, and no emptiness question asked separately.+ assert "[System.IO.Directory]::Delete($Path, $false)" in helper+ assert "-Recurse" not in helper, helper+ assert "Get-ChildItem" not in helper, helper+ # And both master-root sites go through it rather than keeping their own version.+ master_block = _slice(ps, "$masterRoot = $masterRootToStop", "if ($defaultLlamaCpp)")+ assert master_block.count("_RemoveDirIfEmpty") == 2, master_block+ assert "-ErrorAction SilentlyContinue)) {\n _RemovePath" not in master_block++ script = tmp_path / "probe.ps1"+ script.write_text(+ "\n".join(+ (+ f"$txt = Get-Content -Raw '{UNINSTALL_PS1}'",+ '$m = [regex]::Match($txt, "(?ms)^ function _RemoveDirIfEmpty \\{.*?^ \\}")',+ 'if (-not $m.Success) { Write-Output "EXTRACT-FAILED"; exit 1 }',+ "Invoke-Expression $m.Value",+ "function _Substep { param($a, $b) }",+ "_RemoveDirIfEmpty $args[0]",+ 'Write-Output ("EXISTS=" + (Test-Path -LiteralPath $args[0]))',+ )+ ),+ encoding = "utf-8",+ )++ def still_there(path: Path) -> bool:+ out = run_pwsh(+ [PWSH, "-NoProfile", "-File", str(script), str(path)],+ env = {"PATH": os.environ.get("PATH", ""), "HOME": str(tmp_path)},+ capture_output = True,+ text = True,+ check = True,+ ).stdout+ assert "EXTRACT-FAILED" not in out, out+ assert "EXISTS=" in out, out+ return out.strip().splitlines()[-1] == "EXISTS=True"++ empty = tmp_path / "empty"+ empty.mkdir()+ assert not still_there(empty), "an empty root is the one case that may be removed"++ occupied = tmp_path / "occupied"+ occupied.mkdir()+ (occupied / "theirs.txt").write_text("mine", encoding = "utf-8")+ assert still_there(occupied)+ assert (occupied / "theirs.txt").is_file(), "a non-empty root must keep its contents"++ # A directory holding only a subdirectory: rmdir refuses this too, and a -Recurse would not.+ nested = tmp_path / "nested"+ (nested / "child").mkdir(parents = True)+ assert still_there(nested)+ assert (nested / "child").is_dir()+++@NEEDS_POSIX_BASH+def test_only_a_directory_can_be_adopted_at_a_runtime_path(tmp_path):+ """A dangling symlink and a regular file are both things the user put there.++ -d alone read either as "nothing is here", and the caller then rm -rf'd the path or let+ install_*_prebuilt.py os.replace() over it. A dangling link is the ordinary case: its target+ volume is simply not mounted, and resolving it later installs onto somebody's other disk.+ """+ src = SETUP_SH.read_text(encoding = "utf-8")+ block = _slice(src, "_studio_path_shape() {", "\n_packaged_frontend_available")+ script = "\n".join(+ (+ "set -u",+ "_STUDIO_OWNED_MARKER=.unsloth-studio-owned",+ "_studio_owned_adoptable() { return 1; }",+ "_studio_dir_unsearchable() { return 1; }",+ "_path_access_denied() { echo DENIED; exit 9; }",+ "setup_fail() { echo REFUSED; exit 1; }",+ block,+ '_assert_studio_owned_or_absent "$1" llama.cpp true',+ "echo ALLOWED",+ )+ )++ def verdict(path: pathlib.Path) -> str:+ done = subprocess.run(+ ["bash", "-c", script, "_", str(path)],+ env = {"HOME": str(tmp_path), "PATH": "/usr/bin:/bin"},+ capture_output = True,+ text = True,+ timeout = 60,+ )+ return done.stdout.strip().splitlines()[-1] if done.stdout.strip() else done.stderr[-120:]++ assert verdict(tmp_path / "absent") == "ALLOWED"++ dangling = tmp_path / "dangling"+ dangling.symlink_to(tmp_path / "no-such-volume" / "llama.cpp")+ assert verdict(dangling) == "REFUSED"++ plain = tmp_path / "afile"+ plain.write_text("mine")+ assert verdict(plain) == "REFUSED"++ owned = tmp_path / "owned"+ owned.mkdir()+ (owned / ".unsloth-studio-owned").touch()+ assert verdict(owned) == "ALLOWED"+++def test_the_windows_inductor_cache_agrees_with_the_resolver():+ """setup.ps1 persists TORCHINDUCTOR_CACHE_DIR to the USER environment.++ Every later Studio process inherits it, so _setup_cache_env's fill-if-unset default never+ applies on Windows and the containment this branch is for does not happen there. It has to+ name the directory the resolver would have chosen. Two things still outrank that, and both+ are recorded here so a later edit cannot quietly drop them: long paths off keeps the short+ drive-root directory for MAX_PATH headroom, and a path containing a space is refused for the+ same reason storage_roots does, since the C++ builders paste it in unquoted.+ """+ ps = SETUP_PS1.read_text(encoding = "utf-8")+ block = _slice(ps, "$TorchCacheDir = $null", "$env:TORCHINDUCTOR_CACHE_DIR = $TorchCacheDir")+ assert 'Join-Path (Join-Path $StudioHome "cache") "torchinductor"' in block+ assert "$LongPathsEnabled" in block+ assert "'\\s'" in block or '"\\s"' in block, "the whitespace refusal is gone"+ assert '"C:\\tc"' in block++ roots = (REPO_ROOT / "studio" / "backend" / "utils" / "paths" / "storage_roots.py").read_text(+ encoding = "utf-8"+ )+ # The same key, named by both sides, so the two cannot drift apart silently.+ assert '"TORCHINDUCTOR_CACHE_DIR",' in roots+ assert 'str(root / "torchinductor")' in roots+++def test_the_windows_node_guard_covers_a_master_root():+ """setup.ps1's Node ownership guard and its marker both hung off $NodeOverride alone.++ $NodeOverride is set only in the UNSLOTH_STUDIO_HOME / STUDIO_HOME branch. The master-root+ branch sets $NodeParent and leaves it null, so <master>\\node reached the whole-directory+ os.replace() in install_node_prebuilt.py with no ownership evidence at all, and the tree the+ run then created stayed unmarked, which makes the uninstaller decline to remove it later.+ setup.sh had already moved these two sites to _RUNTIME_ROOT_IS_CUSTOM.++ The sibling test above only rejects $StudioHomeIsCustom beside $NodeDir, which this bug+ never wrote: it named a third variable. So the rule here is positive, not a denial.+ """+ ps = SETUP_PS1.read_text(encoding = "utf-8")+ # Every site in the Node install section that decides whether the Node path is the user's.+ # Keyed on $NodeOverride, the variable the bug named, not $NodeDir: the guard's probe moved+ # to its own line, so a $NodeDir test would pass by seeing less. The section start drops the+ # parsing block far above, which rightly says nothing about the runtime root.+ lines = ps.splitlines()+ start = next(i for i, line in enumerate(lines) if "$nodeEntry = if (" in line)+ guards = [line for line in lines[start:] if "$NodeOverride" in line]+ # The guard's probe, and the marker's `if`. Fewer means the block was restructured and this+ # test would otherwise pass by finding nothing.+ assert len(guards) >= 2, guards+ for line in guards:+ assert "$RuntimeRootIsCustom" in line, line+++UNINSTALL_SH = REPO_ROOT / "scripts" / "uninstall.sh"+UNINSTALL_PS1 = REPO_ROOT / "scripts" / "uninstall.ps1"++[email protected](shutil.which("pwsh") is None, reason = "pwsh not available")+def test_the_windows_uninstaller_resolves_a_relative_root_like_setup(tmp_path):+ """setup.ps1 resolves through PowerShell's own location; uninstall.ps1 used+ [IO.Path]::GetFullPath, which anchors at [Environment]::CurrentDirectory.++ PowerShell does not keep those two in step, so after a Set-Location a relative UNSLOTH_HOME+ named one install to setup and a different one to the uninstaller. The owner marker does not+ save you there: it spares trees that are not Unsloth's, and the wrongly resolved path is+ another Unsloth install, marker and all.++ Runs the shipped function rather than matching its text, so a rewrite that keeps the words+ and loses the behaviour still fails.+ """+ initial = tmp_path / "initial"+ chosen = tmp_path / "chosen"+ (chosen / "portable").mkdir(parents = True)+ initial.mkdir()+ out = _master_root_answer(+ tmp_path,+ f"""[System.Environment]::CurrentDirectory = "{initial}"+Set-Location "{chosen}"+$env:UNSLOTH_HOME = "portable"+$env:USERPROFILE = "{tmp_path}/profile"+Write-Output (_MasterRoot)+""",+ )+ assert out == str(chosen / "portable"), out+++def test_neither_uninstaller_recurses_into_an_install_lock_path():+ """A lock is always a regular file, so a directory at one of those fixed names is the user's.++ prebuilt_core.install_lock creates it with os.open(O_CREAT | O_EXCL). Both uninstallers+ reached the lock names through their recursive remover, which in a user-chosen master root+ deletes a whole tree with none of the owner-marker proof the runtime children require.+ Behaviour is covered by tests/sh/test_uninstall_master_root.sh for the POSIX half; this+ holds the PowerShell twin, which has no runner here.+ """+ sh = UNINSTALL_SH.read_text(encoding = "utf-8")+ ps = UNINSTALL_PS1.read_text(encoding = "utf-8")++ assert "_remove_lock_file() {" in sh+ assert "function _RemoveLockFile" in ps++ # The call sites do not all spell the lock out (PowerShell iterates $lockName, both sweep a+ # $stale), so matching only "install.lock" let the master-root loop keep the recursive+ # remover and still pass.+ lockish = ("install.lock", "lockName", "$stale", "_stale", "_mr_lock")+ for text, remover, shape in (+ (sh, "_remove_path ", "_remove_lock_file"),+ (ps, "_RemovePath ", "_RemoveLockFile"),+ ):+ hits = 0+ for line in text.splitlines():+ if line.lstrip().startswith("#"):+ continue+ if remover not in line and shape not in line:+ continue+ if not any(token in line for token in lockish):+ continue+ hits += 1+ assert shape in line, line+ # Counts the call sites found, not the ones left wrong: once they are all correct the+ # remover no longer appears beside a lock at all, and a count of zero would mean the+ # tokens above had stopped matching and this loop proved nothing.+ assert hits >= 4, (remover, hits)++ # The rename keeps the leading dot, and neither a glob without one nor the dot alone is+ # enough, so the sweep matches the installer's full shape; held by+ # test_neither_uninstaller_sweeps_a_stale_lock_name_it_did_not_make below.+ assert "install.lock.stale" in ps+ assert '"*.install.lock.stale.*"' not in ps+++def test_both_uninstallers_clear_the_master_root_children():+ """setup installs llama.cpp, node and whisper.cpp as children of the master root, so an+ uninstaller that only knows the legacy siblings and the Studio root strands them. Behaviour+ is covered by tests/sh/test_uninstall_master_root.sh; this holds the PowerShell twin, which+ the Linux runners cannot execute, and pins the marker gate on both."""+ sh = UNINSTALL_SH.read_text(encoding = "utf-8")+ ps = UNINSTALL_PS1.read_text(encoding = "utf-8")+ assert "_master_root() {" in sh+ assert "function _MasterRoot" in ps+ for src, marker in ((sh, ".unsloth-studio-owned"), (ps, ".unsloth-studio-owned")):+ block = _slice(src, "master root's own children", "llama.cpp build + cache")+ assert marker in block, block+ for child in ("llama.cpp", "node", "whisper.cpp"):+ assert child in block, (child, block)+ # A user-chosen root reaches the deny list on both sides before anything is removed.+ assert '_is_unsafe_root "$_mr_root"' in sh+ assert "_IsUnsafeRoot $masterRoot" in ps+ # And it only contributes its studio child when neither exact override is set, as in+ # storage_roots.studio_root().+ assert '_emit "$(_master_root)/studio"' in sh+ assert '$envRoot = (Join-Path $master "studio")' in ps+++def test_the_stop_pass_covers_the_master_root_runtimes():+ """Windows locks a loaded executable, so a runtime still running under the master root has+ to be stopped before its tree is removed or the delete exhausts its retries. _MasterRoot is+ resolved before the stop pass, and only marker-owned children join it, so an unmarked+ neighbour's process is never killed."""+ ps = UNINSTALL_PS1.read_text(encoding = "utf-8")+ stop_line = next(l for l in ps.splitlines() if l.strip().startswith("$stopRoots = "))+ assert "$masterChildrenToStop" in stop_line, stop_line+ block = _slice(ps, "$masterRootToStop = _MasterRoot", "$stopRoots = ")+ assert ".unsloth-studio-owned" in block, block+ assert "_IsUnsafeRoot $masterRootToStop" in block, block+ assert ps.index("$masterRootToStop = _MasterRoot") < ps.index(+ "_StopProcessesLockingRoots -Roots"+ )+++def test_a_shared_staging_directory_is_pruned_not_deleted():+ """The prebuilt installers share <root>/.staging and prune it only when empty, so anything+ left in a user-chosen root is not ours to delete recursively."""+ sh = UNINSTALL_SH.read_text(encoding = "utf-8")+ ps = UNINSTALL_PS1.read_text(encoding = "utf-8")+ assert 'rmdir "$_mr_root/.staging"' in sh+ assert '_remove_path "$_mr_root/.staging"' not in sh+ # The Windows equivalent of rmdir, for the same reason. Asking with Get-ChildItem and then+ # calling _RemovePath is not it: see+ # test_the_windows_uninstaller_only_removes_a_root_that_is_really_empty.+ staging = _slice(+ ps, '_RemoveDirIfEmpty (Join-Path $masterRoot ".staging")', "# Shared llama.cpp build"+ )+ assert "_RemovePath" not in staging, staging+++def test_the_windows_uninstaller_refuses_a_note_carried_in_from_elsewhere(tmp_path):+ """A Studio tree copied from master root A to B keeps a note naming A.++ A's llama.cpp, node, whisper.cpp and sd.cpp carry exactly the owner markers B's would, so+ the marker gates cannot tell them apart: accepting the copied note has the uninstall of B+ delete the ORIGINAL install's runtimes. The note has to describe the tree it was found in,+ which means the Studio directory it was read from lying inside the root it names.+ """+ original = tmp_path / "original"+ (original / "studio").mkdir(parents = True)+ copied = tmp_path / "copied"+ (copied / "studio" / "share").mkdir(parents = True)+ (copied / "studio" / "share" / ".unsloth-master-root").write_text(+ f"{original}\n", encoding = "utf-8"+ )+ profile = tmp_path / "profile"+ (profile / ".unsloth" / "studio" / "share").mkdir(parents = True)++ script = tmp_path / "probe.ps1"+ script.write_text(+ f"""$txt = Get-Content -Raw "{UNINSTALL_PS1}"+foreach ($n in @("_ExpandTilde", "_RootFromConf", "_MasterRoot")) {{+ $m = [regex]::Match($txt, "(?ms)^ function $n \\{{.*?^ \\}}")+ if (-not $m.Success) {{ Write-Output "EXTRACT-FAILED:$n"; exit 1 }}+ Invoke-Expression $m.Value+}}+$env:UNSLOTH_HOME = ""+$env:STUDIO_HOME = ""+$env:UNSLOTH_STUDIO_HOME = "{copied}/studio"+$env:USERPROFILE = "{profile}"+$answer = _MasterRoot+Write-Output "ANSWER:$answer"+""",+ encoding = "utf-8",+ )+ out = run_pwsh(+ [PWSH, "-NoProfile", "-File", str(script)],+ capture_output = True,+ text = True,+ check = True,+ ).stdout.strip()+ assert "EXTRACT-FAILED" not in out, out+ assert out == "ANSWER:", out+++def test_the_windows_uninstaller_does_not_borrow_another_installs_note(tmp_path):+ """Two installs on one box: the legacy tree carries a note, the named one does not.++ _MasterRoot probed the legacy path first, so its note won here while the removal still+ worked on the tree UNSLOTH_STUDIO_HOME names. The run deleted the named Studio and then+ followed the OTHER install's master root and took its marked runtime children with it.+ Runs the shipped function, as the test below does.+ """+ profile = tmp_path / "profile"+ (profile / ".unsloth" / "studio" / "share").mkdir(parents = True)+ borrowed = tmp_path / "borrowed"+ (borrowed / "studio").mkdir(parents = True)+ (profile / ".unsloth" / "studio" / "share" / ".unsloth-master-root").write_text(+ f"{borrowed}\n", encoding = "utf-8"+ )+ named = tmp_path / "named"+ (named / "share").mkdir(parents = True)++ out = _master_root_answer(+ tmp_path,+ f"""$env:UNSLOTH_HOME = ""+$env:STUDIO_HOME = ""+$env:UNSLOTH_STUDIO_HOME = "{named}"+$env:USERPROFILE = "{profile}"+$answer = _MasterRoot+Write-Output "ANSWER:$answer"+""",+ )+ assert out == "ANSWER:", out+++def test_the_windows_uninstaller_finds_a_master_root_from_the_note(tmp_path):+ """`$env:UNSLOTH_HOME = 'D:\\portable'; unsloth studio update` names the root for one command.++ setup.ps1 puts node\\, llama.cpp\\ and whisper.cpp\\ under it and marks them, and a later+ uninstall run from an ordinary shell has no UNSLOTH_HOME at all. Reading only the current+ environment, _MasterRoot answered null there, so the run removed <master>\\studio and left+ multi-gigabyte runtimes beside it. setup.sh already wrote the note; setup.ps1 did not, and+ the PowerShell uninstaller did not read it.++ Runs the shipped function, so a rewrite that keeps the words and loses the behaviour fails.+ """+ master = tmp_path / "portable"+ (master / "studio" / "share").mkdir(parents = True)+ (master / "studio" / "share" / ".unsloth-master-root").write_text(+ f"{master}\n", encoding = "utf-8"+ )+ profile = tmp_path / "profile"+ (profile / ".unsloth" / "studio" / "share").mkdir(parents = True)++ out = _master_root_answer(+ tmp_path,+ f"""$env:UNSLOTH_HOME = ""+$env:STUDIO_HOME = ""+$env:UNSLOTH_STUDIO_HOME = "{master}/studio"+$env:USERPROFILE = "{profile}"+Write-Output (_MasterRoot)+""",+ )+ assert out == str(master), out+++def test_the_windows_setup_records_the_master_root_for_the_uninstaller():+ """The note the test above reads has to be written, and only where it is true.++ A staging run installs to a throwaway root, and every non-master branch derives the root+ from paths the uninstaller already knows, so a note there would only ever be able to go+ stale. This is the same rule setup.sh applies.+ """+ ps = SETUP_PS1.read_text(encoding = "utf-8")+ block = _slice(+ ps, "# Record the master root inside the Studio tree", "$WithLlamaCppDir = $null"+ )+ assert "(Get-MasterRootOverride)" in block+ assert "-not $StageRoot" in block+ assert '".unsloth-master-root"' in block+ # Staged then renamed: a reader catching a half-written note would name a truncated path,+ # and this note licenses deletions.+ assert "$noteTmp" in block and "Move-Item" in block+ # The 3-argument overwrite overload is .NET Core only, and setup.ps1 runs under 5.1.+ assert "[System.IO.File]::Move(" not in block+++def test_the_windows_uninstaller_clears_the_inductor_path_it_persisted():+ """setup.ps1 writes TORCHINDUCTOR_CACHE_DIR to the USER environment, so it outlives the+ install. Every later PyTorch process on the account inherits it, including ones unrelated to+ Unsloth, and they compile into the deleted tree and rebuild part of it.++ Only a value inside a root this run owned: a directory the user chose is theirs, and the+ shared C:\\tc fallback is not install specific and is not deleted here either.+ """+ ps = UNINSTALL_PS1.read_text(encoding = "utf-8")+ block = _slice(+ ps, "# Clear the persisted Inductor cache path", "# Remove HKCU\\Software\\Unsloth"+ )+ assert "GetEnvironmentVariable('TORCHINDUCTOR_CACHE_DIR', 'User')" in block+ assert "[NullString]::Value, 'User'" in block+ # Scoped to what this run owns. $knownRoots includes roots the gates refused to delete.+ assert "$ownedRoots" in block and "$knownRoots" not in block+ # Comments stripped first: this block explains why C:\tc is spared, and a comment saying so+ # is not the same thing as code naming it.+ code = "\n".join(line for line in block.splitlines() if not line.lstrip().startswith("#"))+ assert "C:\\tc" not in code+++def test_the_windows_node_guard_treats_a_file_as_occupied():+ """install_node_prebuilt's _swap_into_place renames whatever it finds out of the way.++ Guarding on -PathType Container meant a regular file or a symlink named `node` under a+ user-selected master root was invisible to the check and got displaced. Ownership evidence+ lives inside a directory, so a non-directory can never carry it and is refused outright.+ setup.sh's _assert_studio_owned_or_absent takes the same view of -d against -e and -L.+ """+ ps = SETUP_PS1.read_text(encoding = "utf-8")+ block = _slice(+ ps,+ " $nodeEntry = if ($NodeOverride -or $RuntimeRootIsCustom) {",+ "install_node_prebuilt.py",+ )+ code = "\n".join(line for line in block.splitlines() if not line.lstrip().startswith("#"))+ # Get-Item -Force, not Test-Path: under 5.1 Test-Path answers for the link TARGET, so a+ # dangling `node` link read as absent and install_node_prebuilt.py installed through it.+ assert "Get-Item -LiteralPath $NodeDir -Force" in code, code+ assert "Test-Path -LiteralPath $NodeDir" not in code, code+ # A reparse point is not a directory here either, however it resolves.+ assert "$nodeEntry.PSIsContainer" in code and "ReparsePoint" in code, code+ # And a non-directory must fail rather than fall through to the marker questions.+ assert "$nodeIsDir" in code and "-not $nodeIsDir -or" in code+++def test_the_windows_runtime_guard_treats_a_file_as_occupied():+ """The Node guard above is one of three: llama.cpp and whisper.cpp share+ Assert-StudioOwnedOrAbsent, which was still container-only.++ install_llama_prebuilt's activate_install_tree moves aside whatever Path.exists() finds, so+ a regular file named `llama.cpp` under a master root was renamed to a rollback name and+ replaced. The behaviour is run for real in tests/studio/test_path_probe_access_denied.ps1,+ which the Linux runners cannot execute; this holds the shape there too.+ """+ ps = SETUP_PS1.read_text(encoding = "utf-8")+ block = _slice(ps, "function Assert-StudioOwnedOrAbsent", "function Mark-StudioOwned")+ code = "\n".join(line for line in block.splitlines() if not line.lstrip().startswith("#"))+ # Get-Item -Force, not another Test-Path: 5.1 answers false for a dangling link.+ assert "Get-Item -LiteralPath $Path -Force" in code+ # A non-directory is refused, and only under a root the user chose.+ assert "if (-not $isCustomRoot) { return }" in code+ assert "already exists and is not a directory" in block+ # Fatal even in -NonFatal mode: that mode rescues a denial, not somebody else's file.+ refusal = code[+ code.index("Get-Item -LiteralPath $Path -Force") : code.index("Exit-SetupFailure")+ ]+ assert "$NonFatal" not in refusal, refusal+++def test_neither_uninstaller_takes_a_studio_root_that_is_also_the_master_root():+ """The flat layout, UNSLOTH_HOME and UNSLOTH_STUDIO_HOME naming one directory.++ A Studio root is removed WHOLE once it carries the ownership marker, so in the flat case+ anything else the user keeps in that directory goes with the install. Every other+ master-root child is individually marker-gated precisely so a user-chosen root is never+ removed wholesale; this was the one hole in that rule. Kept rather than pruned: data left+ behind is recoverable and printed, a deleted file is not.+ """+ sh = UNINSTALL_SH.read_text(encoding = "utf-8")+ ps = UNINSTALL_PS1.read_text(encoding = "utf-8")++ sh_block = _slice(sh, "_crf_canon=", '_remove_root_recording_db "$_custom_root"')+ sh_code = "\n".join(l for l in sh_block.splitlines() if not l.lstrip().startswith("#"))+ assert "_MASTER_ROOT_SAVED" in sh_code and "continue" in sh_code+ # Canonicalised on both sides, or a symlinked path compares unequal to itself and the guard+ # never fires on the very layout it is for.+ assert "cd -P --" in sh_code++ ps_block = _slice(ps, "$flatMaster = $masterRootToStop", "_RemoveRootRecordingDb $r")+ ps_code = "\n".join(l for l in ps_block.splitlines() if not l.lstrip().startswith("#"))+ assert "$masterRootToStop" in ps_code and "continue" in ps_code+ # Case-insensitive: Windows paths differing only in case are the same directory.+ assert "-ieq" in ps_code+++def test_neither_uninstaller_re_resolves_the_master_root_after_deleting_it():+ """_master_root can read its answer from a note INSIDE a Studio tree.++ The custom-root loop removes that tree, so a second call after it returns nothing and the+ marked llama.cpp, Node and whisper.cpp siblings are stranded: the very failure the note was+ added to prevent, reintroduced by asking too late. Both scripts resolve it once, before+ anything is deleted, and every later use takes that value.+ """+ sh = UNINSTALL_SH.read_text(encoding = "utf-8")+ ps = UNINSTALL_PS1.read_text(encoding = "utf-8")++ sh_code = "\n".join(l for l in sh.splitlines() if not l.lstrip().startswith("#"))+ saved = sh_code.index('_MASTER_ROOT_SAVED="$(_master_root)"')+ removal = sh_code.index("_custom_studio_roots | while")+ # Resolved before the first deletion, and nothing asks again after it. Calls BEFORE the loop+ # are fine: those enumerate while every tree is still on disk.+ assert saved < removal+ after = sh_code[removal:]+ assert "_master_root" not in after, after[: after.index("_master_root") + 200]+ # Both consumers take the saved value: the flat-layout guard and the children block.+ assert after.count('"$_MASTER_ROOT_SAVED"') >= 2++ ps_code = "\n".join(l for l in ps.splitlines() if not l.lstrip().startswith("#"))+ ps_saved = ps_code.index("$masterRootToStop = _MasterRoot")+ ps_removal = ps_code.index("_RemoveRootRecordingDb $r")+ assert ps_saved < ps_removal+ ps_after = ps_code[ps_removal:]+ assert "_MasterRoot" not in ps_after, ps_after[: ps_after.index("_MasterRoot") + 200]+ assert ps_after.count("$masterRootToStop") >= 1+++def test_neither_uninstaller_sweeps_a_stale_lock_name_it_did_not_make():+ """prebuilt_core.py leaves <name>.stale.<pid>. A dotted glob also matched a user's own+ ".backup.install.lock.stale.copy", and in a root the user chose that file is theirs.+ Behaviour for the POSIX half is in tests/sh/test_uninstall_master_root.sh."""+ sh = UNINSTALL_SH.read_text(encoding = "utf-8")+ ps = UNINSTALL_PS1.read_text(encoding = "utf-8")++ sh_code = "\n".join(l for l in sh.splitlines() if not l.lstrip().startswith("#"))+ assert ".*.install.lock.stale.*" not in sh_code+ # A numeric pid, checked at both sweeps: the master root and the default home.+ assert sh_code.count("*[!0-9]*) continue ;;") >= 2++ ps_code = "\n".join(l for l in ps.splitlines() if not l.lstrip().startswith("#"))+ assert '-like ".*.install.lock.stale.*"' not in ps_code+ assert "$script:StaleLockPattern" in ps_code+ assert "[0-9]+$" in ps_code+++@NEEDS_POSIX_BASH+def test_the_master_root_note_does_not_write_through_a_planted_link(tmp_path):+ """The note is staged under an unpredictable name, so a link left in share/ is not followed.++ The staging name used to be "$notePath.$$", and a shell redirection into an existing symlink+ truncates its target. Anyone who could write share/ -- a portable volume mounted for two+ accounts is the shape that matters, since a master root is what this note records -- could+ therefore point that name at a file of theirs and have setup empty it. The attacker's+ capability is simulated exactly rather than approximated: the link is created by the same+ shell that then runs the shipped block, so "$$" matches the way a guessed pid would.++ setup.sh already states this rule for the uv cache probe ("mktemp (O_EXCL) not $$"); the note+ writer is now held to it too.+ """+ src = SETUP_SH.read_text(encoding = "utf-8")+ block = _slice(src, "_master_root_note_is_honoured() {", "LLAMA_CPP_DIR=")++ # Contained, so the honoured-note gate passes and the writer below actually runs. The gate+ # itself is covered by test_the_master_root_note_is_only_written_when_a_reader_honours_it.+ master = tmp_path / "portable"+ studio_home = master / "studio"+ (studio_home / "share").mkdir(parents = True)+ victim = tmp_path / "victim.txt"+ victim.write_text("do not truncate me\n", encoding = "utf-8")++ script = "\n".join(+ (+ "set -u",+ # The predictable name the old block would have opened.+ 'ln -s "$VICTIM" "$STUDIO_HOME/share/.unsloth-master-root.$$"',+ block,+ )+ )+ completed = subprocess.run(+ ["bash", "-c", script],+ env = {+ "PATH": os.environ.get("PATH", "/usr/bin:/bin"),+ "STUDIO_HOME": str(studio_home),+ "UNSLOTH_HOME": str(master),+ "_MASTER_ROOT": str(master),+ "STAGE_ROOT": "",+ "VICTIM": str(victim),+ },+ capture_output = True,+ text = True,+ timeout = 60,+ )+ assert completed.returncode == 0, completed.stderr++ assert victim.read_text(encoding = "utf-8") == "do not truncate me\n"+ note = studio_home / "share" / ".unsloth-master-root"+ assert note.read_text(encoding = "utf-8").strip() == str(master)+ # The rename replaces a link at the final path rather than writing through it.+ assert not note.is_symlink()+ # No staging file survives the run, whatever name it was given.+ leftovers = sorted(+ p.name+ for p in (studio_home / "share").iterdir()+ if p.name.startswith(".unsloth-master-root.") and not p.is_symlink()+ )+ assert leftovers == [], leftovers+++def test_the_windows_note_writer_creates_its_staging_file_exclusively():+ """The setup.ps1 half of the test above. Held structurally: the Linux runners have no+ Windows filesystem to plant a link on, and CreateNew is the thing that must not regress."""+ ps = SETUP_PS1.read_text(encoding = "utf-8")+ block = _slice(ps, "if ((Get-MasterRootOverride) -and -not $StageRoot -and", "\n# ")+ # Comments stripped, as the other structural checks here do: the block explains the old+ # staging name in prose, and the name is only a finding when something executes it.+ block = "\n".join(l for l in block.splitlines() if not l.lstrip().startswith("#"))++ assert "$notePath.$PID" not in block, "predictable staging name is back"+ assert "GetRandomFileName()" in block+ assert "[System.IO.FileMode]::CreateNew" in block+ # WriteAllText opens an existing path rather than failing on it.+ assert "WriteAllText($noteTmp" not in block+++def _run_note_block(+ tmp_path,+ studio_home,+ master,+ *,+ existing_note = None,+ home = None,+):+ """Run the shipped note gate + writer + legacy sweep against a fixture, and report the note.++ The whole region is executed, not pattern-matched: the gate, the writer it guards and the+ sweep below it are one decision, and slicing them apart is how a gate that never runs passes.+ """+ src = SETUP_SH.read_text(encoding = "utf-8")+ block = _slice(src, "_master_root_note_is_honoured() {", "LLAMA_CPP_DIR=")+ note = studio_home / "share" / ".unsloth-master-root"+ note.parent.mkdir(parents = True, exist_ok = True)+ if existing_note is not None:+ note.write_text(str(existing_note) + "\n", encoding = "utf-8")+ completed = subprocess.run(+ ["bash", "-c", "set -u\n" + block],+ env = {+ "PATH": os.environ.get("PATH", "/usr/bin:/bin"),+ "HOME": str(home if home is not None else tmp_path / "home"),+ "STUDIO_HOME": str(studio_home),+ "UNSLOTH_HOME": str(master),+ "_MASTER_ROOT": str(master),+ "STAGE_ROOT": "",+ },+ capture_output = True,+ text = True,+ timeout = 60,+ )+ assert completed.returncode == 0, completed.stderr+ value = note.read_text(encoding = "utf-8").strip() if note.exists() else None+ return value, completed.stderr+++@NEEDS_POSIX_BASH+def test_the_master_root_note_is_only_written_when_a_reader_honours_it(tmp_path):+ """A note whose Studio tree is not INSIDE the root it names is refused by every reader --+ storage_roots.py, the CLI and both uninstallers all require containment -- so writing one+ records nothing and hides the fact that nothing was recorded.++ This is not a corner. install.sh does not read UNSLOTH_HOME yet, so+ `UNSLOTH_HOME=/mnt/portable unsloth studio update` on an ordinary install is exactly this+ shape: Studio stays at ~/.unsloth/studio while llama.cpp, node and whisper.cpp go to+ /mnt/portable. That is the case the note was added for, and the case in which it was written+ and then thrown away by every reader. Warn instead.+ """+ home = tmp_path / "home"+ studio_home = home / ".unsloth" / "studio"+ master = tmp_path / "portable"+ master.mkdir()+ value, stderr = _run_note_block(tmp_path, studio_home, master, home = home)+ assert value is None, f"wrote a note no reader will honour: {value}"+ assert "cannot be recorded" in stderr, stderr++ # The contained layout, which every reader does honour, still records.+ contained = master / "studio"+ value, _ = _run_note_block(tmp_path, contained, master, home = home)+ assert value == str(master)+++@NEEDS_POSIX_BASH+def test_the_legacy_default_root_is_never_recorded_and_an_old_note_is_cleared(tmp_path):+ """`UNSLOTH_HOME=$HOME/.unsloth` names the directory the install is already in. Both+ uninstallers refuse that value outright, so a note carrying it licenses nothing -- but+ storage_roots honours it, and honouring it flips portable_mode() on for every later BARE+ launch, which moves HF_HUB_CACHE off ~/.cache/huggingface. One command that named the default+ root therefore turned a shared model cache into a private one, permanently, with no variable+ set at the time.++ The write is refused, and an existing note carrying that value is cleared on the next run --+ without the sweep the damage survives the fix, since the writer only runs when UNSLOTH_HOME+ is set again and the user who hit this set it once.+ """+ home = tmp_path / "home"+ studio_home = home / ".unsloth" / "studio"+ legacy_master = home / ".unsloth"+ studio_home.mkdir(parents = True)++ # Contained (studio IS inside ~/.unsloth), so only the legacy-root rule can refuse it.+ value, _ = _run_note_block(tmp_path, studio_home, legacy_master, home = home)+ assert value is None, f"recorded the legacy default root: {value}"++ # An install that already carries one from an earlier build is repaired in place.+ value, _ = _run_note_block(+ tmp_path,+ studio_home,+ legacy_master,+ existing_note = legacy_master,+ home = home,+ )+ assert value is None, "a stale legacy-root note survived"++ # A note naming any other root is left alone: it may describe an install this run cannot see.+ other = tmp_path / "portable"+ other.mkdir()+ value, _ = _run_note_block(+ tmp_path,+ studio_home,+ legacy_master,+ existing_note = other,+ home = home,+ )+ assert value == str(other)+++def test_the_windows_note_gate_holds_the_same_two_rules():+ """The setup.ps1 half of the two tests above. Structural: no PowerShell-on-Linux run can+ exercise %USERPROFILE% canonicalisation the way a real Windows profile does."""+ ps = SETUP_PS1.read_text(encoding = "utf-8")+ gate = _slice(ps, "function Test-MasterRootNoteIsHonoured {", "\nif ((Get-MasterRootOverride)")+ assert "$legacy = Get-CanonicalDir" in gate, "the legacy default root is not refused"+ assert "StartsWith($norm + $sep" in gate, "containment is not checked"+ # The gate has to be wired into the writer, not merely defined beside it.+ assert "Test-MasterRootNoteIsHonoured -Root $UnslothHome -StudioRoot $StudioHome" in ps+ sweep = _slice(ps, "$staleNote = Join-Path", "} catch {")+ assert "Remove-Item -LiteralPath $staleNote" in sweep+++def test_the_windows_note_writer_is_a_no_op_when_the_note_already_says_this():+ """Move-Item -Force is not an atomic replace: PowerShell's provider deletes the destination+ and then moves the source, so an interruption in between leaves NO note, and a backend that+ looks next caches "no master root" from it. Re-entering that window on every update to+ rewrite bytes that are already there is the avoidable half, and the staging file has to go+ whether the move threw or not.++ Run under pwsh rather than asserted from source text: the comparison is the point, and a+ structural check would pass on a version that compares the wrong two things.+ """+ ps = SETUP_PS1.read_text(encoding = "utf-8")+ block = _slice(+ ps, ' $notePath = Join-Path $noteDir ".unsloth-master-root"', "\n } catch {"+ )+ assert "Remove-Item -LiteralPath $noteTmp" in block, "the staging file is never cleaned up"+ assert "$noteSame" in block, "the note is rewritten even when it already says this"++[email protected](PWSH is None, reason = "needs pwsh")+def test_the_windows_note_writer_rewrites_only_when_the_value_changed(tmp_path):+ """The behaviour, measured: same value twice leaves the file untouched; a different value+ replaces it; and no staging file survives either way."""+ ps = SETUP_PS1.read_text(encoding = "utf-8")+ block = _slice(+ ps, ' $notePath = Join-Path $noteDir ".unsloth-master-root"', "\n } catch {"+ )+ note_dir = tmp_path / "share"+ note_dir.mkdir()+ script = tmp_path / "write_note.ps1"+ script.write_text(+ f"$noteDir = {_ps_quote(str(note_dir))}\n"+ f"$UnslothHome = {_ps_quote(str(tmp_path / 'master'))}\n"+ + block+ + "\n$final = Join-Path $noteDir '.unsloth-master-root'\n"+ "$stamp = (Get-Item -LiteralPath $final).LastWriteTimeUtc.Ticks\n"+ "Write-Output ((Get-Content -LiteralPath $final -Raw) + '|' + $stamp)\n",+ encoding = "utf-8",+ )+ argv = [PWSH, "-NoProfile", "-File", str(script)]+ first = run_pwsh(argv, capture_output = True, text = True, check = True)+ note = note_dir / ".unsloth-master-root"++ # Back-dated so a rewrite is unmistakable: two runs a millisecond apart land on one+ # filesystem tick, which is how the first version of this test passed against the unfixed+ # writer.+ old_stamp = 1_000_000_000+ os.utime(note, (old_stamp, old_stamp))++ second = run_pwsh(argv, capture_output = True, text = True, check = True)++ body_1, _ = first.stdout.strip().rsplit("|", 1)+ body_2, _ = second.stdout.strip().rsplit("|", 1)+ assert body_1 == body_2 == str(tmp_path / "master") + "\n"+ assert (+ int(note.stat().st_mtime) == old_stamp+ ), "an unchanged note was rewritten, re-entering the delete-then-move window"+ leftovers = [p.name for p in note_dir.iterdir() if p.name != ".unsloth-master-root"]+ assert leftovers == [], leftovers++ # And a CHANGED value must still be written, or the check above passes by doing nothing.+ script.write_text(+ script.read_text(encoding = "utf-8").replace(+ _ps_quote(str(tmp_path / "master")), _ps_quote(str(tmp_path / "moved"))+ ),+ encoding = "utf-8",+ )+ run_pwsh(argv, capture_output = True, text = True, check = True)+ assert note.read_text(encoding = "utf-8").strip() == str(tmp_path / "moved")+ assert int(note.stat().st_mtime) != old_stampdiff --git a/tests/test_studio_install_workspace_guard.py b/tests/test_studio_install_workspace_guard.pyindex 6bbfe72771d..45ffb5b3ebf 100644--- a/tests/test_studio_install_workspace_guard.py+++ b/tests/test_studio_install_workspace_guard.py@@ -697,15 +697,30 @@ def test_setup_helpers_gate_on_canonical_custom_root():"""setup.sh/setup.ps1 ownership guards must gate on a canonical custom-vs-legacy root comparison."""sh_src = SETUP_SH.read_text(encoding = "utf-8")sh_idx = sh_src.index("_assert_studio_owned_or_absent() {")- sh_func = sh_src[sh_idx : sh_idx + 600]+ # To the end of the function, not a fixed width, for the reason the PowerShell half below+ # already gives: a new parameter or comment pushes the assertions out of a fixed window and+ # the test fails while the guard it is about is intact.+ sh_func = sh_src[sh_idx:].split("\n}\n", 1)[0]+ # The caller may name the flag (the runtime children pass _RUNTIME_ROOT_IS_CUSTOM), but the+ # default has to stay the canonical one.assert (- '"$_STUDIO_HOME_IS_CUSTOM" = true' in sh_func- ), "setup.sh _assert_studio_owned_or_absent must gate on _STUDIO_HOME_IS_CUSTOM"+ '_aso_custom="${3:-$_STUDIO_HOME_IS_CUSTOM}"' in sh_func+ and '"$_aso_custom" = true' in sh_func+ ), "setup.sh _assert_studio_owned_or_absent must gate on the canonical custom-root flag"assert ("_LEGACY_STUDIO_HOME=" in sh_srcand "_studio_home_canon=" in sh_srcand "_STUDIO_HOME_IS_CUSTOM=" in sh_src), "setup.sh must compute the canonical custom-root flag"+ # A master root moves the runtime children, so the flag has to widen to cover them. Not the+ # exact one-liner this used to name: UNSLOTH_HOME can legitimately name ~/.unsloth, the root a+ # default install already uses, and treating that as custom made an update reject a legacy+ # source-built llama.cpp that carries no owner marker. tests/test_setup_master_root.py runs+ # the shipped derivation for that case; the rule here is the two halves being present.+ assert '_RUNTIME_ROOT_IS_CUSTOM="$_STUDIO_HOME_IS_CUSTOM"' in sh_src+ assert (+ "_RUNTIME_ROOT_IS_CUSTOM=true" in sh_src and "$_MASTER_ROOT" in sh_src+ ), "setup.sh must widen the flag to a master root, which moves the runtime children"ps_src = SETUP_PS1.read_text(encoding = "utf-8")ps_idx = ps_src.index("function Assert-StudioOwnedOrAbsent")@@ -713,8 +728,8 @@ def test_setup_helpers_gate_on_canonical_custom_root():# out of.ps_func = ps_src[ps_idx:].split("\nfunction ", 1)[0]assert (- "$StudioHomeIsCustom -and" in ps_func- ), "setup.ps1 Assert-StudioOwnedOrAbsent must gate on $StudioHomeIsCustom"+ "$isCustomRoot = $StudioHomeIsCustom" in ps_func and "$isCustomRoot -and" in ps_func+ ), "setup.ps1 Assert-StudioOwnedOrAbsent must gate on the canonical custom-root flag"assert ("$StudioOwnedMarker) -PathType Leaf" in ps_func), "setup.ps1 marker check must use -PathType Leaf so a directory cannot satisfy it"@@ -730,8 +745,8 @@ def test_setup_ps1_inplace_git_sync_marks_studio_owned():"Mark-StudioOwned -Path $LlamaCppDir" in inplace_block), "in-place git-sync branch must call Mark-StudioOwned on success"assert (- "$StudioHomeIsCustom" in inplace_block- ), "in-place Mark-StudioOwned call should be gated on $StudioHomeIsCustom"+ "$RuntimeRootIsCustom" in inplace_block+ ), "in-place Mark-StudioOwned call should be gated on $RuntimeRootIsCustom"def test_setup_ps1_inplace_git_sync_asserts_studio_owned_before_mutation():@@ -926,6 +941,99 @@ def test_tauri_preflight_scrubs_studio_home_env():assert ('cmd.env_remove("STUDIO_HOME")' in commands), "commands.rs check_install_status must scrub STUDIO_HOME"+ # Belt and braces: the managed context is what removes the whole list at these sites.+ assert (+ preflight.count("apply_managed_cli_context_tokio(&mut cmd)") >= 2+ ), "preflight probes must build the managed context, which is what applies the scrub list"+ assert (+ "apply_managed_cli_context_tokio(&mut cmd)" in commands+ ), "commands.rs check_install_status must build the managed context"+++# The three storage_roots.py resolvers that CHOOSE a data root, as opposed to the ones that+# join a subdirectory onto whatever they chose. Every environment variable read inside them+# moves the desktop's databases, assets and caches, so every one has to be scrubbed.+# _env_unsloth_home is the env-reading half unsloth_home splits into once it grows an on-disk+# fallback. Absent resolvers are skipped, not failed, so this holds for either spelling.+_ROOT_CHOOSING_RESOLVERS = (+ "unsloth_home",+ "_env_unsloth_home",+ "portable_mode",+ "studio_root",+)+++def _root_moving_env_names() -> set[str]:+ """The env vars storage_roots.py picks a root from, read out of the shipped source.++ Derived rather than written down, so a fourth root variable fails this test on the commit+ that adds it instead of on the bug report that follows it.+ """+ source = (REPO_ROOT / "studio" / "backend" / "utils" / "paths" / "storage_roots.py").read_text(+ encoding = "utf-8"+ )+ names: set[str] = set()+ seen = 0+ for resolver in _ROOT_CHOOSING_RESOLVERS:+ marker = f"\ndef {resolver}("+ if marker not in source:+ continue+ seen += 1+ start = source.index(marker)+ end = source.index("\ndef ", start + 1)+ names |= set(re.findall(r'os\.environ\.get\(\s*"([A-Z][A-Z0-9_]*)"', source[start:end]))+ assert seen, "none of the root-choosing resolvers exist under these names any more"+ assert names, "the root-choosing resolvers read no environment variable any more"+ return names+++def _rust_string_list(source: str, const_name: str) -> list[str]:+ """The string literals in a `const NAME: &[&str] = &[...];` declaration."""+ start = source.index(f"const {const_name}:")+ return re.findall(r'"([^"]*)"', source[start : source.index(";", start)])+++def test_tauri_managed_children_scrub_every_root_moving_env():+ """A shell-level Unsloth root must not reach the packaged desktop's Python children.++ The desktop pins the legacy ~/.unsloth root and hardcodes it in Rust, so any variable+ storage_roots.py would resolve a different root from has to be removed before the spawn,+ or the databases, assets and caches move while the Rust half keeps reading the old place.+ """+ src_root = REPO_ROOT / "studio" / "src-tauri" / "src"+ process = (src_root / "process.rs").read_text(encoding = "utf-8")+ install = (src_root / "install.rs").read_text(encoding = "utf-8")++ scrubbed = _rust_string_list(process, "MANAGED_CHILD_SCRUBBED_ENV")+ assert len(scrubbed) == len(set(scrubbed)), f"duplicate names in the scrub list: {scrubbed}"+ missing = sorted(_root_moving_env_names() - set(scrubbed))+ assert not missing, (+ f"{missing} would redirect the managed backend's data root away from the legacy one "+ "the Tauri shell hardcodes"+ )++ # Second scrub path: start_backend removes the list again after the managed context, so+ # the skip is a fact about the child. The whole list, not a subset that can drift.+ start = process.index("pub fn start_backend(")+ end = min(+ offset+ for offset in (process.find("\npub fn ", start + 1), process.find("\nfn ", start + 1))+ if offset != -1+ )+ backend_start = process[start:end]+ assert (+ "for name in MANAGED_CHILD_SCRUBBED_ENV" in backend_start+ ), "start_backend must scrub the whole list, not the names that were in it when it was written"++ # Third spawn path: the installer runs install.sh / install.ps1 directly, never reaching+ # apply_managed_cli_context, so it applies the list itself.+ assert (+ "for name in crate::process::MANAGED_CHILD_SCRUBBED_ENV" in install+ ), "install.rs spawns outside the managed context and must scrub the whole list"+ for name in scrubbed:+ assert (+ f'cmd.env_remove("{name}")' not in install+ ), f"install.rs scrubs {name} by hand as well as by list; the hand-written copy can rot"def test_install_sh_shim_uses_atomic_replace():diff --git a/tests/test_studio_root_resilience.py b/tests/test_studio_root_resilience.pyindex edd820c8b2b..d19fcd27d2b 100644--- a/tests/test_studio_root_resilience.py+++ b/tests/test_studio_root_resilience.py@@ -115,7 +115,10 @@ def test_kill_orphan_catches_oserror_from_studio_root():def _exec_search_roots_block(- home: Path, studio_root_value: Path, resolve_raises: bool+ home: Path,+ studio_root_value: Path,+ resolve_raises: bool,+ master: Path | None = None,) -> list[Path]:"""Run _find_llama_server_binary's search_roots derivation -- plus the shared_resolved_studio_root_and_is_legacy() classifier it delegates to -- with a@@ -138,6 +141,7 @@ def _exec_search_roots_block(block = textwrap.dedent(" " * 8 + src[block_start:block_end])fake_module = type(sys)("fake_storage_roots")fake_module.studio_root = lambda: studio_root_value+ fake_module.unsloth_home = lambda: mastersys.modules["utils.paths.storage_roots"] = fake_moduletry:original_resolve = Path.resolve@@ -183,6 +187,20 @@ def test_search_roots_keeps_custom_when_resolve_fails(tmp_path):) not in roots, f"legacy llama path must not appear in custom-mode search_roots: {roots}"+def test_search_roots_follow_the_master_root(tmp_path):+ # llama.cpp is a sibling of studio/ there; a failing resolve() must not drop the master root.+ home = tmp_path / "home"+ home.mkdir()+ master = tmp_path / "portable"+ roots = _exec_search_roots_block(+ home = home,+ studio_root_value = master / "studio",+ resolve_raises = True,+ master = master,+ )+ assert roots == [master / "llama.cpp"]++def test_search_roots_default_mode_uses_legacy_only(tmp_path):home = tmp_path / "home"home.mkdir()diff --git a/tests/test_unsloth_home_root_agreement.py b/tests/test_unsloth_home_root_agreement.pynew file mode 100644index 00000000000..882e261fc85--- /dev/null+++ b/tests/test_unsloth_home_root_agreement.py@@ -0,0 +1,333 @@+# Unsloth Zoo - Utilities for Unsloth+# Copyright 2023-present Daniel Han-Chen, Michael Han-Chen & the Unsloth team. All rights reserved.+#+# This program is free software: you can redistribute it and/or modify+# it under the terms of the GNU Affero General Public License as published+# by the Free Software Foundation, either version 3 of the License, or+# (at your option) any later version.+#+# This program is distributed in the hope that it will be useful,+# but WITHOUT ANY WARRANTY; without even the implied warranty of+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the+# GNU Affero General Public License for more details.+#+# You should have received a copy of the GNU Affero General Public License+# along with this program. If not, see <https://www.gnu.org/licenses/>.++"""UNSLOTH_HOME has to mean the same install to the CLI and to the backend: if the two disagree+the backend writes studio.db, auth and the pid file under <UNSLOTH_HOME>/studio while the CLI+reads ~/.unsloth/studio.+"""++from __future__ import annotations++import json+import os+import subprocess+import sys+from pathlib import Path++REPO_ROOT = Path(__file__).resolve().parents[1]++_PROBE = """+import json, sys+sys.path.insert(0, {backend!r})+import os+from unsloth_cli.commands import studio as cli+from utils.paths.storage_roots import studio_root, unsloth_home+cli._ensure_studio_env_exported()+master = unsloth_home()+print(json.dumps({{+ "cli": str(cli.STUDIO_HOME),+ "cli_is_custom": bool(cli._STUDIO_HOME_IS_CUSTOM),+ "backend": str(studio_root()),+ "exported_studio_home": os.environ.get("UNSLOTH_STUDIO_HOME"),+ "cli_llama": os.environ.get("UNSLOTH_LLAMA_CPP_PATH"),+ "exported_master": os.environ.get("UNSLOTH_HOME"),+ "backend_llama": str((master or studio_root()) / "llama.cpp"),+}}))+"""+++def _probe(env_overrides: dict) -> dict:+ env = dict(os.environ)+ # UNSLOTH_LLAMA_CPP_PATH too, as _main_probe does: an inherited value measures the runner.+ for key in ("UNSLOTH_HOME", "UNSLOTH_STUDIO_HOME", "STUDIO_HOME", "UNSLOTH_LLAMA_CPP_PATH"):+ env.pop(key, None)+ env.update(env_overrides)+ env["PYTHONPATH"] = str(REPO_ROOT)+ source = _PROBE.format(backend = str(REPO_ROOT / "studio" / "backend"))+ out = subprocess.run(+ [sys.executable, "-c", source],+ capture_output = True,+ text = True,+ cwd = str(REPO_ROOT),+ env = env,+ check = True,+ )+ return json.loads(out.stdout.strip().splitlines()[-1])+++def test_unsloth_home_resolves_to_one_studio_root(tmp_path):+ master = tmp_path / "portable"+ result = _probe({"UNSLOTH_HOME": str(master)})++ assert result["backend"] == str(master / "studio")+ assert result["cli"] == result["backend"]+ # Custom, so `unsloth studio ...` re-exports UNSLOTH_STUDIO_HOME.+ assert result["cli_is_custom"] is True+++def test_studio_home_still_outranks_unsloth_home(tmp_path):+ explicit = tmp_path / "explicit"+ result = _probe(+ {"UNSLOTH_HOME": str(tmp_path / "portable"), "UNSLOTH_STUDIO_HOME": str(explicit)}+ )++ assert result["backend"] == str(explicit)+ assert result["cli"] == str(explicit)+++def test_no_unsloth_home_keeps_the_legacy_default(tmp_path):+ result = _probe({"HOME": str(tmp_path / "home"), "USERPROFILE": str(tmp_path / "home")})++ legacy = str(tmp_path / "home" / ".unsloth" / "studio")+ assert result["cli"] == legacy+ assert result["backend"] == legacy+ assert result["cli_is_custom"] is False+++def test_the_cli_exports_the_llama_cpp_path_the_backend_will_use(tmp_path):+ # run.py keeps a non-blank UNSLOTH_LLAMA_CPP_PATH, so a CLI exporting+ # <root>/studio/llama.cpp pins that wrong path for every worker.+ master = tmp_path / "portable"+ result = _probe({"UNSLOTH_HOME": str(master)})++ assert result["cli_llama"] == str(master / "llama.cpp")+ assert result["cli_llama"] == result["backend_llama"]+++def test_the_cli_recovers_a_recorded_master_root_for_the_setup_subprocess(tmp_path):+ # A one-command UNSLOTH_HOME leaves nothing in a later environment, and the backend recovers+ # the root from the note, so a CLI that did not would have setup refresh the runtimes at+ # <master>/studio/ while the backend launched the stale ones at <master>/. Exported rather+ # than read, since setup is a subprocess.+ master = tmp_path / "portable"+ studio = master / "studio"+ (studio / "share").mkdir(parents = True)+ (studio / "share" / ".unsloth-master-root").write_text(f"{master}\n", encoding = "utf-8")+ result = _probe({"UNSLOTH_STUDIO_HOME": str(studio)})++ assert result["exported_master"] == str(master)+ assert result["cli_llama"] == str(master / "llama.cpp")+ assert result["cli_llama"] == result["backend_llama"]+++def test_the_cli_and_the_backend_accept_the_same_nested_studio_root(tmp_path):+ # A real pairing: setup records <root>, and the Studio directory is inside it without being+ # its studio/ child. A stricter rule in the CLI would decline a note the backend accepts.+ master = tmp_path / "root"+ studio = master / "custom" / "studio"+ (studio / "share").mkdir(parents = True)+ (studio / "share" / ".unsloth-master-root").write_text(f"{master}\n", encoding = "utf-8")+ result = _probe({"UNSLOTH_STUDIO_HOME": str(studio)})++ assert result["exported_master"] == str(master)+ assert result["cli"] == str(studio)+ assert result["cli_llama"] == str(master / "llama.cpp")+ assert result["cli_llama"] == result["backend_llama"]+++def test_the_cli_refuses_a_note_carried_in_from_another_master_root(tmp_path):+ # A Studio tree copied from master root A to B keeps a note naming A. Exporting it would+ # point an update at the original install; the Studio directory has to lie inside the root+ # its note names, which is the rule storage_roots and both uninstallers apply.+ original = tmp_path / "original"+ (original / "studio").mkdir(parents = True)+ copied = tmp_path / "copied" / "studio"+ (copied / "share").mkdir(parents = True)+ (copied / "share" / ".unsloth-master-root").write_text(f"{original}\n", encoding = "utf-8")+ result = _probe({"UNSLOTH_STUDIO_HOME": str(copied)})++ assert result["exported_master"] is None+ assert result["cli_llama"] == str(copied / "llama.cpp")+ assert result["cli_llama"] == result["backend_llama"]+++def test_a_plain_custom_root_still_keeps_llama_cpp_inside_it(tmp_path):+ explicit = tmp_path / "explicit"+ result = _probe({"UNSLOTH_STUDIO_HOME": str(explicit)})++ assert result["cli_llama"] == str(explicit / "llama.cpp")+ assert result["cli_llama"] == result["backend_llama"]+++def test_a_master_root_the_cli_declined_is_still_told_to_the_backend(tmp_path):+ """The one root the CLI picks that the backend would not pick for itself.++ install.sh and install.ps1 do not read UNSLOTH_HOME yet, so _resolve_studio_home keeps an+ exported-but-uninstalled master root off the legacy install that actually exists. That+ fallback is not custom, and returning early on non-custom exported nothing at all, so+ studio_root() in the backend went on honouring UNSLOTH_HOME with no install check: the CLI+ ran the legacy venv while the backend under it wrote studio.db, auth and the pid file to+ <master>/studio. The other tests here point the master root at an empty directory AND leave+ the legacy root uninstalled, so the fallback is never entered by them.+ """+ home = tmp_path / "home"+ # The sentinel _looks_like_installer_managed_studio_home reads.+ conf = home / ".unsloth" / "studio" / "share" / "studio.conf"+ conf.parent.mkdir(parents = True)+ conf.write_text("installed\n", encoding = "utf-8")++ result = _probe(+ {+ "HOME": str(home),+ "USERPROFILE": str(home),+ "UNSLOTH_HOME": str(tmp_path / "portable"),+ }+ )++ legacy = str(home / ".unsloth" / "studio")+ assert result["cli"] == legacy+ # Not custom: the root is the Unsloth-owned legacy one, and false is what lets the+ # installers replace the tree without an owner marker.+ assert result["cli_is_custom"] is False+ assert result["exported_studio_home"] == legacy+ assert result["backend"] == legacy+++def test_a_whitespace_studio_home_does_not_defeat_the_export(tmp_path):+ """The same fallback as above, with an inherited UNSLOTH_STUDIO_HOME of " ".++ Every resolver strips before deciding, so " " means unset to _resolve_studio_home and to+ studio_root alike. The export guard read the raw value, where " " is truthy, so it left the+ whitespace in place: the CLI ran the legacy install and the backend under it resolved+ <master>/studio, which is the split this file exists to prevent. Blank was already covered by+ the guard; whitespace-only was the shape that got through.+ """+ home = tmp_path / "home"+ conf = home / ".unsloth" / "studio" / "share" / "studio.conf"+ conf.parent.mkdir(parents = True)+ conf.write_text("installed\n", encoding = "utf-8")++ legacy = str(home / ".unsloth" / "studio")+ for inherited in (" ", "", "\t\n"):+ result = _probe(+ {+ "HOME": str(home),+ "USERPROFILE": str(home),+ "UNSLOTH_HOME": str(tmp_path / "portable"),+ "UNSLOTH_STUDIO_HOME": inherited,+ "UNSLOTH_LLAMA_CPP_PATH": inherited,+ }+ )+ assert result["cli"] == legacy, inherited+ assert result["exported_studio_home"] == legacy, inherited+ assert result["backend"] == legacy, inherited+ # The runtimes live beside studio/ at the master root, and a whitespace value left in+ # place would be scanned as a directory rather than replaced.+ assert result["cli_llama"] == str(tmp_path / "portable" / "llama.cpp"), inherited+++def test_a_legacy_install_still_keeps_llama_cpp_at_the_legacy_path(tmp_path):+ home = tmp_path / "home"+ (home / ".unsloth" / "studio").mkdir(parents = True)+ result = _probe({"HOME": str(home), "USERPROFILE": str(home)})++ # Not custom, so nothing is exported at all and the backend default stands.+ assert result["cli_llama"] is None+ assert result["backend_llama"] == str(home / ".unsloth" / "studio" / "llama.cpp")+++_MAIN_PROBE = """+import json, sys, types+sys.path.insert(0, {backend!r})+# main.py pulls in the whole app on import, so exec only its module-level+# llama.cpp block, which is what decides the managed path and marks it.+import os, re+from pathlib import Path+src = Path({backend!r}, "main.py").read_text(encoding = "utf-8")+# Anchored on the master-root lookup rather than the `if`, because the guard+# reads _MASTER_ROOT and a slice starting at the `if` would not define it.+start = src.index('from utils.paths.storage_roots import unsloth_home as _unsloth_home')+end = src.index('# The studio bundles unsloth_zoo', start)+if 'if _STUDIO_ROOT_RESOLVED != _LEGACY_STUDIO_ROOT' not in src[start:end]:+ raise AssertionError("the extracted slice no longer contains the export guard")+from utils.paths.storage_roots import studio_root as _studio_root+_LEGACY_STUDIO_ROOT = (Path.home() / ".unsloth" / "studio").resolve()+_STUDIO_ROOT_RESOLVED = _studio_root().resolve()+marked = []+mod = types.ModuleType("utils.llama_cpp_path_settings")+mod.mark_managed_llama_cpp_path = lambda p: marked.append(str(p))+sys.modules["utils.llama_cpp_path_settings"] = mod+exec(compile(src[start:end], "main.py", "exec"), globals())+print(json.dumps({{+ "exported": os.environ.get("UNSLOTH_LLAMA_CPP_PATH"),+ "marked": marked,+}}))+"""+++def _main_probe(env_overrides: dict) -> dict:+ env = dict(os.environ)+ for key in ("UNSLOTH_HOME", "UNSLOTH_STUDIO_HOME", "STUDIO_HOME", "UNSLOTH_LLAMA_CPP_PATH"):+ env.pop(key, None)+ env.update(env_overrides)+ env["PYTHONPATH"] = str(REPO_ROOT)+ source = _MAIN_PROBE.format(backend = str(REPO_ROOT / "studio" / "backend"))+ out = subprocess.run(+ [sys.executable, "-c", source],+ capture_output = True,+ text = True,+ cwd = str(REPO_ROOT),+ env = env,+ check = True,+ )+ return json.loads(out.stdout.strip().splitlines()[-1])+++def test_main_marks_the_same_llama_cpp_path_run_py_exports(tmp_path):+ # A direct `uvicorn main:app` exports this outright; under run.py main.py would instead+ # mark the wrong path managed, making the bundled one look like an override.+ master = tmp_path / "portable"+ result = _main_probe({"UNSLOTH_HOME": str(master)})++ assert result["exported"] == str(master / "llama.cpp")+ assert result["marked"] == [str(master / "llama.cpp")]+++def test_main_leaves_a_plain_custom_root_alone(tmp_path):+ explicit = tmp_path / "explicit"+ result = _main_probe({"UNSLOTH_STUDIO_HOME": str(explicit)})++ assert result["exported"] == str(explicit / "llama.cpp")+ assert result["marked"] == [str(explicit / "llama.cpp")]+++def test_main_exports_for_a_master_root_that_is_the_legacy_path(tmp_path):+ # A portable install pointed at the legacy Studio path still owns <root>/llama.cpp, so the+ # legacy equality alone skipped the export and left unsloth_zoo on ~/.unsloth/llama.cpp.+ home = tmp_path / "home"+ legacy = home / ".unsloth" / "studio"+ legacy.mkdir(parents = True)+ result = _main_probe(+ {+ "HOME": str(home),+ "USERPROFILE": str(home),+ "UNSLOTH_HOME": str(legacy),+ "UNSLOTH_STUDIO_HOME": str(legacy),+ }+ )++ assert result["exported"] == str(legacy / "llama.cpp")+ assert result["marked"] == [str(legacy / "llama.cpp")]+++def test_main_still_exports_nothing_without_a_master_root(tmp_path):+ # The other half: no master root, so the guard stays closed rather than pinning the default.+ home = tmp_path / "home"+ (home / ".unsloth" / "studio").mkdir(parents = True)+ result = _main_probe({"HOME": str(home), "USERPROFILE": str(home)})++ assert result["exported"] is None+ assert result["marked"] == []diff --git a/unsloth_cli/_inference.py b/unsloth_cli/_inference.pyindex 10ad1cf1c3e..76e576e0873 100644--- a/unsloth_cli/_inference.py+++ b/unsloth_cli/_inference.py@@ -132,10 +132,41 @@ def read_json_checking_deferred_error(url: str, response):return require_completed_padded_body(url, raise_for_deferred_error(url, body))-def ensure_studio_backend_path() -> None:+_cache_env_seeded = False+++def _seed_cache_env() -> None:+ """Pin the cache locations the backend pins, for in-process CLI commands.++ Otherwise they inherit unsloth_zoo's relative UNSLOTH_COMPILE_LOCATION, resolved against the+ working directory, leaving an unsloth_compiled_cache cache_cleanup will not remove (#8865).+ """+ global _cache_env_seeded+ if _cache_env_seeded:+ return+ _cache_env_seeded = True+ try:+ from utils.paths.storage_roots import setup_cache_env+ setup_cache_env()+ except Exception: # noqa: BLE001 - never fail a command over cache placement+ pass+++def ensure_studio_backend_path(*, seed_cache_env: bool = True) -> None:+ """Put studio/backend on sys.path, and by default pin the cache locations too.++ `seed_cache_env = False` is for callers that only want to IMPORT a path helper.+ setup_cache_env() creates every cache directory it pins, so seeding it from+ `unsloth start`'s Node discovery turned a read-only lookup into 18 mkdirs under a home+ that may have nothing to do with the command being run -- including one against a remote+ server. Seeding stays on for the ML entry points, where the pins are the point.+ """backend_dir = str(Path(__file__).resolve().parents[1] / "studio" / "backend")if backend_dir not in sys.path:sys.path.insert(0, backend_dir)+ if seed_cache_env:+ # After the path insert, before the caller's backend import pulls in unsloth_zoo.compiler.+ _seed_cache_env()def configure_quiet_logging() -> None:diff --git a/unsloth_cli/_studio_deps.py b/unsloth_cli/_studio_deps.pyindex 516070e7d8c..b5db9d270cf 100644--- a/unsloth_cli/_studio_deps.py+++ b/unsloth_cli/_studio_deps.py@@ -681,7 +681,15 @@ def studio_backend_imports(feature: str = "This command", *, studio_only: bool =Only ModuleNotFoundError is intercepted; any other ImportError from thebackend is a real bug and keeps its traceback.++ Every CLI backend import goes through here, so the cache env is pinned here too: `export` and+ `list-checkpoints` reach studio.backend.core.export without calling+ ensure_studio_backend_path(), and would import unsloth_zoo.compiler with+ UNSLOTH_COMPILE_LOCATION unset, writing unsloth_compiled_cache into the working dir (#8865)."""+ from unsloth_cli._inference import ensure_studio_backend_path++ ensure_studio_backend_path()try:yieldexcept ModuleNotFoundError as exc:diff --git a/unsloth_cli/_system_dir_guard.py b/unsloth_cli/_system_dir_guard.pyindex 39afbddd850..790dd15c0e2 100644--- a/unsloth_cli/_system_dir_guard.py+++ b/unsloth_cli/_system_dir_guard.py@@ -281,6 +281,8 @@ def is_relocatable_invocation(argv, environ):# Path overrides written relative to the folder being left: Unsloth resolves them with# Path.resolve(), so moving first would silently retarget them._RELATIVE_PATH_ENV = (+ # Unsloth roots: storage_roots.py.+ "UNSLOTH_HOME","UNSLOTH_STUDIO_HOME","STUDIO_HOME","UNSLOTH_STUDIO_DOCUMENTS_HOME",@@ -321,6 +323,18 @@ _RELATIVE_PATH_ENV = ("UNSLOTH_DG_SHIM","UNSLOTH_COMPILE_LOCATION","TORCHINDUCTOR_CACHE_DIR",+ # storage_roots.py fills these only when blank, so a relative value the user set is kept as+ # written and would name a different folder after the move.+ "TORCH_EXTENSIONS_DIR",+ "TORCH_HOME",+ "TRITON_HOME",+ "TRITON_CACHE_DIR",+ "TRITON_DUMP_DIR",+ "CUDA_CACHE_PATH",+ "MPLCONFIGDIR",+ "NUMBA_CACHE_DIR",+ "DATA_DESIGNER_HOME",+ "DATA_DESIGNER_MANAGED_ASSETS_PATH","UNSLOTH_DIFFUSION_COMPILE_CACHE_DIR","UNSLOTH_DIFFUSION_COND_CACHE_DIR","HF_HOME",@@ -329,6 +343,9 @@ _RELATIVE_PATH_ENV = ("HF_XET_CACHE","HF_DATASETS_CACHE","HF_ASSETS_CACHE",+ # transformers appends this to sys.path, so a relative value would import a different+ # generated module after the move.+ "HF_MODULES_CACHE",# The credential file: a relative value would follow the child and lose access to gated repos."HF_TOKEN_PATH",# Authoritative when non-blank (storage_roots.py), so `unsloth studio update` would installdiff --git a/unsloth_cli/commands/start.py b/unsloth_cli/commands/start.pyindex d85255fe7f0..bdfc819f392 100644--- a/unsloth_cli/commands/start.py+++ b/unsloth_cli/commands/start.py@@ -3534,7 +3534,9 @@ def _refresh_windows_path() -> None:def _managed_node_tools() -> Optional[tuple[Path, Path, bool]]:# Best-effort: any failure here means "no managed Node", never a broken launch.try:- ensure_studio_backend_path()+ # Discovery only: this answers "is there a managed Node", including for a launch aimed+ # at a remote server, so it must not create the cache tree on the way past.+ ensure_studio_backend_path(seed_cache_env = False)from utils.node_runtime import managed_node_binary, resolve_node_executablenode = Path(managed_node_binary())except (ImportError, OSError, RuntimeError, TypeError, ValueError):diff --git a/unsloth_cli/commands/studio.py b/unsloth_cli/commands/studio.pyindex a89b81ddf86..c06b229ed87 100644--- a/unsloth_cli/commands/studio.py+++ b/unsloth_cli/commands/studio.py@@ -40,7 +40,9 @@ def _enable_verbose_access_logs() -> None:os.environ["UNSLOTH_STUDIO_ACCESS_LOG_POLL_DEDUP_MS"] = "0"-# Root order: UNSLOTH_STUDIO_HOME, STUDIO_HOME, sys.prefix, legacy ~/.unsloth/studio. Markers mirror install.ps1 / uninstall.ps1 and are matched as bytes.+# Root order: UNSLOTH_STUDIO_HOME, STUDIO_HOME, UNSLOTH_HOME/studio, sys.prefix,+# legacy ~/.unsloth/studio. Keep this aligned with storage_roots.studio_root().+# Shim markers mirror install.ps1 / uninstall.ps1 and are matched as bytes._CMD_SHIM_MARKERS = (b"unsloth-studio-managed-launcher", b"from unsloth_cli import app")_CMD_SHIM_MAX_BYTES = 8192@@ -76,6 +78,25 @@ def _resolve_studio_home() -> tuple[Path, bool]:return Path(override).expanduser().resolve(), Trueexcept (OSError, ValueError):return Path(override).expanduser(), True+ # Keeps the CLI on the same root as storage_roots.py; see test_unsloth_home_root_agreement.py.+ master = (os.environ.get("UNSLOTH_HOME") or "").strip()+ if master:+ try:+ candidate = Path(master).expanduser().resolve() / "studio"+ except (OSError, ValueError):+ candidate = Path(master).expanduser() / "studio"+ try:+ legacy = (Path.home() / ".unsloth" / "studio").resolve()+ except (OSError, ValueError):+ legacy = Path.home() / ".unsloth" / "studio"+ # install.sh and install.ps1 do not read UNSLOTH_HOME yet, so they leave the venv and the+ # launcher at the legacy root while setup puts the runtimes under the master root:+ # preferring <master>/studio unconditionally reported "Unsloth Studio not set up" for an+ # install that is right there. The master root wins only when it HAS an install.+ if candidate != legacy and not _looks_like_installer_managed_studio_home(candidate):+ if _looks_like_installer_managed_studio_home(legacy):+ return legacy, False+ return candidate, candidate != legacytry:prefix = Path(sys.prefix).resolve()if prefix.name == "unsloth_studio":@@ -90,25 +111,93 @@ def _resolve_studio_home() -> tuple[Path, bool]:STUDIO_HOME, _STUDIO_HOME_IS_CUSTOM = _resolve_studio_home()+MASTER_ROOT_NOTE = ".unsloth-master-root"+++def _recorded_master_root() -> Optional[Path]:+ """The master root setup recorded in this Studio tree, or None.++ Keep this aligned with storage_roots._recorded_master_root(); see+ test_unsloth_home_root_agreement.py. `UNSLOTH_HOME=/mnt/portable unsloth studio update` puts+ node, llama.cpp and whisper.cpp BESIDE studio/ and leaves nothing in a later environment. The+ backend recovers that from the note, so a `unsloth studio update` that did not would hand+ setup a plain Studio root, have it refresh the runtimes one level down at <master>/studio/,+ and leave the backend still launching the stale trees at <master>/.++ The recorded root must exist and THIS Studio directory must lie inside it, so a tree copied+ from one master root to another does not send the update, or a removal, into the original+ install. Containment, not an exact <root>/studio match: the flat layout names one directory+ for both, and UNSLOTH_HOME=/root with UNSLOTH_STUDIO_HOME=/root/custom/studio is a root that+ genuinely contains its Studio somewhere other than the default child. The backend and both+ uninstallers apply exactly this rule, and a stricter one here would have the CLI decline a+ note the backend accepts, which is the same split this function exists to close.+ """+ try:+ recorded = (STUDIO_HOME / "share" / MASTER_ROOT_NOTE).read_text(encoding = "utf-8").strip()+ except (OSError, ValueError, UnicodeDecodeError):+ return None+ if not recorded:+ return None+ try:+ master = Path(recorded).expanduser().resolve()+ here = STUDIO_HOME.resolve()+ if not (master.is_dir() and (here == master or master in here.parents)):+ return None+ # A legacy-rooted install has no master root, and both uninstallers already refuse what+ # that shape records. storage_roots._is_legacy_studio_tree declines it too, and+ # test_unsloth_home_root_agreement.py holds the two together: without this the CLI would+ # export UNSLOTH_HOME for a note the backend has declined. Keyed on the TREE, so a note+ # naming $HOME or any other ancestor goes with it.+ try:+ if here == (Path.home() / ".unsloth" / "studio").resolve():+ return None+ except (OSError, RuntimeError, ValueError):+ pass+ return master+ except (OSError, ValueError):+ return None+ return None+def _ensure_studio_env_exported() -> None:- """Re-export UNSLOTH_STUDIO_HOME / UNSLOTH_LLAMA_CPP_PATH for custom roots only, per- subcommand rather than at import, so unrelated importers see no env changes."""- if not _STUDIO_HOME_IS_CUSTOM:+ """Re-export UNSLOTH_STUDIO_HOME / UNSLOTH_LLAMA_CPP_PATH for custom roots, and for a master+ root the resolver above declined, per subcommand rather than at import, so unrelated+ importers see no env changes."""+ # storage_roots.studio_root() honours UNSLOTH_HOME with no install check, so the fallback+ # keeping this CLI on an installed legacy root must be told to the backend too: unexported,+ # `unsloth studio` runs the legacy venv while the backend inside it writes studio.db, auth+ # and the pid file under <master>/studio. Exporting the root does not make it custom, since+ # the value equals the legacy path both installers compare against.+ # The note, when this run has no UNSLOTH_HOME of its own. Exported rather than merely read,+ # because setup runs as a subprocess and would otherwise refresh the runtimes at+ # <master>/studio/ while the backend kept launching the ones at <master>/.+ if not (os.environ.get("UNSLOTH_HOME") or "").strip():+ _recorded = _recorded_master_root()+ if _recorded is not None:+ os.environ["UNSLOTH_HOME"] = str(_recorded)+ if not _STUDIO_HOME_IS_CUSTOM and not (os.environ.get("UNSLOTH_HOME") or "").strip():return# Truthy-check, not setdefault: a blank UNSLOTH_STUDIO_HOME= must not win.- if not os.environ.get("UNSLOTH_STUDIO_HOME"):+ if not (os.environ.get("UNSLOTH_STUDIO_HOME") or "").strip():os.environ["UNSLOTH_STUDIO_HOME"] = str(STUDIO_HOME)try:_legacy_studio = (Path.home() / ".unsloth" / "studio").resolve()_is_legacy = STUDIO_HOME.resolve() == _legacy_studioexcept (OSError, ValueError):_is_legacy = STUDIO_HOME == (Path.home() / ".unsloth" / "studio")- if _is_legacy:+ # 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"- if not os.environ.get("UNSLOTH_LLAMA_CPP_PATH"):+ if not (os.environ.get("UNSLOTH_LLAMA_CPP_PATH") or "").strip():os.environ["UNSLOTH_LLAMA_CPP_PATH"] = str(_llama_dir)diff --git a/unsloth_cli/tests/test_export_cache_env.py b/unsloth_cli/tests/test_export_cache_env.pynew file mode 100644index 00000000000..b41a6ae1bb5--- /dev/null+++ b/unsloth_cli/tests/test_export_cache_env.py@@ -0,0 +1,155 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""`unsloth export` / `list-checkpoints` must pin the cache env before importing the export+backend.++Neither calls ensure_studio_backend_path(), so before the seeding moved into+studio_backend_imports() they reached studio.backend.core.export with UNSLOTH_COMPILE_LOCATION+unset and unsloth_zoo resolved its relative default against the shell's cwd (#8865).+"""++import json+import os+import subprocess+import sys+import textwrap+from pathlib import Path++import pytest++REPO_ROOT = Path(__file__).resolve().parents[2]++# Runs in its own interpreter: the seeding is process-global (os.environ plus a one-shot flag),+# so an in-process assertion would depend on test ordering.+PROBE = textwrap.dedent(+ """+ import json, os, sys, types++ import typer+ from typer.testing import CliRunner++ command_name = sys.argv[1]+ recorded = {}++ # Stand in for the heavy backend (unsloth, torch) so the probe stays+ # import-light. The CLI's own import statement, and therefore everything that+ # has to happen before it, is untouched.+ class ExportBackend:+ def __init__(self):+ recorded["compile_location"] = os.environ.get("UNSLOTH_COMPILE_LOCATION")++ def load_checkpoint(self, **kwargs):+ return True, "loaded"++ def export_merged_model(self, **kwargs):+ return True, "exported", kwargs["save_directory"]++ def scan_checkpoints(self, **kwargs):+ return []++ # Each stub keeps the REAL directory on __path__ instead of []. The point is to skip+ # the heavy studio.backend.core.export import, not to make the whole studio tree+ # unimportable: unsloth_cli/__init__ eagerly imports commands.start, which pulls+ # studio.backend.utils.coding_agents, and an empty __path__ turned that into+ # ModuleNotFoundError. Submodules still load from disk; the package __init__ files+ # are the thing that never runs, which is what kept this probe light to begin with.+ repo_root = sys.argv[2]+ for name, relative in (+ ("studio", "studio"),+ ("studio.backend", "studio/backend"),+ ("studio.backend.core", "studio/backend/core"),+ ):+ module = types.ModuleType(name)+ module.__path__ = [os.path.join(repo_root, *relative.split("/"))]+ sys.modules[name] = module+ export_module = types.ModuleType("studio.backend.core.export")+ export_module.ExportBackend = ExportBackend+ sys.modules["studio.backend.core.export"] = export_module++ from unsloth_cli.commands import export as export_command++ app = typer.Typer()+ if command_name == "export":+ app.command()(export_command.export)+ args = ["checkpoint", "exported"]+ else:+ app.command()(export_command.list_checkpoints)+ args = []+ result = CliRunner().invoke(app, args)+ recorded["exit_code"] = result.exit_code+ print("PROBE " + json.dumps(recorded))+ """+)++[email protected]("command_name", ["export", "list-checkpoints"])+def test_export_commands_seed_compile_location(tmp_path, command_name):+ unsloth_home = tmp_path / "unsloth"+ workdir = tmp_path / "cwd"+ workdir.mkdir()++ env = dict(os.environ)+ env.pop("UNSLOTH_COMPILE_LOCATION", None)+ # Both outrank UNSLOTH_HOME in the resolver, and conftest.py sets a session-scoped+ # UNSLOTH_STUDIO_HOME, so an inherited one would send the probe somewhere unnamed.+ for key in ("UNSLOTH_STUDIO_HOME", "STUDIO_HOME", "UNSLOTH_PORTABLE"):+ env.pop(key, None)+ env.update(+ HOME = str(tmp_path / "home"),+ UNSLOTH_HOME = str(unsloth_home),+ PYTHONPATH = str(REPO_ROOT),+ )+ completed = subprocess.run(+ [sys.executable, "-c", PROBE, command_name, str(REPO_ROOT)],+ cwd = str(workdir),+ env = env,+ capture_output = True,+ text = True,+ timeout = 300,+ )+ assert completed.returncode == 0, completed.stderr+ line = next(l for l in completed.stdout.splitlines() if l.startswith("PROBE "))+ recorded = json.loads(line[len("PROBE ") :])++ assert recorded["exit_code"] == 0, recorded+ location = recorded["compile_location"]+ assert location, "UNSLOTH_COMPILE_LOCATION was unset when the export backend was imported"+ # Absolute and inside the install root, not resolved against the CWD.+ assert Path(location).is_absolute()+ assert Path(location) == unsloth_home / "studio" / "compiled_cache"+ assert not (workdir / "unsloth_compiled_cache").exists()+++def test_node_discovery_does_not_build_the_cache_tree(tmp_path):+ """`unsloth start` asks whether a managed Node exists; that is a read, not an install.++ ensure_studio_backend_path() seeds the cache environment, and setup_cache_env() CREATES+ every directory it pins, so routing Node discovery through it turned the lookup into 18+ mkdirs under a home that may have nothing to do with the command -- including a launch+ aimed at a remote server. The merge base created nothing here.+ """+ home = tmp_path / "home"+ (home / ".unsloth" / "studio").mkdir(parents = True)+ probe = (+ "import json, os, sys\n"+ f"sys.path.insert(0, {str(REPO_ROOT)!r})\n"+ "from pathlib import Path\n"+ "home = Path(os.environ['HOME'])\n"+ "before = {str(p) for p in home.rglob('*') if p.is_dir()}\n"+ "from unsloth_cli.commands import start\n"+ "start._managed_node_tools()\n"+ "after = {str(p) for p in home.rglob('*') if p.is_dir()}\n"+ "print('PROBE ' + json.dumps(sorted(after - before)))\n"+ )+ completed = subprocess.run(+ [sys.executable, "-c", probe],+ cwd = str(tmp_path),+ env = {"HOME": str(home), "PATH": os.environ.get("PATH", "/usr/bin:/bin")},+ capture_output = True,+ text = True,+ timeout = 300,+ )+ assert completed.returncode == 0, completed.stderr+ line = next(l for l in completed.stdout.splitlines() if l.startswith("PROBE "))+ assert json.loads(line[len("PROBE ") :]) == []