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.

66.7 KB
Raw Blame
# 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 shlex
import shutil
import stat
import string
import subprocess
import sys
import tempfile
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",
)

_PORTABLE_ONLY = ("HF_DATASETS_CACHE", "HF_ASSETS_CACHE", "TORCH_HOME")

_HF_ENV = ("HF_HOME", "HF_HUB_CACHE", "HF_XET_CACHE", "HUGGINGFACE_HUB_CACHE")


@pytest.fixture(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)
    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)
    monkeypatch.delenv("XDG_CONFIG_HOME", raising = False)
    monkeypatch.setenv("HOME", str(tmp_path / "home"))
    monkeypatch.setenv("USERPROFILE", str(tmp_path / "home"))
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "studio"))


@pytest.fixture(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}"


# cpp_builder.py re-splits compiler flags with shlex.split, so a root with a space breaks it.
_TOOLCHAIN_PINNED = (
    "TORCHINDUCTOR_CACHE_DIR",
    "TORCH_EXTENSIONS_DIR",
    "TRITON_CACHE_DIR",
    "TRITON_DUMP_DIR",
    "CUDA_CACHE_PATH",
)


def _a_temp_root_the_policy_accepts(monkeypatch, tmp_path):
    """A temp root the holding policy accepts on each platform; on Windows, LOCALAPPDATA is moved too."""
    root = tmp_path / "Temp"
    root.mkdir()
    monkeypatch.setenv("LOCALAPPDATA", str(tmp_path))
    monkeypatch.setattr(tempfile, "gettempdir", lambda: str(root))
    return root


def _as_the_compiler_sees_it(path):
    """The path as cpp_builder passes it: os.sep becomes / on Windows, so measure it that way, not raw."""
    return str(path).replace(os.sep, "/") if os.name == "nt" else str(path)


def _assert_no_unparseable_pin(sr, refused_root):
    """Unset is not automatically safe: torch's own fallback can reintroduce the refused character."""
    for key in _TOOLCHAIN_PINNED:
        value = os.environ.get(key)
        if value is None:
            continue
        assert value.strip(), f"{key} was left blank, which Inductor reads as a relative path"
        assert not sr.toolchain_path_unparseable(value), f"{key} was pinned to {value!r}"
        assert not value.startswith(str(refused_root)), f"{key} stayed inside {refused_root}"


def test_a_spaced_root_leaves_the_compiler_caches_to_their_own_defaults(monkeypatch, tmp_path):
    """Pinning a spaced path into the compiler broke torch.compile, so a parseable fallback is published."""
    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()

    _assert_no_unparseable_pin(sr, spaced)
    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 guard must fire only on a path a compiler cannot take, not on every path."""
    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


@pytest.mark.parametrize(
    "name",
    [
        pytest.param("o'brien", id = "an apostrophe, which shlex reads as an opening quote"),
        pytest.param(
            'say"hi',
            id = "a double quote",
            marks = pytest.mark.skipif(
                os.name == "nt",
                reason = "illegal in an NTFS name, so the fixture cannot be created",
            ),
        ),
    ],
)
def test_a_quoted_root_leaves_the_compiler_caches_to_their_own_defaults(
    name, monkeypatch, tmp_path
):
    """A quote is worse than a space: POSIX shlex swallows the rest of the command."""
    quoted = tmp_path / name / "studio"
    quoted.mkdir(parents = True)
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(quoted))
    sr = _load_storage_roots()

    sr._setup_cache_env()

    _assert_no_unparseable_pin(sr, quoted)
    for key in ("UV_CACHE_DIR", "NUMBA_CACHE_DIR", "UNSLOTH_COMPILE_LOCATION"):
        assert os.environ[key].startswith(str(quoted.parent)), key


@pytest.mark.skipif(os.name == "nt", reason = "on Windows the separator is not an escape")
def test_a_backslash_in_a_posix_root_leaves_the_compiler_caches_alone(monkeypatch, tmp_path):
    """Legal in a POSIX filename and an escape to shlex, so the character is eaten and the
    compiler is handed a path that does not exist. Windows is exempt because cpp_builder
    rewrites the separator to "/" before it builds the command."""
    odd = tmp_path / "a\\b" / "studio"
    odd.mkdir(parents = True)
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(odd))
    sr = _load_storage_roots()

    sr._setup_cache_env()

    _assert_no_unparseable_pin(sr, odd)


@pytest.mark.parametrize(
    "name",
    [
        "plain",
        "my dir",
        "o'brien",
        'say"hi',
        "a\tb",
        pytest.param(
            "a\\b",
            marks = pytest.mark.skipif(
                os.name == "nt",
                reason = "cpp_builder rewrites the separator before building the command",
            ),
        ),
    ],
)
def test_the_guard_agrees_with_what_shlex_actually_does_to_the_command(name, tmp_path):
    """Asks shlex.split whether a built command keeps the path whole, so the guard cannot drift from it."""
    path = _as_the_compiler_sees_it(tmp_path / name / "cache" / "torchinductor")
    command = f"g++ {path}/main.cpp -o {path}/main.so"
    sr = _load_storage_roots()

    try:
        survives = shlex.split(command) == ["g++", f"{path}/main.cpp", "-o", f"{path}/main.so"]
    except ValueError:
        survives = False

    assert sr.toolchain_path_unparseable(path) is not survives, (
        f"{name!r}: predicate says {sr.toolchain_path_unparseable(path)}, "
        f"shlex.split round trip says {survives}"
    )


def test_no_character_at_all_lets_a_mangled_path_through(tmp_path):
    """The guard may over-refuse Unicode spaces but must never let a mangled path through."""
    sr = _load_storage_roots()
    specials = list(string.printable) + [" ", " ", " ", " ", " ", "é"]
    if os.name == "nt":
        specials.remove("\\")

    leaked = []
    for char in specials:
        path = f"{_as_the_compiler_sees_it(tmp_path)}/unsloth{char}root/cache/torchinductor"
        command = f"g++ {path}/main.cpp -o {path}/main.so"
        try:
            survives = shlex.split(command) == ["g++", f"{path}/main.cpp", "-o", f"{path}/main.so"]
        except ValueError:
            survives = False
        if not survives and not sr.toolchain_path_unparseable(path):
            leaked.append(char)

    assert leaked == [], (
        "these characters would be pinned into a compiler command line that mangles them: "
        + ", ".join(repr(c) for c in leaked)
    )


def test_a_refused_root_gets_a_parseable_cache_rather_than_torchs_own(monkeypatch, tmp_path):
    """Unset is not safe: torch's default keeps the refused character, so a hex-named fallback is used."""
    refused = tmp_path / "o'brien" / "studio"
    refused.mkdir(parents = True)
    temp_root = _a_temp_root_the_policy_accepts(monkeypatch, tmp_path)
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(refused))
    sr = _load_storage_roots()
    monkeypatch.setattr(sr.tempfile, "gettempdir", lambda: str(temp_root))

    sr._setup_cache_env()
    first = os.environ["TORCHINDUCTOR_CACHE_DIR"]

    assert not sr.toolchain_path_unparseable(first)
    assert first.startswith(str(temp_root))
    assert Path(first).is_dir()

    # Stable: a cache that moved every launch would be a cold compile every launch.
    for key in _TOOLCHAIN_PINNED:
        monkeypatch.delenv(key, raising = False)
    sr._setup_cache_env()
    assert os.environ["TORCHINDUCTOR_CACHE_DIR"] == first


def _fallback_path(sr, key, intended):
    """Asks the resolver for its fallback path; a recomputed digest would silently stop matching it."""
    return Path(sr._parseable_toolchain_fallback(key, intended))


@pytest.mark.parametrize(
    "occupy",
    [
        pytest.param("file", id = "the name is already a regular file"),
        pytest.param(
            "readonly",
            id = "the directory exists but cannot be written",
            marks = pytest.mark.skipif(
                os.name == "nt",
                reason = "a read-only bit does not stop a write on Windows",
            ),
        ),
    ],
)
def test_an_unusable_fallback_is_not_published_either(occupy, monkeypatch, tmp_path):
    """mkdir(exist_ok) says nothing about writability, so the fallback gets the same probe too."""
    refused = tmp_path / "o'brien" / "studio"
    refused.mkdir(parents = True)
    temp_root = tmp_path / "tmp"
    temp_root.mkdir()
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(refused))
    sr = _load_storage_roots()
    monkeypatch.setattr(sr.tempfile, "gettempdir", lambda: str(temp_root))

    intended = str(sr.cache_root() / "torchinductor")
    squatter = _fallback_path(sr, "TORCHINDUCTOR_CACHE_DIR", intended)
    if occupy == "file":
        squatter.write_text("not a directory", encoding = "utf-8")
    else:
        squatter.mkdir()
        squatter.chmod(0o500)

    try:
        sr._setup_cache_env()
    finally:
        if occupy == "readonly":
            squatter.chmod(0o700)

    assert "TORCHINDUCTOR_CACHE_DIR" not in os.environ


@pytest.mark.skipif(os.name == "nt", reason = "the temporary root is per-account on Windows")
@pytest.mark.parametrize(
    "plant",
    [
        pytest.param("world-writable", id = "a directory another user left writable"),
        pytest.param("symlink", id = "a symlink planted at the name"),
    ],
)
def test_a_fallback_another_user_could_have_planted_is_refused(plant, monkeypatch, tmp_path):
    """The fallback sits in the SHARED temporary root under a name derived from the install, so
    it is predictable to anyone on the host. A write probe alone accepted a directory another
    local user had pre-created world-writable, and TORCH_EXTENSIONS_DIR is where torch loads
    compiled .so files from, so that is code execution in the Studio process rather than an
    untidy cache. Ownership cannot be staged here without a second uid, so these two cover the
    permission bits and the symlink; the uid check is exercised by inspection only."""
    refused = tmp_path / "o'brien" / "studio"
    refused.mkdir(parents = True)
    shared = tmp_path / "shared-tmp"
    shared.mkdir()
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(refused))
    sr = _load_storage_roots()
    monkeypatch.setattr(sr.tempfile, "gettempdir", lambda: str(shared))

    intended = str(sr.cache_root() / "torch-extensions" / sr._torch_runtime_tag())
    planted = _fallback_path(sr, "TORCH_EXTENSIONS_DIR", intended)
    if plant == "world-writable":
        planted.mkdir(mode = 0o777)
        planted.chmod(0o777)
    else:
        (shared / "elsewhere").mkdir()
        planted.symlink_to(shared / "elsewhere")

    sr._setup_cache_env()

    assert "TORCH_EXTENSIONS_DIR" not in os.environ


@pytest.mark.skipif(os.name == "nt", reason = "POSIX permission bits")
def test_the_fallback_it_creates_is_closed_to_everyone_else(monkeypatch, tmp_path):
    """When nothing blocks it, the fallback cache it creates must be closed to other accounts."""
    refused = tmp_path / "o'brien" / "studio"
    refused.mkdir(parents = True)
    shared = tmp_path / "shared-tmp"
    shared.mkdir()
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(refused))
    sr = _load_storage_roots()
    monkeypatch.setattr(sr.tempfile, "gettempdir", lambda: str(shared))

    sr._setup_cache_env()

    published = Path(os.environ["TORCH_EXTENSIONS_DIR"])
    mode = published.stat().st_mode
    assert not mode & (stat.S_IWGRP | stat.S_IWOTH), oct(mode & 0o777)
    assert published.stat().st_uid == os.geteuid()


@pytest.mark.skipif(os.name == "nt", reason = "POSIX rename permissions")
@pytest.mark.parametrize(
    "mode, published",
    [
        pytest.param(0o755, True, id = "a private holding directory"),
        pytest.param(0o1777, True, id = "world-writable WITH the sticky bit, which is /tmp"),
        pytest.param(0o1775, True, id = "group-writable WITH the sticky bit, owned by us"),
        pytest.param(0o777, False, id = "world-writable and NOT sticky"),
        pytest.param(0o775, False, id = "group-writable and NOT sticky"),
    ],
)
def test_the_holding_directory_decides_whether_the_fallback_can_be_swapped(
    mode, published, monkeypatch, tmp_path
):
    """A writable shared temp root without the sticky bit lets another account swap our cache aside."""
    refused = tmp_path / "o'brien" / "studio"
    refused.mkdir(parents = True)
    shared = tmp_path / "shared"
    shared.mkdir()
    shared.chmod(mode)
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(refused))
    sr = _load_storage_roots()
    monkeypatch.setattr(sr.tempfile, "gettempdir", lambda: str(shared))

    try:
        sr._setup_cache_env()
    finally:
        shared.chmod(0o755)

    assert ("TORCH_EXTENSIONS_DIR" in os.environ) is published


@pytest.mark.skipif(os.name == "nt", reason = "POSIX ownership semantics")
def test_an_ancestor_owned_by_another_account_is_refused(tmp_path):
    """An ancestor must be owned by this account or root too, since its owner can rename our root away."""
    from utils.paths import storage_roots

    outer = tmp_path / "outer"
    outer.mkdir()
    os.chmod(outer, 0o755)
    root = outer / "victim-tmp"
    root.mkdir()
    os.chmod(root, 0o700)

    assert (
        storage_roots._holding_dir_is_safe(root) is True
    ), "the same tree, ours throughout, is what the refusal below has to be measured against"

    real_stat = os.stat

    def foreign_owner(path, *args, **kwargs):
        info = real_stat(path, *args, **kwargs)
        if str(path) != str(outer):
            return info
        fields = list(info)[:10]
        fields[4] = os.geteuid() + 1
        return os.stat_result(tuple(fields))

    os.stat = foreign_owner
    try:
        assert storage_roots._holding_dir_is_safe(root) is False
    finally:
        os.stat = real_stat


@pytest.mark.skipif(os.name == "nt", reason = "POSIX symlink and mode semantics")
def test_a_temporary_root_reached_through_a_swappable_link_is_refused(tmp_path, monkeypatch):
    """Walk the lexical symlink chain too: a link in a 0777 directory stays replaceable. Symlinked
    roots are not refused outright, since macOS /tmp and /var must keep passing."""
    from utils.paths.storage_roots import _holding_dir_is_safe

    shared = tmp_path / "shared"
    shared.mkdir()
    os.chmod(shared, 0o777)
    private = tmp_path / "private"
    private.mkdir()
    os.chmod(private, 0o700)
    safe = tmp_path / "safe"
    safe.mkdir()
    os.chmod(safe, 0o755)

    swappable = shared / "tmp-link"
    swappable.symlink_to(private)
    assert _holding_dir_is_safe(swappable) is False

    aimed_at_shared = safe / "bad-link"
    target = shared / "target"
    target.mkdir()
    os.chmod(target, 0o700)
    aimed_at_shared.symlink_to(target)
    assert _holding_dir_is_safe(aimed_at_shared) is False

    held_safely = safe / "ok-link"
    held_safely.symlink_to(private)
    assert (
        _holding_dir_is_safe(held_safely) is True
    ), "a symlinked temporary root in a directory nobody else can write is still usable"


@pytest.mark.skipif(os.name == "nt", reason = "POSIX rename permissions")
def test_a_private_temp_root_inside_a_shared_parent_is_refused(monkeypatch, tmp_path):
    """Check every ancestor, not one level: a 0700 root inside a 0777 parent can still be renamed away."""
    shared = tmp_path / "shared"
    shared.mkdir()
    private_root = shared / "victim-tmp"
    private_root.mkdir(mode = 0o700)
    sr = _load_storage_roots()

    shared.chmod(0o777)
    try:
        assert sr._holding_dir_is_safe(private_root) is False
        assert sr._dir_is_not_swappable(private_root) is True
        shared.chmod(0o755)
        assert sr._holding_dir_is_safe(private_root) is True
    finally:
        shared.chmod(0o755)


@pytest.mark.skipif(os.name == "nt", reason = "POSIX sticky semantics")
def test_a_sticky_parent_owned_by_somebody_else_is_still_refused(monkeypatch, tmp_path):
    """Sticky is not a blanket safe answer.

    It narrows removal and rename of a child to the child's owner, the DIRECTORY's owner, and a
    privileged process, so a sticky shared directory belonging to another ordinary account still
    lets that account swap our cache after it was validated. /tmp passes because root owns it,
    and that is the case this branch is actually for. Staged by reporting a foreign uid for the
    parent, since a directory owned by another account cannot be created here."""
    shared = tmp_path / "shared"
    shared.mkdir()
    shared.chmod(0o1777)
    sr = _load_storage_roots()
    real_stat = sr.os.stat
    foreign = os.geteuid() + 4242

    def lying_stat(path, *args, **kwargs):
        info = real_stat(path, *args, **kwargs)
        if str(path) == str(shared):
            return os.stat_result(
                (
                    info.st_mode,
                    info.st_ino,
                    info.st_dev,
                    info.st_nlink,
                    foreign,
                    info.st_gid,
                    info.st_size,
                    int(info.st_atime),
                    int(info.st_mtime),
                    int(info.st_ctime),
                )
            )
        return info

    monkeypatch.setattr(sr.os, "stat", lying_stat)
    assert sr._holding_dir_is_safe(shared) is False

    monkeypatch.setattr(sr.os, "stat", real_stat)
    assert sr._holding_dir_is_safe(shared) is True


def test_the_windows_holding_rule_accepts_only_the_per_account_temp_root(monkeypatch, tmp_path):
    """On Windows only the default per-account temp root is accepted; mode bits prove nothing there."""
    local = tmp_path / "AppData" / "Local"
    default_temp = local / "Temp"
    default_temp.mkdir(parents = True)
    shared = tmp_path / "shared-temp"
    shared.mkdir()
    monkeypatch.setenv("LOCALAPPDATA", str(local))
    sr = _load_storage_roots()

    assert sr._windows_temp_root_is_private(default_temp) is True
    assert sr._windows_temp_root_is_private(shared) is False

    monkeypatch.delenv("LOCALAPPDATA", raising = False)
    assert sr._windows_temp_root_is_private(default_temp) is False

    # Source check: forcing os.name to "nt" makes pathlib raise before the branch is reached.
    import inspect

    windows_branch = inspect.getsource(sr._holding_dir_is_safe).split('if os.name == "nt":')[1]
    assert "_windows_temp_root_is_private(parent)" in windows_branch.strip().splitlines()[0]


@pytest.mark.skipif(os.name == "nt", reason = "the identity is the euid on POSIX")
def test_two_accounts_under_one_temp_root_do_not_collide(monkeypatch, tmp_path):
    """Put the euid in the cache digest, never the visible name (a login can be unparseable);
    otherwise a second OS account fails the ownership check."""
    sr = _load_storage_roots()
    intended = "/srv/o'brien/studio/cache/torch-extensions/tag"

    monkeypatch.setattr(sr.os, "geteuid", lambda: 1000)
    mine = sr._parseable_toolchain_fallback("TORCH_EXTENSIONS_DIR", intended)
    monkeypatch.setattr(sr.os, "geteuid", lambda: 1001)
    theirs = sr._parseable_toolchain_fallback("TORCH_EXTENSIONS_DIR", intended)

    assert mine and theirs and mine != theirs
    assert not sr.toolchain_path_unparseable(mine)
    assert sr._parseable_toolchain_fallback("TORCH_EXTENSIONS_DIR", intended) == theirs


def test_a_refused_root_with_no_usable_temp_root_still_publishes_nothing(monkeypatch, tmp_path):
    """The other end of the same branch. When the temporary directory carries the character too
    there is nowhere left to point, and an unset variable is better than a broken one."""
    refused = tmp_path / "o'brien" / "studio"
    refused.mkdir(parents = True)
    monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(refused))
    sr = _load_storage_roots()
    monkeypatch.setattr(sr.tempfile, "gettempdir", lambda: str(tmp_path / "also'bad"))

    sr._setup_cache_env()

    for key in _TOOLCHAIN_PINNED:
        assert key not in os.environ, key


def test_an_explicit_compiler_cache_is_left_alone_when_the_builders_can_read_it(
    monkeypatch, tmp_path
):
    """A caller who set the variable chose it, and a path the builders can read is carried out."""
    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_an_inherited_unreadable_compiler_cache_is_refused(monkeypatch, tmp_path):
    """Refuse an inherited unpasteable cache path; the cache is regenerable anyway."""
    monkeypatch.setenv("TORCHINDUCTOR_CACHE_DIR", str(tmp_path / "their choice"))
    temp_root = _a_temp_root_the_policy_accepts(monkeypatch, tmp_path)
    sr = _load_storage_roots()
    monkeypatch.setattr(sr.tempfile, "gettempdir", lambda: str(temp_root))

    sr._setup_cache_env()

    landed = os.environ.get("TORCHINDUCTOR_CACHE_DIR")
    assert landed != str(tmp_path / "their choice")
    assert landed is not None, "a usable temporary root was available, so it should be used"
    assert not sr.toolchain_path_unparseable(landed)


def test_the_refusal_only_applies_to_the_toolchain_keys(monkeypatch, tmp_path):
    """A spaced HuggingFace cache is nobody's compiler argument and stays exactly as given."""
    chosen = tmp_path / "their choice"
    monkeypatch.setenv("HF_HUB_CACHE", str(chosen))
    sr = _load_storage_roots()

    sr._setup_cache_env()

    assert os.environ["HF_HUB_CACHE"] == 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"))


@pytest.mark.parametrize(
    "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


_UNRECOGNIZED_PORTABLE = ("enabled", "flase", "2", "bogus", "y", "n", "disabled", "-1")


@pytest.mark.parametrize("value", _UNRECOGNIZED_PORTABLE)
def test_unrecognized_unsloth_portable_does_not_enable_portable_mode(monkeypatch, tmp_path, value):
    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}"


@pytest.mark.parametrize("value", _UNRECOGNIZED_PORTABLE + ("0", "false", "off", "no"))
def test_a_portable_root_stays_portable_whatever_unsloth_portable_says(
    monkeypatch, tmp_path, value
):
    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"


@pytest.mark.parametrize("value", _UNRECOGNIZED_PORTABLE)
def test_an_on_disk_portable_root_outranks_an_unrecognized_value(monkeypatch, value):
    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
    for accepted in ("1", "true", "yes", "on", "0", "false", "off", "no"):
        assert accepted in warning


@pytest.mark.parametrize("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.
    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]

    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]


@pytest.mark.parametrize("layout", ("nested", "flat"))
def test_a_self_contained_layout_never_warns(monkeypatch, tmp_path, layout):
    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):
    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:
    """Stat of the target raises the error, since chmod can only produce EACCES, not EIO."""

    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 proves nothing unless a sibling pin that always happens is asserted too."""
    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")


@contextlib.contextmanager
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, so verify chmod really took effect.
            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()
    (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)


@pytest.mark.parametrize(
    "prepare, pinned",
    [
        # MPLCONFIGDIR also moves the config dir; matplotlib creates it on import, so existence is not 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)
    (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


@pytest.mark.parametrize(
    "prepare, pinned",
    [
        # Data Designer's home holds user data, not cache; ours wins once it has been used.
        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 also move ~/.triton/override, which holds user files.
    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 fake 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:
    """Matches matplotlib's own rc lookup: XDG on Linux, ~/.matplotlib on other platforms."""
    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


@pytest.mark.skipif(
    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 needing a home.
    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):
    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
    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)


@contextlib.contextmanager
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:
    """Written out rather than imported from storage_roots, so exact-string tests can catch a tag change."""
    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]
    assert all(part.replace(".", "").replace("-", "").replace("_", "").isalnum() for part in tags)


def test_torch_extension_tag_survives_a_missing_torch(tmp_path):
    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 CPU and CUDA builds share a __version__, differing only in the 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):
    # arm64 and Rosetta x86_64 pythons on one Mac would otherwise share torch's cache folder.
    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 and must not import it; the fake package raises on import.
    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):
    """A later legacy matplotlibrc must not displace the managed one; the dpi would flip per launch."""
    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):
    """A blank toolchain override must count as unset on a refused root, or it becomes a relative path."""
    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 (
        os.environ.get("TORCHINDUCTOR_CACHE_DIR") or ""
    ).strip() != "" or "TORCHINDUCTOR_CACHE_DIR" not in os.environ
    _assert_no_unparseable_pin(sr, spaced)


def test_an_unusable_managed_inductor_path_is_not_published(monkeypatch, tmp_path):
    """Torch trusts TORCHINDUCTOR_CACHE_DIR as given, so an unusable path fails every compile."""
    cache = tmp_path / "studio" / "cache"
    cache.mkdir(parents = True)
    (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
    assert os.environ["CUDA_CACHE_PATH"] == str(cache / "cuda")


@pytest.mark.skipif(
    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 read-only cache directory counts as missing: torch falls back only when the variable is UNSET."""
    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"
    )


@pytest.mark.skipif(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):
    """An unreadable note is not a miss: _recorded_master_root() memoises for the process lifetime."""
    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; forget_recorded_master_root() is the way out.
    (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 must answer False on any failure, since an os.close OSError would crash startup."""
    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 file is out of env_remove's reach, so UNSLOTH_HOME and UNSLOTH_PORTABLE can come back."""
    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):
    """A non-default root that contains this Studio tree is what the recorded 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")


@pytest.mark.parametrize(
    "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
):
    """Honour a master root only when a reader should; the hub cache stays shared when declined."""
    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)


# Pair each decline with pins that must still happen, so the absence checks are falsifiable.
_DECLINE_SIBLINGS = (
    "TORCHINDUCTOR_CACHE_DIR",
    "NUMBA_CACHE_DIR",
    "CUDA_CACHE_PATH",
    "UV_CACHE_DIR",
    "UNSLOTH_COMPILE_LOCATION",
)


@pytest.mark.parametrize("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")
    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):
    """A file in the config path is FileNotFoundError on Windows, so the pin must decline there too."""
    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 directory must still read as empty, or every pin would be declined.
    empty = tmp_path / "really-empty"
    empty.mkdir()
    assert sr._nothing_at(empty / "matplotlibrc") is True
    assert sr._nothing_at(tmp_path / "never" / "created" / "matplotlibrc") is True