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.

52.1 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

"""Per-port PID files so unsloth studio stop finds every server; needs the Unsloth venv for run.py."""

from __future__ import annotations

import contextlib
import errno
import os
import socket
import threading
import time
import sys
from pathlib import Path
from types import SimpleNamespace

import pytest


def _shared_setup_1(monkeypatch):
    events = []
    monkeypatch.setattr(
        cache_cleanup, "clear_unsloth_compiled_cache", lambda *a, **k: events.append("clear")
    )
    return events


_BACKEND = Path(__file__).resolve().parents[1]
if str(_BACKEND) not in sys.path:
    sys.path.insert(0, str(_BACKEND))

import run  # noqa: E402
from utils import cache_cleanup  # noqa: E402

# Captured before the autouse fixture stubs them, for the tests that exercise them.
_REAL_IS_STUDIO_BACKEND = run._pid_is_studio_backend
_REAL_PID_ALIVE = run._pid_alive


@pytest.fixture(autouse = True)
def isolated_root(tmp_path, monkeypatch):
    monkeypatch.setattr(run, "_studio_root", lambda: tmp_path)
    monkeypatch.setattr(run, "_PID_FILE", tmp_path / "studio.pid")
    monkeypatch.setattr(run, "_OWN_PID_FILE", None)
    monkeypatch.setattr(run, "_pid_alive", lambda pid: True)
    monkeypatch.setattr(run, "_pid_is_studio_backend", lambda pid, created_times = (): True)
    # Redirect the lock dir to tmp_path like everything else this file touches.
    monkeypatch.setattr(cache_cleanup, "cache_coordination_dir", lambda: tmp_path)
    monkeypatch.setattr(run, "_OWN_STARTUP_MARKERS", [])
    yield


def _files(tmp_path):
    return sorted(p.name for p in tmp_path.glob("studio-*.pid"))


def _pid_of(path):
    return path.read_text(encoding = "utf-8").splitlines()[0]


def test_write_pid_file_records_port_and_pid(tmp_path):
    run._write_pid_file(8901)

    assert _files(tmp_path) == [f"studio-8901-{os.getpid()}.pid"]
    assert _pid_of(tmp_path / f"studio-8901-{os.getpid()}.pid") == str(os.getpid())


def test_write_pid_file_records_the_start_time(tmp_path):
    # Pins the record to this process, so a reused PID isn't mistaken for it.
    pytest.importorskip("psutil")
    run._write_pid_file(8901)

    record = run._read_pid_record(tmp_path / f"studio-8901-{os.getpid()}.pid")

    assert record[0] == os.getpid()
    lines = (tmp_path / f"studio-8901-{os.getpid()}.pid").read_text().splitlines()
    assert float(lines[1]) == pytest.approx(run._process_create_time(os.getpid()))
    assert _REAL_IS_STUDIO_BACKEND(os.getpid(), [record[1]])


def test_write_pid_file_keeps_the_legacy_file_a_bare_pid(tmp_path):
    # An older CLI's `stop` reads studio.pid and expects only digits.
    run._write_pid_file(8901)

    assert (tmp_path / "studio.pid").read_text(encoding = "utf-8") == str(os.getpid())


def test_second_port_does_not_clobber_the_first(tmp_path):
    (tmp_path / "studio-8901-8550.pid").write_text("8550", encoding = "utf-8")

    run._write_pid_file(8902)

    assert _pid_of(tmp_path / "studio-8901-8550.pid") == "8550"
    assert (tmp_path / f"studio-8902-{os.getpid()}.pid").exists()


def test_same_port_on_two_binds_does_not_clobber(tmp_path):
    # 127.0.0.1:8888 and ::1:8888 can both listen; one file per port would lose one.
    (tmp_path / "studio-8888-8550.pid").write_text("8550", encoding = "utf-8")

    run._write_pid_file(8888)

    assert len(_files(tmp_path)) == 2


def test_remove_pid_file_only_removes_our_own(tmp_path, monkeypatch):
    run._write_pid_file(8901)
    (tmp_path / "studio-8902-8600.pid").write_text("8600", encoding = "utf-8")
    monkeypatch.setattr(run, "_pid_alive", lambda pid: pid == os.getpid())

    run._remove_pid_file()

    assert _files(tmp_path) == ["studio-8902-8600.pid"]
    assert not (tmp_path / "studio.pid").exists()


def test_the_legacy_pointer_moves_to_a_live_sibling(tmp_path):
    # studio.pid belongs to one server; older CLIs read only it, so exit must not delete it.
    run._write_pid_file(8901)
    (tmp_path / "studio-8902-8600.pid").write_text("8600", encoding = "utf-8")

    run._remove_pid_file()

    assert (tmp_path / "studio.pid").read_text(encoding = "utf-8").strip() == "8600"


def test_the_legacy_pointer_is_not_handed_to_a_dead_sibling(tmp_path, monkeypatch):
    run._write_pid_file(8901)
    (tmp_path / "studio-8902-8600.pid").write_text("8600", encoding = "utf-8")
    monkeypatch.setattr(run, "_pid_is_studio_backend", lambda pid, created_times = (): False)

    run._remove_pid_file()

    assert not (tmp_path / "studio.pid").exists()


def test_remove_pid_file_leaves_a_reused_entry_alone(tmp_path):
    run._write_pid_file(8901)
    own = tmp_path / f"studio-8901-{os.getpid()}.pid"
    own.write_text("999999", encoding = "utf-8")

    run._remove_pid_file()

    assert own.read_text(encoding = "utf-8") == "999999"


def test_windows_liveness_does_not_call_every_pid_alive(monkeypatch):
    # os.kill(pid, 0) errors for every pid on Windows, so tasklist is the liveness check.
    import subprocess

    monkeypatch.setattr(run, "_pid_alive", _REAL_PID_ALIVE)
    monkeypatch.setitem(sys.modules, "psutil", None)
    monkeypatch.setattr(sys, "platform", "win32")
    monkeypatch.setattr(
        subprocess,
        "run",
        lambda *a, **k: SimpleNamespace(stdout = '"python.exe","8550",...', returncode = 0),
    )

    assert run._pid_alive(8550) is True
    assert run._pid_alive(9999) is False


def test_windows_liveness_keeps_the_record_when_tasklist_fails(monkeypatch):
    # Unconfirmed must mean keep, matching the CLI's _pid_alive.
    import subprocess

    def _boom(*a, **k):
        raise OSError("tasklist missing")

    monkeypatch.setattr(run, "_pid_alive", _REAL_PID_ALIVE)
    monkeypatch.setitem(sys.modules, "psutil", None)
    monkeypatch.setattr(sys, "platform", "win32")
    monkeypatch.setattr(subprocess, "run", _boom)

    assert run._pid_alive(8550) is True


def test_read_pid_record_parses_pid_time_and_address(tmp_path):
    (tmp_path / "r.pid").write_text("8550\n111.5\n127.0.0.1", encoding = "utf-8")

    assert run._read_pid_record(tmp_path / "r.pid") == (8550, 111.5, "127.0.0.1")


def test_read_pid_record_tolerates_a_bare_pid(tmp_path):
    (tmp_path / "r.pid").write_text("8550", encoding = "utf-8")

    assert run._read_pid_record(tmp_path / "r.pid") == (8550, None, None)


def test_read_pid_record_rejects_pid_zero_and_init(tmp_path):
    # kill(0) signals our whole process group.
    (tmp_path / "zero.pid").write_text("0", encoding = "utf-8")
    (tmp_path / "init.pid").write_text("1", encoding = "utf-8")

    assert run._read_pid_record(tmp_path / "zero.pid") is None
    assert run._read_pid_record(tmp_path / "init.pid") is None


def test_read_pid_record_rejects_a_corrupt_file(tmp_path):
    (tmp_path / "r.pid").write_text("not-a-pid", encoding = "utf-8")

    assert run._read_pid_record(tmp_path / "r.pid") is None


def test_graceful_shutdown_drops_the_record_last(monkeypatch):
    # Drop the record last: cleanup takes seconds, and a retried stop must still find it.
    order = []
    monkeypatch.setattr(run, "_remove_pid_file", lambda: order.append("remove_record"))

    class _Server:
        def __setattr__(self, name, value):
            order.append("release_socket")

    run._graceful_shutdown(_Server())

    assert order == ["release_socket", "remove_record"]


def test_own_studio_on_port_is_found_without_psutil(tmp_path, monkeypatch):
    # Without psutil, detection must use our own records or a duplicate starts silently.
    monkeypatch.setitem(sys.modules, "psutil", None)
    (tmp_path / "studio-8901-8550.pid").write_text("8550\n\n127.0.0.1", encoding = "utf-8")

    assert run._own_studio_on_port(8901, "127.0.0.1") == 8550


def test_no_record_for_the_port_means_no_own_studio(tmp_path):
    # jupyter-lab on 8888 must keep the fallback, not abort the launch.
    (tmp_path / "studio-8901-8550.pid").write_text("8550", encoding = "utf-8")

    assert run._own_studio_on_port(8888, "127.0.0.1") is None


def test_own_studio_on_port_prunes_a_dead_record(tmp_path, monkeypatch):
    monkeypatch.setattr(run, "_pid_alive", lambda pid: False)
    (tmp_path / "studio-8901-8550.pid").write_text("8550", encoding = "utf-8")

    assert run._own_studio_on_port(8901, "127.0.0.1") is None
    assert not (tmp_path / "studio-8901-8550.pid").exists()


def test_a_reused_pid_is_not_treated_as_our_studio(tmp_path, monkeypatch):
    monkeypatch.setattr(run, "_pid_is_studio_backend", lambda pid, created_times = (): False)
    (tmp_path / "studio-8901-8550.pid").write_text("8550", encoding = "utf-8")

    assert run._own_studio_on_port(8901, "127.0.0.1") is None


def test_an_unverifiable_record_still_blocks_a_duplicate(tmp_path, monkeypatch):
    # Can't tell: refusing with a clear message beats a silent second instance.
    monkeypatch.setattr(run, "_pid_is_studio_backend", lambda pid, created_times = (): True)
    (tmp_path / "studio-8901-8550.pid").write_text("8550", encoding = "utf-8")

    assert run._own_studio_on_port(8901, "127.0.0.1") == 8550


def test_start_time_mismatch_rejects_a_reused_pid(monkeypatch):
    monkeypatch.setattr(run, "_pid_is_studio_backend", _REAL_IS_STUDIO_BACKEND)
    monkeypatch.setattr(run, "_process_create_time", lambda pid: 999.0)

    assert run._pid_is_studio_backend(8550, [111.5]) is False
    assert run._pid_is_studio_backend(8550, [999.0]) is True


def test_a_stale_record_does_not_veto_a_live_server_sharing_the_pid(monkeypatch):
    # Crash leaves studio-8888-1234.pid, the OS reuses 1234 for a new server on
    # another port. Keeping only the first timestamp would reject the live one.
    monkeypatch.setattr(run, "_pid_is_studio_backend", _REAL_IS_STUDIO_BACKEND)
    monkeypatch.setattr(run, "_process_create_time", lambda pid: 999.0)

    assert run._pid_is_studio_backend(1234, [111.5, 999.0]) is True
    assert run._pid_is_studio_backend(1234, [111.5, 222.5]) is False


def test_a_stale_record_on_another_port_does_not_hide_a_live_server(tmp_path, monkeypatch):
    monkeypatch.setattr(run, "_pid_is_studio_backend", _REAL_IS_STUDIO_BACKEND)
    monkeypatch.setattr(run, "_process_create_time", lambda pid: 999.0)
    (tmp_path / "studio-8888-1234.pid").write_text("1234\n111.5\n", encoding = "utf-8")
    (tmp_path / "studio-9000-1234.pid").write_text("1234\n999.0\n", encoding = "utf-8")

    assert run._own_studio_on_port(8888, "127.0.0.1") is None
    assert run._own_studio_on_port(9000, "127.0.0.1") == 1234


def test_a_start_time_is_the_only_thing_that_disproves_a_record(monkeypatch):
    monkeypatch.setattr(run, "_pid_is_studio_backend", _REAL_IS_STUDIO_BACKEND)
    monkeypatch.setattr(run, "_process_create_time", lambda pid: 999.0)

    assert run._pid_is_studio_backend(8550, [999.0]) is True
    assert run._pid_is_studio_backend(8550, [111.5]) is False


def test_a_bare_run_py_command_line_is_not_rejected(monkeypatch):
    monkeypatch.setattr(run, "_pid_is_studio_backend", _REAL_IS_STUDIO_BACKEND)

    class _FakeProcess:
        def __init__(self, pid):
            self.pid = pid

        def cmdline(self):
            return ["python", "run.py", "--port", "8901"]

        def create_time(self):
            return 111.5

    monkeypatch.setitem(sys.modules, "psutil", SimpleNamespace(Process = _FakeProcess))

    assert run._pid_is_studio_backend(8550) is True


def test_an_untimed_legacy_record_is_trusted(monkeypatch):
    # `python run.py --port 8901` has no telltale argv, so guessing from the
    # command line rejected real servers. Only a start time can disprove one.
    monkeypatch.setattr(run, "_pid_is_studio_backend", _REAL_IS_STUDIO_BACKEND)
    monkeypatch.setattr(run, "_process_create_time", lambda pid: 999.0)

    assert run._pid_is_studio_backend(8550) is True
    assert run._pid_is_studio_backend(8550, [None]) is True


def test_the_untimed_legacy_record_does_not_cancel_a_timed_one(monkeypatch):
    # An untimed record carries no information, so it must not overrule a start time.
    monkeypatch.setattr(run, "_pid_is_studio_backend", _REAL_IS_STUDIO_BACKEND)
    monkeypatch.setattr(run, "_process_create_time", lambda pid: 999.0)

    assert run._pid_is_studio_backend(8550, [111.5, None]) is False
    assert run._pid_is_studio_backend(8550, [111.5, 999.0]) is True


def test_a_legacy_server_on_the_port_is_recognised(tmp_path, monkeypatch):
    # Pre-upgrade servers wrote only studio.pid, so skipping it strands and overwrites it.
    monkeypatch.setattr(run, "_get_pid_on_port", lambda p: (8550, "python"))
    (tmp_path / "studio.pid").write_text("8550", encoding = "utf-8")

    assert run._own_studio_on_port(8901, "127.0.0.1") == 8550


def test_a_legacy_record_for_a_different_listener_falls_back(tmp_path, monkeypatch):
    monkeypatch.setattr(run, "_get_pid_on_port", lambda p: (117, "jupyter-lab"))
    (tmp_path / "studio.pid").write_text("8550", encoding = "utf-8")

    assert run._own_studio_on_port(8901, "127.0.0.1") is None


def test_an_unknowable_listener_treats_the_legacy_record_as_ours(tmp_path, monkeypatch):
    # No psutil: _get_pid_on_port can't say. Refusing beats a silent duplicate.
    monkeypatch.setattr(run, "_get_pid_on_port", lambda p: None)
    (tmp_path / "studio.pid").write_text("8550", encoding = "utf-8")

    assert run._own_studio_on_port(8901, "127.0.0.1") == 8550


def test_a_dead_legacy_record_falls_back(tmp_path, monkeypatch):
    monkeypatch.setattr(run, "_pid_alive", lambda pid: False)
    monkeypatch.setattr(run, "_get_pid_on_port", lambda p: None)
    (tmp_path / "studio.pid").write_text("8550", encoding = "utf-8")

    assert run._own_studio_on_port(8901, "127.0.0.1") is None


def test_a_stale_per_port_record_does_not_mask_a_legacy_server(tmp_path, monkeypatch):
    # A stale record for a reused PID must not count as the port already known.
    monkeypatch.setattr(run, "_pid_is_studio_backend", _REAL_IS_STUDIO_BACKEND)
    monkeypatch.setattr(run, "_process_create_time", lambda pid: 999.0)
    monkeypatch.setattr(run, "_get_pid_on_port", lambda p: (8550, "python"))
    (tmp_path / "studio-8901-8550.pid").write_text("8550\n111.5\n127.0.0.1", encoding = "utf-8")
    (tmp_path / "studio.pid").write_text("8550", encoding = "utf-8")

    assert run._own_studio_on_port(8901, "127.0.0.1") == 8550


def test_a_current_server_elsewhere_does_not_block_a_foreign_port(tmp_path, monkeypatch):
    # Without psutil, the legacy check cannot see listeners, so it must not claim port 8888.
    monkeypatch.setattr(run, "_get_pid_on_port", lambda p: None)
    (tmp_path / "studio-8901-5000.pid").write_text("5000\n\n127.0.0.1", encoding = "utf-8")
    (tmp_path / "studio.pid").write_text("5000", encoding = "utf-8")

    assert run._own_studio_on_port(8888, "127.0.0.1") is None


def test_a_per_port_record_is_preferred_over_the_legacy_one(tmp_path, monkeypatch):
    monkeypatch.setattr(run, "_get_pid_on_port", lambda p: (8550, "python"))
    (tmp_path / "studio-8901-8600.pid").write_text("8600\n\n127.0.0.1", encoding = "utf-8")
    (tmp_path / "studio.pid").write_text("8550", encoding = "utf-8")

    assert run._own_studio_on_port(8901, "127.0.0.1") == 8600


def test_our_studio_on_another_bind_address_does_not_abort(tmp_path):
    # Our ::1:8889 server is no conflict for 127.0.0.1:8889; fall through to the next port.
    (tmp_path / "studio-8889-8550.pid").write_text("8550\n\n::1", encoding = "utf-8")

    assert run._own_studio_on_port(8889, "127.0.0.1") is None
    assert run._own_studio_on_port(8889, "::1") == 8550


def test_address_matching(tmp_path):
    assert run._addresses_collide("0.0.0.0", "127.0.0.1", 8889) is True
    assert run._addresses_collide("127.0.0.1", "0.0.0.0", 8889) is True
    assert run._addresses_collide("127.0.0.1", "127.0.0.1", 8889) is True
    assert run._addresses_collide("::1", "127.0.0.1", 8889) is False
    # An unrecorded address is unknown, so assume a conflict.
    assert run._addresses_collide(None, "127.0.0.1", 8889) is True


@pytest.mark.parametrize(
    "wildcard",
    ["0", "00", "0.0", "0.0.0", "::0", "0:0:0:0:0:0:0:0", "::ffff:0.0.0.0"],
)
def test_every_wildcard_alias_collides_with_a_specific_bind(wildcard):
    assert run._addresses_collide("127.0.0.1", wildcard, 8889) is True
    assert run._addresses_collide(wildcard, "127.0.0.1", 8889) is True


def test_a_hostname_resolves_the_same_way_the_bind_does(tmp_path):
    # localhost must resolve to the same addresses _is_port_free binds, or a duplicate starts.
    recorded = ",".join(sorted(run._bind_addresses("localhost", 8889)))

    assert run._addresses_collide(recorded, "localhost", 8889) is True


@pytest.mark.skipif(sys.platform != "win32", reason = "Windows socket semantics")
def test_windows_reuseaddr_listener_is_not_reported_as_a_free_port():
    # On Windows SO_REUSEADDR on the probe binds even while a server listens.
    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as listener:
        listener.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
        listener.bind(("127.0.0.1", 0))
        listener.listen()
        port = listener.getsockname()[1]

        assert run._is_port_free("127.0.0.1", port) is False


def test_a_loopback_bind_is_not_free_while_another_process_holds_the_wildcard():
    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as listener:
        listener.bind(("0.0.0.0", 0))
        listener.listen()
        port = listener.getsockname()[1]

        assert run._is_port_free("127.0.0.1", port) is False


@pytest.mark.skipif(sys.platform != "win32", reason = "Windows drops the SYN to a full backlog")
def test_a_wildcard_listener_with_a_full_backlog_is_not_a_free_port():
    # studio.txt alone does not install psutil, the only thing that tells this apart from a free port.
    pytest.importorskip("psutil")
    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as listener:
        listener.bind(("0.0.0.0", 0))
        listener.listen(0)
        port = listener.getsockname()[1]
        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as filler:
            filler.settimeout(2)
            filler.connect(("127.0.0.1", port))

            assert run._is_port_free("127.0.0.1", port) is False


@pytest.mark.parametrize(
    ("listener", "family", "address", "collides"),
    [
        ("0.0.0.0", socket.AF_INET, "127.0.0.1", True),
        ("127.0.0.1", socket.AF_INET, "127.0.0.1", True),
        ("192.168.1.5", socket.AF_INET, "127.0.0.1", False),
        ("::", socket.AF_INET6, "127.0.0.1", False),  # a v6-only wildcard shares the port with IPv4
        ("::", socket.AF_INET6, "::1", True),
    ],
)
def test_only_a_listener_of_the_same_family_takes_the_port(
    monkeypatch, listener, family, address, collides
):
    psutil = pytest.importorskip("psutil")
    row = SimpleNamespace(status = psutil.CONN_LISTEN, family = family, laddr = (listener, 8888))
    monkeypatch.setattr(psutil, "net_connections", lambda kind: [row])

    assert run._listener_collides(address, 8888) is collides


def test_a_timed_out_connect_is_settled_by_the_listener_table(monkeypatch):
    monkeypatch.setattr(run, "sys", SimpleNamespace(platform = "win32"))
    asked = []
    monkeypatch.setattr(
        run, "_listener_collides", lambda address, port: asked.append((address, port)) or True
    )

    class _ProbeSocket:
        def __init__(self, *_args):
            pass

        def setsockopt(self, *_args):
            pass

        def bind(self, _sockaddr):
            pass

        def settimeout(self, _timeout):
            pass

        def connect_ex(self, _sockaddr):
            return errno.EWOULDBLOCK

        def close(self):
            pass

        def __enter__(self):
            return self

        def __exit__(self, *_exc):
            pass

    monkeypatch.setattr(
        socket,
        "getaddrinfo",
        lambda *_args, **_kwargs: [
            (socket.AF_INET, socket.SOCK_STREAM, 6, "", ("127.0.0.1", 8888))
        ],
    )
    monkeypatch.setattr(socket, "socket", _ProbeSocket)

    assert run._is_port_free("127.0.0.1", 8888) is False
    assert asked == [("127.0.0.1", 8888)]


def test_a_free_loopback_port_is_reported_without_a_long_wait():
    # Windows waits out the whole connect timeout on a free port.
    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
        s.bind(("127.0.0.1", 0))
        port = s.getsockname()[1]

    start = time.monotonic()
    assert run._is_port_free("127.0.0.1", port) is True
    assert time.monotonic() - start < 0.75


def test_a_hostname_records_every_address_it_resolves_to(tmp_path):
    # localhost binds 127.0.0.1 and ::1, so record both or a later launch misses us.
    addrs = run._bind_addresses("localhost", 8889)
    recorded = ",".join(sorted(addrs))

    for literal in addrs:
        assert run._addresses_collide(recorded, literal, 8889) is True


@pytest.mark.parametrize("platform", ["win32", "linux"])
@pytest.mark.parametrize("occupied", [False, True])
def test_port_probe_checks_every_resolved_bind_address(monkeypatch, platform, occupied):
    monkeypatch.setattr(run, "sys", SimpleNamespace(platform = platform))
    bind_attempts = []
    connect_attempts = []
    sockets = []

    class _ProbeSocket:
        def __init__(self, family):
            self.family = family
            self.closed = False
            self.options = []
            sockets.append(self)

        def setsockopt(self, *args):
            self.options.append(args)

        def bind(self, sockaddr):
            bind_attempts.append((self.family, sockaddr))
            if occupied and self.family == socket.AF_INET6:
                raise OSError("address already in use")

        def settimeout(self, _timeout):
            pass

        def connect_ex(self, sockaddr):
            connect_attempts.append((self.family, sockaddr))
            return errno.ECONNREFUSED

        def close(self):
            self.closed = True

        def __enter__(self):
            return self

        def __exit__(self, *_exc):
            self.close()

    monkeypatch.setattr(
        socket,
        "getaddrinfo",
        lambda *_args, **_kwargs: [
            (socket.AF_INET, socket.SOCK_STREAM, 6, "", ("127.0.0.1", 8888)),
            (socket.AF_INET6, socket.SOCK_STREAM, 6, "", ("::1", 8888, 0, 0)),
        ],
    )
    monkeypatch.setattr(
        socket,
        "socket",
        lambda family, *_args: _ProbeSocket(family),
    )

    assert run._is_port_free("dual-stack.test", 8888) is (not occupied)
    assert bind_attempts == [
        (socket.AF_INET, ("127.0.0.1", 8888)),
        (socket.AF_INET6, ("::1", 8888, 0, 0)),
    ]
    assert connect_attempts == ([] if occupied else bind_attempts)
    assert all(probe.closed for probe in sockets)
    for probe in sockets[: len(bind_attempts)]:
        assert ((socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) in probe.options) is (
            platform != "win32"
        )
        if probe.family == socket.AF_INET6 and hasattr(socket, "IPV6_V6ONLY"):
            assert (socket.IPPROTO_IPV6, socket.IPV6_V6ONLY, 1) in probe.options


def test_a_multi_address_record_matches_either_literal(tmp_path):
    recorded = "127.0.0.1,::1"

    assert run._addresses_collide(recorded, "127.0.0.1", 8889) is True
    assert run._addresses_collide(recorded, "::1", 8889) is True
    assert run._addresses_collide("127.0.0.1", "::1", 8889) is False


def test_fallback_aborts_on_our_own_server_further_up_the_range(tmp_path, monkeypatch):
    # jupyter holds 8888, our server holds 8889: skipping to 8890 is the duplicate.
    (tmp_path / "studio-8889-8550.pid").write_text("8550\n\n127.0.0.1", encoding = "utf-8")
    monkeypatch.setattr(run, "_is_port_free", lambda host, p: p >= 8890)

    with pytest.raises(SystemExit) as excinfo:
        run._find_free_port("127.0.0.1", 8889, avoid_own_studio = True)

    assert excinfo.value.code == 1


def test_fallback_still_skips_foreign_processes(tmp_path, monkeypatch):
    monkeypatch.setattr(run, "_is_port_free", lambda host, p: p >= 8890)

    assert run._find_free_port("127.0.0.1", 8889, avoid_own_studio = True) == 8890


def test_the_requested_port_is_kept_when_it_is_free(monkeypatch):
    monkeypatch.setattr(run, "_is_port_free", lambda host, p: True)

    assert run._resolve_port("127.0.0.1", 8888) == 8888


def test_our_own_server_on_the_requested_port_aborts_rather_than_falling_back(
    tmp_path, monkeypatch
):
    # Reported bug: with 8888 ours, falling back to 8889 leaves 8888 serving and unrecorded.
    monkeypatch.setattr(run, "_is_port_free", lambda host, p: p != 8888)
    (tmp_path / "studio-8888-8550.pid").write_text("8550\n\n127.0.0.1", encoding = "utf-8")

    with pytest.raises(SystemExit) as excinfo:
        run._resolve_port("127.0.0.1", 8888)

    assert excinfo.value.code == 1


def test_a_foreign_process_on_the_requested_port_still_falls_back(monkeypatch):
    monkeypatch.setattr(run, "_is_port_free", lambda host, p: p != 8888)

    assert run._resolve_port("127.0.0.1", 8888) == 8889


def test_a_caller_that_reads_the_port_back_keeps_the_plain_fallback(tmp_path, monkeypatch):
    # api-only callers follow us to the new port, so aborting would only crash a working launch.
    monkeypatch.setattr(run, "_is_port_free", lambda host, p: p != 8888)
    (tmp_path / "studio-8888-8550.pid").write_text("8550\n\n127.0.0.1", encoding = "utf-8")

    assert run._resolve_port("127.0.0.1", 8888, avoid_own_studio = False) == 8889


def test_the_recorded_address_is_every_address_the_bind_resolves_to(tmp_path):
    # The only test running the writer with a real host spelling.
    run._write_pid_file(8901, "localhost")

    record = run._read_pid_record(tmp_path / f"studio-8901-{os.getpid()}.pid")

    assert record[2] is not None, "no bind address recorded"
    assert set(record[2].split(",")) == run._bind_addresses("localhost", 8901)


def test_a_server_started_on_a_hostname_is_found_again_by_ip(tmp_path):
    run._write_pid_file(8901, "localhost")

    for literal in run._bind_addresses("localhost", 8901):
        assert run._own_studio_on_port(8901, literal) == os.getpid()


def test_bind_addresses_keeps_every_family_a_hostname_resolves_to(monkeypatch):
    # Independent oracle; the sibling test would pass even if this function dropped a family.
    import socket
    monkeypatch.setattr(
        socket,
        "getaddrinfo",
        lambda *a, **k: [
            (socket.AF_INET, socket.SOCK_STREAM, 6, "", ("127.0.0.1", 8889)),
            (socket.AF_INET6, socket.SOCK_STREAM, 6, "", ("::1", 8889, 0, 0)),
        ],
    )

    assert run._bind_addresses("localhost", 8889) == {"127.0.0.1", "::1"}


def test_the_legacy_file_is_written_even_when_the_per_port_record_fails(tmp_path, monkeypatch):
    # studio.pid overwrites an existing path, so it can still succeed when new entries cannot.
    blocked = tmp_path / "not-a-directory"
    blocked.write_text("", encoding = "utf-8")
    monkeypatch.setattr(
        run, "_pid_file_for_port", lambda port: blocked / f"studio-{port}-{os.getpid()}.pid"
    )

    run._write_pid_file(8901, "127.0.0.1")

    assert (tmp_path / "studio.pid").read_text(encoding = "utf-8") == str(os.getpid())
    assert run._OWN_PID_FILE is None


def test_a_record_whose_pid_is_not_ascii_digits_is_discarded(tmp_path):
    # isdigit() passes superscript two, but int() rejects it and ValueError escapes callers.
    (tmp_path / "r.pid").write_text("²", encoding = "utf-8")

    assert run._read_pid_record(tmp_path / "r.pid") is None


def test_the_legacy_file_is_not_taken_from_a_live_server(tmp_path):
    (tmp_path / "studio.pid").write_text("8550", encoding = "utf-8")

    run._write_pid_file(8902, "127.0.0.1")

    assert (tmp_path / "studio.pid").read_text(encoding = "utf-8") == "8550"
    assert (tmp_path / f"studio-8902-{os.getpid()}.pid").exists()


def test_the_legacy_file_is_taken_over_from_a_dead_server(tmp_path, monkeypatch):
    monkeypatch.setattr(run, "_pid_alive", lambda pid: False)
    (tmp_path / "studio.pid").write_text("8550", encoding = "utf-8")

    run._write_pid_file(8902, "127.0.0.1")

    assert (tmp_path / "studio.pid").read_text(encoding = "utf-8") == str(os.getpid())


@pytest.mark.parametrize(
    "filename, contents",
    [
        # The compiled cache is install-tree relative, so a second backend must not wipe it.
        pytest.param(
            "studio-8888-8550.pid",
            "8550\n\n127.0.0.1",
            id = "a_live_sibling_is_found_so_the_shared_cache_survives",
        ),
        # Lifespan startup clears the cache before uvicorn reports a port to record.
        pytest.param(
            "studio-starting-8550.marker", "8550\n", id = "a_sibling_that_is_still_binding_is_found"
        ),
        pytest.param("studio.pid", "8550", id = "a_legacy_only_sibling_is_found"),
    ],
)
def test_live_sibling_backend_finds_the_recorded_port(tmp_path, filename, contents):
    (tmp_path / filename).write_text(contents, encoding = "utf-8")
    assert run.live_sibling_backend() == 8550


def test_our_own_record_is_not_a_sibling(tmp_path):
    me = os.getpid()
    (tmp_path / f"studio-8888-{me}.pid").write_text(f"{me}\n\n127.0.0.1", encoding = "utf-8")

    assert run.live_sibling_backend() is None


def test_a_dead_record_is_not_a_sibling(tmp_path, monkeypatch):
    monkeypatch.setattr(run, "_pid_alive", lambda pid: False)
    (tmp_path / "studio-8888-8550.pid").write_text("8550\n\n127.0.0.1", encoding = "utf-8")

    assert run.live_sibling_backend() is None


def test_a_reused_pid_is_not_a_sibling(tmp_path, monkeypatch):
    monkeypatch.setattr(run, "_pid_is_studio_backend", lambda pid, created_times = (): False)
    (tmp_path / "studio-8888-8550.pid").write_text("8550\n1.0\n127.0.0.1", encoding = "utf-8")

    assert run.live_sibling_backend() is None


def test_a_dead_legacy_record_is_not_a_sibling(tmp_path, monkeypatch):
    monkeypatch.setattr(run, "_pid_alive", lambda pid: False)
    (tmp_path / "studio.pid").write_text("8550", encoding = "utf-8")

    assert run.live_sibling_backend() is None


def test_the_startup_marker_is_written_and_removed(tmp_path):
    run.write_startup_marker()
    marker = tmp_path / f"studio-starting-{os.getpid()}.marker"

    assert marker.is_file()
    record = run._read_pid_record(marker)
    assert record is not None and record[0] == os.getpid()

    run._remove_startup_marker()

    assert not marker.exists()
    assert run._OWN_STARTUP_MARKERS == []


def test_our_own_startup_marker_is_not_a_sibling(tmp_path):
    run.write_startup_marker()

    assert run.live_sibling_backend() is None

    run._remove_startup_marker()


def test_a_startup_marker_is_invisible_to_the_pid_file_glob(tmp_path):
    # PID_FILE_GLOB readers need a port in the name; stop and _legacy_heir skip unbound ones.
    (tmp_path / "studio-starting-8550.marker").write_text("8550\n", encoding = "utf-8")

    assert list(tmp_path.glob(run.PID_FILE_GLOB)) == []


def test_the_marker_outlives_the_early_record_drop(tmp_path):
    # The marker waits for the server thread to end: in-flight imports may still read the cache.
    run.write_startup_marker()
    marker = tmp_path / f"studio-starting-{os.getpid()}.marker"
    run._write_pid_file(8906, "127.0.0.1")

    run._remove_pid_file()

    assert marker.is_file(), "the backend is still serving until the thread ends"
    assert _files(tmp_path) == []

    run._remove_startup_marker()

    assert not marker.exists()


def test_a_bare_legacy_record_cannot_resurrect_a_reused_pid(tmp_path, monkeypatch):
    # A timestamped record written after the bare studio.pid proves that PID's server is gone.
    monkeypatch.setattr(run, "_pid_is_studio_backend", _REAL_IS_STUDIO_BACKEND)
    monkeypatch.setattr(run, "_process_create_time", lambda pid: 999.0)
    legacy = tmp_path / "studio.pid"
    timed = tmp_path / "studio-8888-8550.pid"
    legacy.write_text("8550", encoding = "utf-8")
    timed.write_text("8550\n111.5\n127.0.0.1", encoding = "utf-8")
    os.utime(legacy, (100.0, 100.0))
    os.utime(timed, (200.0, 200.0))

    assert run.live_sibling_backend() is None


def test_an_older_timed_record_does_not_veto_a_newer_legacy_one(tmp_path, monkeypatch):
    # The reverse order: an older timestamp describes a dead process, so it must not veto.
    monkeypatch.setattr(run, "_pid_is_studio_backend", _REAL_IS_STUDIO_BACKEND)
    monkeypatch.setattr(run, "_process_create_time", lambda pid: 999.0)
    legacy = tmp_path / "studio.pid"
    timed = tmp_path / "studio-8888-8550.pid"
    timed.write_text("8550\n111.5\n127.0.0.1", encoding = "utf-8")
    legacy.write_text("8550", encoding = "utf-8")
    os.utime(timed, (100.0, 100.0))
    os.utime(legacy, (200.0, 200.0))

    assert run.live_sibling_backend() == 8550


def test_a_timed_record_for_another_pid_leaves_the_legacy_one_alone(tmp_path, monkeypatch):
    # Corroboration is per PID: a dead record for another server says nothing about studio.pid.
    monkeypatch.setattr(run, "_pid_is_studio_backend", _REAL_IS_STUDIO_BACKEND)
    monkeypatch.setattr(run, "_process_create_time", lambda pid: 999.0)
    (tmp_path / "studio-8888-8551.pid").write_text("8551\n111.5\n127.0.0.1", encoding = "utf-8")
    (tmp_path / "studio.pid").write_text("8550", encoding = "utf-8")

    assert run.live_sibling_backend() == 8550


def test_the_cache_lock_is_exclusive(tmp_path):
    with cache_cleanup.compiled_cache_lock() as first:
        assert first == cache_cleanup.LOCK_HELD
        with cache_cleanup.compiled_cache_lock(timeout = 0.05) as second:
            assert second == cache_cleanup.LOCK_BUSY

    with cache_cleanup.compiled_cache_lock() as again:
        assert again == cache_cleanup.LOCK_HELD


def test_the_probe_and_the_clear_happen_inside_one_lock(tmp_path, monkeypatch):
    # A sibling may publish and compile between our probe and our rmtree.
    events = []

    @contextlib.contextmanager
    def _lock(timeout = None):
        events.append("lock")
        try:
            yield cache_cleanup.LOCK_HELD
        finally:
            events.append("unlock")

    monkeypatch.setattr(cache_cleanup, "compiled_cache_lock", _lock)
    monkeypatch.setattr(
        cache_cleanup, "clear_unsloth_compiled_cache", lambda *a, **k: events.append("clear")
    )

    cache_cleanup.clear_compiled_cache_unless_shared(lambda: events.append("probe"))

    assert events == ["lock", "probe", "clear", "unlock"]


def test_a_busy_cache_lock_keeps_the_cache_without_probing(tmp_path, monkeypatch):
    events = []

    @contextlib.contextmanager
    def _lock(timeout = None):
        yield cache_cleanup.LOCK_BUSY

    monkeypatch.setattr(cache_cleanup, "compiled_cache_lock", _lock)
    monkeypatch.setattr(
        cache_cleanup, "clear_unsloth_compiled_cache", lambda *a, **k: events.append("clear")
    )

    cache_cleanup.clear_compiled_cache_unless_shared(lambda: events.append("probe"))

    assert events == []


def test_a_lock_that_cannot_be_taken_at_all_still_clears(tmp_path, monkeypatch):
    # No usable lock must not mean the cache is never cleared; fall back to the plain probe.
    blocked = tmp_path / "not-a-directory"
    blocked.write_text("", encoding = "utf-8")
    monkeypatch.setattr(cache_cleanup, "cache_coordination_dir", lambda: blocked / "lock")
    events = _shared_setup_1(monkeypatch)

    with cache_cleanup.compiled_cache_lock() as state:
        assert state == cache_cleanup.LOCK_UNAVAILABLE

    cache_cleanup.clear_compiled_cache_unless_shared(lambda: None)

    assert events == ["clear"]


def test_a_live_sibling_keeps_the_compiled_cache(tmp_path, monkeypatch):
    events = _shared_setup_1(monkeypatch)

    cache_cleanup.clear_compiled_cache_unless_shared(lambda: 8550)

    assert events == []


def test_no_sibling_probe_clears_unconditionally(tmp_path, monkeypatch):
    events = _shared_setup_1(monkeypatch)

    cache_cleanup.clear_compiled_cache_unless_shared(None)

    assert events == ["clear"]


def test_the_startup_marker_is_published_under_the_cache_lock(tmp_path, monkeypatch):
    # Publication must share the section with a sibling's probe and clear.
    marker = tmp_path / f"studio-starting-{os.getpid()}.marker"
    events = []

    @contextlib.contextmanager
    def _lock(timeout = None):
        events.append(("lock", marker.exists()))
        try:
            yield cache_cleanup.LOCK_HELD
        finally:
            events.append(("unlock", marker.exists()))

    monkeypatch.setattr(cache_cleanup, "compiled_cache_lock", _lock)

    run.write_startup_marker()

    assert events == [("lock", False), ("unlock", True)]


def test_a_zombie_backend_is_not_a_live_sibling(tmp_path, monkeypatch):
    # A zombie answers kill(0) and keeps its start time, so liveness alone reads it as serving.
    (tmp_path / "studio-8888-4242.pid").write_text("4242\n111.5\n127.0.0.1", encoding = "utf-8")

    monkeypatch.setattr(run, "_pid_alive", lambda pid: True)
    assert run.live_sibling_backend() == 4242, "the check under test must start from live"

    import utils.process_lifetime as process_lifetime

    monkeypatch.setattr(process_lifetime, "_pid_is_zombie", lambda pid: pid == 4242)

    assert run.live_sibling_backend() is None


@pytest.mark.skipif(sys.platform == "win32", reason = "Windows has no unreaped POSIX zombies")
def test_a_real_unreaped_child_is_not_a_live_sibling(tmp_path):
    import subprocess
    import sys

    child = subprocess.Popen([sys.executable, "-c", "import time; time.sleep(60)"])
    try:
        child.kill()
        (tmp_path / f"studio-8889-{child.pid}.pid").write_text(f"{child.pid}\n", encoding = "utf-8")
        deadline = time.monotonic() + 10
        while time.monotonic() < deadline:
            if run.live_sibling_backend() is None:
                break
            time.sleep(0.05)

        assert run.live_sibling_backend() is None, "a zombie was taken for a serving backend"
    finally:
        child.wait()


def test_every_record_call_can_be_repeated(tmp_path):
    # Startup and shutdown can each run more than once, or be left half done.
    run.write_startup_marker()
    marker = tmp_path / f"studio-starting-{os.getpid()}.marker"
    published = sorted(p.name for p in tmp_path.iterdir())
    body = marker.read_text(encoding = "utf-8")

    run.write_startup_marker()

    assert sorted(p.name for p in tmp_path.iterdir()) == published, "a second publish added a file"
    assert marker.read_text(encoding = "utf-8") == body
    assert run._OWN_STARTUP_MARKERS == [marker], "tracked twice would be removed twice"

    run._write_pid_file(8888, "127.0.0.1")
    recorded = sorted(p.name for p in tmp_path.iterdir())
    run._write_pid_file(8888, "127.0.0.1")

    assert sorted(p.name for p in tmp_path.iterdir()) == recorded

    run._remove_startup_marker()
    run._remove_startup_marker()
    run._remove_pid_file()
    run._remove_pid_file()

    assert list(tmp_path.glob(run.STARTUP_MARKER_GLOB)) == []
    assert _files(tmp_path) == []
    assert run._OWN_STARTUP_MARKERS == []


def test_reading_the_siblings_changes_nothing_on_disk(tmp_path):
    # The probe runs on every startup and is a read. If it pruned or rewrote
    # anything, one install's startup would edit another's records.
    (tmp_path / "studio-8888-4242.pid").write_text("4242\n111.5\n127.0.0.1", encoding = "utf-8")
    (tmp_path / "studio.pid").write_text("4243", encoding = "utf-8")
    before = {p.name: p.read_text(encoding = "utf-8") for p in tmp_path.iterdir()}

    for _ in range(3):
        run.live_sibling_backend()

    assert {p.name: p.read_text(encoding = "utf-8") for p in tmp_path.iterdir()} == before


def test_a_busy_lock_publishes_then_waits_for_the_clear_to_finish(tmp_path, monkeypatch):
    # Publish the marker first, then wait for the holder to finish deleting.
    marker = tmp_path / f"studio-starting-{os.getpid()}.marker"
    timeouts = []

    @contextlib.contextmanager
    def _lock(timeout = None):
        timeouts.append((timeout, marker.exists()))
        yield cache_cleanup.LOCK_BUSY if len(timeouts) == 1 else cache_cleanup.LOCK_HELD

    monkeypatch.setattr(cache_cleanup, "compiled_cache_lock", _lock)

    run.write_startup_marker()

    assert timeouts == [
        (30.0, False),
        (run._CACHE_CLEAR_WAIT_SECONDS, True),
    ], "the wait must come after the marker is on disk"


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

    @contextlib.contextmanager
    def _lock(timeout = None):
        calls.append(timeout)
        yield cache_cleanup.LOCK_HELD

    monkeypatch.setattr(cache_cleanup, "compiled_cache_lock", _lock)

    run.write_startup_marker()

    assert calls == [30.0]


def test_a_clear_that_never_finishes_still_lets_the_backend_start(tmp_path, monkeypatch):
    # Refusing to start is worse for the user than starting on a cache that may
    # lose files, so the wait is bounded and startup continues past it.
    @contextlib.contextmanager
    def _lock(timeout = None):
        yield cache_cleanup.LOCK_BUSY

    monkeypatch.setattr(cache_cleanup, "compiled_cache_lock", _lock)
    monkeypatch.setattr(run, "_CACHE_CLEAR_WAIT_SECONDS", 0.0)

    run.write_startup_marker()

    assert list(tmp_path.glob(run.STARTUP_MARKER_GLOB)) != []


def test_a_filesystem_that_cannot_lock_is_not_read_as_contention(tmp_path, monkeypatch):
    # ENOSYS means unsupported, not a sibling; reading it as busy would keep the cache forever.
    def unsupported(fd):
        raise OSError(errno.ENOSYS, "flock not supported")

    monkeypatch.setattr(cache_cleanup, "_try_lock", unsupported)
    events = _shared_setup_1(monkeypatch)

    with cache_cleanup.compiled_cache_lock(timeout = 30.0) as state:
        assert state == cache_cleanup.LOCK_UNAVAILABLE

    cache_cleanup.clear_compiled_cache_unless_shared(lambda: None)

    assert events == ["clear"]


def test_contention_is_still_retried_to_the_timeout(tmp_path, monkeypatch):
    def busy(fd):
        raise OSError(errno.EWOULDBLOCK, "held")

    monkeypatch.setattr(cache_cleanup, "_try_lock", busy)

    started = time.monotonic()
    with cache_cleanup.compiled_cache_lock(timeout = 0.2) as state:
        assert state == cache_cleanup.LOCK_BUSY
    assert time.monotonic() - started >= 0.2, "contention waits out the budget"


def test_a_startup_that_raises_takes_its_marker_back(tmp_path, monkeypatch):
    # colab.py catches SystemExit around run_server, so no exit hook removes the marker.
    run.write_startup_marker()
    assert list(tmp_path.glob(run.STARTUP_MARKER_GLOB)) != []

    def explode(*args, **kwargs):
        raise RuntimeError("startup failed")

    monkeypatch.setattr(run, "run_server", run._drops_its_marker_on_failure(explode))

    with pytest.raises(RuntimeError):
        run.run_server()

    assert list(tmp_path.glob(run.STARTUP_MARKER_GLOB)) == []
    assert run._OWN_STARTUP_MARKERS == []


def test_the_real_run_server_takes_its_marker_back(tmp_path):
    run.write_startup_marker()
    assert list(tmp_path.glob(run.STARTUP_MARKER_GLOB)) != []

    with pytest.raises(SystemExit):
        run.run_server(host = "")

    assert list(tmp_path.glob(run.STARTUP_MARKER_GLOB)) == []
    assert run._OWN_STARTUP_MARKERS == []


def test_a_startup_that_exits_takes_its_marker_back(tmp_path, monkeypatch):
    # SystemExit is a BaseException, and it is the one colab.py catches.
    run.write_startup_marker()

    def bail(*args, **kwargs):
        raise SystemExit(1)

    monkeypatch.setattr(run, "run_server", run._drops_its_marker_on_failure(bail))

    with pytest.raises(SystemExit):
        run.run_server()

    assert list(tmp_path.glob(run.STARTUP_MARKER_GLOB)) == []


def test_an_interrupt_leaves_the_marker_to_a_live_server_thread(tmp_path, monkeypatch):
    # KeyboardInterrupt re-raises without joining; dropping the marker would hide a live backend.
    run.write_startup_marker()
    assert list(tmp_path.glob(run.STARTUP_MARKER_GLOB)) != []

    stop = threading.Event()
    serving = threading.Thread(target = stop.wait, daemon = True)
    serving.start()
    monkeypatch.setattr(run, "_server_thread", serving)

    def interrupt(*args, **kwargs):
        raise KeyboardInterrupt

    monkeypatch.setattr(run, "run_server", run._drops_its_marker_on_failure(interrupt))
    try:
        with pytest.raises(KeyboardInterrupt):
            run.run_server()

        assert (
            list(tmp_path.glob(run.STARTUP_MARKER_GLOB)) != []
        ), "the sibling can no longer see it"
        assert run._OWN_STARTUP_MARKERS != []
    finally:
        stop.set()
        serving.join(timeout = 5)

    with pytest.raises(KeyboardInterrupt):
        run.run_server()

    assert list(tmp_path.glob(run.STARTUP_MARKER_GLOB)) == []


def test_a_server_thread_that_dies_after_readiness_drops_its_records(tmp_path, monkeypatch):
    # An embedded host outlives the uvicorn thread, so the thread's finally must drop the records.
    run.write_startup_marker()
    run._write_pid_file(8905, "127.0.0.1")

    assert list(tmp_path.glob(run.STARTUP_MARKER_GLOB)) != []
    assert _files(tmp_path) != []

    run._remove_startup_marker()
    run._remove_pid_file()

    assert list(tmp_path.glob(run.STARTUP_MARKER_GLOB)) == []
    assert _files(tmp_path) == []


def test_two_cold_starts_keep_rather_than_delete_each_others_modules(tmp_path, monkeypatch):
    # Known limitation: both keep a cache neither cleaned, the safe direction.
    events = _shared_setup_1(monkeypatch)

    cache_cleanup.clear_compiled_cache_unless_shared(lambda: 8550)
    cache_cleanup.clear_compiled_cache_unless_shared(lambda: 8551)

    assert events == []

    cache_cleanup.clear_compiled_cache_unless_shared(lambda: None)

    assert events == ["clear"]


def test_a_transient_unlink_failure_is_retried_on_the_spot(tmp_path, monkeypatch):
    # Retry a briefly held marker (Windows indexer) rather than leave it to atexit.
    run.write_startup_marker()
    marker = tmp_path / f"studio-starting-{os.getpid()}.marker"
    assert run._OWN_STARTUP_MARKERS == [marker]

    real_unlink = Path.unlink
    refused = []

    def refuse_once(self, missing_ok = False):
        if not refused:
            refused.append(self)
            raise OSError("busy")
        return real_unlink(self, missing_ok = missing_ok)

    monkeypatch.setattr(Path, "unlink", refuse_once)
    monkeypatch.setattr(run, "_MARKER_REMOVAL_BACKOFF_SECONDS", 0.0)
    run._remove_startup_marker()

    assert refused, "the first attempt did not run"
    assert run._OWN_STARTUP_MARKERS == []
    assert not marker.exists()


def test_a_marker_that_will_not_delete_stays_retryable(tmp_path, monkeypatch):
    # After the retries, keep the path so a later cleanup can still remove the marker.
    run.write_startup_marker()
    marker = tmp_path / f"studio-starting-{os.getpid()}.marker"
    assert run._OWN_STARTUP_MARKERS == [marker]

    real_unlink = Path.unlink
    attempts = []

    def refuse_while_locked(self, missing_ok = False):
        attempts.append(self)
        if locked:
            raise OSError("busy")
        return real_unlink(self, missing_ok = missing_ok)

    locked = True
    monkeypatch.setattr(Path, "unlink", refuse_while_locked)
    monkeypatch.setattr(run, "_MARKER_REMOVAL_BACKOFF_SECONDS", 0.0)
    run._remove_startup_marker()

    assert len(attempts) == run._MARKER_REMOVAL_ATTEMPTS, "the retries did not run"
    assert run._OWN_STARTUP_MARKERS == [marker], "still tracked for a retry"
    assert marker.exists()

    locked = False
    run._remove_startup_marker()

    assert run._OWN_STARTUP_MARKERS == []
    assert not marker.exists()


def test_startup_prunes_dead_records_but_preserves_live_and_uncertain_ones(tmp_path, monkeypatch):
    dead = [tmp_path / "studio-starting-4242.marker", tmp_path / "studio-8888-4242.pid"]
    for path in dead:
        path.write_text("4242\n111.5\n", encoding = "utf-8")
    kept = {
        "studio-starting-4243.marker": "4243\n111.5\n",
        "studio-8889-4243.pid": "4243\n111.5\n127.0.0.1",
        "studio-starting-4244.marker": "partial write",
        "studio-8890-4244.pid": "partial write",
        "studio-starting-4245.marker": "4242\n111.5\n",
        "studio.pid": "4242",
    }
    for name, body in kept.items():
        (tmp_path / name).write_text(body, encoding = "utf-8")
    monkeypatch.setattr(run, "_pid_alive", lambda pid: pid != 4242)
    monkeypatch.setattr(run, "_pid_is_studio_backend", lambda *args: False)
    run.write_startup_marker()
    assert all(not p.exists() for p in dead)
    assert {name: (tmp_path / name).read_text() for name in kept} == kept


@pytest.mark.parametrize(
    "state", [cache_cleanup.LOCK_HELD, cache_cleanup.LOCK_BUSY, cache_cleanup.LOCK_UNAVAILABLE]
)
def test_startup_prunes_only_inside_the_cache_lock(tmp_path, monkeypatch, state):
    stale = tmp_path / "studio-starting-4242.marker"
    stale.write_text("4242\n111.5\n", encoding = "utf-8")
    held = False

    @contextlib.contextmanager
    def lock(**kwargs):
        nonlocal held
        held = state == cache_cleanup.LOCK_HELD
        yield state
        held = False

    def alive(pid):
        assert held
        return False

    monkeypatch.setattr(cache_cleanup, "compiled_cache_lock", lock)
    monkeypatch.setattr(run, "_pid_alive", alive)
    run.write_startup_marker()
    assert stale.exists() is (state != cache_cleanup.LOCK_HELD)
    assert (tmp_path / f"studio-starting-{os.getpid()}.marker").exists()


@pytest.mark.parametrize("replace_same_body", [False, True])
def test_pruning_keeps_a_pid_record_replaced_during_the_probe(
    tmp_path, monkeypatch, replace_same_body
):
    path = tmp_path / "studio-8888-4242.pid"
    body = "4242\n111.5\n127.0.0.1"
    path.write_text(body, encoding = "utf-8")
    original = path.stat()

    def alive(pid):
        replacement = tmp_path / "replacement"
        replacement.write_text(body if replace_same_body else "4242\n999.0\n127.0.0.1")
        os.utime(replacement, ns = (original.st_atime_ns, original.st_mtime_ns))
        os.replace(replacement, path)
        return False

    monkeypatch.setattr(run, "_pid_alive", alive)
    run.write_startup_marker()
    assert path.exists()


def test_pruning_rechecks_a_pid_that_became_live(tmp_path, monkeypatch):
    path = tmp_path / "studio-starting-4242.marker"
    path.write_text("4242\n111.5\n", encoding = "utf-8")
    answers = iter([False, True])
    monkeypatch.setattr(run, "_pid_alive", lambda pid: next(answers))
    run.write_startup_marker()
    assert path.exists()


def test_pruning_failure_does_not_prevent_startup(tmp_path, monkeypatch):
    path = tmp_path / "studio-starting-4242.marker"
    path.write_text("4242\n111.5\n", encoding = "utf-8")
    unlink = Path.unlink

    def fail(stale, *args, **kwargs):
        if stale == path:
            raise PermissionError("held by another process")
        return unlink(stale, *args, **kwargs)

    monkeypatch.setattr(Path, "unlink", fail)
    monkeypatch.setattr(run, "_pid_alive", lambda pid: False)
    run.write_startup_marker()
    assert path.exists()
    assert (tmp_path / f"studio-starting-{os.getpid()}.marker").exists()


def test_stable_identity_protects_siblings_ports_and_legacy_handoff(tmp_path, monkeypatch):
    from utils import pid_records

    monkeypatch.setattr(run, "_pid_is_studio_backend", _REAL_IS_STUDIO_BACKEND)
    monkeypatch.setattr(run, "_process_create_time", lambda pid: 4600.0)
    monkeypatch.setattr(pid_records, "linux_process_identity", lambda pid: "linux:boot:123")
    path = tmp_path / "studio-8888-4242.pid"
    path.write_text("4242\n1000.0\n127.0.0.1\nlinux:boot:123\n", encoding = "utf-8")
    assert run.live_sibling_backend() == 4242
    assert run._own_studio_on_port(8888, "127.0.0.1") == 4242
    assert run._legacy_heir() == 4242
    monkeypatch.setattr(pid_records, "linux_process_identity", lambda pid: "linux:boot:124")
    assert run.live_sibling_backend() is None
    assert run._own_studio_on_port(8888, "127.0.0.1") is None
    assert run._legacy_heir() is None


def test_pruning_ignores_access_time_changes_from_reading_the_record(tmp_path, monkeypatch):
    path = tmp_path / "studio-8888-4242.pid"
    path.write_text("4242\n111.5\n127.0.0.1", encoding = "utf-8")
    stat = Path.stat
    reads = 0

    def accessed(item, *args, **kwargs):
        nonlocal reads
        result = stat(item, *args, **kwargs)
        if item == path:
            reads += 1
            fields = {name: getattr(result, name) for name in dir(result) if name.startswith("st_")}
            fields["st_atime"] += reads
            fields["st_atime_ns"] += reads * 1_000_000_000
            return SimpleNamespace(**fields)
        return result

    monkeypatch.setattr(Path, "stat", accessed)
    monkeypatch.setattr(run, "_pid_alive", lambda pid: False)
    run.write_startup_marker()
    assert not path.exists()


def test_windows_liveness_keeps_records_when_tasklist_returns_an_error(monkeypatch):
    import subprocess

    monkeypatch.setitem(sys.modules, "psutil", None)
    monkeypatch.setattr(sys, "platform", "win32")
    monkeypatch.setattr(
        subprocess, "run", lambda *args, **kwargs: SimpleNamespace(stdout = "", returncode = 1)
    )
    assert _REAL_PID_ALIVE(8550) is True