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.

386 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

"""`unsloth start` — launch a coding agent against a running Unsloth server."""

import atexit
import base64
import contextlib
import errno
import functools
import hashlib
import http.client
import json
import math
import os
import re
import shlex
import shutil
import signal
import subprocess
import sys
import tempfile
import threading
import time
import urllib.error
import urllib.request
from pathlib import Path
from typing import Literal, NamedTuple, NoReturn, Optional
from urllib.parse import quote, urlencode, urlparse

import click
import typer
from typer.core import TyperCommand

from studio.backend.utils.coding_agents import (
    deepseek_harness_executables_on_path,
    is_deepseek_harness_executable,
)
from unsloth_cli._inference import (
    _USER_AGENT,
    _studio_token,
    ensure_studio_backend_path,
    find_studio_server,
    is_loopback_url,
    raise_for_deferred_error,
    require_completed_padded_body,
    urlopen_local,
    urlopen_no_redirect,
    verify_studio_identity,
)

start_app = typer.Typer(
    help = "Start a coding agent against a running Unsloth server.",
    no_args_is_help = True,
    context_settings = {"help_option_names": ["-h", "--help"]},
)

_CODEX_PROFILE = "unsloth_api"
_CODEX_ENV_KEY = "UNSLOTH_STUDIO_AUTH_TOKEN"
# Codex treats an SSE stream with no bytes for this long as lost, cancels it and reconnects. Its default is 300000 (5 minutes), measured against the WHOLE quiet period, and llama-server sends nothing at all while it processes the prompt. A local CPU host chews through a prompt at low tens of tokens a second and Codex's own preamble is several thousand tokens before the user has typed anything: 16.1 tok/s measured on a 2-core box means ~460s of silence for a ~7300-token first turn, so the default trips before the first token exists. The reconnect is worse than the wait, because llama-server hands the retry a different parallel slot whose KV cache shares no prefix, so each attempt restarts prompt processing from zero and the five retries can never converge. Observed as a request completing in exactly 300056ms with `Reconnecting... 1/5` and no turn ever finishing. 20 minutes here, sized to be longer than a slow local first turn rather than to any server-side budget: nothing here bounds generation, and a genuinely dead stream is still caught, just later.
_CODEX_STREAM_IDLE_TIMEOUT_MS = 1_200_000
_HERMES_ENV_KEY = "UNSLOTH_API_KEY"
# Not "unsloth": Hermes strips a `<provider>/` prefix, so unsloth/<repo> stops matching model.default.
_HERMES_PROVIDER = "unsloth-studio"
_HERMES_LEGACY_PROVIDER = "unsloth"
_HERMES_MCP_MANIFEST = "unsloth_mcp_servers.json"
# Skip the installer's interactive setup wizard: `unsloth start hermes` runs this hint unattended and then writes its own session-scoped Hermes config, so the wizard's global API-key/model prompts would block the launch and point the user at a different provider than the one Unsloth just configured. Both installers expose a skip flag: `-SkipSetup` (PowerShell) and `--skip-setup` (POSIX, passed to the piped script via `bash -s --`). Pin both the fetched script and the repository checkout it performs to the same full commit so a later change to either upstream branch cannot silently replace code that Unsloth executes with the user's privileges.
_HERMES_INSTALL_COMMIT = "f1af945f6c576eccb126fa955edc9be258b33020"
_HERMES_INSTALL_BASE = (
    "https://raw.githubusercontent.com/NousResearch/hermes-agent/"
    f"{_HERMES_INSTALL_COMMIT}/scripts"
)
_HERMES_WINDOWS_INSTALL_HINT = (
    f"& ([scriptblock]::Create((irm {_HERMES_INSTALL_BASE}/install.ps1)))"
    f" -SkipSetup -Commit {_HERMES_INSTALL_COMMIT}"
)
_HERMES_POSIX_INSTALL_HINT = (
    f"curl -fsSL {_HERMES_INSTALL_BASE}/install.sh | bash -s --"
    f" --skip-setup --commit {_HERMES_INSTALL_COMMIT}"
)
# Hermes refuses to initialize when the model window is under 64,000 tokens; its error message points at the model.context_length / auxiliary.compression overrides in config.yaml. write_hermes_config claims this value for smaller windows and scales the compaction threshold back down to the real window.
_HERMES_MIN_CONTEXT = 65536
_DSH_PROVIDER = "unsloth"
_DSH_ENV_KEY = "UNSLOTH_API_KEY"
_DSH_PATCH_FILE = "unsloth.patch.yml"
_DSH_PACKAGE = "@deepseek-ai/dsh@latest"
# dsh picks its sandbox+approval preset from DSH_PERMISSION_MODE via ??, so omitting it would inherit a danger-full-access exported in the parent shell, and "" is not unset to ??. Pin the mode in both directions instead of only setting it for --yolo.
_DSH_SAFE_PERMISSION_MODE = "workspace-write"
_DSH_YOLO_PERMISSION_MODE = "danger-full-access"
# dsh's pi-ai provider sends max_tokens = contextWindow - its prompt estimate - 4,096 (pi-ai CONTEXT_SAFETY_TOKENS), floored at 1, and dsh's own instructions and tools are about 6,500 tokens: at 8,192 every reply is cut after one token (#14315).
_DSH_MIN_CONTEXT = 16384
# First request of a stock install (system prompt + tool schemas) before any user text, measured on Claude Code 2.1 and OpenCode 1.19 / 2.1. MCP servers and project instructions add to it.
_CLAUDE_PROMPT_TOKENS = 16_000
_OPENCODE_PROMPT_TOKENS = 7_500
_OPENCODE_V2_PROMPT_TOKENS = 5_500
_PI_PROVIDER = "unsloth"
_SUBAGENT_NAME = "unsloth"
_SUBAGENT_DESCRIPTION = (
    "Local coding subagent powered by Unsloth for debugging, implementation, and codebase "
    "research. Use when the user asks to spawn an Unsloth or local agent."
)
_AUTO_ROUTE_DESCRIPTION = (
    "Local coding subagent powered by Unsloth. In this session it is the only way to reach "
    "files and the shell: {blocked}. "
    "Give it the complete task in one message (codebase search, reading or summarizing files, "
    "running tests or commands, mechanical edits with a clear spec) and review its result "
    "before answering. Keep talking with the user and planning and design decisions to "
    "yourself."
)
_SUBAGENT_AUTO_ROUTE_DESCRIPTION = _AUTO_ROUTE_DESCRIPTION.format(
    blocked = (
        "your own Read, Grep, Glob, Bash, PowerShell, Monitor, NotebookRead and Agent calls "
        "are blocked"
    )
)
# Without tools of its own the parent cannot check a small model's answer except by asking for the evidence.
_AUTO_ROUTE_VERIFY = (
    " It is a small local model and can be wrong: ask it for the raw command output behind an "
    "answer you rely on, such as a search that found nothing or an edit, and say so if you "
    "cannot confirm it."
)
_AUTO_ROUTE_CHECK = (
    _AUTO_ROUTE_VERIFY + " If it fails, tell the user plainly; you cannot do the step yourself."
)
_OPENCODE_AUTO_ROUTE_DESCRIPTION = (
    _AUTO_ROUTE_DESCRIPTION.format(
        blocked = "your own read, grep, glob, list, lsp, bash and edit tools are blocked"
    )
    + _AUTO_ROUTE_VERIFY
    + " If it fails, do that step with your own read and bash if they work, or else tell the "
    "user plainly that it was not done."
)
_OPENCODE_PLAN_SUBAGENT_NAME = "unsloth-plan"
_OPENCODE_AUTO_ROUTE_PLAN_DESCRIPTION = (
    "Read-only local coding subagent powered by Unsloth for planning and codebase research. "
    "In plan mode it is the only way to read files: your own read, grep, glob, list, lsp and "
    "bash tools are blocked. Give it the complete question in one message."
)
_OPENCODE_HIDDEN_TOOLS = ("grep", "glob", "list", "lsp")
# OpenCode's free tier refuses a request without read or bash, so on V1 the route plugin blocks their calls instead of a permission rule removing them.
_OPENCODE_ROUTED_TOOLS = ("read", "bash")
_OPENCODE_ROUTE_PLUGIN = "unsloth-auto-route.js"
_SUBAGENT_AUTO_ROUTE_INSTRUCTIONS = (
    "Files and the shell in this session are reachable only through the unsloth_agent tool; "
    "your own Read, Grep, Glob, Bash, PowerShell, Monitor, NotebookRead and Agent calls are "
    "blocked by a hook. Give the "
    "tool the complete task in one message, with the paths and commands it needs, and review "
    "its result before answering. Keep talking with the user and planning and design "
    "decisions to yourself. In plan mode call unsloth_plan_agent instead."
)
_SUBAGENT_INSTRUCTIONS = (
    "You are a local coding subagent powered by Unsloth. Complete the assigned task directly, "
    "use the available tools when useful, verify your work, and return a concise result to the "
    "parent agent."
)
_SUBAGENT_PLAN_DESCRIPTION = (
    "Read-only local coding subagent powered by Unsloth for planning and codebase research. "
    "Use this local agent when Claude is in plan mode."
)
_SUBAGENT_PLAN_INSTRUCTIONS = (
    "You are a read-only local coding subagent powered by Unsloth. Investigate the assigned "
    "task with read-only tools, produce a concrete plan or answer, and return a concise result "
    "to the parent agent. Do not modify files."
)
_CLAUDE_SUBAGENT_MCP_MODULE = "unsloth_cli.claude_subagent_mcp"
_CLAUDE_SUBAGENT_SETTINGS_ENV = "UNSLOTH_CLAUDE_SUBAGENT_SETTINGS"
_CLAUDE_SUBAGENT_AUTO_ROUTE_ENV = "UNSLOTH_CLAUDE_SUBAGENT_AUTO_ROUTE"
_CLAUDE_SUBAGENT_FALLBACK_ENV = "UNSLOTH_CLAUDE_SUBAGENT_FALLBACK"
_CLAUDE_ROUTE_FALLBACK_FILE = "local-agent-failed"
_CLAUDE_SUBAGENT_TOOL = "mcp__plugin_unsloth-local-agent_unsloth__unsloth_agent"
_CLAUDE_SUBAGENT_PLAN_TOOL = "mcp__plugin_unsloth-local-agent_unsloth__unsloth_plan_agent"
_CODEX_SUBAGENT_MCP_MODULE = "unsloth_cli.codex_subagent_mcp"
_CODEX_SUBAGENT_MCP_SERVER = "unsloth_local_agent"
_CODEX_SUBAGENT_MCP_TOOL = "spawn_local_agent"
_CODEX_SUBAGENT_CONFIG_ENV = "UNSLOTH_CODEX_SUBAGENT_CONFIG"
_CODEX_PARENT_OVERLAY_MANIFEST = ".unsloth-parent-overlay.json"
_CODEX_USER_FILES = ("AGENTS.md", "AGENTS.override.md", "skills", "rules", "prompts")
_CODEX_USER_FILES_MANIFEST = "unsloth_user_files.json"
_CODEX_COPIED_DIRS = {"agents", "skills", "rules", "prompts", "plugins", "marketplaces", "sessions"}
_CODEX_EPHEMERAL_STALE_SECONDS = 24 * 60 * 60
_CODEX_EPHEMERAL_HEARTBEAT_SECONDS = 60
_CODEX_SUBAGENT_TOOL_DESCRIPTION = (
    f"{_SUBAGENT_DESCRIPTION} Use this tool instead of the built-in spawn_agent tool for those "
    "requests. Other subagent requests may use the built-in tools normally."
)
_CODEX_SUBAGENT_ROUTING_INSTRUCTIONS = (
    "When the user asks to spawn an Unsloth agent or local agent, you must call the "
    "spawn_local_agent MCP tool once with the complete task. Do not answer, simulate the "
    "result, call wait, or use a built-in subagent before calling the tool. Use built-in "
    "subagents for other delegation requests."
)
_CODEX_AUTO_ROUTE_TOOL_DESCRIPTION = (
    _AUTO_ROUTE_DESCRIPTION.format(blocked = "your own shell is disabled") + _AUTO_ROUTE_CHECK
)
_CODEX_AUTO_ROUTE_INSTRUCTIONS = (
    "Your own shell is disabled in this session, so files and commands are reachable only "
    "through the spawn_local_agent MCP tool. Call it without being asked for codebase search, "
    "reading or summarizing files, running tests or commands, and mechanical edits, with the "
    "complete task in one message, and review its result before answering. Keep talking with "
    "the user and planning and design decisions to yourself." + _AUTO_ROUTE_CHECK
)
_CODEX_AUTO_ROUTE_FLAGS = [
    arg
    for feature in ("shell_tool", "multi_agent", "view_image")
    for arg in ("-c", f"features.{feature}=false")
]
_PI_SUBAGENT_EXTENSION = Path(__file__).parent.parent / "pi_subagent.ts"
_PI_USER_RESOURCE_DIRS = ("extensions", "skills", "prompts", "themes", "npm", "git")
_PI_USER_RESOURCE_SETTINGS = ("packages", "extensions", "skills", "prompts", "themes")
_PI_USER_VERBATIM_SETTINGS = ("npmCommand",)
_PI_USER_RESOURCES_MANIFEST = ".unsloth-user-resources.json"
# OpenCode selects a model by "<providerID>/<modelID>". Use a dedicated id to avoid colliding with a user's providers; provider filters are set in the launch-time overlay.
_OPENCODE_PROVIDER = "unsloth-studio"
# OpenCode sends min(limit.output, this) as max_tokens unless the env var below raises it.
_OPENCODE_OUTPUT_TOKEN_MAX = 32_000
_CLAUDE_COMPACT_OUTPUT_RESERVE = 20_000
# Claude Code 2.1.307-2.1.309 compact one token past window - min(max output, 20k) - 3k, in the TUI and -p alike.
_CLAUDE_COMPACT_BUFFER = 3_000
# claude 2.1 ignores a smaller CLAUDE_CODE_AUTO_COMPACT_WINDOW and warns about it on every launch.
_CLAUDE_MIN_AUTO_COMPACT_WINDOW = 100_000
_OPENCODE_OUTPUT_TOKEN_MAX_ENV = "OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX"
_VIBE_PROVIDER = "unsloth-studio"
_VIBE_MODEL_ALIAS = "unsloth"
_VIBE_ENV_KEY = "UNSLOTH_API_KEY"
# Both installers put binaries in ~/.local/bin; Vibe's exits 1 and uv's leaves the shell PATH stale when it is missing.
_VIBE_POSIX_INSTALL_HINT = (
    'curl -LsSf https://mistral.ai/vibe/install.sh | PATH="$HOME/.local/bin:$PATH" bash'
)
_VIBE_WINDOWS_INSTALL_HINT = (
    "irm https://astral.sh/uv/install.ps1 | iex; "
    '$env:Path = "$HOME\\.local\\bin;$env:Path"; uv tool install mistral-vibe'
)
_PROVIDER_HEADER = f"[model_providers.{_CODEX_PROFILE}]"
_PASSTHROUGH = {"allow_extra_args": True, "ignore_unknown_options": True}


class _PassthroughCommand(TyperCommand):
    """Preserve the option separator when forwarding arguments to an agent."""

    def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
        raw_args = list(args)
        try:
            separator = raw_args.index("--")
        except ValueError:
            return super().parse_args(ctx, args)
        trailing_count = len(raw_args) - separator - 1
        remaining = super().parse_args(ctx, args)
        insert_at = max(0, len(remaining) - trailing_count)
        if insert_at >= len(remaining) or remaining[insert_at] != "--":
            remaining.insert(insert_at, "--")
            ctx.args = remaining
        return remaining


# provider routing overrides ANTHROPIC_BASE_URL and would bypass the local server (#9864).
_CLAUDE_ENV_UNSET = (
    "ANTHROPIC_API_KEY",
    "CLAUDE_CODE_OAUTH_TOKEN",
    "ANTHROPIC_UNIX_SOCKET",
    "CLAUDE_CODE_USE_FOUNDRY",
    "ANTHROPIC_FOUNDRY_BASE_URL",
    "ANTHROPIC_FOUNDRY_RESOURCE",
    "CLAUDE_CODE_USE_BEDROCK",
    "CLAUDE_CODE_USE_VERTEX",
    "CLAUDE_CODE_USE_ANTHROPIC_AWS",
    "CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD",
    "CLAUDE_CODE_USE_MANTLE",
)
_CODEX_ENV_UNSET = ("OPENAI_API_KEY", "CODEX_API_KEY", "CODEX_ACCESS_TOKEN")
# Unset all three: OpenClaw tries CODEX_API_KEY before OPENAI_API_KEY, and CODEX_ACCESS_TOKEN reaches its exec tool and the codex CLI.
_OPENCLAW_ENV_UNSET = ("OPENAI_API_KEY", "CODEX_API_KEY", "CODEX_ACCESS_TOKEN")
_OPENCLAW_PROFILE_RE = re.compile(r"[a-z0-9][a-z0-9_-]{0,63}", re.IGNORECASE)

# Shared by every agent command; only the config/env/command differ. Help is grouped into rich panels so `--help` reads as Model / Server / Session instead of one long unaligned list.
_PANEL_MODEL = "Model"
_PANEL_SERVER = "Server"
_PANEL_SAMPLING = "Sampling"
_PANEL_SESSION = "Agent session"

_MODEL_OPTION = typer.Option(
    None,
    "--model",
    "-m",
    rich_help_panel = _PANEL_MODEL,
    help = "Model for the agent, or a bare `org/name(:variant)` positional. "
    "Defaults to the one loaded in Unsloth.",
)
_GGUF_VARIANT_OPTION = typer.Option(
    None,
    "--gguf-variant",
    rich_help_panel = _PANEL_MODEL,
    help = "GGUF quant variant to load (e.g. UD-Q4_K_XL). Defaults to UD-Q4_K_XL for "
    "unsloth/* GGUF repos, else Q4_K_M.",
)
_CONTEXT_OPTION = typer.Option(
    0,
    "--max-seq-length",
    "--context-length",
    rich_help_panel = _PANEL_MODEL,
    help = "Context length in tokens for the load (0 = model default).",
)
_LOAD_4BIT_OPTION = typer.Option(
    True,
    "--load-in-4bit/--no-load-in-4bit",
    rich_help_panel = _PANEL_MODEL,
    help = "Load hub models in 4-bit (ignored for GGUF).",
)
_TENSOR_PARALLEL_OPTION = typer.Option(
    False,
    "--tensor-parallel/--no-tensor-parallel",
    rich_help_panel = _PANEL_MODEL,
    help = "Split a GGUF across GPUs by tensor instead of by layer (multi-GPU only).",
)
_GPU_MEMORY_MODE_OPTION = typer.Option(
    None,
    "--gpu-memory-mode",
    rich_help_panel = _PANEL_MODEL,
    help = (
        "GPU memory strategy for GGUF models loaded by this command. Auto lets "
        "Unsloth manage placement. Manual with default layers and context delegates "
        "placement and sizing to llama.cpp --fit. Omit when attaching to preserve "
        "the running model's mode."
    ),
)

# Server knobs. Tool flags only configure a server `unsloth start` auto-starts (--serve); reasoning rides in the agent's own config where it can.
_SERVE_OPTION = typer.Option(
    True,
    "--serve/--no-serve",
    rich_help_panel = _PANEL_SERVER,
    help = "If no Unsloth server is running, auto-start one for --model and keep it "
    "available after the agent exits. --no-serve errors out instead.",
)
_ENABLE_TOOLS_OPTION = typer.Option(
    None,
    "--enable-tools/--disable-tools",
    rich_help_panel = _PANEL_SERVER,
    help = "Server-side tools (web search, code execution) for the auto-started server. "
    "Default off so the agent's own tools are relayed unchanged.",
)
_TOOL_CALL_HEALING_OPTION = typer.Option(
    None,
    "--enable-tool-call-healing/--disable-tool-call-healing",
    rich_help_panel = _PANEL_SERVER,
    help = "Promote text-form tool calls from small GGUFs back into structured calls. On by "
    "default; when the flag is omitted an inherited UNSLOTH_DISABLE_TOOL_CALL_HEALING is kept.",
)
_TOOL_CALL_NUDGING_OPTION = typer.Option(
    None,
    "--enable-tool-call-nudging/--disable-tool-call-nudging",
    rich_help_panel = _PANEL_SERVER,
    help = "Retry once with a nudge when a non-streaming passthrough tool call can't be healed. "
    "On by default; when the flag is omitted an inherited UNSLOTH_TOOL_CALL_NUDGE is kept.",
)
_REASONING_OPTION = typer.Option(
    None,
    "--reasoning",
    rich_help_panel = _PANEL_SERVER,
    help = (
        "Reasoning mode for this agent session. Defaults to auto so the model's chat "
        "template decides; use 'on' or 'off' to override it."
    ),
)
_REASONING_EFFORT_OPTION = typer.Option(
    None,
    "--reasoning-effort",
    rich_help_panel = _PANEL_SERVER,
    help = (
        "Reasoning effort for this agent session, e.g. 'medium'. The "
        "levels are the model's own, so pass one its chat template accepts. Default: "
        "unset, which keeps the template's level."
    ),
)
# Sampling overrides ride in the agent's own config, so only this session uses them; one the agent cannot send pins the auto-started server instead. Default unset means the model's recommended sampling is used.
_TEMPERATURE_OPTION = typer.Option(
    None,
    "--temperature",
    min = 0.0,
    max = 2.0,
    rich_help_panel = _PANEL_SAMPLING,
    help = "Pin the sampling temperature. Default: unset (per-model recommendation).",
)
_TOP_P_OPTION = typer.Option(
    None,
    "--top-p",
    min = 0.0,
    max = 1.0,
    rich_help_panel = _PANEL_SAMPLING,
    help = "Pin top-p (nucleus) sampling. Default: unset (per-model recommendation).",
)
_TOP_K_OPTION = typer.Option(
    None,
    "--top-k",
    min = -1,
    max = 100,
    rich_help_panel = _PANEL_SAMPLING,
    help = "Pin top-k sampling. Default: unset (per-model recommendation).",
)
_MIN_P_OPTION = typer.Option(
    None,
    "--min-p",
    min = 0.0,
    max = 1.0,
    rich_help_panel = _PANEL_SAMPLING,
    help = "Pin min-p sampling threshold. Default: unset (per-model recommendation).",
)
_REPETITION_PENALTY_OPTION = typer.Option(
    None,
    "--repetition-penalty",
    min = 1.0,
    max = 2.0,
    rich_help_panel = _PANEL_SAMPLING,
    help = "Pin the repetition penalty. Default: unset (per-model recommendation).",
)
_PRESENCE_PENALTY_OPTION = typer.Option(
    None,
    "--presence-penalty",
    min = 0.0,
    max = 2.0,
    rich_help_panel = _PANEL_SAMPLING,
    help = "Pin the presence penalty. Default: unset (per-model recommendation).",
)
_MAX_TOKENS_OPTION = typer.Option(
    None,
    "--max-tokens",
    min = 1,
    rich_help_panel = _PANEL_SAMPLING,
    help = (
        "Most tokens the agent may generate in one response. Default: a quarter of the "
        "context window, up to 32,000. Capped at half the window so the conversation "
        "keeps room."
    ),
)

# Agent-session knobs.
_KEY_OPTION = typer.Option(
    None,
    "--api-key",
    envvar = "UNSLOTH_API_KEY",
    rich_help_panel = _PANEL_SESSION,
    help = "Unsloth API key. For a local Unsloth it is minted automatically and "
    "remembered per server. For a remote server, pass one with --api-key "
    "(or UNSLOTH_API_KEY); it is remembered for next time.",
)
_LAUNCH_OPTION = typer.Option(
    True,
    "--launch/--no-launch",
    rich_help_panel = _PANEL_SESSION,
    help = "--no-launch prints the env and command instead (remote shells, WSL).",
)
# One normalized "run tools without prompting" switch. Each agent spells this differently and it is easy to forget which is which, so accept every spelling and route to the agent's own mechanism in _yolo_command_flags / the config writers.
_YOLO_OPTION = typer.Option(
    False,
    "--yolo",
    "--dangerously-skip-permissions",
    "--dangerously-bypass-approvals-and-sandbox",
    rich_help_panel = _PANEL_SESSION,
    help = "Auto-approve all tool actions for this session; routed to the agent's own "
    "flag/config. Any of the three spellings works for any agent.",
)
_PERSIST_OPTION = typer.Option(
    False,
    "--persist/--no-persist",
    rich_help_panel = _PANEL_SESSION,
    help = (
        "Keep this agent's Unsloth-managed session dir so you can resume it later. "
        "codex/openclaw/hermes/pi/dsh have their whole home relocated into an Unsloth dir "
        "that is a throwaway temp dir (wiped on exit) by default; with --persist it "
        "lives under the Unsloth agents dir and survives, so their own resume can reopen "
        "it. claude and opencode keep sessions in your own stores (~/.claude, "
        "~/.local/share/opencode), so they already resume regardless. To reopen a "
        "session, pass the agent's own resume command through, e.g. "
        "`unsloth start codex --persist resume` or `claude --resume <id>`; those flow to "
        "the agent unchanged."
    ),
)
_AS_SUBAGENT_OPTION = typer.Option(
    False,
    "--as-subagent",
    rich_help_panel = _PANEL_SESSION,
    help = "Keep the coding agent's current model and add Unsloth as a local subagent.",
)
_AUTO_ROUTE_OPTION = typer.Option(
    False,
    "--auto-route",
    rich_help_panel = _PANEL_SESSION,
    help = "Keep the agent's current model and let it hand routine, self-contained work to a "
    "local Unsloth subagent without being asked.",
)
_APP_OPTION = typer.Option(
    False,
    "--app",
    rich_help_panel = _PANEL_SESSION,
    help = (
        "Add Unsloth to the agent's desktop app instead of starting the CLI: writes the "
        "provider and its own API key into your config (backed up first) and leaves your "
        "default model alone, so you pick Unsloth in the app's model picker. Re-run after "
        "loading another model."
    ),
)
_CODEX_APP_OPTION = typer.Option(
    False,
    "--app",
    rich_help_panel = _PANEL_SESSION,
    help = (
        "Switch the Codex desktop app to Unsloth instead of starting the CLI, open it, and "
        "switch it back when this command exits or Unsloth stops (the app only offers one "
        "provider's models at a time)."
    ),
)

# Per-agent CLI flag for "run tools without prompting". OpenCode (native --auto is command-scoped, handled below) and OpenClaw (config-only) are absent from this prefix map.
_YOLO_COMMAND_FLAGS = {
    "claude": ["--dangerously-skip-permissions"],
    "codex": ["--dangerously-bypass-approvals-and-sandbox"],
    "hermes": ["--yolo"],
    # Pi never prompts per tool call; its only approval gate is project trust, so -a (trust project resources) is the closest "do not ask me" equivalent.
    "pi": ["--approve"],
    "vibe": ["--auto-approve"],
}


def _yolo_command_flags(agent: str, yolo: bool) -> list:
    # .get so a config-based agent (or a typo) yields no flag instead of a KeyError.
    return _YOLO_COMMAND_FLAGS.get(agent, []) if yolo else []


# Subcommands that reject --auto (OpenCode exposes it only on the default TUI and `run`), so `opencode serve --auto` is never emitted. Includes console/generate, hidden from `opencode --help` but still registered. Unknown first positionals are TUI paths and get --auto.
_OPENCODE_NON_AUTO_SUBCOMMANDS = frozenset(
    "completion acp mcp attach debug providers auth agent upgrade uninstall serve web "
    "models stats export import github pr session plugin plug db console generate".split()
)
_OPENCODE_V2_SUBCOMMANDS = frozenset(
    "acp api debug console auth mcp plugin models export import mini run service pair serve".split()
)
_OPENCODE_V2_STANDALONE_SUBCOMMANDS = frozenset("api models export import mini run".split())
_OPENCODE_GLOBAL_BOOLEAN_OPTIONS = frozenset(
    "-h --help -v --version --print-logs --pure --mdns --standalone --wizard".split()
)
_OPENCODE_GLOBAL_VALUE_OPTIONS = frozenset(
    "--log-level --port --hostname --mdns-domain --cors --server --completions --cpu-profile".split()
)
_OPENCODE_NATIVE_AUTO_MIN_VERSION = (1, 17, 12)


def _opencode_version(executable: str) -> Optional[tuple[int, int, int]]:
    try:
        output = subprocess.check_output(
            [executable, "--version"],
            text = True,
            encoding = "utf-8",
            errors = "replace",
            timeout = 10,
            stderr = subprocess.DEVNULL,
            env = _probe_env(),
        )
    except Exception:
        return None
    match = re.search(r"(\d+)\.(\d+)\.(\d+)", output)
    return tuple(int(part) for part in match.groups()) if match else None


def _opencode_command() -> tuple[str, bool]:
    resolved_v2 = _which_with_install_dirs("opencode2")
    if resolved_v2:
        return resolved_v2, True
    # Distro packages (Arch extra, opencode-beta) ship V2 as plain `opencode`, which rejects V1's --model flag.
    resolved = _which_with_install_dirs("opencode")
    version = _opencode_version(resolved) if resolved else None
    return "opencode", bool(version) and version[0] >= 2


def _opencode_supports_native_auto(command: str = "opencode") -> bool:
    if Path(command).stem.lower() == "opencode2":
        return True
    executable = _which_with_install_dirs(command)
    if executable is None:
        # No local binary: a --no-launch recipe may run elsewhere, and _run installs the current release on launch, so either way assume native --auto is available.
        return True
    version = _opencode_version(executable)
    return bool(version) and version >= _OPENCODE_NATIVE_AUTO_MIN_VERSION


def _opencode_subcommand(args: list[str]) -> tuple[Optional[str], Optional[int]]:
    """Return an explicit OpenCode subcommand and its index after global options."""
    index = 0
    while index < len(args):
        arg = args[index]
        if arg == "--":
            return None, None
        if arg in _OPENCODE_GLOBAL_BOOLEAN_OPTIONS:
            index += 1
            continue
        if arg in _OPENCODE_GLOBAL_VALUE_OPTIONS:
            index += 2
            continue
        if any(arg.startswith(f"{option}=") for option in _OPENCODE_GLOBAL_VALUE_OPTIONS):
            index += 1
            continue
        # A non-global option (--session) is a TUI flag; stop before its value is mistaken for a subcommand.
        if arg.startswith("-"):
            return None, None
        return arg, index
    return None, None


def _opencode_native_auto_args(
    args: list[str],
    yolo: bool,
    *,
    v2: bool = False,
) -> tuple[list[str], bool]:
    """Add OpenCode's native --auto when the selected command supports it."""
    routed = list(args)
    if not yolo:
        return routed, False
    subcommand, _ = _opencode_subcommand(routed)
    if v2 and subcommand in _OPENCODE_V2_SUBCOMMANDS and subcommand != "run":
        return routed, False
    if not v2 and subcommand in _OPENCODE_NON_AUTO_SUBCOMMANDS:
        return routed, False
    separator = routed.index("--") if "--" in routed else len(routed)
    # --mini's runMini TUI forces auto=false and never forwards --auto, so appending it is useless; fall back to the config permission block so --yolo still auto-approves.
    if any(arg == "--mini" or arg.startswith("--mini=") for arg in routed[:separator]):
        return routed, False
    if "--auto" not in routed[:separator]:
        routed.insert(separator, "--auto")
    return routed, True


def _opencode_v2_standalone_args(args: list[str]) -> list[str]:
    """Keep session-only config on the V2 server that consumes it."""
    routed = list(args)
    separator = routed.index("--") if "--" in routed else len(routed)
    head = routed[:separator]
    if (
        "--standalone" in head
        or "--server" in head
        or any(arg.startswith("--server=") for arg in head)
    ):
        return routed
    subcommand, subcommand_index = _opencode_subcommand(routed)
    if (
        subcommand in _OPENCODE_V2_SUBCOMMANDS
        and subcommand not in _OPENCODE_V2_STANDALONE_SUBCOMMANDS
    ):
        return routed
    insert_at = (
        subcommand_index + 1 if subcommand in _OPENCODE_V2_STANDALONE_SUBCOMMANDS else separator
    )
    routed.insert(insert_at, "--standalone")
    return routed


def _hermes_install_hint() -> str:
    return _HERMES_WINDOWS_INSTALL_HINT if os.name == "nt" else _HERMES_POSIX_INSTALL_HINT


def _vibe_install_hint() -> str:
    return _VIBE_WINDOWS_INSTALL_HINT if os.name == "nt" else _VIBE_POSIX_INSTALL_HINT


def _npm_install_hint(
    package: str,
    *,
    ignore_scripts: bool = False,
    prefix: Optional[Path] = None,
) -> str:
    parts = ["npm", "install", "-g"]
    if prefix is not None:
        parts.extend(("--prefix", str(prefix)))
    elif os.name != "nt":
        # No home (bare container UID): fall back to npm's own prefix instead of failing.
        try:
            parts.extend(("--prefix", str(Path.home() / ".local")))
        except (RuntimeError, OSError):
            pass
    if ignore_scripts:
        parts.append("--ignore-scripts")
    parts.append(package)
    if os.name == "nt":
        return " ".join(_powershell_quote(part) for part in parts)
    return shlex.join(parts)


def _hermes_resume_oneshot_args(args: list[str]) -> list[str]:
    """Route resumed one-shot prompts through Hermes' session-aware chat command."""
    has_resume = any(
        arg in ("--resume", "-r", "--continue", "-c")
        or arg.startswith(("--resume=", "--continue="))
        or (len(arg) > 2 and arg.startswith(("-r", "-c")))
        for arg in args
    )
    if not has_resume:
        return args

    rewritten = list(args)
    for index, arg in enumerate(rewritten):
        if arg in ("-z", "--oneshot"):
            rewritten[index] = "-q"
        elif len(arg) > 2 and arg.startswith("-z"):
            # argparse accepts attached short-option values (`-zPROMPT` and `-z=PROMPT`); preserve the value byte-for-byte when switching to -q.
            rewritten[index] = f"-q{arg[2:]}"
        elif arg.startswith("--oneshot="):
            rewritten[index] = f"--query={arg.partition('=')[2]}"
        else:
            continue
        if any(item == "--usage-file" or item.startswith("--usage-file=") for item in args):
            raise typer.BadParameter(
                "Hermes cannot resume a one-shot session with --usage-file; remove that option."
            )
        # `chat -Q -q` is the only mode that can resume a session, but it does not inherit hermes' one-shot approval semantics: `-z` itself sets HERMES_YOLO_MODE=1 and HERMES_ACCEPT_HOOKS=1 for the call, because a one-shot has no user at the terminal to answer a prompt. Re-add the equivalent flags so a resumed `-z` keeps behaving like a plain `-z` instead of stalling on an approval nobody can answer. This is parity with the flag the user already typed, not the --yolo option: a resumed INTERACTIVE session still prompts as usual.
        prefix = ["chat", "-Q"]
        if "--yolo" not in rewritten:
            prefix.append("--yolo")
        if "--accept-hooks" not in rewritten:
            prefix.append("--accept-hooks")
        rewritten = prefix + rewritten
        return rewritten
    return args


_DSH_LAUNCHER_ARGS = frozenset(
    "--profile --patch --dump-config --dump-default-config -V --version plugin web".split()
)


# Launcher invocations that boot no profile, so they take no --patch overlay.
_DSH_NO_PROFILE_ARGS = frozenset("-V --version plugin".split())


def _dsh_command(args: list[str], patch: Optional[str] = None) -> list[str]:
    head = args[0] if args else ""
    # The web app takes no positionals, so a leading bare word is a profile name (`dsh headless "task"`).
    if (
        head in _DSH_LAUNCHER_ARGS
        or head.startswith(("--profile=", "--patch="))
        or (head and not head.startswith("-"))
    ):
        command = ["dsh", *args]
    else:
        command = ["dsh", "web", *args]
    if patch is not None and command[1] not in _DSH_NO_PROFILE_ARGS:
        # dsh name expands to --profile name only when the name comes first, so put the overlay after a bare name and before any leading option.
        at = 1 if command[1].startswith("-") else 2
        command[at:at] = ["--patch", patch]
    return command


class LoadOptions(NamedTuple):
    """Model-load knobs forwarded to /api/inference/load when --model triggers a load."""

    gguf_variant: Optional[str] = None
    max_seq_length: int = 0
    load_in_4bit: bool = True
    tensor_parallel: bool = False
    gpu_memory_mode: Optional[Literal["auto", "manual"]] = None
    # Names the user actually typed: --context-length 0 equals the declared default yet is a reset the server must hear. Appended last to keep positional callers working.
    supplied: frozenset = frozenset()

    def overrides(self) -> frozenset:
        """Fields that must reach the load: typed explicitly, or differing from default."""
        differing = {
            name
            for name, default in (
                ("gguf_variant", None),
                ("max_seq_length", 0),
                ("load_in_4bit", True),
                ("tensor_parallel", False),
                ("gpu_memory_mode", None),
            )
            if getattr(self, name) != default
        }
        # Internal callers never populate `supplied`, so a non-default value counts too.
        return frozenset(differing) | frozenset(self.supplied)


_LOAD_OPTION_PARAMS = (
    "gguf_variant",
    "max_seq_length",
    "load_in_4bit",
    "tensor_parallel",
    "gpu_memory_mode",
)


def _supplied_load_params(ctx) -> frozenset:
    """Which load knobs Click saw on the command line. The context must be PASSED IN: Typer invokes callbacks with no active click context, so click.get_current_context() is None. Unaskable gives an empty set, and `overrides()` falls back to comparing values."""
    getter = getattr(ctx, "get_parameter_source", None)
    if getter is None:
        return frozenset()
    supplied = set()
    for name in _LOAD_OPTION_PARAMS:
        try:
            source = getter(name)
        except Exception:
            continue
        # By member NAME, not identity or ordering: Typer vendors its own click, so this is typer._click's ParameterSource, and click 8.3 reordered the IntEnum.
        if getattr(source, "name", None) == "COMMANDLINE":
            supplied.add(name)
    return frozenset(supplied)


def _load_options(
    ctx, gguf_variant, max_seq_length, load_in_4bit, tensor_parallel, gpu_memory_mode
) -> LoadOptions:
    """Build LoadOptions for an agent command, recording what was typed."""
    return LoadOptions(
        gguf_variant,
        max_seq_length,
        load_in_4bit,
        tensor_parallel,
        gpu_memory_mode,
        _supplied_load_params(ctx),
    )


class ServerOptions(NamedTuple):
    """Start flags: carried fields ride in the agent's requests; the rest configure an auto-started server."""

    enable_tools: Optional[bool] = None
    tool_call_healing: Optional[bool] = None
    tool_call_nudging: Optional[bool] = None
    reasoning: Optional[Literal["on", "off", "auto"]] = None
    reasoning_effort: Optional[str] = None
    temperature: Optional[float] = None
    top_p: Optional[float] = None
    top_k: Optional[int] = None
    min_p: Optional[float] = None
    repetition_penalty: Optional[float] = None
    presence_penalty: Optional[float] = None
    # Fields the agent's own config sends with each request, kept off the server.
    carried: frozenset = frozenset()
    # Carried fields with a value: an inherited UNSLOTH_SAMPLING_* pin would override them.
    unpinned: frozenset = frozenset()

    def sent_by_agent(self) -> frozenset:
        # A request cannot ask for the template default back, so auto stays a server setting.
        unsent = {"reasoning"} if self.reasoning == "auto" else set()
        if self.reasoning_effort not in _STUDIO_REASONING_EFFORTS:
            unsent.add("reasoning_effort")
        return self.carried - unsent

    def request_body(self) -> dict:
        sent = self.sent_by_agent()
        body = {
            name: getattr(self, name)
            for name in _SAMPLING_FIELDS
            if name in sent and getattr(self, name) is not None
        }
        if "reasoning" in sent and self.reasoning in ("on", "off"):
            body["enable_thinking"] = self.reasoning == "on"
        if "reasoning_effort" in sent:
            body["reasoning_effort"] = self.reasoning_effort
        return body


_SAMPLING_FIELDS = (
    "temperature",
    "top_p",
    "top_k",
    "min_p",
    "repetition_penalty",
    "presence_penalty",
)
_REASONING_FIELDS = frozenset({"reasoning", "reasoning_effort"})
_ALL_REQUEST_FIELDS = frozenset(_SAMPLING_FIELDS) | _REASONING_FIELDS
_REQUEST_BODY_KEYS = (*_SAMPLING_FIELDS, "enable_thinking", "reasoning_effort")
_STUDIO_REASONING_EFFORTS = ("none", "minimal", "low", "medium", "high", "max", "xhigh")
_CODEX_REASONING_EFFORTS = ("none", "minimal", "low", "medium", "high", "xhigh")


def _codex_reasoning_effort(
    reasoning: Optional[str], reasoning_effort: Optional[str]
) -> Optional[str]:
    if reasoning == "off":
        return "none"
    if reasoning_effort in _CODEX_REASONING_EFFORTS:
        return reasoning_effort
    return None


def _merge_request_body(container: dict, key: str, body: dict) -> None:
    current = container.get(key)
    current = (
        {k: v for k, v in current.items() if k not in _REQUEST_BODY_KEYS}
        if isinstance(current, dict)
        else {}
    )
    current.update(body)
    if current:
        container[key] = current
    else:
        container.pop(key, None)


def _split_repo_variant(model: str) -> tuple:
    """Split ``org/name:QUANT`` into ``("org/name", "QUANT")``. ``unsloth run`` and llama.cpp accept ``--model org/name:QUANT`` as shorthand for ``--model org/name --gguf-variant QUANT``, so mirror that here and a ``:variant`` suffix resolves against the already-loaded ``org/name`` (which the loaded listing shows without the suffix) instead of trying to load a repo id containing ``:``, which Hugging Face rejects and which would evict a model another session is using. Local paths, Windows drive letters and ids without a ``:`` pass through unchanged."""
    s = (model or "").strip()
    if not s or s.startswith(("/", "./", "../", "~")) or s == ".":
        return s, None
    if len(s) >= 2 and s[1] == ":" and s[0].isalpha():  # Windows drive, e.g. C:\models\x
        return s, None
    if ":" not in s:
        return s, None
    repo, _, variant = s.rpartition(":")
    if not repo or not variant or "/" in variant:
        return s, None
    return repo, variant


def _looks_like_model(token: str) -> bool:
    """True for a bare `org/name(:variant)` hub id that is not a flag or a local path. Reuses `_is_hub_model_id`, so a relative dir like `owner/repo` that actually exists is left for the agent instead of being taken as a model; a non-existent `org/name` is treated as a hub id."""
    if not token or token.startswith("-") or " " in token:
        return False
    repo, _ = _split_repo_variant(token)
    return _is_hub_model_id(repo)


def _consume_positional_model(model: Optional[str], args: list) -> tuple:
    """Route a leading `org/name` positional to --model when --model was not given. Only the FIRST token is considered so an option value like `--profile owner/repo` is never stolen, and only when --model is absent so an explicit --model always wins. Returns (model, remaining_args) with the consumed token removed from the passthrough."""
    args = list(args)
    if model or not args or not _looks_like_model(args[0]):
        return model, args
    return args[0], args[1:]


def _display_model_spec(model: str, variant: Optional[str]) -> str:
    """Return a user-facing model name that includes the selected GGUF variant."""
    repo, inline_variant = _split_repo_variant(model)
    selected_variant = variant or inline_variant
    return f"{repo}:{selected_variant}" if selected_variant else model


def _model_status(
    base: str,
    key: str,
    model_id: Optional[str] = None,
) -> dict:
    # Studio serving several models answers for the one serving model_id; an older one ignores it.
    query = f"?{urlencode({'model': model_id})}" if model_id else ""
    return _http_json("GET", f"{base}/api/inference/status{query}", key)


def _subagent_model_id(
    base: str,
    key: str,
    entry: dict,
    requested_model: Optional[str],
    requested_variant: Optional[str],
) -> str:
    """Return an API model id that preserves the selected GGUF variant. Coding-agent model definitions outlive the initial load, so if Unsloth later unloads the model a bare repository id may resolve to a different cached quant; include the explicit or currently loaded variant so an automatic reload selects the same weights."""
    model_id = str(entry["id"])
    _, inline_variant = _split_repo_variant(requested_model or "")
    variant = requested_variant or inline_variant
    if not variant:
        try:
            status = _model_status(base, key, model_id)
        except Exception:
            status = {}
            typer.echo(
                "Warning: could not verify the loaded GGUF variant; a later reload "
                "may pick a different cached quant. Pass :variant to pin it.",
                err = True,
            )
        if status.get("is_gguf"):
            variant = status.get("gguf_variant")
    elif _MLX_PRECISION_FOLDER_RE.fullmatch(str(variant).strip()):
        # The API resolves no :folder suffix for an MLX resident (bf16 reads as a GGUF quant), so pin nothing.
        try:
            if _model_status(base, key, model_id).get("is_mlx"):
                variant = None
        except Exception:
            pass
    if variant and _is_hub_model_id(model_id):
        return _display_model_spec(model_id, str(variant))
    if variant:
        # A path load is advertised as a bare basename with no ":variant" channel, so the quant cannot be recorded and a later reload picks for itself.
        typer.echo(
            f"Warning: {model_id} loaded from a path, so the subagent config cannot "
            f"pin the {variant} quant; a reload may choose a different one. Load the "
            "model by repository id to pin it.",
            err = True,
        )
    return model_id


def _fail(message: str) -> NoReturn:
    typer.echo(message, err = True)
    raise typer.Exit(code = 1)


def _reject_as_subagent(agent: str, args: list) -> None:
    # Reject early, or the flag reaches the agent binary after Unsloth loaded the model.
    if any(arg == "--as-subagent" or arg.startswith("--as-subagent=") for arg in args):
        _fail(f"--as-subagent is not supported for {agent}.")
    _reject_auto_route(agent, args)


def _reject_auto_route(agent: str, args: list) -> None:
    if any(arg == "--auto-route" or arg.startswith("--auto-route=") for arg in args):
        _fail(f"--auto-route is not supported for {agent}.")


def _http_error_detail(exc: urllib.error.HTTPError) -> str:
    try:
        body = json.loads(exc.read().decode())
        return body.get("detail") or body["error"]["message"]
    except Exception:
        return str(exc)


def _fail_request(exc: Exception, error: str) -> NoReturn:
    """Fail with `error` plus whatever the server or the transport gave as a reason."""
    if isinstance(exc, urllib.error.HTTPError):
        _fail(f"{error}: {_http_error_detail(exc)}")
    _fail(f"{error}: {getattr(exc, 'reason', None) or exc}")


def _http_json(
    method: str,
    url: str,
    token: str,
    payload = None,
    timeout = 30,
    error = None,
):
    """On a failed request: raise if `error` is None, else fail with `error` plus the reason."""
    request = urllib.request.Request(
        url,
        data = None if payload is None else json.dumps(payload).encode(),
        headers = {
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
            "User-Agent": _USER_AGENT,
        },
        method = method,
    )
    try:
        # No redirects: a 3xx would leak this bearer token to an unvetted base.
        with urlopen_no_redirect(request, timeout = timeout) as response:
            body = json.loads(response.read().decode() or "{}")
        # A padded /load or /unload commits its 200 early, so a late failure arrives in-band; raise it as the HTTPError handled below.
        return raise_for_deferred_error(url, body)
    except (urllib.error.HTTPError, urllib.error.URLError, TimeoutError) as exc:
        if error is None:
            raise
        _fail_request(exc, error)


# A server that WE auto-started (never one we merely found). Kept at module scope so failure paths and the atexit backstop can tear it down without threading a handle through all six agent commands. Only one agent runs per process, so one slot is enough.
_auto_served_server: Optional[subprocess.Popen] = None
# Caps time since the download last advanced, not total elapsed.
_SERVER_START_TIMEOUT_S = 900
_DOWNLOAD_POLL_INTERVAL_S = 1.0
# Ceiling on the doubling back-off the progress reader uses after a polling error.
_DOWNLOAD_POLL_MAX_BACKOFF_S = 60.0
# How often the progress reader re-lists the repos a load announced; each listed repo costs a cache scan per poll.
_LOAD_DOWNLOAD_LIST_INTERVAL_S = 5.0
_START_API_KEY_PREFIX = "UNSLOTH_START_API_KEY: "
_START_PORT_PREFIX = "UNSLOTH_START_PORT: "
_START_API_KEY_MARKER_ENV = "_UNSLOTH_START_API_KEY_MARKER"


def _format_download_bytes(value: int) -> str:
    value = max(0, int(value))
    for unit in ("B", "KiB", "MiB", "GiB", "TiB"):
        if value < 1024 or unit == "TiB":
            precision = 0 if unit in ("B", "KiB") else 1
            return f"{value:.{precision}f} {unit}"
        value /= 1024
    return "0 B"


def _format_download_eta(seconds: float) -> str:
    seconds = max(0, int(seconds))
    if seconds < 60:
        return f"{seconds}s"
    minutes, seconds = divmod(seconds, 60)
    if minutes < 60:
        return f"{minutes}m {seconds:02d}s"
    hours, minutes = divmod(minutes, 60)
    return f"{hours}h {minutes:02d}m"


class _DownloadProgressDisplay:
    """Render download progress without making redirected output noisy."""

    def __init__(self) -> None:
        self._samples: list[tuple[float, int]] = []
        self._shown = False
        self._last_bucket = -1
        self._last_line_length = 0
        self._last_expected = 0
        self._source: Optional[str] = None
        self._interactive = bool(getattr(sys.stdout, "isatty", lambda: False)())

    def update(
        self,
        progress: dict,
        source: Optional[str] = None,
    ) -> None:
        if source != self._source:
            # A new repo is a new transfer; else redirected output (prints only on a rising bucket) stays silent for a base that starts after the adapter finished.
            self._source = source
            self._samples.clear()
            self._last_expected = 0
            # Keep `_shown`: `complete()` and `close()` gate on it.
            self._last_bucket = -1
        downloaded = max(0, int(progress.get("downloaded_bytes") or 0))
        completed = max(0, int(progress.get("completed_bytes") or 0))
        expected = max(0, int(progress.get("expected_bytes") or 0))
        self._last_expected = max(self._last_expected, expected)
        fraction = float(progress.get("progress") or 0)
        if downloaded <= 0:
            return
        # A fully cached snapshot can report 99% with no incomplete bytes; that is not a transfer, so do not show it as a download.
        if completed >= downloaded > 0:
            return

        now = time.monotonic()
        if self._samples and downloaded < self._samples[-1][1]:
            self._samples.clear()
        self._samples.append((now, downloaded))
        cutoff = now - 15.0
        while len(self._samples) > 2 and self._samples[0][0] < cutoff:
            self._samples.pop(0)

        rate = 0.0
        if len(self._samples) >= 2:
            elapsed = self._samples[-1][0] - self._samples[0][0]
            delta = self._samples[-1][1] - self._samples[0][1]
            if elapsed >= 1.0 and delta > 0:
                rate = delta / elapsed

        if expected > 0:
            # The endpoint caps at 99% while bytes remain in an incomplete file; trust it.
            fraction = min(1.0, max(0.0, fraction))
            percent = min(100, max(0, int(fraction * 100)))
            filled = min(24, int(fraction * 24))
            bar = "=" * filled + ">" + "." * max(0, 23 - filled) if filled < 24 else "=" * 24
            line = (
                f"Downloading model [{bar}] {percent:3d}% "
                f"{_format_download_bytes(downloaded)} / {_format_download_bytes(expected)}"
            )
            bucket = percent // 10
            if rate > 0:
                line += f" | {_format_download_bytes(rate)}/s"
                if downloaded < expected:
                    line += f" | ETA {_format_download_eta((expected - downloaded) / rate)}"
        else:
            line = f"Downloading model: {_format_download_bytes(downloaded)}"
            bucket = downloaded // (1024**3)
            if rate > 0:
                line += f" | {_format_download_bytes(rate)}/s"

        if self._interactive:
            padding = " " * max(0, self._last_line_length - len(line))
            typer.echo(f"\r{line}{padding}", nl = False)
            sys.stdout.flush()
            self._last_line_length = len(line)
        elif not self._shown or bucket > self._last_bucket:
            typer.echo(line)
            self._last_bucket = bucket
        self._shown = True

    def close(self) -> None:
        if self._interactive and self._shown:
            typer.echo()
        self._last_line_length = 0

    def complete(self) -> None:
        """Finish a displayed transfer after the model load confirms success."""
        if not self._shown:
            return
        downloaded = self._samples[-1][1] if self._samples else 0
        expected = max(downloaded, getattr(self, "_last_expected", 0))
        self.update(
            {
                "downloaded_bytes": expected,
                "expected_bytes": expected,
                "progress": 1.0,
            }
        )


def _normalized_variant(value: object) -> str:
    return re.sub(r"[^a-z0-9]", "", str(value or "").lower())


class _ModelDownloadProgress:
    """Best-effort polling of the model download endpoints."""

    def __init__(self, base: str, key: str, model: str, variant: Optional[str]) -> None:
        self._base = base
        self._key = key
        self._model = model
        self._variant = variant or ""
        self._expected_bytes = 0
        self._downloaded_bytes = 0
        self._failures = 0
        self._retry_at = 0.0
        self._display = _DownloadProgressDisplay()
        self._configured = False
        # A local model has no Hub reading of its own, but a remote base it names is still listed.
        self._disabled = not _is_hub_model_id(model)
        self._progress_prefix = "/api/hub"
        # Repos the load announced (its base, the base the loader substitutes): bytes summed for liveness.
        self._repo_bytes: dict[str, int] = {}
        self._companions: list[str] = []
        self._finished: dict[
            str, dict
        ] = {}  # Complete companions: final reading kept, never re-read.
        self._listed_at: Optional[float] = None
        self._active_repo = model

    def _is_gguf(self) -> bool:
        return bool(self._variant) or "gguf" in self._model.lower()

    def _configure(self) -> None:
        self._configured = True
        if self._disabled:
            return
        # GGUF repos need the selected quant's size; the repo endpoint totals every quant. Resolve the variant first, otherwise show bytes only.
        if self._is_gguf():
            try:
                params = urlencode({"repo_id": self._model})
                try:
                    info = _http_json(
                        "GET",
                        f"{self._base}/api/hub/gguf-variants?{params}",
                        self._key,
                        timeout = 10,
                    )
                except urllib.error.HTTPError as exc:
                    if exc.code != 404:
                        raise
                    self._progress_prefix = "/api/models"
                    info = _http_json(
                        "GET",
                        f"{self._base}/api/models/gguf-variants?{params}",
                        self._key,
                        timeout = 10,
                    )
                self._variant = self._variant or str(info.get("default_variant") or "")
                wanted = _normalized_variant(self._variant)
                for item in info.get("variants") or []:
                    quant = _normalized_variant(item.get("quant"))
                    filename = _normalized_variant(item.get("filename"))
                    if wanted and (wanted == quant or wanted in filename):
                        self._expected_bytes = int(
                            item.get("download_size_bytes") or item.get("size_bytes") or 0
                        )
                        break
            except Exception:
                # Older servers lack this endpoint; byte progress is still useful.
                pass

    def _companion_repos(self) -> list[str]:
        now = time.monotonic()
        if self._listed_at is not None and now - self._listed_at < _LOAD_DOWNLOAD_LIST_INTERVAL_S:
            return self._companions
        self._listed_at = now
        try:
            url = f"{self._base}{self._progress_prefix}/active-downloads"
            listing = _http_json("GET", url, self._key, timeout = 10)
        except urllib.error.HTTPError as exc:
            if exc.code == 404:
                self._listed_at = float("inf")  # Older server: no load-owned jobs to find.
            return self._companions
        except Exception:
            return self._companions
        for item in listing.get("downloads") or []:
            repo = str(item.get("repo_id") or "")
            if not (item.get("owner") == "load" or item.get("load_attached")):
                continue
            if repo and repo.lower() != self._model.lower() and repo not in self._companions:
                self._companions.append(repo)
        return self._companions

    def _read(
        self,
        repo: str,
        gguf: bool = False,
    ) -> dict:
        if gguf:
            params = urlencode(
                {"repo_id": repo, "variant": self._variant, "expected_bytes": self._expected_bytes}
            )
            url = f"{self._base}{self._progress_prefix}/gguf-download-progress?{params}"
        else:
            params = urlencode({"repo_id": repo})
            url = f"{self._base}{self._progress_prefix}/download-progress?{params}"
        return _http_json("GET", url, self._key, timeout = 10)

    def poll(self) -> None:
        if not self._configured:
            self._configure()
        if time.monotonic() < self._retry_at:
            return
        try:
            readings = {}
            try:
                if not self._disabled:
                    readings[self._model] = self._read(self._model, gguf = self._is_gguf())
            except urllib.error.HTTPError as exc:
                if exc.code != 404 or self._progress_prefix == "/api/models":
                    raise
                self._progress_prefix = "/api/models"
                self.poll()
                return
            for repo in self._companion_repos():
                if repo in self._finished:
                    readings[repo] = self._finished[repo]
                    continue
                try:
                    readings[repo] = item = self._read(repo)
                except Exception:
                    continue
                if (
                    0
                    < int(item.get("expected_bytes") or 0)
                    <= int(item.get("completed_bytes") or 0)
                ):
                    self._finished[repo] = item
            # The line follows whichever repo grew most; a repo first seen already large (a cached base) has not grown.
            growth = 0
            for repo, item in readings.items():
                current = max(0, int(item.get("downloaded_bytes") or 0))
                if current - self._repo_bytes.get(repo, current) > growth:
                    growth, self._active_repo = current - self._repo_bytes[repo], repo
                # Only ever rises, so a dip and recovery never counts as fresh growth.
                self._repo_bytes[repo] = max(self._repo_bytes.get(repo, 0), current)
            self._downloaded_bytes = max(self._downloaded_bytes, sum(self._repo_bytes.values()))
            self._failures = 0
            self._retry_at = 0.0
            active = self._active_repo if self._active_repo in readings else self._model
            if active in readings:
                self._display.update(readings[active], active)
        except Exception:
            # downloaded_bytes drives _start_studio_server liveness: back off on failure but never stop probing, or the download it protects dies.
            self._failures += 1
            self._retry_at = time.monotonic() + min(
                2.0**self._failures, _DOWNLOAD_POLL_MAX_BACKOFF_S
            )

    @property
    def downloaded_bytes(self) -> int:
        return self._downloaded_bytes

    def close(self) -> None:
        self._display.close()

    def complete(self) -> None:
        self._display.complete()


def _load_model_with_progress(
    base: str, key: str, model: str, load: LoadOptions, payload: dict
) -> dict:
    """Run the blocking load request while polling its download progress."""
    load_url = f"{base}/api/inference/load"
    result: list[tuple[bool, object]] = []
    done = threading.Event()

    def _load() -> None:
        try:
            value = _http_json(
                "POST",
                load_url,
                key,
                payload,
                timeout = 3600,
                error = "Model load failed",
            )
            result.append((True, value))
        except BaseException as exc:
            result.append((False, exc))
        finally:
            done.set()

    threading.Thread(target = _load, name = "unsloth-model-load", daemon = True).start()
    progress = _ModelDownloadProgress(base, key, model, load.gguf_variant)
    loading_announced = False
    try:
        while not done.wait(_DOWNLOAD_POLL_INTERVAL_S):
            if not loading_announced:
                typer.echo(f"Loading model: {_display_model_spec(model, load.gguf_variant)}")
                loading_announced = True
            progress.poll()
        ok, value = result[0]
        if not ok:
            assert isinstance(value, BaseException)
            # A pad-only or half-written body fails `_http_json`'s json.loads: report the padded 200 that never completed, not a JSON error from the API.
            if isinstance(value, ValueError):
                require_completed_padded_body(load_url, None)
            raise value
        progress.complete()
        # `_http_json` decodes a blank body as `{}`, which would look like a completed load.
        return require_completed_padded_body(load_url, value)
    finally:
        progress.close()


def _studio_healthy(base: str, timeout: float = 3.0) -> bool:
    request = urllib.request.Request(f"{base}/api/health", headers = {"User-Agent": _USER_AGENT})
    try:
        with urlopen_local(request, timeout = timeout) as response:
            return json.loads(response.read(65536).decode() or "{}").get("status") == "healthy"
    except Exception:
        return False


def _read_log(path: Path) -> str:
    try:
        return path.read_text(encoding = "utf-8", errors = "replace")
    except OSError:
        return "(no server log)"


def _log_tail(path: Path, lines: int = 20) -> str:
    return "\n".join(_read_log(path).splitlines()[-lines:])


def _redacted_log_tail(path: Path, lines: int = 20) -> str:
    """Tail with minted keys removed; only for tails shown on the terminal."""
    return re.sub(r"sk-unsloth-\S+", "sk-unsloth-[redacted]", _log_tail(path, lines))


def _shutdown_server(server: Optional[subprocess.Popen]) -> None:
    # Idempotent teardown of a server WE started, plus its own children (llama-server, cloudflared). A no-op once the process is already gone.
    if server is None or server.poll() is not None:
        return
    if os.name == "nt":
        # terminate()/kill() reach only the parent `unsloth run`; taskkill /T walks the whole tree so the llama-server child does not keep the port and GPU.
        try:
            subprocess.run(
                ["taskkill", "/PID", str(server.pid), "/T", "/F"],
                capture_output = True,
                timeout = 15,
                check = False,
            )
            server.wait(timeout = 5)
        except Exception:
            with contextlib.suppress(Exception):
                server.kill()
        return
    try:
        os.killpg(os.getpgid(server.pid), signal.SIGTERM)
    except OSError:
        server.terminate()
    try:
        server.wait(timeout = 15)
    except Exception:
        try:
            os.killpg(os.getpgid(server.pid), signal.SIGKILL)
        except OSError:
            server.kill()


def _shutdown_auto_served() -> None:
    global _auto_served_server
    server, _auto_served_server = _auto_served_server, None
    if server is not None and server.poll() is None:
        typer.echo("Stopping the auto-started Unsloth server…")
        _shutdown_server(server)


def _keep_auto_served() -> bool:
    """Release ownership so a successfully started server survives this CLI."""
    global _auto_served_server
    server, _auto_served_server = _auto_served_server, None
    atexit.unregister(_shutdown_auto_served)
    return server is not None and server.poll() is None


def _start_studio_server(
    base: str,
    model: str,
    load: LoadOptions,
    server: ServerOptions = ServerOptions(),
) -> tuple:
    """Spawn `unsloth run` for `model`, wait until it is fully ready, and return (base, server)."""
    global _auto_served_server
    # This interpreter, not the `unsloth` on PATH: that can be missing, another install, or on Windows the denied unsloth.exe (#8490).
    # Local import: unsloth_cli.commands.studio imports at package init after this module, so a top-level import would be circular.
    from unsloth_cli.commands.studio import _managed_cli_argv

    launch_head = _managed_cli_argv(Path(sys.executable))
    parsed = urlparse(base)
    # Tools default off means passthrough mode (relay the agent's own tools); --no-cloudflare means loopback only, no tunnel. Mirrors .github/scripts/serve-unsloth-run.sh. Healing/nudging travel via the child env below (version-agnostic) rather than new run flags that an older re-exec'd run could mistake for llama-server args.
    command = [
        *launch_head,
        "run",
        "-H",
        parsed.hostname or "127.0.0.1",
        "-p",
        str(parsed.port or 8888),
        "--enable-tools" if server.enable_tools else "--disable-tools",
        "--no-cloudflare",
        "--model",
        model,
    ]
    if load.gguf_variant:
        command += ["--gguf-variant", load.gguf_variant]
    if load.max_seq_length:
        command += ["--context-length", str(load.max_seq_length)]
    if not load.load_in_4bit:
        command += ["--no-load-in-4bit"]
    if load.tensor_parallel:
        command += ["--tensor-parallel"]
    if load.gpu_memory_mode is not None:
        command += ["--gpu-memory-mode", load.gpu_memory_mode]

    log_path = Path(tempfile.gettempdir()) / f"unsloth-start-server-{os.getpid()}.log"
    typer.echo("Starting Unsloth server")
    typer.echo(f"Model: {_display_model_spec(model, load.gguf_variant)}")
    typer.echo(f"Server log: {log_path}")
    # 0600: the `unsloth run` banner in this log carries the minted sk-unsloth- key, and the tempdir is world-traversable. Unlink first so a stale looser-mode file (pid reuse) cannot survive with its old permissions.
    log_path.unlink(missing_ok = True)
    log = os.fdopen(os.open(log_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600), "wb")
    # Own session/process group so a mid-session Ctrl+C (cancel a turn) does not reach the server. It survives a successful agent session; torn down on startup/launch failure.
    child_env = os.environ.copy()
    # Current llama-server versions read this documented env equivalent of --reasoning. Older managed versions ignore an unknown env variable instead of failing startup on an unknown passthrough CLI flag. An omitted start option follows the model template.
    child_env["LLAMA_ARG_REASONING"] = server.reasoning or "auto"
    # Always written, like the line above: an inherited value would otherwise pin a level the omitted flag promises to leave alone. 'default' is llama.cpp's own sentinel for "keep the chat template's level".
    child_env["LLAMA_ARG_REASONING_EFFORT"] = server.reasoning_effort or "default"
    # Pass the marker via env so an older launcher ignores it instead of treating an unknown CLI flag as a llama-server arg; new launchers preserve it across re-exec.
    child_env[_START_API_KEY_MARKER_ENV] = "1"
    # Convey healing/nudging through the env; `unsloth run` reads these when its own flags are omitted, so this works even if run re-execs into an older Unsloth venv. Only write when the operator set the flag explicitly; otherwise keep whatever they already exported (child_env is a copy of os.environ), falling back to the start defaults (healing on, nudging on) when nothing was inherited.
    if server.tool_call_healing is not None:
        child_env["UNSLOTH_DISABLE_TOOL_CALL_HEALING"] = "0" if server.tool_call_healing else "1"
    elif "UNSLOTH_DISABLE_TOOL_CALL_HEALING" not in child_env:
        child_env["UNSLOTH_DISABLE_TOOL_CALL_HEALING"] = "0"
    if server.tool_call_nudging is not None:
        child_env["UNSLOTH_TOOL_CALL_NUDGE"] = "1" if server.tool_call_nudging else "0"
    elif "UNSLOTH_TOOL_CALL_NUDGE" not in child_env:
        child_env["UNSLOTH_TOOL_CALL_NUDGE"] = "1"
    # Forward any sampling pin via the env; `unsloth run` reads UNSLOTH_SAMPLING_* and the backend resolver applies it as a hard override. Only set fields the operator specified.
    for _sampling_name in _SAMPLING_FIELDS:
        _sampling_env = f"UNSLOTH_SAMPLING_{_sampling_name.upper()}"
        _sampling_value = getattr(server, _sampling_name)
        if _sampling_value is not None:
            child_env[_sampling_env] = str(_sampling_value)
        elif _sampling_name in server.unpinned:
            child_env.pop(_sampling_env, None)
    kwargs: dict = {
        "stdout": log,
        "stderr": subprocess.STDOUT,
        "stdin": subprocess.DEVNULL,
        "env": child_env,
    }
    if os.name == "nt":
        kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
    else:
        kwargs["start_new_session"] = True
    try:
        server = subprocess.Popen(command, **kwargs)
    finally:
        log.close()  # Popen dup'd the fd; drop the parent's copy
    _auto_served_server = server
    atexit.register(_shutdown_auto_served)

    deadline = time.monotonic() + _SERVER_START_TIMEOUT_S
    progress: Optional[_ModelDownloadProgress] = None
    downloaded_bytes = 0
    early_key_seen = False
    port_followed = False
    try:
        while time.monotonic() < deadline:
            if server.poll() is not None:
                # The early key marker lands here before load finishes; redact it.
                tail = _redacted_log_tail(log_path)
                _shutdown_auto_served()
                _fail(f"The Unsloth server stopped before it was ready. Last log lines:\n{tail}")
            tail = _log_tail(log_path, lines = 400)
            # `unsloth run` falls forward off a taken port; it prints the port once, so read the whole log.
            if not port_followed:
                bound_port = re.search(
                    rf"^{re.escape(_START_PORT_PREFIX)}(\d+)$",
                    _read_log(log_path),
                    flags = re.MULTILINE,
                )
                if bound_port:
                    port_followed = True
                    base = _effective_base(base, int(bound_port.group(1)))
            if progress is None:
                marker = re.search(
                    rf"^{re.escape(_START_API_KEY_PREFIX)}(sk-unsloth-[^\s]+)$",
                    tail,
                    flags = re.MULTILINE,
                )
                if marker:
                    early_key_seen = True
                    progress = _ModelDownloadProgress(
                        base,
                        marker.group(1),
                        model,
                        load.gguf_variant,
                    )
            if progress is not None:
                progress.poll()
            # The cap measures time since bytes last arrived; log growth does not count (health polls and
            # heartbeats keep it growing while nothing loads).
            bytes_now = progress.downloaded_bytes if progress is not None else 0
            if bytes_now > downloaded_bytes:
                deadline = time.monotonic() + _SERVER_START_TIMEOUT_S
            downloaded_bytes = bytes_now
            # New children emit an early key marker, so wait for the Model loaded banner; older ones print the key only after load.
            ready_signal = "Model loaded:" in tail if early_key_seen else "sk-unsloth-" in tail
            if _studio_healthy(base) and ready_signal:
                if progress is not None:
                    progress.complete()
                    progress.close()
                    progress = None
                return base, server
            time.sleep(2.0)
    finally:
        if progress is not None:
            progress.close()
    _shutdown_auto_served()
    _fail(
        "The Unsloth server didn't become ready and made no progress for "
        f"{_SERVER_START_TIMEOUT_S}s. See {log_path}."
    )


def _effective_base(base: str, port: Optional[int] = None) -> str:
    # `unsloth run` binds to `parsed.port or 8888` and serves at the root, so normalize UNSLOTH_STUDIO_URL to plain scheme://host:port. A portless http://127.0.0.1 would otherwise launch on 8888 but poll port 80, and a path like /studio would poll /studio/api/health (404), either way hitting the startup timeout. IPv6 literals stay bracketed.
    parsed = urlparse(base)
    host = parsed.hostname or "127.0.0.1"
    if ":" in host:  # bare IPv6 literal (urlparse strips the brackets)
        host = f"[{host}]"
    return f"{parsed.scheme or 'http'}://{host}:{port or parsed.port or 8888}"


def _require_studio(
    model: Optional[str] = None,
    load: Optional[LoadOptions] = None,
    *,
    serve: bool = False,
    launch: bool = True,
    server_options: ServerOptions = ServerOptions(),
) -> tuple:
    """Return (base, server). server is a Popen only when WE auto-started it."""
    sent = server_options.sent_by_agent()
    server_options = server_options._replace(
        unpinned = frozenset(name for name in sent if getattr(server_options, name) is not None),
        **dict.fromkeys(sent),
    )
    # What the agent cannot send itself only reaches the env of a server WE launch, which then applies it to every client.
    _pinned = [
        "--" + _name.replace("_", "-")
        for _name in _SAMPLING_FIELDS
        if getattr(server_options, _name) is not None
    ]
    _reasoning_pins = [
        f"{_flag} {_value}"
        for _flag, _value in (
            ("--reasoning", server_options.reasoning),
            ("--reasoning-effort", server_options.reasoning_effort),
        )
        if _value is not None
    ]
    base = find_studio_server()
    if base is not None:
        if _pinned:
            typer.echo(
                f"Warning: an Unsloth server is already running at {base}, and this agent "
                f"cannot send {', '.join(_pinned)} itself; they apply only when this command "
                "starts the server, so the running server keeps its current sampling. Stop it "
                "with `unsloth studio stop` and re-run to apply them.",
                err = True,
            )
        if _reasoning_pins:
            typer.echo(
                f"Warning: an Unsloth server is already running at {base}, and this agent "
                f"cannot send {', '.join(_reasoning_pins)} itself; it takes effect only when "
                "this command starts the server, so the running server keeps its current "
                "reasoning mode. Stop it with `unsloth studio stop` and re-run to apply the "
                "override.",
                err = True,
            )
        _tool_flags = [
            _on if _value else _off
            for _value, _on, _off in (
                (server_options.enable_tools, "--enable-tools", "--disable-tools"),
                (
                    server_options.tool_call_healing,
                    "--enable-tool-call-healing",
                    "--disable-tool-call-healing",
                ),
                (
                    server_options.tool_call_nudging,
                    "--enable-tool-call-nudging",
                    "--disable-tool-call-nudging",
                ),
            )
            if _value is not None
        ]
        if _tool_flags:
            typer.echo(
                f"Warning: an Unsloth server is already running at {base}; "
                f"{', '.join(_tool_flags)} takes effect only when this command starts the "
                "server, so the running server keeps its current tool settings. Stop it with "
                "`unsloth studio stop` and re-run to apply it.",
                err = True,
            )
        return base, None
    expected = os.environ.get("UNSLOTH_STUDIO_URL", "http://127.0.0.1:8888").rstrip("/")
    # Auto-start a local server only for an interactive launch with a model to serve, and only for a plain-HTTP loopback target: never stand in for an explicit remote UNSLOTH_STUDIO_URL, and never for an https:// one, since `unsloth run` serves plain HTTP and the health poll against https would spin until the startup timeout.
    if (
        serve
        and launch
        and model
        and is_loopback_url(expected)
        and urlparse(expected).scheme == "http"
    ):
        # Normalize to the port unsloth run actually binds, so the health poll and the returned base hit the same server we launch, not a portless :80.
        expected = _effective_base(expected)
        load = load or LoadOptions()
        _server_wide = _pinned + [pin for pin in _reasoning_pins if pin != "--reasoning auto"]
        if _server_wide:
            typer.echo(
                f"Warning: this agent cannot send {', '.join(_server_wide)} itself, so the "
                "server this command starts applies them to every client until it stops.",
                err = True,
            )
        _dropped = [
            f"UNSLOTH_SAMPLING_{_name.upper()}"
            for _name in _SAMPLING_FIELDS
            if _name in server_options.unpinned
            and os.environ.get(f"UNSLOTH_SAMPLING_{_name.upper()}")
        ]
        if _dropped:
            typer.echo(
                f"Warning: this agent's flags replace the inherited {', '.join(_dropped)}, so "
                "the server this command starts drops those pins for every client.",
                err = True,
            )
        # Leave a bare GGUF repo's variant unset: the server's own quant preference already picks the best available (UD-Q4_K_XL for Unsloth uploads, else Q4_K_M) and falls back when that exact quant is missing, which forcing a fixed variant here would break.
        return _start_studio_server(expected, model, load, server_options)
    if not model:
        hint = " Pass --model to have it start one for you, or start one with"
    elif serve and not launch:
        hint = " --no-launch never starts a server; drop it, or start one with"
    else:
        hint = " Start one with"
    _fail(
        f"No running Unsloth server found at {expected}.{hint} `unsloth studio`, or point "
        "UNSLOTH_STUDIO_URL at a remote server."
    )


def _studio_auth_root() -> Path:
    from unsloth_cli.commands.studio import STUDIO_HOME
    return STUDIO_HOME / "auth"


def _key_cache_path() -> Path:
    return _studio_auth_root() / "agent_api_key.json"


def _read_cache(cache: Path) -> dict:
    try:
        data = json.loads(cache.read_text(encoding = "utf-8"))
    except Exception:
        return {}
    return data if isinstance(data, dict) else {}


def _server_buckets(servers: dict, base: str) -> dict:
    # Normalise a server's entry to {"saved": [...], "minted": [...]}, tolerating a corrupt or legacy value (a bare string or list is treated as minted, behind the handshake).
    entry = servers.get(base) if isinstance(servers, dict) else None
    if isinstance(entry, list):
        return {"saved": [], "minted": [k for k in entry if isinstance(k, str)]}
    if not isinstance(entry, dict):
        return {"saved": [], "minted": []}

    def _strs(name: str) -> list:
        value = entry.get(name)
        return [k for k in value if isinstance(k, str)] if isinstance(value, list) else []

    return {"saved": _strs("saved"), "minted": _strs("minted")}


def _cached_keys(cache: Path, base: str, source: str) -> list:
    # Keys are scoped per server. `source` splits user-supplied --api-key keys ("saved", trusted for that base) from auto-minted ones ("minted", replayed only after the identity check). Legacy unscoped caches are ignored.
    return _server_buckets(_read_cache(cache).get("servers", {}), base)[source]


def _write_private_json(path: Path, data: dict) -> None:
    # O_CREAT with 0o600 so a file holding an API key is never world-readable, even briefly (existing files keep whatever perms the user set).
    path.parent.mkdir(parents = True, exist_ok = True, mode = 0o700)
    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
    with os.fdopen(fd, "w") as handle:
        handle.write(json.dumps(data, indent = 2) + "\n")


def _write_private_text(path: Path, text: str) -> None:
    path.parent.mkdir(parents = True, exist_ok = True, mode = 0o700)
    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
    with os.fdopen(fd, "w", encoding = "utf-8") as handle:
        handle.write(text)


def _read_json_object(path: Path) -> Optional[dict]:
    # {} when missing, None when it cannot be parsed as an object, so the caller leaves a user-managed file untouched rather than clobbering it.
    if not path.exists():
        return {}
    try:
        data = json.loads(path.read_text(encoding = "utf-8"))
    except (ValueError, OSError):
        return None
    return data if isinstance(data, dict) else None


def _subdict(parent: dict, key: str) -> dict:
    child = parent.get(key)
    if not isinstance(child, dict):
        child = parent[key] = {}
    return child


def _remember_key(cache: Path, base: str, key: str, source: str) -> None:
    data = _read_cache(cache)
    servers = data.get("servers")
    if not isinstance(servers, dict):
        servers = data["servers"] = {}
    buckets = _server_buckets(servers, base)
    other = "minted" if source == "saved" else "saved"
    buckets[source] = ([key] + [k for k in buckets[source] if k != key])[:8]
    buckets[other] = [k for k in buckets[other] if k != key]  # a key has one provenance
    new_entry = {"saved": buckets["saved"], "minted": buckets["minted"]}
    if servers.get(base) == new_entry:
        return
    servers[base] = new_entry
    # Collapse legacy unscoped fields.
    data.pop("keys", None)
    data.pop("key", None)
    try:
        _write_private_json(cache, data)
    except OSError:
        pass  # worst case the next launch mints another key


def _loaded_models_response(
    base: str,
    key: str,
    timeout = 30,
) -> dict:
    """Raw listing of resident models, enough for startup and key checks; unlike /v1/models it skips
    disk and media discovery, which can outlast the deadline on a slow scan folder."""
    try:
        answer = _http_json("GET", f"{base}/api/inference/loaded-models", key, timeout = timeout)
        if isinstance(answer.get("data"), list):
            return answer
        # Older Studio returns 200 with error JSON for unknown /api paths; no data list means no route, not an empty one that hides a loaded model.
    except urllib.error.HTTPError as exc:
        if exc.code != 404:
            raise
    # Fall back, but never on an auth or server error; older Studios still answer /v1/models.
    return _http_json("GET", f"{base}/v1/models", key, timeout = timeout)


def _key_accepted(base: str, key: str) -> bool:
    # Only a genuine auth rejection (401/403) means "this key is bad, skip it and try the next cached key or mint a fresh one". A 5xx or a network blip is a server-side outage, not a bad key: fail with a clean message instead of silently discarding a working key and minting extras against a struggling server.
    try:
        _loaded_models_response(base, key)
        return True
    except urllib.error.HTTPError as exc:
        if exc.code in (401, 403):
            return False
        _fail(
            f"Unsloth server error while checking an API key ({exc.code}). "
            "The server may be starting up or unhealthy; try again shortly."
        )
    except (urllib.error.URLError, TimeoutError) as exc:
        _fail(
            "Couldn't reach the Unsloth server while checking an API key: "
            f"{getattr(exc, 'reason', None) or exc}"
        )


def _agent_api_key(
    base: str,
    explicit: Optional[str],
    *,
    auto_started: bool = False,
    minted_only: bool = False,
) -> str:
    cache = _key_cache_path()
    if explicit:
        if not auto_started or _key_accepted(base, explicit):
            _remember_key(cache, base, explicit, "saved")
            return explicit
        # The server was auto-started for this run, so an exported UNSLOTH_API_KEY meant for some other server must not fail the launch: the loopback mint path below is guaranteed to work. An explicit key the fresh server accepts is still honored above.

    # Replay a key the user saved for THIS EXACT server first (scoped per base, so it only goes back there, including a remote or SSH-tunnelled Unsloth whose secret the local handshake cannot match). Skip ones the server rejects.
    for key in [] if minted_only else _cached_keys(cache, base, "saved"):
        if _key_accepted(base, key):
            _remember_key(cache, base, key, "saved")
            return key

    # Beyond here we auto-mint or replay an auto-minted key. find_studio_server() trusts a base after only a health check, so both are limited to a loopback server we can cryptographically confirm is ours.
    if not is_loopback_url(base):
        _fail(
            f"No saved API key for {base} and automatic minting only runs against "
            "a local Unsloth. Create an API key in Unsloth → Settings → API and "
            "pass it with --api-key (it is remembered per server), or set "
            "UNSLOTH_API_KEY."
        )
    if not verify_studio_identity(base):
        _fail(
            f"Couldn't verify that {base} is your Unsloth (it may be running as a "
            "different OS user, or another process took the port). Create an API "
            "key in Unsloth → Settings → API and pass it with --api-key, or set "
            "UNSLOTH_API_KEY."
        )

    # Identity verified: replay a previously auto-minted key, else mint a new one.
    token = _studio_token()
    if token is None:
        _fail(
            "Couldn't authenticate with the Unsloth server automatically. Create "
            "an API key in Unsloth → Settings → API and pass it with --api-key, "
            "or set UNSLOTH_API_KEY."
        )
    # Older releases could mint for a managed account, which cannot see the owner's model.
    listed = _http_json(
        "GET", f"{base}/api/auth/api-keys", token, error = "Couldn't list API keys"
    ).get("api_keys", [])
    # A server reporting purposes only lets stamped keys reach saved Connections: re-mint unstamped ones.
    stamped = any("purpose" in entry for entry in listed)
    owned = {
        entry.get("key_prefix")
        for entry in listed
        if not stamped or entry.get("purpose") == "unsloth_start"
    }
    for key in _cached_keys(cache, base, "minted"):
        if key[len("sk-unsloth-") :][:8] in owned and _key_accepted(base, key):
            _remember_key(cache, base, key, "minted")
            return key

    key = _http_json(
        "POST",
        f"{base}/api/auth/api-keys",
        token,
        {"name": "Coding agents (unsloth start)"},
        error = "Couldn't create an API key",
    )["key"]
    _remember_key(cache, base, key, "minted")
    return key


def _loaded_models(base: str, key: str) -> list:
    try:
        return _loaded_models_response(base, key).get("data", [])
    except (urllib.error.HTTPError, urllib.error.URLError, TimeoutError) as exc:
        _fail_request(exc, "Couldn't list models")


def _model_loaded_state(base: str, key: str, model_id: object) -> Optional[bool]:
    """Return whether the model is loaded, or None if the listing is unavailable."""
    try:
        models = _loaded_models_response(base, key, timeout = 5).get("data", [])
    except Exception:
        return None
    return any(m.get("id") == model_id and m.get("loaded") is not False for m in models)


def _model_still_loaded(base: str, key: str, model_id: object) -> bool:
    return _model_loaded_state(base, key, model_id) is True


_HF_REPO_ID_SEGMENT_RE = re.compile(r"^[A-Za-z0-9._-]+$")


def _is_hub_model_id(value: object) -> bool:
    if not isinstance(value, str):
        return False
    text = value.strip()
    if "\\" in text:
        return False
    if text.startswith(("/", "./", "../", "~")):
        return False
    if len(text) >= 2 and text[1] == ":" and text[0].isalpha():
        return False
    # A hub id is exactly "namespace/name" over a restricted charset. Anything with extra path segments (a server-side relative path such as models/Llama/Foo.gguf on a remote Unsloth) is not a hub id and must not be casefold-matched against a differently cased path on a case-sensitive filesystem. This is host independent, unlike the existence probe below which cannot see a path that only exists on the server.
    parts = text.split("/")
    if len(parts) != 2:
        return False
    if any(part in ("", ".", "..") or not _HF_REPO_ID_SEGMENT_RE.match(part) for part in parts):
        return False
    try:
        if Path(os.path.expanduser(text)).exists():
            return False
    except OSError:
        return False
    return True


def _is_model_path(value: str) -> bool:
    """Mirrors core.inference.model_ids._looks_like_path: a repo id is exactly ``org/model``, and anything else with a separator, drive, prefix or .gguf is a path. Deliberately not named _looks_like_path: that name is taken further down by the WSLENV classifier, which only matches absolute paths and would shadow this one."""
    if value.lower().endswith(".gguf"):
        return True
    if value.startswith(("/", "\\", "./", "../", ".\\", "..\\", "~")):
        return True
    if len(value) >= 2 and value[1] == ":":
        return True
    return value.count("/") >= 2 or "\\" in value


def _public_model_id(value: Optional[str]) -> Optional[str]:
    """The id Unsloth advertises for a model loaded by path. The loaded listing never echoes a host path: it reports the file or directory name with any .gguf suffix stripped (core.inference.model_ids.public_model_id), so a path we asked to load has to be matched by that name too."""
    if not value or not _is_model_path(value):
        return None
    name = os.path.basename(value.replace("\\", "/").rstrip("/"))
    if name.lower().endswith(".gguf"):
        name = name[: -len(".gguf")]
    return name or None


def _public_model_ids(value: Optional[str]) -> set:
    """Return a path's basename ID and HF cache repo ID for old and current servers."""
    ids = {_public_model_id(value)} - {None}
    if ids:
        parts = value.replace("\\", "/").split("/")
        for index, part in enumerate(parts):
            if part.startswith("models--") and parts[index + 1 : index + 2] == ["snapshots"]:
                ids.add(part[len("models--") :].replace("--", "/"))
                break
    return ids


def _model_id_matches(
    actual: object,
    requested: object,
    *,
    allow_casefold: bool = True,
) -> bool:
    if actual == requested:
        return True
    # Case-insensitive matching is only safe when the local existence probe in _is_hub_model_id is authoritative, i.e. against a loopback Unsloth on this host. Against a remote Unsloth a two-segment string is indistinguishable from a server-side relative path (Models/Foo vs models/foo), so casefolding it could attach to the wrong model on a case-sensitive server; defer to an exact match there and let the load endpoint resolve the requested path.
    if not allow_casefold:
        return False
    if not (_is_hub_model_id(actual) and _is_hub_model_id(requested)):
        return False
    return str(actual).casefold() == str(requested).casefold()


def _inference_status(
    base: str,
    key: str,
    model_id: Optional[str] = None,
) -> dict:
    """Runtime state of the resident model. {} means "cannot prove anything" (older server), never "nothing is set"."""
    try:
        return _model_status(base, key, model_id)
    except Exception:
        return {}


_OTHER_ACCOUNT_RESIDENT = (
    "The model loaded in Unsloth belongs to another account, so this API key cannot use it. "
    "Pass --model <hf-id-or-path> to load one: the same model and quant shares it, anything "
    "else unloads it for every session using it."
)


def _resident_load_target(models: list, status: dict, allow_casefold: bool):
    """(identifier to post, id it is advertised as) for the running model. The loaded listing shows only the sanitized basename while _same_loaded_identifier compares resident paths exactly, so the load must carry the identifier status reports."""
    if status.get("is_diffusion"):
        # An image runtime answers with an active_model like any other, but it cannot serve chat: targeting it would tear down the diffusion server and then point the agent at a model that can never answer it.
        _fail(
            "Unsloth is serving an image model, which cannot serve chat, so there are no "
            "settings to apply. Re-run with --model naming the chat model to load."
        )
    active_id = status.get("active_model")
    entry = None
    if active_id:
        entry = next(
            (
                m
                for m in models
                if _model_id_matches(m.get("id"), active_id, allow_casefold = allow_casefold)
                and m.get("loaded") is not False
            ),
            None,
        )
    if entry is None and not status:
        # Only when there is no status at all (older server). A status that ANSWERED with active_model null is stating there is no chat resident. Listing ORDER is not evidence either: a loaded speech sidecar is listed like any other resident model, so the first entry can be one. Answer only when the catalog is unambiguous.
        loaded = [m for m in models if m.get("loaded") is not False]
        if len(loaded) == 1:
            entry = loaded[0]
        elif loaded:
            _fail(
                "This Unsloth cannot say which model is serving chat, and more than one is "
                "loaded. Re-run with --model naming the one these settings are for."
            )
    public_id = active_id or (entry or {}).get("id")
    if not public_id:
        if status.get("yours") is False:
            _fail(_OTHER_ACCOUNT_RESIDENT)
        if status:
            # Status answered and named no chat model. Returning empty here would drop the knobs silently, which is the bug this path exists to fix.
            _fail(
                "No chat model is currently loaded, so there are no settings to apply. "
                "Re-run with --model naming the model to load."
            )
        return None, None
    identifier = status.get("model_identifier")
    if identifier:
        return identifier, public_id
    # A native path lease redacts the internal path; inventing one from the basename would address the wrong file, so only a hub id can be posted back.
    if _is_hub_model_id(public_id):
        return public_id, public_id
    _fail(
        f"Unsloth is serving '{public_id}' from a local path it does not expose, so these "
        "settings cannot be applied by attaching. Re-run with --model naming that path."
    )


# /api/inference/status field to the /api/inference/load field that reproduces it. The "requested_" values are what the load was INVOKED with, which is what has to be resent; the bare names are the resolved ones and would pin a value the user never chose.
_RESIDENT_RUNTIME_FIELDS = {
    "cache_type_kv": "cache_type_kv",
    "chat_template_override": "chat_template_override",
    "disable_vision": "disable_vision",
    "gpu_memory_mode": "gpu_memory_mode",
    "gpu_layers": "gpu_layers",
    "n_cpu_moe": "n_cpu_moe",
    "tensor_split": "tensor_split",
    "tensor_parallel": "tensor_parallel",
    "speculative_type": "speculative_type",
    "spec_draft_n_max": "spec_draft_n_max",
    "requested_reasoning_budget": "reasoning_budget",
    "requested_reasoning_budget_message": "reasoning_budget_message",
    # The applied value is null when the runtime refused the request.
    # Scheme and width together; a bare width reads back as mx.quantize, so TurboQuant would reload as it. The width stays for servers without mlx_kv_quant.
    "mlx_kv_quant_requested": "mlx_kv_quant",
    "mlx_kv_bits_requested": "mlx_kv_bits",
    # LoadRequest defaults this to True, so omitting it would reload a full-precision model in 4-bit. Null on GGUF, which has no such setting.
    "load_in_4bit": "load_in_4bit",
    # Same trap: max_seq_length defaults to 0, which _gguf_request_intent copies into n_ctx, so changing another knob would reset a custom context to automatic.
    "requested_context_length": "max_seq_length",
    "requested_gpu_ids": "gpu_ids",
    "requested_parallel_slots": "n_parallel",
    "requested_n_batch": "n_batch",
    "requested_n_ubatch": "n_ubatch",
    "requested_load_mode": "load_mode",
    "requested_ctx_checkpoints": "ctx_checkpoints",
    "requested_cache_ram": "cache_ram",
    "requested_spec_draft_cache_type": "spec_draft_cache_type",
    "requested_llama_extra_args": "llama_extra_args",
}


def _resident_runtime_payload(status: dict, payload: dict) -> dict:
    """The resident's own settings for knobs this load did not name. None means "never set" for every one of these, so it is dropped rather than sent: omitting a field is what lets the server inherit, while sending null would pin the absence. An explicit empty list is kept, since that is a real "launch with none"."""
    if not status:
        return {}
    carried = {}
    for field, load_field in _RESIDENT_RUNTIME_FIELDS.items():
        if load_field in payload:
            continue
        value = status.get(field)
        if value is None:
            continue
        carried[load_field] = value
    offload = status.get("mlx_offload") or {}
    for part, load_field in (("ple", "mlx_ple_offload"), ("experts", "mlx_expert_offload")):
        requested = (offload.get(part) or {}).get("requested")
        if load_field not in payload and requested is not None:
            carried[load_field] = requested
    return carried


def _resident_variant(status: dict) -> Optional[str]:
    return status.get("gguf_variant") if status.get("is_gguf") or status.get("is_mlx") else None


def _resident_serves_variant(status: dict, wanted: Optional[str]) -> bool:
    resident = _resident_variant(status)
    if not resident:
        return False
    # Hub folder names are case-sensitive; llama.cpp quant labels are not.
    if status.get("is_mlx"):
        return str(resident).strip() == str(wanted).strip()
    return str(resident).strip().lower() == str(wanted).strip().lower()


def _load_settings_differ(status: dict, load: LoadOptions, overrides: frozenset) -> bool:
    """Whether applying these settings can restart the resident. Unproven equality counts as a difference: a silent restart is worse than a spurious warning."""
    if not status:
        return True
    # _runtime_matches_intent rejects an identical intent while a spec probe, a DFlash drafter or a changed speculative binary is waiting to be retried, so the server reloads regardless of what the CLI asked for. Equality of the overrides is then no proof of a no-op, and claiming one would skip the gate and the warning.
    if any(
        status.get(field)
        for field in (
            "spec_probe_retry_pending",
            "spec_dflash_retry_pending",
            "spec_fallback_binary_changed",
        )
    ):
        return True
    for name in overrides:
        if name == "gguf_variant":
            # Casefold, not _normalized_variant, which strips separators: a mistyped Q4KM would read as equal here yet still really reload on the server. The preload gate below already compares this way, and the two have to agree.
            if not _resident_serves_variant(status, load.gguf_variant):
                return True
        elif name == "max_seq_length":
            # Requested, not resolved: llama.cpp clamps n_ctx at fit time.
            resident = status.get("requested_context_length")
            if resident is None or int(resident) != int(load.max_seq_length):
                return True
        elif name == "load_in_4bit":
            # GGUF has no 4-bit setting and reports null, which would read as "differs" and warn about an unload the server is not going to perform.
            if status.get("is_gguf"):
                continue
            resident = status.get("load_in_4bit")
            if resident is None or bool(resident) != bool(load.load_in_4bit):
                return True
        elif name == "tensor_parallel":
            # llama.cpp only. The standard load never forwards it, so a restart would apply nothing.
            if not status.get("is_gguf"):
                continue
            # The architecture gate can normalize a tensor request to layer mode and say so, so asking for it AGAIN is the request already applied, not a difference, and the backend dedupes exactly this state. Asking to turn it OFF is the opposite: the backend keeps the tensor intent behind that fallback and does not read a bare false as an explicit drop (the UI sends false routinely), so only a real reload can clear it.
            if status.get("tensor_parallel_dropped_by_arch_gate"):
                if load.tensor_parallel:
                    continue
                return True
            if bool(status.get("tensor_parallel")) != bool(load.tensor_parallel):
                return True
        elif name == "gpu_memory_mode":
            if not status.get("is_gguf"):
                continue
            # A paravirtual host pins every placement request to the same runtime, and a CPU fallback is preserved across reloads by _preserve_cpu_fallback_intent, so in both cases the raw mode cannot tell two requests apart. resident-config-match.ts skips placement on exactly these two for the same reason.
            if status.get("gpu_placement_paravirtual") or status.get("cpu_fallback_reason"):
                continue
            if status.get("gpu_memory_mode") != load.gpu_memory_mode:
                return True
            # Manual to manual is a real no-op: the payload only sends the implicit gpu_layers = -1 when switching INTO manual, so a resident already pinned to a layer count keeps it through the round-trip and nothing changes.
    return False


def _resolve_model(
    base: str,
    key: str,
    requested: Optional[str],
    load: LoadOptions = LoadOptions(),
    preload_check = None,
    infer_resident: bool = True,
) -> dict:
    models = _loaded_models(base, key)
    load_requested = False
    # Only casefold-match ids against a loopback Unsloth, where _is_hub_model_id's local existence probe can actually reject a server-side path; see the note there.
    allow_casefold = is_loopback_url(base)
    # The loaded listing carries the active GGUF variant only while that quant reference still resolves, and never the runtime load settings, so an id match alone can hide the wrong quant (Q8_0 serving while the user asked for UD-Q4_K_XL). When the user passed any explicit load knob, defer to /api/inference/load: the server's already-loaded dedup answers "already_loaded" without reloading when the variant AND settings match, so a second session running the same command still attaches without evicting the first.
    overrides = load.overrides()
    load_has_overrides = bool(overrides)
    # Inferred-attach path only: `requested` becomes the resident's internal identifier (possibly a server path), so this is the id to show and to match on.
    attach_public_id = None
    status_snapshot = None
    # Whether the inferred settings can restart the resident. Computed once: the preload gate, the warning, the consent refusal and force_reload must all agree, and asking twice against a snapshot taken at different times is how they drift apart.
    inferred_differs = False
    same_checkpoint = True
    if requested is None and load_has_overrides and infer_resident:
        status_snapshot = _inference_status(base, key)
        requested, attach_public_id = _resident_load_target(models, status_snapshot, allow_casefold)
        inferred_differs = _load_settings_differ(status_snapshot, load, overrides)
        # preload_check deliberately survives: it is the only gate before the load evicts the shared model (_require_gguf_for_codex runs after _connect returns). An older server answers this listing from the full catalog, which also carries cached-but-unloaded entries (loaded == False); matching one would skip /api/inference/load and leave the agent pointed at a model that is not resident, so only attach to an entry that is actually loaded.
    loaded_match = next(
        (
            m
            for m in models
            if _model_id_matches(m.get("id"), requested, allow_casefold = allow_casefold)
            and m.get("loaded") is not False
        ),
        None,
    )
    match = None if requested and load_has_overrides else loaded_match
    if requested and match is None:
        load_requested = True
        if attach_public_id is None and loaded_match is not None:
            # A full load resets omitted settings, so read the named resident's own slot to carry them.
            status_snapshot = _inference_status(base, key, loaded_match["id"])
            # The listing shows a local checkpoint by basename, so ./foo matches a resident old/foo: inherit only from the checkpoint this load resolves to.
            wanted_path = os.path.abspath(os.path.expanduser(requested))
            # A snapshot naming another model (replaced since the listing, or a server ignoring ?model=) describes nothing of this one.
            same_checkpoint = _model_id_matches(
                status_snapshot.get("active_model"),
                loaded_match["id"],
                allow_casefold = allow_casefold,
            ) and (
                _is_hub_model_id(requested)
                or any(
                    os.path.abspath(os.path.expanduser(str(status_snapshot.get(field))))
                    == wanted_path
                    for field in ("model_identifier", "gguf_path", "model_path")
                    if status_snapshot.get(field)
                )
            )
        # Only here is an evicting load certain: the gate must not reject a request the resident model already satisfies (a path-loaded GGUF shown as a bare basename can collide with a non-GGUF unsloth/<name>).
        # A load of a model already served replaces it in its own slot, which may not be the primary.
        active = loaded_match or next((m for m in models if m.get("loaded") is not False), None)
        # On the inferred path the target came from status, so catalog order can name a different entry (a speech sidecar listed first). Using it would make the survivor probe below report the wrong model as still serving.
        if attach_public_id is not None:
            active = next(
                (
                    m
                    for m in models
                    if _model_id_matches(
                        m.get("id"), attach_public_id, allow_casefold = allow_casefold
                    )
                    and m.get("loaded") is not False
                ),
                None,
            ) or {"id": attach_public_id}
        if preload_check is not None:
            # An explicit knob forces match to None so the server's disk-free dedupe can answer already_loaded; gating it would reject a second session for the model already serving, whose file may have moved. Only the quant is checked below: any other run knob changes the runtime intent, a real reload nothing dedupes.
            other_overrides = bool(overrides - {"gguf_variant"})
            # Match public path IDs before deciding whether to rerun the gate.
            wanted_ids = {requested} | _public_model_ids(requested)
            resident_serves_request = not other_overrides and any(
                m.get("loaded") is not False
                and any(
                    _model_id_matches(m.get("id"), want, allow_casefold = allow_casefold)
                    for want in wanted_ids
                )
                for m in models
            )
            # A proven no-op evicts nothing, so the gate has nothing to protect, and running it would reject an attach the disk-free already-loaded path can still serve (a direct .gguf the server has mapped but that has since moved).
            if attach_public_id is not None and not inferred_differs:
                resident_serves_request = True
            # The loaded listing shows only the basename, so confirm a path request against the identifier the server loaded, else /new/foo.gguf reads as resident because /old/foo.gguf is.
            if resident_serves_request and _is_model_path(requested):
                try:
                    status = _model_status(base, key, requested)
                except Exception:
                    status = {}
                loaded_paths = {
                    str(status.get(field))
                    for field in ("model_identifier", "gguf_path", "model_path")
                    if status.get(field)
                }
                wanted_path = os.path.abspath(os.path.expanduser(requested))
                resident_serves_request = any(
                    os.path.abspath(os.path.expanduser(path)) == wanted_path
                    for path in loaded_paths
                )
            if resident_serves_request and load.gguf_variant:
                try:
                    status = _model_status(base, key, requested)
                except Exception:
                    status = {}
                # Casefold, not _normalized_variant, which strips separators: a mistyped Q4KM would skip the gate here yet still really reload on the server.
                resident_serves_request = _resident_serves_variant(status, load.gguf_variant)
            if not resident_serves_request:
                preload_check(base, key, requested, load.gguf_variant)
        active_id = active.get("id") if active else None
        announced_switch = False
        # Public IDs can collide and status hides paths: wait for the load result.
        switch_unknown = False
        if attach_public_id is not None:
            # An inferred attach never switches model, so the comparison below would misreport a switch and print the server's path.
            if inferred_differs:
                typer.echo(f"Applying new load settings to {attach_public_id}.")
                typer.echo("This unloads the current model for every attached session.")
                announced_switch = True
        elif active_id and not _model_id_matches(
            active_id,
            requested,
            allow_casefold = allow_casefold,
        ):
            if any(
                _model_id_matches(active_id, listed, allow_casefold = allow_casefold)
                for listed in _public_model_ids(requested)
            ):
                switch_unknown = True
            else:
                typer.echo(f"Switching the Unsloth server from {active_id} to {requested}.")
                typer.echo("This unloads the current model for every attached session.")
                announced_switch = True
        elif active_id and load.gguf_variant:
            # Same repo id but an explicit quant still replaces the resident weights; the loaded listing does not carry a variant for every resident model, so ask the status endpoint.
            try:
                status = _model_status(base, key, active_id)
            except Exception:
                status = {}
            resident = _resident_variant(status)
            switching = (
                not _resident_serves_variant(status, load.gguf_variant)
                if status.get("is_mlx")
                else _normalized_variant(resident) != _normalized_variant(load.gguf_variant)
            )
            if resident and switching:
                typer.echo(
                    f"Switching the Unsloth server from {active_id}:{resident} "
                    f"to {requested}:{load.gguf_variant}."
                )
                typer.echo("This unloads the current model for every attached session.")
                announced_switch = True
            elif loaded_match is not None and _load_settings_differ(status, load, overrides):
                typer.echo(f"Applying new load settings to {active_id}.")
                typer.echo("This unloads the current model for every attached session.")
                announced_switch = True
        elif active_id and loaded_match is not None:
            try:
                status = _model_status(base, key, active_id)
            except Exception:
                status = {}
            if _load_settings_differ(status, load, overrides):
                typer.echo(f"Applying new load settings to {active_id}.")
                typer.echo("This unloads the current model for every attached session.")
                announced_switch = True
        elif not active_id and _inference_status(base, key).get("yours") is False:
            typer.echo(
                "Switching the Unsloth server from another account's model to "
                f"{_display_model_spec(requested, load.gguf_variant)}."
            )
            typer.echo(
                "This unloads it for every attached session, unless it is the same model and quant."
            )
        # Mirror `unsloth run`'s load knobs; keep the default payload as just model_path so a bare `--model` load is unchanged. Membership decides, not truthiness: a reset like --context-length 0 equals the default yet must be sent.
        payload = {"model_path": requested}
        if "gguf_variant" in overrides and load.gguf_variant:
            direct_file = attach_public_id is not None and str(requested).lower().endswith(".gguf")
            if direct_file:
                # from_identifier consults a variant only for a DIRECTORY, so a DIFFERENT quant cannot be selected: posting one would reload the very same file and label it with a quant that does not describe its weights. Restating the one already running asks for no change, so drop the inapplicable field and let the other overrides through.
                resident_variant = status_snapshot.get("gguf_variant")
                same = (
                    bool(resident_variant)
                    and str(resident_variant).strip().lower()
                    == str(load.gguf_variant).strip().lower()
                )
                if not same:
                    _fail(
                        f"'{attach_public_id}' was loaded from a single .gguf file, so "
                        f"--gguf-variant {load.gguf_variant} cannot select a different quant. "
                        "Re-run with --model naming the repository to switch quants."
                    )
            else:
                payload["gguf_variant"] = load.gguf_variant
        elif attach_public_id is not None and (
            status_snapshot.get("is_gguf") or status_snapshot.get("is_mlx")
        ):
            # Re-send the running quant: a repo id carries none, so from_identifier would auto-pick (GGUF_QUANT_PREFERENCE, UD-Q4_K_XL first) and changing only the context would evict a chosen Q8_0 to download a different quant. Skip a .gguf path, which loads as itself; the server gates on the same suffix.
            resident_variant = status_snapshot.get("gguf_variant")
            if resident_variant and not str(requested).lower().endswith(".gguf"):
                payload["gguf_variant"] = resident_variant
        elif loaded_match is not None and not str(requested).lower().endswith(".gguf"):
            # Same for a named model already served, read from the slot serving it.
            if (
                status_snapshot.get("is_gguf") or status_snapshot.get("is_mlx")
            ) and status_snapshot.get("gguf_variant"):
                payload["gguf_variant"] = status_snapshot["gguf_variant"]
        if "max_seq_length" in overrides:
            payload["max_seq_length"] = load.max_seq_length
        if "load_in_4bit" in overrides:
            payload["load_in_4bit"] = load.load_in_4bit
        if "tensor_parallel" in overrides:
            payload["tensor_parallel"] = load.tensor_parallel
        if "gpu_memory_mode" in overrides and load.gpu_memory_mode is not None:
            payload["gpu_memory_mode"] = load.gpu_memory_mode
            # -1 means "pick the layers", which is right when the user is switching INTO manual, but on an inferred attach to a resident already in manual it would throw away the layer count it was pinned to. Leave it for the round-trip.
            already_manual = (
                same_checkpoint
                and bool(status_snapshot)
                and status_snapshot.get("gpu_memory_mode") == "manual"
            )
            if load.gpu_memory_mode == "manual" and not already_manual:
                payload["gpu_layers"] = -1
        if (
            attach_public_id is not None
            and inferred_differs
            and status_snapshot.get("requires_trust_remote_code")
        ):
            # The reload cannot reproduce the consent: the payload has no trust_remote_code and no approval fingerprint, and the standard backend tears the worker down BEFORE the replacement is accepted, so a rejected custom-code load leaves nothing resident. Refuse while the model is still serving; naming it with --model goes through the normal consent path.
            _fail(
                f"'{attach_public_id}' was loaded with trust_remote_code, which an attach "
                "cannot re-authorize. Re-run with --model naming it to apply these settings."
            )
        if attach_public_id is not None or loaded_match is not None:
            # A resident reload is a full load, not a PATCH: carry the knobs the user did not name, or changing the context alone drops their KV dtype, slot count, batch sizes and GPU placement.
            carried = _resident_runtime_payload(status_snapshot, payload)
            if attach_public_id is None:
                # Omitted extras are inherited server-side, shadow-stripped against the fields sent: a copied list would beat --context-length, and a carried field would strip an extra that won. So extras mean no carry.
                if not same_checkpoint or status_snapshot.get("requested_llama_extra_args"):
                    carried = {}
                carried.pop("llama_extra_args", None)
                # Outside manual, status reports the planner's emitted ratio, not the request (LlamaCppBackend.tensor_split); sending it pins an Auto split and reloads.
                if {**payload, **carried}.get("gpu_memory_mode") != "manual":
                    carried.pop("tensor_split", None)
                # Status cannot say whether the slot count was the default, and a sent count stops Auto cutting slots to keep a drafter (n_parallel_from_default).
                carried.pop("n_parallel", None)
            payload.update(carried)
            # The server cannot tell an explicit `--context-length 0` reset from the 0 that every UI load sends, so it treats 0 as "no preference" and would answer already_loaded. Say outright that this one is a reload, but only when status PROVED a difference: on an older server _load_settings_differ cannot tell, and forcing there would evict on every attach.
            if attach_public_id is not None and status_snapshot and inferred_differs:
                payload["force_reload"] = True
        try:
            loaded = _load_model_with_progress(base, key, requested, load, payload)
        except Exception:
            # The warning above promised an unload; if the server refused the load before evicting anything, say so. Not BaseException: Ctrl+C must stay immediate, without a probe or a survivor claim.
            if announced_switch and _model_still_loaded(base, key, active_id):
                typer.echo(f"Nothing was unloaded; {active_id} is still serving.", err = True)
            # Report an unannounced eviction only if the listing confirms it.
            if switch_unknown and _model_loaded_state(base, key, active_id) is False:
                typer.echo(f"{active_id} was unloaded for every attached session.", err = True)
            raise
        if loaded.get("status") == "already_loaded":
            # Show the public id on the inferred path; `requested` may be a server path.
            shown = attach_public_id or requested
            typer.echo(f"Reusing loaded model: {_display_model_spec(shown, load.gguf_variant)}")
        elif switch_unknown:
            typer.echo(f"Loaded {requested} in place of {active_id}.")
            typer.echo("This unloaded the previous model for every attached session.")
        # Match public IDs and load-response names, since the listing may omit paths; keep attach_public_id for inferred opaque IDs.
        wanted = ({requested, attach_public_id} - {None}) | _public_model_ids(requested)
        if isinstance(loaded, dict):
            wanted |= {loaded.get("model"), loaded.get("display_name")} - {None}
        models = _loaded_models(base, key)
        match = next(
            (
                m
                for m in models
                if m.get("loaded") is not False
                and any(
                    _model_id_matches(m.get("id"), w, allow_casefold = allow_casefold) for w in wanted
                )
            ),
            None,
        )
    if match is not None:
        if requested and not load_requested:
            typer.echo(f"Reusing loaded model: {_display_model_spec(requested, load.gguf_variant)}")
        return match
    if requested:
        # We asked Unsloth to load it and it did not surface as loaded; do not silently hand back an unrelated loaded model.
        _fail(
            f"Unsloth didn't report '{requested}' as loaded. Double-check the model "
            "id, or load it from the model dropdown in the UI."
        )
    loaded = [m for m in models if m.get("loaded") is not False]
    # A speech or separation model is listed like any resident but carries a task: it cannot chat.
    resident = next((m for m in loaded if m.get("task") is None), None)
    if resident is None:
        if loaded:
            _fail(
                f"Unsloth is serving only {loaded[0].get('id')}, a {loaded[0].get('task')} model "
                "that cannot serve chat. Load a chat model from the model dropdown in the UI, or "
                "pass --model <hf-id-or-path> to load one from here."
            )
        if _inference_status(base, key).get("yours") is False:
            _fail(_OTHER_ACCOUNT_RESIDENT)
        # Empty and unloaded-only listings mean the same; the server version decides which it sends.
        _fail(
            "No model is loaded in Unsloth. Load one from the model dropdown in "
            "the UI, or pass --model <hf-id-or-path> to load it from here."
        )
    return resident


_HF_OFFLINE_TRUE_VALUES = frozenset({"1", "true", "yes", "on"})


def _hf_offline() -> bool:
    return any(
        os.environ.get(var, "").strip().lower() in _HF_OFFLINE_TRUE_VALUES
        for var in ("HF_HUB_OFFLINE", "TRANSFORMERS_OFFLINE")
    )


def _hub_gguf_files(repo: str) -> Optional[list]:
    names = _hub_repo_files(repo)
    if names is None:
        return None
    ggufs = [n for n in names if n.lower().endswith(".gguf")]
    return [n for n in ggufs if not _is_auxiliary_gguf(n)]


def _hub_repo_files(repo: str) -> Optional[list]:
    if _hf_offline():
        return None
    endpoint = os.environ.get("HF_ENDPOINT", "https://huggingface.co").rstrip("/")
    try:
        request = urllib.request.Request(
            f"{endpoint}/api/models/{repo}",
            headers = {"User-Agent": _USER_AGENT},
        )
        with urllib.request.urlopen(request, timeout = 10) as response:
            info = json.loads(response.read().decode() or "{}")
    except Exception:
        return None
    siblings = info.get("siblings")
    if not isinstance(siblings, list) or not siblings:
        return None
    return [
        s["rfilename"]
        for s in siblings
        if isinstance(s, dict) and isinstance(s.get("rfilename"), str)
    ]


# Keep in sync with utils/gguf_names.py; the remote CLI cannot require backend imports.
_DRAFTER_KINDS = ("mtp", "dspark", "dflash", "eagle3", "lilicorr")
_DRAFTER_DIR_KINDS = ("mtp", "dspark")


def _is_auxiliary_gguf(filename: str) -> bool:
    # Mirrors detect_gguf_model_remote (hub.utils.gguf.is_mtp_drafter_path): projectors, separate-file drafters and big-endian builds are not loadable weights. Drafters match by basename prefix or exact parent dir, never substring, since the kind names double as family names and Qwen3.6-...-DFlash-Q4_K_M.gguf IS the model. Only the root-level trailing -be form is filtered; the fuller quant-aware check would over-reject here.
    p = filename.lower().replace("\\", "/")
    parts = [segment for segment in p.split("/") if segment]
    if not parts:
        return False
    name, parents = parts[-1], parts[:-1]
    if "mmproj" in p:
        return True
    if any(name.startswith(f"{kind}-") for kind in _DRAFTER_KINDS):
        return True
    if any(kind in parents for kind in _DRAFTER_DIR_KINDS):
        return True
    stem = name.rsplit(".", 1)[0]
    return not parents and stem.endswith(("-be", "_be"))


def _direct_gguf_is_companion(path: str) -> bool:
    """Whether the server refuses this .gguf path as a model in its own right. A strict subset of detect_gguf_model / gguf_variants._direct_gguf_loads: projector and drafter prefixes read off the basename, companion-only folders off the immediate parent, the same context the server reads, so nothing loadable is refused here. Big-endian is left out on purpose: that check needs quant context the CLI cannot mirror."""
    parts = [segment for segment in path.replace("\\", "/").split("/") if segment]
    if not parts:
        return False
    name = parts[-1].lower()
    if not name.endswith(".gguf"):
        return False
    # Root-independent refusals only: name prefixes read the basename alone, so they mean the same under any model root. A drafter FOLDER does not.
    if "mmproj" in name:
        return True
    return any(name.startswith(f"{kind}-") for kind in _DRAFTER_KINDS)


def _path_syntax_is_native(path: str) -> bool:
    """Whether *path* is spelled the way this OS spells paths. A Windows path read from WSL, or a POSIX one read from Windows, parses into something this process cannot judge (``C:\\models\\m.gguf`` has parent ``.`` here), so its absence locally says nothing about the server's disk."""
    windows_drive = len(path) >= 2 and path[1] == ":" and path[0].isalpha()
    if os.name == "nt":
        return True
    return not windows_drive and "\\" not in path


def _direct_gguf_companion_is_uncertain(path: str) -> bool:
    """Whether only the server can say if this path is a companion. detect_gguf_model reads drafter folders relative to the registered model root, so ``/models/MTP/foo-Q8_0.gguf`` is refused or loaded depending on where that root sits, a question only the server can answer since this process does not know its roots."""
    parts = [segment for segment in path.replace("\\", "/").split("/") if segment]
    return any(segment.lower() in _DRAFTER_DIR_KINDS for segment in parts[:-1])


# Mirrors model_config._extract_quant_label's pattern; change in lockstep.
_QUANT_LABEL_RE = re.compile(
    r"(UD-)?"
    r"(MXFP[0-9]+(?:_[A-Z0-9]+)*"
    r"|IQ[0-9]+_[A-Z]+(?:_[A-Z0-9]+)?"
    r"|P?TQ[0-9]+_[0-9]+"
    r"|Q[0-9]+_K_[A-Z]+"
    r"|P?Q[0-9]+_(?:[0-9]+(?:_G[0-9]+)?|G[0-9]+)"
    r"|Q[0-9]+_K"
    r"|BF16|F16|F32)"
    r"(-[0-9]+(?:\.[0-9]+)?bpw)?",
    re.IGNORECASE,
)


def _direct_gguf_variant_labels(path: str) -> tuple:
    """The labels the server's direct-file resolver accepts for *path*. Mirrors _direct_gguf_for_variant: the quant label read from the basename first, the immediate parent only when the basename carries none, plus the shard-stripped stem itself. The basename wins the disagreement: a Q8_0/foo-Q4_K_M.gguf answers Q4_K_M, so its parent must not vouch for Q8_0 here while the load resolves nothing and evicts."""
    norm = path.replace("\\", "/").rstrip("/")
    name = norm.rsplit("/", 1)[-1]
    stem = re.sub(r"-\d{3,}-of-\d{3,}$", "", name.rsplit(".", 1)[0])
    match = _QUANT_LABEL_RE.search(stem)
    if match is None and "/" in norm:
        match = _QUANT_LABEL_RE.search(norm.rsplit("/", 2)[-2])
    labels = [stem]
    if match is not None:
        label = f"{match.group(1) or ''}{match.group(2)}{match.group(3) or ''}"
        labels.append(label)
        # The resolver also accepts the hub-style bpw-stripped spelling.
        stripped = re.sub(r"-[0-9]+(?:\.[0-9]+)?bpw$", "", label, flags = re.IGNORECASE)
        if stripped != label:
            labels.append(stripped)
    else:
        # The extractor's own fallback: the last hyphen-separated segment.
        labels.append(stem.split("-")[-1])
    return tuple(labels)


# Mirrors hub.utils.gguf._BIG_ENDIAN_GGUF_FILENAME_RE; change in lockstep.
_BIG_ENDIAN_FILENAME_RE = re.compile(r"(^|[-_])be(?:[._-]|$)", re.IGNORECASE)


def _direct_gguf_is_big_endian(path: str) -> bool:
    """Mirrors hub.utils.gguf.is_big_endian_gguf_path over the same one-parent context detect_gguf_model reads; change in lockstep. A quant-named parent exempts a bare -be basename (that file loads); a be marker at or after a basename quant does not."""
    norm = path.replace("\\", "/").rstrip("/")
    parts = [segment for segment in norm.split("/") if segment]
    name = parts[-1]
    stem = name.rsplit(".", 1)[0].lower()
    quant_stem = re.sub(r"-\d{3,}-of-\d{3,}$", "", stem)
    match = _QUANT_LABEL_RE.search(quant_stem)
    parent = parts[-2].lower() if len(parts) > 1 else ""
    if match is None and parent:
        match = _QUANT_LABEL_RE.search(parent)
    quant_key = (
        f"{match.group(1) or ''}{match.group(2)}{match.group(3) or ''}".lower()
        if match is not None
        else quant_stem.split("-")[-1]
    )
    quant_index = stem.find(quant_key) if quant_key else -1
    quant_in_parent_only = (
        bool(parent)
        and quant_index < 0
        and (
            (quant_key and quant_key in parent)
            or (not quant_key and _QUANT_LABEL_RE.search(parent))
        )
    )
    for be in _BIG_ENDIAN_FILENAME_RE.finditer(stem):
        if quant_index >= 0 and quant_index < be.start():
            return True
        tail = stem[be.end() :].lstrip("._-")
        if not tail or _QUANT_LABEL_RE.search(tail) is None:
            return not quant_in_parent_only
    return False


# Mirrors gguf_variants._DIRECT_SPLIT_RE / the load path's _GGUF_SPLIT_FILE_RE; change in lockstep. Five digits exactly: a shorter -001-of-002 name loads as an ordinary file.
_DIRECT_SPLIT_FILE_RE = re.compile(
    r"^(?P<stem>.+)-(?P<index>\d{5})-of-(?P<total>\d{5})$", re.IGNORECASE
)


def _direct_gguf_file_is_ready(path: str) -> bool:
    """Whether a CLI-visible direct .gguf file can actually serve a load. Mirrors the backend's completeness rules: zero bytes is an interrupted copy, and a split needs every sibling index present and non-empty. Unknowable reports ready, so a path this process cannot judge never blocks the load."""

    def _split_set_complete(candidate: Path) -> Optional[bool]:
        match = _DIRECT_SPLIT_FILE_RE.match(candidate.name.rsplit(".", 1)[0])
        if match is None:
            return None
        total = int(match.group("total"))
        if total < 2:
            return None
        sibling = re.compile(
            re.escape(match.group("stem"))
            + r"-(\d{"
            + str(len(match.group("index")))
            + r"})-of-"
            + re.escape(match.group("total"))
            + r"\.gguf$",
            re.IGNORECASE,
        )
        found = {
            int(m.group(1))
            for q in candidate.parent.iterdir()
            if (m := sibling.match(q.name)) and q.is_file() and q.stat().st_size > 0
        }
        return found >= set(range(1, total + 1))

    try:
        p = Path(os.path.expanduser(path))
        # A broken symlink is visible here, and the .gguf suffix alone still makes it a load, which fails after teardown.
        if p.is_symlink() and not p.exists():
            return False
        if not p.is_file():
            return True
        if p.stat().st_size == 0:
            return False
        whole = _split_set_complete(p)
        if whole is not False:
            return True
        # Mirror _local_gguf_load_path: an incomplete nominal set still loads when the shard is a symlink whose target sits with the full set.
        if p.is_symlink():
            target = p.resolve()
            return _split_set_complete(target) is not False
        return False
    except OSError:
        return True


def _answer_offers_variant(
    variants: list,
    variant: str,
    strict: bool = False,
) -> bool:
    """Whether a live variants answer can resolve *variant* to a file. Mirrors llama.cpp's resolution, case-insensitively: quant label first, then the whole-token filename fallback, which is as loose as it gets since a separator-differing label resolves to nothing there either. A row missing both fields cannot be disproven, so it vouches. ``strict`` drops the filename-token tier: the LOCAL resolver takes only exact labels, so a local answer must not vouch for a shorter token (Q4 inside model-Q4_K_M.gguf) the load would never resolve."""
    wanted = str(variant).strip().lower()
    if not wanted:
        return True
    token = re.compile(r"(?<![a-z0-9])" + re.escape(wanted) + r"(?![a-z0-9])")
    for row in variants:
        if not isinstance(row, dict):
            return True
        # A torn local row cannot vouch in strict mode; hub partials stay resumable.
        if strict and row.get("partial") is True:
            continue
        quant = row.get("quant")
        filename = row.get("filename")
        if not isinstance(quant, str) and not isinstance(filename, str):
            return True
        if isinstance(quant, str):
            label = quant.strip().lower()
            # The resolver also accepts the hub-style bpw-stripped spelling.
            if wanted in (label, re.sub(r"-[0-9]+(?:\.[0-9]+)?bpw$", "", label)):
                return True
        if isinstance(filename, str):
            # Local resolver also takes the exact shard-stripped stem, full relative spelling only, never a nested file's bare basename.
            stem = re.sub(r"-\d{3,}-of-\d{3,}$", "", filename.rsplit(".", 1)[0]).lower()
            if wanted == stem:
                return True
            # Any whole quant token of the basename (F16-checkpoint-Q4_K_M -> Q4_K_M).
            if any(
                wanted
                in (
                    f"{m.group(1) or ''}{m.group(2)}".lower(),
                    # Keeps the bpw modifier the hub extractor drops, so both spellings match.
                    f"{m.group(1) or ''}{m.group(2)}{m.group(3) or ''}".lower(),
                )
                for m in _QUANT_LABEL_RE.finditer(stem.rsplit("/", 1)[-1])
            ):
                return True
        if strict:
            if not isinstance(quant, str):
                return True
            continue
        if isinstance(filename, str) and token.search(filename.lower()):
            return True
    return False


class _GgufAgent(NamedTuple):
    label: str
    command: str


_CODEX_GGUF_AGENT = _GgufAgent("Codex", "codex")
_CLAUDE_GGUF_AGENT = _GgufAgent("Claude Code", "claude")


def _fail_gguf_variant_missing(model_id: str, variant: str, variants: list) -> NoReturn:
    offered = [
        row.get("quant")
        for row in variants
        if isinstance(row, dict) and isinstance(row.get("quant"), str) and row.get("quant")
    ]
    message = f"{model_id} has no GGUF variant {variant}."
    if offered:
        message += " Available: " + ", ".join(dict.fromkeys(offered))
    _fail(message)


def _refuse_npu_model(model: Optional[str]) -> None:
    from unsloth_cli._npu import npu_model_path
    npu_path = npu_model_path(model)
    if npu_path:
        model_id = npu_path.split(":", 1)[1]
        # Unchecked, `lemonade:<id>` was split into a GGUF lookup for a repo named "lemonade".
        _fail(
            f"{model_id} is an AMD NPU model. `unsloth start` runs coding agents on GGUF models; "
            f"chat with {model_id} in Unsloth Studio or with `unsloth chat {model_id}`."
        )


def _fail_agent_needs_gguf(agent: _GgufAgent, model_id: str) -> NoReturn:
    message = (
        f"{agent.label} needs a GGUF model served by llama-server, " f"but {model_id} is not one."
    )
    guess = f"{model_id}-GGUF"
    if "gguf" not in model_id.lower() and _is_hub_model_id(guess) and _hub_gguf_files(guess):
        message += f" Try: unsloth start {agent.command} --model {guess}"
    _fail(message)


# Mirrors the frontend's NO_MLX_REASONS: an Apple Silicon host that still cannot load MLX.
_NO_MLX_REASONS = frozenset(
    {"mlx_unavailable", "no_torch", "intel_mac", "rosetta", "detection_failed"}
)

# Mirrors the backend's PRECISION_FOLDER_SOURCE: an MLX precision subfolder (6-bit/), not a GGUF quant.
_MLX_PRECISION_FOLDER_RE = re.compile(
    "(?:mlx[-_]?)?(?:[0-9]{1,2}[-_]?bits?(?:[-_][a-z0-9]+)*"
    "|bf16|fp16|f16|fp32|f32|fp8|mxfp4|nvfp4)",
    re.IGNORECASE,
)


def _asks_gguf_quant(variant: Optional[str]) -> bool:
    return bool(variant) and not _MLX_PRECISION_FOLDER_RE.fullmatch(str(variant).strip())


def _this_host_loads_mlx() -> bool:
    import platform
    return sys.platform == "darwin" and platform.machine() == "arm64"


def _server_loads_mlx(base: str, key: str) -> bool:
    deadline = time.monotonic() + 30
    while True:
        try:
            health = _http_json("GET", f"{base}/api/health?detect_hardware=true", key, timeout = 30)
        except Exception:
            return False
        if not (isinstance(health, dict) and health.get("hardware_detecting")):
            break
        if time.monotonic() >= deadline:
            return False
        time.sleep(1)
    return (
        isinstance(health, dict)
        and health.get("device_type") == "mac"
        and health.get("apple_silicon") is True
        and health.get("chat_only_reason") not in _NO_MLX_REASONS
    )


def _refuse_non_gguf(
    agent: _GgufAgent, model_id: str, base: str, key: str, variant: Optional[str]
) -> None:
    # A requested quant or a .gguf file asks for GGUF, which an MLX load would silently drop.
    if variant or model_id.lower().endswith(".gguf") or not _server_loads_mlx(base, key):
        _fail_agent_needs_gguf(agent, model_id)


def _preflight_agent_gguf(
    agent: _GgufAgent,
    model: Optional[str],
    *,
    serve: bool = True,
    launch: bool = True,
    gguf_variant: Optional[str] = None,
) -> None:
    # Hub-listing preflight for the auto-start path only: with a server running, identifiers
    # resolve against its cwd/cache/token, so _attach_gguf_check asks the server instead.
    # Only a complete listing with no .gguf files rejects; unknown defers to the
    # post-connect check. Mirrors _require_studio's auto-start condition, so with no start
    # possible its "no running server" error comes first, without a hub probe.
    _refuse_npu_model(model)
    if not (serve and launch and model):
        return
    expected = os.environ.get("UNSLOTH_STUDIO_URL", "http://127.0.0.1:8888").rstrip("/")
    if not is_loopback_url(expected) or urlparse(expected).scheme != "http":
        return
    if find_studio_server() is not None:
        return
    repo, inline_variant = _split_repo_variant(model)
    # A bare foo.gguf naming no local file is a shorthand, canonicalized like any owner-less name.
    if "/" not in repo and (not _is_model_path(repo) or repo.lower().endswith(".gguf")):
        # The server canonicalizes owner-less shorthands to unsloth/<name>.
        try:
            if Path(os.path.expanduser(repo)).exists():
                return
        except OSError:
            return
        repo = f"unsloth/{repo}"
    if not _is_hub_model_id(repo):
        return
    files = _hub_gguf_files(repo)
    variant = gguf_variant or inline_variant
    asks_gguf = _asks_gguf_quant(variant) or repo.lower().endswith(".gguf")
    if files is not None and not files and (asks_gguf or not _this_host_loads_mlx()):
        _fail_agent_needs_gguf(agent, repo)
    if files is not None and not files and variant:
        names = _hub_repo_files(repo)
        if names is not None and f"{variant.strip()}/config.json" not in names:
            _fail(f"{repo} has no precision folder {variant}.")


def _attach_gguf_check(
    agent: _GgufAgent,
    base: str,
    key: str,
    model: Optional[str],
    variant: Optional[str] = None,
) -> None:
    # Ask the server before the load evicts the resident model: only a live empty list is definitive; any error, older servers included, defers.
    if not model:
        return
    repo, inline_variant = _split_repo_variant(model)
    # `--model repo:QUANT` is split before the gate runs, so the caller passes the quant on.
    variant = variant or inline_variant
    # A .gguf filesystem path is GGUF by definition; only the hub-id shape owner/name.gguf is probed.
    bare_missing_gguf = False
    if repo.lower().endswith(".gguf") and not _is_model_path(repo.rsplit(".", 1)[0]):
        try:
            bare_missing_gguf = not Path(os.path.expanduser(repo)).exists()
        except OSError:
            bare_missing_gguf = False
    if (
        repo.lower().endswith(".gguf")
        and not bare_missing_gguf
        and not (
            repo.count("/") == 1
            and not repo.startswith(("/", ".", "~"))
            and ":" not in repo
            and "\\" not in repo
        )
    ):
        # Refuse companion or big-endian builds by name: otherwise load falls to transformers and unloads llama-server before failing.
        refused = _direct_gguf_is_companion(repo) or _direct_gguf_is_big_endian(repo)
        if refused:
            _fail_agent_needs_gguf(agent, repo)
        # A drafter folder further up is the server's call.
        uncertain = _direct_gguf_companion_is_uncertain(repo)
        # A direct file loads as itself; a matching sibling is never substituted.
        if not refused and not uncertain:
            # Only when this machine shares the server's filesystem, confirmed by identity (loopback may be an SSH or container forward), else defer.
            # Otherwise an incomplete file loads and llama-server finds bytes missing only after teardown.
            if is_loopback_url(base) and verify_studio_identity(base):
                # A .gguf-NAMED DIRECTORY is scanned, not loaded, so the suffix proves nothing.
                try:
                    is_gguf_dir = Path(os.path.expanduser(repo)).is_dir()
                except OSError:
                    is_gguf_dir = False
                if not is_gguf_dir:
                    # On loopback this reads the server's filesystem: a name missing from a listable dir is missing for the load too; unreadable parent defers.
                    try:
                        probe = Path(os.path.expanduser(repo))
                        missing = (
                            # A Windows path seen from WSL parses to nonsense, so defer.
                            _path_syntax_is_native(repo)
                            and not probe.is_symlink()
                            and probe.parent.is_dir()
                            and not probe.exists()
                        )
                    except OSError:
                        missing = False
                    if missing:
                        _fail(
                            f"{repo} does not exist. Check the path before "
                            f"pointing {agent.label} at it."
                        )
                    if not _direct_gguf_file_is_ready(repo):
                        _fail(
                            f"{repo} is incomplete (zero bytes or a split missing shards); "
                            f"re-download or re-copy it before pointing {agent.label} at it."
                        )
                    # Settle here only a spelling this OS can judge: a WSL-read Windows path would vouch for an unchecked file; explicit variant goes to probe.
                    if not variant and _path_syntax_is_native(repo):
                        return
            # Do not read a remote server's filesystem; the load treats the .gguf suffix as authoritative, so ask the server. Errors still defer.
    # Check the raw name first, as the load does; fall back to unsloth/<name> only when the raw name errors.
    # A live answer settles the raw id; otherwise a non-GGUF directory in the server's cwd would pass the gate and evict.
    candidates = [repo]
    if "/" not in repo and (not _is_model_path(repo) or bare_missing_gguf):
        candidates.append(f"unsloth/{repo}")
    for candidate in candidates:
        try:
            info = _http_json(
                "GET", f"{base}/api/models/gguf-variants?{urlencode({'repo_id': candidate})}", key
            )
        except Exception:
            continue
        variants = info.get("variants") if isinstance(info, dict) else None
        if isinstance(variants, list):
            # A cleanable row is an empty leftover <quant>/ folder, never weights.
            variants = [
                row for row in variants if not (isinstance(row, dict) and row.get("cleanable"))
            ]
        # Non-local raw answers settle nothing; a server lacking the flag still counts its raw answer.
        if (
            "/" not in candidate
            and candidate != candidates[-1]
            and isinstance(info, dict)
            and "resolved_locally" in info
            and not info["resolved_locally"]
        ):
            continue
        # Server answer from the load resolver settles the round, even empty: a root-blind lister can miss a file the load still finds.
        # MLX precision folders download on load, so the downloaded-only allow-list does not apply.
        if (
            isinstance(variants, list)
            and isinstance(info, dict)
            and info.get("variant_format") == "mlx"
        ):
            folders = {row.get("quant") for row in variants if isinstance(row, dict)}
            if variant and variant.strip() not in folders:
                _fail_gguf_variant_missing(candidate, variant, variants)
            _refuse_non_gguf(agent, candidate, base, key, None)
            return
        if isinstance(variants, list) and isinstance(info, dict):
            offered = info.get("loadable_variants")
            # No allow-list means a direct file, which loads as itself whatever the quant, so the variantless verdict decides.
            if variant and offered is None and isinstance(info.get("loadable"), bool):
                if not info["loadable"]:
                    _fail_agent_needs_gguf(agent, candidate)
                return
            if variant and isinstance(offered, list):
                wanted_variant = str(variant).strip().lower()
                if not any(
                    isinstance(q, str) and q.strip().lower() == wanted_variant for q in offered
                ):
                    _fail_gguf_variant_missing(candidate, variant, variants)
                return
            if not variant and isinstance(info.get("loadable"), bool):
                if not info["loadable"]:
                    if variants:
                        _fail_agent_needs_gguf(agent, candidate)
                    _refuse_non_gguf(agent, candidate, base, key, variant)
                return
        if isinstance(variants, list) and variants:
            # llama.cpp kills the resident model before resolving the quant, so settle it here; local answers take exact labels only.
            # owner/name.gguf is exempt like a direct file, since a remote answer judged local would face local-only rules.
            hub_shaped = (
                candidate.count("/") == 1
                and not candidate.startswith(("/", ".", "~"))
                and ":" not in candidate
                and "\\" not in candidate
            )
            local_answer = bool(info.get("resolved_locally")) or (
                not hub_shaped and (_is_model_path(candidate) or "/" not in candidate)
            )
            # Only torn local rows: llama-server would fail after teardown.
            if local_answer and all(
                isinstance(row, dict) and row.get("partial") is True for row in variants
            ):
                _fail(
                    f"{candidate} has only incomplete GGUF weights on the server; "
                    f"finish or re-copy the download before pointing {agent.label} at it."
                )
            # Variantless local load reads only the top level, so subdirectory-only rows need the variant; else it evicts for a load finding nothing.
            if (
                local_answer
                and not variant
                and variants
                and all(
                    isinstance(row, dict)
                    and isinstance(row.get("filename"), str)
                    and "/" in row["filename"]
                    for row in variants
                )
            ):
                offered = ", ".join(
                    dict.fromkeys(
                        row["quant"]
                        for row in variants
                        if isinstance(row.get("quant"), str) and row["quant"]
                    )
                )
                _fail(
                    f"{candidate} keeps its GGUF weights in quant subdirectories, which a "
                    "variantless load cannot pick. Pass --gguf-variant"
                    + (f" (available: {offered})." if offered else ".")
                )
            if variant and not _answer_offers_variant(variants, variant, strict = local_answer):
                _fail_gguf_variant_missing(candidate, variant, variants)
            return
        if isinstance(variants, list):
            # Explicit local syntax resolves locally on every server version, so its live empty answer settles the load; deferring would let the same GGUF-less directory go down the transformers path and evict. Only marker-less names keep deferring: older servers read them as hub ids, and a local hit may be a server-side model from the server's cwd, unless it reports resolved_locally. A bare foo.gguf naming no local file is only the canonicalized spelling, so it settles nothing until the canonical form has answered too.
            if bare_missing_gguf and candidate != candidates[-1]:
                continue
            if not _is_model_path(repo) and not info.get("resolved_locally"):
                try:
                    if Path(os.path.expanduser(repo)).exists():
                        return
                except OSError:
                    return
            _refuse_non_gguf(agent, candidate, base, key, variant)
            return


def _require_gguf_for_agent(agent: _GgufAgent, base: str, key: str, model_id: str) -> None:
    # Only a definite "no" rejects: the callers wrap this in `except BaseException: _shutdown_auto_served()`, so guessing kills a server that may have just loaded a GGUF.
    try:
        status = _model_status(base, key, model_id)
    except urllib.error.HTTPError:
        # Not evidence: get_status 500s from its own probes with a GGUF resident.
        return
    except (OSError, ValueError, http.client.HTTPException):
        # Named explicitly, not `except Exception`, so typer.Exit and real bugs still surface.
        return
    if not isinstance(status, dict):
        return
    is_gguf = status.get("is_gguf")
    # InferenceStatusResponse declares is_gguf non-optional under a response_model, so a current server always sends it. Absent means "not that endpoint", never "non-GGUF".
    if is_gguf is None or is_gguf or status.get("is_mlx"):
        return
    # is_gguf carries a False default, so an idle server answers False while naming no model. The request that follows gets the server's own "No GGUF model loaded" anyway.
    if not (status.get("active_model") or status.get("model_identifier")):
        return
    _fail_agent_needs_gguf(agent, model_id)


_DYNAMIC_SECTIONS_FLAG = "--exclude-dynamic-system-prompt-sections"


def _claude_settings_overlay(
    model_id: str,
    local_env: Optional[dict] = None,
    user: Optional[dict] = None,
) -> str:
    # Command-tier pins beat user/project settings, which Claude applies after the process env.
    settings_env = {name: "" for name in _CLAUDE_ENV_UNSET}
    settings_env.update(local_env or {})
    settings_env.update(
        {
            "CLAUDE_CODE_ATTRIBUTION_HEADER": "0",
            "CLAUDE_CODE_SUBAGENT_MODEL": "inherit",
        }
    )
    return json.dumps(
        {
            **(user or {}),
            "env": {**(user or {}).get("env", {}), **settings_env},
            "availableModels": [model_id],
            # A user's apiKeyHelper would still run and send its cloud key to Unsloth as x-api-key.
            "apiKeyHelper": "",
        }
    )


def _forwarded_claude_settings(args: list) -> tuple:
    """(the forwarded --settings merged, args without them), or (None, args) when one is unreadable."""
    separator = args.index("--") if "--" in args else len(args)
    merged, remaining, index = {}, [], 0
    while index < separator:
        arg = args[index]
        if arg == "--settings" and index + 1 < separator:
            value, index = args[index + 1], index + 2
        elif arg.startswith("--settings="):
            value, index = arg.split("=", 1)[1], index + 1
        else:
            remaining.append(arg)
            index += 1
            continue
        try:
            text = (
                value
                if value.lstrip().startswith("{")
                else Path(value).expanduser().read_text(encoding = "utf-8")
            )
            loaded = json.loads(text)
        except (OSError, ValueError):
            return None, args
        if not isinstance(loaded, dict) or not isinstance(loaded.get("env", {}), dict):
            return None, args
        merged = {**merged, **loaded, "env": {**merged.get("env", {}), **loaded.get("env", {})}}
    return merged, remaining + args[separator:]


def _write_claude_settings(
    path: Path,
    model_id: str,
    local_env: dict,
    user: Optional[dict] = None,
) -> Path:
    overlay = _claude_settings_overlay(model_id, local_env, user)
    digest = hashlib.sha256(overlay.encode("utf-8")).hexdigest()[:16]
    settings = path / f"settings-{digest}.json"
    _write_private_text(settings, overlay)
    return settings


def _claude_version() -> Optional[tuple]:
    # None means no local `claude` (a --no-launch printout for another machine; assume a current build). An unparseable version is treated as too old for the new flags.
    executable = _which_with_install_dirs("claude")
    if executable is None:
        return None
    try:
        result = subprocess.run(
            [executable, "--version"],
            capture_output = True,
            text = True,
            encoding = "utf-8",
            errors = "replace",
            timeout = 10,
            env = _probe_env(),
        )
        # Pull the X.Y.Z out of the output rather than assuming it is the first token: claude prints it first today ("2.1.98 (Claude Code)"), but a format change should not silently drop the optimization flags. No match falls through to "too old", same as an unparseable version.
        match = re.search(r"(\d+)\.(\d+)\.(\d+)", result.stdout)
        return tuple(int(part) for part in match.groups()) if match else (0,)
    except Exception:
        return (0,)


def _claude_flags(model_id: str, settings: Optional[str] = None) -> list:
    # KV-cache-preserving flags: move per-session context out of the system prompt and pass the session overlay. claude < 2.1.98 rejects the dynamic-sections flag but already supports --settings; no local binary means a printout for another machine, so assume a current build.
    version = _claude_version()
    settings_flags = ["--settings", settings or _claude_settings_overlay(model_id)]
    if version is not None and version < (2, 1, 98):
        return settings_flags
    return [_DYNAMIC_SECTIONS_FLAG, *settings_flags]


def _claude_local_command(model_id: str, settings: str, yolo: bool, passthrough: list) -> list:
    local_args = [
        "--model",
        model_id,
        *_claude_flags(model_id, settings),
        *_yolo_command_flags("claude", yolo),
    ]
    forwarded = list(passthrough)
    separator = forwarded.index("--") if "--" in forwarded else len(forwarded)
    before_separator = forwarded[:separator]
    forwarded_settings = []
    remaining = []
    index = 0
    while index < len(before_separator):
        arg = before_separator[index]
        if arg == "--settings" and index + 1 < len(before_separator):
            forwarded_settings.extend(before_separator[index : index + 2])
            index += 2
            continue
        if arg.startswith("--settings="):
            forwarded_settings.append(arg)
        else:
            remaining.append(arg)
        index += 1
    return [
        "claude",
        *forwarded_settings,
        *local_args,
        *remaining,
        *forwarded[separator:],
    ]


def _claude_local_env(
    base: str,
    key: str,
    entry: dict,
    extra_body: Optional[dict] = None,
) -> dict:
    """Build the local endpoint, cache, display, and compaction environment."""
    model_id = entry["id"]
    env = {
        "ANTHROPIC_BASE_URL": base,
        "ANTHROPIC_AUTH_TOKEN": key,
        "ANTHROPIC_MODEL": model_id,
        "CLAUDE_CODE_ATTRIBUTION_HEADER": "0",
        # Per-tool countdown reminders change the system prefix on local models.
        "CLAUDE_CODE_TOTAL_TOKENS_REMINDER": "off",
        "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
        "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
        "CLAUDE_CODE_NO_FLICKER": "1",
    }
    window = entry.get("context_length") or entry.get("max_context_length")
    if window:
        # claude assumes 200k for a model id it does not recognize, and clamps AUTO_COMPACT_WINDOW to [100k, that]. MAX_CONTEXT_TOKENS sets the window itself.
        env["CLAUDE_CODE_MAX_CONTEXT_TOKENS"] = str(int(window))
        # Blank, not omitted, below the floor so an inherited value cannot apply; MAX_CONTEXT_TOKENS still bounds compaction there.
        env["CLAUDE_CODE_AUTO_COMPACT_WINDOW"] = (
            str(int(window)) if int(window) >= _CLAUDE_MIN_AUTO_COMPACT_WINDOW else ""
        )
        env["CLAUDE_AUTOCOMPACT_PCT_OVERRIDE"] = "90"
        # claude reserves min(max output, 20k) + 3k before compacting, so its 32k default output would take 20k of a 32k window; above 20k the cap gains no room.
        output = opencode_output_limit(int(window))
        if output < _CLAUDE_COMPACT_OUTPUT_RESERVE:
            env["CLAUDE_CODE_MAX_OUTPUT_TOKENS"] = str(output)
    if extra_body:
        env["CLAUDE_CODE_EXTRA_BODY"] = json.dumps(extra_body)
    return env


def _codex_provider_table(base: str, key: Optional[str] = None) -> str:
    # The desktop app gets no shell env, so it needs the key itself rather than env_key.
    auth = (
        f"experimental_bearer_token = {json.dumps(key)}" if key else f'env_key = "{_CODEX_ENV_KEY}"'
    )
    return (
        f"{_PROVIDER_HEADER}\n"
        'name = "Unsloth Studio"\n'
        f"base_url = {json.dumps(base + '/v1')}\n"
        f"{auth}\n"
        'wire_api = "responses"\n'
        "requires_openai_auth = false\n"
        f"stream_idle_timeout_ms = {_CODEX_STREAM_IDLE_TIMEOUT_MS}\n"
    )


_CODEX_PROVIDER_TABLES = (_PROVIDER_HEADER, _PROVIDER_HEADER[:-1] + ".")


def _merge_codex_config(
    existing: str,
    base: str,
    key: Optional[str] = None,
) -> str:
    chunks = re.split(r"(?m)^(?=\[)", existing)  # preamble, then one chunk per table
    if key is None and not re.search(r"(?m)^\s*oss_provider\s*=", chunks[0]):
        if chunks[0] and not chunks[0].endswith("\n"):
            chunks[0] += "\n"
        chunks[0] += f'oss_provider = "{_CODEX_PROFILE}"\n'
    text = "".join(c for c in chunks if not c.startswith(_CODEX_PROVIDER_TABLES))
    if not text.endswith("\n"):
        text += "\n"
    if not text.endswith("\n\n"):
        text += "\n"
    return text + _codex_provider_table(base, key)


# Keep custom-model behavior aligned with Codex's own unknown-model fallback. This Apache-2.0 prompt is copied from openai/codex rust-v0.144.0 models-manager/prompt.md.
_CODEX_FALLBACK_PROMPT = Path(__file__).parent.parent / "codex_fallback_prompt.md"
_CODEX_MODEL_CATALOG_MIN_VERSION = (0, 110, 0)
_CODEX_PROFILE_FILE_MIN_VERSION = (0, 134, 0)
_CODEX_PATCH_LINE_ENDINGS_MIN_VERSION = (0, 148, 0)
# Older Codex sends no reasoning for a model without reasoning summaries, and older Pi has no samplingParams.
_CODEX_REASONING_REQUEST_MIN_VERSION = (0, 145, 0)
_PI_SAMPLING_PARAMS_MIN_VERSION = (0, 84, 0)


def _codex_executable_version(executable: str) -> Optional[tuple[int, int, int]]:
    try:
        output = subprocess.check_output(
            [executable, "--version"],
            text = True,
            encoding = "utf-8",
            errors = "replace",
            timeout = 10,
            stderr = subprocess.DEVNULL,
            env = _probe_env(),
        )
    except Exception:
        return None
    match = re.search(r"(\d+)\.(\d+)\.(\d+)", output)
    return tuple(int(part) for part in match.groups()) if match else None


def _codex_update_hint(executable: str) -> Optional[str]:
    # Update the copy that resolves: a new one in ~/.local/bin sits behind an older one earlier on PATH, so an unknown install gets None.
    if any(part in ("Cellar", "Caskroom") for part in Path(os.path.realpath(executable)).parts):
        return "brew upgrade codex"
    directory = Path(executable).parent
    prefix = directory if os.name == "nt" else directory.parent
    package = prefix / ("node_modules" if os.name == "nt" else "lib/node_modules") / "@openai/codex"
    if package.is_dir():
        return _npm_install_hint("@openai/codex@latest", prefix = prefix)
    return None


def _codex_supports_model_catalog() -> bool:
    executable = _which_with_install_dirs("codex")
    if executable is None:
        # A --no-launch recipe may be copied to another machine; assume a current Codex.
        return True
    version = _codex_executable_version(executable)
    return version is not None and version >= _CODEX_MODEL_CATALOG_MIN_VERSION


def _agent_version_at_least(command: str, minimum: tuple) -> bool:
    executable = _which_with_install_dirs(command)
    if executable is None:
        # Only --no-launch gets here without the agent; its recipe may run elsewhere.
        return True
    version = _codex_executable_version(executable)
    return version is not None and version >= minimum


def _codex_supports_patch_line_endings() -> bool:
    executable = _which_with_install_dirs("codex")
    if executable is None:
        # A normal launch installs Codex after this check; no-launch may run elsewhere.
        return True
    version = _codex_executable_version(executable)
    return version is not None and version >= _CODEX_PATCH_LINE_ENDINGS_MIN_VERSION


def _codex_model_catalog(model: dict, visibility: str = "none") -> dict:
    """Return conservative metadata for an Unsloth model unknown to Codex's built-in catalog."""
    model_id = model["id"]
    window = model.get("context_length") or model.get("max_context_length")
    entry = {
        "slug": model_id,
        "display_name": model_id,
        "description": "Model served by Unsloth Studio",
        "supported_reasoning_levels": [],
        "shell_type": "default",
        "visibility": visibility,
        "supported_in_api": True,
        "priority": 99,
        "availability_nux": None,
        "upgrade": None,
        "base_instructions": _CODEX_FALLBACK_PROMPT.read_text(encoding = "utf-8"),
        "supports_reasoning_summaries": False,
        "supports_reasoning_summary_parameter": False,
        "support_verbosity": False,
        "default_verbosity": None,
        "apply_patch_tool_type": "freeform",
        "truncation_policy": {"mode": "bytes", "limit": 10_000},
        "supports_parallel_tool_calls": False,
        "experimental_supported_tools": [],
    }
    if window:
        entry["context_window"] = int(window)
        entry["max_context_window"] = int(window)
    return {"models": [entry]}


_TOML_KEY_PART = re.compile(
    r"""[ \t]*(?:"((?:[^"\\]|\\.)*)"|'([^']*)'|([A-Za-z0-9_-]+))[ \t]*([.\]])"""
)


_TOML_STRING = re.compile(r'"(?:[^"\\]|\\.)*"|\'[^\']*\'')


def _toml_table_path(chunk: str) -> Optional[tuple]:
    """Key path of the [table] or [[array]] header opening chunk, whatever its quoting or comment."""
    line = chunk.lstrip(" \t")
    if not line.startswith("["):
        return None
    parts, pos = [], 2 if line.startswith("[[") else 1
    while True:
        m = _TOML_KEY_PART.match(line, pos)
        if m is None:
            return None
        parts.append(next(g for g in m.groups()[:3] if g is not None))
        pos = m.end()
        if m.group(4) == "]":
            return tuple(parts)


def _toml_chunks(text: str) -> list:
    """Split before each table header; a "[" line inside a string or an array is not one."""
    chunks, current, delim, depth = [], "", None, 0
    for line in text.splitlines(True):
        if delim is None and depth == 0 and line.lstrip(" \t").startswith("["):
            chunks.append(current)
            current = line
            continue
        current += line
        i = 0
        while i < len(line):
            if delim is not None:
                if line.startswith(delim, i):
                    # Up to two quotes may end the string just before its closing delimiter.
                    run = len(line) - i - len(line[i:].lstrip(delim[0]))
                    delim, i = None, i + min(run, 5)
                else:
                    i += 2 if delim == '"""' and line[i] == "\\" else 1
                continue
            c = line[i]
            if c == "#":
                break
            if line.startswith(('"""', "'''"), i):
                delim, i = line[i : i + 3], i + 3
                continue
            if c in "\"'":
                m = _TOML_STRING.match(line, i)
                i = m.end() if m else len(line)
                continue
            depth += (c in "[{") - (c in "]}")
            i += 1
    chunks.append(current)
    return chunks


def _toml_loads():
    try:
        import tomllib  # novermin
    except ImportError:
        try:
            import tomli as tomllib
        except ImportError:
            return None
    return tomllib.loads


def _toml_parses(text: str) -> Optional[bool]:
    loads = _toml_loads()
    if loads is None:
        return None
    try:
        loads(text)
    except ValueError:
        return False
    return True


def _toml_key(key: str) -> str:
    return key if re.fullmatch(r"[A-Za-z0-9_-]+", key) else _toml_value(key)


def _toml_value(value) -> str:
    if isinstance(value, bool):
        return "true" if value else "false"
    if isinstance(value, str):
        # JSON string escapes are TOML's, except that TOML also forbids a raw DEL.
        return json.dumps(value, ensure_ascii = False).replace("\x7f", "\\u007f")
    if isinstance(value, float) and value != value:
        return "nan"
    if isinstance(value, float) and value in (float("inf"), float("-inf")):
        return "inf" if value > 0 else "-inf"
    if isinstance(value, (int, float)):
        return repr(value)
    if isinstance(value, list):
        return "[" + ", ".join(_toml_value(v) for v in value) + "]"
    if isinstance(value, dict):
        return (
            "{ " + ", ".join(f"{_toml_key(k)} = {_toml_value(v)}" for k, v in value.items()) + " }"
        )
    return value.isoformat()  # TOML dates and times


_CODEX_MCP_MANIFEST = "unsloth_mcp_servers.json"


def _codex_mcp_server(chunk: str) -> Optional[tuple]:
    # The server a [mcp_servers.NAME...] table belongs to: owning NAME owns its subtables. A bare
    # [mcp_servers] table can mix servers from two homes, so it is never owned as a whole.
    path = _toml_table_path(chunk)
    return path[:2] if path and len(path) > 1 and path[0] == "mcp_servers" else None


def _codex_mcp_manifest(home: Path) -> tuple:
    """(home it was built from, the user's own home at the end of that chain, inherited servers)."""
    try:
        state = json.loads((home / _CODEX_MCP_MANIFEST).read_text(encoding = "utf-8"))
        inherited = {tuple(path)[:2] for path in state["tables"]}
        source, origin = state.get("source"), state.get("origin")
    except (OSError, ValueError, TypeError, KeyError, AttributeError):
        return None, None, set()
    source = source if isinstance(source, str) else None
    return source, origin if isinstance(origin, str) else source, inherited


def _codex_mcp_followed(home: Path) -> Optional[Path]:
    # A source that was itself a temporary session home is gone once that session exits.
    source, origin, _ = _codex_mcp_manifest(home)
    for candidate in (source, origin):
        if candidate and Path(candidate).is_dir():
            return Path(candidate)
    return None


def _codex_mcp_tables(source: Path, seen: frozenset) -> list:
    """MCP tables in source's config; a home Unsloth built trades its inherited ones for its origin's."""
    try:
        text = (source / "config.toml").read_text(encoding = "utf-8-sig")
    except OSError:
        return []
    loads = _toml_loads()
    try:
        # Parsed, so root dotted keys, inline tables and a bare [mcp_servers] all count.
        servers = loads(text).get("mcp_servers") if loads else None
    except ValueError:
        loads = (
            None  # TOML 1.1, which Codex reads and tomllib does not: copy the tables as written.
        )
    if loads is None:
        tables = [c for c in _toml_chunks(text) if _codex_mcp_server(c)]
    else:
        tables = [
            f"[mcp_servers.{_toml_key(name)}]\n"
            + "".join(f"{_toml_key(k)} = {_toml_value(v)}\n" for k, v in spec.items())
            + "\n"
            for name, spec in (servers.items() if isinstance(servers, dict) else ())
            if isinstance(spec, dict)
        ]
    _, _, inherited = _codex_mcp_manifest(source)
    upstream_home = _codex_mcp_followed(source)
    if upstream_home is not None and str(upstream_home.resolve(strict = False)) not in seen:
        upstream = _codex_mcp_tables(
            upstream_home, seen | {str(upstream_home.resolve(strict = False))}
        )
        # The origin wins a name clash, as it does when that saved home is synced.
        taken = inherited | {_codex_mcp_server(c) for c in upstream}
        tables = [c for c in tables if _codex_mcp_server(c) not in taken] + upstream
    return tables


def _codex_user_home(home: Path) -> Path:
    source = _codex_source_home()
    home_key = home.resolve(strict = False)
    if source.resolve(strict = False) != home_key:
        return source
    # The printed recipe exports CODEX_HOME=home: keep reading the home it was built from.
    followed = _codex_mcp_followed(home)
    if followed is not None and followed.resolve(strict = False) != home_key:
        return followed
    return _codex_source_home(ignore_configured = True)


def _with_user_codex_mcp_servers(text: str, home: Path, source: Path) -> str:
    _, _, carried = _codex_mcp_manifest(home)
    home_key = home.resolve(strict = False)
    source_key = str(source.resolve(strict = False))
    tables = _codex_mcp_tables(source, frozenset({str(home_key), source_key}))
    # Only replace what came from the user's config; servers added in this home stay.
    servers = {_codex_mcp_server(c) for c in tables}
    carried |= servers
    out = "".join(c for c in _toml_chunks(text) if _codex_mcp_server(c) not in carried)
    if tables:
        out = out.rstrip("\n") + "\n\n" + "\n\n".join(c.rstrip("\n") for c in tables) + "\n"
    if _toml_parses(out) is False:
        return text
    _, origin, _ = _codex_mcp_manifest(source)
    # Written even when empty: a recipe shell's CODEX_HOME=home must still find a custom origin.
    (home / _CODEX_MCP_MANIFEST).write_text(
        json.dumps(
            {"source": source_key, "origin": origin or source_key, "tables": sorted(servers)}
        )
        + "\n",
        encoding = "utf-8",
    )
    return out


def write_codex_config(
    base: str,
    model: dict,
    home: Path,
    reasoning_effort: Optional[str] = None,
    keep_mcp_servers: bool = False,
) -> None:
    home.mkdir(parents = True, exist_ok = True)

    config = home / "config.toml"
    existing = config.read_text(encoding = "utf-8") if config.exists() else ""
    merged = _merge_codex_config(existing, base)
    if keep_mcp_servers:
        source = _codex_user_home(home)
        merged = _with_user_codex_mcp_servers(merged, home, source)
        _link_codex_user_files(home, source)
    if merged != existing:
        config.write_text(merged, encoding = "utf-8")
        typer.echo(f"Updated {config}")

    # oss_provider here too: codex --oss picks the provider from it, and the profile layer must beat a user-set value ("ollama") in config.toml.
    profile_text = (
        f'oss_provider = "{_CODEX_PROFILE}"\n'
        f'model_provider = "{_CODEX_PROFILE}"\n'
        f"model = {json.dumps(model['id'])}\n"
    )
    if _codex_supports_patch_line_endings():
        profile_text += (
            "suppress_unstable_features_warning = true\n"
            "features.apply_patch_preserve_line_endings = true\n"
        )
    if _codex_supports_model_catalog() and _CODEX_FALLBACK_PROMPT.is_file():
        catalog = home / "model-catalog.json"
        catalog_text = json.dumps(_codex_model_catalog(model), indent = 2) + "\n"
        if not catalog.exists() or catalog.read_text(encoding = "utf-8") != catalog_text:
            catalog.write_text(catalog_text, encoding = "utf-8")
            typer.echo(f"Updated {catalog}")
        # Resolve relative to the profile file. This also survives WSL launching a Windows Codex binary, where a Linux absolute path inside TOML would not be usable.
        profile_text += f"model_catalog_json = {json.dumps(catalog.name)}\n"

    window = model.get("context_length") or model.get("max_context_length")
    if window:
        profile_text += f"model_context_window = {int(window)}\n"
    if reasoning_effort:
        profile_text += f"model_reasoning_effort = {json.dumps(reasoning_effort)}\n"
    profile = home / f"{_CODEX_PROFILE}.config.toml"
    if not profile.exists() or profile.read_text(encoding = "utf-8") != profile_text:
        profile.write_text(profile_text, encoding = "utf-8")
        typer.echo(f"Updated {profile}")


def write_codex_subagent_bridge(
    base: str,
    key: str,
    model: dict,
    home: Path,
    *,
    yolo: bool,
    reasoning_effort: Optional[str] = None,
    auto_route: bool = False,
) -> Path:
    """Write private config for an explicit local Codex child launched through MCP."""
    child_home = home / "child"
    write_codex_config(base, model, child_home, reasoning_effort)
    path = home / "subagent.json"
    _write_private_json(
        path,
        {
            "api_key": key,
            "codex_home": str(child_home),
            "bypass_permissions": yolo,
            **({"auto_route": True} if auto_route else {}),
        },
    )
    return path


def _wsl_windows_user_profile(executable: str, app: str = "Codex") -> Path:
    """Return the Windows user profile as a path accessible from WSL."""
    profile = os.environ.get("USERPROFILE", "").strip()
    if not profile:
        try:
            profile = subprocess.check_output(
                ["cmd.exe", "/d", "/c", "echo %USERPROFILE%"],
                text = True,
                encoding = "utf-8",
                # The path is the value: a corrupted home is worse than a loud failure.
                errors = "strict",
                stderr = subprocess.DEVNULL,
                cwd = str(Path(executable).parent),
            ).strip()
        except UnicodeDecodeError as exc:
            _fail(
                f"Could not read the Windows user profile for {app} ({exc}); "
                "set USERPROFILE in the WSL environment, for example through WSLENV."
            )
        except (OSError, subprocess.CalledProcessError) as exc:
            _fail(f"Could not find the Windows user profile for {app}: {exc}")
    if not profile or profile == "%USERPROFILE%":
        _fail(f"Could not find the Windows user profile for {app}.")
    if profile.startswith("/"):
        return Path(profile)
    try:
        translated = subprocess.check_output(
            ["wslpath", "-u", profile],
            text = True,
            encoding = "utf-8",
            errors = "replace",
            stderr = subprocess.DEVNULL,
        ).strip()
    except (OSError, subprocess.CalledProcessError) as exc:
        _fail(f"Could not translate Windows user profile {profile}: {exc}")
    if not translated:
        _fail(f"Could not translate Windows user profile {profile}.")
    return Path(translated)


def _codex_source_home(*, ignore_configured: bool = False) -> Path:
    configured = None if ignore_configured else os.environ.get("CODEX_HOME")
    if configured:
        if _wsl_windows_executable(["codex"]) and _looks_like_path(configured):
            if not configured.startswith("/"):
                try:
                    configured = subprocess.check_output(
                        ["wslpath", "-u", configured],
                        text = True,
                        encoding = "utf-8",
                        errors = "replace",
                        stderr = subprocess.DEVNULL,
                    ).strip()
                except (OSError, subprocess.CalledProcessError) as exc:
                    _fail(f"Could not translate Windows CODEX_HOME {configured}: {exc}")
                if not configured:
                    _fail("Could not translate Windows CODEX_HOME.")
        return Path(configured).expanduser()
    executable = _wsl_windows_executable(["codex"])
    if executable:
        return _wsl_windows_user_profile(executable) / ".codex"
    return Path.home() / ".codex"


def _is_junction(path: Path) -> bool:
    # Path.is_junction() was added in Python 3.12.
    if hasattr(path, "is_junction"):
        return path.is_junction()
    try:
        return (
            getattr(os.lstat(path), "st_reparse_tag", None) == 0xA0000003
        )  # IO_REPARSE_TAG_MOUNT_POINT
    except OSError:
        return False


def _is_directory_link(path: Path) -> bool:
    # lstat reads the link, so FILE_ATTRIBUTE_DIRECTORY answers even when dangling.
    try:
        return bool(getattr(os.lstat(path), "st_file_attributes", 0) & 0x10)
    except OSError:
        return False


def _remove_overlay_entry(path: Path) -> None:
    if _is_junction(path):
        path.rmdir()
    elif os.name == "nt" and path.is_symlink() and _is_directory_link(path):
        # DeleteFileW, which unlink maps to, refuses a directory entry; rmdir drops the link.
        path.rmdir()
    elif path.is_symlink() or path.is_file():
        path.unlink()
    elif path.is_dir():
        shutil.rmtree(path)
    elif path.exists():
        path.unlink()


def _create_directory_junction(source: Path, target: Path) -> bool:
    if os.name != "nt":
        return False
    try:
        result = subprocess.run(
            ["cmd.exe", "/d", "/c", "mklink", "/J", str(target), str(source)],
            capture_output = True,
            text = True,
            encoding = "utf-8",
            errors = "replace",
            timeout = 30,
            check = False,
        )
    except (OSError, subprocess.SubprocessError):
        return False
    return result.returncode == 0


def _link_codex_entry(source: Path, target: Path) -> bool:
    _remove_overlay_entry(target)
    try:
        target.symlink_to(source, target_is_directory = source.is_dir())
        return True
    except OSError:
        pass
    if source.is_file():
        # Only auth.json: Codex rewrites it in place, but a SQLite db under a second name keeps its own WAL and corrupts (sqlite.org/howtocorrupt.html 2.6).
        if source.name == "auth.json":
            with contextlib.suppress(OSError):
                os.link(source, target)
                return True
        shutil.copy2(source, target)
        return True
    if source.is_dir():
        if _create_directory_junction(source, target):
            return True
        if source.name in _CODEX_COPIED_DIRS:
            shutil.copytree(source, target)
            return True
    return False


def _link_codex_user_files(home: Path, source: Path) -> None:
    manifest = home / _CODEX_USER_FILES_MANIFEST
    try:
        linked = json.loads(manifest.read_text(encoding = "utf-8"))["entries"]
    except (OSError, ValueError, TypeError, KeyError):
        linked = []
    for entry in linked if isinstance(linked, list) else []:
        parts = entry.split("/") if isinstance(entry, str) else []
        if (
            0 < len(parts) <= 2
            and parts[0] in _CODEX_USER_FILES
            and all(part not in ("", ".", "..") and "\\" not in part for part in parts)
            and os.path.lexists(home.joinpath(*parts))
        ):
            _remove_overlay_entry(home.joinpath(*parts))
    entries = []
    for name in _CODEX_USER_FILES:
        # Resolved: a relative or temporary source would leave dangling links.
        entry = (source / name).resolve(strict = False)
        target = home / name
        if not entry.exists():
            continue
        if name == "rules" and entry.is_dir() and not os.path.lexists(target):
            # Codex appends approvals to rules/default.rules: a linked dir would write them into the user's.
            target.mkdir()
        if not os.path.lexists(target):
            if _link_codex_entry(entry, target):
                entries.append(name)
        elif (
            entry.is_dir()
            and target.is_dir()
            and not target.is_symlink()
            and not _is_junction(target)
        ):
            # Codex creates skills/.system in every home it runs in.
            for child in entry.iterdir():
                child_target = target / child.name
                if name == "rules" and child.is_file():
                    # Codex skips symlinked *.rules (DirEntry::file_type); default.rules stays this home's.
                    if child.name == "default.rules" or os.path.lexists(child_target):
                        child_target = target / f"user-{child.name}"
                    if os.path.lexists(child_target):
                        continue
                    try:
                        os.link(child.resolve(strict = False), child_target)
                    except OSError:
                        shutil.copy2(child, child_target)
                elif os.path.lexists(child_target) or not _link_codex_entry(
                    child.resolve(strict = False), child_target
                ):
                    continue
                entries.append(f"{name}/{child_target.name}")
    _write_private_json(manifest, {"entries": entries})


def write_codex_parent_overlay(overlay: Path, auto_route: bool = False) -> Path:
    """Add local-agent routing without replacing the cloud parent's configuration."""
    overlay.mkdir(parents = True, exist_ok = True, mode = 0o700)

    manifest_path = overlay / _CODEX_PARENT_OVERLAY_MANIFEST
    try:
        manifest = json.loads(manifest_path.read_text(encoding = "utf-8"))
    except (FileNotFoundError, OSError, json.JSONDecodeError):
        manifest = None
    source_home = _codex_source_home()
    overlay_key = str(overlay.resolve(strict = False))
    source_key = str(source_home.resolve(strict = False))
    if source_key == overlay_key:
        previous_source = manifest.get("source_home") if isinstance(manifest, dict) else None
        if isinstance(previous_source, str) and previous_source:
            candidate = Path(previous_source).expanduser()
            if str(candidate.resolve(strict = False)) != overlay_key:
                source_home = candidate
            else:
                source_home = _codex_source_home(ignore_configured = True)
        else:
            source_home = _codex_source_home(ignore_configured = True)
        source_key = str(source_home.resolve(strict = False))
    same_source = isinstance(manifest, dict) and manifest.get("source_home") == source_key
    if same_source:
        managed_entries = manifest.get("entries", [])
        if not isinstance(managed_entries, list):
            managed_entries = []
        for name in managed_entries:
            if isinstance(name, str) and name not in {"", ".", ".."} and Path(name).name == name:
                _remove_overlay_entry(overlay / name)
    else:
        # A reused overlay must never mix credentials, config, or plugins from two different Codex homes. Legacy overlays have no manifest, so rebuild them once.
        for target in list(overlay.iterdir()):
            _remove_overlay_entry(target)

    entries = []
    if source_home.is_dir():
        for source in source_home.iterdir():
            if source.name in {
                "AGENTS.md",
                "AGENTS.override.md",
                _CODEX_PARENT_OVERLAY_MANIFEST,
            }:
                continue
            if _link_codex_entry(source, overlay / source.name):
                entries.append(source.name)
    # Not signed in yet: a dangling link lands the first login in the user's home, not the overlay.
    auth = source_home / "auth.json"
    if not os.path.lexists(auth):
        with contextlib.suppress(OSError):
            source_home.mkdir(parents = True, exist_ok = True, mode = 0o700)
            _remove_overlay_entry(overlay / auth.name)
            (overlay / auth.name).symlink_to(auth)
            entries.append(auth.name)

    _write_private_json(
        manifest_path,
        {"source_home": source_key, "entries": sorted(entries)},
    )

    inherited = ""
    instruction_name = "AGENTS.md"
    for candidate in (source_home / "AGENTS.override.md", source_home / "AGENTS.md"):
        try:
            text = candidate.read_text(encoding = "utf-8")
        except FileNotFoundError:
            continue
        except OSError as exc:
            _fail(f"Could not preserve Codex instructions from {candidate}: {exc}")
        if text.strip():
            inherited = text.rstrip()
            instruction_name = candidate.name
            break

    other_name = "AGENTS.md" if instruction_name == "AGENTS.override.md" else "AGENTS.override.md"
    other = overlay / other_name
    if other.is_file() or other.is_symlink():
        other.unlink()
    routing = _CODEX_SUBAGENT_ROUTING_INSTRUCTIONS
    if auto_route:
        routing = f"{routing}\n\n{_CODEX_AUTO_ROUTE_INSTRUCTIONS}"
    combined = f"{inherited}\n\n{routing}\n" if inherited else f"{routing}\n"
    _write_private_text(overlay / instruction_name, combined)
    return overlay


def _agent_config_path(path: Path, command: list) -> str:
    """Translate a generated config path when a Windows agent runs through WSL."""
    return _wsl_windows_path(path) if _wsl_windows_executable(command) else str(path)


_OPENCODE_ROUTE_PLUGIN_SCRIPT = """\
const LOCAL = new Set(%(local)s);
const ROUTED = new Set(%(routed)s);
const HIDDEN = new Set(["title", "summary", "compaction"]);
const agents = new Map();
// Set when a local run fails, so the parent can do that step itself until the next local run succeeds.
let failed = false;

export const UnslothAutoRoute = async () => ({
  "chat.params": async ({ sessionID, agent }) => {
    if (!HIDDEN.has(agent)) agents.set(sessionID, agent);
  },
  event: async ({ event }) => {
    const { sessionID, error } = event.properties ?? {};
    if (event.type === "session.error" && LOCAL.has(agents.get(sessionID)) && error?.name !== "MessageAbortedError") failed = true;
  },
  "tool.execute.after": async ({ tool, args }) => {
    if (tool === "task" && LOCAL.has(args?.subagent_type)) failed = false;
  },
  "tool.execute.before": async ({ tool, sessionID }) => {
    const agent = agents.get(sessionID);
    if (failed || !ROUTED.has(tool) || LOCAL.has(agent)) return;
    throw new Error(
      "Blocked by Unsloth --auto-route: files and the shell are only reachable through the local " +
        "agent. Hand the complete task to the @" + (agent === "plan" ? %(plan)s : %(build)s) +
        " subagent with the task tool instead.",
    );
  },
});
""" % {
    "local": json.dumps([_SUBAGENT_NAME, _OPENCODE_PLAN_SUBAGENT_NAME]),
    "routed": json.dumps(list(_OPENCODE_ROUTED_TOOLS)),
    "plan": json.dumps(_OPENCODE_PLAN_SUBAGENT_NAME),
    "build": json.dumps(_SUBAGENT_NAME),
}


def _opencode_subagent_inline_config(
    path: Path,
    permission: dict,
    command: str = "opencode",
    v2: bool = False,
    auto_route: bool = False,
) -> dict:
    """Keep the local provider visible without hiding the parent's allowed providers."""
    inline: dict = {}
    inherited = os.environ.get("OPENCODE_CONFIG_CONTENT")
    if inherited:
        try:
            parsed = json.loads(inherited)
        except ValueError:
            _fail("OPENCODE_CONFIG_CONTENT is not valid JSON.")
        if not isinstance(parsed, dict):
            _fail("OPENCODE_CONFIG_CONTENT must contain a JSON object.")
        inline.update(parsed)

    def merge_provider_filters(effective_config: dict) -> None:
        enabled = effective_config.get("enabled_providers")
        if isinstance(enabled, list):
            inherited_enabled = inline.get("enabled_providers")
            if not isinstance(inherited_enabled, list):
                inherited_enabled = []
            providers = [
                provider
                for provider in [*inherited_enabled, *enabled]
                if provider != _OPENCODE_PROVIDER
            ]
            inline["enabled_providers"] = list(dict.fromkeys([*providers, _OPENCODE_PROVIDER]))
        disabled = effective_config.get("disabled_providers")
        if isinstance(disabled, list) and _OPENCODE_PROVIDER in disabled:
            inline["disabled_providers"] = [
                provider for provider in disabled if provider != _OPENCODE_PROVIDER
            ]

    # Keep an inherited inline allowlist usable by the local provider. V2 turns these filters into policies where global/project rules still intentionally outrank this content; the message at launch makes that boundary explicit.
    merge_provider_filters(inline)
    effective = inline

    executable = None if v2 else _which_with_install_dirs(command)
    if v2:
        legacy_depth = inline.pop("subagent_depth", None)
        if (
            isinstance(legacy_depth, int)
            and not isinstance(legacy_depth, bool)
            and legacy_depth > 0
        ):
            experimental = inline.get("experimental")
            if not isinstance(experimental, dict):
                experimental = {}
            experimental.setdefault("subagent_depth", legacy_depth)
            inline["experimental"] = experimental
    elif executable is None:
        typer.echo(
            f"Warning: OpenCode is not installed, so provider filters could not be checked. "
            f"The target configuration must allow '{_OPENCODE_PROVIDER}'.",
            err = True,
        )
    else:
        env = _probe_env(OPENCODE_CONFIG = _agent_config_path(path, [command]))
        try:
            resolved = subprocess.run(
                [executable, "debug", "config"],
                capture_output = True,
                text = True,
                encoding = "utf-8",
                errors = "replace",
                timeout = 15,
                env = env,
            )
        except Exception as exc:
            _fail(f"Could not inspect OpenCode provider filters: {exc}")
        if resolved.returncode != 0:
            detail = resolved.stderr.strip() or resolved.stdout.strip()
            _fail(f"Could not inspect OpenCode provider filters: {detail or 'unknown error'}")
        try:
            effective = json.loads(resolved.stdout)
        except ValueError:
            _fail("Could not inspect OpenCode provider filters: invalid JSON response.")
        if not isinstance(effective, dict):
            _fail("Could not inspect OpenCode provider filters: expected a JSON object.")

        merge_provider_filters(effective)

    if not v2:
        depth = effective.get("subagent_depth")
        inline["subagent_depth"] = (
            depth if isinstance(depth, int) and not isinstance(depth, bool) and depth > 0 else 1
        )
    if permission:
        inline["permission"] = permission
    plugin = path.parent / _OPENCODE_ROUTE_PLUGIN
    if auto_route and not v2:
        _write_private_text(plugin, _OPENCODE_ROUTE_PLUGIN_SCRIPT)
        # OpenCode adds each layer's plugins to the others', so only an inherited inline list needs keeping.
        plugins = inline.get("plugin")
        inline["plugin"] = [
            *(plugins if isinstance(plugins, list) else []),
            _agent_config_path(plugin, [command]),
        ]
    else:
        # A persisted session dir may still hold the plugin from an earlier --auto-route run.
        plugin.unlink(missing_ok = True)
    if auto_route:
        # The V2 CLI has no tool hooks, so there read and bash fall back to permission rules.
        denied = _OPENCODE_HIDDEN_TOOLS + (_OPENCODE_ROUTED_TOOLS if v2 else ())
        permission = {
            **dict.fromkeys((*denied, "edit"), "deny"),
            "task": {"*": "deny", _SUBAGENT_NAME: "allow"},
        }
        # Plan keeps its own edit rules (it may write only its plan file) and reaches the read-only agent.
        plan_permission = {
            **dict.fromkeys(denied, "deny"),
            "task": {"*": "deny", _OPENCODE_PLAN_SUBAGENT_NAME: "allow"},
        }
        # An agent's own permission outranks the global one, so restrict by name every agent a user can be in (an @mention skips the task rule).
        agents = _subdict(inline, "agent")
        configured = effective.get("agent")
        names = {
            "build",
            "general",
            "explore",
            *(configured if isinstance(configured, dict) else ()),
        }
        for name in names - {"plan", _SUBAGENT_NAME, _OPENCODE_PLAN_SUBAGENT_NAME}:
            _subdict(_subdict(agents, name), "permission").update(permission)
        _subdict(_subdict(agents, "plan"), "permission").update(plan_permission)
    return inline


def _b64_path(path: Path) -> str:
    """Path as base64, so it can cross a shell without being expanded."""
    return base64.b64encode(str(path).encode("utf-8")).decode("ascii")


_CLAUDE_PLAN_GATE_SCRIPT = '''\
"""Deny the editing agent while the parent session is in plan mode."""
import json, sys

try:
    mode = (json.load(sys.stdin) or {}).get("permission_mode")
except Exception:
    sys.exit(0)  # fail open: a hook error must never block the parent session
if mode == "plan":
    print(json.dumps({"hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": "deny",
        "permissionDecisionReason": (
            "Plan mode is active. Call the read-only Unsloth plan agent "
            "(unsloth_plan_agent) instead of unsloth_agent."
        ),
    }}))
sys.exit(0)
'''

_CLAUDE_ROUTE_GATE_SCRIPT = """\
import json, os, sys

# The local agent server leaves this file after a failed run, so the parent can do that step itself.
if os.path.exists(os.path.join(os.path.dirname(__file__), "local-agent-failed")):
    sys.exit(0)
print(json.dumps({"hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": (
        "Blocked by Unsloth --auto-route: files and the shell are only reachable through "
        "the local agent. Call the unsloth_agent tool with the complete task instead."
    ),
}}))
sys.exit(0)
"""
# PowerShell is the shell on Windows without Git Bash, Monitor runs commands too, and Agent (Task before Claude Code 2) would hand the same work to a cloud subagent.
_CLAUDE_ROUTE_GATE_MATCHER = "Read|Grep|Glob|Bash|PowerShell|Monitor|NotebookRead|Agent|Task"


_CLAUDE_HOOK_ARGS_MIN_VERSION = (2, 1, 139)


def _claude_hook(gate: Path, exec_form: bool = True) -> dict:
    if exec_form:
        # Exec form: without Git Bash, Windows runs shell-form hooks in PowerShell, which cannot parse them.
        return {
            "type": "command",
            "command": sys.executable,
            "args": ["-c", "import runpy,sys; runpy.run_path(sys.argv[1])", str(gate)],
            "timeout": 10,
        }
    return {
        "type": "command",
        # Run through runpy rather than handing the path to the interpreter: a missing gate is then an ordinary traceback (exit 1, fails open) instead of exit 2, which Claude treats as a blocking error and would deny the tool in every mode. The path is base64'd because this string goes through a shell: a temp root holding $(..) or a backtick expands under sh, %VAR% under cmd, and the gate then silently fails open. base64's alphabet has no metacharacter in either.
        "command": (
            f'"{sys.executable}" -c '
            f'"import base64,runpy; runpy.run_path('
            f"base64.b64decode('{_b64_path(gate)}').decode())\""
        ),
        # A hook with no timeout stalls the parent for as long as it hangs; measured unbounded past 400s.
        "timeout": 10,
    }


def write_claude_subagent_plugin(path: Path, server_env: dict) -> Path:
    """Write a session plugin that exposes the local Claude child through MCP."""
    plugin = path / "unsloth-local-agent"
    command = sys.executable
    args = ["-m", _CLAUDE_SUBAGENT_MCP_MODULE]
    mcp_env = dict(server_env)
    base = server_env.get("UNSLOTH_CLAUDE_SUBAGENT_BASE_URL")
    key = server_env.get("UNSLOTH_CLAUDE_SUBAGENT_API_KEY")
    model_id = server_env.get("UNSLOTH_CLAUDE_SUBAGENT_MODEL")
    if base and key and model_id:
        entry = {
            "id": model_id,
            "context_length": int(
                server_env.get("UNSLOTH_CLAUDE_SUBAGENT_CONTEXT_WINDOW", "0") or 0
            ),
        }
        local_env = _claude_local_env(base, key, entry)
        if "CLAUDE_CODE_EXTRA_BODY" in server_env:
            local_env["CLAUDE_CODE_EXTRA_BODY"] = server_env["CLAUDE_CODE_EXTRA_BODY"]
        settings = _write_claude_settings(plugin, model_id, local_env)
        mcp_env[_CLAUDE_SUBAGENT_SETTINGS_ENV] = str(settings)
    if _wsl_windows_executable(["claude"]):
        command = "wsl.exe"
        args = [
            "-d",
            os.environ["WSL_DISTRO_NAME"],
            "--",
            sys.executable,
            "-m",
            _CLAUDE_SUBAGENT_MCP_MODULE,
        ]
        mcp_env["WSLENV"] = _merge_wslenv(
            os.environ.get("WSLENV", ""),
            (
                *_wsl_bridge_names(server_env, ()),
                *([_CLAUDE_SUBAGENT_SETTINGS_ENV] if base and key and model_id else []),
            ),
        )
    auto_route = server_env.get(_CLAUDE_SUBAGENT_AUTO_ROUTE_ENV) == "1"
    fallback = plugin / "hooks" / _CLAUDE_ROUTE_FALLBACK_FILE
    if auto_route and command != "wsl.exe":
        mcp_env[_CLAUDE_SUBAGENT_FALLBACK_ENV] = str(fallback)
    _write_private_json(
        plugin / ".claude-plugin" / "plugin.json",
        {
            "name": "unsloth-local-agent",
            "version": "1.0.0",
            "description": _SUBAGENT_DESCRIPTION,
            "author": {"name": "Unsloth AI"},
        },
    )
    _write_private_json(
        plugin / ".mcp.json",
        {
            "mcpServers": {
                "unsloth": {
                    "type": "stdio",
                    "command": command,
                    "args": args,
                    "env": mcp_env,
                }
            }
        },
    )
    # Claude already refuses the editing tool in plan mode, since it advertises readOnlyHint false. This PreToolUse hook replaces that dead end with a reason naming the read-only tool to call instead. Skipped under the WSL bridge, where the gate is a Linux path but the hook would run beside the Windows claude.
    gate = plugin / "hooks" / "plan_gate.py"
    route_gate = plugin / "hooks" / "route_gate.py"
    # A persisted plugin dir may still hold gates, or a failure left by an earlier session.
    fallback.unlink(missing_ok = True)
    if command == "wsl.exe" or not auto_route:
        route_gate.unlink(missing_ok = True)
    if command == "wsl.exe":
        for stale in (gate, plugin / "hooks" / "hooks.json"):
            stale.unlink(missing_ok = True)
    else:
        _write_private_text(gate, _CLAUDE_PLAN_GATE_SCRIPT)
        version = _claude_version()
        exec_form = version is None or version >= _CLAUDE_HOOK_ARGS_MIN_VERSION
        entries = [{"matcher": _CLAUDE_SUBAGENT_TOOL, "hooks": [_claude_hook(gate, exec_form)]}]
        if auto_route:
            _write_private_text(route_gate, _CLAUDE_ROUTE_GATE_SCRIPT)
            entries.append(
                {
                    "matcher": _CLAUDE_ROUTE_GATE_MATCHER,
                    "hooks": [_claude_hook(route_gate, exec_form)],
                }
            )
        _write_private_json(plugin / "hooks" / "hooks.json", {"hooks": {"PreToolUse": entries}})
    skill = plugin / "skills" / "local-agent" / "SKILL.md"
    skill.parent.mkdir(parents = True, exist_ok = True, mode = 0o700)
    when = (
        "Use it for routine, self-contained work (codebase search, reading files, running "
        "tests or commands, mechanical edits) without being asked, and whenever the user asks "
        "for an Unsloth or local agent."
        if auto_route
        else "Use when the user asks to spawn an Unsloth agent or local agent."
    )
    skill.write_text(
        "---\n"
        f"description: Delegate a task to the local agent powered by Unsloth. {when}\n"
        "---\n\n"
        "Call the Unsloth local agent tool once with the complete task. In plan mode, call "
        "the read-only Unsloth plan agent instead. Return its result to the user without "
        "claiming that the cloud parent completed the local work.\n",
        encoding = "utf-8",
    )
    return plugin


def _codex_subagent_flags(path: Path) -> list[str]:
    command = sys.executable
    package_root = str(Path(__file__).resolve().parents[2])
    bootstrap = (
        f"import sys;sys.path.insert(0,{json.dumps(package_root)});"
        f"from {_CODEX_SUBAGENT_MCP_MODULE} import main;main()"
    )
    args = ["-c", bootstrap, str(path)]
    if _wsl_windows_executable(["codex"]):
        command = "wsl.exe"
        args = [
            "-d",
            os.environ["WSL_DISTRO_NAME"],
            "--",
            sys.executable,
            "-c",
            bootstrap,
            str(path),
        ]
    server = (
        "{ "
        f"command = {json.dumps(command)}, "
        f"args = {json.dumps(args)}, "
        f"required = true, enabled_tools = [{json.dumps(_CODEX_SUBAGENT_MCP_TOOL)}], "
        'default_tools_approval_mode = "approve", '
        "startup_timeout_sec = 15, tool_timeout_sec = 3600 }"
    )
    return ["-c", f"mcp_servers.{_CODEX_SUBAGENT_MCP_SERVER}={server}"]


def _wsl_windows_executable(command: list) -> Optional[str]:
    if os.name == "nt" or not os.environ.get("WSL_DISTRO_NAME"):
        return None
    executable = shutil.which(command[0])
    if executable and executable.startswith("/mnt/"):
        return executable
    return None


def _wsl_windows_path(path: Path) -> str:
    try:
        translated = subprocess.check_output(
            ["wslpath", "-w", str(path)], text = True, encoding = "utf-8", errors = "replace"
        ).strip()
    except (OSError, subprocess.CalledProcessError) as exc:
        _fail(f"Could not translate WSL path {path}: {exc}")
    if not translated:
        _fail(f"Could not translate WSL path {path}")
    return translated


def _looks_like_path(value: str) -> bool:
    # A var only wants the WSLENV /p flag if its value is a filesystem path: an absolute POSIX path (/...), a UNC path (\\\\...), or a drive-qualified Windows path (C:...). Scalar knobs such as a numeric context window must pass through untranslated, so they get no flag.
    return bool(value) and (value.startswith(("/", "\\")) or (len(value) >= 2 and value[1] == ":"))


def _wsl_bridge_names(env: dict, unset_env: tuple) -> tuple:
    # Build the WSLENV share list for a Windows shim reached from WSL. Path-valued vars get /p so WSLENV translates them to the Windows path the /mnt shim can actually open; a cleared var carries no value to translate.
    names = [name + ("/p" if _looks_like_path(value) else "") for name, value in env.items()]
    names.extend(unset_env)
    return tuple(dict.fromkeys(names))


def _merge_wslenv(current: str, names: tuple) -> str:
    # Index WSLENV entries by bare var name, preserving first-seen order. The vars we bridge are applied last so our entry wins: a user's pre-existing unflagged "HOME" is upgraded to "HOME/p" rather than left as-is, since WSLENV ignores a duplicate name and a bare entry would leave the path untranslated for a Windows shim.
    ordered = []
    by_name = {}
    for entry in (*current.split(":"), *names):
        if not entry:
            continue
        base = entry.split("/", 1)[0]
        if base not in by_name:
            ordered.append(base)
        by_name[base] = entry
    return ":".join(by_name[base] for base in ordered)


def _powershell_quote(arg: str) -> str:
    # PowerShell reads single-quoted strings literally (an embedded ' is doubled), so JSON args such as `--settings {"env":...}` survive intact. list2cmdline's backslash-escaped double quotes are cmd.exe syntax and PowerShell mis-parses them.
    if arg and re.fullmatch(r"[A-Za-z0-9_./:=+-]+", arg):
        return arg
    return "'" + arg.replace("'", "''") + "'"


def _print_env(
    env: dict,
    command: list,
    unset_env: tuple = (),
    wsl_env_bridge: tuple = (),
    cwd_env: tuple = (),
) -> None:
    if os.name == "nt":
        for name in unset_env:
            typer.echo(f"Remove-Item Env:{name} -ErrorAction SilentlyContinue")
        for name, value in env.items():
            # PowerShell: ` is the escape char, and $ triggers expansion inside "".
            escaped = value.replace("`", "``").replace('"', '`"').replace("$", "`$")
            typer.echo(f'$env:{name} = "{escaped}"')
        for name in cwd_env:
            typer.echo(f"$env:{name} = (Get-Location).Path")
        typer.echo(" ".join(_powershell_quote(arg) for arg in command))
        return
    for name in unset_env:
        typer.echo(f"export {name}=" if wsl_env_bridge else f"unset {name}")
    for name, value in env.items():
        typer.echo(f"export {name}={shlex.quote(value)}")
    for name in cwd_env:
        typer.echo(f'export {name}="$PWD"')
    if wsl_env_bridge:
        typer.echo(
            f"export WSLENV={shlex.quote(_merge_wslenv(os.environ.get('WSLENV', ''), wsl_env_bridge))}"
        )
    # The final line is a SELF-CONTAINED one-liner (inline env, VAR=... cmd) rather than a bare command. People copy just the last line, and a bare `codex`/`claude` would then run against their real ~/.codex or Anthropic credentials with zero isolation, for example inheriting a pre-existing damaged ~/.codex state DB and blaming the recipe. Inline assignments scope every var, and empty-string the conflicting ones, to this single invocation, so a partial copy behaves the same as pasting the whole block.
    inline = [f"{name}=" for name in unset_env]
    inline += [f"{name}={shlex.quote(value)}" for name, value in env.items()]
    inline += [f'{name}="$PWD"' for name in cwd_env]
    if wsl_env_bridge:
        inline.append(
            f"WSLENV={shlex.quote(_merge_wslenv(os.environ.get('WSLENV', ''), wsl_env_bridge))}"
        )
    typer.echo(" ".join((*inline, shlex.join(command))))


def _refresh_windows_path() -> None:
    # Merge Windows registry PATH hives after the current process PATH so a freshly installed agent is visible without changing existing precedence.
    if os.name != "nt":
        return
    try:
        import winreg
    except Exception:
        return

    entries = []
    seen = set()

    def add_path(value: str) -> bool:
        added = False
        for entry in str(value).split(os.pathsep):
            entry = entry.strip()
            if not entry:
                continue
            key = os.path.normcase(entry).casefold()
            if key in seen:
                continue
            seen.add(key)
            entries.append(entry)
            added = True
        return added

    add_path(os.environ.get("PATH", ""))
    added_registry = False
    hives = (
        (winreg.HKEY_CURRENT_USER, "Environment"),
        (
            winreg.HKEY_LOCAL_MACHINE,
            r"SYSTEM\CurrentControlSet\Control\Session Manager\Environment",
        ),
    )
    for root, sub in hives:
        try:
            with winreg.OpenKey(root, sub) as key:
                value, _ = winreg.QueryValueEx(key, "Path")
        except OSError:
            continue
        if value:
            added_registry = add_path(os.path.expandvars(str(value))) or added_registry
    if added_registry:
        os.environ["PATH"] = os.pathsep.join(entries)


def _managed_node_tools() -> Optional[tuple[Path, Path, bool]]:
    # Best-effort: any failure here means "no managed Node", never a broken launch.
    try:
        # Discovery only: must not create the cache tree (the launch may target a remote server).
        ensure_studio_backend_path(seed_cache_env = False)
        from utils.node_runtime import managed_node_binary, resolve_node_executable
        node = Path(managed_node_binary())
    except (ImportError, OSError, RuntimeError, TypeError, ValueError):
        return None
    npm = node.with_name("npm.cmd" if os.name == "nt" else "npm")
    try:
        usable = node.is_file() and npm.is_file()
        if os.name != "nt":
            usable = usable and os.access(node, os.X_OK) and os.access(npm, os.X_OK)
    except OSError:
        return None
    if not usable:
        return None
    try:
        resolved = resolve_node_executable()
        preferred = bool(resolved) and Path(resolved).resolve() == node.resolve()
    except (OSError, RuntimeError, TypeError, ValueError):
        preferred = False
    return node, npm, preferred


def _augment_path_with_install_dirs() -> None:
    # Add known install dirs to PATH so a freshly installed agent resolves without a new shell. User dirs are appended (existing tools keep precedence); a preferred managed Node is prepended so Node-backed shims use it. Only user dirs need a home, so a missing home must not drop the managed Node, or a shim fails on `env node` under a bare container UID.
    try:
        home = Path.home()
    except (RuntimeError, OSError):
        home = None
    candidates = [home / ".local" / "bin", home / ".opencode" / "bin"] if home is not None else []
    if os.name == "nt":
        appdata = os.environ.get("APPDATA")
        if appdata:
            candidates.append(Path(appdata) / "npm")
    managed_node = _managed_node_tools()
    if managed_node is not None and not managed_node[2]:
        candidates.append(managed_node[0].parent)
    current = os.environ.get("PATH")
    if current is None:
        # PATH unset: shutil.which() and exec*p* fall back to os.defpath (/bin:/usr/bin), so keep that default instead of collapsing to just the install dirs, which would hide a system-installed agent and strip the launched child's normal PATH. An explicitly empty PATH is left as-is: like shutil.which, it means "search nothing", not os.defpath.
        current = os.defpath
    preferred_node = (
        str(managed_node[0].parent) if managed_node is not None and managed_node[2] else None
    )
    if preferred_node:
        preferred_key = os.path.normcase(preferred_node)
        current = os.pathsep.join(
            entry
            for entry in current.split(os.pathsep)
            if not entry or os.path.normcase(entry) != preferred_key
        )
    seen = {os.path.normcase(entry) for entry in current.split(os.pathsep) if entry}
    additions = [
        str(directory)
        for directory in candidates
        if directory.is_dir() and os.path.normcase(str(directory)) not in seen
    ]
    if preferred_node or additions:
        parts = [part for part in (preferred_node, current, *additions) if part]
        os.environ["PATH"] = os.pathsep.join(parts)


def _probe_env(**extra: str) -> dict:
    """Environment for probes that RUN a resolved shim. _which_with_install_dirs restores PATH before returning, so a shim backed by Unsloth's managed Node would not find that node when executed."""
    original = os.environ.get("PATH")
    _augment_path_with_install_dirs()
    env = os.environ.copy()
    if original is None:
        os.environ.pop("PATH", None)
    else:
        os.environ["PATH"] = original
    env.update(extra)
    return env


def _prefer_windows_cmd_sibling(executable: Optional[str]) -> Optional[str]:
    """Prefer the sibling .cmd when Windows resolved an extensionless npm/pnpm shim. cmd-shim writes ``to``, ``to.cmd`` and ``to.ps1``, and shutil.which can return the extensionless POSIX shim, which CreateProcess rejects with WinError 193. Measured on windows-latest: 3.12.0 probes the bare name before PATHEXT (gh-109590) and 3.12.1 onwards do not, and a PATHEXT holding "." reaches the same place on any version. Substituted only when the file opens with a shebang, so a real PE keeps priority over a stale wrapper beside it; matched on not-a-Windows-suffix so a dotted bin name is caught too."""
    if executable is None or os.name != "nt":
        return executable
    if Path(executable).suffix.lower() in {".exe", ".com", ".cmd", ".bat", ".ps1"}:
        return executable
    with contextlib.suppress(OSError):
        with open(executable, "rb") as resolved_file:
            if resolved_file.read(2) == b"#!":
                # .CMD only matters on case-sensitive volumes; no writer emits .bat.
                for extension in (".cmd", ".CMD"):
                    sibling = Path(executable + extension)
                    if sibling.is_file():
                        return str(sibling)
    return executable


def _which_with_install_dirs(name: str) -> Optional[str]:
    # Probe lookup also searches agent install dirs so it matches _launch(); else flags reach an older build it rejects; PATH is restored.
    original = os.environ.get("PATH")
    _augment_path_with_install_dirs()
    try:
        # Callers spawn this result directly, so the shim rescue is needed here too, not only in _resolved_launch_command.
        return _prefer_windows_cmd_sibling(shutil.which(name))
    finally:
        if original is None:
            os.environ.pop("PATH", None)
        else:
            os.environ["PATH"] = original


def _which_deepseek_harness_with_install_dirs() -> Optional[str]:
    """Find the first valid DeepSeek Harness even when another ``dsh`` shadows it."""
    original = os.environ.get("PATH")
    _augment_path_with_install_dirs()
    try:
        for executable in deepseek_harness_executables_on_path():
            executable = _prefer_windows_cmd_sibling(executable)
            if executable is not None and is_deepseek_harness_executable(executable):
                return executable
        return None
    finally:
        if original is None:
            os.environ.pop("PATH", None)
        else:
            os.environ["PATH"] = original


def _install_source(install_hint: str) -> Optional[str]:
    """The first http(s) URL an install hint fetches, or None (e.g. an npm install)."""
    match = re.search(r"https?://[^\s'\")]+", install_hint)
    return match.group(0) if match else None


def _pinned_raw_github_commit(source: str) -> Optional[str]:
    """Return the immutable full commit in a raw GitHub URL, if present."""
    match = re.match(
        r"^https://raw\.githubusercontent\.com/[^/]+/[^/]+/([0-9a-f]{40})/",
        source,
        flags = re.IGNORECASE,
    )
    return match.group(1).lower() if match else None


# Pi needs node >=22.19.0; npm only warns, so it installs on Node 20.19 and then dies on load.
_PI_MIN_NODE = (22, 19, 0)


def _node_version() -> Optional[tuple]:
    """Version of the `node` a launched npm shim resolves (`#!/usr/bin/env node`), or None."""
    node = _which_with_install_dirs("node")
    if node is None:
        return None
    try:
        found = subprocess.run(
            [node, "--version"],
            capture_output = True,
            text = True,
            timeout = 10,
            env = _probe_env(),
        ).stdout
    except (OSError, subprocess.SubprocessError):
        return None
    match = re.match(r"\s*v?(\d+)\.(\d+)\.(\d+)", found or "")
    return tuple(int(part) for part in match.groups()) if match else None


def _warn_if_node_older(agent: str, minimum: tuple, legacy_package: str) -> None:
    found = _node_version()
    if found is not None and found < minimum:
        typer.echo(
            f"Warning: {agent} needs Node.js {'.'.join(map(str, minimum))} or newer, but `node` "
            f"here is {'.'.join(map(str, found))}. If it fails to start, upgrade Node.js, or "
            f"install the older line with `npm install -g {legacy_package}`.",
            err = True,
        )


def _npm_executable() -> Optional[str]:
    managed_node = _managed_node_tools()
    if not (managed_node and managed_node[2]):
        executable = _prefer_windows_cmd_sibling(shutil.which("npm"))
        if executable and not _wsl_windows_executable([executable]):
            return executable
        if executable:
            # WSL inherits the Windows PATH, so the rejected shim may shadow a native npm.
            for directory in os.get_exec_path():
                candidate = _prefer_windows_cmd_sibling(shutil.which("npm", path = directory))
                if candidate and not _wsl_windows_executable([candidate]):
                    return candidate

    return str(managed_node[1]) if managed_node is not None else None


def _install_command(install_hint: str) -> tuple[list[str], Optional[dict]]:
    if not re.match(r"^\s*npm(?:\s|$)", install_hint):
        if os.name == "nt":
            return (
                [
                    "powershell",
                    "-NoProfile",
                    "-ExecutionPolicy",
                    "Bypass",
                    "-Command",
                    install_hint,
                ],
                None,
            )
        return ["/bin/sh", "-c", install_hint], None

    npm = _npm_executable()
    if npm is None:
        _fail(
            "npm is required to install this agent, but no native system npm or usable "
            "Unsloth-managed Node installation was found. Install Node.js with npm, "
            "then re-run."
        )
    env = dict(os.environ)
    # dirname, not Path().parent: Path picks its flavour from os.name, which the tests override. Empty means npm is a bare name; prepending "" would put the cwd on PATH.
    npm_dir = os.path.dirname(npm)
    current_path = env.get("PATH", "")
    if npm_dir:
        env["PATH"] = os.pathsep.join([npm_dir, current_path]) if current_path else npm_dir
    if os.name == "nt":
        # The hint is already PowerShell-quoted; shlex would drop the doubled ' of a path like O'Brien.
        command = "& " + _powershell_quote(npm) + install_hint.lstrip()[len("npm") :]
        return (
            [
                "powershell",
                "-NoProfile",
                "-ExecutionPolicy",
                "Bypass",
                "-Command",
                command,
            ],
            env,
        )
    return [npm, *shlex.split(install_hint)[1:]], env


def _install_agent(
    name: str,
    install_hint: str,
    *,
    update: bool = False,
) -> Optional[str]:
    # Missing agent under --launch: offer to run its documented install command, then re-resolve it on PATH. Consent-based, and a non-interactive stdin cannot answer the prompt, so both the no-TTY and declined cases return None and let the caller print the hint and exit.
    if not sys.stdin.isatty():
        return None
    typer.echo(f"`{name}` is {'too old' if update else 'not installed'}.")
    # Make the supply-chain risk explicit before the prompt: these are the vendors' own installers (curl | bash, irm | iex, npm), run with the user's privileges, and nothing checks a signature or hash on the fetched content. Naming the source turns a blind "yes" into informed consent.
    source = _install_source(install_hint)
    if source:
        pinned_commit = _pinned_raw_github_commit(source)
        if pinned_commit:
            warning = (
                "Security warning: This will download and execute a third-party script "
                f"from {source} with your privileges. Unsloth pins this content to "
                f"immutable upstream commit {pinned_commit}, but does not independently "
                "verify or sandbox it. Continue only if you trust this source and commit."
            )
        else:
            warning = (
                "Security warning: This will download and execute an unverified third-party "
                f"script from {source} with your privileges. Unsloth does not pin or verify "
                "the downloaded content. Continue only if you trust this source."
            )
    else:
        warning = (
            f"This will RUN `{install_hint}` with your privileges; "
            "there is no signature or hash check."
        )
    typer.secho(warning, fg = "yellow", err = True)
    action = "Update" if update else "Install"
    if not typer.confirm(f"{action} `{name}` now with `{install_hint}`?", default = False):
        return None
    install_command, install_env = _install_command(install_hint)
    try:
        result = subprocess.run(install_command, env = install_env)
    except OSError as exc:
        _fail(
            f"Could not run the install command: {exc}. "
            f"Run it yourself, then re-run: {install_hint}"
        )
    if result.returncode != 0:
        message = f"Install command failed. Run it yourself, then re-run: {install_hint}"
        if os.name == "nt":
            # A hand-run retry can still hit the policy; point at the one-time per-user fix.
            message += (
                "\nIf it fails because running scripts is disabled (PSSecurityException), "
                "allow local scripts for your user, then retry:\n"
                "  Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned"
            )
        _fail(message)
    # Resolve the freshly installed agent without a shell restart: pull registry PATH (Windows) plus well-known install dirs the installer may not have added to PATH.
    _refresh_windows_path()
    _augment_path_with_install_dirs()
    executable = shutil.which(name)
    if executable is None:
        _fail(
            f"`{name}` installed but isn't on PATH yet. Open a new shell (or add it to "
            f"PATH), then re-run. Install command: {install_hint}"
        )
    return executable


def _resolve_or_install_agent(name: str, install_hint: str, resolver) -> str:
    executable = resolver(name)
    invalid_executable = None
    if executable is not None:
        if name != "dsh" or is_deepseek_harness_executable(executable):
            return executable
        invalid_executable = executable
        executable = _which_deepseek_harness_with_install_dirs()
        if executable is not None:
            return executable

    executable = _install_agent(name, install_hint)
    if executable is not None:
        if name != "dsh" or is_deepseek_harness_executable(executable):
            return executable
        invalid_executable = executable
    if name == "dsh":
        executable = _which_deepseek_harness_with_install_dirs()
        if executable is not None:
            return executable

    if invalid_executable is not None:
        _fail(
            f"`{invalid_executable}` is not DeepSeek Harness. Install DeepSeek Harness "
            f"with: {install_hint}"
        )
    _fail(f"`{name}` not found on PATH. Install it with: {install_hint}")


def _require_agent_for_launch(name: str, install_hint: str, launch: bool) -> Optional[str]:
    if not launch:
        return None
    return _resolve_or_install_agent(name, install_hint, _which_with_install_dirs)


def _wsl_shim_env(
    command: list,
    env: dict,
    unset_env: tuple,
    cwd_env: tuple = (),
) -> tuple[dict, tuple]:
    if not _wsl_windows_executable(command):
        return env, ()
    wsl_env_bridge = _wsl_bridge_names(env, unset_env)
    if not wsl_env_bridge and not cwd_env:
        return env, ()
    # Bridge PWD via WSLENV (PWD/p) so the Windows shim finds its project root from the live cwd, not a stale inherited Linux PWD. Do not freeze env["PWD"]: a --no-launch recipe must translate the live PWD when run, not when generated; _launch overrides it. cwd_env values likewise resolve at execution time and are always filesystem paths.
    return env, tuple(dict.fromkeys((*wsl_env_bridge, *(f"{name}/p" for name in cwd_env), "PWD/p")))


_NPM_CMD_SHIM_HEAD = (
    "@ECHO off\n"
    "GOTO start\n"
    ":find_dp0\n"
    "SET dp0=%~dp0\n"
    "EXIT /b\n"
    ":start\n"
    "SETLOCAL\n"
    "CALL :find_dp0\n"
)
_NPM_NODE_CMD_SHIM_PREFIX = (
    re.escape(_NPM_CMD_SHIM_HEAD)
    + r"(?P<environment>(?:@SET [^=\r\n]+=[^\r\n]+\n)*)"
    + re.escape(
        '\nIF EXIST "%dp0%\\node.exe" (\n'
        + '  SET "_prog=%dp0%\\node.exe"\n'
        + ") ELSE (\n"
        + '  SET "_prog=node"\n'
    )
)
_NPM_NODE_CMD_SHIM_SUFFIX = (
    r"(?P<node_args>[^\r\n]*?)[ \t]+" + r'"%dp0%\\(?P<target>[^"\r\n]+)"[ \t]+%\*'
)
_NPM_NODE_CMD_SHIMS = (
    re.compile(
        _NPM_NODE_CMD_SHIM_PREFIX
        + re.escape(
            "  SET PATHEXT=%PATHEXT:;.JS;=;%\n"
            + ")\n\n"
            + 'endLocal & goto #_undefined_# 2>NUL || title %COMSPEC% & "%_prog%"'
        )
        + _NPM_NODE_CMD_SHIM_SUFFIX,
        re.IGNORECASE,
    ),
    re.compile(
        _NPM_NODE_CMD_SHIM_PREFIX
        + re.escape(
            ")\n\n"
            + "endLocal & goto #_undefined_# 2>NUL || title %COMSPEC% & "
            + "set PATHEXT=%PATHEXT:;.JS;=;% & "
            + '"%_prog%"'
        )
        + _NPM_NODE_CMD_SHIM_SUFFIX,
        re.IGNORECASE,
    ),
)
_NPM_NATIVE_CMD_SHIM = re.compile(
    re.escape(_NPM_CMD_SHIM_HEAD) + r'"%dp0%\\(?P<target>[^"\r\n]+)"[ \t]+%\*',
    re.IGNORECASE,
)
_NPM_NODE_SHEBANG = re.compile(
    r"^#!\s*(?:/usr/bin/env\s+(?:-S\s+)?((?:[^ \t=]+=[^ \t=]+\s+)*))?([^ \t]+)(.*)$"
)
_NPM_SHEBANG_DOLLAR = re.compile(r"\$\{?([^$@#?\- \t{}:]+)\}?")


def _npm_batch_environment(declarations: str) -> str:
    lines = []
    for declaration in declarations.split():
        name, separator, value = declaration.partition("=")
        name = name.strip()
        value = value.strip()
        if separator and name and value:
            value = _NPM_SHEBANG_DOLLAR.sub(lambda match: f"%{match.group(1)}%", value)
            lines.append(f"@SET {name}={value}\n")
    return "".join(lines)


def _windows_expand_environment(value: str, environment: dict) -> str:
    folded = {name.casefold(): item for name, item in environment.items()}
    return re.sub(
        r"%([^%\r\n]+)%",
        lambda match: folded.get(match.group(1).casefold(), ""),
        value,
    )


def _npm_node_shim_metadata(target: Path, match, environment: dict) -> Optional[tuple]:
    environment_block = match.group("environment") or ""
    node_args_text = (match.group("node_args") or "").strip()
    known_node_suffix = target.suffix.lower() in {".js", ".cjs", ".mjs"}
    if not environment_block and not node_args_text and known_node_suffix:
        return [], {}

    first_line = target.read_text(encoding = "utf-8").splitlines()[0]
    shebang = _NPM_NODE_SHEBANG.fullmatch(first_line)
    if shebang is None or Path(shebang.group(2)).name.casefold() not in {"node", "node.exe"}:
        return None
    declarations = shebang.group(1) or ""
    if _npm_batch_environment(declarations).casefold() != environment_block.casefold():
        return None
    if (shebang.group(3) or "").strip() != node_args_text:
        return None
    try:
        node_args = shlex.split(node_args_text) if node_args_text else []
    except ValueError:
        return None

    updates = {}
    expanded_environment = dict(environment)
    for line in environment_block.splitlines():
        name, value = line.removeprefix("@SET ").split("=", 1)
        expanded = _windows_expand_environment(value, expanded_environment)
        expanded_environment[name] = expanded
        updates[name] = expanded
    return node_args, updates


def _apply_windows_environment(environment: dict, updates: dict) -> None:
    for name, value in updates.items():
        existing = next((key for key in environment if key.casefold() == name.casefold()), None)
        if existing is not None and existing != name:
            del environment[existing]
        environment[name] = value


def _resolved_launch_command(
    executable: str,
    arguments: list,
    environment: Optional[dict] = None,
) -> list:
    """Return an argv that preserves arguments through standard Windows npm shims."""
    # _launch resolves with raw shutil.which, so rescue here too; the sibling then enters the parser below.
    executable = _prefer_windows_cmd_sibling(executable)
    if os.name == "nt" and Path(executable).suffix.lower() in {".cmd", ".bat"}:
        # cmd.exe treats CR/LF inside `%*` as command separators, and Windows PowerShell's native-command bridge also rewrites embedded quotes. Match complete cmd-shim templates so custom wrappers keep their setup behavior.
        with contextlib.suppress(OSError, UnicodeError, IndexError):
            shim = Path(executable)
            contents = shim.read_text(encoding = "utf-8").replace("\r\n", "\n").strip()
            for pattern in _NPM_NODE_CMD_SHIMS:
                match = pattern.fullmatch(contents)
                if match is None:
                    continue
                relative = Path(*re.split(r"[\\/]+", match.group("target")))
                target = (shim.parent / relative).resolve()
                if not target.is_file() or not any(
                    part.casefold() == "node_modules" for part in target.parts
                ):
                    continue
                metadata = _npm_node_shim_metadata(target, match, environment or os.environ)
                if metadata is None:
                    continue
                node_args, environment_updates = metadata
                bundled_node = shim.parent / "node.exe"
                node = str(bundled_node) if bundled_node.is_file() else shutil.which("node.exe")
                if node:
                    if environment is not None:
                        _apply_windows_environment(environment, environment_updates)
                    return [node, *node_args, str(target), *arguments]

            match = _NPM_NATIVE_CMD_SHIM.fullmatch(contents)
            if match is not None:
                relative = Path(*re.split(r"[\\/]+", match.group("target")))
                target = (shim.parent / relative).resolve()
                if (
                    target.is_file()
                    and any(part.casefold() == "node_modules" for part in target.parts)
                    and target.suffix.lower() in {".exe", ".com"}
                ):
                    return [str(target), *arguments]
    return [executable, *arguments]


def _launch(
    command: list,
    env: dict,
    install_hint: str,
    unset_env: tuple = (),
    cwd_env: tuple = (),
) -> int:
    # Resolve well-known install dirs (~/.local/bin) first, so an already-installed agent not yet on PATH is found instead of prompting a needless reinstall.
    _augment_path_with_install_dirs()
    executable = _resolve_or_install_agent(command[0], install_hint, shutil.which)
    env, wsl_env_bridge = _wsl_shim_env(command, env, unset_env, cwd_env)
    env = {**env, **{name: os.getcwd() for name in cwd_env}}
    child_env = dict(os.environ)
    if wsl_env_bridge:
        # Override stale inherited PWD with the real cwd so the shim resolves the project root.
        env = {**env, "PWD": os.getcwd()}
        child_env["WSLENV"] = _merge_wslenv(child_env.get("WSLENV", ""), wsl_env_bridge)
        for name in unset_env:
            child_env[name] = ""
    else:
        for name in unset_env:
            child_env.pop(name, None)
    child_env.update(env)
    if os.name != "nt" and not wsl_env_bridge:
        # Keep POSIX child processes from seeing a stale inherited PWD when subprocess cwd was changed by the caller. Some Node CLIs use PWD for project-root discovery instead of process.cwd().
        child_env["PWD"] = os.getcwd()
    # Ctrl+C cancels a turn inside the agent; do not let it kill this wrapper. A no-op handler, not SIG_IGN: exec preserves an ignored signal but resets a caught one.
    previous = signal.signal(signal.SIGINT, lambda *_: None)
    try:
        launch_command = _resolved_launch_command(executable, command[1:], child_env)
        code = subprocess.run(launch_command, env = child_env).returncode
    finally:
        signal.signal(signal.SIGINT, previous)
    # Negative returncode means killed by signal N; shells expect 128+N.
    return code if code >= 0 else 128 - code


_CONNECTION_MODEL_PREFIX = "external::"


def _connection_entry(base: str, key: str, model: Optional[str]) -> Optional[dict]:
    # Studio names a Connection model external::<connection id>::<url-encoded model>; a bare name counts when one enabled Connection lists it and no loaded model has it.
    if not model:
        return None
    explicit = model.startswith(_CONNECTION_MODEL_PREFIX)
    if not explicit and any(
        _model_id_matches(entry.get("id"), name, allow_casefold = is_loopback_url(base))
        for entry in _loaded_models(base, key)
        if entry.get("loaded") is not False
        for name in (model, _split_repo_variant(model)[0])
    ):
        return None
    try:
        providers = _http_json("GET", f"{base}/api/providers/", key)
    except (urllib.error.HTTPError, urllib.error.URLError, TimeoutError) as exc:
        # A 4xx is an older server or a key without Connections; anything else must not fall
        # through to a load that could evict the resident model.
        if explicit or not (isinstance(exc, urllib.error.HTTPError) and exc.code < 500):
            _fail_request(exc, "Couldn't list Connections")
        return None
    enabled = [p for p in providers or [] if isinstance(p, dict) and p.get("is_enabled")]
    if explicit:
        provider_id = model[len(_CONNECTION_MODEL_PREFIX) :].partition("::")[0]
        matches = [p for p in enabled if p.get("id") == provider_id]
        if not matches:
            _fail(f"No enabled Connection {provider_id!r} on {base}. Check Settings → Connections.")
    else:
        matches = [p for p in enabled if model in (p.get("models") or [])]
        if not matches:
            return None
    usable = [p for p in matches if p.get("auth_kind") != "chatgpt_oauth"]
    if not usable:
        _fail(
            f"{model} is on a ChatGPT subscription Connection, which only the Unsloth chat can use."
        )
    if explicit:
        return {"id": model, "connection": usable[0].get("display_name") or usable[0]["id"]}
    ids = [f"{_CONNECTION_MODEL_PREFIX}{p['id']}::{quote(model, safe = '')}" for p in usable]
    if len(ids) > 1:
        _fail(f"{model} is offered by more than one Connection. Pass one of: {', '.join(ids)}")
    return {"id": ids[0], "connection": usable[0].get("display_name") or usable[0]["id"]}


def _connect(
    api_key: Optional[str],
    model: Optional[str],
    load: LoadOptions = LoadOptions(),
    *,
    serve: bool = False,
    launch: bool = True,
    server_options: ServerOptions = ServerOptions(),
    preload_check = None,
    connections: bool = False,
) -> tuple:
    _refuse_npu_model(model)
    requested = model
    explicit_connection = bool(model) and model.startswith(_CONNECTION_MODEL_PREFIX)
    # `--model org/name:QUANT` is shorthand for `--model org/name --gguf-variant QUANT`. Split it before we match or serve so the attach path resolves against the already-loaded `org/name` (listed without the suffix) instead of reloading a `:`-suffixed repo id, which Unsloth rejects and which would evict a model another session is using.
    unsplit = None
    if model and not explicit_connection:
        repo, variant = _split_repo_variant(model)
        if variant:
            unsplit = (model, load)
            model = repo
            if not load.gguf_variant:
                load = load._replace(gguf_variant = variant)
            elif load.gguf_variant.lower() != variant.lower():
                typer.echo(
                    f"Warning: using --gguf-variant {load.gguf_variant} instead of the "
                    f":{variant} in --model.",
                    err = True,
                )
    base, server = _require_studio(
        model,
        load,
        serve = serve and not explicit_connection,
        launch = launch,
        server_options = server_options,
    )
    # The server resolves relative paths against its own cwd; only a local Studio shares our filesystem.
    if model and server is None and is_loopback_url(base) and _is_model_path(model):
        if os.path.exists(os.path.expanduser(model)) and verify_studio_identity(base):
            model = os.path.abspath(os.path.expanduser(model))
    try:
        key = _agent_api_key(base, api_key, auto_started = server is not None)
        # Studio's own ids can carry a tag (ollama/qwen3:8b), so a loaded model of that exact id wins over the split.
        if (
            unsplit
            and server is None
            and any(
                entry.get("loaded") is not False
                and _model_id_matches(
                    entry.get("id"), requested, allow_casefold = is_loopback_url(base)
                )
                for entry in _loaded_models(base, key)
            )
        ):
            model, load = unsplit
        connection = None if server is not None else _connection_entry(base, key, requested)
        if connection is not None:
            if not connections:
                _fail(
                    f"{requested} is a Connection model, and this agent can only use models "
                    "loaded in Unsloth. Connection models work with `unsloth start claude`, "
                    "`unsloth start codex` and `unsloth start opencode`."
                )
            typer.echo(f"Using {requested} from the Connection {connection['connection']}.")
            # A Connection reports no context window; an explicit one lets agents size compaction.
            if load.max_seq_length > 0:
                connection["context_length"] = load.max_seq_length
            else:
                typer.echo(
                    "Pass --max-seq-length with the model's context window so the agent can "
                    "compact before the provider runs out of context.",
                    err = True,
                )
            if (
                key not in _cached_keys(_key_cache_path(), base, "minted")
                and not api_key
                and is_loopback_url(base)
                and verify_studio_identity(base)
            ):
                key = _agent_api_key(base, None, minted_only = True)
            if key not in _cached_keys(_key_cache_path(), base, "minted"):
                typer.echo(
                    "Warning: Unsloth Studio only sends a Connection's saved API key for the key "
                    "`unsloth start` issues, so drop --api-key / UNSLOTH_API_KEY unless this "
                    "Connection needs no key.",
                    err = True,
                )
            return base, key, connection
        # A server we just started has exactly the requested model loaded, so resolve to whatever it is serving instead of re-matching the raw --model string. Only an attach can still trigger an evicting load, so _resolve_model gets the pre-load check and runs it only when that load is imminent.
        entry = _resolve_model(
            base,
            key,
            None if server is not None else model,
            load,
            preload_check = None if server is not None else preload_check,
            # That server was started FROM these knobs, so inferring a target here would reload what was just loaded.
            infer_resident = server is None,
        )
        status = _inference_status(base, key, entry["id"]) if model else {}
        # A GGUF can be active while the resolved entry is another resident model.
        if status.get("memory_warning") and any(
            _model_id_matches(
                (entry or {}).get("id"), status_id, allow_casefold = is_loopback_url(base)
            )
            for status_id in (status.get("active_model"), status.get("model_identifier"))
            if status_id
        ):
            typer.echo(f"Warning: {status['memory_warning']}", err = True)
    except BaseException:
        _shutdown_auto_served()
        raise
    return base, key, entry


def _run(
    base: str,
    entry: dict,
    env: dict,
    command: list,
    *,
    launch: bool,
    install_hint: str,
    unset_env: tuple = (),
    clear_screen: bool = False,
    cwd_env: tuple = (),
) -> None:
    # Some agents (Pi) render inline from wherever the cursor sits: their first paint assumes a clean screen rather than clearing or entering the alternate screen themselves. Hand them one so the session does not start mid-scroll under our connection output. click.clear() is cross-platform and a no-op when stdout is not a terminal, so transcripts and --no-launch recipes stay intact.
    if launch and clear_screen:
        click.clear()
    typer.echo(f"Unsloth ready at {base} · model {entry['id']}")
    if not launch:
        env, wsl_env_bridge = _wsl_shim_env(command, env, unset_env, cwd_env)
        _print_env(
            env,
            command,
            unset_env = unset_env,
            wsl_env_bridge = wsl_env_bridge,
            cwd_env = cwd_env,
        )
        if _keep_auto_served():
            typer.echo(f"Unsloth Studio is still running at {base}.")
            typer.echo("Stop it with: unsloth studio stop")
        return
    try:
        code = _launch(
            command,
            env,
            install_hint = install_hint,
            unset_env = unset_env,
            cwd_env = cwd_env,
        )
    except BaseException:
        # Startup succeeded but the agent failed to launch; tear the server down rather than orphan it.
        _shutdown_auto_served()
        raise
    auto_started = _auto_served_server is not None
    kept = _keep_auto_served()
    if auto_started and not kept:
        typer.echo(f"The auto-started Unsloth server at {base} stopped during the session.")
        raise typer.Exit(code = code)
    if code:
        # The server status below must not read as a successful agent session.
        typer.echo(f"The agent exited with code {code}.")
    if is_loopback_url(base):
        typer.echo(f"Unsloth Studio is still running at {base}.")
        typer.echo("Stop it with: unsloth studio stop")
    else:
        typer.echo(f"The remote Unsloth server is still running at {base}.")
    raise typer.Exit(code = code)


def _agents_config_root() -> Path:
    return _studio_auth_root() / "agents"


@contextlib.contextmanager
def _temporary_agent_config(prefix: str):
    # Nothing else prunes Unsloth's auth tree, so reuse the locked session helper: the next launch reclaims homes left by a killed wrapper, and the lock spares live sessions.
    temp_root = _agents_config_root() / ".tmp"
    with contextlib.ExitStack() as stack:
        try:
            temp_root.mkdir(parents = True, exist_ok = True, mode = 0o700)
            path = stack.enter_context(_short_ephemeral_session(temp_root, prefix))
        except OSError:
            # Attaching to a remote or running Unsloth needs no local auth tree, so it may be absent or unwritable. Fall back to the system temp dir, as before: no reclamation there, but the OS prunes it.
            path = Path(tempfile.mkdtemp(prefix = prefix))
            stack.callback(shutil.rmtree, path, ignore_errors = True)
        yield path


# codex-subagent nests CODEX_HOME under <home>/parent, so it needs the short root too.
_CODEX_SHORT_HOME_AGENTS = ("codex", "codex-subagent")


def _ephemeral_session_parent(agent: str) -> Optional[Path]:
    """Return a non-system-temp parent when an agent needs one."""
    if os.name != "nt" or agent not in _CODEX_SHORT_HOME_AGENTS:
        return None
    # Codex creates a deeply nested curated-plugin checkout below CODEX_HOME. A normal %TEMP%\\unsloth-codex-* home can exceed legacy Windows path limits during startup, and Codex also refuses to create its PATH helpers below the system temp directory. Keep the throwaway home short but still private to the current user; _session_config removes it on exit.
    root = Path.home() / ".unsloth" / ".tmp"
    root.mkdir(parents = True, exist_ok = True, mode = 0o700)
    return root


def _ephemeral_session_prefix(agent: str, parent: Optional[Path]) -> str:
    """Return the platform-specific prefix for an ephemeral agent home."""
    if agent in _CODEX_SHORT_HOME_AGENTS and parent is not None:
        return "u-codex-"
    return f"unsloth-{agent}-"


@contextlib.contextmanager
def _locked_file(path: Path, blocking: bool = True):
    """Yield whether an advisory lock was acquired for the first byte of path."""
    handle = path.open("a+b")
    acquired = False
    try:
        if os.name == "nt":
            import msvcrt

            handle.seek(0, os.SEEK_END)
            if handle.tell() == 0:
                handle.write(b"\0")
                handle.flush()
            handle.seek(0)
            while True:
                try:
                    msvcrt.locking(handle.fileno(), msvcrt.LK_NBLCK, 1)
                    acquired = True
                    break
                except OSError as exc:
                    if exc.errno not in (errno.EACCES, errno.EAGAIN, errno.EDEADLK):
                        raise
                    if not blocking:
                        break
                    # LK_LOCK gives up after roughly ten seconds. Poll LK_NBLCK instead so a large stale plugin checkout cannot make a concurrent launch fail just because cleanup takes longer.
                    time.sleep(0.05)
        else:
            import fcntl
            mode = fcntl.LOCK_EX | (0 if blocking else fcntl.LOCK_NB)
            try:
                fcntl.flock(handle.fileno(), mode)
                acquired = True
            except BlockingIOError:
                acquired = False
        yield acquired
    finally:
        if acquired:
            if os.name == "nt":
                handle.seek(0)
                msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
            else:
                fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
        handle.close()


def _reclaim_stale_ephemeral_sessions(parent: Path, prefix: str) -> None:
    """Remove abandoned session homes while preserving locked live sessions."""
    for path in parent.glob(f"{prefix}*"):
        if not path.is_dir():
            continue
        active_lock = path / ".active.lock"
        try:
            modified = active_lock.stat().st_mtime if active_lock.exists() else path.stat().st_mtime
        except FileNotFoundError:
            continue
        # The wrapper owns the advisory lock, not the Codex child. If only the wrapper is killed, its child may still be using CODEX_HOME; give that process a full day to finish before treating the unlocked home as stale.
        if time.time() - modified < _CODEX_EPHEMERAL_STALE_SECONDS:
            continue
        try:
            with _locked_file(active_lock, blocking = False) as stale:
                pass
        except FileNotFoundError:
            # A normally exiting session may have removed itself after the glob.
            continue
        if stale:
            shutil.rmtree(path, ignore_errors = True)


def _refresh_ephemeral_session_marker(path: Path, stop: threading.Event) -> None:
    """Keep the stale grace period relative to wrapper death, not session start."""
    while not stop.wait(_CODEX_EPHEMERAL_HEARTBEAT_SECONDS):
        with contextlib.suppress(OSError):
            os.utime(path, None)


@contextlib.contextmanager
def _short_ephemeral_session(parent: Path, prefix: str = "u-codex-"):
    """Create a session home whose lock makes crash cleanup concurrency-safe."""
    path = None
    active_lock = contextlib.ExitStack()
    heartbeat_stop = None
    heartbeat = None
    try:
        with _locked_file(parent / ".cleanup.lock") as cleanup_lock:
            if not cleanup_lock:  # The blocking acquisition should always succeed.
                raise RuntimeError(f"Could not lock ephemeral session root: {parent}")
            _reclaim_stale_ephemeral_sessions(parent, prefix)
            path = Path(tempfile.mkdtemp(prefix = prefix, dir = parent))
            locked = active_lock.enter_context(_locked_file(path / ".active.lock"))
            if not locked:
                raise RuntimeError(f"Could not lock ephemeral session home: {path}")
            heartbeat_stop = threading.Event()
            heartbeat = threading.Thread(
                target = _refresh_ephemeral_session_marker,
                args = (path / ".active.lock", heartbeat_stop),
                name = "unsloth-agent-home-heartbeat",
                daemon = True,
            )
            heartbeat.start()
        yield path
    finally:
        if heartbeat_stop is not None:
            heartbeat_stop.set()
        if heartbeat is not None:
            heartbeat.join(timeout = 1)
        try:
            with _locked_file(parent / ".cleanup.lock") as cleanup_lock:
                if not cleanup_lock:  # The blocking acquisition should always succeed.
                    raise RuntimeError(f"Could not lock ephemeral session root: {parent}")
                # Release the live marker only after deletion is serialized with startup scavenging, so no scanner can race this rmtree.
                active_lock.close()
                if path is not None:
                    shutil.rmtree(path, ignore_errors = True)
        finally:
            active_lock.close()


@contextlib.contextmanager
def _session_config(
    agent: str,
    launch: bool,
    persist: bool = False,
):
    """Yield a private directory for an agent's session config (never the user's own). launch (the default) uses an ephemeral temp dir removed after the agent process exits, so nothing persists; no-launch uses a stable Unsloth-owned dir, since the printed recipe is run later on this machine; persist (from --persist) uses that same stable dir even for a launch, so the agent's session survives the exit and can be resumed. Either way the user's real ~/.<agent> config is left untouched."""
    if launch and not persist:
        # Windows codex keeps #7519's short home (MAX_PATH); everyone else uses Unsloth's root.
        parent = _ephemeral_session_parent(agent)
        prefix = _ephemeral_session_prefix(agent, parent)
        if parent is not None:
            with _short_ephemeral_session(parent, prefix) as path:
                yield path
        else:
            with _temporary_agent_config(prefix) as path:
                yield path
    else:
        # Never wipe this dir: a previously printed recipe may still be running an agent whose sessions and state live here, and every config writer merges idempotently into an existing home anyway. Writers must also reset any state a previous run's flags left behind (--yolo especially), since files here outlive the invocation that wrote them.
        path = _agents_config_root() / agent
        path.mkdir(parents = True, exist_ok = True, mode = 0o700)
        yield path


def _studio_embedding_model(base: str, key: str) -> Optional[str]:
    """Studio's configured embedding model, or None when this server cannot say. Not a model name: a name this server will not serve, beside fallback "none", is the one combination OpenClaw cannot degrade out of, so the caller writes provider "none" instead."""
    try:
        info = _http_json("GET", f"{base}/api/settings/embedding-model", key, timeout = 10)
    # typer.Exit is a RuntimeError subclass: the broad catch would swallow a deliberate abort.
    except (typer.Exit, typer.Abort, click.exceptions.Exit, click.exceptions.Abort):
        raise
    except Exception:  # noqa: BLE001 - an older or unreachable server still gets a working config
        return None
    name = info.get("embedding_model") if isinstance(info, dict) else None
    if not isinstance(name, str) or not name.strip():
        return None
    # OpenClaw sends this to /v1/embeddings verbatim; Settings stores what was typed.
    return name.strip()


def _openclaw_provider(
    base: str,
    key: str,
    model: dict,
    max_tokens: Optional[int] = None,
    vision: bool = False,
) -> dict:
    # Unsloth is a generic OpenAI-compatible /v1 endpoint (the vLLM/LM Studio path).
    provider_model = {"id": model["id"], "name": model["id"]}
    if vision:
        provider_model["input"] = ["text", "image"]
    window = model.get("context_length") or model.get("max_context_length")
    if window:
        window = int(window)
        provider_model["contextWindow"] = window
        # Unset, OpenClaw caps every reply at 8192 (DEFAULT_MODEL_MAX_TOKENS) whatever the window.
        provider_model["maxTokens"] = _agent_output_limit(window, max_tokens)
    elif max_tokens:
        provider_model["maxTokens"] = max_tokens
    return {
        "baseUrl": f"{base}/v1",
        "apiKey": key,
        "api": "openai-completions",
        "models": [provider_model],
    }


def _openclaw_doctor_command(path: Path, *, windows: bool) -> str:
    """`openclaw doctor --fix` against Unsloth's managed config, in the user's shell syntax."""
    env = {"OPENCLAW_CONFIG_PATH": str(path), "OPENCLAW_STATE_DIR": str(path.parent)}
    if windows:
        sets = "; ".join(
            f'$env:{name} = "{value.replace("`", "``").replace(chr(34), "`" + chr(34)).replace("$", "`$")}"'
            for name, value in env.items()
        )
        return f"{sets}; openclaw doctor --fix"
    inline = " ".join(f"{name}={shlex.quote(value)}" for name, value in env.items())
    return f"{inline} openclaw doctor --fix"


def write_openclaw_config(
    base: str,
    key: str,
    model: dict,
    path: Path,
    yolo: bool = False,
    workspace_path: Optional[str] = None,
    embedding_model: Optional[str] = None,
    request_body: Optional[dict] = None,
    max_tokens: Optional[int] = None,
    vision: bool = False,
) -> None:
    config = _read_json_object(path)
    if config is None:
        typer.echo(
            f"Warning: couldn't parse {path} — add an 'unsloth' provider there "
            "yourself, or move the file aside and re-run.",
            err = True,
        )
        return
    before = json.dumps(config, sort_keys = True)
    models = _subdict(config, "models")
    models.setdefault("mode", "merge")
    _subdict(models, "providers")["unsloth"] = _openclaw_provider(
        base, key, model, max_tokens, vision
    )
    # Memory search is on by default and defaults to openai, so a local session reaches OpenAI unless this block is written.
    search = _subdict(_subdict(config, "memory"), "search")
    if embedding_model:
        search.update(
            {
                "provider": "openai-compatible",
                "model": embedding_model,
                "fallback": "none",
                "remote": {"baseUrl": f"{base}/v1", "apiKey": key},
            }
        )
    else:
        # "none" is OpenClaw's keyword-only mode: no network call, and search still returns hits. Clearing the remote stops a reused --persist config aiming at a dead endpoint.
        search.update({"provider": "none", "fallback": "none"})
        search.pop("model", None)
        search.pop("remote", None)
    # ORed with OPENCLAW_LOAD_SHELL_ENV: a persisted true re-enables the login-shell key import.
    _subdict(_subdict(config, "env"), "shellEnv")["enabled"] = False
    # Pin a default model, else OpenClaw drops into its setup agent ("no models available").
    agents = _subdict(config, "agents")
    defaults = _subdict(agents, "defaults")
    _subdict(defaults, "model")["primary"] = f"unsloth/{model['id']}"
    # OpenClaw applies extra_body last; its own params only read camelCase keys, so top_p would be lost.
    model_ref = f"unsloth/{model['id']}"
    model_settings = defaults.get("models")
    if request_body or (isinstance(model_settings, dict) and model_ref in model_settings):
        params = _subdict(_subdict(_subdict(defaults, "models"), model_ref), "params")
        _merge_request_body(params, "extra_body", request_body or {})
    # `unsloth start openclaw` is a coding-agent entry point, so the selected project may already contain its own AGENTS.md and git metadata. Do not seed OpenClaw's personal-assistant bootstrap files or initialize a repository in it.
    defaults["skipBootstrap"] = True
    # OPENCLAW_STATE_DIR does not relocate the workspace. Callers normally pin it to the directory where `unsloth start openclaw` was invoked so OpenClaw edits the same project as every other coding agent. Keep the managed fallback for direct config-writer callers that do not provide an explicit workspace.
    if workspace_path is None:
        workspace = path.parent / "workspace"
        workspace.mkdir(parents = True, exist_ok = True, mode = 0o700)
        workspace_path = str(workspace)
    defaults["workspace"] = workspace_path
    # Per-agent paths override agents.defaults.workspace and OPENCLAW_STATE_DIR. This config is itself an isolated Unsloth copy, so remove stale explicit paths and let OpenClaw resolve every listed agent beneath the managed defaults/state directory.
    # OpenClaw 2026.10.1 keys agents by id under agents.entries; older configs carry an agents.list array.
    agent_list = agents.get("list")
    agent_entries = agents.get("entries")
    listed = list(agent_list) if isinstance(agent_list, list) else []
    if isinstance(agent_entries, dict):
        listed += list(agent_entries.values())
    for agent_config in listed:
        if isinstance(agent_config, dict):
            agent_config.pop("workspace", None)
            agent_config.pop("agentDir", None)
    if isinstance(agent_list, list):
        # 2026.10.1 rejects agents.list. Converting it (id normalization, ownership, channel bindings,
        # workspace pins) is OpenClaw's own migration, so point at it rather than half-reimplement it.
        typer.echo(
            f"Note: {path} still has the legacy agents.list, which OpenClaw 2026.10.1+ rejects. "
            f"Migrate it with: {_openclaw_doctor_command(path, windows = os.name == 'nt')}",
            err = True,
        )
    # Unauthenticated loopback gateway: without auth.mode=none the client will not open the websocket. The daemon must still be started separately (`openclaw gateway`).
    gateway = _subdict(config, "gateway")
    gateway.setdefault("mode", "local")
    _subdict(gateway, "auth").setdefault("mode", "none")
    if yolo:
        # OpenClaw has no --yolo flag. Its host approvals document (SQLite since 2026.8.1) falls back to tools.exec for omitted fields, so the config side is enough.
        exec_policy = _subdict(_subdict(config, "tools"), "exec")
        exec_policy["host"] = "gateway"
        exec_policy["security"] = "full"
        exec_policy["ask"] = "off"
    else:
        # The no-launch config dir is reused across runs, so a previous --yolo run may have left auto-approval state behind. OpenClaw treats an omitted exec policy as security=full, ask=off on the gateway host, so deleting the keys would keep auto-approval on: a non-yolo run must WRITE a prompting policy. Only a permissive/yolo policy is replaced; a stricter one set by hand survives.
        tools = config.get("tools")
        exec_policy = tools.get("exec") if isinstance(tools, dict) else None
        exec_policy = exec_policy if isinstance(exec_policy, dict) else {}
        # Match ONLY the exact fingerprint --yolo writes (host=gateway, security=full, ask=off, all explicit, no mode); anything else is left untouched. host=auto or an omitted host resolves to security=deny under an active sandbox, so treating those as the permissive gateway default would broaden a fresh sandboxed config from deny to allowlist. host=node and host=sandbox are user-set (--yolo only writes gateway). tools.exec.mode is OpenClaw's normalized knob, cannot be combined with security/ask, and OpenClaw never rewrites our security/ask write into it, so a mode is always a deliberate user policy; never clobber it.
        permissive = (
            "mode" not in exec_policy
            and exec_policy.get("host") == "gateway"
            and exec_policy.get("security") == "full"
            and exec_policy.get("ask") == "off"
        )
        if permissive:
            exec_policy = _subdict(_subdict(config, "tools"), "exec")
            exec_policy.pop("host", None)  # routing only; defaults to the gateway host
            exec_policy["security"] = "allowlist"  # only allowlisted commands skip approval
            exec_policy["ask"] = "on-miss"  # prompt on every non-allowlisted command
    # Older Unsloth wrote --yolo defaults here; OpenClaw 2026.8.1+ refuses every run while this legacy file exists, so drop ours in both modes and keep any other policy.
    approvals = path.parent / "exec-approvals.json"
    if approvals.exists():
        state = _read_json_object(approvals)
        if state is not None:
            defaults = state.get("defaults")
            # Exact yolo fingerprint only: a user policy merely sharing askFallback=full must survive.
            yolo_defaults = (("security", "full"), ("ask", "off"), ("askFallback", "full"))
            is_yolo = isinstance(defaults, dict) and all(
                defaults.get(k) == v for k, v in yolo_defaults
            )
            if is_yolo:
                for k, _ in yolo_defaults:
                    del defaults[k]
                if not defaults:
                    del state["defaults"]
                # Socket metadata and an empty agents map carry no policy (doctor retires such a stub too).
                if all(
                    k in ("version", "socket") or (k == "agents" and not v)
                    for k, v in state.items()
                ):
                    approvals.unlink()
                    typer.echo(f"Removed {approvals}")
                else:
                    _write_private_json(approvals, state)
                    typer.echo(f"Updated {approvals}")
    if approvals.exists():
        # The rest is user policy; importing it is OpenClaw's migration, not ours.
        typer.echo(
            f"Note: {approvals} is a legacy exec approvals file, which OpenClaw 2026.8.1+ refuses to run with. "
            f"Import it with: {_openclaw_doctor_command(path, windows = os.name == 'nt')}",
            err = True,
        )
    if json.dumps(config, sort_keys = True) != before:
        _write_private_json(path, config)
        typer.echo(f"Updated {path}")


def opencode_output_limit(window: int, max_tokens: Optional[int] = None) -> int:
    if max_tokens:
        return max(1, min(int(max_tokens), window // 2))
    return max(1, min(window // 4, _OPENCODE_OUTPUT_TOKEN_MAX))


def _agent_output_limit(window: int, max_tokens: Optional[int]) -> int:
    output = opencode_output_limit(window, max_tokens)
    if max_tokens and output < max_tokens:
        typer.echo(
            f"Warning: --max-tokens {max_tokens} leaves too little of the {window:,}-token "
            f"context for the conversation; using {output:,}.",
            err = True,
        )
    return output


def opencode_compaction_reserved(window: int, output: int) -> int:
    return max(1, min(output, max(window // 10, 8192)))


def _agent_compacts_at(
    agent: str,
    window: int,
    max_tokens: Optional[int] = None,
) -> int:
    if agent == "claude":
        output = min(opencode_output_limit(window), _CLAUDE_COMPACT_OUTPUT_RESERVE)
        return min(window * 9 // 10, window - output - _CLAUDE_COMPACT_BUFFER)
    return window - opencode_compaction_reserved(window, opencode_output_limit(window, max_tokens))


_CLAUDE_RESUME_ARGS = ({"-c", "--continue", "--fork-session"}, {"-r", "--resume", "--session-id"})
_OPENCODE_RESUME_ARGS = ({"-c", "--continue", "--fork", "--no-replay"}, {"-s", "--session"})


def _only_resumes(args: list, resume_args: tuple) -> bool:
    """True when the forwarded args only reopen an interactive session, which keeps the stock prompt."""
    flags, valued = resume_args
    rest = list(args)
    while rest:
        arg = rest.pop(0)
        name = arg.split("=", 1)[0]
        if name in flags:
            continue
        if name not in valued:
            return False
        if "=" not in arg and rest and not rest[0].startswith("-"):
            rest.pop(0)
    return True


def _early_context_check(model: Optional[str], check):
    """Run check now, or return it for _before_load when a running Studio could resolve model to a Connection."""
    # A Connection is only known once _connect asks that server, and it never loads; an auto-started one serves no Connections.
    if model and find_studio_server() is not None:
        return check
    check()
    return None


def _before_load(context_check, preload = None):
    if context_check is None:
        return preload

    def check(base, key, requested, gguf_variant):
        context_check()
        if preload is not None:
            preload(base, key, requested, gguf_variant)

    return check


def _command_line_options(ctx, quote) -> Optional[list]:
    """The options typed on this command line, minus --max-seq-length and --api-key."""
    # Duck-typed: typer may vendor its own click, so isinstance / enum identity against ours fails.
    if ctx is None:
        return None
    parts = []
    for param in ctx.command.params:
        if param.param_type_name != "option" or param.name in ("max_seq_length", "api_key"):
            continue
        if getattr(ctx.get_parameter_source(param.name), "name", None) != "COMMANDLINE":
            continue
        value = ctx.params.get(param.name)
        if param.is_flag:
            if value:
                parts.append(param.opts[0])
            elif param.secondary_opts:
                parts.append(param.secondary_opts[0])
            continue
        for item in value if param.multiple else [value]:
            if item is not None:
                item = getattr(item, "value", item)
                parts += [param.opts[0], quote(str(item))]
    return parts


def _check_agent_context(
    agent: str,
    name: str,
    entry: dict,
    prompt_tokens: int,
    max_tokens: Optional[int] = None,
    loaded: bool = True,
    refuse: bool = True,
    model: Optional[str] = None,
    gguf_variant: Optional[str] = None,
    ctx = None,
) -> None:
    window = entry.get("context_length") or entry.get("max_context_length")
    if not window:
        return
    window = int(window)
    roomy = 2 * prompt_tokens
    compacts_at = _agent_compacts_at(agent, window, max_tokens)
    # Before the load only refuse; the window Studio actually fits is checked again after it.
    if compacts_at >= roomy or (not loaded and (compacts_at >= prompt_tokens or not refuse)):
        return
    suggested = next(
        (
            size
            for size in (1 << bits for bits in range(14, 21))
            if _agent_compacts_at(agent, size, max_tokens) >= roomy
        ),
        1 << 20,
    )
    native = int(entry.get("native_context_length") or 0)
    if native:
        suggested = min(suggested, native)
    if entry.get("connection"):
        # --max-seq-length only labels a Connection's window; it cannot grow the provider's.
        hint = "A Connection's context is set by its provider, so pick a model with a longer one."
    elif native and (
        native <= window or _agent_compacts_at(agent, native, max_tokens) < prompt_tokens
    ):
        hint = f"Its full context is {native:,} tokens, so pick a model with a longer one."
    else:
        quote = _powershell_quote if os.name == "nt" else shlex.quote
        given = _command_line_options(ctx, quote) or []
        # A positional org/name (or none at all, outside a command) never reaches the option sources.
        if model and not {"--model", "-m"} & set(given):
            given = ["--model", quote(model), *given]
        if gguf_variant and "--gguf-variant" not in given:
            given += ["--gguf-variant", quote(gguf_variant)]
        if max_tokens and "--max-tokens" not in given:
            given += ["--max-tokens", str(int(max_tokens))]
        if ctx is not None and ctx.get_parameter_source("api_key").name == "COMMANDLINE":
            # Not remembered yet before the load; never echo the key itself.
            given += ["--api-key", "<your key>"]
        forwarded = list(ctx.args) if ctx is not None else []
        target = "".join(f" {part}" for part in given)
        # Only a refused launch's args (none, or resume flags) are echoed: scripted ones can carry a prompt.
        if refuse:
            tail = "".join(f" {quote(arg)}" for arg in forwarded)
        else:
            tail = " plus your other arguments" if forwarded else ""
        hint = (
            f"Run unsloth start {agent}{target} --max-seq-length {suggested}{tail} "
            "(a smaller quant if that does not fit in memory"
            + ("" if loaded else "; for a Connection, a model with a longer context")
            + ")."
        )
    state = "is loaded" if loaded else "would load"
    if compacts_at < prompt_tokens:
        message = (
            f"{entry['id']} {state} with {window:,} tokens of context, too few for {name}: "
            f"its own instructions and tools take about {prompt_tokens:,}, so it would compact "
            f"on every message. {hint}"
        )
        if refuse:
            _fail(message)
        typer.echo(f"Warning: {message}", err = True)
        return
    typer.echo(
        f"Warning: {entry['id']} {state} with {window:,} tokens of context, and {name}'s "
        f"instructions and tools take about {prompt_tokens:,} of it (more with MCP servers), "
        f"so it will compact often. {hint}",
        err = True,
    )


def _opencode_output_env(model: dict, max_tokens: Optional[int]) -> dict:
    """Lift OpenCode's output ceiling when --max-tokens exceeds it; re-emit an inherited one so a --no-launch recipe keeps it."""
    window = model.get("context_length") or model.get("max_context_length")
    if not max_tokens:
        return {}
    if not window:
        typer.echo(
            "Warning: Unsloth Studio did not report the model's context length, so --max-tokens is ignored.",
            err = True,
        )
        return {}
    output = _agent_output_limit(int(window), max_tokens)
    raw = os.environ.get(_OPENCODE_OUTPUT_TOKEN_MAX_ENV, "")
    inherited = int(raw) if raw.isdigit() and int(raw) > 0 else None
    ceiling = inherited or _OPENCODE_OUTPUT_TOKEN_MAX
    if output <= ceiling and inherited is None:
        return {}
    return {_OPENCODE_OUTPUT_TOKEN_MAX_ENV: str(max(output, ceiling))}


def _opencode_provider(
    base: str,
    key: str,
    model: dict,
    max_tokens: Optional[int] = None,
    request_body: Optional[dict] = None,
    vision: bool = False,
) -> dict:
    model_entry = {"name": model["id"]}
    if vision:
        model_entry["attachment"] = True
        model_entry["modalities"] = {"input": ["text", "image"], "output": ["text"]}
    window = model.get("context_length") or model.get("max_context_length")
    if window:
        window = int(window)
        output = opencode_output_limit(window, max_tokens)
        # Without a limit OpenCode assumes context 0 and never compacts. Without input it compacts at context - output and ignores compaction.reserved.
        model_entry["limit"] = {"context": window, "input": window, "output": output}
    provider_options = {"baseURL": f"{base}/v1", "apiKey": key}
    if request_body:
        # OpenCode 1.x sends model options, reading the effort only as reasoningEffort; 2.x sends only the provider body.
        model_entry["options"] = {
            "reasoningEffort" if name == "reasoning_effort" else name: value
            for name, value in request_body.items()
        }
        if "temperature" in request_body:
            model_entry["temperature"] = True
        provider_options["body"] = request_body
    return {
        "npm": "@ai-sdk/openai-compatible",
        "name": "Unsloth Studio",
        "options": provider_options,
        "models": {model["id"]: model_entry},
    }


def write_opencode_config(
    base: str,
    key: str,
    model: dict,
    path: Path,
    yolo: bool = False,
    as_subagent: bool = False,
    max_tokens: Optional[int] = None,
    request_body: Optional[dict] = None,
    vision: bool = False,
) -> dict:
    config = _read_json_object(path)
    if config is None:
        typer.echo(
            f"Warning: couldn't parse {path} — add an '{_OPENCODE_PROVIDER}' provider "
            "there yourself, or move the file aside and re-run.",
            err = True,
        )
        return {}
    before = json.dumps(config, sort_keys = True)
    config.setdefault("$schema", "https://opencode.ai/config.json")
    window = model.get("context_length") or model.get("max_context_length")
    reserved = None
    if window:
        window = int(window)
        reserved = opencode_compaction_reserved(window, opencode_output_limit(window, max_tokens))
    # Keep the provider definition in this private session file. The launch path adjusts effective provider filters in the higher-priority inline overlay.
    _subdict(config, "provider")[_OPENCODE_PROVIDER] = _opencode_provider(
        base, key, model, max_tokens, request_body, vision
    )
    # Normal mode pins this as the session model. Subagent mode leaves the user's main/small models alone and exposes the local model to @unsloth and /models.
    opencode_model = f"{_OPENCODE_PROVIDER}/{model['id']}"
    if as_subagent:
        for field in ("model", "small_model"):
            if str(config.get(field) or "").startswith(f"{_OPENCODE_PROVIDER}/"):
                config.pop(field, None)
        # Drop a managed compaction block, current or legacy value.
        managed = {reserved, max(1, window // 10)} if window else set()
        compaction = config.get("compaction")
        if (
            isinstance(compaction, dict)
            and compaction.keys() == {"auto", "reserved"}
            and compaction["auto"] is True
            and compaction["reserved"] in managed
        ):
            config.pop("compaction", None)
        _subdict(config, "agent")[_SUBAGENT_NAME] = {
            "description": _SUBAGENT_DESCRIPTION,
            "mode": "subagent",
            "model": opencode_model,
            "prompt": _SUBAGENT_INSTRUCTIONS,
        }
    else:
        config["model"] = opencode_model
        agents = config.get("agent")
        if isinstance(agents, dict):
            agents.pop(_SUBAGENT_NAME, None)
            if not agents:
                config.pop("agent", None)
    if window and not as_subagent:
        # The fixed 20k-token default buffer over-compacts, or never settles, on a small local context.
        compaction = _subdict(config, "compaction")
        compaction["auto"] = True
        compaction["reserved"] = reserved
    tools = ("edit", "bash", "webfetch", *(("task",) if as_subagent else ()))
    if yolo:
        # Fallback for commands without native --auto and for the append-safe bare --no-launch command, where the subcommand is not known yet. Rides inline (OPENCODE_CONFIG_CONTENT) so it wins over a project config. TUI and `run` launches use --auto and call here with yolo=False, letting OpenCode preserve explicit deny rules.
        session_permission = {t: "allow" for t in tools}
        session_permission["external_directory"] = {"*": "allow"}
        config["permission"] = dict(session_permission)
    else:
        # Undo only what --yolo wrote: our yolo sets an explicit per-tool "allow" for these three tools, so flip exactly those explicit allows back to "ask". A "deny"/"ask", a granular object, a string, or a "*" catch-all is the user's own rule and is left untouched. We do NOT carry a permission inline for a non-yolo session: since OPENCODE_CONFIG_CONTENT outranks the project opencode.json we cannot read, any value forced there would override the user's project rules, weakening a project deny or auto-approving through a granular object's permissive default. Clearing our own persisted yolo state is the fix.
        session_permission: dict = {}
        permission = config.get("permission")
        if isinstance(permission, dict):
            for tool in tools:
                if permission.get(tool) == "allow":
                    permission[tool] = "ask"
            if permission.get("external_directory") == {"*": "allow"}:
                permission["external_directory"] = {"*": "ask"}
    if json.dumps(config, sort_keys = True) != before:
        _write_private_json(path, config)
        typer.echo(f"Updated {path}")
    return session_permission


def _set_hermes_provider(
    config: dict,
    base: str,
    model: dict,
    request_body: Optional[dict] = None,
) -> None:
    # Hermes only reads the key for a NAMED custom provider (a bare `provider: custom` ignores it), so register it under providers.*.
    _subdict(config, "model").update(
        provider = f"custom:{_HERMES_PROVIDER}",
        default = model["id"],
        api_mode = "openai",
    )
    window = model.get("context_length") or model.get("max_context_length")
    if window:
        window = int(window)
        # A --persist home keeps what an earlier run pinned for another window.
        _subdict(config, "compression").pop("threshold_tokens", None)
        stale = config.get("auxiliary")
        stale = stale.get("compression") if isinstance(stale, dict) else None
        if isinstance(stale, dict) and stale.get("context_length") == _HERMES_MIN_CONTEXT:
            del stale["context_length"]
        # Hermes auto-detects context from GET /v1/models, but OpenAI's schema has no context field, so it can fall back to a 256k default that overflows a small local model. Pin the real window (top-level model.context_length is the highest-priority override) and compact at 90% of it (Hermes defaults to 50%).
        if window >= _HERMES_MIN_CONTEXT:
            _subdict(config, "model")["context_length"] = window
            if config["model"].get("ollama_num_ctx") == _HERMES_MIN_CONTEXT:
                del config["model"]["ollama_num_ctx"]
            _subdict(config, "compression").update(enabled = True, threshold = 0.9)
        else:
            # Below Hermes' 64,000-token floor it refuses to initialize, so claim the floor and shrink the threshold so compaction still fires at 90% of the REAL window (the threshold is a fraction of the claimed context_length). The auxiliary override keeps the same floor check from rejecting the compression model mid-session.
            _subdict(config, "model")["context_length"] = _HERMES_MIN_CONTEXT
            # Current Hermes refuses a local server below its floor unless ollama_num_ctx claims it; context_length alone no longer passes.
            _subdict(config, "model")["ollama_num_ctx"] = _HERMES_MIN_CONTEXT
            threshold = round(0.9 * window / _HERMES_MIN_CONTEXT, 4)
            # Hermes raises thresholds under 0.75 below 512K; threshold_tokens is the cap it still honors.
            _subdict(config, "compression").update(
                enabled = True, threshold = threshold, threshold_tokens = int(0.9 * window)
            )
            auxiliary = _subdict(_subdict(config, "auxiliary"), "compression")
            auxiliary["context_length"] = _HERMES_MIN_CONTEXT
    providers = _subdict(config, "providers")
    legacy = providers.get(_HERMES_LEGACY_PROVIDER)
    if isinstance(legacy, dict) and legacy.get("key_env") == _HERMES_ENV_KEY:
        del providers[_HERMES_LEGACY_PROVIDER]
    # Merge, not replace: Hermes refuses to resume a session once a field it froze on this entry (a user's api_key) is gone.
    provider = _subdict(providers, _HERMES_PROVIDER)
    provider.update(base_url = f"{base}/v1", api_mode = "openai", key_env = _HERMES_ENV_KEY)
    if request_body:
        provider["extra_body"] = request_body
    else:
        provider.pop("extra_body", None)


def _hermes_mcp_manifest(home: Path) -> tuple:
    try:
        state = json.loads((home / _HERMES_MCP_MANIFEST).read_text(encoding = "utf-8"))
        origin, servers = state.get("origin"), set(state["servers"])
        owned = set(state.get("env", ()))
    except (OSError, ValueError, TypeError, KeyError, AttributeError):
        return None, set(), set()
    return (origin if isinstance(origin, str) else None), servers, owned


def _hermes_mcp_servers(home: Path) -> Optional[dict]:
    import yaml

    try:
        config = yaml.safe_load((home / "config.yaml").read_text(encoding = "utf-8"))
    except OSError:
        return {}
    except (yaml.YAMLError, ValueError):
        return None
    servers = config.get("mcp_servers") if isinstance(config, dict) else None
    return servers if isinstance(servers, dict) else {}


def _with_user_hermes_mcp_servers(config: dict, home: Path) -> None:
    home_key = home.resolve(strict = False)
    configured = os.environ.get("HERMES_HOME", "").strip()
    built = None
    if configured:
        configured = str(Path(configured).expanduser().resolve(strict = False))
        origin = _hermes_mcp_manifest(Path(configured))[0]
        if origin is not None:
            # A home Unsloth built (the recipe exports HERMES_HOME=home) points back at its origin.
            built, configured = Path(configured), origin
    source = _hermes_user_home(configured)
    if source.resolve(strict = False) == home_key:
        configured = ""
        source = _hermes_user_home()
        if source.resolve(strict = False) == home_key:
            return
    servers = _hermes_mcp_servers(source)
    if servers is None:
        return
    if built is not None and built.resolve(strict = False) != home_key:
        # Servers added in that saved home (hermes mcp add in the recipe shell); the origin wins a clash.
        inherited = _hermes_mcp_manifest(built)[1]
        local = _hermes_mcp_servers(built) or {}
        servers = {
            **{n: v for n, v in local.items() if n not in inherited and n not in servers},
            **servers,
        }
    carried = _hermes_mcp_manifest(home)[1]
    current = config.get("mcp_servers")
    # Only replace what came from the user's config; servers added in this home stay.
    kept = {
        name: spec
        for name, spec in (current.items() if isinstance(current, dict) else ())
        if name not in carried and name not in servers
    }
    if kept or servers:
        config["mcp_servers"] = {**kept, **servers}
    else:
        config.pop("mcp_servers", None)
    sources = ((source, set()), (built, _hermes_mcp_manifest(built)[2] if built else set()))
    owned = _carry_hermes_mcp_env(home, config.get("mcp_servers", {}), sources)
    (home / _HERMES_MCP_MANIFEST).write_text(
        json.dumps({"origin": configured, "servers": sorted(servers), "env": owned}) + "\n",
        encoding = "utf-8",
    )


def _hermes_env_key(line: str) -> str:
    return line.strip().removeprefix("export ").partition("=")[0].strip()


def _carry_hermes_mcp_env(home: Path, servers: dict, sources: tuple) -> list:
    # Hermes fills ${VAR} in mcp_servers from HERMES_HOME/.env (hermes mcp add --auth bearer keeps tokens there): copy only those lines, verbatim, so Hermes parses them itself.
    path = home / ".env"
    try:
        current = path.read_text(encoding = "utf-8").splitlines()
    except (OSError, ValueError):
        current = []
    owned = _hermes_mcp_manifest(home)[2]
    found = {_hermes_env_key(line) for line in current} - owned
    wanted = set()
    for ref in re.findall(r"\$\{([^}]+)\}", json.dumps(servers)):
        ref = ref.strip()
        wanted.add(ref[4:].strip() if ref.startswith("env:") else ref)
    carried, local = [], set(found)
    # A saved home's own copies are skipped so a key removed at the origin stays removed.
    for source, skip in sources:
        if source is None or source.resolve(strict = False) == home.resolve(strict = False):
            continue
        try:
            lines = (source / ".env").read_text(encoding = "utf-8").splitlines()
        except (OSError, ValueError):
            continue
        keys = {_hermes_env_key(line) for line in lines} & (wanted - found - skip)
        carried += [line for line in lines if _hermes_env_key(line) in keys]
        found |= keys
    lines = [line for line in current if _hermes_env_key(line) in local] + carried
    if lines != current:
        if lines:
            fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
            with os.fdopen(fd, "w", encoding = "utf-8") as handle:
                handle.write("\n".join(lines) + "\n")
        else:
            path.unlink(missing_ok = True)
    return sorted(found - local)


def write_hermes_config(
    base: str,
    model: dict,
    path: Path,
    request_body: Optional[dict] = None,
    keep_mcp_servers: bool = False,
) -> None:
    import yaml

    config: dict = {}
    if path.exists():
        try:
            loaded = yaml.safe_load(path.read_text(encoding = "utf-8"))
        except (yaml.YAMLError, OSError):
            typer.echo(
                f"Warning: couldn't parse {path} — configure the custom endpoint "
                "there yourself, or move the file aside and re-run.",
                err = True,
            )
            return
        if isinstance(loaded, dict):
            config = loaded
        elif loaded is not None:
            # Non-empty, non-mapping YAML is a user-managed file; leave it.
            typer.echo(
                f"Warning: couldn't parse {path} — configure the custom endpoint "
                "there yourself, or move the file aside and re-run.",
                err = True,
            )
            return
    _set_hermes_provider(config, base, model, request_body)
    if keep_mcp_servers:
        _with_user_hermes_mcp_servers(config, path.parent)
    text = yaml.safe_dump(config, sort_keys = False)
    if not path.exists() or path.read_text(encoding = "utf-8") != text:
        path.parent.mkdir(parents = True, exist_ok = True)
        path.write_text(text, encoding = "utf-8")
        typer.echo(f"Updated {path}")


def _vibe_env(
    base: str,
    model: dict,
    request_body: Optional[dict] = None,
    vision: bool = False,
) -> dict:
    """VIBE_* env vars outrank config.toml, so the user's Vibe config is never written."""
    entry = {"name": model["id"], "provider": _VIBE_PROVIDER, "alias": _VIBE_MODEL_ALIAS}
    if vision:
        entry["supports_images"] = True
    # Vibe sends its own temperature (0.2 by default) with every request.
    temperature = (request_body or {}).get("temperature")
    if temperature is not None:
        entry["temperature"] = float(temperature)
    window = model.get("context_length") or model.get("max_context_length")
    if window:
        window = int(window)
        entry["max_context_length"] = window
        # Vibe's 200k default is past most local windows; Vibe 3 needs min(24k, window / 4) free.
        entry["auto_compact_threshold"] = min(
            int(window * 0.9), window - min(24_000, math.ceil(window / 4))
        )
    provider = {
        "name": _VIBE_PROVIDER,
        "api_base": f"{base}/v1",
        "api_key_env_var": _VIBE_ENV_KEY,
        "api_style": "openai",
        "backend": "generic",
    }
    return {
        "VIBE_PROVIDERS": json.dumps([provider]),
        "VIBE_MODELS": json.dumps([entry]),
        "VIBE_ACTIVE_MODEL": _VIBE_MODEL_ALIAS,
        # An inherited allowlist or resumed cloud session would select a hosted model.
        "VIBE_ALLOWED_MODELS": json.dumps(["re:" + re.escape(model["id"])]),
        "VIBE_ENABLE_TELEMETRY": "false",
        "VIBE_ENABLE_UPDATE_CHECKS": "false",
        "VIBE_ENABLE_AUTO_UPDATE": "false",
        "VIBE_ENABLE_NOTIFICATIONS": "false",
    }


def write_pi_config(
    base: str,
    key: str,
    model: dict,
    path: Path,
    *,
    max_tokens: Optional[int] = None,
    request_body: Optional[dict] = None,
    vision: bool = False,
) -> None:
    config = _read_json_object(path)
    if config is None:
        typer.echo(
            f"Warning: couldn't parse {path} — add an 'unsloth' provider there "
            "yourself, or move the file aside and re-run.",
            err = True,
        )
        return
    before = json.dumps(config, sort_keys = True)
    # Pi reads custom providers from $PI_CODING_AGENT_DIR/models.json; the key lives there, not in the env, matching openclaw/opencode.
    provider_model = {"id": model["id"]}
    if vision:
        provider_model["input"] = ["text", "image"]
    window = model.get("context_length") or model.get("max_context_length")
    if window:
        window = int(window)
        # An unspecified model defaults to contextWindow 128000 / maxTokens 16384, far larger than a small Unsloth context, so Pi compacts too late and overflows the server. Pin the real window and a sane output cap, mirroring OpenCode.
        provider_model["contextWindow"] = window
        provider_model["maxTokens"] = _agent_output_limit(window, max_tokens)
    elif max_tokens:
        provider_model["maxTokens"] = max_tokens
    if request_body:
        provider_model["samplingParams"] = request_body
    _subdict(config, "providers")[_PI_PROVIDER] = {
        "api": "openai-completions",
        "baseUrl": f"{base}/v1",
        "apiKey": key,
        "models": [provider_model],
    }
    if json.dumps(config, sort_keys = True) != before:
        _write_private_json(path, config)
        typer.echo(f"Updated {path}")


def _link_user_dir(source: Path, target: Path) -> bool:
    """Expose source at target. True once target resolves to source."""
    # Refresh links, but preserve real session directories.
    if target.is_symlink() or _is_junction(target):
        _remove_overlay_entry(target)
    if target.exists() or not source.is_dir():
        return False
    target.parent.mkdir(parents = True, exist_ok = True, mode = 0o700)
    try:
        target.symlink_to(source, target_is_directory = True)
    except OSError:
        if not _create_directory_junction(source, target):
            typer.echo(f"Warning: couldn't link {source} into the Pi session.", err = True)
            return False
    return True


def _pi_local_entry(entry: str, source: Path, home: Path, linked: frozenset) -> str:
    """Re-anchor a user path from the original Pi agent directory."""
    value = entry.strip()
    if not value or value == "." or value.startswith("file:"):
        # Nothing to anchor: "" and "." would name the whole agent directory.
        return entry
    if value == "~" or value.startswith(("~/", "~" + os.sep)):
        target = os.path.join(home, value[2:])
    else:
        # Pi stores local packages relative to its agent directory.
        target = os.path.join(source, value)
    target = os.path.normpath(target)
    try:
        relative = os.path.relpath(target, source)
    except ValueError:  # on another Windows drive
        return target
    # Session-relative only where the link landed; where a real session directory blocks it, the entry would point into that directory instead.
    if relative.split(os.sep)[0] in linked:
        return relative
    return target


def _pi_settings_entries(key: str, entries, source: Path, home: Path, linked: frozenset) -> list:
    if not isinstance(entries, list):
        return []
    result = []
    for entry in entries:
        if key == "packages":
            spec = entry.get("source") if isinstance(entry, dict) else entry
            # All other package sources are local paths.
            if isinstance(spec, str) and not spec.strip().startswith(
                ("npm:", "git:", "github:", "http:", "https:", "ssh:")
            ):
                spec = _pi_local_entry(spec, source, home, linked)
                entry = {**entry, "source": spec} if isinstance(entry, dict) else spec
        elif isinstance(entry, str):
            prefix = entry[:1] if entry.startswith(("!", "+", "-")) else ""
            pattern = entry[len(prefix) :]
            if not prefix and "*" not in entry and "?" not in entry:
                entry = _pi_local_entry(entry, source, home, linked)
            elif not pattern.strip().startswith("~"):  # Pi does not expand ~ in patterns
                # The agent directory moved; keep the original too, it still matches basenames.
                anchored = prefix + _pi_local_entry(
                    pattern,
                    source,
                    home,
                    linked,
                )
                if anchored != entry:
                    result.append(entry)
                    entry = anchored
        result.append(entry)
    return result


def _clear_pi_user_resources(agent_dir: Path) -> None:
    """Undo what an earlier launch linked and copied, leaving session state alone."""
    for target in (agent_dir / name for name in _PI_USER_RESOURCE_DIRS):
        if target.is_symlink() or _is_junction(target):
            _remove_overlay_entry(target)
    manifest_path = agent_dir / _PI_USER_RESOURCES_MANIFEST
    previous = _read_json_object(manifest_path)
    if not previous:
        return
    settings_path = agent_dir / "settings.json"
    settings = _read_json_object(settings_path)
    if settings is None:
        return
    before = json.dumps(settings, sort_keys = True)
    for key, copied in previous.items():
        own = settings.get(key)
        if key in _PI_USER_VERBATIM_SETTINGS:
            # An argument vector, not entries: subtracting drops whatever the two share.
            if own == copied:
                settings.pop(key, None)
        elif isinstance(copied, list) and isinstance(own, list):
            rest = [item for item in own if item not in copied]
            if rest:
                settings[key] = rest
            else:
                settings.pop(key, None)
        elif own == copied:
            settings.pop(key, None)
    if json.dumps(settings, sort_keys = True) != before:
        _write_private_json(settings_path, settings)
    manifest_path.unlink(missing_ok = True)


def write_pi_user_resources(agent_dir: Path) -> None:
    """Expose selected user Pi resources inside an isolated session."""
    if _wsl_windows_executable(["pi"]):
        # Windows Pi cannot follow WSL links into mounted drives; drop those.
        _clear_pi_user_resources(agent_dir)
        return
    user_home = Path.home()
    configured = os.environ.get("PI_CODING_AGENT_DIR")
    configured = configured.strip() if configured else ""
    # Pi resolves a relative override from the launch directory.
    source = (
        Path(os.path.abspath(os.path.expanduser(configured)))
        if configured
        else user_home / ".pi" / "agent"
    )
    if source.resolve(strict = False) == agent_dir.resolve(strict = False):
        # Do not treat this session as its own resource source.
        source = user_home / ".pi" / "agent"
    if configured and not source.is_dir():
        # Otherwise this looks exactly like the bug this function exists to fix.
        typer.echo(
            f"Warning: PI_CODING_AGENT_DIR points at {source}, which is not a directory; "
            "no Pi extensions or packages will load in this session.",
            err = True,
        )
    linked = frozenset(
        name for name in _PI_USER_RESOURCE_DIRS if _link_user_dir(source / name, agent_dir / name)
    )

    user_settings_path = source / "settings.json"
    user_settings = _read_json_object(user_settings_path)
    if user_settings is None:
        typer.echo(
            f"Warning: couldn't parse {user_settings_path}; "
            "Pi packages listed there won't load in this session.",
            err = True,
        )
        user_settings = {}
    settings_path = agent_dir / "settings.json"
    settings = _read_json_object(settings_path)
    if settings is None:
        typer.echo(
            f"Warning: couldn't parse {settings_path}; your Pi packages won't load in this session.",
            err = True,
        )
        return
    manifest_path = agent_dir / _PI_USER_RESOURCES_MANIFEST
    previous = _read_json_object(manifest_path)
    if previous is None:
        # Provenance is lost, so entries the user has since removed cannot be reconciled.
        typer.echo(
            f"Warning: couldn't parse {manifest_path}; Pi resources copied by an earlier "
            "launch stay in this session even if you removed them since.",
            err = True,
        )
        previous = {}
    before = json.dumps(settings, sort_keys = True)
    copied = {}
    for key in _PI_USER_RESOURCE_SETTINGS:
        entries = _pi_settings_entries(
            key,
            user_settings.get(key),
            source,
            user_home,
            linked,
        )
        # Refresh copied entries while preserving settings added inside the session.
        stale = previous.get(key) if isinstance(previous.get(key), list) else []
        own = settings.get(key)
        if own is not None and not isinstance(own, list):
            # Pi types these as arrays; leave a shape we do not understand alone.
            typer.echo(
                f"Warning: {settings_path} has a non-list {key!r}; "
                "leaving it as is, so your Pi entries for it won't load in this session.",
                err = True,
            )
            continue
        own = [item for item in own or [] if item not in stale and item not in entries]
        if entries or own:
            # Pi keeps the FIRST duplicate package, so session entries lead; patterns stay user-first.
            settings[key] = own + entries if key == "packages" else entries + own
        else:
            settings.pop(key, None)
        if entries:
            copied[key] = entries
    for key in _PI_USER_VERBATIM_SETTINGS:
        # Pi runs every package lookup and install through npmCommand; inherit it along with the package list or npm cannot find them.
        value = user_settings.get(key)
        own = settings.get(key)
        if own is not None and own != previous.get(key):
            continue  # changed inside the session, so the session owns it now
        if isinstance(value, list) and value and all(isinstance(arg, str) for arg in value):
            settings[key] = value
            copied[key] = value
        else:
            settings.pop(key, None)
    if json.dumps(settings, sort_keys = True) != before:
        _write_private_json(settings_path, settings)
    if copied != previous:
        if copied:
            _write_private_json(manifest_path, copied)
        else:
            manifest_path.unlink(missing_ok = True)


def write_pi_subagent_config(
    base: str,
    key: str,
    model: dict,
    path: Path,
    approve: bool = False,
    max_tokens: Optional[int] = None,
    request_body: Optional[dict] = None,
    vision: bool = False,
) -> None:
    """Write private bootstrap data for the bundled Pi extension."""
    window = model.get("context_length") or model.get("max_context_length")
    window = int(window) if window else 32768
    _write_private_json(
        path,
        {
            "baseUrl": f"{base}/v1",
            "apiKey": key,
            "model": model["id"],
            "contextWindow": window,
            "maxTokens": _agent_output_limit(window, max_tokens),
            "approve": approve,
            **({"samplingParams": request_body} if request_body else {}),
            **({"vision": True} if vision else {}),
        },
    )


def write_dsh_patch(
    base: str,
    model: dict,
    path: Path,
    request_body: Optional[dict] = None,
    vision: bool = False,
) -> None:
    """dsh 0.1.7 dropped settings.yaml, which only applies after a first boot still on the DeepSeek
    default; the --patch overlay is read at boot and rewritten whole, as it is Unsloth's own."""
    import yaml

    model_entry = {"id": model["id"]}
    if vision:
        model_entry["input"] = ["text", "image"]
    window = model.get("context_length") or model.get("max_context_length")
    if window:
        window = int(window)
        model_entry["contextWindow"] = window
        model_entry["maxTokens"] = opencode_output_limit(window)
    compat = {"supportsDeveloperRole": False, "maxTokensField": "max_tokens"}
    if request_body:
        # dsh sends template kwargs only for a model that declares reasoning levels.
        model_entry["reasoningEfforts"] = {
            "off": None,
            "low": "low",
            "medium": "medium",
            "high": "high",
        }
        compat["thinkingFormat"] = "chat-template"
        compat["chatTemplateKwargs"] = request_body
    entries = [
        {
            "id": "llm-pi-ai",
            "name": "@deepseek-ai/dsh-llm-pi-ai",
            "config": {
                "providers": {
                    _DSH_PROVIDER: {
                        "displayName": "Unsloth Studio",
                        "api": "openai-completions",
                        "baseURL": f"{base}/v1",
                        "apiKeyEnv": _DSH_ENV_KEY,
                        # pi-ai reads an unknown base URL as OpenAI itself.
                        "compat": compat,
                        "models": [model_entry],
                    }
                }
            },
        },
        {
            "id": "agent-default-model",
            "name": "@deepseek-ai/dsh-agent-default-model",
            "config": {"provider": _DSH_PROVIDER, "model": model["id"]},
        },
    ]
    text = yaml.safe_dump(entries, sort_keys = False)
    if not path.exists() or path.read_text(encoding = "utf-8") != text:
        path.parent.mkdir(parents = True, exist_ok = True)
        path.write_text(text, encoding = "utf-8")
        typer.echo(f"Updated {path}")


class _AppTarget(NamedTuple):
    agent: str
    label: str
    path: Path
    updates: object = None


def _app_state_path(agent: str, path: Optional[Path] = None) -> Path:
    # One state per settings file, so another profile or config dir keeps its own backup and key.
    name = (
        agent if path is None else f"{agent}-{hashlib.sha256(str(path).encode()).hexdigest()[:12]}"
    )
    return _agents_config_root() / "app" / f"{name}.json"


def _read_app_file(path: Path) -> Optional[str]:
    if path.is_symlink():
        _fail(
            f"{path} is a symlink, so Unsloth won't rewrite it. Replace the link with a "
            "plain file and re-run, or add the Unsloth provider there yourself."
        )
    try:
        fd = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
    except FileNotFoundError:
        return None
    with open(fd, encoding = "utf-8", newline = "") as handle:
        return handle.read()


def _app_file_mode(path: Path) -> Optional[int]:
    try:
        return path.stat().st_mode & 0o777
    except FileNotFoundError:
        return None


def _write_app_file(path: Path, text: str) -> None:
    # Never world-readable, even briefly, and the rename replaces a planted symlink instead of following it.
    path.parent.mkdir(parents = True, exist_ok = True, mode = 0o700)
    fd, temp = tempfile.mkstemp(prefix = f".{path.name}.", dir = path.parent)
    try:
        with open(fd, "w", encoding = "utf-8", newline = "") as handle:
            handle.write(text)
            handle.flush()
            os.fsync(handle.fileno())
        os.replace(temp, path)
    except BaseException:
        with contextlib.suppress(OSError):
            os.unlink(temp)
        raise


_JSONC_COMMENT = re.compile(r'("(?:\\.|[^"\\])*")|//[^\n]*|/\*.*?\*/', re.S)
_JSONC_TRAILING_COMMA = re.compile(r'("(?:\\.|[^"\\])*")|,(?=\s*[\]}])')


def _load_app_config(
    path: Path,
    text: Optional[str],
    *,
    allow_json5: bool = False,
) -> Optional[dict]:
    if text is None or not text.strip():
        return {}
    if allow_json5:
        import json5

        # Raw text: the JSONC stripper below misreads // inside single-quoted JSON5 strings.
        # The json round trip joins surrogate pairs json5 leaves split (UTF-8 can't write them).
        data = json.loads(json.dumps(json5.loads(text)))
    elif path.suffix == ".toml":
        try:
            import tomllib  # novermin
        except ImportError:
            try:
                import tomli as tomllib
            except ImportError:
                return None
        data = tomllib.loads(text)
    elif path.suffix == ".yaml":
        import yaml
        data = yaml.safe_load(text)
    else:
        text = _JSONC_COMMENT.sub(lambda m: m.group(1) or "", text)
        data = json.loads(_JSONC_TRAILING_COMMA.sub(lambda m: m.group(1) or "", text))
    if not isinstance(data, dict):
        raise ValueError("not a settings object")
    return data


def _parse_app_config(
    path: Path,
    text: Optional[str],
    *,
    allow_json5: bool = False,
) -> Optional[dict]:
    try:
        return _load_app_config(path, text, allow_json5 = allow_json5)
    except Exception:
        _fail(f"Couldn't parse {path}, so it was left as is. Fix it and re-run.")


_APP_DELETE = object()


def _jsonc_members(clean: str, start: int) -> tuple:
    """({key: (value_start, value_end)}, closing brace) for the object opening at clean[start]."""
    decoder, space = json.JSONDecoder(), re.compile(r"\s*")
    members, index = {}, space.match(clean, start + 1).end()
    while clean[index] != "}":
        key, index = decoder.raw_decode(clean, index)
        value_start = space.match(clean, space.match(clean, index).end() + 1).end()
        _, value_end = decoder.raw_decode(clean, value_start)
        members[key] = (value_start, value_end)
        index = space.match(clean, value_end).end()
        if clean[index] == ",":
            index = space.match(clean, index + 1).end()
    return members, index


def _splice_jsonc(text: str, keys: tuple, value) -> str:
    """Set keys to value in JSONC text, touching only that member so comments elsewhere survive."""

    def blank(match):
        # Same-length blanking keeps every offset into the original text valid.
        return match.group(1) or re.sub(r"[^\n]", " ", match.group(0))

    clean = _JSONC_TRAILING_COMMA.sub(blank, _JSONC_COMMENT.sub(blank, text))
    start, depth = re.compile(r"\s*").match(clean).end(), 0
    for depth, key in enumerate(keys):
        members, close = _jsonc_members(clean, start)
        if key not in members:
            break
        value_start, value_end = members[key]
        if depth == len(keys) - 1 or clean[value_start] != "{":
            rendered = json.dumps(value, indent = 2, ensure_ascii = False)
            rendered = rendered.replace("\n", "\n" + "  " * (depth + 1))
            return text[:value_start] + rendered + text[value_end:]
        start = value_start
    for key in reversed(keys[depth + 1 :]):
        value = {key: value}
    indent = "  " * (depth + 1)
    rendered = json.dumps(value, indent = 2, ensure_ascii = False).replace("\n", "\n" + indent)
    member = f"{json.dumps(keys[depth])}: {rendered}"
    last = len(clean[:close].rstrip())
    if last != start + 1:
        return text[:last] + f",\n{indent}{member}" + text[last:]
    if text[last:close].strip():
        return text[:last] + f"\n{indent}{member}" + text[last:]
    return text[:last] + f"\n{indent}{member}\n" + "  " * depth + text[close:]


def _set_app_values(
    text: Optional[str],
    path: Path,
    updates: list,
    *,
    allow_json5: bool = False,
) -> Optional[str]:
    config = _parse_app_config(path, text, allow_json5 = allow_json5)
    before = json.dumps(config, sort_keys = True)
    for keys, value in updates:
        if value is _APP_DELETE:
            parent = functools.reduce(
                lambda node, key: node.get(key) if isinstance(node, dict) else None,
                keys[:-1],
                config,
            )
            if isinstance(parent, dict):
                parent.pop(keys[-1], None)
            continue
        parent = config
        for depth, key in enumerate(keys[:-1]):
            if parent.get(key) is None:
                parent[key] = {}
            elif not isinstance(parent[key], dict):
                _fail(
                    f"{'.'.join(keys[: depth + 1])} in {path} isn't a table, so it was left as is."
                )
            parent = parent[key]
        parent[keys[-1]] = value
    if json.dumps(config, sort_keys = True) == before:
        return text
    if allow_json5 or path.suffix != ".yaml":
        candidate = text
        with contextlib.suppress(Exception):
            if candidate and candidate.strip():
                for keys, value in updates:
                    candidate = _splice_jsonc(candidate, keys, value)
                if _load_app_config(path, candidate, allow_json5 = allow_json5) == config:
                    return candidate
        return json.dumps(config, indent = 2, ensure_ascii = False) + "\n"
    import yaml

    # Rewrite only the touched top-level blocks so the rest of the file keeps its comments.
    candidate = text or ""
    for top in dict.fromkeys(keys[0] for keys, _ in updates):
        block = yaml.safe_dump({top: config[top]}, sort_keys = False, allow_unicode = True)
        match = re.search(rf"(?m)^{re.escape(top)}:[^\n]*\n(?:[ \t]+[^\n]*\n)*", candidate)
        if match:
            candidate = candidate[: match.start()] + block + candidate[match.end() :]
        else:
            candidate += ("\n" if candidate and not candidate.endswith("\n") else "") + block
    with contextlib.suppress(Exception):
        if _load_app_config(path, candidate) == config:
            return candidate
    return yaml.safe_dump(config, sort_keys = False, allow_unicode = True)


def _set_toml_key(text: str, name: str, line: str) -> tuple:
    chunks = re.split(r"(?m)^(?=\[)", text)
    match = re.search(rf"(?m)^[ \t]*{name}[ \t]*=[^\r\n]*", chunks[0])
    if match is None:
        return f"{line}\n{text}", None
    chunks[0] = chunks[0][: match.start()] + line + chunks[0][match.end() :]
    return "".join(chunks), match.group(0)


def _unset_toml_key(text: str, name: str, line: str, previous: Optional[str]) -> Optional[str]:
    chunks = re.split(r"(?m)^(?=\[)", text)
    match = re.search(rf"(?m)^[ \t]*{name}[ \t]*=([^\r\n]*)(\r?\n)?", chunks[0])
    if match is None or match.group(0).strip() != line:
        return None
    restored = "" if previous is None else previous + (match.group(2) or "")
    chunks[0] = chunks[0][: match.start()] + restored + chunks[0][match.end() :]
    return "".join(chunks)


def _same_app_config(path: Path, text: str, other: str) -> bool:
    if text.strip() == other.strip():
        return True
    try:
        parsed = _load_app_config(path, text)
        return parsed is not None and parsed == _load_app_config(path, other)
    except Exception:
        return False


def _revoke_app_key(base: str, key_id: object) -> bool:
    if not is_loopback_url(base) or not verify_studio_identity(base):
        return False
    token = _studio_token()
    if token is None:
        return False
    try:
        _http_json("DELETE", f"{base}/api/auth/api-keys/{int(key_id)}", token)
    except urllib.error.HTTPError as exc:
        return exc.code == 404
    except (urllib.error.URLError, TimeoutError, ValueError):
        return False
    return True


def _app_api_key(target: _AppTarget, base: str, explicit: Optional[str], state: dict) -> tuple:
    if explicit:
        return explicit, None
    previous = state.get("key")
    if (
        previous
        and state.get("key_id") is not None
        and state.get("base") == base
        and _key_accepted(base, previous)
    ):
        return previous, state["key_id"]
    token = _studio_token() if verify_studio_identity(base) else None
    if token is None:
        _fail(
            f"Couldn't create an API key for the {target.label} automatically. Create one "
            "in Unsloth → Settings → API and pass it with --api-key."
        )
    answer = _http_json(
        "POST",
        f"{base}/api/auth/api-keys",
        token,
        {"name": target.label},
        error = "Couldn't create an API key",
    )
    return answer["key"], answer["api_key"]["id"]


def _open_app_config(
    target: _AppTarget,
    base: str,
    explicit_key: Optional[str],
    parse = _parse_app_config,
) -> tuple:
    if not is_loopback_url(base) and not explicit_key:
        _fail(
            f"{base} isn't on this machine. --app saves the key in your {target.label} "
            "config, so pass the key for that server with --api-key."
        )
    state_path = _app_state_path(target.agent, None if target.agent == "codex" else target.path)
    state = _read_json_object(state_path) or {}
    if state.get("path") != str(target.path):
        state = {}
    text = _read_app_file(target.path)
    if target.agent == "openclaw":
        parse = functools.partial(_parse_app_config, allow_json5 = True)
    parse(target.path, text)
    key, key_id = _app_api_key(target, base, explicit_key, state)
    return state_path, state, text, key, key_id


def _save_app_config(
    target: _AppTarget,
    state_path: Path,
    state: dict,
    new_state: dict,
    text: Optional[str],
    new_text: str,
) -> None:
    new_state["backup"] = state.get("backup")
    if text is not None and not state:
        backup = target.path.with_name(target.path.name + ".unsloth-backup")
        _write_app_file(backup, text)
        new_state["backup"] = str(backup)
        typer.echo(f"Backed up {target.path} to {backup}")
    _write_private_json(state_path, new_state)
    if new_text != text:
        _write_app_file(target.path, new_text)
        typer.echo(f"Updated {target.path}")
    if state.get("key_id") is not None and state.get("key") != new_state["key"]:
        _revoke_app_key(state["base"], state["key_id"])


def _app_server_notice(base: str) -> None:
    if _keep_auto_served():
        typer.echo(f"Unsloth Studio is still running at {base}; the app needs it running.")
        typer.echo("Stop it with: unsloth studio stop")


def _revoke_new_app_key(base: str, key_id: object, state: dict) -> None:
    # A key minted for a setup that then failed would otherwise stay live and unreachable.
    if key_id is not None and key_id != state.get("key_id"):
        _revoke_app_key(base, key_id)


def _add_app_provider(
    target: _AppTarget, base: str, explicit_key: Optional[str], entry: dict
) -> None:
    state, key_id = {}, None
    try:
        state_path, state, text, key, key_id = _open_app_config(target, base, explicit_key)
        new_text = _set_app_values(
            text,
            target.path,
            target.updates(text, target.path, base, key, entry),
            allow_json5 = target.agent == "openclaw",
        )
        new_state = {"path": str(target.path), "base": base, "key": key, "key_id": key_id}
        _save_app_config(target, state_path, state, new_state, text, new_text)
    except BaseException:
        _revoke_new_app_key(base, key_id, state)
        _shutdown_auto_served()
        raise
    typer.echo(
        f"Added {entry['id']} from Unsloth at {base} to the {target.label}. Your default "
        "model is unchanged: pick Unsloth in the app's model picker (restart the app if it "
        "is open)."
    )
    if key_id is not None:
        typer.echo(
            f"It uses its own API key, '{target.label}', which you can revoke in "
            "Unsloth → Settings → API."
        )
    typer.echo(f"After loading another model, re-run: unsloth start {target.agent} --app")
    _app_server_notice(base)


_CODEX_APP_CATALOG = "unsloth-model-catalog.json"


def _codex_app_lines(model_id: str) -> dict:
    return {
        "model_provider": f'model_provider = "{_CODEX_PROFILE}"',
        "model": f"model = {json.dumps(model_id)}",
        "model_catalog_json": f"model_catalog_json = {json.dumps(_CODEX_APP_CATALOG)}",
    }


def _codex_app_build(text: Optional[str], base: str, key: str, entry: dict, previous) -> tuple:
    previous = dict(previous or {})
    tables = [
        c for c in re.split(r"(?m)^(?=\[)", text or "") if c.startswith(_CODEX_PROVIDER_TABLES)
    ]
    previous.setdefault("table", "".join(tables) or None)
    merged = _merge_codex_config(text or "", base, key)
    for name, line in _codex_app_lines(entry["id"]).items():
        merged, old = _set_toml_key(merged, name, line)
        previous.setdefault(name, old)
    return merged, previous


def _codex_app_restore(text: str, state: dict) -> tuple:
    skipped = []
    chunks = re.split(r"(?m)^(?=\[)", text)
    ours = _codex_provider_table(state["base"], state["key"]).strip()

    def is_ours(chunk: str) -> bool:
        # An editor on Windows may have rewritten the file with CRLF line endings.
        return chunk.replace("\r\n", "\n").strip() == ours

    if any(is_ours(chunk) for chunk in chunks):
        table = state["previous"].get("table") or ""
        text = "".join(table if is_ours(chunk) else chunk for chunk in chunks)
    else:
        skipped.append(_PROVIDER_HEADER)
    for name, line in _codex_app_lines(state["model"]).items():
        restored = _unset_toml_key(text, name, line, state["previous"].get(name))
        if restored is None:
            skipped.append(name)
        else:
            text = restored
    return text, skipped


def _codex_app_target() -> _AppTarget:
    # The desktop app is opened from the Dock or Start menu, so it never sees CODEX_HOME.
    path = _codex_source_home(ignore_configured = True) / "config.toml"
    return _AppTarget("codex", "Codex app", path)


_CODEX_APP_HEALTH_INTERVAL_S = 5.0
_CODEX_APP_HEALTH_MISSES = 3


def _codex_app_owner() -> dict:
    try:
        import psutil
    except ImportError:
        return {"pid": os.getpid(), "started": None}
    return {"pid": os.getpid(), "started": psutil.Process().create_time()}


def _codex_app_owner_alive(owner: object) -> bool:
    try:
        pid = int(owner["pid"])
        if owner["started"] is None:
            # psutil is optional, so fall back to the PID alone.
            from unsloth_cli.commands.studio import _pid_alive
            return _pid_alive(pid)
        import psutil

        return abs(psutil.Process(pid).create_time() - float(owner["started"])) < 1.0
    except Exception:
        return False


def _switch_codex_app_back(state_path: Path, state: dict) -> list:
    path = Path(state["path"])
    text = _read_app_file(path)
    skipped = []
    if text is not None:
        new_text, skipped = _codex_app_restore(text, state)
        backup = Path(state["backup"]) if state.get("backup") else None
        original = _read_app_file(backup) if backup else None
        if original is not None and _same_app_config(path, new_text, original):
            new_text = original
        if state.get("created") and _same_app_config(path, new_text, ""):
            path.unlink()
        elif new_text != text:
            _write_app_file(path, new_text)
        if original is not None and new_text == original:
            if state.get("mode") is not None:
                os.chmod(path, state["mode"])
            backup.unlink(missing_ok = True)
    if "model_catalog_json" not in skipped:
        path.with_name(_CODEX_APP_CATALOG).unlink(missing_ok = True)
    revoked = state.get("key_id") is None or _revoke_app_key(state.get("base", ""), state["key_id"])
    state_path.unlink(missing_ok = True)
    notes = [
        f"Left {name} in {path} as is: it changed while Codex was on Unsloth." for name in skipped
    ]
    if not revoked:
        notes.append(
            "Couldn't reach Unsloth to revoke the app's key; delete 'Codex app' in "
            "Unsloth → Settings → API."
        )
    return notes


def _recover_codex_app() -> Optional[dict]:
    state_path = _app_state_path("codex")
    state = _read_json_object(state_path) or {}
    if not state.get("path"):
        return None
    if _codex_app_owner_alive(state.get("owner")):
        return state
    notes = _switch_codex_app_back(state_path, state)
    typer.echo(
        "Switched the Codex app back from an earlier `unsloth start codex --app` that did not "
        "exit cleanly."
    )
    for note in notes:
        typer.echo(note)
    return None


def _open_codex_app() -> None:
    if sys.platform == "darwin":
        with contextlib.suppress(OSError):
            if (
                subprocess.run(["open", "-b", "com.openai.codex"], capture_output = True).returncode
                == 0
            ):
                return
    typer.echo("Open the Codex app now.")


def _hold_codex_app(base: str) -> None:
    def stop(signum, frame):
        raise KeyboardInterrupt

    previous = {}
    for name in ("SIGTERM", "SIGHUP"):
        if hasattr(signal, name):
            previous[getattr(signal, name)] = signal.signal(getattr(signal, name), stop)
    try:
        misses = 0
        while misses < _CODEX_APP_HEALTH_MISSES:
            time.sleep(_CODEX_APP_HEALTH_INTERVAL_S)
            misses = 0 if _studio_healthy(base) else misses + 1
        typer.echo(f"Unsloth at {base} stopped answering.")
    except KeyboardInterrupt:
        pass
    finally:
        for number, handler in previous.items():
            signal.signal(number, handler)


def _codex_app_session(base: str, explicit_key: Optional[str], entry: dict) -> None:
    target = _codex_app_target()
    catalog = target.path.with_name(_CODEX_APP_CATALOG)
    state, key_id = {}, None
    try:
        state_path, state, text, key, key_id = _open_app_config(target, base, explicit_key)
        new_text, previous = _codex_app_build(text, base, key, entry, None)
        _parse_app_config(target.path, new_text)
        # The Codex app lists only the active provider's catalog, so this is what makes the model pickable.
        _write_app_file(catalog, json.dumps(_codex_model_catalog(entry, "list"), indent = 2) + "\n")
        new_state = {
            "path": str(target.path),
            "base": base,
            "model": entry["id"],
            "key": key,
            "key_id": key_id,
            "owner": _codex_app_owner(),
            "created": text is None,
            "mode": _app_file_mode(target.path),
            "previous": previous,
        }
        _save_app_config(target, state_path, {}, new_state, text, new_text)
    except BaseException:
        _revoke_new_app_key(base, key_id, state)
        _shutdown_auto_served()
        raise
    try:
        _open_codex_app()
        typer.echo(
            f"The Codex app is on {entry['id']} from Unsloth at {base} until this command exits "
            "(Ctrl+C). If the app was already open, quit and reopen it: it reads the model list "
            "only at startup. If this command is killed instead, the next `unsloth start codex` "
            "switches the app back."
        )
        _hold_codex_app(base)
    finally:
        # A second Ctrl+C must not cut the switch back short.
        previous_sigint = signal.signal(signal.SIGINT, signal.SIG_IGN)
        try:
            notes = _switch_codex_app_back(state_path, new_state)
            _shutdown_auto_served()
            # After SIGHUP the terminal may be gone; the switch back has already happened.
            with contextlib.suppress(OSError):
                typer.echo("Switched the Codex app back; restart it if a window is still open.")
                for note in notes:
                    typer.echo(note)
        finally:
            signal.signal(signal.SIGINT, previous_sigint)


def _check_app_flags(
    requested: bool,
    args: list,
    as_subagent: bool = False,
) -> None:
    if requested and (args or as_subagent):
        _fail("--app sets up the desktop app, so it takes no agent arguments or --as-subagent.")


def _opencode_app_target(
    max_tokens: Optional[int] = None, request_body: Optional[dict] = None
) -> _AppTarget:
    # OpenCode Desktop imports the login shell env; it merges config.json, opencode.json, opencode.jsonc, last wins.
    root = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config") / "opencode"
    names = ("opencode.jsonc", "opencode.json", "config.json")
    path = next((root / n for n in names if os.path.lexists(root / n)), root / "opencode.json")

    def updates(text, path, base, key, entry):
        provider = _opencode_provider(
            base, key, entry, max_tokens, request_body, _accepts_images(base, key, entry)
        )
        changes = [(("provider", _OPENCODE_PROVIDER), provider)]
        config = _parse_app_config(path, text) or {}
        enabled = config.get("enabled_providers")
        if isinstance(enabled, list) and _OPENCODE_PROVIDER not in enabled:
            changes.append((("enabled_providers",), [*enabled, _OPENCODE_PROVIDER]))
        # disabled_providers wins over enabled_providers.
        disabled = config.get("disabled_providers")
        if isinstance(disabled, list) and _OPENCODE_PROVIDER in disabled:
            changes.append(
                (("disabled_providers",), [p for p in disabled if p != _OPENCODE_PROVIDER])
            )
        return changes

    return _AppTarget("opencode", "OpenCode app", path, updates)


def _openclaw_app_updates(
    text,
    path,
    base,
    key,
    entry,
    max_tokens = None,
) -> list:
    config = _parse_app_config(path, text, allow_json5 = True) or {}
    agents = config.get("agents")
    defaults = agents.get("defaults") if isinstance(agents, dict) else None
    defaults = defaults if isinstance(defaults, dict) else {}
    ref = f"unsloth/{entry['id']}"
    provider = _openclaw_provider(base, key, entry, max_tokens, _accepts_images(base, key, entry))
    changes = [(("models", "providers", "unsloth"), provider)]
    # The picker only offers allowlisted models once an allowlist exists; never create one.
    policy = defaults.get("modelPolicy")
    allowed = policy.get("allow") if isinstance(policy, dict) else None
    meta = config.get("meta")
    migrations = meta.get("migrations") if isinstance(meta, dict) else None
    migrated = isinstance(migrations, dict) and migrations.get("modelPolicyAllowlist")
    # An empty allow list or models map allows every model, so adding the ref would restrict it.
    if isinstance(allowed, list):
        if allowed and ref not in allowed:
            changes.append((("agents", "defaults", "modelPolicy", "allow"), [*allowed, ref]))
    elif policy is None and not migrated and isinstance(defaults.get("models"), dict):
        if defaults["models"] and ref not in defaults["models"]:
            changes.append((("agents", "defaults", "models", ref), {}))
    return changes


def _openclaw_config_file() -> Optional[str]:
    executable = _which_with_install_dirs("openclaw")
    if executable is None:
        return None
    try:
        output = subprocess.check_output(
            [executable, "config", "file"],
            text = True,
            encoding = "utf-8",
            errors = "replace",
            timeout = 60,
            stderr = subprocess.DEVNULL,
            env = _probe_env(),
        )
    except Exception:
        return None
    lines = [line.strip() for line in output.splitlines() if line.strip()]
    return lines[-1] if lines and os.path.isabs(lines[-1]) else None


def _openclaw_app_target(max_tokens: Optional[int] = None) -> _AppTarget:
    home = Path.home()

    def user_path(value: str) -> Path:
        # Only a leading ~ expands (against OPENCLAW_HOME); abspath keeps symlinks for _read_app_file to refuse.
        if value == "~":
            value = str(home)
        elif value.startswith(("~/", "~\\")):
            value = os.path.join(str(home), value[2:])
        return Path(os.path.abspath(value))

    override = os.environ.get("OPENCLAW_HOME", "").strip()
    if override and override not in ("null", "undefined"):
        home = user_path(override)
    if override := os.environ.get("OPENCLAW_CONFIG_PATH", "").strip():
        path = user_path(override)
    elif override := os.environ.get("OPENCLAW_STATE_DIR", "").strip():
        path = user_path(override) / "openclaw.json"
    else:
        path = home / ".openclaw" / "openclaw.json"
        profile = os.environ.get("OPENCLAW_PROFILE", "").strip()
        # Whether a named profile alone moves the config depends on the build (openclaw#133252, after 2026.10.10-beta.3), so ask OpenClaw.
        if _OPENCLAW_PROFILE_RE.fullmatch(profile) and profile.lower() != "default":
            if (active := _openclaw_config_file()) is not None:
                path = Path(active)
    updates = functools.partial(_openclaw_app_updates, max_tokens = max_tokens)
    return _AppTarget("openclaw", "OpenClaw app", path, updates)


def _hermes_user_home(configured: str = "") -> Path:
    if configured:
        home = Path(configured).expanduser()
        if home.parent.name == "profiles":
            return home
    elif sys.platform == "win32":
        # Hermes' Windows default home (hermes_constants._get_platform_default_hermes_home).
        local = os.environ.get("LOCALAPPDATA", "").strip()
        home = (Path(local) if local else Path.home() / "AppData" / "Local") / "hermes"
    else:
        home = Path.home() / ".hermes"
    try:
        profile = (home / "active_profile").read_text(encoding = "utf-8").strip()
    except OSError:
        profile = ""
    if profile != "default" and re.fullmatch(r"[A-Za-z0-9_][A-Za-z0-9._-]*", profile):
        return home / "profiles" / profile
    return home


def _hermes_app_target(request_body: Optional[dict] = None) -> _AppTarget:
    # Hermes Desktop follows the sticky active profile.
    path = _hermes_user_home() / "config.yaml"

    def updates(text, path, base, key, entry):
        settings: dict = {}
        _set_hermes_provider(settings, base, entry, request_body)
        provider = settings["providers"][_HERMES_PROVIDER]
        del provider["key_env"]
        provider["api_key"] = key
        window = entry.get("context_length") or entry.get("max_context_length")
        if window:
            # model.context_length only covers the default model, so a picked one reads its window here.
            context = max(int(window), _HERMES_MIN_CONTEXT)
            provider["models"] = {entry["id"]: {"context_length": context}}
        changes = [(("providers", _HERMES_PROVIDER), provider)]
        config = _parse_app_config(path, text) or {}
        providers = config.get("providers")
        legacy = providers.get(_HERMES_LEGACY_PROVIDER) if isinstance(providers, dict) else None
        # Only the entry an earlier --app wrote: it points here and carries nothing of the user's.
        if (
            isinstance(legacy, dict)
            and legacy.get("base_url") == provider["base_url"]
            and set(legacy) <= {"base_url", "api_mode", "api_key", "models", "extra_body"}
        ):
            changes.append((("providers", _HERMES_LEGACY_PROVIDER), _APP_DELETE))
            # A default the user picked in the app still names the old entry; move it along.
            model = config.get("model")
            if (
                isinstance(model, dict)
                and model.get("provider") == f"custom:{_HERMES_LEGACY_PROVIDER}"
            ):
                changes.append((("model", "provider"), f"custom:{_HERMES_PROVIDER}"))
        return changes

    return _AppTarget("hermes", "Hermes app", path, updates)


_VSCODE_GROUP = "Unsloth"
_VSCODE_DEFAULT_CONTEXT = 32768
# Copilot's Agent prompt (instructions + tool schemas) does not fit in a smaller window.
_VSCODE_AGENT_MIN_CONTEXT = 32768


def _vscode_models_path() -> Path:
    if sys.platform == "win32":
        appdata = os.environ.get("APPDATA", "").strip()
        root = Path(appdata) if appdata else Path.home() / "AppData" / "Roaming"
    elif sys.platform == "darwin":
        root = Path.home() / "Library" / "Application Support"
    else:
        root = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config")
        code = _wsl_windows_executable(["code"])
        if code and not any((root / app / "User").is_dir() for app in ("Code", "Code - Insiders")):
            # Under WSL, Windows VS Code reads its own user dir, not the distro's.
            root = _wsl_windows_user_profile(code, "VS Code") / "AppData" / "Roaming"
    app = "Code"
    if not (root / "Code" / "User").is_dir() and (root / "Code - Insiders" / "User").is_dir():
        app = "Code - Insiders"
    return root / app / "User" / "chatLanguageModels.json"


def _vscode_groups(path: Path, text: Optional[str]) -> list:
    if text is None or not text.strip():
        return []
    try:
        text = _JSONC_COMMENT.sub(lambda m: m.group(1) or "", text)
        data = json.loads(_JSONC_TRAILING_COMMA.sub(lambda m: m.group(1) or "", text))
    except ValueError:
        data = None
    if not isinstance(data, list):
        _fail(f"Couldn't parse {path}, so it was left as is. Fix it and re-run.")
    return data


def _is_unsloth_vscode_group(group: object) -> bool:
    return (
        isinstance(group, dict)
        and group.get("vendor") == "customendpoint"
        and group.get("name") == _VSCODE_GROUP
    )


def _vscode_models_text(
    text: Optional[str],
    path: Path,
    base: str,
    key: str,
    entry: dict,
    max_tokens: Optional[int] = None,
    tool_calling: bool = True,
    vision: bool = False,
    replaced: frozenset = frozenset(),
    thinking: bool = False,
) -> Optional[str]:
    groups = _vscode_groups(path, text)
    window = int(
        entry.get("context_length") or entry.get("max_context_length") or _VSCODE_DEFAULT_CONTEXT
    )
    output = _agent_output_limit(window, max_tokens)
    model = {
        "id": entry["id"],
        "name": entry["id"],
        "url": f"{base}/v1/chat/completions",
        "apiType": "chat-completions",
        # Agent mode lists only tool-calling models; Studio rejects tools for the rest.
        "toolCalling": tool_calling,
        "vision": vision,
        # Without it VS Code drops reasoning_content when it replays an agent tool round.
        "thinking": thinking,
        "contextWindow": window,
        "maxInputTokens": window - output,
        "maxOutputTokens": output,
        # A raw apiKey is read as a secret-storage reference and dropped, so the key rides here.
        "requestHeaders": {"Authorization": f"Bearer {key}"},
    }
    index = next((i for i, g in enumerate(groups) if _is_unsloth_vscode_group(g)), None)
    updated = list(groups)
    if index is None:
        updated.append({"name": _VSCODE_GROUP, "vendor": "customendpoint", "models": [model]})
    else:
        # Replace only the models this command wrote; the rest of the group is the user's.
        group = dict(groups[index])
        drop = replaced | {entry["id"]}
        kept = [
            m
            for m in group.get("models") or []
            if not (isinstance(m, dict) and m.get("id") in drop)
        ]
        group["models"] = [*kept, model]
        updated[index] = group
    if updated == groups:
        return text
    return json.dumps(updated, indent = 2, ensure_ascii = False) + "\n"


def _vscode_capabilities(base: str, key: str, entry: dict) -> tuple:
    # Scoped to the slot serving this model; an older server ignores the query and answers for the primary.
    try:
        query = urlencode({"model": entry["id"]})
        status = _http_json("GET", f"{base}/api/inference/status?{query}", key)
    except Exception:
        status = {}
    resident = any(
        _model_id_matches(entry["id"], status_id, allow_casefold = is_loopback_url(base))
        for status_id in (status.get("active_model"), status.get("model_identifier"))
        if status_id
    )
    if not resident:
        # Only a status about this model can vouch for it; an older server reports nothing.
        return True, False, False
    return (
        status.get("supports_tools") is not False,
        status.get("is_vision") is True,
        status.get("supports_reasoning") is True,
    )


def _accepts_images(base: str, key: str, entry: dict) -> bool:
    return _vscode_capabilities(base, key, entry)[1]


def _container_engine() -> Optional[str]:
    # `docker run unsloth/unsloth` sets none of the env vars below, only these markers.
    if os.path.exists("/.dockerenv"):
        return "docker"
    if os.path.exists("/run/.containerenv"):
        return "podman"
    return None


_VSCODE_REMOTE_ENV = ("SSH_CONNECTION", "SSH_CLIENT", "SSH_TTY", "REMOTE_CONTAINERS", "CODESPACES")


def _vscode_over_ssh(path: Path, unconfirmed: bool = False) -> bool:
    if sys.platform in ("win32", "darwin"):
        return False
    if path.parent.is_dir():
        # In a container, a dir holding only what an earlier release of this command wrote there
        # (state without "written") is not VS Code's.
        return (
            unconfirmed
            and _container_engine() is not None
            and path.is_file()
            and all(p.name.lstrip(".").startswith(path.name) for p in path.parent.iterdir())
        )
    return (
        any(os.environ.get(name) for name in _VSCODE_REMOTE_ENV) or _container_engine() is not None
    )


def _add_vscode_provider(
    base: str,
    explicit_key: Optional[str],
    entry: dict,
    max_tokens: Optional[int] = None,
    tool_calling: bool = True,
    vision: bool = False,
    thinking: bool = False,
) -> None:
    target = _AppTarget("vscode", "VS Code", _vscode_models_path())
    state, key_id = {}, None
    try:
        state_path, state, text, key, key_id = _open_app_config(
            target, base, explicit_key, _vscode_groups
        )
        remote = _vscode_over_ssh(target.path, bool(state) and not state.get("written"))
        new_text = _vscode_models_text(
            None if remote else text,
            target.path,
            base,
            key,
            entry,
            max_tokens,
            tool_calling,
            vision,
            frozenset(state.get("models") or ()),
            thinking,
        )
        new_state = {
            "path": str(target.path),
            "base": base,
            "key": key,
            "key_id": key_id,
            "models": [entry["id"]],
            "written": not remote,
        }
        if remote:
            # Keep the key in state so a re-run reuses it; a file here would never be read.
            _save_app_config(target, state_path, state, new_state, None, None)
        else:
            _save_app_config(target, state_path, state, new_state, text, new_text)
    except BaseException:
        _revoke_new_app_key(base, key_id, state)
        _shutdown_auto_served()
        raise
    if remote:
        url = urlparse(base)
        port = url.port or (443 if url.scheme == "https" else 80)
        managed = any(os.environ.get(name) for name in _VSCODE_REMOTE_ENV)
        engine = _container_engine()
        if not is_loopback_url(base):
            reach = f"make sure your machine can reach {base}"
        elif engine and not managed:
            reach = (
                f"publish port {port} to the same port on your machine (for example: "
                f"{engine} run -p {port}:{port} ...)"
            )
        else:
            reach = (
                f"forward port {port} to the same port on your machine (for example: "
                f"ssh -L {port}:127.0.0.1:{port} <this host>)"
            )
        typer.echo(
            "This is a remote session (SSH or a container) with no VS Code user dir here, so "
            "nothing was written. VS Code does not list these models in remote windows yet "
            f"(microsoft/vscode#332085), so {reach}. Then, in a local VS Code window, run "
            "Chat: Manage Language Models, open chatLanguageModels.json and add:"
        )
        typer.echo(json.dumps(json.loads(new_text)[0], indent = 2, ensure_ascii = False))
        _app_server_notice(base)
        return
    typer.echo(
        f"Added {entry['id']} from Unsloth at {base} to VS Code. In the Copilot Chat model "
        f"picker, pick it under {_VSCODE_GROUP} (Manage Models if it is hidden; run "
        "Developer: Reload Window if VS Code is open). Needs the GitHub Copilot Chat "
        "extension; no Copilot plan is required."
    )
    if os.environ.get("WSL_DISTRO_NAME") and target.path.parts[:2] == ("/", "mnt"):
        typer.echo(
            "Use it from a local VS Code window: VS Code does not list these models in remote "
            "(WSL, SSH, container) windows yet (microsoft/vscode#332085)."
        )
    if not tool_calling:
        typer.echo(
            f"{entry['id']} has no tool-calling chat template, so it is offered in Ask mode, "
            "not Agent mode."
        )
    window = entry.get("context_length") or entry.get("max_context_length")
    if tool_calling and window and int(window) < _VSCODE_AGENT_MIN_CONTEXT:
        typer.echo(
            f"Warning: {entry['id']} is loaded with {int(window):,} tokens of context, too few "
            "for Copilot's Agent mode, which sends about 20,000 tokens of instructions before "
            "your message. Load it with --context-length "
            f"{_VSCODE_AGENT_MIN_CONTEXT} and re-run unsloth start vscode.",
            err = True,
        )
    if key_id is not None:
        typer.echo(
            f"It uses its own API key, '{target.label}', which you can revoke in "
            "Unsloth → Settings → API."
        )
    typer.echo("After loading another model, re-run: unsloth start vscode")
    _app_server_notice(base)


@start_app.command("claude", cls = _PassthroughCommand, context_settings = _PASSTHROUGH)
def claude(
    ctx: typer.Context,
    model: Optional[str] = _MODEL_OPTION,
    api_key: Optional[str] = _KEY_OPTION,
    launch: bool = _LAUNCH_OPTION,
    gguf_variant: Optional[str] = _GGUF_VARIANT_OPTION,
    max_seq_length: int = _CONTEXT_OPTION,
    load_in_4bit: bool = _LOAD_4BIT_OPTION,
    tensor_parallel: bool = _TENSOR_PARALLEL_OPTION,
    gpu_memory_mode: Optional[Literal["auto", "manual"]] = _GPU_MEMORY_MODE_OPTION,
    enable_tools: Optional[bool] = _ENABLE_TOOLS_OPTION,
    tool_call_healing: Optional[bool] = _TOOL_CALL_HEALING_OPTION,
    tool_call_nudging: Optional[bool] = _TOOL_CALL_NUDGING_OPTION,
    reasoning: Optional[Literal["on", "off", "auto"]] = _REASONING_OPTION,
    reasoning_effort: Optional[str] = _REASONING_EFFORT_OPTION,
    temperature: Optional[float] = _TEMPERATURE_OPTION,
    top_p: Optional[float] = _TOP_P_OPTION,
    top_k: Optional[int] = _TOP_K_OPTION,
    min_p: Optional[float] = _MIN_P_OPTION,
    repetition_penalty: Optional[float] = _REPETITION_PENALTY_OPTION,
    presence_penalty: Optional[float] = _PRESENCE_PENALTY_OPTION,
    serve: bool = _SERVE_OPTION,
    yolo: bool = _YOLO_OPTION,
    persist: bool = _PERSIST_OPTION,
    as_subagent: bool = _AS_SUBAGENT_OPTION,
    auto_route: bool = _AUTO_ROUTE_OPTION,
):
    """Point Claude Code at the running Unsloth server and start it."""
    # Route a leading `org/name` positional to --model; forward the rest to the agent.
    model, ctx.args[:] = _consume_positional_model(model, ctx.args)
    # The route gate is a hook the Windows claude cannot run from WSL, so its own tools would stay on.
    if auto_route and _wsl_windows_executable(["claude"]):
        _fail("--auto-route needs claude installed inside WSL, not the Windows claude.")
    as_subagent = as_subagent or auto_route
    install_hint = (
        "irm https://claude.ai/install.ps1 | iex"
        if os.name == "nt"
        else "curl -fsSL https://claude.ai/install.sh | bash"
    )
    # Before the install prompt: _install_agent runs a remote installer, and this can refuse outright, so asking first fetches a tool the run cannot use.
    _preflight_agent_gguf(
        _CLAUDE_GGUF_AGENT, model, serve = serve, launch = launch, gguf_variant = gguf_variant
    )
    # Only a bare or resumed interactive launch is refused: its prompt is the stock one and the TUI would hide a warning. Other forwarded args (-p, --tools, a --no-launch recipe a driver extends) can shrink the prompt, so they only warn.
    # CLAUDE_CODE_SIMPLE is the env form of --bare: a minimal prompt that may fit, so it only warns too.
    simple = os.environ.get("CLAUDE_CODE_SIMPLE", "").strip().lower() not in (
        "",
        "0",
        "false",
        "no",
        "off",
    )
    refuse_small_context = launch and not simple and _only_resumes(ctx.args, _CLAUDE_RESUME_ARGS)
    context_check = None
    if max_seq_length > 0 and not as_subagent:
        # Before the load, which would evict the resident model only for this to refuse.
        context_check = _early_context_check(
            model,
            functools.partial(
                _check_agent_context,
                "claude",
                "Claude Code",
                {"id": model or "The loaded model", "context_length": max_seq_length},
                _CLAUDE_PROMPT_TOKENS,
                loaded = False,
                model = model,
                gguf_variant = gguf_variant,
                ctx = ctx,
                refuse = refuse_small_context,
            ),
        )
    _require_agent_for_launch("claude", install_hint, launch)
    server_options = ServerOptions(
        enable_tools = enable_tools,
        tool_call_healing = tool_call_healing,
        tool_call_nudging = tool_call_nudging,
        reasoning = reasoning,
        reasoning_effort = reasoning_effort,
        temperature = temperature,
        top_p = top_p,
        top_k = top_k,
        min_p = min_p,
        repetition_penalty = repetition_penalty,
        presence_penalty = presence_penalty,
        carried = _ALL_REQUEST_FIELDS,
    )
    base, key, entry = _connect(
        api_key,
        model,
        _load_options(
            ctx, gguf_variant, max_seq_length, load_in_4bit, tensor_parallel, gpu_memory_mode
        ),
        serve = serve,
        launch = launch,
        preload_check = _before_load(
            context_check, functools.partial(_attach_gguf_check, _CLAUDE_GGUF_AGENT)
        ),
        server_options = server_options,
        connections = True,
    )
    # Before the launch owns the server, so a rejection tears it down, not atexit.
    try:
        if not entry.get("connection"):
            _require_gguf_for_agent(_CLAUDE_GGUF_AGENT, base, key, entry["id"])
        if not as_subagent:
            _check_agent_context(
                "claude",
                "Claude Code",
                entry,
                _CLAUDE_PROMPT_TOKENS,
                refuse = refuse_small_context,
                model = model,
                gguf_variant = gguf_variant,
                ctx = ctx,
            )
    except BaseException:
        _shutdown_auto_served()
        raise
    model_id = entry["id"]
    if as_subagent:
        subagent_id = (
            model_id
            if entry.get("connection")
            else _subagent_model_id(base, key, entry, model, gguf_variant)
        )
        subagent_model = {**entry, "id": subagent_id}
        window = subagent_model.get("context_length") or subagent_model.get("max_context_length")
        server_env = {
            "UNSLOTH_CLAUDE_SUBAGENT_BASE_URL": base,
            "UNSLOTH_CLAUDE_SUBAGENT_API_KEY": key,
            "UNSLOTH_CLAUDE_SUBAGENT_MODEL": subagent_id,
            "UNSLOTH_CLAUDE_SUBAGENT_BYPASS_PERMISSIONS": "1" if yolo else "0",
        }
        if window:
            server_env["UNSLOTH_CLAUDE_SUBAGENT_CONTEXT_WINDOW"] = str(int(window))
        if server_options.request_body():
            server_env["CLAUDE_CODE_EXTRA_BODY"] = json.dumps(server_options.request_body())
        if auto_route:
            server_env[_CLAUDE_SUBAGENT_AUTO_ROUTE_ENV] = "1"
        with _session_config("claude-subagent", launch, persist = persist) as config:
            plugin = write_claude_subagent_plugin(config, server_env)
            command = [
                "claude",
                "--plugin-dir",
                _agent_config_path(plugin, ["claude"]),
                # Before ctx.args: a forwarded `--` would turn later flags positional. The `=` form is used because --allowedTools is variadic, so a detached value swallows the first forwarded positional.
                f"--allowedTools={_CLAUDE_SUBAGENT_TOOL},{_CLAUDE_SUBAGENT_PLAN_TOOL}",
                *_yolo_command_flags("claude", yolo),
                *ctx.args,
            ]
            typer.echo(
                "Unsloth is available as a local agent. "
                + (
                    "Claude hands routine work to it on its own."
                    if auto_route
                    else "Ask Claude to spawn an Unsloth or local agent."
                )
            )
            _run(
                base,
                subagent_model,
                {},
                command,
                launch = launch,
                install_hint = install_hint,
            )
        return

    env = _claude_local_env(base, key, entry, server_options.request_body())
    # Claude Code auto-compacts against its native context window; the local env above supplies the loaded model's real window and a 90% threshold instead. --yolo (or its aliases) maps to Claude's own --dangerously-skip-permissions. IS_SANDBOX is left unset on purpose: Claude refuses bypass mode as root unless a sandbox is detected, and we do not want to falsely claim one on the user's host. claude keeps its history in ~/.claude/projects, which --settings/env never relocate, so a session already survives exit; resume it with `claude --continue` or `--resume <id>` passed through.
    # Claude keeps only the last --settings, so a forwarded one is merged into ours instead of dropped.
    user_settings, args = _forwarded_claude_settings(ctx.args)
    with _session_config("claude", launch, persist = persist) as config:
        settings = _write_claude_settings(config, model_id, env, user_settings)
        command = _claude_local_command(
            model_id,
            _agent_config_path(settings, ["claude"]),
            yolo,
            args,
        )
        _run(
            base,
            entry,
            env,
            command,
            launch = launch,
            install_hint = install_hint,
            unset_env = _CLAUDE_ENV_UNSET,
        )


@start_app.command("codex", cls = _PassthroughCommand, context_settings = _PASSTHROUGH)
def codex(
    ctx: typer.Context,
    model: Optional[str] = _MODEL_OPTION,
    api_key: Optional[str] = _KEY_OPTION,
    launch: bool = _LAUNCH_OPTION,
    gguf_variant: Optional[str] = _GGUF_VARIANT_OPTION,
    max_seq_length: int = _CONTEXT_OPTION,
    load_in_4bit: bool = _LOAD_4BIT_OPTION,
    tensor_parallel: bool = _TENSOR_PARALLEL_OPTION,
    gpu_memory_mode: Optional[Literal["auto", "manual"]] = _GPU_MEMORY_MODE_OPTION,
    enable_tools: Optional[bool] = _ENABLE_TOOLS_OPTION,
    tool_call_healing: Optional[bool] = _TOOL_CALL_HEALING_OPTION,
    tool_call_nudging: Optional[bool] = _TOOL_CALL_NUDGING_OPTION,
    reasoning: Optional[Literal["on", "off", "auto"]] = _REASONING_OPTION,
    reasoning_effort: Optional[str] = _REASONING_EFFORT_OPTION,
    temperature: Optional[float] = _TEMPERATURE_OPTION,
    top_p: Optional[float] = _TOP_P_OPTION,
    top_k: Optional[int] = _TOP_K_OPTION,
    min_p: Optional[float] = _MIN_P_OPTION,
    repetition_penalty: Optional[float] = _REPETITION_PENALTY_OPTION,
    presence_penalty: Optional[float] = _PRESENCE_PENALTY_OPTION,
    serve: bool = _SERVE_OPTION,
    yolo: bool = _YOLO_OPTION,
    persist: bool = _PERSIST_OPTION,
    as_subagent: bool = _AS_SUBAGENT_OPTION,
    auto_route: bool = _AUTO_ROUTE_OPTION,
    app: bool = _CODEX_APP_OPTION,
):
    """Point OpenAI Codex at the running Unsloth server and start it."""
    # Route a leading `org/name` positional to --model; forward the rest to the agent.
    model, ctx.args[:] = _consume_positional_model(model, ctx.args)
    as_subagent = as_subagent or auto_route
    _check_app_flags(app, ctx.args, as_subagent)
    running = _recover_codex_app()
    if app and running is not None:
        _fail(
            "The Codex app is already on Unsloth for another `unsloth start codex --app` "
            f"(PID {running['owner']['pid']}). Stop that one first."
        )
    install_hint = _npm_install_hint("@openai/codex")
    # Before the install prompt: _install_agent runs a remote installer, and this can refuse outright, so asking first fetches a tool the run cannot use.
    _preflight_agent_gguf(
        _CODEX_GGUF_AGENT, model, serve = serve, launch = launch, gguf_variant = gguf_variant
    )
    executable = _require_agent_for_launch("codex", install_hint, launch and not app)
    version = executable and _codex_executable_version(executable)
    if version and version < _CODEX_PROFILE_FILE_MIN_VERSION:
        needed = (
            f"Codex {'.'.join(map(str, _CODEX_PROFILE_FILE_MIN_VERSION))} or newer is needed, "
            f"but {executable} is {'.'.join(map(str, version))}."
        )
        update_hint = _codex_update_hint(executable)
        updated = update_hint and _install_agent("codex", update_hint, update = True)
        version = updated and _codex_executable_version(updated)
        if not updated or (version and version < _CODEX_PROFILE_FILE_MIN_VERSION):
            if update_hint:
                _fail(f"{needed} Update it with `{update_hint}`.")
            _fail(
                f"{needed} Update it the way it was installed, or remove it so "
                "`unsloth start codex` can install a current one."
            )
    codex_effort = _codex_reasoning_effort(reasoning, reasoning_effort)
    if codex_effort and not _agent_version_at_least("codex", _CODEX_REASONING_REQUEST_MIN_VERSION):
        codex_effort = None
    server_options = ServerOptions(
        enable_tools = enable_tools,
        tool_call_healing = tool_call_healing,
        tool_call_nudging = tool_call_nudging,
        reasoning = reasoning,
        reasoning_effort = reasoning_effort,
        temperature = temperature,
        top_p = top_p,
        top_k = top_k,
        min_p = min_p,
        repetition_penalty = repetition_penalty,
        presence_penalty = presence_penalty,
        # The app reads no per-launch flags, so the server applies them.
        carried = _REASONING_FIELDS if codex_effort and not app else frozenset(),
    )
    base, key, entry = _connect(
        api_key,
        model,
        _load_options(
            ctx, gguf_variant, max_seq_length, load_in_4bit, tensor_parallel, gpu_memory_mode
        ),
        serve = serve,
        launch = launch,
        preload_check = functools.partial(_attach_gguf_check, _CODEX_GGUF_AGENT),
        server_options = server_options,
        connections = True,
    )
    # This preflight runs after _connect may have auto-started a server but before _run takes over its lifecycle, so tear the server down here if it rejects the model (a transformers-backend model) rather than leaving it on the atexit backstop.
    try:
        if not entry.get("connection"):
            _require_gguf_for_agent(_CODEX_GGUF_AGENT, base, key, entry["id"])
    except BaseException:
        _shutdown_auto_served()
        raise
    if app and entry.get("connection"):
        _fail("The Codex app can't use a Connection model yet. Drop --app to run it in Codex.")
    if app:
        return _codex_app_session(base, api_key, entry)
    if as_subagent:
        subagent_id = (
            entry["id"]
            if entry.get("connection")
            else _subagent_model_id(base, key, entry, model, gguf_variant)
        )
        subagent_model = {**entry, "id": subagent_id}
        with _session_config("codex-subagent", launch, persist = persist) as home:
            bridge_config = write_codex_subagent_bridge(
                base,
                key,
                subagent_model,
                home,
                yolo = yolo,
                reasoning_effort = codex_effort,
                auto_route = auto_route,
            )
            parent_home = write_codex_parent_overlay(home / "parent", auto_route = auto_route)
            command = [
                "codex",
                *_codex_subagent_flags(bridge_config),
                *(_CODEX_AUTO_ROUTE_FLAGS if auto_route else []),
                *_yolo_command_flags("codex", yolo),
                *ctx.args,
            ]
            typer.echo(
                "Unsloth is available as a local agent. "
                + (
                    "Codex hands routine work to it on its own."
                    if auto_route
                    else "Ask Codex to spawn an Unsloth or local agent."
                )
            )
            _run(
                base,
                subagent_model,
                {"CODEX_HOME": str(parent_home)},
                command,
                launch = launch,
                install_hint = install_hint,
            )
        return
    command = [
        "codex",
        "--oss",
        "--profile",
        _CODEX_PROFILE,
        *_yolo_command_flags("codex", yolo),
        *ctx.args,
    ]
    with _session_config("codex", launch, persist = persist) as home:
        write_codex_config(base, entry, home, codex_effort, keep_mcp_servers = True)
        env = {_CODEX_ENV_KEY: key, "CODEX_HOME": str(home)}
        _run(
            base,
            entry,
            env,
            command,
            launch = launch,
            install_hint = install_hint,
            unset_env = _CODEX_ENV_UNSET,
        )


@start_app.command("openclaw", cls = _PassthroughCommand, context_settings = _PASSTHROUGH)
def openclaw(
    ctx: typer.Context,
    model: Optional[str] = _MODEL_OPTION,
    api_key: Optional[str] = _KEY_OPTION,
    launch: bool = _LAUNCH_OPTION,
    gguf_variant: Optional[str] = _GGUF_VARIANT_OPTION,
    max_seq_length: int = _CONTEXT_OPTION,
    max_tokens: Optional[int] = _MAX_TOKENS_OPTION,
    load_in_4bit: bool = _LOAD_4BIT_OPTION,
    tensor_parallel: bool = _TENSOR_PARALLEL_OPTION,
    gpu_memory_mode: Optional[Literal["auto", "manual"]] = _GPU_MEMORY_MODE_OPTION,
    enable_tools: Optional[bool] = _ENABLE_TOOLS_OPTION,
    tool_call_healing: Optional[bool] = _TOOL_CALL_HEALING_OPTION,
    tool_call_nudging: Optional[bool] = _TOOL_CALL_NUDGING_OPTION,
    reasoning: Optional[Literal["on", "off", "auto"]] = _REASONING_OPTION,
    reasoning_effort: Optional[str] = _REASONING_EFFORT_OPTION,
    temperature: Optional[float] = _TEMPERATURE_OPTION,
    top_p: Optional[float] = _TOP_P_OPTION,
    top_k: Optional[int] = _TOP_K_OPTION,
    min_p: Optional[float] = _MIN_P_OPTION,
    repetition_penalty: Optional[float] = _REPETITION_PENALTY_OPTION,
    presence_penalty: Optional[float] = _PRESENCE_PENALTY_OPTION,
    serve: bool = _SERVE_OPTION,
    yolo: bool = _YOLO_OPTION,
    persist: bool = _PERSIST_OPTION,
    app: bool = _APP_OPTION,
):
    """Point OpenClaw at the running Unsloth server and start it."""
    # Route a leading `org/name` positional to --model; forward the rest to the agent.
    model, ctx.args[:] = _consume_positional_model(model, ctx.args)
    _reject_as_subagent("openclaw", ctx.args)
    _check_app_flags(app, ctx.args)
    install_hint = (
        "iwr -useb https://openclaw.ai/install.ps1 | iex"
        if os.name == "nt"
        else "curl -fsSL https://openclaw.ai/install.sh | bash"
    )
    _require_agent_for_launch("openclaw", install_hint, launch and not app)
    server_options = ServerOptions(
        enable_tools = enable_tools,
        tool_call_healing = tool_call_healing,
        tool_call_nudging = tool_call_nudging,
        reasoning = reasoning,
        reasoning_effort = reasoning_effort,
        temperature = temperature,
        top_p = top_p,
        top_k = top_k,
        min_p = min_p,
        repetition_penalty = repetition_penalty,
        presence_penalty = presence_penalty,
        carried = frozenset() if app else _ALL_REQUEST_FIELDS,
    )
    base, key, entry = _connect(
        api_key,
        model,
        _load_options(
            ctx, gguf_variant, max_seq_length, load_in_4bit, tensor_parallel, gpu_memory_mode
        ),
        serve = serve,
        launch = launch,
        server_options = server_options,
    )
    if app:
        return _add_app_provider(_openclaw_app_target(max_tokens), base, api_key, entry)
    openclaw_args = list(ctx.args)
    # Default a bare `unsloth start openclaw` to the local TUI. Anything the caller passes through is forwarded verbatim so OpenClaw parses it under its own grammar (openclaw [global-flags] <command> [options]): an explicit subcommand, a global flag that must precede the command such as --profile/--dev, or a tui option. We cannot reinterpret those safely because a leading "--flag value" is ambiguous between a global (`--profile test`) and a tui option (`--message hi`), and prepending `tui --local` would break the global form, so only the empty case is defaulted.
    if not openclaw_args:
        openclaw_args = ["tui", "--local"]
    command = ["openclaw", *openclaw_args]
    with _session_config("openclaw", launch, persist = persist) as cfg:
        config_path = cfg / "openclaw.json"
        # The key lives in the config, not the env; --yolo writes the exec policy here too. Resolve the project only when the recipe executes: a --no-launch command may be generated in one directory, saved, and intentionally run later from another.
        write_openclaw_config(
            base,
            key,
            entry,
            config_path,
            yolo = yolo,
            workspace_path = "${OPENCLAW_WORKSPACE_DIR}",
            embedding_model = _studio_embedding_model(base, key),
            request_body = server_options.request_body(),
            max_tokens = max_tokens,
            vision = _accepts_images(base, key, entry),
        )
        # Scope config and state so OpenClaw never touches ~/.openclaw. Shell env off, else it re-imports keys.
        env = {
            "OPENCLAW_CONFIG_PATH": str(config_path),
            "OPENCLAW_STATE_DIR": str(cfg),
            "OPENCLAW_LOAD_SHELL_ENV": "0",
        }
        _run(
            base,
            entry,
            env,
            command,
            launch = launch,
            install_hint = install_hint,
            unset_env = _OPENCLAW_ENV_UNSET,
            cwd_env = ("OPENCLAW_WORKSPACE_DIR",),
        )


@start_app.command("opencode", cls = _PassthroughCommand, context_settings = _PASSTHROUGH)
def opencode(
    ctx: typer.Context,
    model: Optional[str] = _MODEL_OPTION,
    api_key: Optional[str] = _KEY_OPTION,
    launch: bool = _LAUNCH_OPTION,
    gguf_variant: Optional[str] = _GGUF_VARIANT_OPTION,
    max_seq_length: int = _CONTEXT_OPTION,
    load_in_4bit: bool = _LOAD_4BIT_OPTION,
    tensor_parallel: bool = _TENSOR_PARALLEL_OPTION,
    gpu_memory_mode: Optional[Literal["auto", "manual"]] = _GPU_MEMORY_MODE_OPTION,
    enable_tools: Optional[bool] = _ENABLE_TOOLS_OPTION,
    tool_call_healing: Optional[bool] = _TOOL_CALL_HEALING_OPTION,
    tool_call_nudging: Optional[bool] = _TOOL_CALL_NUDGING_OPTION,
    reasoning: Optional[Literal["on", "off", "auto"]] = _REASONING_OPTION,
    reasoning_effort: Optional[str] = _REASONING_EFFORT_OPTION,
    temperature: Optional[float] = _TEMPERATURE_OPTION,
    top_p: Optional[float] = _TOP_P_OPTION,
    top_k: Optional[int] = _TOP_K_OPTION,
    min_p: Optional[float] = _MIN_P_OPTION,
    repetition_penalty: Optional[float] = _REPETITION_PENALTY_OPTION,
    presence_penalty: Optional[float] = _PRESENCE_PENALTY_OPTION,
    max_tokens: Optional[int] = _MAX_TOKENS_OPTION,
    serve: bool = _SERVE_OPTION,
    yolo: bool = _YOLO_OPTION,
    persist: bool = _PERSIST_OPTION,
    as_subagent: bool = _AS_SUBAGENT_OPTION,
    auto_route: bool = _AUTO_ROUTE_OPTION,
    app: bool = _APP_OPTION,
):
    """Point OpenCode at the running Unsloth server and start it."""
    # Route a leading `org/name` positional to --model; forward the rest to the agent.
    model, ctx.args[:] = _consume_positional_model(model, ctx.args)
    as_subagent = as_subagent or auto_route
    _check_app_flags(app, ctx.args, as_subagent)
    command_name, opencode_v2 = _opencode_command()
    install_hint = _npm_install_hint("@opencode/cli" if opencode_v2 else "opencode-ai")
    opencode_prompt_tokens = _OPENCODE_V2_PROMPT_TOKENS if opencode_v2 else _OPENCODE_PROMPT_TOKENS
    refuse_small_context = launch and _only_resumes(ctx.args, _OPENCODE_RESUME_ARGS)
    context_check = None
    if max_seq_length > 0 and not as_subagent and not app:
        context_check = _early_context_check(
            model,
            functools.partial(
                _check_agent_context,
                "opencode",
                "OpenCode",
                {"id": model or "The loaded model", "context_length": max_seq_length},
                opencode_prompt_tokens,
                max_tokens,
                loaded = False,
                model = model,
                gguf_variant = gguf_variant,
                ctx = ctx,
                refuse = refuse_small_context,
            ),
        )
    _require_agent_for_launch(command_name, install_hint, launch and not app)
    server_options = ServerOptions(
        enable_tools = enable_tools,
        tool_call_healing = tool_call_healing,
        tool_call_nudging = tool_call_nudging,
        reasoning = reasoning,
        reasoning_effort = reasoning_effort,
        temperature = temperature,
        top_p = top_p,
        top_k = top_k,
        min_p = min_p,
        repetition_penalty = repetition_penalty,
        presence_penalty = presence_penalty,
        carried = _ALL_REQUEST_FIELDS,
    )
    base, key, entry = _connect(
        api_key,
        model,
        _load_options(
            ctx, gguf_variant, max_seq_length, load_in_4bit, tensor_parallel, gpu_memory_mode
        ),
        serve = serve,
        launch = launch,
        preload_check = _before_load(context_check),
        server_options = server_options,
        connections = True,
    )
    if app and entry.get("connection"):
        _fail(
            "The OpenCode app can't use a Connection model yet. Drop --app to run it in OpenCode."
        )
    if app:
        target = _opencode_app_target(max_tokens, server_options.request_body())
        return _add_app_provider(target, base, api_key, entry)
    if not as_subagent:
        try:
            _check_agent_context(
                "opencode",
                "OpenCode",
                entry,
                opencode_prompt_tokens,
                max_tokens,
                refuse = refuse_small_context,
                model = model,
                gguf_variant = gguf_variant,
                ctx = ctx,
            )
        except BaseException:
            _shutdown_auto_served()
            raise
    if opencode_v2:
        typer.echo(
            f"OpenCode V2 provider policies must allow '{_OPENCODE_PROVIDER}'.",
            err = True,
        )
    if as_subagent:
        subagent_id = (
            entry["id"]
            if entry.get("connection")
            else _subagent_model_id(base, key, entry, model, gguf_variant)
        )
        subagent_model = {**entry, "id": subagent_id}
        # Stay append-safe for a bare no-launch recipe: a later `run <prompt>` would make `opencode --auto run ...` parse as the TUI, so keep yolo in the inline fallback.
        route_native_auto = (
            yolo
            and (opencode_v2 or _opencode_supports_native_auto(command_name))
            and (launch or bool(ctx.args))
        )
        opencode_args = list(ctx.args)
        if opencode_v2:
            opencode_args = _opencode_v2_standalone_args(opencode_args)
        opencode_args, native_auto = _opencode_native_auto_args(
            opencode_args, route_native_auto, v2 = opencode_v2
        )
        command = [command_name, *opencode_args]
        with _session_config("opencode-subagent", launch, persist = persist) as cfg:
            config_path = cfg / "opencode.json"
            session_permission = write_opencode_config(
                base,
                key,
                subagent_model,
                config_path,
                yolo = yolo and not native_auto,
                as_subagent = True,
                max_tokens = max_tokens,
                request_body = server_options.request_body(),
                vision = _accepts_images(base, key, entry),
            )
            env = {
                "OPENCODE_CONFIG": str(config_path),
                **_opencode_output_env(subagent_model, max_tokens),
            }
            inline_config = _opencode_subagent_inline_config(
                config_path,
                session_permission,
                command = command_name,
                v2 = opencode_v2,
                auto_route = auto_route,
            )
            # A project opencode.json outranks the session file and could field-merge its own agent.unsloth over ours. Pin ours in the inline overlay so it wins.
            agents = inline_config.setdefault("agent", {})
            agents[_SUBAGENT_NAME] = {
                "description": (
                    _OPENCODE_AUTO_ROUTE_DESCRIPTION if auto_route else _SUBAGENT_DESCRIPTION
                ),
                "mode": "subagent",
                "model": f"{_OPENCODE_PROVIDER}/{subagent_model['id']}",
                "prompt": _SUBAGENT_INSTRUCTIONS,
            }
            if auto_route:
                # A task subagent does not inherit the parent agent's rules, so both keep their tools.
                agents[_OPENCODE_PLAN_SUBAGENT_NAME] = {
                    "description": _OPENCODE_AUTO_ROUTE_PLAN_DESCRIPTION,
                    "mode": "subagent",
                    "model": f"{_OPENCODE_PROVIDER}/{subagent_model['id']}",
                    "prompt": _SUBAGENT_PLAN_INSTRUCTIONS,
                    "permission": {"edit": "deny", "bash": "deny"},
                }
            env["OPENCODE_CONFIG_CONTENT"] = json.dumps(inline_config)
            typer.echo(
                "Unsloth is available as @unsloth and in /models."
                + (" OpenCode hands routine work to it on its own." if auto_route else "")
            )
            _run(
                base,
                subagent_model,
                env,
                command,
                launch = launch,
                install_hint = install_hint,
            )
        return
    opencode_model = f"{_OPENCODE_PROVIDER}/{entry['id']}"
    # The inline OPENCODE_CONFIG_CONTENT pin below selects the model, so no path passes --model: it misparses before a passthrough subcommand, lands before the `run <prompt>` drivers append to a --no-launch recipe, and OpenCode 2 rejects it on the root command, which a V2 build whose --version probe fails would get (#13747).
    native_auto = False
    route_native_auto = yolo and (opencode_v2 or _opencode_supports_native_auto(command_name))
    if ctx.args:
        opencode_args = list(ctx.args)
        if opencode_v2:
            opencode_args = _opencode_v2_standalone_args(opencode_args)
        opencode_args, native_auto = _opencode_native_auto_args(
            opencode_args, route_native_auto, v2 = opencode_v2
        )
        command = [command_name, *opencode_args]
    elif launch:
        opencode_args = _opencode_v2_standalone_args([]) if opencode_v2 else []
        opencode_args, native_auto = _opencode_native_auto_args(
            opencode_args,
            route_native_auto,
            v2 = opencode_v2,
        )
        command = [command_name, *opencode_args]
    else:
        # Append-safe base: `opencode --auto run ...` parses as the TUI with a project "run", not the run subcommand. The command is unknown here, so keep the config fallback.
        opencode_args = _opencode_v2_standalone_args([]) if opencode_v2 else []
        command = [command_name, *opencode_args]
    # opencode keeps sessions in ~/.local/share/opencode (never relocated), so resume already survives exit; reopen the last one by passing `opencode --continue` through.
    with _session_config("opencode", launch, persist = persist) as cfg:
        config_path = cfg / "opencode.json"
        # OPENCODE_CONFIG is an overlay, loaded between the user's global and project configs, so this adds the Unsloth provider/model for the session without changing the user's default model. The key lives in the config, not the env.
        session_permission = write_opencode_config(
            base,
            key,
            entry,
            config_path,
            yolo = yolo and not native_auto,
            max_tokens = max_tokens,
            request_body = server_options.request_body(),
            vision = _accepts_images(base, key, entry),
        )
        # A project's own opencode.json outranks OPENCODE_CONFIG, so the session model pin would silently lose to a repo config; carry it in OPENCODE_CONFIG_CONTENT, which outranks project config, while the API key stays in the private file. Only the config fallback carries a permission: native --auto omits it (auto-approve asks, keep explicit denies) and a non-yolo session omits it too, honoring project rules. V1 filters are ordinary overlays, so scope that session to our provider; V2 turns filters into security policies where global/project rules intentionally win, so keep those policies intact and tell the user above that they must allow our provider. small_model is opencode's separate model for lightweight tasks; pin it to the session model too, or a user/project small_model on another (now filtered) provider would resolve a not-found error mid-session.
        inline_config: dict = {
            "model": opencode_model,
            "small_model": opencode_model,
        }
        if not opencode_v2:
            inline_config["enabled_providers"] = [_OPENCODE_PROVIDER]
            inline_config["disabled_providers"] = []
        if session_permission:
            inline_config["permission"] = session_permission
        env = {
            "OPENCODE_CONFIG": str(config_path),
            "OPENCODE_CONFIG_CONTENT": json.dumps(inline_config),
            **_opencode_output_env(entry, max_tokens),
        }
        _run(base, entry, env, command, launch = launch, install_hint = install_hint)


@start_app.command("hermes", cls = _PassthroughCommand, context_settings = _PASSTHROUGH)
def hermes(
    ctx: typer.Context,
    model: Optional[str] = _MODEL_OPTION,
    api_key: Optional[str] = _KEY_OPTION,
    launch: bool = _LAUNCH_OPTION,
    gguf_variant: Optional[str] = _GGUF_VARIANT_OPTION,
    max_seq_length: int = _CONTEXT_OPTION,
    load_in_4bit: bool = _LOAD_4BIT_OPTION,
    tensor_parallel: bool = _TENSOR_PARALLEL_OPTION,
    gpu_memory_mode: Optional[Literal["auto", "manual"]] = _GPU_MEMORY_MODE_OPTION,
    enable_tools: Optional[bool] = _ENABLE_TOOLS_OPTION,
    tool_call_healing: Optional[bool] = _TOOL_CALL_HEALING_OPTION,
    tool_call_nudging: Optional[bool] = _TOOL_CALL_NUDGING_OPTION,
    reasoning: Optional[Literal["on", "off", "auto"]] = _REASONING_OPTION,
    reasoning_effort: Optional[str] = _REASONING_EFFORT_OPTION,
    temperature: Optional[float] = _TEMPERATURE_OPTION,
    top_p: Optional[float] = _TOP_P_OPTION,
    top_k: Optional[int] = _TOP_K_OPTION,
    min_p: Optional[float] = _MIN_P_OPTION,
    repetition_penalty: Optional[float] = _REPETITION_PENALTY_OPTION,
    presence_penalty: Optional[float] = _PRESENCE_PENALTY_OPTION,
    serve: bool = _SERVE_OPTION,
    yolo: bool = _YOLO_OPTION,
    persist: bool = _PERSIST_OPTION,
    app: bool = _APP_OPTION,
):
    """Point Hermes (Nous Research) at the running Unsloth server and start it."""
    # Route a leading `org/name` positional to --model; forward the rest to the agent.
    model, ctx.args[:] = _consume_positional_model(model, ctx.args)
    _reject_as_subagent("hermes", ctx.args)
    _check_app_flags(app, ctx.args)
    native_args = [*_yolo_command_flags("hermes", yolo), *ctx.args]
    command = ["hermes", *_hermes_resume_oneshot_args(native_args)]
    install_hint = _hermes_install_hint()
    _require_agent_for_launch("hermes", install_hint, launch and not app)
    server_options = ServerOptions(
        enable_tools = enable_tools,
        tool_call_healing = tool_call_healing,
        tool_call_nudging = tool_call_nudging,
        reasoning = reasoning,
        reasoning_effort = reasoning_effort,
        temperature = temperature,
        top_p = top_p,
        top_k = top_k,
        min_p = min_p,
        repetition_penalty = repetition_penalty,
        presence_penalty = presence_penalty,
        carried = _ALL_REQUEST_FIELDS,
    )
    base, key, entry = _connect(
        api_key,
        model,
        _load_options(
            ctx, gguf_variant, max_seq_length, load_in_4bit, tensor_parallel, gpu_memory_mode
        ),
        serve = serve,
        launch = launch,
        server_options = server_options,
    )
    if app:
        target = _hermes_app_target(server_options.request_body())
        _add_app_provider(target, base, api_key, entry)
        window = entry.get("context_length") or entry.get("max_context_length")
        if window and int(window) < _HERMES_MIN_CONTEXT:
            # The app's compaction settings are global, so they can't be scaled to this model.
            typer.echo(
                f"Warning: {entry['id']} serves {int(window):,} tokens, below Hermes' "
                f"{_HERMES_MIN_CONTEXT:,} floor, so long chats in the app can overflow before "
                f"Hermes compacts. Load it with --max-seq-length {_HERMES_MIN_CONTEXT} to avoid this.",
                err = True,
            )
        return
    with _session_config("hermes", launch, persist = persist) as home:
        # HERMES_HOME relocates hermes' whole home dir (config.yaml, sessions, state) like CODEX_HOME, so the user's ~/.hermes is left untouched for the session.
        write_hermes_config(
            base,
            entry,
            home / "config.yaml",
            server_options.request_body(),
            keep_mcp_servers = True,
        )
        env = {_HERMES_ENV_KEY: key, "HERMES_HOME": str(home)}
        _run(base, entry, env, command, launch = launch, install_hint = install_hint)


@start_app.command("pi", cls = _PassthroughCommand, context_settings = _PASSTHROUGH)
def pi(
    ctx: typer.Context,
    model: Optional[str] = _MODEL_OPTION,
    api_key: Optional[str] = _KEY_OPTION,
    launch: bool = _LAUNCH_OPTION,
    gguf_variant: Optional[str] = _GGUF_VARIANT_OPTION,
    max_seq_length: int = _CONTEXT_OPTION,
    max_tokens: Optional[int] = _MAX_TOKENS_OPTION,
    load_in_4bit: bool = _LOAD_4BIT_OPTION,
    tensor_parallel: bool = _TENSOR_PARALLEL_OPTION,
    gpu_memory_mode: Optional[Literal["auto", "manual"]] = _GPU_MEMORY_MODE_OPTION,
    enable_tools: Optional[bool] = _ENABLE_TOOLS_OPTION,
    tool_call_healing: Optional[bool] = _TOOL_CALL_HEALING_OPTION,
    tool_call_nudging: Optional[bool] = _TOOL_CALL_NUDGING_OPTION,
    reasoning: Optional[Literal["on", "off", "auto"]] = _REASONING_OPTION,
    reasoning_effort: Optional[str] = _REASONING_EFFORT_OPTION,
    temperature: Optional[float] = _TEMPERATURE_OPTION,
    top_p: Optional[float] = _TOP_P_OPTION,
    top_k: Optional[int] = _TOP_K_OPTION,
    min_p: Optional[float] = _MIN_P_OPTION,
    repetition_penalty: Optional[float] = _REPETITION_PENALTY_OPTION,
    presence_penalty: Optional[float] = _PRESENCE_PENALTY_OPTION,
    serve: bool = _SERVE_OPTION,
    yolo: bool = _YOLO_OPTION,
    persist: bool = _PERSIST_OPTION,
    as_subagent: bool = _AS_SUBAGENT_OPTION,
):
    """Point Pi (coding agent) at the running Unsloth server and start it."""
    # Route a leading `org/name` positional to --model; forward the rest to the agent.
    model, ctx.args[:] = _consume_positional_model(model, ctx.args)
    _reject_auto_route("pi", ctx.args)
    install_hint = _npm_install_hint(
        "@earendil-works/pi-coding-agent",
        ignore_scripts = True,
    )
    if as_subagent and not _PI_SUBAGENT_EXTENSION.is_file():
        _fail(f"Missing Pi subagent extension: {_PI_SUBAGENT_EXTENSION}")
    _require_agent_for_launch("pi", install_hint, launch)
    if launch:
        _warn_if_node_older("Pi", _PI_MIN_NODE, "@earendil-works/pi-coding-agent@legacy-node20")
    server_options = ServerOptions(
        enable_tools = enable_tools,
        tool_call_healing = tool_call_healing,
        tool_call_nudging = tool_call_nudging,
        reasoning = reasoning,
        reasoning_effort = reasoning_effort,
        temperature = temperature,
        top_p = top_p,
        top_k = top_k,
        min_p = min_p,
        repetition_penalty = repetition_penalty,
        presence_penalty = presence_penalty,
        carried = _ALL_REQUEST_FIELDS,
    )
    if server_options.request_body() and not _agent_version_at_least(
        "pi", _PI_SAMPLING_PARAMS_MIN_VERSION
    ):
        server_options = server_options._replace(carried = frozenset())
    base, key, entry = _connect(
        api_key,
        model,
        _load_options(
            ctx, gguf_variant, max_seq_length, load_in_4bit, tensor_parallel, gpu_memory_mode
        ),
        serve = serve,
        launch = launch,
        server_options = server_options,
    )
    if as_subagent:
        subagent_id = _subagent_model_id(base, key, entry, model, gguf_variant)
        subagent_model = {**entry, "id": subagent_id}
        extension = _agent_config_path(_PI_SUBAGENT_EXTENSION, ["pi"])
        with _session_config("pi-subagent", launch, persist = persist) as config:
            config_path = config / "subagent.json"
            write_pi_subagent_config(
                base,
                key,
                subagent_model,
                config_path,
                approve = yolo,
                max_tokens = max_tokens,
                request_body = server_options.request_body(),
                vision = _accepts_images(base, key, entry),
            )
            command = [
                "pi",
                "--extension",
                extension,
                *_yolo_command_flags("pi", yolo),
                *ctx.args,
            ]
            typer.echo(
                "Unsloth is available as a local agent and in /model. "
                "Ask Pi to spawn an Unsloth or local agent."
            )
            _run(
                base,
                subagent_model,
                {"UNSLOTH_PI_SUBAGENT_CONFIG": str(config_path)},
                command,
                launch = launch,
                install_hint = install_hint,
                clear_screen = True,
            )
        return
    # Pi defaults to the google provider, so pin our provider/model on the command line; the custom OpenAI-compatible endpoint itself is only configurable via ~/.pi/agent/models.json.
    command = [
        "pi",
        "--provider",
        _PI_PROVIDER,
        "--model",
        entry["id"],
        *_yolo_command_flags("pi", yolo),
        *ctx.args,
    ]
    # --ignore-scripts matches Pi's documented install recipe (its README notes Pi needs no install scripts), so accepting the prompt skips dependency lifecycle scripts.
    with _session_config("pi", launch, persist = persist) as home:
        # getAgentDir() prefers PI_CODING_AGENT_DIR over $HOME/.pi/agent, so pin it here or an inherited value skips our provider/key. HOME stays the user's so Pi's shell commands keep git and gh.
        pi_agent_dir = home / ".pi" / "agent"
        write_pi_config(
            base,
            key,
            entry,
            pi_agent_dir / "models.json",
            max_tokens = max_tokens,
            request_body = server_options.request_body(),
            vision = _accepts_images(base, key, entry),
        )
        write_pi_user_resources(pi_agent_dir)
        env = {"PI_CODING_AGENT_DIR": str(pi_agent_dir)}
        # Pi paints inline from the current cursor position (no alternate screen, no clear on first render), so give it the clean screen it assumes.
        _run(
            base,
            entry,
            env,
            command,
            launch = launch,
            install_hint = install_hint,
            clear_screen = True,
        )


@start_app.command("dsh", cls = _PassthroughCommand, context_settings = _PASSTHROUGH)
def dsh(
    ctx: typer.Context,
    model: Optional[str] = _MODEL_OPTION,
    api_key: Optional[str] = _KEY_OPTION,
    launch: bool = _LAUNCH_OPTION,
    gguf_variant: Optional[str] = _GGUF_VARIANT_OPTION,
    max_seq_length: int = _CONTEXT_OPTION,
    load_in_4bit: bool = _LOAD_4BIT_OPTION,
    tensor_parallel: bool = _TENSOR_PARALLEL_OPTION,
    gpu_memory_mode: Optional[Literal["auto", "manual"]] = _GPU_MEMORY_MODE_OPTION,
    enable_tools: Optional[bool] = _ENABLE_TOOLS_OPTION,
    tool_call_healing: Optional[bool] = _TOOL_CALL_HEALING_OPTION,
    tool_call_nudging: Optional[bool] = _TOOL_CALL_NUDGING_OPTION,
    reasoning: Optional[Literal["on", "off", "auto"]] = _REASONING_OPTION,
    reasoning_effort: Optional[str] = _REASONING_EFFORT_OPTION,
    temperature: Optional[float] = _TEMPERATURE_OPTION,
    top_p: Optional[float] = _TOP_P_OPTION,
    top_k: Optional[int] = _TOP_K_OPTION,
    min_p: Optional[float] = _MIN_P_OPTION,
    repetition_penalty: Optional[float] = _REPETITION_PENALTY_OPTION,
    presence_penalty: Optional[float] = _PRESENCE_PENALTY_OPTION,
    serve: bool = _SERVE_OPTION,
    yolo: bool = _YOLO_OPTION,
    persist: bool = _PERSIST_OPTION,
):
    """Point DeepSeek Harness (dsh) at the running Unsloth server and start it."""
    model, ctx.args[:] = _consume_positional_model(model, ctx.args)
    _reject_as_subagent("dsh", ctx.args)
    install_hint = _npm_install_hint(_DSH_PACKAGE)
    _require_agent_for_launch("dsh", install_hint, launch)
    server_options = ServerOptions(
        enable_tools = enable_tools,
        tool_call_healing = tool_call_healing,
        tool_call_nudging = tool_call_nudging,
        reasoning = reasoning,
        reasoning_effort = reasoning_effort,
        temperature = temperature,
        top_p = top_p,
        top_k = top_k,
        min_p = min_p,
        repetition_penalty = repetition_penalty,
        presence_penalty = presence_penalty,
        carried = _REASONING_FIELDS,
    )
    base, key, entry = _connect(
        api_key,
        model,
        _load_options(
            ctx, gguf_variant, max_seq_length, load_in_4bit, tensor_parallel, gpu_memory_mode
        ),
        serve = serve,
        launch = launch,
        server_options = server_options,
    )
    window = entry.get("context_length") or entry.get("max_context_length")
    if window and int(window) < _DSH_MIN_CONTEXT:
        typer.echo(
            f"Warning: {entry['id']} is loaded with {int(window):,} tokens of context, too few "
            "for DeepSeek Harness: its instructions and tools take about 6,500 and it keeps "
            "4,096 in reserve, so replies are cut short (at 8,192, after a single token). "
            f"Load it with --max-seq-length {_DSH_MIN_CONTEXT} or more (a smaller quant if "
            "that does not fit in memory) and re-run unsloth start dsh.",
            err = True,
        )
    with _session_config("dsh", launch, persist = persist) as home:
        patch = home / _DSH_PATCH_FILE
        write_dsh_patch(
            base, entry, patch, server_options.request_body(), _accepts_images(base, key, entry)
        )
        # A Windows dsh under WSL gets DSH_HOME translated through WSLENV, but not argv.
        command = _dsh_command(ctx.args, _agent_config_path(patch, ["dsh"]))
        env = {
            _DSH_ENV_KEY: key,
            "DSH_HOME": str(home),
            # dsh uploads session records once a user records /feedback.
            "DSH_TELEMETRY_DISABLED": "1",
            "DSH_PERMISSION_MODE": (
                _DSH_YOLO_PERMISSION_MODE if yolo else _DSH_SAFE_PERMISSION_MODE
            ),
        }
        _run(base, entry, env, command, launch = launch, install_hint = install_hint)


@start_app.command("vibe", cls = _PassthroughCommand, context_settings = _PASSTHROUGH)
def vibe(
    ctx: typer.Context,
    model: Optional[str] = _MODEL_OPTION,
    api_key: Optional[str] = _KEY_OPTION,
    launch: bool = _LAUNCH_OPTION,
    gguf_variant: Optional[str] = _GGUF_VARIANT_OPTION,
    max_seq_length: int = _CONTEXT_OPTION,
    load_in_4bit: bool = _LOAD_4BIT_OPTION,
    tensor_parallel: bool = _TENSOR_PARALLEL_OPTION,
    gpu_memory_mode: Optional[Literal["auto", "manual"]] = _GPU_MEMORY_MODE_OPTION,
    enable_tools: Optional[bool] = _ENABLE_TOOLS_OPTION,
    tool_call_healing: Optional[bool] = _TOOL_CALL_HEALING_OPTION,
    tool_call_nudging: Optional[bool] = _TOOL_CALL_NUDGING_OPTION,
    reasoning: Optional[Literal["on", "off", "auto"]] = _REASONING_OPTION,
    reasoning_effort: Optional[str] = _REASONING_EFFORT_OPTION,
    temperature: Optional[float] = _TEMPERATURE_OPTION,
    top_p: Optional[float] = _TOP_P_OPTION,
    top_k: Optional[int] = _TOP_K_OPTION,
    min_p: Optional[float] = _MIN_P_OPTION,
    repetition_penalty: Optional[float] = _REPETITION_PENALTY_OPTION,
    presence_penalty: Optional[float] = _PRESENCE_PENALTY_OPTION,
    serve: bool = _SERVE_OPTION,
    yolo: bool = _YOLO_OPTION,
    persist: bool = _PERSIST_OPTION,
):
    """Point Mistral Vibe at the running Unsloth server and start it."""
    model, ctx.args[:] = _consume_positional_model(model, ctx.args)
    _reject_as_subagent("vibe", ctx.args)
    install_hint = _vibe_install_hint()
    _require_agent_for_launch("vibe", install_hint, launch)
    server_options = ServerOptions(
        enable_tools = enable_tools,
        tool_call_healing = tool_call_healing,
        tool_call_nudging = tool_call_nudging,
        reasoning = reasoning,
        reasoning_effort = reasoning_effort,
        temperature = temperature,
        top_p = top_p,
        top_k = top_k,
        min_p = min_p,
        repetition_penalty = repetition_penalty,
        presence_penalty = presence_penalty,
        carried = frozenset({"temperature"}),
    )
    base, key, entry = _connect(
        api_key,
        model,
        _load_options(
            ctx, gguf_variant, max_seq_length, load_in_4bit, tensor_parallel, gpu_memory_mode
        ),
        serve = serve,
        launch = launch,
        server_options = server_options,
    )
    command = ["vibe", *_yolo_command_flags("vibe", yolo), *ctx.args]
    # Vibe keeps its own home; the env layer pins provider and model above its config files.
    request_body = server_options.request_body()
    if "temperature" not in request_body:
        # Vibe always sends a temperature that beats the model's recommendation; pass that on.
        status = _inference_status(base, key, entry["id"])
        recommended = (status.get("inference") or {}).get("temperature")
        if recommended is not None and any(
            _model_id_matches(entry["id"], status_id, allow_casefold = is_loopback_url(base))
            for status_id in (status.get("active_model"), status.get("model_identifier"))
            if status_id
        ):
            request_body = {**request_body, "temperature": recommended}
    env = {
        _VIBE_ENV_KEY: key,
        **_vibe_env(base, entry, request_body, _accepts_images(base, key, entry)),
    }
    _run(base, entry, env, command, launch = launch, install_hint = install_hint)


_VSCODE_LAUNCH_OPTION = typer.Option(True, "--launch/--no-launch", hidden = True)


@start_app.command("vscode", cls = _PassthroughCommand, context_settings = _PASSTHROUGH)
def vscode(
    ctx: typer.Context,
    model: Optional[str] = _MODEL_OPTION,
    api_key: Optional[str] = _KEY_OPTION,
    launch: bool = _VSCODE_LAUNCH_OPTION,
    gguf_variant: Optional[str] = _GGUF_VARIANT_OPTION,
    max_seq_length: int = _CONTEXT_OPTION,
    load_in_4bit: bool = _LOAD_4BIT_OPTION,
    tensor_parallel: bool = _TENSOR_PARALLEL_OPTION,
    gpu_memory_mode: Optional[Literal["auto", "manual"]] = _GPU_MEMORY_MODE_OPTION,
    enable_tools: Optional[bool] = _ENABLE_TOOLS_OPTION,
    tool_call_healing: Optional[bool] = _TOOL_CALL_HEALING_OPTION,
    tool_call_nudging: Optional[bool] = _TOOL_CALL_NUDGING_OPTION,
    reasoning: Optional[Literal["on", "off", "auto"]] = _REASONING_OPTION,
    reasoning_effort: Optional[str] = _REASONING_EFFORT_OPTION,
    temperature: Optional[float] = _TEMPERATURE_OPTION,
    top_p: Optional[float] = _TOP_P_OPTION,
    top_k: Optional[int] = _TOP_K_OPTION,
    min_p: Optional[float] = _MIN_P_OPTION,
    repetition_penalty: Optional[float] = _REPETITION_PENALTY_OPTION,
    presence_penalty: Optional[float] = _PRESENCE_PENALTY_OPTION,
    max_tokens: Optional[int] = _MAX_TOKENS_OPTION,
    serve: bool = _SERVE_OPTION,
):
    """Add the model Unsloth is serving to VS Code's Copilot Chat model picker."""
    model, ctx.args[:] = _consume_positional_model(model, ctx.args)
    if ctx.args:
        _fail("unsloth start vscode only edits VS Code's settings, so it takes no extra arguments.")
    server_options = ServerOptions(
        enable_tools = enable_tools,
        tool_call_healing = tool_call_healing,
        tool_call_nudging = tool_call_nudging,
        reasoning = reasoning,
        reasoning_effort = reasoning_effort,
        temperature = temperature,
        top_p = top_p,
        top_k = top_k,
        min_p = min_p,
        repetition_penalty = repetition_penalty,
        presence_penalty = presence_penalty,
    )
    base, key, entry = _connect(
        api_key,
        model,
        _load_options(
            ctx, gguf_variant, max_seq_length, load_in_4bit, tensor_parallel, gpu_memory_mode
        ),
        serve = serve,
        launch = launch,
        server_options = server_options,
    )
    tool_calling, vision, thinking = _vscode_capabilities(base, key, entry)
    # Remote: the key _connect accepted. Local: never an explicit key it rejected for a fresh server.
    explicit = key if not is_loopback_url(base) else api_key if key == api_key else None
    _add_vscode_provider(base, explicit, entry, max_tokens, tool_calling, vision, thinking)