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.

216 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

import contextlib
import functools
import importlib.util
import hashlib
import hmac
import http.client
import json
import os
import platform
import re
import secrets
import shlex
import shutil
import sqlite3
import subprocess
import sys
import tempfile
import time
import types
import urllib.error
import urllib.parse
import urllib.request
from datetime import datetime, timezone
from pathlib import Path
from typing import List, Literal, Optional, Sequence, Tuple
import typer
from typer.core import TyperCommand

from unsloth_cli import _studio_deps, _studio_runtime_gate, _studio_stage
from unsloth_cli._argv import _expand_attached_np_short as _expand_attached_np_short
from unsloth_cli._inference import SpeculativeType
from unsloth_cli.commands import _password_prompt
from studio.backend.utils.pid_records import (
    RecordedStart,
    pid_reuse_proven,
    pid_start_matches,
    recorded_start,
)

studio_app = typer.Typer(help = "Unsloth Studio commands.")


def _enable_verbose_access_logs() -> None:
    os.environ["UNSLOTH_STUDIO_ACCESS_LOG_DEDUP_MS"] = "0"
    os.environ["UNSLOTH_STUDIO_ACCESS_LOG_POLL_DEDUP_MS"] = "0"
    os.environ["LOG_LEVEL"] = "DEBUG"


# Root order: UNSLOTH_STUDIO_HOME, STUDIO_HOME, UNSLOTH_HOME/studio, sys.prefix, legacy
# ~/.unsloth/studio; keep aligned with storage_roots.studio_root(). Markers mirror install.ps1.
_CMD_SHIM_MARKERS = (b"unsloth-studio-managed-launcher", b"from unsloth_cli import app")
_CMD_SHIM_MAX_BYTES = 8192


def _looks_like_installer_managed_studio_home(candidate: Path) -> bool:
    # Default POSIX installs keep studio.conf outside the install tree.
    if (candidate / "share" / "studio.conf").is_file() or (
        candidate / "share" / "studio_install_id"
    ).is_file():
        return True
    if platform.system() != "Windows":
        return (candidate / "bin" / "unsloth").is_file()
    if (candidate / "bin" / "unsloth.exe").is_file():
        return True
    return _is_managed_cmd_shim(candidate / "bin" / "unsloth.cmd")


def _is_managed_cmd_shim(path: Path) -> bool:
    try:
        if path.stat().st_size > _CMD_SHIM_MAX_BYTES:
            return False
        body = path.read_bytes()
    except OSError:
        return False
    return all(marker in body for marker in _CMD_SHIM_MARKERS)


def _resolve_studio_home() -> tuple[Path, bool]:
    override = (os.environ.get("UNSLOTH_STUDIO_HOME") or "").strip()
    if not override:
        override = (os.environ.get("STUDIO_HOME") or "").strip()
    if override:
        try:
            return Path(override).expanduser().resolve(), True
        except (OSError, ValueError):
            return Path(override).expanduser(), True
    # Keeps the CLI on the same root as storage_roots.py; see test_unsloth_home_root_agreement.py.
    master = (os.environ.get("UNSLOTH_HOME") or "").strip()
    if master:
        try:
            candidate = Path(master).expanduser().resolve() / "studio"
        except (OSError, ValueError):
            candidate = Path(master).expanduser() / "studio"
        try:
            legacy = (Path.home() / ".unsloth" / "studio").resolve()
        except (OSError, ValueError):
            legacy = Path.home() / ".unsloth" / "studio"
        # Preserve legacy installs until a managed install exists at the master root.
        if candidate != legacy and not _looks_like_installer_managed_studio_home(candidate):
            if _looks_like_installer_managed_studio_home(legacy):
                return legacy, False
        return candidate, candidate != legacy
    try:
        prefix = Path(sys.prefix).resolve()
        if prefix.name == "unsloth_studio":
            inferred = prefix.parent
            legacy = (Path.home() / ".unsloth" / "studio").resolve()
            if inferred != legacy and _looks_like_installer_managed_studio_home(inferred):
                return inferred, True
    except (OSError, ValueError):
        pass
    return Path.home() / ".unsloth" / "studio", False


STUDIO_HOME, _STUDIO_HOME_IS_CUSTOM = _resolve_studio_home()

MASTER_ROOT_NOTE = ".unsloth-master-root"


def _recorded_master_root() -> Optional[Path]:
    """The master root setup recorded in this Studio tree, or None.

    Keep this aligned with storage_roots._recorded_master_root(); see
    test_unsloth_home_root_agreement.py. `UNSLOTH_HOME=/mnt/portable unsloth studio update` puts
    node, llama.cpp and whisper.cpp BESIDE studio/ and leaves nothing in a later environment. The
    backend recovers that from the note, so a `unsloth studio update` that did not would hand
    setup a plain Studio root, have it refresh the runtimes one level down at <master>/studio/,
    and leave the backend still launching the stale trees at <master>/.

    The recorded root must exist and THIS Studio directory must lie inside it, so a tree copied
    from one master root to another does not send the update, or a removal, into the original
    install. Containment, not an exact <root>/studio match: the flat layout names one directory
    for both, and UNSLOTH_HOME=/root with UNSLOTH_STUDIO_HOME=/root/custom/studio is a root that
    genuinely contains its Studio somewhere other than the default child. The backend and both
    uninstallers apply exactly this rule, and a stricter one here would have the CLI decline a
    note the backend accepts, which is the same split this function exists to close.
    """
    try:
        recorded = (STUDIO_HOME / "share" / MASTER_ROOT_NOTE).read_text(encoding = "utf-8").strip()
    except (OSError, ValueError, UnicodeDecodeError):
        return None
    if not recorded:
        return None
    try:
        master = Path(recorded).expanduser().resolve()
        here = STUDIO_HOME.resolve()
        if not (master.is_dir() and (here == master or master in here.parents)):
            return None
        # Decline a legacy-rooted note, keyed on the tree so a note naming $HOME or an ancestor goes too, like storage_roots._is_legacy_studio_tree.
        try:
            if here == (Path.home() / ".unsloth" / "studio").resolve():
                return None
        except (OSError, RuntimeError, ValueError):
            pass
        return master
    except (OSError, ValueError):
        return None
    return None


def _master_root_llama_dir() -> Optional[Path]:
    """``<master>/llama.cpp`` when this install has a master root, else None.

    Under UNSLOTH_HOME the runtimes are siblings of studio/, so the answer cannot be
    derived from the studio home: <studio home>/llama.cpp is one level too deep. Both
    the export below and the grading in _managed_llama_dir_ignoring_the_override read
    this, so the rule exists once rather than twice.

    Environment only, because the command callback recovers a recorded master root
    into UNSLOTH_HOME before anything here runs.
    """
    master = (os.environ.get("UNSLOTH_HOME") or "").strip()
    if not master:
        return None
    try:
        return Path(master).expanduser().resolve() / "llama.cpp"
    except (OSError, ValueError):
        return Path(master).expanduser() / "llama.cpp"


def _ensure_studio_env_exported() -> None:
    """Re-export UNSLOTH_STUDIO_HOME / UNSLOTH_LLAMA_CPP_PATH for custom roots, and for a master
    root the resolver above declined, per subcommand rather than at import, so unrelated
    importers see no env changes."""
    # storage_roots.studio_root() honours UNSLOTH_HOME unconditionally, so export the root this CLI chose,
    # or the backend and setup subprocess write elsewhere.
    if not (os.environ.get("UNSLOTH_HOME") or "").strip():
        _recorded = _recorded_master_root()
        if _recorded is not None:
            os.environ["UNSLOTH_HOME"] = str(_recorded)
    if not _STUDIO_HOME_IS_CUSTOM and not (os.environ.get("UNSLOTH_HOME") or "").strip():
        return
    # Truthy-check, not setdefault: a blank UNSLOTH_STUDIO_HOME= must not win.
    if not (os.environ.get("UNSLOTH_STUDIO_HOME") or "").strip():
        os.environ["UNSLOTH_STUDIO_HOME"] = str(STUDIO_HOME)
    try:
        _legacy_studio = (Path.home() / ".unsloth" / "studio").resolve()
        _is_legacy = STUDIO_HOME.resolve() == _legacy_studio
    except (OSError, ValueError):
        _is_legacy = STUDIO_HOME == (Path.home() / ".unsloth" / "studio")
    # Runtimes are siblings of studio/; run.py keeps a non-blank value, so a wrong export wins everywhere.
    _llama_dir = _master_root_llama_dir()
    if _llama_dir is None:
        _llama_dir = (
            Path.home() / ".unsloth" / "llama.cpp" if _is_legacy else STUDIO_HOME / "llama.cpp"
        )
    if not (os.environ.get("UNSLOTH_LLAMA_CPP_PATH") or "").strip():
        os.environ["UNSLOTH_LLAMA_CPP_PATH"] = str(_llama_dir)


BOOTSTRAP_PASSWORD_FILE = ".bootstrap_password"
DESKTOP_SECRET_FILE = ".desktop_secret"
# Cached raw CLI API key; the full name carries a digest: ".cli_api_key_cli_<digest>".
CLI_API_KEY_FILE_PREFIX = ".cli_api_key_"
DEFAULT_ADMIN_USERNAME = "unsloth"
DESKTOP_SECRET_PREFIX = "desktop-"
API_KEY_PBKDF2_SALT_KEY = "api_key_pbkdf2_salt"
DESKTOP_SECRET_HASH_KEY = "desktop_secret_hash"
DESKTOP_SECRET_CREATED_AT_KEY = "desktop_secret_created_at"
PBKDF2_ITERATIONS = 100_000
_START_API_KEY_MARKER_ENV = "_UNSLOTH_START_API_KEY_MARKER"
# Marks run()'s re-exec'd child; a marked child still outside the venv must stop, not loop.
_STUDIO_REEXEC_ENV = "_UNSLOTH_STUDIO_REEXEC"
_CLOUDFLARE_INTENT_ENV = "_UNSLOTH_CLOUDFLARE_INTENT"


def _consume_start_api_key_marker_env() -> bool:
    return os.environ.pop(_START_API_KEY_MARKER_ENV, None) == "1"


def _preserve_cloudflare_intent(cloudflare: Optional[bool], secure: bool) -> None:
    if _CLOUDFLARE_INTENT_ENV in os.environ:
        return
    if secure or cloudflare is True:
        intent = "enabled"
    elif cloudflare is False:
        intent = "disabled"
    else:
        intent = "unset"
    os.environ[_CLOUDFLARE_INTENT_ENV] = intent


_PACKAGE_ROOT = Path(__file__).resolve().parent.parent.parent


def _should_hide_windows_subprocesses() -> bool:
    if platform.system() != "Windows":
        return False
    try:
        return not sys.stdout.isatty()
    except (AttributeError, OSError, ValueError):
        return True


def _windows_hidden_subprocess_kwargs() -> dict[str, object]:
    if not _should_hide_windows_subprocesses():
        return {}

    kwargs: dict[str, object] = {}
    create_no_window = getattr(subprocess, "CREATE_NO_WINDOW", 0)
    if create_no_window:
        kwargs["creationflags"] = create_no_window

    startupinfo_factory = getattr(subprocess, "STARTUPINFO", None)
    startf_use_showwindow = getattr(subprocess, "STARTF_USESHOWWINDOW", 0)
    sw_hide = getattr(subprocess, "SW_HIDE", 0)
    if startupinfo_factory is not None and startf_use_showwindow:
        startupinfo = startupinfo_factory()
        startupinfo.dwFlags |= startf_use_showwindow
        startupinfo.wShowWindow = sw_hide
        kwargs["startupinfo"] = startupinfo

    return kwargs


# Application Control denies the unsigned unsloth.exe, so managed invocations go through the interpreter (#8490). Byte-identical to process.rs and install.ps1.
_WINDOWS_CLI_ENTRYPOINT = (
    "import sys, os; sys.path[:1] = [x for x in sys.path[:1] if getattr(sys.flags, 'safe_path', False) or x not in ('', os.getcwd())]; "
    "sys.argv[0] = 'unsloth'; from unsloth_cli import app; sys.exit(app())"
)

# The trampoline's exact import (find_spec passes for an empty unsloth_cli), with the sys.path[0] scrub a parity test literal_evals.
_MANAGED_CLI_IMPORT_PROBE = (
    "import sys, os; sys.path[:1] = [x for x in sys.path[:1] if getattr(sys.flags, 'safe_path', False) or x not in ('', os.getcwd())]; "
    "from unsloth_cli import app; sys.exit(0)"
)

# Generous: cold interpreter start plus package import. A timeout means "no verdict", not failure.
_MANAGED_CLI_IMPORT_PROBE_TIMEOUT = 60

# Policy refusals: AppLocker 1260, App Control / Smart App Control 4551. Not 577: a bad hash can be a damaged file.
_APPLICATION_CONTROL_WINERRORS = frozenset({1260, 4551})


def _managed_cli_argv(
    python: Path,
    *args: str,
    isolated: bool = False,
) -> List[str]:
    """argv that runs the managed `unsloth` CLI through *python*. -X utf8 precedes -I because -I
    implies -E. *isolated* mirrors Isolation in process.rs; the default inherits."""
    flags = ["-X", "utf8", "-I"] if isolated else ["-X", "utf8"]
    return [str(python), *flags, "-c", _WINDOWS_CLI_ENTRYPOINT, *args]


def _is_application_control_block(error: OSError) -> bool:
    """True when Windows refused to start a program by policy: nothing ran."""
    return getattr(error, "winerror", None) in _APPLICATION_CONTROL_WINERRORS


@contextlib.contextmanager
def _studio_runtime_launch_guard(*, inherited: bool = False, wait: bool = False):
    guard = _studio_runtime_gate.studio_runtime_launch_guard(
        STUDIO_HOME,
        inherited = inherited,
        wait = wait,
    )
    try:
        acquired = guard.__enter__()
    except _studio_runtime_gate.StudioRuntimeGateBusy:
        typer.echo(
            "Error: Unsloth installation is modifying the managed environment. "
            "Wait for it to finish, then try again.",
            err = True,
        )
        raise typer.Exit(1)
    except OSError as exc:
        typer.echo(f"Error: could not coordinate the Unsloth launch: {exc}", err = True)
        raise typer.Exit(1)

    try:
        yield acquired
    finally:
        guard.__exit__(None, None, None)


def _stream_for_subprocess(stream):
    """Return None without a real OS fd; Windows needs std handles passed explicitly."""
    if stream is None:
        return None
    try:
        stream.fileno()
    except (AttributeError, OSError, ValueError):
        return None
    return stream


def _display_host_for_bind(run_mod, host: str) -> str:
    return run_mod._display_host_for_bind(host)


def _network_share_host_for_bind(run_mod, host: str) -> str:
    resolver = getattr(run_mod, "_network_share_host_for_bind", None)
    if resolver is None:
        return _display_host_for_bind(run_mod, host)
    return resolver(host)


def _loopback_bind_host_for(host: str) -> str:
    from unsloth_cli._tool_policy import wildcard_loopback_host
    return wildcard_loopback_host(host) or "127.0.0.1"


def _is_wildcard_bind(host: str) -> bool:
    from unsloth_cli._tool_policy import is_wildcard_host
    return is_wildcard_host(host)


def _openable_host_for_bind(run_mod, host: str) -> str:
    """URL host: the LAN address if one resolves, else loopback, never a wildcard bind."""
    share_host = _network_share_host_for_bind(run_mod, host)
    if _is_wildcard_bind(share_host):
        return _loopback_bind_host_for(host)
    return share_host


def _require_valid_tls_flags(
    ssl_certfile: Optional[Path],
    ssl_keyfile: Optional[Path],
    *,
    secure: bool,
    cloudflare: Optional[bool],
) -> None:
    """Fail on a bad --ssl-certfile/--ssl-keyfile launch before the password gate can change or strip credentials.
    run_server re-checks the same rules (utils/studio_tls.py) for direct `run.py` callers."""
    if ssl_certfile is None and ssl_keyfile is None:
        return
    if ssl_certfile is None or ssl_keyfile is None:
        typer.echo("Error: --ssl-certfile and --ssl-keyfile must be passed together.", err = True)
        raise typer.Exit(2)
    if secure or cloudflare:
        typer.echo(
            "Error: --ssl-certfile/--ssl-keyfile serve HTTPS directly; do not combine them "
            "with --secure or --cloudflare.",
            err = True,
        )
        raise typer.Exit(2)
    import ssl

    try:
        ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER).load_cert_chain(
            str(ssl_certfile.expanduser()), str(ssl_keyfile.expanduser())
        )
    except (OSError, ssl.SSLError) as exc:
        typer.echo(
            f"Error: could not load the TLS certificate and key ({ssl_certfile}, {ssl_keyfile}): {exc}",
            err = True,
        )
        raise typer.Exit(2)


def _require_bind_host(host: str) -> None:
    if isinstance(host, str) and host.strip():
        return
    typer.echo(
        "Error: --host cannot be empty; use 0.0.0.0 to bind every IPv4 interface.",
        err = True,
    )
    raise typer.Exit(2)


def _normalize_wildcard_bind_host(host: str) -> str:
    from unsloth_cli._tool_policy import normalize_wildcard_bind_host
    try:
        return normalize_wildcard_bind_host(host)
    except ValueError as exc:
        typer.echo(f"Error: {exc}", err = True)
        raise typer.Exit(2) from None


def _require_unambiguous_ephemeral_bind(host: str, port: int) -> None:
    if port != 0:
        return
    from unsloth_cli._tool_policy import resolved_bind_address_count

    if resolved_bind_address_count(host) <= 1:
        return
    typer.echo(
        "Error: --port 0 cannot be used when --host resolves to multiple bind "
        "addresses; choose an explicit port.",
        err = True,
    )
    raise typer.Exit(2)


def _url_host(host: str) -> str:
    url_host = host.replace("%", "%25")
    return (
        f"[{url_host}]"
        if ":" in url_host and not (url_host.startswith("[") and url_host.endswith("]"))
        else url_host
    )


def _emit_run_cloudflare_notice(
    run_mod, host: str, display_host: str, actual_port: int, secure: bool
) -> None:
    from unsloth_cli._tool_policy import is_external_host

    if not is_external_host(host):
        return
    run_mod._verify_global_reachability(display_host, actual_port)
    run_mod._print_cloudflare_line(
        secure = secure,
        loopback_host = _loopback_bind_host_for(host),
    )


def _studio_venv_python() -> Optional[Path]:
    if platform.system() == "Windows":
        p = STUDIO_HOME / "unsloth_studio" / "Scripts" / "python.exe"
    else:
        p = STUDIO_HOME / "unsloth_studio" / "bin" / "python"
    return p if p.is_file() else None


def _resolved_or_self(path: Path) -> Path:
    try:
        return path.resolve()
    except (OSError, RuntimeError, ValueError):  # RuntimeError: symlink loop, Python < 3.13
        return path


def _running_in_studio_venv(venv_dir: Path) -> bool:
    """Compare resolved path components: console-script shebangs hold the resolved venv path,
    so a string prefix check against a symlinked venv_dir never matched and looped forever."""
    prefix = Path(sys.prefix)
    for a, b in (
        (prefix, venv_dir),
        (_resolved_or_self(prefix), _resolved_or_self(venv_dir)),
    ):
        a_s = os.path.normcase(str(a))
        b_s = os.path.normcase(str(b)).rstrip(os.sep + (os.altsep or ""))
        if a_s == b_s or a_s.startswith(b_s + os.sep):
            return True
    try:
        return os.path.samefile(prefix, venv_dir)
    except (OSError, ValueError):
        return False


def _managed_cli_site_packages_layout(python: Path) -> bool:
    """Weaker than the import probe: an empty unsloth_cli/ or orphaned dist-info still passes."""
    site_packages = python.parent.parent / "Lib" / "site-packages"
    if (site_packages / "unsloth_cli").is_dir():
        return True
    return any(site_packages.glob("unsloth-*.dist-info"))


def _managed_cli_package_present(python: Path) -> bool:
    """Whether the venv holding *python* can still import the package the CLI runs. Windows only,
    and asked of the interpreter, since this gate fronts the .bootstrap_password strip."""
    if platform.system() != "Windows":
        return False
    try:
        probe = subprocess.run(
            [str(python), "-X", "utf8", "-c", _MANAGED_CLI_IMPORT_PROBE],
            capture_output = True,
            timeout = _MANAGED_CLI_IMPORT_PROBE_TIMEOUT,
            # A non-interactive Windows launch must not flash a console window (#8490).
            **_windows_hidden_subprocess_kwargs(),
        )
    except subprocess.TimeoutExpired:
        # Timeout is not failure: the untimed re-exec would still come up, so fall back to the on-disk layout.
        return _managed_cli_site_packages_layout(python)
    except (OSError, subprocess.SubprocessError):
        # The re-exec runs that same interpreter. Fail closed: the caller strips .bootstrap_password first.
        return False
    return probe.returncode == 0


def _hsa_override_gfx_arch(value: Optional[str]) -> Optional[str]:
    """gfx arch named by an HSA_OVERRIDE_GFX_VERSION value, or None if unreadable. Kept in sync
    with _hsa_override_gfx_arch in studio/install_python_stack.py and install.sh."""
    if not value:
        return None
    # [0-9] rather than str.isdigit()/\d, both of which accept non-ASCII digits.
    if not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+", value.strip()):
        return None
    major, minor, step = (int(p) for p in value.strip().split("."))
    # Steppings are a single hex nibble; anything wider is not a real target.
    if not (0 <= step <= 15) or major <= 0 or minor > 9:
        return None
    return f"gfx{major}{minor}{step:x}"


def _torch_requires_rocm_metapackage(venv_dir: Path) -> bool:
    """Whether the installed torch actually resolves through the ``rocm`` meta-package: the generic
    pytorch.org wheels vendor their own runtime, so after a switch it is orphaned."""
    for sp_pattern in ("lib/python*/site-packages", "Lib/site-packages"):
        for sp in venv_dir.glob(sp_pattern):
            for info in sp.glob("torch-*.dist-info"):
                if not re.fullmatch(r"torch-[^-]+\.dist-info", info.name):
                    continue
                metadata = info / "METADATA"
                if not metadata.is_file():
                    continue
                try:
                    text = metadata.read_text(encoding = "utf-8", errors = "replace")
                except OSError:
                    return False
                for line in text.splitlines():
                    if not line.lower().startswith("requires-dist:"):
                        continue
                    # Plain `rocm` and `rocm[libraries,devel]` both count; `rocm-sdk-core` is a component, not the arbiter.
                    if re.search(r"requires-dist:\s*rocm(?![-_a-z0-9])", line, re.IGNORECASE):
                        return True
                return False
    return False


# Read by studio/backend/utils/desktop_shell_env.py, which imports the login shell's ROCm variables
# (where the #7331 override lives), so it needs this arbiter.
ROCM_INSTALLED_ARCH_ENV = "UNSLOTH_ROCM_INSTALLED_ARCH"


def _installed_rocm_single_arch(venv_dir: Path) -> Optional[str]:
    """gfx arch the ROCm runtime in *venv_dir* ACTIVELY carries kernels for, or None. Read from the
    `rocm` meta-package: globbing for rocm_sdk_libraries_gfx* would read an ORPHAN. None also
    covers a MULTI-arch family such as gfx120x-all, which contradicts no override."""
    # Only a LIVE install while torch resolves through it: the generic pytorch.org wheels orphan `rocm`, which would then name the OLD family.
    if not _torch_requires_rocm_metapackage(venv_dir):
        return None
    _metadata: Optional[Path] = None
    for sp_pattern in ("lib/python*/site-packages", "Lib/site-packages"):
        for sp in venv_dir.glob(sp_pattern):
            for info in sp.glob("rocm-*.dist-info"):
                # rocm-sdk-* also start "rocm-"; only the bare meta-package arbitrates.
                if (
                    re.fullmatch(r"rocm-[^-]+\.dist-info", info.name)
                    and (info / "METADATA").is_file()
                ):
                    _metadata = info / "METADATA"
                    break
    if _metadata is None:
        return None
    try:
        _text = _metadata.read_text(encoding = "utf-8", errors = "replace")
    except OSError:
        return None
    _families = set()
    for _line in _text.splitlines():
        if not _line.lower().startswith("requires-dist:"):
            continue
        _m = re.search(r"rocm[-_]sdk[-_]libraries[-_]([0-9a-zA-Z]+)", _line)
        if _m:
            _families.add(_m.group(1).lower())
    if len(_families) != 1:
        return None
    _family = _families.pop()
    # Single ISA only: a gfx120x-all family contradicts no override.
    return _family if re.fullmatch(r"gfx[0-9a-f]+", _family) else None


def _clear_hsa_override_contradicting_install(venv_dir: Path) -> Optional[str]:
    """Drop an HSA_OVERRIDE_GFX_VERSION no installed kernel can satisfy (#7331): against per-gfx
    wheels it fails every launch, and install.sh's unset dies with the installer, so this is the
    chokepoint every path shares. Keyed on the INSTALL, never a hardware probe."""
    raw = os.environ.get("HSA_OVERRIDE_GFX_VERSION")
    if not raw or platform.system() == "Windows":
        return None
    arch = _installed_rocm_single_arch(venv_dir)
    if arch is None:
        return None
    named = _hsa_override_gfx_arch(raw)
    if named is None or named == arch:
        return None
    os.environ.pop("HSA_OVERRIDE_GFX_VERSION", None)
    return arch


def _clear_hsa_override_before_launch(silent: bool = False) -> Optional[str]:
    """Run the #7331 spoof clear for whichever entry point is about to launch. Idempotent."""
    _venv = STUDIO_HOME / "unsloth_studio"
    _root = Path(sys.prefix) if _running_in_studio_venv(_venv) else _venv
    _arch = _clear_hsa_override_contradicting_install(_root)
    # Published regardless: a desktop launch never had the override, but the profile still does.
    _installed = _installed_rocm_single_arch(_root)
    if _installed and platform.system() != "Windows":
        os.environ[ROCM_INSTALLED_ARCH_ENV] = _installed
    if _arch is not None and not silent:
        typer.echo(
            f"Cleared HSA_OVERRIDE_GFX_VERSION: this install carries {_arch} kernels "
            f"only, so the runtime has to report the real arch. Remove the export "
            f"from your shell profile as well, or the next terminal restores it.",
            err = True,
        )
    return _arch


def _find_run_py() -> Optional[Path]:
    run_py = _PACKAGE_ROOT / "studio" / "backend" / "run.py"
    if run_py.is_file():
        return run_py
    for pattern in (
        "lib/python*/site-packages/studio/backend/run.py",
        "Lib/site-packages/studio/backend/run.py",
    ):
        for match in (STUDIO_HOME / "unsloth_studio").glob(pattern):
            return match
    return None


def _install_state(deep: bool = False) -> dict:
    """verify_install() result for this root; STUDIO_HOME is an extra search root so a CLI outside
    the managed venv still inspects the venv the desktop app launches."""
    return _studio_deps.install_state(
        extra_roots = (STUDIO_HOME / "unsloth_studio",),
        deep = deep,
    )


_RUN_MODULE = None


def _load_run_module():
    """Import studio.backend.run by file path: `studio update` can leave a partial
    site-packages/studio/backend/ tree that shadows an editable install."""
    global _RUN_MODULE
    if _RUN_MODULE is not None:
        return _RUN_MODULE

    run_py = _find_run_py()
    if run_py is None:
        raise ImportError("Could not find studio/backend/run.py. Re-run: unsloth studio setup")

    loaded = sys.modules.get("studio.backend.run")
    if loaded is not None:
        loaded_path = Path(getattr(loaded, "__file__", None) or "").resolve()
        if loaded_path == run_py.resolve():
            _RUN_MODULE = loaded
            return _RUN_MODULE

    spec = importlib.util.spec_from_file_location("studio.backend.run", run_py)
    if spec is None or spec.loader is None:
        raise ImportError(f"Could not load Unsloth backend from {run_py}")
    module = importlib.util.module_from_spec(spec)
    sys.modules["studio.backend.run"] = module
    try:
        spec.loader.exec_module(module)
    except Exception:
        sys.modules.pop("studio.backend.run", None)
        raise
    _RUN_MODULE = module
    return _RUN_MODULE


def _find_setup_script(repo_root: Optional[Path] = None) -> Optional[Path]:
    """Find studio/setup.sh or studio/setup.ps1, from any CWD. *repo_root* is the --local checkout
    and its script must win, since the editable install removes the tree the installed one builds into."""
    name = "setup.ps1" if platform.system() == "Windows" else "setup.sh"
    # No fallback: reaching for the installed copy's script is what this branch prevents.
    if repo_root is not None:
        s = repo_root / "studio" / name
        return s if s.is_file() else None
    s = _PACKAGE_ROOT / "studio" / name
    if s.is_file():
        return s
    for pattern in (
        f"lib/python*/site-packages/studio/{name}",
        f"Lib/site-packages/studio/{name}",
    ):
        for match in (STUDIO_HOME / "unsloth_studio").glob(pattern):
            return match
    return None


# Mirrored in studio/backend/run.py argparse and the backend denylist test; bump both.
_PARALLEL_MIN = 1
_PARALLEL_MAX = 64
_PARALLEL_DEFAULT_RUN = 4
# At 1 every extra chat queues behind the generating one. _slots_that_fit_on_gpu() may cut it back.
_PARALLEL_DEFAULT_PLAIN = 4


def _resolve_secure(secure: bool, not_secure: bool) -> bool:
    """Reconcile the deprecated --not-secure alias with --secure/--no-secure. Typer parses them as
    independent options, so last-wins ordering is restored from argv to match the backend."""
    if not not_secure:
        return secure
    last_secure = max(
        (i for i, a in enumerate(sys.argv) if a in ("--secure", "--no-secure")),
        default = -1,
    )
    last_not_secure = max(
        (i for i, a in enumerate(sys.argv) if a == "--not-secure"),
        default = -1,
    )
    return secure if last_secure > last_not_secure else False


def _iter_editable_studio_source_roots(venv_dir: Path):
    """Yield repo roots from setuptools `__editable___*_finder.py` MAPPINGs naming `studio`, as the
    parent of the mapped package."""
    import ast
    import re

    for sp_pattern in ("lib/python*/site-packages", "Lib/site-packages"):
        for sp in venv_dir.glob(sp_pattern):
            for finder in sp.glob("__editable___*_finder.py"):
                try:
                    src = finder.read_text(encoding = "utf-8")
                except (OSError, UnicodeDecodeError):
                    continue
                # [^}]* still rejects nested dicts, which the setuptools template never emits.
                m = re.search(r"^MAPPING\s*(?::[^=]*)?=\s*(\{[^}]*\})", src, re.M | re.S)
                if not m:
                    continue
                try:
                    mapping = ast.literal_eval(m.group(1))
                except (SyntaxError, ValueError):
                    continue
                # literal_eval can return a set / list / None: the regex only captures `{...}`.
                if not isinstance(mapping, dict):
                    continue
                studio_pkg = mapping.get("studio")
                if studio_pkg:
                    yield Path(studio_pkg).parent


def _find_frontend_dist() -> Optional[Path]:
    """Locate a built `studio/frontend/dist`, or None so callers can fall back to --api-only.
    Editable source roots are probed too, so a shadowing `unsloth` on PATH cannot win."""
    candidates: List[Path] = [_PACKAGE_ROOT / "studio" / "frontend" / "dist"]
    venv_dir = STUDIO_HOME / "unsloth_studio"
    for pattern in (
        "lib/python*/site-packages/studio/frontend/dist",
        "Lib/site-packages/studio/frontend/dist",
    ):
        candidates.extend(venv_dir.glob(pattern))
    for repo_root in _iter_editable_studio_source_roots(venv_dir):
        candidates.append(repo_root / "studio" / "frontend" / "dist")
    seen: set[Path] = set()
    for c in candidates:
        try:
            resolved = c.resolve()
        except OSError:
            resolved = c
        if resolved in seen:
            continue
        seen.add(resolved)
        if (c / "index.html").is_file():
            return c
    return None


_direct_http_opener = None


def _direct_urlopen(request, timeout):
    global _direct_http_opener

    if _direct_http_opener is None:

        class _NoRedirect(urllib.request.HTTPRedirectHandler):
            def redirect_request(self, req, fp, code, msg, headers, newurl):
                raise urllib.error.HTTPError(
                    req.full_url, code, f"refusing redirect to {newurl}", headers, fp
                )

        _direct_http_opener = urllib.request.build_opener(
            urllib.request.ProxyHandler({}),
            _NoRedirect(),
        )
    return _direct_http_opener.open(request, timeout = timeout)


def _wait_for_server(
    port: int,
    timeout: int = 30,
    request_host: str = "127.0.0.1",
) -> bool:
    import urllib.request
    import urllib.error

    url = f"http://{_url_host(request_host)}:{port}/api/health"
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        try:
            with _direct_urlopen(url, timeout = 2) as resp:
                if resp.status == 200:
                    return True
        except (urllib.error.URLError, OSError, ConnectionError):
            pass
        time.sleep(0.5)
    return False


def _cli_api_key_secret_path(name: str) -> Path:
    """Identity is the digest, so a shared stem (foo/bar vs foo?bar, cli vs CLI) cannot share a
    credential; ASCII-only keeps names within NAME_MAX (255 bytes); multibyte names were
    re-minted every launch (issue 10595)."""
    safe = "".join(
        ch if (ch.isascii() and ch.isalnum()) or ch in "-_" else "_" for ch in name
    ).strip("_")
    if not safe:
        safe = "cli"
    digest = hashlib.sha256(name.encode("utf-8")).hexdigest()[:12]
    return STUDIO_HOME / "auth" / f"{CLI_API_KEY_FILE_PREFIX}{safe[:64]}_{digest}"


def _read_cli_api_key_secret(name: str) -> str:
    try:
        return _cli_api_key_secret_path(name).read_text(encoding = "utf-8").strip()
    except (OSError, ValueError):
        return ""


def _create_api_key_inprocess(name: str) -> str:
    """Return a raw API key for *name*, minting only when the cached one is dead.

    Uses a direct storage call, bypassing the ``must_change_password`` gate that
    blocks HTTP POST /api/auth/api-keys on fresh installs."""
    storage = _load_backend_auth_storage()
    cached = _read_cli_api_key_secret(name)
    if cached and storage.validate_api_key_with_credential(cached, touch = False):
        return cached

    raw_key, _row = storage.create_api_key(
        username = storage.DEFAULT_ADMIN_USERNAME,
        name = name,
    )
    # Best-effort: raising would kill a healthy launch and re-mint on every retry.
    try:
        _write_auth_secret(_cli_api_key_secret_path(name), raw_key)
    except OSError as exc:
        typer.echo(
            f"Warning: could not cache the {name} API key ({exc}); this launch is "
            "unaffected, but the next one will create another key.",
            err = True,
        )
    return raw_key


def _load_backend_auth_storage():
    run_py = _find_run_py()
    backend_dir = run_py.parent if run_py is not None else _PACKAGE_ROOT / "studio" / "backend"
    if backend_dir.is_dir() and str(backend_dir) not in sys.path:
        sys.path.insert(0, str(backend_dir))

    auth_dir = backend_dir / "auth"
    storage_py = auth_dir / "storage.py"
    loaded = sys.modules.get("auth.storage")
    if loaded is not None:
        loaded_path = Path(getattr(loaded, "__file__", None) or "").resolve()
        if loaded_path == storage_py.resolve():
            return loaded

    package = sys.modules.get("auth")
    package_paths = [Path(path).resolve() for path in getattr(package, "__path__", [])]
    if package is None or auth_dir.resolve() not in package_paths:
        package = types.ModuleType("auth")
        package.__path__ = [str(auth_dir)]
        package.__package__ = "auth"
        package.__file__ = str(auth_dir / "__init__.py")
        sys.modules["auth"] = package

    spec = importlib.util.spec_from_file_location("auth.storage", storage_py)
    if spec is None or spec.loader is None:
        raise ImportError(f"Could not load backend auth storage from {storage_py}")
    storage = importlib.util.module_from_spec(spec)
    sys.modules["auth.storage"] = storage
    spec.loader.exec_module(storage)

    return storage


def _write_auth_secret(path: Path, secret: str) -> None:
    path.parent.mkdir(parents = True, exist_ok = True)
    # mkdir under a 022 umask leaves auth/ world-readable; the listing names the files.
    try:
        os.chmod(path.parent, 0o700)
    except OSError:
        pass
    fd, tmp_name = tempfile.mkstemp(prefix = f".{path.name}.", dir = path.parent)
    tmp_path = Path(tmp_name)
    try:
        try:
            os.chmod(tmp_path, 0o600)
        except OSError:
            pass
        # newline pins LF: text mode writes CRLF and `$(cat ...)` leaves the CR on the credential.
        with os.fdopen(fd, "w", encoding = "utf-8", newline = "\n") as f:
            fd = -1
            f.write(secret + "\n")
        os.replace(tmp_path, path)
    except Exception:
        if fd >= 0:
            os.close(fd)
        tmp_path.unlink(missing_ok = True)
        raise
    try:
        os.chmod(path, 0o600)
    except OSError:
        pass


def _connect_auth_db() -> sqlite3.Connection:
    auth_dir = STUDIO_HOME / "auth"
    auth_dir.mkdir(parents = True, exist_ok = True)
    conn = sqlite3.connect(auth_dir / "auth.db")
    # A live server writes this DB while the CLI runs; the default lock wait is zero.
    conn.execute("PRAGMA busy_timeout=5000")
    # sqlite3.connect makes a new DB 0644 under a 022 umask; keep auth/ and auth.db private.
    for _path, _mode in ((auth_dir, 0o700), (auth_dir / "auth.db", 0o600)):
        try:
            os.chmod(_path, _mode)
        except OSError:
            pass
    conn.execute(
        """
        CREATE TABLE IF NOT EXISTS auth_user (
            id INTEGER PRIMARY KEY,
            username TEXT UNIQUE NOT NULL,
            password_salt TEXT NOT NULL,
            password_hash TEXT NOT NULL,
            jwt_secret TEXT NOT NULL,
            must_change_password INTEGER NOT NULL DEFAULT 0
        );
        """
    )
    conn.execute(
        """
        CREATE TABLE IF NOT EXISTS refresh_tokens (
            id INTEGER PRIMARY KEY,
            token_hash TEXT NOT NULL,
            username TEXT NOT NULL,
            expires_at TEXT NOT NULL,
            is_desktop INTEGER NOT NULL DEFAULT 0,
            secret_gen TEXT
        );
        """
    )
    conn.execute(
        """
        CREATE TABLE IF NOT EXISTS api_keys (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            username TEXT NOT NULL,
            key_prefix TEXT NOT NULL,
            key_hash TEXT NOT NULL UNIQUE,
            name TEXT NOT NULL DEFAULT '',
            created_at TEXT NOT NULL,
            last_used_at TEXT,
            expires_at TEXT,
            is_active INTEGER NOT NULL DEFAULT 1
        );
        """
    )
    conn.execute(
        """
        CREATE TABLE IF NOT EXISTS app_secrets (
            key TEXT PRIMARY KEY,
            value TEXT NOT NULL
        );
        """
    )
    auth_columns = {row[1] for row in conn.execute("PRAGMA table_info(auth_user)")}
    if "must_change_password" not in auth_columns:
        conn.execute(
            "ALTER TABLE auth_user ADD COLUMN must_change_password INTEGER NOT NULL DEFAULT 0"
        )
    refresh_columns = {row[1] for row in conn.execute("PRAGMA table_info(refresh_tokens)")}
    if "is_desktop" not in refresh_columns:
        conn.execute("ALTER TABLE refresh_tokens ADD COLUMN is_desktop INTEGER NOT NULL DEFAULT 0")
    if "secret_gen" not in refresh_columns:
        conn.execute("ALTER TABLE refresh_tokens ADD COLUMN secret_gen TEXT")
    conn.commit()
    return conn


def _pbkdf2_hex(value: str, salt: bytes) -> str:
    return hashlib.pbkdf2_hmac(
        "sha256",
        value.encode("utf-8"),
        salt,
        PBKDF2_ITERATIONS,
    ).hex()


def _hash_password(password: str) -> tuple[str, str]:
    salt = secrets.token_hex(16)
    pwd_hash = _pbkdf2_hex(password, salt.encode("utf-8"))
    return salt, pwd_hash


def _get_or_create_api_key_pbkdf2_salt(conn: sqlite3.Connection) -> bytes:
    row = conn.execute(
        "SELECT value FROM app_secrets WHERE key = ?",
        (API_KEY_PBKDF2_SALT_KEY,),
    ).fetchone()
    if row is None:
        salt_hex = secrets.token_hex(32)
        conn.execute(
            "INSERT OR IGNORE INTO app_secrets (key, value) VALUES (?, ?)",
            (API_KEY_PBKDF2_SALT_KEY, salt_hex),
        )
        row = conn.execute(
            "SELECT value FROM app_secrets WHERE key = ?",
            (API_KEY_PBKDF2_SALT_KEY,),
        ).fetchone()
    return bytes.fromhex(row[0])


def _ensure_cli_default_admin(conn: sqlite3.Connection) -> None:
    row = conn.execute(
        "SELECT 1 FROM auth_user WHERE username = ?",
        (DEFAULT_ADMIN_USERNAME,),
    ).fetchone()
    if row is not None:
        return

    bootstrap_password = secrets.token_urlsafe(32)
    password_salt, password_hash = _hash_password(bootstrap_password)
    conn.execute(
        """
        INSERT INTO auth_user (
            username,
            password_salt,
            password_hash,
            jwt_secret,
            must_change_password
        )
        VALUES (?, ?, ?, ?, ?)
        """,
        (
            DEFAULT_ADMIN_USERNAME,
            password_salt,
            password_hash,
            secrets.token_urlsafe(64),
            1,
        ),
    )
    _write_auth_secret(
        STUDIO_HOME / "auth" / BOOTSTRAP_PASSWORD_FILE,
        bootstrap_password,
    )


def _create_desktop_secret_in_cli() -> str:
    raw_secret = DESKTOP_SECRET_PREFIX + secrets.token_urlsafe(48)
    now = datetime.now(timezone.utc).isoformat()
    conn = _connect_auth_db()
    try:
        _ensure_cli_default_admin(conn)
        secret_hash = _pbkdf2_hex(raw_secret, _get_or_create_api_key_pbkdf2_salt(conn))
        conn.execute(
            "INSERT OR REPLACE INTO app_secrets (key, value) VALUES (?, ?)",
            (DESKTOP_SECRET_HASH_KEY, secret_hash),
        )
        conn.execute(
            "INSERT OR REPLACE INTO app_secrets (key, value) VALUES (?, ?)",
            (DESKTOP_SECRET_CREATED_AT_KEY, now),
        )
        conn.commit()
        return raw_secret
    finally:
        conn.close()


def _launch_publishes_tunnel(
    *, cloudflare: Optional[bool], host: str, secure: bool, api_only: bool
) -> bool:
    """Whether this launch will publish Unsloth through the Cloudflare tunnel. Kept separate from
    the wider _should_prompt_password_change, whose guards exist because a headless tunnel launch
    strips .bootstrap_password."""
    if secure:
        return True
    if cloudflare is not True:
        return False
    from unsloth_cli._tool_policy import is_wildcard_host

    return is_wildcard_host(host) and not api_only


def _bind_is_wildcard(host: str) -> bool:
    from unsloth_cli._tool_policy import is_wildcard_host
    return is_wildcard_host(host)


def _should_prompt_password_change(
    *, cloudflare: Optional[bool], host: str, secure: bool, api_only: bool
) -> bool:
    """Whether this launch puts Unsloth where someone else can reach it. is_external_host, NOT
    is_wildcard_host: the narrower test let an ordinary LAN bind reach an older child that served
    the seeded password. A raw bind counts only with a terminal attached, since downstream deletes
    .bootstrap_password and would break -H 0.0.0.0 containers."""
    if secure:
        return True
    if not host or api_only:
        return False
    from unsloth_cli._tool_policy import is_external_host, is_wildcard_host

    if cloudflare is True and is_wildcard_host(host):
        # A tunnel prompts regardless of the terminal; headless is handled downstream.
        return True
    return is_external_host(host) and _prompt_streams_interactive() and _prompt_owns_the_terminal()


def _prompt_streams_interactive() -> bool:
    try:
        return sys.stdin.isatty() and sys.stderr.isatty()
    except (AttributeError, ValueError):
        return False


# Wait for the FIRST keystroke only. 30s stays inside a default Docker HEALTHCHECK start period.
_UNATTENDED_PROMPT_SECONDS = 30.0


def _prompt_owns_the_terminal() -> bool:
    """Whether this process may DRIVE the terminal, not merely see one: a backgrounded job passes
    isatty() but read_masked's tcsetattr SIGTTOUs it and freezes the launch. True on any doubt."""
    try:
        return os.tcgetpgrp(sys.stdin.fileno()) == os.getpgrp()
    except (AttributeError, OSError, ValueError):
        return True


def _bootstrap_deadline_active() -> bool:
    """Whether the backend's bootstrap shutdown deadline will arm. Mirror of
    studio/backend/auth/bootstrap_timeout.py: malformed falls back to the 1h default, 0 disables."""
    raw = os.environ.get("UNSLOTH_STUDIO_BOOTSTRAP_TIMEOUT", "").strip()
    if not raw:
        return True
    try:
        return int(raw) > 0
    except ValueError:
        return True


# Set by the parent after an unanswered prompt so the re-exec'd child does not repeat the wait.
_UNATTENDED_PROMPT_DONE_ENV = "UNSLOTH_STUDIO_UNATTENDED_PROMPT_DONE"


def _deadline_sentence() -> str:
    """Say only what happens: BOOTSTRAP_TIMEOUT=0 arms no deadline, so promising one misleads."""
    if _bootstrap_deadline_active():
        return (
            "Unsloth shuts down after the bootstrap deadline "
            "(UNSLOTH_STUDIO_BOOTSTRAP_TIMEOUT, default 1h) unless the password "
            "is changed."
        )
    return (
        "The bootstrap shutdown deadline is DISABLED for this launch "
        "(UNSLOTH_STUDIO_BOOTSTRAP_TIMEOUT=0), so nothing will stop it serving "
        "that credential."
    )


def _generate_reset_password() -> str:
    try:
        import diceware
        return diceware.get_passphrase(
            options = diceware.handle_options(args = ["-n", "4", "-d", "", "-c"])
        )
    except Exception:
        return secrets.token_urlsafe(24)


def _cli_update_password(
    conn: sqlite3.Connection,
    username: str,
    new_password: str,
    *,
    revoke_api_keys: bool = False,
) -> None:
    """CLI mirror of backend update_password + change-password effects, in one transaction. File
    cleanup runs after commit, so it cannot roll back."""
    password_salt, password_hash = _hash_password(new_password)
    columns = {row[1] for row in conn.execute("PRAGMA table_info(auth_user)")}
    # Managed credentials live in the account_* columns behind the downgrade fence; the owner's row keeps the legacy columns.
    managed = False
    if "account_jwt_secret" in columns:
        row = conn.execute("SELECT role FROM auth_user WHERE username = ?", (username,)).fetchone()
        managed = bool(row) and row[0] not in (None, "owner")
    target_columns = (
        "account_password_salt = ?, account_password_hash = ?, account_jwt_secret = ?"
        if managed
        else "password_salt = ?, password_hash = ?, jwt_secret = ?"
    )
    with conn:
        conn.execute(
            f"""
            UPDATE auth_user
            SET {target_columns}, must_change_password = 0
            WHERE username = ?
            """,
            (password_salt, password_hash, secrets.token_urlsafe(64), username),
        )
        conn.execute("DELETE FROM refresh_tokens WHERE username = ?", (username,))
        if username == DEFAULT_ADMIN_USERNAME:
            conn.execute(
                "DELETE FROM app_secrets WHERE key IN (?, ?)",
                (DESKTOP_SECRET_HASH_KEY, DESKTOP_SECRET_CREATED_AT_KEY),
            )
        if revoke_api_keys:
            conn.execute("DELETE FROM api_keys WHERE username = ?", (username,))
            if managed:
                conn.execute(
                    "DELETE FROM account_api_keys WHERE account_id = "
                    "(SELECT account_id FROM auth_user WHERE username = ?)",
                    (username,),
                )
            columns = {row[1] for row in conn.execute("PRAGMA table_info(auth_user)")}
            if "setup_code_hash" in columns:
                conn.execute(
                    "UPDATE auth_user SET setup_code_hash = NULL, setup_code_expires_at = NULL WHERE username = ?",
                    (username,),
                )
    if username != DEFAULT_ADMIN_USERNAME:
        return
    stale_files = [BOOTSTRAP_PASSWORD_FILE, DESKTOP_SECRET_FILE]
    if revoke_api_keys:
        # Reset only: the rows are gone, so each cached key is plaintext for a dead credential.
        try:
            stale_files += sorted(
                p.name for p in (STUDIO_HOME / "auth").glob(f"{CLI_API_KEY_FILE_PREFIX}*")
            )
        except OSError:
            pass
    for stale in stale_files:
        stale_path = STUDIO_HOME / "auth" / stale
        try:
            stale_path.unlink(missing_ok = True)
        except OSError as exc:
            # The hash is committed, so a failed unlink must not roll back, but a locked-yet-writable file must be truncated or its plaintext re-validates the credential.
            try:
                stale_path.write_text("", encoding = "utf-8")
                cleared = True
            except OSError:
                cleared = False
            if cleared:
                typer.echo(
                    f"Warning: could not remove stale {stale} file ({exc}); cleared its "
                    "contents so the old credential cannot be reused.",
                    err = True,
                )
            else:
                typer.echo(
                    f"Warning: could not remove or clear stale {stale} file ({exc}); the "
                    "old credential is still on disk. Remove it manually to prevent reuse "
                    "after a reset.",
                    err = True,
                )


def _apply_supplied_password_before_launch(supplied_password: "str | None") -> None:
    """Set the INITIAL admin password before the server binds, and only the first: an override would
    be an auth bypass; the parent runs it so the secret stays out of child argv."""
    if not supplied_password:
        return
    try:
        conn = _connect_auth_db()
    except (OSError, sqlite3.Error) as exc:
        typer.echo(
            f"Error: --password could not open the Unsloth auth database ({exc}); not starting.",
            err = True,
        )
        raise typer.Exit(1)
    try:
        _ensure_cli_default_admin(conn)
        conn.commit()
        row = conn.execute(
            "SELECT password_salt, password_hash, must_change_password "
            "FROM auth_user WHERE username = ?",
            (DEFAULT_ADMIN_USERNAME,),
        ).fetchone()
        if not row:
            typer.echo(
                "Error: --password could not initialize the admin account; not starting.",
                err = True,
            )
            raise typer.Exit(1)
        if not row[2]:
            typer.echo(
                "Error: an Unsloth admin password is already set; --password only sets "
                "the initial password. Change it in the UI, or run `unsloth studio "
                "reset-password` for a new one.",
                err = True,
            )
            raise typer.Exit(1)
        password_salt, password_hash = row[0], row[1]

        def _is_current_password(candidate: str) -> bool:
            return hmac.compare_digest(
                _pbkdf2_hex(candidate, password_salt.encode("utf-8")), password_hash
            )

        problem = _password_prompt.validate_new_password(supplied_password, _is_current_password)
        if problem is not None:
            typer.echo(f"Error: {problem} Not starting.", err = True)
            raise typer.Exit(1)
        _cli_update_password(conn, DEFAULT_ADMIN_USERNAME, supplied_password)
        typer.echo(f"Password updated for '{DEFAULT_ADMIN_USERNAME}'.", err = True)
    except (OSError, sqlite3.Error) as exc:
        # Fail closed on any DB failure (typer.Exit from the branches above propagates).
        typer.echo(
            f"Error: --password could not update the Unsloth auth database ({exc}); not starting.",
            err = True,
        )
        raise typer.Exit(1)
    finally:
        conn.close()


def _strip_seeded_bootstrap_password_or_exit(*, context: str) -> None:
    """Remove the seeded plaintext bootstrap password before a public re-exec, so a child of ANY
    version reads None. Removal IS the protection, so a failed removal fails closed."""
    bootstrap_file = STUDIO_HOME / "auth" / BOOTSTRAP_PASSWORD_FILE
    try:
        bootstrap_file.unlink(missing_ok = True)
    except OSError as exc:
        typer.echo(
            "Error: refusing to publish Unsloth on a public Cloudflare URL: "
            f"could not remove the seeded bootstrap password file ({exc}), so an "
            f"older Unsloth child could still serve the default credential ({context}). "
            "Delete it manually or change the admin password (run `unsloth studio` "
            "locally with a terminal attached, or `unsloth studio reset-password`), "
            "then retry.",
            err = True,
        )
        raise typer.Exit(1)


def _require_servable_frontend_or_exit(
    *, frontend: Optional[Path], api_only: bool, cloudflare: Optional[bool], host: str, secure: bool
) -> Optional[Path]:
    """Fail closed BEFORE the pre-exposure gate if a public UI launch has no login page: the gate
    strips .bootstrap_password, and the login page is the only in-band way to change it."""
    if api_only or not _launch_publishes_tunnel(
        cloudflare = cloudflare, host = host, secure = secure, api_only = api_only
    ):
        return frontend
    if frontend is not None:
        # A user-supplied dist is not vetted, so `--frontend /bad/path` would otherwise bypass the guard.
        if (Path(frontend) / "index.html").is_file():
            return frontend
        typer.echo(
            "Error: --frontend points at a directory with no index.html, so a "
            "public Unsloth launch would have no login page to change the seeded "
            "admin password. Point --frontend at a built dist, rebuild it (re-run "
            "install.sh), or use --api-only.",
            err = True,
        )
        raise typer.Exit(1)
    resolved = _find_frontend_dist()
    if resolved is not None:
        return resolved
    typer.echo(
        "Error: the Unsloth frontend is not built, so a public launch would have "
        "no login page to change the seeded admin password. Build it (re-run "
        "install.sh), pass --frontend PATH to a built dist, or use --api-only.",
        err = True,
    )
    raise typer.Exit(1)


def _validate_inproc_backend_before_strip(
    *, cloudflare: Optional[bool], host: str, secure: bool, api_only: bool
) -> None:
    """In-venv analogue of the re-exec launcher check: import the backend before the gate strips
    .bootstrap_password. Headless only, so no prompt waits on the import."""
    if not _launch_publishes_tunnel(
        cloudflare = cloudflare, host = host, secure = secure, api_only = api_only
    ):
        return
    if _prompt_streams_interactive():
        return
    try:
        _load_run_module()
    except Exception as exc:
        typer.echo(
            f"Error: the Unsloth backend could not be loaded ({exc}); refusing to "
            "expose Unsloth publicly before it is confirmed runnable. Re-run: "
            "unsloth studio setup",
            err = True,
        )
        raise typer.Exit(1)


def _tunnel_binary_confirmed_unavailable() -> bool:
    """True only if cloudflared is provably unavailable, so --secure can keep the seeded recovery
    password. False on ANY uncertainty: a leak outweighs a recoverable lockout."""
    run_py = _find_run_py()
    if run_py is None:
        return False
    backend_dir = run_py.parent
    tunnel_py = backend_dir / "cloudflare_tunnel.py"
    if not tunnel_py.is_file():
        return False
    # ensure_cloudflared() imports utils.paths lazily; without studio/backend on sys.path it returns a false "unavailable" that wrongly refuses --secure.
    added_backend_path = False
    try:
        if str(backend_dir) not in sys.path:
            sys.path.insert(0, str(backend_dir))
            added_backend_path = True
        spec = importlib.util.spec_from_file_location("studio.backend.cloudflare_tunnel", tunnel_py)
        if spec is None or spec.loader is None:
            return False
        module = importlib.util.module_from_spec(spec)
        spec.loader.exec_module(module)
        return module.ensure_cloudflared() is None
    except Exception:
        return False
    finally:
        if added_backend_path:
            try:
                sys.path.remove(str(backend_dir))
            except ValueError:
                pass


def _child_self_suppresses(*, in_studio_venv: bool, child_run_py: Optional[Path]) -> bool:
    """True when the child serving Unsloth is provably THIS install's backend, which suppresses the
    seeded credential, so the strip can be skipped. False on ANY doubt."""
    if in_studio_venv:
        return True
    if child_run_py is None:
        return False
    try:
        outer_run_py = (_PACKAGE_ROOT / "studio" / "backend" / "run.py").resolve()
        return child_run_py.resolve() == outer_run_py
    except OSError:
        return False


def _enforce_password_change_before_exposure(
    *,
    cloudflare: Optional[bool],
    host: str,
    secure: bool,
    api_only: bool,
    child_self_suppresses: bool = False,
) -> None:
    """Force a terminal password change before the first public (tunnel) exposure. Committing in the
    parent keeps it off argv/env; without a terminal, fall back to the bootstrap shutdown timer."""
    if not _should_prompt_password_change(
        cloudflare = cloudflare, host = host, secure = secure, api_only = api_only
    ):
        return
    # Use the real predicate, not `cloudflare is True`: a non-secure tunnel only starts for a wildcard host.
    tunnel_will_start = _launch_publishes_tunnel(
        cloudflare = cloudflare, host = host, secure = secure, api_only = api_only
    )
    if not tunnel_will_start and os.environ.get(_UNATTENDED_PROMPT_DONE_ENV):
        # The outer CLI already waited out this terminal. Peeked, never popped (run.py consumes it); never for a tunnel, which fails closed.
        return
    if tunnel_will_start:
        exposure = "on a public Cloudflare URL"
    elif _bind_is_wildcard(host):
        exposure = "on every network interface"
    else:
        # A concrete bind listens on that address only, so "every network interface" is untrue.
        exposure = f"at {host}, which other machines on the network can reach"
    # Before public exposure we must PROVE the password is not the seeded default; an old child could regenerate one. Unprovable fails closed.
    try:
        conn = _connect_auth_db()
    except (OSError, sqlite3.Error) as exc:
        # Cannot confirm a committed admin exists; a transient lock clears on retry.
        typer.echo(
            f"Error: refusing to expose Unsloth {exposure}: could "
            f"not open the Unsloth auth database ({exc}) to confirm the admin "
            "password was changed. Retry (a transient database lock clears), or "
            "change the password first (run `unsloth studio` locally with a "
            "terminal attached, or `unsloth studio reset-password`).",
            err = True,
        )
        raise typer.Exit(1)
    try:
        try:
            _ensure_cli_default_admin(conn)
            # Persist a freshly seeded admin before any re-exec: uncommitted it rolls back on close and an OLD child would regenerate its own.
            conn.commit()
        except (OSError, sqlite3.Error) as exc:
            # Best-effort remove any half-written seed file; the launch is refused regardless.
            try:
                (STUDIO_HOME / "auth" / BOOTSTRAP_PASSWORD_FILE).unlink(missing_ok = True)
            except OSError:
                pass
            typer.echo(
                f"Error: refusing to expose Unsloth {exposure}: could "
                f"not initialize the admin account ({exc}), so a re-exec'd Unsloth "
                "child could regenerate and serve a default credential. Retry (a "
                "transient database lock clears), or change the password first (run "
                "`unsloth studio` locally with a terminal attached, or `unsloth "
                "studio reset-password`).",
                err = True,
            )
            raise typer.Exit(1)
        try:
            row = conn.execute(
                "SELECT password_salt, password_hash, must_change_password "
                "FROM auth_user WHERE username = ?",
                (DEFAULT_ADMIN_USERNAME,),
            ).fetchone()
        except (OSError, sqlite3.Error) as exc:
            if child_self_suppresses:
                # The child suppresses the injection, so nothing serves the seeded credential.
                return
            # The admin is committed, so an old child will not regenerate; strip anyway and fail closed.
            typer.echo(
                f"Warning: could not read the Unsloth admin state back ({exc}); "
                "removing the seeded bootstrap password before public exposure.",
                err = True,
            )
            _strip_seeded_bootstrap_password_or_exit(context = "auth DB row unreadable")
            return
        if not row or not row[2]:
            return
        if not _prompt_streams_interactive():
            # Only proceed headless if the bootstrap deadline protects the launch: it never arms for api-only, and TIMEOUT=0 disables it.
            if api_only or not _bootstrap_deadline_active():
                typer.echo(
                    "Error: refusing to publish Unsloth on a public Cloudflare "
                    "URL: the default admin password was never changed, no "
                    "terminal is attached to change it here, and the bootstrap "
                    "shutdown deadline does not apply to this launch (api-only, "
                    "or UNSLOTH_STUDIO_BOOTSTRAP_TIMEOUT=0). Change the "
                    "password first (run `unsloth studio` locally and log in, "
                    "or re-run with a terminal attached), then retry.",
                    err = True,
                )
                raise typer.Exit(1)
            if child_self_suppresses:
                # The child is this install's own backend and never serves the seeded credential publicly, so skip the strip and keep the file for LOCAL recovery.
                typer.echo(
                    "Warning: Unsloth is being exposed publicly while the admin "
                    "account still uses its auto-generated bootstrap password. The "
                    "login page forces a change and the credential is never served "
                    "on the public page. Set a new password by running `unsloth "
                    "studio` locally with a terminal attached, or `unsloth studio "
                    "reset-password`; Unsloth shuts down after ~1h if the password "
                    "stays unchanged (UNSLOTH_STUDIO_BOOTSTRAP_TIMEOUT).",
                    err = True,
                )
                return
            # On --secure the bind is loopback, so with cloudflared provably unavailable stripping the only recovery credential would just lock the user out.
            if secure and _tunnel_binary_confirmed_unavailable():
                typer.echo(
                    "Error: refusing to expose Unsloth: the Cloudflare tunnel binary "
                    "(cloudflared) is unavailable and could not be downloaded, so no "
                    "public URL can start. The seeded bootstrap password is preserved "
                    "for recovery; fix connectivity and retry, or change the password "
                    "first (`unsloth studio` locally, or `unsloth studio "
                    "reset-password`).",
                    err = True,
                )
                raise typer.Exit(1)
            # An OLD studio-venv child would serve the seeded credential from disk, so delete it here in the parent; must_change_password stays set.
            _strip_seeded_bootstrap_password_or_exit(context = "no terminal to change it")
            typer.echo(
                "Warning: Unsloth is being exposed publicly while the admin account "
                "still uses its auto-generated bootstrap password. The seeded password "
                "file has been removed so it is not served on the public page. Set a new "
                "password by running `unsloth studio` locally with a terminal attached, "
                "or `unsloth studio reset-password`; Unsloth shuts down after ~1h if the "
                "password stays unchanged (UNSLOTH_STUDIO_BOOTSTRAP_TIMEOUT).",
                err = True,
            )
            return
        password_salt, password_hash = row[0], row[1]

        def _is_current_password(candidate: str) -> bool:
            return hmac.compare_digest(
                _pbkdf2_hex(candidate, password_salt.encode("utf-8")), password_hash
            )

        typer.echo(
            f"Unsloth Studio will be reachable {exposure}, so set a password now. "
            "Ctrl+C to abort.",
            err = True,
        )
        try:
            new_password = _password_prompt.prompt_new_password(
                _is_current_password,
                # A raw bind must never block a launch that used to start: a detached pty passes every isatty test yet nobody types. A tunnel fails closed.
                first_key_timeout = None if tunnel_will_start else _UNATTENDED_PROMPT_SECONDS,
            )
        except _password_prompt.PromptUnattended:
            typer.echo(
                "Warning: no response at the terminal, so Unsloth is starting with "
                "the auto-generated admin password on a bind that is reachable from "
                f"the network. {_deadline_sentence()} Change it by logging in, or "
                "with `unsloth studio reset-password`.",
                err = True,
            )
            # Tell the child the terminal has been tried, or it waits its own deadline on the same pty and can trip a startup watchdog.
            os.environ[_UNATTENDED_PROMPT_DONE_ENV] = "1"
            return
        except (KeyboardInterrupt, EOFError):
            # An abort needs the non-interactive hatch more than the old warn did.
            typer.echo(
                "\nError: password change aborted; refusing to expose Unsloth "
                "with the default admin password. Re-run and set a password, or "
                "pass one with --password / UNSLOTH_STUDIO_PASSWORD, or "
                + (
                    "launch without --secure/--cloudflare."
                    if tunnel_will_start
                    else "launch with -H 127.0.0.1 to stay off the network."
                ),
                err = True,
            )
            raise typer.Exit(1)
        _cli_update_password(conn, DEFAULT_ADMIN_USERNAME, new_password)
        typer.echo(f"Password updated for '{DEFAULT_ADMIN_USERNAME}'.", err = True)
    finally:
        conn.close()


def _parse_gpu_ids(value: Optional[str]) -> Optional[List[int]]:
    if value is None or not value.strip():
        return None
    try:
        ids = [int(part) for part in value.split(",") if part.strip()]
    except ValueError:
        raise ValueError(f"--gpus takes comma-separated GPU indices such as 0,1, not {value!r}.")
    if any(i < 0 for i in ids) or len(set(ids)) != len(ids):
        raise ValueError(f"--gpus needs distinct, non-negative GPU indices, not {value!r}.")
    return ids or None


def _load_model_via_http(
    port: int,
    api_key: str,
    model: str,
    gguf_variant: Optional[str],
    max_seq_length: int,
    load_in_4bit: bool,
    gpu_memory_mode: Literal["auto", "manual"] = "auto",
    tensor_parallel: bool = False,
    speculative_type: Optional[SpeculativeType] = None,
    spec_draft_n_max: Optional[int] = None,
    llama_extra_args: Optional[List[str]] = None,
    timeout: int = 600,
    request_host: str = "127.0.0.1",
    engine: str = "auto",
    engine_precision: str = "auto",
    engine_parallelism: str = "tensor",
    gpu_ids: Optional[List[int]] = None,
) -> dict:
    import json
    import urllib.request
    import urllib.error

    from unsloth_cli._inference import raise_for_deferred_error, require_completed_padded_body

    payload: dict = {
        "model_path": model,
        "max_seq_length": max_seq_length,
        "load_in_4bit": load_in_4bit,
    }
    if gguf_variant:
        payload["gguf_variant"] = gguf_variant
    if gpu_memory_mode == "manual":
        payload["gpu_memory_mode"] = "manual"
        payload["gpu_layers"] = -1
    if tensor_parallel:
        payload["tensor_parallel"] = True
    if speculative_type is not None:
        payload["speculative_type"] = speculative_type
    if spec_draft_n_max is not None:
        payload["spec_draft_n_max"] = spec_draft_n_max
    if llama_extra_args:
        payload["llama_extra_args"] = list(llama_extra_args)
    if engine != "auto":
        payload["engine"] = engine
        payload["engine_precision"] = engine_precision
        if engine_parallelism != "tensor":
            payload["engine_parallelism"] = engine_parallelism
    if gpu_ids:
        payload["gpu_ids"] = list(gpu_ids)

    data = json.dumps(payload).encode()
    url = f"http://{_url_host(request_host)}:{port}/api/inference/load"
    req = urllib.request.Request(
        url,
        data = data,
        headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {api_key}",
        },
        method = "POST",
    )
    try:
        with _direct_urlopen(req, timeout = timeout) as resp:
            try:
                body = json.loads(resp.read())
            except ValueError:
                body = None
        # A slow load commits its 200 early and pads the body, so a late failure arrives in-band.
        return require_completed_padded_body(url, raise_for_deferred_error(url, body))
    except urllib.error.HTTPError as exc:
        body = exc.read().decode(errors = "replace")
        raise RuntimeError(f"Model load failed (HTTP {exc.code}): {body}") from exc


def _ensure_engine_installed(engine: str, yes: bool, silent: bool) -> None:
    """Install an optional serving engine on first use, only after the owner agrees."""
    import time

    from core.inference import engine_install

    # status() answers "still checking" while the GPU probe runs; this caller can wait for it.
    reason = engine_install.support_reason(engine)
    if reason:
        raise RuntimeError(reason)
    row = engine_install.status(engine)
    # A rollback the owner chose is loadable as is, as in Settings.
    if row.get("current") or (row.get("installed") and row.get("restored")):
        return
    size = row.get("download_bytes")
    action = "Update" if row.get("installed") else "Install"
    question = f"{action} {engine} {row['version']}" + (
        f" (about {size / 1024**3:.1f} GiB to download)" if size else ""
    )
    notice = _engine_install_notice(engine, row)
    if not yes:
        if not sys.stdin.isatty():
            raise RuntimeError(
                f"{engine} is not installed. Re-run with --yes to install it, or install it "
                "from Settings > Inference engines."
            )
        if notice:
            typer.echo(notice)
        if not typer.confirm(f"{question}?", default = False):
            raise RuntimeError(f"{engine} was not installed, so the model was not loaded.")
    elif not silent:
        if notice:
            typer.echo(notice)
        typer.echo(f"{question}: --yes given, installing.")
    engine_install.start_install(engine)
    last = None
    while True:
        job = engine_install.status(engine)["job"]
        if job.get("state") != "running":
            break
        message = job.get("message") or job.get("phase")
        if message != last and not silent:
            typer.echo(f"  {engine}: {message}")
            last = message
        time.sleep(2)
    if job.get("state") != "success":
        raise RuntimeError(f"{engine} installation did not finish: {job.get('message')}")


def _engine_install_notice(engine: str, row: dict) -> Optional[str]:
    """The Windows consent text Settings shows before the same install (managedEngines.wsl*)."""
    if row.get("host") != "wsl":
        return None
    wsl = row.get("wsl") or {}
    if wsl.get("state") == "restart_required":
        return "Restart Windows to finish turning on WSL2, then run this command again."
    if wsl.get("state") == "ready" and wsl.get("distro"):
        return f"On Windows, {engine} runs inside Unsloth Studio's private WSL2 environment."
    return (
        f"On Windows, {engine} runs inside WSL2 (Windows Subsystem for Linux). Unsloth Studio will turn "
        "on WSL2 and set up its own private Ubuntu environment for engines; your existing Linux "
        "distributions are not touched. Windows will show one administrator (UAC) prompt, and "
        "may ask you to restart before the installation can finish. Nothing changes unless you "
        "answer yes."
    )


def _format_context_length_line(load_result: dict) -> Optional[str]:
    value = load_result.get("context_length")
    if isinstance(value, bool):
        return None
    try:
        value_int = int(value)
    except (TypeError, ValueError):
        return None
    if value_int <= 0:
        return None
    return f"  Context length: {value_int} tokens"


_MODELS_DIRS_ENV = "UNSLOTH_STUDIO_MODELS_DIRS"


def _export_models_dirs(models_dir: Optional[List[Path]]) -> None:
    """Hand --models-dir to the backend through the env, which both launch paths keep; the backend adds each as a Custom Folder."""
    if not models_dir:
        return
    resolved = []
    for raw in models_dir:
        path = Path(raw).expanduser()
        if not path.is_dir():
            typer.echo(f"Error: --models-dir {raw} is not an existing folder.", err = True)
            raise typer.Exit(2)
        resolved_path = str(path.resolve())
        if os.pathsep in resolved_path:
            typer.echo(
                f"Error: --models-dir {raw} contains '{os.pathsep}', which cannot be passed "
                "to Unsloth Studio. Rename the folder or add it from Custom Folders in the model picker.",
                err = True,
            )
            raise typer.Exit(2)
        resolved.append(resolved_path)
    existing = [p for p in os.environ.get(_MODELS_DIRS_ENV, "").split(os.pathsep) if p]
    merged = list(dict.fromkeys(existing + resolved))
    os.environ[_MODELS_DIRS_ENV] = os.pathsep.join(merged)


@studio_app.callback(invoke_without_command = True)
def studio_default(
    ctx: typer.Context,
    port: int = typer.Option(8888, "--port", "-p"),
    host: str = typer.Option("127.0.0.1", "--host", "-H"),
    frontend: Optional[Path] = typer.Option(None, "--frontend", "-f"),
    silent: bool = typer.Option(False, "--silent", "-q"),
    api_only: bool = typer.Option(
        False,
        "--api-only",
        help = "Run API server only, no frontend serving (for Tauri desktop app)",
    ),
    parallel: int = typer.Option(
        _PARALLEL_DEFAULT_PLAIN,
        "--parallel",
        "--n-parallel",
        min = _PARALLEL_MIN,
        max = _PARALLEL_MAX,
        help = (
            f"llama-server parallel decode slots ({_PARALLEL_MIN}..{_PARALLEL_MAX}). "
            f"Default {_PARALLEL_DEFAULT_PLAIN}. The Unsloth run settings "
            "(Parallel Slots) override it per load."
        ),
    ),
    cloudflare: Optional[bool] = typer.Option(
        None,
        "--cloudflare/--no-cloudflare",
        help = "Expose Unsloth on a PUBLIC internet URL via a free Cloudflare HTTPS "
        "tunnel, for non-api-only wildcard binds (0.0.0.0 or ::). Off by default; "
        "pass --cloudflare to enable it (--secure implies it). The Remote access "
        "'Start automatically' setting also starts one on every launch, on any host. "
        "--no-cloudflare forces both off but does not change a raw wildcard bind.",
    ),
    secure: bool = typer.Option(
        False,
        "--secure/--no-secure",
        help = "Expose ONLY a Cloudflare HTTPS link: bind localhost and fail closed "
        "if the tunnel can't start. Without it, --no-secure also serves the raw "
        "0.0.0.0 port, which is reachable from anywhere on the network.",
    ),
    not_secure: bool = typer.Option(
        False,
        "--not-secure",
        hidden = True,
        help = "Deprecated alias for --no-secure.",
    ),
    verbose: bool = typer.Option(
        False,
        "--verbose",
        "-v",
        help = "Log every API request, including the high-frequency polling that is "
        "deduplicated by default.",
    ),
    enable_tools: Optional[bool] = typer.Option(
        None,
        "--enable-tools/--disable-tools",
        help = "Force server-side tools (web search, code execution) on or off for "
        "every request. Default: no server-wide policy, so the per-chat UI toggle "
        "(the request's own enable_tools) decides; `unsloth studio run` is the "
        "launcher that defaults them on. /v1/messages takes the on direction per "
        "request (enable_tools) because it has no confirmation channel; the off "
        "direction still applies everywhere.",
    ),
    disable_dns_pinning: bool = typer.Option(
        False,
        "--disable-dns-pinning",
        help = "Send the hostname (not the validated IP) in web fetches that go through an "
        "explicitly configured HTTP(S)_PROXY, so the proxy can apply hostname policy and "
        "TLS interception. Direct fetches stay pinned to the validated IP.",
    ),
    password: str = typer.Option(
        "",
        "--password",
        help = "Set the INITIAL admin password non-interactively (headless setups), "
        "only when none is set yet. Also reads the UNSLOTH_STUDIO_PASSWORD env var, or "
        "`--password -` to read one line from stdin. A literal value is visible in the "
        "process list and shell history. Rotate later with `unsloth studio reset-password`.",
    ),
    ssl_certfile: Optional[Path] = typer.Option(
        None,
        "--ssl-certfile",
        help = "Serve HTTPS with this certificate (PEM, full chain), e.g. a Tailscale or "
        "Let's Encrypt .crt. Needs --ssl-keyfile. Not combinable with --secure / --cloudflare.",
    ),
    ssl_keyfile: Optional[Path] = typer.Option(
        None,
        "--ssl-keyfile",
        help = "Private key (PEM) for --ssl-certfile.",
    ),
    models_dir: Optional[List[Path]] = typer.Option(
        None,
        "--models-dir",
        help = "Add a folder of local models to Unsloth Studio (repeatable). It is saved as a "
        "Custom Folder, so its models show up in the Chat and Train model pickers on this "
        "and later launches; remove it from Custom Folders in the model picker.",
    ),
):
    """Launch the Unsloth Studio server."""
    # --not-secure is a deprecated alias for --no-secure.
    secure = _resolve_secure(secure, not_secure)
    _ensure_studio_env_exported()
    _export_models_dirs(models_dir)
    if ctx.invoked_subcommand is not None:
        # Typer does not forward parent options, so `unsloth studio --parallel N run` would drop N.
        if parallel != _PARALLEL_DEFAULT_PLAIN:
            typer.echo(
                f"Error: --parallel on `unsloth studio` applies to the "
                f"plain-server path only. For `unsloth studio "
                f"{ctx.invoked_subcommand}`, put the flag after the "
                f"subcommand: `unsloth studio {ctx.invoked_subcommand} "
                f"--parallel {parallel} ...`",
                err = True,
            )
            raise typer.Exit(2)
        if cloudflare is not None:
            _cf_flag = "--cloudflare" if cloudflare else "--no-cloudflare"
            typer.echo(
                f"Error: {_cf_flag} on `unsloth studio` applies to the "
                f"plain-server path only. For `unsloth studio "
                f"{ctx.invoked_subcommand}`, put it after the subcommand: "
                f"`unsloth studio {ctx.invoked_subcommand} {_cf_flag} ...`",
                err = True,
            )
            raise typer.Exit(2)
        if secure:
            typer.echo(
                f"Error: --secure on `unsloth studio` applies to the "
                f"plain-server path only. For `unsloth studio "
                f"{ctx.invoked_subcommand}`, put it after the subcommand: "
                f"`unsloth studio {ctx.invoked_subcommand} --secure ...`",
                err = True,
            )
            raise typer.Exit(2)
        if verbose:
            typer.echo(
                f"Error: --verbose on `unsloth studio` applies to the "
                f"plain-server path only. For `unsloth studio "
                f"{ctx.invoked_subcommand}`, put it after the subcommand: "
                f"`unsloth studio {ctx.invoked_subcommand} --verbose ...`",
                err = True,
            )
            raise typer.Exit(2)
        if enable_tools is not None:
            _tool_flag = "--enable-tools" if enable_tools else "--disable-tools"
            typer.echo(
                f"Error: {_tool_flag} on `unsloth studio` applies to the "
                f"plain-server path only. For `unsloth studio "
                f"{ctx.invoked_subcommand}`, put it after the subcommand: "
                f"`unsloth studio {ctx.invoked_subcommand} {_tool_flag} ...`",
                err = True,
            )
            raise typer.Exit(2)
        if disable_dns_pinning:
            typer.echo(
                "Error: --disable-dns-pinning on `unsloth studio` applies to the "
                f"plain-server path only. For `unsloth studio {ctx.invoked_subcommand}`, "
                f"put it after the subcommand: `unsloth studio {ctx.invoked_subcommand} "
                "--disable-dns-pinning ...`",
                err = True,
            )
            raise typer.Exit(2)
        if api_only:
            typer.echo(
                f"Error: --api-only on `unsloth studio` applies to the "
                f"plain-server path only. For `unsloth studio "
                f"{ctx.invoked_subcommand}`, put it after the subcommand: "
                f"`unsloth studio {ctx.invoked_subcommand} --api-only ...`",
                err = True,
            )
            raise typer.Exit(2)
        if password:
            typer.echo(
                f"Error: --password on `unsloth studio` applies to the "
                f"plain-server path only. For `unsloth studio "
                f"{ctx.invoked_subcommand}`, put it after the subcommand: "
                f"`unsloth studio {ctx.invoked_subcommand} --password ...`",
                err = True,
            )
            raise typer.Exit(2)
        if ssl_certfile is not None or ssl_keyfile is not None:
            typer.echo(
                "Error: --ssl-certfile/--ssl-keyfile apply to `unsloth studio` itself, "
                f"not to `unsloth studio {ctx.invoked_subcommand}`.",
                err = True,
            )
            raise typer.Exit(2)
        return

    _require_bind_host(host)
    _require_valid_tls_flags(ssl_certfile, ssl_keyfile, secure = secure, cloudflare = cloudflare)
    runtime_gate_handoff = _studio_runtime_gate.consume_runtime_gate_handoff()
    runtime_gate_acquire = _studio_runtime_gate.consume_runtime_gate_acquire()
    _preserve_cloudflare_intent(cloudflare, secure)

    # --secure requires the tunnel; force a loopback bind.
    if secure:
        if cloudflare is False:
            typer.echo(
                "Error: --secure requires the Cloudflare tunnel; do not combine it "
                "with --no-cloudflare.",
                err = True,
            )
            raise typer.Exit(2)
        if host not in ("127.0.0.1", "localhost", "::1"):
            typer.echo(
                "Note: --secure ignores -H (it binds loopback and serves only "
                "through the Cloudflare tunnel). Drop --secure to bind "
                f"{host} directly, or keep --secure for a tunnel-only public link.",
                err = True,
            )
        host = "127.0.0.1"

    host = _normalize_wildcard_bind_host(host)
    _require_unambiguous_ephemeral_bind(host, port)

    # --verbose restores the per-request access logs suppressed by default.
    if verbose:
        _enable_verbose_access_logs()
    if disable_dns_pinning:
        os.environ["UNSLOTH_STUDIO_DISABLE_DNS_PINNING"] = "1"
    else:
        os.environ.setdefault("UNSLOTH_STUDIO_DISABLE_DNS_PINNING", "0")

    # Resolve the child launcher BEFORE the gate: a headless gate strips the seeded password, so aborting afterwards leaves no way to log in.
    studio_venv_dir = STUDIO_HOME / "unsloth_studio"
    in_studio_venv = _running_in_studio_venv(studio_venv_dir)
    # Before the env reaches a child: an override contradicting single-arch wheels fails every kernel launch, and install.sh's unset cannot reach here (#7331).
    _clear_hsa_override_before_launch(silent = silent)
    studio_python = run_py = None
    resolved_frontend = frontend
    if not in_studio_venv:
        studio_python = _studio_venv_python()
        run_py = _find_run_py()
        if not (studio_python and run_py):
            typer.echo("Unsloth Studio not set up. Run install.sh first.")
            raise typer.Exit(1)
        # A public UI launch needs a servable login page before the gate strips the seeded password.
        resolved_frontend = _require_servable_frontend_or_exit(
            frontend = resolved_frontend,
            api_only = api_only,
            cloudflare = cloudflare,
            host = host,
            secure = secure,
        )
        # Non-public / api-only launches still forward a resolved dist, for the same silent 404.
        if resolved_frontend is None and not api_only:
            resolved_frontend = _find_frontend_dist()
    else:
        # In the studio venv there is no re-exec: validate frontend and backend BEFORE the headless gate strips the seeded password.
        resolved_frontend = _require_servable_frontend_or_exit(
            frontend = resolved_frontend,
            api_only = api_only,
            cloudflare = cloudflare,
            host = host,
            secure = secure,
        )
        _validate_inproc_backend_before_strip(
            cloudflare = cloudflare, host = host, secure = secure, api_only = api_only
        )

    _apply_supplied_password_before_launch(_password_prompt.resolve_supplied_password(password))
    os.environ.pop(_password_prompt.SUPPLIED_PASSWORD_ENV, None)

    _enforce_password_change_before_exposure(
        cloudflare = cloudflare,
        host = host,
        secure = secure,
        api_only = api_only,
        child_self_suppresses = _child_self_suppresses(
            in_studio_venv = in_studio_venv, child_run_py = run_py
        ),
    )

    if not in_studio_venv:
        if studio_python and run_py:
            if not silent:
                typer.echo("Launching Unsloth Studio... Please wait...")
            args = [
                str(studio_python),
                str(run_py),
                "--host",
                host,
                "--port",
                str(port),
                "--parallel",
                str(parallel),
            ]
            if resolved_frontend is not None:
                args.extend(["--frontend", str(resolved_frontend)])
            if silent:
                args.append("--silent")
            if api_only:
                args.append("--api-only")
            # Explicit polarity: an older run.py defaults --cloudflare on, so an unset default must not re-enable the tunnel on a mixed install.
            if cloudflare is True:
                args.append("--cloudflare")
            elif not secure:
                args.append("--no-cloudflare")
            args.append("--secure" if secure else "--no-secure")
            if enable_tools is True:
                args.append("--enable-tools")
            elif enable_tools is False:
                args.append("--disable-tools")
            if ssl_certfile is not None:
                args.extend(["--ssl-certfile", str(ssl_certfile)])
            if ssl_keyfile is not None:
                args.extend(["--ssl-keyfile", str(ssl_keyfile)])
            # On Windows os.execvp keeps the parent alive and Ctrl+C would orphan the child.
            if sys.platform == "win32":
                import subprocess as _sp

                # Without our std handles, CREATE_NO_WINDOW gives the backend a hidden console and `unsloth studio > log` captures nothing.
                with _studio_runtime_launch_guard(inherited = runtime_gate_handoff):
                    proc = _sp.Popen(
                        args,
                        stdout = _stream_for_subprocess(sys.stdout),
                        stderr = _stream_for_subprocess(sys.stderr),
                        **_windows_hidden_subprocess_kwargs(),
                    )
                try:
                    rc = proc.wait()
                except KeyboardInterrupt:
                    rc = proc.wait()
                if rc != 0:
                    typer.echo(
                        f"\nError: Unsloth server exited unexpectedly (code {rc}).",
                        err = True,
                    )
                    typer.echo(
                        "Check the error above. If a package is missing, "
                        "re-run: unsloth studio setup",
                        err = True,
                    )
                raise typer.Exit(rc)
            else:
                os.execvp(str(studio_python), args)
        else:
            typer.echo("Unsloth Studio not set up. Run install.sh first.")
            raise typer.Exit(1)

    with _studio_runtime_launch_guard(
        inherited = runtime_gate_handoff,
        wait = runtime_gate_acquire,
    ):
        with _studio_deps.studio_backend_imports("unsloth studio"):
            run_mod = _load_run_module()
        run_server = run_mod.run_server

        if not silent:
            launch_host = _openable_host_for_bind(run_mod, host)
            scheme = "https" if ssl_certfile is not None else "http"
            typer.echo(f"Starting Unsloth Studio on {scheme}://{_url_host(launch_host)}:{port}")

        run_kwargs = dict(
            host = host,
            port = port,
            silent = silent,
            api_only = api_only,
            llama_parallel_slots = parallel,
            cloudflare = cloudflare,
            secure = secure,
            enable_tools = enable_tools,
        )
        if ssl_certfile is not None or ssl_keyfile is not None:
            run_kwargs["ssl_certfile"] = str(ssl_certfile) if ssl_certfile else None
            run_kwargs["ssl_keyfile"] = str(ssl_keyfile) if ssl_keyfile else None
        if resolved_frontend is not None:
            run_kwargs["frontend_path"] = resolved_frontend
        run_server(**run_kwargs)

    _graceful_shutdown_on_sigterm()
    try:
        if run_mod._shutdown_event is not None:
            # Event.wait() with no timeout blocks at C level on Linux and swallows SIGINT.
            while not run_mod._shutdown_event.is_set():
                run_mod._shutdown_event.wait(timeout = 1)
        else:
            while True:
                time.sleep(1)
    except KeyboardInterrupt:
        getattr(run_mod, "_note_quit_signal", lambda: None)()
        run_mod._graceful_shutdown(run_mod._server)
        typer.echo("\nShutting down...")
    finally:
        getattr(run_mod, "_wait_for_server_shutdown", lambda: None)()
    # The desktop app and an in-venv `unsloth studio` serve from here, not run.py's __main__.
    getattr(run_mod, "_exit_without_finalizing", lambda: None)()


def _split_repo_variant(model_arg: str) -> tuple[str, Optional[str]]:
    """Split ``org/name:variant`` into ``(repo, variant)``; mirrors llama.cpp's
    ``-hf <repo>:<quant>``. Local paths, Windows drives and ids without ``:`` pass through."""
    s = model_arg.strip()
    if not s:
        return s, None
    if s.startswith(("/", "./", "../", "~")) or s == ".":
        return s, None
    # Windows drive letter: the colon is a path separator.
    if len(s) >= 2 and s[1] == ":" and s[0].isalpha():
        return s, None
    if ":" not in s:
        return s, None
    repo, _, variant = s.rpartition(":")
    if not repo or not variant:
        return s, None
    # Quant labels never contain a slash; `foo:bar/baz` is not repo:variant.
    if "/" in variant:
        return s, None
    return repo, variant


def _consume_legacy_short_aliases(
    args: List[str], aliases: tuple[str, ...], current: Optional[str], canonical: str
) -> tuple[Optional[str], List[str]]:
    """Pop exact-match legacy shorts (`-m`/`-hfr`/`-f`) from args, leaving clusters
    (`-mg`/`-fa`) for the llama-server tail. Inline `-x=value` accepted."""
    out: List[str] = []
    value = current
    i, n = 0, len(args)
    while i < n:
        tok = args[i]
        if tok == "--":
            out.extend(args[i:])
            break
        name, sep, inline = tok.partition("=")
        if name not in aliases:
            out.append(tok)
            i += 1
            continue
        if value is not None:
            raise typer.BadParameter(f"{name} conflicts with {canonical} already provided")
        if sep:
            if inline == "":
                raise typer.BadParameter(f"{name} requires a non-empty value")
            value = inline
            i += 1
        elif i + 1 < n:
            nxt = args[i + 1]
            # `--long` is unambiguously a flag; single-dash `-x` may be a path.
            if nxt.startswith("--") and nxt != "--":
                raise typer.BadParameter(f"{name} expects a value but got the flag {nxt}")
            value = nxt
            i += 2
        else:
            raise typer.BadParameter(f"{name} requires a value")
    return value, out


class _LlamaPassthroughCommand(TyperCommand):
    """Pass unknown short tokens to llama-server whole: Click split `-dev` into `-de` + our -v,
    and `-ctxcp 8` into --port 8. Tokens starting with our own letter (`-p8888`) still cluster."""

    def make_parser(self, ctx):
        parser = super().make_parser(ctx)
        match_short = getattr(parser, "_match_short_opt", None)
        short_opts = getattr(parser, "_short_opt", None)
        if match_short is None or short_opts is None or not ctx.ignore_unknown_options:
            return parser

        def _match_short_opt(arg, state):
            if len(arg) > 2 and arg[:2] not in short_opts:
                state.largs.append(arg)
                return
            match_short(arg, state)

        parser._match_short_opt = _match_short_opt
        return parser


_RUN_PANEL_MODEL = "Model"
_RUN_PANEL_SERVER = "Server & network"
_RUN_PANEL_TOOLS = "Tool calls"
_RUN_PANEL_SAMPLING = "Sampling"
_RUN_PANEL_ADVANCED = "Advanced"


@studio_app.command(
    cls = _LlamaPassthroughCommand,
    context_settings = {
        "allow_extra_args": True,
        "ignore_unknown_options": True,
    },
)
def run(
    ctx: typer.Context,
    model: Optional[str] = typer.Option(
        None,
        "--model",
        "-hf",
        "--hf-repo",
        # `-m` / `-hfr` removed (Click clusters `-mg`/`-md`); the legacy shim still takes exact matches.
        rich_help_panel = _RUN_PANEL_MODEL,
        help = (
            "Model path or HF repo. Accepts llama.cpp-style "
            "`org/repo:variant` syntax. `-hf` / `--hf-repo` match "
            "llama-server's spelling. An AMD Ryzen AI NPU model is "
            "`lemonade:<id>` or its bare id, e.g. `qwen3-0.6b-FLM`."
        ),
    ),
    gguf_variant: Optional[str] = typer.Option(
        None,
        "--gguf-variant",
        rich_help_panel = _RUN_PANEL_MODEL,
        help = "GGUF quant variant (e.g. UD-Q4_K_XL)",
    ),
    verbose: bool = typer.Option(
        False,
        "--verbose",
        "-v",
        rich_help_panel = _RUN_PANEL_ADVANCED,
        help = "Log every API request, including the high-frequency polling that is "
        "deduplicated by default.",
    ),
    max_seq_length: int = typer.Option(
        0,
        "--max-seq-length",
        "--context-length",
        rich_help_panel = _RUN_PANEL_MODEL,
        help = "Runtime context length in tokens (0 = model default for GGUF; 2048 for hub models)",
    ),
    gpu_memory_mode: Literal["auto", "manual"] = typer.Option(
        "auto",
        "--gpu-memory-mode",
        rich_help_panel = _RUN_PANEL_MODEL,
        help = (
            "GPU memory strategy for GGUF models. Auto lets Unsloth select GPUs "
            "and cap context to fit VRAM. Manual with default layers and context "
            "delegates placement and sizing to llama.cpp --fit."
        ),
    ),
    speculative_type: Optional[SpeculativeType] = typer.Option(
        None,
        "--speculative-type",
        rich_help_panel = _RUN_PANEL_MODEL,
        help = (
            "Speculative decoding mode for GGUF models. DSpark automatically uses a "
            "matching dspark-*.gguf sidecar when available. Default: unset (Unsloth auto)."
        ),
    ),
    spec_draft_n_max: Optional[int] = typer.Option(
        None,
        "--spec-draft-n-max",
        min = 1,
        max = 16,
        rich_help_panel = _RUN_PANEL_MODEL,
        help = "Maximum draft tokens per step for MTP or DSpark (1..16).",
    ),
    load_in_4bit: bool = typer.Option(
        True, "--load-in-4bit/--no-load-in-4bit", rich_help_panel = _RUN_PANEL_MODEL
    ),
    api_key_name: str = typer.Option(
        "cli",
        "--api-key-name",
        rich_help_panel = _RUN_PANEL_ADVANCED,
        help = "Label for the API key reused across runs",
    ),
    port: int = typer.Option(8888, "--port", "-p", rich_help_panel = _RUN_PANEL_SERVER),
    host: str = typer.Option("127.0.0.1", "--host", "-H", rich_help_panel = _RUN_PANEL_SERVER),
    frontend: Optional[Path] = typer.Option(None, "--frontend", rich_help_panel = _RUN_PANEL_SERVER),
    api_only: bool = typer.Option(
        False,
        "--api-only",
        rich_help_panel = _RUN_PANEL_SERVER,
        help = "Serve only the API (no web UI), for a headless model server. "
        "Pairs with --secure to expose the API over the Cloudflare link alone.",
    ),
    silent: bool = typer.Option(False, "--silent", "-q", rich_help_panel = _RUN_PANEL_ADVANCED),
    enable_tools: Optional[bool] = typer.Option(
        None,
        "--enable-tools/--disable-tools",
        rich_help_panel = _RUN_PANEL_TOOLS,
        help = (
            "Force server-side tools (web search, code execution) on or off for "
            "every request. Default: on for every bind, with a request's own "
            "enable_tools: false (what the Unsloth UI sends) honored. /v1/messages "
            "takes the on direction per request (enable_tools) because it has no "
            "confirmation channel; the off direction still applies everywhere."
        ),
    ),
    disable_dns_pinning: bool = typer.Option(
        False,
        "--disable-dns-pinning",
        rich_help_panel = _RUN_PANEL_TOOLS,
        help = "Send the hostname (not the validated IP) in web fetches that go through an "
        "explicitly configured HTTP(S)_PROXY, so the proxy can apply hostname policy and "
        "TLS interception. Direct fetches stay pinned to the validated IP.",
    ),
    tool_call_healing: Optional[bool] = typer.Option(
        None,
        "--enable-tool-call-healing/--disable-tool-call-healing",
        rich_help_panel = _RUN_PANEL_TOOLS,
        help = (
            "Promote text-form tool calls (small GGUFs often emit <tool_call>...) "
            "back into structured calls on the client-tool passthrough. Default: on. "
            "An explicit --disable-tool-call-healing is an absolute server kill-switch."
        ),
    ),
    tool_call_nudging: Optional[bool] = typer.Option(
        None,
        "--enable-tool-call-nudging/--disable-tool-call-nudging",
        rich_help_panel = _RUN_PANEL_TOOLS,
        help = (
            "On the non-streaming client-tool passthrough, retry once with a short "
            "nudge when the model emitted a tool signal that healing could not repair. "
            "Default: on. No effect on streaming requests or the server-side agentic loop."
        ),
    ),
    temperature: Optional[float] = typer.Option(
        None,
        "--temperature",
        min = 0.0,
        max = 2.0,
        rich_help_panel = _RUN_PANEL_SAMPLING,
        help = (
            "Pin the sampling temperature for every request that omits it, overriding the "
            "model's recommended value. Default: unset (use the per-model recommendation)."
        ),
    ),
    top_p: Optional[float] = typer.Option(
        None,
        "--top-p",
        min = 0.0,
        max = 1.0,
        rich_help_panel = _RUN_PANEL_SAMPLING,
        help = "Pin top-p (nucleus) sampling. Default: unset (per-model recommendation).",
    ),
    top_k: Optional[int] = typer.Option(
        None,
        "--top-k",
        min = -1,
        max = 100,
        rich_help_panel = _RUN_PANEL_SAMPLING,
        help = "Pin top-k sampling. Default: unset (per-model recommendation).",
    ),
    min_p: Optional[float] = typer.Option(
        None,
        "--min-p",
        min = 0.0,
        max = 1.0,
        rich_help_panel = _RUN_PANEL_SAMPLING,
        help = "Pin min-p sampling threshold. Default: unset (per-model recommendation).",
    ),
    repetition_penalty: Optional[float] = typer.Option(
        None,
        "--repetition-penalty",
        min = 1.0,
        max = 2.0,
        rich_help_panel = _RUN_PANEL_SAMPLING,
        help = "Pin the repetition penalty. Default: unset (per-model recommendation).",
    ),
    presence_penalty: Optional[float] = typer.Option(
        None,
        "--presence-penalty",
        min = 0.0,
        max = 2.0,
        rich_help_panel = _RUN_PANEL_SAMPLING,
        help = "Pin the presence penalty. Default: unset (per-model recommendation).",
    ),
    yes: bool = typer.Option(
        False,
        "--yes",
        "-y",
        rich_help_panel = _RUN_PANEL_ADVANCED,
        help = "Accepted for backward compatibility; the tool policy no longer prompts.",
    ),
    parallel: int = typer.Option(
        _PARALLEL_DEFAULT_RUN,
        "--parallel",
        "--n-parallel",
        "-np",
        min = _PARALLEL_MIN,
        max = _PARALLEL_MAX,
        rich_help_panel = _RUN_PANEL_SERVER,
        help = (
            "llama-server parallel decode slots. N requests share one "
            "loaded model and one KV cache of the full context "
            "(--kv-unified), so a single request can use all of it. "
            "llama.cpp builds without --kv-unified fall back to one slot. "
            "The Unsloth run settings (Parallel Slots) can override it per "
            "load."
        ),
    ),
    cloudflare: Optional[bool] = typer.Option(
        None,
        "--cloudflare/--no-cloudflare",
        rich_help_panel = _RUN_PANEL_SERVER,
        help = "Expose Unsloth on a PUBLIC internet URL via a free Cloudflare HTTPS "
        "tunnel, for non-api-only wildcard binds (0.0.0.0 or ::). Off by default; "
        "pass --cloudflare to enable it (--secure implies it). The Remote access "
        "'Start automatically' setting also starts one on every launch, on any host. "
        "--no-cloudflare forces both off but does not change a raw wildcard bind.",
    ),
    secure: bool = typer.Option(
        False,
        "--secure/--no-secure",
        rich_help_panel = _RUN_PANEL_SERVER,
        help = "Expose ONLY a Cloudflare HTTPS link: bind localhost and fail closed "
        "if the tunnel can't start. Without it, --no-secure also serves the raw "
        "0.0.0.0 port, which is reachable from anywhere on the network.",
    ),
    not_secure: bool = typer.Option(
        False,
        "--not-secure",
        hidden = True,
        help = "Deprecated alias for --no-secure.",
    ),
    tensor_parallel: bool = typer.Option(
        False,
        "--tensor-parallel/--no-tensor-parallel",
        rich_help_panel = _RUN_PANEL_MODEL,
        help = (
            "Split a GGUF across GPUs by tensor (--split-mode tensor) instead of "
            "by layer. Multi-GPU only (no effect on one GPU); dense models gain "
            "decode speed, MoE usually don't."
        ),
    ),
    engine: Literal["auto", "vllm", "sglang"] = typer.Option(
        "auto",
        "--engine",
        rich_help_panel = _RUN_PANEL_MODEL,
        help = (
            "Serve a safetensors model with vLLM or SGLang instead of Unsloth Studio's default "
            "backend. Installed on first use after a confirmation (--yes skips it); "
            "Linux NVIDIA, or Windows through WSL2."
        ),
    ),
    engine_precision: Literal["auto", "bf16", "fp16", "int4", "int8", "fp8"] = typer.Option(
        "auto",
        "--engine-precision",
        rich_help_panel = _RUN_PANEL_MODEL,
        help = "Weight precision for --engine vllm/sglang (auto keeps the checkpoint's).",
    ),
    start_api_key_marker: bool = typer.Option(
        False,
        "--start-api-key-marker",
        hidden = True,
        help = "Emit an early API key marker for the unsloth start parent process.",
    ),
    password: str = typer.Option(
        "",
        "--password",
        rich_help_panel = _RUN_PANEL_ADVANCED,
        help = "Set the INITIAL admin password non-interactively (headless setups), "
        "only when none is set yet. Also reads the UNSLOTH_STUDIO_PASSWORD env var, or "
        "`--password -` to read one line from stdin. A literal value is visible in the "
        "process list and shell history. Rotate later with `unsloth studio reset-password`.",
    ),
    engine_parallelism: Literal["tensor", "pipeline", "data"] = typer.Option(
        "tensor",
        "--engine-parallelism",
        rich_help_panel = _RUN_PANEL_MODEL,
        help = (
            "How --engine vllm/sglang uses several GPUs: tensor splits each layer, pipeline "
            "splits the layers, data runs one replica per GPU and spreads requests across "
            "them. pipeline and data use every visible GPU unless --gpus narrows it."
        ),
    ),
    gpus: Optional[str] = typer.Option(
        None,
        "--gpus",
        rich_help_panel = _RUN_PANEL_MODEL,
        help = (
            "Comma-separated GPU indices to load the model on, for example 0,1 (the "
            "Unsloth Studio GPU picker). Default: automatic selection."
        ),
    ),
):
    """Start Unsloth, load a model, print an API key -- one-liner server.

    Unknown flags pass through to llama-server (GGUF only). Unsloth
    rejects managed flags with HTTP 400: model identity, network
    (--host/--port/--path/--api-prefix/--reuse-port), auth/TLS
    (--api-key/--ssl-*), single-model UI (--ui/--models-*/--webui),
    and parallel slots (use --parallel above). Full denylist in
    studio/backend/core/inference/llama_server_args.py. Other knobs
    (-c, -ngl, --jinja, --flash-attn, -t, ...) pass through and
    last-wins-override Unsloth's auto-set value.

    Example:
        unsloth studio run --model unsloth/Qwen3-1.7B-GGUF --gguf-variant UD-Q4_K_XL
        unsloth studio run --model unsloth/Qwen3-1.7B-GGUF --temperature 0.7 --seed 42 --parallel 8
        unsloth studio run --model some-model --chat-template-file /path/to/tpl.jinja
        unsloth studio run --model unsloth/Qwen3-27B-GGUF --gguf-variant Q8_0 --tensor-parallel
        unsloth studio run --model unsloth/Qwen3-8B --engine vllm --engine-parallelism data
    """
    # Passed via env, so an older re-exec target ignores it instead of treating it as a llama-server arg.
    inherited_start_api_key_marker = _consume_start_api_key_marker_env()
    start_api_key_marker = start_api_key_marker or inherited_start_api_key_marker
    runtime_gate_handoff = _studio_runtime_gate.consume_runtime_gate_handoff()
    # The group callback returns before its own clear once a subcommand is named, so this path must clear the override itself (#7331).
    _clear_hsa_override_before_launch(silent = bool(silent))

    secure = _resolve_secure(secure, not_secure)
    _preserve_cloudflare_intent(cloudflare, secure)
    extra_llama_args: List[str] = list(ctx.args) if ctx.args else []

    # Read from the env at backend import, so resolve before any re-exec; an omitted flag keeps a value the parent forwarded.
    _healing_disabled = (
        os.environ.get("UNSLOTH_DISABLE_TOOL_CALL_HEALING") == "1"
        if tool_call_healing is None
        else not tool_call_healing
    )
    os.environ["UNSLOTH_DISABLE_TOOL_CALL_HEALING"] = "1" if _healing_disabled else "0"
    if tool_call_nudging is not None:
        os.environ["UNSLOTH_TOOL_CALL_NUDGE"] = "1" if tool_call_nudging else "0"
    elif "UNSLOTH_TOOL_CALL_NUDGE" not in os.environ:
        os.environ["UNSLOTH_TOOL_CALL_NUDGE"] = "1"

    # UNSLOTH_SAMPLING_* hard-pins a field over client and per-model recommendation, so only write flags set explicitly.
    for _sampling_env, _sampling_value in (
        ("UNSLOTH_SAMPLING_TEMPERATURE", temperature),
        ("UNSLOTH_SAMPLING_TOP_P", top_p),
        ("UNSLOTH_SAMPLING_TOP_K", top_k),
        ("UNSLOTH_SAMPLING_MIN_P", min_p),
        ("UNSLOTH_SAMPLING_REPETITION_PENALTY", repetition_penalty),
        ("UNSLOTH_SAMPLING_PRESENCE_PENALTY", presence_penalty),
    ):
        if _sampling_value is not None:
            os.environ[_sampling_env] = str(_sampling_value)

    # Set before any re-exec. --log-verbose keeps llama-server's own -v passthrough working.
    added_log_verbose = False
    if verbose:
        _enable_verbose_access_logs()
        if engine == "auto" and not any(
            a in ("--verbose", "-v", "--log-verbose") for a in extra_llama_args
        ):
            extra_llama_args.append("--log-verbose")
            added_log_verbose = True
    if disable_dns_pinning:
        os.environ["UNSLOTH_STUDIO_DISABLE_DNS_PINNING"] = "1"
    else:
        os.environ.setdefault("UNSLOTH_STUDIO_DISABLE_DNS_PINNING", "0")

    # Promote legacy exact `-m`/`-hfr`/`-f` back into typer params; clusters stay in extras.
    model, extra_llama_args = _consume_legacy_short_aliases(
        extra_llama_args,
        ("-m", "-hfr"),
        model,
        "--model",
    )
    legacy_frontend, extra_llama_args = _consume_legacy_short_aliases(
        extra_llama_args,
        ("-f",),
        str(frontend) if frontend is not None else None,
        "--frontend",
    )
    if legacy_frontend is not None and frontend is None:
        frontend = Path(legacy_frontend)

    if model is None:
        typer.echo(
            "Error: Missing option '--model' / '-hf' / '--hf-repo' "
            "(legacy aliases '-m' / '-hfr' are still accepted).",
            err = True,
        )
        raise typer.Exit(2)

    from unsloth_cli._npu import npu_model_path

    # An NPU model's `lemonade:` prefix is not a llama.cpp `repo:variant` split.
    npu_path = npu_model_path(model)
    if npu_path:
        if added_log_verbose:
            extra_llama_args.remove("--log-verbose")
        if gguf_variant or extra_llama_args or engine != "auto":
            typer.echo(
                "Error: NPU models run on FastFlowLM; --gguf-variant, --engine and "
                "llama-server flags do not apply to them.",
                err = True,
            )
            raise typer.Exit(2)
        model = npu_path
    # Parse llama.cpp `repo:variant`; error if it disagrees with --gguf-variant.
    parsed_repo, embedded_variant = (model, None) if npu_path else _split_repo_variant(model)
    if embedded_variant:
        if gguf_variant and gguf_variant != embedded_variant:
            typer.echo(
                f"Error: --model embeds variant '{embedded_variant}' but "
                f"--gguf-variant '{gguf_variant}' was also provided.",
                err = True,
            )
            raise typer.Exit(1)
        model = parsed_repo
        gguf_variant = gguf_variant or embedded_variant
    if engine != "auto" and (gguf_variant or extra_llama_args):
        typer.echo(
            f"Error: --engine {engine} serves safetensors checkpoints; GGUF variants and "
            "llama-server flags apply only to the default backend.",
            err = True,
        )
        raise typer.Exit(2)
    if engine == "auto" and engine_parallelism != "tensor":
        typer.echo(
            "Error: --engine-parallelism applies only to --engine vllm or --engine sglang.",
            err = True,
        )
        raise typer.Exit(2)
    try:
        gpu_ids = _parse_gpu_ids(gpus)
    except ValueError as exc:
        typer.echo(f"Error: {exc}", err = True)
        raise typer.Exit(2)

    _require_bind_host(host)

    # --secure requires the tunnel; force a loopback bind so the raw port is never public.
    if secure:
        if cloudflare is False:
            typer.echo(
                "Error: --secure requires the Cloudflare tunnel; do not combine it "
                "with --no-cloudflare.",
                err = True,
            )
            raise typer.Exit(2)
        if host not in ("127.0.0.1", "localhost", "::1"):
            typer.echo(
                "Note: --secure ignores -H (it binds loopback and serves only "
                "through the Cloudflare tunnel). Drop --secure to bind "
                f"{host} directly, or keep --secure for a tunnel-only public link.",
                err = True,
            )
        host = "127.0.0.1"

    host = _normalize_wildcard_bind_host(host)
    _require_unambiguous_ephemeral_bind(host, port)

    # Tool policy does not depend on the bind. None applies the default without becoming an override, so a request's enable_tools: false is honored.
    from unsloth_cli._tool_policy import is_external_host, resolve_tool_policy

    enable_tools = resolve_tool_policy(
        host = host,
        flag = enable_tools,
        yes = yes,
        silent = silent,
    )

    studio_venv_dir = STUDIO_HOME / "unsloth_studio"
    in_studio_venv = _running_in_studio_venv(studio_venv_dir)
    reexeced = os.environ.pop(_STUDIO_REEXEC_ENV, None) == "1"
    if reexeced and not in_studio_venv:
        typer.echo(
            f"Error: re-launched through {studio_venv_dir} but still running from "
            f"{sys.prefix}, so not re-launching again. Check that UNSLOTH_STUDIO_HOME "
            "points at the Unsloth Studio install, or re-run: unsloth studio setup",
            err = True,
        )
        raise typer.Exit(1)
    studio_bin = None
    resolved_frontend = frontend
    if not in_studio_venv:
        studio_python = _studio_venv_python()
        if not studio_python:
            typer.echo("Unsloth Studio not set up. Run install.sh first.")
            raise typer.Exit(1)
        # Re-exec via the studio venv's console script. On Windows quarantine deletes the stub from a working venv, so the package answers for it.
        studio_bin = studio_python.parent / (
            "unsloth.exe" if platform.system() == "Windows" else "unsloth"
        )
        if not studio_bin.is_file() and not _managed_cli_package_present(studio_python):
            typer.echo("Unsloth venv missing 'unsloth' entry point. Re-run: unsloth studio setup")
            raise typer.Exit(1)
        resolved_frontend = _require_servable_frontend_or_exit(
            frontend = frontend,
            api_only = api_only,
            cloudflare = cloudflare,
            host = host,
            secure = secure,
        )
    else:
        resolved_frontend = _require_servable_frontend_or_exit(
            frontend = frontend,
            api_only = api_only,
            cloudflare = cloudflare,
            host = host,
            secure = secure,
        )
        _validate_inproc_backend_before_strip(
            cloudflare = cloudflare, host = host, secure = secure, api_only = api_only
        )

    _apply_supplied_password_before_launch(_password_prompt.resolve_supplied_password(password))
    os.environ.pop(_password_prompt.SUPPLIED_PASSWORD_ENV, None)

    # Before any re-exec or server exists. This re-exec runs a possibly-OLD console script, so it is NOT provably self-suppressing.
    _enforce_password_change_before_exposure(
        cloudflare = cloudflare,
        host = host,
        secure = secure,
        api_only = api_only,
        child_self_suppresses = _child_self_suppresses(
            in_studio_venv = in_studio_venv, child_run_py = None
        ),
    )

    if not in_studio_venv:
        # Application Control blocks the generated unsloth.exe on some machines but not the signed python.exe beside it.
        if sys.platform == "win32":
            launch_head = _managed_cli_argv(studio_python)
        elif _resolved_or_self(studio_venv_dir) != studio_venv_dir:
            # Older child CLIs loop via the console script's resolved shebang; python keeps the link.
            launch_head = [str(studio_python), "-c", _WINDOWS_CLI_ENTRYPOINT]
        else:
            launch_head = [str(studio_bin)]
        args = [
            *launch_head,
            "studio",
            "run",
            "--model",
            model,
            "--max-seq-length",
            str(max_seq_length),
            "--api-key-name",
            api_key_name,
            "--port",
            str(port),
            "--host",
            host,
        ]
        if gpu_memory_mode != "auto":
            args.extend(["--gpu-memory-mode", gpu_memory_mode])
        if gguf_variant:
            args.extend(["--gguf-variant", gguf_variant])
        if speculative_type is not None:
            args.extend(["--speculative-type", speculative_type])
        if spec_draft_n_max is not None:
            args.extend(["--spec-draft-n-max", str(spec_draft_n_max)])
        # Explicit polarity: a future default flip on one layer must not invert the other.
        args.append("--load-in-4bit" if load_in_4bit else "--no-load-in-4bit")
        # Not just a user-supplied dist: the parent may have found a build the shadowed child cannot, and the child would abort (lockout).
        if resolved_frontend is not None:
            args.extend(["--frontend", str(resolved_frontend)])
        if api_only:
            args.append("--api-only")
        if silent:
            args.append("--silent")
        if enable_tools is True:
            args.append("--enable-tools")
        elif enable_tools is False:
            args.append("--disable-tools")
        if yes:
            args.append("--yes")
        # Typer claims --parallel outside ctx.args; without this the child reverts to its default.
        args.extend(["--parallel", str(parallel)])
        # Explicit polarity: a mixed-version studio venv whose old default was cloudflare-on must not re-enable the tunnel.
        if cloudflare is True:
            args.append("--cloudflare")
        elif not secure:
            args.append("--no-cloudflare")
        args.append("--secure" if secure else "--no-secure")
        args.append("--tensor-parallel" if tensor_parallel else "--no-tensor-parallel")
        if engine != "auto":
            args.extend(["--engine", engine, "--engine-precision", engine_precision])
        # Only when set: an older studio-venv CLI would hand unknown flags to llama-server.
        if engine_parallelism != "tensor":
            args.extend(["--engine-parallelism", engine_parallelism])
        if gpu_ids:
            args.extend(["--gpus", ",".join(str(i) for i in gpu_ids)])
        if verbose:
            args.append("--verbose")
        if extra_llama_args:
            args.extend(extra_llama_args)

        if start_api_key_marker:
            os.environ[_START_API_KEY_MARKER_ENV] = "1"
        os.environ[_STUDIO_REEXEC_ENV] = "1"
        try:
            if sys.platform == "win32":
                with _studio_runtime_launch_guard(inherited = runtime_gate_handoff) as gate_held:
                    popen_kwargs = {}
                    if gate_held:
                        popen_kwargs["env"] = _studio_runtime_gate.runtime_gate_child_environment()
                    proc = subprocess.Popen(args, **popen_kwargs)
                try:
                    rc = proc.wait()
                except KeyboardInterrupt:
                    rc = proc.wait()
                raise typer.Exit(rc)
            else:
                os.execvp(args[0], args)
        finally:
            os.environ.pop(_START_API_KEY_MARKER_ENV, None)
            os.environ.pop(_STUDIO_REEXEC_ENV, None)

    with _studio_deps.studio_backend_imports("unsloth studio"):
        run_mod = _load_run_module()
    run_server = run_mod.run_server

    # Match the route handlers' import path and set it before uvicorn binds; run_server() applies the same pair, idempotently.
    from state.tool_policy import set_tool_policy, set_tool_policy_default

    set_tool_policy_default(True)
    set_tool_policy(enable_tools)

    run_kwargs = dict(
        host = host,
        port = port,
        silent = True,
        api_only = api_only,
        llama_parallel_slots = parallel,
        cloudflare = cloudflare,
        secure = secure,
        emit_tauri_port = False,
        abort_if_own_studio = False,
    )
    if resolved_frontend is not None:
        run_kwargs["frontend_path"] = resolved_frontend
    with _studio_runtime_launch_guard(inherited = runtime_gate_handoff):
        app = run_server(**run_kwargs)
    actual_port = getattr(app.state, "server_port", port) or port

    from studio.backend.run import _graceful_shutdown, _server

    try:
        request_host = getattr(app.state, "server_request_host", None)
        if not isinstance(request_host, str) or not request_host:
            typer.echo("Error: server did not expose its bound address.", err = True)
            raise typer.Exit(1)
        if not silent:
            typer.echo("Starting Unsloth Studio...")
        if not _wait_for_server(actual_port, request_host = request_host):
            typer.echo("Error: server did not become healthy within 30 seconds.", err = True)
            raise typer.Exit(1)

        api_key = _create_api_key_inprocess(api_key_name)
        if start_api_key_marker:
            typer.echo(f"UNSLOTH_START_PORT: {actual_port}")
            typer.echo(f"UNSLOTH_START_API_KEY: {api_key}")

        if engine != "auto":
            try:
                _ensure_engine_installed(engine, yes, silent)
            except RuntimeError as exc:
                typer.echo(f"Error: {exc}", err = True)
                raise typer.Exit(1)
        if engine_parallelism != "tensor" and not gpu_ids:
            # The engine otherwise gets one GPU, which makes pipeline / data a no-op.
            from utils.hardware.hardware import resolve_requested_gpu_ids
            gpu_ids = resolve_requested_gpu_ids(None)
        if npu_path:
            from unsloth_cli._npu import prepare_npu_model
            def _npu_request(method, path, payload, timeout):
                import urllib.request
                request = urllib.request.Request(
                    f"http://{_url_host(request_host)}:{actual_port}{path}",
                    data = None if payload is None else json.dumps(payload).encode(),
                    headers = {
                        "Content-Type": "application/json",
                        "Authorization": f"Bearer {api_key}",
                    },
                    method = method,
                )
                return _direct_urlopen(request, timeout = timeout)

            try:
                prepare_npu_model(
                    _npu_request,
                    model,
                    (lambda _line: None) if silent else typer.echo,
                )
            except RuntimeError as exc:
                typer.echo(f"Error: {exc}", err = True)
                raise typer.Exit(1)
        if not silent:
            typer.echo(f"Loading model: {model}...")
        try:
            result = _load_model_via_http(
                port = actual_port,
                api_key = api_key,
                model = model,
                gguf_variant = gguf_variant,
                max_seq_length = max_seq_length,
                load_in_4bit = load_in_4bit,
                gpu_memory_mode = gpu_memory_mode,
                tensor_parallel = tensor_parallel,
                speculative_type = speculative_type,
                spec_draft_n_max = spec_draft_n_max,
                llama_extra_args = extra_llama_args,
                request_host = request_host,
                engine = engine,
                engine_precision = engine_precision,
                engine_parallelism = engine_parallelism,
                gpu_ids = gpu_ids,
            )
        except RuntimeError as exc:
            typer.echo(f"Error: {exc}", err = True)
            raise typer.Exit(1)
    except BaseException:
        _graceful_shutdown(_server)
        getattr(run_mod, "_wait_for_server_shutdown", lambda: None)()
        raise

    loaded_model = result.get("model", model)
    display_variant = f" ({gguf_variant})" if gguf_variant else ""
    context_length_line = _format_context_length_line(result)

    display_host = _display_host_for_bind(run_mod, host)
    base_host = _openable_host_for_bind(run_mod, host)
    base_url = f"http://{_url_host(base_host)}:{actual_port}"
    sdk_base_url = f"{base_url}/v1"
    _cf_url = getattr(app.state, "cloudflare_url", None)
    if secure and _cf_url:
        sdk_base_url = f"{_cf_url}/v1"

    _tool_notice_fg = (217, 119, 87)
    _is_external = is_external_host(host)
    if enable_tools is False:
        _tool_notice = "Server-side tools are DISABLED (--disable-tools)."
    elif secure:
        _tool_notice = (
            "Server-side tools are ENABLED, reachable via the authenticated "
            "Cloudflare HTTPS tunnel. Anyone with the API key can run code on "
            "this machine. Do not share the API key. Pass --disable-tools to turn off."
        )
    elif _is_external:
        _tool_notice = (
            "Server-side tools are ENABLED and this port is network-reachable. "
            "Anyone who can reach it with the API key can run code on this "
            "machine. Do not share the API key. Pass --disable-tools to turn off."
        )
    else:
        _tool_notice = (
            "Server-side tools are ENABLED for loopback. Pass --disable-tools to turn off."
        )

    if not silent:
        typer.echo("")
        typer.echo("=" * 56)
        if secure and _cf_url:
            typer.echo(f"  Unsloth Studio running (secure) at {_cf_url}")
            typer.echo(f"  On this machine only: {base_url}")
        else:
            typer.echo(f"  Unsloth Studio running at {base_url}")
            _emit_run_cloudflare_notice(run_mod, host, display_host, actual_port, secure)
        typer.echo(f"  Model loaded: {loaded_model}{display_variant}")
        if context_length_line:
            typer.echo(context_length_line)
        typer.echo(f"  API Key:      {api_key}")
        typer.echo("")
        # An NPU model serves /v1/chat/completions only: no Anthropic or streaming Responses example.
        typer.echo("  OpenAI SDK base URL:" if npu_path else "  OpenAI / Anthropic SDK base URL:")
        typer.echo(f"    {sdk_base_url}")
        typer.echo("=" * 56)
        typer.secho(_tool_notice, fg = _tool_notice_fg, bold = True)
        typer.echo("")
        typer.echo("OpenAI Chat Completions:")
        typer.echo(f"  curl {sdk_base_url}/chat/completions \\")
        typer.echo(f'    -H "Authorization: Bearer {api_key}" \\')
        typer.echo('    -H "Content-Type: application/json" \\')
        typer.echo(
            """    -d '{"messages": [{"role": "user", "content": "Hello"}], "stream": true}'"""
        )
        typer.echo("")
        if not npu_path:
            typer.echo("Anthropic Messages:")
            typer.echo(f"  curl {sdk_base_url}/messages \\")
            typer.echo(f'    -H "Authorization: Bearer {api_key}" \\')
            typer.echo('    -H "Content-Type: application/json" \\')
            typer.echo(
                """    -d '{"max_tokens": 256, "messages": [{"role": "user", "content": "Hello"}], "stream": true}'"""
            )
            typer.echo("")
            typer.echo("OpenAI Responses:")
            typer.echo(f"  curl {sdk_base_url}/responses \\")
            typer.echo(f'    -H "Authorization: Bearer {api_key}" \\')
            typer.echo('    -H "Content-Type: application/json" \\')
            typer.echo("""    -d '{"input": "Hello", "stream": true}'""")
            typer.echo("")
    else:
        if secure and _cf_url:
            typer.echo(f"URL:     {_cf_url}")
            typer.echo(f"Local:   {base_url}")
        else:
            typer.echo(f"URL:     {base_url}")
            _emit_run_cloudflare_notice(run_mod, host, display_host, actual_port, secure)
        if context_length_line:
            typer.echo(context_length_line.strip())
        typer.echo(f"API Key: {api_key}")
        typer.secho(_tool_notice, fg = _tool_notice_fg, bold = True)

    _graceful_shutdown_on_sigterm()
    try:
        if run_mod._shutdown_event is not None:
            while not run_mod._shutdown_event.is_set():
                run_mod._shutdown_event.wait(timeout = 1)
        else:
            while True:
                time.sleep(1)
    except KeyboardInterrupt:
        getattr(run_mod, "_note_quit_signal", lambda: None)()
        run_mod._graceful_shutdown(run_mod._server)
        typer.echo("\nShutting down...")
    finally:
        getattr(run_mod, "_wait_for_server_shutdown", lambda: None)()


_PID_FILE = STUDIO_HOME / "studio.pid"
PID_FILE_GLOB = "studio-*.pid"


def _pid_alive(pid: int) -> bool:
    """True if pid exists; os.kill(pid, 0) raises WinError 87 on Windows, so psutil (else tasklist) decides there."""
    if sys.platform == "win32":
        try:
            import psutil

            # OpenProcess-based; access denied already counts as alive.
            return bool(psutil.pid_exists(int(pid)))
        except Exception:
            pass  # psutil is optional for the CLI install
        try:
            out = subprocess.run(
                ["tasklist", "/FI", f"PID eq {int(pid)}", "/NH", "/FO", "CSV"],
                capture_output = True,
                text = True,
                encoding = "utf-8",
                errors = "replace",
                timeout = 10,
            )
        except Exception:
            # Cannot determine; assume alive, taskkill no-ops if already gone.
            return True
        if out.returncode != 0:
            return True
        return f'"{int(pid)}"' in out.stdout
    try:
        os.kill(pid, 0)
    except ProcessLookupError:
        return False
    except PermissionError:
        return True
    return True


def _parse_pid_record(text: str) -> "tuple[int, RecordedStart, str | None] | None":
    lines = text.splitlines()
    if not lines or not lines[0].strip().isdigit():
        return None
    try:
        # isdigit() is not enough: "²".isdigit() is True but int() rejects it.
        pid = int(lines[0].strip())
    except ValueError:
        return None
    # kill(0) signals our whole process group; kill(1) is init. Never either.
    if pid < 2:
        return None
    created = recorded_start(lines)
    # Third line: the addresses run.py bound, absent in a legacy record.
    address = lines[2].strip() if len(lines) > 2 and lines[2].strip() else None
    return pid, created, address


def _read_pid_record(path: Path) -> "tuple[int, RecordedStart, str | None] | None":
    try:
        text = path.read_text(encoding = "utf-8")
    except (OSError, UnicodeDecodeError):
        return None
    return _parse_pid_record(text)


def _unlink_quietly(path: Path) -> None:
    """Unlink quietly: an undeletable record must not stop us reaching the other servers."""
    try:
        path.unlink(missing_ok = True)
    except OSError as e:
        typer.echo(f"Could not remove PID file {path.name}: {e}", err = True)


def _report_unreadable(paths: "list[Path]") -> None:
    names = ", ".join(sorted(p.name for p in paths))
    typer.echo(
        f"Could not read {len(paths)} PID file(s): {names}. A server recorded "
        f"there may still be running; re-run with permission to read "
        f"{STUDIO_HOME} to stop it.",
        err = True,
    )


def _pid_file_entries(
    unreadable: "list[Path] | None" = None,
) -> "list[tuple[int, list[RecordedStart], list[Path]]]":
    """Per recorded server (pid, create_times, files), grouped by PID so a second SIGTERM cannot
    hard-kill mid-shutdown; stale files cannot veto a live server."""
    by_pid: "dict[int, tuple[list[RecordedStart], list[Path]]]" = {}
    try:
        paths = sorted(STUDIO_HOME.glob(PID_FILE_GLOB)) + [_PID_FILE]
    except OSError:
        paths = [_PID_FILE]
    seen = set()
    for path in paths:
        if path in seen or not path.is_file():
            continue
        seen.add(path)
        try:
            text = path.read_text(encoding = "utf-8")
        except (OSError, UnicodeDecodeError) as e:
            # Unreadable is not invalid: a root-owned or mid-write record still belongs to a live server.
            typer.echo(f"Cannot read PID file {path.name}: {e}", err = True)
            if unreadable is not None:
                unreadable.append(path)
            continue
        record = _parse_pid_record(text)
        if record is None:
            typer.echo(f"Ignoring invalid PID file {path.name}")
            _unlink_quietly(path)
            continue
        pid, created, _address = record
        created_times, files = by_pid.setdefault(pid, ([], []))
        created_times.append(created)
        files.append(path)
    return [(pid, times, files) for pid, (times, files) in by_pid.items()]


def _pid_is_studio_server(pid: int, created_times: "Sequence[RecordedStart]" = ()) -> bool:
    return pid_start_matches(pid, created_times)


def _graceful_shutdown_on_sigterm() -> None:
    """Route SIGTERM (docker stop, `unsloth studio stop`) into the wait loop's Ctrl+C path,
    which stops and saves a running training job before anything is killed."""
    import signal as _signal

    def _handler(signum, frame):
        # Restore the default so a second signal force-quits if the shutdown stalls.
        _signal.signal(_signal.SIGTERM, _signal.SIG_DFL)
        raise KeyboardInterrupt

    _signal.signal(_signal.SIGTERM, _handler)


def _signal_stop(pid: int) -> "str | None":
    import signal as _signal

    if pid < 2:
        return f"refusing to signal PID {pid}"
    try:
        if sys.platform == "win32":
            # /T also stops llama-server children, which otherwise keep GPU and port.
            subprocess.run(["taskkill", "/PID", str(pid), "/T", "/F"], check = True)
        else:
            os.kill(pid, _signal.SIGTERM)
    except ProcessLookupError:
        return None
    except Exception as e:
        return str(e)
    return None


@studio_app.command()
def stop():
    """Stop every running Unsloth Studio server for this STUDIO_HOME.

    The port fallback can leave more than one running, so stop them all.
    """
    unreadable: "list[Path]" = []
    entries = _pid_file_entries(unreadable)
    if not entries:
        if unreadable:
            # Reporting success would be a lie: the servers behind the unreadable records are still serving.
            _report_unreadable(unreadable)
            raise typer.Exit(1)
        typer.echo("No running Unsloth server found (no PID file).")
        raise typer.Exit(0)

    signalled, failed, unverified = [], [], []
    for pid, created_times, paths in entries:
        if not _pid_alive(pid):
            for path in paths:
                _unlink_quietly(path)
            continue
        if not _pid_is_studio_server(pid, created_times):
            if pid_reuse_proven(pid, created_times):
                for path in paths:
                    _unlink_quietly(path)
                continue
            unverified.append(pid)
            typer.echo(
                f"Could not verify Unsloth server identity (PID {pid}); kept its PID files.",
                err = True,
            )
            continue
        error = _signal_stop(pid)
        if error is not None:
            failed.append((pid, error))
            typer.echo(f"Failed to stop Unsloth server (PID {pid}): {error}", err = True)
            continue
        typer.echo(f"Sent shutdown signal to Unsloth server (PID {pid}).")
        signalled.append((pid, paths))

    if not signalled and not failed:
        if unverified:
            raise typer.Exit(1)
        if unreadable:
            _report_unreadable(unreadable)
            raise typer.Exit(1)
        typer.echo("No running Unsloth server found (cleaned up stale PID files).")
        raise typer.Exit(0)

    pending = list(signalled)
    # 5 s budget; POSIX checks are one kill(pid, 0), Windows checks may spawn tasklist.
    step = 0.5 if sys.platform == "win32" else 0.05
    for attempt in range(round(5 / step) + 1):
        if not pending:
            break
        if attempt:
            time.sleep(step)
        for entry in list(pending):
            pid, paths = entry
            if not _pid_alive(pid):
                for path in paths:
                    _unlink_quietly(path)
                pending.remove(entry)

    stopped = len(signalled) - len(pending)
    if stopped:
        typer.echo(f"Unsloth server{'s' if stopped > 1 else ''} stopped ({stopped}).")
    for pid, _paths in pending:
        typer.echo(f"Unsloth server (PID {pid}) is shutting down (may take a few seconds).")
    if unreadable:
        _report_unreadable(unreadable)
    if failed or unreadable or unverified:
        raise typer.Exit(1)


def _wait_for_windows_setup_process(process) -> int:
    try:
        return process.wait()
    except BaseException:
        if process.poll() is not None:
            raise
        try:
            subprocess.run(
                ["taskkill", "/PID", str(process.pid), "/T", "/F"],
                stdin = subprocess.DEVNULL,
                stdout = subprocess.DEVNULL,
                stderr = subprocess.DEVNULL,
                check = False,
                **_windows_hidden_subprocess_kwargs(),
            )
        except BaseException:
            # taskkill interrupted or unavailable: hold the gate until setup exits naturally.
            pass
        while process.poll() is None:
            try:
                process.wait()
            except KeyboardInterrupt:
                continue
        raise


# -NoProfile drops $PSDefaultParameterValues, which may hold the only proxy out of a corporate host; a standalone update has no installer to hand it over.
_PROXY_PROBE_BEGIN = "<<UNSLOTH_PROXY_DEFAULTS>>"
_PROXY_PROBE_END = "<</UNSLOTH_PROXY_DEFAULTS>>"

_PS_PROXY_PROBE = (
    "$ErrorActionPreference = 'SilentlyContinue'; "
    # PowerShell 5.1 writes redirected output in the console code page, so a non-ASCII proxy value came back mangled but still parsed as JSON.
    "try { [Console]::OutputEncoding = "
    "New-Object System.Text.UTF8Encoding $false } catch { }; "
    "try { $OutputEncoding = [Console]::OutputEncoding } catch { }; "
    "$PSModuleAutoLoadingPreference = 'All'; "
    # Dot-sourced by name, or this process loads the CONSOLEHOST profile. $PROFILE is populated under -NoProfile.
    "$__unslothHostProfileName = $env:_UNSLOTH_PS_HOST_PROFILE; "
    # All-users first, PowerShell's own startup order, so a user profile overrides it by running last.
    "try { $__unslothProfiles = @($PROFILE.AllUsersAllHosts); "
    # ONLY the caller's host profile: other hosts' profiles can print, clobber the table, or exit.
    "if ($__unslothHostProfileName) { "
    "$__unslothProfiles += (Join-Path (Split-Path -Parent $PROFILE.AllUsersCurrentHost) "
    "$__unslothHostProfileName) }; "
    "$__unslothProfiles += $PROFILE.AllUsersCurrentHost; "
    "$__unslothProfiles += $PROFILE.CurrentUserAllHosts; "
    # ADDED, never substituted: TERM_PROGRAM=vscode is set by every VS Code terminal, so substitution missed a plain pwsh terminal's proxy.
    "if ($__unslothHostProfileName) { "
    "$__unslothProfiles += (Join-Path (Split-Path -Parent $PROFILE.CurrentUserCurrentHost) "
    "$__unslothHostProfileName) }; "
    "$__unslothProfiles += $PROFILE.CurrentUserCurrentHost; "
    "foreach ($__unslothProfile in ($__unslothProfiles | Select-Object -Unique)) { "
    "if ($__unslothProfile -and (Test-Path -LiteralPath $__unslothProfile -PathType Leaf)) { "
    "try { . $__unslothProfile } catch { } } } } catch { }; "
    # Re-pinned: a profile may set [Console]::OutputEncoding, and the parent decodes UTF-8.
    "try { [Console]::OutputEncoding = "
    "New-Object System.Text.UTF8Encoding $false } catch { }; "
    "try { $OutputEncoding = [Console]::OutputEncoding } catch { }; "
    "$out = @{}; "
    "foreach ($k in @($PSDefaultParameterValues.Keys)) { "
    "if ($k -is [string] -and [regex]::IsMatch($k, ':Proxy(Credential|UseDefaultCredentials)?$', "
    "[System.Text.RegularExpressions.RegexOptions]::IgnoreCase)) { "
    "$v = $PSDefaultParameterValues[$k]; "
    "if ($v -is [uri]) { $out[$k] = $v.AbsoluteUri } "
    "elseif ($v -is [string] -or $v -is [bool]) { $out[$k] = $v } "
    # A script block is the supported DYNAMIC default; serialize the RESULT, since executable code must not cross the handoff.
    "elseif ($v -is [scriptblock]) { try { $r = & $v; "
    "if ($r -is [uri]) { $out[$k] = $r.AbsoluteUri } "
    "elseif ($r -is [string] -or $r -is [bool]) { $out[$k] = $r } } catch { } } } }; "
    # $out holds copies, and ConvertTo-Json:AsArray = $true would make this record an array.
    "$PSDefaultParameterValues = @{}; "
    # FRAMED and module-qualified: a profile banner made the parse throw, and an alias could reshape the frame.
    f"if ($out.Count -gt 0) {{ "
    f"Microsoft.PowerShell.Utility\\Write-Output '{_PROXY_PROBE_BEGIN}'; "
    f"$out | Microsoft.PowerShell.Utility\\ConvertTo-Json -Compress; "
    f"Microsoft.PowerShell.Utility\\Write-Output '{_PROXY_PROBE_END}' }}"
)


# What the CALLER's host names its own profile; an unidentifiable host gets none.
_HOST_PROFILE_BY_TERM_PROGRAM = {"vscode": "Microsoft.VSCode_profile.ps1"}


def _caller_host_profile_name() -> Optional[str]:
    term_program = (os.environ.get("TERM_PROGRAM") or "").strip().casefold()
    return _HOST_PROFILE_BY_TERM_PROGRAM.get(term_program)


_WINDOWS_PS_MODULE_DIR = r"System32\WindowsPowerShell\v1.0\Modules"
_WINDOWS_PS_HOSTS = frozenset({"powershell.exe", "powershell", "powershell_ise.exe"})


def _fold_module_entry(entry: str) -> str:
    return entry.replace("/", "\\").rstrip("\\").casefold()


def _windows_powershell_module_path(current: str) -> Optional[str]:
    """``current`` with Windows PowerShell's own module directory first, or None to leave it be: a
    5.1 child started from Python would otherwise resolve its modules to the PowerShell 7 copies."""
    root = os.environ.get("SystemRoot")
    if not root:
        return None
    own = root.rstrip("\\/") + "\\" + _WINDOWS_PS_MODULE_DIR
    entries = [entry for entry in current.split(";") if entry.strip()]
    if entries and _fold_module_entry(entries[0]) == _fold_module_entry(own):
        return None
    kept = [e for e in entries if _fold_module_entry(e) != _fold_module_entry(own)]
    return ";".join([own] + kept)


def _profile_probe_env(host: str = "") -> dict:
    """The probe child's environment: the caller's host profile when it is known, and the probed
    host's own module precedence."""
    env = dict(os.environ)
    name = _caller_host_profile_name()
    if name:
        env["_UNSLOTH_PS_HOST_PROFILE"] = name
    else:
        env.pop("_UNSLOTH_PS_HOST_PROFILE", None)
    if platform.system() == "Windows" and _fold_module_entry(host).rsplit("\\", 1)[-1] in (
        _WINDOWS_PS_HOSTS
    ):
        # os.environ upper-cases keys on Windows, so read PSMODULEPATH or a second, case-differing entry appears.
        key = next((k for k in env if k.upper() == "PSMODULEPATH"), "PSModulePath")
        reordered = _windows_powershell_module_path(env.get(key, ""))
        if reordered:
            env[key] = reordered
    return env


def _framed_probe_record(stdout: str) -> Optional[str]:
    start = stdout.find(_PROXY_PROBE_BEGIN)
    if start < 0:
        return None
    start += len(_PROXY_PROBE_BEGIN)
    end = stdout.find(_PROXY_PROBE_END, start)
    if end < 0:
        return None
    return stdout[start:end].strip() or None


def _profile_probe_hosts() -> list[str]:
    r"""The PowerShell hosts whose profile to ask, caller first. Inferred from PSModulePath by
    ORDER, not absence, since both trees can be present; ambiguous keeps the default order."""
    hosts = ["pwsh.exe", "powershell.exe"]
    module_path = os.environ.get("PSModulePath", "").lower()
    windows_at = module_path.find("windowspowershell")
    seven_at = module_path.find("powershell\\7")
    if windows_at >= 0 and (seven_at < 0 or windows_at < seven_at):
        hosts = ["powershell.exe", "pwsh.exe"]
    return [host for host in hosts if shutil.which(host)]


# Quoted annotations: Python 3.9 evaluates `str | list[str]` at def time and raises TypeError.

_PROFILE_PROBE_TIMEOUT_SECONDS = 20.0


def _probe_profile_proxy_defaults(powershell: "str | list[str]") -> Optional[str]:
    """The caller's profile proxy defaults as JSON, or None. Several hosts MERGE, earlier hosts
    winning per key. Best effort: a broken profile costs one timeout."""
    hosts = [powershell] if isinstance(powershell, str) else list(powershell)
    # ONE budget for the whole probe: two hung profiles must not double the stated cost.
    deadline = time.monotonic() + _PROFILE_PROBE_TIMEOUT_SECONDS
    merged: dict = {}
    claimed: dict = {}
    seen_keys: set = set()
    for host in hosts:
        remaining = deadline - time.monotonic()
        if remaining <= 0:
            break
        try:
            probe = subprocess.run(
                [
                    host,
                    "-NoProfile",
                    "-NonInteractive",
                    "-ExecutionPolicy",
                    "Bypass",
                    "-Command",
                    _PS_PROXY_PROBE,
                ],
                env = _profile_probe_env(host),
                capture_output = True,
                text = True,
                # text=True decodes with the locale codec and STRICT errors, and that UnicodeDecodeError is neither OSError nor SubprocessError.
                encoding = "utf-8",
                errors = "replace",
                timeout = remaining,
                **_windows_hidden_subprocess_kwargs(),
            )
        except (OSError, subprocess.SubprocessError):
            continue
        payload = _framed_probe_record(probe.stdout or "")
        if not payload:
            continue
        try:
            parsed = json.loads(payload)
        except ValueError:
            continue
        if not isinstance(parsed, dict) or not parsed:
            continue
        # Per CMDLET, not per key: pairing one host's Proxy with another's ProxyUseDefaultCredentials would offer Windows credentials to a proxy that never asked.
        for key, value in parsed.items():
            if not isinstance(key, str):
                continue
            cmdlet = key.split(":", 1)[0].casefold()
            folded = key.casefold()
            if _cmdlet_claimed_elsewhere(cmdlet, claimed, parsed):
                continue

            if folded in seen_keys:
                continue
            claimed[cmdlet] = parsed
            seen_keys.add(folded)
            merged[key] = value
    if not merged:
        return None
    return json.dumps(merged)


def _cmdlet_claimed_elsewhere(cmdlet: str, claimed: dict, source: object) -> bool:
    """Whether another host already owns the cmdlet family ``cmdlet`` belongs to. The command"""
    for owned, owner in claimed.items():
        if owner is source:
            continue
        if owned == cmdlet or _patterns_can_overlap(cmdlet, owned):
            return True
    return False


@functools.lru_cache(maxsize = 512)
def _patterns_can_overlap(left: str, right: str) -> bool:
    """Whether any command name matches BOTH wildcard patterns: two can share matches without
    matching each other as strings, so the languages are intersected."""
    if "[" in left or "[" in right:
        return True

    @functools.lru_cache(maxsize = None)
    def walk(i: int, j: int) -> bool:
        # Both patterns are consumed in step, except at '*', which may absorb one more character or none.
        if i == len(left):
            return all(char == "*" for char in right[j:])
        if j == len(right):
            return all(char == "*" for char in left[i:])
        here, there = left[i], right[j]
        if here == "*":
            return walk(i + 1, j) or walk(i, j + 1)
        if there == "*":
            return walk(i, j + 1) or walk(i + 1, j)
        if here == "?" or there == "?" or here == there:
            return walk(i + 1, j + 1)
        return False

    return walk(0, 0)


_PS_PROXY_DEFAULTS_PRELUDE = (
    "$__unslothProxyDefaults = $env:_UNSLOTH_PS_PROXY_DEFAULTS; "
    # Read once, then GONE: a profile proxy can carry credentials every native process would inherit.
    "Remove-Item Env:_UNSLOTH_PS_PROXY_DEFAULTS -ErrorAction SilentlyContinue; "
    "if ($__unslothProxyDefaults) { try { "
    "(ConvertFrom-Json $__unslothProxyDefaults).PSObject.Properties | ForEach-Object { "
    "$PSDefaultParameterValues[$_.Name] = $_.Value } } catch { } }; "
)


_UV_CACHE_BUCKETS = ("archive", "builds", "built-wheels", "wheels", "sdists")
# Only the stores `uv pip install` creates (setup.sh runs nothing else); probing others discards
# warm caches. Re-measure on a uv pin bump.
_UV_PIP_STORES = (
    "archive",
    "builds",
    "built-wheels",
    "git",
    "interpreter",
    "sdists",
    "simple",
    "wheels",
)
_UV_CACHE_METADATA_SUFFIXES = (".lock", ".msgpack", ".http", ".rev")


def _uv_is_bucket_name(name: str) -> bool:
    """A name uv itself creates: <kind>-v<N>, whole suffix numeric, kind from the LAST `-v`.
    Same shape rule as _uv_is_bucket_name in install.sh and Test-StudioUvBucketName in
    install.ps1, over the narrower kind list: this one only answers whether a bucket holds
    package BYTES, where the installers also probe the kinds uv merely writes."""
    kind, marker, version = name.rpartition("-v")
    # isascii too: isdigit() accepts non-ASCII digits, which the sh and PowerShell checks reject.
    return bool(marker) and version.isascii() and version.isdigit() and kind in _UV_CACHE_BUCKETS


def _uv_bucket_entry_name(cache_dir: Path, entry: Path) -> Optional[str]:
    """The name uv opens this entry as, or None if uv does not own it.

    On APFS or NTFS `Archive-V0` IS the directory uv writes at `archive-v0`, so a case-sensitive
    match called a full cache cold while studio/setup.sh, which folds, called it warm, and the
    two then chose different caches. samefile rather than a write probe: only existing entries
    matter here, so the filesystem can be asked without creating anything."""
    if _uv_is_bucket_name(entry.name):
        return entry.name
    lowered = entry.name.lower()
    if lowered == entry.name or not _uv_is_bucket_name(lowered):
        return None
    try:
        return lowered if (cache_dir / lowered).samefile(entry) else None
    except OSError:
        return None


def _uv_cache_has_packages(cache_dir: Path) -> bool:
    """wheels-* is metadata only on uv 0.10, so counting any file reads a merely-resolved cache
    as warm. Same rule as install.sh:_configure_uv_cache, the WHOLE `-v` suffix included: a
    prefix match also takes `archive-v0.backup` and `archive-backup-v0`, whose bytes uv cannot
    reuse, so an update could prefer a cache that is cold in practice and redownload."""
    try:
        buckets = [
            entry
            for entry in cache_dir.iterdir()
            if entry.is_dir() and _uv_bucket_entry_name(cache_dir, entry) is not None
        ]
    except (OSError, ValueError):
        return False
    for bucket in buckets:
        for _root, _dirs, files in os.walk(bucket):
            for name in files:
                if name in ("CACHEDIR.TAG", ".git", ".gitignore"):
                    continue
                if name.endswith(_UV_CACHE_METADATA_SUFFIXES):
                    continue
                return True
    return False


def _uv_platform_cache_dir() -> Optional[Path]:
    if platform.system() == "Windows":
        local_app_data = (os.environ.get("LOCALAPPDATA") or "").strip()
        return Path(local_app_data) / "uv" / "cache" if local_app_data else None
    xdg = (os.environ.get("XDG_CACHE_HOME") or "").strip()
    if xdg:
        return Path(xdg) / "uv"
    home = (os.environ.get("HOME") or "").strip()
    return Path(home) / ".cache" / "uv" if home else None


# clap's BoolishValueParser literals for UV_NO_CACHE.
_UV_TRUE = ("1", "y", "yes", "t", "true", "on")


def _uv_no_cache_requested() -> bool:
    """uv --no-cache discards its cache and outranks --cache-dir, so recording it aims updates at a
    nonexistent cache; UV_NO_CACHE is not stripped, so a padded value leaves the uv cache on and
    this must not stand the selection down."""
    return (os.environ.get("UV_NO_CACHE") or "").lower() in _UV_TRUE


def _uv_default_cache_dir(cwd: Optional[Path] = None) -> Optional[Path]:
    """Asked of uv, not reconstructed, so uv.toml and UV_CONFIG_FILE count, and asked from where
    setup will ask it, since uv discovers uv.toml from its working directory."""
    uv = shutil.which("uv")
    if not uv:
        return _uv_platform_cache_dir()
    child_env = {key: value for key, value in os.environ.items() if key != "UV_CACHE_DIR"}
    try:
        result = subprocess.run(
            [uv, "cache", "dir"],
            cwd = str(cwd) if cwd is not None else None,
            capture_output = True,
            text = True,
            encoding = "utf-8",
            errors = "replace",
            env = child_env,
            timeout = 30,
            **_windows_hidden_subprocess_kwargs(),
        )
    except Exception:
        return _uv_platform_cache_dir()
    if result.returncode != 0:
        # A malformed uv.toml beside the CALLER fails this, though setup.sh runs uv elsewhere.
        return _uv_platform_cache_dir()
    lines = [line for line in (result.stdout or "").splitlines() if line.strip()]
    if not lines:
        return _uv_platform_cache_dir()
    # uv answers a relative cache-dir against its own working directory. No expanduser: uv makes a literal "~" directory.
    probe_cwd = str(cwd) if cwd is not None else os.getcwd()
    working = os.environ.get("UV_WORKING_DIR")
    base = os.path.join(probe_cwd, working) if working else probe_cwd
    return Path(os.path.abspath(os.path.join(base, lines[-1])))


def _recorded_install_uv_cache() -> Optional[Path]:
    """The cache the installer used, as it recorded it. Content cannot tell a Studio cache the
    installer filled from one holding a single wheel the backend dropped there."""
    try:
        recorded = (STUDIO_HOME / "cache" / "uv-cache-dir").read_text(
            encoding = "utf-8-sig", errors = "surrogateescape"
        )
    except OSError:
        return None
    # One record, one trailing delimiter, path before it: splitting on lines would break a path containing a newline.
    if recorded.endswith("\n"):
        recorded = recorded[:-1]
    if recorded.endswith("\r"):
        recorded = recorded[:-1]
    if not recorded.strip():
        return None
    return Path(os.path.abspath(recorded))


def _backfill_uv_cache_marker(env: Optional[dict]) -> None:
    """Record the cache this update used, for installs whose installer never did; otherwise they
    stay on the content fallback, which goes stale once the backend drops a wheel in."""
    if (os.environ.get("UV_CACHE_DIR") or "").strip():
        return
    if _uv_no_cache_requested():
        return
    chosen = (env or {}).get("UV_CACHE_DIR")
    if not chosen:
        return
    live = _recorded_install_uv_cache()
    if live is not None and _uv_cache_has_packages(live):
        return
    stage_root = (os.environ.get(_studio_stage.STAGE_ROOT_ENV) or "").strip()
    if stage_root:
        # A 805-807 desktop shell ran the OLD CLI with --stage and it is running this setup inside its stage, so park the choice for its stage() to promote.
        marker = Path(stage_root) / _studio_stage.UV_CACHE_MARKER
    else:
        marker = STUDIO_HOME / "cache" / "uv-cache-dir"
    try:
        marker.parent.mkdir(parents = True, exist_ok = True)
        marker.unlink(missing_ok = True)
        # fsencode: an undecodable path arrives as surrogates and raises UnicodeEncodeError, not OSError.
        marker.write_bytes(os.fsencode(f"{chosen}\n"))
    except (OSError, ValueError):
        pass


def _uv_is_store_name(name: str) -> bool:
    """The kinds `uv pip install` writes: _uv_is_bucket_name answers warmth, this answers what a
    write probe has to cover. Narrower than install.sh's list on purpose, since install.sh also
    runs uv venv and uv python; re-read uv-cache/src/lib.rs on a pin bump."""
    kind, marker, version = name.rpartition("-v")
    return bool(marker) and version.isascii() and version.isdigit() and kind in _UV_PIP_STORES


def _uv_cache_folds_case(cache_dir: Path) -> bool:
    """Measured on the cache filesystem, not assumed from the platform, exactly as install.sh
    does it: default APFS folds, ext4 does not, and a Mac can have either mounted."""
    probe = cache_dir / f".unsloth-case-probe.{os.getpid()}-A"
    try:
        probe.mkdir()
    except OSError:
        return False
    try:
        return (cache_dir / f".unsloth-case-probe.{os.getpid()}-a").is_dir()
    finally:
        try:
            probe.rmdir()
        except OSError:
            pass


def _uv_cache_is_writable(cache_dir: Path) -> bool:
    """A real create, as install.sh's write probe does: mode bits do not answer for a network mount, and uv aborts on a cache it
    cannot write rather than falling back.

    The stores too, not just the root: uv writes into them, so a root-only probe passes on a
    cache uv then aborts on. Mirrors install.sh's _uv_cache_is_writable."""
    probes = [cache_dir]
    folds = _uv_cache_folds_case(cache_dir)
    try:
        # Only the directories uv owns.
        for entry in cache_dir.iterdir():
            if not _uv_is_store_name(entry.name):
                # On APFS or NTFS `Python-V0` is the same path as `python-v0`.
                if not (folds and _uv_is_store_name(entry.name.lower())):
                    continue
            if not entry.is_dir():
                # A file or any symlink is an existing path uv cannot mkdir.
                return False
            probes.append(entry)
            # One level inside the index stores: uv rewrites this metadata every resolve, so a foreign-owned
            # shard aborts it (measured on uv 0.12.1 and 0.10.7). Bounded on purpose.
            if entry.name.lower().startswith(("simple-", "wheels-")):
                # `index/<hash>` holds custom-index metadata (Studio's torch index); a read-only one aborts uv.
                shards = list(entry.iterdir())
                index_dir = entry / "index"
                if index_dir.is_dir():
                    shards.extend(index_dir.iterdir())
                for shard in shards:
                    if not shard.is_dir():
                        # A file or any symlink here aborts uv too.
                        return False
                    probes.append(shard)
    except OSError:
        return False
    for target in probes:
        try:
            with tempfile.NamedTemporaryFile(dir = target, prefix = ".unsloth-write-probe."):
                pass
        except OSError:
            return False
    # Only names uv is measured to need writable (root .lock, sdists-v9/.git); rejecting more throws
    # away the warm cache.
    for target in probes:
        if target == cache_dir:
            names = (".lock",)
        elif target.name.lower().startswith("sdists-"):
            # The one store measured to abort on a read-only .git; rejecting a cache uv accepts loses the warm cache this path exists to find.
            names = (".git",)
        else:
            continue
        for name in names:
            control = target / name
            if not control.exists() and not control.is_symlink():
                continue
            # A `.lock` directory or symlink to one also aborts uv.
            if not control.is_file() or not os.access(control, os.R_OK | os.W_OK):
                return False
    return True


def _with_studio_uv_cache(env: Optional[dict], cwd: Optional[Path] = None) -> Optional[dict]:
    """Without the installer or _setup_cache_env, uv re-downloads what the install fetched."""
    if (os.environ.get("UV_CACHE_DIR") or "").strip():
        return env
    if _uv_no_cache_requested():
        # Removed: uv reads an exported EMPTY value as `--cache-dir ''` and exits 2, even with --no-cache.
        no_cache = {**(env or os.environ)}
        no_cache.pop("UV_CACHE_DIR", None)
        return no_cache
    studio_cache = STUDIO_HOME / "cache" / "uv"
    recorded = _recorded_install_uv_cache()
    if (
        recorded is not None
        and _uv_cache_has_packages(recorded)
        and _uv_cache_is_writable(recorded)
    ):
        # Only while non-empty and writable: setup treats this as the caller's choice, so a read-only one would abort every uv command.
        return {**(env or os.environ), "UV_CACHE_DIR": str(recorded)}
    # Order by location, not content: one wheel warms the Studio cache even in shared mode, so uv's default goes first, then a warm Studio cache.
    default_cache = _uv_default_cache_dir(cwd)
    if (
        default_cache is not None
        and _uv_cache_has_packages(default_cache)
        and _uv_cache_is_writable(default_cache)
    ):
        return {**(env or os.environ), "UV_CACHE_DIR": str(default_cache)}
    # setup.sh skips its probe for inherited UV_CACHE_DIR, so probe here; never create the root, or setup's fail-fast on a typo is defeated.
    if STUDIO_HOME.is_dir():
        try:
            studio_cache.mkdir(parents = True, exist_ok = True)
        except OSError:
            pass
        if not _uv_cache_is_writable(studio_cache):
            # Explicitly absent: setup.sh's own probe wants the variable gone.
            unset = {**(env or os.environ)}
            unset.pop("UV_CACHE_DIR", None)
            return unset
    return {**(env or os.environ), "UV_CACHE_DIR": str(studio_cache)}


def _with_studio_uv(env: Optional[dict]) -> Optional[dict]:
    """An install with a custom UNSLOTH_STUDIO_HOME keeps its uv-managed Python in <home>/python
    and its own uv in <home>/uv; only that installer creates <home>/python. Without this, setup
    would put a missing or stale uv, and any managed Python, in the profile. setup version-checks
    the uv it finds there and replaces it in place; a uv already on PATH is used as before."""
    try:
        if (
            not _STUDIO_HOME_IS_CUSTOM
            or STUDIO_HOME.resolve() == (Path.home() / ".unsloth" / "studio").resolve()
        ):
            return env
    except (OSError, RuntimeError, ValueError):
        return env
    if not (STUDIO_HOME / "python").is_dir():
        return env
    out = {**(env if env is not None else os.environ)}
    if not (out.get("UV_PYTHON_INSTALL_DIR") or "").strip():
        out["UV_PYTHON_INSTALL_DIR"] = str(STUDIO_HOME / "python")
    # astral's unmanaged mode: that directory, no profile or user PATH edit (setup.sh, setup.ps1).
    if not any(
        (out.get(k) or "").strip()
        for k in ("UV_INSTALL_DIR", "UV_UNMANAGED_INSTALL", "XDG_BIN_HOME")
    ):
        out["UV_UNMANAGED_INSTALL"] = str(STUDIO_HOME / "uv")
    return out


def _run_setup_script(*, verbose: bool = False, repo_root: Optional[Path] = None) -> None:
    script = _find_setup_script(repo_root)
    if not script:
        if repo_root is not None:
            name = "setup.ps1" if platform.system() == "Windows" else "setup.sh"
            typer.echo(f"Error: {repo_root} has no studio/{name}.", err = True)
            typer.echo("  --local needs a complete checkout: the setup script builds", err = True)
            typer.echo("  the frontend into the tree that is installed editable.", err = True)
        else:
            typer.echo("Error: Could not find setup script (setup.sh / setup.ps1).")
        raise typer.Exit(1)

    env = {**os.environ, "UNSLOTH_VERBOSE": "1"} if verbose else None
    # Where setup runs uv from: setup.sh cds into its own directory, setup.ps1 keeps this cwd.
    setup_cwd = None if platform.system() == "Windows" else script.parent
    env = _with_studio_uv_cache(env, cwd = setup_cwd)
    env = _with_studio_uv(env)
    # Saves setup.ps1 the process walk. A HINT, not a promise: only the desktop spawn guarantees
    # the managed venv's python, while a pip install, a checkout or a staged run puts an
    # interpreter here that is nowhere near $VenvDir. Get-SetupHostInterpreterInVenv tests
    # containment itself, so presence of this name is never proof setup runs from the venv.
    env = {**(env or os.environ), "UNSLOTH_SETUP_HOST_PYTHON": sys.executable}

    if platform.system() == "Windows":
        # Resolved, not bare: PATH is not trusted here (#9440) and the Popen below has no OSError handler.
        powershell = _studio_runtime_gate.resolve_windows_powershell()
        powershell_args = [powershell]
        # PRESENCE, not truthiness: install.ps1 sets this to "{}" when it found no proxy, and reloading the profiles it discarded would undo that.
        if os.environ.get("_UNSLOTH_PS_PROXY_DEFAULTS") is None:
            probed = _probe_profile_proxy_defaults(_profile_probe_hosts() or [powershell])
            if probed:
                env = {**(env or os.environ), "_UNSLOTH_PS_PROXY_DEFAULTS": probed}
        # -NoProfile unconditionally: install.ps1 hands off from a tty console, and a profile aliasing uv or python would break setup.ps1.
        powershell_args.append("-NoProfile")
        if _should_hide_windows_subprocesses():
            # Match install.rs: avoid the Hidden/Bypass detection pair; CREATE_NO_WINDOW below already hides the console.
            powershell_args.extend(["-NoLogo", "-NonInteractive"])
        # -Command + `*>&1` (not -File) so setup.ps1's Write-Host output merges into stdout; -File drops it when stdout is a pipe. Single quotes are doubled for paths with apostrophes.
        script_pwsh_literal = str(script).replace("'", "''")
        powershell_args.extend(
            [
                "-ExecutionPolicy",
                "Bypass",
                "-Command",
                f"{_PS_PROXY_DEFAULTS_PRELUDE}& '{script_pwsh_literal}' *>&1",
            ]
        )
        # Popen defaults to close_fds=True on Windows, so with CREATE_NO_WINDOW the child has no console and Write-Host writes to nothing.
        process = subprocess.Popen(
            powershell_args,
            env = env,
            stdin = _stream_for_subprocess(sys.stdin),
            stdout = _stream_for_subprocess(sys.stdout),
            stderr = _stream_for_subprocess(sys.stderr),
            **_windows_hidden_subprocess_kwargs(),
        )
        returncode = _wait_for_windows_setup_process(process)
    else:
        result = subprocess.run(["bash", str(script)], env = env)
        returncode = result.returncode

    if returncode != 0:
        raise typer.Exit(returncode)
    _backfill_uv_cache_marker(env)


# Fetched rather than shipped, so a launcher fix reaches users without waiting for a release.
_INSTALLER_URL_BASH = "https://unsloth.ai/install.sh"
_INSTALLER_URL_PWSH = "https://unsloth.ai/install.ps1"
_INSTALLER_FETCH_HOSTS = frozenset({"unsloth.ai", "raw.githubusercontent.com"})
_INSTALLER_FETCH_TIMEOUT = 30
_INSTALLER_MAX_BYTES = 8 * 1024 * 1024
# The flag this code passes: internal names would be tighter but can be renamed, and a false negative skips every refresh.
_INSTALLER_MARKERS = {
    "install.sh": (b"--shortcuts-only",),
    "install.ps1": (b"--shortcuts-only",),
}


def _is_allowed_installer_url(url: str) -> bool:
    split = urllib.parse.urlsplit(url)
    return split.scheme == "https" and split.hostname in _INSTALLER_FETCH_HOSTS


class _InstallerRedirectHandler(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        if not _is_allowed_installer_url(newurl):
            raise urllib.error.URLError(f"refused installer redirect to {newurl}")
        return super().redirect_request(req, fp, code, msg, headers, newurl)


def _build_installer_opener() -> urllib.request.OpenerDirector:
    """A private opener, so the redirect chain can be checked before it is followed. The installed
    opener cannot be reused: add_handler assigns handler.parent and would repoint it at this one."""
    return urllib.request.build_opener(_InstallerRedirectHandler)


def _looks_like_installer(body: Optional[bytes], installer_name: str) -> bool:
    """Cheap shape check before a fetched installer is executed. Not a trust check: it stops a
    captive-portal page or an error body from being piped into bash."""
    if not body or len(body) < 512:
        return False
    head = body.lstrip()[:256].lower()
    # `<#` opens PowerShell comment-based help, an ordinary start for install.ps1.
    if not head.startswith(b"<#") and (
        head.startswith((b"<!doctype", b"<html", b"<head", b"<?xml", b"<body"))
        or b"<html" in head
        or b"<!doctype" in head
    ):
        return False
    return all(marker in body for marker in _INSTALLER_MARKERS[installer_name])


def _fetch_installer(installer_name: str, *, verbose: bool = False) -> Optional[bytes]:
    """Fetch install.sh / install.ps1, or None if nothing usable came back."""
    url = _INSTALLER_URL_PWSH if installer_name == "install.ps1" else _INSTALLER_URL_BASH
    if not _is_allowed_installer_url(url):
        typer.echo(f"  refresh-launcher  refusing to fetch {installer_name} from {url}")
        return None
    try:
        opener = _build_installer_opener()
        request = urllib.request.Request(url, headers = {"User-Agent": "unsloth-studio-update"})
        with opener.open(request, timeout = _INSTALLER_FETCH_TIMEOUT) as response:
            body = response.read(_INSTALLER_MAX_BYTES + 1)
            # read(amt) does not check Content-Length; only a further read() raises IncompleteRead on a truncated transfer.
            if len(body) <= _INSTALLER_MAX_BYTES:
                body += response.read()
    except (
        urllib.error.URLError,
        # Raised at the HTTP framing layer, which is neither URLError nor OSError.
        http.client.HTTPException,
        TimeoutError,
        OSError,
        ValueError,
    ) as exc:
        typer.echo(f"  refresh-launcher  skipped: could not fetch {url} ({exc})")
        return None

    if len(body) > _INSTALLER_MAX_BYTES:
        typer.echo(f"  refresh-launcher  skipped: oversized {installer_name} response")
        return None
    if not _looks_like_installer(body, installer_name):
        typer.echo(f"  refresh-launcher  skipped: response is not {installer_name}")
        return None
    if verbose:
        typer.echo(f"  refresh-launcher  fetched {url} ({len(body)} bytes)")
    return body


def _installer_script_candidates(installer_name: str) -> List[Path]:
    """Source-tree installers, which outrank the network because `update --local` is testing
    its own installer."""
    candidates: List[Path] = []
    local_repo = (os.environ.get("STUDIO_LOCAL_REPO") or "").strip()
    if local_repo:
        candidates.append(Path(local_repo).expanduser() / installer_name)
    # Clone or editable install: _PACKAGE_ROOT is the repo root.
    root = _PACKAGE_ROOT / installer_name
    if root not in candidates:
        candidates.append(root)
    return candidates


def _installers_on_disk(candidates: Sequence[Path]) -> List[Path]:
    """Every candidate that exists, not just the first: an unlaunchable candidate must still
    leave the next one to try before the network is reached."""
    found: List[Path] = []
    for candidate in candidates:
        try:
            if candidate.is_file():
                found.append(candidate)
        except OSError:
            continue
    return found


def _refresh_desktop_shortcuts(*, verbose: bool = False) -> None:
    """Re-run installer with --shortcuts-only to refresh launchers post-update."""
    env = {**os.environ}
    if verbose:
        env["UNSLOTH_VERBOSE"] = "1"

    is_windows = platform.system() == "Windows"
    installer_name = "install.ps1" if is_windows else "install.sh"

    args = ["--shortcuts-only"]
    if verbose:
        args.append("--verbose")

    checkouts = _installers_on_disk(_installer_script_candidates(installer_name))

    if is_windows:
        ps_argv: List[str] = [_studio_runtime_gate.resolve_windows_powershell()]
        # -NoProfile unconditionally, as in _run_setup_script: the visible console path loads a profile.
        ps_argv.append("-NoProfile")
        if _should_hide_windows_subprocesses():
            # Avoid the Hidden/Bypass detection pair, as in setup above.
            ps_argv.extend(["-NoLogo", "-NonInteractive"])

        # Stops at the first candidate that launched; only an unlaunchable one moves on.
        if any(_run_installer_ps1(script, args, ps_argv, env) for script in checkouts):
            return
        fetched = _fetch_installer(installer_name, verbose = verbose)
        if fetched is not None:
            _run_fetched_installer_ps1(fetched, args, ps_argv, env)
        return

    if any(_run_installer_bash(script, args, env) for script in checkouts):
        return
    fetched = _fetch_installer(installer_name, verbose = verbose)
    if fetched is not None:
        _run_fetched_installer_bash(fetched, args, env)


def _run_installer_bash(script: Path, args: Sequence[str], env: dict) -> bool:
    """False when the interpreter could not be launched, so the caller can fall back to the
    next candidate and then the network instead of ending the refresh early."""
    try:
        result = subprocess.run(["bash", str(script), *args], env = env, check = False)
    except OSError:
        return False
    if result.returncode != 0:
        typer.echo(f"  refresh-launcher  {script.name} exited {result.returncode}")
    return True


def _run_fetched_installer_bash(installer: bytes, args: Sequence[str], env: dict) -> None:
    try:
        result = subprocess.run(["bash", "-s", "--", *args], input = installer, env = env, check = False)
    except OSError as exc:
        typer.echo(f"  refresh-launcher  skipped: bash exec failed ({exc})")
        return
    if result.returncode != 0:
        typer.echo(f"  refresh-launcher  fetched install.sh exited {result.returncode}")


def _run_installer_ps1(
    script: Path, args: Sequence[str], ps_argv: Sequence[str], env: dict
) -> bool:
    """False when powershell.exe could not be launched. See _run_installer_bash."""
    quoted = str(script).replace("'", "''")
    argv = list(ps_argv)
    argv.extend(["-ExecutionPolicy", "Bypass", "-Command", f"& '{quoted}' {' '.join(args)} *>&1"])
    try:
        result = subprocess.run(argv, env = env, check = False, **_windows_hidden_subprocess_kwargs())
    except OSError:
        return False
    if result.returncode != 0:
        typer.echo(f"  refresh-launcher  {script.name} exited {result.returncode}")
    return True


def _run_fetched_installer_ps1(
    installer: bytes, args: Sequence[str], ps_argv: Sequence[str], env: dict
) -> None:
    """Run a fetched install.ps1 from a tempfile. -File rather than `-Command -`: stdin decoding
    mangles install.ps1's box-drawing chars, and args go after the path so `Install-UnslothStudio
    @args` receives them. A tempfile that cannot be written is reported and skipped."""
    try:
        ps1_fd, ps1_path = tempfile.mkstemp(prefix = "unsloth-studio-refresh-", suffix = ".ps1")
    except OSError as exc:
        typer.echo(f"  refresh-launcher  skipped: could not create a temp script ({exc})")
        return
    try:
        try:
            with os.fdopen(ps1_fd, "wb") as fh:
                fh.write(b"\xef\xbb\xbf" + installer)
        except OSError as exc:
            typer.echo(f"  refresh-launcher  skipped: could not write the temp script ({exc})")
            return
        argv = list(ps_argv)
        argv.extend(["-ExecutionPolicy", "Bypass", "-File", ps1_path, *args])
        try:
            result = subprocess.run(
                argv, env = env, check = False, **_windows_hidden_subprocess_kwargs()
            )
        except OSError as exc:
            typer.echo(f"  refresh-launcher  skipped: powershell exec failed ({exc})")
            return
        if result.returncode != 0:
            typer.echo(f"  refresh-launcher  fetched install.ps1 exited {result.returncode}")
    finally:
        try:
            os.unlink(ps1_path)
        except OSError:
            pass


@studio_app.command(hidden = True)
def setup(
    verbose: bool = typer.Option(
        False,
        "--verbose",
        "-v",
        help = "Full pip/build output during setup for troubleshooting.",
    ),
):
    """Run Unsloth setup (called by install.ps1 / install.sh)."""
    runtime_gate_handoff = _studio_runtime_gate.consume_runtime_gate_handoff()
    with _studio_runtime_launch_guard(inherited = runtime_gate_handoff):
        _studio_runtime_gate.ensure_managed_environment_is_idle(STUDIO_HOME)
        # Duplicate-metadata repair can reinstall unsloth even under SKIP_STUDIO_BASE, so free the running Windows launcher.
        with _WindowsLauncherUpdateTransaction() as launcher_update:
            _run_setup_script(verbose = verbose)
            launcher_update.validate_launcher()


def _fail_if_install_damaged(package_name: str = "unsloth") -> None:
    """Refuse to call an update successful when the tree it produced is damaged: pip treats intact
    metadata as satisfied, so the update exits 0 and the backend dies at boot."""
    managed_venv = _studio_stage.runtime_root(STUDIO_HOME) / "unsloth_studio"
    if _studio_deps.running_outside_managed_venv((managed_venv,)):
        # This CLI is not in the venv the update wrote, so its file list describes the wrong tree.
        return
    managed_names = (package_name, "unsloth-zoo")
    managed_conflicts = _studio_deps.installed_metadata_conflicts(names = managed_names)
    if managed_conflicts:
        typer.echo("", err = True)
        typer.echo("Update finished, but Unsloth package metadata is inconsistent:", err = True)
        for entry in managed_conflicts:
            typer.echo(f"  {entry}", err = True)
        typer.echo("", err = True)
        typer.echo("The file check cannot safely choose between these records.", err = True)
        typer.echo("The installer could not repair its managed package metadata.", err = True)
        typer.echo(
            "Recreate the managed environment before running the Unsloth installer again.", err = True
        )
        typer.echo("", err = True)
        typer.echo(
            "To update anyway without this check: unsloth studio update --no-verify", err = True
        )
        raise typer.Exit(code = 1)
    other_conflicts = _studio_deps.installed_metadata_conflicts(exclude_names = managed_names)
    if other_conflicts:
        typer.echo("", err = True)
        typer.echo("Warning: some other packages have duplicate metadata:", err = True)
        for entry in other_conflicts:
            typer.echo(f"  {entry}", err = True)
        typer.echo("", err = True)
        typer.echo("Unsloth skipped file verification for these packages.", err = True)
        typer.echo(
            "Reinstall the intended version from its original package source, or use a clean environment.",
            err = True,
        )
    damaged = _studio_deps.damaged_installed_files()
    if not damaged:
        return
    typer.echo("", err = True)
    typer.echo("Update finished, but some installed files are damaged:", err = True)
    for entry in damaged:
        typer.echo(f"  {entry}", err = True)
    typer.echo("", err = True)
    typer.echo("An update cannot repair these. pip sees intact package metadata and", err = True)
    typer.echo("reinstalls nothing, so Unsloth will keep failing to start. Reinstall", err = True)
    typer.echo("over the top:", err = True)
    # Carry the custom root and the recorded install mode, or the reinstall builds a fresh ~/.unsloth/studio and pulls the whole PyTorch stack. No root argument: recorded_no_torch reads the VENV.
    no_torch = False
    try:
        _manifest = _studio_deps.load_install_manifest_module()
        no_torch = _manifest is not None and _manifest.recorded_no_torch() is True
    except Exception:
        no_torch = False
    if platform.system() == "Windows":
        prefix = ""
        if _STUDIO_HOME_IS_CUSTOM:
            prefix = "$env:UNSLOTH_STUDIO_HOME = '{}'; ".format(str(STUDIO_HOME).replace("'", "''"))
        if no_torch:
            prefix += "$env:UNSLOTH_NO_TORCH = '1'; "
        typer.echo(f"  {prefix}irm https://unsloth.ai/install.ps1 | iex", err = True)
    else:
        # The assignments go before `sh`, not before `curl`: that is the form install.sh documents.
        env = ""
        if _STUDIO_HOME_IS_CUSTOM:
            env = f"UNSLOTH_STUDIO_HOME={shlex.quote(str(STUDIO_HOME))} "
        if no_torch:
            env += "UNSLOTH_NO_TORCH=1 "
        typer.echo(f"  curl -fsSL https://unsloth.ai/install.sh | {env}sh", err = True)
    typer.echo("", err = True)
    # The installer installs only the current requirement sets, so a leftover package is not repaired by the command above.
    typer.echo("If a package above is still listed after that, the installer does not", err = True)
    typer.echo("manage it. Repair it directly, or remove it if nothing needs it:", err = True)
    # --no-deps, or --force-reinstall could swap the installed CUDA/ROCm torch build; <package>==<version>, or it upgrades the orphan its consumers pinned.
    _spec = "<package>==<installed version>"
    if platform.system() == "Windows":
        _py = str(Path(sys.executable)).replace("'", "''")
        typer.echo(f"  & '{_py}' -m pip install --force-reinstall --no-deps {_spec}", err = True)
    else:
        _py = shlex.quote(str(Path(sys.executable)))
        typer.echo(f"  {_py} -m pip install --force-reinstall --no-deps {_spec}", err = True)
    typer.echo("", err = True)
    typer.echo("To update anyway without this check: unsloth studio update --no-verify", err = True)
    raise typer.Exit(code = 1)


@studio_app.command()
def update(
    local: bool = typer.Option(False, "--local", help = "Install from local repo instead of PyPI"),
    package: str = typer.Option(
        "unsloth", "--package", help = "Package name to install/update (for testing)"
    ),
    verbose: bool = typer.Option(
        False,
        "--verbose",
        "-v",
        help = "Full pip/build output during update for troubleshooting.",
    ),
    verify: bool = typer.Option(
        True,
        "--verify/--no-verify",
        help = "After updating, scan installed files for damage an update cannot repair.",
    ),
    stage: bool = typer.Option(
        False,
        "--stage",
        hidden = True,
        help = "Accepted for 805-807 desktop shells, which get a refusal. Background staging is gone.",
    ),
):
    """Update Unsloth Studio dependencies and rebuild."""
    # Re-export UNSLOTH_STUDIO_HOME so the refresh subprocess resolves the same install root.
    _ensure_studio_env_exported()
    # `is True`, not truthiness: an in-process caller that omits it gets a truthy OptionInfo sentinel.
    if stage is True:
        _refuse_staged_update()
        return
    staging = _studio_stage.is_staging()
    # Do not inherit SKIP_STUDIO_BASE from a parent install.ps1 session.
    os.environ.pop("SKIP_STUDIO_BASE", None)
    os.environ["STUDIO_PACKAGE_NAME"] = package
    repo_root: Optional[Path] = None
    if local:
        os.environ["STUDIO_LOCAL_INSTALL"] = "1"
        # Explicit repo root: __file__ holds only from a checkout, and once unsloth is installed non-editably parents[2] IS site-packages, which uv rejects.
        _explicit = (os.environ.get("STUDIO_LOCAL_REPO") or "").strip()
        repo_root = (
            Path(_explicit).expanduser().resolve()
            if _explicit
            else Path(__file__).resolve().parents[2]
        )
        if not (repo_root / "pyproject.toml").is_file():
            typer.echo("Error: --local needs an Unsloth checkout to install from.", err = True)
            typer.echo(f"  no pyproject.toml under: {repo_root}", err = True)
            typer.echo("  This CLI is running from an installed copy, not a source tree.", err = True)
            typer.echo("", err = True)
            typer.echo("  Point at a checkout:", err = True)
            if platform.system() == "Windows":
                # PowerShell has no `VAR=value command` prefix form, and this guard fires on the Windows path.
                typer.echo(
                    "    $env:STUDIO_LOCAL_REPO='C:\\path\\to\\unsloth'; "
                    "unsloth studio update --local",
                    err = True,
                )
            else:
                typer.echo(
                    "    STUDIO_LOCAL_REPO=/path/to/unsloth unsloth studio update --local",
                    err = True,
                )
            typer.echo("  Or update from PyPI:", err = True)
            typer.echo("    unsloth studio update", err = True)
            raise typer.Exit(2)
        os.environ["STUDIO_LOCAL_REPO"] = str(repo_root)
    else:
        os.environ["STUDIO_LOCAL_INSTALL"] = "0"
        os.environ.pop("STUDIO_LOCAL_REPO", None)
    # The gate keeps a second Unsloth process off the venv; the transaction keeps the launcher recoverable across setup.
    runtime_gate_handoff = _studio_runtime_gate.consume_runtime_gate_handoff()
    with _studio_runtime_launch_guard(inherited = runtime_gate_handoff or staging):
        if not staging:
            _studio_runtime_gate.ensure_managed_environment_is_idle(STUDIO_HOME)
        # Constructed after the idle scan (pinned by test_studio_runtime_gate).
        launcher_transaction = _WindowsLauncherUpdateTransaction()
        if staging:
            # A staged run writes no launcher.
            launcher_transaction.enabled = False
        with launcher_transaction as launcher_update:
            _run_setup_script(verbose = verbose, repo_root = repo_root)
            # Runs even with --no-verify: a successful update must leave its own launcher usable.
            launcher_update.validate_launcher()
            if verify:
                _fail_if_install_damaged(package)
    # Tauri desktop owns its own bundle entries; refreshing here would duplicate shortcuts.
    if staging or os.environ.get("UNSLOTH_TAURI_UPDATE") == "1":
        if verbose:
            typer.echo("  refresh-launcher  skipped (Tauri update)")
        return
    _refresh_desktop_shortcuts(verbose = verbose)


def _discard_orphaned_stage() -> None:
    """Take a leftover `.update-stage` out of an 805-807 shell's way: they map any stage directory
    to `stage` and re-spawn `--stage` forever. Renamed before deleting."""
    stage = STUDIO_HOME / _studio_stage.STAGE_DIR_NAME
    if not os.path.lexists(stage):
        return
    aside = STUDIO_HOME / f".update-rollback-stage-{os.getpid()}"
    try:
        os.replace(stage, aside)
    except OSError:
        shutil.rmtree(stage, ignore_errors = True)
    else:
        shutil.rmtree(aside, ignore_errors = True)


def _refuse_staged_update() -> None:
    """Fail fast for a 805-807 desktop shell asking this wheel to stage.

    The `.update-failed.json` marker is what makes their reconciler skip the same version.
    backend_version is a plain String there, so a failed lookup is spelled out rather than null;
    shell_version is an Option<String> and stays null. Nothing here touches the environment.
    """
    from importlib.metadata import version as package_version

    try:
        backend_version = package_version("unsloth")
    except Exception:
        backend_version = "unknown"
    if not isinstance(backend_version, str) or not backend_version:
        backend_version = "unknown"
    shell_version = (os.environ.get(_studio_stage.SHELL_VERSION_ENV) or "").strip() or None
    _discard_orphaned_stage()
    marker = STUDIO_HOME / ".update-failed.json"
    payload = (
        json.dumps({"backend_version": backend_version, "shell_version": shell_version}, indent = 2)
        + "\n"
    )
    try:
        marker.parent.mkdir(parents = True, exist_ok = True)
        temporary = marker.with_name(marker.name + f".{os.getpid()}.tmp")
        temporary.write_text(payload, encoding = "utf-8")
        os.replace(temporary, marker)
    except OSError:
        # A refusal the desktop can act on matters more than the marker.
        pass
    # stdout, not stderr: update.rs promotes a [TAURI:ERROR] line off the child's stdout.
    typer.echo("[TAURI:ERROR] background staging is no longer supported; run the standard update")
    raise typer.Exit(1)


class _WindowsLauncherUpdateTransaction:
    """Keep the managed Windows launcher recoverable during a Python update."""

    _VERSION_TIMEOUT_SECONDS = 10
    # Sentinel rather than a message: _launcher_health_error matches on identity, and it never reaches a user.
    _POLICY_BLOCKED = "an Application Control policy blocked the launcher"
    # Absence is not corruption: quarantine leaves a healthy environment, so keep it apart from the PE-shape failure.
    _LAUNCHER_ABSENT = "the updated launcher is not on disk"
    _RESTORE_ATTEMPTS = 3

    def __init__(self) -> None:
        self.enabled = platform.system() == "Windows"
        self.launcher: Optional[Path] = None
        self.backup: Optional[Path] = None
        self.legacy_backup: Optional[Path] = None
        self.stale: Optional[Path] = None
        self.shim: Optional[Path] = None
        self.lock_path: Optional[Path] = None
        self._lock_file = None
        self._validated = False

    @staticmethod
    def _is_valid_pe(path: Path) -> bool:
        try:
            if not path.is_file() or path.stat().st_size < 2:
                return False
            with path.open("rb") as handle:
                return handle.read(2) == b"MZ"
        except OSError:
            return False

    @staticmethod
    def _atomic_copy(source: Path, destination: Path) -> None:
        """Publish a sibling copy without exposing a partial destination."""
        fd, temporary_name = tempfile.mkstemp(
            prefix = f".{destination.name}.",
            suffix = ".tmp",
            dir = str(destination.parent),
        )
        temporary = Path(temporary_name)
        try:
            with source.open("rb") as source_handle, os.fdopen(fd, "wb") as target_handle:
                fd = -1
                while True:
                    chunk = source_handle.read(1024 * 1024)
                    if not chunk:
                        break
                    target_handle.write(chunk)
                target_handle.flush()
                os.fsync(target_handle.fileno())
            os.replace(temporary, destination)
        finally:
            if fd >= 0:
                os.close(fd)
            try:
                temporary.unlink(missing_ok = True)
            except OSError:
                pass

    def _acquire_lock(self) -> None:
        import msvcrt

        assert self.lock_path is not None
        try:
            self.lock_path.parent.mkdir(parents = True, exist_ok = True)
        except OSError:
            pass
        lock_file = self.lock_path.open("a+b")
        try:
            lock_file.seek(0, os.SEEK_END)
            if lock_file.tell() == 0:
                lock_file.write(b"\0")
                lock_file.flush()
            lock_file.seek(0)
            msvcrt.locking(lock_file.fileno(), msvcrt.LK_NBLCK, 1)
        except OSError:
            lock_file.close()
            typer.echo(
                "Error: another Unsloth Studio update is already running for this environment.",
                err = True,
            )
            raise typer.Exit(1)
        self._lock_file = lock_file

    def _release_lock(self) -> None:
        if self._lock_file is None:
            return
        try:
            import msvcrt
            self._lock_file.seek(0)
            msvcrt.locking(self._lock_file.fileno(), msvcrt.LK_UNLCK, 1)
        except OSError:
            pass
        finally:
            self._lock_file.close()
            self._lock_file = None

    def _recover_missing_launcher(self) -> None:
        assert self.launcher is not None
        # Validity, not existence: a truncated or quarantined launcher is just as unusable.
        if self._is_valid_pe(self.launcher):
            return
        last_error: Optional[Tuple[Path, OSError]] = None
        for recovery in (self.backup, self.stale, self.legacy_backup, self.shim):
            if recovery is not None and self._is_valid_pe(recovery):
                try:
                    self._atomic_copy(recovery, self.launcher)
                except OSError as exc:
                    # Try the next copy: the header check and the copy open the file separately, so one candidate lost to antivirus must not fail the install.
                    last_error = (recovery, exc)
                    continue
                return
        if last_error is not None:
            recovery, exc = last_error
            typer.echo(
                f"Error: could not recover {self.launcher} from {recovery}: {exc}",
                err = True,
            )
            typer.echo(f"Manual recovery copy retained at: {recovery}", err = True)
            raise typer.Exit(1)

    @staticmethod
    def _files_match(left: Path, right: Path) -> bool:
        try:
            if left.stat().st_size != right.stat().st_size:
                return False
            with left.open("rb") as left_handle, right.open("rb") as right_handle:
                while True:
                    left_chunk = left_handle.read(1024 * 1024)
                    if left_chunk != right_handle.read(1024 * 1024):
                        return False
                    if not left_chunk:
                        return True
        except OSError:
            return False

    def _move_launcher_aside(self) -> None:
        """Frees the canonical launcher path so the installer can publish a replacement (uv deletes
        third-party scripts and hard-errors when in use); non-fatal, it costs only the upgrade."""
        assert self.launcher is not None and self.stale is not None
        if not self._is_valid_pe(self.launcher):
            return
        try:
            os.replace(self.launcher, self.stale)
        except OSError as exc:
            # Not fatal, but say what it costs: the pip fallback drops --upgrade-package, leaving unsloth at its old version.
            typer.echo(f"Warning: could not move the Unsloth launcher aside: {exc}", err = True)
            typer.echo(
                "  unsloth itself may not be upgraded. Close anything holding "
                f"{self.launcher} and re-run the update.",
                err = True,
            )

    def _retained_backup(self) -> Optional[Path]:
        """The backup, when it exists and is usable. Nothing to point users at otherwise."""
        if self.backup is not None and self._is_valid_pe(self.backup):
            return self.backup
        return None

    def _recovery_candidates(self) -> List[Path]:
        """Stand-in copies, best first; passing the header check does not make one runnable."""
        seen: List[Path] = []
        for path in (self.backup, self.stale, self.legacy_backup, self.shim):
            if path is None or not self._is_valid_pe(path):
                continue
            if not any(os.path.normcase(str(path)) == os.path.normcase(str(p)) for p in seen):
                seen.append(path)
        return seen

    def _restore_from(self, source: Path) -> bool:
        assert self.launcher is not None
        # The common setup-failure case leaves the original in place; do not replace a running Windows file with a byte-identical source.
        if self._is_valid_pe(self.launcher) and self._files_match(self.launcher, source):
            return True
        last_error: Optional[OSError] = None
        for attempt in range(self._RESTORE_ATTEMPTS):
            try:
                self._atomic_copy(source, self.launcher)
                return self._is_valid_pe(self.launcher)
            except OSError as exc:
                last_error = exc
                if attempt + 1 < self._RESTORE_ATTEMPTS:
                    time.sleep(0.1)
        if last_error is not None:
            typer.echo(f"Error: could not restore the Unsloth launcher: {last_error}", err = True)
        return False

    def _restore_runnable(self) -> bool:
        return self._restore_failure_reason() is None

    def _restore_failure_reason(self) -> Optional[str]:
        """Restore the first runnable copy, or return why the CLI still cannot run; under
        Application Control --version dies in CreateProcess, so only shape is checked."""
        if self._launcher_health_error() is None:
            return None
        candidates = self._recovery_candidates()
        for source in candidates:
            if self._restore_from(source) and self._launcher_health_error() is None:
                return None
        # Nothing ran; leave the best candidate rather than whichever was tried last.
        if candidates:
            self._restore_from(candidates[0])
        # Gone, or denied by policy, is still not a broken CLI. Asked only after every candidate.
        return self._recovered_cli_health_error()

    def _launcher_runs_error(self) -> Optional[str]:
        """Whether THIS launcher file starts and answers --version. About the file, not the CLI: the
        only check that catches a PE-shaped but corrupt stub."""
        assert self.launcher is not None
        if not self.launcher.exists():
            return self._LAUNCHER_ABSENT
        if not self._is_valid_pe(self.launcher):
            return "the updated launcher is not a non-empty PE file"
        try:
            result = subprocess.run(
                [str(self.launcher), "--version"],
                check = False,
                capture_output = True,
                timeout = self._VERSION_TIMEOUT_SECONDS,
                **_windows_hidden_subprocess_kwargs(),
            )
        except subprocess.TimeoutExpired:
            return f"the updated launcher timed out after {self._VERSION_TIMEOUT_SECONDS} seconds"
        except OSError as exc:
            if _is_application_control_block(exc):
                return self._POLICY_BLOCKED
            return f"the updated launcher could not run --version ({exc})"
        if result.returncode != 0:
            return f"the updated launcher returned {result.returncode} for --version"
        return None

    def _launcher_health_error(self) -> Optional[str]:
        """Whether the update left a working CLI; asks the signed interpreter on an Application
        Control denial, else good installs roll back (issue 8490)."""
        error = self._launcher_runs_error()
        if error is self._POLICY_BLOCKED:
            return self._interpreter_health_error(error)
        return error

    def _recovered_cli_health_error(self) -> Optional[str]:
        """_launcher_health_error, once recovery has been ruled out: a missing launcher IS worth
        restoring, but once every candidate failed, quarantine says as little as a denial (#8490)."""
        error = self._launcher_runs_error()
        if error is self._POLICY_BLOCKED or error is self._LAUNCHER_ABSENT:
            return self._interpreter_health_error(error)
        return error

    def _interpreter_health_error(self, reason: str) -> Optional[str]:
        """Health of the managed CLI when the launcher cannot be started. Isolated alone among this
        module's managed invocations, mirroring build_update_command's Isolation::Isolated."""
        assert self.launcher is not None
        python = self.launcher.parent / "python.exe"
        if not python.is_file():
            blocked = reason is self._POLICY_BLOCKED
            state = "is blocked by an Application Control policy" if blocked else "is missing"
            return (
                f"the updated launcher {state} and there is no managed interpreter "
                f"at {python} to ask instead"
            )
        try:
            result = subprocess.run(
                _managed_cli_argv(python, "--version", isolated = True),
                check = False,
                capture_output = True,
                # The import probe's ceiling, not the launcher's: this is an interpreter start plus the whole CLI import.
                timeout = _MANAGED_CLI_IMPORT_PROBE_TIMEOUT,
                **_windows_hidden_subprocess_kwargs(),
            )
        except subprocess.TimeoutExpired:
            return (
                f"the managed Python CLI timed out after "
                f"{_MANAGED_CLI_IMPORT_PROBE_TIMEOUT} seconds"
            )
        except OSError as exc:
            return f"the managed Python CLI could not run --version ({exc})"
        if result.returncode != 0:
            return f"the managed Python CLI returned {result.returncode} for --version"
        return None

    @staticmethod
    def _managed_scripts_dir() -> Path:
        """Scripts dir of the venv setup actually updates: STUDIO_HOME/unsloth_studio, which is not
        this interpreter when a pip-installed or checkout CLI drives the update."""
        managed = STUDIO_HOME / "unsloth_studio"
        if (managed / "pyvenv.cfg").is_file():
            try:
                foreign = managed.resolve() != Path(sys.prefix).resolve()
            except OSError:
                foreign = True
            if foreign:
                return managed / "Scripts"
        return Path(sys.executable).resolve().parent

    def __enter__(self):
        if not self.enabled:
            return self
        try:
            scripts = self._managed_scripts_dir()
        except (OSError, RuntimeError) as exc:
            typer.echo(f"Error: could not resolve the managed Python environment: {exc}", err = True)
            raise typer.Exit(1)
        self.launcher = scripts / "unsloth.exe"
        self.backup = scripts / "unsloth.exe.update-backup"
        self.legacy_backup = scripts / "unsloth.exe.deleteme"
        # Under the Unsloth home, not the venv: setup.ps1 removes the whole $VenvDir, which Windows refuses while a handle inside is open.
        self.lock_path = STUDIO_HOME / "unsloth.exe.update-lock"
        # install.ps1 hardlinks this to the launcher, so it survives the old updater and is a valid recovery source.
        self.shim = STUDIO_HOME / "bin" / "unsloth.exe"
        self.stale = scripts / "unsloth.exe.update-stale"
        self._acquire_lock()
        try:
            self._recover_missing_launcher()
            if not self._is_valid_pe(self.launcher):
                # Warn, do not exit: the previous updater could leave no launcher and no .deleteme, and refusing would strand those users.
                typer.echo(
                    f"Warning: the managed Unsloth launcher is missing or invalid: {self.launcher}",
                    err = True,
                )
                typer.echo("Continuing; setup may reinstall it.", err = True)
                if self._retained_backup() is None:
                    self.backup = None
            elif self._retained_backup() is None:
                # Only when there is no usable backup: a surviving one holds the last launcher known to run.
                try:
                    self._atomic_copy(self.launcher, self.backup)
                except OSError as exc:
                    # A backup is a safety net, not a precondition.
                    typer.echo(f"Warning: could not back up the Unsloth launcher: {exc}", err = True)
                    self.backup = None
            self._move_launcher_aside()
        except BaseException:
            self._release_lock()
            raise
        return self

    def validate_launcher(self) -> None:
        if not self.enabled:
            return
        # Sampled before any restore, since whether setup published anything decides how a bad result reads.
        published = self.launcher.exists()
        error = self._launcher_health_error()
        if error is not None:
            reason = self._restore_failure_reason()
            restored = reason is None
            # Setup publishing nothing is the case this exists for, so restoring is success; a launcher setup DID write that cannot run is a failure.
            if published or not restored:
                # Absence names no cause (#9804); any other error is the published launcher's own and must win over the restored copy's.
                cause = reason if error is self._LAUNCHER_ABSENT else None
                typer.echo(
                    f"Error: Unsloth Studio update failed because {cause or error}.",
                    err = True,
                )
                if restored:
                    typer.echo("The previous launcher was restored.", err = True)
                elif self._retained_backup() is not None:
                    typer.echo(f"Manual recovery copy retained at: {self.backup}", err = True)
                raise typer.Exit(1)
        self._validated = True
        # Only once the launcher is back: a quarantined stub can be judged healthy while every restore failed, and the copies are the only recovery material.
        if not self._is_valid_pe(self.launcher):
            return
        for orphan in (self.stale, self.backup, self.legacy_backup):
            if orphan is None:
                continue
            try:
                orphan.unlink(missing_ok = True)
            except OSError:
                pass

    def __exit__(self, exc_type, exc_value, traceback) -> bool:
        try:
            if self.enabled and exc_type is not None and not self._validated:
                if not self._restore_runnable() and self._retained_backup() is not None:
                    typer.echo(f"Manual recovery copy retained at: {self.backup}", err = True)
        finally:
            self._release_lock()
        return False


def _managed_llama_runtime_is_the_active_one() -> bool:
    """Whether preflight has a managed tree to grade at all.

    Kept as the yes/no question the name asks; ``_llama_runtime_to_grade`` answers
    which tree, and the two cannot disagree.
    """
    return _llama_runtime_to_grade() is not None


def _llama_runtime_to_grade() -> Optional[Path]:
    """The llama.cpp tree preflight should grade, or None when the runtime the
    backend would load is one the user chose and this PR does not grade.

    ``_find_llama_server_binary`` prefers ``LLAMA_SERVER_PATH``, then
    ``UNSLOTH_LLAMA_CPP_PATH``, then Studio's settings folder, and only then the
    managed install. Grading the managed tree regardless would send a user who
    runs their own build into repair over a leftover install their backend never
    opens, and offline that repair cannot even succeed.

    ``UNSLOTH_LLAMA_CPP_PATH`` needs no skip: it moves the managed root itself, so
    ``default_managed_llama_dir`` already grades the tree it names.
    """
    pinned = os.environ.get("LLAMA_SERVER_PATH", "").strip()
    # Use the finder's own _file_status: an absent pin (including a dangling symlink) falls through to the
    # managed tree, which must then be graded.
    if pinned:
        try:
            stops_the_finder = Path(pinned).is_file()
        except PermissionError:
            # is_file raises for a locked file on Windows; _file_status calls it "denied", halting the finder.
            stops_the_finder = True
        except OSError:
            stops_the_finder = False
        if stops_the_finder:
            return None
    # Put studio/backend first on sys.path: else llama_cpp_path_settings swallows a failed storage.studio_db import and selection reads absent.
    backend_dir = _PACKAGE_ROOT / "studio" / "backend"
    if backend_dir.is_dir() and str(backend_dir) not in sys.path:
        sys.path.insert(0, str(backend_dir))
    try:
        from studio.backend.utils.llama_cpp_path_settings import (
            expanded_user_path,
            get_stored_custom_llama_cpp_path,
            llama_server_candidates,
        )
        from studio.install_llama_prebuilt import default_managed_llama_dir
    except Exception:
        # Without a settings module there is no stored selection and no way to check for a server, so use the managed root.
        from studio.install_llama_prebuilt import default_managed_llama_dir
        return default_managed_llama_dir()
    # UNSLOTH_LLAMA_CPP_PATH outranks the stored folder, unless the desktop set it (managed marker).
    override = (os.environ.get("UNSLOTH_LLAMA_CPP_PATH") or "").strip()
    # Classify the override rather than trust the marker: a custom STUDIO_HOME export equals the managed tree yet sets no marker.
    managed_override = os.environ.get("UNSLOTH_STUDIO_MANAGED_LLAMA_CPP_PATH") == "1"
    if override and not managed_override:
        # Compare against STUDIO_ROOT/llama.cpp, never default_managed_llama_dir(), which reads the override first and would call every pin managed.
        managed_override = _same_runtime_tree(
            expanded_user_path(override), _managed_llama_dir_ignoring_the_override()
        )
    if override and not managed_override:
        # Only a folder holding a server stops discovery. Not graded: setup.sh / setup.ps1 never read
        # UNSLOTH_LLAMA_CPP_PATH, so a repair would loop. expanded_user_path: expanduser can raise.
        if _layout_stops_discovery(llama_server_candidates(expanded_user_path(override))):
            return None
    if get_stored_custom_llama_cpp_path() is not None:
        return None
    if managed_override:
        # The finder skips an override naming the managed tree, which is still ours.
        return default_managed_llama_dir()
    # Read with the override out of the way, or it names the folder just ruled out.
    return _managed_llama_dir_ignoring_the_override()


def _same_runtime_tree(left: Path, right: Path) -> bool:
    """Whether two runtime paths name one tree, the way the backend compares them.

    ``mark_managed_llama_cpp_path`` resolves both sides non-strictly and swallows
    the same errors, so a path that has not been created yet still compares, and
    an unreadable one answers "different" rather than raising out of the doctor.
    """
    try:
        return left.resolve(strict = False) == right.resolve(strict = False)
    except (OSError, RuntimeError, ValueError):
        return False


def _layout_stops_discovery(candidates) -> bool:
    """Whether a pinned folder ends ``_find_llama_server_binary``'s search.

    Presence, not usability: ``_scan_pinned`` returns a hit for an executable
    candidate, and for one that is merely present it returns the path as
    ``non_executable`` or ``denied``, which the caller turns into ``_unavailable``
    and a refusal to fall back. Only a layout holding no server at all is walked
    past. Asking for the execute bit here would send preflight off to grade a
    different tree in exactly the case where the pinned one needs repair.
    """
    for candidate in candidates:
        try:
            if candidate.is_file():
                return True
        except PermissionError:
            return True
        except OSError:
            continue
    return False


def _managed_llama_dir_ignoring_the_override() -> Path:
    """default_managed_llama_dir with UNSLOTH_LLAMA_CPP_PATH out of the way, and the
    inferred studio home put back.

    The desktop scrubs UNSLOTH_STUDIO_HOME and STUDIO_HOME before it spawns this
    (MANAGED_CHILD_SCRUBBED_ENV), so default_managed_llama_dir reads an empty
    environment and answers the legacy ~/.unsloth/llama.cpp. _resolve_studio_home has
    already recovered the real root off sys.prefix by then, and preflight::managed's
    inferred_studio_llama_root fingerprints <root>/llama.cpp on the strength of the
    same inference, so reading only the environment here graded the legacy tree while
    the cache watched the custom one: quarantine in the runtime actually in use
    reported Ready and failed at model load.

    Exported rather than computed, because _ensure_studio_env_exported writes exactly
    this value and there should be one rule for it, not two that can drift.
    """
    from studio.install_llama_prebuilt import default_managed_llama_dir

    # Master root first: runtimes sit beside studio/, which default_managed_llama_dir does not see.
    master_dir = _master_root_llama_dir()
    if master_dir is not None:
        return master_dir

    saved = os.environ.pop("UNSLOTH_LLAMA_CPP_PATH", None)
    had_home = "UNSLOTH_STUDIO_HOME" in os.environ
    saved_home = os.environ.get("UNSLOTH_STUDIO_HOME")
    # Truthy-check: a blank UNSLOTH_STUDIO_HOME= is not a root either.
    if _STUDIO_HOME_IS_CUSTOM and not (saved_home or "").strip():
        os.environ["UNSLOTH_STUDIO_HOME"] = str(STUDIO_HOME)
    try:
        return default_managed_llama_dir()
    finally:
        if saved is not None:
            os.environ["UNSLOTH_LLAMA_CPP_PATH"] = saved
        if had_home:
            os.environ["UNSLOTH_STUDIO_HOME"] = saved_home
        else:
            os.environ.pop("UNSLOTH_STUDIO_HOME", None)


@studio_app.command("desktop-capabilities", hidden = True)
def desktop_capabilities(
    json_output: bool = typer.Option(
        False,
        "--json",
        help = "Emit machine-readable JSON.",
    ),
):
    state = _install_state()
    payload = {
        "desktop_protocol_version": 1,
        # 2 adds studio_install_ok; the desktop treats < 2 as stale.
        "desktop_manageability_version": 2,
        "supports_provision_desktop_auth": True,
        "supports_api_only": True,
        "supports_desktop_backend_ownership": True,
        # Did the install finish and are the backend boot deps still there.
        "studio_install_ok": bool(state["ok"]),
        "studio_install_reason": state["reason"],
        # Null when nothing is installed yet. Older desktops ignore both keys.
        "llama_runtime_ok": None,
        "llama_runtime_reason": "",
        "version": "unknown",
    }
    # A probe that cannot answer must not turn a working install stale.
    try:
        from studio.install_llama_prebuilt import installed_runtime_health
        runtime_root = _llama_runtime_to_grade()
        if runtime_root is not None:
            health = installed_runtime_health(runtime_root)
            if health is not None:
                payload["llama_runtime_ok"], payload["llama_runtime_reason"] = health
        else:
            # A null that must not be cached: it depends on a selection the desktop does not watch
            # (managed.rs keys off this reason).
            payload["llama_runtime_reason"] = "llama_runtime_not_managed"
    except Exception:
        # Never cache a failed attempt: it shares the damaged tree's fingerprint.
        payload["llama_runtime_ok"] = None
        payload["llama_runtime_reason"] = "llama_runtime_probe_failed"
    try:
        from importlib.metadata import version as package_version
        payload["version"] = package_version("unsloth")
    except Exception:
        pass

    if json_output:
        typer.echo(json.dumps(payload, sort_keys = True))
        return

    for key, value in payload.items():
        typer.echo(f"{key}: {value}")


@studio_app.command("verify-install")
def verify_install(
    json_output: bool = typer.Option(
        False,
        "--json",
        help = "Emit machine-readable JSON.",
    ),
):
    """Check that the Unsloth Studio dependency install completed.

    Exits 0 when complete, 1 otherwise. setup.sh / setup.ps1 use the exit code
    to decide whether the "already up to date" fast path may be taken.

    Scans the installed files too, unlike `desktop-capabilities`: nothing times
    this one out.
    """
    state = _install_state(deep = True)

    if json_output:
        typer.echo(json.dumps(state, sort_keys = True))
        raise typer.Exit(0 if state["ok"] else 1)

    if state["ok"]:
        typer.echo("Unsloth Studio install is complete.")
        raise typer.Exit(0)

    typer.echo(f"Unsloth Studio install is incomplete ({state['reason']}).")
    if state["missing"]:
        typer.echo(f"  missing packages: {', '.join(state['missing'])}")
    typer.echo("  repair with: unsloth studio update")
    raise typer.Exit(1)


@studio_app.command("provision-desktop-auth", hidden = True)
def provision_desktop_auth():
    """Create/repair desktop auth state for the local machine."""
    auth_dir = STUDIO_HOME / "auth"
    secret = _create_desktop_secret_in_cli()
    _write_auth_secret(auth_dir / DESKTOP_SECRET_FILE, secret)
    typer.echo("Desktop auth ready.")


def _owner_login_alias(conn: sqlite3.Connection) -> Optional[str]:
    if "login_alias" not in {row[1] for row in conn.execute("PRAGMA table_info(auth_user)")}:
        return None
    row = conn.execute(
        "SELECT login_alias FROM auth_user WHERE username = ?", (DEFAULT_ADMIN_USERNAME,)
    ).fetchone()
    return row[0] if row else None


def _reset_password_username(conn: sqlite3.Connection, username: Optional[str]) -> str:
    columns = {row[1] for row in conn.execute("PRAGMA table_info(auth_user)")}
    active_filter = " WHERE is_active = 1" if "is_active" in columns else ""
    count = conn.execute("SELECT COUNT(*) FROM auth_user" + active_filter).fetchone()[0]
    if username is None and count > 1:
        typer.echo("Error: --username is required when multiple accounts are active.", err = True)
        raise typer.Exit(1)
    target = DEFAULT_ADMIN_USERNAME if username is None else username.casefold()
    if target == DEFAULT_ADMIN_USERNAME:
        _ensure_cli_default_admin(conn)
    elif conn.execute("SELECT 1 FROM auth_user WHERE username = ?", (target,)).fetchone() is None:
        if _owner_login_alias(conn) != target:
            typer.echo("Error: account not found.", err = True)
            raise typer.Exit(1)
        target = DEFAULT_ADMIN_USERNAME
    return target


@studio_app.command("reset-password")
def reset_password(
    username: Optional[str] = typer.Option(
        None, "--username", help = "Account to reset; required with multiple active accounts."
    ),
):
    """Reset an Unsloth account password. Rotates in place, so nothing needs restarting. Shared /p
    preview links are not revoked; rotate those in Settings if the old password leaked."""
    new_password = _generate_reset_password()
    try:
        conn = _connect_auth_db()
    except (OSError, sqlite3.Error) as exc:
        typer.echo(
            f"Error: could not open the auth database ({exc}). Check that "
            f"{STUDIO_HOME / 'auth'} is writable; if auth.db itself is unreadable, stop "
            "Unsloth, delete it, and start again to re-seed.",
            err = True,
        )
        raise typer.Exit(1)

    try:
        conn.execute("BEGIN IMMEDIATE")
        target = _reset_password_username(conn, username)
        alias = _owner_login_alias(conn) if target == DEFAULT_ADMIN_USERNAME else None
        _cli_update_password(conn, target, new_password, revoke_api_keys = True)
    except (OSError, sqlite3.Error) as exc:
        typer.echo(f"Error: could not reset the password ({exc}).", err = True)
        raise typer.Exit(1)
    finally:
        conn.close()

    signs_in_as = f" (also signs in as '{alias}')" if alias else ""
    typer.echo(f"New password for '{target}'{signs_in_as}: {new_password}")
    typer.echo(
        "Sessions and API keys revoked. A running Unsloth takes it on the next request, "
        "though repeated failed logins can hold the rate limit shut for up to a minute."
    )