Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Unsloth Studio Installer: ask Python for a path identity before giving up on an exact one (#11104)

Daniel Han72acc861589c
diff --git a/.github/workflows/cross-platform-parity-ci.yml b/.github/workflows/cross-platform-parity-ci.yml
index 35502c4a713..dd130709148 100644
--- a/.github/workflows/cross-platform-parity-ci.yml
+++ b/.github/workflows/cross-platform-parity-ci.yml
@@ -106,6 +106,7 @@ on:
- 'tests/studio/test_nvidia_library_inventory.ps1'
- 'tests/studio/test_nvidia_smi_discovery.ps1'
- 'tests/studio/test_install_lock_excludes_aliases.ps1'
+ - 'tests/studio/test_early_python_path_resolver.ps1'
- 'tests/studio/test_application_control_cli_fallback.ps1'
# test_application_control_cli_fallback.ps1 pins install.ps1's trampoline against
# process.rs's, so a change to either spelling has to run here.
@@ -218,6 +219,7 @@ on:
- 'tests/studio/test_nvidia_library_inventory.ps1'
- 'tests/studio/test_nvidia_smi_discovery.ps1'
- 'tests/studio/test_install_lock_excludes_aliases.ps1'
+ - 'tests/studio/test_early_python_path_resolver.ps1'
- 'tests/studio/test_application_control_cli_fallback.ps1'
# test_application_control_cli_fallback.ps1 pins install.ps1's trampoline against
# process.rs's, so a change to either spelling has to run here.
@@ -390,6 +392,14 @@ jobs:
- name: Install lock alias-exclusion tests
shell: pwsh
run: pwsh -NoProfile -File tests/studio/test_install_lock_excludes_aliases.ps1
+ # Both legs: the lexical fallback differs between Windows PowerShell 5.1 and pwsh 7.
+ - name: Early Python path resolver tests
+ shell: pwsh
+ run: pwsh -NoProfile -File tests/studio/test_early_python_path_resolver.ps1
+ - name: Early Python path resolver tests (Windows PowerShell 5.1)
+ if: runner.os == 'Windows'
+ shell: powershell
+ run: powershell -NoProfile -File tests\studio\test_early_python_path_resolver.ps1
- name: Install lock alias-exclusion tests (Windows PowerShell 5.1)
if: runner.os == 'Windows'
shell: powershell
diff --git a/install.ps1 b/install.ps1
index bb68eebb042..38ded796bd2 100644
--- a/install.ps1
+++ b/install.ps1
@@ -2475,8 +2475,9 @@ exit 1
# the same security software that blocks a type can be acting on the rest of
# the run. Only the narrower claim is true, that the installer can continue.
Write-StudioLine "[WARN] Could not load the native path resolver ($Reason)." -ForegroundColor Yellow
- Write-StudioLine " Continuing with the PowerShell resolver, which cannot recover a path's" -ForegroundColor Yellow
- Write-StudioLine " stored casing or expand an 8.3 name, so paths are compared as written." -ForegroundColor Yellow
+ Write-StudioLine " Continuing with the Python resolver when an interpreter can answer, else the" -ForegroundColor Yellow
+ Write-StudioLine " PowerShell one, which cannot recover a path's stored casing or expand an 8.3" -ForegroundColor Yellow
+ Write-StudioLine " name, so it compares paths as written." -ForegroundColor Yellow
}
function Initialize-StudioFinalPathNativeType {
@@ -2753,6 +2754,154 @@ exit 1
return $current
}
+ # Runs before the install lock: find an existing Python only. Path.resolve matches what
+ # unsloth_cli/_studio_runtime_gate.py hashes, so both sides name the same lock.
+ $script:StudioEarlyPythonProbed = $false
+ $script:StudioEarlyPython = $null
+ $script:StudioEarlyPythonProbedWithoutVenv = $false
+
+ function Get-StudioEarlyPython {
+ # This optional pre-lock probe has no ACL/ownership validation for candidates.
+ # Elevated or uninspectable Windows tokens retain the old resolver ladder.
+ try {
+ $elevation = Get-ElevationState
+ if ($elevation -eq "true" -or
+ ($elevation -ne "false" -and
+ [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT)) { return $null }
+ } catch { return $null }
+ # A miss taken before $VenvDir existed (--tauri) is re-probed once it does.
+ $venvDirValue = $null
+ try { $venvDirValue = Get-Variable -Name VenvDir -ValueOnly -ErrorAction SilentlyContinue } catch {}
+ $venvKnown = -not [string]::IsNullOrWhiteSpace($venvDirValue)
+ if ($script:StudioEarlyPythonProbed) {
+ if (-not ($script:StudioEarlyPythonProbedWithoutVenv -and $venvKnown -and
+ [string]::IsNullOrWhiteSpace($script:StudioEarlyPython))) {
+ return $script:StudioEarlyPython
+ }
+ }
+ $script:StudioEarlyPythonProbed = $true
+ $script:StudioEarlyPythonProbedWithoutVenv = (-not $venvKnown)
+ if ("$($env:UNSLOTH_EARLY_PYTHON_PROBE)".Trim() -eq "0") { return $null }
+ $candidates = @()
+ if ($venvKnown) {
+ # A custom UNSLOTH_STUDIO_HOME can be a shared root, and the guard refusing a venv that is
+ # not Unsloth's runs later: only run one here that the guard would accept.
+ $venvOurs = $false
+ try {
+ $mode = Get-Variable -Name StudioRedirectMode -ValueOnly -ErrorAction Stop
+ $studioHomeValue = Get-Variable -Name StudioHome -ValueOnly -ErrorAction Stop
+ # The guard's own predicates; one not yet defined this early throws, which declines.
+ $venvOurs = ($mode -ne 'env') -or
+ (Test-Path -LiteralPath (Join-Path $venvDirValue ".unsloth-studio-owned") -PathType Leaf) -or
+ (Test-Path -LiteralPath (Join-Path $studioHomeValue "share\studio.conf") -PathType Leaf) -or
+ (Test-Path -LiteralPath (Join-Path $studioHomeValue "bin\unsloth.exe") -PathType Leaf) -or
+ (Test-StudioPlainFile -Path (Join-Path $studioHomeValue ".unsloth-studio-owned")) -or
+ (Test-UnslothCmdShimFile (Join-Path $studioHomeValue "bin\unsloth.cmd"))
+ } catch { $venvOurs = $false }
+ if ($venvOurs) {
+ $candidates += (Join-Path $venvDirValue "Scripts\python.exe")
+ $candidates += (Join-Path $venvDirValue "bin/python3")
+ }
+ }
+ foreach ($name in @("python3", "python")) {
+ try {
+ foreach ($cmd in @(Get-Command $name -All -CommandType Application -ErrorAction SilentlyContinue)) {
+ if ($cmd -and $cmd.Source) { $candidates += $cmd.Source }
+ }
+ } catch {}
+ }
+ foreach ($candidate in $candidates) {
+ if ([string]::IsNullOrWhiteSpace($candidate)) { continue }
+ # Test-Path throws on an unreadable dir under Stop: skip this candidate only.
+ $isFile = $false
+ try { $isFile = Test-Path -LiteralPath $candidate -PathType Leaf } catch {}
+ if (-not $isFile) { continue }
+ # Probe the interpreter's own directory: $PSScriptRoot is empty when the script runs from memory.
+ $probeDir = $null
+ try { $probeDir = [System.IO.Path]::GetDirectoryName($candidate) } catch {}
+ if ([string]::IsNullOrWhiteSpace($probeDir)) { continue }
+ $probe = Invoke-StudioEarlyPython -Exe $candidate -Path $probeDir
+ if (-not [string]::IsNullOrWhiteSpace($probe)) {
+ $script:StudioEarlyPython = $candidate
+ return $candidate
+ }
+ }
+ return $null
+ }
+
+ function Invoke-StudioEarlyPython {
+ param(
+ [Parameter(Mandatory = $true)][string]$Exe,
+ [Parameter(Mandatory = $true)][string]$Path,
+ [int]$TimeoutMs = 10000
+ )
+ # The gate's _resolved_windows_path, strict so loops/dangling links raise. <3.8 does not follow links.
+ $script = "import pathlib,sys" + [char]10 +
+ "sys.exit(2) if sys.version_info < (3,8) else None" + [char]10 +
+ "sys.stdout.buffer.write(str(pathlib.Path(sys.argv[1]).resolve(strict=True)).encode('utf-8'))"
+ $proc = $null
+ $clock = [System.Diagnostics.Stopwatch]::StartNew()
+ try {
+ $psi = New-Object System.Diagnostics.ProcessStartInfo
+ $psi.FileName = $Exe
+ # -S as well as -I: -I still imports site, so a sitecustomize could print or hang.
+ $argv = @("-I", "-S", "-c", $script, $Path)
+ if ($null -ne $psi.PSObject.Properties["ArgumentList"]) {
+ foreach ($a in $argv) { $null = $psi.ArgumentList.Add($a) }
+ } else {
+ # Quote for CommandLineToArgvW, doubling trailing backslashes so "C:\dir\" keeps its quote.
+ $psi.Arguments = (@($argv | ForEach-Object {
+ '"' + ($_ -replace '(\\+)$', '$1$1') + '"'
+ }) -join ' ')
+ }
+ $psi.UseShellExecute = $false
+ $psi.RedirectStandardOutput = $true
+ $psi.RedirectStandardError = $true
+ # Otherwise 5.1 decodes with the console codepage and corrupts non-ASCII paths.
+ $psi.StandardOutputEncoding = [System.Text.Encoding]::UTF8
+ $psi.CreateNoWindow = $true
+ $proc = [System.Diagnostics.Process]::Start($psi)
+ $stdout = $proc.StandardOutput.ReadToEndAsync()
+ $null = $proc.StandardError.ReadToEndAsync()
+ if (-not $proc.WaitForExit($TimeoutMs)) {
+ try { $proc.Kill() } catch {}
+ return $null
+ }
+ if ($proc.ExitCode -ne 0) { return $null }
+ # A leftover child can hold stdout open, so the deadline bounds the read too.
+ $left = [Math]::Max(0, $TimeoutMs - [int]$clock.ElapsedMilliseconds)
+ if (-not $stdout.Wait($left)) { return $null }
+ # Verbatim: Trim() would drop a trailing U+00A0, which NTFS names keep.
+ $answer = "$($stdout.Result)"
+ if ([string]::IsNullOrWhiteSpace($answer)) { return $null }
+ if (-not [System.IO.Path]::IsPathRooted($answer)) { return $null }
+ if (-not (Test-Path -LiteralPath $answer)) { return $null }
+ return $answer
+ } catch {
+ return $null
+ } finally {
+ if ($proc) { try { $proc.Dispose() } catch {} }
+ }
+ }
+
+ # One child per distinct path (misses cached too).
+ $script:StudioPythonFinalPathCache = $null
+
+ function Get-StudioPythonFinalPath {
+ param([Parameter(Mandatory = $true)][string]$Path)
+ if ($null -eq $script:StudioPythonFinalPathCache) { $script:StudioPythonFinalPathCache = @{} }
+ if ($script:StudioPythonFinalPathCache.ContainsKey($Path)) {
+ return $script:StudioPythonFinalPathCache[$Path]
+ }
+ $exe = $null
+ try { $exe = Get-StudioEarlyPython } catch {}
+ # Not cached: the re-probe once $VenvDir is known may still find an interpreter.
+ if (-not $exe) { return $null }
+ $answer = Invoke-StudioEarlyPython -Exe $exe -Path $Path
+ $script:StudioPythonFinalPathCache[$Path] = $answer
+ return $answer
+ }
+
# Exact = $true means the native resolver answered, so the string is what it
# always was. Callers keying a lock on it use that to judge an inequality.
function Resolve-StudioFinalPathInfo {
@@ -2770,6 +2919,13 @@ exit 1
if ([string]::IsNullOrEmpty($leaf) -or [string]::IsNullOrEmpty($parent)) {
return [pscustomobject]@{ Path = $fullPath; Exact = $false }
}
+ # A dangling link/loop reads as missing; a reparse point in the stripped tail must stay inexact.
+ $strippedAttributes = $null
+ try { $strippedAttributes = [System.IO.File]::GetAttributes($existingPath) } catch { }
+ if ($null -ne $strippedAttributes -and
+ ($strippedAttributes -band [System.IO.FileAttributes]::ReparsePoint)) {
+ return [pscustomobject]@{ Path = $fullPath; Exact = $false }
+ }
$missingSegments = @($leaf) + $missingSegments
$existingPath = $parent
}
@@ -2791,10 +2947,14 @@ exit 1
$resolved = $null
if (-not $script:StudioNativeResolveWarned) {
$script:StudioNativeResolveWarned = $true
- Write-StudioLine "[WARN] Could not resolve a path with the native helper; continuing with the PowerShell resolver." -ForegroundColor Yellow
+ Write-StudioLine "[WARN] Could not resolve a path with the native helper; continuing with the fallback resolvers." -ForegroundColor Yellow
}
}
}
+ if ([string]::IsNullOrEmpty($resolved)) {
+ $resolved = Get-StudioPythonFinalPath -Path $existingPath
+ if (-not [string]::IsNullOrWhiteSpace($resolved)) { $exact = $true }
+ }
if ([string]::IsNullOrEmpty($resolved)) {
$resolved = Get-StudioLexicalPath -Path $existingPath
$exact = $false
diff --git a/tests/python/test_windows_installer_concurrency_guard.py b/tests/python/test_windows_installer_concurrency_guard.py
index 284aa11a505..d43580ce3ef 100644
--- a/tests/python/test_windows_installer_concurrency_guard.py
+++ b/tests/python/test_windows_installer_concurrency_guard.py
@@ -96,6 +96,12 @@ _FINAL_PATH_CHAIN = (
"Get-StudioNativeFinalPath",
"Resolve-StudioLinkTarget",
"Get-StudioSubstTarget",
+ "Get-ElevationState",
+ "Get-StudioEarlyPython",
+ "Test-StudioPlainFile",
+ "Test-UnslothCmdShimFile",
+ "Invoke-StudioEarlyPython",
+ "Get-StudioPythonFinalPath",
"Get-StudioLexicalPath",
"Resolve-StudioFinalPathInfo",
"Get-StudioFinalPath",
@@ -131,6 +137,12 @@ def _mutex_helpers(source: str) -> str:
"Get-StudioNativeFinalPath",
"Resolve-StudioLinkTarget",
"Get-StudioSubstTarget",
+ "Get-ElevationState",
+ "Get-StudioEarlyPython",
+ "Test-StudioPlainFile",
+ "Test-UnslothCmdShimFile",
+ "Invoke-StudioEarlyPython",
+ "Get-StudioPythonFinalPath",
"Get-StudioLexicalPath",
"Resolve-StudioFinalPathInfo",
"Get-StudioFinalPath",
@@ -168,6 +180,12 @@ def _process_helpers(source: str) -> str:
"Get-StudioNativeFinalPath",
"Resolve-StudioLinkTarget",
"Get-StudioSubstTarget",
+ "Get-ElevationState",
+ "Get-StudioEarlyPython",
+ "Test-StudioPlainFile",
+ "Test-UnslothCmdShimFile",
+ "Invoke-StudioEarlyPython",
+ "Get-StudioPythonFinalPath",
"Get-StudioLexicalPath",
"Resolve-StudioFinalPathInfo",
"Get-StudioFinalPath",
@@ -1118,7 +1136,9 @@ def test_the_extracted_helpers_can_call_everything_they_call(helpers):
provided = set(re.findall(r"^ function ([\w-]+) \{", extracted, flags = re.M))
assert provided, "the helper extraction produced nothing"
- called = set(re.findall(r"(?<![\w-])([A-Z][\w]*-[\w-]+)", extracted))
+ # Whole-line comments dropped: a function named in prose is not a call.
+ code = "\n".join(line for line in extracted.splitlines() if not line.lstrip().startswith("#"))
+ called = set(re.findall(r"(?<![\w-])([A-Z][\w]*-[\w-]+)", code))
missing = sorted((called & installer_functions) - provided)
assert not missing, (
f"{helpers.__name__} extracts functions that call {missing}, which the "
diff --git a/tests/python/test_windows_installer_native_type_fallback.py b/tests/python/test_windows_installer_native_type_fallback.py
index 1d9bfd49a73..a99311f391a 100644
--- a/tests/python/test_windows_installer_native_type_fallback.py
+++ b/tests/python/test_windows_installer_native_type_fallback.py
@@ -74,7 +74,9 @@ SABOTAGE = (
# What a host that cannot emit looks like. Constrained Language Mode and App Control's
# Dynamic Code Security both come through Test-StudioCanDefineNativeTypes, so overriding
# that gate is the whole of "no native side".
-NO_NATIVE = """function Test-StudioCanDefineNativeTypes { return $false }"""
+# The Python rung is off too: it would answer exactly on any host with an interpreter.
+NO_NATIVE = """$env:UNSLOTH_EARLY_PYTHON_PROBE = "0"
+function Test-StudioCanDefineNativeTypes { return $false }"""
def _extract(pattern: str, source: str) -> str:
@@ -106,6 +108,12 @@ LOCK_CHAIN = (
"Get-StudioNativeFinalPath",
"Resolve-StudioLinkTarget",
"Get-StudioSubstTarget",
+ "Get-ElevationState",
+ "Get-StudioEarlyPython",
+ "Test-StudioPlainFile",
+ "Test-UnslothCmdShimFile",
+ "Invoke-StudioEarlyPython",
+ "Get-StudioPythonFinalPath",
"Get-StudioLexicalPath",
"Resolve-StudioFinalPathInfo",
"Get-StudioFinalPath",
@@ -1128,6 +1136,11 @@ def test_a_native_resolver_that_throws_says_so_once(tmp_path: Path):
result = _run_powershell(
_script(
f"""
+# The subject here is the warning, not the answer, so the Python rung is switched off: it
+# would resolve exactly on any host with an interpreter and the assertion below is about the
+# degraded identity. That the rung rescues a throwing native resolver is covered in
+# tests/studio/test_early_python_path_resolver.ps1.
+$env:UNSLOTH_EARLY_PYTHON_PROBE = "0"
# The helper is "available" and throws anyway, which is what a rename between
# the Test-Path walk and CreateFileW looks like. The stub has to be the type the
# resolver actually calls, and it has to count its calls: a stub the resolver
diff --git a/tests/studio/test_early_python_path_resolver.ps1 b/tests/studio/test_early_python_path_resolver.ps1
new file mode 100644
index 00000000000..d8bd302f287
--- /dev/null
+++ b/tests/studio/test_early_python_path_resolver.ps1
@@ -0,0 +1,373 @@
+#!/usr/bin/env pwsh
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+# The Python rung of Resolve-StudioFinalPathInfo, used when the native resolver answers nothing.
+# Run: pwsh -NoProfile -File tests/studio/test_early_python_path_resolver.ps1
+
+$ErrorActionPreference = "Stop"
+$root = (Resolve-Path ([System.IO.Path]::Combine($PSScriptRoot, "..", ".."))).Path
+$installPs1 = Join-Path $root "install.ps1"
+
+$failures = 0
+function Check($name, $cond) {
+ if ($cond) { Write-Host " PASS $name" }
+ else { Write-Host " FAIL $name" -ForegroundColor Red; $script:failures++ }
+}
+
+$tokens = $null; $errors = $null
+$ast = [System.Management.Automation.Language.Parser]::ParseFile($installPs1, [ref]$tokens, [ref]$errors)
+if ($errors) { $errors | ForEach-Object { $_.ToString() }; throw "install.ps1 has parse errors" }
+foreach ($name in @(
+ "Get-ElevationState", "Get-StudioEarlyPython", "Invoke-StudioEarlyPython", "Get-StudioPythonFinalPath",
+ "Resolve-StudioLinkTarget", "Get-StudioSubstTarget", "Get-StudioLexicalPath",
+ "Resolve-StudioFinalPathInfo", "Test-StudioPlainFile", "Test-UnslothCmdShimFile"
+)) {
+ $fn = $ast.FindAll({ param($n)
+ $n -is [System.Management.Automation.Language.FunctionDefinitionAst] -and $n.Name -eq $name
+ }, $true)
+ if ($fn.Count -lt 1) { throw "expected $name in install.ps1, found none" }
+ Invoke-Expression $fn[0].Extent.Text
+}
+
+# A failed native type is warned about before this rung runs, so the warning cannot promise
+# paths compared as written: the Python rung may still answer exactly.
+$degraded = @($ast.FindAll({ param($n)
+ $n -is [System.Management.Automation.Language.FunctionDefinitionAst] -and $n.Name -eq "Write-StudioFinalPathDegraded"
+}, $true))[0].Extent.Text
+Check "the native-failure warning names the Python rung it falls back to" ($degraded -match 'Python resolver')
+
+# The native rung, forced off.
+function Initialize-StudioFinalPathNativeType { return $false }
+function Get-StudioNativeFinalPath { param([string]$Path) return $null }
+function Write-StudioLine { param([string]$Line, [string]$ForegroundColor = "") }
+
+# Candidate execution happens before the install lock and destination ownership guard.
+$savedElevation = ${function:Get-ElevationState}
+function Get-ElevationState { return "true" }
+$script:StudioEarlyPythonProbed = $false
+$script:StudioEarlyPython = $null
+$script:StudioEarlyPythonProbedWithoutVenv = $false
+try {
+ Check "an elevated run declines the unvalidated early interpreter" ($null -eq (Get-StudioEarlyPython))
+} finally {
+ ${function:Get-ElevationState} = $savedElevation
+ $script:StudioEarlyPythonProbed = $false
+ $script:StudioEarlyPython = $null
+ $script:StudioEarlyPythonProbedWithoutVenv = $false
+}
+
+# The remaining cases model a normal user even on an elevated Windows CI runner.
+function Get-ElevationState { return "false" }
+
+$tmp = Join-Path ([System.IO.Path]::GetTempPath()) ("earlypy-" + [guid]::NewGuid().ToString("N"))
+New-Item -ItemType Directory -Force -Path $tmp | Out-Null
+try {
+ $script:StudioEarlyPythonProbed = $false
+ $script:StudioEarlyPython = $null
+ $exe = Get-StudioEarlyPython
+ if (-not $exe) {
+ Write-Host " SKIP no Python on this host, which is the fallback case and not a failure" -ForegroundColor Yellow
+ exit 0
+ }
+ Write-Host " interpreter: $exe"
+
+ $real = Join-Path $tmp "real"
+ New-Item -ItemType Directory -Force -Path $real | Out-Null
+ $alias = Join-Path $tmp "alias"
+ $madeAlias = $false
+ try {
+ if ($IsWindows -or $env:OS -eq "Windows_NT") {
+ New-Item -ItemType Junction -Path $alias -Target $real -ErrorAction Stop | Out-Null
+ } else {
+ New-Item -ItemType SymbolicLink -Path $alias -Target $real -ErrorAction Stop | Out-Null
+ }
+ $madeAlias = $true
+ } catch {
+ Write-Host " SKIP could not create a directory alias: $($_.Exception.Message)" -ForegroundColor Yellow
+ }
+
+ if ($madeAlias) {
+ # Control: the lexical rung may fold a symlink on pwsh 7, but it is never exact.
+ $savedFinder = ${function:Get-StudioEarlyPython}
+ function Get-StudioEarlyPython { return $null }
+ $inexact = Resolve-StudioFinalPathInfo -Path $alias
+ Check "without the rung the alias identity is inexact (bites)" ($inexact.Exact -eq $false)
+ ${function:Get-StudioEarlyPython} = $savedFinder
+
+ $viaAlias = Get-StudioPythonFinalPath -Path $alias
+ $viaReal = Get-StudioPythonFinalPath -Path $real
+ Check "Python folds the alias onto its target" (
+ -not [string]::IsNullOrWhiteSpace($viaAlias) -and $viaAlias -eq $viaReal)
+
+ $infoAlias = Resolve-StudioFinalPathInfo -Path $alias
+ $infoReal = Resolve-StudioFinalPathInfo -Path $real
+ Check "the resolver reports the alias as exact" ($infoAlias.Exact -eq $true)
+ Check "the resolver gives one identity for both spellings" ($infoAlias.Path -eq $infoReal.Path)
+ }
+
+ # No interpreter: lexical and inexact, as before. Restored afterwards so later checks use the rung.
+ $savedFinder2 = ${function:Get-StudioEarlyPython}
+ function Get-StudioEarlyPython { return $null }
+ $script:StudioEarlyPythonProbed = $false
+ $script:StudioPythonFinalPathCache = $null
+ $noPy = Resolve-StudioFinalPathInfo -Path $real
+ Check "with no interpreter the identity is inexact, as before" ($noPy.Exact -eq $false)
+ Check "with no interpreter a usable path still comes back" (
+ -not [string]::IsNullOrWhiteSpace($noPy.Path))
+ ${function:Get-StudioEarlyPython} = $savedFinder2
+ $script:StudioEarlyPythonProbed = $false
+ $script:StudioEarlyPython = $null
+ Check "the interpreter is back after the no-interpreter case" ($null -ne (Get-StudioEarlyPython))
+
+ # The answer is hashed into a lock name, so non-ASCII must survive 5.1's console codepage.
+ $unicodeName = "studio-ünïcôde-日本語-ß"
+ $unicodeDir = Join-Path $tmp $unicodeName
+ New-Item -ItemType Directory -Force -Path $unicodeDir | Out-Null
+ $unicodeAnswer = Get-StudioPythonFinalPath -Path $unicodeDir
+ Check "a non-ASCII path survives the child process" (
+ -not [string]::IsNullOrWhiteSpace($unicodeAnswer) -and
+ $unicodeAnswer.EndsWith($unicodeName))
+
+ # Trim() would drop the U+00A0 and name the sibling instead.
+ $nbspName = "studio-nbsp" + [char]0x00A0
+ New-Item -ItemType Directory -Force -Path (Join-Path $tmp "studio-nbsp") | Out-Null
+ New-Item -ItemType Directory -Force -Path (Join-Path $tmp $nbspName) | Out-Null
+ # .NET Framework strips it on the way in, so 5.1 cannot create or name such a directory at all.
+ if (@(Get-ChildItem -LiteralPath $tmp -Name) -ccontains $nbspName) {
+ $nbspAnswer = Get-StudioPythonFinalPath -Path (Join-Path $tmp $nbspName)
+ Check "a trailing non-breaking space is kept" ("$nbspAnswer".EndsWith($nbspName))
+ } else {
+ Write-Host " SKIP this host strips a trailing U+00A0 from paths" -ForegroundColor Yellow
+ }
+
+ $gateScript = "import pathlib,sys" + [char]10 +
+ "sys.stdout.buffer.write(str(pathlib.Path(sys.argv[1]).resolve(strict=False)).encode('utf-8'))"
+ $gateAnswer = & $exe -I -c $gateScript $unicodeDir
+ Check "the answer matches the runtime gate's own resolve()" ($unicodeAnswer -eq "$gateAnswer".Trim())
+
+ $loopA = Join-Path $tmp "loop-a"
+ $loopOk = $false
+ try {
+ New-Item -ItemType SymbolicLink -Path $loopA -Target (Join-Path $tmp "loop-b") -ErrorAction Stop | Out-Null
+ New-Item -ItemType SymbolicLink -Path (Join-Path $tmp "loop-b") -Target $loopA -ErrorAction Stop | Out-Null
+ $loopOk = $true
+ } catch {}
+ if ($loopOk) {
+ $loopAnswer = Get-StudioPythonFinalPath -Path $loopA
+ Check "a link loop is not promoted to an exact identity" ([string]::IsNullOrWhiteSpace($loopAnswer))
+ # Test-Path reports the link itself, so the walk stops AT the link.
+ $loopChild = Resolve-StudioFinalPathInfo -Path (Join-Path $loopA "studio")
+ Check "a missing path under a link loop is not exact" ($loopChild.Exact -eq $false)
+ }
+
+ $dangling = Join-Path $tmp "dangling"
+ $danglingOk = $false
+ try {
+ New-Item -ItemType SymbolicLink -Path $dangling -Target (Join-Path $tmp "gone") -ErrorAction Stop | Out-Null
+ $danglingOk = $true
+ } catch {
+ # 5.1 refuses a link to a missing target: link first, then remove the target.
+ try {
+ $gone = Join-Path $tmp "gone"
+ New-Item -ItemType Directory -Force -Path $gone | Out-Null
+ New-Item -ItemType SymbolicLink -Path $dangling -Target $gone -ErrorAction Stop | Out-Null
+ Remove-Item -LiteralPath $gone -Recurse -Force
+ $danglingOk = $true
+ } catch {}
+ }
+ if ($danglingOk) {
+ foreach ($suffix in @("", "studio", "a\b")) {
+ $probePath = if ($suffix) { Join-Path $dangling $suffix } else { $dangling }
+ $info = Resolve-StudioFinalPathInfo -Path $probePath
+ Check "a dangling link is not exact (suffix '$suffix')" ($info.Exact -eq $false)
+ }
+ # Where Test-Path follows the link, the stripped entry's reparse bit alone must keep it inexact.
+ function Test-Path {
+ param([string]$LiteralPath)
+ if ($LiteralPath.StartsWith($dangling)) { return $false }
+ return (Microsoft.PowerShell.Management\Test-Path -LiteralPath $LiteralPath)
+ }
+ try {
+ foreach ($suffix in @("", "studio", "a\b")) {
+ $probePath = if ($suffix) { Join-Path $dangling $suffix } else { $dangling }
+ $info = Resolve-StudioFinalPathInfo -Path $probePath
+ Check "a dangling link Test-Path reports missing is not exact (suffix '$suffix')" ($info.Exact -eq $false)
+ }
+ } finally {
+ Remove-Item Function:Test-Path
+ }
+ }
+
+ # 5.1 has no ArgumentList, so arguments go through one quoted string.
+ $spacedDir = Join-Path $tmp "a dir with spaces"
+ New-Item -ItemType Directory -Force -Path $spacedDir | Out-Null
+ $spacedAnswer = Get-StudioPythonFinalPath -Path $spacedDir
+ Check "a path containing spaces resolves" (
+ -not [string]::IsNullOrWhiteSpace($spacedAnswer) -and $spacedAnswer.EndsWith("spaces"))
+
+ $src = Get-Content -Raw -LiteralPath $installPs1
+ Check "argument construction does not assume ArgumentList exists" (
+ $src -match 'PSObject\.Properties\["ArgumentList"\]')
+ Check "the probe refuses an interpreter older than 3.8" (
+ $src -match 'sys\.version_info\s*<\s*\(3,\s*8\)')
+
+ $refuser = Join-Path $tmp $(if ($IsWindows -or $env:OS -eq "Windows_NT") { "refuse.cmd" } else { "refuse.sh" })
+ if ($IsWindows -or $env:OS -eq "Windows_NT") {
+ "@echo off`r`nexit /b 2`r`n" | Set-Content -LiteralPath $refuser -Encoding ASCII
+ } else {
+ "#!/bin/sh`nexit 2`n" | Set-Content -LiteralPath $refuser
+ & chmod +x $refuser
+ }
+ Check "an interpreter that exits non-zero is rejected" (
+ $null -eq (Invoke-StudioEarlyPython -Exe $refuser -Path $real))
+
+ $slow = Join-Path $tmp $(if ($IsWindows -or $env:OS -eq "Windows_NT") { "slow.cmd" } else { "slow.sh" })
+ if ($IsWindows -or $env:OS -eq "Windows_NT") {
+ "@echo off`r`nping -n 30 127.0.0.1 >nul`r`n" | Set-Content -LiteralPath $slow -Encoding ASCII
+ } else {
+ "#!/bin/sh`nsleep 30`n" | Set-Content -LiteralPath $slow
+ & chmod +x $slow
+ }
+ $started = [DateTime]::UtcNow
+ $hung = Invoke-StudioEarlyPython -Exe $slow -Path $real -TimeoutMs 2000
+ $elapsed = ([DateTime]::UtcNow - $started).TotalSeconds
+ Check "a hung interpreter returns null" ($null -eq $hung)
+ Check "a hung interpreter is killed at the deadline, not waited out" ($elapsed -lt 15)
+
+ # The interpreter exits at once but leaves a child holding stdout: the read is bounded too.
+ $holder = Join-Path $tmp $(if ($IsWindows -or $env:OS -eq "Windows_NT") { "holder.cmd" } else { "holder.sh" })
+ if ($IsWindows -or $env:OS -eq "Windows_NT") {
+ "@echo off`r`nstart /b `"`" ping -n 20 127.0.0.1`r`nexit /b 0`r`n" | Set-Content -LiteralPath $holder -Encoding ASCII
+ } else {
+ "#!/bin/sh`nsleep 20 &`nprintf '%s' `"`$5`"`nexit 0`n" | Set-Content -LiteralPath $holder
+ & chmod +x $holder
+ }
+ $started = [DateTime]::UtcNow
+ $held = Invoke-StudioEarlyPython -Exe $holder -Path $real -TimeoutMs 2000
+ $elapsed = ([DateTime]::UtcNow - $started).TotalSeconds
+ Check "an answer still held open past the deadline is declined" ($null -eq $held)
+ Check "and the wait for it ends at the deadline" ($elapsed -lt 10)
+
+ # This runs before the install lock, so finding an interpreter must write nothing.
+ $before = @(Get-ChildItem -LiteralPath $tmp -Recurse -Force).Count
+ $script:StudioEarlyPythonProbed = $false
+ $script:StudioEarlyPython = $null
+ Remove-Item Function:\Get-StudioEarlyPython -ErrorAction SilentlyContinue
+ foreach ($name in @("Get-StudioEarlyPython")) {
+ $fn = $ast.FindAll({ param($n)
+ $n -is [System.Management.Automation.Language.FunctionDefinitionAst] -and $n.Name -eq $name
+ }, $true)
+ Invoke-Expression $fn[0].Extent.Text
+ }
+ $null = Get-StudioEarlyPython
+ $after = @(Get-ChildItem -LiteralPath $tmp -Recurse -Force).Count
+ Check "finding an interpreter writes nothing" ($after -eq $before)
+
+ # -I alone still imports site, so a sitecustomize could print into the answer or hang.
+ $exe = Get-StudioEarlyPython
+ $isoOnly = (& $exe -I -c "import sys;print(sys.flags.no_site)" 2>$null | Select-Object -First 1)
+ $isoPlus = (& $exe -I -S -c "import sys;print(sys.flags.no_site)" 2>$null | Select-Object -First 1)
+ Check "-I alone leaves site imported on this interpreter" ("$isoOnly".Trim() -eq "0")
+ Check "-S is what turns site off" ("$isoPlus".Trim() -eq "1")
+
+ # Read from the source: a planted sitecustomize is shadowed by the host's own.
+ $resolverFn = @($ast.FindAll({ param($n)
+ $n -is [System.Management.Automation.Language.FunctionDefinitionAst] -and
+ $n.Name -eq "Invoke-StudioEarlyPython"
+ }, $true))[0].Extent.Text
+ Check "the resolver runs the probe with -S as well as -I" (
+ $resolverFn -match '@\("-I",\s*"-S",\s*"-c"')
+ # A miss recorded before $VenvDir existed (the --tauri path) is probed again once it does.
+ $venvHome = Join-Path $tmp "venvhome"
+ $venvBin = if ($IsWindows -or $env:OS -eq "Windows_NT") { "Scripts" } else { "bin" }
+ $venvLeaf = if ($IsWindows -or $env:OS -eq "Windows_NT") { "python.exe" } else { "python3" }
+ New-Item -ItemType Directory -Force -Path (Join-Path $venvHome $venvBin) | Out-Null
+ Copy-Item -LiteralPath $exe -Destination (Join-Path $venvHome (Join-Path $venvBin $venvLeaf)) -Force
+ function Get-Command { param($Name, [switch]$All, $CommandType, $ErrorAction) return @() }
+ Remove-Variable -Name VenvDir -Scope Script -ErrorAction SilentlyContinue
+ Remove-Variable -Name VenvDir -Scope Global -ErrorAction SilentlyContinue
+ $script:StudioEarlyPythonProbed = $false
+ $script:StudioEarlyPython = $null
+ $script:StudioEarlyPythonProbedWithoutVenv = $false
+ Check "with no venv and no system Python the probe finds nothing" ($null -eq (Get-StudioEarlyPython))
+ Check "and it recorded that the venv was unknown when it looked" (
+ $script:StudioEarlyPythonProbedWithoutVenv -eq $true)
+ $global:StudioHome = $tmp
+ $global:StudioRedirectMode = "env"
+ $global:VenvDir = $venvHome
+ Check "a custom home that is not yet Unsloth's does not run its venv interpreter" ($null -eq (Get-StudioEarlyPython))
+ $script:StudioEarlyPythonProbed = $false
+ [System.IO.File]::WriteAllText((Join-Path $venvHome ".unsloth-studio-owned"), "")
+ Check "a custom home carrying the ownership marker does" (
+ "$(Get-StudioEarlyPython)" -like ("*" + $venvBin + "*"))
+ Remove-Item -LiteralPath (Join-Path $venvHome ".unsloth-studio-owned") -Force
+ # The shim counts only as the guard reads it, by content, never by name.
+ New-Item -ItemType Directory -Force -Path (Join-Path $tmp "bin") | Out-Null
+ Set-Content -LiteralPath (Join-Path $tmp "bin\unsloth.cmd") -Value "@echo planted"
+ $script:StudioEarlyPythonProbed = $false
+ $script:StudioEarlyPython = $null
+ Check "a planted unsloth.cmd does not make a custom home Unsloth's" ($null -eq (Get-StudioEarlyPython))
+ Set-Content -LiteralPath (Join-Path $tmp "bin\unsloth.cmd") -Value "@rem unsloth-studio-managed-launcher`r`n@python -c `"from unsloth_cli import app`""
+ $script:StudioEarlyPythonProbed = $false
+ $script:StudioEarlyPython = $null
+ Check "Unsloth's own launcher does" ("$(Get-StudioEarlyPython)" -like ("*" + $venvBin + "*"))
+ Remove-Item -LiteralPath (Join-Path $tmp "bin") -Recurse -Force
+ $script:StudioEarlyPythonProbed = $false
+ $script:StudioEarlyPython = $null
+ $global:StudioRedirectMode = "default"
+ $found = Get-StudioEarlyPython
+ Check "once the venv directory is known the venv interpreter is found after all" (
+ -not [string]::IsNullOrWhiteSpace($found))
+ Check "and it is the one inside the venv, not some other copy" (
+ "$found" -like ("*" + $venvBin + "*"))
+ $script:ReprobeCount = 0
+ function Test-Path { param($LiteralPath, $PathType, $ErrorAction) $script:ReprobeCount++; return $false }
+ $null = Get-StudioEarlyPython
+ Check "a hit is not probed again" ($script:ReprobeCount -eq 0)
+ # An uninspectable candidate (throws under Stop) is skipped without escaping.
+ function Test-Path { param($LiteralPath, $PathType, $ErrorAction)
+ throw [System.UnauthorizedAccessException]::new("Access to the path '$LiteralPath' is denied.") }
+ $script:StudioEarlyPythonProbed = $false
+ $script:StudioEarlyPython = $null
+ $threw = $null
+ try { $none = Get-StudioEarlyPython } catch { $threw = $_ }
+ Check "a candidate that cannot be inspected is skipped, not fatal" ($null -eq $threw -and $null -eq $none)
+ $savedFinder2 = ${function:Get-StudioEarlyPython}
+ function Get-StudioEarlyPython { throw "discovery failed" }
+ $script:StudioPythonFinalPathCache = $null
+ $threw = $null
+ try { $none = Get-StudioPythonFinalPath -Path $real } catch { $threw = $_ }
+ Check "a discovery failure declines to the lexical rung instead of throwing" ($null -eq $threw -and $null -eq $none)
+ ${function:Get-StudioEarlyPython} = $savedFinder2
+ Remove-Item Function:Test-Path -ErrorAction SilentlyContinue
+ Remove-Item Function:Get-Command -ErrorAction SilentlyContinue
+ Remove-Variable -Name VenvDir, StudioHome, StudioRedirectMode -Scope Global -ErrorAction SilentlyContinue
+ $script:ResolveCalls = 0
+ $savedInvoke = ${function:Invoke-StudioEarlyPython}
+ function Invoke-StudioEarlyPython { param($Exe, $Path, $TimeoutMs) $script:ResolveCalls++; return $Path }
+ $savedFinder3 = ${function:Get-StudioEarlyPython}
+ function Get-StudioEarlyPython { return "python3" }
+ $script:StudioPythonFinalPathCache = $null
+ $null = Get-StudioPythonFinalPath -Path $real
+ $null = Get-StudioPythonFinalPath -Path $real
+ $null = Get-StudioPythonFinalPath -Path $real
+ Check "three calls for one path spawn one child" ($script:ResolveCalls -eq 1)
+ $null = Get-StudioPythonFinalPath -Path $tmp
+ Check "and a different path still spawns its own" ($script:ResolveCalls -eq 2)
+ function Invoke-StudioEarlyPython { param($Exe, $Path, $TimeoutMs) $script:ResolveCalls++; return $null }
+ $missPath = Join-Path $tmp "no-such-thing"
+ $null = Get-StudioPythonFinalPath -Path $missPath
+ $null = Get-StudioPythonFinalPath -Path $missPath
+ Check "a miss is remembered as well as an answer" ($script:ResolveCalls -eq 3)
+ ${function:Invoke-StudioEarlyPython} = $savedInvoke
+ ${function:Get-StudioEarlyPython} = $savedFinder3
+ $script:StudioPythonFinalPathCache = $null
+
+} finally {
+ Remove-Item -LiteralPath $tmp -Recurse -Force -ErrorAction SilentlyContinue
+}
+
+Write-Host ""
+if ($failures -gt 0) { Write-Host "$failures check(s) failed" -ForegroundColor Red; exit 1 }
+Write-Host "All early-Python path resolver checks passed"
+exit 0
diff --git a/tests/studio/test_native_path_resolver_degrades.ps1 b/tests/studio/test_native_path_resolver_degrades.ps1
index 86f9888f4f1..df90e9f0719 100644
--- a/tests/studio/test_native_path_resolver_degrades.ps1
+++ b/tests/studio/test_native_path_resolver_degrades.ps1
@@ -100,6 +100,7 @@ $fns = @(
"Test-StudioCanDefineNativeTypes", "Test-StudioEmitInChildProcess", "New-StudioDynamicAssembly",
"New-StudioEmittedNativeType",
"Initialize-StudioFinalPathNativeType", "Get-StudioNativeFinalPath",
+ "Get-ElevationState", "Get-StudioEarlyPython", "Invoke-StudioEarlyPython", "Get-StudioPythonFinalPath",
"Resolve-StudioLinkTarget", "Get-StudioSubstTarget", "Get-StudioLexicalPath",
"Resolve-StudioFinalPathInfo",
"Initialize-StudioProcessImageNativeType", "Get-StudioNativeProcessImagePath",
@@ -192,6 +193,13 @@ Write-Host "REDEFINE_TYPE_INTACT: `$(`$null -ne (("UnslothEmitterOutParamProbe"
# 7. The other rung. Resolve-StudioFinalPathInfo is what every caller actually
# uses, and the point of the change is that it still answers when the native
# side cannot: a lexical path, and Exact false so the runtime lock fails closed.
+# The Python rung sits between the two and would answer EXACTLY on any host with
+# an interpreter, which is the opposite of the state being exercised here, so it
+# is switched off for this probe. It has its own coverage in
+# tests/studio/test_early_python_path_resolver.ps1.
+`$env:UNSLOTH_EARLY_PYTHON_PROBE = "0"
+`$script:StudioEarlyPythonProbed = `$false
+`$script:StudioEarlyPython = `$null
`$info = `$null
`$ladderThrew = `$false
try { `$info = Resolve-StudioFinalPathInfo -Path `$temp } catch { `$ladderThrew = `$true; Write-Host "LADDER_ERROR: `$(`$_.Exception.Message)" }