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.

46.7 KB
Raw Blame
# Unsloth Zoo - Utilities for Unsloth
# Copyright 2023-present Daniel Han-Chen, Michael Han-Chen & the Unsloth team. All rights reserved.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as published
# by the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Affero General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.

"""Runtime validation must match setup: tiktoken is best-effort, so its absence is still complete."""

import contextlib
import pathlib
import shutil
import sys

import pytest
import types as _types
import os
from pathlib import Path

_BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
if _BACKEND_DIR not in sys.path:
    sys.path.insert(0, _BACKEND_DIR)

_loggers_stub = _types.ModuleType("loggers")
_loggers_stub.get_logger = lambda name: __import__("logging").getLogger(name)
sys.modules.setdefault("loggers", _loggers_stub)

import utils.transformers_version as tv


def _sidecar(
    root,
    *names,
    versions = None,
):
    versions = versions or {}
    for name in names:
        (root / name).mkdir(parents = True)
        version = versions.get(name)
        if version:
            info = root / f"{name}-{version}.dist-info"
            info.mkdir()
            (info / "METADATA").write_text(f"Name: {name}\nVersion: {version}\n", encoding = "utf-8")
    (root / tv._STUDIO_OWNED_MARKER).touch()


def test_a_failed_optional_install_leaves_no_partial_payload(tmp_path, monkeypatch):
    """A failed optional tiktoken install still accepts the sidecar, but leaves no payload: a
    half-copied tree would shadow site-packages."""
    root = tmp_path / ".venv_t5_550"
    monkeypatch.setattr(tv, "_venv_dir_is_valid_and_undamaged", lambda *a, **k: False)
    optional = [p for p in tv._VENV_T5_550_PACKAGES if p.startswith("tiktoken")]
    assert optional and tv._sidecar_package_is_optional(optional[0])

    def fake_install(pkg, target):
        if pkg.startswith("tiktoken"):
            (Path(target) / "tiktoken").mkdir()
            (Path(target) / "tiktoken" / "__init__.py").write_text("", encoding = "utf-8")
            (Path(target) / "tiktoken_ext").mkdir()
            (Path(target) / "tiktoken_ext" / "openai_public.py").write_text("", encoding = "utf-8")
            (Path(target) / "tiktoken-0.9.0.dist-info").mkdir()
            (Path(target) / "tiktoken-0.9.0.dist-info" / "METADATA").write_text(
                "", encoding = "utf-8"
            )
            return False
        return True

    monkeypatch.setattr(tv, "_install_to_dir", fake_install)
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is True
    assert not (root / "tiktoken").exists()
    # The plugin namespace too: a partial tiktoken_ext shadows the ambient openai_public module.
    assert not (root / "tiktoken_ext").exists()
    assert not list(root.glob("tiktoken-*.dist-info"))
    assert tv._optional_package_absent(str(root), "tiktoken") is True


def test_a_staging_move_that_fails_part_way_rolls_the_moved_entries_back(tmp_path, monkeypatch):
    """os.replace failing on the second entry used to leave the first one in the sidecar
    with no dist-info for the whole retry backoff; the package must read as absent."""
    root = tmp_path / ".venv_t5_550"
    root.mkdir()

    def fake_install(pkg, target):
        (Path(target) / "tiktoken").mkdir()
        (Path(target) / "tiktoken" / "__init__.py").write_text("", encoding = "utf-8")
        (Path(target) / "tiktoken_ext").mkdir()
        (Path(target) / "tiktoken_ext" / "openai_public.py").write_text("", encoding = "utf-8")
        (Path(target) / "tiktoken-0.9.0.dist-info").mkdir()
        (Path(target) / "tiktoken-0.9.0.dist-info" / "RECORD").write_text("", encoding = "utf-8")
        return True

    monkeypatch.setattr(tv, "_install_to_dir", fake_install)
    real_replace = tv.os.replace
    moved = []

    def flaky_replace(source, target):
        if ".top-up-staging" in str(source) and len(moved) == 1:
            raise OSError("disk full")
        moved.append(target)
        return real_replace(source, target)

    monkeypatch.setattr(tv.os, "replace", flaky_replace)
    assert tv._stage_optional_package("tiktoken", str(root)) is False
    assert len(moved) == 1
    assert not (root / "tiktoken").exists()
    assert not (root / "tiktoken_ext").exists()
    assert not list(root.glob("tiktoken-*.dist-info"))
    assert not (root / ".top-up-staging").exists()
    assert tv._optional_package_absent(str(root), "tiktoken") is True


def test_a_sidecar_without_tiktoken_is_still_valid(tmp_path):
    root = tmp_path / ".venv_t5_550"
    _sidecar(
        root,
        "transformers",
        "huggingface_hub",
        "hf_xet",
        versions = {
            "transformers": tv.TRANSFORMERS_550_VERSION,
            "huggingface_hub": "1.8.0",
            "hf_xet": "1.4.2",
        },
    )
    assert tv._venv_dir_is_valid(str(root), tv._VENV_T5_550_PACKAGES) is True
    assert (
        tv._venv_dir_is_valid(str(root), tv._venv_t5_latest_packages(tv.TRANSFORMERS_550_VERSION))
        is True
    )


def test_a_sidecar_without_a_required_package_is_still_invalid(tmp_path):
    root = tmp_path / ".venv_t5_550"
    _sidecar(
        root,
        "transformers",
        "huggingface_hub",
        "tiktoken",
        versions = {"transformers": tv.TRANSFORMERS_550_VERSION, "huggingface_hub": "1.8.0"},
    )
    assert tv._venv_dir_is_valid(str(root), tv._VENV_T5_550_PACKAGES) is False


def test_a_runtime_repair_survives_a_tiktoken_that_will_not_install(tmp_path, monkeypatch):
    root = tmp_path / ".venv_t5_550"
    installed = []

    def fake_install(pkg, target_dir):
        installed.append(pkg)
        return not pkg.startswith("tiktoken")

    monkeypatch.setattr(tv, "_install_to_dir", fake_install)
    monkeypatch.setattr(tv, "_venv_dir_is_valid_and_undamaged", lambda *a, **k: False)
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is True
    assert installed == list(tv._VENV_T5_550_PACKAGES)

    def fake_install_failing_required(pkg, target_dir):
        return not pkg.startswith("hf_xet")

    monkeypatch.setattr(tv, "_install_to_dir", fake_install_failing_required)
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is False


def test_a_rebuild_records_the_optional_install_it_could_not_do(tmp_path, monkeypatch):
    """A rebuild must record the optional install it could not do, or the next top-up and every
    worker meet the outage again."""
    root = tmp_path / ".venv_t5_550"
    monkeypatch.setattr(tv, "_install_to_dir", lambda pkg, target: not pkg.startswith("tiktoken"))
    monkeypatch.setattr(tv, "_venv_dir_is_valid_and_undamaged", lambda *a, **k: False)
    tv._OPTIONAL_TOP_UP_ATTEMPTED.clear()

    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is True

    optional = next(p for p in tv._VENV_T5_550_PACKAGES if p.startswith("tiktoken"))
    assert tv._top_up_failed_recently(str(root), optional) is True
    assert (os.path.normcase(os.path.abspath(str(root))), optional) in tv._OPTIONAL_TOP_UP_ATTEMPTED
    tv._record_top_up_outcome(str(root), optional, True)
    assert tv._top_up_failed_recently(str(root), optional) is False


def test_a_remnant_that_will_not_go_fails_the_build_instead_of_shadowing(tmp_path, monkeypatch):
    """An unremovable tiktoken remnant must fail the build, since it would shadow site-packages."""
    root = tmp_path / ".venv_t5_550"

    def fake_install(pkg, target_dir):
        if pkg.startswith("tiktoken"):
            (Path(target_dir) / "tiktoken").mkdir(parents = True, exist_ok = True)
            (Path(target_dir) / "tiktoken" / "__init__.py").write_text("", encoding = "utf-8")
            return False
        return True

    monkeypatch.setattr(tv, "_install_to_dir", fake_install)
    monkeypatch.setattr(tv, "_venv_dir_is_valid_and_undamaged", lambda *a, **k: False)
    real_rmtree = tv.shutil.rmtree

    def stuck_rmtree(path, *a, **k):
        if Path(path).name == "tiktoken":
            return None
        return real_rmtree(path, *a, **k)

    monkeypatch.setattr(tv.shutil, "rmtree", stuck_rmtree)
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is False
    # A failed build wipes the partial tree; either way nothing reads as a usable sidecar.
    assert tv._venv_dir_is_valid_and_undamaged(str(root), tv._VENV_T5_550_PACKAGES) is False
    monkeypatch.setattr(tv.shutil, "rmtree", real_rmtree)
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is True
    assert not (root / "tiktoken").exists()
    assert tv._remove_optional_remnants(str(root), "tiktoken==0.12.0") is True


def test_a_present_tiktoken_is_held_to_its_record_like_any_other(tmp_path, monkeypatch):
    """Only absence is optional: a present tiktoken whose RECORD names a missing file (interrupted
    install, stale native extension) fails at import and must be reported."""
    root = tmp_path / ".venv_t5_550"
    _sidecar(
        root,
        "transformers",
        "huggingface_hub",
        "hf_xet",
        versions = {
            "transformers": tv.TRANSFORMERS_550_VERSION,
            "huggingface_hub": "1.8.0",
            "hf_xet": "1.4.2",
        },
    )
    (root / "transformers" / "__init__.py").write_text("", encoding = "utf-8")
    info = root / "tiktoken-0.9.0.dist-info"
    info.mkdir()
    (info / "METADATA").write_text("Name: tiktoken\nVersion: 0.9.0\n", encoding = "utf-8")
    (info / "RECORD").write_text("tiktoken/__init__.py,sha256=abc,1234\n", encoding = "utf-8")
    monkeypatch.delenv(tv._SIDECAR_FILE_CHECK_ENV, raising = False)
    assert tv._sidecar_damaged_files(str(root)) != []
    assert tv._venv_dir_is_valid_and_undamaged(str(root), tv._VENV_T5_550_PACKAGES) is False
    (root / "tiktoken").mkdir()
    (root / "tiktoken" / "__init__.py").write_bytes(b"x" * 1234)
    assert tv._sidecar_damaged_files(str(root)) == []
    assert tv._venv_dir_is_valid_and_undamaged(str(root), tv._VENV_T5_550_PACKAGES) is True
    hub = root / "huggingface_hub-1.8.0.dist-info"
    (hub / "RECORD").write_text("huggingface_hub/gone.py,sha256=abc,12\n", encoding = "utf-8")
    assert tv._sidecar_damaged_files(str(root)) != []


def test_a_valid_sidecar_missing_tiktoken_is_topped_up_once(tmp_path, monkeypatch):
    """A sidecar missing tiktoken gets a one-time top-up, so a transient failure is not permanent."""
    root = tmp_path / ".venv_t5_550"
    root.mkdir()
    monkeypatch.setattr(tv, "_venv_dir_is_valid_and_undamaged", lambda *a, **k: True)
    installed: list[tuple[str, str]] = []
    monkeypatch.setattr(
        tv, "_install_to_dir", lambda pkg, target: installed.append((pkg, target)) or False
    )
    tv._OPTIONAL_TOP_UP_ATTEMPTED.clear()
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is True
    assert installed == [("tiktoken", str(root / ".top-up-staging"))]
    assert root.is_dir(), "the top-up must not wipe the sidecar"
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is True
    assert len(installed) == 1, "an unavailable wheel is asked for once per process"
    tv._OPTIONAL_TOP_UP_ATTEMPTED.clear()
    (root / tv._OPTIONAL_TOP_UP_FAILED).unlink()
    (root / "tiktoken").mkdir()
    (root / "tiktoken" / "__init__.py").write_text("", encoding = "utf-8")
    (root / "tiktoken-0.9.0.dist-info").mkdir()
    (root / "tiktoken-0.9.0.dist-info" / "RECORD").write_text("", encoding = "utf-8")
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is True
    assert len(installed) == 1


def test_a_failed_top_up_is_remembered_across_processes_and_retried_later(tmp_path, monkeypatch):
    """Each worker would rerun the same doomed install, so a failed top-up is recorded beside the
    sidecar, read by later processes, and retried after a while."""
    root = tmp_path / ".venv_t5_550"
    root.mkdir()
    packages = tv._VENV_T5_550_PACKAGES
    installed = []
    monkeypatch.setattr(tv, "_install_to_dir", lambda pkg, target: installed.append(pkg) or False)
    tv._OPTIONAL_TOP_UP_ATTEMPTED.clear()
    tv._top_up_optional_packages(str(root), packages)
    assert installed == ["tiktoken"]
    # A fresh process: the in-memory set is empty, the file is not.
    tv._OPTIONAL_TOP_UP_ATTEMPTED.clear()
    tv._top_up_optional_packages(str(root), packages)
    assert installed == ["tiktoken"]
    failures = tv._read_top_up_failures(str(root))
    failures["tiktoken"] -= tv._OPTIONAL_TOP_UP_RETRY_SECONDS + 1
    tv._write_top_up_failures(str(root), failures)
    tv._OPTIONAL_TOP_UP_ATTEMPTED.clear()
    tv._top_up_optional_packages(str(root), packages)
    assert installed == ["tiktoken", "tiktoken"]
    monkeypatch.setattr(tv, "_install_to_dir", lambda pkg, target: installed.append(pkg) or True)
    failures = tv._read_top_up_failures(str(root))
    failures["tiktoken"] -= tv._OPTIONAL_TOP_UP_RETRY_SECONDS + 1
    tv._write_top_up_failures(str(root), failures)
    tv._OPTIONAL_TOP_UP_ATTEMPTED.clear()
    tv._top_up_optional_packages(str(root), packages)
    assert not (root / tv._OPTIONAL_TOP_UP_FAILED).exists()


def test_a_partial_live_tree_goes_when_the_top_up_install_itself_fails(tmp_path, monkeypatch):
    """An interrupted top-up leaves tiktoken/ without its dist-info; if the next install fails
    offline, the partial payload must not stay ahead of site-packages during backoff."""
    root = tmp_path / ".venv_t5_550"
    (root / "tiktoken").mkdir(parents = True)
    (root / "tiktoken" / "__init__.py").write_text("", encoding = "utf-8")
    (root / "tiktoken_ext").mkdir()
    (root / "tiktoken_ext" / "openai_public.py").write_text("", encoding = "utf-8")
    assert tv._optional_package_absent(str(root), "tiktoken==0.12.0") is True
    monkeypatch.setattr(tv, "_install_to_dir", lambda pkg, target_dir: False)
    assert tv._stage_optional_package("tiktoken==0.12.0", str(root)) is False
    assert not (root / "tiktoken").exists()
    assert not (root / "tiktoken_ext").exists()
    assert not (root / ".top-up-staging").exists()


def _partial_tiktoken(root):
    (root / "tiktoken").mkdir(parents = True, exist_ok = True)
    (root / "tiktoken" / "__init__.py").write_text("", encoding = "utf-8")
    (root / "tiktoken_ext").mkdir(exist_ok = True)
    (root / "tiktoken_ext" / "openai_public.py").write_text("", encoding = "utf-8")


def test_offline_still_clears_a_partial_optional_payload(tmp_path, monkeypatch):
    """A worker killed before its dist-info landed leaves tiktoken/ ahead of site-packages; offline,
    the partial tree must still go, or the sidecar shadows it."""
    root = tmp_path / ".venv_t5_550"
    _partial_tiktoken(root)
    monkeypatch.setenv("UV_OFFLINE", "1")
    installs = []
    monkeypatch.setattr(
        tv, "_install_to_dir", lambda pkg, target_dir: installs.append(pkg) or False
    )
    assert tv._top_up_optional_packages(str(root), tv._VENV_T5_550_PACKAGES) is True
    assert installs == []
    assert not (root / "tiktoken").exists() and not (root / "tiktoken_ext").exists()
    _partial_tiktoken(root)
    monkeypatch.setattr(tv, "_venv_dir_is_valid_and_undamaged", lambda *a, **k: True)
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is True
    assert not (root / "tiktoken").exists()


def test_a_partial_payload_behind_an_unobtainable_lock_withholds_the_sidecar(tmp_path, monkeypatch):
    """If the lock is unobtainable and a payload lacks its RECORD, nothing is touched and the
    sidecar is withheld so the payload cannot shadow the ambient copy; an empty dir is usable."""
    import contextlib

    root = tmp_path / ".venv_t5_550"
    root.mkdir()
    _partial_tiktoken(root)
    monkeypatch.delenv("UV_OFFLINE", raising = False)
    monkeypatch.setattr(tv, "_env_offline", lambda: False)
    monkeypatch.setattr(tv, "_install_to_dir", lambda pkg, target_dir: False)

    @contextlib.contextmanager
    def not_held(venv_dir):
        yield False

    monkeypatch.setattr(tv, "_optional_top_up_lock", not_held)
    tv._OPTIONAL_TOP_UP_ATTEMPTED.clear()
    assert tv._top_up_optional_packages(str(root), tv._VENV_T5_550_PACKAGES) is False
    assert (root / "tiktoken").is_dir()
    import shutil as _shutil

    _shutil.rmtree(root / "tiktoken")
    _shutil.rmtree(root / "tiktoken_ext")
    tv._OPTIONAL_TOP_UP_ATTEMPTED.clear()
    assert tv._top_up_optional_packages(str(root), tv._VENV_T5_550_PACKAGES) is True


def test_a_sidecar_whose_top_up_remnants_will_not_go_is_not_activated(tmp_path, monkeypatch):
    """The top-up failed and the cleanup could not remove the partial tree (a locked
    file, a permission): the sidecar the cleanup itself calls unusable is not activated."""
    root = tmp_path / ".venv_t5_550"
    root.mkdir()
    _partial_tiktoken(root)
    monkeypatch.delenv("UV_OFFLINE", raising = False)
    monkeypatch.setattr(tv, "_env_offline", lambda: False)
    monkeypatch.setattr(tv, "_install_to_dir", lambda pkg, target_dir: False)
    monkeypatch.setattr(tv, "_venv_dir_is_valid_and_undamaged", lambda *a, **k: True)
    real_rmtree = tv.shutil.rmtree

    def stuck_rmtree(path, *a, **k):
        if Path(path).name in ("tiktoken", "tiktoken_ext"):
            return None
        return real_rmtree(path, *a, **k)

    monkeypatch.setattr(tv.shutil, "rmtree", stuck_rmtree)
    tv._OPTIONAL_TOP_UP_ATTEMPTED.clear()
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is False
    assert (root / "tiktoken").is_dir()
    monkeypatch.setattr(tv.shutil, "rmtree", real_rmtree)
    tv._OPTIONAL_TOP_UP_ATTEMPTED.clear()
    (root / tv._OPTIONAL_TOP_UP_FAILED).unlink(missing_ok = True)
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is True
    assert not (root / "tiktoken").exists()


def test_an_interrupted_top_up_is_finished_by_the_next_one(tmp_path, monkeypatch):
    """A package counts as present only once its dist-info has landed, so a process killed mid-move
    leaves a partial payload that the next top-up replaces."""
    root = tmp_path / ".venv_t5_550"
    root.mkdir()
    (root / "tiktoken").mkdir()
    (root / "tiktoken" / "__init__.py").write_text("", encoding = "utf-8")
    assert tv._optional_package_absent(str(root), "tiktoken") is True
    (root / "tiktoken-0.9.0.dist-info").mkdir()
    assert tv._optional_package_absent(str(root), "tiktoken") is True
    (root / "tiktoken-0.9.0.dist-info" / "RECORD").write_text("", encoding = "utf-8")
    assert tv._optional_package_absent(str(root), "tiktoken") is False
    shutil.rmtree(root / "tiktoken-0.9.0.dist-info")

    def fake_install(pkg, target):
        for d in ("tiktoken", "tiktoken_ext", "tiktoken-0.9.0.dist-info"):
            (pathlib.Path(target) / d).mkdir()
            (pathlib.Path(target) / d / "RECORD").write_text(d, encoding = "utf-8")
        (pathlib.Path(target) / "tiktoken" / "__init__.py").write_text("", encoding = "utf-8")
        return True

    monkeypatch.setattr(tv, "_install_to_dir", fake_install)
    tv._OPTIONAL_TOP_UP_ATTEMPTED.clear()
    tv._top_up_optional_packages(str(root), tv._VENV_T5_550_PACKAGES)
    assert tv._optional_package_absent(str(root), "tiktoken") is False
    assert (root / "tiktoken_ext" / "RECORD").is_file()


def test_latest_sidecar_activation_tops_up_a_missing_tiktoken(tmp_path, monkeypatch):
    """Activation goes through _ensure_venv_t5_latest_exists, not provisioning, so a healthy latest
    sidecar missing tiktoken must get its top-up there or Qwen models fail to tokenize."""
    latest = tmp_path / ".venv_t5_latest"
    latest.mkdir()
    packages = ("transformers==9.9.9", "huggingface_hub==1.8.0", "hf_xet==1.4.2", "tiktoken")
    monkeypatch.setattr(tv, "_VENV_T5_LATEST_DIR", str(latest))
    monkeypatch.setattr(tv, "_latest_pin_data", lambda: {"version": "9.9.9", "packages": packages})
    monkeypatch.setattr(tv, "_venv_dir_health", lambda *a, **k: (True, True))
    installed = []
    monkeypatch.setattr(
        tv, "_install_to_dir", lambda pkg, target: installed.append((pkg, target)) or True
    )
    tv._OPTIONAL_TOP_UP_ATTEMPTED.clear()
    assert tv._ensure_venv_t5_latest_exists() is True
    assert installed == [("tiktoken", str(latest / ".top-up-staging"))]


def test_the_top_up_stays_home_offline_and_yields_to_another_process(tmp_path, monkeypatch):
    """Workers activate tiers themselves: offline, a best-effort package must not cost network
    retries, and concurrent top-ups must not both write the shared sidecar."""
    root = tmp_path / ".venv_t5_550"
    root.mkdir()
    packages = tv._VENV_T5_550_PACKAGES
    installed = []
    monkeypatch.setattr(tv, "_install_to_dir", lambda pkg, target: installed.append(pkg) or True)
    tv._OPTIONAL_TOP_UP_ATTEMPTED.clear()
    monkeypatch.setenv("HF_HUB_OFFLINE", "1")
    tv._top_up_optional_packages(str(root), packages)
    assert installed == []
    monkeypatch.delenv("HF_HUB_OFFLINE")
    monkeypatch.setenv("UV_OFFLINE", "1")
    tv._top_up_optional_packages(str(root), packages)
    assert installed == []
    # Every spelling uv accepts, or an offline miss would be remembered as a failure.
    for spelling in ("t", "y", "on", "TRUE"):
        monkeypatch.setenv("UV_OFFLINE", spelling)
        tv._OPTIONAL_TOP_UP_ATTEMPTED.clear()
        tv._top_up_optional_packages(str(root), packages)
        assert installed == [], spelling
    assert not (root / tv._OPTIONAL_TOP_UP_FAILED).exists()
    # ...unless pip has a local wheelhouse, the exception _install_to_dir makes.
    monkeypatch.setenv("UV_OFFLINE", "1")
    monkeypatch.setattr(tv, "_pip_is_configured_offline", lambda: True)
    tv._OPTIONAL_TOP_UP_ATTEMPTED.clear()
    tv._top_up_optional_packages(str(root), packages)
    assert installed == ["tiktoken"]
    installed.clear()
    monkeypatch.setattr(tv, "_pip_is_configured_offline", lambda: False)
    monkeypatch.delenv("UV_OFFLINE")
    # Another process holds the top-up lock: wait up to the bound, then leave the package to it.
    monkeypatch.setattr(tv, "_OPTIONAL_TOP_UP_WAIT_SECONDS", 0.5)
    with tv._optional_top_up_lock(str(root)) as held:
        assert held is True
        tv._OPTIONAL_TOP_UP_ATTEMPTED.clear()
        tv._top_up_optional_packages(str(root), packages)
        assert installed == []
    tv._OPTIONAL_TOP_UP_ATTEMPTED.clear()
    tv._top_up_optional_packages(str(root), packages)
    assert installed == ["tiktoken"]


def test_the_top_up_is_staged_and_lands_dist_info_last(tmp_path, monkeypatch):
    """A scan by another worker must never meet a RECORD whose files have not landed:
    the package is built beside the sidecar and moved in, payload first, dist-info last."""
    root = tmp_path / ".venv_t5_550"
    root.mkdir()
    order = []

    def fake_install(pkg, target):
        assert target != str(root), "installed straight into the shared sidecar"
        for d in ("tiktoken", "tiktoken_ext", "tiktoken-0.9.0.dist-info"):
            (pathlib.Path(target) / d).mkdir()
            (pathlib.Path(target) / d / "marker").write_text(d, encoding = "utf-8")
        return True

    real_replace = tv.os.replace

    def replacing(src, dst):
        order.append(pathlib.Path(dst).name)
        return real_replace(src, dst)

    monkeypatch.setattr(tv, "_install_to_dir", fake_install)
    monkeypatch.setattr(tv.os, "replace", replacing)
    assert tv._stage_optional_package("tiktoken", str(root)) is True
    assert order[-1] == "tiktoken-0.9.0.dist-info"
    assert set(order) == {"tiktoken", "tiktoken_ext", "tiktoken-0.9.0.dist-info"}
    assert (root / "tiktoken" / "marker").is_file() and not (root / ".top-up-staging").exists()


def test_the_top_up_removes_the_recordless_dist_info_an_interrupted_install_left(
    tmp_path, monkeypatch
):
    """A recordless dist-info is removed before new metadata lands, or the old version still reports."""
    root = tmp_path / ".venv_t5_550"
    root.mkdir()
    stale = root / "tiktoken-0.7.0.dist-info"
    stale.mkdir()
    (stale / "METADATA").write_text("Name: tiktoken\nVersion: 0.7.0\n", encoding = "utf-8")
    other = root / "regex-2024.11.6.dist-info"
    other.mkdir()
    (other / "RECORD").write_text("", encoding = "utf-8")

    def fake_install(pkg, target):
        for d in ("tiktoken", "tiktoken-0.9.0.dist-info"):
            (pathlib.Path(target) / d).mkdir()
            (pathlib.Path(target) / d / "marker").write_text(d, encoding = "utf-8")
        return True

    monkeypatch.setattr(tv, "_install_to_dir", fake_install)
    assert tv._stage_optional_package("tiktoken", str(root)) is True
    assert not stale.exists()
    assert (root / "tiktoken-0.9.0.dist-info" / "marker").is_file()
    assert (other / "RECORD").is_file()


def test_a_recordless_record_beside_a_complete_install_is_removed_without_a_top_up(
    tmp_path, monkeypatch
):
    """A retry leaves a stale RECORD beside a present package; remove it without a top-up."""
    root = tmp_path / ".venv_t5_550"
    (root / "tiktoken").mkdir(parents = True)
    (root / "tiktoken" / "__init__.py").write_text("", encoding = "utf-8")
    good = root / "tiktoken-0.9.0.dist-info"
    good.mkdir()
    (good / "RECORD").write_text("", encoding = "utf-8")
    stale = root / "tiktoken-0.7.0.dist-info"
    stale.mkdir()
    (stale / "METADATA").write_text("Name: tiktoken\nVersion: 0.7.0\n", encoding = "utf-8")
    monkeypatch.setattr(tv, "_env_offline", lambda: False)
    monkeypatch.delenv("UV_OFFLINE", raising = False)
    monkeypatch.setattr(
        tv, "_install_to_dir", lambda *a, **k: pytest.fail("installed over a present package")
    )
    tv._OPTIONAL_TOP_UP_ATTEMPTED.clear()
    tv._top_up_optional_packages(str(root), ("tiktoken",))
    assert not stale.exists()
    assert (good / "RECORD").is_file()


def test_an_offline_session_does_not_wipe_a_sidecar_it_cannot_rebuild(tmp_path, monkeypatch):
    """An offline update must not wipe a sidecar it cannot rebuild; a warm cache allows a swap."""
    root = tmp_path / ".venv_t5_550"
    root.mkdir()
    (root / "keep.txt").write_text("", encoding = "utf-8")
    built = {}
    monkeypatch.setattr(
        tv,
        "_venv_dir_is_valid_and_undamaged",
        lambda d, packages, *a, **k: built.get(str(d)) == len(packages),
    )
    installed = []
    monkeypatch.setattr(tv, "_install_to_dir", lambda pkg, target: installed.append(pkg) and False)
    monkeypatch.delenv("HF_HUB_OFFLINE", raising = False)
    siblings = lambda: sorted(
        p.name for p in tmp_path.iterdir() if p.name.startswith(".venv_t5_550.")
    )
    for value in ("1", "t", "Y", "true", "on"):
        monkeypatch.setenv("UV_OFFLINE", value)
        installed.clear()
        assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is False
        assert (root / "keep.txt").is_file()
        assert installed == [tv._VENV_T5_550_PACKAGES[0]]
        assert siblings() == []
    staged_into = []

    def warm_install(pkg, target):
        staged_into.append(target)
        built[target] = built.get(target, 0) + 1
        return True

    monkeypatch.setattr(tv, "_install_to_dir", warm_install)
    monkeypatch.setenv("UV_OFFLINE", "1")
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is True
    assert len(set(staged_into)) == 1
    assert set(staged_into) == {str(tmp_path / f".venv_t5_550.offline-staging-{tv.os.getpid()}")}
    assert not (root / "keep.txt").exists()
    assert (root / tv._STUDIO_OWNED_MARKER).is_file()
    assert siblings() == []
    (root / "keep.txt").write_text("", encoding = "utf-8")
    built.clear()
    monkeypatch.setattr(tv, "_install_to_dir", lambda pkg, target: True)
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is False
    assert (root / "keep.txt").is_file()
    assert siblings() == []
    monkeypatch.setattr(tv, "_venv_dir_is_valid_and_undamaged", lambda *a, **k: False)
    root.mkdir(exist_ok = True)
    (root / "keep.txt").write_text("", encoding = "utf-8")
    installed.clear()
    monkeypatch.setattr(tv, "_install_to_dir", lambda pkg, target: installed.append(pkg) or True)
    # HF offline switches disable the Hub, not the package index; a damaged tier still rebuilds.
    monkeypatch.setenv("UV_OFFLINE", "0")
    monkeypatch.setenv("HF_HUB_OFFLINE", "1")
    assert tv._runtime_repair_is_offline() is False
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is True
    assert installed == list(tv._VENV_T5_550_PACKAGES)


def test_an_empty_directory_is_still_built_offline_from_the_cache(tmp_path, monkeypatch):
    """The offline rule protects only a tree that may still serve: staging dirs and first installs
    are attempted, since uv installs from a warm cache offline; pip fallback stays out."""
    root = tmp_path / ".venv_t5_latest.staging"
    root.mkdir()
    monkeypatch.setattr(tv, "_venv_dir_is_valid_and_undamaged", lambda *a, **k: False)
    installed = []
    monkeypatch.setattr(tv, "_install_to_dir", lambda pkg, target: installed.append(pkg) or True)
    monkeypatch.setenv("UV_OFFLINE", "1")
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "latest staging") is True
    assert installed == list(tv._VENV_T5_550_PACKAGES)
    installed.clear()
    assert tv._ensure_venv_dir(str(tmp_path / "fresh"), tv._VENV_T5_550_PACKAGES, "fresh") is True
    assert installed == list(tv._VENV_T5_550_PACKAGES)


def test_the_pip_fallback_stays_out_offline(tmp_path, monkeypatch):
    calls = []

    class _Result:
        returncode = 1
        stdout = "no cached wheel"

    def fake_run(cmd, **kwargs):
        # The guard asks pip for its configuration first; only installs are counted.
        if list(cmd[-2:]) == ["config", "list"]:
            return _Result()
        calls.append(list(cmd))
        return _Result()

    monkeypatch.setattr(tv.shutil, "which", lambda name: "/usr/bin/uv" if name == "uv" else None)
    monkeypatch.setattr(tv.subprocess, "run", fake_run)
    monkeypatch.setenv("UV_OFFLINE", "1")
    monkeypatch.delenv("PIP_NO_INDEX", raising = False)
    assert tv._install_to_dir("tiktoken", str(tmp_path)) is False
    assert len(calls) == 1 and calls[0][0] == "uv"
    calls.clear()
    monkeypatch.setattr(tv.shutil, "which", lambda name: None)
    assert tv._install_to_dir("tiktoken", str(tmp_path)) is False
    assert calls == []
    monkeypatch.setattr(tv.shutil, "which", lambda name: "/usr/bin/uv" if name == "uv" else None)
    monkeypatch.setenv("UV_OFFLINE", "0")
    calls.clear()
    assert tv._install_to_dir("tiktoken", str(tmp_path)) is False
    assert [c[0] for c in calls] == ["uv", tv.sys.executable]


def test_an_unreadable_sidecar_counts_as_content(tmp_path, monkeypatch):
    """A listing that fails with anything but "not there" cannot say the tree is empty,
    and the path taken for "empty" begins with deleting it."""
    root = tmp_path / ".venv_t5_550"
    root.mkdir()
    (root / "keep.txt").write_text("", encoding = "utf-8")
    assert tv._sidecar_has_content(str(tmp_path / "absent")) is False
    real_listdir = tv.os.listdir

    def denied(path):
        if str(path) == str(root):
            raise PermissionError(13, "Permission denied", str(path))
        return real_listdir(path)

    monkeypatch.setattr(tv.os, "listdir", denied)
    assert tv._sidecar_has_content(str(root)) is True
    monkeypatch.setattr(tv, "_venv_dir_is_valid_and_undamaged", lambda *a, **k: False)
    monkeypatch.setattr(tv, "_install_to_dir", lambda pkg, target: False)
    monkeypatch.setenv("UV_OFFLINE", "1")
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is False
    assert (root / "keep.txt").is_file()


def test_a_sibling_that_vanishes_while_sorting_does_not_abort_the_repair(tmp_path, monkeypatch):
    """A sibling vanishing between listing and mtime read must not abort _ensure_venv_dir."""
    root = tmp_path / ".venv_t5_550"
    ghost = tmp_path / ".venv_t5_550.offline-old-1"
    ghost.mkdir()
    (ghost / tv._STUDIO_OWNED_MARKER).write_text("", encoding = "utf-8")
    real_getmtime = tv.os.path.getmtime

    def vanishing(path):
        if str(path) == str(ghost):
            import shutil as _shutil
            _shutil.rmtree(ghost, ignore_errors = True)
            raise FileNotFoundError(2, "No such file or directory", str(path))
        return real_getmtime(path)

    monkeypatch.setattr(tv.os.path, "getmtime", vanishing)
    assert tv._sidecar_siblings(str(root), tv._OFFLINE_RETIRED_SUFFIX) == [str(ghost)]


def test_a_sidecar_stranded_by_an_interrupted_swap_is_restored_first(tmp_path, monkeypatch):
    """Killed between the swap's two renames, the live path is empty and the tree sits under the
    retired name; the next call restores it before deciding, not as a first install."""
    root = tmp_path / ".venv_t5_550"
    retired = tmp_path / ".venv_t5_550.offline-old-4242"
    retired.mkdir()
    (retired / "keep.txt").write_text("", encoding = "utf-8")
    (retired / tv._STUDIO_OWNED_MARKER).write_text("", encoding = "utf-8")
    monkeypatch.setattr(
        tv, "_venv_dir_is_valid_and_undamaged", lambda d, *a, **k: (Path(d) / "keep.txt").is_file()
    )
    monkeypatch.setattr(tv, "_top_up_optional_packages", lambda *a, **k: True)
    installed = []
    monkeypatch.setattr(tv, "_install_to_dir", lambda pkg, target: installed.append(pkg) and False)
    monkeypatch.setenv("UV_OFFLINE", "1")
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is True
    assert (root / "keep.txt").is_file()
    assert not retired.exists()
    assert installed == []
    leftover = tmp_path / ".venv_t5_550.offline-old-99"
    leftover.mkdir()
    (leftover / "x").write_text("", encoding = "utf-8")
    (leftover / tv._STUDIO_OWNED_MARKER).write_text("", encoding = "utf-8")
    # A retired copy is removed only if this code made it, under exactly its name.
    users = tmp_path / ".venv_t5_550.offline-old-backup"
    users.mkdir()
    (users / "precious").write_text("", encoding = "utf-8")
    unowned = tmp_path / ".venv_t5_550.offline-old-7"
    unowned.mkdir()
    (unowned / "precious").write_text("", encoding = "utf-8")
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is True
    assert (root / "keep.txt").is_file()
    assert not leftover.exists()
    assert (users / "precious").is_file() and (unowned / "precious").is_file()
    import shutil as _shutil

    _shutil.rmtree(root)
    monkeypatch.setattr(tv, "_repair_offline_beside", lambda *a, **k: False)
    assert tv._recover_retired_sidecar(str(root)) is None
    assert not root.exists()
    assert (users / "precious").is_file() and (unowned / "precious").is_file()


def test_a_rebuild_takes_the_tiers_lock_and_keeps_a_tree_finished_under_it(tmp_path, monkeypatch):
    """Two workers repairing one tier: the second waits on the tier's lock and, once it
    holds it, finds the first one's finished tree and keeps it rather than wiping it."""
    root = tmp_path / ".venv_t5_550"
    root.mkdir()
    (root / "half").write_text("", encoding = "utf-8")
    answers = iter([False, True])
    monkeypatch.setattr(tv, "_venv_dir_is_valid_and_undamaged", lambda *a, **k: next(answers))
    monkeypatch.setattr(tv, "_top_up_optional_packages", lambda *a, **k: True)
    monkeypatch.delenv("UV_OFFLINE", raising = False)
    monkeypatch.setattr(tv, "_env_offline", lambda: False)
    monkeypatch.setattr(tv, "_runtime_repair_is_offline", lambda: False)
    installed = []
    monkeypatch.setattr(tv, "_install_to_dir", lambda pkg, target: installed.append(pkg) or True)
    locked = []
    real_lock = tv._file_lock

    @contextlib.contextmanager
    def recording_lock(path, wait):
        locked.append(path)
        with real_lock(path, wait) as held:
            yield held

    monkeypatch.setattr(tv, "_file_lock", recording_lock)
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is True
    assert installed == [] and (root / "half").is_file()
    assert locked == [tv._rebuild_lock_path(str(root))]
    monkeypatch.setattr(tv, "_venv_dir_is_valid_and_undamaged", lambda *a, **k: False)
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is True
    assert installed == list(tv._VENV_T5_550_PACKAGES)
    # Lock not obtained: no unguarded rebuild, this activation goes without the sidecar.
    installed.clear()
    (root / "half").write_text("", encoding = "utf-8")

    @contextlib.contextmanager
    def not_held(path, wait):
        yield False

    monkeypatch.setattr(tv, "_file_lock", not_held)
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is False
    assert installed == [] and (root / "half").is_file()


def test_the_offline_repair_runs_under_the_tiers_lock_too(tmp_path, monkeypatch):
    """Two workers repairing one tier offline would race the two-rename swap, so the offline repair
    takes the same tier lock as the online rebuild and defers if not obtained."""
    root = tmp_path / ".venv_t5_550"
    root.mkdir()
    (root / "keep.txt").write_text("", encoding = "utf-8")
    monkeypatch.setattr(tv, "_venv_dir_is_valid_and_undamaged", lambda *a, **k: False)
    monkeypatch.setenv("UV_OFFLINE", "1")
    repaired = []
    monkeypatch.setattr(tv, "_repair_offline_beside", lambda d, p, l: repaired.append(d) or True)
    locked = []
    real_lock = tv._file_lock

    @contextlib.contextmanager
    def recording_lock(path, wait):
        locked.append(path)
        with real_lock(path, wait) as held:
            yield held

    monkeypatch.setattr(tv, "_file_lock", recording_lock)
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is True
    assert repaired == [str(root)] and locked == [tv._rebuild_lock_path(str(root))]

    @contextlib.contextmanager
    def not_held(path, wait):
        yield False

    monkeypatch.setattr(tv, "_file_lock", not_held)
    repaired.clear()
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is False
    assert repaired == [] and (root / "keep.txt").is_file()


def test_a_wheelhouse_pip_is_allowed_offline(tmp_path, monkeypatch):
    """PIP_NO_INDEX with PIP_FIND_LINKS is a local wheelhouse: an air-gapped install got
    its sidecars that way before UV_OFFLINE was honoured, and the offline guard must
    not turn that pip away."""
    monkeypatch.setenv("UV_OFFLINE", "1")
    monkeypatch.setattr(tv, "_uv_available", lambda: False, raising = False)
    calls = []

    class _Done:
        returncode = 0

    monkeypatch.setattr(tv.subprocess, "run", lambda cmd, **k: calls.append(cmd) or _Done())
    monkeypatch.setattr(tv, "_pip_effective_settings", lambda: None)
    monkeypatch.delenv("PIP_NO_INDEX", raising = False)
    monkeypatch.delenv("PIP_FIND_LINKS", raising = False)
    assert tv._pip_is_configured_offline() is False
    monkeypatch.setenv("PIP_NO_INDEX", "1")
    assert tv._pip_is_configured_offline() is False
    monkeypatch.setenv("PIP_FIND_LINKS", str(tmp_path))
    assert tv._pip_is_configured_offline() is True
    for spelling in ("t", "y", "yes", "on", "TRUE"):
        monkeypatch.setenv("PIP_NO_INDEX", spelling)
        assert tv._pip_is_configured_offline() is True, spelling
    monkeypatch.setenv("PIP_NO_INDEX", "0")
    assert tv._pip_is_configured_offline() is False
    monkeypatch.setenv("PIP_NO_INDEX", "1")
    monkeypatch.setenv("PIP_FIND_LINKS", f"{tmp_path} file://{tmp_path}")
    assert tv._pip_is_configured_offline() is True
    # --find-links takes URLs too, and one of those is the network.
    monkeypatch.setenv("PIP_FIND_LINKS", f"{tmp_path} https://wheels.example/simple")
    assert tv._pip_is_configured_offline() is False
    monkeypatch.setenv("PIP_FIND_LINKS", str(tmp_path / "missing"))
    assert tv._pip_is_configured_offline() is False
    # A FILE is parsed for links, and those may be URLs: only a directory is local.
    index = tmp_path / "index.html"
    index.write_text('<a href="https://wheels.example/tiktoken.whl">x</a>', encoding = "utf-8")
    monkeypatch.setenv("PIP_FIND_LINKS", str(index))
    assert tv._pip_is_configured_offline() is False
    monkeypatch.setenv("PIP_FIND_LINKS", f"file://{index}")
    assert tv._pip_is_configured_offline() is False
    # A UNC share: file://server/share keeps its host, which is part of the path.
    seen = []

    def isdir(path):
        seen.append(path)
        return True

    monkeypatch.setattr(tv.os.path, "isdir", isdir)
    monkeypatch.setenv("PIP_FIND_LINKS", "file://wheelserver/share/wheels")
    assert tv._pip_is_configured_offline() is True
    assert seen and "wheelserver" in seen[-1] and "share" in seen[-1]


def test_the_wheelhouse_is_read_from_pip_config_files_too(tmp_path, monkeypatch):
    """An air-gapped host sets no-index and find-links in pip.conf as often as in the environment,
    so the guard reads pip's effective config (environment over [install] over [global])."""
    monkeypatch.delenv("PIP_NO_INDEX", raising = False)
    monkeypatch.delenv("PIP_FIND_LINKS", raising = False)
    settings = {"global.no-index": "true", "global.find-links": f"\n{tmp_path}"}
    monkeypatch.setattr(tv, "_pip_effective_settings", lambda: dict(settings))
    assert tv._pip_is_configured_offline() is True
    # [install] overrides [global] ...
    settings["install.no-index"] = "false"
    assert tv._pip_is_configured_offline() is False
    # ... and the environment overrides both.
    settings[":env:.no-index"] = "1"
    assert tv._pip_is_configured_offline() is True
    settings[":env:.find-links"] = "https://wheels.example/simple"
    assert tv._pip_is_configured_offline() is False
    del settings[":env:.find-links"]
    settings["global.find-links"] = f"{tmp_path} {tmp_path / 'index.html'}"
    (tmp_path / "index.html").write_text("<a href='https://x/y.whl'>y</a>", encoding = "utf-8")
    assert tv._pip_is_configured_offline() is False


def test_pip_config_list_is_parsed_as_pip_prints_it(tmp_path, monkeypatch):
    """`pip config list` prints repr'd values (a multi-line find-links comes out with
    literal \\n escapes); the parser gives back what pip will read."""
    monkeypatch.delenv("PIP_NO_INDEX", raising = False)
    monkeypatch.delenv("PIP_FIND_LINKS", raising = False)
    conf = tmp_path / "pip.conf"
    conf.write_text(
        f"[global]\nno-index = true\nfind-links =\n    {tmp_path}\n    {tmp_path}\n",
        encoding = "utf-8",
    )
    monkeypatch.setenv("PIP_CONFIG_FILE", str(conf))
    settings = tv._pip_effective_settings()
    if settings is None:
        pytest.skip("pip is not importable by this interpreter")
    assert settings.get("global.no-index") == "true"
    assert settings.get("global.find-links", "").split() == [str(tmp_path), str(tmp_path)]
    assert tv._pip_is_configured_offline() is True
    monkeypatch.setenv("PIP_NO_INDEX", "0")
    assert tv._pip_is_configured_offline() is False
    source = open(tv.__file__, encoding = "utf-8").read()
    assert "if _runtime_repair_is_offline() and not _pip_is_configured_offline():" in source


def test_a_failed_install_keeps_a_tree_another_process_completed_meanwhile(tmp_path, monkeypatch):
    """A failed install's late cleanup must not delete a tree another process just completed."""
    root = tmp_path / ".venv_t5_550"
    root.mkdir()
    verdicts = iter([False, True])
    monkeypatch.setattr(tv, "_venv_dir_is_valid_and_undamaged", lambda *a, **k: next(verdicts))
    monkeypatch.setattr(tv, "_install_to_dir", lambda pkg, target: False)
    monkeypatch.delenv("UV_OFFLINE", raising = False)
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is True
    assert root.is_dir()


def test_a_failed_first_install_leaves_nothing_the_offline_guard_would_keep(tmp_path, monkeypatch):
    """The owned marker is written before the first package, so a failed first install must not
    leave a marker-only or partial tree the offline guard would keep."""
    root = tmp_path / ".venv_t5_550"
    monkeypatch.setattr(tv, "_venv_dir_is_valid_and_undamaged", lambda *a, **k: False)
    monkeypatch.setattr(tv, "_install_to_dir", lambda pkg, target: False)
    monkeypatch.setenv("UV_OFFLINE", "1")
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is False
    assert not root.exists()
    installed = []
    monkeypatch.setattr(tv, "_install_to_dir", lambda pkg, target: installed.append(pkg) or True)
    assert tv._ensure_venv_dir(str(root), tv._VENV_T5_550_PACKAGES, "test sidecar") is True
    assert installed == list(tv._VENV_T5_550_PACKAGES)
    root2 = tmp_path / "marker-only"
    root2.mkdir()
    (root2 / tv._STUDIO_OWNED_MARKER).write_text("", encoding = "utf-8")
    assert tv._sidecar_has_content(str(root2)) is False
    (root2 / "keep.txt").write_text("", encoding = "utf-8")
    assert tv._sidecar_has_content(str(root2)) is True


def test_an_unlockable_filesystem_is_not_waited_out(tmp_path, monkeypatch) -> None:
    """An unlockable filesystem must fail at once, not sleep out the 120 second bound."""
    import errno
    import fcntl
    import time as _time

    import threading

    root = tmp_path / "sidecar"
    root.mkdir()
    attempts = []
    real_flock = fcntl.flock
    real_sleep = _time.sleep
    main_thread = threading.current_thread()

    # Both patches are process-wide; stray background threads from earlier tests get the real calls.
    def unsupported(fd, op):
        if threading.current_thread() is not main_thread:
            return real_flock(fd, op)
        attempts.append(op)
        raise OSError(errno.ENOTSUP, "locking not supported")

    slept = []

    def record(seconds):
        if threading.current_thread() is main_thread:
            slept.append(seconds)
        else:
            real_sleep(seconds)

    monkeypatch.setattr(fcntl, "flock", unsupported)
    monkeypatch.setattr(_time, "sleep", record)
    monkeypatch.setattr(tv.time, "sleep", record)
    with tv._optional_top_up_lock(str(root)) as held:
        assert held is False
    assert len(attempts) == 1, f"asked {len(attempts)} times for an answer that cannot change"
    assert not slept, f"waited on a filesystem that cannot lock: {slept}"


def test_an_interpreter_without_fcntl_does_not_break_activation(tmp_path, monkeypatch) -> None:
    """No fcntl and no msvcrt means no lock, which reads as someone else's turn, not a crash."""
    import builtins

    root = tmp_path / "sidecar"
    root.mkdir()
    real_import = builtins.__import__

    def no_fcntl(name, *args, **kwargs):
        if name in ("fcntl", "msvcrt"):
            raise ImportError(f"no {name} here")
        return real_import(name, *args, **kwargs)

    monkeypatch.setattr(builtins, "__import__", no_fcntl)
    with tv._optional_top_up_lock(str(root)) as held:
        assert held is False


def test_a_close_that_fails_does_not_escape(tmp_path) -> None:
    class _Handle:
        closed = False

        def close(self):
            _Handle.closed = True
            raise OSError("close refused")

    tv._close_quietly(_Handle())
    assert _Handle.closed
    tv._close_quietly(None)